1SYSTEMD-DISSECT(1)              systemd-dissect             SYSTEMD-DISSECT(1)
2
3
4

NAME

6       systemd-dissect - Dissect file system OS images
7

SYNOPSIS

9       systemd-dissect [OPTIONS...] IMAGE
10
11       systemd-dissect [OPTIONS...] --mount IMAGE PATH
12
13       systemd-dissect [OPTIONS...] --copy-from IMAGE PATH [TARGET]
14
15       systemd-dissect [OPTIONS...] --copy-to IMAGE [SOURCE] PATH
16

DESCRIPTION

18       systemd-dissect is a tool for introspecting and interacting with file
19       system OS disk images. It supports four different operations:
20
21        1. Show general OS image information, including the image's os-
22           release(5) data, machine ID, partition information and more.
23
24        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
28        3. Copy files and directories in and out of an OS image.
29
30       The tool may operate on three types of OS images:
31
32        1. OS disk images containing a GPT partition table envelope, with
33           partitions marked according to the Discoverable Partitions
34           Specification[1].
35
36        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
40        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
44       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
50       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

COMMANDS

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
65       --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
74           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
78           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
82           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
88           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
92       -M
93           This is a shortcut for --mount --mkdir.
94
95       --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
111       --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
127           As with --mount file system checks are implicitly run before the
128           copy operation begins.
129
130       -h, --help
131           Print a short help text and exit.
132
133       --version
134           Print a short version string and exit.
135

OPTIONS

137       The following options are understood:
138
139       --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
144       --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
151       --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
162            1. The file system is mounted writable
163
164            2. The file system currently is smaller than the partition it is
165               contained in (and thus can be grown)
166
167            3. The image contains a GPT partition table
168
169            4. The file system is stored on a partition defined by the
170               Discoverable Partitions Specification
171
172            5. Bit 59 of the GPT partition flags for this partition is set, as
173               per specification
174
175            6. The --growfs=no option is not passed.
176
177       --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
182       --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
189       --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
202       --no-pager
203           Do not pipe output into a pager.
204
205       --no-legend
206           Do not print the legend, i.e. column headers and the footer with
207           hints.
208
209       --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

EXIT STATUS

217       On success, 0 is returned, a non-zero failure code otherwise.
218

SEE ALSO

220       systemd(1), systemd-nspawn(1), systemd.exec(5), Discoverable Partitions
221       Specification[1], umount(8), fdisk(8)
222

NOTES

224        1. Discoverable Partitions Specification
225           https://systemd.io/DISCOVERABLE_PARTITIONS
226
227
228
229systemd 251                                                 SYSTEMD-DISSECT(1)
Impressum