Debian Codegraph @

upstream/debian-unstable/man1/systemd-mstack.1

raw
1 '\" t
2 .TH "SYSTEMD\-MSTACK" "1" "" "systemd 261~rc3" "systemd-mstack"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-mstack, mount.mstack \- Mstack Discoverable Disk Images (DDIs)
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-mstack\fR\ 'u
26 \fBsystemd\-mstack\fR [OPTIONS...] \fIIMAGE\fR
27 .HP \w'\fBsystemd\-mstack\fR\ 'u
28 \fBsystemd\-mstack\fR [OPTIONS...] [\-\-mount] \fIIMAGE\fR \fIPATH\fR
29 .HP \w'\fBsystemd\-mstack\fR\ 'u
30 \fBsystemd\-mstack\fR [OPTIONS...] [\-\-umount] \fIPATH\fR
31 .SH "DESCRIPTION"
32 .PP
33 \fBsystemd\-mstack\fR
34 is a tool for introspecting and interacting with
35 \&.mstack/
36 mount stack directories, as described in
37 \fBsystemd.mstack\fR(7)\&. It supports three different operations:
38 .sp
39 .RS 4
40 .ie n \{\
41 \h'-04' 1.\h'+01'\c
42 .\}
43 .el \{\
44 .sp -1
45 .IP " 1." 4.2
46 .\}
47 Show general mount stack information, including all described
48 "overlayfs"
49 layers and bind mounts\&.
50 .RE
51 .sp
52 .RS 4
53 .ie n \{\
54 \h'-04' 2.\h'+01'\c
55 .\}
56 .el \{\
57 .sp -1
58 .IP " 2." 4.2
59 .\}
60 Mount a mount stack to a local directory\&.
61 .RE
62 .sp
63 .RS 4
64 .ie n \{\
65 \h'-04' 3.\h'+01'\c
66 .\}
67 .el \{\
68 .sp -1
69 .IP " 3." 4.2
70 .\}
71 Unmount a mount stack from a local directory\&.
72 .RE
73 .PP
74 The
75 \fBsystemd\-mstack\fR
76 command may be invoked as
77 \fBmount\&.mstack\fR
78 in which case it implements the
79 \fBmount\fR(8)
80 "external helper" interface\&. This ensures mount stack directories compatible with
81 \fBsystemd\-mstack\fR
82 can be mounted directly by
83 \fBmount\fR
84 and
85 \fBfstab\fR(5)\&. For details see below\&.
86 .PP
87 In place of the image path a
88 "\&.v/"
89 versioned directory may be specified, see
90 \fBsystemd.v\fR(7)
91 for details\&.
92 .SH "COMMANDS"
93 .PP
94 If neither of the command switches listed below are passed the specified mount stack is opened and general information about it is shown, including a list of all defined layers\&.
95 .PP
96 \fB\-\-mount\fR, \fB\-m\fR
97 .RS 4
98 Mount the specified mount stack to the specified directory\&.
99 .sp
100 To unmount a mount stack directory mounted like this use the
101 \fB\-\-umount\fR
102 operation\&.
103 .sp
104 Note that this functionality is also available in
105 \fBmount\fR(8)
106 via a command such as
107 \fBmount \-t mstack mystack\&.mstack targetdir/\fR, as well as in
108 \fBfstab\fR(5)\&. For details, see below\&.
109 .sp
110 Added in version 260\&.
111 .RE
112 .PP
113 \fB\-M\fR
114 .RS 4
115 This is a shortcut for
116 \fB\-\-mount \-\-mkdir\fR\&.
117 .sp
118 Added in version 260\&.
119 .RE
120 .PP
121 \fB\-\-umount\fR, \fB\-u\fR
122 .RS 4
123 Unmount a mount stack from the specified directory\&. This command expects one argument: a directory where mount stack was mounted\&.
124 .sp
125 All mounted mounts will be recursively unmounted
126 .sp
127 Added in version 260\&.
128 .RE
129 .PP
130 \fB\-U\fR
131 .RS 4
132 This is a shortcut for
133 \fB\-\-umount \-\-rmdir\fR\&.
134 .sp
135 Added in version 260\&.
136 .RE
137 .PP
138 \fB\-h\fR, \fB\-\-help\fR
139 .RS 4
140 Print a short help text and exit\&.
141 .RE
142 .PP
143 \fB\-\-version\fR
144 .RS 4
145 Print a short version string and exit\&.
146 .RE
147 .SH "OPTIONS"
148 .PP
149 The following options are understood:
150 .PP
151 \fB\-\-read\-only\fR, \fB\-r\fR
152 .RS 4
153 Operate in read\-only mode\&. By default,
154 \fB\-\-mount\fR
155 will establish writable mount points\&. If this option is specified they are established in read\-only mode instead\&.
156 .sp
157 Added in version 260\&.
158 .RE
159 .PP
160 \fB\-\-mkdir\fR
161 .RS 4
162 If combined with
163 \fB\-\-mount\fR
164 the directory to mount the mount stack to is created if it is missing\&. Note that the directory is not automatically removed when the mount stack is unmounted again\&.
165 .sp
166 Added in version 260\&.
167 .RE
168 .PP
169 \fB\-\-rmdir\fR
170 .RS 4
171 If combined with
172 \fB\-\-umount\fR
173 the specified directory where the mount stack is mounted is removed after unmounting it\&.
174 .sp
175 Added in version 260\&.
176 .RE
177 .PP
178 \fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
179 .RS 4
180 Takes an image policy string as argument, as per
181 \fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
182 \fB\-\-image=\fR, see above\&. If not specified, defaults to the
183 "*"
184 policy, i\&.e\&. all recognized file systems in the image are used\&.
185 .RE
186 .PP
187 \fB\-\-image\-filter=\fR\fB\fIfilter\fR\fR
188 .RS 4
189 Takes an image filter string as argument, as per
190 \fBsystemd.image-filter\fR(7)\&. The filter is taken into consideration when operating on the disk image specified via
191 \fB\-\-image=\fR, see above\&. If not specified no filtering is applied\&.
192 .RE
193 .PP
194 \fB\-\-no\-pager\fR
195 .RS 4
196 Do not pipe output into a pager\&.
197 .RE
198 .PP
199 \fB\-\-no\-legend\fR
200 .RS 4
201 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
202 .RE
203 .PP
204 \fB\-\-json=\fR\fB\fIMODE\fR\fR
205 .RS 4
206 Shows output formatted as JSON\&. Expects one of
207 "short"
208 (for the shortest possible output without any redundant whitespace or line breaks),
209 "pretty"
210 (for a pretty version of the same, with indentation and line breaks) or
211 "off"
212 (to turn off JSON output, the default)\&.
213 .RE
214 .SH "EXIT STATUS"
215 .PP
216 On success, 0 is returned, a non\-zero failure code otherwise\&.
217 .SH "INVOCATION AS /SBIN/MOUNT\&.MSTACK"
218 .PP
219 The
220 \fBsystemd\-mstack\fR
221 executable may be symlinked to
222 /sbin/mount\&.mstack\&. If invoked through that it implements
223 \fBmount\fR(8)\*(Aqs "external helper" interface for the (pseudo) file system type
224 "mstack"\&. This means conformant mount stack directories may be mounted directly via
225 .sp
226 .if n \{\
227 .RS 4
228 .\}
229 .nf
230 # mount \-t mstack mystack\&.mstack targetdir/
231 .fi
232 .if n \{\
233 .RE
234 .\}
235 .PP
236 in a fashion mostly equivalent to:
237 .sp
238 .if n \{\
239 .RS 4
240 .\}
241 .nf
242 # systemd\-mstack \-\-mount mystack\&.mstack targetdir/
243 .fi
244 .if n \{\
245 .RE
246 .\}
247 .PP
248 Note that since a single mount stack may contain multiple mount points it should later be unmounted with
249 \fBumount \-R targetdir/\fR, for recursive operation\&.
250 .PP
251 This functionality is particularly useful to mount mount stacks automatically at boot via simple
252 /etc/fstab
253 entries\&. For example:
254 .sp
255 .if n \{\
256 .RS 4
257 .\}
258 .nf
259 /path/to/mystack\&.nspawn /images/mystack/ mstack defaults 0 0
260 .fi
261 .if n \{\
262 .RE
263 .\}
264 .PP
265 When invoked this way the mount options
266 "ro",
267 "rw"
268 map to the corresponding options listed above (i\&.e\&.
269 \fB\-\-read\-only\fR)\&.
270 .SH "SEE ALSO"
271 .PP
272 \fBsystemd\fR(1), \fBsystemd.mstack\fR(7), \fBsystemd-nspawn\fR(1), \fBsystemd.exec\fR(5), \fBmount\fR(8), \fBumount\fR(8)