.\" 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" "5" "2025-02-22"
.PP
.SH NAME
.PP
syd - document format for writing Syd profiles
.PP
.SH API
.PP
Current version of the Syd command API is \fB3\fR.\& This version is \fBstable\fR.\&
.PP
.SH CONFIGURATION
.PP
Syd is configured through sandbox commands.\& For multiple matching rules
(e.\&g.\&  two rules matching the same path), \fIthe last matching rule wins\fR.\&
There are two ways to supply sandbox commands.\& First, Syd may be
configured using a configuration file.\& The path to the configuration
file is speficied using the \fB-P\fR command line switch.\& More than one
configuration file may be specified this way.\& Single commands may also
be passed via \fB-m\fR command line switch.\&  Configuration profiles may be
applied using the \fB-p\fR command line switch.\& See the \fBPROFILES\fR section
for more information.\& Second, Syd may be configured using \fBmagic\fR
\fIstat\fR(2) calls during runtime.\&  This is achieved by calling \fIstat\fR(2)
system call on the special path \fB/dev/syd\fR followed by the sandbox
command.\& Note that runtime configuration is only possible if the sandbox
lock is \fBunset\fR.\& The system call \fIstat\fR(2) was chosen because it is
practical to invoke using builtin shell commands like:
.PP
.nf
.RS 4
; test -c /dev/syd/sandbox/read:on
.fi
.RE
.PP
which enables \fBRead Sandboxing\fR for a shell running under Syd.\& It is
also possible to query certain values using the return value of the
\fIstat\fR(2) call:
.PP
.nf
.RS 4
test -c /dev/syd/sandbox/read? && echo read sandboxing on || echo read sandboxing off
.fi
.RE
.PP
Note, some of these shell builtins may actually call other system calls such as
\fIfstat\fR(2), \fIlstat\fR(2), \fInewfstatat\fR(2), or \fIstatx\fR(2).\& Syd supports the same
interface through all these system calls transparently.\& Check the manual page
\fIsyd\fR(2) for a description of the \fIstat\fR(2) interface.\&
.PP
.SH NAMING
.PP
Configuration file naming of Syd follows a naming scheme which makes it
possible to extract command API version from the file name.\& A Syd
configuration file must have the extension \fBsyd-\fR followed by the API version
(e.\&g.\& \fB"syd-3"\fR for API version \fB3\fR).\&
.PP
.SH SYNTAX
.PP
Input files must use the UTF-8 encoding.\& Config format is line oriented.\&
Comments start with "#".\& Inline comments are \fInot\fR supported.\&  Blank
lines are ignored.\&  All the other lines are treated as if they were
supplied to Syd via the \fB-m\fR command line switch.\& For a list of
available sandbox commands, consult \fIsyd\fR(2).\& For a VIM syntax file for
Syd profiles check here:
https://gitlab.\&exherbo.\&org/sydbox/sydbox/-/tree/main/vim
.PP
As of verson 3.\&15.\&1, Syd adds two additional features to configuration
file parsing:
.PP
.PD 0
.IP 1. 4
Enviroment variable expansion is performed on arguments.\& 
Notably, unset environment variables are not expanded 
to empty strings.\& On environment variable lookup errors and UTF-8 
decoding errors Syd stops parsing and exits with error.\& This is done for 
safety as an unintended empty-string expansion can potentially cause the 
resulting sandboxing rule to allowlist unintended paths without the user 
easily noticing it.\& The user is recommended to set default values for 
environment variables using the familiar "${HOME:-/var/empty}" notation.\& 
If you really want empty-string expansion on unset environment 
variables, you can get this effect using the notation "${HOME:-}" but 
this is not recommended and should be used with care.\&
.IP 2. 4
"include" directives can be used to request the inclusion of another 
configuration file.\& Upon reading an include line, Syd stops parsing the 
current file, validates the given include path and start to parse the 
new configuration file.\& The file must not be writable by group or others 
for safety.\& For include files with relative paths, Syd searches the file 
under the directory of the previous configuration file rather 
than the current working directory for safety and ease of 
configuration.\&  Loops in include directives are detected by 
caching the device id and inode of the configuration files.\& Note, 
this directive is not permitted when loading configuration 
from a file descriptor using the "load" command.\&
.PD
.PP
As of version 3.\&17.\&6, Syd adds the "include_profile" directive which may be
used to include a Syd profile.\& See "syd-cat -p list" for the list of profiles.\&
.PP
.SH PROFILES
.PP
Syd has a number of predefined profiles to make configuration easier.\&
These profiles may be used standalone or stacked with other profiles and
custom configuration to create various levels of isolation and
confinement.\& To see the complete list of profiles, use "syd-cat -p list".\&
To list the rules of a profile, use "syd-cat -p <profile-name>".\& Below you
may find a brief list of common profiles and their functionality:
.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
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fBcontainer\fR
T}	T{
Enables Linux namespaces.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBc\fR.\&
T}
T{
\fBimmutable\fR
T}	T{
Enables Linux namespaces and remounts the following directories \fIread only\fR in the new mount namespace:
T}
T{

T}	T{
\fB/etc\fR, \fB/home\fR, \fB/media\fR, \fB/mnt\fR, \fB/opt\fR, \fB/srv\fR, and \fB/usr\fR.\&
T}
T{

T}	T{
Further mount options such as \fBnodev\fR, \fBnoexec\fR, \fBnosuid\fR, and \fBnoatime\fR are also applied as necessary.\&
T}
T{

T}	T{
In addition, \fB/dev/shm\fR and \fB/tmp\fR are mounted private and kernel filesystems are masked.\&
T}
T{

T}	T{
See \fBsyd-cat -p immutable\fR for the full list of mount options.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBi\fR.\&
T}
T{
\fBprivileged\fR
T}	T{
Do not drop Linux capabilities at startup.\& Used to construct privileged containers.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBp\fR.\&
T}
T{
\fBlandlock\fR
T}	T{
Enables \fBLandLock\fR and allows system directories for \fBLock Sandboxing\fR.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBl\fR.\&
T}
T{
\fBlinux\fR
T}	T{
Common Linux system profile, used by \fBoci\fR, \fBpaludis\fR and \fBuser\fR profiles.\&
T}
T{
\fBoci\fR
T}	T{
Used by \fIsyd-oci\fR(1) as the default container profile.\&
T}
T{
\fBpaludis\fR
T}	T{
Used by the \fBPaludis\fR package mangler.\&
T}
T{
\fBnoipv4\fR
T}	T{
Disables \fBIPv4\fR connectivity.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fB6\fR.\&
T}
T{
\fBnoipv6\fR
T}	T{
Disables \fBIPv6\fR connectivity.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fB4\fR.\&
T}
T{
\fBcore\fR
T}	T{
Allows generation of coredumps.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBC\fR.\&
T}
T{
\fBdebug\fR
T}	T{
Allows debuggers inside the sandbox.\&
T}
T{

T}	T{
Syd does not use \fIptrace\fR(1) with this profile, so tracers may attach.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBD\fR.\&
T}
T{
\fBnomem\fR
T}	T{
Allows unsafe memory (no W^X, no Memory-Deny-Write-Execute, allows e.\&g.\& JITs).\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBM\fR.\&
T}
T{
\fBnopie\fR
T}	T{
Relaxes PIE (Position Independent Executable) restriction.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBP\fR.\&
T}
T{
\fBquiet\fR
T}	T{
Silences all access violations.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBq\fR.\&
T}
T{
\fBoff\fR
T}	T{
Turns all sandboxing off.\&
T}
T{
\fBlib\fR
T}	T{
\fBlibsyd\fR helper profile.\& Turns all sandboxing off and sets sandbox lock to "exec".\&
T}
T{

T}	T{
Useful to configure Syd in the application using \fBlibsyd\fR.\&
T}
T{
\fBuser\fR
T}	T{
Allows user-specific directories, and connections, and parses the files
T}
T{

T}	T{
\fB/etc/user.\&syd-3\fR, and \fB~/.\&user.\&syd-3\fR if they exist.\&
T}
T{

T}	T{
Syd sets the environment variables \fBUID\fR, \fBGID\fR, \fBUSER\fR, \fBHOME\fR before parsing this profile.\&
T}
T{

T}	T{
To enforce system-wide settings, set "lock:on" at the end of \fB/etc/user.\&syd-3\fR.\&
T}
T{

T}	T{
You may refer to this profile shortly as just \fBu\fR.\&
T}
T{
\fBkvm\fR
T}	T{
Profile to allowlist KVM \fIioctl\fR(2) requests without path check.\&
T}
T{

T}	T{
Read: https://www.\&kernel.\&org/doc/Documentation/virtual/kvm/api.\&txt
T}
T{
\fBtty\fR
T}	T{
Profile to allow TTY access, used by \fBoci\fR, \fBpaludis\fR, and \fBuser\fR profiles.\&
T}
T{

T}	T{
Syd sets the environment variable \fBTTY\fR before parsing this profile.\&
T}
T{

T}	T{
If the process has no controlling terminal, \fBTTY\fR variable is set to "/dev/null".\&
T}
.TE
.sp 1
.SS Stacking Profiles
.PP
It is possible to stack multiple profiles to configure a more restricted
sandbox.\& Remember the order you stack the profiles matter, \fIthe last matching
rule wins\fR.\& Below are some examples:
.PP
.PD 0
.IP \(bu 4
syd -puser -pimmutable -mroot:/mnt/gnu .\&.\&.\&
.IP \(bu 4
syd -ppaludis -plandlock -mallow/lock/write+/var/tmp .\&.\&.\&
.PD
.PP
It is also possible to combine the one character shortcuts of helper profiles,
in order to stack them together.\& Below are some examples:
.PP
.PD 0
.IP \(bu 4
syd -pMPX .\&.\&.\& # Disable MDWE, PIE and exec restrictions.\&
.IP \(bu 4
syd -puis .\&.\&.\& # Parse user profile, create an immutable container, and silence access violations.\&
.PD
.PP
.SS Login shell and the User Profile
.PP
When invoked without arguments, \fB/bin/sh\fR is executed under Syd with the
\fBuser\fR profile as a login shell, use \fBSYD_SH\fR environment variable to override
the shell to execute.\&
.PP
.SH SECURITY
.PP
As of version 3.\&30.\&0, Syd aborts with error if path to a specified
configuration file has a symbolic link in \fIany\fR of its path components.\&
.PP
Therefore, the user \fImust\fR supply canonicalized paths as configuration
file arguments.\&
.PP
.SH EXAMPLE
.PP
.nf
.RS 4
# Syd profile for OpenNTPD

# Seccomp sandbox
sandbox/read,stat,write,exec,net:on

# Landlock
sandbox/lock:on

# Provide isolation using namespaces\&.
unshare/mount,uts,pid,ipc,cgroup:1

# Allow adjtimex and keep CAP_SYS_TIME\&.
trace/allow_unsafe_time:1

# Mount everything ro except /var
bind+tmpfs:/dev/shm:nodev,nosuid,noexec
bind+tmpfs:/tmp:nodev,nosuid
bind+/etc:/etc:ro,nodev,noexec,nosuid,noatime
bind+/home:/home:ro,nodev,noexec,nosuid,noatime
bind+/media:/media:ro,nodev,noexec,nosuid,noatime
bind+/mnt:/mnt:ro,nodev,noexec,nosuid,noatime
bind+/opt:/opt:ro,nodev,nosuid,noatime
bind+/srv:/srv:ro,nodev,noexec,nosuid,noatime
bind+/usr:/usr:ro,nodev,noatime

# Hide Syd
deny/read,stat,write+/proc/1/***

# Allow listen to the ntp port on loopback\&.
allow/net/bind+loopback!123

# Allow connections to NTP servers\&.
allow/net/connect+any!53
allow/net/connect+any!123
allow/net/connect+any!65535

# Allow logging to syslog\&.
allow/net/connect+/dev/log

# Allow `listen wildcard`
allow/net/bind+0\&.0\&.0\&.0!0
allow/net/connect+0\&.0\&.0\&.0!0

# Allow listen to the ntpd socket\&.
allow/net/bind+/run/ntpd\&.sock
allow/net/bind+/var/run/ntpd\&.sock
allow/write+/run/ntpd\&.sock
allow/write+/var/run/ntpd\&.sock

# Allow access to system paths
allow/read,stat+/dev/urandom
allow/lock/read+/dev/urandom
allow/read,stat+/etc/hosts
allow/lock/read+/etc/hosts
allow/read,stat+/etc/ntpd\&.conf
allow/lock/read+/etc/ntpd\&.conf
allow/read,stat+/etc/passwd
allow/lock/read+/etc/passwd
allow/read,stat+/etc/resolv\&.conf
allow/lock/read+/etc/resolv\&.conf
allow/read,stat+/etc/services
allow/lock/read+/etc/services
allow/read,stat+/usr/share/zoneinfo-posix/UTC

# chroot /var/empty && cd /
allow/stat+/
allow/stat+/var/empty
allow/write+/dev/null
allow/lock/write+/dev/null

# Allow executing the ntp binary\&.
allow/lock/read+/proc
allow/lock/read+/usr
allow/lock/write+/run
allow/lock/write+/var/run
allow/exec+/usr/**/bin/openntpd*

# Allow writing the drift file\&.
allow/write+/var/db/ntpd\&.drift
allow/lock/write+/var/db/ntpd\&.drift

# Lock configuration
lock:on
.fi
.RE
.PP
.SH SEE ALSO
.PP
\fIsyd\fR(1), \fIsyd\fR(2), \fIsyd\fR(7)
.PP
\fBsyd\fR homepage: https://sydbox.\&exherbolinux.\&org/
.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.\&