tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
fork atom

Documentation: sharedsubtree: Align text

The docs make heavy use of lists. As it is currently written, these
generate a lot of unnecessary hanging indents since these are not
semantically meant to be definition lists by accident.

Align text to trim these indents.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250819061254.31220-5-bagasdotme@gmail.com

authored by

Bagas Sanjaya and committed by
Jonathan Corbet b293fd55 570924bf

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