Skip to content

Usage Guide

Jump to bottom
Ryan edited this page Mar 28, 2026 · 2 revisions

Usage Guide

Complete reference for all operational modes, flags, installation methods, and features.

Table of Contents

Interactive Menu

Running the script with no arguments launches a full-featured interactive menu:

socat-manager
# or explicitly:
socat-manager menu

The menu provides guided input collection for all operational modes with:

  • Validated input at every prompt — ports, hostnames, protocols, session names, and socat options are validated before acceptance
  • Cancel support — type q, quit, cancel, or back at any prompt to abort and return to the main menu
  • Confirmation before execution — every mode shows the constructed CLI command and asks for confirmation before running
  • Dependency check — option 8 verifies all required and recommended system dependencies

All CLI functionality remains fully available for scripted/automated use.

Installation Methods

Makefile Install (Recommended)

sudo make install

Installs to /opt/tools/socat-manager with a wrapper at /usr/local/bin/socat-manager. Custom paths:

make install PREFIX=~/.local/socat-manager BINDIR=~/.local/bin

Uninstall:

sudo make uninstall

Virtual Environment

Creates an isolated copy with its own sessions, logs, and certs directories:

make venv VENV_DIR=./my-project-env
source ./my-project-env/activate.sh
socat-manager listen --port 8080
deactivate_socat   # When done

Direct Execution

No installation required — run directly from the project directory:

chmod +x socat_manager.sh
./socat_manager.sh listen --port 8080

Listen Mode

Start a single TCP or UDP listener that captures incoming data to a log file.

Synopsis

socat-manager listen --port <PORT> [OPTIONS]

Options

Flag Description Default
-p, --port <PORT> Port number to listen on (required) —
--proto <PROTOCOL> Protocol: tcp, tcp4, tcp6, udp, udp4, udp6 tcp4
--dual-stack Also start listener on alternate protocol off
--bind <ADDRESS> Bind to specific IP address 0.0.0.0
--name <NAME> Custom session name auto-generated
--logfile <PATH> Custom log file for captured data auto-generated
--capture Enable traffic capture (verbose hex dump) off
--watchdog Enable auto-restart on crash off
--socat-opts <OPTS> Additional socat address options —

Examples

# Basic TCP listener
socat-manager listen --port 8080

# UDP listener on a specific interface
socat-manager listen --port 5353 --proto udp4 --bind 192.168.1.10

# Dual-stack with traffic capture and watchdog
socat-manager listen --port 8080 --dual-stack --capture --watchdog

Batch Mode

Launch listeners on multiple ports simultaneously from a list, range, or configuration file.

Synopsis

socat-manager batch --ports <LIST> | --range <START-END> | --file <PATH> [OPTIONS]

Options

Flag Description Default
--ports <LIST> Comma-separated port list (e.g., 8080,8081,8082) —
--range <START-END> Port range (e.g., 9000-9010, max 1000 ports) —
--file <PATH> Config file with one port per line —
--proto <PROTOCOL> Protocol for all listeners tcp4
--dual-stack Launch both TCP and UDP on each port off
--capture Enable traffic capture on all listeners off
--watchdog Enable auto-restart on all listeners off

Configuration File Format

# conf/ports.conf — one port per line, comments allowed
8080
8081
8082
# 9999  ← commented out, skipped
443

Examples

# Launch listeners on three ports
socat-manager batch --ports 8080,8081,8082

# Launch a range of UDP listeners
socat-manager batch --range 9000-9010 --proto udp4

# Launch from config file with capture
socat-manager batch --file conf/ports.conf --capture

Forward Mode

Relay traffic from a local port to a remote host and port. Supports TCP and UDP independently.

Synopsis

socat-manager forward --lport <PORT> --rhost <HOST> --rport <PORT> [OPTIONS]

Options

Flag Description Default
--lport <PORT> Local port to listen on (required) —
--rhost <HOST> Remote host to forward to (required) —
--rport <PORT> Remote port to forward to (required) —
--proto <PROTOCOL> Protocol for local listener tcp4
--dual-stack Forward on both TCP and UDP off
--capture Enable traffic capture off
--watchdog Enable auto-restart on crash off

