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