1SYSTEMD-DISSECT(1) systemd-dissect SYSTEMD-DISSECT(1)
2
6 systemd-dissect - Dissect file system OS images
7
9 systemd-dissect [OPTIONS...] IMAGE
10 systemd-dissect [OPTIONS...] --mount IMAGE PATH
12 systemd-dissect [OPTIONS...] --copy-from IMAGE PATH [TARGET]
14 systemd-dissect [OPTIONS...] --copy-to IMAGE [SOURCE] PATH
16
18 systemd-dissect is a tool for introspecting and interacting with file
19 system OS disk images. It supports four different operations:
20 1. Show general OS image information, including the image's os-
22 release(5) data, machine ID, partition information and more.
23 2. Mount an OS image to a local directory. In this mode it will
25 dissect the OS image and mount the included partitions according to
26 their designation onto a directory and possibly sub-directories.
27 3. Copy files and directories in and out of an OS image.
29 The tool may operate on three types of OS images:
31 1. OS disk images containing a GPT partition table envelope, with
33 partitions marked according to the Discoverable Partitions
34 Specification[1].
35 2. OS disk images containing just a plain file-system without an
37 enveloping partition table. (This file system is assumed to be the
38 root file system of the OS.)
39 3. OS disk images containing a GPT or MBR partition table, with a
41 single partition only. (This partition is assumed to contain the
42 root file system of the OS.)
43 OS images may use any kind of Linux-supported file systems. In addition
45 they may make use of LUKS disk encryption, and contain Verity integrity
46 information. Note that qualifying OS images may be booted with systemd-
47 nspawn(1)'s --image= switch, and be used as root file system for system
48 service using the RootImage= unit file setting, see systemd.exec(5).
49 Note that the partition table shown when invoked without command switch
51 (as listed below) does not necessarily show all partitions included in
52 the image, but just the partitions that are understood and considered
53 part of an OS disk image. Specifically, partitions of unknown types are
54 ignored, as well as duplicate partitions (i.e. more than one per
55 partition type), as are root and /usr/ partitions of architectures not
56 compatible with the local system. In other words: this tool will
57 display what it operates with when mounting the image. To display the
58 complete list of partitions use a tool such as fdisk(8).
59
61 If neither of the command switches listed below are passed the
62 specified disk image is opened and general information about the image
63 and the contained partitions and their use is shown.
64 --mount, -m
66 Mount the specified OS image to the specified directory. This will
67 dissect the image, determine the OS root file system — as well as
68 possibly other partitions — and mount them to the specified
69 directory. If the OS image contains multiple partitions marked with
70 the Discoverable Partitions Specification[1] multiple nested mounts
71 are established. This command expects two arguments: a path to an
72 image file and a path to a directory where to mount the image.
73 To unmount an OS image mounted like this use umount(8)'s -R switch
75 (for recursive operation), so that the OS image and all nested
76 partition mounts are unmounted.
77 When the OS image contains LUKS encrypted or Verity integrity
79 protected file systems appropriate volumes are automatically set up
80 and marked for automatic disassembly when the image is unmounted.
81 The OS image may either be specified as path to an OS image stored
83 in a regular file or may refer to block device node (in the latter
84 case the block device must be the "whole" device, i.e. not a
85 partition device). (The other supported commands described here
86 support this, too.)
87 All mounted file systems are checked with the appropriate fsck(8)
89 implementation in automatic fixing mode, unless explicitly turned
90 off (--fsck=no) or read-only operation is requested (--read-only).
91 -M
93 This is a shortcut for --mount --mkdir.
94 --copy-from, -x
96 Copies a file or directory from the specified OS image into the
97 specified location on the host file system. Expects three
98 arguments: a path to an image file, a source path (relative to the
99 image's root directory) and a destination path (relative to the
100 current working directory, or an absolute path, both outside of the
101 image). If the destination path is omitted or specified as dash
102 ("-"), the specified file is written to standard output. If the
103 source path in the image file system refers to a regular file it is
104 copied to the destination path. In this case access mode, extended
105 attributes and timestamps are copied as well, but file ownership is
106 not. If the source path in the image refers to a directory, it is
107 copied to the destination path, recursively with all containing
108 files and directories. In this case the file ownership is copied
109 too.
110 --copy-to, -a
112 Copies a file or directory from the specified location in the host
113 file system into the specified OS image. Expects three arguments: a
114 path to an image file, a source path (relative to the current
115 working directory, or an absolute path, both outside of the image)
116 and a destination path (relative to the image's root directory). If
117 the source path is omitted or specified as dash ("-"), the data to
118 write is read from standard input. If the source path in the host
119 file system refers to a regular file, it is copied to the
120 destination path. In this case access mode, extended attributes and
121 timestamps are copied as well, but file ownership is not. If the
122 source path in the host file system refers to a directory it is
123 copied to the destination path, recursively with all containing
124 files and directories. In this case the file ownership is copied
125 too.
126 As with --mount file system checks are implicitly run before the
128 copy operation begins.
129 -h, --help
131 Print a short help text and exit.
132 --version
134 Print a short version string and exit.
135
137 The following options are understood:
138 --read-only, -r
140 Operate in read-only mode. By default --mount will establish
141 writable mount points. If this option is specified they are
142 established in read-only mode instead.
143 --fsck=no
145 Turn off automatic file system checking. By default when an image
146 is accessed for writing (by --mount or --copy-to) the file systems
147 contained in the OS image are automatically checked using the
148 appropriate fsck(8) command, in automatic fixing mode. This
149 behavior may be switched off using --fsck=no.
150 --growfs=no
152 Turn off automatic growing of accessed file systems to their
153 partition size, if marked for that in the GPT partition table. By
154 default when an image is accessed for writing (by --mount or
155 --copy-to) the file systems contained in the OS image are
156 automatically grown to their partition sizes, if bit 59 in the GPT
157 partition flags is set for partition types that are defined by the
158 Discoverable Partitions Specification[1]. This behavior may be
159 switched off using --growfs=no. File systems are grown
160 automatically on access if all of the following conditions are met:
161 1. The file system is mounted writable
163 2. The file system currently is smaller than the partition it is
165 contained in (and thus can be grown)
166 3. The image contains a GPT partition table
168 4. The file system is stored on a partition defined by the
170 Discoverable Partitions Specification
171 5. Bit 59 of the GPT partition flags for this partition is set, as
173 per specification
174 6. The --growfs=no option is not passed.
176 --mkdir
178 If combined with --mount the directory to mount the OS image to is
179 created if it is missing. Note that the directory is not
180 automatically removed when the disk image is unmounted again.
181 --discard=
183 Takes one of "disabled", "loop", "all", "crypto". If "disabled" the
184 image is accessed with empty block discarding turned off. If "loop"
185 discarding is enabled if operating on a regular file. If "crypt"
186 discarding is enabled even on encrypted file systems. If "all"
187 discarding is unconditionally enabled.
188 --root-hash=, --root-hash-sig=, --verity-data=
190 Configure various aspects of Verity data integrity for the OS
191 image. Option --root-hash= specifies a hex-encoded top-level Verity
192 hash to use for setting up the Verity integrity protection. Option
193 --root-hash-sig= specifies the path to a file containing a PKCS#7
194 signature for the hash. This signature is passed to the kernel
195 during activation, which will match it against signature keys
196 available in the kernel keyring. Option --verity-data= specifies a
197 path to a file with the Verity data to use for the OS image, in
198 case it is stored in a detached file. It is recommended to embed
199 the Verity data directly in the image, using the Verity mechanisms
200 in the Discoverable Partitions Specification[1].
201 --no-pager
203 Do not pipe output into a pager.
204 --no-legend
206 Do not print the legend, i.e. column headers and the footer with
207 hints.
208 --json=MODE
210 Shows output formatted as JSON. Expects one of "short" (for the
211 shortest possible output without any redundant whitespace or line
212 breaks), "pretty" (for a pretty version of the same, with
213 indentation and line breaks) or "off" (to turn off JSON output, the
214 default).
215
217 On success, 0 is returned, a non-zero failure code otherwise.
218
220 systemd(1), systemd-nspawn(1), systemd.exec(5), Discoverable Partitions
221 Specification[1], umount(8), fdisk(8)
222
224 1. Discoverable Partitions Specification
225 https://systemd.io/DISCOVERABLE_PARTITIONS
226systemd 251 SYSTEMD-DISSECT(1)