Docker Container

This guide provides comprehensive instructions for deploying Qtap using Docker, enabling you to quickly set up a powerful and customizable eBPF probe for monitoring outbound traffic.

Prerequisites

1. Docker: Ensure Docker is installed on your host machine. For installation instructions, refer to the Docker official documentation.

2. Configuration Files: Prepare your Qtap YAML config file and any optional WebAssembly (WASM) middleware modules.

Installation Steps

Download the Docker Image

docker pull us-docker.pkg.dev/qpoint-edge/public/qpoint:v0.1.6

Note: Replace v0.1.6 with the desired version of Qtap. Use "head" for latest

Run the Docker Container

docker run \
  --user 0:0 \
  --privileged \
  --cap-add CAP_BPF \
  --cap-add CAP_SYS_ADMIN \
  --pid=host \
  --network=host \
  -v /sys:/sys \
  -v "$(pwd):/app/config" \
  -e TINI_SUBREAPER=1 \
  --ulimit=memlock=-1 \
  us-docker.pkg.dev/qpoint-edge/public/qpoint:v0.1.6 \
  tap \
  --log-level=info \
  --log-encoding=console \
  --qpoint-config=/app/config/qpoint.yaml

Docker Run Command Options Explained

1. --user 0:0: Runs the container as root (necessary for eBPF operations).

2. --privileged: Gives extended privileges to this container.

3. --cap-add CAP_BPF: Adds the CAP_BPF capability (required for eBPF operations).

4. --cap-add CAP_SYS_ADMIN: Adds the CAP_SYS_ADMIN capability (for low-level system operations).

5. --pid=host: Shares the host's PID namespace with the container.

6. --network=host: Uses the host's network stack inside the container.

7. -v /sys:/sys: Mounts the host's /sys directory into the container.

8. -v "$(pwd):/app/config": Mounts the current directory to /app/config in the container.

9. -e TINI_SUBREAPER=1: Sets up Tini as a subreaper for proper signal handling.

10. --ulimit=memlock=-1: Removes the memory lock limit for eBPF programs.

Qtap-specific Flags

• --log-level=info: Sets the logging level.

• --log-encoding=console: Sets the log encoding format.

• --qpoint-config=/app/config/qpoint.yaml: Specifies the path to the Qtap configuration file.

Available Flags and Options

To see all available options and flags, run:

docker run --rm us-docker.pkg.dev/qpoint-edge/public/qpoint:v0.1.6 tap --help

Key flags include:

• --http-display=none: Captured HTTP traffic display mode. (Env: $HTTP_DISPLAY_MODE)

• --registration-endpoint="https://api.qpoint.io": Registration endpoint. (Env: $REGISTRATION_ENDPOINT)

• --registration-token=REGISTRATION-TOKEN: Registration token. (Env: $REGISTRATION_TOKEN)

• --data-dir="/tmp/qpoint": Directory to store state. (Env: $DATA_DIR)

• --qpoint-config=QPOINT-CONFIG: Configuration file path. (Env: $QPOINT_CONFIG)

• --unknown-endpoint-cache-size=1000: Cache size for unknown endpoints. (Env: $UNKNOWN_ENDPOINT_CACHE_SIZE)

• --audit-log-buffer-size=1000: Buffer size for audit logs. (Env: $AUDIT_LOG_BUFFER_SIZE)

• --log-level=error: Log level. (Env: $LOG_LEVEL)

• --log-encoding=json: Log encoding. (Env: $LOG_ENCODING)

• --[no-]log-caller: Log caller. (Env: $LOG_CALLER)

• --status-listen="0.0.0.0:10001": IP:PORT of status server to listen on. (Env: $STATUS_LISTEN)

Important Notes

1. Ensure you're using the correct version of Qtap. The examples use v0.1.6, but you should use the version appropriate for your needs.

2. The Qtap-specific flags should be placed after the tap command in the Docker run command.

3. The --qpoint-config flag is crucial for specifying your configuration file. Ensure the path is correct relative to the mounted volume.

4. Some options can be set via environment variables. The corresponding environment variable is listed for each flag where applicable.