doc/man-pages/pod1/fs_mkmount.pod

   1 =head1 NAME
   2
   3 fs mkmount - Creates a mount point for a volume
   4
   5 =head1 SYNOPSIS
   6
   7 B<fs mkmount -dir> <I<directory>>  B<-vol> <I<volume name>>  [-cell <I<cell name>>]
   8 [B<-rw>]  [B<-fast>]  [B<-help>]
   9
  10 B<fs mk -d> <I<directory>>  B<-v> <I<volume name>>  [B<-c> <I<cell name>>]  [B<-r>]  [B<-f>]  [-h]
  11
  12 =head1 DESCRIPTION
  13
  14 The fs mkmount command creates a mount point for the volume
  15 named by the B<-vol> argument at the location in the AFS file space
  16 specified by the B<-dir> argument. The mount point looks like a
  17 standard directory element, and serves as the volume's root directory,
  18 but is actually a special file system object that refers to an AFS
  19 volume. When the Cache Manager first encounters a given mount point
  20 during pathname traversal, it contacts the VL Server to learn which file
  21 server machines house the indicated volume, then fetches a copy of the
  22 volume's root directory from the appropriate file server machine.
  23
  24 It is possible, although not recommended, to create more than one mount
  25 point to a volume. The Cache Manager can become confused if a volume is
  26 mounted in two places along the same path through the filespace.
  27
  28 The Cache Manager observes three basic rules as it traverses the AFS
  29 filespace and encounters mount points:
  30
  31 =over 4
  32
  33 =item *
  34
  35 Rule 1: Access Backup and Read-only Volumes When
  36 Specified
  37
  38
  39 When the Cache Manager encounters a mount point that specifies a volume
  40 with either a B<.readonly> or a B<.backup>
  41 extension, it accesses that type of volume only. If a mount point does
  42 not have either a B<.backup> or B<.readonly>
  43 extension, the Cache Manager uses Rules 2 and 3.
  44
  45 For example, the Cache Manager never accesses the read/write version of a
  46 volume if the mount point names the backup version. If the specified
  47 version is inaccessible, the Cache Manager reports an error.
  48
  49 =item *
  50
  51 Rule 2: Follow the Read-only Path When Possible
  52
  53
  54 If a mount point resides in a read-only volume and the volume that it
  55 references is replicated, the Cache Manager attempts to access a read-only
  56 copy of the volume; if the referenced volume is not replicated, the Cache
  57 Manager accesses the read/write copy. The Cache Manager is thus said to
  58 prefer a I<read-only path> through the filespace, accessing read-only
  59 volumes when they are available.
  60
  61 The Cache Manager starts on the read-only path in the first place because
  62 it always accesses a read-only copy of the B<root.afs> volume
  63 if it exists; the volume is mounted at the root of a cell's AFS
  64 filespace (named B</afs> by convention). That is, if the
  65 B<root.afs> volume is replicated, the Cache Manager attempts to
  66 access a read-only copy of it rather than the read/write copy. This
  67 rule then keeps the Cache Manager on a read-only path as long as each
  68 successive volume is replicated. The implication is that both the
  69 B<root.afs> and B<root.cell> volumes must be
  70 replicated for the Cache Manager to access replicated volumes mounted below
  71 them in the AFS filespace. The volumes are conventionally mounted at
  72 the B</afs> and B</afs/>I<cellname> directories,
  73 respectively.
  74
  75 =item *
  76
  77 Rule 3: Once on a Read/write Path, Stay There
  78
  79
  80 If a mount point resides in a read/write volume and the volume name does
  81 not have a B<.readonly> or a B<.backup>
  82 extension, the Cache Manager attempts to access only the a read/write version
  83 of the volume. The access attempt fails with an error if the read/write
  84 version is inaccessible, even if a read-only version is accessible. In
  85 this situation the Cache Manager is said to be on a I<read/write path>
  86 and cannot switch back to the read-only path unless mount point explicitly
  87 names a volume with a B<.readonly> extension. (Cellular
  88 mount points are an important exception to this rule, as explained in the
  89 following discussion.
  90
  91 =back
  92
  93 There are three types of mount points, each appropriate for a different
  94 purpose because of the manner in which the Cache Manager interprets
  95 them.
  96
  97 =over 4
  98
  99 =item *
 100
 101 When the Cache Manager crosses a I<regular> mount point, it obeys
 102 all three of the mount point traversal rules previously described. To
 103 create a regular mount point, include only the required B<-dir> and
 104 B<-vol> arguments to the B<fs mkmount> command.
 105 L<(1)>
 106 L<(1)>
 107
 108
 109 =item *
 110
 111 When the Cache Manager crosses a I<read/write> mount point, it
 112 attempts to access only the volume version named in the mount point. If
 113 the volume name is the base (read/write) form, without a
 114 B<.readonly> or B<.backup> extension, the Cache
 115 Manager accesses the read/write version of the volume, even if it is
 116 replicated. In other words, the Cache Manager disregards the second
 117 mount point traversal rule when crossing a read/write mount point: it
 118 switches to the read/write path through the filespace.
 119 L<(1)>
 120 L<(1)>
 121
 122
 123 To create a read/write mount point, include the -rw flag on the
 124 B<fs mkmount> command. It is conventional to create only one
 125 read/write mount point in a cell's filespace, using it to mount the
 126 cell's B<root.cell> volume just below the AFS filespace
 127 root (by convention, B</afs/.>I<cellname>). See
 128 the I<IBM AFS Quick Beginnings> for instructions and the chapter about
 129 volume management in the I<IBM AFS Administration Guide> for further
 130 discussion.
 131
 132 Creating a read/write mount point for a read-only or backup volume is
 133 acceptable, but unnecessary. The first rule of mount point traversal
 134 already specifies that the Cache Manager accesses them if the volume name in a
 135 regular mount point has a B<.readonly> or
 136 B<.backup> extension.
 137
 138 =item *
 139
 140 When the Cache Manager crosses a I<cellular> mount point, it
 141 accesses the indicated volume in the specified cell, which is normally a
 142 foreign cell. (If the mount point does not name a cell along with the
 143 volume, the Cache Manager accesses the volume in the cell where the mount
 144 point resides.) The Cache Manager disregards the third mount point
 145 traversal rule when crossing a regular cellular mount point: it accesses
 146 a read-only version of the volume if it is replicated, even if the volume that
 147 houses the mount point is read/write. Switching to the read-only path
 148 in this way is designed to avoid imposing undue load on the file server
 149 machines in foreign cells.
 150 L<(1)>
 151 L<(1)>
 152 L<(1)>
 153
 154
 155 To create a regular cellular mount point, include the -cell
 156 argument on the B<fs mkmount> command. It is conventional to
 157 create cellular mount points only at the second level in a cell's
 158 filespace, using them to mount foreign cells' B<root.cell>
 159 volumes just below the AFS filespace root (by convention, at
 160 B</afs/>I<foreign_cellname>). The mount point enables
 161 local users to access the foreign cell's filespace, assuming they have
 162 the necessary permissions on the ACL of the volume's root directory and
 163 that there is an entry for the foreign cell in each local client
 164 machine's B</usr/vice/etc/CellServDB> file. In the output
 165 of the B<fs lsmount> command, the cell name and a colon
 166 (C<:>) appear between the initial number sign and the volume
 167 name in a regular cellular mount point name.
 168
 169 =back
 170
 171 =head1 OPTIONS
 172
 173 =over 4
 174
 175 =item -dir
 176
 177 Names the directory to create as a mount point. The directory must
 178 not already exist. Relative pathnames are interpreted with respect to
 179 the current working directory.
 180
 181 Specify the read/write path to the directory, to avoid the failure that
 182 results from attempting to create a new mount point in a read-only
 183 volume. By convention, the read/write path is indicated by placing a
 184 period before the cell name at the pathname's second level (for example,
 185 B</afs/.abc.com>). For further discussion of the
 186 concept of read/write and read-only paths through the filespace, see the
 187 B<Description> section of this reference page.
 188
 189 =item -vol
 190
 191 Specifies the name or volume ID number of the volume to mount. If
 192 appropriate, add the C<.readonly> or C<.backup>
 193 extension to the name, or specify the appropriate volume ID number.
 194
 195 =item -cell
 196
 197 Names the cell in which the volume resides (creates a cellular mount
 198 point). Provide the fully qualified domain name, or a shortened form
 199 that disambiguates it from the other cells listed in the local
 200 B</usr/vice/etc/CellServDB> file.
 201
 202 If this argument is omitted, no cell indicator appears in the mount
 203 point. When the Cache Manager interprets it, it assumes that the volume
 204 named in the mount point resides in the same cell as the volume that houses
 205 the mount point.
 206
 207 =item -rw
 208
 209 Creates a read/write mount point. Omit this flag to create a
 210 regular mount point.
 211
 212 =item -fast
 213
 214 Prevents the Volume Location (VL) Server from checking that the volume has
 215 a VLDB entry and printing a warning message if it does not. Whether or
 216 not this flag is included, the File Server creates the mount point even when
 217 the volume has no VLDB entry.
 218
 219 =item -help
 220
 221 Prints the online help for this command. All other valid options
 222 are ignored.
 223
 224 =back
 225
 226 =head1 EXAMPLES
 227
 228 The following command creates a regular mount point, mounting the volume
 229 B<user.smith> at
 230 B</afs/abc.com/usr/smith>:
 231
 232    % cd /afs/abc.com/usr
 233
 234    % fs mkmount -dir smith -vol user.smith
 235
 236
 237 The following commands create a read/write mount point and a regular mount
 238 point for the ABC Corporation cell's C<root.cell> volume
 239 in that cell's file tree. The second command follows the
 240 convention of putting a period at the beginning of the read/write mount
 241 point's name.
 242
 243    % fs mkmount -dir /afs/abc.com -vol root.cell
 244
 245    % fs mkmount -dir /afs/.abc.com -vol root.cell -rw
 246
 247
 248 The following command mounts the State University cell's
 249 C<root.cell> volume in the ABC Corporation cell's file
 250 tree, creating a regular cellular mount point called
 251 B</afs/stateu.edu>. When a ABC Corporation Cache Manager
 252 encounters this mount point, it crosses into the State University cell on a
 253 read-only path.
 254
 255    % fs mkmount -dir /afs/stateu.edu -vol root.cell -c stateu.edu
 256
 257 =head1 PRIVILEGE REQUIRED
 258
 259 The issuer must have the B<i> (B<insert>) and a
 260 (B<administer>) permissions on the ACL of the directory that is to
 261 house the mount point.
 262
 263 =head1 SEE ALSO
 264
 265 L<CellServDB (client version)(1)>
 266
 267 L<fs_lsmount(1)>,
 268 L<fs_rmmount(1)>
 269
 270 =head1 COPYRIGHT
 271
 272 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 273
 274 This documentation is covered by the IBM Public License Version 1.0.  It was
 275 converted from HTML to POD by software written by Chas Williams and Russ
 276 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.