Proxy Config Reference

This document describes the configuration options for QHx Proxy, including configuration file format, command-line flags, and environment variables.

Configuration Sources

QHx Proxy accepts configuration from two sources:

1. Configuration file: A YAML file specified with the -config flag
2. Environment variable: YAML configuration in the QHX_PROXY_CONFIG environment variable. This is direct YAML text, not a filename.

If no -config flag is provided, the proxy will read the configuration from the QHX_PROXY_CONFIG environment variable. If neither is provided, the proxy will exit with an error.

Command-Line Flags

The following command line flags are supported:

• -config <string>: Path to the YAML configuration file. If not specified, YAML configuration data is taken directly from the environment variable QHX_PROXY_CONFIG.

• -zap-log-level <value>: Configure logging level (debug, info, error, panic or an integer). Higher integer values give higher verbosity.

• -zap-encoder {json | console}: Configures the logging output format.

• -zap-devel: Enables development mode logging configuration.

Environment Variables

QHX_PROXY_CONFIG

• Type: String (YAML or JSON content)
• Required: Only if -config flag is not provided
• Description: Complete YAML/JSON configuration as a string

Example:

export QHX_PROXY_CONFIG='
spiffe:
  workload_socket_path: "unix:///tmp/spire-agent/public/api.sock"
listeners:
  - name: "example"
    address: ":8080"
    mode: "client"
    target:
      url: "https://example.com"
'

Configuration File Format

The configuration file uses YAML with the following structure:

Root Configuration

# SPIFFE configuration (required)
spiffe:
  workload_socket_path: "unix:///tmp/spire-agent/public/api.sock"

# Optional: TLS key logging for debugging
keylog: "/path/to/keylog.txt"

# Listeners configuration (required - at least one)
listeners:
  - name: "example-client"
    address: ":8081"
    protocol: http
    mode: client
    target:
      url: https://onward.example:8081
      spiffe_id: "^spiffe://qhx.dev/ns/foo/sa/bar/.*$"

  - name: "example-server"
    address: ":8082"
    protocol: http
    mode: server
    source:
      spiffe_ids:
        - "^spiffe://qhx.dev/ns/foo/sa/bar/.*$"
    target:
      url: http://localhost:8083

SPIFFE Configuration

The spiffe section configures SPIFFE/SPIRE integration:

workload_socket_path

