Documentation/filesystems/sharedsubtree.txt

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