Configuration Reference

Configuration Reference

Single-page reference for every CLI flag, configuration file, directory, and internal constant.

Global Options

These flags work on the main command, not tied to a specific mode:

Flag	Description
--version	Print version string and exit
-h, --help	Print main help text and exit
-v, --verbose	Enable debug output

Per-Mode Flags

Listen

Flag	Required	Default	Description
-p, --port	✅	—	Port to listen on
--proto		tcp4	Protocol (tcp4, tcp6, udp4, udp6)
--dual-stack		off	Also listen on alternate protocol
--bind		0.0.0.0	Bind address
--name		auto	Custom session name
--logfile		auto	Custom data log path
--capture		off	Traffic capture (socat -v)
--watchdog		off	Auto-restart on crash
--socat-opts		—	Additional socat options

Batch

Flag	Required	Default	Description
--ports	One of three	—	Comma-separated port list
--range	One of three	—	Port range (e.g., 9000-9010)
--file	One of three	—	Config file path
--proto		tcp4	Protocol for all listeners
--dual-stack		off	Dual-stack on each port
--capture		off	Capture on all listeners
--watchdog		off	Watchdog on all listeners

Forward

Flag	Required	Default	Description
--lport	✅	—	Local port
--rhost	✅	—	Remote host
--rport	✅	—	Remote port
--proto		tcp4	Local listener protocol
--dual-stack		off	Forward on both TCP and UDP
--capture		off	Traffic capture
--watchdog		off	Auto-restart

Tunnel

Flag	Required	Default	Description
--port	✅	—	Local TLS port
--rhost	✅	—	Remote host
--rport	✅	—	Remote port
--cert		auto-generated	TLS certificate path
--key		auto-generated	TLS private key path
--proto		tcp4	Only tcp/tcp4 accepted; udp rejected
--capture		off	Traffic capture
--watchdog		off	Auto-restart

Redirect

Flag	Required	Default	Description
--lport	✅	—	Local port
--rhost	✅	—	Remote host
--rport	✅	—	Remote port
--proto		tcp4	Protocol
--dual-stack		off	Redirect on both protocols
--name		auto	Custom session name
--capture		off	Traffic capture
--watchdog		off	Auto-restart

Status

Flag	Required	Default	Description
--detail		off	Extended session info
--cleanup		off	Remove dead session files

Stop

Flag	Required	Default	Description
--all	One of four	—	Stop all sessions
--name	One of four	—	Stop by session name
--port	One of four	—	Stop by port number
--pid	One of four	—	Stop by process ID

Configuration File: ports.conf

Used by batch mode with --file. Plain text, one port per line.

# Comments start with #
8080
8081
8082
# 9999   ← skipped (commented out)
443

# Blank lines are ignored

• Lines starting with # are ignored
• Empty lines are ignored
• Whitespace is stripped
• Each non-comment line must be a valid port number (1-65535)

Directory Structure

Directory	Permissions	Contents
sessions/	700	.session metadata files (600 each)
logs/	755	Master logs, session logs, error logs, capture logs
certs/	755	Auto-generated TLS certificates (.pem) and keys (.key, 600)
conf/	755	Configuration files (ports.conf)

All directories are created automatically on first run, relative to SCRIPT_DIR (the directory containing socat_manager.sh).

Internal Constants

These are defined as readonly or local defaults at the top of the script. They are not user-configurable via CLI flags:

Constant	Value	Scope	Purpose
SCRIPT_VERSION	2.3.0	readonly	Version string reported by --version
STOP_GRACE_SECONDS	5	readonly	Seconds to wait between SIGTERM and SIGKILL
STOP_VERIFY_RETRIES	5	readonly	Default retries for port-freed verification (_stop_session passes 3)
STOP_VERIFY_INTERVAL	0.5	readonly	Seconds between port-freed retries
PID_FILE_WAIT_ITERS	20	readonly	Max iterations waiting for PID file (× 0.1s = 2s timeout)
DEFAULT_WATCHDOG_INTERVAL	5	variable	Seconds between watchdog health checks
DEFAULT_WATCHDOG_MAX_RESTARTS	10	variable	Max auto-restarts before watchdog gives up
Watchdog backoff	1 (initial)	local	Exponential: 1, 2, 4, 8, 16, 32, 60s (capped)
Session ID max attempts	10	local	Max collision retries for session ID generation
MAX_SESSIONS	256	readonly	Maximum concurrent sessions (prevents resource exhaustion)
SESSION_LOCK	sessions/.lock	readonly	Advisory lock file path for concurrent access protection

Session File Format

Each session produces a .session file in sessions/:

SESSION_ID=a1b2c3d4
SESSION_NAME=listen-tcp4-8080-a1b2c3d4
PID=12345
PGID=12345
MODE=listen
PROTOCOL=tcp4
LOCAL_PORT=8080
REMOTE_HOST=
REMOTE_PORT=
SOCAT_CMD=socat TCP4-LISTEN:8080,reuseaddr,fork OPEN:/dev/null,creat,append
STARTED=2026-03-20T14:30:00
CORRELATION=550e8400-e29b-41d4-a716-446655440000
LAUNCHER_PID=99998

All fields are key=value pairs. The file is read by session_read_field() using grep '^KEY=' | cut -d= -f2-.