• Type: String
• Required: Yes
• Description: Path to SPIRE Workload API socket
• Format: Unix socket path (e.g., unix:///tmp/spire-agent/public/api.sock)

Optional Global Settings

keylog

• Type: String
• Required: No
• Description: Path to TLS key log file for debugging TLS connections
• Note: Debugging use only — contains cryptographic keys which compromise confidentiality and integrity of TLS connections

Listeners Configuration

The listeners section defines one or more proxy listeners. Each listener operates independently and can be configured in different modes.

Basic Listener Properties

name

• Type: String
• Required: Yes
• Description: Unique name for the listener
• Constraints: Must be unique across all listeners

address

• Type: String
• Required: Yes
• Description: Network address to listen on
• Format: host:port (e.g., :8080, 127.0.0.1:8081, 0.0.0.0:9000)

mode

• Type: String
• Required: Yes
• Values: "client", "server" or "central"
• Description:
  • client: Client mode - forwards requests over secure mTLS transport
  • server: Server mode - terminates mTLS and forwards to target servers
  • central: Central mode - terminates mTLS and forwards to target servers over mTLS in turn

protocol

• Type: String
• Default: "http"
• Values: "http" (only supported protocol currently)
• Description: Protocol to use for proxying

Target Configuration

Each listener must specify a target using the target section:

url

• Type: String
• Required: Yes
• Description: Target URL to proxy requests to
• Format: Full URL including scheme (e.g., https://api.example.com:8443, http://backend:8080)

spiffe_id

• Type: String
• Required: No (recommended for client mode; validation omitted if not specified)
• Description: Expected SPIFFE ID of the target service
• Format: SPIFFE ID URI (e.g., spiffe://example.org/service-name)
• Note: Used in client mode to validate the target’s identity

Source Configuration (Server Mode)

For server mode listeners, you can restrict which clients are allowed to connect:

spiffe_ids

• Type: Array of strings
• Required: No
• Description: List of allowed client SPIFFE ID patterns (each pattern is a regular expression)
• Default: If not specified, any authenticated SPIFFE client is allowed
• Format: Regular expressions matching SPIFFE ID URIs

Example:

source:
  spiffe_ids:
    - "spiffe://example\\.org/web-.*"      # Allow web services
    - "spiffe://trusted\\.domain/.*"       # Allow any service from trusted domain
    - "spiffe://example\\.org/api-client"  # Allow specific client

Timeout Configuration

Each listener can specify custom timeouts:

read

• Type: Duration string
• Default: "15s"
• Description: Maximum time to read request headers and body
• Format: Go duration format (e.g., "30s", "1m", "500ms")

write

• Type: Duration string
• Default: "60s"
• Description: Maximum time to write response
• Format: Go duration format (e.g., "30s", "2m", "5000ms")

idle

• Type: Duration string
• Default: "120s"
• Description: Maximum time to wait for next request on keep-alive connections
• Format: Go duration format (e.g., "60s", "5m")

Complete Configuration Examples

Client Mode Example

This example configures QHx Proxy in client mode using the HTTP protocol. The application is able to make unencrypted HTTP requests to http://localhost:8081, which are encapsulated in a post-quantum secure mTLS connection to a peer QHx Proxy instance in server mode or a QHx Proxy instance in central mode. The mTLS connection is based on mutual authentication using cryptographically secure, post-quantum safe workload identities for both client and server, which is entirely transparent to the application.

spiffe:
  workload_socket_path: "unix:///tmp/spire-agent/public/api.sock"

listeners:
  - name: "api-client"
    ## Listen on localhost:8081 in client mode using the HTTP protocol
    address: "127.0.0.1:8081"
    mode: "client"
    protocol: "http"
    target:
      ## Destination address
      url: "https://api.example.com:8443"
      ## Require the destination to match this workload identity
      spiffe_id: "spiffe://example.org/api-server"
    timeouts:
      read: "30s"
      write: "60s"
      idle: "300s"

Server Mode Example

This example configures QHx Proxy in server mode using the HTTP protocol. Incoming requests are required to use mTLS and are verified as using a post-quantum safe workload identity which is authorized according to the configuration below. The request is then de-encapsulated and forwarded to the local application server.

spiffe:
  workload_socket_path: "unix:///tmp/spire-agent/public/api.sock"

listeners:
  - ## Listen on :8443 in server mode using the HTTP protocol
    name: "secure-gateway"
    address: ":8443"
    mode: "server"
    protocol: "http"
    target:
      ## Forward to this pod-internal service
      url: "http://localhost:8080"
    source:
      spiffe_ids:
        ## Allow connections from clients with these IDs
        - "spiffe://example\\.org/web-.*"
        - "spiffe://example\\.org/api-gateway"
    timeouts:
      read: "15s"
      write: "60s"
      idle: "120s"

Central Mode Example

spiffe:
  workload_socket_path: "unix:///tmp/spire-agent/public/api.sock"

notary:
  enable: true
  database:
    path: /var/qhx/notary/notary.db

listeners:
  # Central mode listener
  - name: central-http
    address: ":8081"
    mode: central
    protocol: http
    target:
      url: "https://service:8081"
      spiffe_ids:
        - "spiffe://qhx.dev/foo"
    source:
      spiffe_ids:
        - "spiffe://qhx.dev/bar"
    middleware:
      - type: openai
      - type: notary-query

Multi-Listener Example

spiffe:
  workload_socket_path: "unix:///tmp/spire-agent/public/api.sock"

listeners:
  # Client mode listener
  - name: "external-api-client"
    address: ":8081"
    mode: client
    protocol: http
    target:
      url: "https://api.external.com"
      spiffe_id: "spiffe://external.example.org/api"

  # Server mode listener
  - name: "internal-server"
    address: ":8082"
    mode: server
    protocol: http
    target:
      url: "http://backend:3000"
    source:
      spiffe_ids:
        - "spiffe://internal\\.example\\.org/.*"