Debian Codegraph @

upstream/debian-unstable/man7/mount_namespaces.7

raw
1 '\" t
2 .\" Copyright 2016-2021, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH mount_namespaces 7 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mount_namespaces \- overview of Linux mount namespaces
10 .SH DESCRIPTION
11 For an overview of namespaces, see
12 .BR namespaces (7).
13 .P
14 Mount namespaces provide isolation of the list of mounts seen
15 by the processes in each namespace instance.
16 Thus, the processes in each of the mount namespace instances
17 will see distinct single-directory hierarchies.
18 .P
19 The views provided by the
20 .IR /proc/ pid /mounts ,
21 .IR /proc/ pid /mountinfo ,
22 and
23 .IR /proc/ pid /mountstats
24 files (all described in
25 .BR proc (5))
26 correspond to the mount namespace in which the process with the PID
27 .I pid
28 resides.
29 (All of the processes that reside in the same mount namespace
30 will see the same view in these files.)
31 .P
32 A new mount namespace is created using either
33 .BR clone (2)
34 or
35 .BR unshare (2)
36 with the
37 .B CLONE_NEWNS
38 flag.
39 When a new mount namespace is created,
40 its mount list is initialized as follows:
41 .IP \[bu] 3
42 If the namespace is created using
43 .BR clone (2),
44 the mount list of the child's namespace is a copy
45 of the mount list in the parent process's mount namespace.
46 .IP \[bu]
47 If the namespace is created using
48 .BR unshare (2),
49 the mount list of the new namespace is a copy of
50 the mount list in the caller's previous mount namespace.
51 .P
52 Subsequent modifications to the mount list
53 .RB ( mount (2)
54 and
55 .BR umount (2))
56 in either mount namespace will not (by default) affect the
57 mount list seen in the other namespace
58 (but see the following discussion of shared subtrees).
59 .\"
60 .SH SHARED SUBTREES
61 After the implementation of mount namespaces was completed,
62 experience showed that the isolation that they provided was,
63 in some cases, too great.
64 For example, in order to make a newly loaded optical disk
65 available in all mount namespaces,
66 a mount operation was required in each namespace.
67 For this use case, and others,
68 the shared subtree feature was introduced in Linux 2.6.15.
69 This feature allows for automatic, controlled propagation of
70 .BR mount (2)
71 and
72 .BR umount (2)
73 .I events
74 between namespaces
75 (or, more precisely, between the mounts that are members of a
76 .I peer group
77 that are propagating events to one another).
78 .P
79 Each mount is marked (via
80 .BR mount (2))
81 as having one of the following
82 .IR "propagation types" :
83 .TP
84 .B MS_SHARED
85 This mount shares events with members of a peer group.
86 .BR mount (2)
87 and
88 .BR umount (2)
89 events immediately under this mount will propagate
90 to the other mounts that are members of the peer group.
91 .I Propagation
92 here means that the same
93 .BR mount (2)
94 or
95 .BR umount (2)
96 will automatically occur
97 under all of the other mounts in the peer group.
98 Conversely,
99 .BR mount (2)
100 and
101 .BR umount (2)
102 events that take place under
103 peer mounts will propagate to this mount.
104 .TP
105 .B MS_PRIVATE
106 This mount is private;
107 it does not have a peer group.
108 .BR mount (2)
109 and
110 .BR umount (2)
111 events do not propagate into or out of this mount.
112 .TP
113 .B MS_SLAVE
114 .BR mount (2)
115 and
116 .BR umount (2)
117 events propagate into this mount from
118 a (master) shared peer group.
119 .BR mount (2)
120 and
121 .BR umount (2)
122 events under this mount do not propagate to any peer.
123 .IP
124 Note that a mount can be the slave of another peer group
125 while at the same time sharing
126 .BR mount (2)
127 and
128 .BR umount (2)
129 events
130 with a peer group of which it is a member.
131 (More precisely, one peer group can be the slave of another peer group.)
132 .TP
133 .B MS_UNBINDABLE
134 This is like a private mount,
135 and in addition this mount can't be bind mounted.
136 Attempts to bind mount this mount
137 .RB ( mount (2)
138 with the
139 .B MS_BIND
140 flag) will fail.
141 .IP
142 When a recursive bind mount
143 .RB ( mount (2)
144 with the
145 .B MS_BIND
146 and
147 .B MS_REC
148 flags) is performed on a directory subtree,
149 any bind mounts within the subtree are automatically pruned
150 (i.e., not replicated)
151 when replicating that subtree to produce the target subtree.
152 .P
153 For a discussion of the propagation type assigned to a new mount,
154 see NOTES.
155 .P
156 The propagation type is a per-mount-point setting;
157 some mounts may be marked as shared
158 (with each shared mount being a member of a distinct peer group),
159 while others are private
160 (or slaved or unbindable).
161 .P
162 Note that a mount's propagation type determines whether
163 .BR mount (2)
164 and
165 .BR umount (2)
166 of mounts
167 .I immediately under
168 the mount are propagated.
169 Thus, the propagation type does not affect propagation of events for
170 grandchildren and further removed descendant mounts.
171 What happens if the mount itself is unmounted is determined by
172 the propagation type that is in effect for the
173 .I parent
174 of the mount.
175 .P
176 Members are added to a
177 .I peer group
178 when a mount is marked as shared and either:
179 .IP (a) 5
180 the mount is replicated during the creation of a new mount namespace;
181 or
182 .IP (b)
183 a new bind mount is created from the mount.
184 .P
185 In both of these cases, the new mount joins the peer group
186 of which the existing mount is a member.
187 .P
188 A new peer group is also created when a child mount is created under
189 an existing mount that is marked as shared.
190 In this case, the new child mount is also marked as shared and
191 the resulting peer group consists of all the mounts
192 that are replicated under the peers of parent mounts.
193 .P
194 A mount ceases to be a member of a peer group when either
195 the mount is explicitly unmounted,
196 or when the mount is implicitly unmounted because a mount namespace is removed
197 (because it has no more member processes).
198 .P
199 The propagation type of the mounts in a mount namespace
200 can be discovered via the "optional fields" exposed in
201 .IR /proc/ pid /mountinfo .
202 (See
203 .BR proc (5)
204 for details of this file.)
205 The following tags can appear in the optional fields
206 for a record in that file:
207 .TP
208 .I shared:X
209 This mount is shared in peer group
210 .IR X .
211 Each peer group has a unique ID that is automatically
212 generated by the kernel,
213 and all mounts in the same peer group will show the same ID.
214 (These IDs are assigned starting from the value 1,
215 and may be recycled when a peer group ceases to have any members.)
216 .TP
217 .I master:X
218 This mount is a slave to shared peer group
219 .IR X .
220 .TP
221 .IR propagate_from:X " (since Linux 2.6.26)"
222 .\" commit 97e7e0f71d6d948c25f11f0a33878d9356d9579e
223 This mount is a slave and receives propagation from shared peer group
224 .IR X .
225 This tag will always appear in conjunction with a
226 .I master:X
227 tag.
228 Here,
229 .I X
230 is the closest dominant peer group under the process's root directory.
231 If
232 .I X
233 is the immediate master of the mount,
234 or if there is no dominant peer group under the same root,
235 then only the
236 .I master:X
237 field is present and not the
238 .I propagate_from:X
239 field.
240 For further details, see below.
241 .TP
242 .I unbindable
243 This is an unbindable mount.
244 .P
245 If none of the above tags is present, then this is a private mount.
246 .SS MS_SHARED and MS_PRIVATE example
247 Suppose that on a terminal in the initial mount namespace,
248 we mark one mount as shared and another as private,
249 and then view the mounts in
250 .IR /proc/self/mountinfo :
251 .P
252 .in +4n
253 .EX
254 .RB sh1# " mount \-\-make\-shared /mntS"
255 .RB sh1# " mount \-\-make\-private /mntP"
256 .RB sh1# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
257 77 61 8:17 / /mntS rw,relatime shared:1
258 83 61 8:15 / /mntP rw,relatime
259 .EE
260 .in
261 .P
262 From the
263 .I /proc/self/mountinfo
264 output, we see that
265 .I /mntS
266 is a shared mount in peer group 1, and that
267 .I /mntP
268 has no optional tags, indicating that it is a private mount.
269 The first two fields in each record in this file are the unique
270 ID for this mount, and the mount ID of the parent mount.
271 We can further inspect this file to see that the parent mount of
272 .I /mntS
273 and
274 .I /mntP
275 is the root directory,
276 .IR / ,
277 which is mounted as private:
278 .P
279 .in +4n
280 .EX
281 .RB sh1# " cat /proc/self/mountinfo | awk \[aq]$1 == 61\[aq] | sed \[aq]s/ \- .*//\[aq]"
282 61 0 8:2 / / rw,relatime
283 .EE
284 .in
285 .P
286 On a second terminal,
287 we create a new mount namespace where we run a second shell
288 and inspect the mounts:
289 .P
290 .in +4n
291 .EX
292 .RB $ " PS1=\[aq]sh2# \[aq] sudo unshare \-m \-\-propagation unchanged sh"
293 .RB sh2# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
294 222 145 8:17 / /mntS rw,relatime shared:1
295 225 145 8:15 / /mntP rw,relatime
296 .EE
297 .in
298 .P
299 The new mount namespace received a copy of the initial mount namespace's
300 mounts.
301 These new mounts maintain the same propagation types,
302 but have unique mount IDs.
303 (The
304 .I \-\-propagation\~unchanged
305 option prevents
306 .BR unshare (1)
307 from marking all mounts as private when creating a new mount namespace,
308 .\" Since util-linux 2.27
309 which it does by default.)
310 .P
311 In the second terminal, we then create submounts under each of
312 .I /mntS
313 and
314 .I /mntP
315 and inspect the set-up:
316 .P
317 .in +4n
318 .EX
319 .RB sh2# " mkdir /mntS/a"
320 .RB sh2# " mount /dev/sdb6 /mntS/a"
321 .RB sh2# " mkdir /mntP/b"
322 .RB sh2# " mount /dev/sdb7 /mntP/b"
323 .RB sh2# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
324 222 145 8:17 / /mntS rw,relatime shared:1
325 225 145 8:15 / /mntP rw,relatime
326 178 222 8:22 / /mntS/a rw,relatime shared:2
327 230 225 8:23 / /mntP/b rw,relatime
328 .EE
329 .in
330 .P
331 From the above, it can be seen that
332 .I /mntS/a
333 was created as shared (inheriting this setting from its parent mount) and
334 .I /mntP/b
335 was created as a private mount.
336 .P
337 Returning to the first terminal and inspecting the set-up,
338 we see that the new mount created under the shared mount
339 .I /mntS
340 propagated to its peer mount (in the initial mount namespace),
341 but the new mount created under the private mount
342 .I /mntP
343 did not propagate:
344 .P
345 .in +4n
346 .EX
347 .RB sh1# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
348 77 61 8:17 / /mntS rw,relatime shared:1
349 83 61 8:15 / /mntP rw,relatime
350 179 77 8:22 / /mntS/a rw,relatime shared:2
351 .EE
352 .in
353 .\"
354 .SS MS_SLAVE example
355 Making a mount a slave allows it to receive propagated
356 .BR mount (2)
357 and
358 .BR umount (2)
359 events from a master shared peer group,
360 while preventing it from propagating events to that master.
361 This is useful if we want to (say) receive a mount event when
362 an optical disk is mounted in the master shared peer group
363 (in another mount namespace),
364 but want to prevent
365 .BR mount (2)
366 and
367 .BR umount (2)
368 events under the slave mount
369 from having side effects in other namespaces.
370 .P
371 We can demonstrate the effect of slaving by first marking
372 two mounts as shared in the initial mount namespace:
373 .P
374 .in +4n
375 .EX
376 .RB sh1# " mount \-\-make\-shared /mntX"
377 .RB sh1# " mount \-\-make\-shared /mntY"
378 .RB sh1# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
379 132 83 8:23 / /mntX rw,relatime shared:1
380 133 83 8:22 / /mntY rw,relatime shared:2
381 .EE
382 .in
383 .P
384 On a second terminal,
385 we create a new mount namespace and inspect the mounts:
386 .P
387 .in +4n
388 .EX
389 .RB sh2# " unshare \-m \-\-propagation unchanged sh"
390 .RB sh2# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
391 168 167 8:23 / /mntX rw,relatime shared:1
392 169 167 8:22 / /mntY rw,relatime shared:2
393 .EE
394 .in
395 .P
396 In the new mount namespace, we then mark one of the mounts as a slave:
397 .P
398 .in +4n
399 .EX
400 .RB sh2# " mount \-\-make\-slave /mntY"
401 .RB sh2# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
402 168 167 8:23 / /mntX rw,relatime shared:1
403 169 167 8:22 / /mntY rw,relatime master:2
404 .EE
405 .in
406 .P
407 From the above output, we see that
408 .I /mntY
409 is now a slave mount that is receiving propagation events from
410 the shared peer group with the ID 2.
411 .P
412 Continuing in the new namespace, we create submounts under each of
413 .I /mntX
414 and
415 .IR /mntY :
416 .P
417 .in +4n
418 .EX
419 .RB sh2# " mkdir /mntX/a"
420 .RB sh2# " mount /dev/sda3 /mntX/a"
421 .RB sh2# " mkdir /mntY/b"
422 .RB sh2# " mount /dev/sda5 /mntY/b"
423 .EE
424 .in
425 .P
426 When we inspect the state of the mounts in the new mount namespace,
427 we see that
428 .I /mntX/a
429 was created as a new shared mount
430 (inheriting the "shared" setting from its parent mount) and
431 .I /mntY/b
432 was created as a private mount:
433 .P
434 .in +4n
435 .EX
436 .RB sh2# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
437 168 167 8:23 / /mntX rw,relatime shared:1
438 169 167 8:22 / /mntY rw,relatime master:2
439 173 168 8:3 / /mntX/a rw,relatime shared:3
440 175 169 8:5 / /mntY/b rw,relatime
441 .EE
442 .in
443 .P
444 Returning to the first terminal (in the initial mount namespace),
445 we see that the mount
446 .I /mntX/a
447 propagated to the peer (the shared
448 .IR /mntX ),
449 but the mount
450 .I /mntY/b
451 was not propagated:
452 .P
453 .in +4n
454 .EX
455 .RB sh1# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
456 132 83 8:23 / /mntX rw,relatime shared:1
457 133 83 8:22 / /mntY rw,relatime shared:2
458 174 132 8:3 / /mntX/a rw,relatime shared:3
459 .EE
460 .in
461 .P
462 Now we create a new mount under
463 .I /mntY
464 in the first shell:
465 .P
466 .in +4n
467 .EX
468 .RB sh1# " mkdir /mntY/c"
469 .RB sh1# " mount /dev/sda1 /mntY/c"
470 .RB sh1# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
471 132 83 8:23 / /mntX rw,relatime shared:1
472 133 83 8:22 / /mntY rw,relatime shared:2
473 174 132 8:3 / /mntX/a rw,relatime shared:3
474 178 133 8:1 / /mntY/c rw,relatime shared:4
475 .EE
476 .in
477 .P
478 When we examine the mounts in the second mount namespace,
479 we see that in this case the new mount has been propagated
480 to the slave mount,
481 and that the new mount is itself a slave mount (to peer group 4):
482 .P
483 .in +4n
484 .EX
485 .RB sh2# " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
486 168 167 8:23 / /mntX rw,relatime shared:1
487 169 167 8:22 / /mntY rw,relatime master:2
488 173 168 8:3 / /mntX/a rw,relatime shared:3
489 175 169 8:5 / /mntY/b rw,relatime
490 179 169 8:1 / /mntY/c rw,relatime master:4
491 .EE
492 .in
493 .\"
494 .SS MS_UNBINDABLE example
495 One of the primary purposes of unbindable mounts is to avoid
496 the "mount explosion" problem when repeatedly performing bind mounts
497 of a higher-level subtree at a lower-level mount.
498 The problem is illustrated by the following shell session.
499 .P
500 Suppose we have a system with the following mounts:
501 .P
502 .in +4n
503 .EX
504 .RB # " mount | awk \[aq]{print $1, $2, $3}\[aq]"
505 /dev/sda1 on /
506 /dev/sdb6 on /mntX
507 /dev/sdb7 on /mntY
508 .EE
509 .in
510 .P
511 Suppose furthermore that we wish to recursively bind mount
512 the root directory under several users' home directories.
513 We do this for the first user, and inspect the mounts:
514 .P
515 .in +4n
516 .EX
517 .RB # " mount \-\-rbind / /home/cecilia/"
518 .RB # " mount | awk \[aq]{print $1, $2, $3}\[aq]"
519 /dev/sda1 on /
520 /dev/sdb6 on /mntX
521 /dev/sdb7 on /mntY
522 /dev/sda1 on /home/cecilia
523 /dev/sdb6 on /home/cecilia/mntX
524 /dev/sdb7 on /home/cecilia/mntY
525 .EE
526 .in
527 .P
528 When we repeat this operation for the second user,
529 we start to see the explosion problem:
530 .P
531 .in +4n
532 .EX
533 .RB # " mount \-\-rbind / /home/henry"
534 .RB # " mount | awk \[aq]{print $1, $2, $3}\[aq]"
535 /dev/sda1 on /
536 /dev/sdb6 on /mntX
537 /dev/sdb7 on /mntY
538 /dev/sda1 on /home/cecilia
539 /dev/sdb6 on /home/cecilia/mntX
540 /dev/sdb7 on /home/cecilia/mntY
541 /dev/sda1 on /home/henry
542 /dev/sdb6 on /home/henry/mntX
543 /dev/sdb7 on /home/henry/mntY
544 /dev/sda1 on /home/henry/home/cecilia
545 /dev/sdb6 on /home/henry/home/cecilia/mntX
546 /dev/sdb7 on /home/henry/home/cecilia/mntY
547 .EE
548 .in
549 .P
550 Under
551 .IR /home/henry ,
552 we have not only recursively added the
553 .I /mntX
554 and
555 .I /mntY
556 mounts, but also the recursive mounts of those directories under
557 .I /home/cecilia
558 that were created in the previous step.
559 Upon repeating the step for a third user,
560 it becomes obvious that the explosion is exponential in nature:
561 .P
562 .in +4n
563 .EX
564 .RB # " mount \-\-rbind / /home/otto"
565 .RB # " mount | awk \[aq]{print $1, $2, $3}\[aq]"
566 /dev/sda1 on /
567 /dev/sdb6 on /mntX
568 /dev/sdb7 on /mntY
569 /dev/sda1 on /home/cecilia
570 /dev/sdb6 on /home/cecilia/mntX
571 /dev/sdb7 on /home/cecilia/mntY
572 /dev/sda1 on /home/henry
573 /dev/sdb6 on /home/henry/mntX
574 /dev/sdb7 on /home/henry/mntY
575 /dev/sda1 on /home/henry/home/cecilia
576 /dev/sdb6 on /home/henry/home/cecilia/mntX
577 /dev/sdb7 on /home/henry/home/cecilia/mntY
578 /dev/sda1 on /home/otto
579 /dev/sdb6 on /home/otto/mntX
580 /dev/sdb7 on /home/otto/mntY
581 /dev/sda1 on /home/otto/home/cecilia
582 /dev/sdb6 on /home/otto/home/cecilia/mntX
583 /dev/sdb7 on /home/otto/home/cecilia/mntY
584 /dev/sda1 on /home/otto/home/henry
585 /dev/sdb6 on /home/otto/home/henry/mntX
586 /dev/sdb7 on /home/otto/home/henry/mntY
587 /dev/sda1 on /home/otto/home/henry/home/cecilia
588 /dev/sdb6 on /home/otto/home/henry/home/cecilia/mntX
589 /dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY
590 .EE
591 .in
592 .P
593 The mount explosion problem in the above scenario can be avoided
594 by making each of the new mounts unbindable.
595 The effect of doing this is that recursive mounts of the root
596 directory will not replicate the unbindable mounts.
597 We make such a mount for the first user:
598 .P
599 .in +4n
600 .EX
601 .RB # " mount \-\-rbind \-\-make\-unbindable / /home/cecilia"
602 .EE
603 .in
604 .P
605 Before going further, we show that unbindable mounts are indeed unbindable:
606 .P
607 .in +4n
608 .EX
609 .RB # " mkdir /mntZ"
610 .RB # " mount \-\-bind /home/cecilia /mntZ"
611 mount: wrong fs type, bad option, bad superblock on /home/cecilia,
612 missing codepage or helper program, or other error
613 \&
614 In some cases useful info is found in syslog \- try
615 dmesg | tail or so.
616 .EE
617 .in
618 .P
619 Now we create unbindable recursive bind mounts for the other two users:
620 .P
621 .in +4n
622 .EX
623 .RB # " mount \-\-rbind \-\-make\-unbindable / /home/henry"
624 .RB # " mount \-\-rbind \-\-make\-unbindable / /home/otto"
625 .EE
626 .in
627 .P
628 Upon examining the list of mounts,
629 we see there has been no explosion of mounts,
630 because the unbindable mounts were not replicated
631 under each user's directory:
632 .P
633 .in +4n
634 .EX
635 .RB # " mount | awk \[aq]{print $1, $2, $3}\[aq]"
636 /dev/sda1 on /
637 /dev/sdb6 on /mntX
638 /dev/sdb7 on /mntY
639 /dev/sda1 on /home/cecilia
640 /dev/sdb6 on /home/cecilia/mntX
641 /dev/sdb7 on /home/cecilia/mntY
642 /dev/sda1 on /home/henry
643 /dev/sdb6 on /home/henry/mntX
644 /dev/sdb7 on /home/henry/mntY
645 /dev/sda1 on /home/otto
646 /dev/sdb6 on /home/otto/mntX
647 /dev/sdb7 on /home/otto/mntY
648 .EE
649 .in
650 .\"
651 .SS Propagation type transitions
652 The following table shows the effect that applying a new propagation type
653 (i.e.,
654 .IR mount\~\-\-make\-xxxx )
655 has on the existing propagation type of a mount.
656 The rows correspond to existing propagation types,
657 and the columns are the new propagation settings.
658 For reasons of space, "private" is abbreviated as "priv" and
659 "unbindable" as "unbind".
660 .TS
661 lb2 lb2 lb2 lb2 lb1
662 lb | l l l l l.
663 make-shared make-slave make-priv make-unbind
664 _
665 shared shared slave/priv [1] priv unbind
666 slave slave+shared slave [2] priv unbind
667 slave+shared slave+shared slave priv unbind
668 private shared priv [2] priv unbind
669 unbindable shared unbind [2] priv unbind
670 .TE
671 .P
672 Note the following details to the table:
673 .IP [1] 5
674 If a shared mount is the only mount in its peer group,
675 making it a slave automatically makes it private.
676 .IP [2]
677 Slaving a nonshared mount has no effect on the mount.
678 .\"
679 .SS Bind (MS_BIND) semantics
680 Suppose that the following command is performed:
681 .P
682 .in +4n
683 .EX
684 mount \-\-bind A/a B/b
685 .EE
686 .in
687 .P
688 Here,
689 .I A
690 is the source mount,
691 .I B
692 is the destination mount,
693 .I a
694 is a subdirectory path under the mount point
695 .IR A ,
696 and
697 .I b
698 is a subdirectory path under the mount point
699 .IR B .
700 The propagation type of the resulting mount,
701 .IR B/b ,
702 depends on the propagation types of the mounts
703 .I A
704 and
705 .IR B ,
706 and is summarized in the following table.
707 .P
708 .TS
709 lb2 lb1 lb2 lb2 lb2 lb0
710 lb2 lb1 lb2 lb2 lb2 lb0
711 lb lb | l l l l l.
712 source(A)
713 shared private slave unbind
714 _
715 dest(B) shared shared shared slave+shared invalid
716 nonshared shared private slave invalid
717 .TE
718 .P
719 Note that a recursive bind of a subtree follows the same semantics
720 as for a bind operation on each mount in the subtree.
721 (Unbindable mounts are automatically pruned at the target mount point.)
722 .P
723 For further details, see
724 .I Documentation/filesystems/sharedsubtree.rst
725 in the kernel source tree.
726 .\"
727 .SS Move (MS_MOVE) semantics
728 Suppose that the following command is performed:
729 .P
730 .in +4n
731 .EX
732 mount \-\-move A B/b
733 .EE
734 .in
735 .P
736 Here,
737 .I A
738 is the source mount,
739 .I B
740 is the destination mount, and
741 .I b
742 is a subdirectory path under the mount point
743 .IR B .
744 The propagation type of the resulting mount,
745 .IR B/b ,
746 depends on the propagation types of the mounts
747 .I A
748 and
749 .IR B ,
750 and is summarized in the following table.
751 .P
752 .TS
753 lb2 lb1 lb2 lb2 lb2 lb0
754 lb2 lb1 lb2 lb2 lb2 lb0
755 lb lb | l l l l l.
756 source(A)
757 shared private slave unbind
758 _
759 dest(B) shared shared shared slave+shared invalid
760 nonshared shared private slave unbindable
761 .TE
762 .P
763 Note: moving a mount that resides under a shared mount is invalid.
764 .P
765 For further details, see
766 .I Documentation/filesystems/sharedsubtree.rst
767 in the kernel source tree.
768 .\"
769 .SS Mount semantics
770 Suppose that we use the following command to create a mount:
771 .P
772 .in +4n
773 .EX
774 mount device B/b
775 .EE
776 .in
777 .P
778 Here,
779 .I B
780 is the destination mount, and
781 .I b
782 is a subdirectory path under the mount point
783 .IR B .
784 The propagation type of the resulting mount,
785 .IR B/b ,
786 follows the same rules as for a bind mount,
787 where the propagation type of the source mount
788 is considered always to be private.
789 .\"
790 .SS Unmount semantics
791 Suppose that we use the following command to tear down a mount:
792 .P
793 .in +4n
794 .EX
795 umount A
796 .EE
797 .in
798 .P
799 Here,
800 .I A
801 is a mount on
802 .IR B/b ,
803 where
804 .I B
805 is the parent mount and
806 .I b
807 is a subdirectory path under the mount point
808 .IR B .
809 If
810 .B B
811 is shared, then all most-recently-mounted mounts at
812 .I b
813 on mounts that receive propagation from mount
814 .I B
815 and do not have submounts under them are unmounted.
816 .\"
817 .SS The /proc/ pid /mountinfo "propagate_from" tag
818 The
819 .I propagate_from:X
820 tag is shown in the optional fields of a
821 .IR /proc/ pid /mountinfo
822 record in cases where a process can't see a slave's immediate master
823 (i.e., the pathname of the master is not reachable from
824 the filesystem root directory)
825 and so cannot determine the
826 chain of propagation between the mounts it can see.
827 .P
828 In the following example, we first create a two-link master-slave chain
829 between the mounts
830 .IR /mnt ,
831 .IR /tmp/etc ,
832 and
833 .IR /mnt/tmp/etc .
834 Then the
835 .BR chroot (1)
836 command is used to make the
837 .I /tmp/etc
838 mount point unreachable from the root directory,
839 creating a situation where the master of
840 .I /mnt/tmp/etc
841 is not reachable from the (new) root directory of the process.
842 .P
843 First, we bind mount the root directory onto
844 .I /mnt
845 and then bind mount
846 .I /proc
847 at
848 .I /mnt/proc
849 so that after the later
850 .BR chroot (1)
851 the
852 .BR proc (5)
853 filesystem remains visible at the correct location
854 in the chroot-ed environment.
855 .P
856 .in +4n
857 .EX
858 .RB # " mkdir \-p /mnt/proc"
859 .RB # " mount \-\-bind / /mnt"
860 .RB # " mount \-\-bind /proc /mnt/proc"
861 .EE
862 .in
863 .P
864 Next, we ensure that the
865 .I /mnt
866 mount is a shared mount in a new peer group (with no peers):
867 .P
868 .in +4n
869 .EX
870 .RB # " mount \-\-make\-private /mnt" " # Isolate from any previous peer group"
871 .RB # " mount \-\-make\-shared /mnt"
872 .RB # " cat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]"
873 239 61 8:2 / /mnt ...\& shared:102
874 248 239 0:4 / /mnt/proc ...\& shared:5
875 .EE
876 .in
877 .P
878 Next, we bind mount
879 .I /mnt/etc
880 onto
881 .IR /tmp/etc :
882 .P
883 .in +4n
884 .EX
885 .RB # " mkdir \-p /tmp/etc"
886 .RB # " mount \-\-bind /mnt/etc /tmp/etc"
887 .RB # " cat /proc/self/mountinfo | egrep \[aq]/mnt|/tmp/\[aq] | sed \[aq]s/ \- .*//\[aq]"
888 239 61 8:2 / /mnt ...\& shared:102
889 248 239 0:4 / /mnt/proc ...\& shared:5
890 267 40 8:2 /etc /tmp/etc ...\& shared:102
891 .EE
892 .in
893 .P
894 Initially, these two mounts are in the same peer group,
895 but we then make the
896 .I /tmp/etc
897 a slave of
898 .IR /mnt/etc ,
899 and then make
900 .I /tmp/etc
901 shared as well,
902 so that it can propagate events to the next slave in the chain:
903 .P
904 .in +4n
905 .EX
906 .RB # " mount \-\-make\-slave /tmp/etc"
907 .RB # " mount \-\-make\-shared /tmp/etc"
908 .RB # " cat /proc/self/mountinfo | egrep \[aq]/mnt|/tmp/\[aq] | sed \[aq]s/ \- .*//\[aq]"
909 239 61 8:2 / /mnt ...\& shared:102
910 248 239 0:4 / /mnt/proc ...\& shared:5
911 267 40 8:2 /etc /tmp/etc ...\& shared:105 master:102
912 .EE
913 .in
914 .P
915 Then we bind mount
916 .I /tmp/etc
917 onto
918 .IR /mnt/tmp/etc .
919 Again, the two mounts are initially in the same peer group,
920 but we then make
921 .I /mnt/tmp/etc
922 a slave of
923 .IR /tmp/etc :
924 .P
925 .in +4n
926 .EX
927 .RB # " mkdir \-p /mnt/tmp/etc"
928 .RB # " mount \-\-bind /tmp/etc /mnt/tmp/etc"
929 .RB # " mount \-\-make\-slave /mnt/tmp/etc"
930 .RB # " cat /proc/self/mountinfo | egrep \[aq]/mnt|/tmp/\[aq] | sed \[aq]s/ \- .*//\[aq]"
931 239 61 8:2 / /mnt ...\& shared:102
932 248 239 0:4 / /mnt/proc ...\& shared:5
933 267 40 8:2 /etc /tmp/etc ...\& shared:105 master:102
934 273 239 8:2 /etc /mnt/tmp/etc ...\& master:105
935 .EE
936 .in
937 .P
938 From the above, we see that
939 .I /mnt
940 is the master of the slave
941 .IR /tmp/etc ,
942 which in turn is the master of the slave
943 .IR /mnt/tmp/etc .
944 .P
945 We then
946 .BR chroot (1)
947 to the
948 .I /mnt
949 directory, which renders the mount with ID 267 unreachable
950 from the (new) root directory:
951 .P
952 .in +4n
953 .EX
954 .RB # " chroot /mnt"
955 .EE
956 .in
957 .P
958 When we examine the state of the mounts inside the chroot-ed environment,
959 we see the following:
960 .P
961 .in +4n
962 .EX
963 .RB # " cat /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]"
964 239 61 8:2 / / ...\& shared:102
965 248 239 0:4 / /proc ...\& shared:5
966 273 239 8:2 /etc /tmp/etc ...\& master:105 propagate_from:102
967 .EE
968 .in
969 .P
970 Above, we see that the mount with ID 273
971 is a slave whose master is the peer group 105.
972 The mount point for that master is unreachable, and so a
973 .I propagate_from
974 tag is displayed, indicating that the closest dominant peer group
975 (i.e., the nearest reachable mount in the slave chain)
976 is the peer group with the ID 102 (corresponding to the
977 .I /mnt
978 mount point before the
979 .BR chroot (1)
980 was performed).
981 .\"
982 .SH STANDARDS
983 Linux.
984 .SH HISTORY
985 Linux 2.4.19.
986 .\"
987 .SH NOTES
988 The propagation type assigned to a new mount depends
989 on the propagation type of the parent mount.
990 If the mount has a parent
991 (i.e., it is a non-root mount)
992 and the propagation type of the parent is
993 .BR MS_SHARED ,
994 then the propagation type of the new mount is also
995 .BR MS_SHARED .
996 Otherwise, the propagation type of the new mount is
997 .BR MS_PRIVATE .
998 .P
999 Notwithstanding the fact that the default propagation type
1000 for new mount is in many cases
1001 .BR MS_PRIVATE ,
1002 .B MS_SHARED
1003 is typically more useful.
1004 For this reason,
1005 .BR systemd (1)
1006 automatically remounts all mounts as
1007 .B MS_SHARED
1008 on system startup.
1009 Thus, on most modern systems, the default propagation type is in practice
1010 .BR MS_SHARED .
1011 .P
1012 Since, when one uses
1013 .BR unshare (1)
1014 to create a mount namespace,
1015 the goal is commonly to provide full isolation of the mounts
1016 in the new namespace,
1017 .BR unshare (1)
1018 (since
1019 .I util\-linux
1020 2.27) in turn reverses the step performed by
1021 .BR systemd (1),
1022 by making all mounts private in the new namespace.
1023 That is,
1024 .BR unshare (1)
1025 performs the equivalent of the following in the new mount namespace:
1026 .P
1027 .in +4n
1028 .EX
1029 mount \-\-make\-rprivate /
1030 .EE
1031 .in
1032 .P
1033 To prevent this, one can use the
1034 .I \-\-propagation\~unchanged
1035 option to
1036 .BR unshare (1).
1037 .P
1038 An application that creates a new mount namespace directly using
1039 .BR clone (2)
1040 or
1041 .BR unshare (2)
1042 may desire to prevent propagation of mount events to other mount namespaces
1043 (as is done by
1044 .BR unshare (1)).
1045 This can be done by changing the propagation type of
1046 mounts in the new namespace to either
1047 .B MS_SLAVE
1048 or
1049 .BR MS_PRIVATE ,
1050 using a call such as the following:
1051 .P
1052 .in +4n
1053 .EX
1054 mount(NULL, "/", MS_SLAVE | MS_REC, NULL);
1055 .EE
1056 .in
1057 .P
1058 For a discussion of propagation types when moving mounts
1059 .RB ( MS_MOVE )
1060 and creating bind mounts
1061 .RB ( MS_BIND ),
1062 see
1063 .IR Documentation/filesystems/sharedsubtree.rst .
1064 .\"
1065 .\" ============================================================
1066 .\"
1067 .SS Restrictions on mount namespaces
1068 Note the following points with respect to mount namespaces:
1069 .IP [1] 5
1070 Each mount namespace has an owner user namespace.
1071 As explained above, when a new mount namespace is created,
1072 its mount list is initialized as a copy of the mount list
1073 of another mount namespace.
1074 If the new namespace and the namespace from which the mount list
1075 was copied are owned by different user namespaces,
1076 then the new mount namespace is considered
1077 .IR "less privileged" .
1078 .IP [2]
1079 When creating a less privileged mount namespace,
1080 shared mounts are reduced to slave mounts.
1081 This ensures that mappings performed in less
1082 privileged mount namespaces will not propagate to more privileged
1083 mount namespaces.
1084 .IP [3]
1085 Mounts that come as a single unit from a more privileged mount namespace are
1086 locked together and may not be separated in a less privileged mount
1087 namespace.
1088 (The
1089 .BR unshare (2)
1090 .B CLONE_NEWNS
1091 operation brings across all of the mounts from the original
1092 mount namespace as a single unit,
1093 and recursive mounts that propagate between
1094 mount namespaces propagate as a single unit.)
1095 .IP
1096 In this context, "may not be separated" means that the mounts
1097 are locked so that they may not be individually unmounted.
1098 Consider the following example:
1099 .IP
1100 .in +4n
1101 .EX
1102 .RB $ " sudo sh"
1103 .RB # " mount \-\-bind /dev/null /etc/shadow"
1104 .RB # " cat /etc/shadow" " # Produces no output"
1105 .EE
1106 .in
1107 .IP
1108 The above steps, performed in a more privileged mount namespace,
1109 have created a bind mount that
1110 obscures the contents of the shadow password file,
1111 .IR /etc/shadow .
1112 For security reasons, it should not be possible to
1113 .BR umount (2)
1114 that mount in a less privileged mount namespace,
1115 since that would reveal the contents of
1116 .IR /etc/shadow .
1117 .IP
1118 Suppose we now create a new mount namespace
1119 owned by a new user namespace.
1120 The new mount namespace will inherit copies of all of the mounts
1121 from the previous mount namespace.
1122 However, those mounts will be locked because the new mount namespace
1123 is less privileged.
1124 Consequently, an attempt to
1125 .BR umount (2)
1126 the mount fails as show
1127 in the following step:
1128 .IP
1129 .in +4n
1130 .EX
1131 .RB # " unshare \-\-user \-\-map\-root\-user \-\-mount \[rs]"
1132 .B " strace \-o /tmp/log \[rs]"
1133 .B " umount /etc/shadow"
1134 umount: /etc/shadow: not mounted.
1135 .RB # " grep \[aq]\[ha]umount\[aq] /tmp/log"
1136 umount2("/etc/shadow", 0) = \-1 EINVAL (Invalid argument)
1137 .EE
1138 .in
1139 .IP
1140 The error message from
1141 .BR mount (8)
1142 is a little confusing, but the
1143 .BR strace (1)
1144 output reveals that the underlying
1145 .BR umount2 (2)
1146 system call failed with the error
1147 .BR EINVAL ,
1148 which is the error that the kernel returns to indicate that
1149 the mount is locked.
1150 .IP
1151 Note, however, that it is possible to stack (and unstack) a
1152 mount on top of one of the inherited locked mounts in a
1153 less privileged mount namespace:
1154 .IP
1155 .in +4n
1156 .EX
1157 .RB # " echo \[aq]aaaaa\[aq] > /tmp/a" " # File to mount onto /etc/shadow"
1158 .RB # " unshare \-\-user \-\-map\-root\-user \-\-mount \[rs]"
1159 .B " sh \-c \[aq]mount \-\-bind /tmp/a /etc/shadow; cat /etc/shadow\[aq]"
1160 aaaaa
1161 .RB # " umount /etc/shadow"
1162 .EE
1163 .in
1164 .IP
1165 The final
1166 .BR umount (8)
1167 command above, which is performed in the initial mount namespace,
1168 makes the original
1169 .I /etc/shadow
1170 file once more visible in that namespace.
1171 .IP [4]
1172 Following on from point [3],
1173 note that it is possible to
1174 .BR umount (2)
1175 an entire subtree of mounts that
1176 propagated as a unit into a less privileged mount namespace,
1177 as illustrated in the following example.
1178 .IP
1179 First, we create new user and mount namespaces using
1180 .BR unshare (1).
1181 In the new mount namespace,
1182 the propagation type of all mounts is set to private.
1183 We then create a shared bind mount at
1184 .IR /mnt ,
1185 and a small hierarchy of mounts underneath that mount.
1186 .IP
1187 .in +4n
1188 .EX
1189 .RB $ " PS1=\[aq]ns1# \[aq] sudo unshare \-\-user \-\-map\-root\-user \[rs]"
1190 .B " \-\-mount \-\-propagation private bash"
1191 .RB ns1# " echo $$" " # We need the PID of this shell later"
1192 778501
1193 .RB ns1# " mount \-\-make\-shared \-\-bind /mnt /mnt"
1194 .RB ns1# " mkdir /mnt/x"
1195 .RB ns1# " mount \-\-make\-private \-t tmpfs none /mnt/x"
1196 .RB ns1# " mkdir /mnt/x/y"
1197 .RB ns1# " mount \-\-make\-private \-t tmpfs none /mnt/x/y"
1198 .RB ns1# " grep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]"
1199 986 83 8:5 /mnt /mnt rw,relatime shared:344
1200 989 986 0:56 / /mnt/x rw,relatime
1201 990 989 0:57 / /mnt/x/y rw,relatime
1202 .EE
1203 .in
1204 .IP
1205 Continuing in the same shell session,
1206 we then create a second shell in a new user namespace and a new
1207 (less privileged) mount namespace and
1208 check the state of the propagated mounts rooted at
1209 .IR /mnt .
1210 .IP
1211 .in +4n
1212 .EX
1213 .RB ns1# " PS1=\[aq]ns2# \[aq] unshare \-\-user \-\-map\-root\-user \[rs]"
1214 .B " \-\-mount \-\-propagation unchanged bash"
1215 .RB ns2# " grep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]"
1216 1239 1204 8:5 /mnt /mnt rw,relatime master:344
1217 1240 1239 0:56 / /mnt/x rw,relatime
1218 1241 1240 0:57 / /mnt/x/y rw,relatime
1219 .EE
1220 .in
1221 .IP
1222 Of note in the above output is that the propagation type of the mount
1223 .I /mnt
1224 has been reduced to slave, as explained in point [2].
1225 This means that submount events will propagate from the master
1226 .I /mnt
1227 in "ns1", but propagation will not occur in the opposite direction.
1228 .IP
1229 From a separate terminal window, we then use
1230 .BR nsenter (1)
1231 to enter the mount and user namespaces corresponding to "ns1".
1232 In that terminal window, we then recursively bind mount
1233 .I /mnt/x
1234 at the location
1235 .IR /mnt/ppp .
1236 .IP
1237 .in +4n
1238 .EX
1239 .RB $ " PS1=\[aq]ns3# \[aq] sudo nsenter \-t 778501 \-\-user \-\-mount"
1240 .RB ns3# " mount \-\-rbind \-\-make\-private /mnt/x /mnt/ppp"
1241 .RB ns3# " grep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]"
1242 986 83 8:5 /mnt /mnt rw,relatime shared:344
1243 989 986 0:56 / /mnt/x rw,relatime
1244 990 989 0:57 / /mnt/x/y rw,relatime
1245 1242 986 0:56 / /mnt/ppp rw,relatime
1246 1243 1242 0:57 / /mnt/ppp/y rw,relatime shared:518
1247 .EE
1248 .in
1249 .IP
1250 Because the propagation type of the parent mount,
1251 .IR /mnt ,
1252 was shared, the recursive bind mount propagated a small subtree of
1253 mounts under the slave mount
1254 .I /mnt
1255 into "ns2",
1256 as can be verified by executing the following command in that shell session:
1257 .IP
1258 .in +4n
1259 .EX
1260 .RB ns2# " grep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]"
1261 1239 1204 8:5 /mnt /mnt rw,relatime master:344
1262 1240 1239 0:56 / /mnt/x rw,relatime
1263 1241 1240 0:57 / /mnt/x/y rw,relatime
1264 1244 1239 0:56 / /mnt/ppp rw,relatime
1265 1245 1244 0:57 / /mnt/ppp/y rw,relatime master:518
1266 .EE
1267 .in
1268 .IP
1269 While it is not possible to
1270 .BR umount (2)
1271 a part of the propagated subtree
1272 .RI ( /mnt/ppp/y )
1273 in "ns2",
1274 it is possible to
1275 .BR umount (2)
1276 the entire subtree,
1277 as shown by the following commands:
1278 .IP
1279 .in +4n
1280 .EX
1281 .RB ns2# " umount /mnt/ppp/y"
1282 umount: /mnt/ppp/y: not mounted.
1283 .RB ns2# " umount \-l /mnt/ppp | sed \[aq]s/ \- .*//\[aq]" " # Succeeds..."
1284 .RB ns2# " grep /mnt /proc/self/mountinfo"
1285 1239 1204 8:5 /mnt /mnt rw,relatime master:344
1286 1240 1239 0:56 / /mnt/x rw,relatime
1287 1241 1240 0:57 / /mnt/x/y rw,relatime
1288 .EE
1289 .in
1290 .IP [5]
1291 The
1292 .BR mount (2)
1293 flags
1294 .BR MS_RDONLY ,
1295 .BR MS_NOSUID ,
1296 .BR MS_NOEXEC ,
1297 and the "atime" flags
1298 .RB ( MS_NOATIME ,
1299 .BR MS_NODIRATIME ,
1300 .BR MS_RELATIME )
1301 settings become locked
1302 .\" commit 9566d6742852c527bf5af38af5cbb878dad75705
1303 .\" Author: Eric W. Biederman <[email protected]>
1304 .\" Date: Mon Jul 28 17:26:07 2014 -0700
1305 .\"
1306 .\" mnt: Correct permission checks in do_remount
1307 .\"
1308 when propagated from a more privileged to
1309 a less privileged mount namespace,
1310 and may not be changed in the less privileged mount namespace.
1311 .IP
1312 This point is illustrated in the following example where,
1313 in a more privileged mount namespace,
1314 we create a bind mount that is marked as read-only.
1315 For security reasons,
1316 it should not be possible to make the mount writable in
1317 a less privileged mount namespace, and indeed the kernel prevents this:
1318 .IP
1319 .in +4n
1320 .EX
1321 .RB $ " sudo mkdir /mnt/dir"
1322 .RB $ " sudo mount \-\-bind \-o ro /some/path /mnt/dir"
1323 .RB $ " sudo unshare \-\-user \-\-map\-root\-user \-\-mount \[rs]"
1324 .B " mount \-o remount,rw /mnt/dir"
1325 mount: /mnt/dir: permission denied.
1326 .EE
1327 .in
1328 .IP [6]
1329 .\" (As of 3.18-rc1 (in Al Viro's 2014-08-30 vfs.git#for-next tree))
1330 A file or directory that is a mount point in one namespace that is not
1331 a mount point in another namespace, may be renamed, unlinked, or removed
1332 .RB ( rmdir (2))
1333 in the mount namespace in which it is not a mount point
1334 (subject to the usual permission checks).
1335 Consequently, the mount point is removed in the mount namespace
1336 where it was a mount point.
1337 .IP
1338 Previously (before Linux 3.18),
1339 .\" mtk: The change was in Linux 3.18, I think, with this commit:
1340 .\" commit 8ed936b5671bfb33d89bc60bdcc7cf0470ba52fe
1341 .\" Author: Eric W. Biederman <[email protected]>
1342 .\" Date: Tue Oct 1 18:33:48 2013 -0700
1343 .\"
1344 .\" vfs: Lazily remove mounts on unlinked files and directories.
1345 attempting to unlink, rename, or remove a file or directory
1346 that was a mount point in another mount namespace would result in the error
1347 .BR EBUSY .
1348 That behavior had technical problems of enforcement (e.g., for NFS)
1349 and permitted denial-of-service attacks against more privileged users
1350 (i.e., preventing individual files from being updated
1351 by bind mounting on top of them).
1352 .SH EXAMPLES
1353 See
1354 .BR pivot_root (2).
1355 .SH SEE ALSO
1356 .BR unshare (1),
1357 .BR clone (2),
1358 .BR mount (2),
1359 .BR mount_setattr (2),
1360 .BR pivot_root (2),
1361 .BR setns (2),
1362 .BR umount (2),
1363 .BR unshare (2),
1364 .BR proc (5),
1365 .BR namespaces (7),
1366 .BR user_namespaces (7),
1367 .BR findmnt (8),
1368 .BR mount (8),
1369 .BR pam_namespace (8),
1370 .BR pivot_root (8),
1371 .BR umount (8)
1372 .P
1373 .I Documentation/filesystems/sharedsubtree.rst
1374 in the kernel source tree.