Configuration Reference

Synapse supports three configuration methods (highest to lowest priority):

1. YAML Configuration File - via config.yaml
2. Command Line Arguments - override specific settings via CLI flags
3. Environment Variables - e.g. export API_KEY="your-key"

YAML Configuration

Basic Example

mode: "proxy"  # or "agent" (default)

platform:
  api_key: "your-api-key"
  base_url: "https://api.gen0sec.com/v1"
  log_sending_enabled: true

proxy:
  address_http: "0.0.0.0:80"
  address_tls: "0.0.0.0:443"
  upstream:
    conf: "/etc/synapse/upstreams.yaml"

firewall:
  mode: "auto"  # auto, xdp, nftables, iptables, none
  disable_xdp: false

network:
  iface: "eth0"
  ip_version: "both"  # ipv4, ipv6, both

logging:
  level: "info"

Feature Toggles

Feature	YAML Path	Environment Variable	Default
BPF Statistics	logging.bpf_stats.enabled	BPF_STATS_ENABLED	true
TCP Fingerprinting	logging.tcp_fingerprint.enabled	TCP_FINGERPRINT_ENABLED	true
Content Scanning	proxy.content_scanning.enabled	CONTENT_SCANNING_ENABLED	false
CAPTCHA Protection	(enabled when keys are set)	CAPTCHA_SITE_KEY, CAPTCHA_SECRET_KEY	disabled
ACME (Auto TLS)	proxy.acme.enabled	ACME_ENABLED	false
Internal Services	proxy.internal_services.enabled	INTERNAL_SERVICES_ENABLED	true
PROXY Protocol	proxy.protocol.enabled	PROXY_PROTOCOL_ENABLED	false
File Logging	logging.file_logging_enabled	LOGGING_FILE_ENABLED	false
Syslog	logging.syslog.enabled	LOGGING_SYSLOG_ENABLED	false
Log Sending (API)	platform.log_sending_enabled	LOG_SENDING_ENABLED	true
XDP Firewall	firewall.disable_xdp	FIREWALL_DISABLE_XDP	false (XDP enabled)

Complete Configuration Example

mode: "proxy"

platform:
  api_key: "your-api-key"
  base_url: "https://api.gen0sec.com/v1"
  log_sending_enabled: true
  include_response_body: true
  max_body_size: 1048576  # 1MB

proxy:
  address_http: "0.0.0.0:80"
  address_tls: "0.0.0.0:443"
  upstream:
    conf: "/etc/synapse/upstreams.yaml"

  acme:
    enabled: true
    port: 9180
    email: "admin@example.com"
    storage_path: "/var/lib/synapse/acme"
    storage_type: "redis"  # or "file"
    development: false

  geoip:
    refresh_secs: 28800  # 8 hours
    country: { url: "https://git.io/GeoLite2-Country.mmdb", path: "/var/lib/synapse" }
    asn: { url: "https://git.io/GeoLite2-ASN.mmdb", path: "/var/lib/synapse" }
    city: { url: "https://git.io/GeoLite2-City.mmdb", path: "/var/lib/synapse" }

  content_scanning:
    enabled: true
    clamav_server: "localhost:3310"
    max_file_size: 10485760  # 10MB

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

  internal_services:
    enabled: true
    port: 9180
    bind_ip: "127.0.0.1"

  protocol:
    enabled: false
    timeout: 1000

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

  certificates:
    # Custom TLS certificates (optional)

platform:
  api_key: "your-api-key"
  base_url: "https://api.gen0sec.com/v1"
  log_sending_enabled: true
  include_response_body: true
  max_body_size: 1048576
  threat:
    url: "https://download.gen0sec.com/v1"
    path: "/var/lib/synapse"
    refresh_secs: 300  # 5 minutes

firewall:
  mode: "auto"  # auto, xdp, nftables, iptables, none
  disable_xdp: false

network:
  iface: "eth0"
  ifaces: ["eth0", "eth1"]  # overrides iface
  ip_version: "both"  # ipv4, ipv6, both

