Linux Binary

This guide provides a secure, best-practice approach to installing and configuring the Qtap agent on Linux systems, independent from Qplane.

Prerequisites

Before installation, verify your environment's compatibility:

curl -sSL https://github.com/qpoint-io/preflight/releases/latest/download/preflight.sh | sudo bash

Requirements:

• Linux host with kernel version 5.10+

• x86_64 or arm64 architecture

• Root/sudo access

Installation Methods

Automated Installation

The quickest way to install or update Qtap is via our installation script, which places Qtap into your path:

curl -s https://get.qpoint.io/install | sudo sh

Quick test (runs with default settings):

sudo qtap

Running sudo qtap without a configuration file starts Qtap with default settings (captures all egress traffic to stdout). This is useful for quick tests, but not recommended for production. You'll want to create a configuration file to:

• Control what traffic to capture (filters, endpoints, direction)

• Configure storage destinations (S3, Axiom, etc.)

• Set up selective capture with rules (errors only, specific domains)

• Define processing plugins and capture levels

See Configuration below and Configuration Documentation for details.

Manual Installation

For more control, you can manually install the binary:

1. Download the appropriate binary for your architecture:

   # For x86_64
   curl -L https://downloads.qpoint.io/qpoint/qtap-v0.17.1-linux-amd64.tgz -o qtap.tgz
   
   # For arm64
   curl -L https://downloads.qpoint.io/qpoint/qtap-v0.17.1-linux-arm64.tgz -o qtap.tgz

2. Extract and install the binary:

   tar -xzf qtap.tgz
   sudo mv qtap-* /usr/local/bin/qtap
   sudo chmod +x /usr/local/bin/qtap

3. Test the installation:

   sudo qtap

   This runs Qtap with default settings. Press Ctrl+C to stop.

Default behavior: Running sudo qtap without arguments uses built-in defaults (captures all egress traffic to stdout). While this works for testing, you should create a configuration file before production use to control capture behavior, storage destinations, and processing rules.

Configuration Setup

Why you need a configuration file:

Qtap's configuration file (qpoint.yaml) allows you to:

• Control what to capture: Filter by process, domain, direction (egress/ingress)

• Define storage: Send data to S3, Axiom, or other destinations instead of stdout

• Selective capture: Use rules to capture only errors, specific endpoints, or traffic patterns

• Processing control: Choose capture levels (summary/details/full) and formats (text/json)

Without a config file, Qtap captures everything to stdout with no filtering - rarely what you want in production.

Configuration resources:

• Quick start configs: 5-Minute Quickstart

• Progressive tutorial: Complete Guide: Hello World to Production

• Full reference: Configuration Documentation

• Examples: Configuration Examples

Creating Your Configuration File

1. Create a standard configuration directory with appropriate permissions:

   sudo mkdir -p /etc/qtap

2. Create your configuration file:

   sudo nano /etc/qtap/qpoint.yaml

3. Set appropriate permissions:

   sudo chmod 640 /etc/qtap/qpoint.yaml
   sudo chown root:root /etc/qtap/qpoint.yaml

4. For sensitive credentials (if applicable), create a separate environment file:

   sudo touch /etc/qtap/environment
   sudo chmod 600 /etc/qtap/environment

5. Add any sensitive environment variables to this file:

   # Example for S3 credentials if needed
   echo "S3_ACCESS_KEY=your_access_key" | sudo tee -a /etc/qtap/environment
   echo "S3_SECRET_KEY=your_secret_key" | sudo tee -a /etc/qtap/environment

Running as a Systemd Service

1. Create a systemd service file:

   sudo tee /etc/systemd/system/qtap.service << 'EOF'
   [Unit]
   Description=Qtap Traffic Analysis Service
   After=network.target
   
   [Service]
   Type=simple
   User=root
   # Only include Environment if you have sensitive environment variables
   EnvironmentFile=/etc/qtap/environment
   ExecStart=/usr/local/bin/qtap --config=/etc/qtap/qpoint.yaml
   Restart=always
   RestartSec=1
   
   [Install]
   WantedBy=multi-user.target
   EOF

2. Reload systemd, enable and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable qtap
   sudo systemctl start qtap

Verification

1. Check the service status:

   sudo systemctl status qtap

2. Verify the running version:

   qtap --version

3. Monitor the logs:

   sudo journalctl -u qtap -f

Updating Qtap Service

Installation Script

The quickest way to update Qtap is via our installation script:

1. Stop the service:

   sudo systemctl stop qtap

2. Download and install the new version:

   curl -s https://get.qpoint.io/install | sudo sh

3. Restart the service:

   sudo systemctl start qtap

4. Verify the update:

   qtap --version
   sudo systemctl status qtap

Manually

1. Stop the service:

   sudo systemctl stop qtap

2. Download and install the new version:

   # Download the new version
   curl -L https://downloads.qpoint.io/qpoint/qtap-vX.Y.Z-linux-amd64.tgz -o qtap-new.tgz
   
   # Extract and replace
   tar -xzf qtap-new.tgz
   sudo mv qtap-* /usr/local/bin/qtap
   sudo chmod +x /usr/local/bin/qtap

3. Restart the service:

   sudo systemctl start qtap

4. Verify the update:

   qtap --version
   sudo systemctl status qtap

Configuration Management Best Practices

• Version Control: Track configuration changes in a version control system

• Regular Backups: Include /etc/qtap in your backup strategy

• Configuration Reviews: Implement a review process for configuration changes

• Automation: Consider using configuration management tools (Ansible, Chef, Puppet) for deployment

Remember that Qtap requires root permissions to work properly due to its use of eBPF for traffic monitoring.