Commit | Line | Data |
---|---|---|
805e021f CE |
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. |