logging:
  level: "info"  # error, warn, info, debug, trace
  file_logging_enabled: true
  log_directory: "/var/log/synapse"
  max_log_size: 104857600  # 100MB
  log_file_count: 10

  bpf_stats:
    enabled: true
    log_interval_secs: 60
    enable_dropped_ip_events: true
    dropped_ip_events_interval_secs: 30

  tcp_fingerprint:
    enabled: true
    log_interval_secs: 60
    enable_fingerprint_events: true
    fingerprint_events_interval_secs: 30
    min_packet_count: 3
    min_connection_duration_secs: 1

  syslog:
    enabled: false
    facility: "daemon"
    identifier: "synapse"

daemon:
  enabled: false
  pid_file: "/var/run/synapse.pid"
  working_directory: "/"
  user: "root"
  group: "root"
  chown_pid_file: true

Environment Variables

# Application mode
export MODE="proxy"  # or "agent"

# Redis configuration
export REDIS_URL="redis://127.0.0.1/0"
export REDIS_PREFIX="ax:synapse"

# Network configuration
export NETWORK_IFACE="eth0"
export NETWORK_IFACES="eth0,eth1"
export NETWORK_IP_VERSION="both"
export FIREWALL_MODE="auto"
export FIREWALL_DISABLE_XDP="false"

# Gen0Sec Platform
export API_KEY="your-api-key"
export BASE_URL="https://api.gen0sec.com/v1"
export LOG_SENDING_ENABLED="true"

# CAPTCHA
export CAPTCHA_SITE_KEY="your-site-key"
export CAPTCHA_SECRET_KEY="your-secret-key"
export CAPTCHA_JWT_SECRET="your-jwt-secret"
export CAPTCHA_PROVIDER="turnstile"
export CAPTCHA_TOKEN_TTL="7200"
export CAPTCHA_CACHE_TTL="300"

# Content scanning
export CONTENT_SCANNING_ENABLED="true"
export CLAMAV_SERVER="localhost:3310"
export CONTENT_MAX_FILE_SIZE="10485760"

# Internal services
export INTERNAL_SERVICES_ENABLED="true"
export INTERNAL_SERVICES_PORT="9180"
export INTERNAL_SERVICES_BIND_IP="127.0.0.1"

# PROXY protocol
export PROXY_PROTOCOL_ENABLED="true"
export PROXY_PROTOCOL_TIMEOUT="1000"

# Daemon mode
export DAEMON_ENABLED="false"
export DAEMON_PID_FILE="/var/run/synapse.pid"
export DAEMON_WORKING_DIRECTORY="/"
export DAEMON_USER="root"
export DAEMON_GROUP="root"

# Logging
export LOGGING_LEVEL="info"
export LOGGING_FILE_ENABLED="true"
export LOGGING_DIRECTORY="/var/log/synapse"
export LOGGING_MAX_FILE_SIZE="104857600"
export LOGGING_FILE_COUNT="10"
export LOGGING_SYSLOG_ENABLED="false"

# BPF stats
export BPF_STATS_ENABLED="true"
export BPF_STATS_LOG_INTERVAL="60"

# TCP fingerprinting
export TCP_FINGERPRINT_ENABLED="true"
export TCP_FINGERPRINT_LOG_INTERVAL="60"

# ACME
export ACME_ENABLED="true"
export ACME_EMAIL="admin@example.com"
export ACME_STORAGE_TYPE="redis"

# Threat intelligence
export THREAT_MMDB_URL="https://download.gen0sec.com/v1"
export THREAT_MMDB_PATH="/var/lib/synapse"

# GeoIP
export GEOIP_COUNTRY_URL="https://git.io/GeoLite2-Country.mmdb"
export GEOIP_COUNTRY_PATH="/var/lib/synapse"
export GEOIP_REFRESH_SECS="28800"

Upstreams Configuration

Synapse supports advanced upstream routing via a separate configuration file with hot-reloading. Supports multiple service discovery providers: file, Consul, and Kubernetes.

File Provider

provider: "file"
config:
  https_proxy_enabled: false
  sticky_sessions: true
  global_rate_limit: 100
  global_request_headers:
    - "X-Proxy-From:Synapse"
  global_response_headers:
    - "Access-Control-Allow-Origin:*"

internal_paths:
  "/cgi-bin/captcha/verify":
    rate_limit: 200
    servers:
      - "127.0.0.1:9180"

