SYD-TOR(1) General Commands Manual SYD-TOR(1)

syd-tor - SOCKS Proxy Forwarder

syd-tor [-dh] [-b <bufsiz>] -p <pid-fd> -i <socket-fd> [-o addr:port]

Receives listening socket from fd and forwards traffic to addr:port.

External address must be an IPv4 or IPv6 address, defaults to TOR.

PID file descriptor is used to track the exit of Syd process.

-h Display help.
-d Run in debug mode without confinement.
-b bufsiz Set the pipe buffer size. Defaults to the value in /proc/sys/fs/pipe-max-size.
-p pid-fd PID file descriptor of Syd process.
-i socket-fd Socket file descriptor to receive the listening socket from.
-o addr:port Specify external address to forward traffic to. Defaults to 127.0.0.1:9050.

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 the PROXY SANDBOXING section in syd(7) manual page for more information. If you want to use syd-tor(1) in your own project, what you need to do first is to pass it a non-blocking PID fd of your own process with the "-p <pid-fd>" argument so syd-tor(1) can simultaneously exit with it. Care should be given at this stage as PID file descriptors are "O_CLOEXEC" by default. Next, create a UNIX socket-pair, enter a network namespace, bring up the loopback device, bind(2) a socket to a port on it and then send this socket file descriptor through the write end of the socket-pair with sendmsg(2) "SCM_RIGHTS" option. Finally pass the read end of the socket-pair to syd-tor(1) with the "-i <socket-fd>" argument.

syd-tor(1) is designed with performance, security, and privacy in mind, utilizing advanced techniques such as edge-triggered epoll(7) for efficient event notification and full asynchronous operations to handle multiple connections without blocking. It employs zero-copy data transfer using the splice(7) system call to move data directly between file descriptors within the kernel, ensuring high performance and data privacy. To facilitate bidirectional communication, syd-tor(1) uses two pairs of pipes, allowing seamless data flow between the client and the external address. Additionally, syd-tor(1) confines its execution environment using seccomp and Landlock, restricting system calls and file accesses to minimize the attack surface. Compared to socksns, which uses the Tokio runtime for asynchronous I/O, syd-tor(1) emphasizes kernel-level efficiency and security, making it a robust solution for SOCKS proxy forwarding.

syd-tor(1) implements comprehensive security measures to mitigate risks associated with running outside the Syd sandbox, thus preventing potential Man-in-the-Middle (MITM) attacks against containers. Seccomp filters are meticulously configured to allow only necessary syscalls, with connect(2) restricted to a single memory address to prevent unauthorized network connections. This restriction is particularly strict on 64-bit architectures, but has limitations on 32-bit where the socketcall interface can be exploited; hence, additional protective measures are in place. Moreover, executable memory is disallowed to prevent code injection attacks and reading the timestamp counter is prevented on x86 to make timing attacks harder to realize. Landlock and namespaces, if available, enforce further restrictions by disallowing all filesystem access, providing an additional layer of security. These combined techniques ensure that even if syd-tor(1) is compromised, the scope of malicious actions is significantly limited, maintaining the integrity and security of the overall system.

SYD_TOR_DEBUG Run in debug mode without confinement, equivalent to the "-d" option
SYD_TOR_RULES Print seccomp rules in human-readable format to standard error at startup

The syd-tor(1) process runs as a single process and can potentially hit file descriptor (FD) limits due to the number of FDs it opens per connection. Each client connection involves six FDs: one for the client socket, one for the external socket, and four for the pipes used for bidirectional data transfer (two pipes with an input and output FD each). To mitigate this, syd-tor(1) sets the 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.exherbolinux.org/

Maintained by Ali Polatel. Up-to-date sources can be found at https://gitlab.exherbo.org/sydbox/sydbox.git and bugs/patches can be submitted to https://gitlab.exherbo.org/groups/sydbox/-/issues. Discuss in #sydbox on Libera Chat.

2025-02-14