Documentation/filesystems/sharedsubtree.txt

   1 Shared Subtrees
   2 ---------------
   3
   4 Contents:
   5         1) Overview
   6         2) Features
   7         3) smount command
   8         4) Use-case
   9         5) Detailed semantics
  10         6) Quiz
  11         7) FAQ
  12         8) Implementation
  13
  14
  15 1) Overview
  16 -----------
  17
  18 Consider the following situation:
  19
  20 A process wants to clone its own namespace, but still wants to access the CD
  21 that got mounted recently.  Shared subtree semantics provide the necessary
  22 mechanism to accomplish the above.
  23
  24 It provides the necessary building blocks for features like per-user-namespace
  25 and versioned filesystem.
  26
  27 2) Features
  28 -----------
  29
  30 Shared subtree provides four different flavors of mounts; struct vfsmount to be
  31 precise
  32
  33         a. shared mount
  34         b. slave mount
  35         c. private mount
  36         d. unbindable mount
  37
  38
  39 2a) A shared mount can be replicated to as many mountpoints and all the
  40 replicas continue to be exactly same.
  41
  42         Here is an example:
  43
  44         Let's say /mnt has a mount that is shared.
  45         mount --make-shared /mnt
  46
  47         Note: mount(8) command now supports the --make-shared flag,
  48         so the sample 'smount' program is no longer needed and has been
  49         removed.
  50
  51         # mount --bind /mnt /tmp
  52         The above command replicates the mount at /mnt to the mountpoint /tmp
  53         and the contents of both the mounts remain identical.
  54
  55         #ls /mnt
  56         a b c
  57
  58         #ls /tmp
  59         a b c
  60
  61         Now let's say we mount a device at /tmp/a
  62         # mount /dev/sd0  /tmp/a
  63
  64         #ls /tmp/a
  65         t1 t2 t2
  66
  67         #ls /mnt/a
  68         t1 t2 t2
  69
  70         Note that the mount has propagated to the mount at /mnt as well.
  71
  72         And the same is true even when /dev/sd0 is mounted on /mnt/a. The
  73         contents will be visible under /tmp/a too.
  74
  75
  76 2b) A slave mount is like a shared mount except that mount and umount events
  77         only propagate towards it.
  78
  79         All slave mounts have a master mount which is a shared.
  80
  81         Here is an example:
  82
  83         Let's say /mnt has a mount which is shared.
  84         # mount --make-shared /mnt
  85
  86         Let's bind mount /mnt to /tmp
  87         # mount --bind /mnt /tmp
  88
  89         the new mount at /tmp becomes a shared mount and it is a replica of
  90         the mount at /mnt.
  91
  92         Now let's make the mount at /tmp; a slave of /mnt
  93         # mount --make-slave /tmp
  94
  95         let's mount /dev/sd0 on /mnt/a
  96         # mount /dev/sd0 /mnt/a
  97
  98         #ls /mnt/a
  99         t1 t2 t3
 100
 101         #ls /tmp/a
 102         t1 t2 t3
 103
 104         Note the mount event has propagated to the mount at /tmp
 105
 106         However let's see what happens if we mount something on the mount at /tmp
 107
 108         # mount /dev/sd1 /tmp/b
 109
 110         #ls /tmp/b
 111         s1 s2 s3
 112
 113         #ls /mnt/b
 114
 115         Note how the mount event has not propagated to the mount at
 116         /mnt
 117
 118
 119 2c) A private mount does not forward or receive propagation.
 120
 121         This is the mount we are familiar with. Its the default type.
 122
 123
 124 2d) A unbindable mount is a unbindable private mount
 125
 126         let's say we have a mount at /mnt and we make is unbindable
 127
 128         # mount --make-unbindable /mnt
 129
 130          Let's try to bind mount this mount somewhere else.
 131          # mount --bind /mnt /tmp
 132          mount: wrong fs type, bad option, bad superblock on /mnt,
 133                 or too many mounted file systems
 134
 135         Binding a unbindable mount is a invalid operation.
 136
 137
 138 3) smount command
 139
 140         Modern mount(8) command is aware of shared subtree features,
 141         so use it instead of the 'smount' command. [source code removed]
 142
 143
 144 4) Use cases
 145 ------------
 146
 147         A) A process wants to clone its own namespace, but still wants to
 148            access the CD that got mounted recently.
 149
 150            Solution:
 151
 152                 The system administrator can make the mount at /cdrom shared
 153                 mount --bind /cdrom /cdrom
 154                 mount --make-shared /cdrom
 155
 156                 Now any process that clones off a new namespace will have a
 157                 mount at /cdrom which is a replica of the same mount in the
 158                 parent namespace.
 159
 160                 So when a CD is inserted and mounted at /cdrom that mount gets
 161                 propagated to the other mount at /cdrom in all the other clone
 162                 namespaces.
 163
 164         B) A process wants its mounts invisible to any other process, but
 165         still be able to see the other system mounts.
 166
 167            Solution:
 168
 169                 To begin with, the administrator can mark the entire mount tree
 170                 as shareable.
 171
 172                 mount --make-rshared /
 173
 174                 A new process can clone off a new namespace. And mark some part
 175                 of its namespace as slave
 176
 177                 mount --make-rslave /myprivatetree
 178
 179                 Hence forth any mounts within the /myprivatetree done by the
 180                 process will not show up in any other namespace. However mounts
 181                 done in the parent namespace under /myprivatetree still shows
 182                 up in the process's namespace.
 183
 184
 185         Apart from the above semantics this feature provides the
 186         building blocks to solve the following problems:
 187
 188         C)  Per-user namespace
 189
 190                 The above semantics allows a way to share mounts across
 191                 namespaces.  But namespaces are associated with processes. If
 192                 namespaces are made first class objects with user API to
 193                 associate/disassociate a namespace with userid, then each user
 194                 could have his/her own namespace and tailor it to his/her
 195                 requirements. Offcourse its needs support from PAM.
 196
 197         D)  Versioned files
 198
 199                 If the entire mount tree is visible at multiple locations, then
 200                 a underlying versioning file system can return different
 201                 version of the file depending on the path used to access that
 202                 file.
 203
 204                 An example is:
 205
 206                 mount --make-shared /
 207                 mount --rbind / /view/v1
 208                 mount --rbind / /view/v2
 209                 mount --rbind / /view/v3
 210                 mount --rbind / /view/v4
 211
 212                 and if /usr has a versioning filesystem mounted, than that
 213                 mount appears at /view/v1/usr, /view/v2/usr, /view/v3/usr and
 214                 /view/v4/usr too
 215
 216                 A user can request v3 version of the file /usr/fs/namespace.c
 217                 by accessing /view/v3/usr/fs/namespace.c . The underlying
 218                 versioning filesystem can then decipher that v3 version of the
 219                 filesystem is being requested and return the corresponding
 220                 inode.
 221
 222 5) Detailed semantics:
 223 -------------------
 224         The section below explains the detailed semantics of
 225         bind, rbind, move, mount, umount and clone-namespace operations.
 226
 227         Note: the word 'vfsmount' and the noun 'mount' have been used
 228         to mean the same thing, throughout this document.
 229
 230 5a) Mount states
 231
 232         A given mount can be in one of the following states
 233         1) shared
 234         2) slave
 235         3) shared and slave
 236         4) private
 237         5) unbindable
 238
 239         A 'propagation event' is defined as event generated on a vfsmount
 240         that leads to mount or unmount actions in other vfsmounts.
 241
 242         A 'peer group' is defined as a group of vfsmounts that propagate
 243         events to each other.
 244
 245         (1) Shared mounts
 246
 247                 A 'shared mount' is defined as a vfsmount that belongs to a
 248                 'peer group'.
 249
 250                 For example:
 251                         mount --make-shared /mnt
 252                         mount --bin /mnt /tmp
 253
 254                 The mount at /mnt and that at /tmp are both shared and belong
 255                 to the same peer group. Anything mounted or unmounted under
 256                 /mnt or /tmp reflect in all the other mounts of its peer
 257                 group.
 258
 259
 260         (2) Slave mounts
 261
 262                 A 'slave mount' is defined as a vfsmount that receives
 263                 propagation events and does not forward propagation events.
 264
 265                 A slave mount as the name implies has a master mount from which
 266                 mount/unmount events are received. Events do not propagate from
 267                 the slave mount to the master.  Only a shared mount can be made
 268                 a slave by executing the following command
 269
 270                         mount --make-slave mount
 271
 272                 A shared mount that is made as a slave is no more shared unless
 273                 modified to become shared.
 274
 275         (3) Shared and Slave
 276
 277                 A vfsmount can be both shared as well as slave.  This state
 278                 indicates that the mount is a slave of some vfsmount, and
 279                 has its own peer group too.  This vfsmount receives propagation
 280                 events from its master vfsmount, and also forwards propagation
 281                 events to its 'peer group' and to its slave vfsmounts.
 282
 283                 Strictly speaking, the vfsmount is shared having its own
 284                 peer group, and this peer-group is a slave of some other
 285                 peer group.
 286
 287                 Only a slave vfsmount can be made as 'shared and slave' by
 288                 either executing the following command
 289                         mount --make-shared mount
 290                 or by moving the slave vfsmount under a shared vfsmount.
 291
 292         (4) Private mount
 293
 294                 A 'private mount' is defined as vfsmount that does not
 295                 receive or forward any propagation events.
 296
 297         (5) Unbindable mount
 298
 299                 A 'unbindable mount' is defined as vfsmount that does not
 300                 receive or forward any propagation events and cannot
 301                 be bind mounted.
 302
 303
 304         State diagram:
 305         The state diagram below explains the state transition of a mount,
 306         in response to various commands.
 307         ------------------------------------------------------------------------
 308         |             |make-shared |  make-slave  | make-private |make-unbindab|
 309         --------------|------------|--------------|--------------|-------------|
 310         |shared       |shared      |*slave/private|   private    | unbindable  |
 311         |             |            |              |              |             |
 312         |-------------|------------|--------------|--------------|-------------|
 313         |slave        |shared      |    **slave   |    private   | unbindable  |
 314         |             |and slave   |              |              |             |
 315         |-------------|------------|--------------|--------------|-------------|
 316         |shared       |shared      |    slave     |    private   | unbindable  |
 317         |and slave    |and slave   |              |              |             |
 318         |-------------|------------|--------------|--------------|-------------|
 319         |private      |shared      |  **private   |    private   | unbindable  |
 320         |-------------|------------|--------------|--------------|-------------|
 321         |unbindable   |shared      |**unbindable  |    private   | unbindable  |
 322         ------------------------------------------------------------------------
 323
 324         * if the shared mount is the only mount in its peer group, making it
 325         slave, makes it private automatically. Note that there is no master to
 326         which it can be slaved to.
 327
 328         ** slaving a non-shared mount has no effect on the mount.
 329
 330         Apart from the commands listed below, the 'move' operation also changes
 331         the state of a mount depending on type of the destination mount. Its
 332         explained in section 5d.
 333
 334 5b) Bind semantics
 335
 336         Consider the following command
 337
 338         mount --bind A/a  B/b
 339
 340         where 'A' is the source mount, 'a' is the dentry in the mount 'A', 'B'
 341         is the destination mount and 'b' is the dentry in the destination mount.
 342
 343         The outcome depends on the type of mount of 'A' and 'B'. The table
 344         below contains quick reference.
 345    ---------------------------------------------------------------------------
 346    |         BIND MOUNT OPERATION                                            |
 347    |**************************************************************************
 348    |source(A)->| shared       |       private  |       slave    | unbindable |
 349    | dest(B)  |               |                |                |            |
 350    |   |      |               |                |                |            |
 351    |   v      |               |                |                |            |
 352    |**************************************************************************
 353    |  shared  | shared        |     shared     | shared & slave |  invalid   |
 354    |          |               |                |                |            |
 355    |non-shared| shared        |      private   |      slave     |  invalid   |
 356    ***************************************************************************
 357
 358         Details:
 359
 360         1. 'A' is a shared mount and 'B' is a shared mount. A new mount 'C'
 361         which is clone of 'A', is created. Its root dentry is 'a' . 'C' is
 362         mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ...
 363         are created and mounted at the dentry 'b' on all mounts where 'B'
 364         propagates to. A new propagation tree containing 'C1',..,'Cn' is
 365         created. This propagation tree is identical to the propagation tree of
 366         'B'.  And finally the peer-group of 'C' is merged with the peer group
 367         of 'A'.
 368
 369         2. 'A' is a private mount and 'B' is a shared mount. A new mount 'C'
 370         which is clone of 'A', is created. Its root dentry is 'a'. 'C' is
 371         mounted on mount 'B' at dentry 'b'. Also new mount 'C1', 'C2', 'C3' ...
 372         are created and mounted at the dentry 'b' on all mounts where 'B'
 373         propagates to. A new propagation tree is set containing all new mounts
 374         'C', 'C1', .., 'Cn' with exactly the same configuration as the
 375         propagation tree for 'B'.
 376
 377         3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount. A new
 378         mount 'C' which is clone of 'A', is created. Its root dentry is 'a' .
 379         'C' is mounted on mount 'B' at dentry 'b'. Also new mounts 'C1', 'C2',
 380         'C3' ... are created and mounted at the dentry 'b' on all mounts where
 381         'B' propagates to. A new propagation tree containing the new mounts
 382         'C','C1',..  'Cn' is created. This propagation tree is identical to the
 383         propagation tree for 'B'. And finally the mount 'C' and its peer group
 384         is made the slave of mount 'Z'.  In other words, mount 'C' is in the
 385         state 'slave and shared'.
 386
 387         4. 'A' is a unbindable mount and 'B' is a shared mount. This is a
 388         invalid operation.
 389
 390         5. 'A' is a private mount and 'B' is a non-shared(private or slave or
 391         unbindable) mount. A new mount 'C' which is clone of 'A', is created.
 392         Its root dentry is 'a'. 'C' is mounted on mount 'B' at dentry 'b'.
 393
 394         6. 'A' is a shared mount and 'B' is a non-shared mount. A new mount 'C'
 395         which is a clone of 'A' is created. Its root dentry is 'a'. 'C' is
 396         mounted on mount 'B' at dentry 'b'.  'C' is made a member of the
 397         peer-group of 'A'.
 398
 399         7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount. A
 400         new mount 'C' which is a clone of 'A' is created. Its root dentry is
 401         'a'.  'C' is mounted on mount 'B' at dentry 'b'. Also 'C' is set as a
 402         slave mount of 'Z'. In other words 'A' and 'C' are both slave mounts of
 403         'Z'.  All mount/unmount events on 'Z' propagates to 'A' and 'C'. But
 404         mount/unmount on 'A' do not propagate anywhere else. Similarly
 405         mount/unmount on 'C' do not propagate anywhere else.
 406
 407         8. 'A' is a unbindable mount and 'B' is a non-shared mount. This is a
 408         invalid operation. A unbindable mount cannot be bind mounted.
 409
 410 5c) Rbind semantics
 411
 412         rbind is same as bind. Bind replicates the specified mount.  Rbind
 413         replicates all the mounts in the tree belonging to the specified mount.
 414         Rbind mount is bind mount applied to all the mounts in the tree.
 415
 416         If the source tree that is rbind has some unbindable mounts,
 417         then the subtree under the unbindable mount is pruned in the new
 418         location.
 419
 420         eg: let's say we have the following mount tree.
 421
 422                 A
 423               /   \
 424               B   C
 425              / \ / \
 426              D E F G
 427
 428              Let's say all the mount except the mount C in the tree are
 429              of a type other than unbindable.
 430
 431              If this tree is rbound to say Z
 432
 433              We will have the following tree at the new location.
 434
 435                 Z
 436                 |
 437                 A'
 438                /
 439               B'                Note how the tree under C is pruned
 440              / \                in the new location.
 441             D' E'
 442
 443
 444
 445 5d) Move semantics
 446
 447         Consider the following command
 448
 449         mount --move A  B/b
 450
 451         where 'A' is the source mount, 'B' is the destination mount and 'b' is
 452         the dentry in the destination mount.
 453
 454         The outcome depends on the type of the mount of 'A' and 'B'. The table
 455         below is a quick reference.
 456    ---------------------------------------------------------------------------
 457    |                    MOVE MOUNT OPERATION                                 |
 458    |**************************************************************************
 459    | source(A)->| shared      |       private  |       slave    | unbindable |
 460    | dest(B)  |               |                |                |            |
 461    |   |      |               |                |                |            |
 462    |   v      |               |                |                |            |
 463    |**************************************************************************
 464    |  shared  | shared        |     shared     |shared and slave|  invalid   |
 465    |          |               |                |                |            |
 466    |non-shared| shared        |      private   |    slave       | unbindable |
 467    ***************************************************************************
 468         NOTE: moving a mount residing under a shared mount is invalid.
 469
 470       Details follow:
 471
 472         1. 'A' is a shared mount and 'B' is a shared mount.  The mount 'A' is
 473         mounted on mount 'B' at dentry 'b'.  Also new mounts 'A1', 'A2'...'An'
 474         are created and mounted at dentry 'b' on all mounts that receive
 475         propagation from mount 'B'. A new propagation tree is created in the
 476         exact same configuration as that of 'B'. This new propagation tree
 477         contains all the new mounts 'A1', 'A2'...  'An'.  And this new
 478         propagation tree is appended to the already existing propagation tree
 479         of 'A'.
 480
 481         2. 'A' is a private mount and 'B' is a shared mount. The mount 'A' is
 482         mounted on mount 'B' at dentry 'b'. Also new mount 'A1', 'A2'... 'An'
 483         are created and mounted at dentry 'b' on all mounts that receive
 484         propagation from mount 'B'. The mount 'A' becomes a shared mount and a
 485         propagation tree is created which is identical to that of
 486         'B'. This new propagation tree contains all the new mounts 'A1',
 487         'A2'...  'An'.
 488
 489         3. 'A' is a slave mount of mount 'Z' and 'B' is a shared mount.  The
 490         mount 'A' is mounted on mount 'B' at dentry 'b'.  Also new mounts 'A1',
 491         'A2'... 'An' are created and mounted at dentry 'b' on all mounts that
 492         receive propagation from mount 'B'. A new propagation tree is created
 493         in the exact same configuration as that of 'B'. This new propagation
 494         tree contains all the new mounts 'A1', 'A2'...  'An'.  And this new
 495         propagation tree is appended to the already existing propagation tree of
 496         'A'.  Mount 'A' continues to be the slave mount of 'Z' but it also
 497         becomes 'shared'.
 498
 499         4. 'A' is a unbindable mount and 'B' is a shared mount. The operation
 500         is invalid. Because mounting anything on the shared mount 'B' can
 501         create new mounts that get mounted on the mounts that receive
 502         propagation from 'B'.  And since the mount 'A' is unbindable, cloning
 503         it to mount at other mountpoints is not possible.
 504
 505         5. 'A' is a private mount and 'B' is a non-shared(private or slave or
 506         unbindable) mount. The mount 'A' is mounted on mount 'B' at dentry 'b'.
 507
 508         6. 'A' is a shared mount and 'B' is a non-shared mount.  The mount 'A'
 509         is mounted on mount 'B' at dentry 'b'.  Mount 'A' continues to be a
 510         shared mount.
 511
 512         7. 'A' is a slave mount of mount 'Z' and 'B' is a non-shared mount.
 513         The mount 'A' is mounted on mount 'B' at dentry 'b'.  Mount 'A'
 514         continues to be a slave mount of mount 'Z'.
 515
 516         8. 'A' is a unbindable mount and 'B' is a non-shared mount. The mount
 517         'A' is mounted on mount 'B' at dentry 'b'. Mount 'A' continues to be a
 518         unbindable mount.
 519
 520 5e) Mount semantics
 521
 522         Consider the following command
 523
 524         mount device  B/b
 525
 526         'B' is the destination mount and 'b' is the dentry in the destination
 527         mount.
 528
 529         The above operation is the same as bind operation with the exception
 530         that the source mount is always a private mount.
 531
 532
 533 5f) Unmount semantics
 534
 535         Consider the following command
 536
 537         umount A
 538
 539         where 'A' is a mount mounted on mount 'B' at dentry 'b'.
 540
 541         If mount 'B' is shared, then all most-recently-mounted mounts at dentry
 542         'b' on mounts that receive propagation from mount 'B' and does not have
 543         sub-mounts within them are unmounted.
 544
 545         Example: Let's say 'B1', 'B2', 'B3' are shared mounts that propagate to
 546         each other.
 547
 548         let's say 'A1', 'A2', 'A3' are first mounted at dentry 'b' on mount
 549         'B1', 'B2' and 'B3' respectively.
 550
 551         let's say 'C1', 'C2', 'C3' are next mounted at the same dentry 'b' on
 552         mount 'B1', 'B2' and 'B3' respectively.
 553
 554         if 'C1' is unmounted, all the mounts that are most-recently-mounted on
 555         'B1' and on the mounts that 'B1' propagates-to are unmounted.
 556
 557         'B1' propagates to 'B2' and 'B3'. And the most recently mounted mount
 558         on 'B2' at dentry 'b' is 'C2', and that of mount 'B3' is 'C3'.
 559
 560         So all 'C1', 'C2' and 'C3' should be unmounted.
 561
 562         If any of 'C2' or 'C3' has some child mounts, then that mount is not
 563         unmounted, but all other mounts are unmounted. However if 'C1' is told
 564         to be unmounted and 'C1' has some sub-mounts, the umount operation is
 565         failed entirely.
 566
 567 5g) Clone Namespace
 568
 569         A cloned namespace contains all the mounts as that of the parent
 570         namespace.
 571
 572         Let's say 'A' and 'B' are the corresponding mounts in the parent and the
 573         child namespace.
 574
 575         If 'A' is shared, then 'B' is also shared and 'A' and 'B' propagate to
 576         each other.
 577
 578         If 'A' is a slave mount of 'Z', then 'B' is also the slave mount of
 579         'Z'.
 580
 581         If 'A' is a private mount, then 'B' is a private mount too.
 582
 583         If 'A' is unbindable mount, then 'B' is a unbindable mount too.
 584
 585
 586 6) Quiz
 587
 588         A. What is the result of the following command sequence?
 589
 590                 mount --bind /mnt /mnt
 591                 mount --make-shared /mnt
 592                 mount --bind /mnt /tmp
 593                 mount --move /tmp /mnt/1
 594
 595                 what should be the contents of /mnt /mnt/1 /mnt/1/1 should be?
 596                 Should they all be identical? or should /mnt and /mnt/1 be
 597                 identical only?
 598
 599
 600         B. What is the result of the following command sequence?
 601
 602                 mount --make-rshared /
 603                 mkdir -p /v/1
 604                 mount --rbind / /v/1
 605
 606                 what should be the content of /v/1/v/1 be?
 607
 608
 609         C. What is the result of the following command sequence?
 610
 611                 mount --bind /mnt /mnt
 612                 mount --make-shared /mnt
 613                 mkdir -p /mnt/1/2/3 /mnt/1/test
 614                 mount --bind /mnt/1 /tmp
 615                 mount --make-slave /mnt
 616                 mount --make-shared /mnt
 617                 mount --bind /mnt/1/2 /tmp1
 618                 mount --make-slave /mnt
 619
 620                 At this point we have the first mount at /tmp and
 621                 its root dentry is 1. Let's call this mount 'A'
 622                 And then we have a second mount at /tmp1 with root
 623                 dentry 2. Let's call this mount 'B'
 624                 Next we have a third mount at /mnt with root dentry
 625                 mnt. Let's call this mount 'C'
 626
 627                 'B' is the slave of 'A' and 'C' is a slave of 'B'
 628                 A -> B -> C
 629
 630                 at this point if we execute the following command
 631
 632                 mount --bind /bin /tmp/test
 633
 634                 The mount is attempted on 'A'
 635
 636                 will the mount propagate to 'B' and 'C' ?
 637
 638                 what would be the contents of
 639                 /mnt/1/test be?
 640
 641 7) FAQ
 642
 643         Q1. Why is bind mount needed? How is it different from symbolic links?
 644                 symbolic links can get stale if the destination mount gets
 645                 unmounted or moved. Bind mounts continue to exist even if the
 646                 other mount is unmounted or moved.
 647
 648         Q2. Why can't the shared subtree be implemented using exportfs?
 649
 650                 exportfs is a heavyweight way of accomplishing part of what
 651                 shared subtree can do. I cannot imagine a way to implement the
 652                 semantics of slave mount using exportfs?
 653
 654         Q3 Why is unbindable mount needed?
 655
 656                 Let's say we want to replicate the mount tree at multiple
 657                 locations within the same subtree.
 658
 659                 if one rbind mounts a tree within the same subtree 'n' times
 660                 the number of mounts created is an exponential function of 'n'.
 661                 Having unbindable mount can help prune the unneeded bind
 662                 mounts. Here is a example.
 663
 664                 step 1:
 665                    let's say the root tree has just two directories with
 666                    one vfsmount.
 667                                     root
 668                                    /    \
 669                                   tmp    usr
 670
 671                     And we want to replicate the tree at multiple
 672                     mountpoints under /root/tmp
 673
 674                 step2:
 675                       mount --make-shared /root
 676
 677                       mkdir -p /tmp/m1
 678
 679                       mount --rbind /root /tmp/m1
 680
 681                       the new tree now looks like this:
 682
 683                                     root
 684                                    /    \
 685                                  tmp    usr
 686                                 /
 687                                m1
 688                               /  \
 689                              tmp  usr
 690                              /
 691                             m1
 692
 693                           it has two vfsmounts
 694
 695                 step3:
 696                             mkdir -p /tmp/m2
 697                             mount --rbind /root /tmp/m2
 698
 699                         the new tree now looks like this:
 700
 701                                       root
 702                                      /    \
 703                                    tmp     usr
 704                                   /    \
 705                                 m1       m2
 706                                / \       /  \
 707                              tmp  usr   tmp  usr
 708                              / \          /
 709                             m1  m2      m1
 710                                 / \     /  \
 711                               tmp usr  tmp   usr
 712                               /        / \
 713                              m1       m1  m2
 714                             /  \
 715                           tmp   usr
 716                           /  \
 717                          m1   m2
 718
 719                        it has 6 vfsmounts
 720
 721                 step 4:
 722                           mkdir -p /tmp/m3
 723                           mount --rbind /root /tmp/m3
 724
 725                           I wont' draw the tree..but it has 24 vfsmounts
 726
 727
 728                 at step i the number of vfsmounts is V[i] = i*V[i-1].
 729                 This is an exponential function. And this tree has way more
 730                 mounts than what we really needed in the first place.
 731
 732                 One could use a series of umount at each step to prune
 733                 out the unneeded mounts. But there is a better solution.
 734                 Unclonable mounts come in handy here.
 735
 736                 step 1:
 737                    let's say the root tree has just two directories with
 738                    one vfsmount.
 739                                     root
 740                                    /    \
 741                                   tmp    usr
 742
 743                     How do we set up the same tree at multiple locations under
 744                     /root/tmp
 745
 746                 step2:
 747                       mount --bind /root/tmp /root/tmp
 748
 749                       mount --make-rshared /root
 750                       mount --make-unbindable /root/tmp
 751
 752                       mkdir -p /tmp/m1
 753
 754                       mount --rbind /root /tmp/m1
 755
 756                       the new tree now looks like this:
 757
 758                                     root
 759                                    /    \
 760                                  tmp    usr
 761                                 /
 762                                m1
 763                               /  \
 764                              tmp  usr
 765
 766                 step3:
 767                             mkdir -p /tmp/m2
 768                             mount --rbind /root /tmp/m2
 769
 770                       the new tree now looks like this:
 771
 772                                     root
 773                                    /    \
 774                                  tmp    usr
 775                                 /   \
 776                                m1     m2
 777                               /  \     / \
 778                              tmp  usr tmp usr
 779
 780                 step4:
 781
 782                             mkdir -p /tmp/m3
 783                             mount --rbind /root /tmp/m3
 784
 785                       the new tree now looks like this:
 786
 787                                           root
 788                                       /           \
 789                                      tmp           usr
 790                                  /    \    \
 791                                m1     m2     m3
 792                               /  \     / \    /  \
 793                              tmp  usr tmp usr tmp usr
 794
 795 8) Implementation
 796
 797 8A) Datastructure
 798
 799         4 new fields are introduced to struct vfsmount
 800         ->mnt_share
 801         ->mnt_slave_list
 802         ->mnt_slave
 803         ->mnt_master
 804
 805         ->mnt_share links together all the mount to/from which this vfsmount
 806                 send/receives propagation events.
 807
 808         ->mnt_slave_list links all the mounts to which this vfsmount propagates
 809                 to.
 810
 811         ->mnt_slave links together all the slaves that its master vfsmount
 812                 propagates to.
 813
 814         ->mnt_master points to the master vfsmount from which this vfsmount
 815                 receives propagation.
 816
 817         ->mnt_flags takes two more flags to indicate the propagation status of
 818                 the vfsmount.  MNT_SHARE indicates that the vfsmount is a shared
 819                 vfsmount.  MNT_UNCLONABLE indicates that the vfsmount cannot be
 820                 replicated.
 821
 822         All the shared vfsmounts in a peer group form a cyclic list through
 823         ->mnt_share.
 824
 825         All vfsmounts with the same ->mnt_master form on a cyclic list anchored
 826         in ->mnt_master->mnt_slave_list and going through ->mnt_slave.
 827
 828          ->mnt_master can point to arbitrary (and possibly different) members
 829          of master peer group.  To find all immediate slaves of a peer group
 830          you need to go through _all_ ->mnt_slave_list of its members.
 831          Conceptually it's just a single set - distribution among the
 832          individual lists does not affect propagation or the way propagation
 833          tree is modified by operations.
 834
 835         A example propagation tree looks as shown in the figure below.
 836         [ NOTE: Though it looks like a forest, if we consider all the shared
 837         mounts as a conceptual entity called 'pnode', it becomes a tree]
 838
 839
 840                         A <--> B <--> C <---> D
 841                        /|\            /|      |\
 842                       / F G          J K      H I
 843                      /
 844                     E<-->K
 845                         /|\
 846                        M L N
 847
 848         In the above figure  A,B,C and D all are shared and propagate to each
 849         other.   'A' has got 3 slave mounts 'E' 'F' and 'G' 'C' has got 2 slave
 850         mounts 'J' and 'K'  and  'D' has got two slave mounts 'H' and 'I'.
 851         'E' is also shared with 'K' and they propagate to each other.  And
 852         'K' has 3 slaves 'M', 'L' and 'N'
 853
 854         A's ->mnt_share links with the ->mnt_share of 'B' 'C' and 'D'
 855
 856         A's ->mnt_slave_list links with ->mnt_slave of 'E', 'K', 'F' and 'G'
 857
 858         E's ->mnt_share links with ->mnt_share of K
 859         'E', 'K', 'F', 'G' have their ->mnt_master point to struct
 860                                 vfsmount of 'A'
 861         'M', 'L', 'N' have their ->mnt_master point to struct vfsmount of 'K'
 862         K's ->mnt_slave_list links with ->mnt_slave of 'M', 'L' and 'N'
 863
 864         C's ->mnt_slave_list links with ->mnt_slave of 'J' and 'K'
 865         J and K's ->mnt_master points to struct vfsmount of C
 866         and finally D's ->mnt_slave_list links with ->mnt_slave of 'H' and 'I'
 867         'H' and 'I' have their ->mnt_master pointing to struct vfsmount of 'D'.
 868
 869
 870         NOTE: The propagation tree is orthogonal to the mount tree.
 871
 872
 873 8B Algorithm:
 874
 875         The crux of the implementation resides in rbind/move operation.
 876
 877         The overall algorithm breaks the operation into 3 phases: (look at
 878         attach_recursive_mnt() and propagate_mnt())
 879
 880         1. prepare phase.
 881         2. commit phases.
 882         3. abort phases.
 883
 884         Prepare phase:
 885
 886         for each mount in the source tree:
 887                    a) Create the necessary number of mount trees to
 888                         be attached to each of the mounts that receive
 889                         propagation from the destination mount.
 890                    b) Do not attach any of the trees to its destination.
 891                       However note down its ->mnt_parent and ->mnt_mountpoint
 892                    c) Link all the new mounts to form a propagation tree that
 893                       is identical to the propagation tree of the destination
 894                       mount.
 895
 896                    If this phase is successful, there should be 'n' new
 897                    propagation trees; where 'n' is the number of mounts in the
 898                    source tree.  Go to the commit phase
 899
 900                    Also there should be 'm' new mount trees, where 'm' is
 901                    the number of mounts to which the destination mount
 902                    propagates to.
 903
 904                    if any memory allocations fail, go to the abort phase.
 905
 906         Commit phase
 907                 attach each of the mount trees to their corresponding
 908                 destination mounts.
 909
 910         Abort phase
 911                 delete all the newly created trees.
 912
 913         NOTE: all the propagation related functionality resides in the file
 914         pnode.c
 915
 916
 917 ------------------------------------------------------------------------
 918
 919 version 0.1  (created the initial document, Ram Pai linuxram@us.ibm.com)
 920 version 0.2  (Incorporated comments from Al Viro)