.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "SYD" "1" "2025-02-14"
.PP
.SH NAME
.PP
syd - rock solid application kernel
.PP
.SH SYNOPSIS
.PP
\fBsyd\fR [-acefhlmpqxEPV] [--] {command [arg.\&.\&.\&]}
.PP
\fBsyd\fR [-acefhlmpqxEPV] [--] {library.\&so}
.PP
\fBsyd\fR --el
.PP
\fBsyd\fR --sh
.PP
.SH DESCRIPTION
.PP
Syd is a utility leveraging the \fIseccomp\fR(2) system call for sandboxing
processes on Linux systems version 5.\&19 or later.\& It enables
fine-grained control over a process'\&s filesystem and network access
\fIwithout requiring root privileges\fR.\& Syd is designed for ease of use
across a wide array of architectures, including \fBx86\fR, \fBx86_64\fR, \fBx32\fR,
\fBarmv7\fR, \fBaarch64\fR, \fBloongarch64\fR, \fBmips\fR, \fBmips64\fR, \fBmips64el\fR, \fBppc\fR,
\fBppc64\fR, \fBppc64le\fR, \fBriscv64\fR, and \fBs390x\fR embodying the principle of
providing simple, flexible, and robust access control to Linux users.\&
.PP
The core functionality of Syd revolves around restricting a process'\&s
resource access through several mechanisms:
.PP
.PD 0
.IP \(bu 4
\fBBind Mounts\fR: Utilized within a mount namespace to enforce restrictions at 
the \fBVirtual File System (VFS)\fR level, such as \fBread-only\fR, \fBnodev\fR, \fBnoexec\fR, 
\fBnosuid\fR, and \fBnosymfollow\fR.\&
.IP \(bu 4
\fBLandlock\fR: Employs read-only and read-write path restrictions at the kernel level.\&
.IP \(bu 4
\fBseccomp-bpf\fR: Applies Secure Computing user filters for kernel-space sandboxing.\&
.IP \(bu 4
\fBseccomp-notify\fR: Enables sandboxing in kernel space with user space 
fallback for dereferencing pointer arguments in system calls, 
including pathnames and network addresses.\& Access checks utilize 
UNIX shell-style patterns and CIDR notation, defaulting to denying 
system calls with \fBEACCES\fR while attempting to emulate successful 
calls to mitigate \fBTime-of-Check to Time-of-Use (TOCTOU)\fR 
attack vectors.\&
.PD
.PP
Prerequisites for Syd include a Linux kernel supporting \fIpidfd_getfd\fR(2) and
\fIpidfd_send_signal\fR(2) system calls, \fBSECCOMP_USER_NOTIF_FLAG_CONTINUE\fR
operation in the Secure Computing facility, and preferably the
\fBCONFIG_CROSS_MEMORY_ATTACH\fR kernel option.\& For syscall emulation, Syd uses the
seccomp operation \fBSECCOMP_IOCTL_NOTIF_ADDFD\fR.\& Moreover Syd sets the
\fBSECCOMP_FILTER_FLAG_WAIT_KILLABLE_RECV\fR flag to correctly handle interrupts
during tracing.\& While \fILinux version 5.\&19 or later is required\fR, for Landlock
support Syd requires a kernel configured with the option \fBCONFIG_LSM_LANDLOCK\fR
supporting \fILandlock ABI version 3\fR, with \fIsyd-lock\fR(1) available as a helper
program to verify kernel support.\&
.PP
Syd is committed to maintaining rigorous security standards by strictly
delimiting the resource space accessible to sandboxed processes.\& In the
\fBSECURITY\fR section of the \fIsyd\fR(7) manual page, a detailed enumeration of the
security hardening measures implemented by Syd is provided, along with optional
configurations to relax certain restrictions.\& This flexibility allows for the
accommodation of a diverse range of processes within the sandbox environment.\&
.PP
The approach to security within Syd is methodically designed to balance
robust protection with operational flexibility, ensuring that users have the
ability to fine-tune the sandboxing mechanisms to meet specific requirements.\& By
offering insights into the hardening techniques and customization options,
Syd empowers users to navigate the trade-offs between security and
functionality effectively.\&
.PP
.SH OPTIONS
.PP
The following options are understood:
.PP
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fB-h\fR
T}	T{
Show usage and exit.\&
T}
T{
\fB-V\fR
T}	T{
Show version and exit.\&
T}
T{
\fB-c\fR
T}	T{
Login shell compatibility
T}
T{

T}	T{
Causes command to be executed under a shell with the \fBuser\fR profile.\&
T}
T{

T}	T{
The shell to execute is \fB/bin/sh\fR by default.\&
T}
T{

T}	T{
Use the environment variable \fBSYD_SHELL\fR to override.\&
T}
T{
\fB-f\fR
T}	T{
Login shell compatibility.\&
T}
T{

T}	T{
Causes Syd to parse the \fBuser\fR profile on startup.\&
T}
T{
\fB-l\fR, \fB--login\fR
T}	T{
Login shell compatibility
T}
T{

T}	T{
Causes Syd to parse the \fBuser\fR profile on startup.\&
T}
T{
\fB-q\fR
T}	T{
Enable quick boot mode for faster startup times.\&
T}
T{

T}	T{
This must be passed as the first option or it will be ignored.\&
T}
T{

T}	T{
See the explanation of the environment variable \fBSYD_QUICK_BOOT\fR for the safety of this option.\&
T}
T{
\fB-x\fR
T}	T{
Enable \fBtrace\fR aka "dry run" mode.\&
T}
T{

T}	T{
In this mode Syd will allow system calls even if they raise access violations.\&
T}
T{

T}	T{
This mode with extended logging can be used to build sandboxing profiles in an automated way.\&
T}
T{

T}	T{
See \fIpandora\fR(1) which is a tool that uses Syd'\&s trace mode to automatically generate sandbox profiles.\&
T}
T{
\fB-m config\fR
T}	T{
Configure sandbox during init, may be repeated.\&
T}
T{
\fB-p name\fR
T}	T{
Use a sandbox profile during init, may be repeated.\&
T}
T{
\fB-P path\fR
T}	T{
Run a configuration file during init, may be repeated.\&
T}
T{
\fB-a alias\fR
T}	T{
Set alias of the command.\& Passed as \fBargv[0]\fR to the program.\&
T}
T{
\fB-e\fR
T}	T{
Use \fB-e var=val\fR to put var=val in the environment for command, may be repeated.\&
T}
T{

T}	T{
Use \fB-e var\fR to remove var from the environment for command, may be repeated.\&
T}
T{

T}	T{
Use \fB-e var=\fR to pass-through an unsafe environment variable, may be repeated.\&
T}
T{
\fB-E mode\fR
T}	T{
Export secure computing rules with the given format to standard output and exit.\&
T}
T{

T}	T{
Mode must be one of \fBbpf\fR or \fBpfc\fR:
T}
T{

T}	T{
\fBbpf\fR, aka \fBBerkeley Packet Filter\fR is a binary, machine readable format, whereas
T}
T{

T}	T{
\fBpfc\fR, aka \fBPseudo Filter Code\fR is a textual, human readable format.\&
T}
T{
\fB--el\fR
T}	T{
Output \fBsyd.\&el\fR which is the Emacs Lisp implementation of Syd \fIstat\fR(2) interface.\&
T}
T{

T}	T{
This file is also available via the magic path \fB/dev/syd.\&el\fR.\&
T}
T{
\fB--sh\fR
T}	T{
Output a shell script which defines the \fBesyd\fR helper function.\&
T}
T{

T}	T{
This file is also available via the magic path \fB/dev/syd.\&sh\fR.\&
T}
T{

T}	T{
Works with POSIX sh, bash and zsh.\&
T}
T{

T}	T{
You may use \fBeval "$(syd --sh)"\fR in your shell init file.\&
T}
.TE
.sp 1
.SH INVOCATION
.PP
Syd can either execute a command with the specified arguments or load a
dynamic library and execute the function \fIsyd_main()\fR from it.\& In case
the first non-option argument ends with the suffix ".\&so", it is expected
to be the path of a dynamic library to load.\& The dynamic library is
loaded early at the startup in the Syd process such that even its owning
filesystem can be mounted \fInoexec\fR, using e.\&g.\& bind+/:/:noexec.\& This
allows to create a very restricted environment for the library function
to run inside.\& The function \fIsyd_main()\fR must take no arguments and
return an integer.\& This integer is going to be the exit value of the Syd
process.\& Note, loading a library requires care because its contructors
will run unsandboxed.\&
.PP
.SH ENVIRONMENT
.PP
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fBSYD_LOG\fR
T}	T{
Set log level to \fBemerg\fR, \fBalert\fR, \fBcrit\fR, \fBerror\fR, \fBwarn\fR, \fBnotice\fR, \fBinfo\fR or \fBdebug\fR.\&
T}
T{
\fBSYD_LOG_BUF_LEN\fR
T}	T{
Set syslog(2) ring buffer capacity.\&
T}
T{

T}	T{
By default, the ring buffer is allocated on the stack with an architecture-dependent size.\&
T}
T{

T}	T{
Setting this variable makes Syd allocate the ring buffer on the heap with the user-specified size.\&
T}
T{

T}	T{
Note, the value is parsed using the \fBparse-size\fR crate.\&
T}
T{

T}	T{
Refer to their documentation for information on formatting.\&
T}
T{
\fBSYD_LOG_FD\fR
T}	T{
Set log file descriptor, defaults to 2 aka standard error.\&
T}
T{
\fBSYD_PID_FN\fR
T}	T{
Set pid filename, makes Syd write its process ID to this file at startup.\&
T}
T{

T}	T{
The file must \fInot\fR exist and is going to be created with user-only read permissions.\&
T}
T{
\fBSYD_NPROC\fR
T}	T{
Set the number of core syscall handler threads, defaults to the number of CPUs.\&
T}
T{
\fBSYD_NO_SYSLOG\fR
T}	T{
Disable logging to \fIsyslog\fR(3),
T}
T{

T}	T{
By default logs of severity \fBwarn\fR and higher are logged to \fIsyslog\fR(3).\&
T}
T{
\fBSYD_SHELL\fR
T}	T{
Pick the shell to spawn when invoked as a login shell, defaults to "/bin/sh".\&
T}
T{
\fBSYD_SYNC_SCMP\fR
T}	T{
Use synchronous mode for seccomp-notify.\& This may help with performance.\&
T}
T{
\fBSYD_FORCE_TTY\fR
T}	T{
Force TTY output which is pretty-printed JSON.\&
T}
T{
\fBSYD_QUIET_TTY\fR
T}	T{
Force quiet TTY output which is line-oriented JSON.\&
T}
T{
\fBSYD_PROXY_HOST\fR
T}	T{
Override the default value of \fBproxy/ext/host\fR,
T}
T{

T}	T{
If the value is a hostname and not an IP address,
T}
T{

T}	T{
Syd resolves this hostname at startup and selects a response IP randomly.\&
T}
T{
\fBSYD_PROXY_PORT\fR
T}	T{
Override the default value of \fBproxy/ext/port\fR.\&
T}
T{
\fBSYD_QUICK_BOOT\fR
T}	T{
Enable quick boot mode, this makes Syd startup noticably faster:
T}
T{

T}	T{
\fIHowever, quick boot removes a layer of defense against some container breaks!\&\fR
T}
T{

T}	T{
Use this if you frequently re-execute \fIsyd\fR(1) or \fIsyd-oci\fR(1),
T}
T{

T}	T{
as Exherbo Linux does during \fIcave-generate-metadata\fR(1).\&
T}
T{
\fBSYD_NO_CROSS_MEMORY_ATTACH\fR
T}	T{
Disable cross memory attach and use "/proc/pid/mem".\&
T}
T{

T}	T{
By default, Syd falls back to "/proc/pid/mem" automatically,
T}
T{

T}	T{
if \fIprocess_vm_readv\fR(2) or \fIprocess_vm_writev\fR(2) fails with "ENOSYS".\&
T}
.TE
.sp 1
.SH LOGGING
.PP
There'\&re eight log levels: emerg, alert, crit, error, warn, notice,
info, and debug.\& Log level may be set with the "SYD_LOG" environment
variable.\& Logs go to standard error unless a file descriptor is
specified with the environment variable "SYD_LOG_FD".\& The messages of
severity warn and above are also sent to \fIsyslog\fR(3) unless the
environment variable "SYD_NO_SYSLOG" is set.\&
.PP
Syd logs in JSON lines.\& Below is a list of some of the commonly used
keys and their meanings:
.PP
.TS
allbox;l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
\fBKEY\fR
T}	T{
\fBDESCRIPTION\fR
T}
T{
\fBctx\fR
T}	T{
Context of the log entry, e.\&g.\& \fBaccess\fR, \fBsafesetid\fR, \fBsegvguard\fR etc.\&
T}
T{
\fBcap\fR
T}	T{
Sandbox capability
T}
T{
\fBact\fR
T}	T{
Sandbox action: \fBAllow\fR, \fBWarn\fR, \fBDeny\fR, \fBStop\fR, \fBKill\fR or \fBExit\fR
T}
T{
\fBpid\fR
T}	T{
Process ID
T}
T{
\fBpath\fR
T}	T{
Path argument of the syscall
T}
T{
\fBaddr\fR
T}	T{
Network address argument of the syscall, e.\&g.\& "127.\&0.\&0.\&1!\&22"
T}
T{
\fBunix\fR
T}	T{
UNIX socket address argument of the syscall
T}
T{
\fBipv\fR
T}	T{
IP version of the network address in the \fBaddr\fR field (4 or 6)
T}
T{
\fBabs\fR
T}	T{
True if the socket address in the \fBunix\fR field is an abstract UNIX socket
T}
T{
\fBsys\fR
T}	T{
Name of the syscall
T}
T{
\fBarch\fR
T}	T{
Architecture of the syscall
T}
T{
\fBargs\fR
T}	T{
Arguments of the syscalll
T}
T{
\fBsrc\fR
T}	T{
Origin of the syscall in format "path+offset"
T}
T{

T}	T{
Use, e.\&g.\& "objdump -D path | grep offset" to display the syscall instruction
T}
T{
\fBcmd\fR
T}	T{
Process name, or command line if log output is a TTY or "log" feature is enabled
T}
T{
\fBcwd\fR
T}	T{
Current working directory of the process
T}
T{
\fBuid\fR
T}	T{
User ID
T}
T{
\fBtime\fR
T}	T{
Timestamp in ISO8601-compatible format, currently "YYYYMMDDThhmmssZ"
T}
T{

T}	T{
Time format may change but it will always remain ISO8601-compatible
T}
T{
\fBerr\fR
T}	T{
Error information
T}
T{
\fBmsg\fR
T}	T{
Miscellaneous informational messages, mostly used with the "info" log level
T}
T{
\fBtip\fR
T}	T{
Informational messages on how to configure the sandbox
T}
.TE
.sp 1
.SH EXIT CODES
.PP
Syd exits with the same exit code as the sandbox process itself.\& If the
sandbox process exits with a signal, Syd exits with 128 plus the value of the
signal.\& In case there was an error in spawning or waiting for the sandbox
process, Syd exits with \fBerrno\fR indicating the error condition.\& E.\&g.\& \fBsyd
true\fR returns \fB0\fR, \fBsyd false\fR returns \fB1\fR, and \fBsyd -- syd true\fR returns \fB16\fR
which stands for \fBEBUSY\fR which means \fBDevice or resource busy\fR indicating there
is already a secure computing filter loaded.\&
.PP
.SH BENCHMARKS
.PP
The table below lists the benchmark runs we ran for Syd:
.PP
.TS
allbox;l l c
l l c
l l c
l l c
l l c
l l c
l l c.
T{
1: compile kernel
T}	T{
sydbox-{1,3}
T}	T{
https://gitlab.\&exherbo.\&org/-/snippets/2534
T}
T{
2: compile kernel
T}	T{
sydbox-{1,3}
T}	T{
https://gitlab.\&exherbo.\&org/-/snippets/2536
T}
T{
3: unpack compressed tarball
T}	T{
sydbox-{1,3}, Gentoo sandbox
T}	T{
https://gitlab.\&exherbo.\&org/-/snippets/2537
T}
T{
4: compile kernel
T}	T{
sydbox-{1,3}, Gentoo sandbox
T}	T{
https://gitlab.\&exherbo.\&org/-/snippets/2594
T}
T{
5: compile kernel in a Podman container
T}	T{
syd-oci, crun, runc, youki, gvisor
T}	T{
https://gitlab.\&exherbo.\&org/-/snippets/2613
T}
T{
6: compile kernel in a Podman container
T}	T{
syd-oci, crun, runc, youki, gvisor
T}	T{
https://gitlab.\&exherbo.\&org/-/snippets/2622
T}
T{
7: run sqlite-bench
T}	T{
no-syd, syd, syd+crypt
T}	T{
https://gitlab.\&exherbo.\&org/-/snippets/2758
T}
.TE
.sp 1
.SH SEE ALSO
.PP
\fIsyd\fR(2), \fIsyd\fR(5), \fIsyd\fR(7), \fIsyd-lock\fR(1), \fIsyd-ls\fR(1)
.PP
.PD 0
.IP \(bu 4
\fBsyd\fR homepage: https://sydbox.\&exherbolinux.\&org/
.IP \(bu 4
\fBlibsyd\fR homepage: https://libsyd.\&exherbolinux.\&org/
.IP \(bu 4
\fBpandora\fR homepage: https://lib.\&rs/pandora_box
.IP \(bu 4
\fBpaludis\fR homepage: http://paludis.\&exherbolinux.\&org/
.IP \(bu 4
\fBLandlock\fR homepage: https://landlock.\&io
.IP \(bu 4
\fBPath\fR wiki: https://en.\&wikipedia.\&org/wiki/Path_(computing)
.IP \(bu 4
\fBUnix domain socket\fR wiki: https://en.\&wikipedia.\&org/wiki/Unix_domain_socket
.IP \(bu 4
\fBIPv4\fR wiki: https://en.\&wikipedia.\&org/wiki/IPv4
.IP \(bu 4
\fBIPv6\fR wiki: https://en.\&wikipedia.\&org/wiki/IPv6
.IP \(bu 4
\fBTOCTOU\fR wiki: https://en.\&wikipedia.\&org/wiki/Time-of-check_to_time-of-use
.IP \(bu 4
\fBVFS\fR wiki: https://en.\&wikipedia.\&org/wiki/Virtual_file_system
.IP \(bu 4
\fBipnetwork\fR documentation: https://docs.\&rs/ipnetwork
.IP \(bu 4
\fBEnabling Logging\fR: https://docs.\&rs/env_logger/latest/env_logger/#enabling-logging
.PD
.PP
.SH AUTHORS
.PP
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.\&