]> git.proxmox.com Git - mirror_ubuntu-zesty-kernel.git/blame - Documentation/filesystems/sharedsubtree.txt
Merge tag 'v3.9-rc3' into drm-intel-next-queued
[mirror_ubuntu-zesty-kernel.git] / Documentation / filesystems / sharedsubtree.txt
CommitLineData
9cfcceea
RP
1Shared Subtrees
2---------------
3
4Contents:
5 1) Overview
6 2) Features
16c01b20 7 3) Setting mount states
9cfcceea
RP
8 4) Use-case
9 5) Detailed semantics
10 6) Quiz
11 7) FAQ
12 8) Implementation
13
14
151) Overview
16-----------
17
18Consider the following situation:
19
20A process wants to clone its own namespace, but still wants to access the CD
21that got mounted recently. Shared subtree semantics provide the necessary
22mechanism to accomplish the above.
23
24It provides the necessary building blocks for features like per-user-namespace
25and versioned filesystem.
26
272) Features
28-----------
29
30Shared subtree provides four different flavors of mounts; struct vfsmount to be
31precise
32
33 a. shared mount
34 b. slave mount
35 c. private mount
36 d. unbindable mount
37
38
392a) A shared mount can be replicated to as many mountpoints and all the
40replicas continue to be exactly same.
41
42 Here is an example:
43
0288b95b 44 Let's say /mnt has a mount that is shared.
9cfcceea
RP
45 mount --make-shared /mnt
46
0288b95b
RD
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.
9cfcceea 50
0288b95b 51 # mount --bind /mnt /tmp
9cfcceea
RP
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
0288b95b
RD
61 Now let's say we mount a device at /tmp/a
62 # mount /dev/sd0 /tmp/a
9cfcceea
RP
63
64 #ls /tmp/a
d9d1dc80 65 t1 t2 t3
9cfcceea
RP
66
67 #ls /mnt/a
d9d1dc80 68 t1 t2 t3
9cfcceea
RP
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
762b) 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
0288b95b
RD
83 Let's say /mnt has a mount which is shared.
84 # mount --make-shared /mnt
9cfcceea 85
0288b95b
RD
86 Let's bind mount /mnt to /tmp
87 # mount --bind /mnt /tmp
9cfcceea
RP
88
89 the new mount at /tmp becomes a shared mount and it is a replica of
90 the mount at /mnt.
91
0288b95b
RD
92 Now let's make the mount at /tmp; a slave of /mnt
93 # mount --make-slave /tmp
9cfcceea 94
0288b95b
RD
95 let's mount /dev/sd0 on /mnt/a
96 # mount /dev/sd0 /mnt/a
9cfcceea
RP
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
0288b95b 106 However let's see what happens if we mount something on the mount at /tmp
9cfcceea 107
0288b95b 108 # mount /dev/sd1 /tmp/b
9cfcceea
RP
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
1192c) 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
1242d) A unbindable mount is a unbindable private mount
125
0288b95b 126 let's say we have a mount at /mnt and we make is unbindable
9cfcceea 127
0288b95b 128 # mount --make-unbindable /mnt
9cfcceea 129
0288b95b 130 Let's try to bind mount this mount somewhere else.
9cfcceea
RP
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
16c01b20 1383) Setting mount states
9cfcceea 139
16c01b20
PT
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
9cfcceea
RP
147
148
1494) 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
16c01b20 217 and if /usr has a versioning filesystem mounted, then that
9cfcceea
RP
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
2275) 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
2355a) 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
16c01b20 257 mount --bind /mnt /tmp
9cfcceea
RP
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
3395b) 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
4155c) 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
0288b95b 425 eg: let's say we have the following mount tree.
9cfcceea
RP
426
427 A
428 / \
429 B C
430 / \ / \
431 D E F G
432
0288b95b 433 Let's say all the mount except the mount C in the tree are
9cfcceea
RP
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
4505d) 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
5255e) 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
5385f) 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
0288b95b 550 Example: Let's say 'B1', 'B2', 'B3' are shared mounts that propagate to
9cfcceea
RP
551 each other.
552
0288b95b 553 let's say 'A1', 'A2', 'A3' are first mounted at dentry 'b' on mount
9cfcceea
RP
554 'B1', 'B2' and 'B3' respectively.
555
0288b95b 556 let's say 'C1', 'C2', 'C3' are next mounted at the same dentry 'b' on
9cfcceea
RP
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
5725g) Clone Namespace
573
574 A cloned namespace contains all the mounts as that of the parent
575 namespace.
576
0288b95b 577 Let's say 'A' and 'B' are the corresponding mounts in the parent and the
9cfcceea
RP
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
5916) 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
0288b95b 626 its root dentry is 1. Let's call this mount 'A'
9cfcceea 627 And then we have a second mount at /tmp1 with root
0288b95b 628 dentry 2. Let's call this mount 'B'
9cfcceea 629 Next we have a third mount at /mnt with root dentry
0288b95b 630 mnt. Let's call this mount 'C'
9cfcceea
RP
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
6467) 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
0288b95b 661 Let's say we want to replicate the mount tree at multiple
9cfcceea
RP
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:
0288b95b 670 let's say the root tree has just two directories with
9cfcceea
RP
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 wont' 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:
0288b95b 742 let's say the root tree has just two directories with
9cfcceea
RP
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
8008) Implementation
801
8028A) 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
fa00e7e1 810 ->mnt_share links together all the mount to/from which this vfsmount
9cfcceea
RP
811 send/receives propagation events.
812
813 ->mnt_slave_list links all the mounts to which this vfsmount propagates
814 to.
815
fa00e7e1 816 ->mnt_slave links together all the slaves that its master vfsmount
9cfcceea
RP
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
2f99cc6e
AV
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
9cfcceea
RP
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
2f99cc6e
AV
8808B 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.
9cfcceea 891
2f99cc6e 8928C Algorithm:
9cfcceea
RP
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
938version 0.1 (created the initial document, Ram Pai linuxram@us.ibm.com)
939version 0.2 (Incorporated comments from Al Viro)