SYD-TOR(1)

📦
version 3.59.0 · 3 versions
, in arch rolling

💅 SYD-TOR(1) — SOCKS Proxy Forwarder ✨

okay bestie, welcome to the General Commands Manual page for syd-tor, and no cap this one is kind of a whole vibe. It's a SOCKS proxy forwarder, it's locked down like a vault, and it is not gonna hold your hand. Let's get into it 🫶

🌸 NAME 🌸

syd-tor — SOCKS Proxy Forwarder. That's the whole name, that's the whole job. slay.

✨ SYNOPSIS ✨

syd-tor [-dh] -i <socket-fd> [-o addr:port] [-u unix-sock]

That's it, that's the whole entry point. Iconic, honestly 💅

🦋 DESCRIPTION 🦋

So here's the tea: syd-tor receives a listening socket from a file descriptor (that's the fd) and then forwards all the traffic to either addr:port or a UNIX socket.

The external address has to be either an IPv4 address, or an IPv6 address, or a path to a UNIX domain socket. If you don't say anything at all, it lowkey defaults to 127.0.0.1:9050. defaults are a love language fr fr 💖

🎀 OPTIONS 🎀

  • -h — display help. that's it. that's the whole flag. ask and ye shall receive ✨
  • -d — run in debug mode without confinement. ⚠️ this is permitted only if Syd is built with the trusted Cargo feature — otherwise, no dice, bestie.
  • -i socket-fd — the socket file descriptor to receive the listening socket from. this one's the whole point of the program ngl.
  • -o ext-addr — specify the external address to forward traffic to. the address can be an IPv4/IPv6 address in the format addr:port. defaults to 127.0.0.1:9050.
  • -u unix-sock — specify a UNIX domain socket to forward traffic to. 👑 this option has precedence over -o — when both show up to the party, -u is the main character.

🌈 USAGE 🌈

bestie listen, syd-tor(1) is not meant to be used as a standalone tool. like, at all. Syd itself invokes syd-tor(1) at startup when Proxy sandboxing is set to on with "sandbox/proxy:on". for the full lore, go read the PROXY SANDBOXING section in the syd(7) manual page. iykyk 📖

But say you do want to use syd-tor(1) in your own project — okay, entrepreneur, i see you. here's the ritual, in order:

  1. create a UNIX socket-pair
  2. enter a network namespace
  3. bring up the loopback device
  4. bind(2) a socket to a port on it
  5. send this socket file descriptor through the write end of the socket-pair with sendmsg(2) and the SCM_RIGHTS option
  6. finally, pass the read end of the socket-pair to syd-tor(1) with the -i <socket-fd> argument

six steps, no shortcuts, that's the whole choreography 💃

💜 IMPLEMENTATION 💜

syd-tor(1) is designed for performance, security, and privacy — the holy trinity, honestly. the details:

  • it uses edge-triggered epoll(7) for event notification and fully asynchronous operations, so it can handle multiple connections without blocking. no waiting in line, we're built different.
  • it transfers data with zero-copy splice(2), moving bytes directly between file descriptors within the kernel without ever exposing plaintext in user space. the data doesn't even stop to say hi 😭
  • two pairs of pipes carry bidirectional traffic between the client and the external address.
  • the execution environment is confined with seccomp(2) and landlock(7), restricting system calls and file access to the bare minimum required. minimalist queen.
  • compared to socksns, which uses the Tokio runtime for asynchronous I/O, syd-tor(1) relies on kernel-level primitives for efficiency and confinement. different breed fr fr 🔥

🛡️ SECURITY 🛡️

okay this section is long but it's so good. syd-tor(1) applies multiple confinement layers to mitigate risks associated with running outside the Syd sandbox, preventing potential Meddler-in-the-Middle (MITM) attacks against containers. yes, Meddler-in-the-Middle — that's the spelling in the original, we don't editorialize, we respect the source 💅

  • Linux capabilities(7) are dropped early, and the 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 all set to zero, to prevent core dumps and file/process/lock/msgqueue creation inside the main loop. zero, nada, none 🚫
  • seccomp(2) filters are configured to allow only required syscalls.
  • socket(2) is limited to a single domain, type, and protocol, while connect(2) is restricted to a single memory address — preventing unauthorized network connections. one address only, we don't wander.
  • sigaction(2) and rt_sigaction(2) system calls are not permitted to install new signal handlers, and rt_sigreturn(2) isn't permitted either.
  • 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. for the full cookie lore, refer to the Syscall Argument Cookies section of the syd(7) manual page. 🍪
  • 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, the memory area containing the external network address is sealed using mseal(2) and the 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, providing an extra layer of security.
  • the root directory is moved into /proc/self/fdinfo, or /proc/self/fd if the external address is a UNIX socket, with pivot_root(2), and the old root is detached with MNT_DETACH, so no path to the host filesystem remains in the mount namespace.

together, these techniques ensure that even if syd-tor(1) is compromised, the scope of malicious actions is significantly limited, maintaining the overall integrity and security of the system. that's the whole point and she ate 👑

🌱 ENVIRONMENT 🌱

  • SYD_TOR_DEBUG — run in debug mode without confinement, equivalent to the -d option. ⚠️ this is ignored unless Syd is built with the trusted Cargo feature.

💀 CAVEATS 💀

real talk: the syd-tor(1) process runs as a single process, and it can potentially hit file descriptor (FD) limits due to the number of FDs it opens per connection. here's the math, bestie:

each client connection involves six FDs:

  • one for the client socket
  • one for the external socket
  • four for 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. but sometimes that's still not enough, and you'll have to manually adjust your FD limits. it's giving "we tried our best" 😭

🍓 SEE ALSO 🍓

syd homepage: https://sydbox.exherbo.org/ 🌐

🌟 AUTHORS 🌟

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. come say hi, we don't bite 🫶💬

and that's the page!! this edition is dated 2026-09-01 and it's the SYD-TOR(1) page, straight from the General Commands Manual. go forth and forward those SOCKS, bestie — safely, sandboxed, and absolutely slaying. 💖✨🎀🦋

📦 where this page comes from