1MOUNT_NAMESPACES(7)        Linux Programmer's Manual       MOUNT_NAMESPACES(7)
2
3
4

NAME

6       mount_namespaces - overview of Linux mount namespaces
7

DESCRIPTION

9       For an overview of namespaces, see namespaces(7).
10
11       Mount  namespaces provide isolation of the list of mount points seen by
12       the processes in each namespace instance.  Thus, the processes in  each
13       of  the  mount  namespace  instances will see distinct single-directory
14       hierarchies.
15
16       The views provided by  the  /proc/[pid]/mounts,  /proc/[pid]/mountinfo,
17       and  /proc/[pid]/mountstats files (all described in proc(5)) correspond
18       to the mount namespace in which the process with the PID [pid] resides.
19       (All  of the processes that reside in the same mount namespace will see
20       the same view in these files.)
21
22       A new mount namespace is created using either  clone(2)  or  unshare(2)
23       with  the CLONE_NEWNS flag.  When a new mount namespace is created, its
24       mount point list is initialized as follows:
25
26       *  If the namespace is created using clone(2), the mount point list  of
27          the  child's namespace is a copy of the mount point list in the par‐
28          ent's namespace.
29
30       *  If the namespace is created using unshare(2), the mount  point  list
31          of  the new namespace is a copy of the mount point list in the call‐
32          er's previous mount namespace.
33
34       Subsequent  modifications  to  the  mount  point  list  (mount(2)   and
35       umount(2))  in  either mount namespace will not (by default) affect the
36       mount point list seen in the other namespace  (but  see  the  following
37       discussion of shared subtrees).
38
39   Restrictions on mount namespaces
40       Note the following points with respect to mount namespaces:
41
42       *  Each  mount  namespace  has  an  owner user namespace.  As explained
43          above, when a new mount namespace is created, its mount  point  list
44          is  initialized  as  a copy of the mount point list of another mount
45          namespace.  If the new namespace and the namespace  from  which  the
46          mount  point list was copied are owned by different user namespaces,
47          then the new mount namespace is considered less privileged.
48
49       *  When creating a less privileged mount namespace, shared  mounts  are
50          reduced  to  slave  mounts.   (Shared and slave mounts are discussed
51          below.)  This ensures that mappings  performed  in  less  privileged
52          mount  namespaces will not propagate to more privileged mount names‐
53          paces.
54
55       *  Mounts that come as a single unit from  more  privileged  mount  are
56          locked  together and may not be separated in a less privileged mount
57          namespace.  (The unshare(2) CLONE_NEWNS operation brings across  all
58          of  the  mounts  from the original mount namespace as a single unit,
59          and recursive mounts that propagate between mount namespaces  propa‐
60          gate as a single unit.)
61
62       *  The  mount(2) flags MS_RDONLY, MS_NOSUID, MS_NOEXEC, and the "atime"
63          flags  (MS_NOATIME,  MS_NODIRATIME,  MS_RELATIME)  settings   become
64          locked  when  propagated from a more privileged to a less privileged
65          mount namespace, and may not be changed in the less privileged mount
66          namespace.
67
68       *  A  file  or directory that is a mount point in one namespace that is
69          not a mount point in another namespace, may be renamed, unlinked, or
70          removed (rmdir(2)) in the mount namespace in which it is not a mount
71          point (subject to the usual permission checks).   Consequently,  the
72          mount  point  is removed in the mount namespace where it was a mount
73          point.
74
75          Previously (before Linux 3.18), attempting  to  unlink,  rename,  or
76          remove  a  file or directory that was a mount point in another mount
77          namespace would result in the error EBUSY.  That behavior had  tech‐
78          nical  problems of enforcement (e.g., for NFS) and permitted denial-
79          of-service attacks against more privileged users.  (i.e., preventing
80          individual  files  from  being  updated  by  bind mounting on top of
81          them).
82

SHARED SUBTREES

