man7/mount_namespaces.7

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