Skip to main content

Configuration Reference

Moat supports three configuration methods with the following priority (highest to lowest):

  1. YAML Configuration File - Comprehensive configuration via config.yaml
  2. Command Line Arguments - Override specific settings via CLI flags
  3. Environment Variables - Set configuration via AX_* prefixed variables

YAML Configuration​

Complete Example​

server:
  upstream: "http://localhost:8080"
  http_addr: "0.0.0.0:80"
  tls_addr: "0.0.0.0:443"
  http_bind:
    - "0.0.0.0:8081"
  tls_bind:
    - "0.0.0.0:8443"
  health_check:
    enabled: true
    endpoint: "/health"
    port: "0.0.0.0:8080"
    methods:
      - "GET"
      - "HEAD"
    allowed_cidrs:
      - "127.0.0.0/8"
      - "::1/128"

tls:
  mode: "acme"  # disabled, custom, or acme
  only: false

# Custom TLS (when mode is "custom")
tls_custom:
  cert_path: "/path/to/cert.pem"
  key_path: "/path/to/key.pem"

# ACME/Let's Encrypt (when mode is "acme")
acme:
  domains:
    - "example.com"
    - "www.example.com"
  contacts:
    - "[email protected]"
  use_prod: true
  accept_tos: true
  directory: "https://acme-v02.api.letsencrypt.org/directory"
  ca_root: "/path/to/ca-bundle.pem"  # optional

redis:
  url: "redis://127.0.0.1/0"
  prefix: "ax:moat"

network:
  iface: "eth0"
  ifaces:
    - "eth0"
    - "eth1"
  disable_xdp: false

arxignis:
  api_key: "your-api-key"
  base_url: "https://api.arxignis.com/v1"
  log_sending:
    enabled: true
    include_response_body: true
    max_body_size: 1048576  # 1MB

captcha:
  site_key: "your-site-key"
  secret_key: "your-secret-key"
  jwt_secret: "your-jwt-secret"
  provider: "turnstile"  # hcaptcha, recaptcha, or turnstile
  token_ttl: 7200
  cache_ttl: 300

content_scanning:
  enabled: true
  clamav_server: "localhost:3310"
  max_file_size: 10485760  # 10MB
  scan_content_types:
    - "text/html"
    - "application/x-www-form-urlencoded"
    - "multipart/form-data"
  skip_extensions:
    - ".jpg"
    - ".png"
    - ".gif"
  scan_expression: 'http.request.method eq "POST" or http.request.method eq "PUT"'

domains:
  whitelist:
    - "trusted.com"
    - "secure.example.com"

proxy_protocol:
  enabled: true
  timeout: 1000  # milliseconds

bpf_stats:
  enabled: true
  log_interval: 60
  enable_dropped_ip_events: true
  dropped_ip_events_interval: 30

tcp_fingerprint:
  enabled: true
  log_interval: 60
  enable_fingerprint_events: true
  events_interval: 30
  min_packet_count: 3
  min_connection_duration: 1

daemon:
  enabled: false
  pid_file: "/var/run/moat.pid"
  working_directory: "/"
  stdout: "/var/log/moat.out"
  stderr: "/var/log/moat.err"
  user: "nobody"
  group: "daemon"
  chown_pid_file: true

logging:
  level: "info"  # error, warn, info, debug, trace

Command Line Options​

Basic Usage​

moat [OPTIONS]

Required Options​

--arxignis-api-key <KEY>    # API key for Arxignis service
--upstream <URL>            # Upstream origin URL

Network Configuration​

--iface <INTERFACE>         # Network interface for XDP (default: eth0)
--ifaces <INTERFACES>       # Multiple interfaces (comma-separated)
--disable-xdp               # Disable XDP packet filtering

--http-addr <ADDRESS>       # HTTP server bind address (default: 0.0.0.0:80)
--http-bind <ADDRESSES>     # Additional HTTP bind addresses
--tls-addr <ADDRESS>        # HTTPS bind address (default: 0.0.0.0:443)
--tls-bind <ADDRESSES>      # Additional HTTPS bind addresses

TLS Configuration​

