diff --git a/man/rules/meson.build b/man/rules/meson.build index 3fb454faa9..d545f032a2 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -818,6 +818,7 @@ manpages = [ ['systemd-debug-generator', '8', [], ''], ['systemd-delta', '1', [], ''], ['systemd-detect-virt', '1', [], ''], + ['systemd-dissect', '1', [], ''], ['systemd-environment-d-generator', '8', ['30-systemd-environment-d-generator'], diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml new file mode 100644 index 0000000000..181b6568d0 --- /dev/null +++ b/man/systemd-dissect.xml @@ -0,0 +1,244 @@ + + + + + + + + systemd-dissect + systemd + + + + systemd-dissect + 1 + + + + systemd-dissect + Dissect file system OS images + + + + + systemd-dissect OPTIONS IMAGE + + + systemd-dissect OPTIONS IMAGE PATH + + + systemd-dissect OPTIONS IMAGE PATH TARGET + + + systemd-dissect OPTIONS IMAGE SOURCE PATH + + + + + Description + + systemd-dissect is a tool for introspecting and interacting with file system OS + disk images. It supports four different operations: + + + Show general OS image information, including the image's + os-release5 data, + machine ID, partition information and more. + + Mount an OS image to a local directory. In this mode it will dissect the OS image and + mount the included partitions according to their designation onto a directory and possibly + sub-directories. + + Copy files and directories in and out of an OS image. + + + The tool may operate on three types of OS images: + + + OS disk images containing a GPT partition table envelope, with partitions marked + according to the Discoverable Partitions + Specification. + + OS disk images containing just a plain file-system without an enveloping partition + table. (This file system is assumed to be the root file system of the OS.) + + OS disk images containing a GPT or MBR partition table, with a single + partition only. (This partition is assumed to contain the root file system of the OS.) + + + OS images may use any kind of Linux-supported file systems. In addition they may make use of LUKS + disk encryption, and contain Verity integrity information. Note that qualifying OS images may be booted + with system-nspawn1's + switch, and be used as root file system for system service using the + RootImage= unit file setting, see + system.exec5. + + + + Commands + + If neither of the command switches listed below are passed the specified disk image is opened and + general information about the image and the contained partitions and their use is shown. + + + + + + + Mount the specified OS image to the specified directory. This will dissect the image, + determine the OS root file system — as well as possibly other partitions — and mount them to the + specified directory. If the OS image contains multiple partitions marked with the Discoverable Partitions Specification + multiple nested mounts are established. This command expects two arguments: a path to an image file + and a path to a directory where to mount the image. + + To unmount an OS image mounted like this use umount8's + switch (for recursive operation), so that the OS image and all nested partition + mounts are unmounted. + + When the OS image contains LUKS encrypted or Verity integrity protected file systems + appropriate volumes are automatically set up and marked for automatic disassembly when the image is + unmounted. + + The OS image may either be specified as path to an OS image stored in a regular file or may + refer to block device node (in the latter case the block device must be the "whole" device, i.e. not + a partition device). (The other supported commands described here support this, too.) + + All mounted file systems are checked with the appropriate fsck8 + implementation in automatic fixing mode, unless explicitly turned off () or + read-only operation is requested (). + + + + + + This is a shortcut for . + + + + + + + Copies a file or directory from the specified OS image into the specified location on + the host file system. Expects three arguments: a path to an image file, a source path (relative to + the image's root directory) and a destination path (relative to the current working directory, or an + absolute path, both outside of the image). If the destination path is omitted or specified as dash + (-), the specified file is written to standard output. If the source path in the + image file system refers to a regular file it is copied to the destination path. In this case access + mode, extended attributes and timestamps are copied as well, but file ownership is not. If the source + path in the image refers to a directory, it is copied to the destination path, recursively with all + containing files and directories. In this case the file ownership is copied too. + + + + + + + Copies a file or directory from the specified location in the host file system into + the specified OS image. Expects three arguments: a path to an image file, a source path (relative to + the current working directory, or an absolute path, both outside of the image) and a destination path + (relative to the image's root directory). If the source path is omitted or specified as dash + (-), the data to write is read from standard input. If the source path in the host + file system refers to a regular file, it is copied to the destination path. In this case access mode, + extended attributes and timestamps are copied as well, but file ownership is not. If the source path + in the host file system refers to a directory it is copied to the destination path, recursively with + all containing files and directories. In this case the file ownership is copied + too. + + As with file system checks are implicitly run before the copy + operation begins. + + + + + + + + + + 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. + + + + + + Turn off automatic file system checking. By default when an image is accessed for + writing (by or ) the file systems contained in the OS + image are automatically checked using the appropriate fsck8 + command, in automatic fixing mode. This behavior may be switched off using + . + + + + + + If combined with the directory to mount the OS image to is + created if it is missing. Note that the directory is not automatically removed when the disk image is + unmounted again. + + + + + + Takes one of disabled, loop, + all, crypto. If disabled the image is + accessed with empty block discarding turned off. if loop discarding is enabled if + operating on a regular file. If crypt discarding is enabled even on encrypted file + systems. If all discarding is unconditionally enabled. + + + + + + + + Configure various aspects of Verity data integrity for the OS + image. expects a hex-encoding top-level Verity hash to use for setting + up the Verity integrity protection. expects the path to a file + containing a PKCS#7 signature file for the hash. This signature is passed to the kernel during + activation, which will match it against signature keys available in the kernel + keyring. expects the path to a file with the Verity data to use for + the OS image, in case it is stored in a detached file. It is recommended to embed the Verity data + directly in the image, using the Verity mechanisms in the Discoverable Partitions Specification. + + + + + + + + Exit status + + On success, 0 is returned, a non-zero failure code + otherwise. + + + + See Also + + systemd1, + system-nspawn1, + system.exec5, + Discoverable Partitions Specification, + umount8 + + + +