Docker Container

Prerequisites

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

• (For cloud-connected mode) Registration Token: Valid registration token from app.qpoint.io

• (For local mode) Configuration Files: Prepare your Qtap YAML config file

Installation Steps

1. Download the Docker Image:

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

Running Qtap in Docker

Cloud-Connected Mode

To run Qtap in cloud-connected mode, use the following command:

docker run \
  --user 0:0 \
  --privileged \
  --cap-add CAP_BPF \
  --cap-add CAP_SYS_ADMIN \
  --pid=host \
  --network=host \
  -v /sys:/sys \
  -e TINI_SUBREAPER=1 \
  --ulimit=memlock=-1 \
  us-docker.pkg.dev/qpoint-edge/public/qpoint:v0 \
  tap \
  --log-level=info \
  --log-encoding=console \
  --registration-token=$TOKEN

Replace $TOKEN with your actual registration token obtained from app.qpoint.io.

Local Mode

To run Qtap in local mode, use the following command:

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 \
  tap \
  --log-level=info \
  --log-encoding=console \
  --qpoint-config=/app/config/qpoint.yaml

Replace /app/config/qpoint.yaml with the actual path to your YAML configuration file inside the container. Make sure to mount your local configuration file to this path using the -v option.

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.

• --registration-token=$TOKEN: (Cloud-connected mode) Provides the registration token for Qtap.

• --qpoint-config=/app/config/qpoint.yaml: (Local mode) 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 tap --help

Key flags include:

• --[no-]help: Show context-sensitive help (also try --help-long and --help-man).

• --[no-]version: Show application version.

• --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)

• --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. Use "head" for latest.

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

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

4. For cloud-connected mode, the --registration-token flag is essential for associating your Qtap instance with app.qpoint.io. Ensure you replace $TOKEN with your actual registration token.

5. For local mode, ensure the path to your configuration file is correct relative to the mounted volume.

6. The -v "$(pwd):/app/config" option mounts the current directory to /app/config in the container. Ensure your configuration files are in the current directory when running the container, or adjust the path as needed.