SYSTEMD.NSPAWN(5)

📦
version 261.3 · 15 versions
, in ubuntu stonking

💅 systemd.nspawn(5) — the manual, but make it make sense ✨

okay bestie, this is systemd.nspawn — aka the Container settings page 🎀 (yes that's the official manual name, we're just vibing with it)

✨ SYNOPSIS ✨

/etc/systemd/nspawn/machine.nspawn
/run/systemd/nspawn/machine.nspawn
/var/lib/machines/machine.nspawn

three paths, three vibes, all of them absolutely slaying the same file name pattern 🫶

🌸 DESCRIPTION 🌸

So. An nspawn container settings file — you'll clock it by the .nspawn suffix ✨ — is literally just runtime configuration for a local container, and it's what systemd-nspawn(1) reads. Iconic.

Files of this type are named after the containers they define settings for — so the file name isn't random, it's the container's whole identity, main character energy 👑.

They're optional bestie, no cap. You only need one when your container's execution environment needs to differ from the defaults. That's it. That's the requirement 😌

What's inside? Mostly settings that could also be set on the systemd-nspawn command line — but putting them in the file makes it way easier to persistently attach specific settings to specific containers. Because typing the same flags forever is not the move, and we don't do that here 💀

The syntax is inspired by .desktop files — same family as the other configuration files the systemd project supports. And for the full overview, go read systemd.syntax(7) 💖

🦋 .NSPAWN FILE DISCOVERY 🦋

okay so this is the part where it goes looking for your file, and the search order is VERY important, so pay attention 🔍

Files are searched for by appending the .nspawn suffix to the machine name of the container — the machine name is specified with the --machine= switch of systemd-nspawn, or derived from the directory or image file name. iykyk 🧚

Here's the whole little detective story:

  1. First it looks in /etc/systemd/nspawn/ and /run/systemd/nspawn/ 👀
  2. If found there — the settings are read and all of them take full effect (though they may still be overridden by corresponding command line arguments, sneaky 🫣)
  3. Otherwise — it then searches next to the image file, or in the immediate parent of the root directory of the container 🌈
  4. If found there — only a subset of the settings will take effect. Harsh? Maybe. Necessary? Absolutely 💅
⚠️ Okay this next bit is the important part, don't scroll past it: all settings that possibly elevate privileges or grant additional access to resources of the host (like files or directories — yes, those) are ignored when the file is found in that second location. Which options this applies to is documented below, so keep reading.

Now for the trust tea ☕: persistent settings files created and maintained by the administrator (and thus trusted) should be placed in /etc/systemd/nspawn/. Automatically downloaded (and thus potentially untrusted) settings files go in /var/lib/machines/ instead — next to the container images — where their security impact is limited. Safe little corner, we love that for them 🎀

And if you're trying to add privileged settings to .nspawn files you acquired from the image vendor? The recommended move is to copy the settings files into /etc/systemd/nspawn/ and edit them there, so that the privileged options become available. Move it to the trusted neighbourhood and then unlock the good stuff 🔥

The precise algorithm for how those files are searched and interpreted can be configured with systemd-nspawn's --settings= switch — check systemd-nspawn(1) for the details, bestie 📖

...and that's part one, stay tuned because there is SO much more 💜

✨ [Exec] SECTION OPTIONS ✨

okay so bestie, settings files may totally include an [Exec] section, and this is where all the "what actually runs and how" energy lives 💅 it carries various execution parameters:

  • Boot= — takes a boolean argument, and it defaults to off. flip it on and systemd-nspawn will automatically go hunt for an init executable and invoke it, no cap 🔍 in that case, whatever you put in Parameters= gets passed as additional arguments to that init process. this is literally the --boot switch on the systemd-nspawn command line. ⚠️ heads up: this option may not be combined with ProcessTwo=yes. and fun fact, this option is specified by default in the systemd-nspawn@.service template unit 🎀

Added in version 226.

  • Ephemeral= — takes a boolean argument, defaults to off. if enabled, the container runs with a temporary snapshot of its file system that gets yeeted immediately when the container terminates 🫧 it's the equivalent of the --ephemeral command line switch. see systemd-nspawn(1) for the deets on which specific options are supported.

Added in version 240.

  • ProcessTwo= — takes a boolean argument, defaults to off. if enabled, the program you specified runs as PID 2, and a lil stub init process runs as PID 1 🧚 this setting corresponds to the --as-pid2 switch on the systemd-nspawn command line. ⚠️ may not be combined with Boot=yes.

