Frequently Asked Questions (FAQ)

FAQ

General

What is this tool for?

It's a session-managed wrapper around socat that adds lifecycle management (start, stop, status), process group isolation, watchdog auto-restart, traffic capture, and multi-protocol/dual-stack support. It turns individual socat commands into a managed operations platform.

Why not just use socat directly?

You can. This tool adds value when you need to:

• Manage multiple socat sessions simultaneously
• Stop sessions cleanly without hunting PIDs
• Capture traffic with automatic log file management
• Auto-restart crashed sessions
• Run dual-stack (TCP + UDP) on the same port
• Track session metadata (who started what, when, on which port)

How do I launch the interactive menu?

Run with no arguments:

socat-manager
# or explicitly:
socat-manager menu

The menu provides guided input for all modes. Type q at any prompt to cancel and return to the main menu. All CLI commands still work for scripted use.

Does this require root?

Only for binding to privileged ports (below 1024). All other operations work as a regular user.

What Linux distributions are supported?

CI-verified on Ubuntu 22.04/24.04, Debian 12, Kali Rolling, Rocky Linux 9, AlmaLinux 9, and Arch Linux. Expected to work on any distribution with Python 4.4+ and standard coreutils.

Does this work on macOS?

Not currently. The Python variant relies on Linux-specific features: os.setsid() for process group isolation (POSIX, but behavior varies), ss from iproute2 for port availability checks, and /proc/{pid}/comm for process identity verification in kill_by_port(). A macOS port would require replacing ss with lsof (partial fallback already exists) and /proc reads with ps-based equivalents.

Does this work on Windows (WSL)?

It should work under WSL2 with Ubuntu or Debian, since WSL2 provides a full Linux kernel. Not tested in CI.

---

Installation

What's the difference between make install and running directly?

make install copies the script to /opt/tools/socat-manager and creates a socat-manager wrapper in /usr/local/bin. Running directly means you cd to the project directory and run ./socat-manager. Both work identically -- make install is more convenient for system-wide use.

How do I uninstall?

sudo make uninstall

This removes the wrapper and prompts before deleting the installation directory.

What's a virtual environment (venv) for this?

A self-contained copy with its own sessions, logs, and certs directories. Useful for isolating per-engagement data. Create one with make venv VENV_DIR=./my-env.

---

Usage

How do I see what's running?

socat-manager status
socat-manager status --detail    # Extended info

How do I stop a specific session?

socat-manager stop --name listen-tcp4-8080-a1b2c3d4
# Or by port (stops all sessions on that port):
socat-manager stop --port 8080

Can I run TCP and UDP on the same port?

Yes. Use --dual-stack:

socat-manager listen --port 8080 --dual-stack

This creates two independent sessions. Stopping one doesn't affect the other.

Where are the capture logs?

In the logs/ directory relative to the script location:

ls logs/capture-*

Can I use custom TLS certificates?

Yes. Pass --cert and --key to tunnel mode:

socat-manager tunnel --port 4443 --rhost 10.0.0.5 --rport 22 \
    --cert certs/my-cert.pem --key certs/my-key.pem

Without these flags, tunnel mode auto-generates self-signed certificates.

What happens if socat crashes?

Without --watchdog: the session dies, the session file becomes stale. Use socat-manager status --cleanup to clean up.

With --watchdog: the watchdog detects the crash and restarts socat automatically with exponential backoff (1s, 2s, 4s, 8s, ... up to 60s, max 10 restarts).

Can I forward UDP traffic?

Yes. Use --proto udp4:

socat-manager forward --lport 5353 --rhost 10.0.0.1 --rport 53 --proto udp4

Can I create a TLS tunnel for UDP?

No. TLS requires TCP. For UDP forwarding, use forward mode. Tunnel mode rejects UDP with a clear error and guidance.

---

Troubleshooting

Sessions show in status but the port isn't actually listening

The socat process died but the session file wasn't cleaned up:

socat-manager status --cleanup

I get "Unknown option" for a flag that should work

Check your version: socat-manager --version. Some flags (--capture on listen, --proto on tunnel) were added in v2.3.0.

Stopping a TCP session killed my UDP session

Update to v2.2.0+. Protocol-scoped stop was introduced in v2.2.0.

See Troubleshooting Guide for more detailed solutions.

---

Development

How do I run the tests?

make test

See Development Guide for details.

Where do I report a security vulnerability?

Not in a public issue. Use GitHub Security Advisories (repository Security tab → Report a vulnerability). See Security Policy.

How do I add a new mode?

See the "Adding a New Mode" section in the Developer Guide.

Is this compatible with the bash version?

Yes. Session files use the same KEY=VALUE text format. Both variants can read each other's session files. The same CLI flags work in both versions. However, running both variants simultaneously against the same session directory is not recommended.

Do I need pip to run this?

No. The standalone runner (python3 socat-manager.py) works without any installation. pip is only needed if you want the socat-manager command on your PATH.

What's the difference from the bash version?

Functionally identical -- same 7 modes, same session format, same CLI flags. Key Python advantages:

• Direct PID access via Popen.pid (no PID-file handoff workaround)
• Native threading for watchdog (no background subshell)
• Structured logging via Python's logging module
• Type-hinted codebase with full pytest suite
• Monitor-first watchdog design (eliminates duplicate-launch bug class)
• Configurable --max-restarts and --backoff CLI flags on all modes

How do I add a new mode?

See the Developer-Guide page, section "Adding a New Mode". In brief: create a mode handler in modes/, add a command builder if needed, add a CLI subparser, add dispatch routing, add menu submenu, and write tests.

---

Socat Network Operations Manager · MIT License