From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/systemd-dissect.xml | 308 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 man/systemd-dissect.xml (limited to 'man/systemd-dissect.xml') diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml new file mode 100644 index 0000000..b04dadc --- /dev/null +++ b/man/systemd-dissect.xml @@ -0,0 +1,308 @@ + + + + + + + + systemd-dissect + systemd + + + + systemd-dissect + 1 + + + + systemd-dissect + Dissect Discoverable Disk Images (DDIs) + + + + + systemd-dissect OPTIONS IMAGE + + + systemd-dissect OPTIONS IMAGE PATH + + + systemd-dissect OPTIONS 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, specifically Discoverable Disk Images (DDIs). It supports five 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. + + Unmount an OS image from a local directory. In this mode it will recursively unmount + the mounted partitions and remove the underlying loop device, including all the partition sub-devices. + + + 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 systemd-nspawn1's + switch, and be used as root file system for system service using the + RootImage= unit file setting, see + systemd.exec5. + + Note that the partition table shown when invoked without command switch (as listed below) does not + necessarily show all partitions included in the image, but just the partitions that are understood and + considered part of an OS disk image. Specifically, partitions of unknown types are ignored, as well as + duplicate partitions (i.e. more than one per partition type), as are root and /usr/ + partitions of architectures not compatible with the local system. In other words: this tool will display + what it operates with when mounting the image. To display the complete list of partitions use a tool such + as fdisk8. + + + + 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 the operation. + + 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 . + + + + + + + Unmount an OS image from the specified directory. This command expects one argument: + a directory where an OS image was mounted. + + All mounted partitions will be recursively unmounted, and the underlying loop device will be + removed, along with all its partition sub-devices. + + + + + + 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 + . + + + + + + Turn off automatic growing of accessed file systems to their partition size, if + marked for that in the GPT partition table. By default when an image is accessed for writing (by + or ) the file systems contained in the OS image + are automatically grown to their partition sizes, if bit 59 in the GPT partition flags is set for + partition types that are defined by the Discoverable Partitions Specification. This + behavior may be switched off using . File systems are grown automatically + on access if all of the following conditions are met: + + The file system is mounted writable + The file system currently is smaller than the partition it is contained in (and thus can be grown) + The image contains a GPT partition table + The file system is stored on a partition defined by the Discoverable Partitions Specification + Bit 59 of the GPT partition flags for this partition is set, as per specification + The option is not passed. + + + + + + + + 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. + + + + + + If combined with the specified directory where the OS image + is mounted is removed after unmounting the OS image. + + + + + + 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. Option + specifies a hex-encoded top-level Verity hash to use for setting up the + Verity integrity protection. Option specifies the path to a file + containing a PKCS#7 signature for the hash. This signature is passed to the kernel during activation, + which will match it against signature keys available in the kernel keyring. Option + specifies a 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, + systemd-nspawn1, + systemd.exec5, + Discoverable Partitions Specification, + umount8, + fdisk8 + + + + -- cgit v1.2.3