diff options
Diffstat (limited to 'upstream/debian-unstable/man1/systemd-nspawn.1')
| -rw-r--r-- | upstream/debian-unstable/man1/systemd-nspawn.1 | 195 |
1 files changed, 159 insertions, 36 deletions
diff --git a/upstream/debian-unstable/man1/systemd-nspawn.1 b/upstream/debian-unstable/man1/systemd-nspawn.1 index bfd09f6b..77ab1706 100644 --- a/upstream/debian-unstable/man1/systemd-nspawn.1 +++ b/upstream/debian-unstable/man1/systemd-nspawn.1 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\-NSPAWN" "1" "" "systemd 255" "systemd-nspawn" +.TH "SYSTEMD\-NSPAWN" "1" "" "systemd 256~rc3" "systemd-nspawn" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -119,6 +119,56 @@ While running, containers invoked with are registered with the \fBsystemd-machined\fR(8) service that keeps track of running containers, and provides programming interfaces to interact with them\&. +.SH "UNPRIVILEGED OPERATION" +.PP +\fBsystemd\-nspawn\fR +may be invoked with or without privileges\&. The full functionality is currently only available when invoked with privileges\&. When invoked without privileges, various limitations apply, including, but not limited to: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Only disk image based containers are supported (i\&.e\&. +\fB\-\-image=\fR)\&. Directory based ones (i\&.e\&. +\fB\-\-directory=\fR) are not supported\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Machine registration via +\fB\-\-machine=\fR +is not supported\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Only +\fB\-\-private\-network\fR +and +\fB\-\-network\-veth\fR +networking modes are supported\&. +.RE +.PP +When running in unprivileged mode, some needed functionality is provided via +\fBsystemd-mountfsd.service\fR(8) +and +\fBsystemd-nsresourced.service\fR(8) .SH "OPTIONS" .PP If option @@ -138,7 +188,7 @@ Turns off any status output by the tool itself\&. When this switch is used, the Added in version 209\&. .RE .PP -\fB\-\-settings=\fR\fIMODE\fR +\fB\-\-settings=\fR\fB\fIMODE\fR\fR .RS 4 Controls whether \fBsystemd\-nspawn\fR @@ -194,6 +244,12 @@ is specified the directory is determined by searching for a directory named the \fBmachinectl\fR(1) section "Files and Directories" for the precise search path\&. .sp +In place of the directory path a +"\&.v/" +versioned directory may be specified, see +\fBsystemd.v\fR(7) +for details\&. +.sp If neither \fB\-\-directory=\fR, \fB\-\-image=\fR, nor @@ -313,6 +369,12 @@ Any other partitions, such as foreign partitions or swap partitions are not moun \fB\-\-directory=\fR, \fB\-\-template=\fR\&. .sp +In place of the image path a +"\&.v/" +versioned directory may be specified, see +\fBsystemd.v\fR(7) +for details\&. +.sp Added in version 211\&. .RE .PP @@ -346,7 +408,7 @@ and similar options\&. This mode is implied if the container image file or direc 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\&. .RE .PP -\fB\-\-volatile\fR, \fB\-\-volatile=\fR\fIMODE\fR +\fB\-\-volatile\fR, \fB\-\-volatile=\fR\fB\fIMODE\fR\fR .RS 4 Boots the container in volatile mode\&. When no mode parameter is passed or when mode is specified as \fByes\fR, full volatile mode is enabled\&. This means the root directory is mounted as a mostly unpopulated @@ -592,6 +654,20 @@ Added in version 209\&. \fB\-u\fR, \fB\-\-user=\fR .RS 4 After transitioning into the container, change to the specified user defined in the container\*(Aqs user database\&. Like all other systemd\-nspawn features, this is not a security feature and provides protection against accidental destructive operations only\&. +.sp +Note that if credentials are used in combination with a non\-root +\fB\-\-user=\fR +(e\&.g\&.: +\fB\-\-set\-credential=\fR, +\fB\-\-load\-credential=\fR +or +\fB\-\-import\-credential=\fR), then +\fB\-\-no\-new\-privileges=yes\fR +must be used, and +\fB\-\-boot\fR +or +\fB\-\-as\-pid2\fR +must not be used, as the credentials would otherwise be unreadable by the container due to missing privileges after switching to the specified user\&. .RE .PP \fB\-\-kill\-signal=\fR @@ -1504,14 +1580,17 @@ and control whether to create a recursive or a regular bind mount\&. Defaults to \fBrbind\fR\&. \fBnoidmap\fR, -\fBidmap\fR, and +\fBidmap\fR, \fBrootidmap\fR +and +\fBowneridmap\fR control ID mapping\&. .sp Using -\fBidmap\fR -or +\fBidmap\fR, \fBrootidmap\fR +or +\fBowneridmap\fR requires support by the source filesystem for user/group ID mapped mounts\&. Defaults to \fBnoidmap\fR\&. With \fBx\fR @@ -1586,9 +1665,28 @@ on the host\&. Other host users are mapped to inside the container\&. .RE .sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If +\fBowneridmap\fR +is used, the owner of the target directory inside of the container is mapped to +\fBp\fR +on the host\&. Other host users are mapped to +\fBnobody\fR +inside the container\&. +.RE +.sp Whichever ID mapping option is used, the same mapping will be used for users and groups IDs\&. If \fBrootidmap\fR -is used, the group owning the bind mounted directory will have no effect\&. +or +\fBowneridmap\fR +are used, the group owning the bind mounted directory will have no effect\&. .sp Note that when this option is used in combination with \fB\-\-private\-users\fR, the resulting mount points will be owned by the @@ -1727,7 +1825,7 @@ Added in version 220\&. .RE .SS "Input/Output Options" .PP -\fB\-\-console=\fR\fIMODE\fR +\fB\-\-console=\fR\fB\fIMODE\fR\fR .RS 4 Configures how to set up standard input, output and error output for the container payload, as well as the /dev/console @@ -1787,9 +1885,23 @@ Equivalent to .sp Added in version 242\&. .RE +.PP +\fB\-\-background=\fR\fB\fICOLOR\fR\fR +.RS 4 +Change the terminal background color to the specified ANSI color as long as the container runs\&. The color specified should be an ANSI X3\&.64 SGR background color, i\&.e\&. strings such as +"40", +"41", \&..., +"47", +"48;2;\&...", +"48;5;\&..."\&. See +\m[blue]\fBANSI Escape Code (Wikipedia)\fR\m[]\&\s-2\u[6]\d\s+2 +for details\&. Assign an empty string to disable any coloring\&. +.sp +Added in version 256\&. +.RE .SS "Credentials" .PP -\fB\-\-load\-credential=\fR\fIID\fR:\fIPATH\fR, \fB\-\-set\-credential=\fR\fIID\fR:\fIVALUE\fR +\fB\-\-load\-credential=\fR\fB\fIID\fR\fR\fB:\fR\fB\fIPATH\fR\fR, \fB\-\-set\-credential=\fR\fB\fIID\fR\fR\fB:\fR\fB\fIVALUE\fR\fR .RS 4 Pass a credential to the container\&. These two options correspond to the \fILoadCredential=\fR @@ -1812,7 +1924,7 @@ to embed a newline, or "\ex00" to embed a \fBNUL\fR -byte)\&. Note that the invoking shell might already apply unescaping once, hence this might require double escaping!\&. +byte)\&. Note that the invoking shell might already apply unescaping once, hence this might require double escaping! .sp The \fBsystemd-sysusers.service\fR(8) @@ -1868,7 +1980,7 @@ Print a short version string and exit\&. .PP \fI$SYSTEMD_LOG_LEVEL\fR .RS 4 -The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance) +The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Takes a comma\-separated list of values\&. A value may be either one of (in order of decreasing importance) \fBemerg\fR, \fBalert\fR, \fBcrit\fR, @@ -1878,7 +1990,15 @@ The maximum log level of emitted messages (messages with a higher log level, i\& \fBinfo\fR, \fBdebug\fR, or an integer in the range 0\&...7\&. See \fBsyslog\fR(3) -for more information\&. +for more information\&. Each value may optionally be prefixed with one of +\fBconsole\fR, +\fBsyslog\fR, +\fBkmsg\fR +or +\fBjournal\fR +followed by a colon to set the maximum log level for that specific log target (e\&.g\&. +\fBSYSTEMD_LOG_LEVEL=debug,console:info\fR +specifies to log at debug level except when logging to the console which should be at info level)\&. Note that the global maximum log level takes priority over any per target maximum log levels\&. .RE .PP \fI$SYSTEMD_LOG_COLOR\fR @@ -1997,6 +2117,12 @@ will be ignored by the executable, and needs to be handled by the pager\&. This option instructs the pager to not send termcap initialization and deinitialization strings to the terminal\&. It is set by default to allow command output to remain visible in the terminal even after the pager exits\&. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse\&. .RE .sp +Note that setting the regular +\fI$LESS\fR +environment variable has no effect for +\fBless\fR +invocations by systemd tools\&. +.sp See \fBless\fR(1) for more discussion\&. @@ -2008,6 +2134,12 @@ Override the charset passed to \fBless\fR (by default "utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&. +.sp +Note that setting the regular +\fI$LESSCHARSET\fR +environment variable has no effect for +\fBless\fR +invocations by systemd tools\&. .RE .PP \fI$SYSTEMD_PAGERSECURE\fR @@ -2063,24 +2195,24 @@ and other conditions\&. .RE .SH "EXAMPLES" .PP -\fBExample\ \&1.\ \&Download a Fedora image and start a shell in it\fR +\fBExample\ \&1.\ \&Download an Ubuntu TAR image and open a shell in it\fR .sp .if n \{\ .RS 4 .\} .nf -# machinectl pull\-raw \-\-verify=no \e - https://download\&.fedoraproject\&.org/pub/fedora/linux/releases/38/Cloud/x86_64/images/Fedora\-Cloud\-Base\-38\-1\&.6\&.x86_64\&.raw\&.xz \e - Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64 -# systemd\-nspawn \-M Fedora\-Cloud\-Base\-38\-1\&.6\&.x86\-64 +# importctl pull\-tar \-mN https://cloud\-images\&.ubuntu\&.com/jammy/current/jammy\-server\-cloudimg\-amd64\-root\&.tar\&.xz +# systemd\-nspawn \-M jammy\-server\-cloudimg\-amd64\-root .fi .if n \{\ .RE .\} .PP -This downloads an image using -\fBmachinectl\fR(1) -and opens a shell in it\&. +This downloads and verifies the specified +\&.tar +image, and then uses +\fBsystemd-nspawn\fR(1) +to open a shell in it\&. .PP \fBExample\ \&2.\ \&Build and boot a minimal Fedora distribution in a container\fR .sp @@ -2088,21 +2220,21 @@ and opens a shell in it\&. .RS 4 .\} .nf -# dnf \-y \-\-releasever=38 \-\-installroot=/var/lib/machines/f38 \e +# dnf \-y \-\-releasever=40 \-\-installroot=/var/lib/machines/f40 \e \-\-repo=fedora \-\-repo=updates \-\-setopt=install_weak_deps=False install \e passwd dnf fedora\-release vim\-minimal util\-linux systemd systemd\-networkd -# systemd\-nspawn \-bD /var/lib/machines/f38 +# systemd\-nspawn \-bD /var/lib/machines/f40 .fi .if n \{\ .RE .\} .PP This installs a minimal Fedora distribution into the directory -/var/lib/machines/f38 +/var/lib/machines/f40 and then boots that OS in a namespace container\&. Because the installation is located underneath the standard /var/lib/machines/ directory, it is also possible to start the machine using -\fBsystemd\-nspawn \-M f38\fR\&. +\fBsystemd\-nspawn \-M f40\fR\&. .PP \fBExample\ \&3.\ \&Spawn a shell in a container of a minimal Debian unstable distribution\fR .sp @@ -2210,16 +2342,7 @@ This runs a copy of the host system in a snapshot which is removed immediately w The exit code of the program executed in the container is returned\&. .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsystemd.nspawn\fR(5), -\fBchroot\fR(1), -\fBdnf\fR(8), -\fBdebootstrap\fR(8), -\fBpacman\fR(8), -\fBzypper\fR(8), -\fBsystemd.slice\fR(5), -\fBmachinectl\fR(1), -\fBbtrfs\fR(8) +\fBsystemd\fR(1), \fBsystemd.nspawn\fR(5), \fBchroot\fR(1), \fBdnf\fR(8), \fBdebootstrap\fR(8), \fBpacman\fR(8), \fBzypper\fR(8), \fBsystemd.slice\fR(5), \fBmachinectl\fR(1), \fBimportctl\fR(1), \fBsystemd-mountfsd.service\fR(8), \fBsystemd-nsresourced.service\fR(8), \fBbtrfs\fR(8) .SH "NOTES" .IP " 1." 4 Container Interface @@ -2247,9 +2370,9 @@ Overlay Filesystem \%https://docs.kernel.org/filesystems/overlayfs.html .RE .IP " 6." 4 -Fedora +ANSI Escape Code (Wikipedia) .RS 4 -\%https://getfedora.org +\%https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters .RE .IP " 7." 4 Debian |