Debian Codegraph @

upstream/debian-unstable/man7/systemd.mstack.7

raw
1 '\" t
2 .TH "SYSTEMD\&.MSTACK" "7" "" "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 stacks in self descriptive directories
24 .SH "DESCRIPTION"
25 .PP
26 Directories with the
27 "\&.mstack/"
28 suffix may encode \*(Aqmount stacks\*(Aq for assembling OS mount hierarchies based on bind and overlay mounts, for use in
29 \fBsystemd-nspawn\fR(1)\*(Aqs
30 \fB\-\-mstack=\fR
31 switch or the service manager\*(Aqs
32 \fBRootMStack=\fR
33 setting for services\&.
34 "\&.mstack/"
35 directories may contain various files and subdirectories, where each will effect one layer of an
36 "overlayfs"
37 mount, or a bind mount\&. The name of the file or subdirectory indicates how it shall used in the mount hierarchy\&. Specifically, the following names are defined:
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 A
48 layer@\fIid\fR/
49 directory will be turned into a layer of an overlayfs mount\&. The
50 "id"
51 identifier is used to define the order of the layers: a version sort is executed, with the first entry being the bottom layer in the
52 "overlayfs"
53 stack, and the last entry becoming the highest layer (precisely: highest "lowerdir") in the
54 "overlayfs"
55 stack\&.
56 .RE
57 .sp
58 .RS 4
59 .ie n \{\
60 \h'-04' 2.\h'+01'\c
61 .\}
62 .el \{\
63 .sp -1
64 .IP " 2." 4.2
65 .\}
66 Similar, a
67 layer@\fIid\fR\&.raw
68 regular file will be mounted as a DDI, and the resulting mount will be turned into an overlayfs layer, following the same sorting rules\&.
69 .RE
70 .sp
71 .RS 4
72 .ie n \{\
73 \h'-04' 3.\h'+01'\c
74 .\}
75 .el \{\
76 .sp -1
77 .IP " 3." 4.2
78 .\}
79 An
80 rw
81 directory will be turned into a writable layer at the very top of the
82 "overlayfs"
83 stack\&. A subdirectory
84 data
85 of it will become the "upperdir", a subdirectory
86 work
87 will become the "workdir"\&. Note that these two subdirectories do not need to be created explicitly, they are created automatically on first use should they be missing\&.
88 .RE
89 .sp
90 .RS 4
91 .ie n \{\
92 \h'-04' 4.\h'+01'\c
93 .\}
94 .el \{\
95 .sp -1
96 .IP " 4." 4.2
97 .\}
98 A
99 bind@\fIlocation\fR/
100 directory will be bind mounted to the mount point indicated by the
101 \fIlocation\fR
102 identifier, in read\-write fashion\&. The location is encoded via the same escaping logic used for naming
103 "\&.mount"
104 units, i\&.e\&. slashes become dashes\&.
105 .RE
106 .sp
107 .RS 4
108 .ie n \{\
109 \h'-04' 5.\h'+01'\c
110 .\}
111 .el \{\
112 .sp -1
113 .IP " 5." 4.2
114 .\}
115 Similar, a
116 bind@\fIlocation\fR\&.raw
117 file will be mounted as a DDI, and the resulting mount bind mounted to the specified location\&.
118 .RE
119 .sp
120 .RS 4
121 .ie n \{\
122 \h'-04' 6.\h'+01'\c
123 .\}
124 .el \{\
125 .sp -1
126 .IP " 6." 4.2
127 .\}
128 A
129 robind@\fIlocation\fR/
130 is treated very similar to
131 bind@\fIlocation\fR/, but the resulting bind mount is read\-only\&.
132 .RE
133 .sp
134 .RS 4
135 .ie n \{\
136 \h'-04' 7.\h'+01'\c
137 .\}
138 .el \{\
139 .sp -1
140 .IP " 7." 4.2
141 .\}
142 Similar,
143 robind@\fIlocation\fR\&.raw
144 creates a read\-only bind mount from a DDI\&.
145 .RE
146 .sp
147 .RS 4
148 .ie n \{\
149 \h'-04' 8.\h'+01'\c
150 .\}
151 .el \{\
152 .sp -1
153 .IP " 8." 4.2
154 .\}
155 If a
156 root/
157 subdirectory it is used as root of the resulting mount hierarchy, and only the
158 usr/
159 subtree of the overlayfs mount will be bound to
160 usr/
161 in the hierarchy\&.
162 .RE
163 .PP
164 Note that each of the entry types above may be a symbolic link pointing to a directory or image file, instead a directory or image file itself\&.
165 .PP
166 On each listed file or subdirectory type the
167 \fBsystemd.v\fR(7)
168 functionality may be used, for automatic selection of versioned resources\&.
169 .PP
170 Use the
171 \fBsystemd-mstack\fR(1)
172 tool to process or mount
173 \&.mstack/
174 directories from the command line\&.
175 .SH "EXAMPLES"
176 .PP
177 The following
178 \&.mstack/
179 consists of two read\-only overlayfs layers as DDI, plus one writable directory one on top\&. The read\-only layers are symlinked:
180 .sp
181 .RS 4
182 .ie n \{\
183 \h'-04' 1.\h'+01'\c
184 .\}
185 .el \{\
186 .sp -1
187 .IP " 1." 4.2
188 .\}
189 foobar\&.mstack/layer@0\&.raw
190 →
191 \&.\&./base\&.raw
192 .RE
193 .sp
194 .RS 4
195 .ie n \{\
196 \h'-04' 2.\h'+01'\c
197 .\}
198 .el \{\
199 .sp -1
200 .IP " 2." 4.2
201 .\}
202 foobar\&.mstack/layer@1\&.raw
203 →
204 \&.\&./app\&.raw
205 .RE
206 .sp
207 .RS 4
208 .ie n \{\
209 \h'-04' 3.\h'+01'\c
210 .\}
211 .el \{\
212 .sp -1
213 .IP " 3." 4.2
214 .\}
215 foobar\&.mstack/rw/
216 .RE
217 .PP
218 The following
219 \&.mstack/
220 consists of a read\-only DDI mounted to
221 "/usr/"
222 and writable root:
223 .sp
224 .RS 4
225 .ie n \{\
226 \h'-04' 1.\h'+01'\c
227 .\}
228 .el \{\
229 .sp -1
230 .IP " 1." 4.2
231 .\}
232 waldo\&.mstack/layer@0\&.raw
233 →
234 \&.\&./vendor\&.raw
235 .RE
236 .sp
237 .RS 4
238 .ie n \{\
239 \h'-04' 2.\h'+01'\c
240 .\}
241 .el \{\
242 .sp -1
243 .IP " 2." 4.2
244 .\}
245 waldo\&.mstack/root/
246 .RE
247 .PP
248 The following
249 \&.mstack/
250 consists of a read\-only DDI mounted as root, but a writable
251 /var/
252 mounted on top:
253 .sp
254 .RS 4
255 .ie n \{\
256 \h'-04' 1.\h'+01'\c
257 .\}
258 .el \{\
259 .sp -1
260 .IP " 1." 4.2
261 .\}
262 quux\&.mstack/layer@0\&.raw
263 →
264 \&.\&./myapp1\&.raw
265 .RE
266 .sp
267 .RS 4
268 .ie n \{\
269 \h'-04' 2.\h'+01'\c
270 .\}
271 .el \{\
272 .sp -1
273 .IP " 2." 4.2
274 .\}
275 quux\&.mstack/bind:var
276 →
277 \&.\&./myapp1\-var/
278 .RE
279 .SH "SEE ALSO"
280 .PP
281 \fBsystemd\fR(1), \fBsystemd-mstack\fR(1), \fBsystemd-nspawn\fR(1), \fBsystemd.exec\fR(5), \fBsystemd.v\fR(7), \fBsystemd-vpick\fR(1)