9200b2bb01b1ebeb345877b3bb5a3d8f072fa395
[openafs.git] / doc / xml / AdminGuide / auagd010.xml
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> &lt;<replaceable>machine name</replaceable>&gt;
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> [&lt;<emphasis>dir/file path</emphasis>&gt;]</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>
734           <para><anchor id="LIWQ186" />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> &lt;<emphasis>machine name</emphasis>&gt; [&lt;<emphasis>partition name</emphasis>&gt;]</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>
778           <para><anchor id="LIWQ187" />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>
799           <para><anchor id="LIWQ188" />Issue the <emphasis role="bold">vos create</emphasis> command to create the volume.
800           <programlisting>
801    % <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt; \
802         [<emphasis role="bold">-maxquota</emphasis> &lt;<replaceable>initial quota (KB)</replaceable>&gt;]
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>
878           <anchor id="LIWQ189" />
879
880           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount
881           the volume in the filespace. For complete syntax, see <link linkend="HDRWQ212">To create a regular or read/write mount
882           point</link>. <programlisting>
883    % <emphasis role="bold">fs mkmount</emphasis> &lt;<emphasis>directory</emphasis>&gt; &lt;<emphasis>volume name</emphasis>&gt;</programlisting></para>
884         </listitem>
885
886         <listitem>
887           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs lsmount</emphasis> command to verify
888           that the mount point refers to the correct volume. Complete instructions appear in <link linkend="HDRWQ211">To display a
889           mount point</link>. <programlisting>
890    % <emphasis role="bold">fs lsmount</emphasis> &lt;<emphasis>directory</emphasis>&gt;</programlisting></para>
891         </listitem>
892
893         <listitem>
894           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs setvol</emphasis> command with the
895           <emphasis role="bold">-offlinemsg</emphasis> argument to record auxiliary information about the volume in its volume
896           header. For example, you can record who owns the volume or where you have mounted it in the filespace. To display the
897           information, use the <emphasis role="bold">fs examine</emphasis> command. <programlisting>
898    % <emphasis role="bold">fs setvol</emphasis> &lt;<replaceable>dir/file path</replaceable>&gt; <emphasis role="bold">-offlinemsg </emphasis> &lt;<replaceable>offline message</replaceable>&gt;
899 </programlisting></para>
900
901           <para>where <variablelist>
902               <varlistentry>
903                 <term><emphasis role="bold">sv</emphasis></term>
904
905                 <listitem>
906                   <para>Is an acceptable alias for <emphasis role="bold">setvol</emphasis>(and <emphasis role="bold">setv</emphasis>
907                   the shortest acceptable abbreviation).</para>
908                 </listitem>
909               </varlistentry>
910
911               <varlistentry>
912                 <term><emphasis role="bold">dir/file path</emphasis></term>
913
914                 <listitem>
915                   <para>Names the mount point of the volume with which to associate the message. Partial pathnames are interpreted
916                   relative to the current working directory.</para>
917
918                   <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to change
919                   a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at
920                   the pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). For further discussion
921                   of the concept of read/write and read-only paths through the filespace, see <link linkend="HDRWQ209">The Rules of
922                   Mount Point Traversal</link>.</para>
923                 </listitem>
924               </varlistentry>
925
926               <varlistentry>
927                 <term><emphasis role="bold">-offlinemsg</emphasis></term>
928
929                 <listitem>
930                   <para>Specifies up to 128 characters of auxiliary information to record in the volume header.</para>
931                 </listitem>
932               </varlistentry>
933             </variablelist></para>
934         </listitem>
935       </orderedlist>
936     </sect2>
937   </sect1>
938
939   <sect1 id="HDRWQ190">
940     <title>About Clones and Cloning</title>
941
942     <indexterm>
943       <primary>cloning</primary>
944
945       <secondary>defined</secondary>
946     </indexterm>
947
948     <indexterm>
949       <primary>clone</primary>
950     </indexterm>
951
952     <indexterm>
953       <primary>vnode index</primary>
954     </indexterm>
955
956     <indexterm>
957       <primary>backup volume</primary>
958
959       <secondary>space-saving nature of</secondary>
960     </indexterm>
961
962     <para>To create a backup or read-only volume, the Volume Server begins by <emphasis>cloning</emphasis> the read/write source
963     volume to create a <emphasis>clone</emphasis>. The Volume Server creates the clone automatically when you issue the <emphasis
964     role="bold">vos backup</emphasis> or <emphasis role="bold">vos backupsys</emphasis> command (for a backup volume) or the
965     <emphasis role="bold">vos release</emphasis> command (for a read-only volume). No special action is required on your
966     part.</para>
967
968     <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
969     <emphasis>vnode index</emphasis>. The vnode index is a table of pointers between the files and directories in the volume and the
970     physical disk blocks on the partition where the data resides. From the clone, backup and read-only volumes are created in the
971     following manner: <itemizedlist>
972         <listitem>
973           <para>A read-only volume that occupies the same partition as its read/write source (also known as a <emphasis>read-only
974           clone</emphasis>), and a backup volume, are created by attaching a volume header to the clone. These volumes initially
975           consume very little disk space, because the clone portion (the vnode index) points to exactly the same files as the
976           read/write volume, as illustrated in <link linkend="FIGWQ191">Figure 1</link>. The file sharing is possible only because
977           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
978           not actually removed from the partition, because the backup or read-only clone still points to it. Similarly, when a file
979           in the read/write is changed, the entire original file is preserved on disk because the clone still points to it, and the
980           read/write volume's vnode index changes to point to newly space for the changed file. When this happens, the backup or
981           read-only volume is said to grow or start occupying actual disk space.</para>
982         </listitem>
983
984         <listitem>
985           <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
986           the data in the read/write source volume. It occupies the same amount of disk space as the read/write volume did at the
987           time the read-only volume was created.</para>
988         </listitem>
989       </itemizedlist></para>
990
991     <figure id="FIGWQ191" label="1">
992       <title>File Sharing Between the Read/write Source and a Clone Volume</title>
993
994       <mediaobject>
995         <imageobject>
996           <imagedata fileref="vnode.png" scale="50" />
997         </imageobject>
998       </mediaobject>
999     </figure>
1000
1001     <indexterm>
1002       <primary>replication</primary>
1003
1004       <secondary>detailed discussion</secondary>
1005     </indexterm>
1006
1007     <indexterm>
1008       <primary>volume</primary>
1009
1010       <secondary>replicating</secondary>
1011     </indexterm>
1012
1013     <indexterm>
1014       <primary>volume</primary>
1015
1016       <secondary>read-only</secondary>
1017
1018       <see>read-only volume</see>
1019     </indexterm>
1020
1021     <indexterm>
1022       <primary>read-only volume</primary>
1023
1024       <secondary>creating</secondary>
1025     </indexterm>
1026
1027     <indexterm>
1028       <primary>creating</primary>
1029
1030       <secondary>read-only volume</secondary>
1031     </indexterm>
1032
1033     <indexterm>
1034       <primary>cloning</primary>
1035
1036       <secondary>for replication</secondary>
1037     </indexterm>
1038
1039     <indexterm>
1040       <primary>read/write volume</primary>
1041
1042       <secondary>cloning</secondary>
1043
1044       <tertiary>for replication</tertiary>
1045     </indexterm>
1046   </sect1>
1047
1048   <sect1 id="HDRWQ192">
1049     <title>Replicating Volumes (Creating Read-only Volumes)</title>
1050
1051     <para><emphasis>Replication</emphasis> refers to creating a read-only copy of a read/write volume and distributing the copy to
1052     one or more additional file server machines. Replication makes a volume's contents accessible on more than one file server
1053     machine, which increases data availability. It can also increase system efficiency by reducing load on the network and File
1054     Server. Network load is reduced if a client machine's server preference ranks lead the Cache Manager to access the copy of a
1055     volume stored on the closest file server machine. Load on the File Server is reduced because it issues only one callback for all
1056     data fetched from a read-only volume, as opposed to a callback for each file fetched from a read/write volume. The single
1057     callback is sufficient for an entire read-only volume because the volume does not change except in response to administrator
1058     action, whereas each read/write file can change at any time.</para>
1059
1060     <indexterm>
1061       <primary>stages in volume replication</primary>
1062     </indexterm>
1063
1064     <indexterm>
1065       <primary>site definition stage in replication</primary>
1066     </indexterm>
1067
1068     <indexterm>
1069       <primary>replication</primary>
1070
1071       <secondary>site definition stage</secondary>
1072     </indexterm>
1073
1074     <indexterm>
1075       <primary>release stage in replication</primary>
1076     </indexterm>
1077
1078     <indexterm>
1079       <primary>replication</primary>
1080
1081       <secondary>release stage</secondary>
1082     </indexterm>
1083
1084     <para>Replicating a volume requires issuing two commands. First, use the <emphasis role="bold">vos addsite</emphasis> command to
1085     add one or more read-only site definitions to the volume's VLDB entry (a <emphasis>site</emphasis> is a particular partition on
1086     a file server machine). Then use the <emphasis role="bold">vos release</emphasis> command to clone the read/write source volume
1087     and distribute the clone to the defined read-only sites. You issue the <emphasis role="bold">vos addsite</emphasis> only once
1088     for each read-only site, but must reissue the <emphasis role="bold">vos release</emphasis> command every time the read/write
1089     volume's contents change and you want to update the read-only volumes.</para>
1090
1091     <para>For users to have a consistent view of the file system, the release of updated volume contents to read-only sites must be
1092     atomic: either all read-only sites receive the new version of the volume, or all sites keep the version they currently have. The
1093     <emphasis role="bold">vos release</emphasis> command is designed to ensure that all copies of the volume's read-only version
1094     match both the read/write source and each other. In cases where problems such as machine or server process outages prevent
1095     successful completion of the release operation, AFS uses two mechanisms to alert you.</para>
1096
1097     <indexterm>
1098       <primary>replication</primary>
1099
1100       <secondary>determining success of</secondary>
1101     </indexterm>
1102
1103     <indexterm>
1104       <primary>determining</primary>
1105
1106       <secondary>success of replication</secondary>
1107     </indexterm>
1108
1109     <indexterm>
1110       <primary>replication</primary>
1111
1112       <secondary>need for all-or-nothing release</secondary>
1113     </indexterm>
1114
1115     <indexterm>
1116       <primary>all-or-nothing release of read-only volumes</primary>
1117     </indexterm>
1118
1119     <indexterm>
1120       <primary>read-only volume</primary>
1121
1122       <secondary>need for atomic release</secondary>
1123     </indexterm>
1124
1125     <indexterm>
1126       <primary>releasing</primary>
1127
1128       <secondary>read-only volume, need for atomicity</secondary>
1129     </indexterm>
1130
1131     <indexterm>
1132       <primary>ReleaseClone</primary>
1133     </indexterm>
1134
1135     <indexterm>
1136       <primary>replication</primary>
1137
1138       <secondary>role of ReleaseClone</secondary>
1139     </indexterm>
1140
1141     <indexterm>
1142       <primary>New release site flag in VLDB</primary>
1143
1144       <secondary>as indicator of failed replication</secondary>
1145     </indexterm>
1146
1147     <indexterm>
1148       <primary>Old release site flag in VLDB</primary>
1149
1150       <secondary>as indicator of failed replication</secondary>
1151     </indexterm>
1152
1153     <indexterm>
1154       <primary>clone</primary>
1155
1156       <secondary>forcing creation of new</secondary>
1157     </indexterm>
1158
1159     <indexterm>
1160       <primary>replication</primary>
1161
1162       <secondary>forcing creation of new clone</secondary>
1163     </indexterm>
1164
1165     <indexterm>
1166       <primary>vos commands</primary>
1167
1168       <secondary>release</secondary>
1169
1170       <tertiary>forcing new cloning with -f flag</tertiary>
1171     </indexterm>
1172
1173     <indexterm>
1174       <primary>releasing</primary>
1175
1176       <secondary>read-only volume, forcing new cloning</secondary>
1177     </indexterm>
1178
1179     <para>First, the command interpreter generates an error message on the standard error stream naming each read-only site that did
1180     not receive the new volume version. Second, during the release operation the Volume Location (VL) Server marks site definitions
1181     in the VLDB entry with flags (<computeroutput>New release</computeroutput> and <computeroutput>Old release</computeroutput>)
1182     that indicate whether or not the site has the new volume version. If any flags remain after the operation completes, it was not
1183     successful. The Cache Manager refuses to access a read-only site marked with the <computeroutput>Old release</computeroutput>
1184     flag, which potentially imposes a greater load on the sites marked with the <computeroutput>New release</computeroutput> flag.
1185     It is important to investigate and eliminate the cause of the failure and then to issue the <emphasis role="bold">vos
1186     release</emphasis> command as many times as necessary to complete the release without errors.</para>
1187
1188     <para>The pattern of site flags remaining in the volume's VLDB entry after a failed release operation can help determine the
1189     point at which the operation failed. Use the <emphasis role="bold">vos examine</emphasis> or <emphasis role="bold">vos
1190     listvldb</emphasis> command to display the VLDB entry. The VL Server sets the flags in concert with the Volume Server's
1191     operations, as follows: <orderedlist>
1192         <listitem>
1193           <para>Before the operation begins, the VL Server sets the <computeroutput>New release</computeroutput> flag on the
1194           read/write site definition in the VLDB entry and the <computeroutput>Old release</computeroutput> flag on read-only site
1195           definitions (unless the read-only site has been defined since the last release operation and has no actual volume, in
1196           which case its site flag remains <computeroutput>Not released</computeroutput>).</para>
1197         </listitem>
1198
1199         <listitem>
1200           <para>If necessary, the Volume Server creates a temporary copy (a <emphasis>clone</emphasis>) of the read/write source
1201           called the ReleaseClone (see the following discussion of when the Volume Server does or does not create a new
1202           ReleaseClone.) It assigns the ReleaseClone its own volume ID number, which the VL Server records in the
1203           <computeroutput>RClone</computeroutput> field of the source volume's VLDB entry.</para>
1204         </listitem>
1205
1206         <listitem>
1207           <para>The Volume Server distributes a copy of the ReleaseClone to each read-only site defined in the VLDB entry. As the
1208           site successfully receives the new clone, the VL Server sets the site's flag in the VLDB entry to <computeroutput>New
1209           release</computeroutput>.</para>
1210         </listitem>
1211
1212         <listitem>
1213           <para>When all the read-only copies are successfully released, the VL Server clears all the <computeroutput>New
1214           release</computeroutput> site flags. The ReleaseClone is no longer needed, so the Volume Server deletes it and the VL
1215           Server erases its ID from the VLDB entry.</para>
1216         </listitem>
1217       </orderedlist></para>
1218
1219     <para>By default, the Volume Server determines automatically whether or not it needs to create a new ReleaseClone: <itemizedlist>
1220         <listitem>
1221           <para>If there are no flags (<computeroutput>New release</computeroutput>, <computeroutput>Old release</computeroutput>,
1222           or <computeroutput>Not released</computeroutput>) on site definitions in the VLDB entry, the previous <emphasis
1223           role="bold">vos release</emphasis> command completed successfully and all read-only sites currently have the same volume.
1224           The Volume Server infers that the current <emphasis role="bold">vos release</emphasis> command was issued because the
1225           read/write volume has changed. The Volume Server creates a new ReleaseClone and distributes it to all of the read-only
1226           sites.</para>
1227         </listitem>
1228
1229         <listitem>
1230           <para>If any site definition in the VLDB entry is marked with a flag, either the previous release operation did not
1231           complete successfully or a new read-only site was defined since the last release. The Volume Server does not create a new
1232           ReleaseClone, instead distributing the existing ReleaseClone to sites marked with the <computeroutput>Old
1233           release</computeroutput> or <computeroutput>Not released</computeroutput> flag. As previously noted, the VL Server marks
1234           each VLDB site definition with the <computeroutput>New release</computeroutput> flag as the site receives the
1235           ReleaseClone, and clears all flags after all sites successfully receive it.</para>
1236         </listitem>
1237       </itemizedlist></para>
1238
1239     <para>To override the default behavior, forcing the Volume Server to create and release a new ReleaseClone to the read-only
1240     sites, include the <emphasis role="bold">-f</emphasis> flag. This is appropriate if, for example, the data at the read/write
1241     site has changed since the existing ReleaseClone was created during the previous release operation.</para>
1242
1243     <sect2 id="HDRWQ193">
1244       <title>Using Read-only Volumes Effectively</title>
1245
1246       <indexterm>
1247         <primary>criteria for replicating volumes</primary>
1248       </indexterm>
1249
1250       <indexterm>
1251         <primary>replication</primary>
1252
1253         <secondary>suitable types of volumes</secondary>
1254       </indexterm>
1255
1256       <indexterm>
1257         <primary>suitability of volumes for replication</primary>
1258       </indexterm>
1259
1260       <indexterm>
1261         <primary>read/write volume</primary>
1262
1263         <secondary>types suitable for replication</secondary>
1264       </indexterm>
1265
1266       <para>For maximum effectiveness, replicate only volumes that satisfy two criteria: <itemizedlist>
1267           <listitem>
1268             <para>The volume's contents are heavily used. Examples include a volume housing binary files for text editors or other
1269             popular application programs, and volumes mounted along heavily traversed directory paths such as the paths leading to
1270             user home directories. It is an inefficient use of disk space to replicate volumes for which the demand is low enough
1271             that a single File Server can easily service all requests.</para>
1272           </listitem>
1273
1274           <listitem>
1275             <para>The volume's contents change infrequently. As noted, file system consistency demands that the contents of
1276             read-only volumes must match each other and their read/write source at all times. Each time the read/write volume
1277             changes, you must issue the <emphasis role="bold">vos release</emphasis> command to update the read-only volumes. This
1278             can become tedious (and easy to forget) if the read/write volume changes frequently.</para>
1279           </listitem>
1280         </itemizedlist></para>
1281
1282       <indexterm>
1283         <primary>mounting</primary>
1284
1285         <secondary>read-only volume</secondary>
1286       </indexterm>
1287
1288       <indexterm>
1289         <primary>read-only volume</primary>
1290
1291         <secondary>mounting</secondary>
1292       </indexterm>
1293
1294       <para>Explicitly mounting a read-only volume (creating a mount point that names a volume with a <emphasis
1295       role="bold">.readonly</emphasis> extension) is not generally necessary or appropriate. The Cache Manager has a built-in bias
1296       to access the read-only version of a replicated volume whenever possible. As described in more detail in <link
1297       linkend="HDRWQ209">The Rules of Mount Point Traversal</link>, when the Cache Manager encounters a mount point it reads the
1298       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
1299       mount point resides in a read-only volume and names a read/write volume (one that does not have a <emphasis
1300       role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension), the Cache Manager always attempts to
1301       access a read-only copy of the volume. Thus there is normally no reason to force the Cache Manager to access a read-only
1302       volume by mounting it explicitly.</para>
1303
1304       <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
1305       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
1306       data (see <link linkend="HDRWQ190">About Clones and Cloning</link>). Only if a large number of files are removed or changed in
1307       the read/write volume does the read-only copy occupy much disk space. That normally does not happen because the appropriate
1308       response to changes in a replicated read/write volume is to reclone it. The other reason to place a read-only volume at the
1309       read/write site is that the Cache Manager does not attempt to access the read/write version of a replicated volume if all
1310       read-only copies become inaccessible. If the file server machine housing the read/write volume is the only accessible machine,
1311       the Cache Manager can access the data only if there is a read-only copy at the read/write site.</para>
1312
1313       <para>The number of read-only sites to define depends on several factors. Perhaps the main trade-off is between the level of
1314       demand for the volume's contents and how much disk space you are willing to use for multiple copies of the volume. Of course,
1315       each prospective read-only site must have enough available space to accommodate the volume. The limit on the number of
1316       read-only copies of a volume is determined by the maximum number of site definitions in a volume's VLDB entry, which is
1317       defined in the <emphasis> OpenAFS Release Notes</emphasis>. The site housing the read/write and backup versions of the volume
1318       counts as one site, and each read-only site counts as an additional site (even the read-only site defined on the same file
1319       server machine and partition as the read/write site counts as a separate site). Note also that the Volume Server permits only
1320       one read-only copy of a volume per file server machine.</para>
1321     </sect2>
1322
1323     <sect2 id="Header_216">
1324       <title>Replication Scenarios</title>
1325
1326       <indexterm>
1327         <primary>variations possible</primary>
1328
1329         <secondary>in replication</secondary>
1330       </indexterm>
1331
1332       <indexterm>
1333         <primary>replication</primary>
1334
1335         <secondary>variations possible in</secondary>
1336       </indexterm>
1337
1338       <indexterm>
1339         <primary>possible variations</primary>
1340
1341         <secondary>on replication</secondary>
1342       </indexterm>
1343
1344       <para>The instructions in the following section explain how to replicate a volume for which no read-only sites are currently
1345       defined. However, you can also use the instructions in other common situations: <itemizedlist>
1346           <listitem>
1347             <para>If you are releasing a new clone to sites that already exist, you can skip Step <link linkend="LIWQ196">2</link>.
1348             It can still be useful to issue the <emphasis role="bold">vos examine</emphasis> command, however, to verify that the
1349             desired read-only sites are defined.</para>
1350           </listitem>
1351
1352           <listitem>
1353             <para>If you are adding new read-only sites to existing ones, perform all of the steps. In Step <link
1354             linkend="LIWQ197">3</link>, issue the <emphasis role="bold">vos addsite</emphasis> command for the new sites
1355             only.</para>
1356           </listitem>
1357
1358           <listitem>
1359             <para>If you are defining sites but do not want to release a clone to them yet, stop after Step <link
1360             linkend="LIWQ197">3</link>and continue when you are ready.</para>
1361           </listitem>
1362
1363           <listitem>
1364             <para>If you are removing one or more sites before releasing a new clone to the remaining sites, follow the instructions
1365             for site removal in <link linkend="HDRWQ235">Removing Volumes and their Mount Points</link>and then start with Step
1366             <link linkend="LIWQ198">4</link>.</para>
1367           </listitem>
1368         </itemizedlist></para>
1369     </sect2>
1370
1371     <sect2 id="HDRWQ194">
1372       <title>To replicate a read/write volume (create a read-only volume)</title>
1373
1374       <indexterm>
1375         <primary>read-only volume</primary>
1376
1377         <secondary>creating</secondary>
1378
1379         <tertiary>instructions</tertiary>
1380       </indexterm>
1381
1382       <indexterm>
1383         <primary>read/write volume</primary>
1384
1385         <secondary>replication instructions</secondary>
1386       </indexterm>
1387
1388       <orderedlist>
1389         <listitem>
1390           <para><anchor id="LIWQ195" />Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
1391           file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
1392           linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
1393    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
1394 </programlisting></para>
1395         </listitem>
1396
1397         <listitem>
1398           <para><anchor id="LIWQ196" />Select one or more sites at which to replicate the volume. There are several factors to
1399           consider: <itemizedlist>
1400               <listitem>
1401                 <para>How many sites are already defined. As previously noted, it is usually appropriate to define a read-only site
1402                 at the read/write site. Also, the Volume Server permits only one read-only copy of a volume per file server machine.
1403                 To display the volume's current sites, issue the <emphasis role="bold">vos examine</emphasis> command, which is
1404                 described fully in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>.
1405                 <programlisting>
1406    % <emphasis role="bold">vos examine</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
1407 </programlisting></para>
1408
1409                 <para>The final lines of output display the volume's site definitions from the VLDB.</para>
1410               </listitem>
1411
1412               <listitem>
1413                 <para>Whether your cell dedicates any file server machines to housing read-only volumes only. In general, only very
1414                 large cells use read-only server machines.</para>
1415               </listitem>
1416
1417               <listitem>
1418                 <para>Whether a site has enough free space to accommodate the volume. A read-only volume requires the same amount of
1419                 space as the read/write version (unless it is at the read/write site itself). The first line of output from the
1420                 <emphasis role="bold">vos examine</emphasis> command displays the read/write volume's current size in kilobyte
1421                 blocks, as shown in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>.</para>
1422
1423                 <para>To display the amount of space available on a file server machine's partitions, use the <emphasis
1424                 role="bold">vos partinfo</emphasis> command, which is described fully in <link linkend="HDRWQ185">Creating
1425                 Read/write Volumes</link>.</para>
1426
1427                 <programlisting>
1428    % <emphasis role="bold">vos partinfo</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>partition name</replaceable>&gt;]
1429 </programlisting>
1430               </listitem>
1431             </itemizedlist></para>
1432
1433           <indexterm>
1434             <primary>read-only volume</primary>
1435
1436             <secondary>defining site for in VLDB</secondary>
1437           </indexterm>
1438
1439           <indexterm>
1440             <primary>defining</primary>
1441
1442             <secondary>read-only site in VLDB</secondary>
1443           </indexterm>
1444
1445           <indexterm>
1446             <primary>adding</primary>
1447
1448             <secondary>read-only site definition in VLDB</secondary>
1449           </indexterm>
1450
1451           <indexterm>
1452             <primary>VLDB</primary>
1453
1454             <secondary>defining read-only site in</secondary>
1455           </indexterm>
1456
1457           <indexterm>
1458             <primary>commands</primary>
1459
1460             <secondary>vos addsite</secondary>
1461           </indexterm>
1462
1463           <indexterm>
1464             <primary>vos commands</primary>
1465
1466             <secondary>addsite</secondary>
1467           </indexterm>
1468         </listitem>
1469
1470         <listitem>
1471           <para><anchor id="LIWQ197" />Issue the <emphasis role="bold">vos addsite</emphasis> command to define each new read-only
1472           site in the VLDB. <programlisting>
1473    % <emphasis role="bold">vos addsite</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; &lt;<replaceable>volume name or ID</replaceable>&gt;
1474 </programlisting></para>
1475
1476           <para>where <variablelist>
1477               <varlistentry>
1478                 <term><emphasis role="bold">ad</emphasis></term>
1479
1480                 <listitem>
1481                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">addsite</emphasis>.</para>
1482                 </listitem>
1483               </varlistentry>
1484
1485               <varlistentry>
1486                 <term><emphasis role="bold">machine name</emphasis></term>
1487
1488                 <listitem>
1489                   <para>Defines the file server machine for the new site.</para>
1490                 </listitem>
1491               </varlistentry>
1492
1493               <varlistentry>
1494                 <term><emphasis role="bold">partition name</emphasis></term>
1495
1496                 <listitem>
1497                   <para>Names a disk partition on the machine machine name.</para>
1498                 </listitem>
1499               </varlistentry>
1500
1501               <varlistentry>
1502                 <term><emphasis role="bold">volume name or ID</emphasis></term>
1503
1504                 <listitem>
1505                   <para>Identifies the read/write volume to be replicated, either by its complete name or its volume ID
1506                   number.</para>
1507                 </listitem>
1508               </varlistentry>
1509             </variablelist></para>
1510         </listitem>
1511
1512         <listitem>
1513           <para><anchor id="LIWQ198" /><emphasis role="bold">(Optional)</emphasis> Verify that the <emphasis
1514           role="bold">fs</emphasis> process (which incorporates the Volume Server) is functioning normally on each file server
1515           machine where you have defined a read-only site, and that the <emphasis role="bold">vlserver</emphasis> process (the
1516           Volume Location Server) is functioning correctly on each database server machine. Knowing that they are functioning
1517           eliminates two possible sources of failure for the release. Issue the <emphasis role="bold">bos status</emphasis> command
1518           on each file server machine housing a read-only site for this volume and on each database server machine. The command is
1519           described fully in <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>.
1520           <programlisting>
1521    % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">fs vlserver</emphasis>
1522 </programlisting></para>
1523
1524           <indexterm>
1525             <primary>releasing</primary>
1526
1527             <secondary>read-only volume</secondary>
1528           </indexterm>
1529
1530           <indexterm>
1531             <primary>read-only volume</primary>
1532
1533             <secondary>releasing</secondary>
1534           </indexterm>
1535
1536           <indexterm>
1537             <primary>commands</primary>
1538
1539             <secondary>vos release</secondary>
1540
1541             <tertiary>basic instructions</tertiary>
1542           </indexterm>
1543
1544           <indexterm>
1545             <primary>vos commands</primary>
1546
1547             <secondary>release</secondary>
1548
1549             <tertiary>basic instructions</tertiary>
1550           </indexterm>
1551         </listitem>
1552
1553         <listitem>
1554           <para><anchor id="LIWQ199" />Issue the <emphasis role="bold">vos release</emphasis> command to clone the read/write source
1555           volume and distribute the clone to each read-only site. <programlisting>
1556    % <emphasis role="bold">vos release</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt; [<emphasis role="bold">-f</emphasis>]
1557 </programlisting></para>
1558
1559           <para>where <variablelist>
1560               <varlistentry>
1561                 <term><emphasis role="bold">rel</emphasis></term>
1562
1563                 <listitem>
1564                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">release</emphasis>.</para>
1565                 </listitem>
1566               </varlistentry>
1567
1568               <varlistentry>
1569                 <term><emphasis role="bold">volume name or ID</emphasis></term>
1570
1571                 <listitem>
1572                   <para>Identifies the read/write volume to clone, either by its complete name or volume ID number. The read-only
1573                   version is given the same name with a <emphasis role="bold">.readonly</emphasis> extension. All read-only copies
1574                   share the same read-only volume ID number.</para>
1575                 </listitem>
1576               </varlistentry>
1577
1578               <varlistentry>
1579                 <term><emphasis role="bold">-f</emphasis></term>
1580
1581                 <listitem>
1582                   <para>Creates and releases a brand new clone.</para>
1583                 </listitem>
1584               </varlistentry>
1585             </variablelist></para>
1586         </listitem>
1587
1588         <listitem>
1589           <anchor id="LIWQ200" />
1590
1591           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">vos examine</emphasis> command to verify
1592           that no site definition in the VLDB entry is marked with an <computeroutput>Old release</computeroutput> or
1593           <computeroutput>New release</computeroutput> flag. The command is described fully in <link linkend="HDRWQ221">Displaying
1594           One Volume's VLDB Entry and Volume Header</link>. <programlisting>
1595    % <emphasis role="bold">vos examine</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
1596 </programlisting></para>
1597         </listitem>
1598       </orderedlist>
1599
1600       <para>If any flags appear in the output from Step <link linkend="LIWQ200">6</link>, repeat Steps <link
1601       linkend="LIWQ198">4</link>and <link linkend="LIWQ199">5</link>until the Volume Server does not produce any error messages
1602       during the release operation and the flags no longer appear. Do not issue the <emphasis role="bold">vos release</emphasis>
1603       command when you know that the read/write site or any read-only site is inaccessible due to network, machine or server process
1604       outage.</para>
1605     </sect2>
1606   </sect1>
1607
1608   <sect1 id="HDRWQ201">
1609     <title>Creating Backup Volumes</title>
1610
1611     <indexterm>
1612       <primary>read/write volume</primary>
1613
1614       <secondary>cloning</secondary>
1615
1616       <tertiary>for backup version</tertiary>
1617     </indexterm>
1618
1619     <indexterm>
1620       <primary>cloning</primary>
1621
1622       <secondary>for backup</secondary>
1623     </indexterm>
1624
1625     <indexterm>
1626       <primary>creating</primary>
1627
1628       <secondary>backup volume</secondary>
1629     </indexterm>
1630
1631     <indexterm>
1632       <primary>volume</primary>
1633
1634       <secondary>backup</secondary>
1635
1636       <see>backup volume</see>
1637     </indexterm>
1638
1639     <indexterm>
1640       <primary>backup volume</primary>
1641
1642       <secondary>creating</secondary>
1643     </indexterm>
1644
1645     <para>A <emphasis>backup volume</emphasis> is a clone that resides at the same site as its read/write source (to review the
1646     concept of cloning, see <link linkend="HDRWQ190">About Clones and Cloning</link>). Creating a backup version of a volume has two
1647     purposes: <itemizedlist>
1648         <listitem>
1649           <para>It is by convention the first step when dumping a volume's contents to tape with the AFS Backup System. A volume is
1650           inaccessible while it is being dumped, so instead of dumping the read/write volume, you create and dump a backup version.
1651           Users do not normally access the backup version, so it is unlikely that the dump will disturb them. For more details, see
1652           <link linkend="HDRWQ296">Backing Up Data</link>.</para>
1653         </listitem>
1654
1655         <listitem>
1656           <para>It enables users to restore mistakenly deleted or changed data themselves, freeing you for more crucial tasks. The
1657           backup version captures the state of its read/write source at the time the backup is made, and its contents cannot change.
1658           Mount the backup version in the filespace so that users can restore a file to its state at the time you made the backup.
1659           See <link linkend="HDRWQ204">Making the Contents of Backup Volumes Available to Users</link>.</para>
1660         </listitem>
1661       </itemizedlist></para>
1662
1663     <indexterm>
1664       <primary>creating</primary>
1665
1666       <secondary>multiple backup volumes at once</secondary>
1667     </indexterm>
1668
1669     <indexterm>
1670       <primary>volume</primary>
1671
1672       <secondary>creating backup version of many at once</secondary>
1673     </indexterm>
1674
1675     <indexterm>
1676       <primary>backup volume</primary>
1677
1678       <secondary>creating multiple at once</secondary>
1679     </indexterm>
1680
1681     <sect2 id="HDRWQ202">
1682       <title>Backing Up Multiple Volumes at Once</title>
1683
1684       <para>The <emphasis role="bold">vos backupsys</emphasis> command creates a backup version of many read/write volumes at once.
1685       This command is useful when preparing for large-scale backups to tape using the AFS Backup System.</para>
1686
1687       <para>To clone every read/write volume listed in the VLDB, omit all of the command's options. Otherwise, combine the command's
1688       options to clone various groups of volumes. The options use one of two basic criteria to select volumes: location (the
1689       <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments) or presence in the volume
1690       name of one of a set of specified character strings (the <emphasis role="bold">-prefix</emphasis>, <emphasis
1691       role="bold">-exclude</emphasis>, and <emphasis role="bold">-xprefix</emphasis> options).</para>
1692
1693       <para>To clone only volumes that reside on one file server machine, include the <emphasis role="bold">-server</emphasis>
1694       argument. To clone only volumes that reside on one partition, combine the <emphasis role="bold">-server</emphasis> and
1695       <emphasis role="bold">-partition</emphasis> arguments. The <emphasis role="bold">-partition</emphasis> argument can also be
1696       used alone to clone volumes that reside on the indicated partition on every file server machine. These arguments can be
1697       combined with those that select volumes based on their names.</para>
1698
1699       <para>Combine the <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-exclude</emphasis>, and <emphasis
1700       role="bold">-xprefix</emphasis> options (with or without the <emphasis role="bold">-server</emphasis> and <emphasis
1701       role="bold">-partition</emphasis> arguments) in the indicated ways to select volumes based on character strings contained in
1702       their names: <itemizedlist>
1703           <listitem>
1704             <para>To clone every read/write volume at the specified location whose name includes one of a set of specified character
1705             strings (for example, begins with <emphasis role="bold">user.</emphasis> or includes the string <emphasis
1706             role="bold">afs</emphasis>), use the <emphasis role="bold">-prefix</emphasis> argument or combine the <emphasis
1707             role="bold">-xprefix</emphasis> and <emphasis role="bold">-exclude</emphasis> options.</para>
1708           </listitem>
1709
1710           <listitem>
1711             <para>To clone every read/write volume at the specified location except those whose name includes one of a set of
1712             specified character strings, use the <emphasis role="bold">-xprefix</emphasis> argument or combine the <emphasis
1713             role="bold">-prefix</emphasis> and <emphasis role="bold">-exclude</emphasis> options.</para>
1714           </listitem>
1715
1716           <listitem>
1717             <para>To clone every read/write volume at the specified location whose name includes one of one of a set of specified
1718             character strings, except those whose names include one of a different set of specified character strings, combine the
1719             <emphasis role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments. The command creates a
1720             list of all volumes that match the <emphasis role="bold">-prefix</emphasis> argument and then removes from the list the
1721             volumes that match the <emphasis role="bold">-xprefix</emphasis> argument. For effective results, the strings specified
1722             by the <emphasis role="bold">-xprefix</emphasis> argument must designate a subset of the volumes specified by the
1723             <emphasis role="bold">-prefix</emphasis> argument.</para>
1724
1725             <para>If the <emphasis role="bold">-exclude</emphasis> flag is combined with the <emphasis
1726             role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments, the command creates a list of
1727             all volumes that do not match the <emphasis role="bold">-prefix</emphasis> argument and then adds to the list any
1728             volumes that match the <emphasis role="bold">-xprefix</emphasis> argument. As when the <emphasis
1729             role="bold">-exclude</emphasis> flag is not used, the result is effective only if the strings specified by the <emphasis
1730             role="bold">-xprefix</emphasis> argument designate a subset of the volumes specified by the <emphasis
1731             role="bold">-prefix</emphasis> argument.</para>
1732           </listitem>
1733         </itemizedlist></para>
1734
1735       <para>The <emphasis role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments both accept
1736       multiple values, which can be used to define disjoint groups of volumes. Each value can be one of two types: <orderedlist>
1737           <listitem>
1738             <para>A simple character string, which matches volumes whose name begin with the string. All characters are interpreted
1739             literally (that is, characters that potentially have special meaning to the command shell, such as the period, have only
1740             their literal meaning).</para>
1741           </listitem>
1742
1743           <listitem>
1744             <para>A regular expression, which matches volumes whose names contain the expressions. Place a caret ( <emphasis
1745             role="bold">^</emphasis>) at the beginning of the expression, and enclose the entire string in single quotes ( <emphasis
1746             role="bold">'</emphasis> <emphasis role="bold">'</emphasis>). Explaining regular expressions is outside the scope of
1747             this reference page; see the UNIX manual page for <emphasis role="bold">regexp(5)</emphasis> or (for a brief
1748             introduction) <link linkend="HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</link>. As an example, the
1749             following expression matches volumes that have the string <emphasis role="bold">aix</emphasis> anywhere in their names:
1750             <programlisting>
1751   <emphasis role="bold">-prefix '^.*aix'</emphasis>
1752           </programlisting></para>
1753           </listitem>
1754         </orderedlist></para>
1755
1756       <para>To display a list of the volumes to be cloned, without actually cloning them, include the <emphasis
1757       role="bold">-dryrun</emphasis> flag. To display a statement that summarizes the criteria being used to select volume, include
1758       the <emphasis role="bold">-verbose</emphasis> flag.</para>
1759
1760       <para>To back up a single volume, use the <emphasis role="bold">vos backup</emphasis> command, which employs a more
1761       streamlined technique for finding a single volume.</para>
1762
1763       <indexterm>
1764         <primary>automating</primary>
1765
1766         <secondary>creation of backup volumes</secondary>
1767       </indexterm>
1768
1769       <indexterm>
1770         <primary>backup volume</primary>
1771
1772         <secondary>automating creation of</secondary>
1773       </indexterm>
1774
1775       <indexterm>
1776         <primary>volume</primary>
1777
1778         <secondary>automating creation of backup version</secondary>
1779       </indexterm>
1780
1781       <indexterm>
1782         <primary>backup volume</primary>
1783
1784         <secondary>suggested schedule for creation of</secondary>
1785       </indexterm>
1786
1787       <indexterm>
1788         <primary>scheduling</primary>
1789
1790         <secondary>creation of backup volumes</secondary>
1791       </indexterm>
1792
1793       <indexterm>
1794         <primary>cron-type server process</primary>
1795
1796         <secondary>used to automate volume backup</secondary>
1797       </indexterm>
1798     </sect2>
1799
1800     <sect2 id="HDRWQ203">
1801       <title>Automating Creation of Backup Volumes</title>
1802
1803       <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
1804       backup versions at a time when usage is low, because the backup operation causes the read/write volume to be unavailable
1805       momentarily.</para>
1806
1807       <para>You can either issue the necessary the <emphasis role="bold">vos backupsys</emphasis> or <emphasis role="bold">vos
1808       backup</emphasis> commands at the console or create a <emphasis role="bold">cron</emphasis> entry in the <emphasis
1809       role="bold">BosConfig</emphasis> file on a file server machine, which eliminates the need for an administrator to initiate the
1810       backup operation.</para>
1811
1812       <para>The following example command creates a <emphasis role="bold">cron</emphasis> process called <emphasis
1813       role="bold">backupusers</emphasis> in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file on the machine
1814       <emphasis role="bold">fs3.abc.com</emphasis>. The process runs every day at 1:00 a.m. to create a backup version of every
1815       volume in the cell whose name starts with the string <emphasis role="bold">user</emphasis>. The <emphasis
1816       role="bold">-localauth</emphasis> flag enables the process to invoke the privileged <emphasis role="bold">vos
1817       backupsys</emphasis> command while unauthenticated. Note that the <emphasis role="bold">-cmd</emphasis> argument specifies a
1818       complete pathname for the <emphasis role="bold">vos</emphasis> binary, because the PATH environment variable for the BOS
1819       Server (running as the local superuser <emphasis role="bold">root</emphasis>) generally does not include the path to AFS
1820       binaries. <programlisting>
1821    % <emphasis role="bold">bos create fs3.abc.com backupusers cron</emphasis>\ 
1822   <emphasis role="bold">-cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" "1:00"</emphasis>
1823 </programlisting></para>
1824
1825       <indexterm>
1826         <primary>mounting</primary>
1827
1828         <secondary>backup volume</secondary>
1829       </indexterm>
1830
1831       <indexterm>
1832         <primary>backup volume</primary>
1833
1834         <secondary>mounting</secondary>
1835       </indexterm>
1836
1837       <indexterm>
1838         <primary>OldFiles directory</primary>
1839
1840         <secondary>as mount point for backup volume</secondary>
1841       </indexterm>
1842     </sect2>
1843
1844     <sect2 id="HDRWQ204">
1845       <title>Making the Contents of Backup Volumes Available to Users</title>
1846
1847       <para>As noted, a backup volume preserves the state of the read/write source at the time the backup is created. Many cells
1848       choose to mount backup volumes so that users can access and restore data they have accidentally deleted or changed since the
1849       last backup was made, without having to request help from administrators. The most sensible place to mount the backup version
1850       of a user volume is at a subdirectory of the user's home directory. Suitable names for this directory include <emphasis
1851       role="bold">OldFiles</emphasis> and <emphasis role="bold">Backup</emphasis>. The subdirectory looks just like the user's own
1852       home directory as it was at the time the backup was created, with all files and subdirectories in the same relative
1853       positions.</para>
1854
1855       <para>If you do create and mount backup volumes for your users, inform users of their existence. The <emphasis> OpenAFS User
1856       Guide</emphasis> does not mention backup volumes because making them available to users is optional. Explain to users how
1857       often you make a new backup, so they know what they can recover. Remind them also that the data in their backup volume cannot
1858       change; however, they can use the standard UNIX <emphasis role="bold">cp</emphasis> command to copy it into their home volume
1859       and modify it there. Reassure users that the data in their backup volumes does not count against their read/write volume
1860       quota.</para>
1861     </sect2>
1862
1863     <sect2 id="HDRWQ205">
1864       <title>To create and mount a backup volume</title>
1865
1866       <orderedlist>
1867         <listitem>
1868           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
1869           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
1870           display the users in the UserList file</link>. <programlisting>
1871    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
1872 </programlisting></para>
1873         </listitem>
1874
1875         <listitem>
1876           <para>Verify that you have the <emphasis role="bold">insert</emphasis>( <emphasis role="bold">i</emphasis>) and <emphasis
1877           role="bold">administer</emphasis>( <emphasis role="bold">a</emphasis>) permissions on the ACL of the directory in which
1878           you wish to mount the volume. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully
1879           described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
1880    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
1881 </programlisting></para>
1882
1883           <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
1884           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
1885           role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
1886           role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
1887
1888           <indexterm>
1889             <primary>commands</primary>
1890
1891             <secondary>vos backup</secondary>
1892           </indexterm>
1893
1894           <indexterm>
1895             <primary>vos commands</primary>
1896
1897             <secondary>backup</secondary>
1898           </indexterm>
1899         </listitem>
1900
1901         <listitem>
1902           <para><anchor id="LIWQ206" />Issue the <emphasis role="bold">vos backup</emphasis> command to create a backup version of a
1903           read/write source volume. The message shown confirms the success of the backup operation. <programlisting>
1904    % <emphasis role="bold">vos backup</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt; Created backup volume for volume name or ID
1905 </programlisting></para>
1906
1907           <para>where <variablelist>
1908               <varlistentry>
1909                 <term><emphasis role="bold">backup</emphasis></term>
1910
1911                 <listitem>
1912                   <para>Must be typed in full.</para>
1913                 </listitem>
1914               </varlistentry>
1915
1916               <varlistentry>
1917                 <term><emphasis role="bold">volume name or ID</emphasis></term>
1918
1919                 <listitem>
1920                   <para>Identifies the read/write volume to back up, either by its complete name or volume ID number. The backup
1921                   volume has the same name with the addition of the <emphasis role="bold">.backup</emphasis> extension. It has its
1922                   own volume ID number.</para>
1923                 </listitem>
1924               </varlistentry>
1925             </variablelist></para>
1926
1927           <indexterm>
1928             <primary>commands</primary>
1929
1930             <secondary>fs mkmount</secondary>
1931
1932             <tertiary>when mounting backup volume</tertiary>
1933           </indexterm>
1934
1935           <indexterm>
1936             <primary>fs commands</primary>
1937
1938             <secondary>mkmount</secondary>
1939
1940             <tertiary>when mounting backup volume</tertiary>
1941           </indexterm>
1942         </listitem>
1943
1944         <listitem>
1945           <para><anchor id="LIWQ207" /><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs
1946           mkmount</emphasis> to mount the backup volume. While this step is optional, Cache Managers cannot access the volume's
1947           contents if it is not mounted. <programlisting>
1948    % <emphasis role="bold">fs mkmount</emphasis> &lt;<replaceable>directory</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt; <emphasis
1949                 role="bold">.backup</emphasis>
1950 </programlisting></para>
1951
1952           <para>where <variablelist>
1953               <varlistentry>
1954                 <term><emphasis role="bold">mk</emphasis></term>
1955
1956                 <listitem>
1957                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">mkmount</emphasis>.</para>
1958                 </listitem>
1959               </varlistentry>
1960
1961               <varlistentry>
1962                 <term><emphasis role="bold">directory</emphasis></term>
1963
1964                 <listitem>
1965                   <para>Names the mount point to create. Do not create a file or directory of the same name beforehand. Partial
1966                   pathnames are interpreted relative to the current working directory. For the backup version of a user volume, the
1967                   conventional location is the user's home directory.</para>
1968                 </listitem>
1969               </varlistentry>
1970
1971               <varlistentry>
1972                 <term><emphasis role="bold">volume name</emphasis>.backup</term>
1973
1974                 <listitem>
1975                   <para>Is the full name of the backup volume.</para>
1976                 </listitem>
1977               </varlistentry>
1978             </variablelist></para>
1979         </listitem>
1980
1981         <listitem>
1982           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs lsmount</emphasis> command to verify
1983           that the mount point refers to the correct volume. Complete instructions appear in <link linkend="HDRWQ211">To display a
1984           mount point</link>. <programlisting>
1985    % <emphasis role="bold">fs lsmount</emphasis> &lt;<replaceable>directory</replaceable>&gt;
1986 </programlisting></para>
1987         </listitem>
1988       </orderedlist>
1989
1990       <indexterm>
1991         <primary>commands</primary>
1992
1993         <secondary>vos backupsys</secondary>
1994       </indexterm>
1995
1996       <indexterm>
1997         <primary>vos commands</primary>
1998
1999         <secondary>backupsys</secondary>
2000       </indexterm>
2001     </sect2>
2002
2003     <sect2 id="Header_223">
2004       <title>To create multiple backup volumes at once</title>
2005
2006       <orderedlist>
2007         <listitem>
2008           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
2009           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
2010           display the users in the UserList file</link>. <programlisting>
2011    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2012 </programlisting></para>
2013         </listitem>
2014
2015         <listitem>
2016           <para>Issue the <emphasis role="bold">vos backupsys</emphasis> command to create a backup version of every read/write
2017           volume that shares the same prefix or site. The effects of combining the three arguments are described in <link
2018           linkend="HDRWQ202">Backing Up Multiple Volumes at Once</link>. <programlisting>
2019    % <emphasis role="bold">vos backupsys</emphasis> [<emphasis role="bold">-prefix</emphasis> &lt;<replaceable>common prefix on volume(s)</replaceable>&gt;+] \ 
2020         [<emphasis role="bold">-server</emphasis> &lt;<replaceable>machine name</replaceable>&gt;] [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>partition name</replaceable>&gt;] \
2021         [<emphasis role="bold">-exclude</emphasis>] [<emphasis role="bold">-xprefix</emphasis> &lt;<replaceable>negative prefix on volume(s)</replaceable>&gt;+] \
2022         [<emphasis role="bold">-dryrun</emphasis>] [<emphasis role="bold">-verbose</emphasis>]
2023 </programlisting></para>
2024
2025           <para>where <variablelist>
2026               <varlistentry>
2027                 <term><emphasis role="bold">backups</emphasis></term>
2028
2029                 <listitem>
2030                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">backupsys</emphasis>.</para>
2031                 </listitem>
2032               </varlistentry>
2033
2034               <varlistentry>
2035                 <term><emphasis role="bold">-prefix</emphasis></term>
2036
2037                 <listitem>
2038                   <para>Specifies one or more simple character strings or regular expressions of any length; a volume whose name
2039                   includes the string is placed on the list of volumes to be cloned. Include field separators (such as periods) if
2040                   appropriate. This argument can be combined with any combination of the <emphasis role="bold">-server</emphasis>,
2041                   <emphasis role="bold">-partition</emphasis>, <emphasis role="bold">-exclude</emphasis>, and <emphasis
2042                   role="bold">-xprefix</emphasis> options.</para>
2043                 </listitem>
2044               </varlistentry>
2045
2046               <varlistentry>
2047                 <term><emphasis role="bold">-server</emphasis></term>
2048
2049                 <listitem>
2050                   <para>Specifies the file server machine housing the volumes to backup. Can be combined with any combination of the
2051                   <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-partition</emphasis>, <emphasis
2052                   role="bold">-exclude</emphasis>, and <emphasis role="bold">-xprefix</emphasis> options.</para>
2053                 </listitem>
2054               </varlistentry>
2055
2056               <varlistentry>
2057                 <term><emphasis role="bold">-partition</emphasis></term>
2058
2059                 <listitem>
2060                   <para>Specifies the partition housing the volumes you wish to backup. Can be combined with any combination of the
2061                   <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-server</emphasis>, <emphasis
2062                   role="bold">-exclude</emphasis>, and <emphasis role="bold">-xprefix</emphasis> options.</para>
2063                 </listitem>
2064               </varlistentry>
2065
2066               <varlistentry>
2067                 <term><emphasis role="bold">-exclude</emphasis></term>
2068
2069                 <listitem>
2070                   <para>Indicates that all volumes except those indicated with the <emphasis role="bold">-prefix</emphasis> argument
2071                   are to be backed up. The <emphasis role="bold">-prefix</emphasis> argument must be provided along with this one.
2072                   Can also be combined with any combination of the <emphasis role="bold">-prefix</emphasis>, <emphasis
2073                   role="bold">-server</emphasis>, and <emphasis role="bold">-partition</emphasis> arguments; or with both the
2074                   <emphasis role="bold">-prefix</emphasis> and <emphasis role="bold">-xprefix</emphasis> arguments, but not with the
2075                   <emphasis role="bold">-xprefix</emphasis> argument alone.</para>
2076                 </listitem>
2077               </varlistentry>
2078
2079               <varlistentry>
2080                 <term><emphasis role="bold">-xprefix</emphasis></term>
2081
2082                 <listitem>
2083                   <para>Specifies one or more simple character strings or regular expressions of any length; a volume whose name
2084                   does not include the string is placed on the list of volumes to be cloned. Can be combined with any combination of
2085                   the <emphasis role="bold">-prefix</emphasis>, <emphasis role="bold">-server</emphasis>, and <emphasis
2086                   role="bold">-partition</emphasis> arguments; in addition, it can be combined with both the <emphasis
2087                   role="bold">-prefix</emphasis> and <emphasis role="bold">-exclude</emphasis> options, but not with the <emphasis
2088                   role="bold">-exclude</emphasis> flag alone.</para>
2089                 </listitem>
2090               </varlistentry>
2091
2092               <varlistentry>
2093                 <term><emphasis role="bold">-dryrun</emphasis></term>
2094
2095                 <listitem>
2096                   <para>Displays on the standard output stream a list of the volumes to be cloned, without actually cloning
2097                   them.</para>
2098                 </listitem>
2099               </varlistentry>
2100
2101               <varlistentry>
2102                 <term><emphasis role="bold">-verbose</emphasis></term>
2103
2104                 <listitem>
2105                   <para>Displays on the standard output stream a statement that summarizes the criteria being used to select
2106                   volumes, if combined with the <emphasis role="bold">-dryrun</emphasis> flag; otherwise, traces the cloning
2107                   operation for each volume.</para>
2108                 </listitem>
2109               </varlistentry>
2110             </variablelist></para>
2111         </listitem>
2112       </orderedlist>
2113     </sect2>
2114   </sect1>
2115
2116   <sect1 id="HDRWQ208">
2117     <title>Mounting Volumes</title>
2118
2119     <indexterm>
2120       <primary>mounting</primary>
2121
2122       <secondary>volume</secondary>
2123
2124       <tertiary>general instructions</tertiary>
2125     </indexterm>
2126
2127     <para>Mount points make the contents of AFS volumes visible and accessible in the AFS filespace, as described in <link
2128     linkend="HDRWQ183">About Mounting Volumes</link>. This section discusses in more detail how the Cache Manager handles mount
2129     points as it traverses the filespace. It describes the three types of mount points, their purposes, and how to distinguish
2130     between them, and provides instructions for creating, removing, and examining mount points.</para>
2131
2132     <sect2 id="HDRWQ209">
2133       <title>The Rules of Mount Point Traversal</title>
2134
2135       <para>The Cache Manager observes three basic rules as it traverses the AFS filespace and encounters mount points:
2136       <itemizedlist>
2137           <listitem>
2138             <para><emphasis role="bold">Rule 1:</emphasis> Access Backup and Read-only Volumes When Specified</para>
2139
2140             <para>When the Cache Manager encounters a mount point that specifies a volume with either a <emphasis
2141             role="bold">.readonly</emphasis> or a <emphasis role="bold">.backup</emphasis> extension, it accesses that type of
2142             volume only. If a mount point does not have either a <emphasis role="bold">.backup</emphasis> or <emphasis
2143             role="bold">.readonly</emphasis> extension, the Cache Manager uses Rules 2 and 3.</para>
2144
2145             <para>For example, the Cache Manager never accesses the read/write version of a volume if the mount point names the
2146             backup version. If the specified version is inaccessible, the Cache Manager reports an error.</para>
2147           </listitem>
2148
2149           <listitem>
2150             <para><emphasis role="bold">Rule 2:</emphasis> Follow the Read-only Path When Possible</para>
2151
2152             <para>If a mount point resides in a read-only volume and the volume that it references is replicated, the Cache Manager
2153             attempts to access a read-only copy of the volume; if the referenced volume is not replicated, the Cache Manager
2154             accesses the read/write copy. The Cache Manager is thus said to prefer a <emphasis>read-only</emphasis> path through the
2155             filespace, accessing read-only volumes when they are available.</para>
2156
2157             <para>The Cache Manager starts on the read-only path in the first place because it always accesses a read-only copy of
2158             the <emphasis role="bold">root.afs</emphasis> volume if it exists; the volume is mounted at the root of a cell's AFS
2159             filespace (named <emphasis role="bold">/afs</emphasis> by convention). That is, if the <emphasis
2160             role="bold">root.afs</emphasis> volume is replicated, the Cache Manager attempts to access a read-only copy of it rather
2161             than the read/write copy. This rule then keeps the Cache Manager on a read-only path as long as each successive volume
2162             is replicated. The implication is that both the <emphasis role="bold">root.afs</emphasis> and <emphasis
2163             role="bold">root.cell</emphasis> volumes must be replicated for the Cache Manager to access replicated volumes mounted
2164             below them in the AFS filespace. The volumes are conventionally mounted at the <emphasis role="bold">/afs</emphasis> and
2165             <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable> directories, respectively.</para>
2166           </listitem>
2167
2168           <listitem>
2169             <para><emphasis role="bold">Rule 3:</emphasis> Once on a Read/write Path, Stay There</para>
2170
2171             <para>If a mount point resides in a read/write volume and the volume name does not have a <emphasis
2172             role="bold">.readonly</emphasis> or a <emphasis role="bold">.backup</emphasis> extension, the Cache Manager attempts to
2173             access only the a read/write version of the volume. The access attempt fails with an error if the read/write version is
2174             inaccessible, even if a read-only version is accessible. In this situation the Cache Manager is said to be on a
2175             <emphasis>read/write path</emphasis> and cannot switch back to the read-only path unless mount point explicitly names a
2176             volume with a <emphasis role="bold">.readonly</emphasis> extension. (Cellular mount points are an important exception to
2177             this rule, as explained in the following discussion.</para>
2178           </listitem>
2179         </itemizedlist></para>
2180     </sect2>
2181
2182     <sect2 id="HDRWQ210">
2183       <title>The Three Types of Mount Points</title>
2184
2185       <para>AFS uses three types of mount points, each appropriate for a different purpose because of how the Cache Manager handles
2186       them. <itemizedlist>
2187           <listitem>
2188             <para>When the Cache Manager crosses a <emphasis>regular</emphasis> mount point, it obeys all three of the mount point
2189             traversal rules previously described.</para>
2190
2191             <indexterm>
2192               <primary>regular mount point</primary>
2193
2194               <secondary></secondary>
2195
2196               <see>mount point</see>
2197             </indexterm>
2198
2199             <indexterm>
2200               <primary>mount point</primary>
2201
2202               <secondary>regular</secondary>
2203
2204               <tertiary>described</tertiary>
2205             </indexterm>
2206
2207             <para>AFS performs best when the vast majority of mount points in the filespace are regular, because the mount point
2208             traversal rules promote the most efficient use of both replicated and nonreplicated volumes. Because there are likely to
2209             be multiple read-only copies of a replicated volume, it makes sense for the Cache Manager to access one of them rather
2210             than the single read/write version, and the second rule leads it to do so. If a volume is not replicated, the third rule
2211             means that the Cache Manager still accesses the read/write volume when that is the only type available. In other words,
2212             a regular mount point does not force the Cache Manager always to access read-only volumes (it is explicitly not a
2213             "read-only mount point").</para>
2214
2215             <para>To create a regular mount point, use the <emphasis role="bold">fs mkmount</emphasis> command as described in <link
2216             linkend="HDRWQ212">To create a regular or read/write mount point</link>.</para>
2217
2218             <note>
2219               <para>To enable the Cache Manager to access the read-only version of a replicated volume named by a regular mount
2220               point, all volumes that are mounted above it in the pathname must also be replicated. That is the only way the Cache
2221               Manager can stay on a read-only path to the target volume.</para>
2222             </note>
2223           </listitem>
2224
2225           <listitem>
2226             <para>When the Cache Manager crosses a <emphasis>read/write</emphasis> mount point, it attempts to access only the
2227             volume version named in the mount point. If the volume name is the base (read/write) form, without a <emphasis
2228             role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension, the Cache Manager accesses the
2229             read/write version of the volume, even if it is replicated. In other words, the Cache Manager disregards the second
2230             mount point traversal rule when crossing a read/write mount point: it switches to the read/write path through the
2231             filespace.</para>
2232
2233             <indexterm>
2234               <primary>read/write mount point</primary>
2235
2236               <secondary></secondary>
2237
2238               <see>mount point</see>
2239             </indexterm>
2240
2241             <indexterm>
2242               <primary>mount point</primary>
2243
2244               <secondary>read/write</secondary>
2245
2246               <tertiary>described</tertiary>
2247             </indexterm>
2248
2249             <para>It is conventional to create only one read/write mount point in a cell's filespace, using it to mount the cell's
2250             <emphasis role="bold">root.cell</emphasis> volume just below the AFS filespace root (by convention, <emphasis
2251             role="bold">/afs/.</emphasis><replaceable>cellname</replaceable>). As indicated, it is conventional to place a period at
2252             the start of the read/write mount point's name (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). The period
2253             distinguishes the read/write mount point from the regular mount point for the <emphasis role="bold">root.cell</emphasis>
2254             volume at the same level. This is the only case in which it is conventional to create two mount points for the same
2255             volume. A desirable side effect of this naming convention for this read/write mount point is that it does not appear in
2256             the output of the UNIX <emphasis role="bold">ls</emphasis> command unless the <emphasis role="bold">-a</emphasis> flag
2257             is included, essentially hiding it from regular users who have no use for it.</para>
2258
2259             <para>The existence of a single read/write mount point at this point in the filespace provides access to the read/write
2260             version of every volume when necessary, because it puts the Cache Manager on a read/write path right at the top of the
2261             filespace. At the same time, the regular mount point for the <emphasis role="bold">root.cell</emphasis> volume puts the
2262             Cache Manager on a read-only path most of the time.</para>
2263
2264             <para>Using a read/write mount point for a read-only or backup volume is acceptable, but unnecessary. The first rule of
2265             mount point traversal already specifies that the Cache Manager accesses them if the volume name in a regular mount point
2266             has a <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension.</para>
2267
2268             <para>To create a read/write mount point, use the <emphasis role="bold">-rw</emphasis> flag on the <emphasis
2269             role="bold">fs mkmount</emphasis> command as described in <link linkend="HDRWQ212">To create a regular or read/write
2270             mount point</link>.</para>
2271           </listitem>
2272
2273           <listitem>
2274             <para>When the Cache Manager crosses a <emphasis>cellular</emphasis> mount point, it accesses the indicated volume in
2275             the specified cell, which is normally a foreign cell. (If the mount point does not name a cell along with the volume,
2276             the Cache Manager accesses the volume in the cell where the mount point resides.) When crossing a regular cellular mount
2277             point, the Cache Manager disregards the third mount point traversal rule. Instead, it accesses a read-only version of
2278             the volume if it is replicated, even if the volume that houses the mount point is read/write.</para>
2279
2280             <para>It is inappropriate to circumvent this behavior by creating a read/write cellular mount point, because traversing
2281             the read/write path imposes an unfair load on the foreign cell's file server machines. The File Server must issue a
2282             callback for each file fetched from the read/write volume, rather than single callback required for a read-only volume.
2283             In any case, only a cell's own administrators generally need to access the read/write versions of replicated
2284             volumes.</para>
2285
2286             <indexterm>
2287               <primary>cellular mount point</primary>
2288
2289               <secondary></secondary>
2290
2291               <see>mount point</see>
2292             </indexterm>
2293
2294             <indexterm>
2295               <primary>mount point</primary>
2296
2297               <secondary>cellular</secondary>
2298
2299               <tertiary>described</tertiary>
2300             </indexterm>
2301
2302             <indexterm>
2303               <primary>mounting</primary>
2304
2305               <secondary>foreign volume in local cell</secondary>
2306             </indexterm>
2307
2308             <para>It is conventional to create cellular mount points only at the second level in a cell's filespace, using them to
2309             mount foreign cells' <emphasis role="bold">root.cell</emphasis> volumes just below the AFS filespace root (by
2310             convention, at <emphasis role="bold">/afs/</emphasis><replaceable>foreign_cellname</replaceable>). The mount point
2311             enables local users to access the foreign cell's filespace, assuming they have the necessary permissions on the ACL of
2312             the volume's root directory and that there is an entry for the foreign cell in each local client machine's <emphasis
2313             role="bold">/usr/vice/etc/CellServDB</emphasis> file, as described in <link linkend="HDRWQ406">Maintaining Knowledge of
2314             Database Server Machines</link>.</para>
2315
2316             <para>Creating cellular mount points at other levels in the filespace and mounting foreign volumes other than the
2317             <emphasis role="bold">root.cell</emphasis> volume is not generally appropriate. It can be confusing to users if the
2318             Cache Manager switches between cells at various points in a pathname.</para>
2319
2320             <para>To create a regular cellular mount point, use the <emphasis role="bold">-cell</emphasis> argument to specify the
2321             cell name, as described in <link linkend="HDRWQ213">To create a cellular mount point</link>.</para>
2322           </listitem>
2323         </itemizedlist></para>
2324
2325       <para>To examine a mount point, use the <emphasis role="bold">fs lsmount</emphasis> command as described in <link
2326       linkend="HDRWQ211">To display a mount point</link>. The command's output uses distinct notation to identify regular,
2327       read/write, and cellular mount points. To remove a mount point, use the <emphasis role="bold">fs rmmount</emphasis> command as
2328       described in <link linkend="HDRWQ215">To remove a mount point</link>.</para>
2329     </sect2>
2330
2331     <sect2 id="Header_227">
2332       <title>Creating a mount point in a foreign cell</title>
2333
2334       <para>Creating a mount point in a foreign cell's filespace (as opposed to mounting a foreign volume in the local cell) is
2335       basically the same as creating a mount point in the local filespace. The differences are that the <emphasis role="bold">fs
2336       mkmount</emphasis> command's directory argument specifies a pathname in the foreign cell rather than the local cell, and you
2337       must have the required permissions on the ACL of the foreign directory where you are creating the mount point. The <emphasis
2338       role="bold">fs mkmount</emphasis> command's <emphasis role="bold">-cell</emphasis> argument always specifies the cell in which
2339       the volume resides, not the cell in which to create the mount point.</para>
2340     </sect2>
2341
2342     <sect2 id="HDRWQ211">
2343       <title>To display a mount point</title>
2344
2345       <indexterm>
2346         <primary>displaying</primary>
2347
2348         <secondary>mount point</secondary>
2349       </indexterm>
2350
2351       <indexterm>
2352         <primary>mount point</primary>
2353
2354         <secondary>displaying</secondary>
2355       </indexterm>
2356
2357       <indexterm>
2358         <primary>mount point</primary>
2359
2360         <secondary>distinguishing different types</secondary>
2361       </indexterm>
2362
2363       <indexterm>
2364         <primary>commands</primary>
2365
2366         <secondary>fs lsmount</secondary>
2367       </indexterm>
2368
2369       <indexterm>
2370         <primary>fs commands</primary>
2371
2372         <secondary>lsmount</secondary>
2373       </indexterm>
2374
2375       <orderedlist>
2376         <listitem>
2377           <para>Issue the <emphasis role="bold">fs lsmount</emphasis> command. <programlisting>
2378    % <emphasis role="bold">fs lsmount</emphasis> &lt;<replaceable>directory</replaceable>&gt;
2379 </programlisting></para>
2380
2381           <para>where <variablelist>
2382               <varlistentry>
2383                 <term><emphasis role="bold">ls</emphasis></term>
2384
2385                 <listitem>
2386                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">lsmount</emphasis>.</para>
2387                 </listitem>
2388               </varlistentry>
2389
2390               <varlistentry>
2391                 <term><emphasis role="bold">directory</emphasis></term>
2392
2393                 <listitem>
2394                   <para>Names the mount point to display.</para>
2395                 </listitem>
2396               </varlistentry>
2397             </variablelist></para>
2398         </listitem>
2399       </orderedlist>
2400
2401       <para>If the specified directory is a mount point, the output is of the following form:</para>
2402
2403       <programlisting>
2404    'directory' is a mount point for volume 'volume name'
2405 </programlisting>
2406
2407       <para>For a regular mount point, a number sign (<computeroutput>#</computeroutput>) precedes the volume name string, as in the
2408       following example command issued on a client machine in the <emphasis role="bold">abc.com</emphasis> cell.</para>
2409
2410       <programlisting>
2411    % <emphasis role="bold">fs lsmount /afs/abc.com/usr/terry</emphasis>
2412    '/afs/abc.com/usr/terry' is a mount point for volume '#user.terry'
2413 </programlisting>
2414
2415       <para>For a read/write mount point, a percent sign (<computeroutput>%</computeroutput>) precedes the volume name string, as in
2416       the following example command issued on a client machine in the <emphasis role="bold">abc.com</emphasis> cell. The cell's
2417       administrators have followed the convention of preceding the read/write mount point's name with a period.</para>
2418
2419       <programlisting>
2420    % <emphasis role="bold">fs lsmount /afs/.abc.com</emphasis>
2421    '/afs/.abc.com' is a mount point for volume '%root.cell'
2422 </programlisting>
2423
2424       <para>For a cellular mount point, a cell name and colon (<computeroutput>:</computeroutput>) follow the number or percent sign
2425       and precede the volume name string, as in the following example command issued on a client machine in the <emphasis
2426       role="bold">abc.com</emphasis> cell.</para>
2427
2428       <programlisting>
2429    % <emphasis role="bold">fs lsmount /afs/ghi.gov</emphasis>
2430    '/afs/ghi.gov' is a mount point for volume '#ghi.gov:root.cell'
2431 </programlisting>
2432
2433       <para>For a symbolic link to a mount point, the output is of the form shown in the following example command issued on a
2434       client machine in the <emphasis role="bold">abc.com</emphasis> cell.</para>
2435
2436       <programlisting>
2437    % <emphasis role="bold">fs lsmount /afs/abc</emphasis>
2438    '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
2439 </programlisting>
2440
2441       <para>If the directory is not a mount point or is not in AFS, the output reads as follows.</para>
2442
2443       <programlisting>
2444    'directory' is not a mount point.
2445 </programlisting>
2446
2447       <para>If the output is garbled, it is possible that the mount point has become corrupted in the local cache. Use the <emphasis
2448       role="bold">fs flushmount</emphasis> command as described in <link linkend="HDRWQ413">To flush one or more mount
2449       points</link>. This forces the Cache Manager to refetch the mount point.</para>
2450     </sect2>
2451
2452     <sect2 id="HDRWQ212">
2453       <title>To create a regular or read/write mount point</title>
2454
2455       <indexterm>
2456         <primary>creating</primary>
2457
2458         <secondary>read/write or regular mount point</secondary>
2459       </indexterm>
2460
2461       <indexterm>
2462         <primary>mount point</primary>
2463
2464         <secondary>creating read/write or regular</secondary>
2465       </indexterm>
2466
2467       <indexterm>
2468         <primary>mount point</primary>
2469
2470         <secondary>regular</secondary>
2471
2472         <tertiary>creating</tertiary>
2473       </indexterm>
2474
2475       <indexterm>
2476         <primary>mount point</primary>
2477
2478         <secondary>read/write</secondary>
2479
2480         <tertiary>creating</tertiary>
2481       </indexterm>
2482
2483       <indexterm>
2484         <primary>commands</primary>
2485
2486         <secondary>fs mkmount</secondary>
2487
2488         <tertiary>general instructions</tertiary>
2489       </indexterm>
2490
2491       <indexterm>
2492         <primary>fs commands</primary>
2493
2494         <secondary>mkmount</secondary>
2495
2496         <tertiary>general instructions</tertiary>
2497       </indexterm>
2498
2499       <orderedlist>
2500         <listitem>
2501           <para>Verify that you have the <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) and <emphasis
2502           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) permissions on the ACL of the directory where you
2503           are placing the mount point. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully
2504           described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
2505    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
2506 </programlisting></para>
2507         </listitem>
2508
2509         <listitem>
2510           <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to create the mount point. Include the <emphasis
2511           role="bold">-rw</emphasis> flag if creating a read/write mount point. <programlisting>
2512    % <emphasis role="bold">fs mkmount</emphasis> &lt;<replaceable>directory</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt; [<emphasis
2513                 role="bold">-rw</emphasis>]
2514 </programlisting></para>
2515
2516           <para>where <variablelist>
2517               <varlistentry>
2518                 <term><emphasis role="bold">mk</emphasis></term>
2519
2520                 <listitem>
2521                   <para>Is the shortest acceptable abbreviation for <emphasis role="bold">mkmount</emphasis>.</para>
2522                 </listitem>
2523               </varlistentry>
2524
2525               <varlistentry>
2526                 <term><emphasis role="bold">directory</emphasis></term>
2527
2528                 <listitem>
2529                   <para>Names the mount point to create. A file or directory with the same name cannot already exist. A partial
2530                   pathname is interpreted relative to the current working directory.</para>
2531
2532                   <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create
2533                   a new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period
2534                   before the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>).
2535                   For further discussion of the concept of read/write and read-only paths through the filespace, see <link
2536                   linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para>
2537                 </listitem>
2538               </varlistentry>
2539
2540               <varlistentry>
2541                 <term><emphasis role="bold">volume name</emphasis></term>
2542
2543                 <listitem>
2544                   <para>Specifies the volume's full name, including the <emphasis role="bold">.backup</emphasis> or <emphasis
2545                   role="bold">.readonly</emphasis> extension for a backup or read-only volume, if appropriate.</para>
2546                 </listitem>
2547               </varlistentry>
2548
2549               <varlistentry>
2550                 <term><emphasis role="bold">-rw</emphasis></term>
2551
2552                 <listitem>
2553                   <para>Creates a read/write mount point.</para>
2554                 </listitem>
2555               </varlistentry>
2556             </variablelist></para>
2557         </listitem>
2558       </orderedlist>
2559     </sect2>
2560
2561     <sect2 id="HDRWQ213">
2562       <title>To create a cellular mount point</title>
2563
2564       <indexterm>
2565         <primary>creating</primary>
2566
2567         <secondary>cellular mount point</secondary>
2568       </indexterm>
2569
2570       <indexterm>
2571         <primary>mount point</primary>
2572
2573         <secondary>creating cellular</secondary>
2574       </indexterm>
2575
2576       <indexterm>
2577         <primary>mount point</primary>
2578
2579         <secondary>cellular</secondary>
2580
2581         <tertiary>creating</tertiary>
2582       </indexterm>
2583
2584       <orderedlist>
2585         <listitem>
2586           <para>Verify that you have the <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) and <emphasis
2587           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) permissions on the ACL of the directory where you
2588           are placing the mount point. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully
2589           described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
2590    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
2591 </programlisting></para>
2592         </listitem>
2593
2594         <listitem>
2595           <para><anchor id="LIWQ214" />If you are mounting one or more foreign cells' <emphasis role="bold">root.cell</emphasis>
2596           volume at the second level in your filespace and your cell's <emphasis role="bold">root.afs</emphasis> volume is
2597           replicated, you must create a temporary mount point for the <emphasis role="bold">root.afs</emphasis> volume's read/write
2598           version in a directory on which the ACL grants you the <emphasis role="bold">i</emphasis> and <emphasis
2599           role="bold">a</emphasis> permissions. The following command creates a mount point called <emphasis
2600           role="bold">new_cells</emphasis> in your cell's <emphasis role="bold">/afs/.</emphasis><replaceable>cellname</replaceable>
2601           directory (the entry point to the read/write path in your cell).</para>
2602
2603           <para>Substitute your cell's name for cellname.</para>
2604
2605           <programlisting>
2606    % <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable>
2607    % <emphasis role="bold">fs mkmount new_cells root.afs</emphasis>
2608    % <emphasis role="bold">cd new_cells</emphasis>
2609 </programlisting>
2610         </listitem>
2611
2612         <listitem>
2613           <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command with the <emphasis role="bold">-cell</emphasis>
2614           argument to create a cellular mount point. Repeat the command for each cellular mount point as required. <programlisting>
2615    % <emphasis role="bold">fs mkmount</emphasis> &lt;<replaceable>directory</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt; <emphasis
2616                 role="bold">-cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;
2617 </programlisting></para>
2618
2619           <para>where <variablelist>
2620               <varlistentry>
2621                 <term><emphasis role="bold">mk</emphasis></term>
2622
2623                 <listitem>
2624                   <para>Is the shortest acceptable abbreviation for <emphasis role="bold">mkmount</emphasis>.</para>
2625                 </listitem>
2626               </varlistentry>
2627
2628               <varlistentry>
2629                 <term><emphasis role="bold">directory</emphasis></term>
2630
2631                 <listitem>
2632                   <para>Names the mount point to create. A file or directory with the same name cannot already exist. A partial
2633                   pathname is interpreted relative to the current working directory. If you are mounting a foreign cell's <emphasis
2634                   role="bold">root.cell</emphasis> volume, the standard value for this argument is the cell's complete Internet
2635                   domain name.</para>
2636                 </listitem>
2637               </varlistentry>
2638
2639               <varlistentry>
2640                 <term><emphasis role="bold">volume name</emphasis></term>
2641
2642                 <listitem>
2643                   <para>Specifies the volume's full name, usually <emphasis role="bold">root.cell</emphasis> for a cellular mount
2644                   point.</para>
2645                 </listitem>
2646               </varlistentry>
2647
2648               <varlistentry>
2649                 <term><emphasis role="bold">-cell</emphasis></term>
2650
2651                 <listitem>
2652                   <para>Specifies the complete Internet domain name of the cell in which the volume resides.</para>
2653                 </listitem>
2654               </varlistentry>
2655             </variablelist></para>
2656         </listitem>
2657
2658         <listitem>
2659           <para>If you performed the instructions in Step <link linkend="LIWQ214">2</link>, issue the <emphasis role="bold">vos
2660           release</emphasis> command to release the new version of the <emphasis role="bold">root.afs</emphasis> volume to its
2661           read-only sites. (This command requires that you be listed in your cell's <emphasis
2662           role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, verify by issuing the <emphasis role="bold">bos
2663           listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the users in the UserList
2664           file</link>.)</para>
2665
2666           <para>Also issue the <emphasis role="bold">fs checkvolumes</emphasis> command to force the local Cache Manager to access
2667           the new replica of the <emphasis role="bold">root.afs</emphasis> volume. If desired, you can also remove the temporary
2668           <emphasis role="bold">new_cells</emphasis> mount point from the <emphasis
2669           role="bold">/afs/.</emphasis><replaceable>cellname</replaceable> directory.</para>
2670
2671           <programlisting>
2672    % <emphasis role="bold">vos release root.afs</emphasis>
2673    % <emphasis role="bold">fs checkvolumes</emphasis>
2674    % <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable>
2675    % <emphasis role="bold">fs rmmount new_cells</emphasis>
2676 </programlisting>
2677
2678           <para>For your users to access a newly mounted foreign cell, you must also create an entry for it in each client machine's
2679           local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file and either reboot the machine or use the <emphasis
2680           role="bold">fs newcell</emphasis> command to insert the entry directly into its kernel memory. See the instructions in
2681           <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
2682         </listitem>
2683       </orderedlist>
2684     </sect2>
2685
2686     <sect2 id="HDRWQ215">
2687       <title>To remove a mount point</title>
2688
2689       <indexterm>
2690         <primary>removing</primary>
2691
2692         <secondary>mount point</secondary>
2693       </indexterm>
2694
2695       <indexterm>
2696         <primary>unmounting</primary>
2697
2698         <secondary>volume</secondary>
2699       </indexterm>
2700
2701       <indexterm>
2702         <primary>mount point</primary>
2703
2704         <secondary>removing</secondary>
2705       </indexterm>
2706
2707       <indexterm>
2708         <primary>commands</primary>
2709
2710         <secondary>fs rmmount</secondary>
2711       </indexterm>
2712
2713       <indexterm>
2714         <primary>fs commands</primary>
2715
2716         <secondary>rmmount</secondary>
2717       </indexterm>
2718
2719       <orderedlist>
2720         <listitem>
2721           <para>Verify that you have the <emphasis role="bold">d</emphasis>( <emphasis role="bold">delete</emphasis>) permission on
2722           the ACL of the directory from which you are removing the mount point. If necessary, issue the <emphasis role="bold">fs
2723           listacl</emphasis> command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
2724    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
2725 </programlisting></para>
2726
2727           <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
2728           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
2729           role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
2730           role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
2731         </listitem>
2732
2733         <listitem>
2734           <para>Issue the <emphasis role="bold">fs rmmount</emphasis> command to remove the mount point. The volume still exists,
2735           but its contents are inaccessible if this is the only mount point for it. <programlisting>
2736    % <emphasis role="bold">fs rmmount</emphasis> &lt;<replaceable>directory</replaceable>&gt;
2737 </programlisting></para>
2738
2739           <para>where <variablelist>
2740               <varlistentry>
2741                 <term><emphasis role="bold">rm</emphasis></term>
2742
2743                 <listitem>
2744                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">rmmount</emphasis>.</para>
2745                 </listitem>
2746               </varlistentry>
2747
2748               <varlistentry>
2749                 <term><emphasis role="bold">directory</emphasis></term>
2750
2751                 <listitem>
2752                   <para>Names the mount point to remove. A partial pathname is interpreted relative to the current working
2753                   directory.</para>
2754
2755                   <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete
2756                   a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before
2757                   the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). For
2758                   further discussion of the concept of read/write and read-only paths through the filespace, see <link
2759                   linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para>
2760                 </listitem>
2761               </varlistentry>
2762             </variablelist></para>
2763         </listitem>
2764       </orderedlist>
2765     </sect2>
2766   </sect1>
2767
2768   <sect1 id="HDRWQ216">
2769     <title>Displaying Information About Volumes</title>
2770
2771     <indexterm>
2772       <primary>displaying</primary>
2773
2774       <secondary>volume information</secondary>
2775     </indexterm>
2776
2777     <indexterm>
2778       <primary>volume</primary>
2779
2780       <secondary>displaying information about</secondary>
2781     </indexterm>
2782
2783     <para>This section explains how to display information about volumes. If you know a volume's name or volume ID number, there are
2784     commands for displaying its VLDB entry, its volume header, or both. Other commands display the name or location of the volume
2785     that contains a specified file or directory.</para>
2786
2787     <para>For instructions on displaying a volume's quota, see <link linkend="HDRWQ234">Setting and Displaying Volume Quota and
2788     Current Size</link>.</para>
2789
2790     <sect2 id="HDRWQ217">
2791       <title>Displaying VLDB Entries</title>
2792
2793       <indexterm>
2794         <primary>displaying</primary>
2795
2796         <secondary>volume's VLDB entry</secondary>
2797       </indexterm>
2798
2799       <indexterm>
2800         <primary>VLDB</primary>
2801
2802         <secondary>displaying volume entry</secondary>
2803       </indexterm>
2804
2805       <indexterm>
2806         <primary>volume entry (VLDB)</primary>
2807
2808         <secondary>displaying</secondary>
2809       </indexterm>
2810
2811       <indexterm>
2812         <primary>locked VLDB entry</primary>
2813
2814         <secondary>displaying</secondary>
2815       </indexterm>
2816
2817       <para>The <emphasis role="bold">vos listvldb</emphasis> command displays the VLDB entry for the volumes indicated by the
2818       combination of arguments you provide. The possibilities are listed here from most to least inclusive: <itemizedlist>
2819           <listitem>
2820             <para>To display every entry in the VLDB, provide no arguments. It can take a long time to generate the output,
2821             depending on the number of entries.</para>
2822           </listitem>
2823
2824           <listitem>
2825             <para>To display every VLDB entry that mentions a specific file server machine as the site of a volume, specify the
2826             machine's name with the <emphasis role="bold">-server</emphasis> argument.</para>
2827           </listitem>
2828
2829           <listitem>
2830             <para>To display every VLDB entry that mentions a certain partition on any file server machine as the site of a volume,
2831             specify the partition name with the <emphasis role="bold">-partition</emphasis> argument.</para>
2832           </listitem>
2833
2834           <listitem>
2835             <para>To display every VLDB entry that mentions a certain partition on a certain file server machine as the site of a
2836             volume, combine the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis>
2837             arguments.</para>
2838           </listitem>
2839
2840           <listitem>
2841             <para>To display a single VLDB entry, specify a volume name or ID number with the <emphasis role="bold">-name</emphasis>
2842             argument.</para>
2843           </listitem>
2844
2845           <listitem>
2846             <para>To display the VLDB entry only for volumes with locked VLDB entries, use the <emphasis
2847             role="bold">-locked</emphasis> flag with any of the site definitions mentioned previously.</para>
2848           </listitem>
2849         </itemizedlist></para>
2850
2851       <indexterm>
2852         <primary>commands</primary>
2853
2854         <secondary>vos listvldb</secondary>
2855
2856         <tertiary>syntax</tertiary>
2857       </indexterm>
2858
2859       <indexterm>
2860         <primary>vos commands</primary>
2861
2862         <secondary>listvldb</secondary>
2863
2864         <tertiary>syntax</tertiary>
2865       </indexterm>
2866     </sect2>
2867
2868     <sect2 id="HDRWQ218">
2869       <title>To display VLDB entries</title>
2870
2871       <orderedlist>
2872         <listitem>
2873           <para>Issue the <emphasis role="bold">vos listvldb</emphasis> command. <programlisting>
2874    % <emphasis role="bold">vos listvldb</emphasis> [<emphasis role="bold">-name</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;] [<emphasis
2875                 role="bold">-server</emphasis> &lt;<replaceable>machine name</replaceable>&gt;] \
2876         [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>partition name</replaceable>&gt;] [<emphasis role="bold">-locked</emphasis>]
2877 </programlisting></para>
2878
2879           <para>where <variablelist>
2880               <varlistentry>
2881                 <term><emphasis role="bold">listvl</emphasis></term>
2882
2883                 <listitem>
2884                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listvldb</emphasis>.</para>
2885                 </listitem>
2886               </varlistentry>
2887
2888               <varlistentry>
2889                 <term><emphasis role="bold">-name</emphasis></term>
2890
2891                 <listitem>
2892                   <para>Identifies one volume either by its complete name or volume ID number. Do not combine this argument with the
2893                   <emphasis role="bold">-server</emphasis> or <emphasis role="bold">-partition</emphasis> arguments.</para>
2894                 </listitem>
2895               </varlistentry>
2896
2897               <varlistentry>
2898                 <term><emphasis role="bold">-server</emphasis></term>
2899
2900                 <listitem>
2901                   <para>Specifies a file server machine. Combine this argument with the <emphasis role="bold">-partition</emphasis>
2902                   argument if desired, but not with the <emphasis role="bold">-name</emphasis> argument.</para>
2903                 </listitem>
2904               </varlistentry>
2905
2906               <varlistentry>
2907                 <term><emphasis role="bold">-partition</emphasis></term>
2908
2909                 <listitem>
2910                   <para>Specifies a partition. Combine this argument with the <emphasis role="bold">-server</emphasis> argument if
2911                   desired, but not with the <emphasis role="bold">-name</emphasis> argument.</para>
2912                 </listitem>
2913               </varlistentry>
2914
2915               <varlistentry>
2916                 <term><emphasis role="bold">-locked</emphasis></term>
2917
2918                 <listitem>
2919                   <para>Displays only locked VLDB entries. Combine this flag with any of the other options.</para>
2920                 </listitem>
2921               </varlistentry>
2922             </variablelist></para>
2923         </listitem>
2924       </orderedlist>
2925
2926       <para>The VLDB entry for each volume includes the following information: <itemizedlist>
2927           <listitem>
2928             <para>The base (read/write) volume name. The read-only and backup versions have the same name with a <emphasis
2929             role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extension, respectively.</para>
2930           </listitem>
2931
2932           <listitem>
2933             <para>The volume ID numbers allocated to the versions of the volume that actually exist, in fields labeled
2934             <computeroutput>RWrite</computeroutput> for the read/write, <computeroutput>ROnly</computeroutput> for the read-only,
2935             <computeroutput>Backup</computeroutput> for the backup, and <computeroutput>RClone</computeroutput> for the
2936             ReleaseClone. (If a field does not appear, the corresponding version of the volume does not exist.) The appearance of
2937             the <computeroutput>RClone</computeroutput> field normally indicates that a release operation did not complete
2938             successfully; the <computeroutput>Old release</computeroutput> and <computeroutput>New release</computeroutput> flags
2939             often also appear on one or more of the site definition lines described just following.</para>
2940
2941             <indexterm>
2942               <primary>site</primary>
2943
2944               <secondary>count in VLDB</secondary>
2945             </indexterm>
2946
2947             <indexterm>
2948               <primary>VLDB</primary>
2949
2950               <secondary>site count for volume</secondary>
2951             </indexterm>
2952           </listitem>
2953
2954           <listitem>
2955             <para>The number of sites that house a read/write or read-only copy of the volume, following the string
2956             <computeroutput>number of sites -&gt;</computeroutput>.</para>
2957
2958             <indexterm>
2959               <primary>type flag for volume</primary>
2960
2961               <secondary>VLDB entry</secondary>
2962             </indexterm>
2963
2964             <indexterm>
2965               <primary>VLDB</primary>
2966
2967               <secondary>volume type flags</secondary>
2968             </indexterm>
2969
2970             <indexterm>
2971               <primary>release</primary>
2972
2973               <secondary>status flags on site definitions in VLDB entry</secondary>
2974             </indexterm>
2975
2976             <indexterm>
2977               <primary>VLDB</primary>
2978
2979               <secondary>release status flags in volume entry</secondary>
2980             </indexterm>
2981
2982             <indexterm>
2983               <primary>status flag</primary>
2984
2985               <secondary>release, on site definitions in VLDB entry</secondary>
2986             </indexterm>
2987           </listitem>
2988
2989           <listitem>
2990             <para>A line for each site that houses a read/write or read-only copy of the volume, specifying the file server machine,
2991             partition, and type of volume (<computeroutput>RW</computeroutput> for read/write or <computeroutput>RO</computeroutput>
2992             for read-only). If a backup version exists, it is understood to share the read/write site. Several flags can appear with
2993             a site definition: <variablelist>
2994                 <indexterm>
2995                   <primary>Not released</primary>
2996
2997                   <secondary>status flag on site definition in VLDB entry</secondary>
2998                 </indexterm>
2999
3000                 <varlistentry>
3001                   <term><computeroutput>Not released</computeroutput></term>
3002
3003                   <listitem>
3004                     <para>Indicates that the <emphasis role="bold">vos release</emphasis> command has not been issued since the
3005                     <emphasis role="bold">vos addsite</emphasis> command was used to define the read-only site.</para>
3006
3007                     <indexterm>
3008                       <primary>Old release</primary>
3009
3010                       <secondary>status flag on site definition in VLDB entry</secondary>
3011                     </indexterm>
3012                   </listitem>
3013                 </varlistentry>
3014
3015                 <varlistentry>
3016                   <term><computeroutput>Old release</computeroutput></term>
3017
3018                   <listitem>
3019                     <para>Indicates that a <emphasis role="bold">vos release</emphasis> command did not complete successfully,
3020                     leaving the previous, obsolete version of the volume at this site.</para>
3021
3022                     <indexterm>
3023                       <primary>New release</primary>
3024
3025                       <secondary>status flag on site definition in VLDB entry</secondary>
3026                     </indexterm>
3027                   </listitem>
3028                 </varlistentry>
3029
3030                 <varlistentry>
3031                   <term><computeroutput>New release</computeroutput></term>
3032
3033                   <listitem>
3034                     <para>Indicates that a <emphasis role="bold">vos release</emphasis> command did not complete successfully, but
3035                     that this site did receive the correct new version of the volume.</para>
3036                   </listitem>
3037                 </varlistentry>
3038               </variablelist></para>
3039           </listitem>
3040
3041           <listitem>
3042             <para>If the VLDB entry is locked, the string <computeroutput>Volume is currently LOCKED</computeroutput>.</para>
3043           </listitem>
3044         </itemizedlist></para>
3045
3046       <para>For further discussion of the <computeroutput>New release</computeroutput> and <computeroutput>Old
3047       release</computeroutput> flags, see <link linkend="HDRWQ192">Replicating Volumes (Creating Read-only Volumes)</link>.</para>
3048
3049       <para>An example of this command and its output for a single volume:</para>
3050
3051       <programlisting>
3052    % <emphasis role="bold">vos listvldb user.terry</emphasis>
3053    user.terry
3054        RWrite: 50489902    Backup: 50489904
3055        number of sites -&gt; 1
3056           server fs3.abc.com partition /vicepc RW Site
3057 </programlisting>
3058     </sect2>
3059
3060     <sect2 id="HDRWQ219">
3061       <title>Displaying Volume Headers</title>
3062
3063       <indexterm>
3064         <primary>displaying</primary>
3065
3066         <secondary>volume header</secondary>
3067       </indexterm>
3068
3069       <indexterm>
3070         <primary>volume header</primary>
3071
3072         <secondary>displaying</secondary>
3073
3074         <tertiary>only</tertiary>
3075       </indexterm>
3076
3077       <para>The <emphasis role="bold">vos listvol</emphasis> command displays the volume header for every volume on one or all
3078       partitions on a file server machine. The <emphasis role="bold">vos</emphasis> command interpreter obtains the information from
3079       the Volume Server on the specified machine. You can control the amount of information displayed by including one of the
3080       <emphasis role="bold">-fast</emphasis>, the <emphasis role="bold">-long</emphasis>, or the <emphasis
3081       role="bold">-extended</emphasis> flags described following the instructions in <link linkend="HDRWQ220">To display volume
3082       headers</link>.</para>
3083
3084       <para>To display a single volume's volume header of one volume only, use the <emphasis role="bold">vos examine</emphasis>
3085       command as described in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>.</para>
3086
3087       <indexterm>
3088         <primary>commands</primary>
3089
3090         <secondary>vos listvol</secondary>
3091
3092         <tertiary>syntax</tertiary>
3093       </indexterm>
3094
3095       <indexterm>
3096         <primary>vos commands</primary>
3097
3098         <secondary>listvol</secondary>
3099
3100         <tertiary>syntax</tertiary>
3101       </indexterm>
3102     </sect2>
3103
3104     <sect2 id="HDRWQ220">
3105       <title>To display volume headers</title>
3106
3107       <orderedlist>
3108         <listitem>
3109           <para>Issue the <emphasis role="bold">vos listvol</emphasis> command. <programlisting>
3110    % <emphasis role="bold">vos listvol</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>partition name</replaceable>&gt;] [<emphasis
3111                 role="bold">-fast</emphasis>] [<emphasis role="bold">-long</emphasis>] [<emphasis role="bold">-extended</emphasis>]
3112 </programlisting></para>
3113
3114           <para>where <variablelist>
3115               <varlistentry>
3116                 <term><emphasis role="bold">listvo</emphasis></term>
3117
3118                 <listitem>
3119                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listvol</emphasis>.</para>
3120                 </listitem>
3121               </varlistentry>
3122
3123               <varlistentry>
3124                 <term><emphasis role="bold">machine name</emphasis></term>
3125
3126                 <listitem>
3127                   <para>Names the file server machine for which to display volume headers. Provide this argument alone or with the
3128                   partition name argument.</para>
3129                 </listitem>
3130               </varlistentry>
3131
3132               <varlistentry>
3133                 <term><emphasis role="bold">partition name</emphasis></term>
3134
3135                 <listitem>
3136                   <para>Names one partition on the file server machine named by the machine name argument, which must be provided
3137                   along with this one.</para>
3138                 </listitem>
3139               </varlistentry>
3140
3141               <varlistentry>
3142                 <term><emphasis role="bold">-fast</emphasis></term>
3143
3144                 <listitem>
3145                   <para>Displays only the volume ID numbers of relevant volumes. Do not combine this flag with the <emphasis
3146                   role="bold">-long</emphasis> or <emphasis role="bold">-extended</emphasis> flag.</para>
3147                 </listitem>
3148               </varlistentry>
3149
3150               <varlistentry>
3151                 <term><emphasis role="bold">-long</emphasis></term>
3152
3153                 <listitem>
3154                   <para>Displays more detailed information about each volume. Do not combine this flag with the <emphasis
3155                   role="bold">-fast</emphasis> or <emphasis role="bold">-extended</emphasis> flag.</para>
3156                 </listitem>
3157               </varlistentry>
3158
3159               <varlistentry>
3160                 <term><emphasis role="bold">-extended</emphasis></term>
3161
3162                 <listitem>
3163                   <para>Displays all of the information displayed by the <emphasis role="bold">-long</emphasis> flag, plus tables of
3164                   statistics about reads and writes to the files in the volume. Do not combine this flag with the <emphasis
3165                   role="bold">-fast</emphasis> or <emphasis role="bold">-long</emphasis> flag.</para>
3166                 </listitem>
3167               </varlistentry>
3168             </variablelist></para>
3169         </listitem>
3170       </orderedlist>
3171
3172       <para>The output is ordered alphabetically by volume name and by default provides the following information on a single line
3173       for each volume: <itemizedlist>
3174           <listitem>
3175             <para>Name</para>
3176           </listitem>
3177
3178           <listitem>
3179             <para>Volume ID number</para>
3180
3181             <indexterm>
3182               <primary>type flag for volume</primary>
3183
3184               <secondary>volume header</secondary>
3185             </indexterm>
3186           </listitem>
3187
3188           <listitem>
3189             <para>Type (the flag is <computeroutput>RW</computeroutput> for read/write, <computeroutput>RO</computeroutput> for
3190             read-only, <computeroutput>BK</computeroutput> for backup)</para>
3191           </listitem>
3192
3193           <listitem>
3194             <para>Size in kilobytes (<computeroutput>1024</computeroutput> equals a megabyte)</para>
3195           </listitem>
3196
3197           <listitem>
3198             <para>Number of files in the volume, if the <emphasis role="bold">-extended</emphasis> flag is provided</para>
3199
3200             <indexterm>
3201               <primary>status flags in volume header</primary>
3202             </indexterm>
3203           </listitem>
3204
3205           <listitem>
3206             <para>Status on the file server machine, which is one of the following: <variablelist>
3207                 <indexterm>
3208                   <primary>On-line status flag in volume header</primary>
3209                 </indexterm>
3210
3211                 <varlistentry>
3212                   <term><computeroutput>On-line</computeroutput></term>
3213
3214                   <listitem>
3215                     <para>The volume is completely accessible to Cache Managers.</para>
3216
3217                     <indexterm>
3218                       <primary>Off-line status flag in volume header</primary>
3219                     </indexterm>
3220                   </listitem>
3221                 </varlistentry>
3222
3223                 <varlistentry>
3224                   <term><computeroutput>Off-line</computeroutput></term>
3225
3226                   <listitem>
3227                     <para>The volume is not accessible to Cache Managers, but does not seem to be corrupted. This status appears
3228                     while a volume is being dumped, for example.</para>
3229
3230                     <indexterm>
3231                       <primary>needs salvage status flag in volume header</primary>
3232                     </indexterm>
3233                   </listitem>
3234                 </varlistentry>
3235
3236                 <varlistentry>
3237                   <term><computeroutput>Off-line**needs salvage**</computeroutput></term>
3238
3239                   <listitem>
3240                     <para>The volume is not accessible to Cache Managers, because it seems to be corrupted. Use the <emphasis
3241                     role="bold">bos salvage</emphasis> or <emphasis role="bold">salvager</emphasis> command to repair the
3242                     corruption.</para>
3243                   </listitem>
3244                 </varlistentry>
3245               </variablelist></para>
3246           </listitem>
3247         </itemizedlist></para>
3248
3249       <para>If the following message appears instead of the previously listed information, it indicates that a volume is not
3250       accessible to Cache Managers or the <emphasis role="bold">vos</emphasis> command interpreter, for example because a clone is
3251       being created.</para>
3252
3253       <programlisting>
3254    **** Volume volume_ID is busy ****
3255 </programlisting>
3256
3257       <para>If the following message appears instead of the previously listed information, it indicates that the File Server is
3258       unable to attach the volume, perhaps because it is seriously corrupted. The <emphasis role="bold">FileLog</emphasis> and
3259       <emphasis role="bold">VolserLog</emphasis> log files in the <emphasis role="bold">/usr/afs/logs</emphasis> directory on the
3260       file server machine possibly provide additional information; use the <emphasis role="bold">bos getlog</emphasis> command to
3261       display them.</para>
3262
3263       <programlisting>
3264    **** Could not attach volume volume_ID ****
3265 </programlisting>
3266
3267       <para>(For instructions on salvaging a corrupted or unattached volume, see <link linkend="HDRWQ232">Salvaging
3268       Volumes</link>.)</para>
3269
3270       <para>The information about individual volumes is bracketed by summary lines. The first line of output specifies the number of
3271       volumes in the listing. The last line of output summarizes the number of volumes that are online, offline, and busy, as in the
3272       following example:</para>
3273
3274       <programlisting>
3275    % <emphasis role="bold">vos listvol  fs2.abc.com /vicepb</emphasis>
3276    Total number of volumes on server fs2.abc.com \
3277                                        partition /vicepb : 66
3278    sys                  1969534847 RW       1582 K On-line
3279    sys.backup           1969535105 BK       1582 K On-line
3280          .                   .     .         .   .    .
3281          .                   .     .         .   .    .
3282    user.pat             1969534536 RW      17518 K On-line
3283    user.pat.backup      1969534538 BK      17537 K On-line
3284    Total volumes onLine 66 ; Total volumes offLine 0 ;  Total busy 0
3285 </programlisting>
3286
3287       <para><emphasis role="bold">Output with the -fast Flag</emphasis></para>
3288
3289       <indexterm>
3290         <primary>vos commands</primary>
3291
3292         <secondary>listvol</secondary>
3293
3294         <tertiary>output with -fast flag</tertiary>
3295       </indexterm>
3296
3297       <para>If you include the <emphasis role="bold">-fast</emphasis> flag displays only the volume ID number of each volume,
3298       arranged in increasing numerical order, as in the following example. The final line (which summarizes the number of on-line,
3299       off-line, and busy volumes) is omitted.</para>
3300
3301       <programlisting>
3302    % <emphasis role="bold">vos listvol fs3.abc.com /vicepa -f</emphasis>
3303    Total number of volumes on server fs3.abc.com  \
3304                                        partition /vicepa: 37
3305    50489902
3306    50489904
3307       .
3308       .
3309    35970325
3310    49732810
3311 </programlisting>
3312
3313       <para><emphasis role="bold">Output with the -long Flag</emphasis></para>
3314
3315       <indexterm>
3316         <primary>vos commands</primary>
3317
3318         <secondary>listvol</secondary>
3319
3320         <tertiary>output with -long flag</tertiary>
3321       </indexterm>
3322
3323       <para>When you include the <emphasis role="bold">-long</emphasis> flag, , the output for each volume includes all of the
3324       information in the default listing plus the following. Each item in this list corresponds to a separate line of output:
3325       <itemizedlist>
3326           <listitem>
3327             <para>The file server machine and partition that house the volume, as determined by the command interpreter as the
3328             command runs, rather than derived from the VLDB or the volume header.</para>
3329
3330             <indexterm>
3331               <primary>read/write volume</primary>
3332
3333               <secondary>ID number in volume header</secondary>
3334             </indexterm>
3335
3336             <indexterm>
3337               <primary>read-only volume</primary>
3338
3339               <secondary>ID number in volume header</secondary>
3340             </indexterm>
3341
3342             <indexterm>
3343               <primary>backup volume</primary>
3344
3345               <secondary>ID number in volume header</secondary>
3346             </indexterm>
3347
3348             <indexterm>
3349               <primary>ReleaseClone volume</primary>
3350
3351               <secondary>ID number in volume header</secondary>
3352             </indexterm>
3353
3354             <indexterm>
3355               <primary>RWrite field in volume header</primary>
3356             </indexterm>
3357
3358             <indexterm>
3359               <primary>ROnly field in volume header</primary>
3360             </indexterm>
3361
3362             <indexterm>
3363               <primary>Backup field in volume header</primary>
3364             </indexterm>
3365
3366             <indexterm>
3367               <primary>RClone field in volume header</primary>
3368             </indexterm>
3369           </listitem>
3370
3371           <listitem>
3372             <para>The volume ID numbers associated with the various versions of the volume: read/write
3373             (<computeroutput>RWrite</computeroutput>), read-only (<computeroutput>ROnly</computeroutput>), backup
3374             (<computeroutput>Backup</computeroutput>), and ReleaseClone (<computeroutput>RClone</computeroutput>). One of them
3375             matches the volume ID number that appears on the first line of the volume's output. If the value in the
3376             <computeroutput>RWrite</computeroutput>, <computeroutput>ROnly</computeroutput>, or
3377             <computeroutput>Backup</computeroutput> field is <computeroutput>0</computeroutput> (zero), there is no volume of that
3378             type. If there is currently no ReleaseClone, the <computeroutput>RClone</computeroutput> field does not appear at
3379             all.</para>
3380
3381             <indexterm>
3382               <primary>volume quota</primary>
3383
3384               <secondary>recorded in volume header</secondary>
3385             </indexterm>
3386
3387             <indexterm>
3388               <primary>MaxQuota field in volume header</primary>
3389             </indexterm>
3390           </listitem>
3391
3392           <listitem>
3393             <para>The maximum space quota allotted to the read/write copy of the volume, expressed in kilobyte blocks in the
3394             <computeroutput>MaxQuota</computeroutput> field.</para>
3395
3396             <indexterm>
3397               <primary>creation date</primary>
3398
3399               <secondary>recorded in volume header</secondary>
3400             </indexterm>
3401
3402             <indexterm>
3403               <primary>volume</primary>
3404
3405               <secondary>Creation date in volume header</secondary>
3406             </indexterm>
3407           </listitem>
3408
3409           <listitem>
3410             <para>The date and time the volume was created, in the <computeroutput>Creation</computeroutput> field. If the volume
3411             has been restored with the <emphasis role="bold">backup diskrestore</emphasis>, <emphasis role="bold">backup
3412             volrestore</emphasis>, or <emphasis role="bold">vos restore</emphasis> command, this is the restore time.</para>
3413
3414             <indexterm>
3415               <primary>update date</primary>
3416
3417               <secondary>recorded in volume header</secondary>
3418             </indexterm>
3419
3420             <indexterm>
3421               <primary>volume</primary>
3422
3423               <secondary>Last Update date in volume header</secondary>
3424             </indexterm>
3425           </listitem>
3426
3427           <listitem>
3428             <para>The date and time when the contents of the volume last changed, in the <computeroutput>Last
3429             Update</computeroutput> field. For read-only and backup volumes, it matches the timestamp in the
3430             <computeroutput>Creation</computeroutput> field.</para>
3431
3432             <indexterm>
3433               <primary>access</primary>
3434
3435               <secondary>count, in volume header</secondary>
3436             </indexterm>
3437
3438             <indexterm>
3439               <primary>volume</primary>
3440
3441               <secondary>counter in header for number of accesses</secondary>
3442             </indexterm>
3443           </listitem>
3444
3445           <listitem>
3446             <para>The number of times the volume has been accessed for a fetch or store operation since the later of the two
3447             following times: <itemizedlist>
3448                 <listitem>
3449                   <para>12:00 a.m. on the day the command is issued</para>
3450                 </listitem>
3451
3452                 <listitem>
3453                   <para>The last time the volume changed location</para>
3454                 </listitem>
3455               </itemizedlist></para>
3456           </listitem>
3457         </itemizedlist></para>
3458
3459       <para>An example of the output when the <emphasis role="bold">-long</emphasis> flag is included:</para>
3460
3461       <programlisting>
3462    % <emphasis role="bold">vos listvol fs2.abc.com b -long</emphasis>
3463    Total number of volumes on server fs2.abc.com
3464                                        partition /vicepb: 66
3465          .                   .      .         .   .    .
3466          .                   .      .         .   .    .
3467    user.pat             1969534536 RW      17518 K On-line
3468         fs2.abc.com /vicepb
3469         RWrite 1969534536 ROnly 0        Backup 1969534538
3470         MaxQuota      20000 K
3471         Creation    Mon Jun 12 09:02:25 1989
3472         Last Update Thu Jan  4 17:39:34 1990
3473         1573 accesses in the past day (i.e., vnode references)
3474    user.pat.backup      1969534538 BK      17537 K On-line
3475         fs2.abc.com /vicepb
3476         RWrite 1969534536 ROnly 0        Backup 1969534538
3477         MaxQuota      20000 K
3478         Creation    Fri Jan  5 06:37:59 1990
3479         Last Update Fri Jan  5 06:37:59 1990
3480         0 accesses in the past day (i.e., vnode references)
3481             .               .         .     .       .
3482             .               .         .     .       .
3483    Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
3484 </programlisting>
3485
3486       <para><emphasis role="bold">Output with the -extended Flag</emphasis></para>
3487
3488       <indexterm>
3489         <primary>vos commands</primary>
3490
3491         <secondary>listvol</secondary>
3492
3493         <tertiary>output with -extended flag</tertiary>
3494       </indexterm>
3495
3496       <para>When you include the <emphasis role="bold">-extended</emphasis> flag, the output for each volume includes all of the
3497       information reported with the <emphasis role="bold">-long</emphasis> flag, plus two tables of statistics: <itemizedlist>
3498           <listitem>
3499             <para>The table labeled <computeroutput>Raw Read/Write Stats</computeroutput> table summarizes the number of times the
3500             volume has been accessed for reading or writing.</para>
3501           </listitem>
3502
3503           <listitem>
3504             <para>The table labeled <computeroutput>Writes Affecting Authorship</computeroutput> table contains information on
3505             writes made to files and directories in the specified volume.</para>
3506           </listitem>
3507         </itemizedlist></para>
3508
3509       <para>An example of the output when the <emphasis role="bold">-extended</emphasis> flag is included:</para>
3510
3511       <programlisting>
3512    % <emphasis role="bold">vos listvol fs3.abc.com a -extended</emphasis>
3513    common.bboards   1969535592 RW    23149 K used 9401 files On-line
3514        fs3.abc.com /vicepa
3515        RWrite 1969535592 ROnly          0 Backup 1969535594
3516        MaxQuota      30000 K
3517        Creation    Mon Mar  8 14:26:05 1999
3518        Last Update Mon Apr 26 09:20:43 1999
3519        11533 accesses in the past day (i.e., vnode references)
3520                          Raw Read/Write Stats
3521              |-------------------------------------------|
3522              |    Same Network     |    Diff Network     |
3523              |----------|----------|----------|----------|
3524              |  Total   |   Auth   |   Total  |   Auth   |
3525              |----------|----------|----------|----------|
3526    Reads     |      151 |      151 |     1092 |     1068 |
3527    Writes    |        3 |        3 |      324 |      324 |
3528              |-------------------------------------------|
3529                       Writes Affecting Authorship
3530              |-------------------------------------------|
3531              |   File Authorship   | Directory Authorship|
3532              |----------|----------|----------|----------|
3533              |   Same   |   Diff   |    Same  |   Diff   |
3534              |----------|----------|----------|----------|
3535    0-60 sec  |       92 |        0 |      100 |        4 |
3536    1-10 min  |        1 |        0 |       14 |        6 |
3537    10min-1hr |        0 |        0 |       19 |        4 |
3538    1hr-1day  |        1 |        0 |       13 |        0 |
3539    1day-1wk  |        1 |        0 |        1 |        0 |
3540    &gt; 1wk     |        0 |        0 |        0 |        0 |
3541              |-------------------------------------------|
3542 </programlisting>
3543     </sect2>
3544
3545     <sect2 id="HDRWQ221">
3546       <title>Displaying One Volume's VLDB Entry and Volume Header</title>
3547
3548       <indexterm>
3549         <primary>displaying</primary>
3550
3551         <secondary>VLDB entry</secondary>
3552
3553         <tertiary>with volume header</tertiary>
3554       </indexterm>
3555
3556       <indexterm>
3557         <primary>displaying</primary>
3558
3559         <secondary>VLDB entry with volume header</secondary>
3560       </indexterm>
3561
3562       <indexterm>
3563         <primary>VLDB</primary>
3564
3565         <secondary>displaying entry</secondary>
3566
3567         <tertiary>with volume header</tertiary>
3568       </indexterm>
3569
3570       <indexterm>
3571         <primary>entry in VLDB</primary>
3572
3573         <secondary>displaying, with volume header</secondary>
3574       </indexterm>
3575
3576       <indexterm>
3577         <primary>displaying</primary>
3578
3579         <secondary>volume header</secondary>
3580
3581         <tertiary>with VLDB entry</tertiary>
3582       </indexterm>
3583
3584       <indexterm>
3585         <primary>displaying</primary>
3586
3587         <secondary>volume header with VLDB entry</secondary>
3588       </indexterm>
3589
3590       <indexterm>
3591         <primary>volume header</primary>
3592
3593         <secondary>displaying</secondary>
3594
3595         <tertiary>with VLDB entry</tertiary>
3596       </indexterm>
3597
3598       <para>The <emphasis role="bold">vos examine</emphasis> command displays information from both the VLDB and the volume header
3599       for a single volume. There is some redundancy in the information from the two sources, which allows you to compare the VLDB
3600       and volume header.</para>
3601
3602       <para>Because the volume header for each version of a volume (read/write, read-only, and backup) is different, you can specify
3603       which one to display. Include the <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis>
3604       extension on the volume name or ID argument as appropriate. The information from the VLDB is the same for all three
3605       versions.</para>
3606
3607       <indexterm>
3608         <primary>commands</primary>
3609
3610         <secondary>vos examine</secondary>
3611
3612         <tertiary>basic instructions</tertiary>
3613       </indexterm>
3614
3615       <indexterm>
3616         <primary>vos commands</primary>
3617
3618         <secondary>examine</secondary>
3619
3620         <tertiary>basic instructions</tertiary>
3621       </indexterm>
3622     </sect2>
3623
3624     <sect2 id="HDRWQ222">
3625       <title>To display one volume's VLDB entry and volume header</title>
3626
3627       <orderedlist>
3628         <listitem>
3629           <para>Issue the <emphasis role="bold">vos examine</emphasis> command. <programlisting>
3630    % <emphasis role="bold">vos examine</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
3631 </programlisting></para>
3632
3633           <para>where <variablelist>
3634               <varlistentry>
3635                 <term><emphasis role="bold">e</emphasis></term>
3636
3637                 <listitem>
3638                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
3639                 </listitem>
3640               </varlistentry>
3641
3642               <varlistentry>
3643                 <term><emphasis role="bold">volume name or ID</emphasis></term>
3644
3645                 <listitem>
3646                   <para>Identifies one volume either by its complete name or volume ID number. It can be a read/write, read-only, or
3647                   backup type. Use the <emphasis role="bold">.backup</emphasis> or <emphasis role="bold">.readonly</emphasis>
3648                   extension if appropriate.</para>
3649                 </listitem>
3650               </varlistentry>
3651             </variablelist></para>
3652         </listitem>
3653       </orderedlist>
3654
3655       <para>The top part of the output displays the same information from a volume header as the <emphasis role="bold">vos
3656       listvol</emphasis> command with the <emphasis role="bold">-long</emphasis> flag, as described following the instructions in
3657       <link linkend="HDRWQ220">To display volume headers</link>. If you specify the read-only version of the volume and it exists at
3658       more than one site, the output includes all of them. The bottom part of the output lists the same information from the VLDB as
3659       the <emphasis role="bold">vos listvldb</emphasis> command, as described following the instructions in <link
3660       linkend="HDRWQ218">To display VLDB entries</link>.</para>
3661
3662       <para>Below is an example for a volume whose VLDB entry is currently locked.</para>
3663
3664       <programlisting>
3665    % <emphasis role="bold">vos examine user.terry</emphasis>
3666    user.terry                    536870981 RW   3459 K On-line
3667        fs3.abc.com /vicepa
3668        Write 5360870981   ROnly          0  Backup 536870983
3669        MaxQuota      40000 K
3670        Creation    Mon Jun 12 15:22:06 1989
3671        Last Update Fri Jun 16 09:34:35 1989
3672        5719 accesses in the past day (i.e., vnode references)