Examples

# Forward local 8080 to a backend web server
socat-manager forward --lport 8080 --rhost 10.0.0.5 --rport 80

# DNS relay (UDP)
socat-manager forward --lport 5353 --rhost 10.0.0.1 --rport 53 --proto udp4

# Forward with traffic capture for inspection
socat-manager forward --lport 443 --rhost backend.local --rport 8443 --capture

Tunnel Mode

Create a TLS-encrypted tunnel to a remote host. Automatically generates self-signed certificates if none are provided. TCP only (TLS requires TCP).

Synopsis

socat-manager tunnel --port <PORT> --rhost <HOST> --rport <PORT> [OPTIONS]

Options

Flag Description Default
--port <PORT> Local port for the TLS endpoint (required) —
--rhost <HOST> Remote host to tunnel to (required) —
--rport <PORT> Remote port to tunnel to (required) —
--cert <PATH> TLS certificate file (PEM) auto-generated
--key <PATH> TLS private key file (PEM) auto-generated
--proto <PROTOCOL> Only tcp/tcp4 supported; tcp6 warns; udp rejected with guidance tcp4
--capture Enable traffic capture off
--watchdog Enable auto-restart on crash off

Protocol Notes

Tunnel mode is TLS-only, which requires TCP. The --proto flag accepts:

  • tcp / tcp4 — accepted silently (default)
  • tcp6 — accepted with a warning that IPv6 TLS support is limited
  • udp / udp4 / udp6 — rejected with guidance to use forward --proto udp4 instead

Examples

# TLS tunnel to an SSH server (auto-generated certs)
socat-manager tunnel --port 4443 --rhost 10.0.0.5 --rport 22

# TLS tunnel with custom certs and capture
socat-manager tunnel --port 8443 --rhost db.internal --rport 3306 \
    --cert certs/server.pem --key certs/server.key --capture

Redirect Mode

Transparent port redirection. Relays connections from a local port to a remote host without TLS. Supports TCP and UDP independently.

Synopsis

socat-manager redirect --lport <PORT> --rhost <HOST> --rport <PORT> [OPTIONS]

Options

Flag Description Default
--lport <PORT> Local port to listen on (required) —
--rhost <HOST> Remote host to redirect to (required) —
--rport <PORT> Remote port to redirect to (required) —
--proto <PROTOCOL> Protocol: tcp4, udp4, etc. tcp4
--dual-stack Redirect on both TCP and UDP off
--name <NAME> Custom session name auto-generated
--capture Enable traffic capture off
--watchdog Enable auto-restart on crash off

Examples

# Redirect HTTP to a backend
socat-manager redirect --lport 80 --rhost 192.168.1.10 --rport 8080

# DNS redirect (UDP)
socat-manager redirect --lport 53 --rhost 10.0.0.1 --rport 5353 --proto udp4

# Dual-stack HTTPS redirect with capture
socat-manager redirect --lport 443 --rhost backend --rport 8443 --dual-stack --capture

Status Mode

View active sessions, session details, and perform cleanup of dead sessions.

Synopsis

socat-manager status [OPTIONS]

Options

Flag Description
--detail Show extended session information (PID, PGID, command, timestamps)
--cleanup Remove session files for sessions whose processes have died

Examples

# Show all active sessions
socat-manager status

# Show extended details for all sessions
socat-manager status --detail

# Clean up stale session files
socat-manager status --cleanup

Stop Mode

Terminate sessions by name, port, PID, or all at once.

Synopsis

socat-manager stop --all | --name <NAME> | --port <PORT> | --pid <PID>

Options

Flag Description
--all Stop all active sessions
--name <NAME> Stop session(s) matching this name
--port <PORT> Stop session(s) on this port
--pid <PID> Stop the session with this PID

Stop Sequence

