1SYSTEMD-DISSECT(1) systemd-dissect SYSTEMD-DISSECT(1)
2
6 systemd-dissect - Dissect Discoverable Disk Images (DDIs)
7
9 systemd-dissect [OPTIONS...] IMAGE
10 systemd-dissect [OPTIONS...] --mount IMAGE PATH
12 systemd-dissect [OPTIONS...] --umount PATH
14 systemd-dissect [OPTIONS...] --list IMAGE
16 systemd-dissect [OPTIONS...] --mtree IMAGE
18 systemd-dissect [OPTIONS...] --with IMAGE [COMMAND...]
20 systemd-dissect [OPTIONS...] --copy-from IMAGE PATH [TARGET]
22 systemd-dissect [OPTIONS...] --copy-to IMAGE [SOURCE] PATH
24 systemd-dissect [OPTIONS...] --discover
26
28 systemd-dissect is a tool for introspecting and interacting with file
29 system OS disk images, specifically Discoverable Disk Images (DDIs). It
30 supports four different operations:
31 1. Show general OS image information, including the image's os-
33 release(5) data, machine ID, partition information and more.
34 2. Mount an OS image to a local directory. In this mode it will
36 dissect the OS image and mount the included partitions according to
37 their designation onto a directory and possibly sub-directories.
38 3. Unmount an OS image from a local directory. In this mode it will
40 recursively unmount the mounted partitions and remove the
41 underlying loop device, including all the partition sub-devices.
42 4. Copy files and directories in and out of an OS image.
44 The tool may operate on three types of OS images:
46 1. OS disk images containing a GPT partition table envelope, with
48 partitions marked according to the Discoverable Partitions
49 Specification[1].
50 2. OS disk images containing just a plain file-system without an
52 enveloping partition table. (This file system is assumed to be the
53 root file system of the OS.)
54 3. OS disk images containing a GPT or MBR partition table, with a
56 single partition only. (This partition is assumed to contain the
57 root file system of the OS.)
58 OS images may use any kind of Linux-supported file systems. In addition
60 they may make use of LUKS disk encryption, and contain Verity integrity
61 information. Note that qualifying OS images may be booted with systemd-
62 nspawn(1)'s --image= switch, and be used as root file system for system
63 service using the RootImage= unit file setting, see systemd.exec(5).
64 Note that the partition table shown when invoked without command switch
66 (as listed below) does not necessarily show all partitions included in
67 the image, but just the partitions that are understood and considered
68 part of an OS disk image. Specifically, partitions of unknown types are
69 ignored, as well as duplicate partitions (i.e. more than one per
70 partition type), as are root and /usr/ partitions of architectures not
71 compatible with the local system. In other words: this tool will
72 display what it operates with when mounting the image. To display the
73 complete list of partitions use a tool such as fdisk(8).
74
76 If neither of the command switches listed below are passed the
77 specified disk image is opened and general information about the image
78 and the contained partitions and their use is shown.
79 --mount, -m
81 Mount the specified OS image to the specified directory. This will
82 dissect the image, determine the OS root file system — as well as
83 possibly other partitions — and mount them to the specified
84 directory. If the OS image contains multiple partitions marked with
85 the Discoverable Partitions Specification[1] multiple nested mounts
86 are established. This command expects two arguments: a path to an
87 image file and a path to a directory where to mount the image.
88 To unmount an OS image mounted like this use the --umount
90 operation.
91 When the OS image contains LUKS encrypted or Verity integrity
93 protected file systems appropriate volumes are automatically set up
94 and marked for automatic disassembly when the image is unmounted.
95 The OS image may either be specified as path to an OS image stored
97 in a regular file or may refer to block device node (in the latter
98 case the block device must be the "whole" device, i.e. not a
99 partition device). (The other supported commands described here
100 support this, too.)
101 All mounted file systems are checked with the appropriate fsck(8)
103 implementation in automatic fixing mode, unless explicitly turned
104 off (--fsck=no) or read-only operation is requested (--read-only).
105 -M
107 This is a shortcut for --mount --mkdir.
108 --umount, -u
110 Unmount an OS image from the specified directory. This command
111 expects one argument: a directory where an OS image was mounted.
112 All mounted partitions will be recursively unmounted, and the
114 underlying loop device will be removed, along with all its
115 partition sub-devices.
116 -U
118 This is a shortcut for --umount --rmdir.
119 --list, -l
121 Prints the paths of all the files and directories in the specified
122 OS image to standard output.
123 --mtree
125 Generates a BSD mtree(8) compatible file manifest of the specified
126 disk image. This is useful for comparing disk image contents in
127 detail, including inode information and other metadata. While the
128 generated manifest will contain detailed inode information, it
129 currently excludes extended attributes, file system capabilities,
130 MAC labels, chattr(1) file flags, btrfs(5) subvolume information,
131 and various other file metadata. File content information is shown
132 via a SHA256 digest. Additional fields might be added in future.
133 Note that inode information such as link counts, inode numbers and
134 timestamps is excluded from the output on purpose, as it typically
135 complicates reproducibility.
136 --with
138 Runs the specified command with the specified OS image mounted.
139 This will mount the image to a temporary directory, switch the
140 current working directory to it, and invoke the specified command
141 line as child process. Once the process ends it will unmount the
142 image again, and remove the temporary directory. If no command is
143 specified a shell is invoked. The image is mounted writable, use
144 --read-only to switch to read-only operation. The invoked process
145 will have the $SYSTEMD_DISSECT_ROOT environment variable set,
146 containing the absolute path name of the temporary mount point,
147 i.e. the same directory that is set as the current working
148 directory.
149 --copy-from, -x
151 Copies a file or directory from the specified OS image into the
152 specified location on the host file system. Expects three
153 arguments: a path to an image file, a source path (relative to the
154 image's root directory) and a destination path (relative to the
155 current working directory, or an absolute path, both outside of the
156 image). If the destination path is omitted or specified as dash
157 ("-"), the specified file is written to standard output. If the
158 source path in the image file system refers to a regular file it is
159 copied to the destination path. In this case access mode, extended
160 attributes and timestamps are copied as well, but file ownership is
161 not. If the source path in the image refers to a directory, it is
162 copied to the destination path, recursively with all containing
163 files and directories. In this case the file ownership is copied
164 too.
165 --copy-to, -a
167 Copies a file or directory from the specified location in the host
168 file system into the specified OS image. Expects three arguments: a
169 path to an image file, a source path (relative to the current
170 working directory, or an absolute path, both outside of the image)
171 and a destination path (relative to the image's root directory). If
172 the source path is omitted or specified as dash ("-"), the data to
173 write is read from standard input. If the source path in the host
174 file system refers to a regular file, it is copied to the
175 destination path. In this case access mode, extended attributes and
176 timestamps are copied as well, but file ownership is not. If the
177 source path in the host file system refers to a directory it is
178 copied to the destination path, recursively with all containing
179 files and directories. In this case the file ownership is copied
180 too.
181 As with --mount file system checks are implicitly run before the
183 copy operation begins.
184 --discover
186 Show a list of DDIs in well-known directories. This will show
187 machine, portable service and system extension disk images in the
188 usual directories /usr/lib/machines/, /usr/lib/portables/,
189 /usr/lib/extensions/, /var/lib/machines/, /var/lib/portables/,
190 /var/lib/extensions/ and so on.
191 -h, --help
193 Print a short help text and exit.
194 --version
196 Print a short version string and exit.
197
199 The following options are understood:
200 --read-only, -r
202 Operate in read-only mode. By default --mount will establish
203 writable mount points. If this option is specified they are
204 established in read-only mode instead.
205 --fsck=no
207 Turn off automatic file system checking. By default when an image
208 is accessed for writing (by --mount or --copy-to) the file systems
209 contained in the OS image are automatically checked using the
210 appropriate fsck(8) command, in automatic fixing mode. This
211 behavior may be switched off using --fsck=no.
212 --growfs=no
214 Turn off automatic growing of accessed file systems to their
215 partition size, if marked for that in the GPT partition table. By
216 default when an image is accessed for writing (by --mount or
217 --copy-to) the file systems contained in the OS image are
218 automatically grown to their partition sizes, if bit 59 in the GPT
219 partition flags is set for partition types that are defined by the
220 Discoverable Partitions Specification[1]. This behavior may be
221 switched off using --growfs=no. File systems are grown
222 automatically on access if all of the following conditions are met:
223 1. The file system is mounted writable
225 2. The file system currently is smaller than the partition it is
227 contained in (and thus can be grown)
228 3. The image contains a GPT partition table
230 4. The file system is stored on a partition defined by the
232 Discoverable Partitions Specification
233 5. Bit 59 of the GPT partition flags for this partition is set, as
235 per specification
236 6. The --growfs=no option is not passed.
238 --mkdir
240 If combined with --mount the directory to mount the OS image to is
241 created if it is missing. Note that the directory is not
242 automatically removed when the disk image is unmounted again.
243 --rmdir
245 If combined with --umount the specified directory where the OS
246 image is mounted is removed after unmounting the OS image.
247 --discard=
249 Takes one of "disabled", "loop", "all", "crypto". If "disabled" the
250 image is accessed with empty block discarding turned off. If "loop"
251 discarding is enabled if operating on a regular file. If "crypt"
252 discarding is enabled even on encrypted file systems. If "all"
253 discarding is unconditionally enabled.
254 --in-memory
256 If specified an in-memory copy of the specified disk image is used.
257 This may be used to operate with write-access on a (possibly
258 read-only) image, without actually modifying the original file.
259 This may also be used in order to operate on a disk image without
260 keeping the originating file system busy, in order to allow it to
261 be unmounted.
262 --root-hash=, --root-hash-sig=, --verity-data=
264 Configure various aspects of Verity data integrity for the OS
265 image. Option --root-hash= specifies a hex-encoded top-level Verity
266 hash to use for setting up the Verity integrity protection. Option
267 --root-hash-sig= specifies the path to a file containing a PKCS#7
268 signature for the hash. This signature is passed to the kernel
269 during activation, which will match it against signature keys
270 available in the kernel keyring. Option --verity-data= specifies a
271 path to a file with the Verity data to use for the OS image, in
272 case it is stored in a detached file. It is recommended to embed
273 the Verity data directly in the image, using the Verity mechanisms
274 in the Discoverable Partitions Specification[1].
275 --no-pager
277 Do not pipe output into a pager.
278 --no-legend
280 Do not print the legend, i.e. column headers and the footer with
281 hints.
282 --json=MODE
284 Shows output formatted as JSON. Expects one of "short" (for the
285 shortest possible output without any redundant whitespace or line
286 breaks), "pretty" (for a pretty version of the same, with
287 indentation and line breaks) or "off" (to turn off JSON output, the
288 default).
289
291 On success, 0 is returned, a non-zero failure code otherwise. If the
292 --with command is used the exit status of the invoked command is
293 propagated.
294
296 Example 1. Generate a tarball from an OS disk image
297 $ systemd-dissect --with foo.raw tar cz . >foo.tar.gz
299
301 systemd(1), systemd-nspawn(1), systemd.exec(5), Discoverable Partitions
302 Specification[1], umount(8), fdisk(8)
303
305 1. Discoverable Partitions Specification
306 https://uapi-group.org/specifications/specs/discoverable_partitions_specification
307systemd 253 SYSTEMD-DISSECT(1)