SYD(1)

📦
version 3.59.0 · 3 versions
, in arch rolling

💅 SYD — the rock solid application kernel

okay bestie, so you're reading syd, section 1 of the General Commands Manual, and honestly? This one's a whole vibe. Buckle up 🎀

✨ NAME ✨

syd — Rock solid application kernel. That's it, that's the name, and it ate. 👑

✨ SYNOPSIS ✨

syd [-acefhlmpqtxEPV] [--] {command [arg...]}

syd --api

syd --check

syd --el

syd --sh

🌸 DESCRIPTION 🌸

Okay so picture this: Syd is a utility that uses the seccomp(2) system call to sandbox processes on Linux systems version 5.19 or later. It gives you per-syscall control over a process's filesystem and network access, and the best part? no root privileges required. none. zero. nope. 💅

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 — literally embodying the principle of providing simple, flexible, and reliable access control to Linux users. slay across the whole architecture spectrum fr fr 🌈

The core functionality of Syd revolves around restricting a process's resource access through several mechanisms — and each one is kind of iconic in its own way:

  • 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. (yes that's a lot of words but it's important, iykyk 😭)

🫶 Prerequisites, aka the vibe check

Prerequisites for Syd include a Linux kernel supporting the pidfd_getfd(2) and pidfd_send_signal(2) system calls, the 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) 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) manual page lists all hardening measures and the trace/allow_unsafe_* options to relax specific restrictions when needed. so like, if you need to loosen the reins, that's where you look 👀

✨ OPTIONS ✨

The following options are understood, bestie:

  • -h, --help — Show usage and exit. short and sweet 🎀
  • -V, --version — Show version and exit. say hi to the version number ✨
  • -C, --check — Print sandboxing support information about the current system and exit. a lil report card for your kernel 📋
  • -v, --verbose — Increase verbosity, equivalent to incrementing log/verbose by one. more yapping, more info 🔍
  • -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. (yes -f and -l are twins, they're matching besties 🫶)
  • -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) 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) 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) 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. The syd(2) 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) manual page for more information. 🔌

🌸 ENVIRONMENT 🌸

okay so before Syd even starts judging syscalls, she’s scanning a whole little stack of env vars like a group chat she refuses to mute 💅. these are the knobs, defaults, and warnings — every single one is here, no cap.

  • SYD_IPC — sets the UNIX socket address for runtime configuration. it’s equivalent to the ipc command, see the syd(2) manual page. the ipc command has precedence over this environment variable, periodt.
  • SYD_LOG — sets the log level to emerg, alert, crit, error, warn, notice, info, or debug. pick your vibe ✨.
  • SYD_LOG_BUF_LEN — sets the syslog(2) ring buffer capacity. by default, the ring buffer is allocated on the stack with 256k size. setting this variable makes Syd allocate the ring buffer on the heap with the user-specified size. the value is parsed using the parse-size crate — refer to their documentation for info on formatting, iykyk.
  • SYD_LOG_FD — sets the log file descriptor, defaults to stderr(3). 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"). no cap, that’s the whole rule 💀.
  • SYD_PDS — sets the parent-death signal with PR_SET_PDEATHSIG(2const) using a signal name or number.
  • SYD_PID_FN — sets the pid filename, and 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 — sets the number of core syscall handler threads, defaults to the number of CPUs. the number must be at least 1.
  • SYD_NPROC_MAX — sets the number of maximum syscall handler threads, defaults to usize::MAX. the number must be greater than SYD_NPROC.
  • SYD_CHDIR — changes the current working directory to a safe directory at startup. this is implied if no optional arguments are given.
  • SYD_COMPAT_SOCKET — allows the legacy socketcall(2) 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 — picks 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 — exports secure computing rules with the given format, equivalent to the -E option.
  • SYD_SKIP_SCMP — skips seccomp(2) confinement of per-Syd threads. this is unsafe and should only be used for profiling. Syd honours the RUST_BACKTRACE environment variable when this is set. this is ignored unless Syd is built with the trusted Cargo feature.
  • SYD_SKIP_NAME — skips 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-disables 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 — forces the RESOLVE_NO_SYMLINKS resolve flag at the open(2) boundary. equivalent to trace/force_no_symlinks:1.
  • SYD_FORCE_NO_MAGICLINKS — forces the RESOLVE_NO_MAGICLINKS resolve flag at the open(2) boundary. equivalent to trace/force_no_magiclinks:1.
  • SYD_FORCE_NO_XDEV — forces the RESOLVE_NO_XDEV resolve flag at the open(2) boundary. equivalent to trace/force_no_xdev:1.
  • SYD_FORCE_CLOEXEC — forces close-on-exec for file descriptors. equivalent to trace/force_cloexec:1.
  • SYD_FORCE_RAND_FD — uses randomized file descriptors to harden against fd reuse. equivalent to trace/force_rand_fd:1. this environment variable is ignored if kcmp(2) isn’t supported.
  • SYD_FORCE_RO_OPEN — rejects creating and writing open(2) calls. equivalent to trace/force_ro_open:1.
  • SYD_FORCE_WX_OPEN — rejects creating and writing open(2) calls for executables. equivalent to trace/force_wx_open:1.
  • SYD_FORCE_LOCAL_NET — forces local networking, and rewrites all addresses to loopback for bind/connect. equivalent to trace/force_local_net:1.
  • SYD_FORCE_TTY — forces TTY output, which is pretty-printed JSON.
  • SYD_QUIET_TTY — forces quiet TTY output, which is line-oriented JSON.
  • SYD_PROXY_HOST — overrides 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 — overrides the default value of proxy/ext/port.
  • SYD_PROXY_UNIX — sets the default value for proxy/ext/unix, which overrides proxy/ext/host.
  • SYD_QUICK_BOOT — enables quick boot mode, and 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) or syd-oci(1), as Exherbo Linux does during cave-generate-metadata(1). this is ignored unless Syd is built with the trusted Cargo feature.
