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