--tls-mode <MODE>           # disabled, custom, or acme (default: disabled)
--tls-only                  # Reject non-SSL requests
--tls-cert-path <PATH>      # Custom certificate path
--tls-key-path <PATH>       # Custom private key path

ACME Configuration​

--acme-domains <DOMAINS>    # Domains for ACME (comma-separated)
--acme-contacts <CONTACTS>  # Contact addresses (comma-separated)
--acme-use-prod             # Use Let's Encrypt production
--acme-accept-tos           # Accept ACME Terms of Service
--acme-directory <URL>      # Override ACME directory URL
--acme-ca-root <PATH>       # Custom CA bundle

Redis Configuration​

--redis-url <URL>           # Redis connection URL (default: redis://127.0.0.1/0)
--redis-prefix <PREFIX>     # Namespace prefix (default: ax:moat)

CAPTCHA Configuration​

--captcha-site-key <KEY>    # CAPTCHA site key
--captcha-secret-key <KEY>  # CAPTCHA secret key
--captcha-jwt-secret <SECRET> # JWT secret for tokens
--captcha-provider <PROVIDER> # hcaptcha, recaptcha, or turnstile
--captcha-token-ttl <SECONDS> # Token TTL (default: 7200)
--captcha-cache-ttl <SECONDS> # Cache TTL (default: 300)

Domain Filtering​

--domain-whitelist <DOMAINS> # Allowed domains (comma-separated)

PROXY Protocol​

--proxy-protocol-enabled    # Enable PROXY protocol support
--proxy-protocol-timeout <MS> # Timeout in milliseconds (default: 1000)

Daemon Mode​

--daemon, -d                # Run as daemon
--daemon-pid-file <PATH>    # PID file path (default: /var/run/moat.pid)
--daemon-working-dir <PATH> # Working directory (default: /)
--daemon-stdout <PATH>      # Stdout log file (default: /var/log/moat.out)
--daemon-stderr <PATH>      # Stderr log file (default: /var/log/moat.err)
--daemon-user <USER>        # User to run as (e.g., nobody)
--daemon-group <GROUP>      # Group to run as (e.g., daemon)

Logging​

--log-level <LEVEL>         # error, warn, info, debug, trace (default: info)

Environment Variables​

All configuration options can be overridden using environment variables with the AX_ prefix:

Server Configuration​

AX_SERVER_UPSTREAM="http://localhost:8080"
AX_SERVER_HTTP_ADDR="0.0.0.0:80"
AX_SERVER_TLS_ADDR="0.0.0.0:443"
AX_SERVER_HTTP_BIND="0.0.0.0:8081,0.0.0.0:8082"
AX_SERVER_TLS_BIND="0.0.0.0:8443"

Health Check Configuration​

AX_SERVER_HEALTH_CHECK_ENABLED="true"
AX_SERVER_HEALTH_CHECK_ENDPOINT="/health"
AX_SERVER_HEALTH_CHECK_PORT="0.0.0.0:8080"
AX_SERVER_HEALTH_CHECK_METHODS="GET,HEAD"
AX_SERVER_HEALTH_CHECK_ALLOWED_CIDRS="127.0.0.0/8,::1/128"

TLS Configuration​

AX_TLS_MODE="acme"
AX_TLS_ONLY="false"
AX_TLS_CUSTOM_CERT_PATH="/path/to/cert.pem"
AX_TLS_CUSTOM_KEY_PATH="/path/to/key.pem"

ACME Configuration​

AX_ACME_DOMAINS="example.com,www.example.com"
AX_ACME_CONTACTS="[email protected]"
AX_ACME_USE_PROD="true"
AX_ACME_ACCEPT_TOS="true"
AX_ACME_DIRECTORY="https://acme-v02.api.letsencrypt.org/directory"
AX_ACME_CA_ROOT="/path/to/ca-bundle.pem"

Redis Configuration​

AX_REDIS_URL="redis://127.0.0.1/0"
AX_REDIS_PREFIX="ax:moat"

Network Configuration​

AX_NETWORK_IFACE="eth0"
AX_NETWORK_IFACES="eth0,eth1"
AX_NETWORK_DISABLE_XDP="false"

Arxignis Configuration​