quick boot removes a layer of defense against some container breaks! like… bestie, read that twice before you turn it on 😭.
  • SYD_RLIMIT_AS — sets the default value for rlimit/as.
  • SYD_RLIMIT_CORE — sets the default value for rlimit/core.
  • SYD_RLIMIT_DATA — sets the default value for rlimit/data.
  • SYD_RLIMIT_FSIZE — sets the default value for rlimit/fsize.
  • SYD_RLIMIT_MEMLOCK — sets the default value for rlimit/memlock.
  • SYD_RLIMIT_NICE — sets the default value for rlimit/nice.
  • SYD_RLIMIT_NOFILE — sets the default value for rlimit/nofile.
  • SYD_RLIMIT_NPROC — sets the default value for rlimit/nproc.
  • SYD_RLIMIT_RTPRIO — sets the default value for rlimit/rtprio.
  • SYD_RLIMIT_RTTIME — sets the default value for rlimit/rttime.
  • SYD_RLIMIT_SIGPENDING — sets the default value for rlimit/sigpending.
  • SYD_RLIMIT_STACK — sets the default value for rlimit/stack.
  • SYD_TMOUT — sets the default value for timeout.
  • SYD_NO_CROSS_MEMORY_ATTACH — disables cross memory attach and uses proc_pid_mem(5) 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) automatically if process_vm_readv(2) or process_vm_writev(2) 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 — overrides uname(2) to get the host Linux kernel version used for feature detection. Syd reports the major and minor kernel version at the uname(2) 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 — overrides the sandbox/lpath option for the paludis profile, defaults to off.
  • SYD_PALUDIS_NPATH — overrides the sandbox/npath option for the paludis profile, defaults to off.
  • SYD_PALUDIS_LIST — overrides the sandbox/list option for the paludis profile, defaults to off.
  • SYD_PALUDIS_WALK — overrides the sandbox/walk option for the paludis profile, defaults to off.
  • SYD_PALUDIS_IOCTL — overrides the sandbox/ioctl option for the paludis profile, defaults to off.
  • SYD_PALUDIS_PASSFD — overrides the sandbox/passfd option for the paludis profile, defaults to off.
  • SYD_USER_LPATH — overrides the sandbox/lpath option for the user profile, defaults to on.

💜 LOGGING 💜

okay so there are literally eight log levels, and they go in descending priority like this: emerg, alert, crit, error, warn, notice, info, and debug. you can set the log level with the SYD_LOG environment variable, bestie. 📝

logs go to stderr(3) unless you specify a file descriptor with the SYD_LOG_FD environment variable. and Syd logs in JSON lines — very structured, very demure, very cutesy. 🎀

below is a list of the commonly used log keys with their descriptions, and yes we're going through all of them because every single one matters, no skips:

  • id — the sandbox ID, as 64 lowercase hexadecimal characters ✨
  • ctx — the context of the log entry, e.g. access, safesetid, segvguard etc.
  • cap — the sandbox capability
  • act — the sandbox action, one of: allow, warn, deny, panic, stop, abort, kill or exit
  • pid — the process ID
  • path — the path argument of the syscall
  • addr — the network address argument of the syscall, e.g. 127.0.0.1!22
  • unix — the UNIX socket address argument of the syscall
  • ipv — the IP version of the network address in the addr field (4 or 6)
  • abs — true if the socket address in the unix field is an abstract UNIX socket
  • sys — the name of the syscall
  • arch — the architecture of the syscall
  • args — the arguments of the syscall
  • cmd — the process name, or the command line if the log output is a TTY or the log feature is enabled
  • cwd — the current working directory of the sandbox process
  • uid — the user ID
  • time — the timestamp in an ISO8601-compatible format, currently YYYYMMDDThhmmssZ
    • heads up: the time format may change, but it will always remain ISO8601-compatible 🕰️
    • and formatting errors fallback to printing the timestamp as an integer, so it's never just vibes and silence
  • err — error information 💀
  • msg — informational messages
  • tip — educational messages on how to configure Syd (we love a helpful icon 🧚)

🌈 EXIT STATUS 🌈

Syd exits with the same exit code as the sandbox process. like, it's not doing its own thing, it's matching energy. 💅

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 errno(3) indicating the error condition.

and the special ones, memorize these:

  • 101 — Syd exits with this on panics 😭
  • 102 — Syd exits with this on fatal allocator errors
  • 124 — Syd exits with this if the sandbox timeout is exceeded ⏰

🦋 SEE ALSO 🦋

the whole friend group, fr fr:

syd(2), syd(5), syd(7), syd-lock(1), syd-ls(1), syd-mdwe(1), syd-ring(1), sydtutorial(7)

and the homepages, because we support our faves:

👑 AUTHORS 👑

maintained by Ali Polatel — icon behavior, honestly. 🫶

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.

and if you wanna chat about it: #sydbox on Libera Chat, or #sydbox:mailstation.de on Matrix. come say hi, we don't bite 🌸

okay that's the whole page bestie, you're officially Syd-literate, go forth and sandbox responsibly 💖✨

this edition of the page is dated 2026-09-01 and it's the SYD(1) manual — go off, manual page, slay 💅

📦 where this page comes from