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/.abc.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.abc.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.abc.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/.abc.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">abc.com</emphasis> cell.</para>
2405
2406       <programlisting>
2407    % <emphasis role="bold">fs lsmount /afs/abc.com/usr/terry</emphasis>
2408    '/afs/abc.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">abc.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/.abc.com</emphasis>
2417    '/afs/.abc.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">abc.com</emphasis> cell.</para>
2423
2424       <programlisting>
2425    % <emphasis role="bold">fs lsmount /afs/ghi.gov</emphasis>
2426    '/afs/ghi.gov' is a mount point for volume '#ghi.gov: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">abc.com</emphasis> cell.</para>
2431
2432       <programlisting>
2433    % <emphasis role="bold">fs lsmount /afs/abc</emphasis>
2434    '/afs/abc' 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/.abc.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/.abc.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</para>
2781           </listitem>
2782           <listitem>
2783             <para><emphasis role="bold">Unix:</emphasis>
2784             /afs/.:mount/example.com#root.cell</para>
2785           </listitem>
2786       </itemizedlist>
2787     </sect2>
2788   </sect1>
2789
2790   <sect1 id="HDRWQ216">
2791     <title>Displaying Information About Volumes</title>
2792
2793     <indexterm>
2794       <primary>displaying</primary>
2795
2796       <secondary>volume information</secondary>
2797     </indexterm>
2798
2799     <indexterm>
2800       <primary>volume</primary>
2801
2802       <secondary>displaying information about</secondary>
2803     </indexterm>
2804
2805     <para>This section explains how to display information about volumes. If you know a volume's name or volume ID number, there are
2806     commands for displaying its VLDB entry, its volume header, or both. Other commands display the name or location of the volume
2807     that contains a specified file or directory.</para>
2808
2809     <para>For instructions on displaying a volume's quota, see <link linkend="HDRWQ234">Setting and Displaying Volume Quota and
2810     Current Size</link>.</para>
2811
2812     <sect2 id="HDRWQ217">
2813       <title>Displaying VLDB Entries</title>
2814
2815       <indexterm>
2816         <primary>displaying</primary>
2817
2818         <secondary>volume's VLDB entry</secondary>
2819       </indexterm>
2820
2821       <indexterm>
2822         <primary>VLDB</primary>
2823
2824         <secondary>displaying volume entry</secondary>
2825       </indexterm>
2826
2827       <indexterm>
2828         <primary>volume entry (VLDB)</primary>
2829
2830         <secondary>displaying</secondary>
2831       </indexterm>
2832
2833       <indexterm>
2834         <primary>locked VLDB entry</primary>
2835
2836         <secondary>displaying</secondary>
2837       </indexterm>
2838
2839       <para>The <emphasis role="bold">vos listvldb</emphasis> command displays the VLDB entry for the volumes indicated by the
2840       combination of arguments you provide. The possibilities are listed here from most to least inclusive: <itemizedlist>
2841           <listitem>
2842             <para>To display every entry in the VLDB, provide no arguments. It can take a long time to generate the output,
2843             depending on the number of entries.</para>
2844           </listitem>
2845
2846           <listitem>
2847             <para>To display every VLDB entry that mentions a specific file server machine as the site of a volume, specify the
2848             machine's name with the <emphasis role="bold">-server</emphasis> argument.</para>
2849           </listitem>
2850
2851           <listitem>
2852             <para>To display every VLDB entry that mentions a certain partition on any file server machine as the site of a volume,
2853             specify the partition name with the <emphasis role="bold">-partition</emphasis> argument.</para>
2854           </listitem>
2855
2856           <listitem>
2857             <para>To display every VLDB entry that mentions a certain partition on a certain file server machine as the site of a
2858             volume, combine the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis>
2859             arguments.</para>
2860           </listitem>
2861
2862           <listitem>
2863             <para>To display a single VLDB entry, specify a volume name or ID number with the <emphasis role="bold">-name</emphasis>
2864             argument.</para>
2865           </listitem>
2866
2867           <listitem>
2868             <para>To display the VLDB entry only for volumes with locked VLDB entries, use the <emphasis
2869             role="bold">-locked</emphasis> flag with any of the site definitions mentioned previously.</para>
2870           </listitem>
2871         </itemizedlist></para>
2872
2873       <indexterm>
2874         <primary>commands</primary>
2875
2876         <secondary>vos listvldb</secondary>
2877
2878         <tertiary>syntax</tertiary>
2879       </indexterm>
2880
2881       <indexterm>
2882         <primary>vos commands</primary>
2883
2884         <secondary>listvldb</secondary>
2885
2886         <tertiary>syntax</tertiary>
2887       </indexterm>
2888     </sect2>
2889
2890     <sect2 id="HDRWQ218">
2891       <title>To display VLDB entries</title>
2892
2893       <orderedlist>
2894         <listitem>
2895           <para>Issue the <emphasis role="bold">vos listvldb</emphasis> command. <programlisting>
2896    % <emphasis role="bold">vos listvldb</emphasis> [<emphasis role="bold">-name</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;] [<emphasis
2897                 role="bold">-server</emphasis> &lt;<replaceable>machine name</replaceable>&gt;] \
2898         [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>partition name</replaceable>&gt;] [<emphasis role="bold">-locked</emphasis>]
2899 </programlisting></para>
2900
2901           <para>where <variablelist>
2902               <varlistentry>
2903                 <term><emphasis role="bold">listvl</emphasis></term>
2904
2905                 <listitem>
2906                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listvldb</emphasis>.</para>
2907                 </listitem>
2908               </varlistentry>
2909
2910               <varlistentry>
2911                 <term><emphasis role="bold">-name</emphasis></term>
2912
2913                 <listitem>
2914                   <para>Identifies one volume either by its complete name or volume ID number. Do not combine this argument with the
2915                   <emphasis role="bold">-server</emphasis> or <emphasis role="bold">-partition</emphasis> arguments.</para>
2916                 </listitem>
2917               </varlistentry>
2918
2919               <varlistentry>
2920                 <term><emphasis role="bold">-server</emphasis></term>
2921
2922                 <listitem>
2923                   <para>Specifies a file server machine. Combine this argument with the <emphasis role="bold">-partition</emphasis>
2924                   argument if desired, but not with the <emphasis role="bold">-name</emphasis> argument.</para>
2925                 </listitem>
2926               </varlistentry>
2927
2928               <varlistentry>
2929                 <term><emphasis role="bold">-partition</emphasis></term>
2930
2931                 <listitem>
2932                   <para>Specifies a partition. Combine this argument with the <emphasis role="bold">-server</emphasis> argument if
2933                   desired, but not with the <emphasis role="bold">-name</emphasis> argument.</para>
2934                 </listitem>
2935               </varlistentry>
2936
2937               <varlistentry>
2938                 <term><emphasis role="bold">-locked</emphasis></term>
2939
2940                 <listitem>
2941                   <para>Displays only locked VLDB entries. Combine this flag with any of the other options.</para>
2942                 </listitem>
2943               </varlistentry>
2944             </variablelist></para>
2945         </listitem>
2946       </orderedlist>
2947
2948       <para>The VLDB entry for each volume includes the following information: <itemizedlist>
2949           <listitem>
2950             <para>The base (read/write) volume name. The read-only and backup versions have the same name with a <emphasis
2951             role="bold">.readonly</emphasis> and <emphasis role="bold">.backup</emphasis> extension, respectively.</para>
2952           </listitem>
2953
2954           <listitem>
2955             <para>The volume ID numbers allocated to the versions of the volume that actually exist, in fields labeled
2956             <computeroutput>RWrite</computeroutput> for the read/write, <computeroutput>ROnly</computeroutput> for the read-only,
2957             <computeroutput>Backup</computeroutput> for the backup, and <computeroutput>RClone</computeroutput> for the
2958             ReleaseClone. (If a field does not appear, the corresponding version of the volume does not exist.) The appearance of
2959             the <computeroutput>RClone</computeroutput> field normally indicates that a release operation did not complete
2960             successfully; the <computeroutput>Old release</computeroutput> and <computeroutput>New release</computeroutput> flags
2961             often also appear on one or more of the site definition lines described just following.</para>
2962
2963             <indexterm>
2964               <primary>site</primary>
2965
2966               <secondary>count in VLDB</secondary>
2967             </indexterm>
2968
2969             <indexterm>
2970               <primary>VLDB</primary>
2971
2972               <secondary>site count for volume</secondary>
2973             </indexterm>
2974           </listitem>
2975
2976           <listitem>
2977             <para>The number of sites that house a read/write or read-only copy of the volume, following the string
2978             <computeroutput>number of sites -&gt;</computeroutput>.</para>
2979
2980             <indexterm>
2981               <primary>type flag for volume</primary>
2982
2983               <secondary>VLDB entry</secondary>
2984             </indexterm>
2985
2986             <indexterm>
2987               <primary>VLDB</primary>
2988
2989               <secondary>volume type flags</secondary>
2990             </indexterm>
2991
2992             <indexterm>
2993               <primary>release</primary>
2994
2995               <secondary>status flags on site definitions in VLDB entry</secondary>
2996             </indexterm>
2997
2998             <indexterm>
2999               <primary>VLDB</primary>
3000
3001               <secondary>release status flags in volume entry</secondary>
3002             </indexterm>
3003
3004             <indexterm>
3005               <primary>status flag</primary>
3006
3007               <secondary>release, on site definitions in VLDB entry</secondary>
3008             </indexterm>
3009           </listitem>
3010
3011           <listitem>
3012             <para>A line for each site that houses a read/write or read-only copy of the volume, specifying the file server machine,
3013             partition, and type of volume (<computeroutput>RW</computeroutput> for read/write or <computeroutput>RO</computeroutput>
3014             for read-only). If a backup version exists, it is understood to share the read/write site. Several flags can appear with
3015             a site definition: <variablelist>
3016                 <indexterm>
3017                   <primary>Not released</primary>
3018
3019                   <secondary>status flag on site definition in VLDB entry</secondary>
3020                 </indexterm>
3021
3022                 <varlistentry>
3023                   <term><computeroutput>Not released</computeroutput></term>
3024
3025                   <listitem>
3026                     <para>Indicates that the <emphasis role="bold">vos release</emphasis> command has not been issued since the
3027                     <emphasis role="bold">vos addsite</emphasis> command was used to define the read-only site.</para>
3028
3029                     <indexterm>
3030                       <primary>Old release</primary>
3031
3032                       <secondary>status flag on site definition in VLDB entry</secondary>
3033                     </indexterm>
3034                   </listitem>
3035                 </varlistentry>
3036
3037                 <varlistentry>
3038                   <term><computeroutput>Old release</computeroutput></term>
3039
3040                   <listitem>
3041                     <para>Indicates that a <emphasis role="bold">vos release</emphasis> command did not complete successfully,
3042                     leaving the previous, obsolete version of the volume at this site.</para>
3043
3044                     <indexterm>
3045                       <primary>New release</primary>
3046
3047                       <secondary>status flag on site definition in VLDB entry</secondary>
3048                     </indexterm>
3049                   </listitem>
3050                 </varlistentry>
3051
3052                 <varlistentry>
3053                   <term><computeroutput>New release</computeroutput></term>
3054
3055                   <listitem>
3056                     <para>Indicates that a <emphasis role="bold">vos release</emphasis> command did not complete successfully, but
3057                     that this site did receive the correct new version of the volume.</para>
3058                   </listitem>
3059                 </varlistentry>
3060               </variablelist></para>
3061           </listitem>
3062
3063           <listitem>
3064             <para>If the VLDB entry is locked, the string <computeroutput>Volume is currently LOCKED</computeroutput>.</para>
3065           </listitem>
3066         </itemizedlist></para>
3067
3068       <para>For further discussion of the <computeroutput>New release</computeroutput> and <computeroutput>Old
3069       release</computeroutput> flags, see <link linkend="HDRWQ192">Replicating Volumes (Creating Read-only Volumes)</link>.</para>
3070
3071       <para>An example of this command and its output for a single volume:</para>
3072
3073       <programlisting>
3074    % <emphasis role="bold">vos listvldb user.terry</emphasis>
3075    user.terry
3076        RWrite: 50489902    Backup: 50489904
3077        number of sites -&gt; 1
3078           server fs3.abc.com partition /vicepc RW Site
3079 </programlisting>
3080     </sect2>
3081
3082     <sect2 id="HDRWQ219">
3083       <title>Displaying Volume Headers</title>
3084
3085       <indexterm>
3086         <primary>displaying</primary>
3087
3088         <secondary>volume header</secondary>
3089       </indexterm>
3090
3091       <indexterm>
3092         <primary>volume header</primary>
3093
3094         <secondary>displaying</secondary>
3095
3096         <tertiary>only</tertiary>
3097       </indexterm>
3098
3099       <para>The <emphasis role="bold">vos listvol</emphasis> command displays the volume header for every volume on one or all
3100       partitions on a file server machine. The <emphasis role="bold">vos</emphasis> command interpreter obtains the information from
3101       the Volume Server on the specified machine. You can control the amount of information displayed by including one of the
3102       <emphasis role="bold">-fast</emphasis>, the <emphasis role="bold">-long</emphasis>, or the <emphasis
3103       role="bold">-extended</emphasis> flags described following the instructions in <link linkend="HDRWQ220">To display volume
3104       headers</link>.</para>
3105
3106       <para>To display a single volume's volume header of one volume only, use the <emphasis role="bold">vos examine</emphasis>
3107       command as described in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header</link>.</para>
3108
3109       <indexterm>
3110         <primary>commands</primary>
3111
3112         <secondary>vos listvol</secondary>
3113
3114         <tertiary>syntax</tertiary>
3115       </indexterm>
3116
3117       <indexterm>
3118         <primary>vos commands</primary>
3119
3120         <secondary>listvol</secondary>
3121
3122         <tertiary>syntax</tertiary>
3123       </indexterm>
3124     </sect2>
3125
3126     <sect2 id="HDRWQ220">
3127       <title>To display volume headers</title>
3128
3129       <orderedlist>
3130         <listitem>
3131           <para>Issue the <emphasis role="bold">vos listvol</emphasis> command. <programlisting>
3132    % <emphasis role="bold">vos listvol</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>partition name</replaceable>&gt;] [<emphasis
3133                 role="bold">-fast</emphasis>] [<emphasis role="bold">-long</emphasis>] [<emphasis role="bold">-extended</emphasis>]
3134 </programlisting></para>
3135
3136           <para>where <variablelist>
3137               <varlistentry>
3138                 <term><emphasis role="bold">listvo</emphasis></term>
3139
3140                 <listitem>
3141                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listvol</emphasis>.</para>
3142                 </listitem>
3143               </varlistentry>
3144
3145               <varlistentry>
3146                 <term><emphasis role="bold">machine name</emphasis></term>
3147
3148                 <listitem>
3149                   <para>Names the file server machine for which to display volume headers. Provide this argument alone or with the
3150                   partition name argument.</para>
3151                 </listitem>
3152               </varlistentry>
3153
3154               <varlistentry>
3155                 <term><emphasis role="bold">partition name</emphasis></term>
3156
3157                 <listitem>
3158                   <para>Names one partition on the file server machine named by the machine name argument, which must be provided
3159                   along with this one.</para>
3160                 </listitem>
3161               </varlistentry>
3162
3163               <varlistentry>
3164                 <term><emphasis role="bold">-fast</emphasis></term>
3165
3166                 <listitem>
3167                   <para>Displays only the volume ID numbers of relevant volumes. Do not combine this flag with the <emphasis
3168                   role="bold">-long</emphasis> or <emphasis role="bold">-extended</emphasis> flag.</para>
3169                 </listitem>
3170               </varlistentry>
3171
3172               <varlistentry>
3173                 <term><emphasis role="bold">-long</emphasis></term>
3174
3175                 <listitem>
3176                   <para>Displays more detailed information about each volume. Do not combine this flag with the <emphasis
3177                   role="bold">-fast</emphasis> or <emphasis role="bold">-extended</emphasis> flag.</para>
3178                 </listitem>
3179               </varlistentry>
3180
3181               <varlistentry>
3182                 <term><emphasis role="bold">-extended</emphasis></term>
3183
3184                 <listitem>
3185                   <para>Displays all of the information displayed by the <emphasis role="bold">-long</emphasis> flag, plus tables of
3186                   statistics about reads and writes to the files in the volume. Do not combine this flag with the <emphasis
3187                   role="bold">-fast</emphasis> or <emphasis role="bold">-long</emphasis> flag.</para>
3188                 </listitem>
3189               </varlistentry>
3190             </variablelist></para>
3191         </listitem>
3192       </orderedlist>
3193
3194       <para>The output is ordered alphabetically by volume name and by default provides the following information on a single line
3195       for each volume: <itemizedlist>
3196           <listitem>
3197             <para>Name</para>
3198           </listitem>
3199
3200           <listitem>
3201             <para>Volume ID number</para>
3202
3203             <indexterm>
3204               <primary>type flag for volume</primary>
3205
3206               <secondary>volume header</secondary>
3207             </indexterm>
3208           </listitem>
3209
3210           <listitem>
3211             <para>Type (the flag is <computeroutput>RW</computeroutput> for read/write, <computeroutput>RO</computeroutput> for
3212             read-only, <computeroutput>BK</computeroutput> for backup)</para>
3213           </listitem>
3214
3215           <listitem>
3216             <para>Size in kilobytes (<computeroutput>1024</computeroutput> equals a megabyte)</para>
3217           </listitem>
3218
3219           <listitem>
3220             <para>Number of files in the volume, if the <emphasis role="bold">-extended</emphasis> flag is provided</para>
3221
3222             <indexterm>
3223               <primary>status flags in volume header</primary>
3224             </indexterm>
3225           </listitem>
3226
3227           <listitem>
3228             <para>Status on the file server machine, which is one of the following: <variablelist>
3229                 <indexterm>
3230                   <primary>On-line status flag in volume header</primary>
3231                 </indexterm>
3232
3233                 <varlistentry>
3234                   <term><computeroutput>On-line</computeroutput></term>
3235
3236                   <listitem>
3237                     <para>The volume is completely accessible to Cache Managers.</para>
3238
3239                     <indexterm>
3240                       <primary>Off-line status flag in volume header</primary>
3241                     </indexterm>
3242                   </listitem>
3243                 </varlistentry>
3244
3245                 <varlistentry>
3246                   <term><computeroutput>Off-line</computeroutput></term>
3247
3248                   <listitem>
3249                     <para>The volume is not accessible to Cache Managers, but does not seem to be corrupted. This status appears
3250                     while a volume is being dumped, for example.</para>
3251
3252                     <indexterm>
3253                       <primary>needs salvage status flag in volume header</primary>
3254                     </indexterm>
3255                   </listitem>
3256                 </varlistentry>
3257
3258                 <varlistentry>
3259                   <term><computeroutput>Off-line**needs salvage**</computeroutput></term>
3260
3261                   <listitem>
3262                     <para>The volume is not accessible to Cache Managers, because it seems to be corrupted. Use the <emphasis
3263                     role="bold">bos salvage</emphasis> or <emphasis role="bold">salvager</emphasis> command to repair the
3264                     corruption.</para>
3265                   </listitem>
3266                 </varlistentry>
3267               </variablelist></para>
3268           </listitem>
3269         </itemizedlist></para>
3270
3271       <para>If the following message appears instead of the previously listed information, it indicates that a volume is not
3272       accessible to Cache Managers or the <emphasis role="bold">vos</emphasis> command interpreter, for example because a clone is
3273       being created.</para>
3274
3275       <programlisting>
3276    **** Volume volume_ID is busy ****
3277 </programlisting>
3278
3279       <para>If the following message appears instead of the previously listed information, it indicates that the File Server is
3280       unable to attach the volume, perhaps because it is seriously corrupted. The <emphasis role="bold">FileLog</emphasis> and
3281       <emphasis role="bold">VolserLog</emphasis> log files in the <emphasis role="bold">/usr/afs/logs</emphasis> directory on the
3282       file server machine possibly provide additional information; use the <emphasis role="bold">bos getlog</emphasis> command to
3283       display them.</para>
3284
3285       <programlisting>
3286    **** Could not attach volume volume_ID ****
3287 </programlisting>
3288
3289       <para>(For instructions on salvaging a corrupted or unattached volume, see <link linkend="HDRWQ232">Salvaging
3290       Volumes</link>.)</para>
3291
3292       <para>The information about individual volumes is bracketed by summary lines. The first line of output specifies the number of
3293       volumes in the listing. The last line of output summarizes the number of volumes that are online, offline, and busy, as in the
3294       following example:</para>
3295
3296       <programlisting>
3297    % <emphasis role="bold">vos listvol  fs2.abc.com /vicepb</emphasis>
3298    Total number of volumes on server fs2.abc.com \
3299                                        partition /vicepb : 66
3300    sys                  1969534847 RW       1582 K On-line
3301    sys.backup           1969535105 BK       1582 K On-line
3302          .                   .     .         .   .    .
3303          .                   .     .         .   .    .
3304    user.pat             1969534536 RW      17518 K On-line
3305    user.pat.backup      1969534538 BK      17537 K On-line
3306    Total volumes onLine 66 ; Total volumes offLine 0 ;  Total busy 0
3307 </programlisting>
3308
3309       <para><emphasis role="bold">Output with the -fast Flag</emphasis></para>
3310
3311       <indexterm>
3312         <primary>vos commands</primary>
3313
3314         <secondary>listvol</secondary>
3315
3316         <tertiary>output with -fast flag</tertiary>
3317       </indexterm>
3318
3319       <para>If you include the <emphasis role="bold">-fast</emphasis> flag displays only the volume ID number of each volume,
3320       arranged in increasing numerical order, as in the following example. The final line (which summarizes the number of on-line,
3321       off-line, and busy volumes) is omitted.</para>
3322
3323       <programlisting>
3324    % <emphasis role="bold">vos listvol fs3.abc.com /vicepa -f</emphasis>
3325    Total number of volumes on server fs3.abc.com  \
3326                                        partition /vicepa: 37
3327    50489902
3328    50489904
3329       .
3330       .
3331    35970325
3332    49732810
3333 </programlisting>
3334
3335       <para><emphasis role="bold">Output with the -long Flag</emphasis></para>
3336
3337       <indexterm>
3338         <primary>vos commands</primary>
3339
3340         <secondary>listvol</secondary>
3341
3342         <tertiary>output with -long flag</tertiary>
3343       </indexterm>
3344
3345       <para>When you include the <emphasis role="bold">-long</emphasis> flag, , the output for each volume includes all of the
3346       information in the default listing plus the following. Each item in this list corresponds to a separate line of output:
3347       <itemizedlist>
3348           <listitem>
3349             <para>The file server machine and partition that house the volume, as determined by the command interpreter as the
3350             command runs, rather than derived from the VLDB or the volume header.</para>
3351
3352             <indexterm>
3353               <primary>read/write volume</primary>
3354
3355               <secondary>ID number in volume header</secondary>
3356             </indexterm>
3357
3358             <indexterm>
3359               <primary>read-only volume</primary>
3360
3361               <secondary>ID number in volume header</secondary>
3362             </indexterm>
3363
3364             <indexterm>
3365               <primary>backup volume</primary>
3366
3367               <secondary>ID number in volume header</secondary>
3368             </indexterm>
3369
3370             <indexterm>
3371               <primary>ReleaseClone volume</primary>
3372
3373               <secondary>ID number in volume header</secondary>
3374             </indexterm>
3375
3376             <indexterm>
3377               <primary>RWrite field in volume header</primary>
3378             </indexterm>
3379
3380             <indexterm>
3381               <primary>ROnly field in volume header</primary>
3382             </indexterm>
3383
3384             <indexterm>
3385               <primary>Backup field in volume header</primary>
3386             </indexterm>
3387
3388             <indexterm>
3389               <primary>RClone field in volume header</primary>
3390             </indexterm>
3391           </listitem>
3392
3393           <listitem>
3394             <para>The volume ID numbers associated with the various versions of the volume: read/write
3395             (<computeroutput>RWrite</computeroutput>), read-only (<computeroutput>ROnly</computeroutput>), backup
3396             (<computeroutput>Backup</computeroutput>), and ReleaseClone (<computeroutput>RClone</computeroutput>). One of them
3397             matches the volume ID number that appears on the first line of the volume's output. If the value in the
3398             <computeroutput>RWrite</computeroutput>, <computeroutput>ROnly</computeroutput>, or
3399             <computeroutput>Backup</computeroutput> field is <computeroutput>0</computeroutput> (zero), there is no volume of that
3400             type. If there is currently no ReleaseClone, the <computeroutput>RClone</computeroutput> field does not appear at
3401             all.</para>
3402
3403             <indexterm>
3404               <primary>volume quota</primary>
3405
3406               <secondary>recorded in volume header</secondary>
3407             </indexterm>
3408
3409             <indexterm>
3410               <primary>MaxQuota field in volume header</primary>
3411             </indexterm>
3412           </listitem>
3413
3414           <listitem>
3415             <para>The maximum space quota allotted to the read/write copy of the volume, expressed in kilobyte blocks in the
3416             <computeroutput>MaxQuota</computeroutput> field.</para>
3417
3418             <indexterm>
3419               <primary>creation date</primary>
3420
3421               <secondary>recorded in volume header</secondary>
3422             </indexterm>
3423
3424             <indexterm>
3425               <primary>volume</primary>
3426
3427               <secondary>Creation date in volume header</secondary>
3428             </indexterm>
3429           </listitem>
3430
3431           <listitem>
3432             <para>The date and time the volume was created, in the <computeroutput>Creation</computeroutput> field. If the volume
3433             has been restored with the <emphasis role="bold">backup diskrestore</emphasis>, <emphasis role="bold">backup
3434             volrestore</emphasis>, or <emphasis role="bold">vos restore</emphasis> command, this is the restore time.</para>
3435
3436             <indexterm>
3437               <primary>update date</primary>
3438
3439               <secondary>recorded in volume header</secondary>
3440             </indexterm>
3441
3442             <indexterm>
3443               <primary>volume</primary>
3444
3445               <secondary>Last Update date in volume header</secondary>
3446             </indexterm>
3447           </listitem>
3448
3449           <listitem>
3450             <para>The date and time when the contents of the volume last changed, in the <computeroutput>Last
3451             Update</computeroutput> field. For read-only and backup volumes, it matches the timestamp in the
3452             <computeroutput>Creation</computeroutput> field.</para>
3453
3454             <indexterm>
3455               <primary>access</primary>
3456
3457               <secondary>count, in volume header</secondary>
3458             </indexterm>
3459
3460             <indexterm>
3461               <primary>volume</primary>
3462
3463               <secondary>counter in header for number of accesses</secondary>
3464             </indexterm>
3465           </listitem>
3466
3467           <listitem>
3468             <para>The number of times the volume has been accessed for a fetch or store operation since the later of the two
3469             following times: <itemizedlist>
3470                 <listitem>
3471                   <para>12:00 a.m. on the day the command is issued</para>
3472                 </listitem>
3473
3474                 <listitem>
3475                   <para>The last time the volume changed location</para>
3476                 </listitem>
3477               </itemizedlist></para>
3478           </listitem>
3479         </itemizedlist></para>
3480
3481       <para>An example of the output when the <emphasis role="bold">-long</emphasis> flag is included:</para>
3482
3483       <programlisting>
3484    % <emphasis role="bold">vos listvol fs2.abc.com b -long</emphasis>
3485    Total number of volumes on server fs2.abc.com
3486                                        partition /vicepb: 66
3487          .                   .      .         .   .    .
3488          .                   .      .         .   .    .
3489    user.pat             1969534536 RW      17518 K On-line
3490         fs2.abc.com /vicepb
3491         RWrite 1969534536 ROnly 0        Backup 1969534538
3492         MaxQuota      20000 K
3493         Creation    Mon Jun 12 09:02:25 1989
3494         Last Update Thu Jan  4 17:39:34 1990
3495         1573 accesses in the past day (i.e., vnode references)
3496    user.pat.backup      1969534538 BK      17537 K On-line
3497         fs2.abc.com /vicepb
3498         RWrite 1969534536 ROnly 0        Backup 1969534538
3499         MaxQuota      20000 K
3500         Creation    Fri Jan  5 06:37:59 1990
3501         Last Update Fri Jan  5 06:37:59 1990
3502         0 accesses in the past day (i.e., vnode references)
3503             .               .         .     .       .
3504             .               .         .     .       .
3505    Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
3506 </programlisting>
3507
3508       <para><emphasis role="bold">Output with the -extended Flag</emphasis></para>
3509
3510       <indexterm>
3511         <primary>vos commands</primary>
3512
3513         <secondary>listvol</secondary>
3514
3515         <tertiary>output with -extended flag</tertiary>
3516       </indexterm>
3517
3518       <para>When you include the <emphasis role="bold">-extended</emphasis> flag, the output for each volume includes all of the
3519       information reported with the <emphasis role="bold">-long</emphasis> flag, plus two tables of statistics: <itemizedlist>
3520           <listitem>
3521             <para>The table labeled <computeroutput>Raw Read/Write Stats</computeroutput> table summarizes the number of times the
3522             volume has been accessed for reading or writing.</para>
3523           </listitem>
3524
3525           <listitem>
3526             <para>The table labeled <computeroutput>Writes Affecting Authorship</computeroutput> table contains information on
3527             writes made to files and directories in the specified volume.</para>
3528           </listitem>
3529         </itemizedlist></para>
3530
3531       <para>An example of the output when the <emphasis role="bold">-extended</emphasis> flag is included:</para>
3532
3533       <programlisting>
3534    % <emphasis role="bold">vos listvol fs3.abc.com a -extended</emphasis>
3535    common.bboards   1969535592 RW    23149 K used 9401 files On-line
3536        fs3.abc.com /vicepa
3537        RWrite 1969535592 ROnly          0 Backup 1969535594
3538        MaxQuota      30000 K
3539        Creation    Mon Mar  8 14:26:05 1999
3540        Last Update Mon Apr 26 09:20:43 1999
3541        11533 accesses in the past day (i.e., vnode references)
3542                          Raw Read/Write Stats
3543              |-------------------------------------------|
3544              |    Same Network     |    Diff Network     |
3545              |----------|----------|----------|----------|
3546              |  Total   |   Auth   |   Total  |   Auth   |
3547              |----------|----------|----------|----------|
3548    Reads     |      151 |      151 |     1092 |     1068 |
3549    Writes    |        3 |        3 |      324 |      324 |
3550              |-------------------------------------------|
3551                       Writes Affecting Authorship
3552              |-------------------------------------------|
3553              |   File Authorship   | Directory Authorship|
3554              |----------|----------|----------|----------|
3555              |   Same   |   Diff   |    Same  |   Diff   |
3556              |----------|----------|----------|----------|
3557    0-60 sec  |       92 |        0 |      100 |        4 |
3558    1-10 min  |        1 |        0 |       14 |        6 |
3559    10min-1hr |        0 |        0 |       19 |        4 |
3560    1hr-1day  |        1 |        0 |       13 |        0 |
3561    1day-1wk  |        1 |        0 |        1 |        0 |
3562    &gt; 1wk     |        0 |        0 |        0 |        0 |
3563              |-------------------------------------------|
3564 </programlisting>
3565     </sect2>
3566
3567     <sect2 id="HDRWQ221">
3568       <title>Displaying One Volume's VLDB Entry and Volume Header</title>
3569
3570       <indexterm>
3571         <primary>displaying</primary>
3572
3573         <secondary>VLDB entry</secondary>
3574
3575         <tertiary>with volume header</tertiary>
3576       </indexterm>
3577
3578       <indexterm>
3579         <primary>displaying</primary>
3580
3581         <secondary>VLDB entry with volume header</secondary>
3582       </indexterm>
3583
3584       <indexterm>
3585         <primary>VLDB</primary>
3586
3587         <secondary>displaying entry</secondary>
3588
3589         <tertiary>with volume header</tertiary>
3590       </indexterm>
3591
3592       <indexterm>
3593         <primary>entry in VLDB</primary>
3594
3595         <secondary>displaying, with volume header</secondary>
3596       </indexterm>
3597
3598       <indexterm>
3599         <primary>displaying</primary>
3600
3601         <secondary>volume header</secondary>
3602
3603         <tertiary>with VLDB entry</tertiary>
3604       </indexterm>
3605
3606       <indexterm>
3607         <primary>displaying</primary>
3608
3609         <secondary>volume header with VLDB entry</secondary>
3610       </indexterm>
3611
3612       <indexterm>
3613         <primary>volume header</primary>
3614
3615         <secondary>displaying</secondary>
3616
3617         <tertiary>with VLDB entry</tertiary>
3618       </indexterm>
3619
3620       <para>The <emphasis role="bold">vos examine</emphasis> command displays information from both the VLDB and the volume header
3621       for a single volume. There is some redundancy in the information from the two sources, which allows you to compare the VLDB
3622       and volume header.</para>
3623
3624       <para>Because the volume header for each version of a volume (read/write, read-only, and backup) is different, you can specify
3625       which one to display. Include the <emphasis role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis>
3626       extension on the volume name or ID argument as appropriate. The information from the VLDB is the same for all three
3627       versions.</para>
3628
3629       <indexterm>
3630         <primary>commands</primary>
3631
3632         <secondary>vos examine</secondary>
3633
3634         <tertiary>basic instructions</tertiary>
3635       </indexterm>
3636
3637       <indexterm>
3638         <primary>vos commands</primary>
3639
3640         <secondary>examine</secondary>
3641
3642         <tertiary>basic instructions</tertiary>
3643       </indexterm>
3644     </sect2>
3645
3646     <sect2 id="HDRWQ222">
3647       <title>To display one volume's VLDB entry and volume header</title>
3648
3649       <orderedlist>
3650         <listitem>
3651           <para>Issue the <emphasis role="bold">vos examine</emphasis> command. <programlisting>
3652    % <emphasis role="bold">vos examine</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
3653 </programlisting></para>
3654
3655           <para>where <variablelist>
3656               <varlistentry>
3657                 <term><emphasis role="bold">e</emphasis></term>
3658
3659                 <listitem>
3660                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
3661                 </listitem>
3662               </varlistentry>
3663
3664               <varlistentry>
3665                 <term><emphasis role="bold">volume name or ID</emphasis></term>
3666
3667                 <listitem>
3668                   <para>Identifies one volume either by its complete name or volume ID number. It can be a read/write, read-only, or
3669                   backup type. Use the <emphasis role="bold">.backup</emphasis> or <emphasis role="bold">.readonly</emphasis>
3670                   extension if appropriate.</para>
3671                 </listitem>
3672               </varlistentry>
3673             </variablelist></para>
3674         </listitem>
3675       </orderedlist>
3676
3677       <para>The top part of the output displays the same information from a volume header as the <emphasis role="bold">vos
3678       listvol</emphasis> command with the <emphasis role="bold">-long</emphasis> flag, as described following the instructions in
3679       <link linkend="HDRWQ220">To display volume headers</link>. If you specify the read-only version of the volume and it exists at
3680       more than one site, the output includes all of them. The bottom part of the output lists the same information from the VLDB as
3681       the <emphasis role="bold">vos listvldb</emphasis> command, as described following the instructions in <link
3682       linkend="HDRWQ218">To display VLDB entries</link>.</para>
3683
3684       <para>Below is an example for a volume whose VLDB entry is currently locked.</para>
3685
3686       <programlisting>
3687    % <emphasis role="bold">vos examine user.terry</emphasis>
3688    user.terry                    536870981 RW   3459 K On-line
3689        fs3.abc.com /vicepa
3690        Write 5360870981   ROnly          0  Backup 536870983
3691        MaxQuota      40000 K
3692        Creation    Mon Jun 12 15:22:06 1989
3693        Last Update Fri Jun 16 09:34:35 1989
3694        5719 accesses in the past day (i.e., vnode references)
3695        RWrite: 5360870981   Backup: 536870983
3696        number of sites -&gt; 1
3697           server fs3.abc.com partition /vicepa RW Site
3698        Volume is currently LOCKED
3699 </programlisting>
3700     </sect2>
3701
3702     <sect2 id="HDRWQ223">
3703       <title>Displaying the Name or Location of the Volume that Contains a File</title>
3704
3705       <para>This section explains how to learn the name, volume ID number, or location of the volume that contains a file or
3706       directory.</para>
3707
3708       <para>You can also use one piece of information about a volume (for example, its name) to obtain other information about it
3709       (for example, its location). The following list points you to the relevant instructions: <itemizedlist>
3710           <indexterm>
3711             <primary>translating</primary>
3712
3713             <secondary>volume name to ID number</secondary>
3714           </indexterm>
3715
3716           <indexterm>
3717             <primary>learning</primary>
3718
3719             <secondary>volume ID</secondary>
3720
3721             <tertiary>given volume name</tertiary>
3722           </indexterm>
3723
3724           <indexterm>
3725             <primary>volume name</primary>
3726
3727             <secondary>translating</secondary>
3728
3729             <tertiary>to volume ID number</tertiary>
3730           </indexterm>
3731
3732           <indexterm>
3733             <primary>volume ID number</primary>
3734
3735             <secondary>learning</secondary>
3736
3737             <tertiary>from volume name</tertiary>
3738           </indexterm>
3739
3740           <indexterm>
3741             <primary>vos commands</primary>
3742
3743             <secondary>examine</secondary>
3744
3745             <tertiary>to learn volume ID</tertiary>
3746           </indexterm>
3747
3748           <indexterm>
3749             <primary>translating</primary>
3750
3751             <secondary>volume ID number to name</secondary>
3752           </indexterm>
3753
3754           <indexterm>
3755             <primary>learning</primary>
3756
3757             <secondary>volume name</secondary>
3758
3759             <tertiary>given volume ID number</tertiary>
3760           </indexterm>
3761
3762           <indexterm>
3763             <primary>volume name</primary>
3764
3765             <secondary>learning</secondary>
3766
3767             <tertiary>from volume ID number</tertiary>
3768           </indexterm>
3769
3770           <indexterm>
3771             <primary>volume ID number</primary>
3772
3773             <secondary>translating</secondary>
3774
3775             <tertiary>to volume name</tertiary>
3776           </indexterm>
3777
3778           <indexterm>
3779             <primary>vos commands</primary>
3780
3781             <secondary>examine</secondary>
3782
3783             <tertiary>to learn volume name</tertiary>
3784           </indexterm>
3785
3786           <listitem>
3787             <para>To use a volume's name to learn the volume ID numbers of all its existing versions, use the <emphasis
3788             role="bold">vos examine</emphasis> command as described in <link linkend="HDRWQ222">To display one volume's VLDB entry
3789             and volume header</link>.</para>
3790
3791             <para>You can also use the command to learn a volume's name by providing its ID number.</para>
3792           </listitem>
3793
3794           <listitem>
3795             <para>To use a volume's name or ID number to learn its location, use the <emphasis role="bold">vos listvldb</emphasis>
3796             command as described in <link linkend="HDRWQ218">To display VLDB entries</link>.</para>
3797
3798             <indexterm>
3799               <primary>translating</primary>
3800
3801               <secondary>volume name/ID number to volume location</secondary>
3802             </indexterm>
3803
3804             <indexterm>
3805               <primary>learning</primary>
3806
3807               <secondary>volume location</secondary>
3808
3809               <tertiary>given volume name/ID number</tertiary>
3810             </indexterm>
3811
3812             <indexterm>
3813               <primary>volume name</primary>
3814
3815               <secondary>translating</secondary>
3816
3817               <tertiary>to volume location</tertiary>
3818             </indexterm>
3819
3820             <indexterm>
3821               <primary>volume ID number</primary>
3822
3823               <secondary>translating</secondary>
3824
3825               <tertiary>to volume location</tertiary>
3826             </indexterm>
3827
3828             <indexterm>
3829               <primary>volume location</primary>
3830
3831               <secondary>learning from volume name/ID number</secondary>
3832             </indexterm>
3833
3834             <indexterm>
3835               <primary>vos commands</primary>
3836
3837               <secondary>listvldb</secondary>
3838
3839               <tertiary>to learn volume location</tertiary>
3840             </indexterm>
3841           </listitem>
3842         </itemizedlist></para>
3843
3844       <indexterm>
3845         <primary>translating</primary>
3846
3847         <secondary>directory/file name to volume name</secondary>
3848       </indexterm>
3849
3850       <indexterm>
3851         <primary>learning</primary>
3852
3853         <secondary>volume name</secondary>
3854
3855         <tertiary>given directory/file name</tertiary>
3856       </indexterm>
3857
3858       <indexterm>
3859         <primary>directory/file name</primary>
3860
3861         <secondary>translating to volume name</secondary>
3862       </indexterm>
3863
3864       <indexterm>
3865         <primary>volume name</primary>
3866
3867         <secondary>learning</secondary>
3868
3869         <tertiary>from directory/file name</tertiary>
3870       </indexterm>
3871
3872       <indexterm>
3873         <primary>commands</primary>
3874
3875         <secondary>fs listquota</secondary>
3876       </indexterm>
3877
3878       <indexterm>
3879         <primary>fs commands</primary>
3880
3881         <secondary>listquota</secondary>
3882       </indexterm>
3883
3884       <sect3 id="HDRWQ224">
3885         <title>To display the name of the volume that contains a file</title>
3886
3887         <orderedlist>
3888           <listitem>
3889             <para>Issue the <emphasis role="bold">fs listquota</emphasis> command. <programlisting>
3890    % <emphasis role="bold">fs listquota</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
3891 </programlisting></para>
3892
3893             <para>where <variablelist>
3894                 <varlistentry>
3895                   <term><emphasis role="bold">lq</emphasis></term>
3896
3897                   <listitem>
3898                     <para>Is an acceptable alias for <emphasis role="bold">listquota</emphasis>(and <emphasis
3899                     role="bold">listq</emphasis> the shortest acceptable abbreviation).</para>
3900                   </listitem>
3901                 </varlistentry>
3902
3903                 <varlistentry>
3904                   <term><emphasis role="bold">dir/file path</emphasis></term>
3905
3906                   <listitem>
3907                     <para>Names a directory or file housed in the volume for which to display the name. Partial pathnames are
3908                     interpreted relative to the current working directory, which is the default if this argument is omitted.</para>
3909                   </listitem>
3910                 </varlistentry>
3911               </variablelist></para>
3912           </listitem>
3913         </orderedlist>
3914
3915         <para>The following is an example of the output:</para>
3916
3917         <programlisting>
3918    % <emphasis role="bold">fs listquota /afs/abc.com/usr/terry</emphasis>
3919    Volume Name     Quota    Used    % Used   Partition
3920    user.terry      15000    5071       34%         86%
3921 </programlisting>
3922
3923         <indexterm>
3924           <primary>translating</primary>
3925
3926           <secondary>directory/file name to volume ID number</secondary>
3927         </indexterm>
3928
3929         <indexterm>
3930           <primary>learning</primary>
3931
3932           <secondary>volume ID</secondary>
3933
3934           <tertiary>given directory/file name</tertiary>
3935         </indexterm>
3936
3937         <indexterm>
3938           <primary>directory/file name</primary>
3939
3940           <secondary>translating to volume ID number</secondary>
3941         </indexterm>
3942
3943         <indexterm>
3944           <primary>volume ID number</primary>
3945
3946           <secondary>learning from directory/file name</secondary>
3947         </indexterm>
3948
3949         <indexterm>
3950           <primary>commands</primary>
3951
3952           <secondary>fs examine</secondary>
3953         </indexterm>
3954
3955         <indexterm>
3956           <primary>fs commands</primary>
3957
3958           <secondary>examine</secondary>
3959         </indexterm>
3960       </sect3>
3961
3962       <sect3 id="HDRWQ225">
3963         <title>To display the ID number of the volume that contains a file</title>
3964
3965         <orderedlist>
3966           <listitem>
3967             <para>Issue the <emphasis role="bold">fs examine</emphasis> command. <programlisting>
3968    % <emphasis role="bold">fs examine</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
3969 </programlisting></para>
3970
3971             <para>where <variablelist>
3972                 <varlistentry>
3973                   <term><emphasis role="bold">exa</emphasis></term>
3974
3975                   <listitem>
3976                     <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
3977                   </listitem>
3978                 </varlistentry>
3979
3980                 <varlistentry>
3981                   <term><emphasis role="bold">dir/file path</emphasis></term>
3982
3983                   <listitem>
3984                     <para>Names a directory or file housed in the volume for which to display the volume ID. Partial pathnames are
3985                     interpreted relative to the current working directory, which is the default if this argument is omitted.</para>
3986                   </listitem>
3987                 </varlistentry>
3988               </variablelist></para>
3989           </listitem>
3990         </orderedlist>
3991
3992         <para>The following example illustrates how the output reports the volume ID number in the
3993         <computeroutput>vid</computeroutput> field.</para>
3994
3995         <programlisting>
3996    % <emphasis role="bold">fs examine /afs/abc.com/usr/terry</emphasis>
3997    Volume status for vid = 50489902 named user.terry
3998    Current maximum quota is 15000
3999    Current blocks used are 5073
4000    The partition has 46383 blocks available out of 333305
4001 </programlisting>
4002
4003         <note>
4004           <para>The partition-related statistics in this command's output do not always agree with the corresponding values in the
4005           output of the standard UNIX <emphasis role="bold">df</emphasis> command. The statistics reported by this command can be up
4006           to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency. Also, on
4007           some operating systems, the <emphasis role="bold">df</emphasis> command's report of partition size includes reserved space
4008           not included in this command's calculation, and so is likely to be about 10% larger.</para>
4009         </note>
4010
4011         <indexterm>
4012           <primary>translating</primary>
4013
4014           <secondary>directory/file name to volume location</secondary>
4015         </indexterm>
4016
4017         <indexterm>
4018           <primary>learning</primary>
4019
4020           <secondary>volume location</secondary>
4021
4022           <tertiary>given directory/file name</tertiary>
4023         </indexterm>
4024
4025         <indexterm>
4026           <primary>directory/file name</primary>
4027
4028           <secondary>translating to volume location</secondary>
4029         </indexterm>
4030
4031         <indexterm>
4032           <primary>volume location</primary>
4033
4034           <secondary>learning from directory/file name</secondary>
4035         </indexterm>
4036
4037         <indexterm>
4038           <primary>volume</primary>
4039
4040           <secondary>location</secondary>
4041
4042           <see>volume location</see>
4043         </indexterm>
4044
4045         <indexterm>
4046           <primary>commands</primary>
4047
4048           <secondary>fs whereis</secondary>
4049         </indexterm>
4050
4051         <indexterm>
4052           <primary>fs commands</primary>
4053
4054           <secondary>whereis</secondary>
4055         </indexterm>
4056       </sect3>
4057
4058       <sect3 id="Header_242">
4059         <title>To display the location of the volume that contains a file</title>
4060
4061         <orderedlist>
4062           <listitem>
4063             <para>Issue the <emphasis role="bold">fs whereis</emphasis> command to display the name of the file server machine that
4064             houses the volume containing a file or directory. <programlisting>
4065    % <emphasis role="bold">fs whereis</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
4066 </programlisting></para>
4067
4068             <para>where <variablelist>
4069                 <varlistentry>
4070                   <term><emphasis role="bold">whe</emphasis></term>
4071
4072                   <listitem>
4073                     <para>Is the shortest acceptable abbreviation of <emphasis role="bold">whereis</emphasis>.</para>
4074                   </listitem>
4075                 </varlistentry>
4076
4077                 <varlistentry>
4078                   <term><emphasis role="bold">dir/file path</emphasis></term>
4079
4080                   <listitem>
4081                     <para>Names a directory or file for which to report the location. Partial pathnames are interpreted relative to
4082                     the current working directory, which is the default if this argument is omitted.</para>
4083                   </listitem>
4084                 </varlistentry>
4085               </variablelist></para>
4086
4087             <para>The output displays the file server machine that houses the volume containing the file, as in the following
4088             example:</para>
4089
4090             <programlisting>
4091    % <emphasis role="bold">fs whereis /afs/abc.com/user/terry</emphasis>
4092    File /afs/abc.com/usr/terry is on host fs2.abc.com
4093 </programlisting>
4094           </listitem>
4095
4096           <listitem>
4097             <para>If you also want to know which partition houses the volume, first issue the <emphasis role="bold">fs
4098             listquota</emphasis> command to display the volume's name. For complete syntax, see <link linkend="HDRWQ224">To display
4099             the name of the volume that contains a file</link>. <programlisting>
4100    % <emphasis role="bold">fs listquota</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
4101 </programlisting></para>
4102
4103             <para>Then issue the <emphasis role="bold">vos listvldb</emphasis> command, providing the volume name as the volume name
4104             or ID argument. For complete syntax and a description of the output, see <link linkend="HDRWQ218">To display VLDB
4105             entries</link>.</para>
4106
4107             <programlisting>
4108    % <emphasis role="bold">vos listvldb</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
4109 </programlisting>
4110           </listitem>
4111         </orderedlist>
4112       </sect3>
4113     </sect2>
4114   </sect1>
4115
4116   <sect1 id="HDRWQ226">
4117     <title>Moving Volumes</title>
4118
4119     <indexterm>
4120       <primary>moving</primary>
4121
4122       <secondary>volume</secondary>
4123     </indexterm>
4124
4125     <indexterm>
4126       <primary>volume</primary>
4127
4128       <secondary>moving</secondary>
4129     </indexterm>
4130
4131     <para>There are three main reasons to move volumes: <itemizedlist>
4132         <listitem>
4133           <para>To place volumes on other partitions or machines temporarily while repairing or replacing a disk or file server
4134           machine.</para>
4135         </listitem>
4136
4137         <listitem>
4138           <para><indexterm>
4139               <primary>disk partition</primary>
4140
4141               <secondary>moving volumes to reduce overcrowding</secondary>
4142             </indexterm> <indexterm>
4143               <primary>overcrowding of disk partition</primary>
4144
4145               <secondary>moving volumes to reduce</secondary>
4146             </indexterm> <indexterm>
4147               <primary>overcrowding of disk partition</primary>
4148
4149               <secondary>effect on users</secondary>
4150             </indexterm> <indexterm>
4151               <primary>failure</primary>
4152
4153               <secondary>of file storage due to full partition</secondary>
4154             </indexterm> <indexterm>
4155               <primary>file storage</primary>
4156
4157               <secondary>failed due to partition crowding</secondary>
4158             </indexterm> To free space on a partition that is becoming overcrowded. One symptom of overcrowding is that users cannot
4159           to save files even though the relevant volume is below its quota. The following error message confirms the problem:
4160           <programlisting>
4161    afs: failed to store file (partition full)
4162 </programlisting></para>
4163
4164           <para>You can track available space on AFS server partitions by using the <emphasis role="bold">scout</emphasis> or
4165           <emphasis role="bold">afsmonitor</emphasis> programs described in <link linkend="HDRWQ323">Monitoring and Auditing AFS
4166           Performance</link>.</para>
4167         </listitem>
4168
4169         <listitem>
4170           <para>A file server machine is becoming overloaded because it houses many more volumes than other machines of the same
4171           size, or has volumes with more popular files in them.</para>
4172         </listitem>
4173       </itemizedlist></para>
4174
4175     <indexterm>
4176       <primary>read/write volume</primary>
4177
4178       <secondary>moving</secondary>
4179     </indexterm>
4180
4181     <indexterm>
4182       <primary>backup volume</primary>
4183
4184       <secondary>removed by read/write move</secondary>
4185     </indexterm>
4186
4187     <para>To move a read/write volume, use the <emphasis role="bold">vos move</emphasis> command as described in the following
4188     instructions. Before attempting to move the volume, the <emphasis role="bold">vos</emphasis> command interpreter verifies that
4189     there is enough free space for it on the destination partition. If not, it does not attempt the move operation and prints the
4190     following message.</para>
4191
4192     <programlisting>
4193    vos: no space on target partition destination_part to move volume volume
4194 </programlisting>
4195
4196     <para>To move a read-only volume, you actually remove the volume from the current site by issuing the <emphasis role="bold">vos
4197     remove</emphasis> command as described in <link linkend="HDRWQ236">To remove a volume and unmount it</link>. Then define a new
4198     site and release the volume to it by issuing the <emphasis role="bold">vos addsite</emphasis> and <emphasis role="bold">vos
4199     release</emphasis> commands as described in <link linkend="HDRWQ194">To replicate a read/write volume (create a read-only
4200     volume)</link>.</para>
4201
4202     <indexterm>
4203       <primary>read-only volume</primary>
4204
4205       <secondary>moving</secondary>
4206     </indexterm>
4207
4208     <indexterm>
4209       <primary>backup volume</primary>
4210
4211       <secondary>moving</secondary>
4212     </indexterm>
4213
4214     <para>A backup volume always resides at the same site as its read/write source volume, so you cannot move a backup volume except
4215     as part of moving the read/write source. The <emphasis role="bold">vos move</emphasis> command automatically deletes the backup
4216     version when you move a read/write volume. To create a new backup volume at the new site as soon as the move operation
4217     completes, issue the <emphasis role="bold">vos backup</emphasis> command as described in <link linkend="HDRWQ205">To create and
4218     mount a backup volume</link>.</para>
4219
4220     <indexterm>
4221       <primary>commands</primary>
4222
4223       <secondary>vos move</secondary>
4224
4225       <tertiary>basic instructions</tertiary>
4226     </indexterm>
4227
4228     <indexterm>
4229       <primary>vos commands</primary>
4230
4231       <secondary>move</secondary>
4232
4233       <tertiary>basic instructions</tertiary>
4234     </indexterm>
4235
4236     <sect2 id="Header_244">
4237       <title>To move a read/write volume</title>
4238
4239       <orderedlist>
4240         <listitem>
4241           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
4242           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
4243           display the users in the UserList file</link>. <programlisting>
4244    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
4245 </programlisting></para>
4246         </listitem>
4247
4248         <listitem>
4249           <para>Issue the <emphasis role="bold">vos move</emphasis> command to move the volume. Type it on a single line; it appears
4250           on multiple lines here only for legibility. <programlisting>
4251    % <emphasis role="bold">vos move</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt; \ &lt;<replaceable>machine name on source</replaceable>&gt;
4252           &lt;<replaceable>partition name on source </replaceable>&gt; \ &lt;<replaceable>machine name on destination</replaceable>&gt; &lt;partition name on
4253           destination&gt;
4254 </programlisting></para>
4255
4256           <para>where <variablelist>
4257               <varlistentry>
4258                 <term><emphasis role="bold">m</emphasis></term>
4259
4260                 <listitem>
4261                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">move</emphasis>.</para>
4262                 </listitem>
4263               </varlistentry>
4264
4265               <varlistentry>
4266                 <term><emphasis role="bold">volume name or ID</emphasis></term>
4267
4268                 <listitem>
4269                   <para>Specifies the name or volume ID number of the read/write volume to move.</para>
4270                 </listitem>
4271               </varlistentry>
4272
4273               <varlistentry>
4274                 <term><emphasis role="bold">machine name on source</emphasis></term>
4275
4276                 <listitem>
4277                   <para>Names the file server machine currently housing the volume.</para>
4278                 </listitem>
4279               </varlistentry>
4280
4281               <varlistentry>
4282                 <term><emphasis role="bold">partition name on source</emphasis></term>
4283
4284                 <listitem>
4285                   <para>Names the partition currently housing the volume.</para>
4286                 </listitem>
4287               </varlistentry>
4288
4289               <varlistentry>
4290                 <term><emphasis role="bold">machine name on destination</emphasis></term>
4291
4292                 <listitem>
4293                   <para>Names the file server machine to which to move the volume.</para>
4294                 </listitem>
4295               </varlistentry>
4296
4297               <varlistentry>
4298                 <term><emphasis role="bold">partition name on destination</emphasis></term>
4299
4300                 <listitem>
4301                   <para>Names the partition to which to move the volume.</para>
4302                 </listitem>
4303               </varlistentry>
4304             </variablelist></para>
4305
4306           <note>
4307             <para>It is best not to halt a <emphasis role="bold">vos move</emphasis> operation before it completes, because parts of
4308             the volume can be left on both the source and destination machines. For more information, see the command's reference
4309             page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
4310           </note>
4311         </listitem>
4312
4313         <listitem>
4314           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">vos listvldb</emphasis> command to
4315           confirm the success of the move. Complete instructions appear in <link linkend="HDRWQ218">To display VLDB entries</link>.
4316           <programlisting>
4317    % <emphasis role="bold">vos listvldb</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
4318 </programlisting></para>
4319         </listitem>
4320
4321         <listitem>
4322           <para>If a backup version existed at the read/write volume's previous site, create a new backup at the new site by issuing
4323           the <emphasis role="bold">vos backup</emphasis> command, which is fully described in <link linkend="HDRWQ205">To create
4324           and mount a backup volume</link>. <programlisting>
4325    % <emphasis role="bold">vos backup</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
4326 </programlisting></para>
4327         </listitem>
4328       </orderedlist>
4329     </sect2>
4330   </sect1>
4331
4332   <sect1 id="HDRWQ227">
4333     <title>Synchronizing the VLDB and Volume Headers</title>
4334
4335     <indexterm>
4336       <primary>VLDB</primary>
4337
4338       <secondary>synchronizing with volume headers</secondary>
4339     </indexterm>
4340
4341     <indexterm>
4342       <primary>volume header</primary>
4343
4344       <secondary>synchronizing with VLDB</secondary>
4345     </indexterm>
4346
4347     <indexterm>
4348       <primary>volume</primary>
4349
4350       <secondary>synchronizing VLDB and volume header</secondary>
4351     </indexterm>
4352
4353     <para>AFS can provide transparent file access because the Volume Location Database (VLDB) constantly tracks volume locations.
4354     When the Cache Manager needs a file, it contacts the Volume Location (VL) Server, which reads the VLDB for the current location
4355     of the volume containing the file. Therefore, the VLDB must accurately reflect the state of volumes on the file server machines
4356     at all times. The Volume Server and VL Server automatically update a volume's VLDB entry when its status changes during a
4357     <emphasis role="bold">vos</emphasis> operation, by performing the following series of steps. <orderedlist>
4358         <listitem id="LIWQ228">
4359           <para>The VL Server locks the VLDB entry. The lock advises other operations not to manipulate any
4360           of the volume versions (read/write, read-only, or backup), which prevents the inconsistency that can result from multiple
4361           simultaneous operations.</para>
4362         </listitem>
4363
4364         <listitem id="LIWQ229">
4365           <para><indexterm>
4366               <primary>intention flag in VLDB entry</primary>
4367             </indexterm> <indexterm>
4368               <primary>VLDB</primary>
4369
4370               <secondary>intention flag set by VL Server</secondary>
4371             </indexterm>
4372           The VL Server sets an <emphasis>intention flag</emphasis> in the VLDB entry that
4373           indicates the kind of operation to be performed. This flag never appears in VLDB listings because it is for internal use
4374           only. In case the operation terminates prematurely, this flag tells the Salvager which operation was interrupted. (The
4375           Salvager then determines the steps necessary either to complete the operation or return the volume to a previous
4376           consistent state. For more information on salvaging, see <link linkend="HDRWQ232">Salvaging Volumes</link>.)</para>
4377         </listitem>
4378
4379         <listitem id="LIWQ230">
4380           <para>The Volume Server manipulates the volume. It usually sets the
4381           <computeroutput>Off-line</computeroutput> flag in the volume header, which makes the volume inaccessible to the File
4382           Server and other Volume Server operations during the manipulation. When the operation completes, the volume is again
4383           marked <computeroutput>On-line</computeroutput>.</para>
4384         </listitem>
4385
4386         <listitem id="LIWQ231">
4387           <para>The VL Server records any changes resulting from the operation in the VLDB entry. Once the
4388           operation is complete, it removes the intention flag set in Step <link linkend="LIWQ229">2</link>and releases the lock set
4389           in Step <link linkend="LIWQ228">1</link>.</para>
4390         </listitem>
4391       </orderedlist></para>
4392
4393     <para>If a <emphasis role="bold">vos</emphasis> operation fails while the Volume Server is manipulating the volume
4394     (corresponding to Step <link linkend="LIWQ230">3</link>), the volume can be left in an intermediate state, which is termed
4395     <emphasis>corruption</emphasis>. In this case, the <computeroutput>Off-line</computeroutput> or <computeroutput>Off-line**needs
4396     salvage**</computeroutput> marker usually appears at the end of the first line of output from the <emphasis role="bold">vos
4397     examine</emphasis> command. To repair the corruption, run the Salvager before attempting to resynchronize the VLDB and volume
4398     headers. For salvaging instructions, see <link linkend="HDRWQ232">Salvaging Volumes</link>.</para>
4399
4400     <para>More commonly, an interruption while flags are being set or removed (corresponding to Step <link
4401     linkend="LIWQ228">1</link>, Step <link linkend="LIWQ229">2</link>, or Step <link linkend="LIWQ231">4</link>) causes a
4402     discrepancy between the VLDB and volume headers. To resynchronize the VLDB and volumes, use the <emphasis role="bold">vos
4403     syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis> commands. To achieve complete VLDB consistency, it is best
4404     to run the <emphasis role="bold">vos syncvldb</emphasis> command on all file server machines in the cell, and then run the
4405     <emphasis role="bold">vos syncserv</emphasis> command on all file server machines in the cell.</para>
4406
4407     <indexterm>
4408       <primary>symptoms</primary>
4409
4410       <secondary>of VLDB/volume header desynchronization</secondary>
4411     </indexterm>
4412
4413     <indexterm>
4414       <primary>desynchronization of VLDB/volume headers</primary>
4415
4416       <secondary>symptoms of</secondary>
4417     </indexterm>
4418
4419     <indexterm>
4420       <primary>synchrony of VLDB and volume headers</primary>
4421
4422       <secondary>symptoms of lack of</secondary>
4423     </indexterm>
4424
4425     <para>There are several symptoms that indicate a volume operation failed: <itemizedlist>
4426         <listitem>
4427           <para>Error messages on the standard error stream or in server process log files indicate that an operation terminated
4428           abnormally. Perhaps you had to halt the operation before it completed (for instance, by using a signal such as <emphasis
4429           role="bold">Ctrl-c</emphasis>), or a file server machine or server process was not functioning when the operation ran. To
4430           determine if a machine or process is still not functioning, issue the <emphasis role="bold">bos status</emphasis> command
4431           as described in <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>.</para>
4432         </listitem>
4433
4434         <listitem>
4435           <para>A subsequent <emphasis role="bold">vos</emphasis> operation fails because a previous failure left a VLDB entry
4436           locked. Sometimes an error message reports that a volume is locked. To display a list of locked volumes, use the <emphasis
4437           role="bold">-locked</emphasis> flag on the <emphasis role="bold">vos listvldb</emphasis> command as described in <link
4438           linkend="HDRWQ217">Displaying VLDB Entries</link>.</para>
4439
4440           <para>If the only problem with a volume is that its VLDB entry is locked, you probably do not need to synchronize the
4441           entire VLDB. Instead use the <emphasis role="bold">vos unlock</emphasis> or <emphasis role="bold">vos
4442           unlockvldb</emphasis> command to unlock the entry, as described in <link linkend="HDRWQ247">Unlocking and Locking VLDB
4443           Entries</link>.</para>
4444         </listitem>
4445
4446         <listitem>
4447           <para>A subsequent <emphasis role="bold">vos</emphasis> operation fails because a previous failure left a volume marked as
4448           offline. To check a volume's current status, check the first line of output from the <emphasis role="bold">vos
4449           examine</emphasis> command as described in <link linkend="HDRWQ221">Displaying One Volume's VLDB Entry and Volume
4450           Header</link>.</para>
4451         </listitem>
4452       </itemizedlist></para>
4453
4454     <indexterm>
4455       <primary>synchrony of VLDB and volume headers</primary>
4456
4457       <secondary>restoring</secondary>
4458     </indexterm>
4459
4460     <indexterm>
4461       <primary>restoring</primary>
4462
4463       <secondary>synchrony of VLDB and volume headers</secondary>
4464     </indexterm>
4465
4466     <indexterm>
4467       <primary>desynchronization of VLDB/volume headers</primary>
4468
4469       <secondary>fixing</secondary>
4470     </indexterm>
4471
4472     <indexterm>
4473       <primary>Salvager</primary>
4474
4475       <secondary>running before VLDB/volume header resynchronization</secondary>
4476     </indexterm>
4477
4478     <indexterm>
4479       <primary>vos commands</primary>
4480
4481       <secondary>syncvldb</secondary>
4482
4483       <tertiary>effect</tertiary>
4484     </indexterm>
4485
4486     <para>The <emphasis role="bold">vos syncvldb</emphasis> command corrects the information in the Volume Location Database (VLDB)
4487     either about all volumes housed on a file server machine, about the volumes on just one partition, or about a single volume. If
4488     checking about one or more partitions, the command contacts the Volume Server to obtain a list of the volumes that actually
4489     reside on each partition. It then obtains the VLDB entry for each volume from the VL Server. It changes the VLDB entry as
4490     necessary to reflect the state of the volume on the partition. For example, it creates or updates a VLDB entry when it finds a
4491     volume for which the VLDB entry is missing or incomplete. However, if there is already a VLDB entry that defines a different
4492     location for the volume, or there are irreconcilable conflicts with other VLDB entries, it instead writes a message about the
4493     conflict to the standard error stream. The command never removes volumes from the file server machine.</para>
4494
4495     <para>When checking a single volume's VLDB entry, the command also automatically performs the operations invoked by the
4496     <emphasis role="bold">vos syncserv</emphasis> command: it not only verifies that the VLDB entry is correct for the specified
4497     volume type (read/write, backup, or read-only), but also checks that any related volume types mentioned in the VLDB entry
4498     actually exist at the site listed in the entry.</para>
4499
4500     <indexterm>
4501       <primary>vos commands</primary>
4502
4503       <secondary>syncserv</secondary>
4504
4505       <tertiary>effect</tertiary>
4506     </indexterm>
4507
4508     <para>The <emphasis role="bold">vos syncserv</emphasis> command verifies that each volume type (read/write, read-only, and
4509     backup) mentioned in a VLDB entry actually exists at the site indicated in the entry. It checks all VLDB entries that mention a
4510     site either on any of a file server machine's partitions or on one partition. Note that command can end up inspecting sites
4511     other than on the specified machine or partition, if there are read-only versions of the volume at sites other than the
4512     read/write site.</para>
4513
4514     <para>The command alters any incorrect information in the VLDB, unless there is an irreconcilable conflict with other VLDB
4515     entries. In that case, it writes a message to the standard error stream instead. The command never removes volumes from their
4516     sites.</para>
4517
4518     <indexterm>
4519       <primary>commands</primary>
4520
4521       <secondary>vos syncvldb</secondary>
4522     </indexterm>
4523
4524     <indexterm>
4525       <primary>vos commands</primary>
4526
4527       <secondary>syncvldb</secondary>
4528
4529       <tertiary>syntax</tertiary>
4530     </indexterm>
4531
4532     <indexterm>
4533       <primary>commands</primary>
4534
4535       <secondary>vos syncserv</secondary>
4536     </indexterm>
4537
4538     <indexterm>
4539       <primary>vos commands</primary>
4540
4541       <secondary>syncserv</secondary>
4542
4543       <tertiary>syntax</tertiary>
4544     </indexterm>
4545
4546     <sect2 id="Header_246">
4547       <title>To synchronize the VLDB with volume headers</title>
4548
4549       <orderedlist>
4550         <listitem>
4551           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
4552           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
4553           display the users in the UserList file</link>. <programlisting>
4554    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
4555 </programlisting></para>
4556         </listitem>
4557
4558         <listitem id="LIVOL-SYNCVL">
4559           <para>Issue the <emphasis role="bold">vos syncvldb</emphasis> command to make the VLDB reflect
4560           the true state of all volumes on a machine or partition, or the state of one volume.</para>
4561
4562           <note>
4563             <para>To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your
4564             cell for the <emphasis role="bold">-server</emphasis> argument in turn and omitting the <emphasis
4565             role="bold">-partition</emphasis> and <emphasis role="bold">-volume</emphasis> arguments, before proceeding to Step
4566             <link linkend="LIVOL-SYNCSR">3</link>.</para>
4567           </note>
4568
4569           <programlisting>
4570    % <emphasis role="bold">vos syncvldb -server</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>partition name</replaceable>&gt;] \
4571         [<emphasis role="bold">-volume</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;] [<emphasis role="bold">-verbose &gt;&gt;</emphasis> file]
4572 </programlisting>
4573
4574           <para>where <variablelist>
4575               <varlistentry>
4576                 <term><emphasis role="bold">syncv</emphasis></term>
4577
4578                 <listitem>
4579                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">syncvldb</emphasis>.</para>
4580                 </listitem>
4581               </varlistentry>
4582
4583               <varlistentry>
4584                 <term><emphasis role="bold">-server</emphasis></term>
4585
4586                 <listitem>
4587                   <para>Names the file server machine housing the volumes for which to verify VLDB entries. If you are also
4588                   providing the <emphasis role="bold">-volume</emphasis> argument, this argument must name the machine where the
4589                   volume actually resides.</para>
4590                 </listitem>
4591               </varlistentry>
4592
4593               <varlistentry>
4594                 <term><emphasis role="bold">-partition</emphasis></term>
4595
4596                 <listitem>
4597                   <para>Identifies the partition (on the file server machine specified by the <emphasis
4598                   role="bold">-server</emphasis> argument) housing the volumes for which to verify VLDB entries. In general, it is
4599                   best to omit this argument so that either the VLDB entries for all volumes on a server machine are corrected (if
4600                   you do not provide the <emphasis role="bold">-volume</emphasis> argument), or so that you do not need to guarantee
4601                   that the partition actually houses the volume named by the <emphasis role="bold">-volume</emphasis>
4602                   argument.</para>
4603                 </listitem>
4604               </varlistentry>
4605
4606               <varlistentry>
4607                 <term><emphasis role="bold">-volume</emphasis></term>
4608
4609                 <listitem>
4610                   <para>Specifies the name or volume ID number of a single volume for which to verify the VLDB entry.</para>
4611                 </listitem>
4612               </varlistentry>
4613
4614               <varlistentry>
4615                 <term><emphasis role="bold">-verbose &gt;&gt; file</emphasis></term>
4616
4617                 <listitem>
4618                   <para>Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the
4619                   machine on which you are issuing the command. The command often writes a large amount of output to the standard
4620                   output stream; writing it to a file enables you to examine the output more carefully.</para>
4621                 </listitem>
4622               </varlistentry>
4623             </variablelist></para>
4624         </listitem>
4625
4626         <listitem id="LIVOL-SYNCSR">
4627           <para>Issue the <emphasis role="bold">vos syncserv</emphasis> command to inspect each volume
4628           for which the VLDB lists a version at the specified site.</para>
4629
4630           <note>
4631             <para>To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your
4632             cell for the machine name argument in turn and omitting the partition name argument.</para>
4633           </note>
4634
4635           <programlisting>
4636    % <emphasis role="bold">vos syncserv</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>partition name</replaceable>&gt;] [<emphasis
4637               role="bold">-v &gt;&gt;</emphasis> file]
4638 </programlisting>
4639
4640           <para>where <variablelist>
4641               <varlistentry>
4642                 <term><emphasis role="bold">syncs</emphasis></term>
4643
4644                 <listitem>
4645                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">syncserv</emphasis>.</para>
4646                 </listitem>
4647               </varlistentry>
4648
4649               <varlistentry>
4650                 <term><emphasis role="bold">machine name</emphasis></term>
4651
4652                 <listitem>
4653                   <para>Names the file server machine mentioned in each VLDB entry to check.</para>
4654                 </listitem>
4655               </varlistentry>
4656
4657               <varlistentry>
4658                 <term><emphasis role="bold">partition name</emphasis></term>
4659
4660                 <listitem>
4661                   <para>Identifies the partition mentioned in each VLDB entry to check. If synchronizing the entire VLDB, omit this
4662                   argument.</para>
4663                 </listitem>
4664               </varlistentry>
4665
4666               <varlistentry>
4667                 <term><emphasis role="bold">-v &gt;&gt; file</emphasis></term>
4668
4669                 <listitem>
4670                   <para>Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the
4671                   machine on which you are issuing the command. The command often writes a large amount of output to the standard
4672                   output stream; writing it to a file enables you to examine the output more carefully.</para>
4673                 </listitem>
4674               </varlistentry>
4675             </variablelist></para>
4676         </listitem>
4677       </orderedlist>
4678     </sect2>
4679   </sect1>
4680
4681   <sect1 id="HDRWQ232">
4682     <title>Salvaging Volumes</title>
4683
4684     <indexterm>
4685       <primary>volume</primary>
4686
4687       <secondary>salvaging</secondary>
4688     </indexterm>
4689
4690     <indexterm>
4691       <primary>corruption</primary>
4692
4693       <secondary>symptoms and types</secondary>
4694     </indexterm>
4695
4696     <indexterm>
4697       <primary>symptoms</primary>
4698
4699       <secondary>volume corruption</secondary>
4700     </indexterm>
4701
4702     <indexterm>
4703       <primary>volume</primary>
4704
4705       <secondary>symptoms of corruption</secondary>
4706     </indexterm>
4707
4708     <indexterm>
4709       <primary>Salvager</primary>
4710
4711       <secondary>instructions for invoking</secondary>
4712     </indexterm>
4713
4714     <indexterm>
4715       <primary>file server machine</primary>
4716
4717       <secondary>salvaging volumes</secondary>
4718     </indexterm>
4719
4720     <indexterm>
4721       <primary>salvaging</primary>
4722
4723       <secondary>volumes</secondary>
4724     </indexterm>
4725
4726     <indexterm>
4727       <primary>partition</primary>
4728
4729       <secondary>salvaging all volumes</secondary>
4730     </indexterm>
4731
4732     <para>An unexpected interruption while the Volume Server or File Server is manipulating the data in a volume can leave the
4733     volume in an intermediate state (<emphasis>corrupted</emphasis>), rather than just creating a discrepancy between the
4734     information in the VLDB and volume headers. For example, the failure of the operation that saves changes to a file (by
4735     overwriting old data with new) can leave the old and new data mixed together on the disk.</para>
4736
4737     <para>If an operation halts because the Volume Server or File Server exits unexpectedly, the BOS Server automatically shuts down
4738     all components of the <emphasis role="bold">fs</emphasis> process and invokes the Salvager. The Salvager checks for and repairs
4739     any inconsistencies it can. Sometimes, however, there are symptoms of the following sort, which indicate corruption serious
4740     enough to create problems but not serious enough to cause the File Server component to fail. In these cases you can invoke the
4741     Salvager yourself by issuing the <emphasis role="bold">bos salvage</emphasis> command. <itemizedlist>
4742         <listitem>
4743           <para><emphasis role="bold">Symptom:</emphasis> A file appears in the output of the <emphasis role="bold">ls</emphasis>
4744           command, but attempts to access the file fail with messages indicating that it does not exist.</para>
4745
4746           <para><emphasis role="bold">Possible cause:</emphasis> The Volume Server or File Server exited in the middle of a
4747           file-creation operation, after changing the directory structure, but before actually storing data. (Other possible causes
4748           are that the ACL on the directory does not grant the permissions you need to access the file, or there is a process,
4749           machine, or network outage. Check for these causes before assuming the file is corrupted.)</para>
4750
4751           <para><emphasis role="bold">Salvager's solution:</emphasis> Remove the file's entry from the directory structure.</para>
4752         </listitem>
4753
4754         <listitem>
4755           <para><emphasis role="bold">Symptom:</emphasis> A volume is marked <computeroutput>Off-line</computeroutput> in the output
4756           from the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvol</emphasis> commands, or
4757           attempts to access the volume fail.</para>
4758
4759           <para><emphasis role="bold">Possible cause:</emphasis> Two files or versions of a file are sharing the same disk blocks
4760           because of an interrupted operation. The File Server and Volume Server normally refuse to attach volumes that exhibit this
4761           type of corruption, because it can be very dangerous. If the Volume Server or File Server do attach the volume but are
4762           unsure of the status of the affected disk blocks, they sometimes try to write yet more data there. When they cannot
4763           perform the write, the data is lost. This effect can cascade, causing loss of all data on a partition.</para>
4764
4765           <para><emphasis role="bold">Salvager's solution:</emphasis> Delete the data from the corrupted disk blocks in preference
4766           to losing an entire partition.</para>
4767         </listitem>
4768
4769         <listitem>
4770           <para><emphasis role="bold">Symptom:</emphasis> There is less space available on the partition than you expect based on
4771           the size statistic reported for each volume by the <emphasis role="bold">vos listvol</emphasis> command.</para>
4772
4773           <para><emphasis role="bold">Possible cause:</emphasis> There are orphaned files and directories. An
4774           <emphasis>orphaned</emphasis> element is completely inaccessible because it is not referenced by any directory that can
4775           act as its parent (is higher in the file tree). An orphaned element is not counted in the calculation of a volume's size
4776           (or against its quota), even though it occupies space on the server partition.</para>
4777
4778           <para><emphasis role="bold">Salvager's solution:</emphasis> By default, print a message to the <emphasis
4779           role="bold">/usr/afs/logs/SalvageLog</emphasis> file reporting how many orphans were found and the approximate number of
4780           kilobytes they are consuming. You can use the <emphasis role="bold">-orphans</emphasis> argument to remove or attach
4781           orphaned elements instead. See <link linkend="HDRWQ233">To salvage volumes</link>.</para>
4782         </listitem>
4783       </itemizedlist></para>
4784
4785     <para>When you notice symptoms such as these, use the <emphasis role="bold">bos salvage</emphasis> command to invoke the
4786     Salvager before corruption spreads. (Even though it operates on volumes, the command belongs to the <emphasis
4787     role="bold">bos</emphasis> suite because the BOS Server must coordinate the shutdown and restart of the Volume Server and File
4788     Server with the Salvager. It shuts them down before the Salvager starts, and automatically restarts them when the salvage
4789     operation finishes.)</para>
4790
4791     <para>All of the AFS data stored on a file server machine is inaccessible during the salvage of one or more partitions. If you
4792     salvage just one volume, it alone is inaccessible.</para>
4793
4794     <para>When processing one or more partitions, the command restores consistency to corrupted read/write volumes where possible.
4795     For read-only or backup volumes, it inspects only the volume header: <itemizedlist>
4796         <listitem>
4797           <para>If the volume header is corrupted, the Salvager removes the volume completely and records the removal in its log
4798           file, <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis>. Issue the <emphasis role="bold">vos release</emphasis> or
4799           <emphasis role="bold">vos backup</emphasis> command to create the read-only or backup volume again.</para>
4800         </listitem>
4801
4802         <listitem>
4803           <para>If the volume header is intact, the Salvager skips the volume (does not check for corruption in the contents).
4804           However, if the File Server notices corruption as it initializes, it sometimes refuses to attach the volume or bring it
4805           online. In this case, it is simplest to remove the volume by issuing the <emphasis role="bold">vos remove</emphasis> or
4806           <emphasis role="bold">vos zap</emphasis> command. Then issue the <emphasis role="bold">vos release</emphasis> or <emphasis
4807           role="bold">vos backup</emphasis> command to create it again.</para>
4808         </listitem>
4809       </itemizedlist></para>
4810
4811     <para>Combine the <emphasis role="bold">bos salvage</emphasis> command's arguments as indicated to salvage different numbers of
4812     volumes: <itemizedlist>
4813         <listitem>
4814           <para>To salvage all volumes on a file server machine, combine the <emphasis role="bold">-server</emphasis> argument and
4815           the <emphasis role="bold">-all</emphasis> flag.</para>
4816         </listitem>
4817
4818         <listitem>
4819           <para>To salvage all volumes on one partition, combine the <emphasis role="bold">-server</emphasis> and <emphasis
4820           role="bold">-partition</emphasis> arguments.</para>
4821         </listitem>
4822
4823         <listitem>
4824           <para>To salvage only one read/write volume, combine the <emphasis role="bold">-server</emphasis>, <emphasis
4825           role="bold">-partition</emphasis>, and <emphasis role="bold">-volume</emphasis> arguments. Only that volume is
4826           inaccessible to Cache Managers, because the BOS Server does not shutdown the File Server and Volume Server processes
4827           during the salvage of a single volume. Do not name a read-only or backup volume with the <emphasis
4828           role="bold">-volume</emphasis> argument. Instead, remove the volume, using the <emphasis role="bold">vos remove</emphasis>
4829           or <emphasis role="bold">vos zap</emphasis> command. Then create a new copy of the volume with the <emphasis
4830           role="bold">vos release</emphasis> or <emphasis role="bold">vos backup</emphasis> command.</para>
4831         </listitem>
4832       </itemizedlist></para>
4833
4834     <para>The Salvager always writes a trace to the <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis> file on the file
4835     server machine where it runs. To record the trace in another file as well (either in AFS or on the local disk of the machine
4836     where you issue the <emphasis role="bold">bos salvage</emphasis> command), name the file with the <emphasis
4837     role="bold">-file</emphasis> argument. Or, to display the trace on the standard output stream as it is written to the <emphasis
4838     role="bold">/usr/afs/logs/SalvageLog</emphasis> file, include the <emphasis role="bold">-showlog</emphasis> flag.</para>
4839
4840     <para>By default, multiple Salvager subprocesses run in parallel: one for each partition up to four, and four subprocesses for
4841     four or more partitions. To increase or decrease the number of subprocesses running in parallel, provide a positive integer
4842     value for the <emphasis role="bold">-parallel</emphasis> argument.</para>
4843
4844     <para>If there is more than one server partition on a physical disk, the Salvager by default salvages them serially to avoid the
4845     inefficiency of constantly moving the disk head from one partition to another. However, this strategy is often not ideal if the
4846     partitions are configured as logical volumes that span multiple disks. To force the Salvager to salvage logical volumes in
4847     parallel, provide the string <emphasis role="bold">all</emphasis> as the value for the <emphasis
4848     role="bold">-parallel</emphasis> argument. Provide a positive integer to specify the number of subprocesses to run in parallel
4849     (for example, <emphasis role="bold">-parallel 5all</emphasis> for five subprocesses), or omit the integer to run up to four
4850     subprocesses, depending on the number of logical volumes being salvaged.</para>
4851
4852     <para>The Salvager creates temporary files as it runs, by default writing them to the partition it is salvaging. The number of
4853     files can be quite large, and if the partition is too full to accommodate them, the Salvager terminates without completing the
4854     salvage operation (it always removes the temporary files before exiting). Other Salvager subprocesses running at the same time
4855     continue until they finish salvaging all other partitions where there is enough disk space for temporary files. To complete the
4856     interrupted salvage, reissue the command against the appropriate partitions, adding the <emphasis role="bold">-tmpdir</emphasis>
4857     argument to redirect the temporary files to a local disk directory that has enough space.</para>
4858
4859     <para>The <emphasis role="bold">-orphans</emphasis> argument controls how the Salvager handles orphaned files and directories
4860     that it finds on server partitions it is salvaging. An orphaned element is completely inaccessible because it is not referenced
4861     by the vnode of any directory that can act as its parent (is higher in the filespace). Orphaned objects occupy space on the
4862     server partition, but do not count against the volume's quota.</para>
4863
4864     <para>During the salvage, the output of the <emphasis role="bold">bos status</emphasis> command reports the following auxiliary
4865     status for the <emphasis role="bold">fs</emphasis> process:</para>
4866
4867     <programlisting>
4868    Salvaging file system
4869 </programlisting>
4870
4871     <indexterm>
4872       <primary>bos commands</primary>
4873
4874       <secondary>salvage</secondary>
4875     </indexterm>
4876
4877     <indexterm>
4878       <primary>commands</primary>
4879
4880       <secondary>bos salvage</secondary>
4881     </indexterm>
4882
4883     <sect2 id="HDRWQ233">
4884       <title>To salvage volumes</title>
4885
4886       <orderedlist>
4887         <listitem>
4888           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
4889           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
4890           display the users in the UserList file</link>. <programlisting>
4891    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
4892 </programlisting></para>
4893         </listitem>
4894
4895         <listitem>
4896           <para>Issue the <emphasis role="bold">bos salvage</emphasis> command to salvage one or more volumes. <programlisting>
4897    % <emphasis role="bold">bos salvage  -server</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>salvage partition</replaceable>&gt;]  \
4898                   [<emphasis role="bold">-volume</emphasis> &lt;<replaceable>salvage volume number or volume name</replaceable>&gt;]  \
4899                   [<emphasis role="bold">-file</emphasis> salvage log output file]  [<emphasis role="bold">-all</emphasis>]  [<emphasis
4900                 role="bold">-showlog</emphasis>]  \
4901                   [<emphasis role="bold">-parallel</emphasis> &lt;<replaceable># of max parallel partition salvaging</replaceable>&gt;]  \
4902                   [<emphasis role="bold">-tmpdir</emphasis> &lt;<replaceable>directory to place tmp files</replaceable>&gt;]  \
4903                   [<emphasis role="bold">-orphans</emphasis> &lt;<emphasis role="bold">ignore</emphasis> | <emphasis role="bold">remove</emphasis> | <emphasis
4904                 role="bold">attach</emphasis> &gt;]
4905 </programlisting></para>
4906
4907           <para>where <variablelist>
4908               <varlistentry>
4909                 <term><emphasis role="bold">-server</emphasis></term>
4910
4911                 <listitem>
4912                   <para>Names the file server machine on which to salvage volumes. This argument can be combined either with the
4913                   <emphasis role="bold">-all</emphasis> flag, the <emphasis role="bold">-partition</emphasis> argument, or both the
4914                   <emphasis role="bold">-partition</emphasis> and <emphasis role="bold">-volume</emphasis> arguments.</para>
4915                 </listitem>
4916               </varlistentry>
4917
4918               <varlistentry>
4919                 <term><emphasis role="bold">-partition</emphasis></term>
4920
4921                 <listitem>
4922                   <para>Names a single partition on which to salvage all volumes. The <emphasis role="bold">-server</emphasis>
4923                   argument must be provided along with this one.</para>
4924                 </listitem>
4925               </varlistentry>
4926
4927               <varlistentry>
4928                 <term><emphasis role="bold">-volume</emphasis></term>
4929
4930                 <listitem>
4931                   <para>Specifies the name or volume ID number of one read/write volume to salvage. Combine this argument with the
4932                   <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments.</para>
4933                 </listitem>
4934               </varlistentry>
4935
4936               <varlistentry>
4937                 <term><emphasis role="bold">-file</emphasis></term>
4938
4939                 <listitem>
4940                   <para>Specifies the complete pathname of a file into which to write a trace of the salvage operation, in addition
4941                   to the <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis> file on the server machine. If the file pathname
4942                   is local, the trace is written to the specified file on the local disk of the machine where the <emphasis
4943                   role="bold">bos salvage</emphasis> command is issued. If the <emphasis role="bold">-volume</emphasis> argument is
4944                   included, the file can be in AFS, though not in the volume being salvaged. Do not combine this argument with the
4945                   <emphasis role="bold">-showlog</emphasis> flag.</para>
4946                 </listitem>
4947               </varlistentry>
4948
4949               <varlistentry>
4950                 <term><emphasis role="bold">-all</emphasis></term>
4951
4952                 <listitem>
4953                   <para>Salvages all volumes on all of the partitions on the machine named by the <emphasis
4954                   role="bold">-server</emphasis> argument.</para>
4955                 </listitem>
4956               </varlistentry>
4957
4958               <varlistentry>
4959                 <term><emphasis role="bold">-showlog</emphasis></term>
4960
4961                 <listitem>
4962                   <para>Displays the trace of the salvage operation on the standard output stream, as well as writing it to the
4963                   <emphasis role="bold">/usr/afs/logs/SalvageLog</emphasis> file.</para>
4964                 </listitem>
4965               </varlistentry>
4966
4967               <varlistentry>
4968                 <term><emphasis role="bold">-parallel</emphasis></term>
4969
4970                 <listitem>
4971                   <para>Specifies the maximum number of Salvager subprocesses to run in parallel. Provide one of three values:
4972                   <itemizedlist>
4973                       <listitem>
4974                         <para>An integer from the range <emphasis role="bold">1</emphasis> to <emphasis role="bold">32</emphasis>. A
4975                         value of <emphasis role="bold">1</emphasis> means that a single Salvager process salvages the partitions
4976                         sequentially.</para>
4977                       </listitem>
4978
4979                       <listitem>
4980                         <para>The string <emphasis role="bold">all</emphasis> to run up to four Salvager subprocesses in parallel on
4981                         partitions formatted as logical volumes that span multiple physical disks. Use this value only with such
4982                         logical volumes.</para>
4983                       </listitem>
4984
4985                       <listitem>
4986                         <para>The string <emphasis role="bold">all</emphasis> followed immediately (with no intervening space) by an
4987                         integer from the range <emphasis role="bold">1</emphasis> to <emphasis role="bold">32</emphasis>, to run the
4988                         specified number of Salvager subprocesses in parallel on partitions formatted as logical volumes. Use this
4989                         value only with such logical volumes.</para>
4990                       </listitem>
4991                     </itemizedlist></para>
4992
4993                   <para>The BOS Server never starts more Salvager subprocesses than there are partitions, and always starts only one
4994                   process to salvage a single volume. If this argument is omitted, up to four Salvager subprocesses run in
4995                   parallel.</para>
4996                 </listitem>
4997               </varlistentry>
4998
4999               <varlistentry>
5000                 <term><emphasis role="bold">-tmpdir</emphasis></term>
5001
5002                 <listitem>
5003                   <para>Specifies the full pathname of a local disk directory to which the Salvager process writes temporary files
5004                   as it runs. By default, it writes them to the partition it is currently salvaging.</para>
5005                 </listitem>
5006               </varlistentry>
5007
5008               <varlistentry>
5009                 <term><emphasis role="bold">-orphans</emphasis></term>
5010
5011                 <listitem>
5012                   <para>Controls how the Salvager handles orphaned files and directories. Choose one of the following three values:
5013                   <variablelist>
5014                       <varlistentry>
5015                         <term><emphasis role="bold">ignore</emphasis></term>
5016
5017                         <listitem>
5018                           <para>Leaves the orphaned objects on the disk, but prints a message to the <emphasis
5019                           role="bold">/usr/afs/logs/SalvageLog</emphasis> file reporting how many orphans were found and the
5020                           approximate number of kilobytes they are consuming. This is the default if you omit the <emphasis
5021                           role="bold">-orphans</emphasis> argument.</para>
5022                         </listitem>
5023                       </varlistentry>
5024
5025                       <varlistentry>
5026                         <term><emphasis role="bold">remove</emphasis></term>
5027
5028                         <listitem>
5029                           <para>Removes the orphaned objects, and prints a message to the <emphasis
5030                           role="bold">/usr/afs/logs/SalvageLog</emphasis> file reporting how many orphans were removed and the
5031                           approximate number of kilobytes they were consuming.</para>
5032                         </listitem>
5033                       </varlistentry>
5034
5035                       <varlistentry>
5036                         <term><emphasis role="bold">attach</emphasis></term>
5037
5038                         <listitem>
5039                           <para>Attaches the orphaned objects by creating a reference to them in the vnode of the volume's root
5040                           directory. Since each object's actual name is now lost, the Salvager assigns each one a name of the
5041                           following form: <simplelist>
5042                               <member><emphasis role="bold">_ _ORPHANFILE_ _.</emphasis> index for files</member>
5043
5044                               <member><emphasis role="bold">_ _ORPHANDIR_ _.</emphasis> index for directories</member>
5045                             </simplelist></para>
5046
5047                           <para>where index is a two-digit number that uniquely identifies each object. The orphans are charged
5048                           against the volume's quota and appear in the output of the <emphasis role="bold">ls</emphasis> command
5049                           issued against the volume's root directory.</para>
5050                         </listitem>
5051                       </varlistentry>
5052                     </variablelist></para>
5053                 </listitem>
5054               </varlistentry>
5055             </variablelist></para>
5056         </listitem>
5057       </orderedlist>
5058     </sect2>
5059   </sect1>
5060
5061   <sect1 id="HDRWQ234">
5062     <title>Setting and Displaying Volume Quota and Current Size</title>
5063
5064     <indexterm>
5065       <primary>volume</primary>
5066
5067       <secondary>quota</secondary>
5068
5069       <see>volume quota</see>
5070     </indexterm>
5071
5072     <indexterm>
5073       <primary>default</primary>
5074
5075       <secondary>volume quota</secondary>
5076     </indexterm>
5077
5078     <para>Every AFS volume has an associated quota which limits the volume's size. The default quota for a newly created volume is
5079     5,000 kilobyte blocks (slightly less that 5 MB). When a volume reaches its quota, the File Server rejects attempts to create new
5080     files or directories in it. If an application is writing data into an existing file in a full volume, the File Server allows a
5081     defined overage (by default, 1 MB). (You can use the <emphasis role="bold">fileserver</emphasis> command's <emphasis
5082     role="bold">-spare</emphasis> or <emphasis role="bold">-pctspare</emphasis> argument to change the default overage; see the
5083     command's reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.)</para>
5084
5085     <para>To set a quota other than 5000 KB as you create a volume, include the <emphasis role="bold">-maxquota</emphasis> argument
5086     to the <emphasis role="bold">vos create</emphasis> command, as described in <link linkend="HDRWQ185">Creating Read/write
5087     Volumes</link>. To modify an existing volume's quota, issue either the <emphasis role="bold">fs setquota</emphasis> or the
5088     <emphasis role="bold">fs setvol</emphasis> command as described in the following instructions. Do not set an existing volume's
5089     quota lower than its current size.</para>
5090
5091     <para>In general, smaller volumes are easier to administer than larger ones. If you need to move volumes, say for load-balancing
5092     purposes, it is easier to find enough free space on other partitions for small volumes. Move operations complete more quickly
5093     for small volumes, reducing the potential for outages or other errors to interrupt the move. AFS supports a maximum volume size,
5094     which can vary for different AFS releases; see the <emphasis> OpenAFS Release Notes</emphasis> for the version you are using.
5095     Also, the size of a partition or logical places an absolute limit on volume size, because a volume cannot span multiple
5096     partitions or logical volumes.</para>
5097
5098     <para>It is generally safe to overpack partitions by putting more volumes on them than can actually fit if all the volumes reach
5099     their maximum quota. However, only experience determines to what degree overpacking works in your cell. It depends on what kind
5100     of quota you assign to volumes (particularly user volumes, which are more likely than system volumes to grow unpredictably) and
5101     how much information people generate and store in comparison to their quota.</para>
5102
5103     <para>There are several commands that display a volume's quota, as described in the following instructions. They differ in how
5104     much related information they produce.</para>
5105
5106     <sect2 id="Header_250">
5107       <title>To set quota for a single volume</title>
5108
5109       <indexterm>
5110         <primary>maximum volume quota</primary>
5111       </indexterm>
5112
5113       <indexterm>
5114         <primary>setting</primary>
5115
5116         <secondary>volume quota</secondary>
5117
5118         <tertiary>on single volume</tertiary>
5119       </indexterm>
5120
5121       <indexterm>
5122         <primary>volume quota</primary>
5123
5124         <secondary>setting</secondary>
5125
5126         <tertiary>on single volume</tertiary>
5127       </indexterm>
5128
5129       <indexterm>
5130         <primary>commands</primary>
5131
5132         <secondary>fs setquota</secondary>
5133       </indexterm>
5134
5135       <indexterm>
5136         <primary>fs commands</primary>
5137
5138         <secondary>setquota</secondary>
5139       </indexterm>
5140
5141       <orderedlist>
5142         <listitem>
5143           <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
5144           <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
5145           the members of the system:administrators group</link>. <programlisting>
5146    % <emphasis role="bold">pts membership system:administrators</emphasis>
5147 </programlisting></para>
5148         </listitem>
5149
5150         <listitem>
5151           <para>Issue the <emphasis role="bold">fs setquota</emphasis> command to set the volume's maximum quota. <programlisting>
5152    % <emphasis role="bold">fs setquota</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;] <emphasis role="bold">-max</emphasis> &lt;<replaceable>max quota in kbytes</replaceable>&gt;
5153 </programlisting></para>
5154
5155           <para>where <variablelist>
5156               <varlistentry>
5157                 <term><emphasis role="bold">sq</emphasis></term>
5158
5159                 <listitem>
5160                   <para>Is an acceptable alias for <emphasis role="bold">setquota</emphasis>.</para>
5161                 </listitem>
5162               </varlistentry>
5163
5164               <varlistentry>
5165                 <term><emphasis role="bold">dir/file path</emphasis></term>
5166
5167                 <listitem>
5168                   <para>Names a file or directory in the volume for which to set the indicated quota. Partial pathnames are
5169                   interpreted relative to the current working directory, which is the default if you omit this argument.</para>
5170
5171                   <para>Specify the read/write path to the file or directory, to avoid the failure that results when you attempt to
5172                   change a read-only volume. By convention, you indicate the read/write path by placing a period before the cell
5173                   name at the pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). For further
5174                   discussion of the concept of read/write and read-only paths through the filespace, see <link
5175                   linkend="HDRWQ209">The Rules of Mount Point Traversal</link>.</para>
5176                 </listitem>
5177               </varlistentry>
5178
5179               <varlistentry>
5180                 <term><emphasis role="bold">max quota in kbytes</emphasis></term>
5181
5182                 <listitem>
5183                   <para>Sets the volume's quota, expressed in kilobyte blocks ( <emphasis role="bold">1024</emphasis> equals a
5184                   megabyte). A value of <emphasis role="bold">0</emphasis> grants an unlimited quota, but the size of the partition
5185                   imposes an absolute limit. You must include the <emphasis role="bold">-max</emphasis> switch if omitting the
5186                   dir/file path argument (to set the quota on the volume that houses the current working directory).</para>
5187                 </listitem>
5188               </varlistentry>
5189             </variablelist></para>
5190         </listitem>
5191       </orderedlist>
5192     </sect2>
5193
5194     <sect2 id="Header_251">
5195       <title>To set maximum quota on one or more volumes</title>
5196
5197       <indexterm>
5198         <primary>setting</primary>
5199
5200         <secondary>volume quota</secondary>
5201
5202         <tertiary>on multiple volumes</tertiary>
5203       </indexterm>
5204
5205       <indexterm>
5206         <primary>volume quota</primary>
5207
5208         <secondary>setting</secondary>
5209
5210         <tertiary>on multiple volumes</tertiary>
5211       </indexterm>
5212
5213       <indexterm>
5214         <primary>commands</primary>
5215
5216         <secondary>fs setvol</secondary>
5217       </indexterm>
5218
5219       <indexterm>
5220         <primary>fs commands</primary>
5221
5222         <secondary>setvol</secondary>
5223       </indexterm>
5224
5225       <orderedlist>
5226         <listitem>
5227           <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
5228           <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
5229           the members of the system:administrators group</link>. <programlisting>
5230    % <emphasis role="bold">pts membership system:administrators</emphasis>
5231 </programlisting></para>
5232         </listitem>
5233
5234         <listitem>
5235           <para>Issue the <emphasis role="bold">fs setvol</emphasis> command to set the quota on one or more volumes.
5236           <programlisting>
5237    % <emphasis role="bold">fs setvol</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;+] <emphasis role="bold">-max</emphasis> &lt;<replaceable>disk space quota in 1K units</replaceable>&gt;
5238 </programlisting></para>
5239
5240           <para>where <variablelist>
5241               <varlistentry>
5242                 <term><emphasis role="bold">sv</emphasis></term>
5243
5244                 <listitem>
5245                   <para>Is an acceptable alias for <emphasis role="bold">setvol</emphasis>.</para>
5246                 </listitem>
5247               </varlistentry>
5248
5249               <varlistentry>
5250                 <term><emphasis role="bold">dir/file path</emphasis></term>
5251
5252                 <listitem>
5253                   <para>Names one file or directory that resides in each volume for which to set the indicated quota. Partial
5254                   pathnames are interpreted relative to the current working directory, which is the default if you omit this
5255                   argument.</para>
5256                 </listitem>
5257               </varlistentry>
5258
5259               <varlistentry>
5260                 <term><emphasis role="bold">disk space quota in 1K units</emphasis></term>
5261
5262                 <listitem>
5263                   <para>Sets the maximum quota on each volume, expressed in kilobytes blocks ( <emphasis role="bold">1024</emphasis>
5264                   equals a megabyte). A value of <emphasis role="bold">0</emphasis> grants an unlimited quota, but the size of the
5265                   partition does impose an absolute limit.</para>
5266                 </listitem>
5267               </varlistentry>
5268             </variablelist></para>
5269         </listitem>
5270       </orderedlist>
5271
5272       <indexterm>
5273         <primary>commands</primary>
5274
5275         <secondary>fs quota</secondary>
5276       </indexterm>
5277
5278       <indexterm>
5279         <primary>fs commands</primary>
5280
5281         <secondary>quota</secondary>
5282       </indexterm>
5283
5284       <indexterm>
5285         <primary>displaying</primary>
5286
5287         <secondary>volume quota</secondary>
5288
5289         <tertiary>percent used</tertiary>
5290       </indexterm>
5291
5292       <indexterm>
5293         <primary>volume quota</primary>
5294
5295         <secondary>displaying</secondary>
5296
5297         <tertiary>percent used</tertiary>
5298       </indexterm>
5299     </sect2>
5300
5301     <sect2 id="Header_252">
5302       <title>To display percent quota used</title>
5303
5304       <orderedlist>
5305         <listitem>
5306           <para>Issue the <emphasis role="bold">fs quota</emphasis> command. <programlisting>
5307    % <emphasis role="bold">fs quota</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;+]
5308 </programlisting></para>
5309
5310           <para>where <variablelist>
5311               <varlistentry>
5312                 <term><emphasis role="bold">q</emphasis></term>
5313
5314                 <listitem>
5315                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">quota</emphasis>.</para>
5316                 </listitem>
5317               </varlistentry>
5318
5319               <varlistentry>
5320                 <term><emphasis role="bold">dir/file path</emphasis></term>
5321
5322                 <listitem>
5323                   <para>Names a directory or file in each volume for which to display percent quota used. Partial pathnames are
5324                   interpreted relative to the current working directory, which is the default if you omit this argument.</para>
5325                 </listitem>
5326               </varlistentry>
5327             </variablelist></para>
5328         </listitem>
5329       </orderedlist>
5330
5331       <para>The following example illustrates the output produced by this command:</para>
5332
5333       <programlisting>
5334    % <emphasis role="bold">fs quota /afs/abc.com/usr/terry</emphasis>
5335    34% of quota used.
5336 </programlisting>
5337
5338       <indexterm>
5339         <primary>commands</primary>
5340
5341         <secondary>fs listquota</secondary>
5342       </indexterm>
5343
5344       <indexterm>
5345         <primary>fs commands</primary>
5346
5347         <secondary>listquota</secondary>
5348       </indexterm>
5349
5350       <indexterm>
5351         <primary>displaying</primary>
5352
5353         <secondary>volume quota</secondary>
5354
5355         <tertiary>with volume size</tertiary>
5356       </indexterm>
5357
5358       <indexterm>
5359         <primary>volume quota</primary>
5360
5361         <secondary>displaying</secondary>
5362
5363         <tertiary>with volume size</tertiary>
5364       </indexterm>
5365
5366       <indexterm>
5367         <primary>displaying</primary>
5368
5369         <secondary>volume size</secondary>
5370       </indexterm>
5371
5372       <indexterm>
5373         <primary>volume</primary>
5374
5375         <secondary>size, displaying</secondary>
5376       </indexterm>
5377     </sect2>
5378
5379     <sect2 id="Header_253">
5380       <title>To display quota, current size, and other information</title>
5381
5382       <orderedlist>
5383         <listitem>
5384           <para>Issue the <emphasis role="bold">fs listquota</emphasis> command. <programlisting>
5385    % <emphasis role="bold">fs listquota</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;+]
5386 </programlisting></para>
5387
5388           <para>where <variablelist>
5389               <varlistentry>
5390                 <term><emphasis role="bold">lq</emphasis></term>
5391
5392                 <listitem>
5393                   <para>Is an alias for <emphasis role="bold">listquota</emphasis>.</para>
5394                 </listitem>
5395               </varlistentry>
5396
5397               <varlistentry>
5398                 <term><emphasis role="bold">dir/file path</emphasis></term>
5399
5400                 <listitem>
5401                   <para>Names a directory or file in each volume for which to display quota along with volume name and current space
5402                   usage. Partial pathnames are interpreted relative to the current working directory, which is the default if you
5403                   omit this argument.</para>
5404                 </listitem>
5405               </varlistentry>
5406             </variablelist></para>
5407         </listitem>
5408       </orderedlist>
5409
5410       <para>As illustrated in the following example, the output reports the volume's name, its quota and current size (both in
5411       kilobyte units), the percent quota used, and the percentage of space on the volume's host partition that is used.</para>
5412
5413       <programlisting>
5414    % <emphasis role="bold">fs listquota /afs/abc.com/usr/terry</emphasis>
5415    Volume Name     Quota    Used    % Used   Partition
5416    user.terry      15000    5071       34%         86%
5417 </programlisting>
5418
5419       <indexterm>
5420         <primary>displaying</primary>
5421
5422         <secondary>volume quota</secondary>
5423
5424         <tertiary>with volume &amp; partition info</tertiary>
5425       </indexterm>
5426
5427       <indexterm>
5428         <primary>displaying</primary>
5429
5430         <secondary>volume size</secondary>
5431       </indexterm>
5432
5433       <indexterm>
5434         <primary>volume quota</primary>
5435
5436         <secondary>displaying</secondary>
5437
5438         <tertiary>with volume &amp;partition info</tertiary>
5439       </indexterm>
5440
5441       <indexterm>
5442         <primary>displaying</primary>
5443
5444         <secondary>disk partition size</secondary>
5445       </indexterm>
5446
5447       <indexterm>
5448         <primary>disk partition</primary>
5449
5450         <secondary>displaying size of single</secondary>
5451       </indexterm>
5452
5453       <indexterm>
5454         <primary>commands</primary>
5455
5456         <secondary>fs examine</secondary>
5457       </indexterm>
5458
5459       <indexterm>
5460         <primary>fs commands</primary>
5461
5462         <secondary>examine</secondary>
5463       </indexterm>
5464     </sect2>
5465
5466     <sect2 id="Header_254">
5467       <title>To display quota, current size, and more partition information</title>
5468
5469       <orderedlist>
5470         <listitem>
5471           <para>Issue the <emphasis role="bold">fs examine</emphasis> command. <programlisting>
5472    % <emphasis role="bold">fs examine</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;+]
5473 </programlisting></para>
5474
5475           <para>where <variablelist>
5476               <varlistentry>
5477                 <term><emphasis role="bold">exa</emphasis></term>
5478
5479                 <listitem>
5480                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
5481                 </listitem>
5482               </varlistentry>
5483
5484               <varlistentry>
5485                 <term><emphasis role="bold">dir/file path</emphasis></term>
5486
5487                 <listitem>
5488                   <para>Names a directory or file in each volume for which to display quota information and information about the
5489                   host partition. Partial pathnames are interpreted relative to the current working directory, which is the default
5490                   if you omit this argument.</para>
5491                 </listitem>
5492               </varlistentry>
5493             </variablelist></para>
5494         </listitem>
5495       </orderedlist>
5496
5497       <para>As illustrated in the following example, the output displays the volume's volume ID number and name, its quota and
5498       current size (both in kilobyte units), and the free and total number of kilobyte blocks on the volume's host partition.</para>
5499
5500       <programlisting>
5501    % <emphasis role="bold">fs examine /afs/abc.com/usr/terry</emphasis>
5502    Volume status for vid = 50489902 named user.terry
5503    Current maximum quota is 15000
5504    Current blocks used are 5073
5505    The partition has 46383 blocks available out of 333305
5506 </programlisting>
5507
5508       <note>
5509         <para>The partition-related statistics in this command's output do not always agree with the corresponding values in the
5510         output of the standard UNIX <emphasis role="bold">df</emphasis> command. The statistics reported by this command can be up
5511         to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency. Also, on
5512         some operating systems, the <emphasis role="bold">df</emphasis> command's report of partition size includes reserved space
5513         not included in this command's calculation, and so is likely to be about 10% larger.</para>
5514       </note>
5515     </sect2>
5516   </sect1>
5517
5518   <sect1 id="HDRWQ235">
5519     <title>Removing Volumes and their Mount Points</title>
5520
5521     <indexterm>
5522       <primary>volume</primary>
5523
5524       <secondary>removing</secondary>
5525
5526       <tertiary>basic instructions</tertiary>
5527     </indexterm>
5528
5529     <indexterm>
5530       <primary>removing</primary>
5531
5532       <secondary>mount point</secondary>
5533     </indexterm>
5534
5535     <indexterm>
5536       <primary>unmounting</primary>
5537
5538       <secondary>volume</secondary>
5539     </indexterm>
5540
5541     <indexterm>
5542       <primary>mount point</primary>
5543
5544       <secondary>removing</secondary>
5545     </indexterm>
5546
5547     <indexterm>
5548       <primary>removing</primary>
5549
5550       <secondary>volume</secondary>
5551     </indexterm>
5552
5553     <para>To remove a volume from its site and its record from the VLDB, use the <emphasis role="bold">vos remove</emphasis>
5554     command. Use it to remove any of the three types of volumes; the effect depends on the type. <itemizedlist>
5555         <listitem>
5556           <para><indexterm>
5557               <primary>read/write volume</primary>
5558
5559               <secondary>removing</secondary>
5560
5561               <tertiary>effect of</tertiary>
5562             </indexterm> <indexterm>
5563               <primary>backup volume</primary>
5564
5565               <secondary>removed by read/write removal</secondary>
5566             </indexterm> If you indicate the read/write volume by specifying the volume's base name without a <emphasis
5567           role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis> extension, the command removes both the
5568           read/write and associated backup volume from the partition that houses them. You do not need to provide the <emphasis
5569           role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, because there can be only one
5570           read/write site. The site information is also removed from the VLDB entry, and the site count (reported by the <emphasis
5571           role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvldb</emphasis> commands as <computeroutput>number of
5572           sites</computeroutput>) decrements by one. The read/write and backup volume ID numbers no longer appear in the output from
5573           the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvldb</emphasis> commands, but they are
5574           preserved internally. Read-only sites, if any, are not affected, but cannot be changed unless a read/write site is again
5575           defined. The entire VLDB entry is removed if there are no read-only sites.</para>
5576
5577           <para>If there are no read-only copies left, it is best to remove the volume's mount point to prevent attempts to access
5578           the volume's contents. Do not remove the mount point if copies of the read-only volume remain.</para>
5579         </listitem>
5580
5581         <listitem>
5582           <para>If you indicate a read-only volume by including the <emphasis role="bold">.readonly</emphasis> extension on its
5583           name, it is removed from the partition that houses it, and the corresponding site information is removed from the VLDB
5584           entry. The site count reported by the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos
5585           listvldb</emphasis> commands as <computeroutput>number of sites</computeroutput> decrements by one for each volume you
5586           remove.</para>
5587
5588           <indexterm>
5589             <primary>read-only volume</primary>
5590
5591             <secondary>removing</secondary>
5592
5593             <tertiary>effect of</tertiary>
5594           </indexterm>
5595
5596           <para>If there is more than one read-only site, you must include the <emphasis role="bold">-server</emphasis> argument
5597           (and optionally <emphasis role="bold">-partition</emphasis> argument) to specify the site from which to remove the volume.
5598           If there is only one read-only site, the volume name is sufficient; if no read/write volume exists in this case, the
5599           entire VLDB entry is removed.</para>
5600
5601           <para>It is not generally appropriate to remove the volume's mount point when removing a read-only volume, especially if
5602           the read/write version of the volume still exists. If the read/write version no longer exists, remove the mount point as
5603           described in Step <link linkend="LIWQ239">5</link>of <link linkend="HDRWQ236">To remove a volume and unmount
5604           it</link>.</para>
5605         </listitem>
5606
5607         <listitem>
5608           <para>If you indicate a backup volume by including the <emphasis role="bold">.backup</emphasis> extension on its name, it
5609           is removed from the partition that houses it and its site information is removed from the VLDB entry. You do not need to
5610           provide the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments, because
5611           there can be only one backup site. The backup volume ID number no longer appears in the output from the <emphasis
5612           role="bold">vos examine</emphasis> or <emphasis role="bold">vos listvldb</emphasis> command, but is preserved
5613           internally.</para>
5614
5615           <para>In the standard configuration, there is a separate mount point for the backup version of a user volume. Remember to
5616           remove the mount point to prevent attempt to access the nonexistent volume's contents.</para>
5617         </listitem>
5618       </itemizedlist></para>
5619
5620     <sect2 id="Header_256">
5621       <title>Other Removal Commands</title>
5622
5623       <indexterm>
5624         <primary>volume</primary>
5625
5626         <secondary>removing</secondary>
5627
5628         <tertiary>alternate commands</tertiary>
5629       </indexterm>
5630
5631       <para>The <emphasis role="bold">vos remove</emphasis> command is almost always the appropriate way to remove a volume, because
5632       it automatically removes a volume's VLDB entry and both the volume header and all data from the partition. If either the VLDB
5633       entry or volume header does not exist, it is sometimes necessary to use other commands that remove only the remaining element.
5634       Do not use these commands in the normal case when both the VLDB entry and the volume header exist, because by definition they
5635       create discrepancies between them. For details on the commands' syntax, see their reference pages in the <emphasis> OpenAFS
5636       Administration Reference</emphasis>.</para>
5637
5638       <indexterm>
5639         <primary>commands</primary>
5640
5641         <secondary>vos zap</secondary>
5642       </indexterm>
5643
5644       <indexterm>
5645         <primary>vos commands</primary>
5646
5647         <secondary>zap</secondary>
5648       </indexterm>
5649
5650       <para>The <emphasis role="bold">vos zap</emphasis> command removes a volume from its site by removing the volume header and
5651       volume data for which a VLDB entry no longer exists. You can tell a VLDB entry is missing if the <emphasis role="bold">vos
5652       listvol</emphasis> command displays the volume header but the <emphasis role="bold">vos examine</emphasis> or <emphasis
5653       role="bold">vos listvldb</emphasis> command cannot locate the VLDB entry. You must run this command to correct the
5654       discrepancy, because the <emphasis role="bold">vos syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis>
5655       commands never remove volume headers.</para>
5656
5657       <indexterm>
5658         <primary>commands</primary>
5659
5660         <secondary>vos remsite</secondary>
5661       </indexterm>
5662
5663       <indexterm>
5664         <primary>vos commands</primary>
5665
5666         <secondary>remsite</secondary>
5667       </indexterm>
5668
5669       <para>The <emphasis role="bold">vos remsite</emphasis> command removes a read-only site definition from the VLDB without
5670       affecting the volume on the file server machine. Use this command when you have mistakenly issued the <emphasis
5671       role="bold">vos addsite</emphasis> command to define a read-only site, but have not yet issued the <emphasis role="bold">vos
5672       release</emphasis> command to release the volume to the site. If you have actually released a volume to the site, use the
5673       <emphasis role="bold">vos remove</emphasis> command instead.</para>
5674
5675       <indexterm>
5676         <primary>commands</primary>
5677
5678         <secondary>vos delentry</secondary>
5679       </indexterm>
5680
5681       <indexterm>
5682         <primary>vos commands</primary>
5683
5684         <secondary>delentry</secondary>
5685       </indexterm>
5686
5687       <para>The <emphasis role="bold">vos delentry</emphasis> command removes the entire VLDB entry that mentions the volume you
5688       specify. If versions of the volume actually exist on file server machines, they are not affected. This command is useful if
5689       you know for certain that a volume removal was not recorded in the VLDB (perhaps you used the <emphasis role="bold">vos
5690       zap</emphasis> command during an emergency), and do not want to take the time to resynchronize the entire VLDB with the
5691       <emphasis role="bold">vos syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis> commands.</para>
5692     </sect2>
5693
5694     <sect2 id="HDRWQ236">
5695       <title>To remove a volume and unmount it</title>
5696
5697       <indexterm>
5698         <primary>read/write volume</primary>
5699
5700         <secondary>removing</secondary>
5701
5702         <tertiary>instructions</tertiary>
5703       </indexterm>
5704
5705       <orderedlist>
5706         <listitem>
5707           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
5708           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
5709           display the users in the UserList file</link>. <programlisting>
5710    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
5711 </programlisting></para>
5712         </listitem>
5713
5714         <listitem>
5715           <para>If removing the volume's mount point, verify that you have the <emphasis role="bold">d</emphasis>( <emphasis
5716           role="bold">delete</emphasis>) permission on its parent directory's ACL. If necessary, issue the <emphasis role="bold">fs
5717           listacl</emphasis> command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
5718    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
5719 </programlisting></para>
5720
5721           <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
5722           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
5723           role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
5724           role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
5725         </listitem>
5726
5727         <listitem id="LIWQ237">
5728
5729           <para><emphasis role="bold">(Optional)</emphasis> Dump the volume to a file or to tape, in case you want to restore it
5730           later. To copy the volume's contents to a file, use the <emphasis role="bold">vos dump</emphasis> command as instructed in
5731           <link linkend="HDRWQ240">Dumping and Restoring Volumes</link>. You can then copy the file to tape using a third-party
5732           backup utility or an archiving utility such as the UNIX <emphasis role="bold">tar</emphasis> command.</para>
5733
5734           <para>Alternatively, use the AFS Backup System to create a tape copy. In this case, it can be convenient to create a
5735           temporary volume set that includes only the volume of interest. Temporary volume sets are not recorded in the Backup
5736           Database, and so do not clutter database with records for volume sets that you use only once. For instructions, see <link
5737           linkend="HDRWQ301">To create a dump</link>.</para>
5738
5739           <indexterm>
5740             <primary>commands</primary>
5741
5742             <secondary>vos remove</secondary>
5743
5744             <tertiary>basic instructions</tertiary>
5745           </indexterm>
5746
5747           <indexterm>
5748             <primary>vos commands</primary>
5749
5750             <secondary>remove</secondary>
5751
5752             <tertiary>basic instructions</tertiary>
5753           </indexterm>
5754         </listitem>
5755
5756         <listitem id="LIWQ238">
5757           <para>Issue the <emphasis role="bold">vos remove</emphasis> command to remove the volume. If
5758           removing a read-only volume from multiple sites, repeat the command for each one. <programlisting>
5759    % <emphasis role="bold">vos remove</emphasis> [<emphasis role="bold">-server</emphasis> machine name&gt;] [<emphasis role="bold">-partition</emphasis> &lt;<replaceable>partition name</replaceable>&gt;] \
5760                <emphasis role="bold">-id</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
5761 </programlisting></para>
5762
5763           <para>where <variablelist>
5764               <varlistentry>
5765                 <term><emphasis role="bold">remo</emphasis></term>
5766
5767                 <listitem>
5768                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">remove</emphasis>.</para>
5769                 </listitem>
5770               </varlistentry>
5771
5772               <varlistentry>
5773                 <term><emphasis role="bold">-server</emphasis></term>
5774
5775                 <listitem>
5776                   <para>Specifies the file server machine on which the volume resides. It is necessary only when the <emphasis
5777                   role="bold">-id</emphasis> argument names a read-only volume that exists at multiple sites.</para>
5778                 </listitem>
5779               </varlistentry>
5780
5781               <varlistentry>
5782                 <term><emphasis role="bold">-partition</emphasis></term>
5783
5784                 <listitem>
5785                   <para>Specifies the partition on machine name where the volume resides. It is necessary only when the <emphasis
5786                   role="bold">-id</emphasis> argument names a read-only volume that exists at multiple sites. Provide the <emphasis
5787                   role="bold">-server</emphasis> argument along with this one.</para>
5788                 </listitem>
5789               </varlistentry>
5790
5791               <varlistentry>
5792                 <term><emphasis role="bold">-id</emphasis></term>
5793
5794                 <listitem>
5795                   <para>Identifies the volume to remove, either by its complete name or volume ID number. If identifying a read-only
5796                   or backup volume by name, include the appropriate extension ( <emphasis role="bold">.readonly</emphasis> or
5797                   <emphasis role="bold">.backup</emphasis>).</para>
5798                 </listitem>
5799               </varlistentry>
5800             </variablelist></para>
5801
5802           <indexterm>
5803             <primary>commands</primary>
5804
5805             <secondary>fs rmmount</secondary>
5806           </indexterm>
5807
5808           <indexterm>
5809             <primary>fs commands</primary>
5810
5811             <secondary>rmmount</secondary>
5812
5813             <tertiary>when removing volume</tertiary>
5814           </indexterm>
5815         </listitem>
5816
5817         <listitem id="LIWQ239">
5818           <para>If you are removing the last existing version of the volume, issue the <emphasis
5819           role="bold">fs rmmount</emphasis> command remove the corresponding mount point. Complete instructions appear in <link
5820           linkend="HDRWQ236">To remove a volume and unmount it</link>.</para>
5821
5822           <para>If you are removing a backup volume that is mounted in the conventional way (at a subdirectory of its read/write
5823           volume's root directory), then removing the source volume's mount point in this step is sufficient to remove the backup
5824           volume's mount point. If you mounted the backup at a completely separate directory, you need to repeat this step for the
5825           backup volume's mount point.</para>
5826
5827           <programlisting>
5828    % <emphasis role="bold">fs rmmount</emphasis> &lt;<replaceable>directory</replaceable>&gt;
5829 </programlisting>
5830         </listitem>
5831
5832         <listitem>
5833           <para><emphasis role="bold">(Optional)</emphasis> If you created a dump file in Step <link linkend="LIWQ237">3</link>,
5834           transfer it to tape. The preferred method is to use the AFS Backup System, which is described in <link
5835           linkend="HDRWQ248">Configuring the AFS Backup System</link>and <link linkend="HDRWQ283">Backing Up and Restoring AFS
5836           Data</link>.</para>
5837         </listitem>
5838       </orderedlist>
5839     </sect2>
5840   </sect1>
5841
5842   <sect1 id="HDRWQ240">
5843     <title>Dumping and Restoring Volumes</title>
5844
5845     <indexterm>
5846       <primary>dumping</primary>
5847
5848       <secondary>volumes</secondary>
5849
5850       <tertiary>without using AFS Backup System</tertiary>
5851     </indexterm>
5852
5853     <indexterm>
5854       <primary>volume</primary>
5855
5856       <secondary>dumping without AFS Backup System</secondary>
5857     </indexterm>
5858
5859     <para><emphasis>Dumping</emphasis> a volume with the <emphasis role="bold">vos dump</emphasis> command converts its contents
5860     into ASCII format and writes them to the file you specify. The <emphasis role="bold">vos restore</emphasis> command places a
5861     dump file's contents into a volume after converting them into the volume format appropriate for the indicated file server
5862     machine.</para>
5863
5864     <sect2 id="Header_259">
5865       <title>About Dumping Volumes</title>
5866
5867       <indexterm>
5868         <primary>read/write volume</primary>
5869
5870         <secondary>dumping</secondary>
5871       </indexterm>
5872
5873       <indexterm>
5874         <primary>read-only volume</primary>
5875
5876         <secondary>dumping</secondary>
5877       </indexterm>
5878
5879       <indexterm>
5880         <primary>backup volume</primary>
5881
5882         <secondary>dumping</secondary>
5883       </indexterm>
5884
5885       <indexterm>
5886         <primary>availability of data</primary>
5887
5888         <secondary>interrupted by dumping</secondary>
5889       </indexterm>
5890
5891       <indexterm>
5892         <primary>data</primary>
5893
5894         <secondary>availability interrupted by dumping</secondary>
5895       </indexterm>
5896
5897       <indexterm>
5898         <primary>dumping</primary>
5899
5900         <secondary>volumes</secondary>
5901
5902         <tertiary>reasons</tertiary>
5903       </indexterm>
5904
5905       <para>Dumping a volume can be useful in several situations, including the following: <itemizedlist>
5906           <listitem>
5907             <para>You want to back it up to tape, perhaps by using a third-party backup utility. To facilitate this type of backup
5908             operation, the <emphasis role="bold">vos dump</emphasis> command can write to a named pipe. To learn about using the AFS
5909             Backup System instead, see <link linkend="HDRWQ248">Configuring the AFS Backup System</link>and <link
5910             linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
5911           </listitem>
5912
5913           <listitem>
5914             <para>You are removing the volume from your cell (perhaps because its owner is leaving your cell). The <emphasis
5915             role="bold">vos dump</emphasis> command enables you to create a copy for safekeeping without incurring the overhead of
5916             the Backup System. For complete instructions on removing a volume, see <link linkend="HDRWQ235">Removing Volumes and
5917             their Mount Points</link>.</para>
5918           </listitem>
5919
5920           <listitem>
5921             <para>You want to create a copy of the volume for safekeeping on a non-AFS server partition, perhaps while you move the
5922             actual volume to another machine or perform maintenance tasks on the partition that houses the volume.</para>
5923           </listitem>
5924
5925           <listitem>
5926             <para>You need to replace a corrupted read/write volume. If an uncorrupted read-only or backup version of the volume
5927             exists, dump it and restore the data into the read/write volume, overwriting the corrupted contents.</para>
5928           </listitem>
5929
5930           <listitem>
5931             <para>You want to copy or transfer the contents of the volume to another cell. You cannot use the <emphasis
5932             role="bold">vos move</emphasis> command, because AFS supports volume moves only between file server machines that belong
5933             to the same cell.</para>
5934           </listitem>
5935
5936           <listitem>
5937             <para>You want to have another read/write copy of the volume's contents. The second volume must have a different name
5938             than the original one. If you want the contents of the two volumes to remain identical, you must update them both
5939             manually. AFS provides no facility for keeping read/write volumes synchronized in this way.</para>
5940           </listitem>
5941
5942           <listitem>
5943             <para>You want a copy of only the files and directories in the volume with modification time stamps after a certain
5944             date. The <emphasis role="bold">vos dump</emphasis> command can create an incremental dump file as described in Step
5945             <link linkend="LIWQ241">3</link>of the following instructions.</para>
5946           </listitem>
5947         </itemizedlist></para>
5948
5949       <indexterm>
5950         <primary>full dump</primary>
5951
5952         <secondary>creating using vos command</secondary>
5953       </indexterm>
5954
5955       <indexterm>
5956         <primary>incremental dump</primary>
5957
5958         <secondary>creating using vos command</secondary>
5959       </indexterm>
5960
5961       <indexterm>
5962         <primary>dumping</primary>
5963
5964         <secondary>volumes</secondary>
5965
5966         <tertiary>using vos command</tertiary>
5967       </indexterm>
5968
5969       <para>You can use the <emphasis role="bold">vos dump</emphasis> command to create a <emphasis>full dump</emphasis>, which
5970       contains the complete contents of the volume at the time you issue the command, or an <emphasis>incremental dump</emphasis>,
5971       which contains only those files and directories with modification timestamps (as displayed by the <emphasis role="bold">ls
5972       -l</emphasis> command) that are later than a date and time you specify. See Step <link linkend="LIWQ241">3</link>of the
5973       following instructions.</para>
5974
5975       <para>Dumping a volume does not change its VLDB entry or permanently affect its status on the file server machine, but the
5976       volume's contents are inaccessible during the dump operation. To avoid interrupting access to the volume, it is generally best
5977       to dump the volume's backup version, just after using the <emphasis role="bold">vos backup</emphasis> or <emphasis
5978       role="bold">vos backupsys</emphasis> command to create a new backup version.</para>
5979
5980       <para>If you do not provide a filename into which to write the dump, the <emphasis role="bold">vos dump</emphasis> command
5981       directs the output to the standard output stream. You can pipe it directly to the <emphasis role="bold">vos restore</emphasis>
5982       command if you wish.</para>
5983
5984       <para>Because a volume dump file is in ASCII format, you can read its contents using a text editor or a command such as the
5985       <emphasis role="bold">cat</emphasis> command. However, dump files sometimes contain special characters that do not have
5986       alphanumeric correlates, which can cause problems for some display programs.</para>
5987
5988       <para>By default, the <emphasis role="bold">vos</emphasis> command interpreter consults the Volume Location Database (VLDB) to
5989       learn the volume's location, so the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis>
5990       arguments are not required. If the <emphasis role="bold">-id</emphasis> argument identifies a read-only volume that resides at
5991       multiple sites, then the command dumps the version from just one of them (normally, the one listed first in the volume's VLDB
5992       entry as reported by the <emphasis role="bold">vos examine</emphasis> or <emphasis role="bold">vos listvldb</emphasis>
5993       command). To dump the read-only volume from a particular site, use the <emphasis role="bold">-server</emphasis> and <emphasis
5994       role="bold">-partition</emphasis> arguments to specify the site. To bypass the VLDB lookup entirely, provide a volume ID
5995       number (rather than a volume name) as the value for the <emphasis role="bold">-id</emphasis> argument, along with the
5996       <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments. This makes it possible to
5997       dump a volume for which there is no VLDB entry.</para>
5998
5999       <indexterm>
6000         <primary>commands</primary>
6001
6002         <secondary>vos dump</secondary>
6003       </indexterm>
6004
6005       <indexterm>
6006         <primary>vos commands</primary>
6007
6008         <secondary>dump</secondary>
6009       </indexterm>
6010     </sect2>
6011
6012     <sect2 id="Header_260">
6013       <title>To dump a volume</title>
6014
6015       <orderedlist>
6016         <listitem>
6017           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
6018           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
6019           display the users in the UserList file</link>. <programlisting>
6020    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
6021 </programlisting></para>
6022         </listitem>
6023
6024         <listitem>
6025           <para>Verify that you have the permissions necessary to create the dump file. If placing it in AFS, you must have the
6026           <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) permission on the ACL of the file's
6027           directory. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link
6028           linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
6029    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
6030 </programlisting></para>
6031
6032           <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
6033           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
6034           role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
6035           role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
6036         </listitem>
6037
6038         <listitem id="LIWQ241">
6039           <para>Issue the <emphasis role="bold">vos dump</emphasis> command to dump the volume.
6040           <programlisting>
6041    % <emphasis role="bold">vos dump -id</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt; [<emphasis role="bold">-time</emphasis> &lt;<replaceable>dump from time</replaceable>&gt;] [<emphasis
6042                 role="bold">-file</emphasis> &lt;<replaceable>arg</replaceable>&gt;] [<emphasis role="bold">-server</emphasis> &lt;<replaceable>server</replaceable>&gt;] [<emphasis
6043                 role="bold">-partition</emphasis> &lt;<replaceable>partition</replaceable>&gt;]
6044 </programlisting></para>
6045
6046           <para>where <variablelist>
6047               <varlistentry>
6048                 <term><emphasis role="bold">-id</emphasis></term>
6049
6050                 <listitem>
6051                   <para>Identifies the volume to be dumped by its complete name or volume ID number. If you want to dump the
6052                   read-only or backup version, specify its volume ID number or add the appropriate extension ( <emphasis
6053                   role="bold">.readonly</emphasis> or <emphasis role="bold">.backup</emphasis>) to the name.</para>
6054
6055                   <para>To bypass the normal VLDB lookup of the volume's location, provide the volume ID number and combine this
6056                   argument with the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis>
6057                   arguments.</para>
6058                 </listitem>
6059               </varlistentry>
6060
6061               <varlistentry>
6062                 <term><emphasis role="bold">-time</emphasis></term>
6063
6064                 <listitem>
6065                   <para>Specifies whether the dump is full or incremental. Omit this argument to create a full dump, or provide one
6066                   of three acceptable values: <itemizedlist>
6067                       <listitem>
6068                         <para>The value <emphasis role="bold">0</emphasis>(zero) to create a full dump.</para>
6069                       </listitem>
6070
6071                       <listitem>
6072                         <para>A date in the format mm <emphasis role="bold">/</emphasis> dd <emphasis role="bold">/</emphasis> yyyy
6073                         (month, day and year) to create an incremental dump that includes only files and directories with
6074                         modification timestamps later than midnight (12:00 a.m.) on the indicated date. Valid values for the year
6075                         range from <emphasis role="bold">1970</emphasis> to <emphasis role="bold">2037</emphasis>; higher values are
6076                         not valid because the latest possible date in the standard UNIX representation is in 2038. The command
6077                         interpreter automatically reduces later dates to the maximum value. An example is <emphasis
6078                         role="bold">01/13/1999</emphasis>.</para>
6079                       </listitem>
6080
6081                       <listitem>
6082                         <para>A date and time in the format <emphasis role="bold">"</emphasis> mm <emphasis role="bold">/</emphasis>
6083                         dd <emphasis role="bold">/</emphasis> yyyy hh <emphasis role="bold">:</emphasis> MM <emphasis
6084                         role="bold">"</emphasis> to create an incremental dump that includes only files and directories with
6085                         modification timestamps later than the specified date and time. The date format is the same as for a date
6086                         alone. Express the time as hours and minutes (hh:MM) in 24-hour format (for example, <emphasis
6087                         role="bold">20:30</emphasis> is 8:30 p.m.). Surround the entire expression with double quotes (" ") because
6088                         it contains a space. An example is <emphasis role="bold">"01/13/1999 22:30"</emphasis>.</para>
6089                       </listitem>
6090                     </itemizedlist></para>
6091                 </listitem>
6092               </varlistentry>
6093
6094               <varlistentry>
6095                 <term><emphasis role="bold">-file</emphasis></term>
6096
6097                 <listitem>
6098                   <para>Specifies the pathname of the file to which to write the dump. The file can be in AFS, but not in the volume
6099                   being dumped. A partial pathname is interpreted relative to the current working directory. Omit this argument to
6100                   direct the dump to the standard output stream.</para>
6101                 </listitem>
6102               </varlistentry>
6103
6104               <varlistentry>
6105                 <term><emphasis role="bold">-server</emphasis></term>
6106
6107                 <listitem>
6108                   <para>Specifies the file server machine on which the volume resides. Provide the <emphasis
6109                   role="bold">-partition</emphasis> argument along with this one.</para>
6110                 </listitem>
6111               </varlistentry>
6112
6113               <varlistentry>
6114                 <term><emphasis role="bold">-partition</emphasis></term>
6115
6116                 <listitem>
6117                   <para>Specifies the partition on which the volume resides. Provide the <emphasis role="bold">-server</emphasis>
6118                   argument along with this one.</para>
6119                 </listitem>
6120               </varlistentry>
6121             </variablelist></para>
6122         </listitem>
6123       </orderedlist>
6124     </sect2>
6125
6126     <sect2 id="Header_261">
6127       <title>About Restoring Volumes</title>
6128
6129       <indexterm>
6130         <primary>volume</primary>
6131
6132         <secondary>restoring</secondary>
6133
6134         <tertiary>with vos restore command</tertiary>
6135       </indexterm>
6136
6137       <indexterm>
6138         <primary>restoring</primary>
6139
6140         <secondary>volumes without using AFS Backup System</secondary>
6141       </indexterm>
6142
6143       <para>Although you can dump any of the three types of volumes (read/write, read-only, or backup), you can restore a dump file
6144       to the file system only as a read/write volume, using the <emphasis role="bold">vos restore</emphasis> command. The command
6145       automatically translates the dump file's contents from ASCII back into the volume format appropriate for the file server
6146       machine that stores the restored version. As with the <emphasis role="bold">vos dump</emphasis> command, you can restore a
6147       dump file via a named pipe, which facilitates interoperation with third-party backup utilities.</para>
6148
6149       <para>You can restore the contents of a dump file in one of two basic ways. In either case, you must restore a full dump of
6150       the volume before restoring any incremental dumps. Any incremental dumps that you then restore must have been created after
6151       the full dump. If there is more than one incremental dump, you must restore them in the order they were created. <itemizedlist>
6152           <listitem>
6153             <para>You can restore volume data into a brand new volume with a new name and at a location that you specify. See <link
6154             linkend="HDRWQ242">To restore a dump into a new volume and mount it</link>.</para>
6155
6156             <para>You can assign a volume ID number as you restore the volume, though it is best to have the Volume Server allocate
6157             a volume number automatically. The most common reason for specifying the volume ID is that a volume's VLDB entry has
6158             disappeared for some reason, but you know the former read/write volume ID number and want to reuse it.</para>
6159           </listitem>
6160
6161           <listitem>
6162             <para>You can restore volume data into an existing volume (usually the one that was previously dumped), overwriting its
6163             current contents. This is convenient if the current contents are corrupted or otherwise incorrect, because it allows you
6164             to replace them with a coherent version from the past or from one of the volume's clones. See <link
6165             linkend="HDRWQ244">To restore a dump file, overwriting an existing volume</link>.</para>
6166
6167             <para>Provide the <emphasis role="bold">-overwrite</emphasis> argument to preconfirm that you wish to overwrite the
6168             volume's contents, and to specify whether you are restoring a full or incremental dump. If you omit the <emphasis
6169             role="bold">-overwrite</emphasis> argument, the Volume Server generates the following prompt to confirm that you want to
6170             overwrite the existing volume with either a full ( <emphasis role="bold">f</emphasis>) or incremental ( <emphasis
6171             role="bold">i</emphasis>) dump:</para>
6172
6173             <programlisting>
6174    Do you want to do a full/incremental restore or abort? [fia](a):
6175 </programlisting>
6176
6177             <para>If you pipe in the dump file via the standard input stream instead of using the <emphasis
6178             role="bold">-file</emphasis> argument to name it, you must include the <emphasis role="bold">-overwrite</emphasis>
6179             argument because there is nowhere for the Volume Server to display the prompt in this case.</para>
6180
6181             <para>You can move the volume to a new site as you overwrite it with a full dump, by using the <emphasis
6182             role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments to specify the new site. You
6183             cannot move the volume when restoring an incremental dump.</para>
6184           </listitem>
6185         </itemizedlist></para>
6186
6187       <para>The <emphasis role="bold">vos restore</emphasis> command sets the restored volume's creation date in the volume header
6188       to the time of the restore operation, as reported in the <computeroutput>Creation</computeroutput> field in the output from
6189       the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvol</emphasis> commands.</para>
6190
6191       <indexterm>
6192         <primary>commands</primary>
6193
6194         <secondary>vos restore</secondary>
6195       </indexterm>
6196
6197       <indexterm>
6198         <primary>vos commands</primary>
6199
6200         <secondary>restore</secondary>
6201
6202         <tertiary>to create new volume</tertiary>
6203       </indexterm>
6204     </sect2>
6205
6206     <sect2 id="HDRWQ242">
6207       <title>To restore a dump into a new volume and mount it</title>
6208
6209       <orderedlist>
6210         <listitem>
6211           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
6212           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
6213           display the users in the UserList file</link>. <programlisting>
6214    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
6215 </programlisting></para>
6216         </listitem>
6217
6218         <listitem>
6219           <para>Verify that you have permissions needed to read the dump file and to mount the new volume. If the dump file resides
6220           in AFS, you need the <emphasis role="bold">r</emphasis>( <emphasis role="bold">read</emphasis>) permission on the ACL of
6221           its directory. You need the <emphasis role="bold">i</emphasis>( <emphasis role="bold">insert</emphasis>) and <emphasis
6222           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) permissions on the ACL of the directory where you
6223           are mounting the new volume. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully
6224           described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
6225    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
6226 </programlisting></para>
6227
6228           <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
6229           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
6230           role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
6231           role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
6232         </listitem>
6233
6234         <listitem>
6235           <para>Select a site (disk partition on a file server machine) for the new volume. If your cell groups different types of
6236           volumes onto different file server machines, that can guide your decision. It often makes sense to put the volume on the
6237           emptiest partition that meets your other criteria. To display how much space is available on a file server machine's
6238           partitions, use the <emphasis role="bold">vos partinfo</emphasis> command, which is described fully in <link
6239           linkend="HDRWQ185">Creating Read/write Volumes</link>. <programlisting>
6240    % <emphasis role="bold">vos partinfo</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>partition name</replaceable>&gt;]
6241 </programlisting></para>
6242         </listitem>
6243
6244         <listitem id="LIWQ243">
6245           <para>Issue the <emphasis role="bold">vos restore</emphasis> command to create a new volume and
6246           restore the dump file into it. Type it on a single line; it appears on multiple lines here only for legibility.
6247           <programlisting>
6248    % <emphasis role="bold">vos restore</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; \
6249                    &lt;<replaceable>name of volume to be restored</replaceable>&gt; \
6250                    [<emphasis role="bold">-file</emphasis> &lt;<replaceable>dump file</replaceable>&gt;] [<emphasis role="bold">-id</emphasis> &lt;<replaceable>volume ID</replaceable>&gt;]
6251 </programlisting></para>
6252
6253           <para>where <variablelist>
6254               <varlistentry>
6255                 <term><emphasis role="bold">res</emphasis></term>
6256
6257                 <listitem>
6258                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">restore</emphasis>.</para>
6259                 </listitem>
6260               </varlistentry>
6261
6262               <varlistentry>
6263                 <term><emphasis role="bold">machine name</emphasis></term>
6264
6265                 <listitem>
6266                   <para>Names the file server machine on which to create the new volume.</para>
6267                 </listitem>
6268               </varlistentry>
6269
6270               <varlistentry>
6271                 <term><emphasis role="bold">partition name</emphasis></term>
6272
6273                 <listitem>
6274                   <para>Names the partition on which to create the new volume.</para>
6275                 </listitem>
6276               </varlistentry>
6277
6278               <varlistentry>
6279                 <term><emphasis role="bold">name of volume to be restored</emphasis></term>
6280
6281                 <listitem>
6282                   <para>Names the new read/write volume, which must not already have a VLDB entry. It can be up to 22 characters in
6283                   length.</para>
6284                 </listitem>
6285               </varlistentry>
6286
6287               <varlistentry>
6288                 <term><emphasis role="bold">-file</emphasis></term>
6289
6290                 <listitem>
6291                   <para>Is the dump file to restore. Partial pathnames are interpreted with respect to the current working
6292                   directory. Omit this argument if using a pipe to read in the dump file from the standard input stream.</para>
6293                 </listitem>
6294               </varlistentry>
6295
6296               <varlistentry>
6297                 <term><emphasis role="bold">-volume</emphasis></term>
6298
6299                 <listitem>
6300                   <para>Specifies the new volume's ID number. It is appropriate only if you are restoring a volume that no longer
6301                   exists and want to use the volume ID number it had previously.</para>
6302                 </listitem>
6303               </varlistentry>
6304             </variablelist></para>
6305
6306           <indexterm>
6307             <primary>commands</primary>
6308
6309             <secondary>fs mkmount</secondary>
6310
6311             <tertiary>when restoring volume</tertiary>
6312           </indexterm>
6313
6314           <indexterm>
6315             <primary>fs commands</primary>
6316
6317             <secondary>mkmount</secondary>
6318
6319             <tertiary>when restoring volume</tertiary>
6320           </indexterm>
6321         </listitem>
6322
6323         <listitem>
6324           <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the new volume, making its contents
6325           accessible. Complete instructions appear in <link linkend="HDRWQ212">To create a regular or read/write mount point</link>.
6326           <programlisting>
6327    % <emphasis role="bold">fs mkmount</emphasis> &lt;<replaceable>directory</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt;
6328 </programlisting></para>
6329         </listitem>
6330
6331         <listitem>
6332           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">fs lsmount</emphasis> command to verify
6333           that the mount point refers to the correct volume. Complete instructions appear in <link linkend="HDRWQ211">To display a
6334           mount point</link>. <programlisting>
6335    % <emphasis role="bold">fs lsmount</emphasis> &lt;<replaceable>directory</replaceable>&gt;
6336 </programlisting></para>
6337         </listitem>
6338       </orderedlist>
6339
6340       <indexterm>
6341         <primary>commands</primary>
6342
6343         <secondary>vos restore</secondary>
6344       </indexterm>
6345
6346       <indexterm>
6347         <primary>vos commands</primary>
6348
6349         <secondary>restore</secondary>
6350
6351         <tertiary>to overwrite volume</tertiary>
6352       </indexterm>
6353     </sect2>
6354
6355     <sect2 id="HDRWQ244">
6356       <title>To restore a dump file, overwriting an existing volume</title>
6357
6358       <orderedlist>
6359         <listitem>
6360           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
6361           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
6362           display the users in the UserList file</link>. <programlisting>
6363    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
6364 </programlisting></para>
6365         </listitem>
6366
6367         <listitem>
6368           <para>Verify that you have permissions needed to read the dump file. If it resides in AFS, you need the <emphasis
6369           role="bold">r</emphasis>( <emphasis role="bold">read</emphasis>) permission on the ACL of its directory. If necessary,
6370           issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link
6371           linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
6372    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
6373 </programlisting></para>
6374
6375           <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
6376           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
6377           role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
6378           role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
6379         </listitem>
6380
6381         <listitem>
6382           <para>Restore the contents of the dump file into a read/write volume, overwriting the current contents. The volume retains
6383           its current volume ID number. Type it on a single line; it appears on multiple lines here only for legibility.
6384           <programlisting>
6385    % <emphasis role="bold">vos restore</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt;  \
6386                  &lt;<replaceable>name of volume to be restored</replaceable>&gt;   \
6387                  [<emphasis role="bold">-file</emphasis> &lt;<replaceable>dump file</replaceable>&gt;] [<emphasis role="bold">-id</emphasis> &lt;<replaceable>volume ID</replaceable>&gt;]
6388 </programlisting></para>
6389
6390           <para>where <variablelist>
6391               <varlistentry>
6392                 <term><emphasis role="bold">res</emphasis></term>
6393
6394                 <listitem>
6395                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">restore</emphasis>.</para>
6396                 </listitem>
6397               </varlistentry>
6398
6399               <varlistentry>
6400                 <term><emphasis role="bold">machine name</emphasis></term>
6401
6402                 <listitem>
6403                   <para>Names the file server machine where the volume already exists, or the machine to which to move it. In the
6404                   latter case, the value for the <emphasis role="bold">-overwrite</emphasis> argument must be <emphasis
6405                   role="bold">full</emphasis>.</para>
6406                 </listitem>
6407               </varlistentry>
6408
6409               <varlistentry>
6410                 <term><emphasis role="bold">partition name</emphasis></term>
6411
6412                 <listitem>
6413                   <para>Names the partition where the volume already exists, or the partition to which to move it. In the latter
6414                   case, the value for the <emphasis role="bold">-overwrite</emphasis> argument must be <emphasis
6415                   role="bold">full</emphasis>.</para>
6416                 </listitem>
6417               </varlistentry>
6418
6419               <varlistentry>
6420                 <term><emphasis role="bold">name of volume to be restored</emphasis></term>
6421
6422                 <listitem>
6423                   <para>Names the read/write volume to overwrite with the contents of the dump file.</para>
6424                 </listitem>
6425               </varlistentry>
6426
6427               <varlistentry>
6428                 <term><emphasis role="bold">-file</emphasis></term>
6429
6430                 <listitem>
6431                   <para>Is the dump file to restore. Partial pathnames are interpreted with respect to the current working
6432                   directory. Omit this argument if using a pipe to read in the dump file from the standard input stream; in this
6433                   case, you must provide the <emphasis role="bold">-overwrite</emphasis> argument.</para>
6434                 </listitem>
6435               </varlistentry>
6436
6437               <varlistentry>
6438                 <term><emphasis role="bold">-overwrite</emphasis></term>
6439
6440                 <listitem>
6441                   <para>Preconfirms that you want to overwrite the existing volume and specifies which type of dump file you are
6442                   restoring. Provide one of the following values: <itemizedlist>
6443                       <listitem>
6444                         <para><emphasis role="bold">f</emphasis> or <emphasis role="bold">full</emphasis> if restoring a full dump
6445                         file</para>
6446                       </listitem>
6447
6448                       <listitem>
6449                         <para><emphasis role="bold">i</emphasis> or <emphasis role="bold">incremental</emphasis> if restoring an
6450                         incremental dump file. This value is not acceptable if you are moving the volume while restoring it.</para>
6451                       </listitem>
6452
6453                       <listitem>
6454                         <para><emphasis role="bold">a</emphasis> to terminate the restore operation</para>
6455                       </listitem>
6456                     </itemizedlist></para>
6457                 </listitem>
6458               </varlistentry>
6459             </variablelist></para>
6460         </listitem>
6461
6462         <listitem>
6463           <para>If the volume is replicated, issue the <emphasis role="bold">vos release</emphasis> command to release the newly
6464           restored contents to read-only sites. Complete instructions appear in <link linkend="HDRWQ192">Replicating Volumes
6465           (Creating Read-only Volumes)</link>. <programlisting>
6466    % <emphasis role="bold">vos release</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
6467 </programlisting></para>
6468         </listitem>
6469
6470         <listitem>
6471           <para>Issue the <emphasis role="bold">vos backup</emphasis> command to create a new backup version of the volume. Complete
6472           instructions appear in <link linkend="HDRWQ201">Creating Backup Volumes</link>. <programlisting>
6473    % <emphasis role="bold">vos backup</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
6474 </programlisting></para>
6475         </listitem>
6476       </orderedlist>
6477     </sect2>
6478   </sect1>
6479
6480   <sect1 id="HDRWQ245">
6481     <title>Renaming Volumes</title>
6482
6483     <indexterm>
6484       <primary>renaming</primary>
6485
6486       <secondary>volume</secondary>
6487     </indexterm>
6488
6489     <indexterm>
6490       <primary>volume</primary>
6491
6492       <secondary>renaming</secondary>
6493     </indexterm>
6494
6495     <indexterm>
6496       <primary>changing</primary>
6497
6498       <secondary>volume name</secondary>
6499     </indexterm>
6500
6501     <indexterm>
6502       <primary>volume name</primary>
6503
6504       <secondary>changing</secondary>
6505
6506       <tertiary>basic instructions</tertiary>
6507     </indexterm>
6508
6509     <para>You can use the <emphasis role="bold">vos rename</emphasis> command to rename a volume. For example, it is appropriate to
6510     rename a user's home volume if you use the <emphasis role="bold">user.</emphasis> username convention for user volume names and
6511     you change the username. (For complete instructions for changing usernames, see <link linkend="HDRWQ518">Changing
6512     Usernames</link>.)</para>
6513
6514     <indexterm>
6515       <primary>read/write volume</primary>
6516
6517       <secondary>changing name of</secondary>
6518     </indexterm>
6519
6520     <indexterm>
6521       <primary>read-only volume</primary>
6522
6523       <secondary>changing name of</secondary>
6524     </indexterm>
6525
6526     <indexterm>
6527       <primary>backup volume</primary>
6528
6529       <secondary>changing name of</secondary>
6530     </indexterm>
6531
6532     <para>The <emphasis role="bold">vos rename</emphasis> command accepts only read/write volume names, but automatically changes
6533     the names of the associated read-only and backup volumes. As directed in the following instructions, you need to replace the
6534     volume's current mount point with a new one that reflects the name change.</para>
6535
6536     <indexterm>
6537       <primary>commands</primary>
6538
6539       <secondary>vos rename</secondary>
6540
6541       <tertiary>basic instructions</tertiary>
6542     </indexterm>
6543
6544     <indexterm>
6545       <primary>vos commands</primary>
6546
6547       <secondary>rename</secondary>
6548
6549       <tertiary>basic instructions</tertiary>
6550     </indexterm>
6551
6552     <sect2 id="HDRWQ246">
6553       <title>To rename a volume</title>
6554
6555       <orderedlist>
6556         <listitem>
6557           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
6558           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
6559           display the users in the UserList file</link>. <programlisting>
6560    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
6561 </programlisting></para>
6562         </listitem>
6563
6564         <listitem>
6565           <para>Verify that you have the <emphasis role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>), <emphasis
6566           role="bold">d</emphasis>( <emphasis role="bold">delete</emphasis>), and <emphasis role="bold">i</emphasis>( <emphasis
6567           role="bold">insert</emphasis>) access permissions for the directory in which you are replacing the volume's mount point.
6568           If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link
6569           linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
6570    % <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
6571 </programlisting></para>
6572
6573           <para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
6574           role="bold">a</emphasis>( <emphasis role="bold">administer</emphasis>) and by default also the <emphasis
6575           role="bold">l</emphasis>( <emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
6576           role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
6577         </listitem>
6578
6579         <listitem id="LIVOL-REN">
6580           <para>Issue the <emphasis role="bold">vos rename</emphasis> command to rename the volume.
6581           <programlisting>
6582    % <emphasis role="bold">vos rename</emphasis> &lt;<replaceable>old volume name</replaceable>&gt; &lt;<replaceable>new volume name</replaceable>&gt;
6583 </programlisting></para>
6584
6585           <para>where <variablelist>
6586               <varlistentry>
6587                 <term><emphasis role="bold">ren</emphasis></term>
6588
6589                 <listitem>
6590                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">rename</emphasis>.</para>
6591                 </listitem>
6592               </varlistentry>
6593
6594               <varlistentry>
6595                 <term><emphasis role="bold">old volume name</emphasis></term>
6596
6597                 <listitem>
6598                   <para>Is the current name of a read/write volume.</para>
6599                 </listitem>
6600               </varlistentry>
6601
6602               <varlistentry>
6603                 <term><emphasis role="bold">new volume name</emphasis></term>
6604
6605                 <listitem>
6606                   <para>Is the new name for the volume. It cannot be more than 22 characters in length.</para>
6607                 </listitem>
6608               </varlistentry>
6609             </variablelist></para>
6610
6611           <para>If there is no Volume Location Database (VLDB) entry for the specified current volume name, the command fails with
6612           the following error message:</para>
6613
6614           <programlisting>
6615    vos: Could not find entry for volume old_volume_name.
6616 </programlisting>
6617
6618           <indexterm>
6619             <primary>commands</primary>
6620
6621             <secondary>fs rmmount</secondary>
6622           </indexterm>
6623
6624           <indexterm>
6625             <primary>fs commands</primary>
6626
6627             <secondary>rmmount</secondary>
6628
6629             <tertiary>when renaming volume</tertiary>
6630           </indexterm>
6631         </listitem>
6632
6633         <listitem>
6634           <para>Issue the <emphasis role="bold">fs rmmount</emphasis> command to remove the mount point that refers to the volume's
6635           old name. Complete instructions appear in <link linkend="HDRWQ215">To remove a mount point</link>. <programlisting>
6636    % <emphasis role="bold">fs rmmount</emphasis> &lt;<replaceable>directory</replaceable>&gt;
6637 </programlisting></para>
6638
6639           <indexterm>
6640             <primary>commands</primary>
6641
6642             <secondary>fs mkmount</secondary>
6643
6644             <tertiary>when renaming volume</tertiary>
6645           </indexterm>
6646
6647           <indexterm>
6648             <primary>fs commands</primary>
6649
6650             <secondary>mkmount</secondary>
6651
6652             <tertiary>when renaming volume</tertiary>
6653           </indexterm>
6654         </listitem>
6655
6656         <listitem>
6657           <para>Issue the <emphasis role="bold">fs mkmount</emphasis> to create a mount point that indicates the volume's new name.
6658           Complete instructions appear in <link linkend="HDRWQ212">To create a regular or read/write mount point</link>.
6659           <programlisting>
6660    % <emphasis role="bold">fs mkmount</emphasis> &lt;<replaceable>directory</replaceable>&gt; &lt;<replaceable>volume name</replaceable>&gt; [<emphasis
6661                 role="bold">-rw</emphasis>]
6662 </programlisting></para>
6663         </listitem>
6664       </orderedlist>
6665     </sect2>
6666   </sect1>
6667
6668   <sect1 id="HDRWQ247">
6669     <title>Unlocking and Locking VLDB Entries</title>
6670
6671     <para>As detailed in <link linkend="HDRWQ227">Synchronizing the VLDB and Volume Headers</link>, The Volume Location (VL) Server
6672     locks the Volume Location Database (VLDB) entry for a volume before the Volume Server executes any operation on it. No other
6673     operation can affect a volume with a locked VLDB entry, so the lock prevents the inconsistency or corruption that can result
6674     from multiple simultaneous operations on a volume.</para>
6675
6676     <indexterm>
6677       <primary>locking</primary>
6678
6679       <secondary>VLDB entry</secondary>
6680     </indexterm>
6681
6682     <indexterm>
6683       <primary>VLDB</primary>
6684
6685       <secondary>locking/unlocking entry</secondary>
6686     </indexterm>
6687
6688     <indexterm>
6689       <primary>entry in VLDB</primary>
6690
6691       <secondary>locking/unlocking</secondary>
6692     </indexterm>
6693
6694     <indexterm>
6695       <primary>unlocking</primary>
6696
6697       <secondary>VLDB entry</secondary>
6698     </indexterm>
6699
6700     <indexterm>
6701       <primary>locked VLDB entry</primary>
6702
6703       <secondary>unlocking</secondary>
6704     </indexterm>
6705
6706     <para>To verify that a VLDB entry is locked, issue the <emphasis role="bold">vos listvldb</emphasis> command as described in
6707     <link linkend="HDRWQ218">To display VLDB entries</link>. The command has a <emphasis role="bold">-locked</emphasis> flag that
6708     displays locked entries only. If the VLDB entry is locked, the string <computeroutput>Volume is currently
6709     LOCKED</computeroutput> appears on the last line of the volume's output.</para>
6710
6711     <para>To lock a VLDB entry yourself, use the <emphasis role="bold">vos lock</emphasis> command. This is useful when you suspect
6712     something is wrong with a volume and you want to prevent any changes to it while you are investigating the problem.</para>
6713
6714     <para>To unlock a locked VLDB entry, issue the <emphasis role="bold">vos unlock</emphasis> command, which unlocks a single VLDB
6715     entry, or the <emphasis role="bold">vos unlockvldb</emphasis> command, which unlocks potentially many entries. This is useful
6716     when a volume operation fails prematurely and leaves a VLDB entry locked, preventing you from acting to correct the problems
6717     resulting from the failure.</para>
6718
6719     <indexterm>
6720       <primary>commands</primary>
6721
6722       <secondary>vos lock</secondary>
6723     </indexterm>
6724
6725     <indexterm>
6726       <primary>vos commands</primary>
6727
6728       <secondary>lock</secondary>
6729     </indexterm>
6730
6731     <sect2 id="Header_267">
6732       <title>To lock a VLDB entry</title>
6733
6734       <orderedlist>
6735         <listitem>
6736           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
6737           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
6738           display the users in the UserList file</link>. <programlisting>
6739    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
6740 </programlisting></para>
6741         </listitem>
6742
6743         <listitem>
6744           <para>Issue the <emphasis role="bold">vos lock</emphasis> to lock the entry. <programlisting>
6745    % <emphasis role="bold">vos lock</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
6746 </programlisting></para>
6747
6748           <para>where <variablelist>
6749               <varlistentry>
6750                 <term><emphasis role="bold">lo</emphasis></term>
6751
6752                 <listitem>
6753                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">lock</emphasis>.</para>
6754                 </listitem>
6755               </varlistentry>
6756
6757               <varlistentry>
6758                 <term><emphasis role="bold">volume name or ID</emphasis></term>
6759
6760                 <listitem>
6761                   <para>Identifies the volume to be locked, either by its complete name or volume ID number. It can be any of the
6762                   three versions of the volume.</para>
6763                 </listitem>
6764               </varlistentry>
6765             </variablelist></para>
6766         </listitem>
6767       </orderedlist>
6768
6769       <indexterm>
6770         <primary>commands</primary>
6771
6772         <secondary>vos unlock</secondary>
6773       </indexterm>
6774
6775       <indexterm>
6776         <primary>vos commands</primary>
6777
6778         <secondary>unlock</secondary>
6779       </indexterm>
6780     </sect2>
6781
6782     <sect2 id="Header_268">
6783       <title>To unlock a single VLDB entry</title>
6784
6785       <orderedlist>
6786         <listitem>
6787           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
6788           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
6789           display the users in the UserList file</link>. <programlisting>
6790    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
6791 </programlisting></para>
6792         </listitem>
6793
6794         <listitem>
6795           <para>Issue the <emphasis role="bold">vos unlock</emphasis> command to unlock the entry. <programlisting>
6796    % <emphasis role="bold">vos unlock</emphasis> &lt;<replaceable>volume name or ID</replaceable>&gt;
6797 </programlisting></para>
6798
6799           <para>where <variablelist>
6800               <varlistentry>
6801                 <term><emphasis role="bold">unlock</emphasis></term>
6802
6803                 <listitem>
6804                   <para>Must be typed in full.</para>
6805                 </listitem>
6806               </varlistentry>
6807
6808               <varlistentry>
6809                 <term><emphasis role="bold">volume name or ID</emphasis></term>
6810
6811                 <listitem>
6812                   <para>Identifies the volume to be unlocked, either by its complete name or volume ID number. It can be any of the
6813                   three versions of the volume.</para>
6814                 </listitem>
6815               </varlistentry>
6816             </variablelist></para>
6817         </listitem>
6818       </orderedlist>
6819
6820       <indexterm>
6821         <primary>commands</primary>
6822
6823         <secondary>vos unlockvldb</secondary>
6824       </indexterm>
6825
6826       <indexterm>
6827         <primary>vos commands</primary>
6828
6829         <secondary>unlockvldb</secondary>
6830       </indexterm>
6831     </sect2>
6832
6833     <sect2 id="Header_269">
6834       <title>To unlock multiple VLDB entries</title>
6835
6836       <orderedlist>
6837         <listitem>
6838           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
6839           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
6840           display the users in the UserList file</link>. <programlisting>
6841    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
6842 </programlisting></para>
6843         </listitem>
6844
6845         <listitem>
6846           <para>Issue the <emphasis role="bold">vos unlockvldb</emphasis> command to unlock the desired entries. <programlisting>
6847    % <emphasis role="bold">vos unlockvldb</emphasis> [&lt;<replaceable>machine name</replaceable>&gt;] [&lt;<replaceable>partition name</replaceable>&gt;]
6848 </programlisting></para>
6849
6850           <para>where <variablelist>
6851               <varlistentry>
6852                 <term><emphasis role="bold">unlockv</emphasis></term>
6853
6854                 <listitem>
6855                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">unlockvldb</emphasis>.</para>
6856                 </listitem>
6857               </varlistentry>
6858
6859               <varlistentry>
6860                 <term><emphasis role="bold">machine name</emphasis></term>
6861
6862                 <listitem>
6863                   <para>Specifies a file server machine. Provide this argument alone to unlock all VLDB entries that mention the
6864                   machine in a site definition. Omit both this argument and the partition name argument to unlock all VLDB
6865                   entries.</para>
6866                 </listitem>
6867               </varlistentry>
6868
6869               <varlistentry>
6870                 <term><emphasis role="bold">partition name</emphasis></term>
6871
6872                 <listitem>
6873                   <para>Specifies a partition. Provide this argument alone to unlock all VLDB entries that mention the partition (on
6874                   any machine) in a site definition. Omit both this argument and the machine name argument to unlock all VLDB
6875                   entries.</para>
6876                 </listitem>
6877               </varlistentry>
6878             </variablelist></para>
6879         </listitem>
6880       </orderedlist>
6881     </sect2>
6882   </sect1>
6883 </chapter>