1SYSTEMD-DISSECT(1) systemd-dissect SYSTEMD-DISSECT(1)
2
6 systemd-dissect, mount.ddi - 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...] --attach IMAGE
16 systemd-dissect [OPTIONS...] --detach PATH
18 systemd-dissect [OPTIONS...] --list IMAGE
20 systemd-dissect [OPTIONS...] --mtree IMAGE
22 systemd-dissect [OPTIONS...] --with IMAGE [COMMAND...]
24 systemd-dissect [OPTIONS...] --copy-from IMAGE PATH [TARGET]
26 systemd-dissect [OPTIONS...] --copy-to IMAGE [SOURCE] PATH
28 systemd-dissect [OPTIONS...] --discover
30 systemd-dissect [OPTIONS...] --validate IMAGE
32
34 systemd-dissect is a tool for introspecting and interacting with file
35 system OS disk images, specifically Discoverable Disk Images (DDIs). It
36 supports four different operations:
37 1. Show general OS image information, including the image's os-
39 release(5) data, machine ID, partition information and more.
40 2. Mount an OS image to a local directory. In this mode it will
42 dissect the OS image and mount the included partitions according to
43 their designation onto a directory and possibly sub-directories.
44 3. Unmount an OS image from a local directory. In this mode it will
46 recursively unmount the mounted partitions and remove the
47 underlying loop device, including all the partition sub-devices.
48 4. Copy files and directories in and out of an OS image.
50 The tool may operate on three types of OS images:
52 1. OS disk images containing a GPT partition table envelope, with
54 partitions marked according to the Discoverable Partitions
55 Specification[1].
56 2. OS disk images containing just a plain file-system without an
58 enveloping partition table. (This file system is assumed to be the
59 root file system of the OS.)
60 3. OS disk images containing a GPT or MBR partition table, with a
62 single partition only. (This partition is assumed to contain the
63 root file system of the OS.)
64 OS images may use any kind of Linux-supported file systems. In addition
66 they may make use of LUKS disk encryption, and contain Verity integrity
67 information. Note that qualifying OS images may be booted with systemd-
68 nspawn(1)'s --image= switch, and be used as root file system for system
69 service using the RootImage= unit file setting, see systemd.exec(5).
70 Note that the partition table shown when invoked without command switch
72 (as listed below) does not necessarily show all partitions included in
73 the image, but just the partitions that are understood and considered
74 part of an OS disk image. Specifically, partitions of unknown types are
75 ignored, as well as duplicate partitions (i.e. more than one per
76 partition type), as are root and /usr/ partitions of architectures not
77 compatible with the local system. In other words: this tool will
78 display what it operates with when mounting the image. To display the
79 complete list of partitions use a tool such as fdisk(8).
80 The systemd-dissect command may be invoked as mount.ddi in which case
82 it implements the mount(8) "external helper" interface. This ensures
83 disk images compatible with systemd-dissect can be mounted directly by
84 mount and fstab(5). For details see below.
85
87 If neither of the command switches listed below are passed the
88 specified disk image is opened and general information about the image
89 and the contained partitions and their use is shown.
90 --mount, -m
92 Mount the specified OS image to the specified directory. This will
93 dissect the image, determine the OS root file system — as well as
94 possibly other partitions — and mount them to the specified
95 directory. If the OS image contains multiple partitions marked with
96 the Discoverable Partitions Specification[1] multiple nested mounts
97 are established. This command expects two arguments: a path to an
98 image file and a path to a directory where to mount the image.
99 To unmount an OS image mounted like this use the --umount
101 operation.
102 When the OS image contains LUKS encrypted or Verity integrity
104 protected file systems appropriate volumes are automatically set up
105 and marked for automatic disassembly when the image is unmounted.
106 The OS image may either be specified as path to an OS image stored
108 in a regular file or may refer to block device node (in the latter
109 case the block device must be the "whole" device, i.e. not a
110 partition device). (The other supported commands described here
111 support this, too.)
112 All mounted file systems are checked with the appropriate fsck(8)
114 implementation in automatic fixing mode, unless explicitly turned
115 off (--fsck=no) or read-only operation is requested (--read-only).
116 Note that this functionality is also available in mount(8) via a
118 command such as mount -t ddi myimage.raw targetdir/, as well as in
119 fstab(5). For details, see below.
120 -M
122 This is a shortcut for --mount --mkdir.
123 --umount, -u
125 Unmount an OS image from the specified directory. This command
126 expects one argument: a directory where an OS image was mounted.
127 All mounted partitions will be recursively unmounted, and the
129 underlying loop device will be removed, along with all its
130 partition sub-devices.
131 -U
133 This is a shortcut for --umount --rmdir.
134 --attach
136 Attach the specified disk image to an automatically allocated
137 loopback block device, and print the path to the loopback block
138 device to standard output. This is similar to an invocation of
139 losetup --find --show, but will validate the image as DDI before
140 attaching, and derive the correct sector size to use automatically.
141 Moreover, it ensures the per-partition block devices are created
142 before returning. Takes a path to a disk image file.
143 --detach
145 Detach the specified disk image from a loopback block device. This
146 undoes the effect of --attach above. This expects either a path to
147 a loopback block device as an argument, or the path to the backing
148 image file. In the latter case it will automatically determine the
149 right device to detach.
150 --list, -l
152 Prints the paths of all the files and directories in the specified
153 OS image or directory to standard output.
154 --mtree
156 Generates a BSD mtree(8) compatible file manifest of the specified
157 disk image or directory. This is useful for comparing image
158 contents in detail, including inode information and other metadata.
159 While the generated manifest will contain detailed inode
160 information, it currently excludes extended attributes, file system
161 capabilities, MAC labels, chattr(1) file flags, btrfs(5) subvolume
162 information, and various other file metadata. File content
163 information is shown via a SHA256 digest. Additional fields might
164 be added in future. Note that inode information such as link
165 counts, inode numbers and timestamps is excluded from the output on
166 purpose, as it typically complicates reproducibility.
167 --with
169 Runs the specified command with the specified OS image mounted.
170 This will mount the image to a temporary directory, switch the
171 current working directory to it, and invoke the specified command
172 line as child process. Once the process ends it will unmount the
173 image again, and remove the temporary directory. If no command is
174 specified a shell is invoked. The image is mounted writable, use
175 --read-only to switch to read-only operation. The invoked process
176 will have the $SYSTEMD_DISSECT_ROOT environment variable set,
177 containing the absolute path name of the temporary mount point,
178 i.e. the same directory that is set as the current working
179 directory.
180 --copy-from, -x
182 Copies a file or directory from the specified OS image or directory
183 into the specified location on the host file system. Expects three
184 arguments: a path to an image file or directory, a source path
185 (relative to the image's root directory) and a destination path
186 (relative to the current working directory, or an absolute path,
187 both outside of the image). If the destination path is omitted or
188 specified as dash ("-"), the specified file is written to standard
189 output. If the source path in the image file system refers to a
190 regular file it is copied to the destination path. In this case
191 access mode, extended attributes and timestamps are copied as well,
192 but file ownership is not. If the source path in the image refers
193 to a directory, it is copied to the destination path, recursively
194 with all containing files and directories. In this case the file
195 ownership is copied too.
196 --copy-to, -a
198 Copies a file or directory from the specified location in the host
199 file system into the specified OS image or directory. Expects three
200 arguments: a path to an image file or directory, a source path
201 (relative to the current working directory, or an absolute path,
202 both outside of the image) and a destination path (relative to the
203 image's root directory). If the source path is omitted or specified
204 as dash ("-"), the data to write is read from standard input. If
205 the source path in the host file system refers to a regular file,
206 it is copied to the destination path. In this case access mode,
207 extended attributes and timestamps are copied as well, but file
208 ownership is not. If the source path in the host file system refers
209 to a directory it is copied to the destination path, recursively
210 with all containing files and directories. In this case the file
211 ownership is copied too.
212 As with --mount file system checks are implicitly run before the
214 copy operation begins.
215 --discover
217 Show a list of DDIs in well-known directories. This will show
218 machine, portable service and system/configuration extension disk
219 images in the usual directories /usr/lib/machines/,
220 /usr/lib/portables/, /usr/lib/confexts/, /var/lib/machines/,
221 /var/lib/portables/, /var/lib/extensions/ and so on.
222 --validate
224 Validates the partition arrangement of a disk image (DDI), and
225 ensures it matches the image policy specified via --image-policy=,
226 if one is specified. This parses the partition table and probes the
227 file systems in the image, but does not attempt to mount them (nor
228 to set up disk encryption/authentication via LUKS/Verity). It does
229 this taking the configured image dissection policy into account.
230 Since this operation does not mount file systems, this command –
231 unlike all other commands implemented by this tool – requires no
232 privileges other than the ability to access the specified file.
233 Prints "OK" and returns zero if the image appears to be in order
234 and matches the specified image dissection policy. Otherwise prints
235 an error message and returns non-zero.
236 -h, --help
238 Print a short help text and exit.
239 --version
241 Print a short version string and exit.
242
244 The following options are understood:
245 --read-only, -r
247 Operate in read-only mode. By default --mount will establish
248 writable mount points. If this option is specified they are
249 established in read-only mode instead.
250 --fsck=no
252 Turn off automatic file system checking. By default when an image
253 is accessed for writing (by --mount or --copy-to) the file systems
254 contained in the OS image are automatically checked using the
255 appropriate fsck(8) command, in automatic fixing mode. This
256 behavior may be switched off using --fsck=no.
257 --growfs=no
259 Turn off automatic growing of accessed file systems to their
260 partition size, if marked for that in the GPT partition table. By
261 default when an image is accessed for writing (by --mount or
262 --copy-to) the file systems contained in the OS image are
263 automatically grown to their partition sizes, if bit 59 in the GPT
264 partition flags is set for partition types that are defined by the
265 Discoverable Partitions Specification[1]. This behavior may be
266 switched off using --growfs=no. File systems are grown
267 automatically on access if all of the following conditions are met:
268 1. The file system is mounted writable
270 2. The file system currently is smaller than the partition it is
272 contained in (and thus can be grown)
273 3. The image contains a GPT partition table
275 4. The file system is stored on a partition defined by the
277 Discoverable Partitions Specification
278 5. Bit 59 of the GPT partition flags for this partition is set, as
280 per specification
281 6. The --growfs=no option is not passed.
283 --mkdir
285 If combined with --mount the directory to mount the OS image to is
286 created if it is missing. Note that the directory is not
287 automatically removed when the disk image is unmounted again.
288 --rmdir
290 If combined with --umount the specified directory where the OS
291 image is mounted is removed after unmounting the OS image.
292 --discard=
294 Takes one of "disabled", "loop", "all", "crypto". If "disabled" the
295 image is accessed with empty block discarding turned off. If "loop"
296 discarding is enabled if operating on a regular file. If "crypt"
297 discarding is enabled even on encrypted file systems. If "all"
298 discarding is unconditionally enabled.
299 --in-memory
301 If specified an in-memory copy of the specified disk image is used.
302 This may be used to operate with write-access on a (possibly
303 read-only) image, without actually modifying the original file.
304 This may also be used in order to operate on a disk image without
305 keeping the originating file system busy, in order to allow it to
306 be unmounted.
307 --root-hash=, --root-hash-sig=, --verity-data=
309 Configure various aspects of Verity data integrity for the OS
310 image. Option --root-hash= specifies a hex-encoded top-level Verity
311 hash to use for setting up the Verity integrity protection. Option
312 --root-hash-sig= specifies the path to a file containing a PKCS#7
313 signature for the hash. This signature is passed to the kernel
314 during activation, which will match it against signature keys
315 available in the kernel keyring. Option --verity-data= specifies a
316 path to a file with the Verity data to use for the OS image, in
317 case it is stored in a detached file. It is recommended to embed
318 the Verity data directly in the image, using the Verity mechanisms
319 in the Discoverable Partitions Specification[1].
320 --loop-ref=
322 Configures the "reference" string the kernel shall report as
323 backing file for the loopback block device. While this is supposed
324 to be a path or filename referencing the backing file, this is not
325 enforced and the kernel accepts arbitrary free-form strings, chosen
326 by the user. Accepts arbitrary strings up to a length of 63
327 characters. This sets the kernel's ".lo_file_name" field for the
328 block device. Note this is distinct from the
329 /sys/class/block/loopX/loop/backing_file attribute file that always
330 reports a path referring to the actual backing file. The latter is
331 subject to mount namespace translation, the former is not.
332 --mtree-hash=no
334 If combined with --mtree, turns off inclusion of file hashes in the
335 mtree output. This makes the --mtree faster when operating on large
336 images.
337 --image-policy=policy
339 Takes an image policy string as argument, as per systemd.image-
340 policy(7). The policy is enforced when operating on the disk image
341 specified via --image=, see above. If not specified defaults to the
342 "*" policy, i.e. all recognized file systems in the image are used.
343 --no-pager
345 Do not pipe output into a pager.
346 --no-legend
348 Do not print the legend, i.e. column headers and the footer with
349 hints.
350 --json=MODE
352 Shows output formatted as JSON. Expects one of "short" (for the
353 shortest possible output without any redundant whitespace or line
354 breaks), "pretty" (for a pretty version of the same, with
355 indentation and line breaks) or "off" (to turn off JSON output, the
356 default).
357
359 On success, 0 is returned, a non-zero failure code otherwise. If the
360 --with command is used the exit status of the invoked command is
361 propagated.
362
364 The systemd-dissect executable may be symlinked to /sbin/mount.ddi. If
365 invoked through that it implements mount(8)'s "external helper"
366 interface for the (pseudo) file system type "ddi". This means
367 conformant disk images may be mounted directly via
368 # mount -t ddi myimage.raw targetdir/
370 in a fashion mostly equivalent to:
372 # systemd-dissect --mount myimage.raw targetdir/
374 Note that since a single DDI may contain multiple file systems it
376 should later be unmounted with umount -R targetdir/, for recursive
377 operation.
378 This functionality is particularly useful to mount DDIs automatically
380 at boot via simple /etc/fstab entries. For example:
381 /path/to/myimage.raw /images/myimage/ ddi defaults 0 0
383 When invoked this way the mount options "ro", "rw", "discard",
385 "nodiscard" map to the corresponding options listed above (i.e.
386 --read-only, --discard=all, --discard=disabled). Mount options are not
387 generically passed on to the file systems inside the images.
388
390 Example 1. Generate a tarball from an OS disk image
391 # systemd-dissect --with foo.raw tar cz . >foo.tar.gz
393
395 systemd(1), systemd-nspawn(1), systemd.exec(5), Discoverable Partitions
396 Specification[1], mount(8), umount(8), fdisk(8)
397
399 1. Discoverable Partitions Specification
400 https://uapi-group.org/specifications/specs/discoverable_partitions_specification
401systemd 254 SYSTEMD-DISSECT(1)