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