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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qpoint.io/getting-started/qtap/installation/linux-binary.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.