Added in version 229.

  • Parameters= — takes a whitespace-separated list of arguments. single ("'") and double (""") quotes may be used around arguments that have whitespace in them. this is either a command line, starting with the binary name to execute, or — if Boot= is enabled — the list of arguments to pass along to the init process. it corresponds to the command line parameters passed on the systemd-nspawn command line ✨
📌 note: Boot=no, Parameters=a b "c c" is the same as systemd-nspawn a b "c c", and Boot=yes, Parameters=b 'c c' is the same as systemd-nspawn --boot b 'c c'. iykyk 💖

Added in version 226.

  • Environment= — takes an environment variable assignment made of a key and a value, separated by =. it sets an environment variable for the main process invoked in the container 🌸 this setting may be used multiple times to set multiple environment variables, so go off. corresponds to the --setenv= command line switch.

Added in version 226.

  • User= — takes a UNIX user name. specifies the user name to invoke the container's main process as. this user has to be known in the container's user database, no pretending 👑 corresponds to the --user= command line switch.

Added in version 226.

  • WorkingDirectory= — selects the working directory for the process invoked in the container. expects an absolute path in the container's file system namespace. corresponds to the --chdir= command line switch 📂

Added in version 229.

  • PivotRoot= — selects a directory to pivot to / inside the container when starting up. takes a single path, or a pair of two paths separated by a colon. both paths must be absolute, and they're resolved in the container's file system namespace. corresponds to the --pivot-root= command line switch 🌀

Added in version 233.

  • Capability=, DropCapability= — take a space-separated list of Linux process capabilities (peep capabilities(7) for details). Capability= specifies extra capabilities to pass on top of the default set, and DropCapability= specifies capabilities to drop from that default set ✂️ these settings correspond to the --capability= and --drop-capability= command line switches. note that Capability= is a privileged setting, and it only takes effect in .nspawn files in /etc/systemd/nspawn/ and /run/system/nspawn/ (see above). DropCapability=, on the other hand, takes effect in all cases, periodt. if you pass the special value "all", all capabilities are retained (or dropped).

these settings change the bounding set of capabilities, which also limits the ambient capabilities as given with AmbientCapability= 🔥

Added in version 226.

  • AmbientCapability= — takes a space-separated list of Linux process capabilities (see capabilities(7)). this setting specifies capabilities that will be passed to the started program in the inheritable and ambient capability sets. this will grant these capabilities to this process 🎁 corresponds to the --ambient-capability= command line switch.

the value "all" is not supported for this setting 🙅

the setting of AmbientCapability= must be covered by the bounding set settings that were established by Capability= and DropCapability=.

also note that AmbientCapability= is a privileged setting (see above) 👀

Added in version 248.

  • NoNewPrivileges= — takes a boolean argument that controls the PR_SET_NO_NEW_PRIVS flag for the container payload. equivalent to the --no-new-privileges= command line switch. see systemd-nspawn(1) for details 🦋

Added in version 239.

  • KillSignal= — specify the process signal to send to the container's PID 1 when nspawn itself receives SIGTERM, so we can trigger an orderly shutdown of the container 🛑 defaults to SIGRTMIN+3 if Boot= is used (on systemd-compatible init systems SIGRTMIN+3 triggers an orderly shutdown, iconic). for a list of valid signals, see signal(7).

Added in version 230.

  • Personality= — configures the kernel personality for the container. equivalent to the --personality= switch 🎭

Added in version 226.

  • MachineID= — configures the 128-bit machine ID (UUID) to pass to the container. equivalent to the --uuid= command line switch. this option is privileged (see above) 🔐

Added in version 226.

  • PrivateUsers= — configures support for usernamespacing. equivalent to the --private-users= command line switch, and it takes the same options. this option is privileged (see above). it's also the default if the systemd-nspawn@.service template unit file is used 💫

Added in version 230.

  • PrivateUsersDelegate= — takes a non-negative integer. configures delegation of additional 64K UID/GID ranges into the container's user namespace for use by nested containers 🪆 when set to a value greater than zero, the systemd-nsresourced.service(8) varlink socket will be bind-mounted into the container so that processes inside it can allocate further user namespaces from the delegated ranges. equivalent to the --private-users-delegate= command line switch. requires PrivateUsers=managed. defaults to 0. see systemd-nspawn(1) for details.

Added in version 260.

  • NotifyReady= — configures support for notifications coming from the container's init process 📣 equivalent to the --notify-ready= command line switch, and takes the same parameters. see systemd-nspawn(1) for details about the specific options supported.

Added in version 231.

  • SystemCallFilter= — configures the system call filter applied to containers. equivalent to the --system-call-filter= command line switch, and takes the same list parameter. see systemd-nspawn(1) for details 🧿

Added in version 235.

  • RestrictAddressFamilies= — restricts the socket address families accessible to the container. equivalent to the --restrict-address-families= command line switch, and takes the same list parameter. see systemd-nspawn(1) for details 🔒

Added in version 261.

  • LimitCPU=, LimitFSIZE=, LimitDATA=, LimitSTACK=, LimitCORE=, LimitRSS=, LimitNOFILE=, LimitAS=, LimitNPROC=, LimitMEMLOCK=, LimitLOCKS=, LimitSIGPENDING=, LimitMSGQUEUE=, LimitNICE=, LimitRTPRIO=, LimitRTTIME= — configures various types of resource limits applied to containers. this is equivalent to the --rlimit= command line switch, and takes the same arguments. see systemd-nspawn(1) for details ⚖️

Added in version 239.

  • OOMScoreAdjust= — configures the OOM score adjustment value. equivalent to the --oom-score-adjust= command line switch, and takes the same argument. see systemd-nspawn(1) for details 💀

Added in version 239.

  • CPUAffinity= — configures the CPU affinity. equivalent to the --cpu-affinity= command line switch, and takes the same argument. see systemd-nspawn(1) for details 🧠

Added in version 239.

  • Hostname= — configures the kernel hostname set for the container. equivalent to the --hostname= command line switch, and takes the same argument. see systemd-nspawn(1) for details 🏷️

Added in version 239.

  • ResolvConf= — configures how /etc/resolv.conf in the container shall be handled. equivalent to the --resolv-conf= command line switch, and takes the same argument. see systemd-nspawn(1) for details 🌐

Added in version 239.

  • Timezone= — configures how /etc/localtime in the container shall be handled. equivalent to the --timezone= command line switch, and takes the same argument. see systemd-nspawn(1) for details 🕰️

Added in version 239.

  • LinkJournal= — configures how to link host and container journal setups. equivalent to the --link-journal= command line switch, and takes the same parameter. see systemd-nspawn(1) for details 📓

Added in version 239.

  • SuppressSync= — configures whether to suppress disk synchronization for the container payload. equivalent to the --suppress-sync= command line switch, and takes the same parameter. see systemd-nspawn(1) for details 💾

Added in version 250.

💖 [FILES] SECTION OPTIONS 💖

okay so your settings file can also have a [Files] section, and this one is literally the whole file-system vibe check for your container — all the parameters that configure its file system live here 🫶

  • ReadOnly= — takes a boolean, defaults to off. flip it on and your container runs with a read-only file system (no cap, nothing's getting written 💀). this one matches the --read-only command line switch.

added in version 226 ✨

  • Volatile= — takes a boolean, or the special value "state". this controls whether the container runs with volatile state and/or configuration. it's the same thing as --volatile=, so peek at systemd-nspawn(1) for the deets on which values are supported.

added in version 226 ✨

  • Bind=, BindReadOnly= — adds a bind mount from the host into the container, slay. takes a single path, a pair of two paths separated by a colon, or a triplet of two paths plus an option string separated by colons. use it multiple times to configure multiple bind mounts, go off. equivalent to the command line switches --bind= and --bind-ro= — systemd-nspawn(1) has the specifics. heads up: this setting is privileged (see above 👀).

added in version 226 ✨

  • BindUser= — binds a user from the host into the container. equivalent to the command line switch --bind-user=, see systemd-nspawn(1) for what it actually supports. also privileged (see above 👀).

added in version 249 ✨

  • BindUserShell= — when you use it with BindUser, this specifies the shell that gets included in the user record of users bound from the host into the container. equivalent to --bind-user-shell=, check systemd-nspawn(1). privileged again (see above 👀).

added in version 258 ✨

  • TemporaryFileSystem= — adds a "tmpfs" mount to the container 🎀 takes a path, or a pair of path and option string separated by a colon. multiple uses = multiple "tmpfs" mounts. equivalent to the --tmpfs= command line switch, details in systemd-nspawn(1). privileged (see above 👀).

added in version 226 ✨

  • Inaccessible= — masks the file or directory you name in the container by over-mounting it with an empty file node of the same type with the most restrictive access mode. takes a file system path as its argument. use it multiple times to mask multiple files or directories. equivalent to the --inaccessible= command line switch, see systemd-nspawn(1) for the specifics. privileged (see above 👀).

added in version 242 ✨

  • Overlay=, OverlayReadOnly= — adds an overlay mount point, obsessed. takes a colon-separated list of paths. multiple uses = multiple overlay mounts. equivalent to the --overlay= and --overlay-ro= command line switches — systemd-nspawn(1) has the fine print. privileged (see above 👀).

added in version 233 ✨

  • PrivateUsersOwnership= — configures whether the ownership of the files and directories in the container tree shall be adjusted to the UID/GID range used, if necessary and user namespacing is enabled. equivalent to the --private-users-ownership= command line switch. privileged (see above 👀).

added in version 249 ✨

🌐 [NETWORK] SECTION OPTIONS 🌐

next up, the [Network] section — every parameter that configures how your container connects to the world 🦋

  • Private= — takes a boolean, defaults to off. enable it and the container runs in its own network namespace, not sharing network interfaces and configuration with the host. matches the --private-network command line switch.

added in version 226 ✨

  • NamespacePath= — takes the path to a file representing a kernel network namespace that the container shall run in. the path should refer to a (possibly bind-mounted) network namespace file, as exposed by the kernel below /proc/$PID/ns/net. this makes the container enter the given network namespace. one classic use case is handing it a network namespace under /run/netns created by ip-netns(8) — for example, NamespacePath=/run/netns/foo. ⚠️ note that this option cannot be used together with other network-related options, such as Private= or Interface=. corresponds to the --network-namespace-path command line switch.

added in version 259 ✨

  • VirtualEthernet= — takes a boolean. configures whether to create a virtual Ethernet connection ("veth") between host and the container. this setting implies Private=yes. corresponds to the --network-veth command line switch. and fun fact: this option is the default if the systemd-nspawn@.service template unit file is used 👑

added in version 226 ✨

  • VirtualEthernetExtra= — takes a colon-separated pair of interface names, and configures an additional virtual Ethernet connection ("veth") between host and container. the first specified name is the interface name on the host, the second is the interface name in the container. the second one may be omitted, in which case it's set to the same name as the host side interface. this setting implies Private=yes. corresponds to the --network-veth-extra= command line switch, and may be used multiple times. it's independent of VirtualEthernet=. ⚠️ note that this option is unrelated to the Bridge= setting below, so any connections created this way are not automatically added to any bridge device on the host side. privileged (see above 👀).

added in version 228 ✨

  • Interface= — takes a space-separated list of interfaces to add to the container. the interface object is defined either by a single interface name referencing the name on the host, or a colon-separated pair of interfaces — in which case the first references the name on the host and the second the name in the container. corresponds to the --network-interface= command line switch and implies Private=yes. privileged (see above 👀).

added in version 226 ✨

  • MACVLAN=, IPVLAN= — take a space-separated list of interfaces to add MACVLAN or IPVLAN interfaces to, which are then added to the container. the interface object is defined either by a single interface name referencing the name on the host, or a colon-separated pair of interfaces, where the first references the name on the host and the second the name in the container. these correspond to the --network-macvlan= and --network-ipvlan= command line switches and imply Private=yes. both privileged (see above 👀).

added in version 226 ✨

  • Bridge= — takes an interface name. this setting implies VirtualEthernet=yes and Private=yes, and has the effect that the host side of the created virtual Ethernet link is connected to the specified bridge interface 🫶 corresponds to the --network-bridge= command line switch. privileged (see above 👀).

added in version 226 ✨

  • Zone= — takes a network zone name. this setting implies VirtualEthernet=yes and Private=yes, and has the effect that the host side of the created virtual Ethernet link is connected to an automatically managed bridge interface named after the passed argument, prefixed with "vz-". corresponds to the --network-zone= command line switch. privileged (see above 👀).

added in version 230 ✨

  • Port= — exposes a TCP or UDP port of the container on the host 👑 corresponds to the --port= command line switch — see systemd-nspawn(1) for the precise syntax of the argument this option takes. privileged (see above 👀).

added in version 226 ✨

🦋 SEE ALSO 🦋

and that's a wrap bestie, you literally ate this entire page 💅 the whole thing is from systemd 261.3, filed under SYSTEMD.NSPAWN(5) — go forth and spawn responsibly, ily, mwah 🎀✨

📦 where this page comes from