man7/mount_namespaces.7

   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 2019-08-02 "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 '/mnt' | sed 's/ \- .*//'\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
 670
 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 shared  shared  slave/priv [1]  priv    unbind
 722 slave   slave+shared    slave [2]       priv    unbind
 723 slave+shared    slave+shared    slave   priv    unbind
 724 private shared  priv [2]        priv    unbind
 725 unbindable      shared  unbind [2]      priv    unbind
 726 .TE
 727 .sp 1
 728 Note the following details to the table:
 729 .IP [1] 4
 730 If a shared mount is the only mount in its peer group,
 731 making it a slave automatically makes it private.
 732 .IP [2]
 733 Slaving a nonshared mount has no effect on the mount.
 734 .\"
 735 .SS Bind (MS_BIND) semantics
 736 Suppose that the following command is performed:
 737 .PP
 738 .in +4n
 739 .EX
 740 mount \-\-bind A/a B/b
 741 .EE
 742 .in
 743 .PP
 744 Here,
 745 .I A
 746 is the source mount point,
 747 .I B
 748 is the destination mount point,
 749 .I a
 750 is a subdirectory path under the mount point
 751 .IR A ,
 752 and
 753 .I b
 754 is a subdirectory path under the mount point
 755 .IR B .
 756 The propagation type of the resulting mount,
 757 .IR B/b ,
 758 depends on the propagation types of the mount points
 759 .IR A
 760 and
 761 .IR B ,
 762 and is summarized in the following table.
 763 .PP
 764 .TS
 765 lb2 lb1 lb2 lb2 lb2 lb0
 766 lb2 lb1 lb2 lb2 lb2 lb0
 767 lb lb l l l l l.
 768                         source(A)
 769                 shared  private slave   unbind
 770 _
 771 dest(B) shared    |     shared  shared  slave+shared    invalid
 772         nonshared |     shared  private slave   invalid
 773 .TE
 774 .sp 1
 775 Note that a recursive bind of a subtree follows the same semantics
 776 as for a bind operation on each mount in the subtree.
 777 (Unbindable mounts are automatically pruned at the target mount point.)
 778 .PP
 779 For further details, see
 780 .I Documentation/filesystems/sharedsubtree.txt
 781 in the kernel source tree.
 782 .\"
 783 .SS Move (MS_MOVE) semantics
 784 Suppose that the following command is performed:
 785 .PP
 786 .in +4n
 787 .EX
 788 mount \-\-move A B/b
 789 .EE
 790 .in
 791 .PP
 792 Here,
 793 .I A
 794 is the source mount point,
 795 .I B
 796 is the destination mount point, and
 797 .I b
 798 is a subdirectory path under the mount point
 799 .IR B .
 800 The propagation type of the resulting mount,
 801 .IR B/b ,
 802 depends on the propagation types of the mount points
 803 .IR A
 804 and
 805 .IR B ,
 806 and is summarized in the following table.
 807 .PP
 808 .TS
 809 lb2 lb1 lb2 lb2 lb2 lb0
 810 lb2 lb1 lb2 lb2 lb2 lb0
 811 lb lb l l l l l.
 812                         source(A)
 813                 shared  private slave   unbind
 814 _
 815 dest(B) shared    |     shared  shared  slave+shared    invalid
 816         nonshared |     shared  private slave   unbindable
 817 .TE
 818 .sp 1
 819 Note: moving a mount that resides under a shared mount is invalid.
 820 .PP
 821 For further details, see
 822 .I Documentation/filesystems/sharedsubtree.txt
 823 in the kernel source tree.
 824 .\"
 825 .SS Mount semantics
 826 Suppose that we use the following command to create a mount point:
 827 .PP
 828 .in +4n
 829 .EX
 830 mount device B/b
 831 .EE
 832 .in
 833 .PP
 834 Here,
 835 .I B
 836 is the destination mount point, and
 837 .I b
 838 is a subdirectory path under the mount point
 839 .IR B .
 840 The propagation type of the resulting mount,
 841 .IR B/b ,
 842 follows the same rules as for a bind mount,
 843 where the propagation type of the source mount
 844 is considered always to be private.
 845 .\"
 846 .SS Unmount semantics
 847 Suppose that we use the following command to tear down a mount point:
 848 .PP
 849 .in +4n
 850 .EX
 851 unmount A
 852 .EE
 853 .in
 854 .PP
 855 Here,
 856 .I A
 857 is a mount point on
 858 .IR B/b ,
 859 where
 860 .I B
 861 is the parent mount and
 862 .I b
 863 is a subdirectory path under the mount point
 864 .IR B .
 865 If
 866 .B B
 867 is shared, then all most-recently-mounted mounts at
 868 .I b
 869 on mounts that receive propagation from mount
 870 .I B
 871 and do not have submounts under them are unmounted.
 872 .\"
 873 .SS The /proc/[pid]/mountinfo "propagate_from" tag
 874 The
 875 .I propagate_from:X
 876 tag is shown in the optional fields of a
 877 .IR /proc/[pid]/mountinfo
 878 record in cases where a process can't see a slave's immediate master
 879 (i.e., the pathname of the master is not reachable from
 880 the filesystem root directory)
 881 and so cannot determine the
 882 chain of propagation between the mounts it can see.
 883 .PP
 884 In the following example, we first create a two-link master-slave chain
 885 between the mounts
 886 .IR /mnt ,
 887 .IR /tmp/etc ,
 888 and
 889 .IR /mnt/tmp/etc .
 890 Then the
 891 .BR chroot (1)
 892 command is used to make the
 893 .IR /tmp/etc
 894 mount point unreachable from the root directory,
 895 creating a situation where the master of
 896 .IR /mnt/tmp/etc
 897 is not reachable from the (new) root directory of the process.
 898 .PP
 899 First, we bind mount the root directory onto
 900 .IR /mnt
 901 and then bind mount
 902 .IR /proc
 903 at
 904 .IR /mnt/proc
 905 so that after the later
 906 .BR chroot (1)
 907 the
 908 .BR proc (5)
 909 filesystem remains visible at the correct location
 910 in the chroot-ed environment.
 911 .PP
 912 .in +4n
 913 .EX
 914 # \fBmkdir \-p /mnt/proc\fP
 915 # \fBmount \-\-bind / /mnt\fP
 916 # \fBmount \-\-bind /proc /mnt/proc\fP
 917 .EE
 918 .in
 919 .PP
 920 Next, we ensure that the
 921 .IR /mnt
 922 mount is a shared mount in a new peer group (with no peers):
 923 .PP
 924 .in +4n
 925 .EX
 926 # \fBmount \-\-make\-private /mnt\fP  # Isolate from any previous peer group
 927 # \fBmount \-\-make\-shared /mnt\fP
 928 # \fBcat /proc/self/mountinfo | grep \(aq/mnt\(aq | sed \(aqs/ \- .*//\(aq\fP
 929 239 61 8:2 / /mnt ... shared:102
 930 248 239 0:4 / /mnt/proc ... shared:5
 931 .EE
 932 .in
 933 .PP
 934 Next, we bind mount
 935 .IR /mnt/etc
 936 onto
 937 .IR /tmp/etc :
 938 .PP
 939 .in +4n
 940 .EX
 941 # \fBmkdir \-p /tmp/etc\fP
 942 # \fBmount \-\-bind /mnt/etc /tmp/etc\fP
 943 # \fBcat /proc/self/mountinfo | egrep \(aq/mnt|/tmp/\(aq | sed \(aqs/ \- .*//\(aq\fP
 944 239 61 8:2 / /mnt ... shared:102
 945 248 239 0:4 / /mnt/proc ... shared:5
 946 267 40 8:2 /etc /tmp/etc ... shared:102
 947 .EE
 948 .in
 949 .PP
 950 Initially, these two mount points are in the same peer group,
 951 but we then make the
 952 .IR /tmp/etc
 953 a slave of
 954 .IR /mnt/etc ,
 955 and then make
 956 .IR /tmp/etc
 957 shared as well,
 958 so that it can propagate events to the next slave in the chain:
 959 .PP
 960 .in +4n
 961 .EX
 962 # \fBmount \-\-make\-slave /tmp/etc\fP
 963 # \fBmount \-\-make\-shared /tmp/etc\fP
 964 # \fBcat /proc/self/mountinfo | egrep \(aq/mnt|/tmp/\(aq | sed \(aqs/ \- .*//\(aq\fP
 965 239 61 8:2 / /mnt ... shared:102
 966 248 239 0:4 / /mnt/proc ... shared:5
 967 267 40 8:2 /etc /tmp/etc ... shared:105 master:102
 968 .EE
 969 .in
 970 .PP
 971 Then we bind mount
 972 .IR /tmp/etc
 973 onto
 974 .IR /mnt/tmp/etc .
 975 Again, the two mount points are initially in the same peer group,
 976 but we then make
 977 .IR /mnt/tmp/etc
 978 a slave of
 979 .IR /tmp/etc :
 980 .PP
 981 .in +4n
 982 .EX
 983 # \fBmkdir \-p /mnt/tmp/etc\fP
 984 # \fBmount \-\-bind /tmp/etc /mnt/tmp/etc\fP
 985 # \fBmount \-\-make\-slave /mnt/tmp/etc\fP
 986 # \fBcat /proc/self/mountinfo | egrep \(aq/mnt|/tmp/\(aq | sed \(aqs/ \- .*//\(aq\fP
 987 239 61 8:2 / /mnt ... shared:102
 988 248 239 0:4 / /mnt/proc ... shared:5
 989 267 40 8:2 /etc /tmp/etc ... shared:105 master:102
 990 273 239 8:2 /etc /mnt/tmp/etc ... master:105
 991 .EE
 992 .in
 993 .PP
 994 From the above, we see that
 995 .IR /mnt
 996 is the master of the slave
 997 .IR /tmp/etc ,
 998 which in turn is the master of the slave
 999 .IR /mnt/tmp/etc .
