--- name: "syd" section: "1" platform: "linux" package: "syd" version: "3.59.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/syd" --- # syd(1) Rock solid application kernel ## NAME **syd** - Rock solid application kernel ## SYNOPSIS **syd** \[-acefhlmpqtxEPV\] \[--\] {command \[arg...\]} **syd** --api **syd** --check **syd** --el **syd** --sh ## DESCRIPTION Syd is a utility that uses the [*seccomp*(2)](/seccomp/2.md) system call to sandbox processes on Linux systems version 5.19 or later. It enables per-syscall control over a process's filesystem and network access *without* *requiring root privileges*. Syd is designed for ease of use across a wide array of architectures, including **x86**, **x86\_64**, **x32**, **armv7**, **aarch64**, **loongarch64**, **mips**, **mips64**, **mips64el**, **ppc**, **ppc64**, **ppc64le**, **riscv64**, and **s390x** embodying the principle of providing simple, flexible, and reliable access control to Linux users. The core functionality of Syd revolves around restricting a process's resource access through several mechanisms: - • **Bind Mounts**: Utilized within a mount namespace to enforce restrictions at the **Virtual File System (VFS)** level, such as **read-only**, **nodev**, **noexec**, **nosuid**, and **nosymfollow**. - • **Landlock**: Employs read-only and read-write path restrictions at the kernel level. - • **seccomp-bpf**: Applies Secure Computing user filters for kernel-space sandboxing. - • **seccomp-notify**: Enables sandboxing in kernel space with user space fallback for dereferencing pointer arguments in system calls, including pathnames and network addresses. Access checks use UNIX shell-style patterns and CIDR notation, defaulting to denying system calls with **EACCES** while attempting to emulate successful calls to mitigate **Time-of-Check to Time-of-Use (TOCTOU)** attack vectors. Prerequisites for Syd include a Linux kernel supporting [*pidfd\_getfd*(2)](/pidfd_getfd/2.md) and [*pidfd\_send\_signal*(2)](/pidfd_send_signal/2.md) system calls, **SECCOMP\_USER\_NOTIF\_FLAG\_CONTINUE** operation in the Secure Computing facility, and preferably the **CONFIG\_CROSS\_MEMORY\_ATTACH** kernel option. For syscall emulation, Syd uses the seccomp operation **SECCOMP\_IOCTL\_NOTIF\_ADDFD**. Syd also sets the **SECCOMP\_FILTER\_FLAG\_WAIT\_KILLABLE\_RECV** flag to correctly handle interrupts during tracing. While *Linux version 5.19 or later is required*, for Landlock support Syd requires a kernel configured with the option **CONFIG\_LSM\_LANDLOCK** supporting *Landlock ABI version 3*, with [*syd-lock*(1)](/syd-lock/1.md) available as a helper program to verify kernel support. Linux kernel options **CONFIG\_KCMP** and **CONFIG\_UNIX\_DIAG** are recommended. By default, Syd restricts the resource space accessible to sandboxed processes as tightly as possible. The **SECURITY** section of the [*syd*(7)](/syd/7.md) manual page lists all hardening measures and the *trace/allow\_unsafe\_\** options to relax specific restrictions when needed. ## OPTIONS The following options are understood: | | | | --- | --- | | **-h**, **--help** | Show usage and exit. | | **-V**, **--version** | Show version and exit. | | **-C**, **--check** | Print sandboxing support information about the current system and exit. | | **-v**, **--verbose** | Increase verbosity, equivalent to incrementing **log/verbose** by one. | | **-c** | Login shell compatibility | | | Causes command to be executed under a shell with the **user** profile. | | | The shell to execute is */bin/sh* by default. | | | Use the environment variable **SYD\_SHELL** to override. | | **-f** | Login shell compatibility. | | | Causes Syd to parse the **user** profile on startup. | | **-l**, **--login** | Login shell compatibility | | | Causes Syd to parse the **user** profile on startup. | | **-q** | Enable quick boot mode for faster startup times. | | | This must be passed as the first option or it will be ignored. | | | See the explanation of the environment variable **SYD\_QUICK\_BOOT** for the safety of this option. | | **-x** | Enable **trace** aka "dry run" mode. | | | In this mode Syd will allow system calls even if they raise access violations. | | | This mode with extended logging can be used to build sandboxing profiles in an automated way. | | | See *pandora*(1) which is a tool that uses Syd's trace mode to automatically generate sandbox profiles. | | **-m config** | Configure sandbox during init, may be repeated. | | **-p name** | Use a sandbox profile during init, may be repeated. | | **-P path** | Run a configuration file during init, may be repeated. | | **-a alias** | Set alias of the command. Passed as **argv\[0\]** to the program. | | **-e** | Use **-e var=val** to put var=val in the environment for command, may be repeated. | | | Use **-e var** to remove var from the environment for command, may be repeated. | | | Use **-e var=** to pass-through an unsafe environment variable, may be repeated. | | **-t timeout** | Specify sandbox timeout in human readable format. | | | Equivalent to **timeout** option, refer to [*syd*(2)](/syd/2.md) for more information. | | **-E mode** | Export secure computing rules with the given format to standard output and exit. | | | Mode must be one of **bpf** or **pfc**: | | | **bpf**, aka **Berkeley Packet Filter** is a binary, machine readable format, whereas | | | **pfc**, aka **Pseudo Filter Code** is a textual, human readable format. | | **--api** | Output [*syd*(2)](/syd/2.md) API specification in JSON format. | | | This specification is intended to ease generation of language bindings. | | | This specification is also available via the magic path **/dev/syd**. | | **--el** | Output **syd.el** which is the Emacs Lisp implementation of Syd [*stat*(2)](/stat/2.md) interface. | | | This file is also available via the magic path **/dev/syd.el**. | | **--sh** | Output a shell script which defines the **esyd** helper function. | | | This file is also available via the magic path **/dev/syd.sh**. | | | Works with POSIX sh, bash and zsh. | | | You may use **eval "$(syd --sh)"** in your shell init file. | ## INVOCATION Syd executes a command with the specified arguments under a sandbox and exits with the same status. The sandbox may be constructed by command-line arguments and configuration files. [*syd*(2)](/syd/2.md) API is available for dynamic configuration if the sandbox lock allows it. An IPC socket may be configured with the *ipc* command to configure Syd through a UNIX socket. Refer to the [*syd*(2)](/syd/2.md) manual page for more information. ## ENVIRONMENT | | | | --- | --- | | **SYD\_IPC** | Specify UNIX socket address for runtime configuration. | | | Equivalent to the **ipc** command, see the [*syd*(2)](/syd/2.md) manual page. | | | **ipc** command has precedence over this environment variable. | | **SYD\_LOG** | Set log level to **emerg**, **alert**, **crit**, **error**, **warn**, **notice**, **info** or **debug**. | | **SYD\_LOG\_BUF\_LEN** | Set [*syslog*(2)](/syslog/2.md) ring buffer capacity. | | | By default, ring buffer is allocated on the stack with 256k size. | | | Setting this variable makes Syd allocate ring buffer on the heap with user-specified size. | | | The value is parsed using the **parse-size** crate. | | | Refer to their documentation for information on formatting. | | **SYD\_LOG\_FD** | Set log file descriptor, defaults to [*stderr*(3)](/stderr/3.md). | | | Negative values are permitted as a shorthand to disable logging. | | | Positive values must be valid FDs or Syd will exit with **EBADF** ("Bad file number"). | | **SYD\_PDS** | Set parent-death signal with [*PR\_SET\_PDEATHSIG*(2const)](/PR_SET_PDEATHSIG/2const.md) using signal name or number. | | **SYD\_PID\_FN** | Set pid filename, makes Syd write its process ID to this file at startup. | | | The file must not exist and is going to be created with user-only read permissions. | | **SYD\_NPROC** | Set the number of core syscall handler threads, defaults to the number of CPUs. | | | The number must be at least 1. | | **SYD\_NPROC\_MAX** | Set the number of maximum syscall handler threads, defaults to usize::MAX. | | | The number must be greater than **SYD\_NPROC**. | | **SYD\_CHDIR** | Change current working directory to a safe directory at startup. | | | This is implied if no optional arguments are given. | | **SYD\_COMPAT\_SOCKET** | Allow the legacy [*socketcall*(2)](/socketcall/2.md) multiplexer system call. | | | This is only necessary for compatibility with libcs which don't yet support the newer non-multiplexed system calls available as of Linux-4.3. | | | Equivalent to **trace/allow\_unsafe\_socketcall:1**. | | **SYD\_SHELL** | Pick the shell to spawn when invoked as a login shell. It is not split into words. | | | Defaults to **/usr/bin/bash --login --noprofile --norc --restricted**. | | **SYD\_DUMP\_SCMP** | Export secure computing rules with the given format, equivalent to the **-E** option. | | **SYD\_SKIP\_SCMP** | Skip [*seccomp*(2)](/seccomp/2.md) confinement of per-Syd threads. | | | This is **unsafe** and should only used for profiling. | | | Syd honours **RUST\_BACKTRACE** environment variable when this is set. | | | This is ignored unless Syd is built with the **trusted** Cargo feature. | | **SYD\_SKIP\_NAME** | Skip randomizing Syd thread names which is useful for debugging. | | | This is ignored unless Syd is built with the **trusted** Cargo feature. | | **SYD\_FORCE\_NO\_UNIX\_DIAG** | Force disable UNIX socket diagnostics, to test fallback paths used on kernels configured without **CONFIG\_UNIX\_DIAG**. | | | This is intended for testing and should not be used in production. | | | This is ignored unless Syd is built with the **trusted** Cargo feature. | | **SYD\_FORCE\_NO\_SYMLINKS** | Force **RESOLVE\_NO\_SYMLINKS** resolve flag at [*open*(2)](/open/2.md) boundary. | | | Equivalent to **trace/force\_no\_symlinks:1**. | | **SYD\_FORCE\_NO\_MAGICLINKS** | Force **RESOLVE\_NO\_MAGICLINKS** resolve flag at [*open*(2)](/open/2.md) boundary. | | | Equivalent to **trace/force\_no\_magiclinks:1**. | | **SYD\_FORCE\_NO\_XDEV** | Force **RESOLVE\_NO\_XDEV** resolve flag at [*open*(2)](/open/2.md) boundary. | | | Equivalent to **trace/force\_no\_xdev:1**. | | **SYD\_FORCE\_CLOEXEC** | Force close-on-exec for file descriptors. | | | Equivalent to **trace/force\_cloexec:1**. | | **SYD\_FORCE\_RAND\_FD** | Use randomized file descriptors to harden against fd reuse. | | | Equivalent to **trace/force\_rand\_fd:1**. | | | This environment variable is ignored if [*kcmp*(2)](/kcmp/2.md) isn't supported. | | **SYD\_FORCE\_RO\_OPEN** | Reject creating and writing [*open*(2)](/open/2.md) calls. | | | Equivalent to **trace/force\_ro\_open:1**. | | **SYD\_FORCE\_WX\_OPEN** | Reject creating and writing [*open*(2)](/open/2.md) calls for executables. | | | Equivalent to **trace/force\_wx\_open:1**. | | **SYD\_FORCE\_LOCAL\_NET** | Force local networking, rewrites all addresses to loopback for bind/connect. | | | Equivalent to **trace/force\_local\_net:1**. | | **SYD\_FORCE\_TTY** | Force TTY output which is pretty-printed JSON. | | **SYD\_QUIET\_TTY** | Force quiet TTY output which is line-oriented JSON. | | **SYD\_PROXY\_HOST** | Override the default value of **proxy/ext/host**, | | | If the value is a hostname and not an IP address, | | | Syd resolves this hostname at startup and selects a response IP randomly. | | **SYD\_PROXY\_PORT** | Override the default value of **proxy/ext/port**. | | **SYD\_PROXY\_UNIX** | Set the default value for **proxy/ext/unix** which overrides **proxy/ext/host**. | | **SYD\_QUICK\_BOOT** | Enable quick boot mode, this makes Syd startup noticeably faster: | | | However, quick boot removes a layer of defense against some container breaks! | | | Use this if you frequently re-execute [*syd*(1)](/syd/1.md) or [*syd-oci*(1)](/syd-oci/1.md), | | | as Exherbo Linux does during *cave-generate-metadata*(1). | | | This is ignored unless Syd is built with the **trusted** Cargo feature. | | **SYD\_RLIMIT\_AS** | Set the default value for **rlimit/as**. | | **SYD\_RLIMIT\_CORE** | Set the default value for **rlimit/core**. | | **SYD\_RLIMIT\_DATA** | Set the default value for **rlimit/data**. | | **SYD\_RLIMIT\_FSIZE** | Set the default value for **rlimit/fsize**. | | **SYD\_RLIMIT\_MEMLOCK** | Set the default value for **rlimit/memlock**. | | **SYD\_RLIMIT\_NICE** | Set the default value for **rlimit/nice**. | | **SYD\_RLIMIT\_NOFILE** | Set the default value for **rlimit/nofile**. | | **SYD\_RLIMIT\_NPROC** | Set the default value for **rlimit/nproc**. | | **SYD\_RLIMIT\_RTPRIO** | Set the default value for **rlimit/rtprio**. | | **SYD\_RLIMIT\_RTTIME** | Set the default value for **rlimit/rttime**. | | **SYD\_RLIMIT\_SIGPENDING** | Set the default value for **rlimit/sigpending**. | | **SYD\_RLIMIT\_STACK** | Set the default value for **rlimit/stack**. | | **SYD\_TMOUT** | Set the default value for **timeout**. | | **SYD\_NO\_CROSS\_MEMORY\_ATTACH** | Disable cross memory attach and use [*proc\_pid\_mem*(5)](/proc_pid_mem/5.md) unconditionally. | | **SYD\_PROC\_PID\_MEM\_FALLBACK** | By default, Syd uses cross memory attach unconditionally. | | | Setting this variable causes Syd to fall back to [*proc\_pid\_mem*(5)](/proc_pid_mem/5.md) automatically, | | | if [*process\_vm\_readv*(2)](/process_vm_readv/2.md) or [*process\_vm\_writev*(2)](/process_vm_writev/2.md) fails with **ENOSYS**, | | | which indicates kernel support is missing for these system calls. | | | The variable **SYD\_NO\_CROSS\_MEMORY\_ATTACH** has precedence over this variable. | | **SYD\_ASSUME\_KERNEL** | Override [*uname*(2)](/uname/2.md) to get host Linux kernel version used for feature detection. | | | Syd reports the major and minor kernel version at [*uname*(2)](/uname/2.md) boundary within the sandbox. | | | The micro version is randomized per-Syd run to prevent information leaks. | | | This environment variable is ignored unless Syd is built with the "trusted" feature. | | **SYD\_PALUDIS\_LPATH** | Override *sandbox/lpath* option for the *paludis* profile, defaults to off. | | **SYD\_PALUDIS\_NPATH** | Override *sandbox/npath* option for the *paludis* profile, defaults to off. | | **SYD\_PALUDIS\_LIST** | Override *sandbox/list* option for the *paludis* profile, defaults to off. | | **SYD\_PALUDIS\_WALK** | Override *sandbox/walk* option for the *paludis* profile, defaults to off. | | **SYD\_PALUDIS\_IOCTL** | Override *sandbox/ioctl* option for the *paludis* profile, defaults to off. | | **SYD\_PALUDIS\_PASSFD** | Override *sandbox/passfd* option for the *paludis* profile, defaults to off. | | **SYD\_USER\_LPATH** | Override *sandbox/lpath* option for the *user* profile, defaults to on. | ## LOGGING There're eight log levels: emerg, alert, crit, error, warn, notice, info, and debug with descending priority. Log level may be set with the **SYD\_LOG** environment variable. Logs go to [*stderr*(3)](/stderr/3.md) unless a file descriptor is specified with the environment variable **SYD\_LOG\_FD**. Syd logs in JSON lines. Below is a list of commonly used log keys with their descriptions: | | | | --- | --- | | **KEY** | **DESCRIPTION** | | **id** | Sandbox ID as 64 lowercase hexadecimal characters. | | **ctx** | Context of log entry, e.g. **access**, **safesetid**, **segvguard** etc. | | **cap** | Sandbox capability | | **act** | Sandbox action: **allow**, **warn**, **deny**, **panic**, **stop**, **abort**, **kill** or **exit** | | **pid** | Process ID | | **path** | Path argument of syscall | | **addr** | Network address argument of syscall, e.g. **127.0.0.1!22** | | **unix** | UNIX socket address argument of syscall | | **ipv** | IP version of network address in **addr** field (4 or 6) | | **abs** | True if socket address in **unix** field is an abstract UNIX socket | | **sys** | Name of syscall | | **arch** | Architecture of syscall | | **args** | Arguments of syscalll | | **cmd** | Process name, or command line if log output is a TTY or **log** feature is enabled | | **cwd** | Current working directory of sandbox process | | **uid** | User ID | | **time** | Timestamp in ISO8601-compatible format, currently **YYYYMMDDThhmmssZ** | | | Time format may change but it will always remain ISO8601-compatible. | | | Formatting errors fallback to printing timestamp as an integer. | | **err** | Error information | | **msg** | Informational messages | | **tip** | Educational messages on how to configure Syd | ## EXIT STATUS Syd exits with same exit code as the sandbox process. If the sandbox process exits with a signal, Syd exits with 128 plus value of the signal. In case there was an error in spawning or waiting for the sandbox process, Syd exits with [*errno*(3)](/errno/3.md) indicating the error condition. Syd exits with 101 on panics. Syd exits with 102 on fatal allocator errors. Syd exits with 124 if sandbox timeout is exceeded. ## SEE ALSO [*syd*(2)](/syd/2.md), [*syd*(5)](/syd/5.md), [*syd*(7)](/syd/7.md), [*syd-lock*(1)](/syd-lock/1.md), [*syd-ls*(1)](/syd-ls/1.md), [*syd-mdwe*(1)](/syd-mdwe/1.md), [*syd-ring*(1)](/syd-ring/1.md), [*sydtutorial*(7)](/sydtutorial/7.md) - • **syd** homepage: https://sydbox.exherbo.org/ - • **libsyd** homepage: https://libsyd.exherbo.org/ - • **pandora** homepage: https://lib.rs/pandora\_box - • **paludis** homepage: http://paludis.exherbo.org/ - • **Landlock** homepage: https://landlock.io ## 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.