84       After the implementation of mount namespaces was completed,  experience
85       showed  that  the  isolation that they provided was, in some cases, too
86       great.  For example, in order to  make  a  newly  loaded  optical  disk
87       available  in  all  mount namespaces, a mount operation was required in
88       each namespace.  For this use case, and others, the shared subtree fea‐
89       ture  was  introduced  in  Linux 2.6.15.  This feature allows for auto‐
90       matic, controlled propagation  of  mount  and  unmount  events  between
91       namespaces  (or,  more  precisely,  between the members of a peer group
92       that are propagating events to one another).
93
94       Each mount point is marked (via mount(2)) as having one of the  follow‐
95       ing propagation types:
96
97       MS_SHARED
98              This  mount  point  shares  events with members of a peer group.
99              Mount and unmount events immediately under this mount point will
100              propagate to the other mount points that are members of the peer
101              group.  Propagation here means that the same  mount  or  unmount
102              will  automatically occur under all of the other mount points in
103              the peer group.  Conversely, mount and unmount events that  take
104              place  under  peer  mount  points  will  propagate to this mount
105              point.
106
107       MS_PRIVATE
108              This mount point is private; it does  not  have  a  peer  group.
109              Mount  and  unmount  events do not propagate into or out of this
110              mount point.
111
112       MS_SLAVE
113              Mount and unmount events propagate into this mount point from  a
114              (master) shared peer group.  Mount and unmount events under this
115              mount point do not propagate to any peer.
116
117              Note that a mount point can be the slave of another  peer  group
118              while  at  the same time sharing mount and unmount events with a
119              peer group of which it is a member.  (More precisely,  one  peer
120              group can be the slave of another peer group.)
121
122       MS_UNBINDABLE
123              This  is  like a private mount, and in addition this mount can't
124              be bind mounted.  Attempts to bind mount  this  mount  (mount(2)
125              with the MS_BIND flag) will fail.
126
127              When  a  recursive  bind  mount  (mount(2)  with the MS_BIND and
128              MS_REC flags) is performed on  a  directory  subtree,  any  bind
129              mounts  within  the  subtree are automatically pruned (i.e., not
130              replicated) when replicating that subtree to produce the  target
131              subtree.
132
133       For  a  discussion of the propagation type assigned to a new mount, see
134       NOTES.
135
136       The propagation type is a per-mount-point setting;  some  mount  points
137       may be marked as shared (with each shared mount point being a member of
138       a distinct peer group), while others are private (or slaved or  unbind‐
139       able).
140
141       Note  that  a  mount's  propagation  type determines whether mounts and
142       unmounts of mount points immediately under the mount point  are  propa‐
143       gated.   Thus,  the  propagation  type  does  not affect propagation of
144       events for grandchildren and further removed descendant  mount  points.
145       What  happens  if  the mount point itself is unmounted is determined by
146       the propagation type that is in effect for  the  parent  of  the  mount
147       point.
148
149       Members  are  added  to  a  peer  group when a mount point is marked as
150       shared and either:
151
152       *  the mount point is replicated during the creation  of  a  new  mount
153          namespace; or
154
155       *  a new bind mount is created from the mount point.
156
157       In  both  of  these  cases, the new mount point joins the peer group of
158       which the existing mount point is a member.
159
160       A new peer group is also created when a child mount  point  is  created
161       under  an existing mount point that is marked as shared.  In this case,
162       the new child mount point is also marked as shared  and  the  resulting
163       peer  group  consists of all the mount points that are replicated under
164       the peers of parent mount.
165
166       A mount ceases to be a member of a peer group when either the mount  is
167       explicitly unmounted, or when the mount is implicitly unmounted because
168       a mount namespace is removed (because it has no more member processes).
169
170       The propagation type of the mount points in a mount  namespace  can  be
171       discovered  via the "optional fields" exposed in /proc/[pid]/mountinfo.
172       (See proc(5) for details of this file.)  The following tags can  appear
173       in the optional fields for a record in that file:
174
175       shared:X
176              This mount point is shared in peer group X.  Each peer group has
177              a unique ID that is automatically generated by the  kernel,  and
178              all  mount  points in the same peer group will show the same ID.
179              (These IDs are assigned starting from the value 1,  and  may  be
180              recycled when a peer group ceases to have any members.)
181
182       master:X
183              This mount is a slave to shared peer group X.
184
185       propagate_from:X (since Linux 2.6.26)
186              This  mount is a slave and receives propagation from shared peer
187              group X.  This tag will always appear in conjunction with a mas‐
188              ter:X tag.  Here, X is the closest dominant peer group under the
189              process's root directory.  If X is the immediate master  of  the
190              mount,  or  if  there  is  no dominant peer group under the same
191              root, then only the master:X field is present and not the propa‐
192              gate_from:X field.  For further details, see below.
193
194       unbindable
195              This is an unbindable mount.
196
197       If none of the above tags is present, then this is a private mount.
198
199   MS_SHARED and MS_PRIVATE example
200       Suppose  that on a terminal in the initial mount namespace, we mark one
201       mount point as shared and another as private, and then view the  mounts
202       in /proc/self/mountinfo:
203
204           sh1# mount --make-shared /mntS
205           sh1# mount --make-private /mntP
206           sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
207           77 61 8:17 / /mntS rw,relatime shared:1
208           83 61 8:15 / /mntP rw,relatime
209
210       From  the  /proc/self/mountinfo  output,  we see that /mntS is a shared
211       mount in peer group 1, and that /mntP has no optional tags,  indicating
212       that  it  is  a  private mount.  The first two fields in each record in
213       this file are the unique ID for this mount, and the  mount  ID  of  the
214       parent  mount.  We can further inspect this file to see that the parent
215       mount point of /mntS and /mntP is  the  root  directory,  /,  which  is
216       mounted as private:
217
218           sh1# cat /proc/self/mountinfo | awk '$1 == 61' | sed 's/ - .*//'
219           61 0 8:2 / / rw,relatime
220
221       On  a  second  terminal, we create a new mount namespace where we run a
222       second shell and inspect the mounts:
223
224           $ PS1='sh2# ' sudo unshare -m --propagation unchanged sh
225           sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
226           222 145 8:17 / /mntS rw,relatime shared:1
227           225 145 8:15 / /mntP rw,relatime
228
229       The new mount namespace received a copy of  the  initial  mount  names‐
230       pace's mount points.  These new mount points maintain the same propaga‐
231       tion types, but have unique mount  IDs.   (The  --propagation unchanged
232       option prevents unshare(1) from marking all mounts as private when cre‐
233       ating a new mount namespace, which it does by default.)
234
235       In the second terminal, we then create submounts under  each  of  /mntS
236       and /mntP and inspect the set-up:
237
238           sh2# mkdir /mntS/a
239           sh2# mount /dev/sdb6 /mntS/a
240           sh2# mkdir /mntP/b
241           sh2# mount /dev/sdb7 /mntP/b
242           sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
243           222 145 8:17 / /mntS rw,relatime shared:1
244           225 145 8:15 / /mntP rw,relatime
245           178 222 8:22 / /mntS/a rw,relatime shared:2
246           230 225 8:23 / /mntP/b rw,relatime
247
248       From  the  above,  it  can  be  seen that /mntS/a was created as shared
249       (inheriting this setting from its parent mount) and /mntP/b was created
250       as a private mount.
251
252       Returning  to the first terminal and inspecting the set-up, we see that
253       the new mount created under the shared mount point /mntS propagated  to
254       its peer mount (in the initial mount namespace), but the new mount cre‐
255       ated under the private mount point /mntP did not propagate:
256
257           sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
258           77 61 8:17 / /mntS rw,relatime shared:1
259           83 61 8:15 / /mntP rw,relatime
260           179 77 8:22 / /mntS/a rw,relatime shared:2
261
262   MS_SLAVE example
263       Making a mount point a slave allows it to receive propagated mount  and
264       unmount  events  from  a  master shared peer group, while preventing it
265       from propagating events to that master.  This is useful if we  want  to
266       (say) receive a mount event when an optical disk is mounted in the mas‐
267       ter shared peer group (in another mount namespace), but want to prevent
268       mount and unmount events under the slave mount from having side effects
269       in other namespaces.
270
271       We can demonstrate the effect of slaving by  first  marking  two  mount
272       points as shared in the initial mount namespace:
273
274           sh1# mount --make-shared /mntX
275           sh1# mount --make-shared /mntY
276           sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
277           132 83 8:23 / /mntX rw,relatime shared:1
278           133 83 8:22 / /mntY rw,relatime shared:2
279
280       On  a  second terminal, we create a new mount namespace and inspect the
281       mount points:
282
283           sh2# unshare -m --propagation unchanged sh
284           sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
285           168 167 8:23 / /mntX rw,relatime shared:1
286           169 167 8:22 / /mntY rw,relatime shared:2
287
288       In the new mount namespace, we then mark one of the mount points  as  a
289       slave:
290
291           sh2# mount --make-slave /mntY
292           sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
293           168 167 8:23 / /mntX rw,relatime shared:1
294           169 167 8:22 / /mntY rw,relatime master:2
295
296       From  the  above output, we see that /mntY is now a slave mount that is
297       receiving propagation events from the shared peer group with the ID 2.
298
299       Continuing in the new namespace, we  create  submounts  under  each  of
300       /mntX and /mntY:
301
302           sh2# mkdir /mntX/a
303           sh2# mount /dev/sda3 /mntX/a
304           sh2# mkdir /mntY/b
305           sh2# mount /dev/sda5 /mntY/b
306
307       When  we  inspect the state of the mount points in the new mount names‐
308       pace, we see that /mntX/a was created as a new shared mount (inheriting
309       the  "shared" setting from its parent mount) and /mntY/b was created as
310       a private mount:
311
312           sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
313           168 167 8:23 / /mntX rw,relatime shared:1
314           169 167 8:22 / /mntY rw,relatime master:2
315           173 168 8:3 / /mntX/a rw,relatime shared:3
316           175 169 8:5 / /mntY/b rw,relatime
317
318       Returning to the first terminal (in the initial  mount  namespace),  we
319       see  that  the mount /mntX/a propagated to the peer (the shared /mntX),
320       but the mount /mntY/b was not propagated:
321
322           sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
323           132 83 8:23 / /mntX rw,relatime shared:1
324           133 83 8:22 / /mntY rw,relatime shared:2
325           174 132 8:3 / /mntX/a rw,relatime shared:3
326
327       Now we create a new mount point under /mntY in the first shell:
328
329           sh1# mkdir /mntY/c
330           sh1# mount /dev/sda1 /mntY/c
331           sh1# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
332           132 83 8:23 / /mntX rw,relatime shared:1
333           133 83 8:22 / /mntY rw,relatime shared:2
334           174 132 8:3 / /mntX/a rw,relatime shared:3
335           178 133 8:1 / /mntY/c rw,relatime shared:4
336
337       When we examine the mount points in the second mount namespace, we  see
338       that  in this case the new mount has been propagated to the slave mount
339       point, and that the new mount is itself a slave mount  (to  peer  group
340       4):
341
342           sh2# cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
343           168 167 8:23 / /mntX rw,relatime shared:1
344           169 167 8:22 / /mntY rw,relatime master:2
345           173 168 8:3 / /mntX/a rw,relatime shared:3
346           175 169 8:5 / /mntY/b rw,relatime
347           179 169 8:1 / /mntY/c rw,relatime master:4
348
349   MS_UNBINDABLE example
350       One of the primary purposes of unbindable mounts is to avoid the "mount
351       point explosion" problem when repeatedly performing bind  mounts  of  a
352       higher-level  subtree  at  a  lower-level  mount point.  The problem is
353       illustrated by the following shell session.
354
355       Suppose we have a system with the following mount points:
356
357           # mount | awk '{print $1, $2, $3}'
358           /dev/sda1 on /
359           /dev/sdb6 on /mntX
360           /dev/sdb7 on /mntY
361
362       Suppose furthermore that we wish to recursively  bind  mount  the  root
363       directory  under  several  users' home directories.  We do this for the
364       first user, and inspect the mount points:
365
366           # mount --rbind / /home/cecilia/
367           # mount | awk '{print $1, $2, $3}'
368           /dev/sda1 on /
369           /dev/sdb6 on /mntX
370           /dev/sdb7 on /mntY
371           /dev/sda1 on /home/cecilia
372           /dev/sdb6 on /home/cecilia/mntX
373           /dev/sdb7 on /home/cecilia/mntY
374
375       When we repeat this operation for the second user, we start to see  the
376       explosion problem:
377
378           # mount --rbind / /home/henry
379           # mount | awk '{print $1, $2, $3}'
380           /dev/sda1 on /
381           /dev/sdb6 on /mntX
382           /dev/sdb7 on /mntY
383           /dev/sda1 on /home/cecilia
384           /dev/sdb6 on /home/cecilia/mntX
385           /dev/sdb7 on /home/cecilia/mntY
386           /dev/sda1 on /home/henry
387           /dev/sdb6 on /home/henry/mntX
388           /dev/sdb7 on /home/henry/mntY
389           /dev/sda1 on /home/henry/home/cecilia
390           /dev/sdb6 on /home/henry/home/cecilia/mntX
391           /dev/sdb7 on /home/henry/home/cecilia/mntY
392
393       Under  /home/henry,  we  have  not only recursively added the /mntX and
394       /mntY mounts, but also the recursive mounts of those directories  under
395       /home/cecilia  that  were created in the previous step.  Upon repeating
396       the step for a third user, it becomes obvious  that  the  explosion  is
397       exponential in nature:
398
399           # mount --rbind / /home/otto
400           # mount | awk '{print $1, $2, $3}'
401           /dev/sda1 on /
402           /dev/sdb6 on /mntX
403           /dev/sdb7 on /mntY
404           /dev/sda1 on /home/cecilia
405           /dev/sdb6 on /home/cecilia/mntX
406           /dev/sdb7 on /home/cecilia/mntY
407           /dev/sda1 on /home/henry
408           /dev/sdb6 on /home/henry/mntX
409           /dev/sdb7 on /home/henry/mntY
410           /dev/sda1 on /home/henry/home/cecilia
411           /dev/sdb6 on /home/henry/home/cecilia/mntX
412           /dev/sdb7 on /home/henry/home/cecilia/mntY
413           /dev/sda1 on /home/otto
414           /dev/sdb6 on /home/otto/mntX
415           /dev/sdb7 on /home/otto/mntY
416           /dev/sda1 on /home/otto/home/cecilia
417           /dev/sdb6 on /home/otto/home/cecilia/mntX
418           /dev/sdb7 on /home/otto/home/cecilia/mntY
419           /dev/sda1 on /home/otto/home/henry
420           /dev/sdb6 on /home/otto/home/henry/mntX
421           /dev/sdb7 on /home/otto/home/henry/mntY
422           /dev/sda1 on /home/otto/home/henry/home/cecilia
423           /dev/sdb6 on /home/otto/home/henry/home/cecilia/mntX
424           /dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY
425
426       The  mount  explosion  problem  in the above scenario can be avoided by
427       making each of the new mounts unbindable.  The effect of doing this  is
428       that  recursive  mounts  of  the  root directory will not replicate the
429       unbindable mounts.  We make such a mount for the first user:
430
431           # mount --rbind --make-unbindable / /home/cecilia
432
433       Before going further, we show that unbindable mounts are indeed unbind‐
434       able:
435
436           # mkdir /mntZ
437           # mount --bind /home/cecilia /mntZ
438           mount: wrong fs type, bad option, bad superblock on /home/cecilia,
439                  missing codepage or helper program, or other error
440
441                  In some cases useful info is found in syslog - try
442                  dmesg | tail or so.
443
444       Now we create unbindable recursive bind mounts for the other two users:
445
446           # mount --rbind --make-unbindable / /home/henry
447           # mount --rbind --make-unbindable / /home/otto
448
449       Upon  examining  the  list  of  mount  points, we see there has been no
450       explosion of mount points,  because  the  unbindable  mounts  were  not
451       replicated under each user's directory:
452
453           # mount | awk '{print $1, $2, $3}'
454           /dev/sda1 on /
455           /dev/sdb6 on /mntX
456           /dev/sdb7 on /mntY
457           /dev/sda1 on /home/cecilia
458           /dev/sdb6 on /home/cecilia/mntX
459           /dev/sdb7 on /home/cecilia/mntY
460           /dev/sda1 on /home/henry
461           /dev/sdb6 on /home/henry/mntX
462           /dev/sdb7 on /home/henry/mntY
463           /dev/sda1 on /home/otto
464           /dev/sdb6 on /home/otto/mntX
465           /dev/sdb7 on /home/otto/mntY
466
467   Propagation type transitions
468       The  following  table  shows the effect that applying a new propagation
469       type (i.e., mount --make-xxxx) has on the existing propagation type  of
470       a  mount point.  The rows correspond to existing propagation types, and
471       the columns are the new propagation settings.  For  reasons  of  space,
472       "private" is abbreviated as "priv" and "unbindable" as "unbind".
473
474                     make-shared   make-slave      make-priv  make-unbind
475       shared        shared        slave/priv [1]  priv       unbind
476       slave         slave+shared  slave [2]       priv       unbind
477       slave+shared  slave+shared  slave           priv       unbind
478       private       shared        priv [2]        priv       unbind
479       unbindable    shared        unbind [2]      priv       unbind
480
481       Note the following details to the table:
482
483       [1] If  a shared mount is the only mount in its peer group, making it a
484           slave automatically makes it private.
485
486       [2] Slaving a nonshared mount has no effect on the mount.
487
488   Bind (MS_BIND) semantics
489       Suppose that the following command is performed:
490
491           mount --bind A/a B/b
492
493       Here, A is the source mount point, B is the destination mount point,  a
494       is a subdirectory path under the mount point A, and b is a subdirectory
495       path under the mount point B.  The propagation type  of  the  resulting
496       mount,  B/b, depends on the propagation types of the mount points A and
497       B, and is summarized in the following table.
498
499                                    source(A)
500                            shared  private    slave         unbind
501       ───────────────────────────────────────────────────────────────
502       dest(B)  shared    | shared  shared     slave+shared  invalid
503                nonshared | shared  private    slave         invalid
504
505       Note that a recursive bind of a subtree follows the same  semantics  as
506       for  a bind operation on each mount in the subtree.  (Unbindable mounts
507       are automatically pruned at the target mount point.)
508
509       For further details, see Documentation/filesystems/sharedsubtree.txt in
510       the kernel source tree.
511
512   Move (MS_MOVE) semantics
513       Suppose that the following command is performed:
514
515           mount --move A B/b
516
517       Here,  A  is  the source mount point, B is the destination mount point,
518       and b is a subdirectory path under the mount point B.  The  propagation
519       type  of  the resulting mount, B/b, depends on the propagation types of
520       the mount points A and B, and is summarized in the following table.
521
522                                    source(A)
523                            shared  private    slave         unbind
524       ──────────────────────────────────────────────────────────────────
525       dest(B)  shared    | shared  shared     slave+shared  invalid
526                nonshared | shared  private    slave         unbindable
527
528       Note: moving a mount that resides under a shared mount is invalid.
529
530       For further details, see Documentation/filesystems/sharedsubtree.txt in
531       the kernel source tree.
532
533   Mount semantics
534       Suppose that we use the following command to create a mount point:
535
536           mount device B/b
537
538       Here,  B  is  the destination mount point, and b is a subdirectory path
539       under the mount point B.  The propagation type of the resulting  mount,
540       B/b,  follows the same rules as for a bind mount, where the propagation
541       type of the source mount is considered always to be private.
542
543   Unmount semantics
544       Suppose that we use the following command to tear down a mount point:
545
546           unmount A
547
548       Here, A is a mount point on B/b, where B is the parent mount and b is a
549       subdirectory  path  under  the mount point B.  If B is shared, then all
550       most-recently-mounted mounts at b on mounts  that  receive  propagation
551       from mount B and do not have submounts under them are unmounted.
552
553   The /proc/[pid]/mountinfo propagate_from tag
554       The  propagate_from:X  tag  is  shown  in  the  optional  fields  of  a
555       /proc/[pid]/mountinfo record in cases  where  a  process  can't  see  a
556       slave's  immediate  master  (i.e.,  the  pathname  of the master is not
557       reachable from the filesystem root directory) and so  cannot  determine
558       the chain of propagation between the mounts it can see.
559
560       In the following example, we first create a two-link master-slave chain
561       between  the  mounts  /mnt,  /tmp/etc,  and  /mnt/tmp/etc.   Then   the
562       chroot(1)  command is used to make the /tmp/etc mount point unreachable
563       from the root directory, creating  a  situation  where  the  master  of
564       /mnt/tmp/etc  is  not  reachable  from  the (new) root directory of the
565       process.
566
567       First, we bind mount the root directory onto /mnt and then  bind  mount
568       /proc  at  /mnt/proc  so  that  after  the  later chroot(1) the proc(5)
569       filesystem remains visible at the correct  location  in  the  chroot-ed
570       environment.
571
572           # mkdir -p /mnt/proc
573           # mount --bind / /mnt
574           # mount --bind /proc /mnt/proc
575
576       Next,  we  ensure  that  the /mnt mount is a shared mount in a new peer
577       group (with no peers):
578
579           # mount --make-private /mnt  # Isolate from any previous peer group
580           # mount --make-shared /mnt
581           # cat /proc/self/mountinfo | grep '/mnt' | sed 's/ - .*//'
582           239 61 8:2 / /mnt ... shared:102
583           248 239 0:4 / /mnt/proc ... shared:5
584
585       Next, we bind mount /mnt/etc onto /tmp/etc:
586
587           # mkdir -p /tmp/etc
588           # mount --bind /mnt/etc /tmp/etc
589           # cat /proc/self/mountinfo | egrep '/mnt|/tmp/' | sed 's/ - .*//'
590           239 61 8:2 / /mnt ... shared:102
591           248 239 0:4 / /mnt/proc ... shared:5
592           267 40 8:2 /etc /tmp/etc ... shared:102
593
594       Initially, these two mount points are in the same peer  group,  but  we
595       then  make  the  /tmp/etc  a  slave of /mnt/etc, and then make /tmp/etc
596       shared as well, so that it can propagate events to the  next  slave  in
597       the chain:
598
599           # mount --make-slave /tmp/etc
600           # mount --make-shared /tmp/etc
601           # cat /proc/self/mountinfo | egrep '/mnt|/tmp/' | sed 's/ - .*//'
602           239 61 8:2 / /mnt ... shared:102
603           248 239 0:4 / /mnt/proc ... shared:5
604           267 40 8:2 /etc /tmp/etc ... shared:105 master:102
605
606       Then  we  bind  mount /tmp/etc onto /mnt/tmp/etc.  Again, the two mount
607       points are  initially  in  the  same  peer  group,  but  we  then  make
608       /mnt/tmp/etc a slave of /tmp/etc:
609
610           # mkdir -p /mnt/tmp/etc
611           # mount --bind /tmp/etc /mnt/tmp/etc
612           # mount --make-slave /mnt/tmp/etc
613           # cat /proc/self/mountinfo | egrep '/mnt|/tmp/' | sed 's/ - .*//'
614           239 61 8:2 / /mnt ... shared:102
615           248 239 0:4 / /mnt/proc ... shared:5
616           267 40 8:2 /etc /tmp/etc ... shared:105 master:102
617           273 239 8:2 /etc /mnt/tmp/etc ... master:105
618
619       From  the  above, we see that /mnt is the master of the slave /tmp/etc,
620       which in turn is the master of the slave /mnt/tmp/etc.
621
622       We then chroot(1) to the /mnt directory, which renders the  mount  with
623       ID 267 unreachable from the (new) root directory:
624
625           # chroot /mnt
626
627       When  we  examine the state of the mounts inside the chroot-ed environ‐
628       ment, we see the following:
629
630           # cat /proc/self/mountinfo | sed 's/ - .*//'
631           239 61 8:2 / / ... shared:102
632           248 239 0:4 / /proc ... shared:5
633           273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102
634
635       Above, we see that the mount with ID 273 is a slave whose master is the
636       peer group 105.  The mount point for that master is unreachable, and so
637       a propagate_from tag is displayed, indicating that the closest dominant
638       peer  group  (i.e.,  the nearest reachable mount in the slave chain) is
639       the peer group with the ID 102 (corresponding to the /mnt  mount  point
640       before the chroot(1) was performed.
641

VERSIONS

643       Mount namespaces first appeared in Linux 2.4.19.
644

CONFORMING TO

646       Namespaces are a Linux-specific feature.
647

NOTES

649       The propagation type assigned to a new mount point depends on the prop‐
650       agation type of the parent mount.  If the  mount  point  has  a  parent
651       (i.e.,  it  is  a non-root mount point) and the propagation type of the
652       parent is MS_SHARED, then the propagation type of the new mount is also
653       MS_SHARED.  Otherwise, the propagation type of the new mount is MS_PRI‐
654       VATE.
655
656       Notwithstanding the fact that the  default  propagation  type  for  new
657       mount  points  is in many cases MS_PRIVATE, MS_SHARED is typically more
658       useful.  For this reason, systemd(1) automatically remounts  all  mount
659       points  as  MS_SHARED on system startup.  Thus, on most modern systems,
660       the default propagation type is in practice MS_SHARED.
661
662       Since, when one uses unshare(1) to create a mount namespace,  the  goal
663       is  commonly  to  provide full isolation of the mount points in the new
664       namespace, unshare(1) (since util-linux version 2.27) in turn  reverses
665       the step performed by systemd(1), by making all mount points private in
666       the new namespace.  That is, unshare(1) performs the equivalent of  the
667       following in the new mount namespace:
668
669           mount --make-rprivate /
670
671       To  prevent  this,  one  can  use the --propagation unchanged option to
672       unshare(1).
673
674       An application that  creates  a  new  mount  namespace  directly  using
675       clone(2)  or  unshare(2)  may  desire  to  prevent propagation of mount
676       events to other mount namespaces (as is done by unshare(1)).  This  can
677       be  done  by  changing  the propagation type of mount points in the new
678       namespace to either MS_SLAVE or MS_PRIVATE.  using a call such  as  the
679       following:
680
681                  mount(NULL, "/", MS_SLAVE | MS_REC, NULL);
682
683       For  a discussion of propagation types when moving mounts (MS_MOVE) and
684       creating bind mounts (MS_BIND),  see  Documentation/filesystems/shared‐
685       subtree.txt.
686

EXAMPLE

688       See pivot_root(2).
689

SEE ALSO

691       unshare(1),  clone(2),  mount(2),  pivot_root(2),  setns(2), umount(2),
692       unshare(2),  proc(5),  namespaces(7),  user_namespaces(7),  findmnt(8),
693       pivot_root(8)
694
695       Documentation/filesystems/sharedsubtree.txt in the kernel source tree.
696

COLOPHON

698       This  page  is  part of release 5.04 of the Linux man-pages project.  A
699       description of the project, information about reporting bugs,  and  the
700       latest     version     of     this    page,    can    be    found    at
701       https://www.kernel.org/doc/man-pages/.
702
703
704
705Linux                             2019-08-02               MOUNT_NAMESPACES(7)
Impressum