1.\" 2.\" Copyright (c) 1992, 1993, 1994 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software donated to Berkeley by 6.\" John Heidemann of the UCLA Ficus project. 7.\" 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the University of 20.\" California, Berkeley and its contributors. 21.\" 4. Neither the name of the University nor the names of its contributors 22.\" may be used to endorse or promote products derived from this software 23.\" without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 29.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35.\" SUCH DAMAGE. 36.\" 37.\" @(#)mount_null.8 8.6 (Berkeley) 5/1/95 38.\" $FreeBSD: src/sbin/mount_null/mount_null.8,v 1.11.2.6 2001/12/20 16:40:00 ru Exp $ 39.\" $DragonFly: src/sbin/mount_null/mount_null.8,v 1.8 2008/10/26 00:05:24 swildner Exp $ 40.\" 41.Dd September 28, 2008 42.Dt MOUNT_NULL 8 43.Os 44.Sh NAME 45.Nm mount_null 46.Nd "mount a loopback filesystem sub-tree; demonstrate the use of a null file system layer" 47.Sh SYNOPSIS 48.Nm 49.Op Fl o Ar options 50.Ar target 51.Ar mount-point 52.Nm 53.Fl u 54.Op Fl o Ar options 55.Ar mount-point 56.Sh DESCRIPTION 57The 58.Nm 59command creates a 60null layer, duplicating a sub-tree of the file system 61name space under another part of the global file system namespace. 62This allows existing files and directories to be accessed 63using a different pathname. 64.Pp 65The primary differences between a virtual copy of the filesystem 66and a symbolic link are that the 67.Xr getcwd 3 68functions work correctly in the virtual copy, and that other filesystems 69may be mounted on the virtual copy without affecting the original. 70A different device number for the virtual copy is returned by 71.Xr stat 2 , 72but in other respects it is indistinguishable from the original. 73.Pp 74The 75.Nm null 76filesystem differs from a traditional 77loopback file system in two respects: it is implemented using 78a stackable layers techniques, and its 79.Do null-node Dc Ns s 80stack above 81all lower-layer vnodes, not just over directory vnodes. 82.Pp 83The options are as follows: 84.Bl -tag -width indent 85.It Fl o 86Options are specified with a 87.Fl o 88flag followed by a comma separated string of options. 89See the 90.Xr mount 8 91man page for possible options and their meanings. 92.It Fl u 93Update the mount point. 94This is typically used to upgrade a mount to 95read-write or downgrade it to read-only. 96.El 97.Pp 98The null layer has three purposes. 99First, it serves as a demonstration of layering by providing a layer 100which does nothing. 101(It actually does everything the loopback file system does, 102which is slightly more than nothing.) 103Second, it is used for NFS exporting 104.Nm HAMMER 105PFSs. 106Third, the null layer can serve as a prototype layer. 107Since it provides all necessary layer framework, 108new file system layers can be created very easily by starting 109with a null layer. 110.Pp 111The remainder of this man page examines the null layer as a basis 112for constructing new layers. 113.\" 114.\" 115.Sh INSTANTIATING NEW NULL LAYERS 116New null layers are created with 117.Nm . 118.Nm Mount_null 119takes two arguments, the pathname 120of the lower vfs (target-pn) and the pathname where the null 121layer will appear in the namespace (mount-point-pn). After 122the null layer is put into place, the contents 123of target-pn subtree will be aliased under mount-point-pn. 124.\" 125.\" 126.Sh OPERATION OF A NULL LAYER 127The null layer is the minimum file system layer, 128simply bypassing all possible operations to the lower layer 129for processing there. The majority of its activity centers 130on the bypass routine, through which nearly all vnode operations 131pass. 132.Pp 133The bypass routine accepts arbitrary vnode operations for 134handling by the lower layer. It begins by examining vnode 135operation arguments and replacing any null-nodes by their 136lower-layer equivalents. It then invokes the operation 137on the lower layer. Finally, it replaces the null-nodes 138in the arguments and, if a vnode is returned by the operation, 139stacks a null-node on top of the returned vnode. 140.Pp 141Although bypass handles most operations, 142.Em vop_getattr , 143.Em vop_inactive , 144.Em vop_reclaim , 145and 146.Em vop_print 147are not bypassed. 148.Em Vop_getattr 149must change the fsid being returned. 150.Em Vop_inactive 151and 152.Em vop_reclaim 153are not bypassed so that 154they can handle freeing null-layer specific data. 155.Em Vop_print 156is not bypassed to avoid excessive debugging 157information. 158.\" 159.\" 160.Sh INSTANTIATING VNODE STACKS 161Mounting associates the null layer with a lower layer, 162in effect stacking two VFSes. Vnode stacks are instead 163created on demand as files are accessed. 164.Pp 165The initial mount creates a single vnode stack for the 166root of the new null layer. All other vnode stacks 167are created as a result of vnode operations on 168this or other null vnode stacks. 169.Pp 170New vnode stacks come into existence as a result of 171an operation which returns a vnode. 172The bypass routine stacks a null-node above the new 173vnode before returning it to the caller. 174.Pp 175For example, imagine mounting a null layer with 176.Bd -literal -offset indent 177mount_null /usr/include /dev/layer/null 178.Ed 179.Pp 180Changing directory to 181.Pa /dev/layer/null 182will assign 183the root null-node (which was created when the null layer was mounted). 184Now consider opening 185.Pa sys . 186A 187.Em vop_lookup 188would be 189done on the root null-node. This operation would bypass through 190to the lower layer which would return a vnode representing 191the 192.Xr UFS 5 193.Pa sys 194(assuming that the lower layer is an 195.Xr UFS 5 196file system). 197Null_bypass then builds a null-node 198aliasing the 199.Xr UFS 5 200.Pa sys 201and returns this to the caller. 202Later operations on the null-node 203.Pa sys 204will repeat this 205process when constructing other vnode stacks. 206.\" 207.\" 208.Sh CREATING OTHER FILE SYSTEM LAYERS 209One of the easiest ways to construct new file system layers is to make 210a copy of the null layer, rename all files and variables, and 211then begin modifying the copy. 212.Xr Sed 1 213can be used to easily rename 214all variables. 215.\" 216.\" 217.Sh INVOKING OPERATIONS ON LOWER LAYERS 218There are two techniques to invoke operations on a lower layer 219when the operation cannot be completely bypassed. Each method 220is appropriate in different situations. In both cases, 221it is the responsibility of the aliasing layer to make 222the operation arguments "correct" for the lower layer 223by mapping a vnode argument to the lower layer. 224.Pp 225The first approach is to call the aliasing layer's bypass routine. 226This method is most suitable when you wish to invoke the operation 227currently being handled on the lower layer. 228It has the advantage that 229the bypass routine already must do argument mapping. 230An example of this is 231.Em null_getattrs 232in the null layer. 233.Pp 234A second approach is to directly invoke vnode operations on 235the lower layer with the 236.Em VOP_OPERATIONNAME 237interface. 238The advantage of this method is that it is easy to invoke 239arbitrary operations on the lower layer. The disadvantage 240is that vnode arguments must be manually mapped. 241.\" 242.\" 243.Sh SEE ALSO 244.Xr HAMMER 5 , 245.Xr mount 8 246.Pp 247UCLA Technical Report CSD-910056, 248.Em "Stackable Layers: an Architecture for File System Development" . 249.Sh HISTORY 250The 251.Nm 252utility first appeared in 253.Bx 4.4 . 254.An Matthew Dillon 255made 256.Nm 257work in 258.Dx 1.7 , 259after it had been broken for some time. 260