Headless Installation

This installation guide provides step-by-step instructions for deploying Qpoint Proxy using Docker, enabling you to quickly set up a powerful and customizable egress proxy for controlling outbound traffic. Before beginning the installation, ensure Docker is installed and running on your system.

Prerequisites

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

• Configuration Files: Prepare your proxy-config.yaml and any optional WebAssembly (WASM) modules.

Docker Installation

1. Prepare Configuration Files:

   • Place your proxy-config.yaml and http_duration.wasm in a known directory. This directory will be mounted into the Docker container below.

2. Download the Docker Image:

   • Pull the latest version of the Qpoint Proxy Docker image

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

Run the Docker Container

Example 1: Running Without WASM Middleware

If you don't require custom middleware, you can omit the volume mount for the WASM file:

docker run \
    --name qpoint-proxy \
    -p 10080:10080 \
    -p 10443:10443 \
    -p 18080:18080 \
    -p 18443:18443 \
    -p 9901:9901 \
    -v ./proxy-config.yaml:/app/proxy-config.yaml \
    us-docker.pkg.dev/qpoint-edge/public/qpoint:head \
    proxy \
    --envoy-log-level=error \
    --log-level=debug \
    --qpoint-config ./proxy-config.yaml \
    --log-encoding="console" \
    --dns-lookup-family="V4_ONLY"

In this configuration, the proxy will run with the settings defined in proxy-config.yaml but without any additional processing provided by WASM modules.

Example 2: Running With WASM Middleware

For scenarios where middleware is needed, include the WASM file mount and ensure your configuration file references the correct WASM module path:

docker run \
    --name qpoint-proxy \   
    -p 10080:10080 \
    -p 10443:10443 \
    -p 18080:18080 \
    -p 18443:18443 \
    -p 9901:9901 \
    -v ./proxy-config.yaml:/app/proxy-config.yaml \
    -v ./wasm/http_duration.wasm:/app/wasm/http_duration.wasm \
    us-docker.pkg.dev/qpoint-edge/public/qpoint:head \
    proxy \
    --envoy-log-level=error \
    --log-level=debug \
    --qpoint-config ./proxy-config.yaml \
    --log-encoding="console" \
    --dns-lookup-family="V4_ONLY"

Flags

• --[no-]help: Shows help information. Variants include --help-long and --help-man.

• --data-dir="/tmp/qtap": Specifies the directory to store state, defaulting to /tmp/qtap.

• --tags=TAGS: Tags to auto-attach to metrics.

• --middleware-egress-listen=":11001": Specifies the IP:PORT for middleware egress traffic, defaulting to :11001.

• --registration-endpoint="https://api.qpoint.io": Registration endpoint for the proxy.

• --registration-token=REGISTRATION-TOKEN: Token used for registration.

• --qpoint-config=QPOINT-CONFIG: Path to the configuration file.

• --status-listen="0.0.0.0:10001": IP:PORT where the status server listens, defaulting to 0.0.0.0:10001.

• --envoy-config-root=".": Root directory for generating dynamic Envoy configurations.

• --envoy-log-level=error: Log level for Envoy, defaulting to error.

• --dns-lookup-family=V4_ONLY: DNS lookup family, options include V4_ONLY.

• --default-tcp-listen-address="0.0.0.0": Default TCP IP address for listening, defaulting to 0.0.0.0.

• --transparent-tcp-forward-ports="18080:80,18443:443": Comma-separated list of <IP:>LISTEN_PORT:DESTINATION_PORT for transparent TCP listening and forwarding.

• --middleware-tcp-forward-ports="10080:80,10443:443": Comma-separated list of <IP:>LISTEN_PORT:DESTINATION_PORT for middleware TCP listening and forwarding.

• --unknown-endpoint-file-path="./unknown": File path for unknown endpoints.

• --unknown-endpoint-cache-size=1000: Cache size for unknown endpoints, defaulting to 1000.

• --log-level=error: Log level, defaulting to error.

• --log-encoding=json: Log encoding format, defaulting to json.

• --[no-]log-caller: Flag to include the log caller in the logs.

Troubleshooting

If you encounter issues during the installation:

• Check Docker Logs: Use docker logs [container_id] to view the logs for the proxy container. This can provide insight into any errors or configuration issues.

• Configuration Validation: Ensure that your proxy-config.yaml is correctly formatted and all paths to files are correctly mapped in the Docker command.

By following these steps, you should have a functioning instance of Qpoint Proxy deployed using Docker, ready to be configured for your specific network requirements.