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