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