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 --add) 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 --mkdir
152 If combined with --mount the directory to mount the OS image to is
153 created if it is missing. Note that the directory is not
154 automatically removed when the disk image is unmounted again.
155 --discard=
157 Takes one of "disabled", "loop", "all", "crypto". If "disabled" the
158 image is accessed with empty block discarding turned off. If "loop"
159 discarding is enabled if operating on a regular file. If "crypt"
160 discarding is enabled even on encrypted file systems. If "all"
161 discarding is unconditionally enabled.
162 --root-hash=, --root-hash-sig=, --verity-data=
164 Configure various aspects of Verity data integrity for the OS
165 image. Option --root-hash= specifies a hex-encoded top-level Verity
166 hash to use for setting up the Verity integrity protection. Option
167 --root-hash-sig= specifies the path to a file containing a PKCS#7
168 signature for the hash. This signature is passed to the kernel
169 during activation, which will match it against signature keys
170 available in the kernel keyring. Option --verity-data= specifies a
171 path to a file with the Verity data to use for the OS image, in
172 case it is stored in a detached file. It is recommended to embed
173 the Verity data directly in the image, using the Verity mechanisms
174 in the Discoverable Partitions Specification[1].
175 --no-pager
177 Do not pipe output into a pager.
178 --no-legend
180 Do not print the legend, i.e. column headers and the footer with
181 hints.
182 --json=MODE
184 Shows output formatted as JSON. Expects one of "short" (for the
185 shortest possible output without any redundant whitespace or line
186 breaks), "pretty" (for a pretty version of the same, with
187 indentation and line breaks) or "off" (to turn off JSON output, the
188 default).
189
191 On success, 0 is returned, a non-zero failure code otherwise.
192
194 systemd(1), systemd-nspawn(1), systemd.exec(5), Discoverable Partitions
195 Specification[1], umount(8), fdisk(8)
196
198 1. Discoverable Partitions Specification
199 https://systemd.io/DISCOVERABLE_PARTITIONS
200systemd 248 SYSTEMD-DISSECT(1)