-
-
Notifications
You must be signed in to change notification settings - Fork 0
FAQ
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.
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)
Run with no arguments:
socat-manager
# or explicitly:
socat-manager menuThe 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.
Only for binding to privileged ports (below 1024). All other operations work as a regular user.
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 bash 4.4+ and standard coreutils.
Not currently. The script relies on Linux-specific features: /proc/sys/kernel/random/uuid, setsid from util-linux, and ss from iproute2. A macOS port would require replacing these with macOS equivalents.
It should work under WSL2 with Ubuntu or Debian, since WSL2 provides a full Linux kernel. Not tested in CI.
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.sh. Both work identically — make install is more convenient for system-wide use.
sudo make uninstallThis removes the wrapper and prompts before deleting the installation directory.
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.
socat-manager status
socat-manager status --detail # Extended infosocat-manager stop --name listen-tcp4-8080-a1b2c3d4
# Or by port (stops all sessions on that port):
socat-manager stop --port 8080Yes. Use --dual-stack:
socat-manager listen --port 8080 --dual-stackThis creates two independent sessions. Stopping one doesn't affect the other.
In the logs/ directory relative to the script location:
ls logs/capture-*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.pemWithout these flags, tunnel mode auto-generates self-signed certificates.
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).
Yes. Use --proto udp4:
socat-manager forward --lport 5353 --rhost 10.0.0.1 --rport 53 --proto udp4No. TLS requires TCP. For UDP forwarding, use forward mode. Tunnel mode rejects UDP with a clear error and guidance.
The socat process died but the session file wasn't cleaned up:
socat-manager status --cleanupCheck your version: socat-manager --version. Some flags (--capture on listen, --proto on tunnel) were added in v2.3.0.
Update to v2.2.0+. Protocol-scoped stop was introduced in v2.2.0.
See Troubleshooting Guide for more detailed solutions.
make testSee Development Guide for details.
Not in a public issue. Use GitHub Security Advisories (repository Security tab → Report a vulnerability). See Security Policy.
See the "Adding a New Mode" section in the Developer Guide.
Socat Network Operations Manager · Repository · Releases · Report Bug · Request Feature · MIT License
Getting Started
Operations
Architecture
Development
Project