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

syd-pty - PTY to STDIO bidirectional forwarder

syd-pty [-dh] [-x <x-size>] [-y <y-size>] -p <pid-fd> -i <pty-fd>

Forwards data between the given pty(7) main file descriptor, and stdio(3).

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

-h Display help.
-d Run in debug mode without confinement.
-p pid-fd PID file descriptor of Syd process.
-i pty-fd PTY main file descriptor.
-x x-size Specify window row size (default: inherit).
-y y-size Specify window column size (default: inherit).

syd-pty(1) is not meant to be used as a standalone tool. Syd invokes syd-pty(1) at startup when PTY sandboxing is set to on with "sandbox/pty:on". See the PTY SANDBOXING section in syd(7) manual page for more information. If you want to use syd-pty(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-pty(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 new pseudoterminal with posix_openpt(3) or openpty(3) and pass the main end of the file descriptor pair to syd-pty(1) with the "-i <pty-fd>" argument.

syd-pty(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 pseudoterminal activities without blocking. It employs zero-copy data transfer using the splice(2) system call to move data directly between file descriptors within the kernel, ensuring high performance and data privacy. To facilitate bidirectional communication, syd-pty(1) uses two pairs of pipes, allowing seamless data flow between pty(7) and stdio(3). Additionally, syd-pty(1) confines its execution environment using seccomp and Landlock, restricting system calls and file accesses to minimize the attack surface.

syd-pty(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. 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 and network access, providing an additional layer of security. These combined techniques ensure that even if syd-pty(1) is compromised, the scope of malicious actions is significantly limited, maintaining the integrity and security of the overall system.

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

syd(1), syd(2), syd(7), stdio(3), pty(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 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.

2025-06-27