'\" t .TH "SYSTEMD\&.NSPAWN" "5" "" "systemd 256.6" "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 .RS 4 /etc/systemd/nspawn/\fImachine\fR\&.nspawn .RE .RS 4 /run/systemd/nspawn/\fImachine\fR\&.nspawn .RE .RS 4 /var/lib/machines/\fImachine\fR\&.nspawn .RE .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)