sbin/mount_null/mount_null.8

   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
  57 The
  58 .Nm
  59 command creates a
  60 null layer, duplicating a sub-tree of the file system
  61 name space under another part of the global file system namespace.
  62 This allows existing files and directories to be accessed
  63 using a different pathname.
  64 .Pp
  65 The primary differences between a virtual copy of the filesystem
  66 and a symbolic link are that the
  67 .Xr getcwd 3
  68 functions work correctly in the virtual copy, and that other filesystems
  69 may be mounted on the virtual copy without affecting the original.
  70 A different device number for the virtual copy is returned by
  71 .Xr stat 2 ,
  72 but in other respects it is indistinguishable from the original.
  73 .Pp
  74 The
  75 .Nm null
  76 filesystem differs from a traditional
  77 loopback file system in two respects: it is implemented using
  78 a stackable layers techniques, and its
  79 .Do null-node Dc Ns s
  80 stack above
  81 all lower-layer vnodes, not just over directory vnodes.
  82 .Pp
  83 The options are as follows:
  84 .Bl -tag -width indent
  85 .It Fl o
  86 Options are specified with a
  87 .Fl o
  88 flag followed by a comma separated string of options.
  89 See the
  90 .Xr mount 8
  91 man page for possible options and their meanings.
  92 .It Fl u
  93 Update the mount point.
  94 This is typically used to upgrade a mount to
  95 read-write or downgrade it to read-only.
  96 .El
  97 .Pp
  98 The null layer has three purposes.
  99 First, it serves as a demonstration of layering by providing a layer
 100 which does nothing.
 101 (It actually does everything the loopback file system does,
 102 which is slightly more than nothing.)
 103 Second, it is used for NFS exporting
 104 .Nm HAMMER
 105 PFSs.
 106 Third, the null layer can serve as a prototype layer.
 107 Since it provides all necessary layer framework,
 108 new file system layers can be created very easily by starting
 109 with a null layer.
 110 .Pp
 111 The remainder of this man page examines the null layer as a basis
 112 for constructing new layers.
 113 .\"
 114 .\"
 115 .Sh INSTANTIATING NEW NULL LAYERS
 116 New null layers are created with
 117 .Nm .
 118 .Nm Mount_null
 119 takes two arguments, the pathname
 120 of the lower vfs (target-pn) and the pathname where the null
 121 layer will appear in the namespace (mount-point-pn).  After
 122 the null layer is put into place, the contents
 123 of target-pn subtree will be aliased under mount-point-pn.
 124 .\"
 125 .\"
 126 .Sh OPERATION OF A NULL LAYER
 127 The null layer is the minimum file system layer,
 128 simply bypassing all possible operations to the lower layer
 129 for processing there.  The majority of its activity centers
 130 on the bypass routine, through which nearly all vnode operations
 131 pass.
 132 .Pp
 133 The bypass routine accepts arbitrary vnode operations for
 134 handling by the lower layer.  It begins by examining vnode
 135 operation arguments and replacing any null-nodes by their
 136 lower-layer equivalents.  It then invokes the operation
 137 on the lower layer.  Finally, it replaces the null-nodes
 138 in the arguments and, if a vnode is returned by the operation,
 139 stacks a null-node on top of the returned vnode.
 140 .Pp
 141 Although bypass handles most operations,
 142 .Em vop_getattr ,
 143 .Em vop_inactive ,
 144 .Em vop_reclaim ,
 145 and
 146 .Em vop_print
 147 are not bypassed.
 148 .Em Vop_getattr
 149 must change the fsid being returned.
 150 .Em Vop_inactive
 151 and
 152 .Em vop_reclaim
 153 are not bypassed so that
 154 they can handle freeing null-layer specific data.
 155 .Em Vop_print
 156 is not bypassed to avoid excessive debugging
 157 information.
 158 .\"
 159 .\"
 160 .Sh INSTANTIATING VNODE STACKS
 161 Mounting associates the null layer with a lower layer,
 162 in effect stacking two VFSes.  Vnode stacks are instead
 163 created on demand as files are accessed.
 164 .Pp
 165 The initial mount creates a single vnode stack for the
 166 root of the new null layer.  All other vnode stacks
 167 are created as a result of vnode operations on
 168 this or other null vnode stacks.
 169 .Pp
 170 New vnode stacks come into existence as a result of
 171 an operation which returns a vnode.
 172 The bypass routine stacks a null-node above the new
 173 vnode before returning it to the caller.
 174 .Pp
 175 For example, imagine mounting a null layer with
 176 .Bd -literal -offset indent
 177 mount_null /usr/include /dev/layer/null
 178 .Ed
 179 .Pp
 180 Changing directory to
 181 .Pa /dev/layer/null
 182 will assign
 183 the root null-node (which was created when the null layer was mounted).
 184 Now consider opening
 185 .Pa sys .
 186 A
 187 .Em vop_lookup
 188 would be
 189 done on the root null-node.  This operation would bypass through
 190 to the lower layer which would return a vnode representing
 191 the
 192 .Xr UFS 5
 193 .Pa sys
 194 (assuming that the lower layer is an
 195 .Xr UFS 5
 196 file system).
 197 Null_bypass then builds a null-node
 198 aliasing the
 199 .Xr UFS 5
 200 .Pa sys
 201 and returns this to the caller.
 202 Later operations on the null-node
 203 .Pa sys
 204 will repeat this
 205 process when constructing other vnode stacks.
 206 .\"
 207 .\"
 208 .Sh CREATING OTHER FILE SYSTEM LAYERS
 209 One of the easiest ways to construct new file system layers is to make
 210 a copy of the null layer, rename all files and variables, and
 211 then begin modifying the copy.
 212 .Xr Sed 1
 213 can be used to easily rename
 214 all variables.
 215 .\"
 216 .\"
 217 .Sh INVOKING OPERATIONS ON LOWER LAYERS
 218 There are two techniques to invoke operations on a lower layer
 219 when the operation cannot be completely bypassed.  Each method
 220 is appropriate in different situations.  In both cases,
 221 it is the responsibility of the aliasing layer to make
 222 the operation arguments "correct" for the lower layer
 223 by mapping a vnode argument to the lower layer.
 224 .Pp
 225 The first approach is to call the aliasing layer's bypass routine.
 226 This method is most suitable when you wish to invoke the operation
 227 currently being handled on the lower layer.
 228 It has the advantage that
 229 the bypass routine already must do argument mapping.
 230 An example of this is
 231 .Em null_getattrs
 232 in the null layer.
 233 .Pp
 234 A second approach is to directly invoke vnode operations on
 235 the lower layer with the
 236 .Em VOP_OPERATIONNAME
 237 interface.
 238 The advantage of this method is that it is easy to invoke
 239 arbitrary operations on the lower layer.  The disadvantage
 240 is that vnode arguments must be manually mapped.
 241 .\"
 242 .\"
 243 .Sh SEE ALSO
 244 .Xr HAMMER 5 ,
 245 .Xr mount 8
 246 .Pp
 247 UCLA Technical Report CSD-910056,
 248 .Em "Stackable Layers: an Architecture for File System Development" .
 249 .Sh HISTORY
 250 The
 251 .Nm
 252 utility first appeared in
 253 .Bx 4.4 .
 254 .An Matthew Dillon
 255 made
 256 .Nm
 257 work in
 258 .Dx 1.7 ,
 259 after it had been broken for some time.