> For the complete documentation index, see [llms.txt](https://docs.qpoint.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qpoint.io/getting-started/qtap/installation/linux-binary.md).

# Linux Binary

This guide provides a secure, best-practice approach to installing and configuring the Qtap agent on Linux systems, independent from [Qplane](/getting-started/qplane.md).

## Prerequisites

Before installation, verify your environment's compatibility:

{% code overflow="wrap" %}

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

{% endcode %}

## 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:

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

**Quick test (runs with default settings):**

```bash
sudo qtap
```

{% hint style="info" %}
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](#configuration-setup) below and [Configuration Documentation](/getting-started/qtap/configuration.md) for details.
{% endhint %}

### Manual Installation

For more control, you can manually install the binary:

1. Download the appropriate binary for your architecture:

   ```bash
   # 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:

   ```bash
   tar -xzf qtap.tgz
   sudo mv qtap-* /usr/local/bin/qtap
   sudo chmod +x /usr/local/bin/qtap
   ```
3. Test the installation:

   ```bash
   sudo qtap
   ```

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

{% hint style="warning" %}
**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.
{% endhint %}

## 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](/guides/qtap-guides/getting-started/qtap-starter-configuration-stdout-only.md)
* **Progressive tutorial**: [Complete Guide: Hello World to Production](/guides/qtap-guides/getting-started/getting-started-complete-guide.md)
* **Full reference**: [Configuration Documentation](/getting-started/qtap/configuration.md)
* **Examples**: [Configuration Examples](/getting-started/qtap/configuration/configuration-examples.md)

### Creating Your Configuration File

1. Create a standard configuration directory with appropriate permissions:

   ```bash
   sudo mkdir -p /etc/qtap
   ```
2. Create your [configuration file](/getting-started/qtap/configuration.md):

   ```bash
   sudo nano /etc/qtap/qpoint.yaml
   ```
3. Set appropriate permissions:

   ```bash
   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:

   ```bash
   sudo touch /etc/qtap/environment
   sudo chmod 600 /etc/qtap/environment
   ```
5. Add any sensitive environment variables to this file:

   ```bash
   # 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:

   ```bash
   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:

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

## Verification

1. Check the service status:

   ```bash
   sudo systemctl status qtap
   ```
2. Verify the running version:

   ```bash
   qtap --version
   ```
3. Monitor the logs:

   ```bash
   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:

   ```bash
   sudo systemctl stop qtap
   ```
2. Download and install the new version:

   ```bash
   curl -s https://get.qpoint.io/install | sudo sh
   ```
3. Restart the service:

   ```bash
   sudo systemctl start qtap
   ```
4. Verify the update:

   ```bash
   qtap --version
   sudo systemctl status qtap
   ```

### Manually

1. Stop the service:

   ```bash
   sudo systemctl stop qtap
   ```
2. Download and install the new version:

   ```bash
   # 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:

   ```bash
   sudo systemctl start qtap
   ```
4. Verify the update:

   ```bash
   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.