diff --git a/man/importctl.xml b/man/importctl.xml index 9e97b2a241..3c14b83f08 100644 --- a/man/importctl.xml +++ b/man/importctl.xml @@ -39,9 +39,9 @@ importctl may be used to download, import, and export disk images via systemd-importd.service8. - importctl operates both on block-level disk images (such as DDIs) as well as - file-system-level images (tarballs). It supports disk images in one of the four following - classes: + importctl operates both on block-level disk images (such as DDIs), + file-system-level images (tarballs), as well as OCI images. It supports disk images in one of the four + following classes: VM images or full OS container images, that may be run via @@ -171,6 +171,24 @@ + + pull-oci REF [NAME] + + Downloads the specified OCI container image, and makes it available under the + specified local name in the image directory for the selected . The first + argument must be an OCI container reference, such as library/nginx If the local + name is omitted, it is automatically derived from the last component of the URL, with its suffix + removed. + + When downloading images of this type no image verification is done beyond the usual + authentication of the HTTPS certificates. + + Note that pressing Control-c during execution of this command will not abort the download. Use + cancel-transfer, described below. + + + + import-tar FILE [NAME] import-raw FILE [NAME] diff --git a/man/rules/meson.build b/man/rules/meson.build index 9eae3e8249..94ac1c919b 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -1074,6 +1074,7 @@ manpages = [ ['systemd-modules-load.service', '8', ['systemd-modules-load'], 'HAVE_KMOD'], ['systemd-mount', '1', ['systemd-umount'], ''], ['systemd-mountfsd.service', '8', ['systemd-mountfsd'], 'ENABLE_MOUNTFSD'], + ['systemd-mstack', '1', ['mount.mstack'], 'HAVE_BLKID'], ['systemd-mute-console', '1', ['systemd-mute-console.socket', 'systemd-mute-console@.service'], @@ -1249,6 +1250,7 @@ manpages = [ ['systemd.kill', '5', [], ''], ['systemd.link', '5', [], ''], ['systemd.mount', '5', [], ''], + ['systemd.mstack', '7', [], ''], ['systemd.net-naming-scheme', '7', [], ''], ['systemd.netdev', '5', [], 'ENABLE_NETWORKD'], ['systemd.network', '5', [], 'ENABLE_NETWORKD'], diff --git a/man/systemd-mstack.xml b/man/systemd-mstack.xml new file mode 100644 index 0000000000..41ae1fd831 --- /dev/null +++ b/man/systemd-mstack.xml @@ -0,0 +1,218 @@ + + + + + + + + systemd-mstack + systemd + + + + systemd-mstack + 1 + + + + systemd-mstack + mount.mstack + Mstack Discoverable Disk Images (DDIs) + + + + + systemd-mstack OPTIONS IMAGE + + + systemd-mstack OPTIONS --mount IMAGE PATH + + + systemd-mstack OPTIONS --umount PATH + + + + + Description + + systemd-mstack is a tool for introspecting and interacting with + .mstack/ mount stack directories, as described in + systemd.mstack7. It + supports three different operations: + + + Show general mount stack information, including all described + overlayfs layers and bind mounts. + + Mount a mount stack to a local directory. + + Unmount a mount stack from a local directory. + + + The systemd-mstack command may be invoked as mount.mstack in + which case it implements the mount8 "external + helper" interface. This ensures mount stack directories compatible with systemd-mstack + can be mounted directly by mount and fstab5. For + details see below. + + + + + + Commands + + If neither of the command switches listed below are passed the specified mount stack is opened and + general information about it is shown, including a list of all defined layers. + + + + + + + Mount the specified mount stack to the specified directory. + + To unmount a mount stack directory mounted like this use the operation. + + Note that this functionality is also available in mount8 via a + command such as mount -t mstack mystack.mstack targetdir/, as well as in fstab5. For + details, see below. + + + + + + + + This is a shortcut for . + + + + + + + + + Unmount a mount stack from the specified directory. This command expects one argument: + a directory where mount stack was mounted. + + All mounted mounts will be recursively unmounted + + + + + + + + This is a shortcut for . + + + + + + + + + + + + Options + + The following options are understood: + + + + + + + Operate in read-only mode. By default, will establish + writable mount points. If this option is specified they are established in read-only mode + instead. + + + + + + + + If combined with the directory to mount the mount stack to + is created if it is missing. Note that the directory is not automatically removed when the mount + stack is unmounted again. + + + + + + + + If combined with the specified directory where the mount stack + is mounted is removed after unmounting it. + + + + + + + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code otherwise. + + + + Invocation as <command>/sbin/mount.mstack</command> + + + + The systemd-mstack executable may be symlinked to + /sbin/mount.mstack. If invoked through that it implements mount8's + "external helper" interface for the (pseudo) file system type mstack. This means + conformant mount stack directories may be mounted directly via + + # mount -t mstack mystack.mstack targetdir/ + + in a fashion mostly equivalent to: + + # systemd-mstack --mount mystack.mstack targetdir/ + + Note that since a single mount stack may contain multiple mount points it should later be unmounted with + umount -R targetdir/, for recursive operation. + + This functionality is particularly useful to mount mount stacks automatically at boot via simple + /etc/fstab entries. For example: + + /path/to/mystack.nspawn /images/mystack/ mstack defaults 0 0 + + When invoked this way the mount options ro, rw map to the + corresponding options listed above (i.e. ). + + + + See Also + + systemd1 + systemd.mstack7 + systemd-nspawn1 + systemd.exec5 + mount8 + umount8 + + + + diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index fc2c0e145b..da598d090c 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -370,6 +370,18 @@ + + + + Mount stack to mount the root directory for the container from. Takes a path to a + directory implementing + systemd.mstack7. This + may be used to run a container of an overlayfs assembled from a number of layers, + possibly writable and augmented with additional bind mounts. + + + + @@ -2038,6 +2050,7 @@ After=sys-subsystem-net-devices-ens1.device importctl1 systemd-mountfsd.service8 systemd-nsresourced.service8 + systemd.mstack7 btrfs8 diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 59b6919a75..825621693e 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -352,6 +352,26 @@ + + RootMStack= + + Takes a path to a + systemd.mstack7 + directory encapsulating a mount stack consisting of layers and bind mounts. Similar to + RootDirectory= and RootImage= this runs the service off a + distinct root file system, in this case set up via overlayfs. + + Since .mstack/ directories may reference disk images (DDIs) similar device + policy extensions and dependencies are in effect when RootMStack= is used as are + if RootImage= is used. + + + + + + + + MountAPIVFS= diff --git a/man/systemd.mstack.xml b/man/systemd.mstack.xml new file mode 100644 index 0000000000..778d2cc9dc --- /dev/null +++ b/man/systemd.mstack.xml @@ -0,0 +1,126 @@ + + + + + + + + systemd.mstack + systemd + + + + systemd.mstack + 7 + + + + systemd.mstack + Mount stacks in self descriptive directories + + + + Description + + Directories with the .mstack/ suffix may encode 'mount stacks' for assembling OS + mount hierarchies based on bind and overlay mounts, for use in + systemd-nspawn1's + switch or the service manager's setting for + services. .mstack/ directroies may contain various files and subdirectories, where + each will effect one layer of an overlayfs mount, or a bind mount. The name of the + file or subdirectory indicates how it shall used in the mount hierarchy. Specifically, the following + names are defined: + + + A layer@id/ directory will be turned into + a layer of an overlayfs mount. The id identifier is used to define the order of the + layers: a version sort is executed, with the first entry being the bottom layer in the + overlayfs stack, and the last entry becoming the highest layer (precisely: + highest "lowerdir") in the overlayfs stack. + + Similar, a layer@id.raw regular file + will be mounted as a DDI, and the resulting mount will be turned into an overlayfs layer, following the + same sorting rules. + + An rw directory will be turned into a writable layer at the very top + of the overlayfs stack. A subdirectory data of it will become + the "upperdir", a subdirectory work will become the "workdir". Note that these two + subdirectories do not need to be created explicitly, they are created automatically on first use should + they be missing. + + A bind@location/ directory will be bind + mounted to the mount point indicated by the location identifier, in read-write + fashion. The loction is encoded via the same escaping logic used for naming .mount + units, i.e. slashes become dashes. + + Similar, a + bind@location.raw file will be mounted as a DDI, and the + resulting mount bind mounted to the specified location. + + A robind@location/ is treated very + similar to bind@location/, but the resulting bind mount + is read-only. + + Similar, robind@location.raw creates a + read-only bind mount from a DDI. + + If a root/ subdirectory it is used as root of the resulting mount + hierarchy, and only the usr/ subtree of the overlayfs mount will be bound to + usr/ in the hierarchy. + + + Note that each of the entry types above may be a symbolic link pointing to a directory or image + file, instead a directory or image file itself. + + On each listed file or subdirectory type the + systemd.v7 + functionality may be used, for automatic selection of versioned resources. + + Use the + systemd-mstack1 tool + to process or mount .mstack/ directories from the command line. + + + + Examples + + The following .mstack/ consists of two read-only overlayfs layers as DDI, plus one + writable directory one on top. The read-only layers are symlinked: + + + foobar.mstack/layer@0.raw → ../base.raw + foobar.mstack/layer@1.raw → ../app.raw + foobar.mstack/rw/ + + + The following .mstack/ consists of a read-only DDI mounted to /usr/ + and writable root: + + + waldo.mstack/layer@0.raw → ../vendor.raw + waldo.mstack/root/ + + + The following .mstack/ consists of a read-only DDI mounted as root, but a + writable /var/ mounted on top: + + + quux.mstack/layer@0.raw → ../myapp1.raw + quux.mstack/bind:var → ../myapp1-var/ + + + + + See Also + + systemd1 + systemd-mstack1 + systemd-nspawn1 + systemd.exec5 + systemd.v7 + systemd-vpick1 + + + +