1000 .PP
1001 We then
1002 .BR chroot (1)
1003 to the
1004 .IR /mnt
1005 directory, which renders the mount with ID 267 unreachable
1006 from the (new) root directory:
1007 .PP
1008 .in +4n
1009 .EX
1010 # \fBchroot /mnt\fP
1011 .EE
1012 .in
1013 .PP
1014 When we examine the state of the mounts inside the chroot-ed environment,
1015 we see the following:
1016 .PP
1017 .in +4n
1018 .EX
1019 # \fBcat /proc/self/mountinfo | sed \(aqs/ \- .*//\(aq\fP
1020 239 61 8:2 / / ... shared:102
1021 248 239 0:4 / /proc ... shared:5
1022 273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102
1023 .EE
1024 .in
1025 .PP
1026 Above, we see that the mount with ID 273
1027 is a slave whose master is the peer group 105.
1028 The mount point for that master is unreachable, and so a
1029 .IR propagate_from
1030 tag is displayed, indicating that the closest dominant peer group
1031 (i.e., the nearest reachable mount in the slave chain)
1032 is the peer group with the ID 102 (corresponding to the
1033 .IR /mnt
1034 mount point before the
1035 .BR chroot (1)
1036 was performed.
1037 .\"
1038 .SH VERSIONS
1039 Mount namespaces first appeared in Linux 2.4.19.
1040 .SH CONFORMING TO
1041 Namespaces are a Linux-specific feature.
1042 .\"
1043 .SH NOTES
1044 The propagation type assigned to a new mount point depends
1045 on the propagation type of the parent mount.
1046 If the mount point has a parent (i.e., it is a non-root mount
1047 point) and the propagation type of the parent is
1048 .BR MS_SHARED ,
1049 then the propagation type of the new mount is also
1050 .BR MS_SHARED .
1051 Otherwise, the propagation type of the new mount is
1052 .BR MS_PRIVATE .
1053 .PP
1054 Notwithstanding the fact that the default propagation type
1055 for new mount points is in many cases
1056 .BR MS_PRIVATE ,
1057 .BR MS_SHARED
1058 is typically more useful.
1059 For this reason,
1060 .BR systemd (1)
1061 automatically remounts all mount points as
1062 .BR MS_SHARED
1063 on system startup.
1064 Thus, on most modern systems, the default propagation type is in practice
1065 .BR MS_SHARED .
1066 .PP
1067 Since, when one uses
1068 .BR unshare (1)
1069 to create a mount namespace,
1070 the goal is commonly to provide full isolation of the mount points
1071 in the new namespace,
1072 .BR unshare (1)
1073 (since
1074 .IR util-linux
1075 version 2.27) in turn reverses the step performed by
1076 .BR systemd (1),
1077 by making all mount points private in the new namespace.
1078 That is,
1079 .BR unshare (1)
1080 performs the equivalent of the following in the new mount namespace:
1081 .PP
1082 .in +4n
1083 .EX
1084 mount \-\-make\-rprivate /
1085 .EE
1086 .in
1087 .PP
1088 To prevent this, one can use the
1089 .IR "\-\-propagation\ unchanged"
1090 option to
1091 .BR unshare (1).
1092 .PP
1093 An application that creates a new mount namespace directly using
1094 .BR clone (2)
1095 or
1096 .BR unshare (2)
1097 may desire to prevent propagation of mount events to other mount namespaces
1098 (as is done by
1099 .BR unshare (1)).
1100 This can be done by changing the propagation type of
1101 mount points in the new namespace to either
1102 .BR MS_SLAVE
1103 or
1104 .BR MS_PRIVATE .
1105 using a call such as the following:
1106 .PP
1107 .in +4n
1108 .EX
1109 mount(NULL, "/", MS_SLAVE | MS_REC, NULL);
1110 .EE
1111 .in
1112 .PP
1113 For a discussion of propagation types when moving mounts
1114 .RB ( MS_MOVE )
1115 and creating bind mounts
1116 .RB ( MS_BIND ),
1117 see
1118 .IR Documentation/filesystems/sharedsubtree.txt .
1119 .SH EXAMPLE
1120 See
1121 .BR pivot_root (2).
1122 .SH SEE ALSO
1123 .BR unshare (1),
1124 .BR clone (2),
1125 .BR mount (2),
1126 .BR pivot_root (2),
1127 .BR setns (2),
1128 .BR umount (2),
1129 .BR unshare (2),
1130 .BR proc (5),
1131 .BR namespaces (7),
1132 .BR user_namespaces (7),
1133 .BR findmnt (8),
1134 .BR mount (8),
1135 .BR pivot_root (8),
1136 .BR umount (8)
1137 .PP
1138 .IR Documentation/filesystems/sharedsubtree.txt
1139 in the kernel source tree.