upstreams:
  example.com:
    certificate: "example.com"
    acme:
      challenge_type: "dns-01"  # or "http-01" (default)
      email: "admin@example.com"
      wildcard: true
    paths:
      "/":
        rate_limit: 200
        force_https: true
        ssl_enabled: true
        request_headers:
          - "Host: api.example.com"
        connection_timeout: 30
        read_timeout: 120
        write_timeout: 30
        idle_timeout: 60
        servers:
          - "127.0.0.1:8000"
          - address: "127.0.0.1:8001"
            weight: 3
          - address: "127.0.0.1:8002"
            weight: 2

Kubernetes Provider

provider: "kubernetes"
config:
  sticky_sessions: true
  global_rate_limit: 300

kubernetes:
  servers:
    - "https://k8s-api.example.com:6443"
  tokenpath: "/var/run/secrets/kubernetes.io/serviceaccount/token"
  services:
    - upstream: "http://my-service.default.svc.cluster.local:8080"
      hostname: "api.example.com"
      path: "/"
      rate_limit: 500

Consul Provider

provider: "consul"
config:
  sticky_sessions: true
  global_rate_limit: 200

consul:
  servers:
    - "consul1.example.com:8500"
    - "consul2.example.com:8500"
  token: "your-consul-token"
  services:
    - upstream: "http://service-name.service.consul:8080"
      hostname: "api.example.com"
      path: "/"
      rate_limit: 500

SIGHUP Configuration Reload

Synapse supports runtime configuration reload via SIGHUP signal:

kill -HUP $(cat /var/run/synapse.pid)

Hot-reloadable Settings

Setting	Config Path	Notes
Log level	logging.level	Switches log verbosity instantly
Log sending	platform.log_sending_enabled	Enable/disable API log sending
API key	platform.api_key	Update platform credentials
Base URL	platform.base_url	Change API endpoint
Include response body	platform.include_response_body	Toggle body capture in access logs
Max body size	platform.max_body_size	Adjust body size limit for logs
Upstreams	proxy.upstream.conf	Re-reads upstreams YAML file
Security rules	Local file or API	Re-fetches access rules and WAF rules
GeoIP databases	proxy.geoip.*	Re-downloads MMDB files

Settings That Require Restart

Setting	Config Path	Reason
Listen addresses	proxy.address_http, proxy.address_tls	Port bindings set at startup
Network interface	network.iface, network.ifaces	XDP attached at startup
Firewall mode	firewall.mode, firewall.disable_xdp	BPF programs loaded at startup
Runtime threads	multi_thread, worker_threads	Tokio runtime created at startup
Daemon settings	daemon.*	Process daemonization is one-time
Redis connection	proxy.redis.*	Connection pool created at startup
CAPTCHA config	proxy.captcha.*	Provider initialized once
Content scanning	proxy.content_scanning.*	Scanner initialized once
Certificate paths	proxy.certificates	Loaded at startup
ACME settings	proxy.acme.*	ACME manager created at startup
Internal services	proxy.internal_services.*	Server bound at startup
BPF stats intervals	logging.bpf_stats.*	Task timers set at spawn time
TCP fingerprint intervals	logging.tcp_fingerprint.*	Task timers set at spawn time
File logging config	logging.file_logging_enabled, logging.log_directory	Log appenders built at startup
Syslog config	logging.syslog.*	Syslog appender built at startup
IP version	network.ip_version	BPF filter compiled at startup
PROXY protocol	proxy.protocol.*	Listener configured at startup

Internal Services Endpoints

When proxy.internal_services.enabled is true, the following endpoints are available:

Endpoint	Method	Purpose
/health	GET	Health check
/cgi-bin/captcha/verify	POST	CAPTCHA verification
/.well-known/acme-challenge/*	GET	ACME HTTP-01 challenges
/cert/expiration	GET	Check all certificate expiration status
/cert/expiration/:domain	GET	Check specific certificate status
/cert/renew/:domain	POST	Manually trigger certificate renewal

Next Steps

• Daemon Mode - Run as a background service
• JA4+ Fingerprinting - Complete fingerprinting suite
• Testing Guide - Validate your configuration