diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index eb411102bc..9bc4bb7c44 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -133,6 +133,75 @@ The following options are understood: + + + + + + Turns off any status output by the tool + itself. When this switch is used, the only output from nspawn + will be the console output of the container OS + itself. + + + + MODE + + Controls whether + systemd-nspawn shall search for and use + additional per-container settings from + .nspawn files. Takes a boolean or the + special values or + . + + If enabled (the default), a settings file named after the + machine (as specified with the + setting, or derived from the directory or image file name) + with the suffix .nspawn is searched in + /etc/systemd/nspawn/ and + /run/systemd/nspawn/. If it is found + there, its settings are read and used. If it is not found + there, it is subsequently searched in the same directory as the + image file or in the immediate parent of the root directory of + the container. In this case, if the file is found, its settings + will be also read and used, but potentially unsafe settings + are ignored. Note that in both these cases, settings on the + command line take precedence over the corresponding settings + from loaded .nspawn files, if both are + specified. Unsafe settings are considered all settings that + elevate the container's privileges or grant access to + additional resources such as files or directories of the + host. For details about the format and contents of + .nspawn files, consult + systemd.nspawn5. + + If this option is set to , the + file is searched, read and used the same way, however, the order of + precedence is reversed: settings read from the + .nspawn file will take precedence over + the corresponding command line options, if both are + specified. + + If this option is set to , the + file is searched, read and used the same way, but regardless + of being found in /etc/systemd/nspawn/, + /run/systemd/nspawn/ or next to the image + file or container root directory, all settings will take + effect, however, command line arguments still take precedence + over corresponding settings. + + If disabled, no .nspawn file is read + and no settings except the ones on the command line are in + effect. + + + + + + Image Options + + + @@ -247,6 +316,66 @@ from the OCI runtime JSON data (but data passed on the command line takes precedence). + + + + Mount the container's root file system (and any other file systems container in the container + image) read-only. This has no effect on additional mounts made with , + and similar options. This mode is implied if the container image file or directory is + marked read-only itself. It is also implied if is used. In this case the container + image on disk is strictly read-only, while changes are permitted but kept non-persistently in memory only. For + further details, see below. + + + + + MODE + + Boots the container in volatile mode. When no mode parameter is passed or when mode is + specified as , full volatile mode is enabled. This means the root directory is mounted as a + mostly unpopulated tmpfs instance, and /usr/ from the OS tree is + mounted into it in read-only mode (the system thus starts up with read-only OS image, but pristine state and + configuration, any changes are lost on shutdown). When the mode parameter is specified as + , the OS tree is mounted read-only, but /var/ is mounted as a + writable tmpfs instance into it (the system thus starts up with read-only OS resources and + configuration, but pristine state, and any changes to the latter are lost on shutdown). When the mode parameter + is specified as the read-only root file system is combined with a writable + tmpfs instance through overlayfs, so that it appears at it normally + would, but any changes are applied to the temporary file system only and lost when the container is + terminated. When the mode parameter is specified as (the default), the whole OS tree is + made available writable (unless is specified, see above). + + Note that if one of the volatile modes is chosen, its effect is limited to the root file system (or + /var/ in case of ), and any other mounts placed in the hierarchy are + unaffected — regardless if they are established automatically (e.g. the EFI system partition that might be + mounted to /efi/ or /boot/) or explicitly (e.g. through an additional + command line option such as , see below). This means, even if + is used changes to /efi/ or + /boot/ are prohibited in case such a partition exists in the container image operated on, + and even if is used the hypothetical file /etc/foobar is + potentially writable if if used to mount it from outside the read-only + container /etc directory. + + The option is closely related to this setting, and provides similar + behaviour by making a temporary, ephemeral copy of the whole OS image and executing that. For further details, + see above. + + The and options provide similar functionality, but + for specific sub-directories of the OS image only. For details, see below. + + This option provides similar functionality for containers as the systemd.volatile= + kernel command line switch provides for host systems. See + kernel-command-line7 for + details. + + Note that setting this option to or will only work correctly + with operating systems in the container that can boot up with only /usr mounted, and are + able to automatically populate /var, and also /etc in case of + --volatile=yes. The option does not require any particular + preparations in the OS, but do note that overlayfs behaviour differs from regular file + systems in a number of ways, and hence compatibility is limited. + + @@ -262,6 +391,27 @@ used, also as formatted hexadecimal characters. + + + + Pivot the specified directory to / inside the container, and either unmount the + container's old root, or pivot it to another specified directory. Takes one of: a path argument — in which case the + specified path will be pivoted to / and the old root will be unmounted; or a colon-separated pair + of new root path and pivot destination for the old root. The new root path will be pivoted to /, + and the old / will be pivoted to the other directory. Both paths must be absolute, and are resolved + in the container's file system namespace. + + This is for containers which have several bootable directories in them; for example, several + OSTree deployments. It emulates the behavior of + the boot loader and initial RAM disk which normally select which directory to mount as the root and start the + container's PID 1 in. + + + + + Execution Options + + @@ -336,19 +486,14 @@ - + + - Pivot the specified directory to / inside the container, and either unmount the - container's old root, or pivot it to another specified directory. Takes one of: a path argument — in which case the - specified path will be pivoted to / and the old root will be unmounted; or a colon-separated pair - of new root path and pivot destination for the old root. The new root path will be pivoted to /, - and the old / will be pivoted to the other directory. Both paths must be absolute, and are resolved - in the container's file system namespace. - - This is for containers which have several bootable directories in them; for example, several - OSTree deployments. It emulates the behavior of - the boot loader and initial RAM disk which normally select which directory to mount as the root and start the - container's PID 1 in. + Specifies an environment variable assignment + to pass to the init process in the container, in the format + NAME=VALUE. This may be used to override + the default variables or to set additional variables. This + parameter may be used more than once. @@ -362,6 +507,36 @@ destructive operations only. + + + + Specify the process signal to send to the container's PID 1 when nspawn itself receives + SIGTERM, in order to trigger an orderly shutdown of the container. Defaults to + SIGRTMIN+3 if is used (on systemd-compatible init systems + SIGRTMIN+3 triggers an orderly shutdown). If is not used and this + option is not specified the container's processes are terminated abruptly via SIGKILL. For + a list of valid signals, see signal7. + + + + + + Configures support for notifications from the container's init process. + takes a boolean ( and ). + With option systemd-nspawn notifies systemd + with a READY=1 message when the init process is created. + With option systemd-nspawn waits for the + READY=1 message from the init process in the container + before sending its own to systemd. For more details about notifications + see sd_notify3). + + + + + System Identity Options + + @@ -406,7 +581,12 @@ /etc/machine-id in the container is unpopulated. + + + Property Options + + @@ -427,6 +607,42 @@ + + + + Controls whether the container is registered with + systemd-machined8. Takes a + boolean argument, which defaults to yes. This option should be enabled when the container + runs a full Operating System (more specifically: a system and service manager as PID 1), and is useful to + ensure that the container is accessible via + machinectl1 and shown by + tools such as ps1. If the container + does not run a service manager, it is recommended to set this option to + no. + + + + + + Instead of creating a transient scope unit to run the container in, simply use the service or + scope unit systemd-nspawn has been invoked in. If is set + this unit is registered with + systemd-machined8. This + switch should be used if systemd-nspawn is invoked from within a service unit, and the + service unit's sole purpose is to run a single systemd-nspawn container. This option is not + available if run from a user session. + Note that passing disables the effect of and + . Use and in + combination to disable any kind of unit allocation or registration with + systemd-machined. + + + + + User Namespacing Options + + @@ -519,6 +735,13 @@ + + + + Networking Options + + + @@ -535,23 +758,6 @@ - - - - Takes the path to a file representing a kernel - network namespace that the container shall run in. The specified 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 of the - typical use cases is to give a network namespace under - /run/netns created by ip-netns8, - for example, . - Note that this option cannot be used together with other - network-related options, such as - or . - - @@ -689,6 +895,23 @@ + + + + Takes the path to a file representing a kernel + network namespace that the container shall run in. The specified 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 of the + typical use cases is to give a network namespace under + /run/netns created by ip-netns8, + for example, . + Note that this option cannot be used together with other + network-related options, such as + or . + + @@ -707,26 +930,12 @@ , . + - - - - - Sets the SELinux security context to be used - to label processes in the container. - - - - - - - - Sets the SELinux security context to be used - to label files in the virtual API file systems in the - container. - - + + Security Options + @@ -780,6 +989,31 @@ capabilities are passed using the --capabilities=. + + + + + Sets the SELinux security context to be used + to label processes in the container. + + + + + + + + Sets the SELinux security context to be used + to label files in the virtual API file systems in the + container. + + + + + + Resource Options + + + @@ -825,58 +1059,23 @@ - + - Specify the process signal to send to the container's PID 1 when nspawn itself receives - SIGTERM, in order to trigger an orderly shutdown of the container. Defaults to - SIGRTMIN+3 if is used (on systemd-compatible init systems - SIGRTMIN+3 triggers an orderly shutdown). If is not used and this - option is not specified the container's processes are terminated abruptly via SIGKILL. For - a list of valid signals, see signal7. + Control the architecture ("personality") + reported by + uname2 + in the container. Currently, only x86 and + x86-64 are supported. This is useful when + running a 32-bit container on a 64-bit host. If this setting + is not used, the personality reported in the container is the + same as the one reported on the host. + - - - - Control whether the container's journal shall - be made visible to the host system. If enabled, allows viewing - the container's journal files from the host (but not vice - versa). Takes one of no, - host, try-host, - guest, try-guest, - auto. If no, the journal - is not linked. If host, the journal files - are stored on the host file system (beneath - /var/log/journal/machine-id) - and the subdirectory is bind-mounted into the container at the - same location. If guest, the journal files - are stored on the guest file system (beneath - /var/log/journal/machine-id) - and the subdirectory is symlinked into the host at the same - location. try-host and - try-guest do the same but do not fail if - the host does not have persistent journaling enabled. If - auto (the default), and the right - subdirectory of /var/log/journal exists, - it will be bind mounted into the container. If the - subdirectory does not exist, no linking is performed. - Effectively, booting a container once with - guest or host will link - the journal persistently if further on the default of - auto is used. - - Note that is the default if the - systemd-nspawn@.service template unit file is used. - - - - - - Equivalent to - . - + + Integration Options + @@ -926,16 +1125,53 @@ - + - Mount the container's root file system (and any other file systems container in the container - image) read-only. This has no effect on additional mounts made with , - and similar options. This mode is implied if the container image file or directory is - marked read-only itself. It is also implied if is used. In this case the container - image on disk is strictly read-only, while changes are permitted but kept non-persistently in memory only. For - further details, see below. + Control whether the container's journal shall + be made visible to the host system. If enabled, allows viewing + the container's journal files from the host (but not vice + versa). Takes one of no, + host, try-host, + guest, try-guest, + auto. If no, the journal + is not linked. If host, the journal files + are stored on the host file system (beneath + /var/log/journal/machine-id) + and the subdirectory is bind-mounted into the container at the + same location. If guest, the journal files + are stored on the guest file system (beneath + /var/log/journal/machine-id) + and the subdirectory is symlinked into the host at the same + location. try-host and + try-guest do the same but do not fail if + the host does not have persistent journaling enabled. If + auto (the default), and the right + subdirectory of /var/log/journal exists, + it will be bind mounted into the container. If the + subdirectory does not exist, no linking is performed. + Effectively, booting a container once with + guest or host will link + the journal persistently if further on the default of + auto is used. + + Note that is the default if the + systemd-nspawn@.service template unit file is used. + + + + Equivalent to + . + + + + + + Mount Options + + + @@ -1044,65 +1280,15 @@ this switch. Note that this option cannot be used to replace the root file system of the container with an overlay - file system. However, the option described below provides similar functionality, + file system. However, the option described above provides similar functionality, with a focus on implementing stateless operating system images. + - - - - - Specifies an environment variable assignment - to pass to the init process in the container, in the format - NAME=VALUE. This may be used to override - the default variables or to set additional variables. This - parameter may be used more than once. - - - - - - Controls whether the container is registered with - systemd-machined8. Takes a - boolean argument, which defaults to yes. This option should be enabled when the container - runs a full Operating System (more specifically: a system and service manager as PID 1), and is useful to - ensure that the container is accessible via - machinectl1 and shown by - tools such as ps1. If the container - does not run a service manager, it is recommended to set this option to - no. - - - - - - Instead of creating a transient scope unit to run the container in, simply use the service or - scope unit systemd-nspawn has been invoked in. If is set - this unit is registered with - systemd-machined8. This - switch should be used if systemd-nspawn is invoked from within a service unit, and the - service unit's sole purpose is to run a single systemd-nspawn container. This option is not - available if run from a user session. - Note that passing disables the effect of and - . Use and in - combination to disable any kind of unit allocation or registration with - systemd-machined. - - - - - - Control the architecture ("personality") - reported by - uname2 - in the container. Currently, only x86 and - x86-64 are supported. This is useful when - running a 32-bit container on a 64-bit host. If this setting - is not used, the personality reported in the container is the - same as the one reported on the host. - + + Input/Output Options + MODE @@ -1139,133 +1325,10 @@ Equivalent to . - - - - - Turns off any status output by the tool - itself. When this switch is used, the only output from nspawn - will be the console output of the container OS - itself. - - - - - MODE - - Boots the container in volatile mode. When no mode parameter is passed or when mode is - specified as , full volatile mode is enabled. This means the root directory is mounted as a - mostly unpopulated tmpfs instance, and /usr/ from the OS tree is - mounted into it in read-only mode (the system thus starts up with read-only OS image, but pristine state and - configuration, any changes are lost on shutdown). When the mode parameter is specified as - , the OS tree is mounted read-only, but /var/ is mounted as a - writable tmpfs instance into it (the system thus starts up with read-only OS resources and - configuration, but pristine state, and any changes to the latter are lost on shutdown). When the mode parameter - is specified as the read-only root file system is combined with a writable - tmpfs instance through overlayfs, so that it appears at it normally - would, but any changes are applied to the temporary file system only and lost when the container is - terminated. When the mode parameter is specified as (the default), the whole OS tree is - made available writable (unless is specified, see above). - - Note that if one of the volatile modes is chosen, its effect is limited to the root file system (or - /var/ in case of ), and any other mounts placed in the hierarchy are - unaffected — regardless if they are established automatically (e.g. the EFI system partition that might be - mounted to /efi/ or /boot/) or explicitly (e.g. through an additional - command line option such as , see above). This means, even if - is used changes to /efi/ or - /boot/ are prohibited in case such a partition exists in the container image operated on, - and even if is used the hypothetical file /etc/foobar is - potentially writable if if used to mount it from outside the read-only - container /etc directory. - - The option is closely related to this setting, and provides similar - behaviour by making a temporary, ephemeral copy of the whole OS image and executing that. For further details, - see above. - - The and options provide similar functionality, but - for specific sub-directories of the OS image only. For details, see above. - - This option provides similar functionality for containers as the systemd.volatile= - kernel command line switch provides for host systems. See - kernel-command-line7 for - details. - - Note that setting this option to or will only work correctly - with operating systems in the container that can boot up with only /usr mounted, and are - able to automatically populate /var, and also /etc in case of - --volatile=yes. The option does not require any particular - preparations in the OS, but do note that overlayfs behaviour differs from regular file - systems in a number of ways, and hence compatibility is limited. - - - - MODE - - Controls whether - systemd-nspawn shall search for and use - additional per-container settings from - .nspawn files. Takes a boolean or the - special values or - . - - If enabled (the default), a settings file named after the - machine (as specified with the - setting, or derived from the directory or image file name) - with the suffix .nspawn is searched in - /etc/systemd/nspawn/ and - /run/systemd/nspawn/. If it is found - there, its settings are read and used. If it is not found - there, it is subsequently searched in the same directory as the - image file or in the immediate parent of the root directory of - the container. In this case, if the file is found, its settings - will be also read and used, but potentially unsafe settings - are ignored. Note that in both these cases, settings on the - command line take precedence over the corresponding settings - from loaded .nspawn files, if both are - specified. Unsafe settings are considered all settings that - elevate the container's privileges or grant access to - additional resources such as files or directories of the - host. For details about the format and contents of - .nspawn files, consult - systemd.nspawn5. - - If this option is set to , the - file is searched, read and used the same way, however, the order of - precedence is reversed: settings read from the - .nspawn file will take precedence over - the corresponding command line options, if both are - specified. - - If this option is set to , the - file is searched, read and used the same way, but regardless - of being found in /etc/systemd/nspawn/, - /run/systemd/nspawn/ or next to the image - file or container root directory, all settings will take - effect, however, command line arguments still take precedence - over corresponding settings. - - If disabled, no .nspawn file is read - and no settings except the ones on the command line are in - effect. - - - - - - Configures support for notifications from the container's init process. - takes a boolean ( and ). - With option systemd-nspawn notifies systemd - with a READY=1 message when the init process is created. - With option systemd-nspawn waits for the - READY=1 message from the init process in the container - before sending its own to systemd. For more details about notifications - see sd_notify3). - - - +