Commit | Line | Data |
---|---|---|
805e021f CE |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <chapter id="HDRWQ174"> | |
3 | <title>Managing Volumes</title> | |
4 | ||
5 | <para>This chapter explains how to manage the volumes stored on file server machines. The volume is the designated unit of | |
6 | administration in AFS, so managing them is a large part of the administrator's duties.</para> | |
7 | ||
8 | <sect1 id="HDRWQ175"> | |
9 | <title>Summary of Instructions</title> | |
10 | ||
11 | <para>This chapter explains how to perform the following tasks by using the indicated commands:</para> | |
12 | ||
13 | <informaltable frame="none"> | |
14 | <tgroup cols="2"> | |
15 | <colspec colwidth="58*" /> | |
16 | ||
17 | <colspec colwidth="42*" /> | |
18 | ||
19 | <tbody> | |
20 | <row> | |
21 | <entry>Create read/write volume</entry> | |
22 | ||
23 | <entry><emphasis role="bold">vos create</emphasis></entry> | |
24 | </row> | |
25 | ||
26 | <row> | |
27 | <entry>Create read-only volume</entry> | |
28 | ||
29 | <entry><emphasis role="bold">vos addsite</emphasis> <emphasis role="bold">and</emphasis> <emphasis role="bold">vos | |
30 | release</emphasis></entry> | |
31 | </row> | |
32 | ||
33 | <row> | |
34 | <entry>Create backup volume</entry> | |
35 | ||
36 | <entry><emphasis role="bold">vos backup</emphasis></entry> | |
37 | </row> | |
38 | ||
39 | <row> | |
40 | <entry>Create many backup volumes at once</entry> | |
41 | ||
42 | <entry><emphasis role="bold">vos backupsys</emphasis></entry> | |
43 | </row> | |
44 | ||
45 | <row> | |
46 | <entry>Examine VLDB entry</entry> | |
47 | ||
48 | <entry><emphasis role="bold">vos listvldb</emphasis></entry> | |
49 | </row> | |
50 | ||
51 | <row> | |
52 | <entry>Examine volume header</entry> | |
53 | ||
54 | <entry><emphasis role="bold">vos listvol</emphasis></entry> | |
55 | </row> | |
56 | ||
57 | <row> | |
58 | <entry>Examine both VLDB entry and volume header</entry> | |
59 | ||
60 | <entry><emphasis role="bold">vos examine</emphasis></entry> | |
61 | </row> | |
62 | ||
63 | <row> | |
64 | <entry>Display volume's name</entry> | |
65 | ||
66 | <entry><emphasis role="bold">fs listquota</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs | |
67 | examine</emphasis></entry> | |
68 | </row> | |
69 | ||
70 | <row> | |
71 | <entry>Display volume's ID number</entry> | |
72 | ||
73 | <entry><emphasis role="bold">fs examine</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">vos | |
74 | examine</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">vos listvol</emphasis></entry> | |
75 | </row> | |
76 | ||
77 | <row> | |
78 | <entry>Display partition's size and space available</entry> | |
79 | ||
80 | <entry><emphasis role="bold">vos partinfo</emphasis></entry> | |
81 | </row> | |
82 | ||
83 | <row> | |
84 | <entry>Display volume's location</entry> | |
85 | ||
86 | <entry><emphasis role="bold">fs whereis</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">vos | |
87 | examine</emphasis></entry> | |
88 | </row> | |
89 | ||
90 | <row> | |
91 | <entry>Create mount point</entry> | |
92 | ||
93 | <entry><emphasis role="bold">fs mkmount</emphasis></entry> | |
94 | </row> | |
95 | ||
96 | <row> | |
97 | <entry>Remove mount point</entry> | |
98 | ||
99 | <entry><emphasis role="bold">fs rmmount</emphasis></entry> | |
100 | </row> | |
101 | ||
102 | <row> | |
103 | <entry>Display mount point</entry> | |
104 | ||
105 | <entry><emphasis role="bold">fs lsmount</emphasis></entry> | |
106 | </row> | |
107 | ||
108 | <row> | |
109 | <entry>Move read/write volume</entry> | |
110 | ||
111 | <entry><emphasis role="bold">vos move</emphasis></entry> | |
112 | </row> | |
113 | ||
114 | <row> | |
115 | <entry>Synchronize VLDB with volume headers</entry> | |
116 | ||
117 | <entry><emphasis role="bold">vos syncvldb</emphasis> <emphasis role="bold">and</emphasis> <emphasis role="bold">vos | |
118 | syncserv</emphasis></entry> | |
119 | </row> | |
120 | ||
121 | <row> | |
122 | <entry>Set volume quota</entry> | |
123 | ||
124 | <entry><emphasis role="bold">fs setvol</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs | |
125 | setquota</emphasis></entry> | |
126 | </row> | |
127 | ||
128 | <row> | |
129 | <entry>Display volume quota</entry> | |
130 | ||
131 | <entry><emphasis role="bold">fs quota</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs | |
132 | listquota</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs examine</emphasis></entry> | |
133 | </row> | |
134 | ||
135 | <row> | |
136 | <entry>Display volume's current size</entry> | |
137 | ||
138 | <entry><emphasis role="bold">fs listquota</emphasis> <emphasis role="bold">or</emphasis> <emphasis role="bold">fs | |
139 | examine</emphasis></entry> | |
140 | </row> | |
141 | ||
142 | <row> | |
143 | <entry>Display list of volumes on a machine/partition</entry> | |
144 | ||
145 | <entry><emphasis role="bold">vos listvol</emphasis></entry> | |
146 | </row> | |
147 | ||
148 | <row> | |
149 | <entry>Remove read/write volume</entry> | |
150 | ||
151 | <entry><emphasis role="bold">vos remove</emphasis> <emphasis role="bold">and</emphasis> <emphasis role="bold">fs | |
152 | rmmount</emphasis></entry> | |
153 | </row> | |
154 | ||
155 | <row> | |
156 | <entry>Remove read-only volume</entry> | |
157 | ||
158 | <entry><emphasis role="bold">vos remove</emphasis></entry> | |
159 | </row> | |
160 | ||
161 | <row> | |
162 | <entry>Remove backup volume</entry> | |
163 | ||
164 | <entry><emphasis role="bold">vos remove</emphasis> <emphasis role="bold">and</emphasis> <emphasis role="bold">fs | |
165 | rmmount</emphasis></entry> | |
166 | </row> | |
167 | ||
168 | <row> | |
169 | <entry>Remove volume; no VLDB change</entry> | |
170 | ||
171 | <entry><emphasis role="bold">vos zap</emphasis></entry> | |
172 | </row> | |
173 | ||
174 | <row> | |
175 | <entry>Remove read-only site definition</entry> | |
176 | ||
177 | <entry><emphasis role="bold">vos remsite</emphasis></entry> | |
178 | </row> | |
179 | ||
180 | <row> | |
181 | <entry>Remove VLDB entry; no volume change</entry> | |
182 | ||
183 | <entry><emphasis role="bold">vos delentry</emphasis></entry> | |
184 | </row> | |
185 | ||
186 | <row> | |
187 | <entry>Dump volume</entry> | |
188 | ||
189 | <entry><emphasis role="bold">vos dump</emphasis></entry> | |
190 | </row> | |
191 | ||
192 | <row> | |
193 | <entry>Restore dumped volume</entry> | |
194 | ||
195 | <entry><emphasis role="bold">vos restore</emphasis></entry> | |
196 | </row> | |
197 | ||
198 | <row> | |
199 | <entry>Rename volume</entry> | |
200 | ||
201 | <entry><emphasis role="bold">vos rename</emphasis>, <emphasis role="bold">fs rmmount</emphasis> <emphasis | |
202 | role="bold">and</emphasis> <emphasis role="bold">fs mkmount</emphasis></entry> | |
203 | </row> | |
204 | ||
205 | <row> | |
206 | <entry>Unlock volume</entry> | |
207 | ||
208 | <entry><emphasis role="bold">vos unlock</emphasis></entry> | |
209 | </row> | |
210 | ||
211 | <row> | |
212 | <entry>Unlock multiple volumes</entry> | |
213 | ||
214 | <entry><emphasis role="bold">vos unlockvldb</emphasis></entry> | |
215 | </row> | |
216 | ||
217 | <row> | |
218 | <entry>Lock volume</entry> | |
219 | ||
220 | <entry><emphasis role="bold">vos lock</emphasis></entry> | |
221 | </row> | |
222 | </tbody> | |
223 | </tgroup> | |
224 | </informaltable> | |
225 | </sect1> | |
226 | ||
227 | <sect1 id="HDRWQ177"> | |
228 | <title>About Volumes</title> | |
229 | ||
230 | <indexterm> | |
231 | <primary>volume</primary> | |
232 | ||
233 | <secondary>defined</secondary> | |
234 | </indexterm> | |
235 | ||
236 | <para>An AFS <emphasis>volume</emphasis> is a logical unit of disk space that functions like a container for the files in an AFS | |
237 | directory, keeping them all together on one partition of a file server machine. To make a volume's contents visible in the | |
238 | cell's file tree and accessible to users, you mount the volume at a directory location in the AFS filespace. The association | |
239 | between the volume and its location in the filespace is called a <emphasis>mount point</emphasis>, and because of AFS's internal | |
240 | workings it looks and acts just like a standard directory element. Users can access and manipulate a volume's contents in the | |
241 | same way they access and manipulate the contents of a standard UNIX directory. For more on the relationship between volumes and | |
242 | directories, see <link linkend="HDRWQ183">About Mounting Volumes</link>.</para> | |
243 | ||
244 | <para>Many of an administrator's daily activities involve manipulating volumes, since they are the basic storage and | |
245 | administrative unit of AFS. For a discussion of some of the ways volumes can make your job easier, see <link | |
246 | linkend="HDRWQ179">How Volumes Improve AFS Efficiency</link>.</para> | |
247 | ||
248 | <sect2 id="HDRWQ178"> | |
249 | <title>The Three Types of Volumes</title> | |
250 | ||
251 | <para>There are three types of volumes in AFS, as described in the following list: <itemizedlist> | |
252 | <listitem> | |
253 | <para>The single <emphasis>read/write</emphasis> version of a volume houses the modifiable versions of the files and | |
254 | directories in that volume. It is often referred to as the <emphasis>read/write</emphasis> source because volumes of the | |
255 | other two types are derived from it by a copying procedure called <emphasis>cloning</emphasis>. For instructions on | |
256 | creating read/write volumes, see <link linkend="HDRWQ185">Creating Read/write Volumes</link>.</para> | |
257 | ||
258 | <indexterm> | |
259 | <primary>read/write volume</primary> | |
260 | ||
261 | <secondary>defined</secondary> | |
262 | </indexterm> | |
263 | </listitem> | |
264 | ||
265 | <listitem> | |
266 | <para>A <emphasis>read-only</emphasis> volume is a copy of the read/write source volume and can exist at multiple | |
267 | <emphasis>sites</emphasis> (a site is a particular partition on a particular file server machine). Placing the same data | |
268 | at more than one site is called <emphasis>replication</emphasis>; see <link linkend="HDRWQ179">How Volumes Improve AFS | |
269 | Efficiency</link>. As the name suggests, a read-only volume's contents do not change automatically as the read/write | |
270 | source changes, but only when an administrator issues the <emphasis role="bold">vos release</emphasis> command. For | |
271 | users to have a consistent view of the AFS filespace, all copies of the read-only volume must match each other and their | |
272 | read/write source. All read-only volumes share the same name, which is derived by adding the <emphasis | |
273 | role="bold">.readonly</emphasis> extension to the read/write source's name. For instructions on creating of read-only | |
274 | volumes, see <link linkend="HDRWQ192">Replicating Volumes (Creating Read-only Volumes)</link>.</para> | |
275 | ||
276 | <indexterm> | |
277 | <primary>read-only volume</primary> | |
278 | ||
279 | <secondary>defined</secondary> | |
280 | </indexterm> | |
281 | ||
282 | <indexterm> | |
283 | <primary>site</primary> | |
284 | ||
285 | <secondary>volume, defined</secondary> | |
286 | </indexterm> | |
287 | ||
288 | <indexterm> | |
289 | <primary>volume</primary> | |
290 | ||
291 | <secondary>site, defined</secondary> | |
292 | </indexterm> | |
293 | </listitem> | |
294 | ||
295 | <listitem> | |
296 | <para>A <emphasis>backup</emphasis> volume is a clone of the read/write source volume and is stored at the same site as | |
297 | the source. A backup version is useful because it records the state of the read/write source at a certain time, allowing | |
298 | recovery of data that is later mistakenly changed or deleted (for further discussion see <link linkend="HDRWQ179">How | |
299 | Volumes Improve AFS Efficiency</link>). A backup volume's name is derived by adding the <emphasis | |
300 | role="bold">.backup</emphasis> extension to the read/write source's name. For instructions on creating of backup | |
301 | volumes, see <link linkend="HDRWQ201">Creating Backup Volumes</link>.</para> | |
302 | ||
303 | <indexterm> | |
304 | <primary>backup volume</primary> | |
305 | ||
306 | <secondary>defined</secondary> | |
307 | </indexterm> | |
308 | ||
309 | <note> | |
310 | <para>A backup volume is not the same as the backup of a volume transferred to tape using the AFS Backup System, | |
311 | although making a backup version of a volume is usually a stage in the process of backing up the volume to tape. For | |
312 | information on backing up a volume using the AFS Backup System, see <link linkend="HDRWQ296">Backing Up | |
313 | Data</link>.</para> | |
314 | </note> | |
315 | </listitem> | |
316 | </itemizedlist></para> | |
317 | ||
318 | <para>As noted, the three types of volumes are related to one another: read-only and backup volumes are both derived from a | |
319 | read/write volume through a process called cloning. Read-only and backup volumes are exact copies of the read/write source at | |
320 | the time they are created.</para> | |
321 | </sect2> | |
322 | ||
323 | <sect2 id="HDRWQ179"> | |
324 | <title>How Volumes Improve AFS Efficiency</title> | |
325 | ||
326 | <indexterm> | |
327 | <primary>volume</primary> | |
328 | ||
329 | <secondary>benefits for efficiency</secondary> | |
330 | </indexterm> | |
331 | ||
332 | <para>Volumes make your cell easier to manage and more efficient in the following three ways: <itemizedlist> | |
333 | <listitem> | |
334 | <para>Volumes are easy to move between partitions, on the same or different machines, because they are by definition | |
335 | smaller than a partition. Perhaps the most common reasons to move volumes are to balance the load among file server | |
336 | machines or to take advantage of greater disk capacity on certain machines. You can move volumes as often as necessary | |
337 | without disrupting user access to their contents, because the move procedure makes the contents unavailable for only a | |
338 | few seconds. The automatic tracking of volume locations in the Volume Location Database (VLDB) assures that access | |
339 | remains transparent. For instructions on moving volumes, see <link linkend="HDRWQ226">Moving Volumes</link>.</para> | |
340 | ||
341 | <indexterm> | |
342 | <primary>volume</primary> | |
343 | ||
344 | <secondary>in load balancing</secondary> | |
345 | </indexterm> | |
346 | </listitem> | |
347 | ||
348 | <listitem> | |
349 | <para>Volumes are the unit of replication in AFS. <emphasis>Replication</emphasis> refers to creating a read-only clone | |
350 | from the read/write source and distributing of the clone to one or more sites. Replication improves system efficiency | |
351 | because more than one machine can fill requests for popular files. It also boosts system reliability by helping to keep | |
352 | data available in the face of machine or server process outage. In general, volumes containing popular application | |
353 | programs and other files that do not change often are the best candidates for replication, but you can replicate any | |
354 | read/write volume. See <link linkend="HDRWQ192">Replicating Volumes (Creating Read-only Volumes)</link>.</para> | |
355 | ||
356 | <indexterm> | |
357 | <primary>volume</primary> | |
358 | ||
359 | <secondary>as unit of replication</secondary> | |
360 | </indexterm> | |
361 | ||
362 | <indexterm> | |
363 | <primary>replication</primary> | |
364 | ||
365 | <secondary>defined</secondary> | |
366 | </indexterm> | |
367 | </listitem> | |
368 | ||
369 | <listitem> | |
370 | <indexterm> | |
371 | <primary>volume</primary> | |
372 | ||
373 | <secondary>as unit of backup</secondary> | |
374 | </indexterm> | |
375 | ||
376 | <para>Volumes are the unit of backup in AFS, in two senses. You can create a backup volume version to preserves the | |
377 | state of a read/write source volume at a specified time. You can mount the backup version in the AFS filespace, enabling | |
378 | users to restore data they have accidentally changed or deleted without administrator assistance, which frees you for | |
379 | more important jobs. If you make a new backup version of user volumes once a day (presumably overwriting the former | |
380 | backup), then users are always be able to retrieve the previous day's version of a file. For instructions, see <link | |
381 | linkend="HDRWQ201">Creating Backup Volumes</link>.</para> | |
382 | ||
383 | <para>Backup also refers to using the AFS Backup System to store permanent copies of volume contents on tape or in a | |
384 | special backup data. See <link linkend="HDRWQ248">Configuring the AFS Backup System</link>and <link | |
385 | linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para> | |
386 | </listitem> | |
387 | </itemizedlist></para> | |
388 | </sect2> | |
389 | ||
390 | <sect2 id="HDRWQ180"> | |
391 | <title>Volume Information in the VLDB</title> | |
392 | ||
393 | <para>The Volume Location Database (VLDB) includes entries for every volume in a cell. Perhaps the most important information | |
394 | in the entry is the volume's location, which is key to transparent access to AFS data. When a user opens a file, the Cache | |
395 | Manager consults the Volume Location (VL) Server, which maintains the VLDB, for a list of the file server machines that house | |
396 | the volume containing the file. The Cache Manager then requests the file from the File Server running on one of the relevant | |
397 | file server machines. The file location procedure is invisible to the user, who only needs to know the file's pathname.</para> | |
398 | ||
399 | <indexterm> | |
400 | <primary>VLDB</primary> | |
401 | ||
402 | <secondary>volume entry</secondary> | |
403 | </indexterm> | |
404 | ||
405 | <indexterm> | |
406 | <primary>volume</primary> | |
407 | ||
408 | <secondary>entry in VLDB</secondary> | |
409 | </indexterm> | |
410 | ||
411 | <indexterm> | |
412 | <primary>entry in VLDB</primary> | |
413 | ||
414 | <secondary>for volume</secondary> | |
415 | </indexterm> | |
416 | ||
417 | <para>The VLDB volume entry for a read/write volume also contains the pertinent information about the read-only and backup | |
418 | versions, which do not have their own VLDB entries. (The rare exception is a read-only volume that has its own VLDB entry | |
419 | because its read/write source has been removed.) A volume's VLDB entry records the volume's name, the unique volume ID number | |
420 | for each version (read/write, read-only, backup, and releaseClone), a count of the number of sites that house a read/write or | |
421 | read-only version, and a list of the sites.</para> | |
422 | ||
423 | <para>To display the VLDB entry for one or more volumes, use the <emphasis role="bold">vos listvldb</emphasis> command as | |
424 | described in <link linkend="HDRWQ218">To display VLDB entries</link>. To display the VLDB entry for a single volume along with | |
425 | its <emphasis>volume header</emphasis>, use the <emphasis role="bold">vos examine</emphasis> command as described in <link | |
426 | linkend="HDRWQ222">To display one volume's VLDB entry and volume header</link>. (See the following section for a description | |
427 | of the volume header.)</para> | |
428 | </sect2> | |
429 | ||
430 | <sect2 id="HDRWQ181"> | |
431 | <title>The Information in Volume Headers</title> | |
432 | ||
433 | <indexterm> | |
434 | <primary>volume</primary> | |
435 | ||
436 | <secondary>header</secondary> | |
437 | ||
438 | <see>volume header</see> | |
439 | </indexterm> | |
440 | ||
441 | <indexterm> | |
442 | <primary>volume header</primary> | |
443 | ||
444 | <secondary>about</secondary> | |
445 | </indexterm> | |
446 | ||
447 | <para>Whereas all versions of a volume share one VLDB entry, each volume on an AFS server partition has its own volume header, | |
448 | a data structure that maps the files and directories in the volume to physical memory addresses on the partition that stores | |
449 | them. The volume header binds the volume's contents into a logical unit without requiring that they be stored in contiguous | |
450 | memory blocks. The volume header also records the following information about the volume, some of it redundant with the VLDB | |
451 | entry: name, volume ID number, type, size, status (online, offline, or busy), space quota, timestamps for creation date and | |
452 | date of last modification, and number of accesses during the current day.</para> | |
453 | ||
454 | <para>To display the volume headers on one or more partitions, use the <emphasis role="bold">vos listvol</emphasis> command as | |
455 | described in <link linkend="HDRWQ220">To display volume headers</link>. To display the VLDB entry for a single volume along | |
456 | with its volume header, use the <emphasis role="bold">vos examine</emphasis> command as described in <link | |
457 | linkend="HDRWQ222">To display one volume's VLDB entry and volume header</link>.</para> | |
458 | </sect2> | |
459 | ||
460 | <sect2 id="HDRWQ182"> | |
461 | <title>Keeping the VLDB and Volume Headers Synchronized</title> | |
462 | ||
463 | <indexterm> | |
464 | <primary>synchrony of VLDB and volume headers</primary> | |
465 | ||
466 | <secondary>maintained by VL and Volume Servers</secondary> | |
467 | </indexterm> | |
468 | ||
469 | <indexterm> | |
470 | <primary>VLDB</primary> | |
471 | ||
472 | <secondary>synchronizing with volume headers</secondary> | |
473 | </indexterm> | |
474 | ||
475 | <indexterm> | |
476 | <primary>volume header</primary> | |
477 | ||
478 | <secondary>synchronizing with VLDB</secondary> | |
479 | </indexterm> | |
480 | ||
481 | <indexterm> | |
482 | <primary>maintaining</primary> | |
483 | ||
484 | <secondary>synchrony of VLDB with volume headers</secondary> | |
485 | </indexterm> | |
486 | ||
487 | <indexterm> | |
488 | <primary>VL Server</primary> | |
489 | ||
490 | <secondary>role in VLDB/volume header synchronization</secondary> | |
491 | </indexterm> | |
492 | ||
493 | <indexterm> | |
494 | <primary>Volume Server</primary> | |
495 | ||
496 | <secondary>role in VLDB/volume header synchronization</secondary> | |
497 | </indexterm> | |
498 | ||
499 | <para>It is vital that the information in the VLDB correspond to the status of the actual volumes on the servers (as recorded | |
500 | in volume headers) as much of the time as possible. If a volume's location information in the VLDB is incorrect, the Cache | |
501 | Manager cannot find access its contents. Whenever you issue a <emphasis role="bold">vos</emphasis> command that changes a | |
502 | volume's status, the Volume Server and VL Server cooperate to keep the volume header and VLDB synchronized. In rare cases, the | |
503 | header and VLDB can diverge, for instance because a <emphasis role="bold">vos</emphasis> operation halts prematurely. For | |
504 | instructions on resynchronizing them, see <link linkend="HDRWQ227">Synchronizing the VLDB and Volume Headers</link>.</para> | |
505 | </sect2> | |
506 | ||
507 | <sect2 id="HDRWQ183"> | |
508 | <title>About Mounting Volumes</title> | |
509 | ||
510 | <indexterm> | |
511 | <primary>mount point</primary> | |
512 | ||
513 | <secondary>defined</secondary> | |
514 | </indexterm> | |
515 | ||
516 | <indexterm> | |
517 | <primary>volume</primary> | |
518 | ||
519 | <secondary>mounting</secondary> | |
520 | ||
521 | <tertiary>about</tertiary> | |
522 | </indexterm> | |
523 | ||
524 | <indexterm> | |
525 | <primary>mounting</primary> | |
526 | ||
527 | <secondary>volume</secondary> | |
528 | ||
529 | <tertiary>about</tertiary> | |
530 | </indexterm> | |
531 | ||
532 | <para>To make a volume's contents visible in the cell's file tree and accessible to users, you mount the volume at a directory | |
533 | location in the AFS filespace. The association between the volume and its location in the filespace is called a | |
534 | <emphasis>mount point</emphasis>. An AFS mount point looks and functions like a regular UNIX file system directory, but | |
535 | structurally it is more like a symbolic link that tells the Cache Manager the name of the volume associated with the | |
536 | directory. A mount point looks and acts like a directory only because the Cache Manager knows how to interpret it.</para> | |
537 | ||
538 | <para>Consider the common case where the Cache Manager needs to retrieve a file requested by an application program. The Cache | |
539 | Manager traverses the file's complete pathname, starting at the AFS root (by convention mounted at the <emphasis | |
540 | role="bold">/afs</emphasis> directory) and continuing to the file. When the Cache Manager encounters (or | |
541 | <emphasis>crosses</emphasis>) a mount point during the traversal, it reads it to learn the name of the volume mounted at that | |
542 | directory location. After obtaining location information about the volume from the Volume Location (VL) Server, the Cache | |
543 | Manager fetches the indicated volume and opens its <emphasis>root directory</emphasis>. The root directory of a volume lists | |
544 | all the files, subdirectories, and mount points that reside in it. The Cache Manager scans the root directory listing for the | |
545 | next element in the pathname. It continues down the path, using this method to interpret any other mount points it encounters, | |
546 | until it reaches the volume that houses the requested file.</para> | |
547 | ||
548 | <indexterm> | |
549 | <primary>root directory</primary> | |
550 | </indexterm> | |
551 | ||
552 | <indexterm> | |
553 | <primary>Cache Manager</primary> | |
554 | ||
555 | <secondary>as interpreter of mount points</secondary> | |
556 | </indexterm> | |
557 | ||
558 | <para>Mount points act as the glue that connects the AFS file space, creating the illusion of a single, seamless file tree | |
559 | even when volumes reside on many different file server machines. A volume's contents are visible and accessible when the | |
560 | volume is mounted at a directory location, and are not accessible at all if the volume is not mounted.</para> | |
561 | ||
562 | <para>You can mount a volume at more than one location in the file tree, but this is not recommended for two reasons. First, | |
563 | it distorts the hierarchical nature of the filespace. Second, the Cache Manager can become confused about which pathname it | |
564 | followed to reach the file (causing unpredictable output from the <emphasis role="bold">pwd</emphasis> command, for example). | |
565 | However, if you mount a volume at more than one directory, the access control list (ACL) associated with the volume's root | |
566 | directory applies to all of the mount points.</para> | |
567 | ||
568 | <indexterm> | |
569 | <primary>mount point</primary> | |
570 | ||
571 | <secondary>creating multiple per volume</secondary> | |
572 | </indexterm> | |
573 | ||
574 | <indexterm> | |
575 | <primary>volume</primary> | |
576 | ||
577 | <secondary>mounting</secondary> | |
578 | ||
579 | <tertiary>more than once</tertiary> | |
580 | </indexterm> | |
581 | ||
582 | <para>There are several types of mount points, each of which the Cache Manager handles in a different way and each of which is | |
583 | appropriate for a different purpose. See <link linkend="HDRWQ208">Mounting Volumes</link>.</para> | |
584 | </sect2> | |
585 | ||
586 | <sect2 id="HDRWQ184"> | |
587 | <title>About Volume Names</title> | |
588 | ||
589 | <indexterm> | |
590 | <primary>volume</primary> | |
591 | ||
592 | <secondary>name</secondary> | |
593 | ||
594 | <see>volume name</see> | |
595 | </indexterm> | |
596 | ||
597 | <indexterm> | |
598 | <primary>length restriction on volume names</primary> | |
599 | </indexterm> | |
600 | ||
601 | <para>A read/write volume's name can be up to 22 characters in length. The Volume Server automatically adds the <emphasis | |
602 | role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extensions to read-only and backup volumes | |
603 | respectively. Do not explicitly add the extensions to volume names, even if they are appropriate.</para> | |
604 | ||
605 | <para>It is conventional for a volume's name to indicate the type of data it houses. For example, it is conventional to name | |
606 | all user volumes <emphasis role="bold">user</emphasis>.username where username is the user's login name. Similarly, many cells | |
607 | elect to put system binaries in volumes with names that begin with the system type code. For a list of other naming | |
608 | conventions, see <link linkend="HDRWQ44">Creating Volumes to Simplify Administration</link>.</para> | |
609 | ||
610 | <indexterm> | |
611 | <primary>conventions</primary> | |
612 | ||
613 | <secondary>volume names</secondary> | |
614 | </indexterm> | |
615 | ||
616 | <indexterm> | |
617 | <primary>volume name</primary> | |
618 | ||
619 | <secondary>conventions</secondary> | |
620 | </indexterm> | |
621 | </sect2> | |
622 | </sect1> | |
623 | ||
624 | <sect1 id="HDRWQ185"> | |
625 | <title>Creating Read/write Volumes</title> | |
626 | ||
627 | <indexterm> | |
628 | <primary>creating</primary> | |
629 | ||
630 | <secondary>read/write volume</secondary> | |
631 | </indexterm> | |
632 | ||
633 | <indexterm> | |
634 | <primary>volume</primary> | |
635 | ||
636 | <secondary>read/write</secondary> | |
637 | ||
638 | <see>read/write volume</see> | |
639 | </indexterm> | |
640 | ||
641 | <indexterm> | |
642 | <primary>read/write volume</primary> | |
643 | ||
644 | <secondary>creating</secondary> | |
645 | </indexterm> | |
646 | ||
647 | <para>A read/write volume is the most basic type of volume, and must exist before you can create read-only or backup versions of | |
648 | it. When you issue the <emphasis role="bold">vos create</emphasis> command to create a read/write volume, the VL Server creates | |
649 | a VLDB entry for it which records the name you specify, assigns a read/write volume ID number, and reserves the next two | |
650 | consecutive volume ID numbers for read-only and backup versions that possibly are to be created later. At the same time, the | |
651 | Volume Server creates a volume header at the site you designate, allocating space on disk to record the name of the volume's | |
652 | root directory. The name is filled in when you issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the | |
653 | volume, and matches the mount point name. The following is also recorded in the volume header: <itemizedlist> | |
654 | <listitem> | |
655 | <para>An initial ACL associated with the volume's root directory. By default it grants all seven AFS access permissions to | |
656 | the <emphasis role="bold">system:administrators</emphasis> group. After you mount the volume, you can use the <emphasis | |
657 | role="bold">fs setacl</emphasis> command to add other entries and to remove or change the entry for the <emphasis | |
658 | role="bold">system:administrators</emphasis> group. See <link linkend="HDRWQ573">Setting ACL Entries</link>.</para> | |
659 | ||
660 | <indexterm> | |
661 | <primary>default</primary> | |
662 | ||
663 | <secondary>ACL</secondary> | |
664 | </indexterm> | |
665 | ||
666 | <indexterm> | |
667 | <primary>ACL</primary> | |
668 | ||
669 | <secondary>default on new volume</secondary> | |
670 | </indexterm> | |
671 | </listitem> | |
672 | ||
673 | <listitem> | |
674 | <para>A space quota, which limits the amount of disk space the read/write version of the volume can use on the file server | |
675 | partition. The default is of 5000 kilobyte blocks, but you can use the <emphasis role="bold">-maxquota</emphasis> argument | |
676 | to the <emphasis role="bold">vos create</emphasis> command to set a different quota.</para> | |
677 | ||
678 | <para>To change the quota after creation, use the <emphasis role="bold">fs setquota</emphasis> command as described in | |
679 | <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current Size</link>.</para> | |
680 | ||
681 | <indexterm> | |
682 | <primary>volume quota</primary> | |
683 | ||
684 | <secondary>default for new volume</secondary> | |
685 | </indexterm> | |
686 | ||
687 | <indexterm> | |
688 | <primary>default</primary> | |
689 | ||
690 | <secondary>volume quota</secondary> | |
691 | </indexterm> | |
692 | </listitem> | |
693 | </itemizedlist></para> | |
694 | ||
695 | <sect2 id="Header_212"> | |
696 | <title>To create (and mount) a read/write volume</title> | |
697 | ||
698 | <orderedlist> | |
699 | <listitem> | |
700 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
701 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
702 | display the users in the UserList file</link>. <programlisting> | |
703 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
704 | </programlisting></para> | |
705 | </listitem> | |
706 | ||
707 | <listitem> | |
708 | <para>Verify that you have the <emphasis role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>), <emphasis | |
709 | role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>), and <emphasis role="bold">l</emphasis>( <emphasis | |
710 | role="bold">lookup</emphasis>) permissions on the ACL of the directory where you plan to mount the volume. If necessary, | |
711 | issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link | |
712 | linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
713 | % <emphasis role="bold">fs listacl</emphasis> [<<emphasis>dir/file path</emphasis>>]</programlisting></para> | |
714 | ||
715 | <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis | |
716 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis | |
717 | role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis | |
718 | role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para> | |
719 | ||
720 | <indexterm> | |
721 | <primary>commands</primary> | |
722 | ||
723 | <secondary>vos partinfo</secondary> | |
724 | </indexterm> | |
725 | ||
726 | <indexterm> | |
727 | <primary>vos commands</primary> | |
728 | ||
729 | <secondary>partinfo</secondary> | |
730 | </indexterm> | |
731 | </listitem> | |
732 | ||
733 | <listitem id="LIWQ186"> | |
734 | <para>Select a site (disk partition on a file server machine) for the new volume. To verify that | |
735 | the site has enough free space to house the volume (now, or if it grows to use its entire quota), issue the <emphasis | |
736 | role="bold">vos partinfo</emphasis> command.</para> | |
737 | ||
738 | <note> | |
739 | <para>The partition-related statistics in this command's output do not always agree with the corresponding values in the | |
740 | output of the standard UNIX <emphasis role="bold">df</emphasis> command. The statistics reported by this command can be | |
741 | up to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency. | |
742 | Also, on some operating systems, the <emphasis role="bold">df</emphasis> command's report of partition size includes | |
743 | reserved space not included in this command's calculation, and so is likely to be about 10% larger.</para> | |
744 | </note> | |
745 | ||
746 | <programlisting> | |
747 | % <emphasis role="bold">vos partinfo</emphasis> <<emphasis>machine name</emphasis>> [<<emphasis>partition name</emphasis>>]</programlisting> | |
748 | ||
749 | <para>where <variablelist> | |
750 | <varlistentry> | |
751 | <term><emphasis role="bold">p</emphasis></term> | |
752 | ||
753 | <listitem> | |
754 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">partinfo</emphasis>.</para> | |
755 | </listitem> | |
756 | </varlistentry> | |
757 | ||
758 | <varlistentry> | |
759 | <term><emphasis role="bold">machine name</emphasis></term> | |
760 | ||
761 | <listitem> | |
762 | <para>Specifies the file server machine for which to display partition size and usage.</para> | |
763 | </listitem> | |
764 | </varlistentry> | |
765 | ||
766 | <varlistentry> | |
767 | <term><emphasis role="bold">partition name</emphasis></term> | |
768 | ||
769 | <listitem> | |
770 | <para>Names one partition for which to display partition size and usage. If you omit it, the output displays the | |
771 | size and space available for all partitions on the machine.</para> | |
772 | </listitem> | |
773 | </varlistentry> | |
774 | </variablelist></para> | |
775 | </listitem> | |
776 | ||
777 | <listitem id="LIWQ187"> | |
778 | <para>Select a volume name, taking note of the information in <link linkend="HDRWQ184">About Volume | |
779 | Names</link>.</para> | |
780 | ||
781 | <indexterm> | |
782 | <primary>vos commands</primary> | |
783 | ||
784 | <secondary>create</secondary> | |
785 | ||
786 | <tertiary>basic instructions</tertiary> | |
787 | </indexterm> | |
788 | ||
789 | <indexterm> | |
790 | <primary>commands</primary> | |
791 | ||
792 | <secondary>vos create</secondary> | |
793 | ||
794 | <tertiary>basic instructions</tertiary> | |
795 | </indexterm> | |
796 | </listitem> | |
797 | ||
798 | <listitem id="LIWQ188"> | |
799 | <para>Issue the <emphasis role="bold">vos create</emphasis> command to create the volume. | |
800 | <programlisting> | |
801 | % <emphasis role="bold">vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <<replaceable>volume name</replaceable>> \ | |
802 | [<emphasis role="bold">-maxquota</emphasis> <<replaceable>initial quota (KB)</replaceable>>] | |
803 | </programlisting></para> | |
804 | ||
805 | <para>where <variablelist> | |
806 | <varlistentry> | |
807 | <term><emphasis role="bold">cr</emphasis></term> | |
808 | ||
809 | <listitem> | |
810 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">create</emphasis>.</para> | |
811 | </listitem> | |
812 | </varlistentry> | |
813 | ||
814 | <varlistentry> | |
815 | <term><emphasis role="bold">machine name</emphasis></term> | |
816 | ||
817 | <listitem> | |
818 | <para>Specifies the file server machine on which to place the volume.</para> | |
819 | </listitem> | |
820 | </varlistentry> | |
821 | ||
822 | <varlistentry> | |
823 | <term><emphasis role="bold">partition name</emphasis></term> | |
824 | ||
825 | <listitem> | |
826 | <para>Specifies the disk partition on which to place the volume.</para> | |
827 | </listitem> | |
828 | </varlistentry> | |
829 | ||
830 | <varlistentry> | |
831 | <term><emphasis role="bold">volume name</emphasis></term> | |
832 | ||
833 | <listitem> | |
834 | <para>Names the volume. It can be up to 22 alphanumeric and punctuation characters in length. Your cell possibly | |
835 | has naming conventions for volumes, such as beginning user volume names with the string <emphasis | |
836 | role="bold">user</emphasis> and using the period to separate parts of the name.</para> | |
837 | </listitem> | |
838 | </varlistentry> | |
839 | ||
840 | <varlistentry> | |
841 | <term><emphasis role="bold">-maxquota</emphasis></term> | |
842 | ||
843 | <listitem> | |
844 | <para>Sets the volume's quota, as a number of kilobyte blocks. If you omit this argument, the quota is set to 5000 | |
845 | kilobyte blocks.</para> | |
846 | </listitem> | |
847 | </varlistentry> | |
848 | </variablelist></para> | |
849 | ||
850 | <indexterm> | |
851 | <primary>mounting</primary> | |
852 | ||
853 | <secondary>read/write volume</secondary> | |
854 | </indexterm> | |
855 | ||
856 | <indexterm> | |
857 | <primary>read/write volume</primary> | |
858 | ||
859 | <secondary>mounting</secondary> | |
860 | </indexterm> | |
861 | ||
862 | <indexterm> | |
863 | <primary>commands</primary> | |
864 | ||
865 | <secondary>fs mkmount</secondary> | |
866 | </indexterm> | |
867 | ||
868 | <indexterm> | |
869 | <primary>fs commands</primary> | |
870 | ||
871 | <secondary>mkmount</secondary> | |
872 | ||
873 | <tertiary>for read/write volume</tertiary> | |
874 | </indexterm> | |
875 | </listitem> | |
876 | ||
877 | <listitem id="LIWQ189"> | |
878 | <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount | |
879 | the volume in the filespace. For complete syntax, see <link linkend="HDRWQ212">To create a regular or read/write mount | |
880 | point</link>. <programlisting> | |
881 | % <emphasis role="bold">fs mkmount</emphasis> <<emphasis>directory</emphasis>> <<emphasis>volume name</emphasis>></programlisting></para> | |
882 | </listitem> | |
883 | ||
884 | <listitem> | |
885 | <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs lsmount</emphasis> command to verify | |
886 | that the mount point refers to the correct volume. Complete instructions appear in <link linkend="HDRWQ211">To display a | |
887 | mount point</link>. <programlisting> | |
888 | % <emphasis role="bold">fs lsmount</emphasis> <<emphasis>directory</emphasis>></programlisting></para> | |
889 | </listitem> | |
890 | ||
891 | <listitem> | |
892 | <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs setvol</emphasis> command with the | |
893 | <emphasis role="bold">-offlinemsg</emphasis> argument to record auxiliary information about the volume in its volume | |
894 | header. For example, you can record who owns the volume or where you have mounted it in the filespace. To display the | |
895 | information, use the <emphasis role="bold">fs examine</emphasis> command. <programlisting> | |
896 | % <emphasis role="bold">fs setvol</emphasis> <<replaceable>dir/file path</replaceable>> <emphasis role="bold">-offlinemsg </emphasis> <<replaceable>offline message</replaceable>> | |
897 | </programlisting></para> | |
898 | ||
899 | <para>where <variablelist> | |
900 | <varlistentry> | |
901 | <term><emphasis role="bold">sv</emphasis></term> | |
902 | ||
903 | <listitem> | |
904 | <para>Is an acceptable alias for <emphasis role="bold">setvol</emphasis>(and <emphasis role="bold">setv</emphasis> | |
905 | the shortest acceptable abbreviation).</para> | |
906 | </listitem> | |
907 | </varlistentry> | |
908 | ||
909 | <varlistentry> | |
910 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
911 | ||
912 | <listitem> | |
913 | <para>Names the mount point of the volume with which to associate the message. Partial pathnames are interpreted | |
914 | relative to the current working directory.</para> | |
915 | ||
916 | <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to change | |
917 | a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at | |
918 | the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For further discussion | |
919 | of the concept of read/write and read-only paths through the filespace, see <link linkend="HDRWQ209">The Rules of | |
920 | Mount Point Traversal</link>.</para> | |
921 | </listitem> | |
922 | </varlistentry> | |
923 | ||
924 | <varlistentry> | |
925 | <term><emphasis role="bold">-offlinemsg</emphasis></term> | |
926 | ||
927 | <listitem> | |
928 | <para>Specifies up to 128 characters of auxiliary information to record in the volume header.</para> | |
929 | </listitem> | |
930 | </varlistentry> | |
931 | </variablelist></para> | |
932 | </listitem> | |
933 | </orderedlist> | |
934 | </sect2> | |
935 | </sect1> | |
936 | ||
937 | <sect1 id="HDRWQ190"> | |
938 | <title>About Clones and Cloning</title> | |
939 | ||
940 | <indexterm> | |
941 | <primary>cloning</primary> | |
942 | ||
943 | <secondary>defined</secondary> | |
944 | </indexterm> | |
945 | ||
946 | <indexterm> | |
947 | <primary>clone</primary> | |
948 | </indexterm> | |
949 | ||
950 | <indexterm> | |
951 | <primary>vnode index</primary> | |
952 | </indexterm> | |
953 | ||
954 | <indexterm> | |
955 | <primary>backup volume</primary> | |
956 | ||
957 | <secondary>space-saving nature of</secondary> | |
958 | </indexterm> | |
959 | ||
960 | <para>To create a backup or read-only volume, the Volume Server begins by <emphasis>cloning</emphasis> the read/write source | |
961 | volume to create a <emphasis>clone</emphasis>. The Volume Server creates the clone automatically when you issue the <emphasis | |
962 | role="bold">vos backup</emphasis> or <emphasis role="bold">vos backupsys</emphasis> command (for a backup volume) or the | |
963 | <emphasis role="bold">vos release</emphasis> command (for a read-only volume). No special action is required on your | |
964 | part.</para> | |
965 | ||
966 | <para>A clone is not a copy of the data in the read/write source volume, but rather a copy of the read/write volume's | |
967 | <emphasis>vnode index</emphasis>. The vnode index is a table of pointers between the files and directories in the volume and the | |
968 | physical disk blocks on the partition where the data resides. From the clone, backup and read-only volumes are created in the | |
969 | following manner: <itemizedlist> | |
970 | <listitem> | |
971 | <para>A read-only volume that occupies the same partition as its read/write source (also known as a <emphasis>read-only | |
972 | clone</emphasis>), and a backup volume, are created by attaching a volume header to the clone. These volumes initially | |
973 | consume very little disk space, because the clone portion (the vnode index) points to exactly the same files as the | |
974 | read/write volume, as illustrated in <link linkend="FIGWQ191">Figure 1</link>. The file sharing is possible only because | |
975 | the clone is on the same partition as the read/write source volume. When a file in the read/write volume is deleted, it is | |
976 | not actually removed from the partition, because the backup or read-only clone still points to it. Similarly, when a file | |
977 | in the read/write is changed, the entire original file is preserved on disk because the clone still points to it, and the | |
978 | read/write volume's vnode index changes to point to newly space for the changed file. When this happens, the backup or | |
979 | read-only volume is said to grow or start occupying actual disk space.</para> | |
980 | </listitem> | |
981 | ||
982 | <listitem> | |
983 | <para>A read-only volume that does not occupy the same site as the read/write source is a copy of the clone and of all of | |
984 | the data in the read/write source volume. It occupies the same amount of disk space as the read/write volume did at the | |
985 | time the read-only volume was created.</para> | |
986 | </listitem> | |
987 | </itemizedlist></para> | |
988 | ||
989 | <figure id="FIGWQ191" label="1"> | |
990 | <title>File Sharing Between the Read/write Source and a Clone Volume</title> | |
991 | ||
992 | <mediaobject> | |
993 | <imageobject> | |
994 | <imagedata fileref="vnode.png" scale="50" /> | |
995 | </imageobject> | |
996 | </mediaobject> | |
997 | </figure> | |
998 | ||
999 | <indexterm> | |
1000 | <primary>replication</primary> | |
1001 | ||
1002 | <secondary>detailed discussion</secondary> | |
1003 | </indexterm> | |
1004 | ||
1005 | <indexterm> | |
1006 | <primary>volume</primary> | |
1007 | ||
1008 | <secondary>replicating</secondary> | |
1009 | </indexterm> | |
1010 | ||
1011 | <indexterm> | |
1012 | <primary>volume</primary> | |
1013 | ||
1014 | <secondary>read-only</secondary> | |
1015 | ||
1016 | <see>read-only volume</see> | |
1017 | </indexterm> | |
1018 | ||
1019 | <indexterm> | |
1020 | <primary>read-only volume</primary> | |
1021 | ||
1022 | <secondary>creating</secondary> | |
1023 | </indexterm> | |
1024 | ||
1025 | <indexterm> | |
1026 | <primary>creating</primary> | |
1027 | ||
1028 | <secondary>read-only volume</secondary> | |
1029 | </indexterm> | |
1030 | ||
1031 | <indexterm> | |
1032 | <primary>cloning</primary> | |
1033 | ||
1034 | <secondary>for replication</secondary> | |
1035 | </indexterm> | |
1036 | ||
1037 | <indexterm> | |
1038 | <primary>read/write volume</primary> | |
1039 | ||
1040 | <secondary>cloning</secondary> | |
1041 | ||
1042 | <tertiary>for replication</tertiary> | |
1043 | </indexterm> | |
1044 | </sect1> | |
1045 | ||
1046 | <sect1 id="HDRWQ192"> | |
1047 | <title>Replicating Volumes (Creating Read-only Volumes)</title> | |
1048 | ||
1049 | <para><emphasis>Replication</emphasis> refers to creating a read-only copy of a read/write volume and distributing the copy to | |
1050 | one or more additional file server machines. Replication makes a volume's contents accessible on more than one file server | |
1051 | machine, which increases data availability. It can also increase system efficiency by reducing load on the network and File | |
1052 | Server. Network load is reduced if a client machine's server preference ranks lead the Cache Manager to access the copy of a | |
1053 | volume stored on the closest file server machine. Load on the File Server is reduced because it issues only one callback for all | |
1054 | data fetched from a read-only volume, as opposed to a callback for each file fetched from a read/write volume. The single | |
1055 | callback is sufficient for an entire read-only volume because the volume does not change except in response to administrator | |
1056 | action, whereas each read/write file can change at any time.</para> | |
1057 | ||
1058 | <indexterm> | |
1059 | <primary>stages in volume replication</primary> | |
1060 | </indexterm> | |
1061 | ||
1062 | <indexterm> | |
1063 | <primary>site definition stage in replication</primary> | |
1064 | </indexterm> | |
1065 | ||
1066 | <indexterm> | |
1067 | <primary>replication</primary> | |
1068 | ||
1069 | <secondary>site definition stage</secondary> | |
1070 | </indexterm> | |
1071 | ||
1072 | <indexterm> | |
1073 | <primary>release stage in replication</primary> | |
1074 | </indexterm> | |
1075 | ||
1076 | <indexterm> | |
1077 | <primary>replication</primary> | |
1078 | ||
1079 | <secondary>release stage</secondary> | |
1080 | </indexterm> | |
1081 | ||
1082 | <para>Replicating a volume requires issuing two commands. First, use the <emphasis role="bold">vos addsite</emphasis> command to | |
1083 | add one or more read-only site definitions to the volume's VLDB entry (a <emphasis>site</emphasis> is a particular partition on | |
1084 | a file server machine). Then use the <emphasis role="bold">vos release</emphasis> command to clone the read/write source volume | |
1085 | and distribute the clone to the defined read-only sites. You issue the <emphasis role="bold">vos addsite</emphasis> only once | |
1086 | for each read-only site, but must reissue the <emphasis role="bold">vos release</emphasis> command every time the read/write | |
1087 | volume's contents change and you want to update the read-only volumes.</para> | |
1088 | ||
1089 | <para>For users to have a consistent view of the file system, the release of updated volume contents to read-only sites must be | |
1090 | atomic: either all read-only sites receive the new version of the volume, or all sites keep the version they currently have. The | |
1091 | <emphasis role="bold">vos release</emphasis> command is designed to ensure that all copies of the volume's read-only version | |
1092 | match both the read/write source and each other. In cases where problems such as machine or server process outages prevent | |
1093 | successful completion of the release operation, AFS uses two mechanisms to alert you.</para> | |
1094 | ||
1095 | <indexterm> | |
1096 | <primary>replication</primary> | |
1097 | ||
1098 | <secondary>determining success of</secondary> | |
1099 | </indexterm> | |
1100 | ||
1101 | <indexterm> | |
1102 | <primary>determining</primary> | |
1103 | ||
1104 | <secondary>success of replication</secondary> | |
1105 | </indexterm> | |
1106 | ||
1107 | <indexterm> | |
1108 | <primary>replication</primary> | |
1109 | ||
1110 | <secondary>need for all-or-nothing release</secondary> | |
1111 | </indexterm> | |
1112 | ||
1113 | <indexterm> | |
1114 | <primary>all-or-nothing release of read-only volumes</primary> | |
1115 | </indexterm> | |
1116 | ||
1117 | <indexterm> | |
1118 | <primary>read-only volume</primary> | |
1119 | ||
1120 | <secondary>need for atomic release</secondary> | |
1121 | </indexterm> | |
1122 | ||
1123 | <indexterm> | |
1124 | <primary>releasing</primary> | |
1125 | ||
1126 | <secondary>read-only volume, need for atomicity</secondary> | |
1127 | </indexterm> | |
1128 | ||
1129 | <indexterm> | |
1130 | <primary>ReleaseClone</primary> | |
1131 | </indexterm> | |
1132 | ||
1133 | <indexterm> | |
1134 | <primary>replication</primary> | |
1135 | ||
1136 | <secondary>role of ReleaseClone</secondary> | |
1137 | </indexterm> | |
1138 | ||
1139 | <indexterm> | |
1140 | <primary>New release site flag in VLDB</primary> | |
1141 | ||
1142 | <secondary>as indicator of failed replication</secondary> | |
1143 | </indexterm> | |
1144 | ||
1145 | <indexterm> | |
1146 | <primary>Old release site flag in VLDB</primary> | |
1147 | ||
1148 | <secondary>as indicator of failed replication</secondary> | |
1149 | </indexterm> | |
1150 | ||
1151 | <indexterm> | |
1152 | <primary>clone</primary> | |
1153 | ||
1154 | <secondary>forcing creation of new</secondary> | |
1155 | </indexterm> | |
1156 | ||
1157 | <indexterm> | |
1158 | <primary>replication</primary> | |
1159 | ||
1160 | <secondary>forcing creation of new clone</secondary> | |
1161 | </indexterm> | |
1162 | ||
1163 | <indexterm> | |
1164 | <primary>vos commands</primary> | |
1165 | ||
1166 | <secondary>release</secondary> | |
1167 | ||
1168 | <tertiary>forcing new cloning with -f flag</tertiary> | |
1169 | </indexterm> | |
1170 | ||
1171 | <indexterm> | |
1172 | <primary>releasing</primary> | |
1173 | ||
1174 | <secondary>read-only volume, forcing new cloning</secondary> | |
1175 | </indexterm> | |
1176 | ||
1177 | <para>First, the command interpreter generates an error message on the standard error stream naming each read-only site that did | |
1178 | not receive the new volume version. Second, during the release operation the Volume Location (VL) Server marks site definitions | |
1179 | in the VLDB entry with flags (<computeroutput>New release</computeroutput> and <computeroutput>Old release</computeroutput>) | |
1180 | that indicate whether or not the site has the new volume version. If any flags remain after the operation completes, it was not | |
1181 | successful. The Cache Manager refuses to access a read-only site marked with the <computeroutput>Old release</computeroutput> | |
1182 | flag, which potentially imposes a greater load on the sites marked with the <computeroutput>New release</computeroutput> flag. | |
1183 | It is important to investigate and eliminate the cause of the failure and then to issue the <emphasis role="bold">vos | |
1184 | release</emphasis> command as many times as necessary to complete the release without errors.</para> | |
1185 | ||
1186 | <para>The pattern of site flags remaining in the volume's VLDB entry after a failed release operation can help determine the | |
1187 | point at which the operation failed. Use the <emphasis role="bold">vos examine</emphasis> or <emphasis role="bold">vos | |
1188 | listvldb</emphasis> command to display the VLDB entry. The VL Server sets the flags in concert with the Volume Server's | |
1189 | operations, as follows: <orderedlist> | |
1190 | <listitem> | |
1191 | <para>Before the operation begins, the VL Server sets the <computeroutput>New release</computeroutput> flag on the | |
1192 | read/write site definition in the VLDB entry and the <computeroutput>Old release</computeroutput> flag on read-only site | |
1193 | definitions (unless the read-only site has been defined since the last release operation and has no actual volume, in | |
1194 | which case its site flag remains <computeroutput>Not released</computeroutput>).</para> | |
1195 | </listitem> | |
1196 | ||
1197 | <listitem> | |
1198 | <para>If necessary, the Volume Server creates a temporary copy (a <emphasis>clone</emphasis>) of the read/write source | |
1199 | called the ReleaseClone (see the following discussion of when the Volume Server does or does not create a new | |
1200 | ReleaseClone.) It assigns the ReleaseClone its own volume ID number, which the VL Server records in the | |
1201 | <computeroutput>RClone</computeroutput> field of the source volume's VLDB entry.</para> | |
1202 | </listitem> | |
1203 | ||
1204 | <listitem> | |
1205 | <para>The Volume Server distributes a copy of the ReleaseClone to each read-only site defined in the VLDB entry. As the | |
1206 | site successfully receives the new clone, the VL Server sets the site's flag in the VLDB entry to <computeroutput>New | |
1207 | release</computeroutput>.</para> | |
1208 | </listitem> | |
1209 | ||
1210 | <listitem> | |
1211 | <para>When all the read-only copies are successfully released, the VL Server clears all the <computeroutput>New | |
1212 | release</computeroutput> site flags. The ReleaseClone is no longer needed, so the Volume Server deletes it and the VL | |
1213 | Server erases its ID from the VLDB entry.</para> | |
1214 | </listitem> | |
1215 | </orderedlist></para> | |
1216 | ||
1217 | <para>By default, the Volume Server determines automatically whether or not it needs to create a new ReleaseClone: <itemizedlist> | |
1218 | <listitem> | |
1219 | <para>If there are no flags (<computeroutput>New release</computeroutput>, <computeroutput>Old release</computeroutput>, | |
1220 | or <computeroutput>Not released</computeroutput>) on site definitions in the VLDB entry, the previous <emphasis | |
1221 | role="bold">vos release</emphasis> command completed successfully and all read-only sites currently have the same volume. | |
1222 | The Volume Server infers that the current <emphasis role="bold">vos release</emphasis> command was issued because the | |
1223 | read/write volume has changed. The Volume Server creates a new ReleaseClone and distributes it to all of the read-only | |
1224 | sites.</para> | |
1225 | </listitem> | |
1226 | ||
1227 | <listitem> | |
1228 | <para>If any site definition in the VLDB entry is marked with a flag, either the previous release operation did not | |
1229 | complete successfully or a new read-only site was defined since the last release. The Volume Server does not create a new | |
1230 | ReleaseClone, instead distributing the existing ReleaseClone to sites marked with the <computeroutput>Old | |
1231 | release</computeroutput> or <computeroutput>Not released</computeroutput> flag. As previously noted, the VL Server marks | |
1232 | each VLDB site definition with the <computeroutput>New release</computeroutput> flag as the site receives the | |
1233 | ReleaseClone, and clears all flags after all sites successfully receive it.</para> | |
1234 | </listitem> | |
1235 | </itemizedlist></para> | |
1236 | ||
1237 | <para>To override the default behavior, forcing the Volume Server to create and release a new ReleaseClone to the read-only | |
1238 | sites, include the <emphasis role="bold">-f</emphasis> flag. This is appropriate if, for example, the data at the read/write | |
1239 | site has changed since the existing ReleaseClone was created during the previous release operation.</para> | |
1240 | ||
1241 | <sect2 id="HDRWQ193"> | |
1242 | <title>Using Read-only Volumes Effectively</title> | |
1243 | ||
1244 | <indexterm> | |
1245 | <primary>criteria for replicating volumes</primary> | |
1246 | </indexterm> | |
1247 | ||
1248 | <indexterm> | |
1249 | <primary>replication</primary> | |
1250 | ||
1251 | <secondary>suitable types of volumes</secondary> | |
1252 | </indexterm> | |
1253 | ||
1254 | <indexterm> | |
1255 | <primary>suitability of volumes for replication</primary> | |
1256 | </indexterm> | |
1257 | ||
1258 | <indexterm> | |
1259 | <primary>read/write volume</primary> | |
1260 | ||
1261 | <secondary>types suitable for replication</secondary> | |
1262 | </indexterm> | |
1263 | ||
1264 | <para>For maximum effectiveness, replicate only volumes that satisfy two criteria: <itemizedlist> | |
1265 | <listitem> | |
1266 | <para>The volume's contents are heavily used. Examples include a volume housing binary files for text editors or other | |
1267 | popular application programs, and volumes mounted along heavily traversed directory paths such as the paths leading to | |
1268 | user home directories. It is an inefficient use of disk space to replicate volumes for which the demand is low enough | |
1269 | that a single File Server can easily service all requests.</para> | |
1270 | </listitem> | |
1271 | ||
1272 | <listitem> | |
1273 | <para>The volume's contents change infrequently. As noted, file system consistency demands that the contents of | |
1274 | read-only volumes must match each other and their read/write source at all times. Each time the read/write volume | |
1275 | changes, you must issue the <emphasis role="bold">vos release</emphasis> command to update the read-only volumes. This | |
1276 | can become tedious (and easy to forget) if the read/write volume changes frequently.</para> | |
1277 | </listitem> | |
1278 | </itemizedlist></para> | |
1279 | ||
1280 | <indexterm> | |
1281 | <primary>mounting</primary> | |
1282 | ||
1283 | <secondary>read-only volume</secondary> | |
1284 | </indexterm> | |
1285 | ||
1286 | <indexterm> | |
1287 | <primary>read-only volume</primary> | |
1288 | ||
1289 | <secondary>mounting</secondary> | |
1290 | </indexterm> | |
1291 | ||
1292 | <para>Explicitly mounting a read-only volume (creating a mount point that names a volume with a <emphasis | |
1293 | role="bold">.readonly</emphasis> extension) is not generally necessary or appropriate. The Cache Manager has a built-in bias | |
1294 | to access the read-only version of a replicated volume whenever possible. As described in more detail in <link | |
1295 | linkend="HDRWQ209">The Rules of Mount Point Traversal</link>, when the Cache Manager encounters a mount point it reads the | |
1296 | volume name inside it and contacts the VL Server for a list of the sites that house the volume. In the normal case, if the | |
1297 | mount point resides in a read-only volume and names a read/write volume (one that does not have a <emphasis | |
1298 | role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension), the Cache Manager always attempts to | |
1299 | access a read-only copy of the volume. Thus there is normally no reason to force the Cache Manager to access a read-only | |
1300 | volume by mounting it explicitly.</para> | |
1301 | ||
1302 | <para>It is a good practice to place a read-only volume at the read/write site, for a couple of reasons. First, the read-only | |
1303 | volume at the read/write site requires only a small amount of disk space, because it is a clone rather a copy of all of the | |
1304 | data (see <link linkend="HDRWQ190">About Clones and Cloning</link>). Only if a large number of files are removed or changed in | |
1305 | the read/write volume does the read-only copy occupy much disk space. That normally does not happen because the appropriate | |
1306 | response to changes in a replicated read/write volume is to reclone it. The other reason to place a read-only volume at the | |
1307 | read/write site is that the Cache Manager does not attempt to access the read/write version of a replicated volume if all | |
1308 | read-only copies become inaccessible. If the file server machine housing the read/write volume is the only accessible machine, | |
1309 | the Cache Manager can access the data only if there is a read-only copy at the read/write site.</para> | |
1310 | ||
1311 | <para>The number of read-only sites to define depends on several factors. Perhaps the main trade-off is between the level of | |
1312 | demand for the volume's contents and how much disk space you are willing to use for multiple copies of the volume. Of course, | |
1313 | each prospective read-only site must have enough available space to accommodate the volume. The limit on the number of | |
1314 | read-only copies of a volume is determined by the maximum number of site definitions in a volume's VLDB entry, which is | |
1315 | defined in the <emphasis> OpenAFS Release Notes</emphasis>. The site housing the read/write and backup versions of the volume | |
1316 | counts as one site, and each read-only site counts as an additional site (even the read-only site defined on the same file | |
1317 | server machine and partition as the read/write site counts as a separate site). Note also that the Volume Server permits only | |
1318 | one read-only copy of a volume per file server machine.</para> | |
1319 | </sect2> | |
1320 | ||
1321 | <sect2 id="Header_216"> | |
1322 | <title>Replication Scenarios</title> | |
1323 | ||
1324 | <indexterm> | |
1325 | <primary>variations possible</primary> | |
1326 | ||
1327 | <secondary>in replication</secondary> | |
1328 | </indexterm> | |
1329 | ||
1330 | <indexterm> | |
1331 | <primary>replication</primary> | |
1332 | ||
1333 | <secondary>variations possible in</secondary> | |
1334 | </indexterm> | |
1335 | ||
1336 | <indexterm> | |
1337 | <primary>possible variations</primary> | |
1338 | ||
1339 | <secondary>on replication</secondary> | |
1340 | </indexterm> | |
1341 | ||
1342 | <para>The instructions in the following section explain how to replicate a volume for which no read-only sites are currently | |
1343 | defined. However, you can also use the instructions in other common situations: <itemizedlist> | |
1344 | <listitem> | |
1345 | <para>If you are releasing a new clone to sites that already exist, you can skip Step <link linkend="LIWQ196">2</link>. | |
1346 | It can still be useful to issue the <emphasis role="bold">vos examine</emphasis> command, however, to verify that the | |
1347 | desired read-only sites are defined.</para> | |
1348 | </listitem> | |
1349 | ||
1350 | <listitem> | |
1351 | <para>If you are adding new read-only sites to existing ones, perform all of the steps. In Step <link | |
1352 | linkend="LIWQ197">3</link>, issue the <emphasis role="bold">vos addsite</emphasis> command for the new sites | |
1353 | only.</para> | |
1354 | </listitem> | |
1355 | ||
1356 | <listitem> | |
1357 | <para>If you are defining sites but do not want to release a clone to them yet, stop after Step <link | |
1358 | linkend="LIWQ197">3</link>and continue when you are ready.</para> | |
1359 | </listitem> | |
1360 | ||
1361 | <listitem> | |
1362 | <para>If you are removing one or more sites before releasing a new clone to the remaining sites, follow the instructions | |
1363 | for site removal in <link linkend="HDRWQ235">Removing Volumes and their Mount Points</link>and then start with Step | |
1364 | <link linkend="LIWQ198">4</link>.</para> | |
1365 | </listitem> | |
1366 | </itemizedlist></para> | |
1367 | </sect2> | |
1368 | ||
1369 | <sect2 id="HDRWQ194"> | |
1370 | <title>To replicate a read/write volume (create a read-only volume)</title> | |
1371 | ||
1372 | <indexterm> | |
1373 | <primary>read-only volume</primary> | |
1374 | ||
1375 | <secondary>creating</secondary> | |
1376 | ||
1377 | <tertiary>instructions</tertiary> | |
1378 | </indexterm> | |
1379 | ||
1380 | <indexterm> | |
1381 | <primary>read/write volume</primary> | |
1382 | ||
1383 | <secondary>replication instructions</secondary> | |
1384 | </indexterm> | |
1385 | ||
1386 | <orderedlist> | |
1387 | <listitem id="LIWQ195"> | |
1388 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> | |
1389 | file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link | |
1390 | linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting> | |
1391 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
1392 | </programlisting></para> | |
1393 | </listitem> | |
1394 | ||
1395 | <listitem id="LIWQ196"> | |
1396 | <para>Select one or more sites at which to replicate the volume. There are several factors to | |
1397 | consider: <itemizedlist> | |
1398 | <listitem> | |
1399 | <para>How many sites are already defined. As previously noted, it is usually appropriate to define a read-only site | |
1400 | at the read/write site. Also, the Volume Server permits only one read-only copy of a volume per file server machine. | |
1401 | To display the volume's current sites, issue the <emphasis role="bold">vos examine</emphasis> command, which is | |
1402 | described fully in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>. | |
1403 | <programlisting> | |
1404 | % <emphasis role="bold">vos examine</emphasis> <<replaceable>volume name or ID</replaceable>> | |
1405 | </programlisting></para> | |
1406 | ||
1407 | <para>The final lines of output display the volume's site definitions from the VLDB.</para> | |
1408 | </listitem> | |
1409 | ||
1410 | <listitem> | |
1411 | <para>Whether your cell dedicates any file server machines to housing read-only volumes only. In general, only very | |
1412 | large cells use read-only server machines.</para> | |
1413 | </listitem> | |
1414 | ||
1415 | <listitem> | |
1416 | <para>Whether a site has enough free space to accommodate the volume. A read-only volume requires the same amount of | |
1417 | space as the read/write version (unless it is at the read/write site itself). The first line of output from the | |
1418 | <emphasis role="bold">vos examine</emphasis> command displays the read/write volume's current size in kilobyte | |
1419 | blocks, as shown in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>.</para> | |
1420 | ||
1421 | <para>To display the amount of space available on a file server machine's partitions, use the <emphasis | |
1422 | role="bold">vos partinfo</emphasis> command, which is described fully in <link linkend="HDRWQ185">Creating | |
1423 | Read/write Volumes</link>.</para> | |
1424 | ||
1425 | <programlisting> | |
1426 | % <emphasis role="bold">vos partinfo</emphasis> <<replaceable>machine name</replaceable>> [<<replaceable>partition name</replaceable>>] | |
1427 | </programlisting> | |
1428 | </listitem> | |
1429 | </itemizedlist></para> | |
1430 | ||
1431 | <indexterm> | |
1432 | <primary>read-only volume</primary> | |
1433 | ||
1434 | <secondary>defining site for in VLDB</secondary> | |
1435 | </indexterm> | |
1436 | ||
1437 | <indexterm> | |
1438 | <primary>defining</primary> | |
1439 | ||
1440 | <secondary>read-only site in VLDB</secondary> | |
1441 | </indexterm> | |
1442 | ||
1443 | <indexterm> | |
1444 | <primary>adding</primary> | |
1445 | ||
1446 | <secondary>read-only site definition in VLDB</secondary> | |
1447 | </indexterm> | |
1448 | ||
1449 | <indexterm> | |
1450 | <primary>VLDB</primary> | |
1451 | ||
1452 | <secondary>defining read-only site in</secondary> | |
1453 | </indexterm> | |
1454 | ||
1455 | <indexterm> | |
1456 | <primary>commands</primary> | |
1457 | ||
1458 | <secondary>vos addsite</secondary> | |
1459 | </indexterm> | |
1460 | ||
1461 | <indexterm> | |
1462 | <primary>vos commands</primary> | |
1463 | ||
1464 | <secondary>addsite</secondary> | |
1465 | </indexterm> | |
1466 | </listitem> | |
1467 | ||
1468 | <listitem id="LIWQ197"> | |
1469 | <para>Issue the <emphasis role="bold">vos addsite</emphasis> command to define each new read-only | |
1470 | site in the VLDB. <programlisting> | |
1471 | % <emphasis role="bold">vos addsite</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <<replaceable>volume name or ID</replaceable>> | |
1472 | </programlisting></para> | |
1473 | ||
1474 | <para>where <variablelist> | |
1475 | <varlistentry> | |
1476 | <term><emphasis role="bold">ad</emphasis></term> | |
1477 | ||
1478 | <listitem> | |
1479 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">addsite</emphasis>.</para> | |
1480 | </listitem> | |
1481 | </varlistentry> | |
1482 | ||
1483 | <varlistentry> | |
1484 | <term><emphasis role="bold">machine name</emphasis></term> | |
1485 | ||
1486 | <listitem> | |
1487 | <para>Defines the file server machine for the new site.</para> | |
1488 | </listitem> | |
1489 | </varlistentry> | |
1490 | ||
1491 | <varlistentry> | |
1492 | <term><emphasis role="bold">partition name</emphasis></term> | |
1493 | ||
1494 | <listitem> | |
1495 | <para>Names a disk partition on the machine machine name.</para> | |
1496 | </listitem> | |
1497 | </varlistentry> | |
1498 | ||
1499 | <varlistentry> | |
1500 | <term><emphasis role="bold">volume name or ID</emphasis></term> | |
1501 | ||
1502 | <listitem> | |
1503 | <para>Identifies the read/write volume to be replicated, either by its complete name or its volume ID | |
1504 | number.</para> | |
1505 | </listitem> | |
1506 | </varlistentry> | |
1507 | </variablelist></para> | |
1508 | </listitem> | |
1509 | ||
1510 | <listitem id="LIWQ198"> | |
1511 | <para><emphasis role="bold">(Optional)</emphasis> Verify that the <emphasis | |
1512 | role="bold">fs</emphasis> process (which incorporates the Volume Server) is functioning normally on each file server | |
1513 | machine where you have defined a read-only site, and that the <emphasis role="bold">vlserver</emphasis> process (the | |
1514 | Volume Location Server) is functioning correctly on each database server machine. Knowing that they are functioning | |
1515 | eliminates two possible sources of failure for the release. Issue the <emphasis role="bold">bos status</emphasis> command | |
1516 | on each file server machine housing a read-only site for this volume and on each database server machine. The command is | |
1517 | described fully in <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>. | |
1518 | <programlisting> | |
1519 | % <emphasis role="bold">bos status</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">fs vlserver</emphasis> | |
1520 | </programlisting></para> | |
1521 | ||
1522 | <indexterm> | |
1523 | <primary>releasing</primary> | |
1524 | ||
1525 | <secondary>read-only volume</secondary> | |
1526 | </indexterm> | |
1527 | ||
1528 | <indexterm> | |
1529 | <primary>read-only volume</primary> | |
1530 | ||
1531 | <secondary>releasing</secondary> | |
1532 | </indexterm> | |
1533 | ||
1534 | <indexterm> | |
1535 | <primary>commands</primary> | |
1536 | ||
1537 | <secondary>vos release</secondary> | |
1538 | ||
1539 | <tertiary>basic instructions</tertiary> | |
1540 | </indexterm> | |
1541 | ||
1542 | <indexterm> | |
1543 | <primary>vos commands</primary> | |
1544 | ||
1545 | <secondary>release</secondary> | |
1546 | ||
1547 | <tertiary>basic instructions</tertiary> | |
1548 | </indexterm> | |
1549 | </listitem> | |
1550 | ||
1551 | <listitem id="LIWQ199"> | |
1552 | <para>Issue the <emphasis role="bold">vos release</emphasis> command to clone the read/write source | |
1553 | volume and distribute the clone to each read-only site. <programlisting> | |
1554 | % <emphasis role="bold">vos release</emphasis> <<replaceable>volume name or ID</replaceable>> [<emphasis role="bold">-f</emphasis>] | |
1555 | </programlisting></para> | |
1556 | ||
1557 | <para>where <variablelist> | |
1558 | <varlistentry> | |
1559 | <term><emphasis role="bold">rel</emphasis></term> | |
1560 | ||
1561 | <listitem> | |
1562 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">release</emphasis>.</para> | |
1563 | </listitem> | |
1564 | </varlistentry> | |
1565 | ||
1566 | <varlistentry> | |
1567 | <term><emphasis role="bold">volume name or ID</emphasis></term> | |
1568 | ||
1569 | <listitem> | |
1570 | <para>Identifies the read/write volume to clone, either by its complete name or volume ID number. The read-only | |
1571 | version is given the same name with a <emphasis role="bold">.readonly</emphasis> extension. All read-only copies | |
1572 | share the same read-only volume ID number.</para> | |
1573 | </listitem> | |
1574 | </varlistentry> | |
1575 | ||
1576 | <varlistentry> | |
1577 | <term><emphasis role="bold">-f</emphasis></term> | |
1578 | ||
1579 | <listitem> | |
1580 | <para>Creates and releases a brand new clone.</para> | |
1581 | </listitem> | |
1582 | </varlistentry> | |
1583 | </variablelist></para> | |
1584 | </listitem> | |
1585 | ||
1586 | <listitem id="LIWQ200"> | |
1587 | <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">vos examine</emphasis> command to verify | |
1588 | that no site definition in the VLDB entry is marked with an <computeroutput>Old release</computeroutput> or | |
1589 | <computeroutput>New release</computeroutput> flag. The command is described fully in <link linkend="HDRWQ221">Displaying | |
1590 | One Volume's VLDB Entry and Volume Header</link>. <programlisting> | |
1591 | % <emphasis role="bold">vos examine</emphasis> <<replaceable>volume name or ID</replaceable>> | |
1592 | </programlisting></para> | |
1593 | </listitem> | |
1594 | </orderedlist> | |
1595 | ||
1596 | <para>If any flags appear in the output from Step <link linkend="LIWQ200">6</link>, repeat Steps <link | |
1597 | linkend="LIWQ198">4</link>and <link linkend="LIWQ199">5</link>until the Volume Server does not produce any error messages | |
1598 | during the release operation and the flags no longer appear. Do not issue the <emphasis role="bold">vos release</emphasis> | |
1599 | command when you know that the read/write site or any read-only site is inaccessible due to network, machine or server process | |
1600 | outage.</para> | |
1601 | </sect2> | |
1602 | </sect1> | |
1603 | ||
1604 | <sect1 id="HDRWQ201"> | |
1605 | <title>Creating Backup Volumes</title> | |
1606 | ||
1607 | <indexterm> | |
1608 | <primary>read/write volume</primary> | |
1609 | ||
1610 | <secondary>cloning</secondary> | |
1611 | ||
1612 | <tertiary>for backup version</tertiary> | |
1613 | </indexterm> | |
1614 | ||
1615 | <indexterm> | |
1616 | <primary>cloning</primary> | |
1617 | ||
1618 | <secondary>for backup</secondary> | |
1619 | </indexterm> | |
1620 | ||
1621 | <indexterm> | |
1622 | <primary>creating</primary> | |
1623 | ||
1624 | <secondary>backup volume</secondary> | |
1625 | </indexterm> | |
1626 | ||
1627 | <indexterm> | |
1628 | <primary>volume</primary> | |
1629 | ||
1630 | <secondary>backup</secondary> | |
1631 | ||
1632 | <see>backup volume</see> | |
1633 | </indexterm> | |
1634 | ||
1635 | <indexterm> | |
1636 | <primary>backup volume</primary> | |
1637 | ||
1638 | <secondary>creating</secondary> | |
1639 | </indexterm> | |
1640 | ||
1641 | <para>A <emphasis>backup volume</emphasis> is a clone that resides at the same site as its read/write source (to review the | |
1642 | concept of cloning, see <link linkend="HDRWQ190">About Clones and Cloning</link>). Creating a backup version of a volume has two | |
1643 | purposes: <itemizedlist> | |
1644 | <listitem> | |
1645 | <para>It is by convention the first step when dumping a volume's contents to tape with the AFS Backup System. A volume is | |
1646 | inaccessible while it is being dumped, so instead of dumping the read/write volume, you create and dump a backup version. | |
1647 | Users do not normally access the backup version, so it is unlikely that the dump will disturb them. For more details, see | |
1648 | <link linkend="HDRWQ296">Backing Up Data</link>.</para> | |
1649 | </listitem> | |
1650 | ||
1651 | <listitem> | |
1652 | <para>It enables users to restore mistakenly deleted or changed data themselves, freeing you for more crucial tasks. The | |
1653 | backup version captures the state of its read/write source at the time the backup is made, and its contents cannot change. | |
1654 | Mount the backup version in the filespace so that users can restore a file to its state at the time you made the backup. | |
1655 | See <link linkend="HDRWQ204">Making the Contents of Backup Volumes Available to Users</link>.</para> | |
1656 | </listitem> | |
1657 | </itemizedlist></para> | |
1658 | ||
1659 | <indexterm> | |
1660 | <primary>creating</primary> | |
1661 | ||
1662 | <secondary>multiple backup volumes at once</secondary> | |
1663 | </indexterm> | |
1664 | ||
1665 | <indexterm> | |
1666 | <primary>volume</primary> | |
1667 | ||
1668 | <secondary>creating backup version of many at once</secondary> | |
1669 | </indexterm> | |
1670 | ||
1671 | <indexterm> | |
1672 | <primary>backup volume</primary> | |
1673 | ||
1674 | <secondary>creating multiple at once</secondary> | |
1675 | </indexterm> | |
1676 | ||
1677 | <sect2 id="HDRWQ202"> | |
1678 | <title>Backing Up Multiple Volumes at Once</title> | |
1679 | ||
1680 | <para>The <emphasis role="bold">vos backupsys</emphasis> command creates a backup version of many read/write volumes at once. | |
1681 | This command is useful when preparing for large-scale backups to tape using the AFS Backup System.</para> | |
1682 | ||
1683 | <para>To clone every read/write volume listed in the VLDB, omit all of the command's options. Otherwise, combine the command's | |
1684 | options to clone various groups of volumes. The options use one of two basic criteria to select volumes: location (the | |
1685 | <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments) or presence in the volume | |
1686 | name of one of a set of specified character strings (the <emphasis role="bold">-prefix</emphasis>, <emphasis | |
1687 | role="bold">-exclude</emphasis>, and <emphasis role="bold">-xprefix</emphasis> options).</para> | |
1688 | ||
1689 | <para>To clone only volumes that reside on one file server machine, include the <emphasis role="bold">-server</emphasis> | |
1690 | argument. To clone only volumes that reside on one partition, combine the <emphasis role="bold">-server</emphasis> and | |
1691 | <emphasis role="bold">-partition</emphasis> arguments. The <emphasis role="bold">-partition</emphasis> argument can also be | |
1692 | used alone to clone volumes that reside on the indicated partition on every file server machine. These arguments can be | |
1693 | combined with those that select volumes based on their names.</para> | |
1694 | ||
1695 | <para>Combine the <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-exclude</emphasis>, and <emphasis | |
1696 | role="bold">-xprefix</emphasis> options (with or without the <emphasis role="bold">-server</emphasis> and <emphasis | |
1697 | role="bold">-partition</emphasis> arguments) in the indicated ways to select volumes based on character strings contained in | |
1698 | their names: <itemizedlist> | |
1699 | <listitem> | |
1700 | <para>To clone every read/write volume at the specified location whose name includes one of a set of specified character | |
1701 | strings (for example, begins with <emphasis role="bold">user.</emphasis> or includes the string <emphasis | |
1702 | role="bold">afs</emphasis>), use the <emphasis role="bold">-prefix</emphasis> argument or combine the <emphasis | |
1703 | role="bold">-xprefix</emphasis> and <emphasis role="bold">-exclude</emphasis> options.</para> | |
1704 | </listitem> | |
1705 | ||
1706 | <listitem> | |
1707 | <para>To clone every read/write volume at the specified location except those whose name includes one of a set of | |
1708 | specified character strings, use the <emphasis role="bold">-xprefix</emphasis> argument or combine the <emphasis | |
1709 | role="bold">-prefix</emphasis> and <emphasis role="bold">-exclude</emphasis> options.</para> | |
1710 | </listitem> | |
1711 | ||
1712 | <listitem> | |
1713 | <para>To clone every read/write volume at the specified location whose name includes one of one of a set of specified | |
1714 | character strings, except those whose names include one of a different set of specified character strings, combine the | |
1715 | <emphasis role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments. The command creates a | |
1716 | list of all volumes that match the <emphasis role="bold">-prefix</emphasis> argument and then removes from the list the | |
1717 | volumes that match the <emphasis role="bold">-xprefix</emphasis> argument. For effective results, the strings specified | |
1718 | by the <emphasis role="bold">-xprefix</emphasis> argument must designate a subset of the volumes specified by the | |
1719 | <emphasis role="bold">-prefix</emphasis> argument.</para> | |
1720 | ||
1721 | <para>If the <emphasis role="bold">-exclude</emphasis> flag is combined with the <emphasis | |
1722 | role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments, the command creates a list of | |
1723 | all volumes that do not match the <emphasis role="bold">-prefix</emphasis> argument and then adds to the list any | |
1724 | volumes that match the <emphasis role="bold">-xprefix</emphasis> argument. As when the <emphasis | |
1725 | role="bold">-exclude</emphasis> flag is not used, the result is effective only if the strings specified by the <emphasis | |
1726 | role="bold">-xprefix</emphasis> argument designate a subset of the volumes specified by the <emphasis | |
1727 | role="bold">-prefix</emphasis> argument.</para> | |
1728 | </listitem> | |
1729 | </itemizedlist></para> | |
1730 | ||
1731 | <para>The <emphasis role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments both accept | |
1732 | multiple values, which can be used to define disjoint groups of volumes. Each value can be one of two types: <orderedlist> | |
1733 | <listitem> | |
1734 | <para>A simple character string, which matches volumes whose name begin with the string. All characters are interpreted | |
1735 | literally (that is, characters that potentially have special meaning to the command shell, such as the period, have only | |
1736 | their literal meaning).</para> | |
1737 | </listitem> | |
1738 | ||
1739 | <listitem> | |
1740 | <para>A regular expression, which matches volumes whose names contain the expressions. Place a caret ( <emphasis | |
1741 | role="bold">^</emphasis>) at the beginning of the expression, and enclose the entire string in single quotes ( <emphasis | |
1742 | role="bold">'</emphasis> <emphasis role="bold">'</emphasis>). Explaining regular expressions is outside the scope of | |
1743 | this reference page; see the UNIX manual page for <emphasis role="bold">regexp(5)</emphasis> or (for a brief | |
1744 | introduction) <link linkend="HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</link>. As an example, the | |
1745 | following expression matches volumes that have the string <emphasis role="bold">aix</emphasis> anywhere in their names: | |
1746 | <programlisting> | |
1747 | <emphasis role="bold">-prefix '^.*aix'</emphasis> | |
1748 | </programlisting></para> | |
1749 | </listitem> | |
1750 | </orderedlist></para> | |
1751 | ||
1752 | <para>To display a list of the volumes to be cloned, without actually cloning them, include the <emphasis | |
1753 | role="bold">-dryrun</emphasis> flag. To display a statement that summarizes the criteria being used to select volume, include | |
1754 | the <emphasis role="bold">-verbose</emphasis> flag.</para> | |
1755 | ||
1756 | <para>To back up a single volume, use the <emphasis role="bold">vos backup</emphasis> command, which employs a more | |
1757 | streamlined technique for finding a single volume.</para> | |
1758 | ||
1759 | <indexterm> | |
1760 | <primary>automating</primary> | |
1761 | ||
1762 | <secondary>creation of backup volumes</secondary> | |
1763 | </indexterm> | |
1764 | ||
1765 | <indexterm> | |
1766 | <primary>backup volume</primary> | |
1767 | ||
1768 | <secondary>automating creation of</secondary> | |
1769 | </indexterm> | |
1770 | ||
1771 | <indexterm> | |
1772 | <primary>volume</primary> | |
1773 | ||
1774 | <secondary>automating creation of backup version</secondary> | |
1775 | </indexterm> | |
1776 | ||
1777 | <indexterm> | |
1778 | <primary>backup volume</primary> | |
1779 | ||
1780 | <secondary>suggested schedule for creation of</secondary> | |
1781 | </indexterm> | |
1782 | ||
1783 | <indexterm> | |
1784 | <primary>scheduling</primary> | |
1785 | ||
1786 | <secondary>creation of backup volumes</secondary> | |
1787 | </indexterm> | |
1788 | ||
1789 | <indexterm> | |
1790 | <primary>cron-type server process</primary> | |
1791 | ||
1792 | <secondary>used to automate volume backup</secondary> | |
1793 | </indexterm> | |
1794 | </sect2> | |
1795 | ||
1796 | <sect2 id="HDRWQ203"> | |
1797 | <title>Automating Creation of Backup Volumes</title> | |
1798 | ||
1799 | <para>Most cells find that it is best to make a new backup version of relevant volumes each day. It is best to create the | |
1800 | backup versions at a time when usage is low, because the backup operation causes the read/write volume to be unavailable | |
1801 | momentarily.</para> | |
1802 | ||
1803 | <para>You can either issue the necessary the <emphasis role="bold">vos backupsys</emphasis> or <emphasis role="bold">vos | |
1804 | backup</emphasis> commands at the console or create a <emphasis role="bold">cron</emphasis> entry in the <emphasis | |
1805 | role="bold">BosConfig</emphasis> file on a file server machine, which eliminates the need for an administrator to initiate the | |
1806 | backup operation.</para> | |
1807 | ||
1808 | <para>The following example command creates a <emphasis role="bold">cron</emphasis> process called <emphasis | |
1809 | role="bold">backupusers</emphasis> in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file on the machine | |
1810 | <emphasis role="bold">fs3.example.com</emphasis>. The process runs every day at 1:00 a.m. to create a backup version of every | |
1811 | volume in the cell whose name starts with the string <emphasis role="bold">user</emphasis>. The <emphasis | |
1812 | role="bold">-localauth</emphasis> flag enables the process to invoke the privileged <emphasis role="bold">vos | |
1813 | backupsys</emphasis> command while unauthenticated. Note that the <emphasis role="bold">-cmd</emphasis> argument specifies a | |
1814 | complete pathname for the <emphasis role="bold">vos</emphasis> binary, because the PATH environment variable for the BOS | |
1815 | Server (running as the local superuser <emphasis role="bold">root</emphasis>) generally does not include the path to AFS | |
1816 | binaries. <programlisting> | |
1817 | % <emphasis role="bold">bos create fs3.example.com backupusers cron</emphasis>\ | |
1818 | <emphasis role="bold">-cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" "1:00"</emphasis> | |
1819 | </programlisting></para> | |
1820 | ||
1821 | <indexterm> | |
1822 | <primary>mounting</primary> | |
1823 | ||
1824 | <secondary>backup volume</secondary> | |
1825 | </indexterm> | |
1826 | ||
1827 | <indexterm> | |
1828 | <primary>backup volume</primary> | |
1829 | ||
1830 | <secondary>mounting</secondary> | |
1831 | </indexterm> | |
1832 | ||
1833 | <indexterm> | |
1834 | <primary>OldFiles directory</primary> | |
1835 | ||
1836 | <secondary>as mount point for backup volume</secondary> | |
1837 | </indexterm> | |
1838 | </sect2> | |
1839 | ||
1840 | <sect2 id="HDRWQ204"> | |
1841 | <title>Making the Contents of Backup Volumes Available to Users</title> | |
1842 | ||
1843 | <para>As noted, a backup volume preserves the state of the read/write source at the time the backup is created. Many cells | |
1844 | choose to mount backup volumes so that users can access and restore data they have accidentally deleted or changed since the | |
1845 | last backup was made, without having to request help from administrators. The most sensible place to mount the backup version | |
1846 | of a user volume is at a subdirectory of the user's home directory. Suitable names for this directory include <emphasis | |
1847 | role="bold">OldFiles</emphasis> and <emphasis role="bold">Backup</emphasis>. The subdirectory looks just like the user's own | |
1848 | home directory as it was at the time the backup was created, with all files and subdirectories in the same relative | |
1849 | positions.</para> | |
1850 | ||
1851 | <para>If you do create and mount backup volumes for your users, inform users of their existence. The <emphasis> OpenAFS User | |
1852 | Guide</emphasis> does not mention backup volumes because making them available to users is optional. Explain to users how | |
1853 | often you make a new backup, so they know what they can recover. Remind them also that the data in their backup volume cannot | |
1854 | change; however, they can use the standard UNIX <emphasis role="bold">cp</emphasis> command to copy it into their home volume | |
1855 | and modify it there. Reassure users that the data in their backup volumes does not count against their read/write volume | |
1856 | quota.</para> | |
1857 | </sect2> | |
1858 | ||
1859 | <sect2 id="HDRWQ205"> | |
1860 | <title>To create and mount a backup volume</title> | |
1861 | ||
1862 | <orderedlist> | |
1863 | <listitem> | |
1864 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
1865 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
1866 | display the users in the UserList file</link>. <programlisting> | |
1867 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
1868 | </programlisting></para> | |
1869 | </listitem> | |
1870 | ||
1871 | <listitem> | |
1872 | <para>Verify that you have the <emphasis role="bold">insert</emphasis>( <emphasis role="bold">i</emphasis>) and <emphasis | |
1873 | role="bold">administer</emphasis>( <emphasis role="bold">a</emphasis>) permissions on the ACL of the directory in which | |
1874 | you wish to mount the volume. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully | |
1875 | described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
1876 | % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
1877 | </programlisting></para> | |
1878 | ||
1879 | <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis | |
1880 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis | |
1881 | role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis | |
1882 | role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para> | |
1883 | ||
1884 | <indexterm> | |
1885 | <primary>commands</primary> | |
1886 | ||
1887 | <secondary>vos backup</secondary> | |
1888 | </indexterm> | |
1889 | ||
1890 | <indexterm> | |
1891 | <primary>vos commands</primary> | |
1892 | ||
1893 | <secondary>backup</secondary> | |
1894 | </indexterm> | |
1895 | </listitem> | |
1896 | ||
1897 | <listitem id="LIWQ206"> | |
1898 | <para>Issue the <emphasis role="bold">vos backup</emphasis> command to create a backup version of a | |
1899 | read/write source volume. The message shown confirms the success of the backup operation. <programlisting> | |
1900 | % <emphasis role="bold">vos backup</emphasis> <<replaceable>volume name or ID</replaceable>> Created backup volume for volume name or ID | |
1901 | </programlisting></para> | |
1902 | ||
1903 | <para>where <variablelist> | |
1904 | <varlistentry> | |
1905 | <term><emphasis role="bold">backup</emphasis></term> | |
1906 | ||
1907 | <listitem> | |
1908 | <para>Must be typed in full.</para> | |
1909 | </listitem> | |
1910 | </varlistentry> | |
1911 | ||
1912 | <varlistentry> | |
1913 | <term><emphasis role="bold">volume name or ID</emphasis></term> | |
1914 | ||
1915 | <listitem> | |
1916 | <para>Identifies the read/write volume to back up, either by its complete name or volume ID number. The backup | |
1917 | volume has the same name with the addition of the <emphasis role="bold">.backup</emphasis> extension. It has its | |
1918 | own volume ID number.</para> | |
1919 | </listitem> | |
1920 | </varlistentry> | |
1921 | </variablelist></para> | |
1922 | ||
1923 | <indexterm> | |
1924 | <primary>commands</primary> | |
1925 | ||
1926 | <secondary>fs mkmount</secondary> | |
1927 | ||
1928 | <tertiary>when mounting backup volume</tertiary> | |
1929 | </indexterm> | |
1930 | ||
1931 | <indexterm> | |
1932 | <primary>fs commands</primary> | |
1933 | ||
1934 | <secondary>mkmount</secondary> | |
1935 | ||
1936 | <tertiary>when mounting backup volume</tertiary> | |
1937 | </indexterm> | |
1938 | </listitem> | |
1939 | ||
1940 | <listitem id="LIWQ207"> | |
1941 | <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs | |
1942 | mkmount</emphasis> to mount the backup volume. While this step is optional, Cache Managers cannot access the volume's | |
1943 | contents if it is not mounted. <programlisting> | |
1944 | % <emphasis role="bold">fs mkmount</emphasis> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>> <emphasis | |
1945 | role="bold">.backup</emphasis> | |
1946 | </programlisting></para> | |
1947 | ||
1948 | <para>where <variablelist> | |
1949 | <varlistentry> | |
1950 | <term><emphasis role="bold">mk</emphasis></term> | |
1951 | ||
1952 | <listitem> | |
1953 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">mkmount</emphasis>.</para> | |
1954 | </listitem> | |
1955 | </varlistentry> | |
1956 | ||
1957 | <varlistentry> | |
1958 | <term><emphasis role="bold">directory</emphasis></term> | |
1959 | ||
1960 | <listitem> | |
1961 | <para>Names the mount point to create. Do not create a file or directory of the same name beforehand. Partial | |
1962 | pathnames are interpreted relative to the current working directory. For the backup version of a user volume, the | |
1963 | conventional location is the user's home directory.</para> | |
1964 | </listitem> | |
1965 | </varlistentry> | |
1966 | ||
1967 | <varlistentry> | |
1968 | <term><emphasis role="bold">volume name</emphasis>.backup</term> | |
1969 | ||
1970 | <listitem> | |
1971 | <para>Is the full name of the backup volume.</para> | |
1972 | </listitem> | |
1973 | </varlistentry> | |
1974 | </variablelist></para> | |
1975 | </listitem> | |
1976 | ||
1977 | <listitem> | |
1978 | <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs lsmount</emphasis> command to verify | |
1979 | that the mount point refers to the correct volume. Complete instructions appear in <link linkend="HDRWQ211">To display a | |
1980 | mount point</link>. <programlisting> | |
1981 | % <emphasis role="bold">fs lsmount</emphasis> <<replaceable>directory</replaceable>> | |
1982 | </programlisting></para> | |
1983 | </listitem> | |
1984 | </orderedlist> | |
1985 | ||
1986 | <indexterm> | |
1987 | <primary>commands</primary> | |
1988 | ||
1989 | <secondary>vos backupsys</secondary> | |
1990 | </indexterm> | |
1991 | ||
1992 | <indexterm> | |
1993 | <primary>vos commands</primary> | |
1994 | ||
1995 | <secondary>backupsys</secondary> | |
1996 | </indexterm> | |
1997 | </sect2> | |
1998 | ||
1999 | <sect2 id="Header_223"> | |
2000 | <title>To create multiple backup volumes at once</title> | |
2001 | ||
2002 | <orderedlist> | |
2003 | <listitem> | |
2004 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
2005 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
2006 | display the users in the UserList file</link>. <programlisting> | |
2007 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
2008 | </programlisting></para> | |
2009 | </listitem> | |
2010 | ||
2011 | <listitem> | |
2012 | <para>Issue the <emphasis role="bold">vos backupsys</emphasis> command to create a backup version of every read/write | |
2013 | volume that shares the same prefix or site. The effects of combining the three arguments are described in <link | |
2014 | linkend="HDRWQ202">Backing Up Multiple Volumes at Once</link>. <programlisting> | |
2015 | % <emphasis role="bold">vos backupsys</emphasis> [<emphasis role="bold">-prefix</emphasis> <<replaceable>common prefix on volume(s)</replaceable>>+] \ | |
2016 | [<emphasis role="bold">-server</emphasis> <<replaceable>machine name</replaceable>>] [<emphasis role="bold">-partition</emphasis> <<replaceable>partition name</replaceable>>] \ | |
2017 | [<emphasis role="bold">-exclude</emphasis>] [<emphasis role="bold">-xprefix</emphasis> <<replaceable>negative prefix on volume(s)</replaceable>>+] \ | |
2018 | [<emphasis role="bold">-dryrun</emphasis>] [<emphasis role="bold">-verbose</emphasis>] | |
2019 | </programlisting></para> | |
2020 | ||
2021 | <para>where <variablelist> | |
2022 | <varlistentry> | |
2023 | <term><emphasis role="bold">backups</emphasis></term> | |
2024 | ||
2025 | <listitem> | |
2026 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">backupsys</emphasis>.</para> | |
2027 | </listitem> | |
2028 | </varlistentry> | |
2029 | ||
2030 | <varlistentry> | |
2031 | <term><emphasis role="bold">-prefix</emphasis></term> | |
2032 | ||
2033 | <listitem> | |
2034 | <para>Specifies one or more simple character strings or regular expressions of any length; a volume whose name | |
2035 | includes the string is placed on the list of volumes to be cloned. Include field separators (such as periods) if | |
2036 | appropriate. This argument can be combined with any combination of the <emphasis role="bold">-server</emphasis>, | |
2037 | <emphasis role="bold">-partition</emphasis>, <emphasis role="bold">-exclude</emphasis>, and <emphasis | |
2038 | role="bold">-xprefix</emphasis> options.</para> | |
2039 | </listitem> | |
2040 | </varlistentry> | |
2041 | ||
2042 | <varlistentry> | |
2043 | <term><emphasis role="bold">-server</emphasis></term> | |
2044 | ||
2045 | <listitem> | |
2046 | <para>Specifies the file server machine housing the volumes to backup. Can be combined with any combination of the | |
2047 | <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-partition</emphasis>, <emphasis | |
2048 | role="bold">-exclude</emphasis>, and <emphasis role="bold">-xprefix</emphasis> options.</para> | |
2049 | </listitem> | |
2050 | </varlistentry> | |
2051 | ||
2052 | <varlistentry> | |
2053 | <term><emphasis role="bold">-partition</emphasis></term> | |
2054 | ||
2055 | <listitem> | |
2056 | <para>Specifies the partition housing the volumes you wish to backup. Can be combined with any combination of the | |
2057 | <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-server</emphasis>, <emphasis | |
2058 | role="bold">-exclude</emphasis>, and <emphasis role="bold">-xprefix</emphasis> options.</para> | |
2059 | </listitem> | |
2060 | </varlistentry> | |
2061 | ||
2062 | <varlistentry> | |
2063 | <term><emphasis role="bold">-exclude</emphasis></term> | |
2064 | ||
2065 | <listitem> | |
2066 | <para>Indicates that all volumes except those indicated with the <emphasis role="bold">-prefix</emphasis> argument | |
2067 | are to be backed up. The <emphasis role="bold">-prefix</emphasis> argument must be provided along with this one. | |
2068 | Can also be combined with any combination of the <emphasis role="bold">-prefix</emphasis>, <emphasis | |
2069 | role="bold">-server</emphasis>, and <emphasis role="bold">-partition</emphasis> arguments; or with both the | |
2070 | <emphasis role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments, but not with the | |
2071 | <emphasis role="bold">-xprefix</emphasis> argument alone.</para> | |
2072 | </listitem> | |
2073 | </varlistentry> | |
2074 | ||
2075 | <varlistentry> | |
2076 | <term><emphasis role="bold">-xprefix</emphasis></term> | |
2077 | ||
2078 | <listitem> | |
2079 | <para>Specifies one or more simple character strings or regular expressions of any length; a volume whose name | |
2080 | does not include the string is placed on the list of volumes to be cloned. Can be combined with any combination of | |
2081 | the <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-server</emphasis>, and <emphasis | |
2082 | role="bold">-partition</emphasis> arguments; in addition, it can be combined with both the <emphasis | |
2083 | role="bold">-prefix</emphasis> and <emphasis role="bold">-exclude</emphasis> options, but not with the <emphasis | |
2084 | role="bold">-exclude</emphasis> flag alone.</para> | |
2085 | </listitem> | |
2086 | </varlistentry> | |
2087 | ||
2088 | <varlistentry> | |
2089 | <term><emphasis role="bold">-dryrun</emphasis></term> | |
2090 | ||
2091 | <listitem> | |
2092 | <para>Displays on the standard output stream a list of the volumes to be cloned, without actually cloning | |
2093 | them.</para> | |
2094 | </listitem> | |
2095 | </varlistentry> | |
2096 | ||
2097 | <varlistentry> | |
2098 | <term><emphasis role="bold">-verbose</emphasis></term> | |
2099 | ||
2100 | <listitem> | |
2101 | <para>Displays on the standard output stream a statement that summarizes the criteria being used to select | |
2102 | volumes, if combined with the <emphasis role="bold">-dryrun</emphasis> flag; otherwise, traces the cloning | |
2103 | operation for each volume.</para> | |
2104 | </listitem> | |
2105 | </varlistentry> | |
2106 | </variablelist></para> | |
2107 | </listitem> | |
2108 | </orderedlist> | |
2109 | </sect2> | |
2110 | </sect1> | |
2111 | ||
2112 | <sect1 id="HDRWQ208"> | |
2113 | <title>Mounting Volumes</title> | |
2114 | ||
2115 | <indexterm> | |
2116 | <primary>mounting</primary> | |
2117 | ||
2118 | <secondary>volume</secondary> | |
2119 | ||
2120 | <tertiary>general instructions</tertiary> | |
2121 | </indexterm> | |
2122 | ||
2123 | <para>Mount points make the contents of AFS volumes visible and accessible in the AFS filespace, as described in <link | |
2124 | linkend="HDRWQ183">About Mounting Volumes</link>. This section discusses in more detail how the Cache Manager handles mount | |
2125 | points as it traverses the filespace. It describes the three types of mount points, their purposes, and how to distinguish | |
2126 | between them, and provides instructions for creating, removing, and examining mount points.</para> | |
2127 | ||
2128 | <sect2 id="HDRWQ209"> | |
2129 | <title>The Rules of Mount Point Traversal</title> | |
2130 | ||
2131 | <para>The Cache Manager observes three basic rules as it traverses the AFS filespace and encounters mount points: | |
2132 | <itemizedlist> | |
2133 | <listitem> | |
2134 | <para><emphasis role="bold">Rule 1:</emphasis> Access Backup and Read-only Volumes When Specified</para> | |
2135 | ||
2136 | <para>When the Cache Manager encounters a mount point that specifies a volume with either a <emphasis | |
2137 | role="bold">.readonly</emphasis> or a <emphasis role="bold">.backup</emphasis> extension, it accesses that type of | |
2138 | volume only. If a mount point does not have either a <emphasis role="bold">.backup</emphasis> or <emphasis | |
2139 | role="bold">.readonly</emphasis> extension, the Cache Manager uses Rules 2 and 3.</para> | |
2140 | ||
2141 | <para>For example, the Cache Manager never accesses the read/write version of a volume if the mount point names the | |
2142 | backup version. If the specified version is inaccessible, the Cache Manager reports an error.</para> | |
2143 | </listitem> | |
2144 | ||
2145 | <listitem> | |
2146 | <para><emphasis role="bold">Rule 2:</emphasis> Follow the Read-only Path When Possible</para> | |
2147 | ||
2148 | <para>If a mount point resides in a read-only volume and the volume that it references is replicated, the Cache Manager | |
2149 | attempts to access a read-only copy of the volume; if the referenced volume is not replicated, the Cache Manager | |
2150 | accesses the read/write copy. The Cache Manager is thus said to prefer a <emphasis>read-only</emphasis> path through the | |
2151 | filespace, accessing read-only volumes when they are available.</para> | |
2152 | ||
2153 | <para>The Cache Manager starts on the read-only path in the first place because it always accesses a read-only copy of | |
2154 | the <emphasis role="bold">root.afs</emphasis> volume if it exists; the volume is mounted at the root of a cell's AFS | |
2155 | filespace (named <emphasis role="bold">/afs</emphasis> by convention). That is, if the <emphasis | |
2156 | role="bold">root.afs</emphasis> volume is replicated, the Cache Manager attempts to access a read-only copy of it rather | |
2157 | than the read/write copy. This rule then keeps the Cache Manager on a read-only path as long as each successive volume | |
2158 | is replicated. The implication is that both the <emphasis role="bold">root.afs</emphasis> and <emphasis | |
2159 | role="bold">root.cell</emphasis> volumes must be replicated for the Cache Manager to access replicated volumes mounted | |
2160 | below them in the AFS filespace. The volumes are conventionally mounted at the <emphasis role="bold">/afs</emphasis> and | |
2161 | <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable> directories, respectively.</para> | |
2162 | </listitem> | |
2163 | ||
2164 | <listitem> | |
2165 | <para><emphasis role="bold">Rule 3:</emphasis> Once on a Read/write Path, Stay There</para> | |
2166 | ||
2167 | <para>If a mount point resides in a read/write volume and the volume name does not have a <emphasis | |
2168 | role="bold">.readonly</emphasis> or a <emphasis role="bold">.backup</emphasis> extension, the Cache Manager attempts to | |
2169 | access only the a read/write version of the volume. The access attempt fails with an error if the read/write version is | |
2170 | inaccessible, even if a read-only version is accessible. In this situation the Cache Manager is said to be on a | |
2171 | <emphasis>read/write path</emphasis> and cannot switch back to the read-only path unless mount point explicitly names a | |
2172 | volume with a <emphasis role="bold">.readonly</emphasis> extension. (Cellular mount points are an important exception to | |
2173 | this rule, as explained in the following discussion.</para> | |
2174 | </listitem> | |
2175 | </itemizedlist></para> | |
2176 | </sect2> | |
2177 | ||
2178 | <sect2 id="HDRWQ210"> | |
2179 | <title>The Three Types of Mount Points</title> | |
2180 | ||
2181 | <para>AFS uses three types of mount points, each appropriate for a different purpose because of how the Cache Manager handles | |
2182 | them. <itemizedlist> | |
2183 | <listitem> | |
2184 | <para>When the Cache Manager crosses a <emphasis>regular</emphasis> mount point, it obeys all three of the mount point | |
2185 | traversal rules previously described.</para> | |
2186 | ||
2187 | <indexterm> | |
2188 | <primary>regular mount point</primary> | |
2189 | ||
2190 | <secondary></secondary> | |
2191 | ||
2192 | <see>mount point</see> | |
2193 | </indexterm> | |
2194 | ||
2195 | <indexterm> | |
2196 | <primary>mount point</primary> | |
2197 | ||
2198 | <secondary>regular</secondary> | |
2199 | ||
2200 | <tertiary>described</tertiary> | |
2201 | </indexterm> | |
2202 | ||
2203 | <para>AFS performs best when the vast majority of mount points in the filespace are regular, because the mount point | |
2204 | traversal rules promote the most efficient use of both replicated and nonreplicated volumes. Because there are likely to | |
2205 | be multiple read-only copies of a replicated volume, it makes sense for the Cache Manager to access one of them rather | |
2206 | than the single read/write version, and the second rule leads it to do so. If a volume is not replicated, the third rule | |
2207 | means that the Cache Manager still accesses the read/write volume when that is the only type available. In other words, | |
2208 | a regular mount point does not force the Cache Manager always to access read-only volumes (it is explicitly not a | |
2209 | "read-only mount point").</para> | |
2210 | ||
2211 | <para>To create a regular mount point, use the <emphasis role="bold">fs mkmount</emphasis> command as described in <link | |
2212 | linkend="HDRWQ212">To create a regular or read/write mount point</link>.</para> | |
2213 | ||
2214 | <note> | |
2215 | <para>To enable the Cache Manager to access the read-only version of a replicated volume named by a regular mount | |
2216 | point, all volumes that are mounted above it in the pathname must also be replicated. That is the only way the Cache | |
2217 | Manager can stay on a read-only path to the target volume.</para> | |
2218 | </note> | |
2219 | </listitem> | |
2220 | ||
2221 | <listitem> | |
2222 | <para>When the Cache Manager crosses a <emphasis>read/write</emphasis> mount point, it attempts to access only the | |
2223 | volume version named in the mount point. If the volume name is the base (read/write) form, without a <emphasis | |
2224 | role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension, the Cache Manager accesses the | |
2225 | read/write version of the volume, even if it is replicated. In other words, the Cache Manager disregards the second | |
2226 | mount point traversal rule when crossing a read/write mount point: it switches to the read/write path through the | |
2227 | filespace.</para> | |
2228 | ||
2229 | <indexterm> | |
2230 | <primary>read/write mount point</primary> | |
2231 | ||
2232 | <secondary></secondary> | |
2233 | ||
2234 | <see>mount point</see> | |
2235 | </indexterm> | |
2236 | ||
2237 | <indexterm> | |
2238 | <primary>mount point</primary> | |
2239 | ||
2240 | <secondary>read/write</secondary> | |
2241 | ||
2242 | <tertiary>described</tertiary> | |
2243 | </indexterm> | |
2244 | ||
2245 | <para>It is conventional to create only one read/write mount point in a cell's filespace, using it to mount the cell's | |
2246 | <emphasis role="bold">root.cell</emphasis> volume just below the AFS filespace root (by convention, <emphasis | |
2247 | role="bold">/afs/.</emphasis><replaceable>cellname</replaceable>). As indicated, it is conventional to place a period at | |
2248 | the start of the read/write mount point's name (for example, <emphasis role="bold">/afs/.example.com</emphasis>). The period | |
2249 | distinguishes the read/write mount point from the regular mount point for the <emphasis role="bold">root.cell</emphasis> | |
2250 | volume at the same level. This is the only case in which it is conventional to create two mount points for the same | |
2251 | volume. A desirable side effect of this naming convention for this read/write mount point is that it does not appear in | |
2252 | the output of the UNIX <emphasis role="bold">ls</emphasis> command unless the <emphasis role="bold">-a</emphasis> flag | |
2253 | is included, essentially hiding it from regular users who have no use for it.</para> | |
2254 | ||
2255 | <para>The existence of a single read/write mount point at this point in the filespace provides access to the read/write | |
2256 | version of every volume when necessary, because it puts the Cache Manager on a read/write path right at the top of the | |
2257 | filespace. At the same time, the regular mount point for the <emphasis role="bold">root.cell</emphasis> volume puts the | |
2258 | Cache Manager on a read-only path most of the time.</para> | |
2259 | ||
2260 | <para>Using a read/write mount point for a read-only or backup volume is acceptable, but unnecessary. The first rule of | |
2261 | mount point traversal already specifies that the Cache Manager accesses them if the volume name in a regular mount point | |
2262 | has a <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension.</para> | |
2263 | ||
2264 | <para>To create a read/write mount point, use the <emphasis role="bold">-rw</emphasis> flag on the <emphasis | |
2265 | role="bold">fs mkmount</emphasis> command as described in <link linkend="HDRWQ212">To create a regular or read/write | |
2266 | mount point</link>.</para> | |
2267 | </listitem> | |
2268 | ||
2269 | <listitem> | |
2270 | <para>When the Cache Manager crosses a <emphasis>cellular</emphasis> mount point, it accesses the indicated volume in | |
2271 | the specified cell, which is normally a foreign cell. (If the mount point does not name a cell along with the volume, | |
2272 | the Cache Manager accesses the volume in the cell where the mount point resides.) When crossing a regular cellular mount | |
2273 | point, the Cache Manager disregards the third mount point traversal rule. Instead, it accesses a read-only version of | |
2274 | the volume if it is replicated, even if the volume that houses the mount point is read/write.</para> | |
2275 | ||
2276 | <para>It is inappropriate to circumvent this behavior by creating a read/write cellular mount point, because traversing | |
2277 | the read/write path imposes an unfair load on the foreign cell's file server machines. The File Server must issue a | |
2278 | callback for each file fetched from the read/write volume, rather than single callback required for a read-only volume. | |
2279 | In any case, only a cell's own administrators generally need to access the read/write versions of replicated | |
2280 | volumes.</para> | |
2281 | ||
2282 | <indexterm> | |
2283 | <primary>cellular mount point</primary> | |
2284 | ||
2285 | <secondary></secondary> | |
2286 | ||
2287 | <see>mount point</see> | |
2288 | </indexterm> | |
2289 | ||
2290 | <indexterm> | |
2291 | <primary>mount point</primary> | |
2292 | ||
2293 | <secondary>cellular</secondary> | |
2294 | ||
2295 | <tertiary>described</tertiary> | |
2296 | </indexterm> | |
2297 | ||
2298 | <indexterm> | |
2299 | <primary>mounting</primary> | |
2300 | ||
2301 | <secondary>foreign volume in local cell</secondary> | |
2302 | </indexterm> | |
2303 | ||
2304 | <para>It is conventional to create cellular mount points only at the second level in a cell's filespace, using them to | |
2305 | mount foreign cells' <emphasis role="bold">root.cell</emphasis> volumes just below the AFS filespace root (by | |
2306 | convention, at <emphasis role="bold">/afs/</emphasis><replaceable>foreign_cellname</replaceable>). The mount point | |
2307 | enables local users to access the foreign cell's filespace, assuming they have the necessary permissions on the ACL of | |
2308 | the volume's root directory and that there is an entry for the foreign cell in each local client machine's <emphasis | |
2309 | role="bold">/usr/vice/etc/CellServDB</emphasis> file, as described in <link linkend="HDRWQ406">Maintaining Knowledge of | |
2310 | Database Server Machines</link>.</para> | |
2311 | ||
2312 | <para>Creating cellular mount points at other levels in the filespace and mounting foreign volumes other than the | |
2313 | <emphasis role="bold">root.cell</emphasis> volume is not generally appropriate. It can be confusing to users if the | |
2314 | Cache Manager switches between cells at various points in a pathname.</para> | |
2315 | ||
2316 | <para>To create a regular cellular mount point, use the <emphasis role="bold">-cell</emphasis> argument to specify the | |
2317 | cell name, as described in <link linkend="HDRWQ213">To create a cellular mount point</link>.</para> | |
2318 | </listitem> | |
2319 | </itemizedlist></para> | |
2320 | ||
2321 | <para>To examine a mount point, use the <emphasis role="bold">fs lsmount</emphasis> command as described in <link | |
2322 | linkend="HDRWQ211">To display a mount point</link>. The command's output uses distinct notation to identify regular, | |
2323 | read/write, and cellular mount points. To remove a mount point, use the <emphasis role="bold">fs rmmount</emphasis> command as | |
2324 | described in <link linkend="HDRWQ215">To remove a mount point</link>.</para> | |
2325 | </sect2> | |
2326 | ||
2327 | <sect2 id="Header_227"> | |
2328 | <title>Creating a mount point in a foreign cell</title> | |
2329 | ||
2330 | <para>Creating a mount point in a foreign cell's filespace (as opposed to mounting a foreign volume in the local cell) is | |
2331 | basically the same as creating a mount point in the local filespace. The differences are that the <emphasis role="bold">fs | |
2332 | mkmount</emphasis> command's directory argument specifies a pathname in the foreign cell rather than the local cell, and you | |
2333 | must have the required permissions on the ACL of the foreign directory where you are creating the mount point. The <emphasis | |
2334 | role="bold">fs mkmount</emphasis> command's <emphasis role="bold">-cell</emphasis> argument always specifies the cell in which | |
2335 | the volume resides, not the cell in which to create the mount point.</para> | |
2336 | </sect2> | |
2337 | ||
2338 | <sect2 id="HDRWQ211"> | |
2339 | <title>To display a mount point</title> | |
2340 | ||
2341 | <indexterm> | |
2342 | <primary>displaying</primary> | |
2343 | ||
2344 | <secondary>mount point</secondary> | |
2345 | </indexterm> | |
2346 | ||
2347 | <indexterm> | |
2348 | <primary>mount point</primary> | |
2349 | ||
2350 | <secondary>displaying</secondary> | |
2351 | </indexterm> | |
2352 | ||
2353 | <indexterm> | |
2354 | <primary>mount point</primary> | |
2355 | ||
2356 | <secondary>distinguishing different types</secondary> | |
2357 | </indexterm> | |
2358 | ||
2359 | <indexterm> | |
2360 | <primary>commands</primary> | |
2361 | ||
2362 | <secondary>fs lsmount</secondary> | |
2363 | </indexterm> | |
2364 | ||
2365 | <indexterm> | |
2366 | <primary>fs commands</primary> | |
2367 | ||
2368 | <secondary>lsmount</secondary> | |
2369 | </indexterm> | |
2370 | ||
2371 | <orderedlist> | |
2372 | <listitem> | |
2373 | <para>Issue the <emphasis role="bold">fs lsmount</emphasis> command. <programlisting> | |
2374 | % <emphasis role="bold">fs lsmount</emphasis> <<replaceable>directory</replaceable>> | |
2375 | </programlisting></para> | |
2376 | ||
2377 | <para>where <variablelist> | |
2378 | <varlistentry> | |
2379 | <term><emphasis role="bold">ls</emphasis></term> | |
2380 | ||
2381 | <listitem> | |
2382 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">lsmount</emphasis>.</para> | |
2383 | </listitem> | |
2384 | </varlistentry> | |
2385 | ||
2386 | <varlistentry> | |
2387 | <term><emphasis role="bold">directory</emphasis></term> | |
2388 | ||
2389 | <listitem> | |
2390 | <para>Names the mount point to display.</para> | |
2391 | </listitem> | |
2392 | </varlistentry> | |
2393 | </variablelist></para> | |
2394 | </listitem> | |
2395 | </orderedlist> | |
2396 | ||
2397 | <para>If the specified directory is a mount point, the output is of the following form:</para> | |
2398 | ||
2399 | <programlisting> | |
2400 | 'directory' is a mount point for volume 'volume name' | |
2401 | </programlisting> | |
2402 | ||
2403 | <para>For a regular mount point, a number sign (<computeroutput>#</computeroutput>) precedes the volume name string, as in the | |
2404 | following example command issued on a client machine in the <emphasis role="bold">example.com</emphasis> cell.</para> | |
2405 | ||
2406 | <programlisting> | |
2407 | % <emphasis role="bold">fs lsmount /afs/example.com/usr/terry</emphasis> | |
2408 | '/afs/example.com/usr/terry' is a mount point for volume '#user.terry' | |
2409 | </programlisting> | |
2410 | ||
2411 | <para>For a read/write mount point, a percent sign (<computeroutput>%</computeroutput>) precedes the volume name string, as in | |
2412 | the following example command issued on a client machine in the <emphasis role="bold">example.com</emphasis> cell. The cell's | |
2413 | administrators have followed the convention of preceding the read/write mount point's name with a period.</para> | |
2414 | ||
2415 | <programlisting> | |
2416 | % <emphasis role="bold">fs lsmount /afs/.example.com</emphasis> | |
2417 | '/afs/.example.com' is a mount point for volume '%root.cell' | |
2418 | </programlisting> | |
2419 | ||
2420 | <para>For a cellular mount point, a cell name and colon (<computeroutput>:</computeroutput>) follow the number or percent sign | |
2421 | and precede the volume name string, as in the following example command issued on a client machine in the <emphasis | |
2422 | role="bold">example.com</emphasis> cell.</para> | |
2423 | ||
2424 | <programlisting> | |
2425 | % <emphasis role="bold">fs lsmount /afs/example.org</emphasis> | |
2426 | '/afs/example.org' is a mount point for volume '#example.org:root.cell' | |
2427 | </programlisting> | |
2428 | ||
2429 | <para>For a symbolic link to a mount point, the output is of the form shown in the following example command issued on a | |
2430 | client machine in the <emphasis role="bold">example.com</emphasis> cell.</para> | |
2431 | ||
2432 | <programlisting> | |
2433 | % <emphasis role="bold">fs lsmount /afs/example</emphasis> | |
2434 | '/afs/example' is a symbolic link, leading to a mount point for volume '#root.cell' | |
2435 | </programlisting> | |
2436 | ||
2437 | <para>If the directory is not a mount point or is not in AFS, the output reads as follows.</para> | |
2438 | ||
2439 | <programlisting> | |
2440 | 'directory' is not a mount point. | |
2441 | </programlisting> | |
2442 | ||
2443 | <para>If the output is garbled, it is possible that the mount point has become corrupted in the local cache. Use the <emphasis | |
2444 | role="bold">fs flushmount</emphasis> command as described in <link linkend="HDRWQ413">To flush one or more mount | |
2445 | points</link>. This forces the Cache Manager to refetch the mount point.</para> | |
2446 | </sect2> | |
2447 | ||
2448 | <sect2 id="HDRWQ212"> | |
2449 | <title>To create a regular or read/write mount point</title> | |
2450 | ||
2451 | <indexterm> | |
2452 | <primary>creating</primary> | |
2453 | ||
2454 | <secondary>read/write or regular mount point</secondary> | |
2455 | </indexterm> | |
2456 | ||
2457 | <indexterm> | |
2458 | <primary>mount point</primary> | |
2459 | ||
2460 | <secondary>creating read/write or regular</secondary> | |
2461 | </indexterm> | |
2462 | ||
2463 | <indexterm> | |
2464 | <primary>mount point</primary> | |
2465 | ||
2466 | <secondary>regular</secondary> | |
2467 | ||
2468 | <tertiary>creating</tertiary> | |
2469 | </indexterm> | |
2470 | ||
2471 | <indexterm> | |
2472 | <primary>mount point</primary> | |
2473 | ||
2474 | <secondary>read/write</secondary> | |
2475 | ||
2476 | <tertiary>creating</tertiary> | |
2477 | </indexterm> | |
2478 | ||
2479 | <indexterm> | |
2480 | <primary>commands</primary> | |
2481 | ||
2482 | <secondary>fs mkmount</secondary> | |
2483 | ||
2484 | <tertiary>general instructions</tertiary> | |
2485 | </indexterm> | |
2486 | ||
2487 | <indexterm> | |
2488 | <primary>fs commands</primary> | |
2489 | ||
2490 | <secondary>mkmount</secondary> | |
2491 | ||
2492 | <tertiary>general instructions</tertiary> | |
2493 | </indexterm> | |
2494 | ||
2495 | <orderedlist> | |
2496 | <listitem> | |
2497 | <para>Verify that you have the <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) and <emphasis | |
2498 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) permissions on the ACL of the directory where you | |
2499 | are placing the mount point. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully | |
2500 | described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
2501 | % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
2502 | </programlisting></para> | |
2503 | </listitem> | |
2504 | ||
2505 | <listitem> | |
2506 | <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to create the mount point. Include the <emphasis | |
2507 | role="bold">-rw</emphasis> flag if creating a read/write mount point. <programlisting> | |
2508 | % <emphasis role="bold">fs mkmount</emphasis> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>> [<emphasis | |
2509 | role="bold">-rw</emphasis>] | |
2510 | </programlisting></para> | |
2511 | ||
2512 | <para>where <variablelist> | |
2513 | <varlistentry> | |
2514 | <term><emphasis role="bold">mk</emphasis></term> | |
2515 | ||
2516 | <listitem> | |
2517 | <para>Is the shortest acceptable abbreviation for <emphasis role="bold">mkmount</emphasis>.</para> | |
2518 | </listitem> | |
2519 | </varlistentry> | |
2520 | ||
2521 | <varlistentry> | |
2522 | <term><emphasis role="bold">directory</emphasis></term> | |
2523 | ||
2524 | <listitem> | |
2525 | <para>Names the mount point to create. A file or directory with the same name cannot already exist. A partial | |
2526 | pathname is interpreted relative to the current working directory.</para> | |
2527 | ||
2528 | <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create | |
2529 | a new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period | |
2530 | before the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). | |
2531 | For further discussion of the concept of read/write and read-only paths through the filespace, see <link | |
2532 | linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para> | |
2533 | </listitem> | |
2534 | </varlistentry> | |
2535 | ||
2536 | <varlistentry> | |
2537 | <term><emphasis role="bold">volume name</emphasis></term> | |
2538 | ||
2539 | <listitem> | |
2540 | <para>Specifies the volume's full name, including the <emphasis role="bold">.backup</emphasis> or <emphasis | |
2541 | role="bold">.readonly</emphasis> extension for a backup or read-only volume, if appropriate.</para> | |
2542 | </listitem> | |
2543 | </varlistentry> | |
2544 | ||
2545 | <varlistentry> | |
2546 | <term><emphasis role="bold">-rw</emphasis></term> | |
2547 | ||
2548 | <listitem> | |
2549 | <para>Creates a read/write mount point.</para> | |
2550 | </listitem> | |
2551 | </varlistentry> | |
2552 | </variablelist></para> | |
2553 | </listitem> | |
2554 | </orderedlist> | |
2555 | </sect2> | |
2556 | ||
2557 | <sect2 id="HDRWQ213"> | |
2558 | <title>To create a cellular mount point</title> | |
2559 | ||
2560 | <indexterm> | |
2561 | <primary>creating</primary> | |
2562 | ||
2563 | <secondary>cellular mount point</secondary> | |
2564 | </indexterm> | |
2565 | ||
2566 | <indexterm> | |
2567 | <primary>mount point</primary> | |
2568 | ||
2569 | <secondary>creating cellular</secondary> | |
2570 | </indexterm> | |
2571 | ||
2572 | <indexterm> | |
2573 | <primary>mount point</primary> | |
2574 | ||
2575 | <secondary>cellular</secondary> | |
2576 | ||
2577 | <tertiary>creating</tertiary> | |
2578 | </indexterm> | |
2579 | ||
2580 | <orderedlist> | |
2581 | <listitem> | |
2582 | <para>Verify that you have the <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) and <emphasis | |
2583 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) permissions on the ACL of the directory where you | |
2584 | are placing the mount point. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully | |
2585 | described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
2586 | % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
2587 | </programlisting></para> | |
2588 | </listitem> | |
2589 | ||
2590 | <listitem id="LIWQ214"> | |
2591 | <para>If you are mounting one or more foreign cells' <emphasis role="bold">root.cell</emphasis> | |
2592 | volume at the second level in your filespace and your cell's <emphasis role="bold">root.afs</emphasis> volume is | |
2593 | replicated, you must create a temporary mount point for the <emphasis role="bold">root.afs</emphasis> volume's read/write | |
2594 | version in a directory on which the ACL grants you the <emphasis role="bold">i</emphasis> and <emphasis | |
2595 | role="bold">a</emphasis> permissions. The following command creates a mount point called <emphasis | |
2596 | role="bold">new_cells</emphasis> in your cell's <emphasis role="bold">/afs/.</emphasis><replaceable>cellname</replaceable> | |
2597 | directory (the entry point to the read/write path in your cell).</para> | |
2598 | ||
2599 | <para>Substitute your cell's name for cellname.</para> | |
2600 | ||
2601 | <programlisting> | |
2602 | % <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable> | |
2603 | % <emphasis role="bold">fs mkmount new_cells root.afs</emphasis> | |
2604 | % <emphasis role="bold">cd new_cells</emphasis> | |
2605 | </programlisting> | |
2606 | </listitem> | |
2607 | ||
2608 | <listitem> | |
2609 | <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command with the <emphasis role="bold">-cell</emphasis> | |
2610 | argument to create a cellular mount point. Repeat the command for each cellular mount point as required. <programlisting> | |
2611 | % <emphasis role="bold">fs mkmount</emphasis> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>> <emphasis | |
2612 | role="bold">-cell</emphasis> <<replaceable>cell name</replaceable>> | |
2613 | </programlisting></para> | |
2614 | ||
2615 | <para>where <variablelist> | |
2616 | <varlistentry> | |
2617 | <term><emphasis role="bold">mk</emphasis></term> | |
2618 | ||
2619 | <listitem> | |
2620 | <para>Is the shortest acceptable abbreviation for <emphasis role="bold">mkmount</emphasis>.</para> | |
2621 | </listitem> | |
2622 | </varlistentry> | |
2623 | ||
2624 | <varlistentry> | |
2625 | <term><emphasis role="bold">directory</emphasis></term> | |
2626 | ||
2627 | <listitem> | |
2628 | <para>Names the mount point to create. A file or directory with the same name cannot already exist. A partial | |
2629 | pathname is interpreted relative to the current working directory. If you are mounting a foreign cell's <emphasis | |
2630 | role="bold">root.cell</emphasis> volume, the standard value for this argument is the cell's complete Internet | |
2631 | domain name.</para> | |
2632 | </listitem> | |
2633 | </varlistentry> | |
2634 | ||
2635 | <varlistentry> | |
2636 | <term><emphasis role="bold">volume name</emphasis></term> | |
2637 | ||
2638 | <listitem> | |
2639 | <para>Specifies the volume's full name, usually <emphasis role="bold">root.cell</emphasis> for a cellular mount | |
2640 | point.</para> | |
2641 | </listitem> | |
2642 | </varlistentry> | |
2643 | ||
2644 | <varlistentry> | |
2645 | <term><emphasis role="bold">-cell</emphasis></term> | |
2646 | ||
2647 | <listitem> | |
2648 | <para>Specifies the complete Internet domain name of the cell in which the volume resides.</para> | |
2649 | </listitem> | |
2650 | </varlistentry> | |
2651 | </variablelist></para> | |
2652 | </listitem> | |
2653 | ||
2654 | <listitem> | |
2655 | <para>If you performed the instructions in Step <link linkend="LIWQ214">2</link>, issue the <emphasis role="bold">vos | |
2656 | release</emphasis> command to release the new version of the <emphasis role="bold">root.afs</emphasis> volume to its | |
2657 | read-only sites. (This command requires that you be listed in your cell's <emphasis | |
2658 | role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, verify by issuing the <emphasis role="bold">bos | |
2659 | listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the users in the UserList | |
2660 | file</link>.)</para> | |
2661 | ||
2662 | <para>Also issue the <emphasis role="bold">fs checkvolumes</emphasis> command to force the local Cache Manager to access | |
2663 | the new replica of the <emphasis role="bold">root.afs</emphasis> volume. If desired, you can also remove the temporary | |
2664 | <emphasis role="bold">new_cells</emphasis> mount point from the <emphasis | |
2665 | role="bold">/afs/.</emphasis><replaceable>cellname</replaceable> directory.</para> | |
2666 | ||
2667 | <programlisting> | |
2668 | % <emphasis role="bold">vos release root.afs</emphasis> | |
2669 | % <emphasis role="bold">fs checkvolumes</emphasis> | |
2670 | % <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable> | |
2671 | % <emphasis role="bold">fs rmmount new_cells</emphasis> | |
2672 | </programlisting> | |
2673 | ||
2674 | <para>For your users to access a newly mounted foreign cell, you must also create an entry for it in each client machine's | |
2675 | local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file and either reboot the machine or use the <emphasis | |
2676 | role="bold">fs newcell</emphasis> command to insert the entry directly into its kernel memory. See the instructions in | |
2677 | <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para> | |
2678 | </listitem> | |
2679 | </orderedlist> | |
2680 | </sect2> | |
2681 | ||
2682 | <sect2 id="HDRWQ215"> | |
2683 | <title>To remove a mount point</title> | |
2684 | ||
2685 | <indexterm> | |
2686 | <primary>removing</primary> | |
2687 | ||
2688 | <secondary>mount point</secondary> | |
2689 | </indexterm> | |
2690 | ||
2691 | <indexterm> | |
2692 | <primary>unmounting</primary> | |
2693 | ||
2694 | <secondary>volume</secondary> | |
2695 | </indexterm> | |
2696 | ||
2697 | <indexterm> | |
2698 | <primary>mount point</primary> | |
2699 | ||
2700 | <secondary>removing</secondary> | |
2701 | </indexterm> | |
2702 | ||
2703 | <indexterm> | |
2704 | <primary>commands</primary> | |
2705 | ||
2706 | <secondary>fs rmmount</secondary> | |
2707 | </indexterm> | |
2708 | ||
2709 | <indexterm> | |
2710 | <primary>fs commands</primary> | |
2711 | ||
2712 | <secondary>rmmount</secondary> | |
2713 | </indexterm> | |
2714 | ||
2715 | <orderedlist> | |
2716 | <listitem> | |
2717 | <para>Verify that you have the <emphasis role="bold">d</emphasis>( <emphasis role="bold">delete</emphasis>) permission on | |
2718 | the ACL of the directory from which you are removing the mount point. If necessary, issue the <emphasis role="bold">fs | |
2719 | listacl</emphasis> command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
2720 | % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
2721 | </programlisting></para> | |
2722 | ||
2723 | <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis | |
2724 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis | |
2725 | role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis | |
2726 | role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para> | |
2727 | </listitem> | |
2728 | ||
2729 | <listitem> | |
2730 | <para>Issue the <emphasis role="bold">fs rmmount</emphasis> command to remove the mount point. The volume still exists, | |
2731 | but its contents are inaccessible if this is the only mount point for it. <programlisting> | |
2732 | % <emphasis role="bold">fs rmmount</emphasis> <<replaceable>directory</replaceable>> | |
2733 | </programlisting></para> | |
2734 | ||
2735 | <para>where <variablelist> | |
2736 | <varlistentry> | |
2737 | <term><emphasis role="bold">rm</emphasis></term> | |
2738 | ||
2739 | <listitem> | |
2740 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">rmmount</emphasis>.</para> | |
2741 | </listitem> | |
2742 | </varlistentry> | |
2743 | ||
2744 | <varlistentry> | |
2745 | <term><emphasis role="bold">directory</emphasis></term> | |
2746 | ||
2747 | <listitem> | |
2748 | <para>Names the mount point to remove. A partial pathname is interpreted relative to the current working | |
2749 | directory.</para> | |
2750 | ||
2751 | <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete | |
2752 | a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before | |
2753 | the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For | |
2754 | further discussion of the concept of read/write and read-only paths through the filespace, see <link | |
2755 | linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para> | |
2756 | </listitem> | |
2757 | </varlistentry> | |
2758 | </variablelist></para> | |
2759 | </listitem> | |
2760 | </orderedlist> | |
2761 | </sect2> | |
2762 | ||
2763 | <sect2> | |
2764 | <title>To access volumes directly by volume ID</title> | |
2765 | ||
2766 | <indexterm> | |
2767 | <primary>volume</primary> | |
2768 | ||
2769 | <secondary>direct access</secondary> | |
2770 | </indexterm> | |
2771 | ||
2772 | <para>You can directly access volumes by volume IDs. This is only | |
2773 | recommended for temporary access to a volume. For example, if you | |
2774 | have recently restored a volume from a backup, you can use this | |
2775 | syntax to quickly access the volume without mounting it.</para> | |
2776 | ||
2777 | <para>This feature is available with Windows and Linux based cache | |
2778 | managers by default. This feature is available with other Unix based | |
2779 | cache managers when the dynamic root (-dynroot) and fake stat | |
2780 | (-fakestat) modes are enabled.</para> | |
2781 | ||
2782 | <para>Examples:</para> | |
2783 | <itemizedlist> | |
2784 | <listitem> | |
2785 | <para><emphasis role="bold">Windows:</emphasis> | |
2786 | \\afs\example.com%root.cell - Access a read/write volume directly</para> | |
2787 | </listitem> | |
2788 | <listitem> | |
2789 | <para><emphasis role="bold">Windows:</emphasis> | |
2790 | \\afs\example.com#root.cell - Access a read-only volume directly</para> | |
2791 | </listitem> | |
2792 | <listitem> | |
2793 | <para><emphasis role="bold">Unix:</emphasis> | |
2794 | /afs/.:mount/example.com:root.cell - Access a read/write volume directly</para> | |
2795 | </listitem> | |
2796 | <listitem> | |
2797 | <para><emphasis role="bold">Unix:</emphasis> | |
2798 | /afs/.:mount/example.com:root.cell.readonly - Access a read-only volume directly</para> | |
2799 | </listitem> | |
2800 | <listitem> | |
2801 | <para><emphasis role="bold">Unix:</emphasis> | |
2802 | /afs/.:mount/example.com:root.cell.backup - Access a backup volume directly</para> | |
2803 | </listitem> | |
2804 | </itemizedlist> | |
2805 | </sect2> | |
2806 | </sect1> | |
2807 | ||
2808 | <sect1 id="HDRWQ216"> | |
2809 | <title>Displaying Information About Volumes</title> | |
2810 | ||
2811 | <indexterm> | |
2812 | <primary>displaying</primary> | |
2813 | ||
2814 | <secondary>volume information</secondary> | |
2815 | </indexterm> | |
2816 | ||
2817 | <indexterm> | |
2818 | <primary>volume</primary> | |
2819 | ||
2820 | <secondary>displaying information about</secondary> | |
2821 | </indexterm> | |
2822 | ||
2823 | <para>This section explains how to display information about volumes. If you know a volume's name or volume ID number, there are | |
2824 | commands for displaying its VLDB entry, its volume header, or both. Other commands display the name or location of the volume | |
2825 | that contains a specified file or directory.</para> | |
2826 | ||
2827 | <para>For instructions on displaying a volume's quota, see <link linkend="HDRWQ234">Setting and Displaying Volume Quota and | |
2828 | Current Size</link>.</para> | |
2829 | ||
2830 | <sect2 id="HDRWQ217"> | |
2831 | <title>Displaying VLDB Entries</title> | |
2832 | ||
2833 | <indexterm> | |
2834 | <primary>displaying</primary> | |
2835 | ||
2836 | <secondary>volume's VLDB entry</secondary> | |
2837 | </indexterm> | |
2838 | ||
2839 | <indexterm> | |
2840 | <primary>VLDB</primary> | |
2841 | ||
2842 | <secondary>displaying volume entry</secondary> | |
2843 | </indexterm> | |
2844 | ||
2845 | <indexterm> | |
2846 | <primary>volume entry (VLDB)</primary> | |
2847 | ||
2848 | <secondary>displaying</secondary> | |
2849 | </indexterm> | |
2850 | ||
2851 | <indexterm> | |
2852 | <primary>locked VLDB entry</primary> | |
2853 | ||
2854 | <secondary>displaying</secondary> | |
2855 | </indexterm> | |
2856 | ||
2857 | <para>The <emphasis role="bold">vos listvldb</emphasis> command displays the VLDB entry for the volumes indicated by the | |
2858 | combination of arguments you provide. The possibilities are listed here from most to least inclusive: <itemizedlist> | |
2859 | <listitem> | |
2860 | <para>To display every entry in the VLDB, provide no arguments. It can take a long time to generate the output, | |
2861 | depending on the number of entries.</para> | |
2862 | </listitem> | |
2863 | ||
2864 | <listitem> | |
2865 | <para>To display every VLDB entry that mentions a specific file server machine as the site of a volume, specify the | |
2866 | machine's name with the <emphasis role="bold">-server</emphasis> argument.</para> | |
2867 | </listitem> | |
2868 | ||
2869 | <listitem> | |
2870 | <para>To display every VLDB entry that mentions a certain partition on any file server machine as the site of a volume, | |
2871 | specify the partition name with the <emphasis role="bold">-partition</emphasis> argument.</para> | |
2872 | </listitem> | |
2873 | ||
2874 | <listitem> | |
2875 | <para>To display every VLDB entry that mentions a certain partition on a certain file server machine as the site of a | |
2876 | volume, combine the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> | |
2877 | arguments.</para> | |
2878 | </listitem> | |
2879 | ||
2880 | <listitem> | |
2881 | <para>To display a single VLDB entry, specify a volume name or ID number with the <emphasis role="bold">-name</emphasis> | |
2882 | argument.</para> | |
2883 | </listitem> | |
2884 | ||
2885 | <listitem> | |
2886 | <para>To display the VLDB entry only for volumes with locked VLDB entries, use the <emphasis | |
2887 | role="bold">-locked</emphasis> flag with any of the site definitions mentioned previously.</para> | |
2888 | </listitem> | |
2889 | </itemizedlist></para> | |
2890 | ||
2891 | <indexterm> | |
2892 | <primary>commands</primary> | |
2893 | ||
2894 | <secondary>vos listvldb</secondary> | |
2895 | ||
2896 | <tertiary>syntax</tertiary> | |
2897 | </indexterm> | |
2898 | ||
2899 | <indexterm> | |
2900 | <primary>vos commands</primary> | |
2901 | ||
2902 | <secondary>listvldb</secondary> | |
2903 | ||
2904 | <tertiary>syntax</tertiary> | |
2905 | </indexterm> | |
2906 | </sect2> | |
2907 | ||
2908 | <sect2 id="HDRWQ218"> | |
2909 | <title>To display VLDB entries</title> | |
2910 | ||
2911 | <orderedlist> | |
2912 | <listitem> | |
2913 | <para>Issue the <emphasis role="bold">vos listvldb</emphasis> command. <programlisting> | |
2914 | % <emphasis role="bold">vos listvldb</emphasis> [<emphasis role="bold">-name</emphasis> <<replaceable>volume name or ID</replaceable>>] [<emphasis | |
2915 | role="bold">-server</emphasis> <<replaceable>machine name</replaceable>>] \ | |
2916 | [<emphasis role="bold">-partition</emphasis> <<replaceable>partition name</replaceable>>] [<emphasis role="bold">-locked</emphasis>] | |
2917 | </programlisting></para> | |
2918 | ||
2919 | <para>where <variablelist> | |
2920 | <varlistentry> | |
2921 | <term><emphasis role="bold">listvl</emphasis></term> | |
2922 | ||
2923 | <listitem> | |
2924 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listvldb</emphasis>.</para> | |
2925 | </listitem> | |
2926 | </varlistentry> | |
2927 | ||
2928 | <varlistentry> | |
2929 | <term><emphasis role="bold">-name</emphasis></term> | |
2930 | ||
2931 | <listitem> | |
2932 | <para>Identifies one volume either by its complete name or volume ID number. Do not combine this argument with the | |
2933 | <emphasis role="bold">-server</emphasis> or <emphasis role="bold">-partition</emphasis> arguments.</para> | |
2934 | </listitem> | |
2935 | </varlistentry> | |
2936 | ||
2937 | <varlistentry> | |
2938 | <term><emphasis role="bold">-server</emphasis></term> | |
2939 | ||
2940 | <listitem> | |
2941 | <para>Specifies a file server machine. Combine this argument with the <emphasis role="bold">-partition</emphasis> | |
2942 | argument if desired, but not with the <emphasis role="bold">-name</emphasis> argument.</para> | |
2943 | </listitem> | |
2944 | </varlistentry> | |
2945 | ||
2946 | <varlistentry> | |
2947 | <term><emphasis role="bold">-partition</emphasis></term> | |
2948 | ||
2949 | <listitem> | |
2950 | <para>Specifies a partition. Combine this argument with the <emphasis role="bold">-server</emphasis> argument if | |
2951 | desired, but not with the <emphasis role="bold">-name</emphasis> argument.</para> | |
2952 | </listitem> | |
2953 | </varlistentry> | |
2954 | ||
2955 | <varlistentry> | |
2956 | <term><emphasis role="bold">-locked</emphasis></term> | |
2957 | ||
2958 | <listitem> | |
2959 | <para>Displays only locked VLDB entries. Combine this flag with any of the other options.</para> | |
2960 | </listitem> | |
2961 | </varlistentry> | |
2962 | </variablelist></para> | |
2963 | </listitem> | |
2964 | </orderedlist> | |
2965 | ||
2966 | <para>The VLDB entry for each volume includes the following information: <itemizedlist> | |
2967 | <listitem> | |
2968 | <para>The base (read/write) volume name. The read-only and backup versions have the same name with a <emphasis | |
2969 | role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extension, respectively.</para> | |
2970 | </listitem> | |
2971 | ||
2972 | <listitem> | |
2973 | <para>The volume ID numbers allocated to the versions of the volume that actually exist, in fields labeled | |
2974 | <computeroutput>RWrite</computeroutput> for the read/write, <computeroutput>ROnly</computeroutput> for the read-only, | |
2975 | <computeroutput>Backup</computeroutput> for the backup, and <computeroutput>RClone</computeroutput> for the | |
2976 | ReleaseClone. (If a field does not appear, the corresponding version of the volume does not exist.) The appearance of | |
2977 | the <computeroutput>RClone</computeroutput> field normally indicates that a release operation did not complete | |
2978 | successfully; the <computeroutput>Old release</computeroutput> and <computeroutput>New release</computeroutput> flags | |
2979 | often also appear on one or more of the site definition lines described just following.</para> | |
2980 | ||
2981 | <indexterm> | |
2982 | <primary>site</primary> | |
2983 | ||
2984 | <secondary>count in VLDB</secondary> | |
2985 | </indexterm> | |
2986 | ||
2987 | <indexterm> | |
2988 | <primary>VLDB</primary> | |
2989 | ||
2990 | <secondary>site count for volume</secondary> | |
2991 | </indexterm> | |
2992 | </listitem> | |
2993 | ||
2994 | <listitem> | |
2995 | <para>The number of sites that house a read/write or read-only copy of the volume, following the string | |
2996 | <computeroutput>number of sites -></computeroutput>.</para> | |
2997 | ||
2998 | <indexterm> | |
2999 | <primary>type flag for volume</primary> | |
3000 | ||
3001 | <secondary>VLDB entry</secondary> | |
3002 | </indexterm> | |
3003 | ||
3004 | <indexterm> | |
3005 | <primary>VLDB</primary> | |
3006 | ||
3007 | <secondary>volume type flags</secondary> | |
3008 | </indexterm> | |
3009 | ||
3010 | <indexterm> | |
3011 | <primary>release</primary> | |
3012 | ||
3013 | <secondary>status flags on site definitions in VLDB entry</secondary> | |
3014 | </indexterm> | |
3015 | ||
3016 | <indexterm> | |
3017 | <primary>VLDB</primary> | |
3018 | ||
3019 | <secondary>release status flags in volume entry</secondary> | |
3020 | </indexterm> | |
3021 | ||
3022 | <indexterm> | |
3023 | <primary>status flag</primary> | |
3024 | ||
3025 | <secondary>release, on site definitions in VLDB entry</secondary> | |
3026 | </indexterm> | |
3027 | </listitem> | |
3028 | ||
3029 | <listitem> | |
3030 | <para>A line for each site that houses a read/write or read-only copy of the volume, specifying the file server machine, | |
3031 | partition, and type of volume (<computeroutput>RW</computeroutput> for read/write or <computeroutput>RO</computeroutput> | |
3032 | for read-only). If a backup version exists, it is understood to share the read/write site. Several flags can appear with | |
3033 | a site definition: <variablelist> | |
3034 | <indexterm> | |
3035 | <primary>Not released</primary> | |
3036 | ||
3037 | <secondary>status flag on site definition in VLDB entry</secondary> | |
3038 | </indexterm> | |
3039 | ||
3040 | <varlistentry> | |
3041 | <term><computeroutput>Not released</computeroutput></term> | |
3042 | ||
3043 | <listitem> | |
3044 | <para>Indicates that the <emphasis role="bold">vos release</emphasis> command has not been issued since the | |
3045 | <emphasis role="bold">vos addsite</emphasis> command was used to define the read-only site.</para> | |
3046 | ||
3047 | <indexterm> | |
3048 | <primary>Old release</primary> | |
3049 | ||
3050 | <secondary>status flag on site definition in VLDB entry</secondary> | |
3051 | </indexterm> | |
3052 | </listitem> | |
3053 | </varlistentry> | |
3054 | ||
3055 | <varlistentry> | |
3056 | <term><computeroutput>Old release</computeroutput></term> | |
3057 | ||
3058 | <listitem> | |
3059 | <para>Indicates that a <emphasis role="bold">vos release</emphasis> command did not complete successfully, | |
3060 | leaving the previous, obsolete version of the volume at this site.</para> | |
3061 | ||
3062 | <indexterm> | |
3063 | <primary>New release</primary> | |
3064 | ||
3065 | <secondary>status flag on site definition in VLDB entry</secondary> | |
3066 | </indexterm> | |
3067 | </listitem> | |
3068 | </varlistentry> | |
3069 | ||
3070 | <varlistentry> | |
3071 | <term><computeroutput>New release</computeroutput></term> | |
3072 | ||
3073 | <listitem> | |
3074 | <para>Indicates that a <emphasis role="bold">vos release</emphasis> command did not complete successfully, but | |
3075 | that this site did receive the correct new version of the volume.</para> | |
3076 | </listitem> | |
3077 | </varlistentry> | |
3078 | </variablelist></para> | |
3079 | </listitem> | |
3080 | ||
3081 | <listitem> | |
3082 | <para>If the VLDB entry is locked, the string <computeroutput>Volume is currently LOCKED</computeroutput>.</para> | |
3083 | </listitem> | |
3084 | </itemizedlist></para> | |
3085 | ||
3086 | <para>For further discussion of the <computeroutput>New release</computeroutput> and <computeroutput>Old | |
3087 | release</computeroutput> flags, see <link linkend="HDRWQ192">Replicating Volumes (Creating Read-only Volumes)</link>.</para> | |
3088 | ||
3089 | <para>An example of this command and its output for a single volume:</para> | |
3090 | ||
3091 | <programlisting> | |
3092 | % <emphasis role="bold">vos listvldb user.terry</emphasis> | |
3093 | user.terry | |
3094 | RWrite: 50489902 Backup: 50489904 | |
3095 | number of sites -> 1 | |
3096 | server fs3.example.com partition /vicepc RW Site | |
3097 | </programlisting> | |
3098 | </sect2> | |
3099 | ||
3100 | <sect2 id="HDRWQ219"> | |
3101 | <title>Displaying Volume Headers</title> | |
3102 | ||
3103 | <indexterm> | |
3104 | <primary>displaying</primary> | |
3105 | ||
3106 | <secondary>volume header</secondary> | |
3107 | </indexterm> | |
3108 | ||
3109 | <indexterm> | |
3110 | <primary>volume header</primary> | |
3111 | ||
3112 | <secondary>displaying</secondary> | |
3113 | ||
3114 | <tertiary>only</tertiary> | |
3115 | </indexterm> | |
3116 | ||
3117 | <para>The <emphasis role="bold">vos listvol</emphasis> command displays the volume header for every volume on one or all | |
3118 | partitions on a file server machine. The <emphasis role="bold">vos</emphasis> command interpreter obtains the information from | |
3119 | the Volume Server on the specified machine. You can control the amount of information displayed by including one of the | |
3120 | <emphasis role="bold">-fast</emphasis>, the <emphasis role="bold">-long</emphasis>, or the <emphasis | |
3121 | role="bold">-extended</emphasis> flags described following the instructions in <link linkend="HDRWQ220">To display volume | |
3122 | headers</link>.</para> | |
3123 | ||
3124 | <para>To display a single volume's volume header of one volume only, use the <emphasis role="bold">vos examine</emphasis> | |
3125 | command as described in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>.</para> | |
3126 | ||
3127 | <indexterm> | |
3128 | <primary>commands</primary> | |
3129 | ||
3130 | <secondary>vos listvol</secondary> | |
3131 | ||
3132 | <tertiary>syntax</tertiary> | |
3133 | </indexterm> | |
3134 | ||
3135 | <indexterm> | |
3136 | <primary>vos commands</primary> | |
3137 | ||
3138 | <secondary>listvol</secondary> | |
3139 | ||
3140 | <tertiary>syntax</tertiary> | |
3141 | </indexterm> | |
3142 | </sect2> | |
3143 | ||
3144 | <sect2 id="HDRWQ220"> | |
3145 | <title>To display volume headers</title> | |
3146 | ||
3147 | <orderedlist> | |
3148 | <listitem> | |
3149 | <para>Issue the <emphasis role="bold">vos listvol</emphasis> command. <programlisting> | |
3150 | % <emphasis role="bold">vos listvol</emphasis> <<replaceable>machine name</replaceable>> [<<replaceable>partition name</replaceable>>] [<emphasis | |
3151 | role="bold">-fast</emphasis>] [<emphasis role="bold">-long</emphasis>] [<emphasis role="bold">-extended</emphasis>] | |
3152 | </programlisting></para> | |
3153 | ||
3154 | <para>where <variablelist> | |
3155 | <varlistentry> | |
3156 | <term><emphasis role="bold">listvo</emphasis></term> | |
3157 | ||
3158 | <listitem> | |
3159 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listvol</emphasis>.</para> | |
3160 | </listitem> | |
3161 | </varlistentry> | |
3162 | ||
3163 | <varlistentry> | |
3164 | <term><emphasis role="bold">machine name</emphasis></term> | |
3165 | ||
3166 | <listitem> | |
3167 | <para>Names the file server machine for which to display volume headers. Provide this argument alone or with the | |
3168 | partition name argument.</para> | |
3169 | </listitem> | |
3170 | </varlistentry> | |
3171 | ||
3172 | <varlistentry> | |
3173 | <term><emphasis role="bold">partition name</emphasis></term> | |
3174 | ||
3175 | <listitem> | |
3176 | <para>Names one partition on the file server machine named by the machine name argument, which must be provided | |
3177 | along with this one.</para> | |
3178 | </listitem> | |
3179 | </varlistentry> | |
3180 | ||
3181 | <varlistentry> | |
3182 | <term><emphasis role="bold">-fast</emphasis></term> | |
3183 | ||
3184 | <listitem> | |
3185 | <para>Displays only the volume ID numbers of relevant volumes. Do not combine this flag with the <emphasis | |
3186 | role="bold">-long</emphasis> or <emphasis role="bold">-extended</emphasis> flag.</para> | |
3187 | </listitem> | |
3188 | </varlistentry> | |
3189 | ||
3190 | <varlistentry> | |
3191 | <term><emphasis role="bold">-long</emphasis></term> | |
3192 | ||
3193 | <listitem> | |
3194 | <para>Displays more detailed information about each volume. Do not combine this flag with the <emphasis | |
3195 | role="bold">-fast</emphasis> or <emphasis role="bold">-extended</emphasis> flag.</para> | |
3196 | </listitem> | |
3197 | </varlistentry> | |
3198 | ||
3199 | <varlistentry> | |
3200 | <term><emphasis role="bold">-extended</emphasis></term> | |
3201 | ||
3202 | <listitem> | |
3203 | <para>Displays all of the information displayed by the <emphasis role="bold">-long</emphasis> flag, plus tables of | |
3204 | statistics about reads and writes to the files in the volume. Do not combine this flag with the <emphasis | |
3205 | role="bold">-fast</emphasis> or <emphasis role="bold">-long</emphasis> flag.</para> | |
3206 | </listitem> | |
3207 | </varlistentry> | |
3208 | </variablelist></para> | |
3209 | </listitem> | |
3210 | </orderedlist> | |
3211 | ||
3212 | <para>The output is ordered alphabetically by volume name and by default provides the following information on a single line | |
3213 | for each volume: <itemizedlist> | |
3214 | <listitem> | |
3215 | <para>Name</para> | |
3216 | </listitem> | |
3217 | ||
3218 | <listitem> | |
3219 | <para>Volume ID number</para> | |
3220 | ||
3221 | <indexterm> | |
3222 | <primary>type flag for volume</primary> | |
3223 | ||
3224 | <secondary>volume header</secondary> | |
3225 | </indexterm> | |
3226 | </listitem> | |
3227 | ||
3228 | <listitem> | |
3229 | <para>Type (the flag is <computeroutput>RW</computeroutput> for read/write, <computeroutput>RO</computeroutput> for | |
3230 | read-only, <computeroutput>BK</computeroutput> for backup)</para> | |
3231 | </listitem> | |
3232 | ||
3233 | <listitem> | |
3234 | <para>Size in kilobytes (<computeroutput>1024</computeroutput> equals a megabyte)</para> | |
3235 | </listitem> | |
3236 | ||
3237 | <listitem> | |
3238 | <para>Number of files in the volume, if the <emphasis role="bold">-extended</emphasis> flag is provided</para> | |
3239 | ||
3240 | <indexterm> | |
3241 | <primary>status flags in volume header</primary> | |
3242 | </indexterm> | |
3243 | </listitem> | |
3244 | ||
3245 | <listitem> | |
3246 | <para>Status on the file server machine, which is one of the following: <variablelist> | |
3247 | <indexterm> | |
3248 | <primary>On-line status flag in volume header</primary> | |
3249 | </indexterm> | |
3250 | ||
3251 | <varlistentry> | |
3252 | <term><computeroutput>On-line</computeroutput></term> | |
3253 | ||
3254 | <listitem> | |
3255 | <para>The volume is completely accessible to Cache Managers.</para> | |
3256 | ||
3257 | <indexterm> | |
3258 | <primary>Off-line status flag in volume header</primary> | |
3259 | </indexterm> | |
3260 | </listitem> | |
3261 | </varlistentry> | |
3262 | ||
3263 | <varlistentry> | |
3264 | <term><computeroutput>Off-line</computeroutput></term> | |
3265 | ||
3266 | <listitem> | |
3267 | <para>The volume is not accessible to Cache Managers, but does not seem to be corrupted. This status appears | |
3268 | while a volume is being dumped, for example.</para> | |
3269 | ||
3270 | <indexterm> | |
3271 | <primary>needs salvage status flag in volume header</primary> | |
3272 | </indexterm> | |
3273 | </listitem> | |
3274 | </varlistentry> | |
3275 | ||
3276 | <varlistentry> | |
3277 | <term><computeroutput>Off-line**needs salvage**</computeroutput></term> | |
3278 | ||
3279 | <listitem> | |
3280 | <para>The volume is not accessible to Cache Managers, because it seems to be corrupted. Use the <emphasis | |
3281 | role="bold">bos salvage</emphasis> or <emphasis role="bold">salvager</emphasis> command to repair the | |
3282 | corruption.</para> | |
3283 | </listitem> | |
3284 | </varlistentry> | |
3285 | </variablelist></para> | |
3286 | </listitem> | |
3287 | </itemizedlist></para> | |
3288 | ||
3289 | <para>If the following message appears instead of the previously listed information, it indicates that a volume is not | |
3290 | accessible to Cache Managers or the <emphasis role="bold">vos</emphasis> command interpreter, for example because a clone is | |
3291 | being created.</para> | |
3292 | ||
3293 | <programlisting> | |
3294 | **** Volume volume_ID is busy **** | |
3295 | </programlisting> | |
3296 | ||
3297 | <para>If the following message appears instead of the previously listed information, it indicates that the File Server is | |
3298 | unable to attach the volume, perhaps because it is seriously corrupted. The <emphasis role="bold">FileLog</emphasis> and | |
3299 | <emphasis role="bold">VolserLog</emphasis> log files in the <emphasis role="bold">/usr/afs/logs</emphasis> directory on the | |
3300 | file server machine possibly provide additional information; use the <emphasis role="bold">bos getlog</emphasis> command to | |
3301 | display them.</para> | |
3302 | ||
3303 | <programlisting> | |
3304 | **** Could not attach volume volume_ID **** | |
3305 | </programlisting> | |
3306 | ||
3307 | <para>(For instructions on salvaging a corrupted or unattached volume, see <link linkend="HDRWQ232">Salvaging | |
3308 | Volumes</link>.)</para> | |
3309 | ||
3310 | <para>The information about individual volumes is bracketed by summary lines. The first line of output specifies the number of | |
3311 | volumes in the listing. The last line of output summarizes the number of volumes that are online, offline, and busy, as in the | |
3312 | following example:</para> | |
3313 | ||
3314 | <programlisting> | |
3315 | % <emphasis role="bold">vos listvol fs2.example.com /vicepb</emphasis> | |
3316 | Total number of volumes on server fs2.example.com \ | |
3317 | partition /vicepb : 66 | |
3318 | sys 1969534847 RW 1582 K On-line | |
3319 | sys.backup 1969535105 BK 1582 K On-line | |
3320 | . . . . . . | |
3321 | . . . . . . | |
3322 | user.pat 1969534536 RW 17518 K On-line | |
3323 | user.pat.backup 1969534538 BK 17537 K On-line | |
3324 | Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0 | |
3325 | </programlisting> | |
3326 | ||
3327 | <para><emphasis role="bold">Output with the -fast Flag</emphasis></para> | |
3328 | ||
3329 | <indexterm> | |
3330 | <primary>vos commands</primary> | |
3331 | ||
3332 | <secondary>listvol</secondary> | |
3333 | ||
3334 | <tertiary>output with -fast flag</tertiary> | |
3335 | </indexterm> | |
3336 | ||
3337 | <para>If you include the <emphasis role="bold">-fast</emphasis> flag displays only the volume ID number of each volume, | |
3338 | arranged in increasing numerical order, as in the following example. The final line (which summarizes the number of on-line, | |
3339 | off-line, and busy volumes) is omitted.</para> | |
3340 | ||
3341 | <programlisting> | |
3342 | % <emphasis role="bold">vos listvol fs3.example.com /vicepa -f</emphasis> | |
3343 | Total number of volumes on server fs3.example.com \ | |
3344 | partition /vicepa: 37 | |
3345 | 50489902 | |
3346 | 50489904 | |
3347 | . | |
3348 | . | |
3349 | 35970325 | |
3350 | 49732810 | |
3351 | </programlisting> | |
3352 | ||
3353 | <para><emphasis role="bold">Output with the -long Flag</emphasis></para> | |
3354 | ||
3355 | <indexterm> | |
3356 | <primary>vos commands</primary> | |
3357 | ||
3358 | <secondary>listvol</secondary> | |
3359 | ||
3360 | <tertiary>output with -long flag</tertiary> | |
3361 | </indexterm> | |
3362 | ||
3363 | <para>When you include the <emphasis role="bold">-long</emphasis> flag, , the output for each volume includes all of the | |
3364 | information in the default listing plus the following. Each item in this list corresponds to a separate line of output: | |
3365 | <itemizedlist> | |
3366 | <listitem> | |
3367 | <para>The file server machine and partition that house the volume, as determined by the command interpreter as the | |
3368 | command runs, rather than derived from the VLDB or the volume header.</para> | |
3369 | ||
3370 | <indexterm> | |
3371 | <primary>read/write volume</primary> | |
3372 | ||
3373 | <secondary>ID number in volume header</secondary> | |
3374 | </indexterm> | |
3375 | ||
3376 | <indexterm> | |
3377 | <primary>read-only volume</primary> | |
3378 | ||
3379 | <secondary>ID number in volume header</secondary> | |
3380 | </indexterm> | |
3381 | ||
3382 | <indexterm> | |
3383 | <primary>backup volume</primary> | |
3384 | ||
3385 | <secondary>ID number in volume header</secondary> | |
3386 | </indexterm> | |
3387 | ||
3388 | <indexterm> | |
3389 | <primary>ReleaseClone volume</primary> | |
3390 | ||
3391 | <secondary>ID number in volume header</secondary> | |
3392 | </indexterm> | |
3393 | ||
3394 | <indexterm> | |
3395 | <primary>RWrite field in volume header</primary> | |
3396 | </indexterm> | |
3397 | ||
3398 | <indexterm> | |
3399 | <primary>ROnly field in volume header</primary> | |
3400 | </indexterm> | |
3401 | ||
3402 | <indexterm> | |
3403 | <primary>Backup field in volume header</primary> | |
3404 | </indexterm> | |
3405 | ||
3406 | <indexterm> | |
3407 | <primary>RClone field in volume header</primary> | |
3408 | </indexterm> | |
3409 | </listitem> | |
3410 | ||
3411 | <listitem> | |
3412 | <para>The volume ID numbers associated with the various versions of the volume: read/write | |
3413 | (<computeroutput>RWrite</computeroutput>), read-only (<computeroutput>ROnly</computeroutput>), backup | |
3414 | (<computeroutput>Backup</computeroutput>), and ReleaseClone (<computeroutput>RClone</computeroutput>). One of them | |
3415 | matches the volume ID number that appears on the first line of the volume's output. If the value in the | |
3416 | <computeroutput>RWrite</computeroutput>, <computeroutput>ROnly</computeroutput>, or | |
3417 | <computeroutput>Backup</computeroutput> field is <computeroutput>0</computeroutput> (zero), there is no volume of that | |
3418 | type. If there is currently no ReleaseClone, the <computeroutput>RClone</computeroutput> field does not appear at | |
3419 | all.</para> | |
3420 | ||
3421 | <indexterm> | |
3422 | <primary>volume quota</primary> | |
3423 | ||
3424 | <secondary>recorded in volume header</secondary> | |
3425 | </indexterm> | |
3426 | ||
3427 | <indexterm> | |
3428 | <primary>MaxQuota field in volume header</primary> | |
3429 | </indexterm> | |
3430 | </listitem> | |
3431 | ||
3432 | <listitem> | |
3433 | <para>The maximum space quota allotted to the read/write copy of the volume, expressed in kilobyte blocks in the | |
3434 | <computeroutput>MaxQuota</computeroutput> field.</para> | |
3435 | ||
3436 | <indexterm> | |
3437 | <primary>creation date</primary> | |
3438 | ||
3439 | <secondary>recorded in volume header</secondary> | |
3440 | </indexterm> | |
3441 | ||
3442 | <indexterm> | |
3443 | <primary>volume</primary> | |
3444 | ||
3445 | <secondary>Creation date in volume header</secondary> | |
3446 | </indexterm> | |
3447 | </listitem> | |
3448 | ||
3449 | <listitem> | |
3450 | <para>The date and time the volume was created, in the <computeroutput>Creation</computeroutput> field. If the volume | |
3451 | has been restored with the <emphasis role="bold">backup diskrestore</emphasis>, <emphasis role="bold">backup | |
3452 | volrestore</emphasis>, or <emphasis role="bold">vos restore</emphasis> command, this is the restore time.</para> | |
3453 | ||
3454 | <indexterm> | |
3455 | <primary>update date</primary> | |
3456 | ||
3457 | <secondary>recorded in volume header</secondary> | |
3458 | </indexterm> | |
3459 | ||
3460 | <indexterm> | |
3461 | <primary>volume</primary> | |
3462 | ||
3463 | <secondary>Last Update date in volume header</secondary> | |
3464 | </indexterm> | |
3465 | </listitem> | |
3466 | ||
3467 | <listitem> | |
3468 | <para>The date and time when the contents of the volume last changed, in the <computeroutput>Last | |
3469 | Update</computeroutput> field. For read-only and backup volumes, it matches the timestamp in the | |
3470 | <computeroutput>Creation</computeroutput> field.</para> | |
3471 | ||
3472 | <indexterm> | |
3473 | <primary>access</primary> | |
3474 | ||
3475 | <secondary>count, in volume header</secondary> | |
3476 | </indexterm> | |
3477 | ||
3478 | <indexterm> | |
3479 | <primary>volume</primary> | |
3480 | ||
3481 | <secondary>counter in header for number of accesses</secondary> | |
3482 | </indexterm> | |
3483 | </listitem> | |
3484 | ||
3485 | <listitem> | |
3486 | <para>The number of times the volume has been accessed for a fetch or store operation since the later of the two | |
3487 | following times: <itemizedlist> | |
3488 | <listitem> | |
3489 | <para>12:00 a.m. on the day the command is issued</para> | |
3490 | </listitem> | |
3491 | ||
3492 | <listitem> | |
3493 | <para>The last time the volume changed location</para> | |
3494 | </listitem> | |
3495 | </itemizedlist></para> | |
3496 | </listitem> | |
3497 | </itemizedlist></para> | |
3498 | ||
3499 | <para>An example of the output when the <emphasis role="bold">-long</emphasis> flag is included:</para> | |
3500 | ||
3501 | <programlisting> | |
3502 | % <emphasis role="bold">vos listvol fs2.example.com b -long</emphasis> | |
3503 | Total number of volumes on server fs2.example.com | |
3504 | partition /vicepb: 66 | |
3505 | . . . . . . | |
3506 | . . . . . . | |
3507 | user.pat 1969534536 RW 17518 K On-line | |
3508 | fs2.example.com /vicepb | |
3509 | RWrite 1969534536 ROnly 0 Backup 1969534538 | |
3510 | MaxQuota 20000 K | |
3511 | Creation Mon Jun 12 09:02:25 1989 | |
3512 | Last Update Thu Jan 4 17:39:34 1990 | |
3513 | 1573 accesses in the past day (i.e., vnode references) | |
3514 | user.pat.backup 1969534538 BK 17537 K On-line | |
3515 | fs2.example.com /vicepb | |
3516 | RWrite 1969534536 ROnly 0 Backup 1969534538 | |
3517 | MaxQuota 20000 K | |
3518 | Creation Fri Jan 5 06:37:59 1990 | |
3519 | Last Update Fri Jan 5 06:37:59 1990 | |
3520 | 0 accesses in the past day (i.e., vnode references) | |
3521 | . . . . . | |
3522 | . . . . . | |
3523 | Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0 | |
3524 | </programlisting> | |
3525 | ||
3526 | <para><emphasis role="bold">Output with the -extended Flag</emphasis></para> | |
3527 | ||
3528 | <indexterm> | |
3529 | <primary>vos commands</primary> | |
3530 | ||
3531 | <secondary>listvol</secondary> | |
3532 | ||
3533 | <tertiary>output with -extended flag</tertiary> | |
3534 | </indexterm> | |
3535 | ||
3536 | <para>When you include the <emphasis role="bold">-extended</emphasis> flag, the output for each volume includes all of the | |
3537 | information reported with the <emphasis role="bold">-long</emphasis> flag, plus two tables of statistics: <itemizedlist> | |
3538 | <listitem> | |
3539 | <para>The table labeled <computeroutput>Raw Read/Write Stats</computeroutput> table summarizes the number of times the | |
3540 | volume has been accessed for reading or writing.</para> | |
3541 | </listitem> | |
3542 | ||
3543 | <listitem> | |
3544 | <para>The table labeled <computeroutput>Writes Affecting Authorship</computeroutput> table contains information on | |
3545 | writes made to files and directories in the specified volume.</para> | |
3546 | </listitem> | |
3547 | </itemizedlist></para> | |
3548 | ||
3549 | <para>An example of the output when the <emphasis role="bold">-extended</emphasis> flag is included:</para> | |
3550 | ||
3551 | <programlisting> | |
3552 | % <emphasis role="bold">vos listvol fs3.example.com a -extended</emphasis> | |
3553 | common.bboards 1969535592 RW 23149 K used 9401 files On-line | |
3554 | fs3.example.com /vicepa | |
3555 | RWrite 1969535592 ROnly 0 Backup 1969535594 | |
3556 | MaxQuota 30000 K | |
3557 | Creation Mon Mar 8 14:26:05 1999 | |
3558 | Last Update Mon Apr 26 09:20:43 1999 | |
3559 | 11533 accesses in the past day (i.e., vnode references) | |
3560 | Raw Read/Write Stats | |
3561 | |-------------------------------------------| | |
3562 | | Same Network | Diff Network | | |
3563 | |----------|----------|----------|----------| | |
3564 | | Total | Auth | Total | Auth | | |
3565 | |----------|----------|----------|----------| | |
3566 | Reads | 151 | 151 | 1092 | 1068 | | |
3567 | Writes | 3 | 3 | 324 | 324 | | |
3568 | |-------------------------------------------| | |
3569 | Writes Affecting Authorship | |
3570 | |-------------------------------------------| | |
3571 | | File Authorship | Directory Authorship| | |
3572 | |----------|----------|----------|----------| | |
3573 | | Same | Diff | Same | Diff | | |
3574 | |----------|----------|----------|----------| | |
3575 | 0-60 sec | 92 | 0 | 100 | 4 | | |
3576 | 1-10 min | 1 | 0 | 14 | 6 | | |
3577 | 10min-1hr | 0 | 0 | 19 | 4 | | |
3578 | 1hr-1day | 1 | 0 | 13 | 0 | | |
3579 | 1day-1wk | 1 | 0 | 1 | 0 | | |
3580 | > 1wk | 0 | 0 | 0 | 0 | | |
3581 | |-------------------------------------------| | |
3582 | </programlisting> | |
3583 | </sect2> | |
3584 | ||
3585 | <sect2 id="HDRWQ221"> | |
3586 | <title>Displaying One Volume's VLDB Entry and Volume Header</title> | |
3587 | ||
3588 | <indexterm> | |
3589 | <primary>displaying</primary> | |
3590 | ||
3591 | <secondary>VLDB entry</secondary> | |
3592 | ||
3593 | <tertiary>with volume header</tertiary> | |
3594 | </indexterm> | |
3595 | ||
3596 | <indexterm> | |
3597 | <primary>displaying</primary> | |
3598 | ||
3599 | <secondary>VLDB entry with volume header</secondary> | |
3600 | </indexterm> | |
3601 | ||
3602 | <indexterm> | |
3603 | <primary>VLDB</primary> | |
3604 | ||
3605 | <secondary>displaying entry</secondary> | |
3606 | ||
3607 | <tertiary>with volume header</tertiary> | |
3608 | </indexterm> | |
3609 | ||
3610 | <indexterm> | |
3611 | <primary>entry in VLDB</primary> | |
3612 | ||
3613 | <secondary>displaying, with volume header</secondary> | |
3614 | </indexterm> | |
3615 | ||
3616 | <indexterm> | |
3617 | <primary>displaying</primary> | |
3618 | ||
3619 | <secondary>volume header</secondary> | |
3620 | ||
3621 | <tertiary>with VLDB entry</tertiary> | |
3622 | </indexterm> | |
3623 | ||
3624 | <indexterm> | |
3625 | <primary>displaying</primary> | |
3626 | ||
3627 | <secondary>volume header with VLDB entry</secondary> | |
3628 | </indexterm> | |
3629 | ||
3630 | <indexterm> | |
3631 | <primary>volume header</primary> | |
3632 | ||
3633 | <secondary>displaying</secondary> | |
3634 | ||
3635 | <tertiary>with VLDB entry</tertiary> | |
3636 | </indexterm> | |
3637 | ||
3638 | <para>The <emphasis role="bold">vos examine</emphasis> command displays information from both the VLDB and the volume header | |
3639 | for a single volume. There is some redundancy in the information from the two sources, which allows you to compare the VLDB | |
3640 | and volume header.</para> | |
3641 | ||
3642 | <para>Because the volume header for each version of a volume (read/write, read-only, and backup) is different, you can specify | |
3643 | which one to display. Include the <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> | |
3644 | extension on the volume name or ID argument as appropriate. The information from the VLDB is the same for all three | |
3645 | versions.</para> | |
3646 | ||
3647 | <indexterm> | |
3648 | <primary>commands</primary> | |
3649 | ||
3650 | <secondary>vos examine</secondary> | |
3651 | ||
3652 | <tertiary>basic instructions</tertiary> | |
3653 | </indexterm> | |
3654 | ||
3655 | <indexterm> | |
3656 | <primary>vos commands</primary> | |
3657 | ||
3658 | <secondary>examine</secondary> | |
3659 | ||
3660 | <tertiary>basic instructions</tertiary> | |
3661 | </indexterm> | |
3662 | </sect2> | |
3663 | ||
3664 | <sect2 id="HDRWQ222"> | |
3665 | <title>To display one volume's VLDB entry and volume header</title> | |
3666 | ||
3667 | <orderedlist> | |
3668 | <listitem> | |
3669 | <para>Issue the <emphasis role="bold">vos examine</emphasis> command. <programlisting> | |
3670 | % <emphasis role="bold">vos examine</emphasis> <<replaceable>volume name or ID</replaceable>> | |
3671 | </programlisting></para> | |
3672 | ||
3673 | <para>where <variablelist> | |
3674 | <varlistentry> | |
3675 | <term><emphasis role="bold">e</emphasis></term> | |
3676 | ||
3677 | <listitem> | |
3678 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para> | |
3679 | </listitem> | |
3680 | </varlistentry> | |
3681 | ||
3682 | <varlistentry> | |
3683 | <term><emphasis role="bold">volume name or ID</emphasis></term> | |
3684 | ||
3685 | <listitem> | |
3686 | <para>Identifies one volume either by its complete name or volume ID number. It can be a read/write, read-only, or | |
3687 | backup type. Use the <emphasis role="bold">.backup</emphasis> or <emphasis role="bold">.readonly</emphasis> | |
3688 | extension if appropriate.</para> | |
3689 | </listitem> | |
3690 | </varlistentry> | |
3691 | </variablelist></para> | |
3692 | </listitem> | |
3693 | </orderedlist> | |
3694 | ||
3695 | <para>The top part of the output displays the same information from a volume header as the <emphasis role="bold">vos | |
3696 | listvol</emphasis> command with the <emphasis role="bold">-long</emphasis> flag, as described following the instructions in | |
3697 | <link linkend="HDRWQ220">To display volume headers</link>. If you specify the read-only version of the volume and it exists at | |
3698 | more than one site, the output includes all of them. The bottom part of the output lists the same information from the VLDB as | |
3699 | the <emphasis role="bold">vos listvldb</emphasis> command, as described following the instructions in <link | |
3700 | linkend="HDRWQ218">To display VLDB entries</link>.</para> | |
3701 | ||
3702 | <para>Below is an example for a volume whose VLDB entry is currently locked.</para> | |
3703 | ||
3704 | <programlisting> | |
3705 | % <emphasis role="bold">vos examine user.terry</emphasis> | |
3706 | user.terry 536870981 RW 3459 K On-line | |
3707 | fs3.example.com /vicepa | |
3708 | Write 5360870981 ROnly 0 Backup 536870983 | |
3709 | MaxQuota 40000 K | |
3710 | Creation Mon Jun 12 15:22:06 1989 | |
3711 | Last Update Fri Jun 16 09:34:35 1989 | |
3712 | 5719 accesses in the past day (i.e., vnode references) | |
3713 | RWrite: 5360870981 Backup: 536870983 | |
3714 | number of sites -> 1 | |
3715 | server fs3.example.com partition /vicepa RW Site | |
3716 | Volume is currently LOCKED | |
3717 | </programlisting> | |
3718 | </sect2> | |
3719 | ||
3720 | <sect2 id="HDRWQ223"> | |
3721 | <title>Displaying the Name or Location of the Volume that Contains a File</title> | |
3722 | ||
3723 | <para>This section explains how to learn the name, volume ID number, or location of the volume that contains a file or | |
3724 | directory.</para> | |
3725 | ||
3726 | <para>You can also use one piece of information about a volume (for example, its name) to obtain other information about it | |
3727 | (for example, its location). The following list points you to the relevant instructions: <itemizedlist> | |
3728 | <indexterm> | |
3729 | <primary>translating</primary> | |
3730 | ||
3731 | <secondary>volume name to ID number</secondary> | |
3732 | </indexterm> | |
3733 | ||
3734 | <indexterm> | |
3735 | <primary>learning</primary> | |
3736 | ||
3737 | <secondary>volume ID</secondary> | |
3738 | ||
3739 | <tertiary>given volume name</tertiary> | |
3740 | </indexterm> | |
3741 | ||
3742 | <indexterm> | |
3743 | <primary>volume name</primary> | |
3744 | ||
3745 | <secondary>translating</secondary> | |
3746 | ||
3747 | <tertiary>to volume ID number</tertiary> | |
3748 | </indexterm> | |
3749 | ||
3750 | <indexterm> | |
3751 | <primary>volume ID number</primary> | |
3752 | ||
3753 | <secondary>learning</secondary> | |
3754 | ||
3755 | <tertiary>from volume name</tertiary> | |
3756 | </indexterm> | |
3757 | ||
3758 | <indexterm> | |
3759 | <primary>vos commands</primary> | |
3760 | ||
3761 | <secondary>examine</secondary> | |
3762 | ||
3763 | <tertiary>to learn volume ID</tertiary> | |
3764 | </indexterm> | |
3765 | ||
3766 | <indexterm> | |
3767 | <primary>translating</primary> | |
3768 | ||
3769 | <secondary>volume ID number to name</secondary> | |
3770 | </indexterm> | |
3771 | ||
3772 | <indexterm> | |
3773 | <primary>learning</primary> | |
3774 | ||
3775 | <secondary>volume name</secondary> | |
3776 | ||
3777 | <tertiary>given volume ID number</tertiary> | |
3778 | </indexterm> | |
3779 | ||
3780 | <indexterm> | |
3781 | <primary>volume name</primary> | |
3782 | ||
3783 | <secondary>learning</secondary> | |
3784 | ||
3785 | <tertiary>from volume ID number</tertiary> | |
3786 | </indexterm> | |
3787 | ||
3788 | <indexterm> | |
3789 | <primary>volume ID number</primary> | |
3790 | ||
3791 | <secondary>translating</secondary> | |
3792 | ||
3793 | <tertiary>to volume name</tertiary> | |
3794 | </indexterm> | |
3795 | ||
3796 | <indexterm> | |
3797 | <primary>vos commands</primary> | |
3798 | ||
3799 | <secondary>examine</secondary> | |
3800 | ||
3801 | <tertiary>to learn volume name</tertiary> | |
3802 | </indexterm> | |
3803 | ||
3804 | <listitem> | |
3805 | <para>To use a volume's name to learn the volume ID numbers of all its existing versions, use the <emphasis | |
3806 | role="bold">vos examine</emphasis> command as described in <link linkend="HDRWQ222">To display one volume's VLDB entry | |
3807 | and volume header</link>.</para> | |
3808 | ||
3809 | <para>You can also use the command to learn a volume's name by providing its ID number.</para> | |
3810 | </listitem> | |
3811 | ||
3812 | <listitem> | |
3813 | <para>To use a volume's name or ID number to learn its location, use the <emphasis role="bold">vos listvldb</emphasis> | |
3814 | command as described in <link linkend="HDRWQ218">To display VLDB entries</link>.</para> | |
3815 | ||
3816 | <indexterm> | |
3817 | <primary>translating</primary> | |
3818 | ||
3819 | <secondary>volume name/ID number to volume location</secondary> | |
3820 | </indexterm> | |
3821 | ||
3822 | <indexterm> | |
3823 | <primary>learning</primary> | |
3824 | ||
3825 | <secondary>volume location</secondary> | |
3826 | ||
3827 | <tertiary>given volume name/ID number</tertiary> | |
3828 | </indexterm> | |
3829 | ||
3830 | <indexterm> | |
3831 | <primary>volume name</primary> | |
3832 | ||
3833 | <secondary>translating</secondary> | |
3834 | ||
3835 | <tertiary>to volume location</tertiary> | |
3836 | </indexterm> | |
3837 | ||
3838 | <indexterm> | |
3839 | <primary>volume ID number</primary> | |
3840 | ||
3841 | <secondary>translating</secondary> | |
3842 | ||
3843 | <tertiary>to volume location</tertiary> | |
3844 | </indexterm> | |
3845 | ||
3846 | <indexterm> | |
3847 | <primary>volume location</primary> | |
3848 | ||
3849 | <secondary>learning from volume name/ID number</secondary> | |
3850 | </indexterm> | |
3851 | ||
3852 | <indexterm> | |
3853 | <primary>vos commands</primary> | |
3854 | ||
3855 | <secondary>listvldb</secondary> | |
3856 | ||
3857 | <tertiary>to learn volume location</tertiary> | |
3858 | </indexterm> | |
3859 | </listitem> | |
3860 | </itemizedlist></para> | |
3861 | ||
3862 | <indexterm> | |
3863 | <primary>translating</primary> | |
3864 | ||
3865 | <secondary>directory/file name to volume name</secondary> | |
3866 | </indexterm> | |
3867 | ||
3868 | <indexterm> | |
3869 | <primary>learning</primary> | |
3870 | ||
3871 | <secondary>volume name</secondary> | |
3872 | ||
3873 | <tertiary>given directory/file name</tertiary> | |
3874 | </indexterm> | |
3875 | ||
3876 | <indexterm> | |
3877 | <primary>directory/file name</primary> | |
3878 | ||
3879 | <secondary>translating to volume name</secondary> | |
3880 | </indexterm> | |
3881 | ||
3882 | <indexterm> | |
3883 | <primary>volume name</primary> | |
3884 | ||
3885 | <secondary>learning</secondary> | |
3886 | ||
3887 | <tertiary>from directory/file name</tertiary> | |
3888 | </indexterm> | |
3889 | ||
3890 | <indexterm> | |
3891 | <primary>commands</primary> | |
3892 | ||
3893 | <secondary>fs listquota</secondary> | |
3894 | </indexterm> | |
3895 | ||
3896 | <indexterm> | |
3897 | <primary>fs commands</primary> | |
3898 | ||
3899 | <secondary>listquota</secondary> | |
3900 | </indexterm> | |
3901 | ||
3902 | <sect3 id="HDRWQ224"> | |
3903 | <title>To display the name of the volume that contains a file</title> | |
3904 | ||
3905 | <orderedlist> | |
3906 | <listitem> | |
3907 | <para>Issue the <emphasis role="bold">fs listquota</emphasis> command. <programlisting> | |
3908 | % <emphasis role="bold">fs listquota</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
3909 | </programlisting></para> | |
3910 | ||
3911 | <para>where <variablelist> | |
3912 | <varlistentry> | |
3913 | <term><emphasis role="bold">lq</emphasis></term> | |
3914 | ||
3915 | <listitem> | |
3916 | <para>Is an acceptable alias for <emphasis role="bold">listquota</emphasis>(and <emphasis | |
3917 | role="bold">listq</emphasis> the shortest acceptable abbreviation).</para> | |
3918 | </listitem> | |
3919 | </varlistentry> | |
3920 | ||
3921 | <varlistentry> | |
3922 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
3923 | ||
3924 | <listitem> | |
3925 | <para>Names a directory or file housed in the volume for which to display the name. Partial pathnames are | |
3926 | interpreted relative to the current working directory, which is the default if this argument is omitted.</para> | |
3927 | </listitem> | |
3928 | </varlistentry> | |
3929 | </variablelist></para> | |
3930 | </listitem> | |
3931 | </orderedlist> | |
3932 | ||
3933 | <para>The following is an example of the output:</para> | |
3934 | ||
3935 | <programlisting> | |
3936 | % <emphasis role="bold">fs listquota /afs/example.com/usr/terry</emphasis> | |
3937 | Volume Name Quota Used % Used Partition | |
3938 | user.terry 15000 5071 34% 86% | |
3939 | </programlisting> | |
3940 | ||
3941 | <indexterm> | |
3942 | <primary>translating</primary> | |
3943 | ||
3944 | <secondary>directory/file name to volume ID number</secondary> | |
3945 | </indexterm> | |
3946 | ||
3947 | <indexterm> | |
3948 | <primary>learning</primary> | |
3949 | ||
3950 | <secondary>volume ID</secondary> | |
3951 | ||
3952 | <tertiary>given directory/file name</tertiary> | |
3953 | </indexterm> | |
3954 | ||
3955 | <indexterm> | |
3956 | <primary>directory/file name</primary> | |
3957 | ||
3958 | <secondary>translating to volume ID number</secondary> | |
3959 | </indexterm> | |
3960 | ||
3961 | <indexterm> | |
3962 | <primary>volume ID number</primary> | |
3963 | ||
3964 | <secondary>learning from directory/file name</secondary> | |
3965 | </indexterm> | |
3966 | ||
3967 | <indexterm> | |
3968 | <primary>commands</primary> | |
3969 | ||
3970 | <secondary>fs examine</secondary> | |
3971 | </indexterm> | |
3972 | ||
3973 | <indexterm> | |
3974 | <primary>fs commands</primary> | |
3975 | ||
3976 | <secondary>examine</secondary> | |
3977 | </indexterm> | |
3978 | </sect3> | |
3979 | ||
3980 | <sect3 id="HDRWQ225"> | |
3981 | <title>To display the ID number of the volume that contains a file</title> | |
3982 | ||
3983 | <orderedlist> | |
3984 | <listitem> | |
3985 | <para>Issue the <emphasis role="bold">fs examine</emphasis> command. <programlisting> | |
3986 | % <emphasis role="bold">fs examine</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
3987 | </programlisting></para> | |
3988 | ||
3989 | <para>where <variablelist> | |
3990 | <varlistentry> | |
3991 | <term><emphasis role="bold">exa</emphasis></term> | |
3992 | ||
3993 | <listitem> | |
3994 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para> | |
3995 | </listitem> | |
3996 | </varlistentry> | |
3997 | ||
3998 | <varlistentry> | |
3999 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
4000 | ||
4001 | <listitem> | |
4002 | <para>Names a directory or file housed in the volume for which to display the volume ID. Partial pathnames are | |
4003 | interpreted relative to the current working directory, which is the default if this argument is omitted.</para> | |
4004 | </listitem> | |
4005 | </varlistentry> | |
4006 | </variablelist></para> | |
4007 | </listitem> | |
4008 | </orderedlist> | |
4009 | ||
4010 | <para>The following example illustrates how the output reports the volume ID number in the | |
4011 | <computeroutput>vid</computeroutput> field.</para> | |
4012 | ||
4013 | <programlisting> | |
4014 | % <emphasis role="bold">fs examine /afs/example.com/usr/terry</emphasis> | |
4015 | Volume status for vid = 50489902 named user.terry | |
4016 | Current maximum quota is 15000 | |
4017 | Current blocks used are 5073 | |
4018 | The partition has 46383 blocks available out of 333305 | |
4019 | </programlisting> | |
4020 | ||
4021 | <note> | |
4022 | <para>The partition-related statistics in this command's output do not always agree with the corresponding values in the | |
4023 | output of the standard UNIX <emphasis role="bold">df</emphasis> command. The statistics reported by this command can be up | |
4024 | to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency. Also, on | |
4025 | some operating systems, the <emphasis role="bold">df</emphasis> command's report of partition size includes reserved space | |
4026 | not included in this command's calculation, and so is likely to be about 10% larger.</para> | |
4027 | </note> | |
4028 | ||
4029 | <indexterm> | |
4030 | <primary>translating</primary> | |
4031 | ||
4032 | <secondary>directory/file name to volume location</secondary> | |
4033 | </indexterm> | |
4034 | ||
4035 | <indexterm> | |
4036 | <primary>learning</primary> | |
4037 | ||
4038 | <secondary>volume location</secondary> | |
4039 | ||
4040 | <tertiary>given directory/file name</tertiary> | |
4041 | </indexterm> | |
4042 | ||
4043 | <indexterm> | |
4044 | <primary>directory/file name</primary> | |
4045 | ||
4046 | <secondary>translating to volume location</secondary> | |
4047 | </indexterm> | |
4048 | ||
4049 | <indexterm> | |
4050 | <primary>volume location</primary> | |
4051 | ||
4052 | <secondary>learning from directory/file name</secondary> | |
4053 | </indexterm> | |
4054 | ||
4055 | <indexterm> | |
4056 | <primary>volume</primary> | |
4057 | ||
4058 | <secondary>location</secondary> | |
4059 | ||
4060 | <see>volume location</see> | |
4061 | </indexterm> | |
4062 | ||
4063 | <indexterm> | |
4064 | <primary>commands</primary> | |
4065 | ||
4066 | <secondary>fs whereis</secondary> | |
4067 | </indexterm> | |
4068 | ||
4069 | <indexterm> | |
4070 | <primary>fs commands</primary> | |
4071 | ||
4072 | <secondary>whereis</secondary> | |
4073 | </indexterm> | |
4074 | </sect3> | |
4075 | ||
4076 | <sect3 id="Header_242"> | |
4077 | <title>To display the location of the volume that contains a file</title> | |
4078 | ||
4079 | <orderedlist> | |
4080 | <listitem> | |
4081 | <para>Issue the <emphasis role="bold">fs whereis</emphasis> command to display the name of the file server machine that | |
4082 | houses the volume containing a file or directory. <programlisting> | |
4083 | % <emphasis role="bold">fs whereis</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
4084 | </programlisting></para> | |
4085 | ||
4086 | <para>where <variablelist> | |
4087 | <varlistentry> | |
4088 | <term><emphasis role="bold">whe</emphasis></term> | |
4089 | ||
4090 | <listitem> | |
4091 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">whereis</emphasis>.</para> | |
4092 | </listitem> | |
4093 | </varlistentry> | |
4094 | ||
4095 | <varlistentry> | |
4096 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
4097 | ||
4098 | <listitem> | |
4099 | <para>Names a directory or file for which to report the location. Partial pathnames are interpreted relative to | |
4100 | the current working directory, which is the default if this argument is omitted.</para> | |
4101 | </listitem> | |
4102 | </varlistentry> | |
4103 | </variablelist></para> | |
4104 | ||
4105 | <para>The output displays the file server machine that houses the volume containing the file, as in the following | |
4106 | example:</para> | |
4107 | ||
4108 | <programlisting> | |
4109 | % <emphasis role="bold">fs whereis /afs/example.com/user/terry</emphasis> | |
4110 | File /afs/example.com/usr/terry is on host fs2.example.com | |
4111 | </programlisting> | |
4112 | </listitem> | |
4113 | ||
4114 | <listitem> | |
4115 | <para>If you also want to know which partition houses the volume, first issue the <emphasis role="bold">fs | |
4116 | listquota</emphasis> command to display the volume's name. For complete syntax, see <link linkend="HDRWQ224">To display | |
4117 | the name of the volume that contains a file</link>. <programlisting> | |
4118 | % <emphasis role="bold">fs listquota</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
4119 | </programlisting></para> | |
4120 | ||
4121 | <para>Then issue the <emphasis role="bold">vos listvldb</emphasis> command, providing the volume name as the volume name | |
4122 | or ID argument. For complete syntax and a description of the output, see <link linkend="HDRWQ218">To display VLDB | |
4123 | entries</link>.</para> | |
4124 | ||
4125 | <programlisting> | |
4126 | % <emphasis role="bold">vos listvldb</emphasis> <<replaceable>volume name or ID</replaceable>> | |
4127 | </programlisting> | |
4128 | </listitem> | |
4129 | </orderedlist> | |
4130 | </sect3> | |
4131 | </sect2> | |
4132 | </sect1> | |
4133 | ||
4134 | <sect1 id="HDRWQ226"> | |
4135 | <title>Moving Volumes</title> | |
4136 | ||
4137 | <indexterm> | |
4138 | <primary>moving</primary> | |
4139 | ||
4140 | <secondary>volume</secondary> | |
4141 | </indexterm> | |
4142 | ||
4143 | <indexterm> | |
4144 | <primary>volume</primary> | |
4145 | ||
4146 | <secondary>moving</secondary> | |
4147 | </indexterm> | |
4148 | ||
4149 | <para>There are three main reasons to move volumes: <itemizedlist> | |
4150 | <listitem> | |
4151 | <para>To place volumes on other partitions or machines temporarily while repairing or replacing a disk or file server | |
4152 | machine.</para> | |
4153 | </listitem> | |
4154 | ||
4155 | <listitem> | |
4156 | <para><indexterm> | |
4157 | <primary>disk partition</primary> | |
4158 | ||
4159 | <secondary>moving volumes to reduce overcrowding</secondary> | |
4160 | </indexterm> <indexterm> | |
4161 | <primary>overcrowding of disk partition</primary> | |
4162 | ||
4163 | <secondary>moving volumes to reduce</secondary> | |
4164 | </indexterm> <indexterm> | |
4165 | <primary>overcrowding of disk partition</primary> | |
4166 | ||
4167 | <secondary>effect on users</secondary> | |
4168 | </indexterm> <indexterm> | |
4169 | <primary>failure</primary> | |
4170 | ||
4171 | <secondary>of file storage due to full partition</secondary> | |
4172 | </indexterm> <indexterm> | |
4173 | <primary>file storage</primary> | |
4174 | ||
4175 | <secondary>failed due to partition crowding</secondary> | |
4176 | </indexterm> To free space on a partition that is becoming overcrowded. One symptom of overcrowding is that users cannot | |
4177 | to save files even though the relevant volume is below its quota. The following error message confirms the problem: | |
4178 | <programlisting> | |
4179 | afs: failed to store file (partition full) | |
4180 | </programlisting></para> | |
4181 | ||
4182 | <para>You can track available space on AFS server partitions by using the <emphasis role="bold">scout</emphasis> or | |
4183 | <emphasis role="bold">afsmonitor</emphasis> programs described in <link linkend="HDRWQ323">Monitoring and Auditing AFS | |
4184 | Performance</link>.</para> | |
4185 | </listitem> | |
4186 | ||
4187 | <listitem> | |
4188 | <para>A file server machine is becoming overloaded because it houses many more volumes than other machines of the same | |
4189 | size, or has volumes with more popular files in them.</para> | |
4190 | </listitem> | |
4191 | </itemizedlist></para> | |
4192 | ||
4193 | <indexterm> | |
4194 | <primary>read/write volume</primary> | |
4195 | ||
4196 | <secondary>moving</secondary> | |
4197 | </indexterm> | |
4198 | ||
4199 | <indexterm> | |
4200 | <primary>backup volume</primary> | |
4201 | ||
4202 | <secondary>removed by read/write move</secondary> | |
4203 | </indexterm> | |
4204 | ||
4205 | <para>To move a read/write volume, use the <emphasis role="bold">vos move</emphasis> command as described in the following | |
4206 | instructions. Before attempting to move the volume, the <emphasis role="bold">vos</emphasis> command interpreter verifies that | |
4207 | there is enough free space for it on the destination partition. If not, it does not attempt the move operation and prints the | |
4208 | following message.</para> | |
4209 | ||
4210 | <programlisting> | |
4211 | vos: no space on target partition destination_part to move volume volume | |
4212 | </programlisting> | |
4213 | ||
4214 | <para>To move a read-only volume, you actually remove the volume from the current site by issuing the <emphasis role="bold">vos | |
4215 | remove</emphasis> command as described in <link linkend="HDRWQ236">To remove a volume and unmount it</link>. Then define a new | |
4216 | site and release the volume to it by issuing the <emphasis role="bold">vos addsite</emphasis> and <emphasis role="bold">vos | |
4217 | release</emphasis> commands as described in <link linkend="HDRWQ194">To replicate a read/write volume (create a read-only | |
4218 | volume)</link>.</para> | |
4219 | ||
4220 | <indexterm> | |
4221 | <primary>read-only volume</primary> | |
4222 | ||
4223 | <secondary>moving</secondary> | |
4224 | </indexterm> | |
4225 | ||
4226 | <indexterm> | |
4227 | <primary>backup volume</primary> | |
4228 | ||
4229 | <secondary>moving</secondary> | |
4230 | </indexterm> | |
4231 | ||
4232 | <para>A backup volume always resides at the same site as its read/write source volume, so you cannot move a backup volume except | |
4233 | as part of moving the read/write source. The <emphasis role="bold">vos move</emphasis> command automatically deletes the backup | |
4234 | version when you move a read/write volume. To create a new backup volume at the new site as soon as the move operation | |
4235 | completes, issue the <emphasis role="bold">vos backup</emphasis> command as described in <link linkend="HDRWQ205">To create and | |
4236 | mount a backup volume</link>.</para> | |
4237 | ||
4238 | <indexterm> | |
4239 | <primary>commands</primary> | |
4240 | ||
4241 | <secondary>vos move</secondary> | |
4242 | ||
4243 | <tertiary>basic instructions</tertiary> | |
4244 | </indexterm> | |
4245 | ||
4246 | <indexterm> | |
4247 | <primary>vos commands</primary> | |
4248 | ||
4249 | <secondary>move</secondary> | |
4250 | ||
4251 | <tertiary>basic instructions</tertiary> | |
4252 | </indexterm> | |
4253 | ||
4254 | <sect2 id="Header_244"> | |
4255 | <title>To move a read/write volume</title> | |
4256 | ||
4257 | <orderedlist> | |
4258 | <listitem> | |
4259 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
4260 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
4261 | display the users in the UserList file</link>. <programlisting> | |
4262 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
4263 | </programlisting></para> | |
4264 | </listitem> | |
4265 | ||
4266 | <listitem> | |
4267 | <para>Issue the <emphasis role="bold">vos move</emphasis> command to move the volume. Type it on a single line; it appears | |
4268 | on multiple lines here only for legibility. <programlisting> | |
4269 | % <emphasis role="bold">vos move</emphasis> <<replaceable>volume name or ID</replaceable>> \ <<replaceable>machine name on source</replaceable>> | |
4270 | <<replaceable>partition name on source </replaceable>> \ <<replaceable>machine name on destination</replaceable>> <partition name on | |
4271 | destination> | |
4272 | </programlisting></para> | |
4273 | ||
4274 | <para>where <variablelist> | |
4275 | <varlistentry> | |
4276 | <term><emphasis role="bold">m</emphasis></term> | |
4277 | ||
4278 | <listitem> | |
4279 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">move</emphasis>.</para> | |
4280 | </listitem> | |
4281 | </varlistentry> | |
4282 | ||
4283 | <varlistentry> | |
4284 | <term><emphasis role="bold">volume name or ID</emphasis></term> | |
4285 | ||
4286 | <listitem> | |
4287 | <para>Specifies the name or volume ID number of the read/write volume to move.</para> | |
4288 | </listitem> | |
4289 | </varlistentry> | |
4290 | ||
4291 | <varlistentry> | |
4292 | <term><emphasis role="bold">machine name on source</emphasis></term> | |
4293 | ||
4294 | <listitem> | |
4295 | <para>Names the file server machine currently housing the volume.</para> | |
4296 | </listitem> | |
4297 | </varlistentry> | |
4298 | ||
4299 | <varlistentry> | |
4300 | <term><emphasis role="bold">partition name on source</emphasis></term> | |
4301 | ||
4302 | <listitem> | |
4303 | <para>Names the partition currently housing the volume.</para> | |
4304 | </listitem> | |
4305 | </varlistentry> | |
4306 | ||
4307 | <varlistentry> | |
4308 | <term><emphasis role="bold">machine name on destination</emphasis></term> | |
4309 | ||
4310 | <listitem> | |
4311 | <para>Names the file server machine to which to move the volume.</para> | |
4312 | </listitem> | |
4313 | </varlistentry> | |
4314 | ||
4315 | <varlistentry> | |
4316 | <term><emphasis role="bold">partition name on destination</emphasis></term> | |
4317 | ||
4318 | <listitem> | |
4319 | <para>Names the partition to which to move the volume.</para> | |
4320 | </listitem> | |
4321 | </varlistentry> | |
4322 | </variablelist></para> | |
4323 | ||
4324 | <note> | |
4325 | <para>It is best not to halt a <emphasis role="bold">vos move</emphasis> operation before it completes, because parts of | |
4326 | the volume can be left on both the source and destination machines. For more information, see the command's reference | |
4327 | page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para> | |
4328 | </note> | |
4329 | </listitem> | |
4330 | ||
4331 | <listitem> | |
4332 | <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">vos listvldb</emphasis> command to | |
4333 | confirm the success of the move. Complete instructions appear in <link linkend="HDRWQ218">To display VLDB entries</link>. | |
4334 | <programlisting> | |
4335 | % <emphasis role="bold">vos listvldb</emphasis> <<replaceable>volume name or ID</replaceable>> | |
4336 | </programlisting></para> | |
4337 | </listitem> | |
4338 | ||
4339 | <listitem> | |
4340 | <para>If a backup version existed at the read/write volume's previous site, create a new backup at the new site by issuing | |
4341 | the <emphasis role="bold">vos backup</emphasis> command, which is fully described in <link linkend="HDRWQ205">To create | |
4342 | and mount a backup volume</link>. <programlisting> | |
4343 | % <emphasis role="bold">vos backup</emphasis> <<replaceable>volume name or ID</replaceable>> | |
4344 | </programlisting></para> | |
4345 | </listitem> | |
4346 | </orderedlist> | |
4347 | </sect2> | |
4348 | </sect1> | |
4349 | ||
4350 | <sect1 id="HDRWQ227"> | |
4351 | <title>Synchronizing the VLDB and Volume Headers</title> | |
4352 | ||
4353 | <indexterm> | |
4354 | <primary>VLDB</primary> | |
4355 | ||
4356 | <secondary>synchronizing with volume headers</secondary> | |
4357 | </indexterm> | |
4358 | ||
4359 | <indexterm> | |
4360 | <primary>volume header</primary> | |
4361 | ||
4362 | <secondary>synchronizing with VLDB</secondary> | |
4363 | </indexterm> | |
4364 | ||
4365 | <indexterm> | |
4366 | <primary>volume</primary> | |
4367 | ||
4368 | <secondary>synchronizing VLDB and volume header</secondary> | |
4369 | </indexterm> | |
4370 | ||
4371 | <para>AFS can provide transparent file access because the Volume Location Database (VLDB) constantly tracks volume locations. | |
4372 | When the Cache Manager needs a file, it contacts the Volume Location (VL) Server, which reads the VLDB for the current location | |
4373 | of the volume containing the file. Therefore, the VLDB must accurately reflect the state of volumes on the file server machines | |
4374 | at all times. The Volume Server and VL Server automatically update a volume's VLDB entry when its status changes during a | |
4375 | <emphasis role="bold">vos</emphasis> operation, by performing the following series of steps. <orderedlist> | |
4376 | <listitem id="LIWQ228"> | |
4377 | <para>The VL Server locks the VLDB entry. The lock advises other operations not to manipulate any | |
4378 | of the volume versions (read/write, read-only, or backup), which prevents the inconsistency that can result from multiple | |
4379 | simultaneous operations.</para> | |
4380 | </listitem> | |
4381 | ||
4382 | <listitem id="LIWQ229"> | |
4383 | <para><indexterm> | |
4384 | <primary>intention flag in VLDB entry</primary> | |
4385 | </indexterm> <indexterm> | |
4386 | <primary>VLDB</primary> | |
4387 | ||
4388 | <secondary>intention flag set by VL Server</secondary> | |
4389 | </indexterm> | |
4390 | The VL Server sets an <emphasis>intention flag</emphasis> in the VLDB entry that | |
4391 | indicates the kind of operation to be performed. This flag never appears in VLDB listings because it is for internal use | |
4392 | only. In case the operation terminates prematurely, this flag tells the Salvager which operation was interrupted. (The | |
4393 | Salvager then determines the steps necessary either to complete the operation or return the volume to a previous | |
4394 | consistent state. For more information on salvaging, see <link linkend="HDRWQ232">Salvaging Volumes</link>.)</para> | |
4395 | </listitem> | |
4396 | ||
4397 | <listitem id="LIWQ230"> | |
4398 | <para>The Volume Server manipulates the volume. It usually sets the | |
4399 | <computeroutput>Off-line</computeroutput> flag in the volume header, which makes the volume inaccessible to the File | |
4400 | Server and other Volume Server operations during the manipulation. When the operation completes, the volume is again | |
4401 | marked <computeroutput>On-line</computeroutput>.</para> | |
4402 | </listitem> | |
4403 | ||
4404 | <listitem id="LIWQ231"> | |
4405 | <para>The VL Server records any changes resulting from the operation in the VLDB entry. Once the | |
4406 | operation is complete, it removes the intention flag set in Step <link linkend="LIWQ229">2</link>and releases the lock set | |
4407 | in Step <link linkend="LIWQ228">1</link>.</para> | |
4408 | </listitem> | |
4409 | </orderedlist></para> | |
4410 | ||
4411 | <para>If a <emphasis role="bold">vos</emphasis> operation fails while the Volume Server is manipulating the volume | |
4412 | (corresponding to Step <link linkend="LIWQ230">3</link>), the volume can be left in an intermediate state, which is termed | |
4413 | <emphasis>corruption</emphasis>. In this case, the <computeroutput>Off-line</computeroutput> or <computeroutput>Off-line**needs | |
4414 | salvage**</computeroutput> marker usually appears at the end of the first line of output from the <emphasis role="bold">vos | |
4415 | examine</emphasis> command. To repair the corruption, run the Salvager before attempting to resynchronize the VLDB and volume | |
4416 | headers. For salvaging instructions, see <link linkend="HDRWQ232">Salvaging Volumes</link>.</para> | |
4417 | ||
4418 | <para>More commonly, an interruption while flags are being set or removed (corresponding to Step <link | |
4419 | linkend="LIWQ228">1</link>, Step <link linkend="LIWQ229">2</link>, or Step <link linkend="LIWQ231">4</link>) causes a | |
4420 | discrepancy between the VLDB and volume headers. To resynchronize the VLDB and volumes, use the <emphasis role="bold">vos | |
4421 | syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis> commands. To achieve complete VLDB consistency, it is best | |
4422 | to run the <emphasis role="bold">vos syncvldb</emphasis> command on all file server machines in the cell, and then run the | |
4423 | <emphasis role="bold">vos syncserv</emphasis> command on all file server machines in the cell.</para> | |
4424 | ||
4425 | <indexterm> | |
4426 | <primary>symptoms</primary> | |
4427 | ||
4428 | <secondary>of VLDB/volume header desynchronization</secondary> | |
4429 | </indexterm> | |
4430 | ||
4431 | <indexterm> | |
4432 | <primary>desynchronization of VLDB/volume headers</primary> | |
4433 | ||
4434 | <secondary>symptoms of</secondary> | |
4435 | </indexterm> | |
4436 | ||
4437 | <indexterm> | |
4438 | <primary>synchrony of VLDB and volume headers</primary> | |
4439 | ||
4440 | <secondary>symptoms of lack of</secondary> | |
4441 | </indexterm> | |
4442 | ||
4443 | <para>There are several symptoms that indicate a volume operation failed: <itemizedlist> | |
4444 | <listitem> | |
4445 | <para>Error messages on the standard error stream or in server process log files indicate that an operation terminated | |
4446 | abnormally. Perhaps you had to halt the operation before it completed (for instance, by using a signal such as <emphasis | |
4447 | role="bold">Ctrl-c</emphasis>), or a file server machine or server process was not functioning when the operation ran. To | |
4448 | determine if a machine or process is still not functioning, issue the <emphasis role="bold">bos status</emphasis> command | |
4449 | as described in <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>.</para> | |
4450 | </listitem> | |
4451 | ||
4452 | <listitem> | |
4453 | <para>A subsequent <emphasis role="bold">vos</emphasis> operation fails because a previous failure left a VLDB entry | |
4454 | locked. Sometimes an error message reports that a volume is locked. To display a list of locked volumes, use the <emphasis | |
4455 | role="bold">-locked</emphasis> flag on the <emphasis role="bold">vos listvldb</emphasis> command as described in <link | |
4456 | linkend="HDRWQ217">Displaying VLDB Entries</link>.</para> | |
4457 | ||
4458 | <para>If the only problem with a volume is that its VLDB entry is locked, you probably do not need to synchronize the | |
4459 | entire VLDB. Instead use the <emphasis role="bold">vos unlock</emphasis> or <emphasis role="bold">vos | |
4460 | unlockvldb</emphasis> command to unlock the entry, as described in <link linkend="HDRWQ247">Unlocking and Locking VLDB | |
4461 | Entries</link>.</para> | |
4462 | </listitem> | |
4463 | ||
4464 | <listitem> | |
4465 | <para>A subsequent <emphasis role="bold">vos</emphasis> operation fails because a previous failure left a volume marked as | |
4466 | offline. To check a volume's current status, check the first line of output from the <emphasis role="bold">vos | |
4467 | examine</emphasis> command as described in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume | |
4468 | Header</link>.</para> | |
4469 | </listitem> | |
4470 | </itemizedlist></para> | |
4471 | ||
4472 | <indexterm> | |
4473 | <primary>synchrony of VLDB and volume headers</primary> | |
4474 | ||
4475 | <secondary>restoring</secondary> | |
4476 | </indexterm> | |
4477 | ||
4478 | <indexterm> | |
4479 | <primary>restoring</primary> | |
4480 | ||
4481 | <secondary>synchrony of VLDB and volume headers</secondary> | |
4482 | </indexterm> | |
4483 | ||
4484 | <indexterm> | |
4485 | <primary>desynchronization of VLDB/volume headers</primary> | |
4486 | ||
4487 | <secondary>fixing</secondary> | |
4488 | </indexterm> | |
4489 | ||
4490 | <indexterm> | |
4491 | <primary>Salvager</primary> | |
4492 | ||
4493 | <secondary>running before VLDB/volume header resynchronization</secondary> | |
4494 | </indexterm> | |
4495 | ||
4496 | <indexterm> | |
4497 | <primary>vos commands</primary> | |
4498 | ||
4499 | <secondary>syncvldb</secondary> | |
4500 | ||
4501 | <tertiary>effect</tertiary> | |
4502 | </indexterm> | |
4503 | ||
4504 | <para>The <emphasis role="bold">vos syncvldb</emphasis> command corrects the information in the Volume Location Database (VLDB) | |
4505 | either about all volumes housed on a file server machine, about the volumes on just one partition, or about a single volume. If | |
4506 | checking about one or more partitions, the command contacts the Volume Server to obtain a list of the volumes that actually | |
4507 | reside on each partition. It then obtains the VLDB entry for each volume from the VL Server. It changes the VLDB entry as | |
4508 | necessary to reflect the state of the volume on the partition. For example, it creates or updates a VLDB entry when it finds a | |
4509 | volume for which the VLDB entry is missing or incomplete. However, if there is already a VLDB entry that defines a different | |
4510 | location for the volume, or there are irreconcilable conflicts with other VLDB entries, it instead writes a message about the | |
4511 | conflict to the standard error stream. The command never removes volumes from the file server machine.</para> | |
4512 | ||
4513 | <para>When checking a single volume's VLDB entry, the command also automatically performs the operations invoked by the | |
4514 | <emphasis role="bold">vos syncserv</emphasis> command: it not only verifies that the VLDB entry is correct for the specified | |
4515 | volume type (read/write, backup, or read-only), but also checks that any related volume types mentioned in the VLDB entry | |
4516 | actually exist at the site listed in the entry.</para> | |
4517 | ||
4518 | <indexterm> | |
4519 | <primary>vos commands</primary> | |
4520 | ||
4521 | <secondary>syncserv</secondary> | |
4522 | ||
4523 | <tertiary>effect</tertiary> | |
4524 | </indexterm> | |
4525 | ||
4526 | <para>The <emphasis role="bold">vos syncserv</emphasis> command verifies that each volume type (read/write, read-only, and | |
4527 | backup) mentioned in a VLDB entry actually exists at the site indicated in the entry. It checks all VLDB entries that mention a | |
4528 | site either on any of a file server machine's partitions or on one partition. Note that command can end up inspecting sites | |
4529 | other than on the specified machine or partition, if there are read-only versions of the volume at sites other than the | |
4530 | read/write site.</para> | |
4531 | ||
4532 | <para>The command alters any incorrect information in the VLDB, unless there is an irreconcilable conflict with other VLDB | |
4533 | entries. In that case, it writes a message to the standard error stream instead. The command never removes volumes from their | |
4534 | sites.</para> | |
4535 | ||
4536 | <indexterm> | |
4537 | <primary>commands</primary> | |
4538 | ||
4539 | <secondary>vos syncvldb</secondary> | |
4540 | </indexterm> | |
4541 | ||
4542 | <indexterm> | |
4543 | <primary>vos commands</primary> | |
4544 | ||
4545 | <secondary>syncvldb</secondary> | |
4546 | ||
4547 | <tertiary>syntax</tertiary> | |
4548 | </indexterm> | |
4549 | ||
4550 | <indexterm> | |
4551 | <primary>commands</primary> | |
4552 | ||
4553 | <secondary>vos syncserv</secondary> | |
4554 | </indexterm> | |
4555 | ||
4556 | <indexterm> | |
4557 | <primary>vos commands</primary> | |
4558 | ||
4559 | <secondary>syncserv</secondary> | |
4560 | ||
4561 | <tertiary>syntax</tertiary> | |
4562 | </indexterm> | |
4563 | ||
4564 | <sect2 id="Header_246"> | |
4565 | <title>To synchronize the VLDB with volume headers</title> | |
4566 | ||
4567 | <orderedlist> | |
4568 | <listitem> | |
4569 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
4570 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
4571 | display the users in the UserList file</link>. <programlisting> | |
4572 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
4573 | </programlisting></para> | |
4574 | </listitem> | |
4575 | ||
4576 | <listitem id="LIVOL-SYNCVL"> | |
4577 | <para>Issue the <emphasis role="bold">vos syncvldb</emphasis> command to make the VLDB reflect | |
4578 | the true state of all volumes on a machine or partition, or the state of one volume.</para> | |
4579 | ||
4580 | <note> | |
4581 | <para>To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your | |
4582 | cell for the <emphasis role="bold">-server</emphasis> argument in turn and omitting the <emphasis | |
4583 | role="bold">-partition</emphasis> and <emphasis role="bold">-volume</emphasis> arguments, before proceeding to Step | |
4584 | <link linkend="LIVOL-SYNCSR">3</link>.</para> | |
4585 | </note> | |
4586 | ||
4587 | <programlisting> | |
4588 | % <emphasis role="bold">vos syncvldb -server</emphasis> <<replaceable>machine name</replaceable>> [<emphasis role="bold">-partition</emphasis> <<replaceable>partition name</replaceable>>] \ | |
4589 | [<emphasis role="bold">-volume</emphasis> <<replaceable>volume name or ID</replaceable>>] [<emphasis role="bold">-verbose >></emphasis> file] | |
4590 | </programlisting> | |
4591 | ||
4592 | <para>where <variablelist> | |
4593 | <varlistentry> | |
4594 | <term><emphasis role="bold">syncv</emphasis></term> | |
4595 | ||
4596 | <listitem> | |
4597 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">syncvldb</emphasis>.</para> | |
4598 | </listitem> | |
4599 | </varlistentry> | |
4600 | ||
4601 | <varlistentry> | |
4602 | <term><emphasis role="bold">-server</emphasis></term> | |
4603 | ||
4604 | <listitem> | |
4605 | <para>Names the file server machine housing the volumes for which to verify VLDB entries. If you are also | |
4606 | providing the <emphasis role="bold">-volume</emphasis> argument, this argument must name the machine where the | |
4607 | volume actually resides.</para> | |
4608 | </listitem> | |
4609 | </varlistentry> | |
4610 | ||
4611 | <varlistentry> | |
4612 | <term><emphasis role="bold">-partition</emphasis></term> | |
4613 | ||
4614 | <listitem> | |
4615 | <para>Identifies the partition (on the file server machine specified by the <emphasis | |
4616 | role="bold">-server</emphasis> argument) housing the volumes for which to verify VLDB entries. In general, it is | |
4617 | best to omit this argument so that either the VLDB entries for all volumes on a server machine are corrected (if | |
4618 | you do not provide the <emphasis role="bold">-volume</emphasis> argument), or so that you do not need to guarantee | |
4619 | that the partition actually houses the volume named by the <emphasis role="bold">-volume</emphasis> | |
4620 | argument.</para> | |
4621 | </listitem> | |
4622 | </varlistentry> | |
4623 | ||
4624 | <varlistentry> | |
4625 | <term><emphasis role="bold">-volume</emphasis></term> | |
4626 | ||
4627 | <listitem> | |
4628 | <para>Specifies the name or volume ID number of a single volume for which to verify the VLDB entry.</para> | |
4629 | </listitem> | |
4630 | </varlistentry> | |
4631 | ||
4632 | <varlistentry> | |
4633 | <term><emphasis role="bold">-verbose >> file</emphasis></term> | |
4634 | ||
4635 | <listitem> | |
4636 | <para>Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the | |
4637 | machine on which you are issuing the command. The command often writes a large amount of output to the standard | |
4638 | output stream; writing it to a file enables you to examine the output more carefully.</para> | |
4639 | </listitem> | |
4640 | </varlistentry> | |
4641 | </variablelist></para> | |
4642 | </listitem> | |
4643 | ||
4644 | <listitem id="LIVOL-SYNCSR"> | |
4645 | <para>Issue the <emphasis role="bold">vos syncserv</emphasis> command to inspect each volume | |
4646 | for which the VLDB lists a version at the specified site.</para> | |
4647 | ||
4648 | <note> | |
4649 | <para>To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your | |
4650 | cell for the machine name argument in turn and omitting the partition name argument.</para> | |
4651 | </note> | |
4652 | ||
4653 | <programlisting> | |
4654 | % <emphasis role="bold">vos syncserv</emphasis> <<replaceable>machine name</replaceable>> [<<replaceable>partition name</replaceable>>] [<emphasis | |
4655 | role="bold">-v >></emphasis> file] | |
4656 | </programlisting> | |
4657 | ||
4658 | <para>where <variablelist> | |
4659 | <varlistentry> | |
4660 | <term><emphasis role="bold">syncs</emphasis></term> | |
4661 | ||
4662 | <listitem> | |
4663 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">syncserv</emphasis>.</para> | |
4664 | </listitem> | |
4665 | </varlistentry> | |
4666 | ||
4667 | <varlistentry> | |
4668 | <term><emphasis role="bold">machine name</emphasis></term> | |
4669 | ||
4670 | <listitem> | |
4671 | <para>Names the file server machine mentioned in each VLDB entry to check.</para> | |
4672 | </listitem> | |
4673 | </varlistentry> | |
4674 | ||
4675 | <varlistentry> | |
4676 | <term><emphasis role="bold">partition name</emphasis></term> | |
4677 | ||
4678 | <listitem> | |
4679 | <para>Identifies the partition mentioned in each VLDB entry to check. If synchronizing the entire VLDB, omit this | |
4680 | argument.</para> | |
4681 | </listitem> | |
4682 | </varlistentry> | |
4683 | ||
4684 | <varlistentry> | |
4685 | <term><emphasis role="bold">-v >> file</emphasis></term> | |
4686 | ||
4687 | <listitem> | |
4688 | <para>Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the | |
4689 | machine on which you are issuing the command. The command often writes a large amount of output to the standard | |
4690 | output stream; writing it to a file enables you to examine the output more carefully.</para> | |
4691 | </listitem> | |
4692 | </varlistentry> | |
4693 | </variablelist></para> | |
4694 | </listitem> | |
4695 | </orderedlist> | |
4696 | </sect2> | |
4697 | </sect1> | |
4698 | ||
4699 | <sect1 id="HDRWQ232"> | |
4700 | <title>Salvaging Volumes</title> | |
4701 | ||
4702 | <indexterm> | |
4703 | <primary>volume</primary> | |
4704 | ||
4705 | <secondary>salvaging</secondary> | |
4706 | </indexterm> | |
4707 | ||
4708 | <indexterm> | |
4709 | <primary>corruption</primary> | |
4710 | ||
4711 | <secondary>symptoms and types</secondary> | |
4712 | </indexterm> | |
4713 | ||
4714 | <indexterm> | |
4715 | <primary>symptoms</primary> | |
4716 | ||
4717 | <secondary>volume corruption</secondary> | |
4718 | </indexterm> | |
4719 | ||
4720 | <indexterm> | |
4721 | <primary>volume</primary> | |
4722 | ||
4723 | <secondary>symptoms of corruption</secondary> | |
4724 | </indexterm> | |
4725 | ||
4726 | <indexterm> | |
4727 | <primary>Salvager</primary> | |
4728 | ||
4729 | <secondary>instructions for invoking</secondary> | |
4730 | </indexterm> | |
4731 | ||
4732 | <indexterm> | |
4733 | <primary>file server machine</primary> | |
4734 | ||
4735 | <secondary>salvaging volumes</secondary> | |
4736 | </indexterm> | |
4737 | ||
4738 | <indexterm> | |
4739 | <primary>salvaging</primary> | |
4740 | ||
4741 | <secondary>volumes</secondary> | |
4742 | </indexterm> | |
4743 | ||
4744 | <indexterm> | |
4745 | <primary>partition</primary> | |
4746 | ||
4747 | <secondary>salvaging all volumes</secondary> | |
4748 | </indexterm> | |
4749 | ||
4750 | <para>An unexpected interruption while the Volume Server or File Server is manipulating the data in a volume can leave the | |
4751 | volume in an intermediate state (<emphasis>corrupted</emphasis>), rather than just creating a discrepancy between the | |
4752 | information in the VLDB and volume headers. For example, the failure of the operation that saves changes to a file (by | |
4753 | overwriting old data with new) can leave the old and new data mixed together on the disk.</para> | |
4754 | ||
4755 | <para>If an operation halts because the Volume Server or File Server exits unexpectedly, the BOS Server automatically shuts down | |
4756 | all components of the <emphasis role="bold">fs</emphasis> process and invokes the Salvager. The Salvager checks for and repairs | |
4757 | any inconsistencies it can. Sometimes, however, there are symptoms of the following sort, which indicate corruption serious | |
4758 | enough to create problems but not serious enough to cause the File Server component to fail. In these cases you can invoke the | |
4759 | Salvager yourself by issuing the <emphasis role="bold">bos salvage</emphasis> command. <itemizedlist> | |
4760 | <listitem> | |
4761 | <para><emphasis role="bold">Symptom:</emphasis> A file appears in the output of the <emphasis role="bold">ls</emphasis> | |
4762 | command, but attempts to access the file fail with messages indicating that it does not exist.</para> | |
4763 | ||
4764 | <para><emphasis role="bold">Possible cause:</emphasis> The Volume Server or File Server exited in the middle of a | |
4765 | file-creation operation, after changing the directory structure, but before actually storing data. (Other possible causes | |
4766 | are that the ACL on the directory does not grant the permissions you need to access the file, or there is a process, | |
4767 | machine, or network outage. Check for these causes before assuming the file is corrupted.)</para> | |
4768 | ||
4769 | <para><emphasis role="bold">Salvager's solution:</emphasis> Remove the file's entry from the directory structure.</para> | |
4770 | </listitem> | |
4771 | ||
4772 | <listitem> | |
4773 | <para><emphasis role="bold">Symptom:</emphasis> A volume is marked <computeroutput>Off-line</computeroutput> in the output | |
4774 | from the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvol</emphasis> commands, or | |
4775 | attempts to access the volume fail.</para> | |
4776 | ||
4777 | <para><emphasis role="bold">Possible cause:</emphasis> Two files or versions of a file are sharing the same disk blocks | |
4778 | because of an interrupted operation. The File Server and Volume Server normally refuse to attach volumes that exhibit this | |
4779 | type of corruption, because it can be very dangerous. If the Volume Server or File Server do attach the volume but are | |
4780 | unsure of the status of the affected disk blocks, they sometimes try to write yet more data there. When they cannot | |
4781 | perform the write, the data is lost. This effect can cascade, causing loss of all data on a partition.</para> | |
4782 | ||
4783 | <para><emphasis role="bold">Salvager's solution:</emphasis> Delete the data from the corrupted disk blocks in preference | |
4784 | to losing an entire partition.</para> | |
4785 | </listitem> | |
4786 | ||
4787 | <listitem> | |
4788 | <para><emphasis role="bold">Symptom:</emphasis> There is less space available on the partition than you expect based on | |
4789 | the size statistic reported for each volume by the <emphasis role="bold">vos listvol</emphasis> command.</para> | |
4790 | ||
4791 | <para><emphasis role="bold">Possible cause:</emphasis> There are orphaned files and directories. An | |
4792 | <emphasis>orphaned</emphasis> element is completely inaccessible because it is not referenced by any directory that can | |
4793 | act as its parent (is higher in the file tree). An orphaned element is not counted in the calculation of a volume's size | |
4794 | (or against its quota), even though it occupies space on the server partition.</para> | |
4795 | ||
4796 | <para><emphasis role="bold">Salvager's solution:</emphasis> By default, print a message to the <emphasis | |
4797 | role="bold">/usr/afs/logs/SalvageLog</emphasis> file reporting how many orphans were found and the approximate number of | |
4798 | kilobytes they are consuming. You can use the <emphasis role="bold">-orphans</emphasis> argument to remove or attach | |
4799 | orphaned elements instead. See <link linkend="HDRWQ233">To salvage volumes</link>.</para> | |
4800 | </listitem> | |
4801 | </itemizedlist></para> | |
4802 | ||
4803 | <para>When you notice symptoms such as these, use the <emphasis role="bold">bos salvage</emphasis> command to invoke the | |
4804 | Salvager before corruption spreads. (Even though it operates on volumes, the command belongs to the <emphasis | |
4805 | role="bold">bos</emphasis> suite because the BOS Server must coordinate the shutdown and restart of the Volume Server and File | |
4806 | Server with the Salvager. It shuts them down before the Salvager starts, and automatically restarts them when the salvage | |
4807 | operation finishes.)</para> | |
4808 | ||
4809 | <para>All of the AFS data stored on a file server machine is inaccessible during the salvage of one or more partitions. If you | |
4810 | salvage just one volume, it alone is inaccessible.</para> | |
4811 | ||
4812 | <para>When processing one or more partitions, the command restores consistency to corrupted read/write volumes where possible. | |
4813 | For read-only or backup volumes, it inspects only the volume header: <itemizedlist> | |
4814 | <listitem> | |
4815 | <para>If the volume header is corrupted, the Salvager removes the volume completely and records the removal in its log | |
4816 | file, <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis>. Issue the <emphasis role="bold">vos release</emphasis> or | |
4817 | <emphasis role="bold">vos backup</emphasis> command to create the read-only or backup volume again.</para> | |
4818 | </listitem> | |
4819 | ||
4820 | <listitem> | |
4821 | <para>If the volume header is intact, the Salvager skips the volume (does not check for corruption in the contents). | |
4822 | However, if the File Server notices corruption as it initializes, it sometimes refuses to attach the volume or bring it | |
4823 | online. In this case, it is simplest to remove the volume by issuing the <emphasis role="bold">vos remove</emphasis> or | |
4824 | <emphasis role="bold">vos zap</emphasis> command. Then issue the <emphasis role="bold">vos release</emphasis> or <emphasis | |
4825 | role="bold">vos backup</emphasis> command to create it again.</para> | |
4826 | </listitem> | |
4827 | </itemizedlist></para> | |
4828 | ||
4829 | <para>Combine the <emphasis role="bold">bos salvage</emphasis> command's arguments as indicated to salvage different numbers of | |
4830 | volumes: <itemizedlist> | |
4831 | <listitem> | |
4832 | <para>To salvage all volumes on a file server machine, combine the <emphasis role="bold">-server</emphasis> argument and | |
4833 | the <emphasis role="bold">-all</emphasis> flag.</para> | |
4834 | </listitem> | |
4835 | ||
4836 | <listitem> | |
4837 | <para>To salvage all volumes on one partition, combine the <emphasis role="bold">-server</emphasis> and <emphasis | |
4838 | role="bold">-partition</emphasis> arguments.</para> | |
4839 | </listitem> | |
4840 | ||
4841 | <listitem> | |
4842 | <para>To salvage only one read/write volume, combine the <emphasis role="bold">-server</emphasis>, <emphasis | |
4843 | role="bold">-partition</emphasis>, and <emphasis role="bold">-volume</emphasis> arguments. Only that volume is | |
4844 | inaccessible to Cache Managers, because the BOS Server does not shutdown the File Server and Volume Server processes | |
4845 | during the salvage of a single volume. Do not name a read-only or backup volume with the <emphasis | |
4846 | role="bold">-volume</emphasis> argument. Instead, remove the volume, using the <emphasis role="bold">vos remove</emphasis> | |
4847 | or <emphasis role="bold">vos zap</emphasis> command. Then create a new copy of the volume with the <emphasis | |
4848 | role="bold">vos release</emphasis> or <emphasis role="bold">vos backup</emphasis> command.</para> | |
4849 | </listitem> | |
4850 | </itemizedlist></para> | |
4851 | ||
4852 | <para>The Salvager always writes a trace to the <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis> file on the file | |
4853 | server machine where it runs. To record the trace in another file as well (either in AFS or on the local disk of the machine | |
4854 | where you issue the <emphasis role="bold">bos salvage</emphasis> command), name the file with the <emphasis | |
4855 | role="bold">-file</emphasis> argument. Or, to display the trace on the standard output stream as it is written to the <emphasis | |
4856 | role="bold">/usr/afs/logs/SalvageLog</emphasis> file, include the <emphasis role="bold">-showlog</emphasis> flag.</para> | |
4857 | ||
4858 | <para>By default, multiple Salvager subprocesses run in parallel: one for each partition up to four, and four subprocesses for | |
4859 | four or more partitions. To increase or decrease the number of subprocesses running in parallel, provide a positive integer | |
4860 | value for the <emphasis role="bold">-parallel</emphasis> argument.</para> | |
4861 | ||
4862 | <para>If there is more than one server partition on a physical disk, the Salvager by default salvages them serially to avoid the | |
4863 | inefficiency of constantly moving the disk head from one partition to another. However, this strategy is often not ideal if the | |
4864 | partitions are configured as logical volumes that span multiple disks. To force the Salvager to salvage logical volumes in | |
4865 | parallel, provide the string <emphasis role="bold">all</emphasis> as the value for the <emphasis | |
4866 | role="bold">-parallel</emphasis> argument. Provide a positive integer to specify the number of subprocesses to run in parallel | |
4867 | (for example, <emphasis role="bold">-parallel 5all</emphasis> for five subprocesses), or omit the integer to run up to four | |
4868 | subprocesses, depending on the number of logical volumes being salvaged.</para> | |
4869 | ||
4870 | <para>The Salvager creates temporary files as it runs, by default writing them to the partition it is salvaging. The number of | |
4871 | files can be quite large, and if the partition is too full to accommodate them, the Salvager terminates without completing the | |
4872 | salvage operation (it always removes the temporary files before exiting). Other Salvager subprocesses running at the same time | |
4873 | continue until they finish salvaging all other partitions where there is enough disk space for temporary files. To complete the | |
4874 | interrupted salvage, reissue the command against the appropriate partitions, adding the <emphasis role="bold">-tmpdir</emphasis> | |
4875 | argument to redirect the temporary files to a local disk directory that has enough space.</para> | |
4876 | ||
4877 | <para>The <emphasis role="bold">-orphans</emphasis> argument controls how the Salvager handles orphaned files and directories | |
4878 | that it finds on server partitions it is salvaging. An orphaned element is completely inaccessible because it is not referenced | |
4879 | by the vnode of any directory that can act as its parent (is higher in the filespace). Orphaned objects occupy space on the | |
4880 | server partition, but do not count against the volume's quota.</para> | |
4881 | ||
4882 | <para>During the salvage, the output of the <emphasis role="bold">bos status</emphasis> command reports the following auxiliary | |
4883 | status for the <emphasis role="bold">fs</emphasis> process:</para> | |
4884 | ||
4885 | <programlisting> | |
4886 | Salvaging file system | |
4887 | </programlisting> | |
4888 | ||
4889 | <indexterm> | |
4890 | <primary>bos commands</primary> | |
4891 | ||
4892 | <secondary>salvage</secondary> | |
4893 | </indexterm> | |
4894 | ||
4895 | <indexterm> | |
4896 | <primary>commands</primary> | |
4897 | ||
4898 | <secondary>bos salvage</secondary> | |
4899 | </indexterm> | |
4900 | ||
4901 | <sect2 id="HDRWQ233"> | |
4902 | <title>To salvage volumes</title> | |
4903 | ||
4904 | <orderedlist> | |
4905 | <listitem> | |
4906 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
4907 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
4908 | display the users in the UserList file</link>. <programlisting> | |
4909 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
4910 | </programlisting></para> | |
4911 | </listitem> | |
4912 | ||
4913 | <listitem> | |
4914 | <para>Issue the <emphasis role="bold">bos salvage</emphasis> command to salvage one or more volumes. <programlisting> | |
4915 | % <emphasis role="bold">bos salvage -server</emphasis> <<replaceable>machine name</replaceable>> [<emphasis role="bold">-partition</emphasis> <<replaceable>salvage partition</replaceable>>] \ | |
4916 | [<emphasis role="bold">-volume</emphasis> <<replaceable>salvage volume number or volume name</replaceable>>] \ | |
4917 | [<emphasis role="bold">-file</emphasis> salvage log output file] [<emphasis role="bold">-all</emphasis>] [<emphasis | |
4918 | role="bold">-showlog</emphasis>] \ | |
4919 | [<emphasis role="bold">-parallel</emphasis> <<replaceable># of max parallel partition salvaging</replaceable>>] \ | |
4920 | [<emphasis role="bold">-tmpdir</emphasis> <<replaceable>directory to place tmp files</replaceable>>] \ | |
4921 | [<emphasis role="bold">-orphans</emphasis> <<emphasis role="bold">ignore</emphasis> | <emphasis role="bold">remove</emphasis> | <emphasis | |
4922 | role="bold">attach</emphasis> >] | |
4923 | </programlisting></para> | |
4924 | ||
4925 | <para>where <variablelist> | |
4926 | <varlistentry> | |
4927 | <term><emphasis role="bold">-server</emphasis></term> | |
4928 | ||
4929 | <listitem> | |
4930 | <para>Names the file server machine on which to salvage volumes. This argument can be combined either with the | |
4931 | <emphasis role="bold">-all</emphasis> flag, the <emphasis role="bold">-partition</emphasis> argument, or both the | |
4932 | <emphasis role="bold">-partition</emphasis> and <emphasis role="bold">-volume</emphasis> arguments.</para> | |
4933 | </listitem> | |
4934 | </varlistentry> | |
4935 | ||
4936 | <varlistentry> | |
4937 | <term><emphasis role="bold">-partition</emphasis></term> | |
4938 | ||
4939 | <listitem> | |
4940 | <para>Names a single partition on which to salvage all volumes. The <emphasis role="bold">-server</emphasis> | |
4941 | argument must be provided along with this one.</para> | |
4942 | </listitem> | |
4943 | </varlistentry> | |
4944 | ||
4945 | <varlistentry> | |
4946 | <term><emphasis role="bold">-volume</emphasis></term> | |
4947 | ||
4948 | <listitem> | |
4949 | <para>Specifies the name or volume ID number of one read/write volume to salvage. Combine this argument with the | |
4950 | <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments.</para> | |
4951 | </listitem> | |
4952 | </varlistentry> | |
4953 | ||
4954 | <varlistentry> | |
4955 | <term><emphasis role="bold">-file</emphasis></term> | |
4956 | ||
4957 | <listitem> | |
4958 | <para>Specifies the complete pathname of a file into which to write a trace of the salvage operation, in addition | |
4959 | to the <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis> file on the server machine. If the file pathname | |
4960 | is local, the trace is written to the specified file on the local disk of the machine where the <emphasis | |
4961 | role="bold">bos salvage</emphasis> command is issued. If the <emphasis role="bold">-volume</emphasis> argument is | |
4962 | included, the file can be in AFS, though not in the volume being salvaged. Do not combine this argument with the | |
4963 | <emphasis role="bold">-showlog</emphasis> flag.</para> | |
4964 | </listitem> | |
4965 | </varlistentry> | |
4966 | ||
4967 | <varlistentry> | |
4968 | <term><emphasis role="bold">-all</emphasis></term> | |
4969 | ||
4970 | <listitem> | |
4971 | <para>Salvages all volumes on all of the partitions on the machine named by the <emphasis | |
4972 | role="bold">-server</emphasis> argument.</para> | |
4973 | </listitem> | |
4974 | </varlistentry> | |
4975 | ||
4976 | <varlistentry> | |
4977 | <term><emphasis role="bold">-showlog</emphasis></term> | |
4978 | ||
4979 | <listitem> | |
4980 | <para>Displays the trace of the salvage operation on the standard output stream, as well as writing it to the | |
4981 | <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis> file.</para> | |
4982 | </listitem> | |
4983 | </varlistentry> | |
4984 | ||
4985 | <varlistentry> | |
4986 | <term><emphasis role="bold">-parallel</emphasis></term> | |
4987 | ||
4988 | <listitem> | |
4989 | <para>Specifies the maximum number of Salvager subprocesses to run in parallel. Provide one of three values: | |
4990 | <itemizedlist> | |
4991 | <listitem> | |
4992 | <para>An integer from the range <emphasis role="bold">1</emphasis> to <emphasis role="bold">32</emphasis>. A | |
4993 | value of <emphasis role="bold">1</emphasis> means that a single Salvager process salvages the partitions | |
4994 | sequentially.</para> | |
4995 | </listitem> | |
4996 | ||
4997 | <listitem> | |
4998 | <para>The string <emphasis role="bold">all</emphasis> to run up to four Salvager subprocesses in parallel on | |
4999 | partitions formatted as logical volumes that span multiple physical disks. Use this value only with such | |
5000 | logical volumes.</para> | |
5001 | </listitem> | |
5002 | ||
5003 | <listitem> | |
5004 | <para>The string <emphasis role="bold">all</emphasis> followed immediately (with no intervening space) by an | |
5005 | integer from the range <emphasis role="bold">1</emphasis> to <emphasis role="bold">32</emphasis>, to run the | |
5006 | specified number of Salvager subprocesses in parallel on partitions formatted as logical volumes. Use this | |
5007 | value only with such logical volumes.</para> | |
5008 | </listitem> | |
5009 | </itemizedlist></para> | |
5010 | ||
5011 | <para>The BOS Server never starts more Salvager subprocesses than there are partitions, and always starts only one | |
5012 | process to salvage a single volume. If this argument is omitted, up to four Salvager subprocesses run in | |
5013 | parallel.</para> | |
5014 | </listitem> | |
5015 | </varlistentry> | |
5016 | ||
5017 | <varlistentry> | |
5018 | <term><emphasis role="bold">-tmpdir</emphasis></term> | |
5019 | ||
5020 | <listitem> | |
5021 | <para>Specifies the full pathname of a local disk directory to which the Salvager process writes temporary files | |
5022 | as it runs. By default, it writes them to the partition it is currently salvaging.</para> | |
5023 | </listitem> | |
5024 | </varlistentry> | |
5025 | ||
5026 | <varlistentry> | |
5027 | <term><emphasis role="bold">-orphans</emphasis></term> | |
5028 | ||
5029 | <listitem> | |
5030 | <para>Controls how the Salvager handles orphaned files and directories. Choose one of the following three values: | |
5031 | <variablelist> | |
5032 | <varlistentry> | |
5033 | <term><emphasis role="bold">ignore</emphasis></term> | |
5034 | ||
5035 | <listitem> | |
5036 | <para>Leaves the orphaned objects on the disk, but prints a message to the <emphasis | |
5037 | role="bold">/usr/afs/logs/SalvageLog</emphasis> file reporting how many orphans were found and the | |
5038 | approximate number of kilobytes they are consuming. This is the default if you omit the <emphasis | |
5039 | role="bold">-orphans</emphasis> argument.</para> | |
5040 | </listitem> | |
5041 | </varlistentry> | |
5042 | ||
5043 | <varlistentry> | |
5044 | <term><emphasis role="bold">remove</emphasis></term> | |
5045 | ||
5046 | <listitem> | |
5047 | <para>Removes the orphaned objects, and prints a message to the <emphasis | |
5048 | role="bold">/usr/afs/logs/SalvageLog</emphasis> file reporting how many orphans were removed and the | |
5049 | approximate number of kilobytes they were consuming.</para> | |
5050 | </listitem> | |
5051 | </varlistentry> | |
5052 | ||
5053 | <varlistentry> | |
5054 | <term><emphasis role="bold">attach</emphasis></term> | |
5055 | ||
5056 | <listitem> | |
5057 | <para>Attaches the orphaned objects by creating a reference to them in the vnode of the volume's root | |
5058 | directory. Since each object's actual name is now lost, the Salvager assigns each one a name of the | |
5059 | following form: <simplelist> | |
5060 | <member><emphasis role="bold">_ _ORPHANFILE_ _.</emphasis> index for files</member> | |
5061 | ||
5062 | <member><emphasis role="bold">_ _ORPHANDIR_ _.</emphasis> index for directories</member> | |
5063 | </simplelist></para> | |
5064 | ||
5065 | <para>where index is a two-digit number that uniquely identifies each object. The orphans are charged | |
5066 | against the volume's quota and appear in the output of the <emphasis role="bold">ls</emphasis> command | |
5067 | issued against the volume's root directory.</para> | |
5068 | </listitem> | |
5069 | </varlistentry> | |
5070 | </variablelist></para> | |
5071 | </listitem> | |
5072 | </varlistentry> | |
5073 | </variablelist></para> | |
5074 | </listitem> | |
5075 | </orderedlist> | |
5076 | </sect2> | |
5077 | </sect1> | |
5078 | ||
5079 | <sect1 id="HDRWQ234"> | |
5080 | <title>Setting and Displaying Volume Quota and Current Size</title> | |
5081 | ||
5082 | <indexterm> | |
5083 | <primary>volume</primary> | |
5084 | ||
5085 | <secondary>quota</secondary> | |
5086 | ||
5087 | <see>volume quota</see> | |
5088 | </indexterm> | |
5089 | ||
5090 | <indexterm> | |
5091 | <primary>default</primary> | |
5092 | ||
5093 | <secondary>volume quota</secondary> | |
5094 | </indexterm> | |
5095 | ||
5096 | <para>Every AFS volume has an associated quota which limits the volume's size. The default quota for a newly created volume is | |
5097 | 5,000 kilobyte blocks (slightly less that 5 MB). When a volume reaches its quota, the File Server rejects attempts to create new | |
5098 | files or directories in it. If an application is writing data into an existing file in a full volume, the File Server allows a | |
5099 | defined overage (by default, 1 MB). (You can use the <emphasis role="bold">fileserver</emphasis> command's <emphasis | |
5100 | role="bold">-spare</emphasis> or <emphasis role="bold">-pctspare</emphasis> argument to change the default overage; see the | |
5101 | command's reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.)</para> | |
5102 | ||
5103 | <para>To set a quota other than 5000 KB as you create a volume, include the <emphasis role="bold">-maxquota</emphasis> argument | |
5104 | to the <emphasis role="bold">vos create</emphasis> command, as described in <link linkend="HDRWQ185">Creating Read/write | |
5105 | Volumes</link>. To modify an existing volume's quota, issue either the <emphasis role="bold">fs setquota</emphasis> or the | |
5106 | <emphasis role="bold">fs setvol</emphasis> command as described in the following instructions. Do not set an existing volume's | |
5107 | quota lower than its current size.</para> | |
5108 | ||
5109 | <para>In general, smaller volumes are easier to administer than larger ones. If you need to move volumes, say for load-balancing | |
5110 | purposes, it is easier to find enough free space on other partitions for small volumes. Move operations complete more quickly | |
5111 | for small volumes, reducing the potential for outages or other errors to interrupt the move. AFS supports a maximum volume size, | |
5112 | which can vary for different AFS releases; see the <emphasis> OpenAFS Release Notes</emphasis> for the version you are using. | |
5113 | Also, the size of a partition or logical places an absolute limit on volume size, because a volume cannot span multiple | |
5114 | partitions or logical volumes.</para> | |
5115 | ||
5116 | <para>It is generally safe to overpack partitions by putting more volumes on them than can actually fit if all the volumes reach | |
5117 | their maximum quota. However, only experience determines to what degree overpacking works in your cell. It depends on what kind | |
5118 | of quota you assign to volumes (particularly user volumes, which are more likely than system volumes to grow unpredictably) and | |
5119 | how much information people generate and store in comparison to their quota.</para> | |
5120 | ||
5121 | <para>There are several commands that display a volume's quota, as described in the following instructions. They differ in how | |
5122 | much related information they produce.</para> | |
5123 | ||
5124 | <sect2 id="Header_250"> | |
5125 | <title>To set quota for a single volume</title> | |
5126 | ||
5127 | <indexterm> | |
5128 | <primary>maximum volume quota</primary> | |
5129 | </indexterm> | |
5130 | ||
5131 | <indexterm> | |
5132 | <primary>setting</primary> | |
5133 | ||
5134 | <secondary>volume quota</secondary> | |
5135 | ||
5136 | <tertiary>on single volume</tertiary> | |
5137 | </indexterm> | |
5138 | ||
5139 | <indexterm> | |
5140 | <primary>volume quota</primary> | |
5141 | ||
5142 | <secondary>setting</secondary> | |
5143 | ||
5144 | <tertiary>on single volume</tertiary> | |
5145 | </indexterm> | |
5146 | ||
5147 | <indexterm> | |
5148 | <primary>commands</primary> | |
5149 | ||
5150 | <secondary>fs setquota</secondary> | |
5151 | </indexterm> | |
5152 | ||
5153 | <indexterm> | |
5154 | <primary>fs commands</primary> | |
5155 | ||
5156 | <secondary>setquota</secondary> | |
5157 | </indexterm> | |
5158 | ||
5159 | <orderedlist> | |
5160 | <listitem> | |
5161 | <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the | |
5162 | <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display | |
5163 | the members of the system:administrators group</link>. <programlisting> | |
5164 | % <emphasis role="bold">pts membership system:administrators</emphasis> | |
5165 | </programlisting></para> | |
5166 | </listitem> | |
5167 | ||
5168 | <listitem> | |
5169 | <para>Issue the <emphasis role="bold">fs setquota</emphasis> command to set the volume's maximum quota. <programlisting> | |
5170 | % <emphasis role="bold">fs setquota</emphasis> [<<replaceable>dir/file path</replaceable>>] <emphasis role="bold">-max</emphasis> <<replaceable>max quota in kbytes</replaceable>> | |
5171 | </programlisting></para> | |
5172 | ||
5173 | <para>where <variablelist> | |
5174 | <varlistentry> | |
5175 | <term><emphasis role="bold">sq</emphasis></term> | |
5176 | ||
5177 | <listitem> | |
5178 | <para>Is an acceptable alias for <emphasis role="bold">setquota</emphasis>.</para> | |
5179 | </listitem> | |
5180 | </varlistentry> | |
5181 | ||
5182 | <varlistentry> | |
5183 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
5184 | ||
5185 | <listitem> | |
5186 | <para>Names a file or directory in the volume for which to set the indicated quota. Partial pathnames are | |
5187 | interpreted relative to the current working directory, which is the default if you omit this argument.</para> | |
5188 | ||
5189 | <para>Specify the read/write path to the file or directory, to avoid the failure that results when you attempt to | |
5190 | change a read-only volume. By convention, you indicate the read/write path by placing a period before the cell | |
5191 | name at the pathname's second level (for example, <emphasis role="bold">/afs/.example.com</emphasis>). For further | |
5192 | discussion of the concept of read/write and read-only paths through the filespace, see <link | |
5193 | linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para> | |
5194 | </listitem> | |
5195 | </varlistentry> | |
5196 | ||
5197 | <varlistentry> | |
5198 | <term><emphasis role="bold">max quota in kbytes</emphasis></term> | |
5199 | ||
5200 | <listitem> | |
5201 | <para>Sets the volume's quota, expressed in kilobyte blocks ( <emphasis role="bold">1024</emphasis> equals a | |
5202 | megabyte). A value of <emphasis role="bold">0</emphasis> grants an unlimited quota, but the size of the partition | |
5203 | imposes an absolute limit. You must include the <emphasis role="bold">-max</emphasis> switch if omitting the | |
5204 | dir/file path argument (to set the quota on the volume that houses the current working directory).</para> | |
5205 | </listitem> | |
5206 | </varlistentry> | |
5207 | </variablelist></para> | |
5208 | </listitem> | |
5209 | </orderedlist> | |
5210 | </sect2> | |
5211 | ||
5212 | <sect2 id="Header_251"> | |
5213 | <title>To set maximum quota on one or more volumes</title> | |
5214 | ||
5215 | <indexterm> | |
5216 | <primary>setting</primary> | |
5217 | ||
5218 | <secondary>volume quota</secondary> | |
5219 | ||
5220 | <tertiary>on multiple volumes</tertiary> | |
5221 | </indexterm> | |
5222 | ||
5223 | <indexterm> | |
5224 | <primary>volume quota</primary> | |
5225 | ||
5226 | <secondary>setting</secondary> | |
5227 | ||
5228 | <tertiary>on multiple volumes</tertiary> | |
5229 | </indexterm> | |
5230 | ||
5231 | <indexterm> | |
5232 | <primary>commands</primary> | |
5233 | ||
5234 | <secondary>fs setvol</secondary> | |
5235 | </indexterm> | |
5236 | ||
5237 | <indexterm> | |
5238 | <primary>fs commands</primary> | |
5239 | ||
5240 | <secondary>setvol</secondary> | |
5241 | </indexterm> | |
5242 | ||
5243 | <orderedlist> | |
5244 | <listitem> | |
5245 | <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the | |
5246 | <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display | |
5247 | the members of the system:administrators group</link>. <programlisting> | |
5248 | % <emphasis role="bold">pts membership system:administrators</emphasis> | |
5249 | </programlisting></para> | |
5250 | </listitem> | |
5251 | ||
5252 | <listitem> | |
5253 | <para>Issue the <emphasis role="bold">fs setvol</emphasis> command to set the quota on one or more volumes. | |
5254 | <programlisting> | |
5255 | % <emphasis role="bold">fs setvol</emphasis> [<<replaceable>dir/file path</replaceable>>+] <emphasis role="bold">-max</emphasis> <<replaceable>disk space quota in 1K units</replaceable>> | |
5256 | </programlisting></para> | |
5257 | ||
5258 | <para>where <variablelist> | |
5259 | <varlistentry> | |
5260 | <term><emphasis role="bold">sv</emphasis></term> | |
5261 | ||
5262 | <listitem> | |
5263 | <para>Is an acceptable alias for <emphasis role="bold">setvol</emphasis>.</para> | |
5264 | </listitem> | |
5265 | </varlistentry> | |
5266 | ||
5267 | <varlistentry> | |
5268 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
5269 | ||
5270 | <listitem> | |
5271 | <para>Names one file or directory that resides in each volume for which to set the indicated quota. Partial | |
5272 | pathnames are interpreted relative to the current working directory, which is the default if you omit this | |
5273 | argument.</para> | |
5274 | </listitem> | |
5275 | </varlistentry> | |
5276 | ||
5277 | <varlistentry> | |
5278 | <term><emphasis role="bold">disk space quota in 1K units</emphasis></term> | |
5279 | ||
5280 | <listitem> | |
5281 | <para>Sets the maximum quota on each volume, expressed in kilobytes blocks ( <emphasis role="bold">1024</emphasis> | |
5282 | equals a megabyte). A value of <emphasis role="bold">0</emphasis> grants an unlimited quota, but the size of the | |
5283 | partition does impose an absolute limit.</para> | |
5284 | </listitem> | |
5285 | </varlistentry> | |
5286 | </variablelist></para> | |
5287 | </listitem> | |
5288 | </orderedlist> | |
5289 | ||
5290 | <indexterm> | |
5291 | <primary>commands</primary> | |
5292 | ||
5293 | <secondary>fs quota</secondary> | |
5294 | </indexterm> | |
5295 | ||
5296 | <indexterm> | |
5297 | <primary>fs commands</primary> | |
5298 | ||
5299 | <secondary>quota</secondary> | |
5300 | </indexterm> | |
5301 | ||
5302 | <indexterm> | |
5303 | <primary>displaying</primary> | |
5304 | ||
5305 | <secondary>volume quota</secondary> | |
5306 | ||
5307 | <tertiary>percent used</tertiary> | |
5308 | </indexterm> | |
5309 | ||
5310 | <indexterm> | |
5311 | <primary>volume quota</primary> | |
5312 | ||
5313 | <secondary>displaying</secondary> | |
5314 | ||
5315 | <tertiary>percent used</tertiary> | |
5316 | </indexterm> | |
5317 | </sect2> | |
5318 | ||
5319 | <sect2 id="Header_252"> | |
5320 | <title>To display percent quota used</title> | |
5321 | ||
5322 | <orderedlist> | |
5323 | <listitem> | |
5324 | <para>Issue the <emphasis role="bold">fs quota</emphasis> command. <programlisting> | |
5325 | % <emphasis role="bold">fs quota</emphasis> [<<replaceable>dir/file path</replaceable>>+] | |
5326 | </programlisting></para> | |
5327 | ||
5328 | <para>where <variablelist> | |
5329 | <varlistentry> | |
5330 | <term><emphasis role="bold">q</emphasis></term> | |
5331 | ||
5332 | <listitem> | |
5333 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">quota</emphasis>.</para> | |
5334 | </listitem> | |
5335 | </varlistentry> | |
5336 | ||
5337 | <varlistentry> | |
5338 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
5339 | ||
5340 | <listitem> | |
5341 | <para>Names a directory or file in each volume for which to display percent quota used. Partial pathnames are | |
5342 | interpreted relative to the current working directory, which is the default if you omit this argument.</para> | |
5343 | </listitem> | |
5344 | </varlistentry> | |
5345 | </variablelist></para> | |
5346 | </listitem> | |
5347 | </orderedlist> | |
5348 | ||
5349 | <para>The following example illustrates the output produced by this command:</para> | |
5350 | ||
5351 | <programlisting> | |
5352 | % <emphasis role="bold">fs quota /afs/example.com/usr/terry</emphasis> | |
5353 | 34% of quota used. | |
5354 | </programlisting> | |
5355 | ||
5356 | <indexterm> | |
5357 | <primary>commands</primary> | |
5358 | ||
5359 | <secondary>fs listquota</secondary> | |
5360 | </indexterm> | |
5361 | ||
5362 | <indexterm> | |
5363 | <primary>fs commands</primary> | |
5364 | ||
5365 | <secondary>listquota</secondary> | |
5366 | </indexterm> | |
5367 | ||
5368 | <indexterm> | |
5369 | <primary>displaying</primary> | |
5370 | ||
5371 | <secondary>volume quota</secondary> | |
5372 | ||
5373 | <tertiary>with volume size</tertiary> | |
5374 | </indexterm> | |
5375 | ||
5376 | <indexterm> | |
5377 | <primary>volume quota</primary> | |
5378 | ||
5379 | <secondary>displaying</secondary> | |
5380 | ||
5381 | <tertiary>with volume size</tertiary> | |
5382 | </indexterm> | |
5383 | ||
5384 | <indexterm> | |
5385 | <primary>displaying</primary> | |
5386 | ||
5387 | <secondary>volume size</secondary> | |
5388 | </indexterm> | |
5389 | ||
5390 | <indexterm> | |
5391 | <primary>volume</primary> | |
5392 | ||
5393 | <secondary>size, displaying</secondary> | |
5394 | </indexterm> | |
5395 | </sect2> | |
5396 | ||
5397 | <sect2 id="Header_253"> | |
5398 | <title>To display quota, current size, and other information</title> | |
5399 | ||
5400 | <orderedlist> | |
5401 | <listitem> | |
5402 | <para>Issue the <emphasis role="bold">fs listquota</emphasis> command. <programlisting> | |
5403 | % <emphasis role="bold">fs listquota</emphasis> [<<replaceable>dir/file path</replaceable>>+] | |
5404 | </programlisting></para> | |
5405 | ||
5406 | <para>where <variablelist> | |
5407 | <varlistentry> | |
5408 | <term><emphasis role="bold">lq</emphasis></term> | |
5409 | ||
5410 | <listitem> | |
5411 | <para>Is an alias for <emphasis role="bold">listquota</emphasis>.</para> | |
5412 | </listitem> | |
5413 | </varlistentry> | |
5414 | ||
5415 | <varlistentry> | |
5416 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
5417 | ||
5418 | <listitem> | |
5419 | <para>Names a directory or file in each volume for which to display quota along with volume name and current space | |
5420 | usage. Partial pathnames are interpreted relative to the current working directory, which is the default if you | |
5421 | omit this argument.</para> | |
5422 | </listitem> | |
5423 | </varlistentry> | |
5424 | </variablelist></para> | |
5425 | </listitem> | |
5426 | </orderedlist> | |
5427 | ||
5428 | <para>As illustrated in the following example, the output reports the volume's name, its quota and current size (both in | |
5429 | kilobyte units), the percent quota used, and the percentage of space on the volume's host partition that is used.</para> | |
5430 | ||
5431 | <programlisting> | |
5432 | % <emphasis role="bold">fs listquota /afs/example.com/usr/terry</emphasis> | |
5433 | Volume Name Quota Used % Used Partition | |
5434 | user.terry 15000 5071 34% 86% | |
5435 | </programlisting> | |
5436 | ||
5437 | <indexterm> | |
5438 | <primary>displaying</primary> | |
5439 | ||
5440 | <secondary>volume quota</secondary> | |
5441 | ||
5442 | <tertiary>with volume & partition info</tertiary> | |
5443 | </indexterm> | |
5444 | ||
5445 | <indexterm> | |
5446 | <primary>displaying</primary> | |
5447 | ||
5448 | <secondary>volume size</secondary> | |
5449 | </indexterm> | |
5450 | ||
5451 | <indexterm> | |
5452 | <primary>volume quota</primary> | |
5453 | ||
5454 | <secondary>displaying</secondary> | |
5455 | ||
5456 | <tertiary>with volume &partition info</tertiary> | |
5457 | </indexterm> | |
5458 | ||
5459 | <indexterm> | |
5460 | <primary>displaying</primary> | |
5461 | ||
5462 | <secondary>disk partition size</secondary> | |
5463 | </indexterm> | |
5464 | ||
5465 | <indexterm> | |
5466 | <primary>disk partition</primary> | |
5467 | ||
5468 | <secondary>displaying size of single</secondary> | |
5469 | </indexterm> | |
5470 | ||
5471 | <indexterm> | |
5472 | <primary>commands</primary> | |
5473 | ||
5474 | <secondary>fs examine</secondary> | |
5475 | </indexterm> | |
5476 | ||
5477 | <indexterm> | |
5478 | <primary>fs commands</primary> | |
5479 | ||
5480 | <secondary>examine</secondary> | |
5481 | </indexterm> | |
5482 | </sect2> | |
5483 | ||
5484 | <sect2 id="Header_254"> | |
5485 | <title>To display quota, current size, and more partition information</title> | |
5486 | ||
5487 | <orderedlist> | |
5488 | <listitem> | |
5489 | <para>Issue the <emphasis role="bold">fs examine</emphasis> command. <programlisting> | |
5490 | % <emphasis role="bold">fs examine</emphasis> [<<replaceable>dir/file path</replaceable>>+] | |
5491 | </programlisting></para> | |
5492 | ||
5493 | <para>where <variablelist> | |
5494 | <varlistentry> | |
5495 | <term><emphasis role="bold">exa</emphasis></term> | |
5496 | ||
5497 | <listitem> | |
5498 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para> | |
5499 | </listitem> | |
5500 | </varlistentry> | |
5501 | ||
5502 | <varlistentry> | |
5503 | <term><emphasis role="bold">dir/file path</emphasis></term> | |
5504 | ||
5505 | <listitem> | |
5506 | <para>Names a directory or file in each volume for which to display quota information and information about the | |
5507 | host partition. Partial pathnames are interpreted relative to the current working directory, which is the default | |
5508 | if you omit this argument.</para> | |
5509 | </listitem> | |
5510 | </varlistentry> | |
5511 | </variablelist></para> | |
5512 | </listitem> | |
5513 | </orderedlist> | |
5514 | ||
5515 | <para>As illustrated in the following example, the output displays the volume's volume ID number and name, its quota and | |
5516 | current size (both in kilobyte units), and the free and total number of kilobyte blocks on the volume's host partition.</para> | |
5517 | ||
5518 | <programlisting> | |
5519 | % <emphasis role="bold">fs examine /afs/example.com/usr/terry</emphasis> | |
5520 | Volume status for vid = 50489902 named user.terry | |
5521 | Current maximum quota is 15000 | |
5522 | Current blocks used are 5073 | |
5523 | The partition has 46383 blocks available out of 333305 | |
5524 | </programlisting> | |
5525 | ||
5526 | <note> | |
5527 | <para>The partition-related statistics in this command's output do not always agree with the corresponding values in the | |
5528 | output of the standard UNIX <emphasis role="bold">df</emphasis> command. The statistics reported by this command can be up | |
5529 | to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency. Also, on | |
5530 | some operating systems, the <emphasis role="bold">df</emphasis> command's report of partition size includes reserved space | |
5531 | not included in this command's calculation, and so is likely to be about 10% larger.</para> | |
5532 | </note> | |
5533 | </sect2> | |
5534 | </sect1> | |
5535 | ||
5536 | <sect1 id="HDRWQ235"> | |
5537 | <title>Removing Volumes and their Mount Points</title> | |
5538 | ||
5539 | <indexterm> | |
5540 | <primary>volume</primary> | |
5541 | ||
5542 | <secondary>removing</secondary> | |
5543 | ||
5544 | <tertiary>basic instructions</tertiary> | |
5545 | </indexterm> | |
5546 | ||
5547 | <indexterm> | |
5548 | <primary>removing</primary> | |
5549 | ||
5550 | <secondary>mount point</secondary> | |
5551 | </indexterm> | |
5552 | ||
5553 | <indexterm> | |
5554 | <primary>unmounting</primary> | |
5555 | ||
5556 | <secondary>volume</secondary> | |
5557 | </indexterm> | |
5558 | ||
5559 | <indexterm> | |
5560 | <primary>mount point</primary> | |
5561 | ||
5562 | <secondary>removing</secondary> | |
5563 | </indexterm> | |
5564 | ||
5565 | <indexterm> | |
5566 | <primary>removing</primary> | |
5567 | ||
5568 | <secondary>volume</secondary> | |
5569 | </indexterm> | |
5570 | ||
5571 | <para>To remove a volume from its site and its record from the VLDB, use the <emphasis role="bold">vos remove</emphasis> | |
5572 | command. Use it to remove any of the three types of volumes; the effect depends on the type. <itemizedlist> | |
5573 | <listitem> | |
5574 | <para><indexterm> | |
5575 | <primary>read/write volume</primary> | |
5576 | ||
5577 | <secondary>removing</secondary> | |
5578 | ||
5579 | <tertiary>effect of</tertiary> | |
5580 | </indexterm> <indexterm> | |
5581 | <primary>backup volume</primary> | |
5582 | ||
5583 | <secondary>removed by read/write removal</secondary> | |
5584 | </indexterm> If you indicate the read/write volume by specifying the volume's base name without a <emphasis | |
5585 | role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension, the command removes both the | |
5586 | read/write and associated backup volume from the partition that houses them. You do not need to provide the <emphasis | |
5587 | role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, because there can be only one | |
5588 | read/write site. The site information is also removed from the VLDB entry, and the site count (reported by the <emphasis | |
5589 | role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvldb</emphasis> commands as <computeroutput>number of | |
5590 | sites</computeroutput>) decrements by one. The read/write and backup volume ID numbers no longer appear in the output from | |
5591 | the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvldb</emphasis> commands, but they are | |
5592 | preserved internally. Read-only sites, if any, are not affected, but cannot be changed unless a read/write site is again | |
5593 | defined. The entire VLDB entry is removed if there are no read-only sites.</para> | |
5594 | ||
5595 | <para>If there are no read-only copies left, it is best to remove the volume's mount point to prevent attempts to access | |
5596 | the volume's contents. Do not remove the mount point if copies of the read-only volume remain.</para> | |
5597 | </listitem> | |
5598 | ||
5599 | <listitem> | |
5600 | <para>If you indicate a read-only volume by including the <emphasis role="bold">.readonly</emphasis> extension on its | |
5601 | name, it is removed from the partition that houses it, and the corresponding site information is removed from the VLDB | |
5602 | entry. The site count reported by the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos | |
5603 | listvldb</emphasis> commands as <computeroutput>number of sites</computeroutput> decrements by one for each volume you | |
5604 | remove.</para> | |
5605 | ||
5606 | <indexterm> | |
5607 | <primary>read-only volume</primary> | |
5608 | ||
5609 | <secondary>removing</secondary> | |
5610 | ||
5611 | <tertiary>effect of</tertiary> | |
5612 | </indexterm> | |
5613 | ||
5614 | <para>If there is more than one read-only site, you must include the <emphasis role="bold">-server</emphasis> argument | |
5615 | (and optionally <emphasis role="bold">-partition</emphasis> argument) to specify the site from which to remove the volume. | |
5616 | If there is only one read-only site, the volume name is sufficient; if no read/write volume exists in this case, the | |
5617 | entire VLDB entry is removed.</para> | |
5618 | ||
5619 | <para>It is not generally appropriate to remove the volume's mount point when removing a read-only volume, especially if | |
5620 | the read/write version of the volume still exists. If the read/write version no longer exists, remove the mount point as | |
5621 | described in Step <link linkend="LIWQ239">5</link>of <link linkend="HDRWQ236">To remove a volume and unmount | |
5622 | it</link>.</para> | |
5623 | </listitem> | |
5624 | ||
5625 | <listitem> | |
5626 | <para>If you indicate a backup volume by including the <emphasis role="bold">.backup</emphasis> extension on its name, it | |
5627 | is removed from the partition that houses it and its site information is removed from the VLDB entry. You do not need to | |
5628 | provide the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, because | |
5629 | there can be only one backup site. The backup volume ID number no longer appears in the output from the <emphasis | |
5630 | role="bold">vos examine</emphasis> or <emphasis role="bold">vos listvldb</emphasis> command, but is preserved | |
5631 | internally.</para> | |
5632 | ||
5633 | <para>In the standard configuration, there is a separate mount point for the backup version of a user volume. Remember to | |
5634 | remove the mount point to prevent attempt to access the nonexistent volume's contents.</para> | |
5635 | </listitem> | |
5636 | </itemizedlist></para> | |
5637 | ||
5638 | <sect2 id="Header_256"> | |
5639 | <title>Other Removal Commands</title> | |
5640 | ||
5641 | <indexterm> | |
5642 | <primary>volume</primary> | |
5643 | ||
5644 | <secondary>removing</secondary> | |
5645 | ||
5646 | <tertiary>alternate commands</tertiary> | |
5647 | </indexterm> | |
5648 | ||
5649 | <para>The <emphasis role="bold">vos remove</emphasis> command is almost always the appropriate way to remove a volume, because | |
5650 | it automatically removes a volume's VLDB entry and both the volume header and all data from the partition. If either the VLDB | |
5651 | entry or volume header does not exist, it is sometimes necessary to use other commands that remove only the remaining element. | |
5652 | Do not use these commands in the normal case when both the VLDB entry and the volume header exist, because by definition they | |
5653 | create discrepancies between them. For details on the commands' syntax, see their reference pages in the <emphasis> OpenAFS | |
5654 | Administration Reference</emphasis>.</para> | |
5655 | ||
5656 | <indexterm> | |
5657 | <primary>commands</primary> | |
5658 | ||
5659 | <secondary>vos zap</secondary> | |
5660 | </indexterm> | |
5661 | ||
5662 | <indexterm> | |
5663 | <primary>vos commands</primary> | |
5664 | ||
5665 | <secondary>zap</secondary> | |
5666 | </indexterm> | |
5667 | ||
5668 | <para>The <emphasis role="bold">vos zap</emphasis> command removes a volume from its site by removing the volume header and | |
5669 | volume data for which a VLDB entry no longer exists. You can tell a VLDB entry is missing if the <emphasis role="bold">vos | |
5670 | listvol</emphasis> command displays the volume header but the <emphasis role="bold">vos examine</emphasis> or <emphasis | |
5671 | role="bold">vos listvldb</emphasis> command cannot locate the VLDB entry. You must run this command to correct the | |
5672 | discrepancy, because the <emphasis role="bold">vos syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis> | |
5673 | commands never remove volume headers.</para> | |
5674 | ||
5675 | <indexterm> | |
5676 | <primary>commands</primary> | |
5677 | ||
5678 | <secondary>vos remsite</secondary> | |
5679 | </indexterm> | |
5680 | ||
5681 | <indexterm> | |
5682 | <primary>vos commands</primary> | |
5683 | ||
5684 | <secondary>remsite</secondary> | |
5685 | </indexterm> | |
5686 | ||
5687 | <para>The <emphasis role="bold">vos remsite</emphasis> command removes a read-only site definition from the VLDB without | |
5688 | affecting the volume on the file server machine. Use this command when you have mistakenly issued the <emphasis | |
5689 | role="bold">vos addsite</emphasis> command to define a read-only site, but have not yet issued the <emphasis role="bold">vos | |
5690 | release</emphasis> command to release the volume to the site. If you have actually released a volume to the site, use the | |
5691 | <emphasis role="bold">vos remove</emphasis> command instead.</para> | |
5692 | ||
5693 | <indexterm> | |
5694 | <primary>commands</primary> | |
5695 | ||
5696 | <secondary>vos delentry</secondary> | |
5697 | </indexterm> | |
5698 | ||
5699 | <indexterm> | |
5700 | <primary>vos commands</primary> | |
5701 | ||
5702 | <secondary>delentry</secondary> | |
5703 | </indexterm> | |
5704 | ||
5705 | <para>The <emphasis role="bold">vos delentry</emphasis> command removes the entire VLDB entry that mentions the volume you | |
5706 | specify. If versions of the volume actually exist on file server machines, they are not affected. This command is useful if | |
5707 | you know for certain that a volume removal was not recorded in the VLDB (perhaps you used the <emphasis role="bold">vos | |
5708 | zap</emphasis> command during an emergency), and do not want to take the time to resynchronize the entire VLDB with the | |
5709 | <emphasis role="bold">vos syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis> commands.</para> | |
5710 | </sect2> | |
5711 | ||
5712 | <sect2 id="HDRWQ236"> | |
5713 | <title>To remove a volume and unmount it</title> | |
5714 | ||
5715 | <indexterm> | |
5716 | <primary>read/write volume</primary> | |
5717 | ||
5718 | <secondary>removing</secondary> | |
5719 | ||
5720 | <tertiary>instructions</tertiary> | |
5721 | </indexterm> | |
5722 | ||
5723 | <orderedlist> | |
5724 | <listitem> | |
5725 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
5726 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
5727 | display the users in the UserList file</link>. <programlisting> | |
5728 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
5729 | </programlisting></para> | |
5730 | </listitem> | |
5731 | ||
5732 | <listitem> | |
5733 | <para>If removing the volume's mount point, verify that you have the <emphasis role="bold">d</emphasis>( <emphasis | |
5734 | role="bold">delete</emphasis>) permission on its parent directory's ACL. If necessary, issue the <emphasis role="bold">fs | |
5735 | listacl</emphasis> command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
5736 | % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
5737 | </programlisting></para> | |
5738 | ||
5739 | <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis | |
5740 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis | |
5741 | role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis | |
5742 | role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para> | |
5743 | </listitem> | |
5744 | ||
5745 | <listitem id="LIWQ237"> | |
5746 | ||
5747 | <para><emphasis role="bold">(Optional)</emphasis> Dump the volume to a file or to tape, in case you want to restore it | |
5748 | later. To copy the volume's contents to a file, use the <emphasis role="bold">vos dump</emphasis> command as instructed in | |
5749 | <link linkend="HDRWQ240">Dumping and Restoring Volumes</link>. You can then copy the file to tape using a third-party | |
5750 | backup utility or an archiving utility such as the UNIX <emphasis role="bold">tar</emphasis> command.</para> | |
5751 | ||
5752 | <para>Alternatively, use the AFS Backup System to create a tape copy. In this case, it can be convenient to create a | |
5753 | temporary volume set that includes only the volume of interest. Temporary volume sets are not recorded in the Backup | |
5754 | Database, and so do not clutter database with records for volume sets that you use only once. For instructions, see <link | |
5755 | linkend="HDRWQ301">To create a dump</link>.</para> | |
5756 | ||
5757 | <indexterm> | |
5758 | <primary>commands</primary> | |
5759 | ||
5760 | <secondary>vos remove</secondary> | |
5761 | ||
5762 | <tertiary>basic instructions</tertiary> | |
5763 | </indexterm> | |
5764 | ||
5765 | <indexterm> | |
5766 | <primary>vos commands</primary> | |
5767 | ||
5768 | <secondary>remove</secondary> | |
5769 | ||
5770 | <tertiary>basic instructions</tertiary> | |
5771 | </indexterm> | |
5772 | </listitem> | |
5773 | ||
5774 | <listitem id="LIWQ238"> | |
5775 | <para>Issue the <emphasis role="bold">vos remove</emphasis> command to remove the volume. If | |
5776 | removing a read-only volume from multiple sites, repeat the command for each one. <programlisting> | |
5777 | % <emphasis role="bold">vos remove</emphasis> [<emphasis role="bold">-server</emphasis> machine name>] [<emphasis role="bold">-partition</emphasis> <<replaceable>partition name</replaceable>>] \ | |
5778 | <emphasis role="bold">-id</emphasis> <<replaceable>volume name or ID</replaceable>> | |
5779 | </programlisting></para> | |
5780 | ||
5781 | <para>where <variablelist> | |
5782 | <varlistentry> | |
5783 | <term><emphasis role="bold">remo</emphasis></term> | |
5784 | ||
5785 | <listitem> | |
5786 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">remove</emphasis>.</para> | |
5787 | </listitem> | |
5788 | </varlistentry> | |
5789 | ||
5790 | <varlistentry> | |
5791 | <term><emphasis role="bold">-server</emphasis></term> | |
5792 | ||
5793 | <listitem> | |
5794 | <para>Specifies the file server machine on which the volume resides. It is necessary only when the <emphasis | |
5795 | role="bold">-id</emphasis> argument names a read-only volume that exists at multiple sites.</para> | |
5796 | </listitem> | |
5797 | </varlistentry> | |
5798 | ||
5799 | <varlistentry> | |
5800 | <term><emphasis role="bold">-partition</emphasis></term> | |
5801 | ||
5802 | <listitem> | |
5803 | <para>Specifies the partition on machine name where the volume resides. It is necessary only when the <emphasis | |
5804 | role="bold">-id</emphasis> argument names a read-only volume that exists at multiple sites. Provide the <emphasis | |
5805 | role="bold">-server</emphasis> argument along with this one.</para> | |
5806 | </listitem> | |
5807 | </varlistentry> | |
5808 | ||
5809 | <varlistentry> | |
5810 | <term><emphasis role="bold">-id</emphasis></term> | |
5811 | ||
5812 | <listitem> | |
5813 | <para>Identifies the volume to remove, either by its complete name or volume ID number. If identifying a read-only | |
5814 | or backup volume by name, include the appropriate extension ( <emphasis role="bold">.readonly</emphasis> or | |
5815 | <emphasis role="bold">.backup</emphasis>).</para> | |
5816 | </listitem> | |
5817 | </varlistentry> | |
5818 | </variablelist></para> | |
5819 | ||
5820 | <indexterm> | |
5821 | <primary>commands</primary> | |
5822 | ||
5823 | <secondary>fs rmmount</secondary> | |
5824 | </indexterm> | |
5825 | ||
5826 | <indexterm> | |
5827 | <primary>fs commands</primary> | |
5828 | ||
5829 | <secondary>rmmount</secondary> | |
5830 | ||
5831 | <tertiary>when removing volume</tertiary> | |
5832 | </indexterm> | |
5833 | </listitem> | |
5834 | ||
5835 | <listitem id="LIWQ239"> | |
5836 | <para>If you are removing the last existing version of the volume, issue the <emphasis | |
5837 | role="bold">fs rmmount</emphasis> command remove the corresponding mount point. Complete instructions appear in <link | |
5838 | linkend="HDRWQ236">To remove a volume and unmount it</link>.</para> | |
5839 | ||
5840 | <para>If you are removing a backup volume that is mounted in the conventional way (at a subdirectory of its read/write | |
5841 | volume's root directory), then removing the source volume's mount point in this step is sufficient to remove the backup | |
5842 | volume's mount point. If you mounted the backup at a completely separate directory, you need to repeat this step for the | |
5843 | backup volume's mount point.</para> | |
5844 | ||
5845 | <programlisting> | |
5846 | % <emphasis role="bold">fs rmmount</emphasis> <<replaceable>directory</replaceable>> | |
5847 | </programlisting> | |
5848 | </listitem> | |
5849 | ||
5850 | <listitem> | |
5851 | <para><emphasis role="bold">(Optional)</emphasis> If you created a dump file in Step <link linkend="LIWQ237">3</link>, | |
5852 | transfer it to tape. The preferred method is to use the AFS Backup System, which is described in <link | |
5853 | linkend="HDRWQ248">Configuring the AFS Backup System</link>and <link linkend="HDRWQ283">Backing Up and Restoring AFS | |
5854 | Data</link>.</para> | |
5855 | </listitem> | |
5856 | </orderedlist> | |
5857 | </sect2> | |
5858 | </sect1> | |
5859 | ||
5860 | <sect1 id="HDRWQ240"> | |
5861 | <title>Dumping and Restoring Volumes</title> | |
5862 | ||
5863 | <indexterm> | |
5864 | <primary>dumping</primary> | |
5865 | ||
5866 | <secondary>volumes</secondary> | |
5867 | ||
5868 | <tertiary>without using AFS Backup System</tertiary> | |
5869 | </indexterm> | |
5870 | ||
5871 | <indexterm> | |
5872 | <primary>volume</primary> | |
5873 | ||
5874 | <secondary>dumping without AFS Backup System</secondary> | |
5875 | </indexterm> | |
5876 | ||
5877 | <para><emphasis>Dumping</emphasis> a volume with the <emphasis role="bold">vos dump</emphasis> command converts its contents | |
5878 | into ASCII format and writes them to the file you specify. The <emphasis role="bold">vos restore</emphasis> command places a | |
5879 | dump file's contents into a volume after converting them into the volume format appropriate for the indicated file server | |
5880 | machine.</para> | |
5881 | ||
5882 | <sect2 id="Header_259"> | |
5883 | <title>About Dumping Volumes</title> | |
5884 | ||
5885 | <indexterm> | |
5886 | <primary>read/write volume</primary> | |
5887 | ||
5888 | <secondary>dumping</secondary> | |
5889 | </indexterm> | |
5890 | ||
5891 | <indexterm> | |
5892 | <primary>read-only volume</primary> | |
5893 | ||
5894 | <secondary>dumping</secondary> | |
5895 | </indexterm> | |
5896 | ||
5897 | <indexterm> | |
5898 | <primary>backup volume</primary> | |
5899 | ||
5900 | <secondary>dumping</secondary> | |
5901 | </indexterm> | |
5902 | ||
5903 | <indexterm> | |
5904 | <primary>availability of data</primary> | |
5905 | ||
5906 | <secondary>interrupted by dumping</secondary> | |
5907 | </indexterm> | |
5908 | ||
5909 | <indexterm> | |
5910 | <primary>data</primary> | |
5911 | ||
5912 | <secondary>availability interrupted by dumping</secondary> | |
5913 | </indexterm> | |
5914 | ||
5915 | <indexterm> | |
5916 | <primary>dumping</primary> | |
5917 | ||
5918 | <secondary>volumes</secondary> | |
5919 | ||
5920 | <tertiary>reasons</tertiary> | |
5921 | </indexterm> | |
5922 | ||
5923 | <para>Dumping a volume can be useful in several situations, including the following: <itemizedlist> | |
5924 | <listitem> | |
5925 | <para>You want to back it up to tape, perhaps by using a third-party backup utility. To facilitate this type of backup | |
5926 | operation, the <emphasis role="bold">vos dump</emphasis> command can write to a named pipe. To learn about using the AFS | |
5927 | Backup System instead, see <link linkend="HDRWQ248">Configuring the AFS Backup System</link>and <link | |
5928 | linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para> | |
5929 | </listitem> | |
5930 | ||
5931 | <listitem> | |
5932 | <para>You are removing the volume from your cell (perhaps because its owner is leaving your cell). The <emphasis | |
5933 | role="bold">vos dump</emphasis> command enables you to create a copy for safekeeping without incurring the overhead of | |
5934 | the Backup System. For complete instructions on removing a volume, see <link linkend="HDRWQ235">Removing Volumes and | |
5935 | their Mount Points</link>.</para> | |
5936 | </listitem> | |
5937 | ||
5938 | <listitem> | |
5939 | <para>You want to create a copy of the volume for safekeeping on a non-AFS server partition, perhaps while you move the | |
5940 | actual volume to another machine or perform maintenance tasks on the partition that houses the volume.</para> | |
5941 | </listitem> | |
5942 | ||
5943 | <listitem> | |
5944 | <para>You need to replace a corrupted read/write volume. If an uncorrupted read-only or backup version of the volume | |
5945 | exists, dump it and restore the data into the read/write volume, overwriting the corrupted contents.</para> | |
5946 | </listitem> | |
5947 | ||
5948 | <listitem> | |
5949 | <para>You want to copy or transfer the contents of the volume to another cell. You cannot use the <emphasis | |
5950 | role="bold">vos move</emphasis> command, because AFS supports volume moves only between file server machines that belong | |
5951 | to the same cell.</para> | |
5952 | </listitem> | |
5953 | ||
5954 | <listitem> | |
5955 | <para>You want to have another read/write copy of the volume's contents. The second volume must have a different name | |
5956 | than the original one. If you want the contents of the two volumes to remain identical, you must update them both | |
5957 | manually. AFS provides no facility for keeping read/write volumes synchronized in this way.</para> | |
5958 | </listitem> | |
5959 | ||
5960 | <listitem> | |
5961 | <para>You want a copy of only the files and directories in the volume with modification time stamps after a certain | |
5962 | date. The <emphasis role="bold">vos dump</emphasis> command can create an incremental dump file as described in Step | |
5963 | <link linkend="LIWQ241">3</link>of the following instructions.</para> | |
5964 | </listitem> | |
5965 | </itemizedlist></para> | |
5966 | ||
5967 | <indexterm> | |
5968 | <primary>full dump</primary> | |
5969 | ||
5970 | <secondary>creating using vos command</secondary> | |
5971 | </indexterm> | |
5972 | ||
5973 | <indexterm> | |
5974 | <primary>incremental dump</primary> | |
5975 | ||
5976 | <secondary>creating using vos command</secondary> | |
5977 | </indexterm> | |
5978 | ||
5979 | <indexterm> | |
5980 | <primary>dumping</primary> | |
5981 | ||
5982 | <secondary>volumes</secondary> | |
5983 | ||
5984 | <tertiary>using vos command</tertiary> | |
5985 | </indexterm> | |
5986 | ||
5987 | <para>You can use the <emphasis role="bold">vos dump</emphasis> command to create a <emphasis>full dump</emphasis>, which | |
5988 | contains the complete contents of the volume at the time you issue the command, or an <emphasis>incremental dump</emphasis>, | |
5989 | which contains only those files and directories with modification timestamps (as displayed by the <emphasis role="bold">ls | |
5990 | -l</emphasis> command) that are later than a date and time you specify. See Step <link linkend="LIWQ241">3</link>of the | |
5991 | following instructions.</para> | |
5992 | ||
5993 | <para>Dumping a volume does not change its VLDB entry or permanently affect its status on the file server machine, but the | |
5994 | volume's contents are inaccessible during the dump operation. To avoid interrupting access to the volume, it is generally best | |
5995 | to dump the volume's backup version, just after using the <emphasis role="bold">vos backup</emphasis> or <emphasis | |
5996 | role="bold">vos backupsys</emphasis> command to create a new backup version.</para> | |
5997 | ||
5998 | <para>If you do not provide a filename into which to write the dump, the <emphasis role="bold">vos dump</emphasis> command | |
5999 | directs the output to the standard output stream. You can pipe it directly to the <emphasis role="bold">vos restore</emphasis> | |
6000 | command if you wish.</para> | |
6001 | ||
6002 | <para>Because a volume dump file is in ASCII format, you can read its contents using a text editor or a command such as the | |
6003 | <emphasis role="bold">cat</emphasis> command. However, dump files sometimes contain special characters that do not have | |
6004 | alphanumeric correlates, which can cause problems for some display programs.</para> | |
6005 | ||
6006 | <para>By default, the <emphasis role="bold">vos</emphasis> command interpreter consults the Volume Location Database (VLDB) to | |
6007 | learn the volume's location, so the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> | |
6008 | arguments are not required. If the <emphasis role="bold">-id</emphasis> argument identifies a read-only volume that resides at | |
6009 | multiple sites, then the command dumps the version from just one of them (normally, the one listed first in the volume's VLDB | |
6010 | entry as reported by the <emphasis role="bold">vos examine</emphasis> or <emphasis role="bold">vos listvldb</emphasis> | |
6011 | command). To dump the read-only volume from a particular site, use the <emphasis role="bold">-server</emphasis> and <emphasis | |
6012 | role="bold">-partition</emphasis> arguments to specify the site. To bypass the VLDB lookup entirely, provide a volume ID | |
6013 | number (rather than a volume name) as the value for the <emphasis role="bold">-id</emphasis> argument, along with the | |
6014 | <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments. This makes it possible to | |
6015 | dump a volume for which there is no VLDB entry.</para> | |
6016 | ||
6017 | <indexterm> | |
6018 | <primary>commands</primary> | |
6019 | ||
6020 | <secondary>vos dump</secondary> | |
6021 | </indexterm> | |
6022 | ||
6023 | <indexterm> | |
6024 | <primary>vos commands</primary> | |
6025 | ||
6026 | <secondary>dump</secondary> | |
6027 | </indexterm> | |
6028 | </sect2> | |
6029 | ||
6030 | <sect2 id="Header_260"> | |
6031 | <title>To dump a volume</title> | |
6032 | ||
6033 | <orderedlist> | |
6034 | <listitem> | |
6035 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
6036 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
6037 | display the users in the UserList file</link>. <programlisting> | |
6038 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
6039 | </programlisting></para> | |
6040 | </listitem> | |
6041 | ||
6042 | <listitem> | |
6043 | <para>Verify that you have the permissions necessary to create the dump file. If placing it in AFS, you must have the | |
6044 | <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) permission on the ACL of the file's | |
6045 | directory. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link | |
6046 | linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
6047 | % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
6048 | </programlisting></para> | |
6049 | ||
6050 | <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis | |
6051 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis | |
6052 | role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis | |
6053 | role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para> | |
6054 | </listitem> | |
6055 | ||
6056 | <listitem id="LIWQ241"> | |
6057 | <para>Issue the <emphasis role="bold">vos dump</emphasis> command to dump the volume. | |
6058 | <programlisting> | |
6059 | % <emphasis role="bold">vos dump -id</emphasis> <<replaceable>volume name or ID</replaceable>> [<emphasis role="bold">-time</emphasis> <<replaceable>dump from time</replaceable>>] [<emphasis | |
6060 | role="bold">-file</emphasis> <<replaceable>arg</replaceable>>] [<emphasis role="bold">-server</emphasis> <<replaceable>server</replaceable>>] [<emphasis | |
6061 | role="bold">-partition</emphasis> <<replaceable>partition</replaceable>>] | |
6062 | </programlisting></para> | |
6063 | ||
6064 | <para>where <variablelist> | |
6065 | <varlistentry> | |
6066 | <term><emphasis role="bold">-id</emphasis></term> | |
6067 | ||
6068 | <listitem> | |
6069 | <para>Identifies the volume to be dumped by its complete name or volume ID number. If you want to dump the | |
6070 | read-only or backup version, specify its volume ID number or add the appropriate extension ( <emphasis | |
6071 | role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis>) to the name.</para> | |
6072 | ||
6073 | <para>To bypass the normal VLDB lookup of the volume's location, provide the volume ID number and combine this | |
6074 | argument with the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> | |
6075 | arguments.</para> | |
6076 | </listitem> | |
6077 | </varlistentry> | |
6078 | ||
6079 | <varlistentry> | |
6080 | <term><emphasis role="bold">-time</emphasis></term> | |
6081 | ||
6082 | <listitem> | |
6083 | <para>Specifies whether the dump is full or incremental. Omit this argument to create a full dump, or provide one | |
6084 | of three acceptable values: <itemizedlist> | |
6085 | <listitem> | |
6086 | <para>The value <emphasis role="bold">0</emphasis>(zero) to create a full dump.</para> | |
6087 | </listitem> | |
6088 | ||
6089 | <listitem> | |
6090 | <para>A date in the format mm <emphasis role="bold">/</emphasis> dd <emphasis role="bold">/</emphasis> yyyy | |
6091 | (month, day and year) to create an incremental dump that includes only files and directories with | |
6092 | modification timestamps later than midnight (12:00 a.m.) on the indicated date. Valid values for the year | |
6093 | range from <emphasis role="bold">1970</emphasis> to <emphasis role="bold">2037</emphasis>; higher values are | |
6094 | not valid because the latest possible date in the standard UNIX representation is in 2038. The command | |
6095 | interpreter automatically reduces later dates to the maximum value. An example is <emphasis | |
6096 | role="bold">01/13/1999</emphasis>.</para> | |
6097 | </listitem> | |
6098 | ||
6099 | <listitem> | |
6100 | <para>A date and time in the format <emphasis role="bold">"</emphasis> mm <emphasis role="bold">/</emphasis> | |
6101 | dd <emphasis role="bold">/</emphasis> yyyy hh <emphasis role="bold">:</emphasis> MM <emphasis | |
6102 | role="bold">"</emphasis> to create an incremental dump that includes only files and directories with | |
6103 | modification timestamps later than the specified date and time. The date format is the same as for a date | |
6104 | alone. Express the time as hours and minutes (hh:MM) in 24-hour format (for example, <emphasis | |
6105 | role="bold">20:30</emphasis> is 8:30 p.m.). Surround the entire expression with double quotes (" ") because | |
6106 | it contains a space. An example is <emphasis role="bold">"01/13/1999 22:30"</emphasis>.</para> | |
6107 | </listitem> | |
6108 | </itemizedlist></para> | |
6109 | </listitem> | |
6110 | </varlistentry> | |
6111 | ||
6112 | <varlistentry> | |
6113 | <term><emphasis role="bold">-file</emphasis></term> | |
6114 | ||
6115 | <listitem> | |
6116 | <para>Specifies the pathname of the file to which to write the dump. The file can be in AFS, but not in the volume | |
6117 | being dumped. A partial pathname is interpreted relative to the current working directory. Omit this argument to | |
6118 | direct the dump to the standard output stream.</para> | |
6119 | </listitem> | |
6120 | </varlistentry> | |
6121 | ||
6122 | <varlistentry> | |
6123 | <term><emphasis role="bold">-server</emphasis></term> | |
6124 | ||
6125 | <listitem> | |
6126 | <para>Specifies the file server machine on which the volume resides. Provide the <emphasis | |
6127 | role="bold">-partition</emphasis> argument along with this one.</para> | |
6128 | </listitem> | |
6129 | </varlistentry> | |
6130 | ||
6131 | <varlistentry> | |
6132 | <term><emphasis role="bold">-partition</emphasis></term> | |
6133 | ||
6134 | <listitem> | |
6135 | <para>Specifies the partition on which the volume resides. Provide the <emphasis role="bold">-server</emphasis> | |
6136 | argument along with this one.</para> | |
6137 | </listitem> | |
6138 | </varlistentry> | |
6139 | </variablelist></para> | |
6140 | </listitem> | |
6141 | </orderedlist> | |
6142 | </sect2> | |
6143 | ||
6144 | <sect2 id="Header_261"> | |
6145 | <title>About Restoring Volumes</title> | |
6146 | ||
6147 | <indexterm> | |
6148 | <primary>volume</primary> | |
6149 | ||
6150 | <secondary>restoring</secondary> | |
6151 | ||
6152 | <tertiary>with vos restore command</tertiary> | |
6153 | </indexterm> | |
6154 | ||
6155 | <indexterm> | |
6156 | <primary>restoring</primary> | |
6157 | ||
6158 | <secondary>volumes without using AFS Backup System</secondary> | |
6159 | </indexterm> | |
6160 | ||
6161 | <para>Although you can dump any of the three types of volumes (read/write, read-only, or backup), you can restore a dump file | |
6162 | to the file system only as a read/write volume, using the <emphasis role="bold">vos restore</emphasis> command. The command | |
6163 | automatically translates the dump file's contents from ASCII back into the volume format appropriate for the file server | |
6164 | machine that stores the restored version. As with the <emphasis role="bold">vos dump</emphasis> command, you can restore a | |
6165 | dump file via a named pipe, which facilitates interoperation with third-party backup utilities.</para> | |
6166 | ||
6167 | <para>You can restore the contents of a dump file in one of two basic ways. In either case, you must restore a full dump of | |
6168 | the volume before restoring any incremental dumps. Any incremental dumps that you then restore must have been created after | |
6169 | the full dump. If there is more than one incremental dump, you must restore them in the order they were created. <itemizedlist> | |
6170 | <listitem> | |
6171 | <para>You can restore volume data into a brand new volume with a new name and at a location that you specify. See <link | |
6172 | linkend="HDRWQ242">To restore a dump into a new volume and mount it</link>.</para> | |
6173 | ||
6174 | <para>You can assign a volume ID number as you restore the volume, though it is best to have the Volume Server allocate | |
6175 | a volume number automatically. The most common reason for specifying the volume ID is that a volume's VLDB entry has | |
6176 | disappeared for some reason, but you know the former read/write volume ID number and want to reuse it.</para> | |
6177 | </listitem> | |
6178 | ||
6179 | <listitem> | |
6180 | <para>You can restore volume data into an existing volume (usually the one that was previously dumped), overwriting its | |
6181 | current contents. This is convenient if the current contents are corrupted or otherwise incorrect, because it allows you | |
6182 | to replace them with a coherent version from the past or from one of the volume's clones. See <link | |
6183 | linkend="HDRWQ244">To restore a dump file, overwriting an existing volume</link>.</para> | |
6184 | ||
6185 | <para>Provide the <emphasis role="bold">-overwrite</emphasis> argument to preconfirm that you wish to overwrite the | |
6186 | volume's contents, and to specify whether you are restoring a full or incremental dump. If you omit the <emphasis | |
6187 | role="bold">-overwrite</emphasis> argument, the Volume Server generates the following prompt to confirm that you want to | |
6188 | overwrite the existing volume with either a full ( <emphasis role="bold">f</emphasis>) or incremental ( <emphasis | |
6189 | role="bold">i</emphasis>) dump:</para> | |
6190 | ||
6191 | <programlisting> | |
6192 | Do you want to do a full/incremental restore or abort? [fia](a): | |
6193 | </programlisting> | |
6194 | ||
6195 | <para>If you pipe in the dump file via the standard input stream instead of using the <emphasis | |
6196 | role="bold">-file</emphasis> argument to name it, you must include the <emphasis role="bold">-overwrite</emphasis> | |
6197 | argument because there is nowhere for the Volume Server to display the prompt in this case.</para> | |
6198 | ||
6199 | <para>You can move the volume to a new site as you overwrite it with a full dump, by using the <emphasis | |
6200 | role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments to specify the new site. You | |
6201 | cannot move the volume when restoring an incremental dump.</para> | |
6202 | </listitem> | |
6203 | </itemizedlist></para> | |
6204 | ||
6205 | <para>The <emphasis role="bold">vos restore</emphasis> command sets the restored volume's creation date in the volume header | |
6206 | to the time of the restore operation, as reported in the <computeroutput>Creation</computeroutput> field in the output from | |
6207 | the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvol</emphasis> commands.</para> | |
6208 | ||
6209 | <indexterm> | |
6210 | <primary>commands</primary> | |
6211 | ||
6212 | <secondary>vos restore</secondary> | |
6213 | </indexterm> | |
6214 | ||
6215 | <indexterm> | |
6216 | <primary>vos commands</primary> | |
6217 | ||
6218 | <secondary>restore</secondary> | |
6219 | ||
6220 | <tertiary>to create new volume</tertiary> | |
6221 | </indexterm> | |
6222 | </sect2> | |
6223 | ||
6224 | <sect2 id="HDRWQ242"> | |
6225 | <title>To restore a dump into a new volume and mount it</title> | |
6226 | ||
6227 | <orderedlist> | |
6228 | <listitem> | |
6229 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
6230 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
6231 | display the users in the UserList file</link>. <programlisting> | |
6232 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
6233 | </programlisting></para> | |
6234 | </listitem> | |
6235 | ||
6236 | <listitem> | |
6237 | <para>Verify that you have permissions needed to read the dump file and to mount the new volume. If the dump file resides | |
6238 | in AFS, you need the <emphasis role="bold">r</emphasis>( <emphasis role="bold">read</emphasis>) permission on the ACL of | |
6239 | its directory. You need the <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) and <emphasis | |
6240 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) permissions on the ACL of the directory where you | |
6241 | are mounting the new volume. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully | |
6242 | described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
6243 | % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
6244 | </programlisting></para> | |
6245 | ||
6246 | <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis | |
6247 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis | |
6248 | role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis | |
6249 | role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para> | |
6250 | </listitem> | |
6251 | ||
6252 | <listitem> | |
6253 | <para>Select a site (disk partition on a file server machine) for the new volume. If your cell groups different types of | |
6254 | volumes onto different file server machines, that can guide your decision. It often makes sense to put the volume on the | |
6255 | emptiest partition that meets your other criteria. To display how much space is available on a file server machine's | |
6256 | partitions, use the <emphasis role="bold">vos partinfo</emphasis> command, which is described fully in <link | |
6257 | linkend="HDRWQ185">Creating Read/write Volumes</link>. <programlisting> | |
6258 | % <emphasis role="bold">vos partinfo</emphasis> <<replaceable>machine name</replaceable>> [<<replaceable>partition name</replaceable>>] | |
6259 | </programlisting></para> | |
6260 | </listitem> | |
6261 | ||
6262 | <listitem id="LIWQ243"> | |
6263 | <para>Issue the <emphasis role="bold">vos restore</emphasis> command to create a new volume and | |
6264 | restore the dump file into it. Type it on a single line; it appears on multiple lines here only for legibility. | |
6265 | <programlisting> | |
6266 | % <emphasis role="bold">vos restore</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> \ | |
6267 | <<replaceable>name of volume to be restored</replaceable>> \ | |
6268 | [<emphasis role="bold">-file</emphasis> <<replaceable>dump file</replaceable>>] [<emphasis role="bold">-id</emphasis> <<replaceable>volume ID</replaceable>>] | |
6269 | </programlisting></para> | |
6270 | ||
6271 | <para>where <variablelist> | |
6272 | <varlistentry> | |
6273 | <term><emphasis role="bold">res</emphasis></term> | |
6274 | ||
6275 | <listitem> | |
6276 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">restore</emphasis>.</para> | |
6277 | </listitem> | |
6278 | </varlistentry> | |
6279 | ||
6280 | <varlistentry> | |
6281 | <term><emphasis role="bold">machine name</emphasis></term> | |
6282 | ||
6283 | <listitem> | |
6284 | <para>Names the file server machine on which to create the new volume.</para> | |
6285 | </listitem> | |
6286 | </varlistentry> | |
6287 | ||
6288 | <varlistentry> | |
6289 | <term><emphasis role="bold">partition name</emphasis></term> | |
6290 | ||
6291 | <listitem> | |
6292 | <para>Names the partition on which to create the new volume.</para> | |
6293 | </listitem> | |
6294 | </varlistentry> | |
6295 | ||
6296 | <varlistentry> | |
6297 | <term><emphasis role="bold">name of volume to be restored</emphasis></term> | |
6298 | ||
6299 | <listitem> | |
6300 | <para>Names the new read/write volume, which must not already have a VLDB entry. It can be up to 22 characters in | |
6301 | length.</para> | |
6302 | </listitem> | |
6303 | </varlistentry> | |
6304 | ||
6305 | <varlistentry> | |
6306 | <term><emphasis role="bold">-file</emphasis></term> | |
6307 | ||
6308 | <listitem> | |
6309 | <para>Is the dump file to restore. Partial pathnames are interpreted with respect to the current working | |
6310 | directory. Omit this argument if using a pipe to read in the dump file from the standard input stream.</para> | |
6311 | </listitem> | |
6312 | </varlistentry> | |
6313 | ||
6314 | <varlistentry> | |
6315 | <term><emphasis role="bold">-volume</emphasis></term> | |
6316 | ||
6317 | <listitem> | |
6318 | <para>Specifies the new volume's ID number. It is appropriate only if you are restoring a volume that no longer | |
6319 | exists and want to use the volume ID number it had previously.</para> | |
6320 | </listitem> | |
6321 | </varlistentry> | |
6322 | </variablelist></para> | |
6323 | ||
6324 | <indexterm> | |
6325 | <primary>commands</primary> | |
6326 | ||
6327 | <secondary>fs mkmount</secondary> | |
6328 | ||
6329 | <tertiary>when restoring volume</tertiary> | |
6330 | </indexterm> | |
6331 | ||
6332 | <indexterm> | |
6333 | <primary>fs commands</primary> | |
6334 | ||
6335 | <secondary>mkmount</secondary> | |
6336 | ||
6337 | <tertiary>when restoring volume</tertiary> | |
6338 | </indexterm> | |
6339 | </listitem> | |
6340 | ||
6341 | <listitem> | |
6342 | <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the new volume, making its contents | |
6343 | accessible. Complete instructions appear in <link linkend="HDRWQ212">To create a regular or read/write mount point</link>. | |
6344 | <programlisting> | |
6345 | % <emphasis role="bold">fs mkmount</emphasis> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>> | |
6346 | </programlisting></para> | |
6347 | </listitem> | |
6348 | ||
6349 | <listitem> | |
6350 | <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs lsmount</emphasis> command to verify | |
6351 | that the mount point refers to the correct volume. Complete instructions appear in <link linkend="HDRWQ211">To display a | |
6352 | mount point</link>. <programlisting> | |
6353 | % <emphasis role="bold">fs lsmount</emphasis> <<replaceable>directory</replaceable>> | |
6354 | </programlisting></para> | |
6355 | </listitem> | |
6356 | </orderedlist> | |
6357 | ||
6358 | <indexterm> | |
6359 | <primary>commands</primary> | |
6360 | ||
6361 | <secondary>vos restore</secondary> | |
6362 | </indexterm> | |
6363 | ||
6364 | <indexterm> | |
6365 | <primary>vos commands</primary> | |
6366 | ||
6367 | <secondary>restore</secondary> | |
6368 | ||
6369 | <tertiary>to overwrite volume</tertiary> | |
6370 | </indexterm> | |
6371 | </sect2> | |
6372 | ||
6373 | <sect2 id="HDRWQ244"> | |
6374 | <title>To restore a dump file, overwriting an existing volume</title> | |
6375 | ||
6376 | <orderedlist> | |
6377 | <listitem> | |
6378 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
6379 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
6380 | display the users in the UserList file</link>. <programlisting> | |
6381 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
6382 | </programlisting></para> | |
6383 | </listitem> | |
6384 | ||
6385 | <listitem> | |
6386 | <para>Verify that you have permissions needed to read the dump file. If it resides in AFS, you need the <emphasis | |
6387 | role="bold">r</emphasis>( <emphasis role="bold">read</emphasis>) permission on the ACL of its directory. If necessary, | |
6388 | issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link | |
6389 | linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
6390 | % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
6391 | </programlisting></para> | |
6392 | ||
6393 | <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis | |
6394 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis | |
6395 | role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis | |
6396 | role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para> | |
6397 | </listitem> | |
6398 | ||
6399 | <listitem> | |
6400 | <para>Restore the contents of the dump file into a read/write volume, overwriting the current contents. The volume retains | |
6401 | its current volume ID number. Type it on a single line; it appears on multiple lines here only for legibility. | |
6402 | <programlisting> | |
6403 | % <emphasis role="bold">vos restore</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> \ | |
6404 | <<replaceable>name of volume to be restored</replaceable>> \ | |
6405 | [<emphasis role="bold">-file</emphasis> <<replaceable>dump file</replaceable>>] [<emphasis role="bold">-id</emphasis> <<replaceable>volume ID</replaceable>>] | |
6406 | </programlisting></para> | |
6407 | ||
6408 | <para>where <variablelist> | |
6409 | <varlistentry> | |
6410 | <term><emphasis role="bold">res</emphasis></term> | |
6411 | ||
6412 | <listitem> | |
6413 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">restore</emphasis>.</para> | |
6414 | </listitem> | |
6415 | </varlistentry> | |
6416 | ||
6417 | <varlistentry> | |
6418 | <term><emphasis role="bold">machine name</emphasis></term> | |
6419 | ||
6420 | <listitem> | |
6421 | <para>Names the file server machine where the volume already exists, or the machine to which to move it. In the | |
6422 | latter case, the value for the <emphasis role="bold">-overwrite</emphasis> argument must be <emphasis | |
6423 | role="bold">full</emphasis>.</para> | |
6424 | </listitem> | |
6425 | </varlistentry> | |
6426 | ||
6427 | <varlistentry> | |
6428 | <term><emphasis role="bold">partition name</emphasis></term> | |
6429 | ||
6430 | <listitem> | |
6431 | <para>Names the partition where the volume already exists, or the partition to which to move it. In the latter | |
6432 | case, the value for the <emphasis role="bold">-overwrite</emphasis> argument must be <emphasis | |
6433 | role="bold">full</emphasis>.</para> | |
6434 | </listitem> | |
6435 | </varlistentry> | |
6436 | ||
6437 | <varlistentry> | |
6438 | <term><emphasis role="bold">name of volume to be restored</emphasis></term> | |
6439 | ||
6440 | <listitem> | |
6441 | <para>Names the read/write volume to overwrite with the contents of the dump file.</para> | |
6442 | </listitem> | |
6443 | </varlistentry> | |
6444 | ||
6445 | <varlistentry> | |
6446 | <term><emphasis role="bold">-file</emphasis></term> | |
6447 | ||
6448 | <listitem> | |
6449 | <para>Is the dump file to restore. Partial pathnames are interpreted with respect to the current working | |
6450 | directory. Omit this argument if using a pipe to read in the dump file from the standard input stream; in this | |
6451 | case, you must provide the <emphasis role="bold">-overwrite</emphasis> argument.</para> | |
6452 | </listitem> | |
6453 | </varlistentry> | |
6454 | ||
6455 | <varlistentry> | |
6456 | <term><emphasis role="bold">-overwrite</emphasis></term> | |
6457 | ||
6458 | <listitem> | |
6459 | <para>Preconfirms that you want to overwrite the existing volume and specifies which type of dump file you are | |
6460 | restoring. Provide one of the following values: <itemizedlist> | |
6461 | <listitem> | |
6462 | <para><emphasis role="bold">f</emphasis> or <emphasis role="bold">full</emphasis> if restoring a full dump | |
6463 | file</para> | |
6464 | </listitem> | |
6465 | ||
6466 | <listitem> | |
6467 | <para><emphasis role="bold">i</emphasis> or <emphasis role="bold">incremental</emphasis> if restoring an | |
6468 | incremental dump file. This value is not acceptable if you are moving the volume while restoring it.</para> | |
6469 | </listitem> | |
6470 | ||
6471 | <listitem> | |
6472 | <para><emphasis role="bold">a</emphasis> to terminate the restore operation</para> | |
6473 | </listitem> | |
6474 | </itemizedlist></para> | |
6475 | </listitem> | |
6476 | </varlistentry> | |
6477 | </variablelist></para> | |
6478 | </listitem> | |
6479 | ||
6480 | <listitem> | |
6481 | <para>If the volume is replicated, issue the <emphasis role="bold">vos release</emphasis> command to release the newly | |
6482 | restored contents to read-only sites. Complete instructions appear in <link linkend="HDRWQ192">Replicating Volumes | |
6483 | (Creating Read-only Volumes)</link>. <programlisting> | |
6484 | % <emphasis role="bold">vos release</emphasis> <<replaceable>volume name or ID</replaceable>> | |
6485 | </programlisting></para> | |
6486 | </listitem> | |
6487 | ||
6488 | <listitem> | |
6489 | <para>Issue the <emphasis role="bold">vos backup</emphasis> command to create a new backup version of the volume. Complete | |
6490 | instructions appear in <link linkend="HDRWQ201">Creating Backup Volumes</link>. <programlisting> | |
6491 | % <emphasis role="bold">vos backup</emphasis> <<replaceable>volume name or ID</replaceable>> | |
6492 | </programlisting></para> | |
6493 | </listitem> | |
6494 | </orderedlist> | |
6495 | </sect2> | |
6496 | </sect1> | |
6497 | ||
6498 | <sect1 id="HDRWQ245"> | |
6499 | <title>Renaming Volumes</title> | |
6500 | ||
6501 | <indexterm> | |
6502 | <primary>renaming</primary> | |
6503 | ||
6504 | <secondary>volume</secondary> | |
6505 | </indexterm> | |
6506 | ||
6507 | <indexterm> | |
6508 | <primary>volume</primary> | |
6509 | ||
6510 | <secondary>renaming</secondary> | |
6511 | </indexterm> | |
6512 | ||
6513 | <indexterm> | |
6514 | <primary>changing</primary> | |
6515 | ||
6516 | <secondary>volume name</secondary> | |
6517 | </indexterm> | |
6518 | ||
6519 | <indexterm> | |
6520 | <primary>volume name</primary> | |
6521 | ||
6522 | <secondary>changing</secondary> | |
6523 | ||
6524 | <tertiary>basic instructions</tertiary> | |
6525 | </indexterm> | |
6526 | ||
6527 | <para>You can use the <emphasis role="bold">vos rename</emphasis> command to rename a volume. For example, it is appropriate to | |
6528 | rename a user's home volume if you use the <emphasis role="bold">user.</emphasis> username convention for user volume names and | |
6529 | you change the username. (For complete instructions for changing usernames, see <link linkend="HDRWQ518">Changing | |
6530 | Usernames</link>.)</para> | |
6531 | ||
6532 | <indexterm> | |
6533 | <primary>read/write volume</primary> | |
6534 | ||
6535 | <secondary>changing name of</secondary> | |
6536 | </indexterm> | |
6537 | ||
6538 | <indexterm> | |
6539 | <primary>read-only volume</primary> | |
6540 | ||
6541 | <secondary>changing name of</secondary> | |
6542 | </indexterm> | |
6543 | ||
6544 | <indexterm> | |
6545 | <primary>backup volume</primary> | |
6546 | ||
6547 | <secondary>changing name of</secondary> | |
6548 | </indexterm> | |
6549 | ||
6550 | <para>The <emphasis role="bold">vos rename</emphasis> command accepts only read/write volume names, but automatically changes | |
6551 | the names of the associated read-only and backup volumes. As directed in the following instructions, you need to replace the | |
6552 | volume's current mount point with a new one that reflects the name change.</para> | |
6553 | ||
6554 | <indexterm> | |
6555 | <primary>commands</primary> | |
6556 | ||
6557 | <secondary>vos rename</secondary> | |
6558 | ||
6559 | <tertiary>basic instructions</tertiary> | |
6560 | </indexterm> | |
6561 | ||
6562 | <indexterm> | |
6563 | <primary>vos commands</primary> | |
6564 | ||
6565 | <secondary>rename</secondary> | |
6566 | ||
6567 | <tertiary>basic instructions</tertiary> | |
6568 | </indexterm> | |
6569 | ||
6570 | <sect2 id="HDRWQ246"> | |
6571 | <title>To rename a volume</title> | |
6572 | ||
6573 | <orderedlist> | |
6574 | <listitem> | |
6575 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
6576 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
6577 | display the users in the UserList file</link>. <programlisting> | |
6578 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
6579 | </programlisting></para> | |
6580 | </listitem> | |
6581 | ||
6582 | <listitem> | |
6583 | <para>Verify that you have the <emphasis role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>), <emphasis | |
6584 | role="bold">d</emphasis>( <emphasis role="bold">delete</emphasis>), and <emphasis role="bold">i</emphasis>( <emphasis | |
6585 | role="bold">insert</emphasis>) access permissions for the directory in which you are replacing the volume's mount point. | |
6586 | If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link | |
6587 | linkend="HDRWQ572">Displaying ACLs</link>. <programlisting> | |
6588 | % <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>] | |
6589 | </programlisting></para> | |
6590 | ||
6591 | <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis | |
6592 | role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis | |
6593 | role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis | |
6594 | role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para> | |
6595 | </listitem> | |
6596 | ||
6597 | <listitem id="LIVOL-REN"> | |
6598 | <para>Issue the <emphasis role="bold">vos rename</emphasis> command to rename the volume. | |
6599 | <programlisting> | |
6600 | % <emphasis role="bold">vos rename</emphasis> <<replaceable>old volume name</replaceable>> <<replaceable>new volume name</replaceable>> | |
6601 | </programlisting></para> | |
6602 | ||
6603 | <para>where <variablelist> | |
6604 | <varlistentry> | |
6605 | <term><emphasis role="bold">ren</emphasis></term> | |
6606 | ||
6607 | <listitem> | |
6608 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">rename</emphasis>.</para> | |
6609 | </listitem> | |
6610 | </varlistentry> | |
6611 | ||
6612 | <varlistentry> | |
6613 | <term><emphasis role="bold">old volume name</emphasis></term> | |
6614 | ||
6615 | <listitem> | |
6616 | <para>Is the current name of a read/write volume.</para> | |
6617 | </listitem> | |
6618 | </varlistentry> | |
6619 | ||
6620 | <varlistentry> | |
6621 | <term><emphasis role="bold">new volume name</emphasis></term> | |
6622 | ||
6623 | <listitem> | |
6624 | <para>Is the new name for the volume. It cannot be more than 22 characters in length.</para> | |
6625 | </listitem> | |
6626 | </varlistentry> | |
6627 | </variablelist></para> | |
6628 | ||
6629 | <para>If there is no Volume Location Database (VLDB) entry for the specified current volume name, the command fails with | |
6630 | the following error message:</para> | |
6631 | ||
6632 | <programlisting> | |
6633 | vos: Could not find entry for volume old_volume_name. | |
6634 | </programlisting> | |
6635 | ||
6636 | <indexterm> | |
6637 | <primary>commands</primary> | |
6638 | ||
6639 | <secondary>fs rmmount</secondary> | |
6640 | </indexterm> | |
6641 | ||
6642 | <indexterm> | |
6643 | <primary>fs commands</primary> | |
6644 | ||
6645 | <secondary>rmmount</secondary> | |
6646 | ||
6647 | <tertiary>when renaming volume</tertiary> | |
6648 | </indexterm> | |
6649 | </listitem> | |
6650 | ||
6651 | <listitem> | |
6652 | <para>Issue the <emphasis role="bold">fs rmmount</emphasis> command to remove the mount point that refers to the volume's | |
6653 | old name. Complete instructions appear in <link linkend="HDRWQ215">To remove a mount point</link>. <programlisting> | |
6654 | % <emphasis role="bold">fs rmmount</emphasis> <<replaceable>directory</replaceable>> | |
6655 | </programlisting></para> | |
6656 | ||
6657 | <indexterm> | |
6658 | <primary>commands</primary> | |
6659 | ||
6660 | <secondary>fs mkmount</secondary> | |
6661 | ||
6662 | <tertiary>when renaming volume</tertiary> | |
6663 | </indexterm> | |
6664 | ||
6665 | <indexterm> | |
6666 | <primary>fs commands</primary> | |
6667 | ||
6668 | <secondary>mkmount</secondary> | |
6669 | ||
6670 | <tertiary>when renaming volume</tertiary> | |
6671 | </indexterm> | |
6672 | </listitem> | |
6673 | ||
6674 | <listitem> | |
6675 | <para>Issue the <emphasis role="bold">fs mkmount</emphasis> to create a mount point that indicates the volume's new name. | |
6676 | Complete instructions appear in <link linkend="HDRWQ212">To create a regular or read/write mount point</link>. | |
6677 | <programlisting> | |
6678 | % <emphasis role="bold">fs mkmount</emphasis> <<replaceable>directory</replaceable>> <<replaceable>volume name</replaceable>> [<emphasis | |
6679 | role="bold">-rw</emphasis>] | |
6680 | </programlisting></para> | |
6681 | </listitem> | |
6682 | </orderedlist> | |
6683 | </sect2> | |
6684 | </sect1> | |
6685 | ||
6686 | <sect1 id="HDRWQ247"> | |
6687 | <title>Unlocking and Locking VLDB Entries</title> | |
6688 | ||
6689 | <para>As detailed in <link linkend="HDRWQ227">Synchronizing the VLDB and Volume Headers</link>, The Volume Location (VL) Server | |
6690 | locks the Volume Location Database (VLDB) entry for a volume before the Volume Server executes any operation on it. No other | |
6691 | operation can affect a volume with a locked VLDB entry, so the lock prevents the inconsistency or corruption that can result | |
6692 | from multiple simultaneous operations on a volume.</para> | |
6693 | ||
6694 | <indexterm> | |
6695 | <primary>locking</primary> | |
6696 | ||
6697 | <secondary>VLDB entry</secondary> | |
6698 | </indexterm> | |
6699 | ||
6700 | <indexterm> | |
6701 | <primary>VLDB</primary> | |
6702 | ||
6703 | <secondary>locking/unlocking entry</secondary> | |
6704 | </indexterm> | |
6705 | ||
6706 | <indexterm> | |
6707 | <primary>entry in VLDB</primary> | |
6708 | ||
6709 | <secondary>locking/unlocking</secondary> | |
6710 | </indexterm> | |
6711 | ||
6712 | <indexterm> | |
6713 | <primary>unlocking</primary> | |
6714 | ||
6715 | <secondary>VLDB entry</secondary> | |
6716 | </indexterm> | |
6717 | ||
6718 | <indexterm> | |
6719 | <primary>locked VLDB entry</primary> | |
6720 | ||
6721 | <secondary>unlocking</secondary> | |
6722 | </indexterm> | |
6723 | ||
6724 | <para>To verify that a VLDB entry is locked, issue the <emphasis role="bold">vos listvldb</emphasis> command as described in | |
6725 | <link linkend="HDRWQ218">To display VLDB entries</link>. The command has a <emphasis role="bold">-locked</emphasis> flag that | |
6726 | displays locked entries only. If the VLDB entry is locked, the string <computeroutput>Volume is currently | |
6727 | LOCKED</computeroutput> appears on the last line of the volume's output.</para> | |
6728 | ||
6729 | <para>To lock a VLDB entry yourself, use the <emphasis role="bold">vos lock</emphasis> command. This is useful when you suspect | |
6730 | something is wrong with a volume and you want to prevent any changes to it while you are investigating the problem.</para> | |
6731 | ||
6732 | <para>To unlock a locked VLDB entry, issue the <emphasis role="bold">vos unlock</emphasis> command, which unlocks a single VLDB | |
6733 | entry, or the <emphasis role="bold">vos unlockvldb</emphasis> command, which unlocks potentially many entries. This is useful | |
6734 | when a volume operation fails prematurely and leaves a VLDB entry locked, preventing you from acting to correct the problems | |
6735 | resulting from the failure.</para> | |
6736 | ||
6737 | <indexterm> | |
6738 | <primary>commands</primary> | |
6739 | ||
6740 | <secondary>vos lock</secondary> | |
6741 | </indexterm> | |
6742 | ||
6743 | <indexterm> | |
6744 | <primary>vos commands</primary> | |
6745 | ||
6746 | <secondary>lock</secondary> | |
6747 | </indexterm> | |
6748 | ||
6749 | <sect2 id="Header_267"> | |
6750 | <title>To lock a VLDB entry</title> | |
6751 | ||
6752 | <orderedlist> | |
6753 | <listitem> | |
6754 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
6755 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
6756 | display the users in the UserList file</link>. <programlisting> | |
6757 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
6758 | </programlisting></para> | |
6759 | </listitem> | |
6760 | ||
6761 | <listitem> | |
6762 | <para>Issue the <emphasis role="bold">vos lock</emphasis> to lock the entry. <programlisting> | |
6763 | % <emphasis role="bold">vos lock</emphasis> <<replaceable>volume name or ID</replaceable>> | |
6764 | </programlisting></para> | |
6765 | ||
6766 | <para>where <variablelist> | |
6767 | <varlistentry> | |
6768 | <term><emphasis role="bold">lo</emphasis></term> | |
6769 | ||
6770 | <listitem> | |
6771 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">lock</emphasis>.</para> | |
6772 | </listitem> | |
6773 | </varlistentry> | |
6774 | ||
6775 | <varlistentry> | |
6776 | <term><emphasis role="bold">volume name or ID</emphasis></term> | |
6777 | ||
6778 | <listitem> | |
6779 | <para>Identifies the volume to be locked, either by its complete name or volume ID number. It can be any of the | |
6780 | three versions of the volume.</para> | |
6781 | </listitem> | |
6782 | </varlistentry> | |
6783 | </variablelist></para> | |
6784 | </listitem> | |
6785 | </orderedlist> | |
6786 | ||
6787 | <indexterm> | |
6788 | <primary>commands</primary> | |
6789 | ||
6790 | <secondary>vos unlock</secondary> | |
6791 | </indexterm> | |
6792 | ||
6793 | <indexterm> | |
6794 | <primary>vos commands</primary> | |
6795 | ||
6796 | <secondary>unlock</secondary> | |
6797 | </indexterm> | |
6798 | </sect2> | |
6799 | ||
6800 | <sect2 id="Header_268"> | |
6801 | <title>To unlock a single VLDB entry</title> | |
6802 | ||
6803 | <orderedlist> | |
6804 | <listitem> | |
6805 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
6806 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
6807 | display the users in the UserList file</link>. <programlisting> | |
6808 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
6809 | </programlisting></para> | |
6810 | </listitem> | |
6811 | ||
6812 | <listitem> | |
6813 | <para>Issue the <emphasis role="bold">vos unlock</emphasis> command to unlock the entry. <programlisting> | |
6814 | % <emphasis role="bold">vos unlock</emphasis> <<replaceable>volume name or ID</replaceable>> | |
6815 | </programlisting></para> | |
6816 | ||
6817 | <para>where <variablelist> | |
6818 | <varlistentry> | |
6819 | <term><emphasis role="bold">unlock</emphasis></term> | |
6820 | ||
6821 | <listitem> | |
6822 | <para>Must be typed in full.</para> | |
6823 | </listitem> | |
6824 | </varlistentry> | |
6825 | ||
6826 | <varlistentry> | |
6827 | <term><emphasis role="bold">volume name or ID</emphasis></term> | |
6828 | ||
6829 | <listitem> | |
6830 | <para>Identifies the volume to be unlocked, either by its complete name or volume ID number. It can be any of the | |
6831 | three versions of the volume.</para> | |
6832 | </listitem> | |
6833 | </varlistentry> | |
6834 | </variablelist></para> | |
6835 | </listitem> | |
6836 | </orderedlist> | |
6837 | ||
6838 | <indexterm> | |
6839 | <primary>commands</primary> | |
6840 | ||
6841 | <secondary>vos unlockvldb</secondary> | |
6842 | </indexterm> | |
6843 | ||
6844 | <indexterm> | |
6845 | <primary>vos commands</primary> | |
6846 | ||
6847 | <secondary>unlockvldb</secondary> | |
6848 | </indexterm> | |
6849 | </sect2> | |
6850 | ||
6851 | <sect2 id="Header_269"> | |
6852 | <title>To unlock multiple VLDB entries</title> | |
6853 | ||
6854 | <orderedlist> | |
6855 | <listitem> | |
6856 | <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue | |
6857 | the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To | |
6858 | display the users in the UserList file</link>. <programlisting> | |
6859 | % <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>> | |
6860 | </programlisting></para> | |
6861 | </listitem> | |
6862 | ||
6863 | <listitem> | |
6864 | <para>Issue the <emphasis role="bold">vos unlockvldb</emphasis> command to unlock the desired entries. <programlisting> | |
6865 | % <emphasis role="bold">vos unlockvldb</emphasis> [<<replaceable>machine name</replaceable>>] [<<replaceable>partition name</replaceable>>] | |
6866 | </programlisting></para> | |
6867 | ||
6868 | <para>where <variablelist> | |
6869 | <varlistentry> | |
6870 | <term><emphasis role="bold">unlockv</emphasis></term> | |
6871 | ||
6872 | <listitem> | |
6873 | <para>Is the shortest acceptable abbreviation of <emphasis role="bold">unlockvldb</emphasis>.</para> | |
6874 | </listitem> | |
6875 | </varlistentry> | |
6876 | ||
6877 | <varlistentry> | |
6878 | <term><emphasis role="bold">machine name</emphasis></term> | |
6879 | ||
6880 | <listitem> | |
6881 | <para>Specifies a file server machine. Provide this argument alone to unlock all VLDB entries that mention the | |
6882 | machine in a site definition. Omit both this argument and the partition name argument to unlock all VLDB | |
6883 | entries.</para> | |
6884 | </listitem> | |
6885 | </varlistentry> | |
6886 | ||
6887 | <varlistentry> | |
6888 | <term><emphasis role="bold">partition name</emphasis></term> | |
6889 | ||
6890 | <listitem> | |
6891 | <para>Specifies a partition. Provide this argument alone to unlock all VLDB entries that mention the partition (on | |
6892 | any machine) in a site definition. Omit both this argument and the machine name argument to unlock all VLDB | |
6893 | entries.</para> | |
6894 | </listitem> | |
6895 | </varlistentry> | |
6896 | </variablelist></para> | |
6897 | </listitem> | |
6898 | </orderedlist> | |
6899 | </sect2> | |
6900 | </sect1> | |
6901 | </chapter> |