Configuration

CloakProbe uses a TOML configuration file for clean, organized settings. Environment variables can override config values for container deployments.

Configuration File

Location

Config files are searched in this order:

1. Path specified with -c / --config argument
2. ./cloakprobe.toml (current directory)
3. /etc/cloakprobe/cloakprobe.toml (system-wide)

Example Configuration

/etc/cloakprobe/cloakprobe.toml

[server]
bind_address = "127.0.0.1"
port = 8080
mode = "cloudflare"
region = "eu-central"

[privacy]
mode = "strict"

[database]
asn_db_path = "/opt/cloakprobe/data/asn_db.bin"
org_db_path = "/opt/cloakprobe/data/orgs_db.bin"

Configuration Options

Server Section

Option	Default	Description
bind_address	0.0.0.0	IP address to bind the HTTP server
port	8080	Port number to listen on
mode	cloudflare	Proxy mode: cloudflare or nginx
region	(none)	Optional region identifier shown in API

Proxy Modes

CloakProbe supports two proxy modes for client IP extraction:

Cloudflare Mode

[server]
mode = "cloudflare"

• Trusts CF-Connecting-IP header from Cloudflare
• Use when running behind Cloudflare CDN
• Important: Only accept connections from Cloudflare IPs to prevent IP spoofing

Nginx Mode

[server]
mode = "nginx"

• Trusts X-Real-IP or X-Forwarded-For headers
• Use when running behind nginx or other standard reverse proxies
• Important: Configure nginx to always set X-Real-IP = $remote_addr

Security

Always configure your reverse proxy to prevent header spoofing. See the nginx deployment guide for secure configurations.

Privacy Section

Option	Default	Description
mode	strict	Privacy mode: strict or balanced

Strict Mode (Default)

[privacy]
mode = "strict"

• No logging of IP addresses
• Minimal server information exposed
• logs_retained: false in API response

Balanced Mode

[privacy]
mode = "balanced"

• Standard logging enabled
• Full server information
• logs_retained: true in API response

Database Section

Option	Default	Description
asn_db_path	data/asn_db.bin	Path to ASN database
org_db_path	data/orgs_db.bin	Path to multi-RIR organization database (optional)

Command Line Options

cloakprobe [OPTIONS]

OPTIONS:
    -c, --config <PATH>    Path to configuration file (TOML)
    -h, --help             Print help information
    -v, --version          Print version information

Environment Variables (Override)

Environment variables override TOML config values. Useful for container deployments:

Variable	Description
CLOAKPROBE_BIND_ADDRESS	Override bind address
CLOAKPROBE_PORT	Override port
CLOAKPROBE_MODE	Override proxy mode (cloudflare or nginx)
CLOAKPROBE_REGION	Override region identifier
CLOAKPROBE_PRIVACY_MODE	Override privacy mode
CLOAKPROBE_ASN_DB_PATH	Override ASN database path
CLOAKPROBE_ORG_DB_PATH	Override organization database path

Systemd Configuration

The default systemd service uses the configuration file:

[Service]
ExecStart=/opt/cloakprobe/cloakprobe -c /etc/cloakprobe/cloakprobe.toml

To edit the configuration:

sudo nano /etc/cloakprobe/cloakprobe.toml
sudo systemctl restart cloakprobe

Multi-Instance Setup

For running multiple instances (e.g., different proxy modes), use the template service:

# Create instance-specific configs
sudo cp /etc/cloakprobe/cloakprobe.toml /etc/cloakprobe/cloudflare.toml
sudo cp /etc/cloakprobe/cloakprobe.toml /etc/cloakprobe/nginx.toml

# Edit configs (different ports, modes)
sudo nano /etc/cloakprobe/cloudflare.toml  # port=8080, mode=cloudflare
sudo nano /etc/cloakprobe/nginx.toml       # port=8081, mode=nginx

# Start instances
sudo systemctl start cloakprobe@cloudflare
sudo systemctl start cloakprobe@nginx

Running Manually

For testing or development:

With Config File

./cloakprobe -c cloakprobe.toml

With Env Override

CLOAKPROBE_PORT=3000 \
CLOAKPROBE_MODE=nginx \
./cloakprobe -c cloakprobe.toml

Docker

docker run -d \
  -p 8080:8080 \
  -v ./cloakprobe.toml:/etc/cloakprobe/cloakprobe.toml:ro \
  -v ./data:/opt/cloakprobe/data:ro \
  cloakprobe:latest -c /etc/cloakprobe/cloakprobe.toml

Memory Usage

CloakProbe loads databases into memory for fast lookups:

Database	Approximate Size
ASN database	~50-100 MB
Multi-RIR org database	~30-60 MB

Ensure your server has sufficient RAM for the databases plus application overhead.