The stop command follows a 9-step sequence for reliable process termination:

  1. Read protocol from session file
  2. Touch .stop signal file (tells watchdog not to restart)
  3. kill -TERM -${PGID} (entire process group)
  4. kill -TERM ${PID} + pkill -TERM -P ${PID} (direct + children)
  5. Wait up to 5 seconds (STOP_GRACE_SECONDS) in 0.5s intervals
  6. kill -KILL -${PGID} + kill -KILL ${PID} if still alive
  7. _kill_by_port — protocol-scoped fallback by port number
  8. check_port_freed — protocol-scoped port release verification
  9. Remove session file and signal files

Examples

# Stop everything
socat-manager stop --all

# Stop a specific session by name
socat-manager stop --name listen-tcp4-8080

# Stop all sessions on port 8080 (both TCP and UDP)
socat-manager stop --port 8080

# Stop a specific process
socat-manager stop --pid 12345

Protocol Configuration

Supported Protocols

Value Description
tcp / tcp4 TCP over IPv4 (default)
tcp6 TCP over IPv6
udp / udp4 UDP over IPv4
udp6 UDP over IPv6

Shorthand values (tcp, udp) are automatically normalized to their IPv4 equivalents (tcp4, udp4).

Setting Protocol

Use --proto on any mode:

socat-manager listen --port 5353 --proto udp4
socat-manager forward --lport 8080 --rhost 10.0.0.5 --rport 80 --proto tcp6

Dual-Stack Operations

The --dual-stack flag launches both TCP and UDP sessions on the same port simultaneously. Each protocol gets its own independent session with its own session ID, session file, and lifecycle.

socat-manager listen --port 8080 --dual-stack
# Creates two sessions:
#   listen-tcp4-8080-a1b2c3d4
#   listen-udp4-8080-e5f6g7h8

Stopping one protocol does not affect the other:

socat-manager stop --name listen-tcp4-8080-a1b2c3d4
# UDP session on 8080 continues running

Traffic Capture

The --capture flag enables socat's verbose mode (-v), which dumps bidirectional traffic in hex format to a capture log file.

socat-manager listen --port 8080 --capture
# Capture log: logs/capture-tcp4-8080-<timestamp>.log

With --dual-stack, each protocol gets its own capture file:

socat-manager redirect --lport 443 --rhost backend --rport 8443 --dual-stack --capture
# TCP capture: logs/capture-tcp4-443-backend-8443-<timestamp>.log
# UDP capture: logs/capture-udp4-443-backend-8443-<timestamp>.log

Watchdog Auto-Restart

The --watchdog flag enables automatic restart when a session's socat process dies unexpectedly. The watchdog uses exponential backoff to prevent restart loops.

socat-manager listen --port 8080 --watchdog

The watchdog checks:

  • Is the PID still alive?
  • Is there a .stop signal file? (If yes, don't restart — this was a deliberate stop)
  • Has the backoff interval elapsed?

Session Lifecycle

Session Creation

When a mode launches, it:

  1. Generates an 8-character hex session ID
  2. Writes a .session metadata file to sessions/
  3. Launches socat under setsid for process group isolation
  4. Uses PID-file handoff to capture the real socat PID

Session Metadata

Each .session file contains:

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=uuid-string
LAUNCHER_PID=99999

Session Termination

See the Stop Mode section for the 9-step stop sequence.

Log Management

Log Types

Log Location Content
Master log logs/socat_manager-<timestamp>.log All operations across all sessions
Session log logs/session-<SID>-<timestamp>.log Audit trail for one session
Error log logs/session-<SID>-error.log stderr capture for one session
Capture log logs/capture-<proto>-<port>-<timestamp>.log Traffic hex dump (when --capture enabled)

Log Format

[2026-03-20T14:30:00Z] [INFO] [session:a1b2c3d4] Listener started on port 8080/tcp4

All logs are created automatically in the logs/ directory relative to the script location (or install directory).

Socat Network Operations Manager · Repository · Releases · Report Bug · Request Feature · MIT License

📖 Navigation

Home

Getting Started

Operations

Architecture

Development

Project

📦 Releases · 🐛 Issues · 📄 Source

Clone this wiki locally