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