| SYD-TOR(1) | General Commands Manual | SYD-TOR(1) |
syd-tor - SOCKS Proxy Forwarder
syd-tor [-dh] -i <socket-fd> [-o addr:port] [-u unix-sock]
Receives listening socket from fd and forwards traffic to addr:port or UNIX socket.
External address must either be an IPv4, or an IPv6 address or path to a UNIX domain socket, defaults to 127.0.0.1:9050.
| -h | Display help. |
| -d | Run in debug mode without confinement. |
| This is permitted only if Syd is built with the trusted Cargo feature. | |
| -i socket-fd | Socket file descriptor to receive listening socket from. |
| -o ext-addr | Specify external address to forward traffic to. |
| Address may be an IPv4/IPv6 address in format "addr:port". | |
| Defaults to "127.0.0.1:9050". | |
| -u unix-sock | Specify UNIX domain socket to forward traffic to. |
| This option has precedence over -o. |
syd-tor(1) is not meant to be used as a standalone tool. Syd invokes syd-tor(1) at startup when Proxy sandboxing is set to on with "sandbox/proxy:on". See PROXY SANDBOXING section in syd(7) manual page for more information. If you want to use syd-tor(1) in your own project, create a UNIX socket-pair, enter a network namespace, bring up loopback device, bind(2) a socket to a port on it and then send this socket file descriptor through write end of socket-pair with sendmsg(2) SCM_RIGHTS option. Finally pass read end of the socket-pair to syd-tor(1) with "-i <socket-fd>" argument.
syd-tor(1) is designed for performance, security, and privacy, using edge-triggered epoll(7) for event notification and fully asynchronous operations to handle multiple connections without blocking. It transfers data with zero-copy splice(2), moving bytes directly between file descriptors within kernel without exposing plaintext in user space. Two pairs of pipes carry bidirectional traffic between client and external address. Execution environment is confined with seccomp(2) and landlock(7), restricting system calls and file access to minimum required. Compared to socksns, which uses Tokio runtime for asynchronous I/O, syd-tor(1) relies on kernel-level primitives for efficiency and confinement.
syd-tor(1) applies multiple confinement layers to mitigate risks associated with running outside Syd sandbox, preventing potential Meddler-in-the-Middle (MITM) attacks against containers. Linux capabilities(7) are dropped early and no-new-privs attribute is set so no unwanted capability leaks into the process. Resource limits RLIMIT_CORE, RLIMIT_FSIZE, RLIMIT_NPROC, RLIMIT_LOCKS, RLIMIT_MEMLOCK, and RLIMIT_MSGQUEUE are set to zero to prevent core dumps and file/process/lock/msgqueue creation inside main loop. seccomp(2) filters are configured to allow only required syscalls. socket(2) syscall is limited to a single domain, type, and protocol, while connect(2) is restricted to a single memory address, preventing unauthorized network connections. sigaction(2), and rt_sigaction(2) system calls are not permitted to install new signal handlers, and rt_sigreturn(2) isn't permitted. pipe2(2), socket(2), connect(2), accept4(2), and shutdown(2) system calls are protected by syscall argument cookies determined randomly using getrandom(2) at startup. Refer to Syscall Argument Cookies section of syd(7) manual page for more information on argument cookies. These restrictions require direct socket system calls. They are permitted without restrictions on architectures x86, m68k, mips, mipsel, ppc, ppc64, ppc64le, s390, s390x, sheb, and sh, which multiplex sockets through socketcall(2). On 64-bit Linux 6.10 and later, memory area containing external network address is sealed using mseal(2) and surrounding memory is protected with guard pages to prevent overflow or adjacent corruption. Executable memory is also disallowed to prevent code injection attacks. If available, landlock(7) and namespaces(7) impose further restrictions by disallowing all filesystem access, thereby providing an extra layer of security. Root directory is moved into /proc/self/fdinfo, or /proc/self/fd if external address is a UNIX socket, with pivot_root(2) and old root is detached with MNT_DETACH, so no path to host filesystem remains in mount namespace. Together, these techniques ensure that even if syd-tor(1) is compromised, scope of malicious actions is significantly limited, maintaining overall integrity and security of the system.
| SYD_TOR_DEBUG | Run in debug mode without confinement, equivalent to "-d" option. |
| This is ignored unless Syd is built with trusted Cargo feature. |
syd-tor(1) process runs as a single process and can potentially hit file descriptor (FD) limits due to number of FDs it opens per connection. Each client connection involves six FDs: one for client socket, one for external socket, and four for pipes used for bidirectional data transfer (two pipes with an input and output FD each). To mitigate this, syd-tor(1) sets file-max limit to the hard limit by overriding the soft limit at startup. However, in some cases, this may not be sufficient, and manual adjustment of FD limits may be necessary.
syd(1), syd(2), syd(7)
syd homepage: https://sydbox.exherbo.org/
Maintained by Ali Polatel. Up-to-date sources can be found at https://gitlab.exherbo.org/sydbox/sydbox.git and on Radicle at rad:z38HCnbmcDegA2BMxuPaPRPMdp6wF. Bugs/patches can be submitted to https://gitlab.exherbo.org/groups/sydbox/-/issues. Discuss in #sydbox on Libera Chat or in #sydbox:mailstation.de on Matrix.
| 2026-08-19 |