diff options
Diffstat (limited to 'man/systemd-nspawn.xml')
| -rw-r--r-- | man/systemd-nspawn.xml | 138 |
1 files changed, 89 insertions, 49 deletions
diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 349bc8a..2645a6b 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1,6 +1,6 @@ <?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % entities SYSTEM "custom-entities.ent" > %entities; ]> @@ -119,6 +119,28 @@ </refsect1> <refsect1> + <title>Unprivileged Operation</title> + + <para><command>systemd-nspawn</command> 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:</para> + + <itemizedlist> + <listitem><para>Only disk image based containers are supported (i.e. <option>--image=</option>). + Directory based ones (i.e. <option>--directory=</option>) are not supported.</para></listitem> + + <listitem><para>Machine registration via <option>--machine=</option> is not supported.</para></listitem> + + <listitem><para>Only <option>--private-network</option> and <option>--network-veth</option> networking modes are supported.</para></listitem> + </itemizedlist> + + <para>When running in unprivileged mode, some needed functionality is provided via + <citerefentry><refentrytitle>systemd-mountfsd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd-nsresourced.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></para> + </refsect1> + + <refsect1> <title>Options</title> <para>If option <option>--boot</option> is specified, the arguments @@ -146,7 +168,7 @@ </varlistentry> <varlistentry> - <term><option>--settings=</option><replaceable>MODE</replaceable></term> + <term><option>--settings=<replaceable>MODE</replaceable></option></term> <listitem><para>Controls whether <command>systemd-nspawn</command> shall search for and use @@ -209,21 +231,19 @@ <term><option>-D</option></term> <term><option>--directory=</option></term> - <listitem><para>Directory to use as file system root for the - container.</para> + <listitem><para>Directory to use as file system root for the container.</para> - <para>If neither <option>--directory=</option>, nor - <option>--image=</option> is specified the directory is - determined by searching for a directory named the same as the - machine name specified with <option>--machine=</option>. See + <para>If neither <option>--directory=</option>, nor <option>--image=</option> is specified the + directory is determined by searching for a directory named the same as the machine name specified + with <option>--machine=</option>. See <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> section "Files and Directories" for the precise search path.</para> - <para>If neither <option>--directory=</option>, - <option>--image=</option>, nor <option>--machine=</option> - are specified, the current directory will - be used. May not be specified together with - <option>--image=</option>.</para></listitem> + <xi:include href="vpick.xml" xpointer="directory"/> + + <para>If neither <option>--directory=</option>, <option>--image=</option>, nor + <option>--machine=</option> are specified, the current directory will be used. May not be specified + together with <option>--image=</option>.</para></listitem> </varlistentry> <varlistentry> @@ -317,6 +337,8 @@ <para>Any other partitions, such as foreign partitions or swap partitions are not mounted. May not be specified together with <option>--directory=</option>, <option>--template=</option>.</para> + <xi:include href="vpick.xml" xpointer="image"/> + <xi:include href="version-info.xml" xpointer="v211"/></listitem> </varlistentry> @@ -357,7 +379,7 @@ <varlistentry> <term><option>--volatile</option></term> - <term><option>--volatile=</option><replaceable>MODE</replaceable></term> + <term><option>--volatile=<replaceable>MODE</replaceable></option></term> <listitem><para>Boots the container in volatile mode. When no mode parameter is passed or when mode is specified as <option>yes</option>, full volatile mode is enabled. This means the root directory is mounted as a @@ -584,7 +606,14 @@ <listitem><para>After transitioning into the container, change to the specified user defined in the container's user database. Like all other systemd-nspawn features, this is not a security feature and - provides protection against accidental destructive operations only.</para></listitem> + provides protection against accidental destructive operations only.</para> + + <para>Note that if credentials are used in combination with a non-root <option>--user=</option> + (e.g.: <option>--set-credential=</option>, <option>--load-credential=</option> or + <option>--import-credential=</option>), then <option>--no-new-privileges=yes</option> must be used, and + <option>--boot</option> or <option>--as-pid2</option> must not be used, as the credentials would + otherwise be unreadable by the container due to missing privileges after switching to the specified + user.</para></listitem> </varlistentry> <varlistentry> @@ -1487,12 +1516,12 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <para>Mount options are comma-separated. <option>rbind</option> and <option>norbind</option> control whether to create a recursive or a regular bind mount. Defaults to <option>rbind</option>. <option>noidmap</option>, - <option>idmap</option>, and <option>rootidmap</option> control ID mapping.</para> + <option>idmap</option>, <option>rootidmap</option> and <option>owneridmap</option> control ID mapping.</para> - <para>Using <option>idmap</option> or <option>rootidmap</option> requires support by the source filesystem - for user/group ID mapped mounts. Defaults to <option>noidmap</option>. With <option>x</option> being the container's UID range - offset, <option>y</option> being the length of the container's UID range, and <option>p</option> being the - owner UID of the bind mount source inode on the host: + <para>Using <option>idmap</option>, <option>rootidmap</option> or <option>owneridmap</option> requires support + by the source filesystem for user/group ID mapped mounts. Defaults to <option>noidmap</option>. With + <option>x</option> being the container's UID range offset, <option>y</option> being the length of the + container's UID range, and <option>p</option> being the owner UID of the bind mount source inode on the host: <itemizedlist> <listitem><para>If <option>noidmap</option> is used, any user <option>z</option> in the range @@ -1508,10 +1537,15 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <listitem><para>If <option>rootidmap</option> is used, the user <option>0</option> seen from inside of the container is mapped to <option>p</option> on the host. Other host users are mapped to <option>nobody</option> inside the container.</para></listitem> + + <listitem><para>If <option>owneridmap</option> is used, the owner of the target directory inside of the + container is mapped to <option>p</option> on the host. Other host users are mapped to + <option>nobody</option> inside the container.</para></listitem> </itemizedlist></para> <para>Whichever ID mapping option is used, the same mapping will be used for users and groups IDs. If - <option>rootidmap</option> is used, the group owning the bind mounted directory will have no effect.</para> + <option>rootidmap</option> or <option>owneridmap</option> are used, the group owning the bind mounted directory + will have no effect.</para> <para>Note that when this option is used in combination with <option>--private-users</option>, the resulting mount points will be owned by the <constant>nobody</constant> user. That's because the mount and its files and @@ -1665,7 +1699,7 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <variablelist> <varlistentry> - <term><option>--console=</option><replaceable>MODE</replaceable></term> + <term><option>--console=<replaceable>MODE</replaceable></option></term> <listitem><para>Configures how to set up standard input, output and error output for the container payload, as well as the <filename>/dev/console</filename> device for the container. Takes one of @@ -1708,6 +1742,21 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <xi:include href="version-info.xml" xpointer="v242"/></listitem> </varlistentry> + + <varlistentry> + <term><option>--background=<replaceable>COLOR</replaceable></option></term> + + <listitem><para>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 <literal>40</literal>, <literal>41</literal>, …, <literal>47</literal>, <literal>48;2;…</literal>, + <literal>48;5;…</literal>. See <ulink + url="https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters">ANSI + Escape Code (Wikipedia)</ulink> for details. Assign an empty string to disable any coloring.</para> + + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + </variablelist> </refsect2> @@ -1716,8 +1765,8 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <variablelist> <varlistentry> - <term><option>--load-credential=</option><replaceable>ID</replaceable>:<replaceable>PATH</replaceable></term> - <term><option>--set-credential=</option><replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></term> + <term><option>--load-credential=<replaceable>ID</replaceable>:<replaceable>PATH</replaceable></option></term> + <term><option>--set-credential=<replaceable>ID</replaceable>:<replaceable>VALUE</replaceable></option></term> <listitem><para>Pass a credential to the container. These two options correspond to the <varname>LoadCredential=</varname> and <varname>SetCredential=</varname> settings in unit files. See @@ -1780,19 +1829,7 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <refsect1> <title>Examples</title> - <example> - <title>Download a - <ulink url="https://getfedora.org">Fedora</ulink> image and start a shell in it</title> - - <programlisting># machinectl pull-raw --verify=no \ - https://download.fedoraproject.org/pub/fedora/linux/releases/&fedora_latest_version;/Cloud/x86_64/images/Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86_64.raw.xz \ - Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64 -# systemd-nspawn -M Fedora-Cloud-Base-&fedora_latest_version;-&fedora_cloud_release;.x86-64</programlisting> - - <para>This downloads an image using - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - and opens a shell in it.</para> - </example> + <xi:include href="importctl.xml" xpointer="example-import-tar" /> <example> <title>Build and boot a minimal Fedora distribution in a container</title> @@ -1891,18 +1928,21 @@ After=sys-subsystem-net-devices-ens1.device</programlisting> <refsect1> <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry project='mankier'><refentrytitle>zypper</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry project='url'><refentrytitle url='https://btrfs.readthedocs.io/en/latest/btrfs.html'>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> + <para><simplelist type="inline"> + <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd.nspawn</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> + <member><citerefentry project='man-pages'><refentrytitle>chroot</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry project='mankier'><refentrytitle>dnf</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry project='die-net'><refentrytitle>debootstrap</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry project='archlinux'><refentrytitle>pacman</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry project='mankier'><refentrytitle>zypper</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-mountfsd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-nsresourced.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry project='url'><refentrytitle url='https://btrfs.readthedocs.io/en/latest/btrfs.html'>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + </simplelist></para> </refsect1> </refentry> |