path: root/upstream/fedora-40/man5/systemd.nspawn.5

'\" t
.TH "SYSTEMD\&.NSPAWN" "5" "" "systemd 255" "systemd.nspawn"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd.nspawn \- Container settings
.SH "SYNOPSIS"
.PP
/etc/systemd/nspawn/\fImachine\fR\&.nspawn
.PP
/run/systemd/nspawn/\fImachine\fR\&.nspawn
.PP
/var/lib/machines/\fImachine\fR\&.nspawn
.SH "DESCRIPTION"
.PP
An nspawn container settings file (suffix
\&.nspawn) contains runtime configuration for a local container, and is used by
\fBsystemd-nspawn\fR(1)\&. Files of this type are named after the containers they define settings for\&. They are optional, and only required for containers whose execution environment shall differ from the defaults\&. Files of this type mostly contain settings that may also be set on the
\fBsystemd\-nspawn\fR
command line, and make it easier to persistently attach specific settings to specific containers\&. The syntax of these files is inspired by
\&.desktop
files, similarly to other configuration files supported by the systemd project\&. See
\fBsystemd.syntax\fR(7)
for an overview\&.
.SH "\&.NSPAWN FILE DISCOVERY"
.PP
Files are searched for by appending the
\&.nspawn
suffix to the machine name of the container, as specified with the
\fB\-\-machine=\fR
switch of
\fBsystemd\-nspawn\fR, or derived from the directory or image file name\&. This file is first searched for in
/etc/systemd/nspawn/
and
/run/systemd/nspawn/\&. If found there, the settings are read and all of them take full effect (but may still be overridden by corresponding command line arguments)\&. Otherwise, the file will then be searched for next to the image file or in the immediate parent of the root directory of the container\&. If the file is found there, only a subset of the settings will take effect however\&. All settings that possibly elevate privileges or grant additional access to resources of the host (such as files or directories) are ignored\&. To which options this applies is documented below\&.
.PP
Persistent settings files created and maintained by the administrator (and thus trusted) should be placed in
/etc/systemd/nspawn/, while automatically downloaded (and thus potentially untrusted) settings files are placed in
/var/lib/machines/
instead (next to the container images), where their security impact is limited\&. In order to add privileged settings to
\&.nspawn
files acquired from the image vendor, it is recommended to copy the settings files into
/etc/systemd/nspawn/
and edit them there, so that the privileged options become available\&. The precise algorithm for how the files are searched and interpreted may be configured with
\fBsystemd\-nspawn\fR\*(Aqs
\fB\-\-settings=\fR
switch, see
\fBsystemd-nspawn\fR(1)
for details\&.
.SH "[EXEC] SECTION OPTIONS"
.PP
Settings files may include an [Exec] section, which carries various execution parameters:
.PP
\fIBoot=\fR
.RS 4
Takes a boolean argument, which defaults to off\&. If enabled,
\fBsystemd\-nspawn\fR
will automatically search for an
init
executable and invoke it\&. In this case, the specified parameters using
\fIParameters=\fR
are passed as additional arguments to the
init
process\&. This setting corresponds to the
\fB\-\-boot\fR
switch on the
\fBsystemd\-nspawn\fR
command line\&. This option may not be combined with
\fIProcessTwo=yes\fR\&. This option is specified by default in the
systemd\-nspawn@\&.service
template unit\&.
.sp
Added in version 226\&.
.RE
.PP
\fIEphemeral=\fR
.RS 4
Takes a boolean argument, which defaults to off, If enabled, the container is run with a temporary snapshot of its file system that is removed immediately when the container terminates\&. This is equivalent to the
\fB\-\-ephemeral\fR
command line switch\&. See
\fBsystemd-nspawn\fR(1)
for details about the specific options supported\&.
.sp
Added in version 240\&.
.RE
.PP
\fIProcessTwo=\fR
.RS 4
Takes a boolean argument, which defaults to off\&. If enabled, the specified program is run as PID 2\&. A stub init process is run as PID 1\&. This setting corresponds to the
\fB\-\-as\-pid2\fR
switch on the
\fBsystemd\-nspawn\fR
command line\&. This option may not be combined with
\fIBoot=yes\fR\&.
.sp
Added in version 229\&.
.RE
.PP
\fIParameters=\fR
.RS 4
Takes a whitespace\-separated list of arguments\&. Single ("\*(Aq") and double (""") quotes may be used around arguments with whitespace\&. This is either a command line, beginning with the binary name to execute, or \(en if
\fIBoot=\fR
is enabled \(en the list of arguments to pass to the init process\&. This setting corresponds to the command line parameters passed on the
\fBsystemd\-nspawn\fR
command line\&.
.sp
Note:
\fBBoot=no\fR,
\fBParameters=a b "c c"\fR
is the same as
\fBsystemd\-nspawn a b "c c"\fR, and
\fBBoot=yes\fR,
\fBParameters=b \*(Aqc c\*(Aq\fR
is the same as
\fBsystemd\-nspawn \-\-boot b \*(Aqc c\*(Aq\fR\&.
.sp
Added in version 226\&.
.RE
.PP
\fIEnvironment=\fR
.RS 4
Takes an environment variable assignment consisting of key and value, separated by
"="\&. Sets an environment variable for the main process invoked in the container\&. This setting may be used multiple times to set multiple environment variables\&. It corresponds to the
\fB\-\-setenv=\fR
command line switch\&.
.sp
Added in version 226\&.
.RE
.PP
\fIUser=\fR
.RS 4
Takes a UNIX user name\&. Specifies the user name to invoke the main process of the container as\&. This user must be known in the container\*(Aqs user database\&. This corresponds to the
\fB\-\-user=\fR
command line switch\&.
.sp
Added in version 226\&.
.RE
.PP
\fIWorkingDirectory=\fR
.RS 4
Selects the working directory for the process invoked in the container\&. Expects an absolute path in the container\*(Aqs file system namespace\&. This corresponds to the
\fB\-\-chdir=\fR
command line switch\&.
.sp
Added in version 229\&.
.RE
.PP
\fIPivotRoot=\fR
.RS 4
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 are resolved in the container\*(Aqs file system namespace\&. This corresponds to the
\fB\-\-pivot\-root=\fR
command line switch\&.
.sp
Added in version 233\&.
.RE
.PP
\fICapability=\fR, \fIDropCapability=\fR
.RS 4
Takes a space\-separated list of Linux process capabilities (see
\fBcapabilities\fR(7)
for details)\&. The
\fICapability=\fR
setting specifies additional capabilities to pass on top of the default set of capabilities\&. The
\fIDropCapability=\fR
setting specifies capabilities to drop from the default set\&. These settings correspond to the
\fB\-\-capability=\fR
and
\fB\-\-drop\-capability=\fR
command line switches\&. Note that
\fICapability=\fR
is a privileged setting, and only takes effect in
\&.nspawn
files in
/etc/systemd/nspawn/
and
/run/system/nspawn/
(see above)\&. On the other hand,
\fIDropCapability=\fR
takes effect in all cases\&. If the special value
"all"
is passed, all capabilities are retained (or dropped)\&.
.sp
These settings change the bounding set of capabilities which also limits the ambient capabilities as given with the
\fIAmbientCapability=\fR\&.
.sp
Added in version 226\&.
.RE
.PP
\fIAmbientCapability=\fR
.RS 4
Takes a space\-separated list of Linux process capabilities (see
\fBcapabilities\fR(7)
for details)\&. The
\fIAmbientCapability=\fR
setting specifies capabilities which will be passed to the started program in the inheritable and ambient capability sets\&. This will grant these capabilities to this process\&. This setting correspond to the
\fB\-\-ambient\-capability=\fR
command line switch\&.
.sp
The value
"all"
is not supported for this setting\&.
.sp
The setting of
\fIAmbientCapability=\fR
must be covered by the bounding set settings which were established by
\fICapability=\fR
and
\fIDropCapability=\fR\&.
.sp
Note that
\fIAmbientCapability=\fR
is a privileged setting (see above)\&.
.sp
Added in version 248\&.
.RE
.PP
\fINoNewPrivileges=\fR
.RS 4
Takes a boolean argument that controls the
\fBPR_SET_NO_NEW_PRIVS\fR
flag for the container payload\&. This is equivalent to the
\fB\-\-no\-new\-privileges=\fR
command line switch\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 239\&.
.RE
.PP
\fIKillSignal=\fR
.RS 4
Specify the process signal to send to the container\*(Aqs PID 1 when nspawn itself receives SIGTERM, in order to trigger an orderly shutdown of the container\&. Defaults to SIGRTMIN+3 if
\fBBoot=\fR
is used (on systemd\-compatible init systems SIGRTMIN+3 triggers an orderly shutdown)\&. For a list of valid signals, see
\fBsignal\fR(7)\&.
.sp
Added in version 230\&.
.RE
.PP
\fIPersonality=\fR
.RS 4
Configures the kernel personality for the container\&. This is equivalent to the
\fB\-\-personality=\fR
switch\&.
.sp
Added in version 226\&.
.RE
.PP
\fIMachineID=\fR
.RS 4
Configures the 128\-bit machine ID (UUID) to pass to the container\&. This is equivalent to the
\fB\-\-uuid=\fR
command line switch\&. This option is privileged (see above)\&.
.sp
Added in version 226\&.
.RE
.PP
\fIPrivateUsers=\fR
.RS 4
Configures support for usernamespacing\&. This is equivalent to the
\fB\-\-private\-users=\fR
command line switch, and takes the same options\&. This option is privileged (see above)\&. This option is the default if the
systemd\-nspawn@\&.service
template unit file is used\&.
.sp
Added in version 230\&.
.RE
.PP
\fINotifyReady=\fR
.RS 4
Configures support for notifications from the container\*(Aqs init process\&. This is equivalent to the
\fB\-\-notify\-ready=\fR
command line switch, and takes the same parameters\&. See
\fBsystemd-nspawn\fR(1)
for details about the specific options supported\&.
.sp
Added in version 231\&.
.RE
.PP
\fISystemCallFilter=\fR
.RS 4
Configures the system call filter applied to containers\&. This is equivalent to the
\fB\-\-system\-call\-filter=\fR
command line switch, and takes the same list parameter\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 235\&.
.RE
.PP
\fILimitCPU=\fR, \fILimitFSIZE=\fR, \fILimitDATA=\fR, \fILimitSTACK=\fR, \fILimitCORE=\fR, \fILimitRSS=\fR, \fILimitNOFILE=\fR, \fILimitAS=\fR, \fILimitNPROC=\fR, \fILimitMEMLOCK=\fR, \fILimitLOCKS=\fR, \fILimitSIGPENDING=\fR, \fILimitMSGQUEUE=\fR, \fILimitNICE=\fR, \fILimitRTPRIO=\fR, \fILimitRTTIME=\fR
.RS 4
Configures various types of resource limits applied to containers\&. This is equivalent to the
\fB\-\-rlimit=\fR
command line switch, and takes the same arguments\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 239\&.
.RE
.PP
\fIOOMScoreAdjust=\fR
.RS 4
Configures the OOM score adjustment value\&. This is equivalent to the
\fB\-\-oom\-score\-adjust=\fR
command line switch, and takes the same argument\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 239\&.
.RE
.PP
\fICPUAffinity=\fR
.RS 4
Configures the CPU affinity\&. This is equivalent to the
\fB\-\-cpu\-affinity=\fR
command line switch, and takes the same argument\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 239\&.
.RE
.PP
\fIHostname=\fR
.RS 4
Configures the kernel hostname set for the container\&. This is equivalent to the
\fB\-\-hostname=\fR
command line switch, and takes the same argument\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 239\&.
.RE
.PP
\fIResolvConf=\fR
.RS 4
Configures how
/etc/resolv\&.conf
in the container shall be handled\&. This is equivalent to the
\fB\-\-resolv\-conf=\fR
command line switch, and takes the same argument\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 239\&.
.RE
.PP
\fITimezone=\fR
.RS 4
Configures how
/etc/localtime
in the container shall be handled\&. This is equivalent to the
\fB\-\-timezone=\fR
command line switch, and takes the same argument\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 239\&.
.RE
.PP
\fILinkJournal=\fR
.RS 4
Configures how to link host and container journal setups\&. This is equivalent to the
\fB\-\-link\-journal=\fR
command line switch, and takes the same parameter\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 239\&.
.RE
.PP
\fISuppressSync=\fR
.RS 4
Configures whether to suppress disk synchronization for the container payload\&. This is equivalent to the
\fB\-\-suppress\-sync=\fR
command line switch, and takes the same parameter\&. See
\fBsystemd-nspawn\fR(1)
for details\&.
.sp
Added in version 250\&.
.RE
.SH "[FILES] SECTION OPTIONS"
.PP
Settings files may include a [Files] section, which carries various parameters configuring the file system of the container:
.PP
\fIReadOnly=\fR
.RS 4
Takes a boolean argument, which defaults to off\&. If specified, the container will be run with a read\-only file system\&. This setting corresponds to the
\fB\-\-read\-only\fR
command line switch\&.
.sp
Added in version 226\&.
.RE
.PP
\fIVolatile=\fR
.RS 4
Takes a boolean argument, or the special value
"state"\&. This configures whether to run the container with volatile state and/or configuration\&. This option is equivalent to
\fB\-\-volatile=\fR, see
\fBsystemd-nspawn\fR(1)
for details about the specific options supported\&.
.sp
Added in version 226\&.
.RE
.PP
\fIBind=\fR, \fIBindReadOnly=\fR
.RS 4
Adds a bind mount from the host into the container\&. 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\&. This option may be used multiple times to configure multiple bind mounts\&. This option is equivalent to the command line switches
\fB\-\-bind=\fR
and
\fB\-\-bind\-ro=\fR, see
\fBsystemd-nspawn\fR(1)
for details about the specific options supported\&. This setting is privileged (see above)\&.
.sp
Added in version 226\&.
.RE
.PP
\fIBindUser=\fR
.RS 4
Binds a user from the host into the container\&. This option is equivalent to the command line switch
\fB\-\-bind\-user=\fR, see
\fBsystemd-nspawn\fR(1)
for details about the specific options supported\&. This setting is privileged (see above)\&.
.sp
Added in version 249\&.
.RE
.PP
\fITemporaryFileSystem=\fR
.RS 4
Adds a
"tmpfs"
mount to the container\&. Takes a path or a pair of path and option string, separated by a colon\&. This option may be used multiple times to configure multiple
"tmpfs"
mounts\&. This option is equivalent to the command line switch
\fB\-\-tmpfs=\fR, see
\fBsystemd-nspawn\fR(1)
for details about the specific options supported\&. This setting is privileged (see above)\&.
.sp
Added in version 226\&.
.RE
.PP
\fIInaccessible=\fR
.RS 4
Masks the specified file or directory 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 argument\&. This option may be used multiple times to mask multiple files or directories\&. This option is equivalent to the command line switch
\fB\-\-inaccessible=\fR, see
\fBsystemd-nspawn\fR(1)
for details about the specific options supported\&. This setting is privileged (see above)\&.
.sp
Added in version 242\&.
.RE
.PP
\fIOverlay=\fR, \fIOverlayReadOnly=\fR
.RS 4
Adds an overlay mount point\&. Takes a colon\-separated list of paths\&. This option may be used multiple times to configure multiple overlay mounts\&. This option is equivalent to the command line switches
\fB\-\-overlay=\fR
and
\fB\-\-overlay\-ro=\fR, see
\fBsystemd-nspawn\fR(1)
for details about the specific options supported\&. This setting is privileged (see above)\&.
.sp
Added in version 233\&.
.RE
.PP
\fIPrivateUsersOwnership=\fR
.RS 4
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\&. This is equivalent to the
\fB\-\-private\-users\-ownership=\fR
command line switch\&. This option is privileged (see above)\&.
.sp
Added in version 249\&.
.RE
.SH "[NETWORK] SECTION OPTIONS"
.PP
Settings files may include a [Network] section, which carries various parameters configuring the network connectivity of the container:
.PP
\fIPrivate=\fR
.RS 4
Takes a boolean argument, which defaults to off\&. If enabled, the container will run in its own network namespace and not share network interfaces and configuration with the host\&. This setting corresponds to the
\fB\-\-private\-network\fR
command line switch\&.
.sp
Added in version 226\&.
.RE
.PP
\fIVirtualEthernet=\fR
.RS 4
Takes a boolean argument\&. Configures whether to create a virtual Ethernet connection ("veth") between host and the container\&. This setting implies
\fIPrivate=yes\fR\&. This setting corresponds to the
\fB\-\-network\-veth\fR
command line switch\&. This option is privileged (see above)\&. This option is the default if the
systemd\-nspawn@\&.service
template unit file is used\&.
.sp
Added in version 226\&.
.RE
.PP
\fIVirtualEthernetExtra=\fR
.RS 4
Takes a colon\-separated pair of interface names\&. Configures an additional virtual Ethernet connection ("veth") between host and the container\&. The first specified name is the interface name on the host, the second the interface name in the container\&. The latter may be omitted in which case it is set to the same name as the host side interface\&. This setting implies
\fIPrivate=yes\fR\&. This setting corresponds to the
\fB\-\-network\-veth\-extra=\fR
command line switch, and may be used multiple times\&. It is independent of
\fIVirtualEthernet=\fR\&. Note that this option is unrelated to the
\fIBridge=\fR
setting below, and thus any connections created this way are not automatically added to any bridge device on the host side\&. This option is privileged (see above)\&.
.sp
Added in version 228\&.
.RE
.PP
\fIInterface=\fR
.RS 4
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 one references the name on the host, and the second one the name in the container\&. This option corresponds to the
\fB\-\-network\-interface=\fR
command line switch and implies
\fIPrivate=yes\fR\&. This option is privileged (see above)\&.
.sp
Added in version 226\&.
.RE
.PP
\fIMACVLAN=\fR, \fIIPVLAN=\fR
.RS 4
Takes a space\-separated list of interfaces to add MACLVAN 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, in which case the first one references the name on the host, and the second one the name in the container\&. These options correspond to the
\fB\-\-network\-macvlan=\fR
and
\fB\-\-network\-ipvlan=\fR
command line switches and imply
\fIPrivate=yes\fR\&. These options are privileged (see above)\&.
.sp
Added in version 226\&.
.RE
.PP
\fIBridge=\fR
.RS 4
Takes an interface name\&. This setting implies
\fIVirtualEthernet=yes\fR
and
\fIPrivate=yes\fR
and has the effect that the host side of the created virtual Ethernet link is connected to the specified bridge interface\&. This option corresponds to the
\fB\-\-network\-bridge=\fR
command line switch\&. This option is privileged (see above)\&.
.sp
Added in version 226\&.
.RE
.PP
\fIZone=\fR
.RS 4
Takes a network zone name\&. This setting implies
\fIVirtualEthernet=yes\fR
and
\fIPrivate=yes\fR
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\-"\&. This option corresponds to the
\fB\-\-network\-zone=\fR
command line switch\&. This option is privileged (see above)\&.
.sp
Added in version 230\&.
.RE
.PP
\fIPort=\fR
.RS 4
Exposes a TCP or UDP port of the container on the host\&. This option corresponds to the
\fB\-\-port=\fR
command line switch, see
\fBsystemd-nspawn\fR(1)
for the precise syntax of the argument this option takes\&. This option is privileged (see above)\&.
.sp
Added in version 226\&.
.RE
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsystemd-nspawn\fR(1),
\fBsystemd.directives\fR(7)