AX_ARXIGNIS_API_KEY="your-api-key"
AX_ARXIGNIS_BASE_URL="https://api.arxignis.com/v1"
AX_ARXIGNIS_LOG_SENDING_ENABLED="true"
AX_ARXIGNIS_INCLUDE_RESPONSE_BODY="true"
AX_ARXIGNIS_MAX_BODY_SIZE="1048576"

CAPTCHA Configuration​

AX_CAPTCHA_SITE_KEY="your-site-key"
AX_CAPTCHA_SECRET_KEY="your-secret-key"
AX_CAPTCHA_JWT_SECRET="your-jwt-secret"
AX_CAPTCHA_PROVIDER="turnstile"
AX_CAPTCHA_TOKEN_TTL="7200"
AX_CAPTCHA_CACHE_TTL="300"

Content Scanning Configuration​

AX_CONTENT_SCANNING_ENABLED="true"
AX_CLAMAV_SERVER="localhost:3310"
AX_CONTENT_MAX_FILE_SIZE="10485760"
AX_CONTENT_SCAN_CONTENT_TYPES="text/html,application/x-www-form-urlencoded,multipart/form-data"
AX_CONTENT_SKIP_EXTENSIONS=".jpg,.png,.gif"
AX_CONTENT_SCAN_EXPRESSION='http.request.method eq "POST" or http.request.method eq "PUT"'

Domain Filtering​

AX_DOMAINS_WHITELIST="trusted.com,secure.example.com"

PROXY Protocol​

AX_PROXY_PROTOCOL_ENABLED="true"
AX_PROXY_PROTOCOL_TIMEOUT="1000"

BPF Statistics​

AX_BPF_STATS_ENABLED="true"
AX_BPF_STATS_LOG_INTERVAL="60"
AX_BPF_STATS_ENABLE_DROPPED_IP_EVENTS="true"
AX_BPF_STATS_DROPPED_IP_EVENTS_INTERVAL="30"

TCP Fingerprinting​

AX_TCP_FINGERPRINT_ENABLED="true"
AX_TCP_FINGERPRINT_LOG_INTERVAL="60"
AX_TCP_FINGERPRINT_ENABLE_FINGERPRINT_EVENTS="true"
AX_TCP_FINGERPRINT_EVENTS_INTERVAL="30"
AX_TCP_FINGERPRINT_MIN_PACKET_COUNT="3"
AX_TCP_FINGERPRINT_MIN_CONNECTION_DURATION="1"

Daemon Configuration​

AX_DAEMON_ENABLED="false"
AX_DAEMON_PID_FILE="/var/run/moat.pid"
AX_DAEMON_WORKING_DIRECTORY="/"
AX_DAEMON_STDOUT="/var/log/moat.out"
AX_DAEMON_STDERR="/var/log/moat.err"
AX_DAEMON_USER="nobody"
AX_DAEMON_GROUP="daemon"
AX_DAEMON_CHOWN_PID_FILE="true"

Logging Configuration​

AX_LOGGING_LEVEL="info"

Usage Examples​

HTTP Proxy​

moat --iface eth0 --arxignis-api-key "your-key" --upstream "http://127.0.0.1:8081"

HTTPS with Custom TLS​

moat --iface eth0 --tls-mode custom \
  --tls-cert-path /path/to/cert.pem \
  --tls-key-path /path/to/key.pem \
  --upstream "http://127.0.0.1:8081" \
  --arxignis-api-key "your-key"

HTTPS with ACME​

moat --iface eth0 --tls-mode acme \
  --acme-domains "example.com,www.example.com" \
  --acme-contacts "[email protected]" \
  --upstream "http://127.0.0.1:8081" \
  --arxignis-api-key "your-key"

With CAPTCHA Protection​

moat --iface eth0 \
  --captcha-site-key "your-site-key" \
  --captcha-secret-key "your-secret-key" \
  --captcha-jwt-secret "your-jwt-secret" \
  --captcha-provider "turnstile" \
  --upstream "http://127.0.0.1:8081" \
  --arxignis-api-key "your-key"

Configuration File​

moat --config /path/to/config.yaml

Next Steps​