1 <?xml version=
"1.0" encoding=
"UTF-8"?>
2 <chapter id=
"HDRWQ174">
3 <title>Managing Volumes
</title>
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>
9 <title>Summary of Instructions
</title>
11 <para>This chapter explains how to perform the following tasks by using the indicated commands:
</para>
13 <informaltable frame=
"none">
15 <colspec colwidth=
"58*" />
17 <colspec colwidth=
"42*" />
21 <entry>Create read/write volume
</entry>
23 <entry><emphasis role=
"bold">vos create
</emphasis></entry>
27 <entry>Create read-only volume
</entry>
29 <entry><emphasis role=
"bold">vos addsite
</emphasis> <emphasis role=
"bold">and
</emphasis> <emphasis role=
"bold">vos
30 release
</emphasis></entry>
34 <entry>Create backup volume
</entry>
36 <entry><emphasis role=
"bold">vos backup
</emphasis></entry>
40 <entry>Create many backup volumes at once
</entry>
42 <entry><emphasis role=
"bold">vos backupsys
</emphasis></entry>
46 <entry>Examine VLDB entry
</entry>
48 <entry><emphasis role=
"bold">vos listvldb
</emphasis></entry>
52 <entry>Examine volume header
</entry>
54 <entry><emphasis role=
"bold">vos listvol
</emphasis></entry>
58 <entry>Examine both VLDB entry and volume header
</entry>
60 <entry><emphasis role=
"bold">vos examine
</emphasis></entry>
64 <entry>Display volume's name
</entry>
66 <entry><emphasis role=
"bold">fs listquota
</emphasis> <emphasis role=
"bold">or
</emphasis> <emphasis role=
"bold">fs
67 examine
</emphasis></entry>
71 <entry>Display volume's ID number
</entry>
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>
78 <entry>Display partition's size and space available
</entry>
80 <entry><emphasis role=
"bold">vos partinfo
</emphasis></entry>
84 <entry>Display volume's location
</entry>
86 <entry><emphasis role=
"bold">fs whereis
</emphasis> <emphasis role=
"bold">or
</emphasis> <emphasis role=
"bold">vos
87 examine
</emphasis></entry>
91 <entry>Create mount point
</entry>
93 <entry><emphasis role=
"bold">fs mkmount
</emphasis></entry>
97 <entry>Remove mount point
</entry>
99 <entry><emphasis role=
"bold">fs rmmount
</emphasis></entry>
103 <entry>Display mount point
</entry>
105 <entry><emphasis role=
"bold">fs lsmount
</emphasis></entry>
109 <entry>Move read/write volume
</entry>
111 <entry><emphasis role=
"bold">vos move
</emphasis></entry>
115 <entry>Synchronize VLDB with volume headers
</entry>
117 <entry><emphasis role=
"bold">vos syncvldb
</emphasis> <emphasis role=
"bold">and
</emphasis> <emphasis role=
"bold">vos
118 syncserv
</emphasis></entry>
122 <entry>Set volume quota
</entry>
124 <entry><emphasis role=
"bold">fs setvol
</emphasis> <emphasis role=
"bold">or
</emphasis> <emphasis role=
"bold">fs
125 setquota
</emphasis></entry>
129 <entry>Display volume quota
</entry>
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>
136 <entry>Display volume's current size
</entry>
138 <entry><emphasis role=
"bold">fs listquota
</emphasis> <emphasis role=
"bold">or
</emphasis> <emphasis role=
"bold">fs
139 examine
</emphasis></entry>
143 <entry>Display list of volumes on a machine/partition
</entry>
145 <entry><emphasis role=
"bold">vos listvol
</emphasis></entry>
149 <entry>Remove read/write volume
</entry>
151 <entry><emphasis role=
"bold">vos remove
</emphasis> <emphasis role=
"bold">and
</emphasis> <emphasis role=
"bold">fs
152 rmmount
</emphasis></entry>
156 <entry>Remove read-only volume
</entry>
158 <entry><emphasis role=
"bold">vos remove
</emphasis></entry>
162 <entry>Remove backup volume
</entry>
164 <entry><emphasis role=
"bold">vos remove
</emphasis> <emphasis role=
"bold">and
</emphasis> <emphasis role=
"bold">fs
165 rmmount
</emphasis></entry>
169 <entry>Remove volume; no VLDB change
</entry>
171 <entry><emphasis role=
"bold">vos zap
</emphasis></entry>
175 <entry>Remove read-only site definition
</entry>
177 <entry><emphasis role=
"bold">vos remsite
</emphasis></entry>
181 <entry>Remove VLDB entry; no volume change
</entry>
183 <entry><emphasis role=
"bold">vos delentry
</emphasis></entry>
187 <entry>Dump volume
</entry>
189 <entry><emphasis role=
"bold">vos dump
</emphasis></entry>
193 <entry>Restore dumped volume
</entry>
195 <entry><emphasis role=
"bold">vos restore
</emphasis></entry>
199 <entry>Rename volume
</entry>
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>
206 <entry>Unlock volume
</entry>
208 <entry><emphasis role=
"bold">vos unlock
</emphasis></entry>
212 <entry>Unlock multiple volumes
</entry>
214 <entry><emphasis role=
"bold">vos unlockvldb
</emphasis></entry>
218 <entry>Lock volume
</entry>
220 <entry><emphasis role=
"bold">vos lock
</emphasis></entry>
227 <sect1 id=
"HDRWQ177">
228 <title>About Volumes
</title>
231 <primary>volume
</primary>
233 <secondary>defined
</secondary>
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>
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>
248 <sect2 id=
"HDRWQ178">
249 <title>The Three Types of Volumes
</title>
251 <para>There are three types of volumes in AFS, as described in the following list:
<itemizedlist>
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>
259 <primary>read/write volume
</primary>
261 <secondary>defined
</secondary>
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>
277 <primary>read-only volume
</primary>
279 <secondary>defined
</secondary>
283 <primary>site
</primary>
285 <secondary>volume, defined
</secondary>
289 <primary>volume
</primary>
291 <secondary>site, defined
</secondary>
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>
304 <primary>backup volume
</primary>
306 <secondary>defined
</secondary>
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
316 </itemizedlist></para>
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>
323 <sect2 id=
"HDRWQ179">
324 <title>How Volumes Improve AFS Efficiency
</title>
327 <primary>volume
</primary>
329 <secondary>benefits for efficiency
</secondary>
332 <para>Volumes make your cell easier to manage and more efficient in the following three ways:
<itemizedlist>
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>
342 <primary>volume
</primary>
344 <secondary>in load balancing
</secondary>
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>
357 <primary>volume
</primary>
359 <secondary>as unit of replication
</secondary>
363 <primary>replication
</primary>
365 <secondary>defined
</secondary>
371 <primary>volume
</primary>
373 <secondary>as unit of backup
</secondary>
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>
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>
387 </itemizedlist></para>
390 <sect2 id=
"HDRWQ180">
391 <title>Volume Information in the VLDB
</title>
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>
400 <primary>VLDB
</primary>
402 <secondary>volume entry
</secondary>
406 <primary>volume
</primary>
408 <secondary>entry in VLDB
</secondary>
412 <primary>entry in VLDB
</primary>
414 <secondary>for volume
</secondary>
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>
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>
430 <sect2 id=
"HDRWQ181">
431 <title>The Information in Volume Headers
</title>
434 <primary>volume
</primary>
436 <secondary>header
</secondary>
438 <see>volume header
</see>
442 <primary>volume header
</primary>
444 <secondary>about
</secondary>
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>
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>
460 <sect2 id=
"HDRWQ182">
461 <title>Keeping the VLDB and Volume Headers Synchronized
</title>
464 <primary>synchrony of VLDB and volume headers
</primary>
466 <secondary>maintained by VL and Volume Servers
</secondary>
470 <primary>VLDB
</primary>
472 <secondary>synchronizing with volume headers
</secondary>
476 <primary>volume header
</primary>
478 <secondary>synchronizing with VLDB
</secondary>
482 <primary>maintaining
</primary>
484 <secondary>synchrony of VLDB with volume headers
</secondary>
488 <primary>VL Server
</primary>
490 <secondary>role in VLDB/volume header synchronization
</secondary>
494 <primary>Volume Server
</primary>
496 <secondary>role in VLDB/volume header synchronization
</secondary>
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>
507 <sect2 id=
"HDRWQ183">
508 <title>About Mounting Volumes
</title>
511 <primary>mount point
</primary>
513 <secondary>defined
</secondary>
517 <primary>volume
</primary>
519 <secondary>mounting
</secondary>
521 <tertiary>about
</tertiary>
525 <primary>mounting
</primary>
527 <secondary>volume
</secondary>
529 <tertiary>about
</tertiary>
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>
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>
549 <primary>root directory
</primary>
553 <primary>Cache Manager
</primary>
555 <secondary>as interpreter of mount points
</secondary>
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>
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>
569 <primary>mount point
</primary>
571 <secondary>creating multiple per volume
</secondary>
575 <primary>volume
</primary>
577 <secondary>mounting
</secondary>
579 <tertiary>more than once
</tertiary>
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>
586 <sect2 id=
"HDRWQ184">
587 <title>About Volume Names
</title>
590 <primary>volume
</primary>
592 <secondary>name
</secondary>
594 <see>volume name
</see>
598 <primary>length restriction on volume names
</primary>
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>
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>
611 <primary>conventions
</primary>
613 <secondary>volume names
</secondary>
617 <primary>volume name
</primary>
619 <secondary>conventions
</secondary>
624 <sect1 id=
"HDRWQ185">
625 <title>Creating Read/write Volumes
</title>
628 <primary>creating
</primary>
630 <secondary>read/write volume
</secondary>
634 <primary>volume
</primary>
636 <secondary>read/write
</secondary>
638 <see>read/write volume
</see>
642 <primary>read/write volume
</primary>
644 <secondary>creating
</secondary>
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>
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>
661 <primary>default
</primary>
663 <secondary>ACL
</secondary>
667 <primary>ACL
</primary>
669 <secondary>default on new volume
</secondary>
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>
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>
682 <primary>volume quota
</primary>
684 <secondary>default for new volume
</secondary>
688 <primary>default
</primary>
690 <secondary>volume quota
</secondary>
693 </itemizedlist></para>
695 <sect2 id=
"Header_212">
696 <title>To create (and mount) a read/write volume
</title>
700 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
701 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
702 display the users in the UserList file
</link>.
<programlisting>
703 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
704 </programlisting></para>
708 <para>Verify that you have the
<emphasis role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>),
<emphasis
709 role=
"bold">i
</emphasis>(
<emphasis role=
"bold">insert
</emphasis>), and
<emphasis role=
"bold">l
</emphasis>(
<emphasis
710 role=
"bold">lookup
</emphasis>) permissions on the ACL of the directory where you plan to mount the volume. If necessary,
711 issue the
<emphasis role=
"bold">fs listacl
</emphasis> command, which is fully described in
<link
712 linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
713 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<emphasis>dir/file path
</emphasis>>]
</programlisting></para>
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>
721 <primary>commands
</primary>
723 <secondary>vos partinfo
</secondary>
727 <primary>vos commands
</primary>
729 <secondary>partinfo
</secondary>
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>
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>
747 %
<emphasis role=
"bold">vos partinfo
</emphasis> <<emphasis>machine name
</emphasis>> [
<<emphasis>partition name
</emphasis>>]
</programlisting>
749 <para>where
<variablelist>
751 <term><emphasis role=
"bold">p
</emphasis></term>
754 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">partinfo
</emphasis>.
</para>
759 <term><emphasis role=
"bold">machine name
</emphasis></term>
762 <para>Specifies the file server machine for which to display partition size and usage.
</para>
767 <term><emphasis role=
"bold">partition name
</emphasis></term>
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>
774 </variablelist></para>
777 <listitem id=
"LIWQ187">
778 <para>Select a volume name, taking note of the information in
<link linkend=
"HDRWQ184">About Volume
782 <primary>vos commands
</primary>
784 <secondary>create
</secondary>
786 <tertiary>basic instructions
</tertiary>
790 <primary>commands
</primary>
792 <secondary>vos create
</secondary>
794 <tertiary>basic instructions
</tertiary>
798 <listitem id=
"LIWQ188">
799 <para>Issue the
<emphasis role=
"bold">vos create
</emphasis> command to create the volume.
801 %
<emphasis role=
"bold">vos create
</emphasis> <<replaceable>machine name
</replaceable>> <<replaceable>partition name
</replaceable>> <<replaceable>volume name
</replaceable>> \
802 [
<emphasis role=
"bold">-maxquota
</emphasis> <<replaceable>initial quota (KB)
</replaceable>>]
803 </programlisting></para>
805 <para>where
<variablelist>
807 <term><emphasis role=
"bold">cr
</emphasis></term>
810 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">create
</emphasis>.
</para>
815 <term><emphasis role=
"bold">machine name
</emphasis></term>
818 <para>Specifies the file server machine on which to place the volume.
</para>
823 <term><emphasis role=
"bold">partition name
</emphasis></term>
826 <para>Specifies the disk partition on which to place the volume.
</para>
831 <term><emphasis role=
"bold">volume name
</emphasis></term>
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>
841 <term><emphasis role=
"bold">-maxquota
</emphasis></term>
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>
848 </variablelist></para>
851 <primary>mounting
</primary>
853 <secondary>read/write volume
</secondary>
857 <primary>read/write volume
</primary>
859 <secondary>mounting
</secondary>
863 <primary>commands
</primary>
865 <secondary>fs mkmount
</secondary>
869 <primary>fs commands
</primary>
871 <secondary>mkmount
</secondary>
873 <tertiary>for read/write volume
</tertiary>
877 <listitem id=
"LIWQ189">
878 <para><emphasis role=
"bold">(Optional)
</emphasis> Issue the
<emphasis role=
"bold">fs mkmount
</emphasis> command to mount
879 the volume in the filespace. For complete syntax, see
<link linkend=
"HDRWQ212">To create a regular or read/write mount
880 point
</link>.
<programlisting>
881 %
<emphasis role=
"bold">fs mkmount
</emphasis> <<emphasis>directory
</emphasis>> <<emphasis>volume name
</emphasis>></programlisting></para>
885 <para><emphasis role=
"bold">(Optional)
</emphasis> Issue the
<emphasis role=
"bold">fs lsmount
</emphasis> command to verify
886 that the mount point refers to the correct volume. Complete instructions appear in
<link linkend=
"HDRWQ211">To display a
887 mount point
</link>.
<programlisting>
888 %
<emphasis role=
"bold">fs lsmount
</emphasis> <<emphasis>directory
</emphasis>></programlisting></para>
892 <para><emphasis role=
"bold">(Optional)
</emphasis> Issue the
<emphasis role=
"bold">fs setvol
</emphasis> command with the
893 <emphasis role=
"bold">-offlinemsg
</emphasis> argument to record auxiliary information about the volume in its volume
894 header. For example, you can record who owns the volume or where you have mounted it in the filespace. To display the
895 information, use the
<emphasis role=
"bold">fs examine
</emphasis> command.
<programlisting>
896 %
<emphasis role=
"bold">fs setvol
</emphasis> <<replaceable>dir/file path
</replaceable>> <emphasis role=
"bold">-offlinemsg
</emphasis> <<replaceable>offline message
</replaceable>>
897 </programlisting></para>
899 <para>where
<variablelist>
901 <term><emphasis role=
"bold">sv
</emphasis></term>
904 <para>Is an acceptable alias for
<emphasis role=
"bold">setvol
</emphasis>(and
<emphasis role=
"bold">setv
</emphasis>
905 the shortest acceptable abbreviation).
</para>
910 <term><emphasis role=
"bold">dir/file path
</emphasis></term>
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>
916 <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to change
917 a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at
918 the pathname's second level (for example,
<emphasis role=
"bold">/afs/.example.com
</emphasis>). For further discussion
919 of the concept of read/write and read-only paths through the filespace, see
<link linkend=
"HDRWQ209">The Rules of
920 Mount Point Traversal
</link>.
</para>
925 <term><emphasis role=
"bold">-offlinemsg
</emphasis></term>
928 <para>Specifies up to
128 characters of auxiliary information to record in the volume header.
</para>
931 </variablelist></para>
937 <sect1 id=
"HDRWQ190">
938 <title>About Clones and Cloning
</title>
941 <primary>cloning
</primary>
943 <secondary>defined
</secondary>
947 <primary>clone
</primary>
951 <primary>vnode index
</primary>
955 <primary>backup volume
</primary>
957 <secondary>space-saving nature of
</secondary>
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
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>
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>
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>
987 </itemizedlist></para>
989 <figure id=
"FIGWQ191" label=
"1">
990 <title>File Sharing Between the Read/write Source and a Clone Volume
</title>
994 <imagedata fileref=
"vnode.png" scale=
"50" />
1000 <primary>replication
</primary>
1002 <secondary>detailed discussion
</secondary>
1006 <primary>volume
</primary>
1008 <secondary>replicating
</secondary>
1012 <primary>volume
</primary>
1014 <secondary>read-only
</secondary>
1016 <see>read-only volume
</see>
1020 <primary>read-only volume
</primary>
1022 <secondary>creating
</secondary>
1026 <primary>creating
</primary>
1028 <secondary>read-only volume
</secondary>
1032 <primary>cloning
</primary>
1034 <secondary>for replication
</secondary>
1038 <primary>read/write volume
</primary>
1040 <secondary>cloning
</secondary>
1042 <tertiary>for replication
</tertiary>
1046 <sect1 id=
"HDRWQ192">
1047 <title>Replicating Volumes (Creating Read-only Volumes)
</title>
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>
1059 <primary>stages in volume replication
</primary>
1063 <primary>site definition stage in replication
</primary>
1067 <primary>replication
</primary>
1069 <secondary>site definition stage
</secondary>
1073 <primary>release stage in replication
</primary>
1077 <primary>replication
</primary>
1079 <secondary>release stage
</secondary>
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>
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>
1096 <primary>replication
</primary>
1098 <secondary>determining success of
</secondary>
1102 <primary>determining
</primary>
1104 <secondary>success of replication
</secondary>
1108 <primary>replication
</primary>
1110 <secondary>need for all-or-nothing release
</secondary>
1114 <primary>all-or-nothing release of read-only volumes
</primary>
1118 <primary>read-only volume
</primary>
1120 <secondary>need for atomic release
</secondary>
1124 <primary>releasing
</primary>
1126 <secondary>read-only volume, need for atomicity
</secondary>
1130 <primary>ReleaseClone
</primary>
1134 <primary>replication
</primary>
1136 <secondary>role of ReleaseClone
</secondary>
1140 <primary>New release site flag in VLDB
</primary>
1142 <secondary>as indicator of failed replication
</secondary>
1146 <primary>Old release site flag in VLDB
</primary>
1148 <secondary>as indicator of failed replication
</secondary>
1152 <primary>clone
</primary>
1154 <secondary>forcing creation of new
</secondary>
1158 <primary>replication
</primary>
1160 <secondary>forcing creation of new clone
</secondary>
1164 <primary>vos commands
</primary>
1166 <secondary>release
</secondary>
1168 <tertiary>forcing new cloning with -f flag
</tertiary>
1172 <primary>releasing
</primary>
1174 <secondary>read-only volume, forcing new cloning
</secondary>
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>
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>
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>
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>
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>
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>
1215 </orderedlist></para>
1217 <para>By default, the Volume Server determines automatically whether or not it needs to create a new ReleaseClone:
<itemizedlist>
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
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>
1235 </itemizedlist></para>
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>
1241 <sect2 id=
"HDRWQ193">
1242 <title>Using Read-only Volumes Effectively
</title>
1245 <primary>criteria for replicating volumes
</primary>
1249 <primary>replication
</primary>
1251 <secondary>suitable types of volumes
</secondary>
1255 <primary>suitability of volumes for replication
</primary>
1259 <primary>read/write volume
</primary>
1261 <secondary>types suitable for replication
</secondary>
1264 <para>For maximum effectiveness, replicate only volumes that satisfy two criteria:
<itemizedlist>
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>
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>
1278 </itemizedlist></para>
1281 <primary>mounting
</primary>
1283 <secondary>read-only volume
</secondary>
1287 <primary>read-only volume
</primary>
1289 <secondary>mounting
</secondary>
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>
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>
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>
1321 <sect2 id=
"Header_216">
1322 <title>Replication Scenarios
</title>
1325 <primary>variations possible
</primary>
1327 <secondary>in replication
</secondary>
1331 <primary>replication
</primary>
1333 <secondary>variations possible in
</secondary>
1337 <primary>possible variations
</primary>
1339 <secondary>on replication
</secondary>
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>
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>
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
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>
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>
1366 </itemizedlist></para>
1369 <sect2 id=
"HDRWQ194">
1370 <title>To replicate a read/write volume (create a read-only volume)
</title>
1373 <primary>read-only volume
</primary>
1375 <secondary>creating
</secondary>
1377 <tertiary>instructions
</tertiary>
1381 <primary>read/write volume
</primary>
1383 <secondary>replication instructions
</secondary>
1387 <listitem id=
"LIWQ195">
1388 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis>
1389 file. If necessary, issue the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link
1390 linkend=
"HDRWQ593">To display the users in the UserList file
</link>.
<programlisting>
1391 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
1392 </programlisting></para>
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>
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>.
1404 %
<emphasis role=
"bold">vos examine
</emphasis> <<replaceable>volume name or ID
</replaceable>>
1405 </programlisting></para>
1407 <para>The final lines of output display the volume's site definitions from the VLDB.
</para>
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>
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>
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>
1426 %
<emphasis role=
"bold">vos partinfo
</emphasis> <<replaceable>machine name
</replaceable>> [
<<replaceable>partition name
</replaceable>>]
1429 </itemizedlist></para>
1432 <primary>read-only volume
</primary>
1434 <secondary>defining site for in VLDB
</secondary>
1438 <primary>defining
</primary>
1440 <secondary>read-only site in VLDB
</secondary>
1444 <primary>adding
</primary>
1446 <secondary>read-only site definition in VLDB
</secondary>
1450 <primary>VLDB
</primary>
1452 <secondary>defining read-only site in
</secondary>
1456 <primary>commands
</primary>
1458 <secondary>vos addsite
</secondary>
1462 <primary>vos commands
</primary>
1464 <secondary>addsite
</secondary>
1468 <listitem id=
"LIWQ197">
1469 <para>Issue the
<emphasis role=
"bold">vos addsite
</emphasis> command to define each new read-only
1470 site in the VLDB.
<programlisting>
1471 %
<emphasis role=
"bold">vos addsite
</emphasis> <<replaceable>machine name
</replaceable>> <<replaceable>partition name
</replaceable>> <<replaceable>volume name or ID
</replaceable>>
1472 </programlisting></para>
1474 <para>where
<variablelist>
1476 <term><emphasis role=
"bold">ad
</emphasis></term>
1479 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">addsite
</emphasis>.
</para>
1484 <term><emphasis role=
"bold">machine name
</emphasis></term>
1487 <para>Defines the file server machine for the new site.
</para>
1492 <term><emphasis role=
"bold">partition name
</emphasis></term>
1495 <para>Names a disk partition on the machine machine name.
</para>
1500 <term><emphasis role=
"bold">volume name or ID
</emphasis></term>
1503 <para>Identifies the read/write volume to be replicated, either by its complete name or its volume ID
1507 </variablelist></para>
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>.
1519 %
<emphasis role=
"bold">bos status
</emphasis> <<replaceable>machine name
</replaceable>> <emphasis role=
"bold">fs vlserver
</emphasis>
1520 </programlisting></para>
1523 <primary>releasing
</primary>
1525 <secondary>read-only volume
</secondary>
1529 <primary>read-only volume
</primary>
1531 <secondary>releasing
</secondary>
1535 <primary>commands
</primary>
1537 <secondary>vos release
</secondary>
1539 <tertiary>basic instructions
</tertiary>
1543 <primary>vos commands
</primary>
1545 <secondary>release
</secondary>
1547 <tertiary>basic instructions
</tertiary>
1551 <listitem id=
"LIWQ199">
1552 <para>Issue the
<emphasis role=
"bold">vos release
</emphasis> command to clone the read/write source
1553 volume and distribute the clone to each read-only site.
<programlisting>
1554 %
<emphasis role=
"bold">vos release
</emphasis> <<replaceable>volume name or ID
</replaceable>> [
<emphasis role=
"bold">-f
</emphasis>]
1555 </programlisting></para>
1557 <para>where
<variablelist>
1559 <term><emphasis role=
"bold">rel
</emphasis></term>
1562 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">release
</emphasis>.
</para>
1567 <term><emphasis role=
"bold">volume name or ID
</emphasis></term>
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>
1577 <term><emphasis role=
"bold">-f
</emphasis></term>
1580 <para>Creates and releases a brand new clone.
</para>
1583 </variablelist></para>
1586 <listitem id=
"LIWQ200">
1587 <para><emphasis role=
"bold">(Optional)
</emphasis> Issue the
<emphasis role=
"bold">vos examine
</emphasis> command to verify
1588 that no site definition in the VLDB entry is marked with an
<computeroutput>Old release
</computeroutput> or
1589 <computeroutput>New release
</computeroutput> flag. The command is described fully in
<link linkend=
"HDRWQ221">Displaying
1590 One Volume's VLDB Entry and Volume Header
</link>.
<programlisting>
1591 %
<emphasis role=
"bold">vos examine
</emphasis> <<replaceable>volume name or ID
</replaceable>>
1592 </programlisting></para>
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
1604 <sect1 id=
"HDRWQ201">
1605 <title>Creating Backup Volumes
</title>
1608 <primary>read/write volume
</primary>
1610 <secondary>cloning
</secondary>
1612 <tertiary>for backup version
</tertiary>
1616 <primary>cloning
</primary>
1618 <secondary>for backup
</secondary>
1622 <primary>creating
</primary>
1624 <secondary>backup volume
</secondary>
1628 <primary>volume
</primary>
1630 <secondary>backup
</secondary>
1632 <see>backup volume
</see>
1636 <primary>backup volume
</primary>
1638 <secondary>creating
</secondary>
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>
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>
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>
1657 </itemizedlist></para>
1660 <primary>creating
</primary>
1662 <secondary>multiple backup volumes at once
</secondary>
1666 <primary>volume
</primary>
1668 <secondary>creating backup version of many at once
</secondary>
1672 <primary>backup volume
</primary>
1674 <secondary>creating multiple at once
</secondary>
1677 <sect2 id=
"HDRWQ202">
1678 <title>Backing Up Multiple Volumes at Once
</title>
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>
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>
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>
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>
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>
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>
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>
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>
1729 </itemizedlist></para>
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>
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>
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:
1747 <emphasis role=
"bold">-prefix '^.*aix'
</emphasis>
1748 </programlisting></para>
1750 </orderedlist></para>
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>
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>
1760 <primary>automating
</primary>
1762 <secondary>creation of backup volumes
</secondary>
1766 <primary>backup volume
</primary>
1768 <secondary>automating creation of
</secondary>
1772 <primary>volume
</primary>
1774 <secondary>automating creation of backup version
</secondary>
1778 <primary>backup volume
</primary>
1780 <secondary>suggested schedule for creation of
</secondary>
1784 <primary>scheduling
</primary>
1786 <secondary>creation of backup volumes
</secondary>
1790 <primary>cron-type server process
</primary>
1792 <secondary>used to automate volume backup
</secondary>
1796 <sect2 id=
"HDRWQ203">
1797 <title>Automating Creation of Backup Volumes
</title>
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
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>
1808 <para>The following example command creates a
<emphasis role=
"bold">cron
</emphasis> process called
<emphasis
1809 role=
"bold">backupusers
</emphasis> in the
<emphasis role=
"bold">/usr/afs/local/BosConfig
</emphasis> file on the machine
1810 <emphasis role=
"bold">fs3.example.com
</emphasis>. The process runs every day at
1:
00 a.m. to create a backup version of every
1811 volume in the cell whose name starts with the string
<emphasis role=
"bold">user
</emphasis>. The
<emphasis
1812 role=
"bold">-localauth
</emphasis> flag enables the process to invoke the privileged
<emphasis role=
"bold">vos
1813 backupsys
</emphasis> command while unauthenticated. Note that the
<emphasis role=
"bold">-cmd
</emphasis> argument specifies a
1814 complete pathname for the
<emphasis role=
"bold">vos
</emphasis> binary, because the PATH environment variable for the BOS
1815 Server (running as the local superuser
<emphasis role=
"bold">root
</emphasis>) generally does not include the path to AFS
1816 binaries.
<programlisting>
1817 %
<emphasis role=
"bold">bos create fs3.example.com backupusers cron
</emphasis>\
1818 <emphasis role=
"bold">-cmd
"/usr/afs/bin/vos backupsys -prefix user -localauth" "1:00"</emphasis>
1819 </programlisting></para>
1822 <primary>mounting
</primary>
1824 <secondary>backup volume
</secondary>
1828 <primary>backup volume
</primary>
1830 <secondary>mounting
</secondary>
1834 <primary>OldFiles directory
</primary>
1836 <secondary>as mount point for backup volume
</secondary>
1840 <sect2 id=
"HDRWQ204">
1841 <title>Making the Contents of Backup Volumes Available to Users
</title>
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
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
1859 <sect2 id=
"HDRWQ205">
1860 <title>To create and mount a backup volume
</title>
1864 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
1865 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
1866 display the users in the UserList file
</link>.
<programlisting>
1867 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
1868 </programlisting></para>
1872 <para>Verify that you have the
<emphasis role=
"bold">insert
</emphasis>(
<emphasis role=
"bold">i
</emphasis>) and
<emphasis
1873 role=
"bold">administer
</emphasis>(
<emphasis role=
"bold">a
</emphasis>) permissions on the ACL of the directory in which
1874 you wish to mount the volume. If necessary, issue the
<emphasis role=
"bold">fs listacl
</emphasis> command, which is fully
1875 described in
<link linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
1876 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
1877 </programlisting></para>
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>
1885 <primary>commands
</primary>
1887 <secondary>vos backup
</secondary>
1891 <primary>vos commands
</primary>
1893 <secondary>backup
</secondary>
1897 <listitem id=
"LIWQ206">
1898 <para>Issue the
<emphasis role=
"bold">vos backup
</emphasis> command to create a backup version of a
1899 read/write source volume. The message shown confirms the success of the backup operation.
<programlisting>
1900 %
<emphasis role=
"bold">vos backup
</emphasis> <<replaceable>volume name or ID
</replaceable>> Created backup volume for volume name or ID
1901 </programlisting></para>
1903 <para>where
<variablelist>
1905 <term><emphasis role=
"bold">backup
</emphasis></term>
1908 <para>Must be typed in full.
</para>
1913 <term><emphasis role=
"bold">volume name or ID
</emphasis></term>
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>
1921 </variablelist></para>
1924 <primary>commands
</primary>
1926 <secondary>fs mkmount
</secondary>
1928 <tertiary>when mounting backup volume
</tertiary>
1932 <primary>fs commands
</primary>
1934 <secondary>mkmount
</secondary>
1936 <tertiary>when mounting backup volume
</tertiary>
1940 <listitem id=
"LIWQ207">
1941 <para><emphasis role=
"bold">(Optional)
</emphasis> Issue the
<emphasis role=
"bold">fs
1942 mkmount
</emphasis> to mount the backup volume. While this step is optional, Cache Managers cannot access the volume's
1943 contents if it is not mounted.
<programlisting>
1944 %
<emphasis role=
"bold">fs mkmount
</emphasis> <<replaceable>directory
</replaceable>> <<replaceable>volume name
</replaceable>> <emphasis
1945 role=
"bold">.backup
</emphasis>
1946 </programlisting></para>
1948 <para>where
<variablelist>
1950 <term><emphasis role=
"bold">mk
</emphasis></term>
1953 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">mkmount
</emphasis>.
</para>
1958 <term><emphasis role=
"bold">directory
</emphasis></term>
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>
1968 <term><emphasis role=
"bold">volume name
</emphasis>.backup
</term>
1971 <para>Is the full name of the backup volume.
</para>
1974 </variablelist></para>
1978 <para><emphasis role=
"bold">(Optional)
</emphasis> Issue the
<emphasis role=
"bold">fs lsmount
</emphasis> command to verify
1979 that the mount point refers to the correct volume. Complete instructions appear in
<link linkend=
"HDRWQ211">To display a
1980 mount point
</link>.
<programlisting>
1981 %
<emphasis role=
"bold">fs lsmount
</emphasis> <<replaceable>directory
</replaceable>>
1982 </programlisting></para>
1987 <primary>commands
</primary>
1989 <secondary>vos backupsys
</secondary>
1993 <primary>vos commands
</primary>
1995 <secondary>backupsys
</secondary>
1999 <sect2 id=
"Header_223">
2000 <title>To create multiple backup volumes at once
</title>
2004 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
2005 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
2006 display the users in the UserList file
</link>.
<programlisting>
2007 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
2008 </programlisting></para>
2012 <para>Issue the
<emphasis role=
"bold">vos backupsys
</emphasis> command to create a backup version of every read/write
2013 volume that shares the same prefix or site. The effects of combining the three arguments are described in
<link
2014 linkend=
"HDRWQ202">Backing Up Multiple Volumes at Once
</link>.
<programlisting>
2015 %
<emphasis role=
"bold">vos backupsys
</emphasis> [
<emphasis role=
"bold">-prefix
</emphasis> <<replaceable>common prefix on volume(s)
</replaceable>>+] \
2016 [
<emphasis role=
"bold">-server
</emphasis> <<replaceable>machine name
</replaceable>>] [
<emphasis role=
"bold">-partition
</emphasis> <<replaceable>partition name
</replaceable>>] \
2017 [
<emphasis role=
"bold">-exclude
</emphasis>] [
<emphasis role=
"bold">-xprefix
</emphasis> <<replaceable>negative prefix on volume(s)
</replaceable>>+] \
2018 [
<emphasis role=
"bold">-dryrun
</emphasis>] [
<emphasis role=
"bold">-verbose
</emphasis>]
2019 </programlisting></para>
2021 <para>where
<variablelist>
2023 <term><emphasis role=
"bold">backups
</emphasis></term>
2026 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">backupsys
</emphasis>.
</para>
2031 <term><emphasis role=
"bold">-prefix
</emphasis></term>
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>
2043 <term><emphasis role=
"bold">-server
</emphasis></term>
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>
2053 <term><emphasis role=
"bold">-partition
</emphasis></term>
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>
2063 <term><emphasis role=
"bold">-exclude
</emphasis></term>
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>
2076 <term><emphasis role=
"bold">-xprefix
</emphasis></term>
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>
2089 <term><emphasis role=
"bold">-dryrun
</emphasis></term>
2092 <para>Displays on the standard output stream a list of the volumes to be cloned, without actually cloning
2098 <term><emphasis role=
"bold">-verbose
</emphasis></term>
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>
2106 </variablelist></para>
2112 <sect1 id=
"HDRWQ208">
2113 <title>Mounting Volumes
</title>
2116 <primary>mounting
</primary>
2118 <secondary>volume
</secondary>
2120 <tertiary>general instructions
</tertiary>
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>
2128 <sect2 id=
"HDRWQ209">
2129 <title>The Rules of Mount Point Traversal
</title>
2131 <para>The Cache Manager observes three basic rules as it traverses the AFS filespace and encounters mount points:
2134 <para><emphasis role=
"bold">Rule
1:
</emphasis> Access Backup and Read-only Volumes When Specified
</para>
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>
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>
2146 <para><emphasis role=
"bold">Rule
2:
</emphasis> Follow the Read-only Path When Possible
</para>
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>
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>
2165 <para><emphasis role=
"bold">Rule
3:
</emphasis> Once on a Read/write Path, Stay There
</para>
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>
2175 </itemizedlist></para>
2178 <sect2 id=
"HDRWQ210">
2179 <title>The Three Types of Mount Points
</title>
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>
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>
2188 <primary>regular mount point
</primary>
2190 <secondary></secondary>
2192 <see>mount point
</see>
2196 <primary>mount point
</primary>
2198 <secondary>regular
</secondary>
2200 <tertiary>described
</tertiary>
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>
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>
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>
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
2230 <primary>read/write mount point
</primary>
2232 <secondary></secondary>
2234 <see>mount point
</see>
2238 <primary>mount point
</primary>
2240 <secondary>read/write
</secondary>
2242 <tertiary>described
</tertiary>
2245 <para>It is conventional to create only one read/write mount point in a cell's filespace, using it to mount the cell's
2246 <emphasis role=
"bold">root.cell
</emphasis> volume just below the AFS filespace root (by convention,
<emphasis
2247 role=
"bold">/afs/.
</emphasis><replaceable>cellname
</replaceable>). As indicated, it is conventional to place a period at
2248 the start of the read/write mount point's name (for example,
<emphasis role=
"bold">/afs/.example.com
</emphasis>). The period
2249 distinguishes the read/write mount point from the regular mount point for the
<emphasis role=
"bold">root.cell
</emphasis>
2250 volume at the same level. This is the only case in which it is conventional to create two mount points for the same
2251 volume. A desirable side effect of this naming convention for this read/write mount point is that it does not appear in
2252 the output of the UNIX
<emphasis role=
"bold">ls
</emphasis> command unless the
<emphasis role=
"bold">-a
</emphasis> flag
2253 is included, essentially hiding it from regular users who have no use for it.
</para>
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>
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>
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>
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>
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
2283 <primary>cellular mount point
</primary>
2285 <secondary></secondary>
2287 <see>mount point
</see>
2291 <primary>mount point
</primary>
2293 <secondary>cellular
</secondary>
2295 <tertiary>described
</tertiary>
2299 <primary>mounting
</primary>
2301 <secondary>foreign volume in local cell
</secondary>
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>
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>
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>
2319 </itemizedlist></para>
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>
2327 <sect2 id=
"Header_227">
2328 <title>Creating a mount point in a foreign cell
</title>
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>
2338 <sect2 id=
"HDRWQ211">
2339 <title>To display a mount point
</title>
2342 <primary>displaying
</primary>
2344 <secondary>mount point
</secondary>
2348 <primary>mount point
</primary>
2350 <secondary>displaying
</secondary>
2354 <primary>mount point
</primary>
2356 <secondary>distinguishing different types
</secondary>
2360 <primary>commands
</primary>
2362 <secondary>fs lsmount
</secondary>
2366 <primary>fs commands
</primary>
2368 <secondary>lsmount
</secondary>
2373 <para>Issue the
<emphasis role=
"bold">fs lsmount
</emphasis> command.
<programlisting>
2374 %
<emphasis role=
"bold">fs lsmount
</emphasis> <<replaceable>directory
</replaceable>>
2375 </programlisting></para>
2377 <para>where
<variablelist>
2379 <term><emphasis role=
"bold">ls
</emphasis></term>
2382 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">lsmount
</emphasis>.
</para>
2387 <term><emphasis role=
"bold">directory
</emphasis></term>
2390 <para>Names the mount point to display.
</para>
2393 </variablelist></para>
2397 <para>If the specified directory is a mount point, the output is of the following form:
</para>
2400 'directory' is a mount point for volume 'volume name'
2403 <para>For a regular mount point, a number sign (
<computeroutput>#
</computeroutput>) precedes the volume name string, as in the
2404 following example command issued on a client machine in the
<emphasis role=
"bold">example.com
</emphasis> cell.
</para>
2407 %
<emphasis role=
"bold">fs lsmount /afs/example.com/usr/terry
</emphasis>
2408 '/afs/example.com/usr/terry' is a mount point for volume '#user.terry'
2411 <para>For a read/write mount point, a percent sign (
<computeroutput>%
</computeroutput>) precedes the volume name string, as in
2412 the following example command issued on a client machine in the
<emphasis role=
"bold">example.com
</emphasis> cell. The cell's
2413 administrators have followed the convention of preceding the read/write mount point's name with a period.
</para>
2416 %
<emphasis role=
"bold">fs lsmount /afs/.example.com
</emphasis>
2417 '/afs/.example.com' is a mount point for volume '%root.cell'
2420 <para>For a cellular mount point, a cell name and colon (
<computeroutput>:
</computeroutput>) follow the number or percent sign
2421 and precede the volume name string, as in the following example command issued on a client machine in the
<emphasis
2422 role=
"bold">example.com
</emphasis> cell.
</para>
2425 %
<emphasis role=
"bold">fs lsmount /afs/example.org
</emphasis>
2426 '/afs/example.org' is a mount point for volume '#example.org:root.cell'
2429 <para>For a symbolic link to a mount point, the output is of the form shown in the following example command issued on a
2430 client machine in the
<emphasis role=
"bold">example.com
</emphasis> cell.
</para>
2433 %
<emphasis role=
"bold">fs lsmount /afs/example
</emphasis>
2434 '/afs/example' is a symbolic link, leading to a mount point for volume '#root.cell'
2437 <para>If the directory is not a mount point or is not in AFS, the output reads as follows.
</para>
2440 'directory' is not a mount point.
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>
2448 <sect2 id=
"HDRWQ212">
2449 <title>To create a regular or read/write mount point
</title>
2452 <primary>creating
</primary>
2454 <secondary>read/write or regular mount point
</secondary>
2458 <primary>mount point
</primary>
2460 <secondary>creating read/write or regular
</secondary>
2464 <primary>mount point
</primary>
2466 <secondary>regular
</secondary>
2468 <tertiary>creating
</tertiary>
2472 <primary>mount point
</primary>
2474 <secondary>read/write
</secondary>
2476 <tertiary>creating
</tertiary>
2480 <primary>commands
</primary>
2482 <secondary>fs mkmount
</secondary>
2484 <tertiary>general instructions
</tertiary>
2488 <primary>fs commands
</primary>
2490 <secondary>mkmount
</secondary>
2492 <tertiary>general instructions
</tertiary>
2497 <para>Verify that you have the
<emphasis role=
"bold">i
</emphasis>(
<emphasis role=
"bold">insert
</emphasis>) and
<emphasis
2498 role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>) permissions on the ACL of the directory where you
2499 are placing the mount point. If necessary, issue the
<emphasis role=
"bold">fs listacl
</emphasis> command, which is fully
2500 described in
<link linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
2501 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
2502 </programlisting></para>
2506 <para>Issue the
<emphasis role=
"bold">fs mkmount
</emphasis> command to create the mount point. Include the
<emphasis
2507 role=
"bold">-rw
</emphasis> flag if creating a read/write mount point.
<programlisting>
2508 %
<emphasis role=
"bold">fs mkmount
</emphasis> <<replaceable>directory
</replaceable>> <<replaceable>volume name
</replaceable>> [
<emphasis
2509 role=
"bold">-rw
</emphasis>]
2510 </programlisting></para>
2512 <para>where
<variablelist>
2514 <term><emphasis role=
"bold">mk
</emphasis></term>
2517 <para>Is the shortest acceptable abbreviation for
<emphasis role=
"bold">mkmount
</emphasis>.
</para>
2522 <term><emphasis role=
"bold">directory
</emphasis></term>
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>
2528 <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create
2529 a new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period
2530 before the cell name at the pathname's second level (for example,
<emphasis role=
"bold">/afs/.example.com
</emphasis>).
2531 For further discussion of the concept of read/write and read-only paths through the filespace, see
<link
2532 linkend=
"HDRWQ209">The Rules of Mount Point Traversal
</link>.
</para>
2537 <term><emphasis role=
"bold">volume name
</emphasis></term>
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>
2546 <term><emphasis role=
"bold">-rw
</emphasis></term>
2549 <para>Creates a read/write mount point.
</para>
2552 </variablelist></para>
2557 <sect2 id=
"HDRWQ213">
2558 <title>To create a cellular mount point
</title>
2561 <primary>creating
</primary>
2563 <secondary>cellular mount point
</secondary>
2567 <primary>mount point
</primary>
2569 <secondary>creating cellular
</secondary>
2573 <primary>mount point
</primary>
2575 <secondary>cellular
</secondary>
2577 <tertiary>creating
</tertiary>
2582 <para>Verify that you have the
<emphasis role=
"bold">i
</emphasis>(
<emphasis role=
"bold">insert
</emphasis>) and
<emphasis
2583 role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>) permissions on the ACL of the directory where you
2584 are placing the mount point. If necessary, issue the
<emphasis role=
"bold">fs listacl
</emphasis> command, which is fully
2585 described in
<link linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
2586 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
2587 </programlisting></para>
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>
2599 <para>Substitute your cell's name for cellname.
</para>
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>
2609 <para>Issue the
<emphasis role=
"bold">fs mkmount
</emphasis> command with the
<emphasis role=
"bold">-cell
</emphasis>
2610 argument to create a cellular mount point. Repeat the command for each cellular mount point as required.
<programlisting>
2611 %
<emphasis role=
"bold">fs mkmount
</emphasis> <<replaceable>directory
</replaceable>> <<replaceable>volume name
</replaceable>> <emphasis
2612 role=
"bold">-cell
</emphasis> <<replaceable>cell name
</replaceable>>
2613 </programlisting></para>
2615 <para>where
<variablelist>
2617 <term><emphasis role=
"bold">mk
</emphasis></term>
2620 <para>Is the shortest acceptable abbreviation for
<emphasis role=
"bold">mkmount
</emphasis>.
</para>
2625 <term><emphasis role=
"bold">directory
</emphasis></term>
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
2636 <term><emphasis role=
"bold">volume name
</emphasis></term>
2639 <para>Specifies the volume's full name, usually
<emphasis role=
"bold">root.cell
</emphasis> for a cellular mount
2645 <term><emphasis role=
"bold">-cell
</emphasis></term>
2648 <para>Specifies the complete Internet domain name of the cell in which the volume resides.
</para>
2651 </variablelist></para>
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>
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>
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>
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>
2682 <sect2 id=
"HDRWQ215">
2683 <title>To remove a mount point
</title>
2686 <primary>removing
</primary>
2688 <secondary>mount point
</secondary>
2692 <primary>unmounting
</primary>
2694 <secondary>volume
</secondary>
2698 <primary>mount point
</primary>
2700 <secondary>removing
</secondary>
2704 <primary>commands
</primary>
2706 <secondary>fs rmmount
</secondary>
2710 <primary>fs commands
</primary>
2712 <secondary>rmmount
</secondary>
2717 <para>Verify that you have the
<emphasis role=
"bold">d
</emphasis>(
<emphasis role=
"bold">delete
</emphasis>) permission on
2718 the ACL of the directory from which you are removing the mount point. If necessary, issue the
<emphasis role=
"bold">fs
2719 listacl
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
2720 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
2721 </programlisting></para>
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>
2730 <para>Issue the
<emphasis role=
"bold">fs rmmount
</emphasis> command to remove the mount point. The volume still exists,
2731 but its contents are inaccessible if this is the only mount point for it.
<programlisting>
2732 %
<emphasis role=
"bold">fs rmmount
</emphasis> <<replaceable>directory
</replaceable>>
2733 </programlisting></para>
2735 <para>where
<variablelist>
2737 <term><emphasis role=
"bold">rm
</emphasis></term>
2740 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">rmmount
</emphasis>.
</para>
2745 <term><emphasis role=
"bold">directory
</emphasis></term>
2748 <para>Names the mount point to remove. A partial pathname is interpreted relative to the current working
2751 <para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete
2752 a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before
2753 the cell name at the pathname's second level (for example,
<emphasis role=
"bold">/afs/.example.com
</emphasis>). For
2754 further discussion of the concept of read/write and read-only paths through the filespace, see
<link
2755 linkend=
"HDRWQ209">The Rules of Mount Point Traversal
</link>.
</para>
2758 </variablelist></para>
2764 <title>To access volumes directly by volume ID
</title>
2767 <primary>volume
</primary>
2769 <secondary>direct access
</secondary>
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>
2777 <para>This feature is available with Windows and Linux based cache
2778 managers by default. This feature is available with other Unix based
2779 cache managers when the dynamic root (-dynroot) and fake stat
2780 (-fakestat) modes are enabled.
</para>
2782 <para>Examples:
</para>
2785 <para><emphasis role=
"bold">Windows:
</emphasis>
2786 \\afs\example.com%root.cell - Access a read/write volume directly
</para>
2789 <para><emphasis role=
"bold">Windows:
</emphasis>
2790 \\afs\example.com#root.cell - Access a read-only volume directly
</para>
2793 <para><emphasis role=
"bold">Unix:
</emphasis>
2794 /afs/.:mount/example.com:root.cell - Access a read/write volume directly
</para>
2797 <para><emphasis role=
"bold">Unix:
</emphasis>
2798 /afs/.:mount/example.com:root.cell.readonly - Access a read-only volume directly
</para>
2801 <para><emphasis role=
"bold">Unix:
</emphasis>
2802 /afs/.:mount/example.com:root.cell.backup - Access a backup volume directly
</para>
2808 <sect1 id=
"HDRWQ216">
2809 <title>Displaying Information About Volumes
</title>
2812 <primary>displaying
</primary>
2814 <secondary>volume information
</secondary>
2818 <primary>volume
</primary>
2820 <secondary>displaying information about
</secondary>
2823 <para>This section explains how to display information about volumes. If you know a volume's name or volume ID number, there are
2824 commands for displaying its VLDB entry, its volume header, or both. Other commands display the name or location of the volume
2825 that contains a specified file or directory.
</para>
2827 <para>For instructions on displaying a volume's quota, see
<link linkend=
"HDRWQ234">Setting and Displaying Volume Quota and
2828 Current Size
</link>.
</para>
2830 <sect2 id=
"HDRWQ217">
2831 <title>Displaying VLDB Entries
</title>
2834 <primary>displaying
</primary>
2836 <secondary>volume's VLDB entry
</secondary>
2840 <primary>VLDB
</primary>
2842 <secondary>displaying volume entry
</secondary>
2846 <primary>volume entry (VLDB)
</primary>
2848 <secondary>displaying
</secondary>
2852 <primary>locked VLDB entry
</primary>
2854 <secondary>displaying
</secondary>
2857 <para>The
<emphasis role=
"bold">vos listvldb
</emphasis> command displays the VLDB entry for the volumes indicated by the
2858 combination of arguments you provide. The possibilities are listed here from most to least inclusive:
<itemizedlist>
2860 <para>To display every entry in the VLDB, provide no arguments. It can take a long time to generate the output,
2861 depending on the number of entries.
</para>
2865 <para>To display every VLDB entry that mentions a specific file server machine as the site of a volume, specify the
2866 machine's name with the
<emphasis role=
"bold">-server
</emphasis> argument.
</para>
2870 <para>To display every VLDB entry that mentions a certain partition on any file server machine as the site of a volume,
2871 specify the partition name with the
<emphasis role=
"bold">-partition
</emphasis> argument.
</para>
2875 <para>To display every VLDB entry that mentions a certain partition on a certain file server machine as the site of a
2876 volume, combine the
<emphasis role=
"bold">-server
</emphasis> and
<emphasis role=
"bold">-partition
</emphasis>
2881 <para>To display a single VLDB entry, specify a volume name or ID number with the
<emphasis role=
"bold">-name
</emphasis>
2886 <para>To display the VLDB entry only for volumes with locked VLDB entries, use the
<emphasis
2887 role=
"bold">-locked
</emphasis> flag with any of the site definitions mentioned previously.
</para>
2889 </itemizedlist></para>
2892 <primary>commands
</primary>
2894 <secondary>vos listvldb
</secondary>
2896 <tertiary>syntax
</tertiary>
2900 <primary>vos commands
</primary>
2902 <secondary>listvldb
</secondary>
2904 <tertiary>syntax
</tertiary>
2908 <sect2 id=
"HDRWQ218">
2909 <title>To display VLDB entries
</title>
2913 <para>Issue the
<emphasis role=
"bold">vos listvldb
</emphasis> command.
<programlisting>
2914 %
<emphasis role=
"bold">vos listvldb
</emphasis> [
<emphasis role=
"bold">-name
</emphasis> <<replaceable>volume name or ID
</replaceable>>] [
<emphasis
2915 role=
"bold">-server
</emphasis> <<replaceable>machine name
</replaceable>>] \
2916 [
<emphasis role=
"bold">-partition
</emphasis> <<replaceable>partition name
</replaceable>>] [
<emphasis role=
"bold">-locked
</emphasis>]
2917 </programlisting></para>
2919 <para>where
<variablelist>
2921 <term><emphasis role=
"bold">listvl
</emphasis></term>
2924 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">listvldb
</emphasis>.
</para>
2929 <term><emphasis role=
"bold">-name
</emphasis></term>
2932 <para>Identifies one volume either by its complete name or volume ID number. Do not combine this argument with the
2933 <emphasis role=
"bold">-server
</emphasis> or
<emphasis role=
"bold">-partition
</emphasis> arguments.
</para>
2938 <term><emphasis role=
"bold">-server
</emphasis></term>
2941 <para>Specifies a file server machine. Combine this argument with the
<emphasis role=
"bold">-partition
</emphasis>
2942 argument if desired, but not with the
<emphasis role=
"bold">-name
</emphasis> argument.
</para>
2947 <term><emphasis role=
"bold">-partition
</emphasis></term>
2950 <para>Specifies a partition. Combine this argument with the
<emphasis role=
"bold">-server
</emphasis> argument if
2951 desired, but not with the
<emphasis role=
"bold">-name
</emphasis> argument.
</para>
2956 <term><emphasis role=
"bold">-locked
</emphasis></term>
2959 <para>Displays only locked VLDB entries. Combine this flag with any of the other options.
</para>
2962 </variablelist></para>
2966 <para>The VLDB entry for each volume includes the following information:
<itemizedlist>
2968 <para>The base (read/write) volume name. The read-only and backup versions have the same name with a
<emphasis
2969 role=
"bold">.readonly
</emphasis> and
<emphasis role=
"bold">.backup
</emphasis> extension, respectively.
</para>
2973 <para>The volume ID numbers allocated to the versions of the volume that actually exist, in fields labeled
2974 <computeroutput>RWrite
</computeroutput> for the read/write,
<computeroutput>ROnly
</computeroutput> for the read-only,
2975 <computeroutput>Backup
</computeroutput> for the backup, and
<computeroutput>RClone
</computeroutput> for the
2976 ReleaseClone. (If a field does not appear, the corresponding version of the volume does not exist.) The appearance of
2977 the
<computeroutput>RClone
</computeroutput> field normally indicates that a release operation did not complete
2978 successfully; the
<computeroutput>Old release
</computeroutput> and
<computeroutput>New release
</computeroutput> flags
2979 often also appear on one or more of the site definition lines described just following.
</para>
2982 <primary>site
</primary>
2984 <secondary>count in VLDB
</secondary>
2988 <primary>VLDB
</primary>
2990 <secondary>site count for volume
</secondary>
2995 <para>The number of sites that house a read/write or read-only copy of the volume, following the string
2996 <computeroutput>number of sites -
></computeroutput>.
</para>
2999 <primary>type flag for volume
</primary>
3001 <secondary>VLDB entry
</secondary>
3005 <primary>VLDB
</primary>
3007 <secondary>volume type flags
</secondary>
3011 <primary>release
</primary>
3013 <secondary>status flags on site definitions in VLDB entry
</secondary>
3017 <primary>VLDB
</primary>
3019 <secondary>release status flags in volume entry
</secondary>
3023 <primary>status flag
</primary>
3025 <secondary>release, on site definitions in VLDB entry
</secondary>
3030 <para>A line for each site that houses a read/write or read-only copy of the volume, specifying the file server machine,
3031 partition, and type of volume (
<computeroutput>RW
</computeroutput> for read/write or
<computeroutput>RO
</computeroutput>
3032 for read-only). If a backup version exists, it is understood to share the read/write site. Several flags can appear with
3033 a site definition:
<variablelist>
3035 <primary>Not released
</primary>
3037 <secondary>status flag on site definition in VLDB entry
</secondary>
3041 <term><computeroutput>Not released
</computeroutput></term>
3044 <para>Indicates that the
<emphasis role=
"bold">vos release
</emphasis> command has not been issued since the
3045 <emphasis role=
"bold">vos addsite
</emphasis> command was used to define the read-only site.
</para>
3048 <primary>Old release
</primary>
3050 <secondary>status flag on site definition in VLDB entry
</secondary>
3056 <term><computeroutput>Old release
</computeroutput></term>
3059 <para>Indicates that a
<emphasis role=
"bold">vos release
</emphasis> command did not complete successfully,
3060 leaving the previous, obsolete version of the volume at this site.
</para>
3063 <primary>New release
</primary>
3065 <secondary>status flag on site definition in VLDB entry
</secondary>
3071 <term><computeroutput>New release
</computeroutput></term>
3074 <para>Indicates that a
<emphasis role=
"bold">vos release
</emphasis> command did not complete successfully, but
3075 that this site did receive the correct new version of the volume.
</para>
3078 </variablelist></para>
3082 <para>If the VLDB entry is locked, the string
<computeroutput>Volume is currently LOCKED
</computeroutput>.
</para>
3084 </itemizedlist></para>
3086 <para>For further discussion of the
<computeroutput>New release
</computeroutput> and
<computeroutput>Old
3087 release
</computeroutput> flags, see
<link linkend=
"HDRWQ192">Replicating Volumes (Creating Read-only Volumes)
</link>.
</para>
3089 <para>An example of this command and its output for a single volume:
</para>
3092 %
<emphasis role=
"bold">vos listvldb user.terry
</emphasis>
3094 RWrite:
50489902 Backup:
50489904
3095 number of sites -
> 1
3096 server fs3.example.com partition /vicepc RW Site
3100 <sect2 id=
"HDRWQ219">
3101 <title>Displaying Volume Headers
</title>
3104 <primary>displaying
</primary>
3106 <secondary>volume header
</secondary>
3110 <primary>volume header
</primary>
3112 <secondary>displaying
</secondary>
3114 <tertiary>only
</tertiary>
3117 <para>The
<emphasis role=
"bold">vos listvol
</emphasis> command displays the volume header for every volume on one or all
3118 partitions on a file server machine. The
<emphasis role=
"bold">vos
</emphasis> command interpreter obtains the information from
3119 the Volume Server on the specified machine. You can control the amount of information displayed by including one of the
3120 <emphasis role=
"bold">-fast
</emphasis>, the
<emphasis role=
"bold">-long
</emphasis>, or the
<emphasis
3121 role=
"bold">-extended
</emphasis> flags described following the instructions in
<link linkend=
"HDRWQ220">To display volume
3122 headers
</link>.
</para>
3124 <para>To display a single volume's volume header of one volume only, use the
<emphasis role=
"bold">vos examine
</emphasis>
3125 command as described in
<link linkend=
"HDRWQ221">Displaying One Volume's VLDB Entry and Volume Header
</link>.
</para>
3128 <primary>commands
</primary>
3130 <secondary>vos listvol
</secondary>
3132 <tertiary>syntax
</tertiary>
3136 <primary>vos commands
</primary>
3138 <secondary>listvol
</secondary>
3140 <tertiary>syntax
</tertiary>
3144 <sect2 id=
"HDRWQ220">
3145 <title>To display volume headers
</title>
3149 <para>Issue the
<emphasis role=
"bold">vos listvol
</emphasis> command.
<programlisting>
3150 %
<emphasis role=
"bold">vos listvol
</emphasis> <<replaceable>machine name
</replaceable>> [
<<replaceable>partition name
</replaceable>>] [
<emphasis
3151 role=
"bold">-fast
</emphasis>] [
<emphasis role=
"bold">-long
</emphasis>] [
<emphasis role=
"bold">-extended
</emphasis>]
3152 </programlisting></para>
3154 <para>where
<variablelist>
3156 <term><emphasis role=
"bold">listvo
</emphasis></term>
3159 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">listvol
</emphasis>.
</para>
3164 <term><emphasis role=
"bold">machine name
</emphasis></term>
3167 <para>Names the file server machine for which to display volume headers. Provide this argument alone or with the
3168 partition name argument.
</para>
3173 <term><emphasis role=
"bold">partition name
</emphasis></term>
3176 <para>Names one partition on the file server machine named by the machine name argument, which must be provided
3177 along with this one.
</para>
3182 <term><emphasis role=
"bold">-fast
</emphasis></term>
3185 <para>Displays only the volume ID numbers of relevant volumes. Do not combine this flag with the
<emphasis
3186 role=
"bold">-long
</emphasis> or
<emphasis role=
"bold">-extended
</emphasis> flag.
</para>
3191 <term><emphasis role=
"bold">-long
</emphasis></term>
3194 <para>Displays more detailed information about each volume. Do not combine this flag with the
<emphasis
3195 role=
"bold">-fast
</emphasis> or
<emphasis role=
"bold">-extended
</emphasis> flag.
</para>
3200 <term><emphasis role=
"bold">-extended
</emphasis></term>
3203 <para>Displays all of the information displayed by the
<emphasis role=
"bold">-long
</emphasis> flag, plus tables of
3204 statistics about reads and writes to the files in the volume. Do not combine this flag with the
<emphasis
3205 role=
"bold">-fast
</emphasis> or
<emphasis role=
"bold">-long
</emphasis> flag.
</para>
3208 </variablelist></para>
3212 <para>The output is ordered alphabetically by volume name and by default provides the following information on a single line
3213 for each volume:
<itemizedlist>
3219 <para>Volume ID number
</para>
3222 <primary>type flag for volume
</primary>
3224 <secondary>volume header
</secondary>
3229 <para>Type (the flag is
<computeroutput>RW
</computeroutput> for read/write,
<computeroutput>RO
</computeroutput> for
3230 read-only,
<computeroutput>BK
</computeroutput> for backup)
</para>
3234 <para>Size in kilobytes (
<computeroutput>1024</computeroutput> equals a megabyte)
</para>
3238 <para>Number of files in the volume, if the
<emphasis role=
"bold">-extended
</emphasis> flag is provided
</para>
3241 <primary>status flags in volume header
</primary>
3246 <para>Status on the file server machine, which is one of the following:
<variablelist>
3248 <primary>On-line status flag in volume header
</primary>
3252 <term><computeroutput>On-line
</computeroutput></term>
3255 <para>The volume is completely accessible to Cache Managers.
</para>
3258 <primary>Off-line status flag in volume header
</primary>
3264 <term><computeroutput>Off-line
</computeroutput></term>
3267 <para>The volume is not accessible to Cache Managers, but does not seem to be corrupted. This status appears
3268 while a volume is being dumped, for example.
</para>
3271 <primary>needs salvage status flag in volume header
</primary>
3277 <term><computeroutput>Off-line**needs salvage**
</computeroutput></term>
3280 <para>The volume is not accessible to Cache Managers, because it seems to be corrupted. Use the
<emphasis
3281 role=
"bold">bos salvage
</emphasis> or
<emphasis role=
"bold">salvager
</emphasis> command to repair the
3285 </variablelist></para>
3287 </itemizedlist></para>
3289 <para>If the following message appears instead of the previously listed information, it indicates that a volume is not
3290 accessible to Cache Managers or the
<emphasis role=
"bold">vos
</emphasis> command interpreter, for example because a clone is
3291 being created.
</para>
3294 **** Volume volume_ID is busy ****
3297 <para>If the following message appears instead of the previously listed information, it indicates that the File Server is
3298 unable to attach the volume, perhaps because it is seriously corrupted. The
<emphasis role=
"bold">FileLog
</emphasis> and
3299 <emphasis role=
"bold">VolserLog
</emphasis> log files in the
<emphasis role=
"bold">/usr/afs/logs
</emphasis> directory on the
3300 file server machine possibly provide additional information; use the
<emphasis role=
"bold">bos getlog
</emphasis> command to
3301 display them.
</para>
3304 **** Could not attach volume volume_ID ****
3307 <para>(For instructions on salvaging a corrupted or unattached volume, see
<link linkend=
"HDRWQ232">Salvaging
3308 Volumes
</link>.)
</para>
3310 <para>The information about individual volumes is bracketed by summary lines. The first line of output specifies the number of
3311 volumes in the listing. The last line of output summarizes the number of volumes that are online, offline, and busy, as in the
3312 following example:
</para>
3315 %
<emphasis role=
"bold">vos listvol fs2.example.com /vicepb
</emphasis>
3316 Total number of volumes on server fs2.example.com \
3317 partition /vicepb :
66
3318 sys
1969534847 RW
1582 K On-line
3319 sys.backup
1969535105 BK
1582 K On-line
3322 user.pat
1969534536 RW
17518 K On-line
3323 user.pat.backup
1969534538 BK
17537 K On-line
3324 Total volumes onLine
66 ; Total volumes offLine
0 ; Total busy
0
3327 <para><emphasis role=
"bold">Output with the -fast Flag
</emphasis></para>
3330 <primary>vos commands
</primary>
3332 <secondary>listvol
</secondary>
3334 <tertiary>output with -fast flag
</tertiary>
3337 <para>If you include the
<emphasis role=
"bold">-fast
</emphasis> flag displays only the volume ID number of each volume,
3338 arranged in increasing numerical order, as in the following example. The final line (which summarizes the number of on-line,
3339 off-line, and busy volumes) is omitted.
</para>
3342 %
<emphasis role=
"bold">vos listvol fs3.example.com /vicepa -f
</emphasis>
3343 Total number of volumes on server fs3.example.com \
3344 partition /vicepa:
37
3353 <para><emphasis role=
"bold">Output with the -long Flag
</emphasis></para>
3356 <primary>vos commands
</primary>
3358 <secondary>listvol
</secondary>
3360 <tertiary>output with -long flag
</tertiary>
3363 <para>When you include the
<emphasis role=
"bold">-long
</emphasis> flag, , the output for each volume includes all of the
3364 information in the default listing plus the following. Each item in this list corresponds to a separate line of output:
3367 <para>The file server machine and partition that house the volume, as determined by the command interpreter as the
3368 command runs, rather than derived from the VLDB or the volume header.
</para>
3371 <primary>read/write volume
</primary>
3373 <secondary>ID number in volume header
</secondary>
3377 <primary>read-only volume
</primary>
3379 <secondary>ID number in volume header
</secondary>
3383 <primary>backup volume
</primary>
3385 <secondary>ID number in volume header
</secondary>
3389 <primary>ReleaseClone volume
</primary>
3391 <secondary>ID number in volume header
</secondary>
3395 <primary>RWrite field in volume header
</primary>
3399 <primary>ROnly field in volume header
</primary>
3403 <primary>Backup field in volume header
</primary>
3407 <primary>RClone field in volume header
</primary>
3412 <para>The volume ID numbers associated with the various versions of the volume: read/write
3413 (
<computeroutput>RWrite
</computeroutput>), read-only (
<computeroutput>ROnly
</computeroutput>), backup
3414 (
<computeroutput>Backup
</computeroutput>), and ReleaseClone (
<computeroutput>RClone
</computeroutput>). One of them
3415 matches the volume ID number that appears on the first line of the volume's output. If the value in the
3416 <computeroutput>RWrite
</computeroutput>,
<computeroutput>ROnly
</computeroutput>, or
3417 <computeroutput>Backup
</computeroutput> field is
<computeroutput>0</computeroutput> (zero), there is no volume of that
3418 type. If there is currently no ReleaseClone, the
<computeroutput>RClone
</computeroutput> field does not appear at
3422 <primary>volume quota
</primary>
3424 <secondary>recorded in volume header
</secondary>
3428 <primary>MaxQuota field in volume header
</primary>
3433 <para>The maximum space quota allotted to the read/write copy of the volume, expressed in kilobyte blocks in the
3434 <computeroutput>MaxQuota
</computeroutput> field.
</para>
3437 <primary>creation date
</primary>
3439 <secondary>recorded in volume header
</secondary>
3443 <primary>volume
</primary>
3445 <secondary>Creation date in volume header
</secondary>
3450 <para>The date and time the volume was created, in the
<computeroutput>Creation
</computeroutput> field. If the volume
3451 has been restored with the
<emphasis role=
"bold">backup diskrestore
</emphasis>,
<emphasis role=
"bold">backup
3452 volrestore
</emphasis>, or
<emphasis role=
"bold">vos restore
</emphasis> command, this is the restore time.
</para>
3455 <primary>update date
</primary>
3457 <secondary>recorded in volume header
</secondary>
3461 <primary>volume
</primary>
3463 <secondary>Last Update date in volume header
</secondary>
3468 <para>The date and time when the contents of the volume last changed, in the
<computeroutput>Last
3469 Update
</computeroutput> field. For read-only and backup volumes, it matches the timestamp in the
3470 <computeroutput>Creation
</computeroutput> field.
</para>
3473 <primary>access
</primary>
3475 <secondary>count, in volume header
</secondary>
3479 <primary>volume
</primary>
3481 <secondary>counter in header for number of accesses
</secondary>
3486 <para>The number of times the volume has been accessed for a fetch or store operation since the later of the two
3487 following times:
<itemizedlist>
3489 <para>12:
00 a.m. on the day the command is issued
</para>
3493 <para>The last time the volume changed location
</para>
3495 </itemizedlist></para>
3497 </itemizedlist></para>
3499 <para>An example of the output when the
<emphasis role=
"bold">-long
</emphasis> flag is included:
</para>
3502 %
<emphasis role=
"bold">vos listvol fs2.example.com b -long
</emphasis>
3503 Total number of volumes on server fs2.example.com
3504 partition /vicepb:
66
3507 user.pat
1969534536 RW
17518 K On-line
3508 fs2.example.com /vicepb
3509 RWrite
1969534536 ROnly
0 Backup
1969534538
3511 Creation Mon Jun
12 09:
02:
25 1989
3512 Last Update Thu Jan
4 17:
39:
34 1990
3513 1573 accesses in the past day (i.e., vnode references)
3514 user.pat.backup
1969534538 BK
17537 K On-line
3515 fs2.example.com /vicepb
3516 RWrite
1969534536 ROnly
0 Backup
1969534538
3518 Creation Fri Jan
5 06:
37:
59 1990
3519 Last Update Fri Jan
5 06:
37:
59 1990
3520 0 accesses in the past day (i.e., vnode references)
3523 Total volumes onLine
66 ; Total volumes offLine
0 ; Total busy
0
3526 <para><emphasis role=
"bold">Output with the -extended Flag
</emphasis></para>
3529 <primary>vos commands
</primary>
3531 <secondary>listvol
</secondary>
3533 <tertiary>output with -extended flag
</tertiary>
3536 <para>When you include the
<emphasis role=
"bold">-extended
</emphasis> flag, the output for each volume includes all of the
3537 information reported with the
<emphasis role=
"bold">-long
</emphasis> flag, plus two tables of statistics:
<itemizedlist>
3539 <para>The table labeled
<computeroutput>Raw Read/Write Stats
</computeroutput> table summarizes the number of times the
3540 volume has been accessed for reading or writing.
</para>
3544 <para>The table labeled
<computeroutput>Writes Affecting Authorship
</computeroutput> table contains information on
3545 writes made to files and directories in the specified volume.
</para>
3547 </itemizedlist></para>
3549 <para>An example of the output when the
<emphasis role=
"bold">-extended
</emphasis> flag is included:
</para>
3552 %
<emphasis role=
"bold">vos listvol fs3.example.com a -extended
</emphasis>
3553 common.bboards
1969535592 RW
23149 K used
9401 files On-line
3554 fs3.example.com /vicepa
3555 RWrite
1969535592 ROnly
0 Backup
1969535594
3557 Creation Mon Mar
8 14:
26:
05 1999
3558 Last Update Mon Apr
26 09:
20:
43 1999
3559 11533 accesses in the past day (i.e., vnode references)
3560 Raw Read/Write Stats
3561 |-------------------------------------------|
3562 | Same Network | Diff Network |
3563 |----------|----------|----------|----------|
3564 | Total | Auth | Total | Auth |
3565 |----------|----------|----------|----------|
3566 Reads |
151 |
151 |
1092 |
1068 |
3567 Writes |
3 |
3 |
324 |
324 |
3568 |-------------------------------------------|
3569 Writes Affecting Authorship
3570 |-------------------------------------------|
3571 | File Authorship | Directory Authorship|
3572 |----------|----------|----------|----------|
3573 | Same | Diff | Same | Diff |
3574 |----------|----------|----------|----------|
3575 0-
60 sec |
92 |
0 |
100 |
4 |
3576 1-
10 min |
1 |
0 |
14 |
6 |
3577 10min-
1hr |
0 |
0 |
19 |
4 |
3578 1hr-
1day |
1 |
0 |
13 |
0 |
3579 1day-
1wk |
1 |
0 |
1 |
0 |
3580 > 1wk |
0 |
0 |
0 |
0 |
3581 |-------------------------------------------|
3585 <sect2 id=
"HDRWQ221">
3586 <title>Displaying One Volume's VLDB Entry and Volume Header
</title>
3589 <primary>displaying
</primary>
3591 <secondary>VLDB entry
</secondary>
3593 <tertiary>with volume header
</tertiary>
3597 <primary>displaying
</primary>
3599 <secondary>VLDB entry with volume header
</secondary>
3603 <primary>VLDB
</primary>
3605 <secondary>displaying entry
</secondary>
3607 <tertiary>with volume header
</tertiary>
3611 <primary>entry in VLDB
</primary>
3613 <secondary>displaying, with volume header
</secondary>
3617 <primary>displaying
</primary>
3619 <secondary>volume header
</secondary>
3621 <tertiary>with VLDB entry
</tertiary>
3625 <primary>displaying
</primary>
3627 <secondary>volume header with VLDB entry
</secondary>
3631 <primary>volume header
</primary>
3633 <secondary>displaying
</secondary>
3635 <tertiary>with VLDB entry
</tertiary>
3638 <para>The
<emphasis role=
"bold">vos examine
</emphasis> command displays information from both the VLDB and the volume header
3639 for a single volume. There is some redundancy in the information from the two sources, which allows you to compare the VLDB
3640 and volume header.
</para>
3642 <para>Because the volume header for each version of a volume (read/write, read-only, and backup) is different, you can specify
3643 which one to display. Include the
<emphasis role=
"bold">.readonly
</emphasis> or
<emphasis role=
"bold">.backup
</emphasis>
3644 extension on the volume name or ID argument as appropriate. The information from the VLDB is the same for all three
3648 <primary>commands
</primary>
3650 <secondary>vos examine
</secondary>
3652 <tertiary>basic instructions
</tertiary>
3656 <primary>vos commands
</primary>
3658 <secondary>examine
</secondary>
3660 <tertiary>basic instructions
</tertiary>
3664 <sect2 id=
"HDRWQ222">
3665 <title>To display one volume's VLDB entry and volume header
</title>
3669 <para>Issue the
<emphasis role=
"bold">vos examine
</emphasis> command.
<programlisting>
3670 %
<emphasis role=
"bold">vos examine
</emphasis> <<replaceable>volume name or ID
</replaceable>>
3671 </programlisting></para>
3673 <para>where
<variablelist>
3675 <term><emphasis role=
"bold">e
</emphasis></term>
3678 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">examine
</emphasis>.
</para>
3683 <term><emphasis role=
"bold">volume name or ID
</emphasis></term>
3686 <para>Identifies one volume either by its complete name or volume ID number. It can be a read/write, read-only, or
3687 backup type. Use the
<emphasis role=
"bold">.backup
</emphasis> or
<emphasis role=
"bold">.readonly
</emphasis>
3688 extension if appropriate.
</para>
3691 </variablelist></para>
3695 <para>The top part of the output displays the same information from a volume header as the
<emphasis role=
"bold">vos
3696 listvol
</emphasis> command with the
<emphasis role=
"bold">-long
</emphasis> flag, as described following the instructions in
3697 <link linkend=
"HDRWQ220">To display volume headers
</link>. If you specify the read-only version of the volume and it exists at
3698 more than one site, the output includes all of them. The bottom part of the output lists the same information from the VLDB as
3699 the
<emphasis role=
"bold">vos listvldb
</emphasis> command, as described following the instructions in
<link
3700 linkend=
"HDRWQ218">To display VLDB entries
</link>.
</para>
3702 <para>Below is an example for a volume whose VLDB entry is currently locked.
</para>
3705 %
<emphasis role=
"bold">vos examine user.terry
</emphasis>
3706 user.terry
536870981 RW
3459 K On-line
3707 fs3.example.com /vicepa
3708 Write
5360870981 ROnly
0 Backup
536870983
3710 Creation Mon Jun
12 15:
22:
06 1989
3711 Last Update Fri Jun
16 09:
34:
35 1989
3712 5719 accesses in the past day (i.e., vnode references)
3713 RWrite:
5360870981 Backup:
536870983
3714 number of sites -
> 1
3715 server fs3.example.com partition /vicepa RW Site
3716 Volume is currently LOCKED
3720 <sect2 id=
"HDRWQ223">
3721 <title>Displaying the Name or Location of the Volume that Contains a File
</title>
3723 <para>This section explains how to learn the name, volume ID number, or location of the volume that contains a file or
3726 <para>You can also use one piece of information about a volume (for example, its name) to obtain other information about it
3727 (for example, its location). The following list points you to the relevant instructions:
<itemizedlist>
3729 <primary>translating
</primary>
3731 <secondary>volume name to ID number
</secondary>
3735 <primary>learning
</primary>
3737 <secondary>volume ID
</secondary>
3739 <tertiary>given volume name
</tertiary>
3743 <primary>volume name
</primary>
3745 <secondary>translating
</secondary>
3747 <tertiary>to volume ID number
</tertiary>
3751 <primary>volume ID number
</primary>
3753 <secondary>learning
</secondary>
3755 <tertiary>from volume name
</tertiary>
3759 <primary>vos commands
</primary>
3761 <secondary>examine
</secondary>
3763 <tertiary>to learn volume ID
</tertiary>
3767 <primary>translating
</primary>
3769 <secondary>volume ID number to name
</secondary>
3773 <primary>learning
</primary>
3775 <secondary>volume name
</secondary>
3777 <tertiary>given volume ID number
</tertiary>
3781 <primary>volume name
</primary>
3783 <secondary>learning
</secondary>
3785 <tertiary>from volume ID number
</tertiary>
3789 <primary>volume ID number
</primary>
3791 <secondary>translating
</secondary>
3793 <tertiary>to volume name
</tertiary>
3797 <primary>vos commands
</primary>
3799 <secondary>examine
</secondary>
3801 <tertiary>to learn volume name
</tertiary>
3805 <para>To use a volume's name to learn the volume ID numbers of all its existing versions, use the
<emphasis
3806 role=
"bold">vos examine
</emphasis> command as described in
<link linkend=
"HDRWQ222">To display one volume's VLDB entry
3807 and volume header
</link>.
</para>
3809 <para>You can also use the command to learn a volume's name by providing its ID number.
</para>
3813 <para>To use a volume's name or ID number to learn its location, use the
<emphasis role=
"bold">vos listvldb
</emphasis>
3814 command as described in
<link linkend=
"HDRWQ218">To display VLDB entries
</link>.
</para>
3817 <primary>translating
</primary>
3819 <secondary>volume name/ID number to volume location
</secondary>
3823 <primary>learning
</primary>
3825 <secondary>volume location
</secondary>
3827 <tertiary>given volume name/ID number
</tertiary>
3831 <primary>volume name
</primary>
3833 <secondary>translating
</secondary>
3835 <tertiary>to volume location
</tertiary>
3839 <primary>volume ID number
</primary>
3841 <secondary>translating
</secondary>
3843 <tertiary>to volume location
</tertiary>
3847 <primary>volume location
</primary>
3849 <secondary>learning from volume name/ID number
</secondary>
3853 <primary>vos commands
</primary>
3855 <secondary>listvldb
</secondary>
3857 <tertiary>to learn volume location
</tertiary>
3860 </itemizedlist></para>
3863 <primary>translating
</primary>
3865 <secondary>directory/file name to volume name
</secondary>
3869 <primary>learning
</primary>
3871 <secondary>volume name
</secondary>
3873 <tertiary>given directory/file name
</tertiary>
3877 <primary>directory/file name
</primary>
3879 <secondary>translating to volume name
</secondary>
3883 <primary>volume name
</primary>
3885 <secondary>learning
</secondary>
3887 <tertiary>from directory/file name
</tertiary>
3891 <primary>commands
</primary>
3893 <secondary>fs listquota
</secondary>
3897 <primary>fs commands
</primary>
3899 <secondary>listquota
</secondary>
3902 <sect3 id=
"HDRWQ224">
3903 <title>To display the name of the volume that contains a file
</title>
3907 <para>Issue the
<emphasis role=
"bold">fs listquota
</emphasis> command.
<programlisting>
3908 %
<emphasis role=
"bold">fs listquota
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
3909 </programlisting></para>
3911 <para>where
<variablelist>
3913 <term><emphasis role=
"bold">lq
</emphasis></term>
3916 <para>Is an acceptable alias for
<emphasis role=
"bold">listquota
</emphasis>(and
<emphasis
3917 role=
"bold">listq
</emphasis> the shortest acceptable abbreviation).
</para>
3922 <term><emphasis role=
"bold">dir/file path
</emphasis></term>
3925 <para>Names a directory or file housed in the volume for which to display the name. Partial pathnames are
3926 interpreted relative to the current working directory, which is the default if this argument is omitted.
</para>
3929 </variablelist></para>
3933 <para>The following is an example of the output:
</para>
3936 %
<emphasis role=
"bold">fs listquota /afs/example.com/usr/terry
</emphasis>
3937 Volume Name Quota Used % Used Partition
3938 user.terry
15000 5071 34%
86%
3942 <primary>translating
</primary>
3944 <secondary>directory/file name to volume ID number
</secondary>
3948 <primary>learning
</primary>
3950 <secondary>volume ID
</secondary>
3952 <tertiary>given directory/file name
</tertiary>
3956 <primary>directory/file name
</primary>
3958 <secondary>translating to volume ID number
</secondary>
3962 <primary>volume ID number
</primary>
3964 <secondary>learning from directory/file name
</secondary>
3968 <primary>commands
</primary>
3970 <secondary>fs examine
</secondary>
3974 <primary>fs commands
</primary>
3976 <secondary>examine
</secondary>
3980 <sect3 id=
"HDRWQ225">
3981 <title>To display the ID number of the volume that contains a file
</title>
3985 <para>Issue the
<emphasis role=
"bold">fs examine
</emphasis> command.
<programlisting>
3986 %
<emphasis role=
"bold">fs examine
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
3987 </programlisting></para>
3989 <para>where
<variablelist>
3991 <term><emphasis role=
"bold">exa
</emphasis></term>
3994 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">examine
</emphasis>.
</para>
3999 <term><emphasis role=
"bold">dir/file path
</emphasis></term>
4002 <para>Names a directory or file housed in the volume for which to display the volume ID. Partial pathnames are
4003 interpreted relative to the current working directory, which is the default if this argument is omitted.
</para>
4006 </variablelist></para>
4010 <para>The following example illustrates how the output reports the volume ID number in the
4011 <computeroutput>vid
</computeroutput> field.
</para>
4014 %
<emphasis role=
"bold">fs examine /afs/example.com/usr/terry
</emphasis>
4015 Volume status for vid =
50489902 named user.terry
4016 Current maximum quota is
15000
4017 Current blocks used are
5073
4018 The partition has
46383 blocks available out of
333305
4022 <para>The partition-related statistics in this command's output do not always agree with the corresponding values in the
4023 output of the standard UNIX
<emphasis role=
"bold">df
</emphasis> command. The statistics reported by this command can be up
4024 to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency. Also, on
4025 some operating systems, the
<emphasis role=
"bold">df
</emphasis> command's report of partition size includes reserved space
4026 not included in this command's calculation, and so is likely to be about
10% larger.
</para>
4030 <primary>translating
</primary>
4032 <secondary>directory/file name to volume location
</secondary>
4036 <primary>learning
</primary>
4038 <secondary>volume location
</secondary>
4040 <tertiary>given directory/file name
</tertiary>
4044 <primary>directory/file name
</primary>
4046 <secondary>translating to volume location
</secondary>
4050 <primary>volume location
</primary>
4052 <secondary>learning from directory/file name
</secondary>
4056 <primary>volume
</primary>
4058 <secondary>location
</secondary>
4060 <see>volume location
</see>
4064 <primary>commands
</primary>
4066 <secondary>fs whereis
</secondary>
4070 <primary>fs commands
</primary>
4072 <secondary>whereis
</secondary>
4076 <sect3 id=
"Header_242">
4077 <title>To display the location of the volume that contains a file
</title>
4081 <para>Issue the
<emphasis role=
"bold">fs whereis
</emphasis> command to display the name of the file server machine that
4082 houses the volume containing a file or directory.
<programlisting>
4083 %
<emphasis role=
"bold">fs whereis
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
4084 </programlisting></para>
4086 <para>where
<variablelist>
4088 <term><emphasis role=
"bold">whe
</emphasis></term>
4091 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">whereis
</emphasis>.
</para>
4096 <term><emphasis role=
"bold">dir/file path
</emphasis></term>
4099 <para>Names a directory or file for which to report the location. Partial pathnames are interpreted relative to
4100 the current working directory, which is the default if this argument is omitted.
</para>
4103 </variablelist></para>
4105 <para>The output displays the file server machine that houses the volume containing the file, as in the following
4109 %
<emphasis role=
"bold">fs whereis /afs/example.com/user/terry
</emphasis>
4110 File /afs/example.com/usr/terry is on host fs2.example.com
4115 <para>If you also want to know which partition houses the volume, first issue the
<emphasis role=
"bold">fs
4116 listquota
</emphasis> command to display the volume's name. For complete syntax, see
<link linkend=
"HDRWQ224">To display
4117 the name of the volume that contains a file
</link>.
<programlisting>
4118 %
<emphasis role=
"bold">fs listquota
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
4119 </programlisting></para>
4121 <para>Then issue the
<emphasis role=
"bold">vos listvldb
</emphasis> command, providing the volume name as the volume name
4122 or ID argument. For complete syntax and a description of the output, see
<link linkend=
"HDRWQ218">To display VLDB
4123 entries
</link>.
</para>
4126 %
<emphasis role=
"bold">vos listvldb
</emphasis> <<replaceable>volume name or ID
</replaceable>>
4134 <sect1 id=
"HDRWQ226">
4135 <title>Moving Volumes
</title>
4138 <primary>moving
</primary>
4140 <secondary>volume
</secondary>
4144 <primary>volume
</primary>
4146 <secondary>moving
</secondary>
4149 <para>There are three main reasons to move volumes:
<itemizedlist>
4151 <para>To place volumes on other partitions or machines temporarily while repairing or replacing a disk or file server
4157 <primary>disk partition
</primary>
4159 <secondary>moving volumes to reduce overcrowding
</secondary>
4160 </indexterm> <indexterm>
4161 <primary>overcrowding of disk partition
</primary>
4163 <secondary>moving volumes to reduce
</secondary>
4164 </indexterm> <indexterm>
4165 <primary>overcrowding of disk partition
</primary>
4167 <secondary>effect on users
</secondary>
4168 </indexterm> <indexterm>
4169 <primary>failure
</primary>
4171 <secondary>of file storage due to full partition
</secondary>
4172 </indexterm> <indexterm>
4173 <primary>file storage
</primary>
4175 <secondary>failed due to partition crowding
</secondary>
4176 </indexterm> To free space on a partition that is becoming overcrowded. One symptom of overcrowding is that users cannot
4177 to save files even though the relevant volume is below its quota. The following error message confirms the problem:
4179 afs: failed to store file (partition full)
4180 </programlisting></para>
4182 <para>You can track available space on AFS server partitions by using the
<emphasis role=
"bold">scout
</emphasis> or
4183 <emphasis role=
"bold">afsmonitor
</emphasis> programs described in
<link linkend=
"HDRWQ323">Monitoring and Auditing AFS
4184 Performance
</link>.
</para>
4188 <para>A file server machine is becoming overloaded because it houses many more volumes than other machines of the same
4189 size, or has volumes with more popular files in them.
</para>
4191 </itemizedlist></para>
4194 <primary>read/write volume
</primary>
4196 <secondary>moving
</secondary>
4200 <primary>backup volume
</primary>
4202 <secondary>removed by read/write move
</secondary>
4205 <para>To move a read/write volume, use the
<emphasis role=
"bold">vos move
</emphasis> command as described in the following
4206 instructions. Before attempting to move the volume, the
<emphasis role=
"bold">vos
</emphasis> command interpreter verifies that
4207 there is enough free space for it on the destination partition. If not, it does not attempt the move operation and prints the
4208 following message.
</para>
4211 vos: no space on target partition destination_part to move volume volume
4214 <para>To move a read-only volume, you actually remove the volume from the current site by issuing the
<emphasis role=
"bold">vos
4215 remove
</emphasis> command as described in
<link linkend=
"HDRWQ236">To remove a volume and unmount it
</link>. Then define a new
4216 site and release the volume to it by issuing the
<emphasis role=
"bold">vos addsite
</emphasis> and
<emphasis role=
"bold">vos
4217 release
</emphasis> commands as described in
<link linkend=
"HDRWQ194">To replicate a read/write volume (create a read-only
4218 volume)
</link>.
</para>
4221 <primary>read-only volume
</primary>
4223 <secondary>moving
</secondary>
4227 <primary>backup volume
</primary>
4229 <secondary>moving
</secondary>
4232 <para>A backup volume always resides at the same site as its read/write source volume, so you cannot move a backup volume except
4233 as part of moving the read/write source. The
<emphasis role=
"bold">vos move
</emphasis> command automatically deletes the backup
4234 version when you move a read/write volume. To create a new backup volume at the new site as soon as the move operation
4235 completes, issue the
<emphasis role=
"bold">vos backup
</emphasis> command as described in
<link linkend=
"HDRWQ205">To create and
4236 mount a backup volume
</link>.
</para>
4239 <primary>commands
</primary>
4241 <secondary>vos move
</secondary>
4243 <tertiary>basic instructions
</tertiary>
4247 <primary>vos commands
</primary>
4249 <secondary>move
</secondary>
4251 <tertiary>basic instructions
</tertiary>
4254 <sect2 id=
"Header_244">
4255 <title>To move a read/write volume
</title>
4259 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
4260 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
4261 display the users in the UserList file
</link>.
<programlisting>
4262 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
4263 </programlisting></para>
4267 <para>Issue the
<emphasis role=
"bold">vos move
</emphasis> command to move the volume. Type it on a single line; it appears
4268 on multiple lines here only for legibility.
<programlisting>
4269 %
<emphasis role=
"bold">vos move
</emphasis> <<replaceable>volume name or ID
</replaceable>> \
<<replaceable>machine name on source
</replaceable>>
4270 <<replaceable>partition name on source
</replaceable>> \
<<replaceable>machine name on destination
</replaceable>> <partition name on
4272 </programlisting></para>
4274 <para>where
<variablelist>
4276 <term><emphasis role=
"bold">m
</emphasis></term>
4279 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">move
</emphasis>.
</para>
4284 <term><emphasis role=
"bold">volume name or ID
</emphasis></term>
4287 <para>Specifies the name or volume ID number of the read/write volume to move.
</para>
4292 <term><emphasis role=
"bold">machine name on source
</emphasis></term>
4295 <para>Names the file server machine currently housing the volume.
</para>
4300 <term><emphasis role=
"bold">partition name on source
</emphasis></term>
4303 <para>Names the partition currently housing the volume.
</para>
4308 <term><emphasis role=
"bold">machine name on destination
</emphasis></term>
4311 <para>Names the file server machine to which to move the volume.
</para>
4316 <term><emphasis role=
"bold">partition name on destination
</emphasis></term>
4319 <para>Names the partition to which to move the volume.
</para>
4322 </variablelist></para>
4325 <para>It is best not to halt a
<emphasis role=
"bold">vos move
</emphasis> operation before it completes, because parts of
4326 the volume can be left on both the source and destination machines. For more information, see the command's reference
4327 page in the
<emphasis>OpenAFS Administration Reference
</emphasis>.
</para>
4332 <para><emphasis role=
"bold">(Optional)
</emphasis> Issue the
<emphasis role=
"bold">vos listvldb
</emphasis> command to
4333 confirm the success of the move. Complete instructions appear in
<link linkend=
"HDRWQ218">To display VLDB entries
</link>.
4335 %
<emphasis role=
"bold">vos listvldb
</emphasis> <<replaceable>volume name or ID
</replaceable>>
4336 </programlisting></para>
4340 <para>If a backup version existed at the read/write volume's previous site, create a new backup at the new site by issuing
4341 the
<emphasis role=
"bold">vos backup
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ205">To create
4342 and mount a backup volume
</link>.
<programlisting>
4343 %
<emphasis role=
"bold">vos backup
</emphasis> <<replaceable>volume name or ID
</replaceable>>
4344 </programlisting></para>
4350 <sect1 id=
"HDRWQ227">
4351 <title>Synchronizing the VLDB and Volume Headers
</title>
4354 <primary>VLDB
</primary>
4356 <secondary>synchronizing with volume headers
</secondary>
4360 <primary>volume header
</primary>
4362 <secondary>synchronizing with VLDB
</secondary>
4366 <primary>volume
</primary>
4368 <secondary>synchronizing VLDB and volume header
</secondary>
4371 <para>AFS can provide transparent file access because the Volume Location Database (VLDB) constantly tracks volume locations.
4372 When the Cache Manager needs a file, it contacts the Volume Location (VL) Server, which reads the VLDB for the current location
4373 of the volume containing the file. Therefore, the VLDB must accurately reflect the state of volumes on the file server machines
4374 at all times. The Volume Server and VL Server automatically update a volume's VLDB entry when its status changes during a
4375 <emphasis role=
"bold">vos
</emphasis> operation, by performing the following series of steps.
<orderedlist>
4376 <listitem id=
"LIWQ228">
4377 <para>The VL Server locks the VLDB entry. The lock advises other operations not to manipulate any
4378 of the volume versions (read/write, read-only, or backup), which prevents the inconsistency that can result from multiple
4379 simultaneous operations.
</para>
4382 <listitem id=
"LIWQ229">
4384 <primary>intention flag in VLDB entry
</primary>
4385 </indexterm> <indexterm>
4386 <primary>VLDB
</primary>
4388 <secondary>intention flag set by VL Server
</secondary>
4390 The VL Server sets an
<emphasis>intention flag
</emphasis> in the VLDB entry that
4391 indicates the kind of operation to be performed. This flag never appears in VLDB listings because it is for internal use
4392 only. In case the operation terminates prematurely, this flag tells the Salvager which operation was interrupted. (The
4393 Salvager then determines the steps necessary either to complete the operation or return the volume to a previous
4394 consistent state. For more information on salvaging, see
<link linkend=
"HDRWQ232">Salvaging Volumes
</link>.)
</para>
4397 <listitem id=
"LIWQ230">
4398 <para>The Volume Server manipulates the volume. It usually sets the
4399 <computeroutput>Off-line
</computeroutput> flag in the volume header, which makes the volume inaccessible to the File
4400 Server and other Volume Server operations during the manipulation. When the operation completes, the volume is again
4401 marked
<computeroutput>On-line
</computeroutput>.
</para>
4404 <listitem id=
"LIWQ231">
4405 <para>The VL Server records any changes resulting from the operation in the VLDB entry. Once the
4406 operation is complete, it removes the intention flag set in Step
<link linkend=
"LIWQ229">2</link>and releases the lock set
4407 in Step
<link linkend=
"LIWQ228">1</link>.
</para>
4409 </orderedlist></para>
4411 <para>If a
<emphasis role=
"bold">vos
</emphasis> operation fails while the Volume Server is manipulating the volume
4412 (corresponding to Step
<link linkend=
"LIWQ230">3</link>), the volume can be left in an intermediate state, which is termed
4413 <emphasis>corruption
</emphasis>. In this case, the
<computeroutput>Off-line
</computeroutput> or
<computeroutput>Off-line**needs
4414 salvage**
</computeroutput> marker usually appears at the end of the first line of output from the
<emphasis role=
"bold">vos
4415 examine
</emphasis> command. To repair the corruption, run the Salvager before attempting to resynchronize the VLDB and volume
4416 headers. For salvaging instructions, see
<link linkend=
"HDRWQ232">Salvaging Volumes
</link>.
</para>
4418 <para>More commonly, an interruption while flags are being set or removed (corresponding to Step
<link
4419 linkend=
"LIWQ228">1</link>, Step
<link linkend=
"LIWQ229">2</link>, or Step
<link linkend=
"LIWQ231">4</link>) causes a
4420 discrepancy between the VLDB and volume headers. To resynchronize the VLDB and volumes, use the
<emphasis role=
"bold">vos
4421 syncvldb
</emphasis> and
<emphasis role=
"bold">vos syncserv
</emphasis> commands. To achieve complete VLDB consistency, it is best
4422 to run the
<emphasis role=
"bold">vos syncvldb
</emphasis> command on all file server machines in the cell, and then run the
4423 <emphasis role=
"bold">vos syncserv
</emphasis> command on all file server machines in the cell.
</para>
4426 <primary>symptoms
</primary>
4428 <secondary>of VLDB/volume header desynchronization
</secondary>
4432 <primary>desynchronization of VLDB/volume headers
</primary>
4434 <secondary>symptoms of
</secondary>
4438 <primary>synchrony of VLDB and volume headers
</primary>
4440 <secondary>symptoms of lack of
</secondary>
4443 <para>There are several symptoms that indicate a volume operation failed:
<itemizedlist>
4445 <para>Error messages on the standard error stream or in server process log files indicate that an operation terminated
4446 abnormally. Perhaps you had to halt the operation before it completed (for instance, by using a signal such as
<emphasis
4447 role=
"bold">Ctrl-c
</emphasis>), or a file server machine or server process was not functioning when the operation ran. To
4448 determine if a machine or process is still not functioning, issue the
<emphasis role=
"bold">bos status
</emphasis> command
4449 as described in
<link linkend=
"HDRWQ158">Displaying Process Status and Information from the BosConfig File
</link>.
</para>
4453 <para>A subsequent
<emphasis role=
"bold">vos
</emphasis> operation fails because a previous failure left a VLDB entry
4454 locked. Sometimes an error message reports that a volume is locked. To display a list of locked volumes, use the
<emphasis
4455 role=
"bold">-locked
</emphasis> flag on the
<emphasis role=
"bold">vos listvldb
</emphasis> command as described in
<link
4456 linkend=
"HDRWQ217">Displaying VLDB Entries
</link>.
</para>
4458 <para>If the only problem with a volume is that its VLDB entry is locked, you probably do not need to synchronize the
4459 entire VLDB. Instead use the
<emphasis role=
"bold">vos unlock
</emphasis> or
<emphasis role=
"bold">vos
4460 unlockvldb
</emphasis> command to unlock the entry, as described in
<link linkend=
"HDRWQ247">Unlocking and Locking VLDB
4461 Entries
</link>.
</para>
4465 <para>A subsequent
<emphasis role=
"bold">vos
</emphasis> operation fails because a previous failure left a volume marked as
4466 offline. To check a volume's current status, check the first line of output from the
<emphasis role=
"bold">vos
4467 examine
</emphasis> command as described in
<link linkend=
"HDRWQ221">Displaying One Volume's VLDB Entry and Volume
4468 Header
</link>.
</para>
4470 </itemizedlist></para>
4473 <primary>synchrony of VLDB and volume headers
</primary>
4475 <secondary>restoring
</secondary>
4479 <primary>restoring
</primary>
4481 <secondary>synchrony of VLDB and volume headers
</secondary>
4485 <primary>desynchronization of VLDB/volume headers
</primary>
4487 <secondary>fixing
</secondary>
4491 <primary>Salvager
</primary>
4493 <secondary>running before VLDB/volume header resynchronization
</secondary>
4497 <primary>vos commands
</primary>
4499 <secondary>syncvldb
</secondary>
4501 <tertiary>effect
</tertiary>
4504 <para>The
<emphasis role=
"bold">vos syncvldb
</emphasis> command corrects the information in the Volume Location Database (VLDB)
4505 either about all volumes housed on a file server machine, about the volumes on just one partition, or about a single volume. If
4506 checking about one or more partitions, the command contacts the Volume Server to obtain a list of the volumes that actually
4507 reside on each partition. It then obtains the VLDB entry for each volume from the VL Server. It changes the VLDB entry as
4508 necessary to reflect the state of the volume on the partition. For example, it creates or updates a VLDB entry when it finds a
4509 volume for which the VLDB entry is missing or incomplete. However, if there is already a VLDB entry that defines a different
4510 location for the volume, or there are irreconcilable conflicts with other VLDB entries, it instead writes a message about the
4511 conflict to the standard error stream. The command never removes volumes from the file server machine.
</para>
4513 <para>When checking a single volume's VLDB entry, the command also automatically performs the operations invoked by the
4514 <emphasis role=
"bold">vos syncserv
</emphasis> command: it not only verifies that the VLDB entry is correct for the specified
4515 volume type (read/write, backup, or read-only), but also checks that any related volume types mentioned in the VLDB entry
4516 actually exist at the site listed in the entry.
</para>
4519 <primary>vos commands
</primary>
4521 <secondary>syncserv
</secondary>
4523 <tertiary>effect
</tertiary>
4526 <para>The
<emphasis role=
"bold">vos syncserv
</emphasis> command verifies that each volume type (read/write, read-only, and
4527 backup) mentioned in a VLDB entry actually exists at the site indicated in the entry. It checks all VLDB entries that mention a
4528 site either on any of a file server machine's partitions or on one partition. Note that command can end up inspecting sites
4529 other than on the specified machine or partition, if there are read-only versions of the volume at sites other than the
4530 read/write site.
</para>
4532 <para>The command alters any incorrect information in the VLDB, unless there is an irreconcilable conflict with other VLDB
4533 entries. In that case, it writes a message to the standard error stream instead. The command never removes volumes from their
4537 <primary>commands
</primary>
4539 <secondary>vos syncvldb
</secondary>
4543 <primary>vos commands
</primary>
4545 <secondary>syncvldb
</secondary>
4547 <tertiary>syntax
</tertiary>
4551 <primary>commands
</primary>
4553 <secondary>vos syncserv
</secondary>
4557 <primary>vos commands
</primary>
4559 <secondary>syncserv
</secondary>
4561 <tertiary>syntax
</tertiary>
4564 <sect2 id=
"Header_246">
4565 <title>To synchronize the VLDB with volume headers
</title>
4569 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
4570 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
4571 display the users in the UserList file
</link>.
<programlisting>
4572 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
4573 </programlisting></para>
4576 <listitem id=
"LIVOL-SYNCVL">
4577 <para>Issue the
<emphasis role=
"bold">vos syncvldb
</emphasis> command to make the VLDB reflect
4578 the true state of all volumes on a machine or partition, or the state of one volume.
</para>
4581 <para>To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your
4582 cell for the
<emphasis role=
"bold">-server
</emphasis> argument in turn and omitting the
<emphasis
4583 role=
"bold">-partition
</emphasis> and
<emphasis role=
"bold">-volume
</emphasis> arguments, before proceeding to Step
4584 <link linkend=
"LIVOL-SYNCSR">3</link>.
</para>
4588 %
<emphasis role=
"bold">vos syncvldb -server
</emphasis> <<replaceable>machine name
</replaceable>> [
<emphasis role=
"bold">-partition
</emphasis> <<replaceable>partition name
</replaceable>>] \
4589 [
<emphasis role=
"bold">-volume
</emphasis> <<replaceable>volume name or ID
</replaceable>>] [
<emphasis role=
"bold">-verbose
>></emphasis> file]
4592 <para>where
<variablelist>
4594 <term><emphasis role=
"bold">syncv
</emphasis></term>
4597 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">syncvldb
</emphasis>.
</para>
4602 <term><emphasis role=
"bold">-server
</emphasis></term>
4605 <para>Names the file server machine housing the volumes for which to verify VLDB entries. If you are also
4606 providing the
<emphasis role=
"bold">-volume
</emphasis> argument, this argument must name the machine where the
4607 volume actually resides.
</para>
4612 <term><emphasis role=
"bold">-partition
</emphasis></term>
4615 <para>Identifies the partition (on the file server machine specified by the
<emphasis
4616 role=
"bold">-server
</emphasis> argument) housing the volumes for which to verify VLDB entries. In general, it is
4617 best to omit this argument so that either the VLDB entries for all volumes on a server machine are corrected (if
4618 you do not provide the
<emphasis role=
"bold">-volume
</emphasis> argument), or so that you do not need to guarantee
4619 that the partition actually houses the volume named by the
<emphasis role=
"bold">-volume
</emphasis>
4625 <term><emphasis role=
"bold">-volume
</emphasis></term>
4628 <para>Specifies the name or volume ID number of a single volume for which to verify the VLDB entry.
</para>
4633 <term><emphasis role=
"bold">-verbose
>> file
</emphasis></term>
4636 <para>Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the
4637 machine on which you are issuing the command. The command often writes a large amount of output to the standard
4638 output stream; writing it to a file enables you to examine the output more carefully.
</para>
4641 </variablelist></para>
4644 <listitem id=
"LIVOL-SYNCSR">
4645 <para>Issue the
<emphasis role=
"bold">vos syncserv
</emphasis> command to inspect each volume
4646 for which the VLDB lists a version at the specified site.
</para>
4649 <para>To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your
4650 cell for the machine name argument in turn and omitting the partition name argument.
</para>
4654 %
<emphasis role=
"bold">vos syncserv
</emphasis> <<replaceable>machine name
</replaceable>> [
<<replaceable>partition name
</replaceable>>] [
<emphasis
4655 role=
"bold">-v
>></emphasis> file]
4658 <para>where
<variablelist>
4660 <term><emphasis role=
"bold">syncs
</emphasis></term>
4663 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">syncserv
</emphasis>.
</para>
4668 <term><emphasis role=
"bold">machine name
</emphasis></term>
4671 <para>Names the file server machine mentioned in each VLDB entry to check.
</para>
4676 <term><emphasis role=
"bold">partition name
</emphasis></term>
4679 <para>Identifies the partition mentioned in each VLDB entry to check. If synchronizing the entire VLDB, omit this
4685 <term><emphasis role=
"bold">-v
>> file
</emphasis></term>
4688 <para>Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the
4689 machine on which you are issuing the command. The command often writes a large amount of output to the standard
4690 output stream; writing it to a file enables you to examine the output more carefully.
</para>
4693 </variablelist></para>
4699 <sect1 id=
"HDRWQ232">
4700 <title>Salvaging Volumes
</title>
4703 <primary>volume
</primary>
4705 <secondary>salvaging
</secondary>
4709 <primary>corruption
</primary>
4711 <secondary>symptoms and types
</secondary>
4715 <primary>symptoms
</primary>
4717 <secondary>volume corruption
</secondary>
4721 <primary>volume
</primary>
4723 <secondary>symptoms of corruption
</secondary>
4727 <primary>Salvager
</primary>
4729 <secondary>instructions for invoking
</secondary>
4733 <primary>file server machine
</primary>
4735 <secondary>salvaging volumes
</secondary>
4739 <primary>salvaging
</primary>
4741 <secondary>volumes
</secondary>
4745 <primary>partition
</primary>
4747 <secondary>salvaging all volumes
</secondary>
4750 <para>An unexpected interruption while the Volume Server or File Server is manipulating the data in a volume can leave the
4751 volume in an intermediate state (
<emphasis>corrupted
</emphasis>), rather than just creating a discrepancy between the
4752 information in the VLDB and volume headers. For example, the failure of the operation that saves changes to a file (by
4753 overwriting old data with new) can leave the old and new data mixed together on the disk.
</para>
4755 <para>If an operation halts because the Volume Server or File Server exits unexpectedly, the BOS Server automatically shuts down
4756 all components of the
<emphasis role=
"bold">fs
</emphasis> process and invokes the Salvager. The Salvager checks for and repairs
4757 any inconsistencies it can. Sometimes, however, there are symptoms of the following sort, which indicate corruption serious
4758 enough to create problems but not serious enough to cause the File Server component to fail. In these cases you can invoke the
4759 Salvager yourself by issuing the
<emphasis role=
"bold">bos salvage
</emphasis> command.
<itemizedlist>
4761 <para><emphasis role=
"bold">Symptom:
</emphasis> A file appears in the output of the
<emphasis role=
"bold">ls
</emphasis>
4762 command, but attempts to access the file fail with messages indicating that it does not exist.
</para>
4764 <para><emphasis role=
"bold">Possible cause:
</emphasis> The Volume Server or File Server exited in the middle of a
4765 file-creation operation, after changing the directory structure, but before actually storing data. (Other possible causes
4766 are that the ACL on the directory does not grant the permissions you need to access the file, or there is a process,
4767 machine, or network outage. Check for these causes before assuming the file is corrupted.)
</para>
4769 <para><emphasis role=
"bold">Salvager's solution:
</emphasis> Remove the file's entry from the directory structure.
</para>
4773 <para><emphasis role=
"bold">Symptom:
</emphasis> A volume is marked
<computeroutput>Off-line
</computeroutput> in the output
4774 from the
<emphasis role=
"bold">vos examine
</emphasis> and
<emphasis role=
"bold">vos listvol
</emphasis> commands, or
4775 attempts to access the volume fail.
</para>
4777 <para><emphasis role=
"bold">Possible cause:
</emphasis> Two files or versions of a file are sharing the same disk blocks
4778 because of an interrupted operation. The File Server and Volume Server normally refuse to attach volumes that exhibit this
4779 type of corruption, because it can be very dangerous. If the Volume Server or File Server do attach the volume but are
4780 unsure of the status of the affected disk blocks, they sometimes try to write yet more data there. When they cannot
4781 perform the write, the data is lost. This effect can cascade, causing loss of all data on a partition.
</para>
4783 <para><emphasis role=
"bold">Salvager's solution:
</emphasis> Delete the data from the corrupted disk blocks in preference
4784 to losing an entire partition.
</para>
4788 <para><emphasis role=
"bold">Symptom:
</emphasis> There is less space available on the partition than you expect based on
4789 the size statistic reported for each volume by the
<emphasis role=
"bold">vos listvol
</emphasis> command.
</para>
4791 <para><emphasis role=
"bold">Possible cause:
</emphasis> There are orphaned files and directories. An
4792 <emphasis>orphaned
</emphasis> element is completely inaccessible because it is not referenced by any directory that can
4793 act as its parent (is higher in the file tree). An orphaned element is not counted in the calculation of a volume's size
4794 (or against its quota), even though it occupies space on the server partition.
</para>
4796 <para><emphasis role=
"bold">Salvager's solution:
</emphasis> By default, print a message to the
<emphasis
4797 role=
"bold">/usr/afs/logs/SalvageLog
</emphasis> file reporting how many orphans were found and the approximate number of
4798 kilobytes they are consuming. You can use the
<emphasis role=
"bold">-orphans
</emphasis> argument to remove or attach
4799 orphaned elements instead. See
<link linkend=
"HDRWQ233">To salvage volumes
</link>.
</para>
4801 </itemizedlist></para>
4803 <para>When you notice symptoms such as these, use the
<emphasis role=
"bold">bos salvage
</emphasis> command to invoke the
4804 Salvager before corruption spreads. (Even though it operates on volumes, the command belongs to the
<emphasis
4805 role=
"bold">bos
</emphasis> suite because the BOS Server must coordinate the shutdown and restart of the Volume Server and File
4806 Server with the Salvager. It shuts them down before the Salvager starts, and automatically restarts them when the salvage
4807 operation finishes.)
</para>
4809 <para>All of the AFS data stored on a file server machine is inaccessible during the salvage of one or more partitions. If you
4810 salvage just one volume, it alone is inaccessible.
</para>
4812 <para>When processing one or more partitions, the command restores consistency to corrupted read/write volumes where possible.
4813 For read-only or backup volumes, it inspects only the volume header:
<itemizedlist>
4815 <para>If the volume header is corrupted, the Salvager removes the volume completely and records the removal in its log
4816 file,
<emphasis role=
"bold">/usr/afs/logs/SalvageLog
</emphasis>. Issue the
<emphasis role=
"bold">vos release
</emphasis> or
4817 <emphasis role=
"bold">vos backup
</emphasis> command to create the read-only or backup volume again.
</para>
4821 <para>If the volume header is intact, the Salvager skips the volume (does not check for corruption in the contents).
4822 However, if the File Server notices corruption as it initializes, it sometimes refuses to attach the volume or bring it
4823 online. In this case, it is simplest to remove the volume by issuing the
<emphasis role=
"bold">vos remove
</emphasis> or
4824 <emphasis role=
"bold">vos zap
</emphasis> command. Then issue the
<emphasis role=
"bold">vos release
</emphasis> or
<emphasis
4825 role=
"bold">vos backup
</emphasis> command to create it again.
</para>
4827 </itemizedlist></para>
4829 <para>Combine the
<emphasis role=
"bold">bos salvage
</emphasis> command's arguments as indicated to salvage different numbers of
4830 volumes:
<itemizedlist>
4832 <para>To salvage all volumes on a file server machine, combine the
<emphasis role=
"bold">-server
</emphasis> argument and
4833 the
<emphasis role=
"bold">-all
</emphasis> flag.
</para>
4837 <para>To salvage all volumes on one partition, combine the
<emphasis role=
"bold">-server
</emphasis> and
<emphasis
4838 role=
"bold">-partition
</emphasis> arguments.
</para>
4842 <para>To salvage only one read/write volume, combine the
<emphasis role=
"bold">-server
</emphasis>,
<emphasis
4843 role=
"bold">-partition
</emphasis>, and
<emphasis role=
"bold">-volume
</emphasis> arguments. Only that volume is
4844 inaccessible to Cache Managers, because the BOS Server does not shutdown the File Server and Volume Server processes
4845 during the salvage of a single volume. Do not name a read-only or backup volume with the
<emphasis
4846 role=
"bold">-volume
</emphasis> argument. Instead, remove the volume, using the
<emphasis role=
"bold">vos remove
</emphasis>
4847 or
<emphasis role=
"bold">vos zap
</emphasis> command. Then create a new copy of the volume with the
<emphasis
4848 role=
"bold">vos release
</emphasis> or
<emphasis role=
"bold">vos backup
</emphasis> command.
</para>
4850 </itemizedlist></para>
4852 <para>The Salvager always writes a trace to the
<emphasis role=
"bold">/usr/afs/logs/SalvageLog
</emphasis> file on the file
4853 server machine where it runs. To record the trace in another file as well (either in AFS or on the local disk of the machine
4854 where you issue the
<emphasis role=
"bold">bos salvage
</emphasis> command), name the file with the
<emphasis
4855 role=
"bold">-file
</emphasis> argument. Or, to display the trace on the standard output stream as it is written to the
<emphasis
4856 role=
"bold">/usr/afs/logs/SalvageLog
</emphasis> file, include the
<emphasis role=
"bold">-showlog
</emphasis> flag.
</para>
4858 <para>By default, multiple Salvager subprocesses run in parallel: one for each partition up to four, and four subprocesses for
4859 four or more partitions. To increase or decrease the number of subprocesses running in parallel, provide a positive integer
4860 value for the
<emphasis role=
"bold">-parallel
</emphasis> argument.
</para>
4862 <para>If there is more than one server partition on a physical disk, the Salvager by default salvages them serially to avoid the
4863 inefficiency of constantly moving the disk head from one partition to another. However, this strategy is often not ideal if the
4864 partitions are configured as logical volumes that span multiple disks. To force the Salvager to salvage logical volumes in
4865 parallel, provide the string
<emphasis role=
"bold">all
</emphasis> as the value for the
<emphasis
4866 role=
"bold">-parallel
</emphasis> argument. Provide a positive integer to specify the number of subprocesses to run in parallel
4867 (for example,
<emphasis role=
"bold">-parallel
5all
</emphasis> for five subprocesses), or omit the integer to run up to four
4868 subprocesses, depending on the number of logical volumes being salvaged.
</para>
4870 <para>The Salvager creates temporary files as it runs, by default writing them to the partition it is salvaging. The number of
4871 files can be quite large, and if the partition is too full to accommodate them, the Salvager terminates without completing the
4872 salvage operation (it always removes the temporary files before exiting). Other Salvager subprocesses running at the same time
4873 continue until they finish salvaging all other partitions where there is enough disk space for temporary files. To complete the
4874 interrupted salvage, reissue the command against the appropriate partitions, adding the
<emphasis role=
"bold">-tmpdir
</emphasis>
4875 argument to redirect the temporary files to a local disk directory that has enough space.
</para>
4877 <para>The
<emphasis role=
"bold">-orphans
</emphasis> argument controls how the Salvager handles orphaned files and directories
4878 that it finds on server partitions it is salvaging. An orphaned element is completely inaccessible because it is not referenced
4879 by the vnode of any directory that can act as its parent (is higher in the filespace). Orphaned objects occupy space on the
4880 server partition, but do not count against the volume's quota.
</para>
4882 <para>During the salvage, the output of the
<emphasis role=
"bold">bos status
</emphasis> command reports the following auxiliary
4883 status for the
<emphasis role=
"bold">fs
</emphasis> process:
</para>
4886 Salvaging file system
4890 <primary>bos commands
</primary>
4892 <secondary>salvage
</secondary>
4896 <primary>commands
</primary>
4898 <secondary>bos salvage
</secondary>
4901 <sect2 id=
"HDRWQ233">
4902 <title>To salvage volumes
</title>
4906 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
4907 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
4908 display the users in the UserList file
</link>.
<programlisting>
4909 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
4910 </programlisting></para>
4914 <para>Issue the
<emphasis role=
"bold">bos salvage
</emphasis> command to salvage one or more volumes.
<programlisting>
4915 %
<emphasis role=
"bold">bos salvage -server
</emphasis> <<replaceable>machine name
</replaceable>> [
<emphasis role=
"bold">-partition
</emphasis> <<replaceable>salvage partition
</replaceable>>] \
4916 [
<emphasis role=
"bold">-volume
</emphasis> <<replaceable>salvage volume number or volume name
</replaceable>>] \
4917 [
<emphasis role=
"bold">-file
</emphasis> salvage log output file] [
<emphasis role=
"bold">-all
</emphasis>] [
<emphasis
4918 role=
"bold">-showlog
</emphasis>] \
4919 [
<emphasis role=
"bold">-parallel
</emphasis> <<replaceable># of max parallel partition salvaging
</replaceable>>] \
4920 [
<emphasis role=
"bold">-tmpdir
</emphasis> <<replaceable>directory to place tmp files
</replaceable>>] \
4921 [
<emphasis role=
"bold">-orphans
</emphasis> <<emphasis role=
"bold">ignore
</emphasis> |
<emphasis role=
"bold">remove
</emphasis> |
<emphasis
4922 role=
"bold">attach
</emphasis> >]
4923 </programlisting></para>
4925 <para>where
<variablelist>
4927 <term><emphasis role=
"bold">-server
</emphasis></term>
4930 <para>Names the file server machine on which to salvage volumes. This argument can be combined either with the
4931 <emphasis role=
"bold">-all
</emphasis> flag, the
<emphasis role=
"bold">-partition
</emphasis> argument, or both the
4932 <emphasis role=
"bold">-partition
</emphasis> and
<emphasis role=
"bold">-volume
</emphasis> arguments.
</para>
4937 <term><emphasis role=
"bold">-partition
</emphasis></term>
4940 <para>Names a single partition on which to salvage all volumes. The
<emphasis role=
"bold">-server
</emphasis>
4941 argument must be provided along with this one.
</para>
4946 <term><emphasis role=
"bold">-volume
</emphasis></term>
4949 <para>Specifies the name or volume ID number of one read/write volume to salvage. Combine this argument with the
4950 <emphasis role=
"bold">-server
</emphasis> and
<emphasis role=
"bold">-partition
</emphasis> arguments.
</para>
4955 <term><emphasis role=
"bold">-file
</emphasis></term>
4958 <para>Specifies the complete pathname of a file into which to write a trace of the salvage operation, in addition
4959 to the
<emphasis role=
"bold">/usr/afs/logs/SalvageLog
</emphasis> file on the server machine. If the file pathname
4960 is local, the trace is written to the specified file on the local disk of the machine where the
<emphasis
4961 role=
"bold">bos salvage
</emphasis> command is issued. If the
<emphasis role=
"bold">-volume
</emphasis> argument is
4962 included, the file can be in AFS, though not in the volume being salvaged. Do not combine this argument with the
4963 <emphasis role=
"bold">-showlog
</emphasis> flag.
</para>
4968 <term><emphasis role=
"bold">-all
</emphasis></term>
4971 <para>Salvages all volumes on all of the partitions on the machine named by the
<emphasis
4972 role=
"bold">-server
</emphasis> argument.
</para>
4977 <term><emphasis role=
"bold">-showlog
</emphasis></term>
4980 <para>Displays the trace of the salvage operation on the standard output stream, as well as writing it to the
4981 <emphasis role=
"bold">/usr/afs/logs/SalvageLog
</emphasis> file.
</para>
4986 <term><emphasis role=
"bold">-parallel
</emphasis></term>
4989 <para>Specifies the maximum number of Salvager subprocesses to run in parallel. Provide one of three values:
4992 <para>An integer from the range
<emphasis role=
"bold">1</emphasis> to
<emphasis role=
"bold">32</emphasis>. A
4993 value of
<emphasis role=
"bold">1</emphasis> means that a single Salvager process salvages the partitions
4994 sequentially.
</para>
4998 <para>The string
<emphasis role=
"bold">all
</emphasis> to run up to four Salvager subprocesses in parallel on
4999 partitions formatted as logical volumes that span multiple physical disks. Use this value only with such
5000 logical volumes.
</para>
5004 <para>The string
<emphasis role=
"bold">all
</emphasis> followed immediately (with no intervening space) by an
5005 integer from the range
<emphasis role=
"bold">1</emphasis> to
<emphasis role=
"bold">32</emphasis>, to run the
5006 specified number of Salvager subprocesses in parallel on partitions formatted as logical volumes. Use this
5007 value only with such logical volumes.
</para>
5009 </itemizedlist></para>
5011 <para>The BOS Server never starts more Salvager subprocesses than there are partitions, and always starts only one
5012 process to salvage a single volume. If this argument is omitted, up to four Salvager subprocesses run in
5018 <term><emphasis role=
"bold">-tmpdir
</emphasis></term>
5021 <para>Specifies the full pathname of a local disk directory to which the Salvager process writes temporary files
5022 as it runs. By default, it writes them to the partition it is currently salvaging.
</para>
5027 <term><emphasis role=
"bold">-orphans
</emphasis></term>
5030 <para>Controls how the Salvager handles orphaned files and directories. Choose one of the following three values:
5033 <term><emphasis role=
"bold">ignore
</emphasis></term>
5036 <para>Leaves the orphaned objects on the disk, but prints a message to the
<emphasis
5037 role=
"bold">/usr/afs/logs/SalvageLog
</emphasis> file reporting how many orphans were found and the
5038 approximate number of kilobytes they are consuming. This is the default if you omit the
<emphasis
5039 role=
"bold">-orphans
</emphasis> argument.
</para>
5044 <term><emphasis role=
"bold">remove
</emphasis></term>
5047 <para>Removes the orphaned objects, and prints a message to the
<emphasis
5048 role=
"bold">/usr/afs/logs/SalvageLog
</emphasis> file reporting how many orphans were removed and the
5049 approximate number of kilobytes they were consuming.
</para>
5054 <term><emphasis role=
"bold">attach
</emphasis></term>
5057 <para>Attaches the orphaned objects by creating a reference to them in the vnode of the volume's root
5058 directory. Since each object's actual name is now lost, the Salvager assigns each one a name of the
5059 following form:
<simplelist>
5060 <member><emphasis role=
"bold">_ _ORPHANFILE_ _.
</emphasis> index for files
</member>
5062 <member><emphasis role=
"bold">_ _ORPHANDIR_ _.
</emphasis> index for directories
</member>
5063 </simplelist></para>
5065 <para>where index is a two-digit number that uniquely identifies each object. The orphans are charged
5066 against the volume's quota and appear in the output of the
<emphasis role=
"bold">ls
</emphasis> command
5067 issued against the volume's root directory.
</para>
5070 </variablelist></para>
5073 </variablelist></para>
5079 <sect1 id=
"HDRWQ234">
5080 <title>Setting and Displaying Volume Quota and Current Size
</title>
5083 <primary>volume
</primary>
5085 <secondary>quota
</secondary>
5087 <see>volume quota
</see>
5091 <primary>default
</primary>
5093 <secondary>volume quota
</secondary>
5096 <para>Every AFS volume has an associated quota which limits the volume's size. The default quota for a newly created volume is
5097 5,
000 kilobyte blocks (slightly less that
5 MB). When a volume reaches its quota, the File Server rejects attempts to create new
5098 files or directories in it. If an application is writing data into an existing file in a full volume, the File Server allows a
5099 defined overage (by default,
1 MB). (You can use the
<emphasis role=
"bold">fileserver
</emphasis> command's
<emphasis
5100 role=
"bold">-spare
</emphasis> or
<emphasis role=
"bold">-pctspare
</emphasis> argument to change the default overage; see the
5101 command's reference page in the
<emphasis>OpenAFS Administration Reference
</emphasis>.)
</para>
5103 <para>To set a quota other than
5000 KB as you create a volume, include the
<emphasis role=
"bold">-maxquota
</emphasis> argument
5104 to the
<emphasis role=
"bold">vos create
</emphasis> command, as described in
<link linkend=
"HDRWQ185">Creating Read/write
5105 Volumes
</link>. To modify an existing volume's quota, issue either the
<emphasis role=
"bold">fs setquota
</emphasis> or the
5106 <emphasis role=
"bold">fs setvol
</emphasis> command as described in the following instructions. Do not set an existing volume's
5107 quota lower than its current size.
</para>
5109 <para>In general, smaller volumes are easier to administer than larger ones. If you need to move volumes, say for load-balancing
5110 purposes, it is easier to find enough free space on other partitions for small volumes. Move operations complete more quickly
5111 for small volumes, reducing the potential for outages or other errors to interrupt the move. AFS supports a maximum volume size,
5112 which can vary for different AFS releases; see the
<emphasis> OpenAFS Release Notes
</emphasis> for the version you are using.
5113 Also, the size of a partition or logical places an absolute limit on volume size, because a volume cannot span multiple
5114 partitions or logical volumes.
</para>
5116 <para>It is generally safe to overpack partitions by putting more volumes on them than can actually fit if all the volumes reach
5117 their maximum quota. However, only experience determines to what degree overpacking works in your cell. It depends on what kind
5118 of quota you assign to volumes (particularly user volumes, which are more likely than system volumes to grow unpredictably) and
5119 how much information people generate and store in comparison to their quota.
</para>
5121 <para>There are several commands that display a volume's quota, as described in the following instructions. They differ in how
5122 much related information they produce.
</para>
5124 <sect2 id=
"Header_250">
5125 <title>To set quota for a single volume
</title>
5128 <primary>maximum volume quota
</primary>
5132 <primary>setting
</primary>
5134 <secondary>volume quota
</secondary>
5136 <tertiary>on single volume
</tertiary>
5140 <primary>volume quota
</primary>
5142 <secondary>setting
</secondary>
5144 <tertiary>on single volume
</tertiary>
5148 <primary>commands
</primary>
5150 <secondary>fs setquota
</secondary>
5154 <primary>fs commands
</primary>
5156 <secondary>setquota
</secondary>
5161 <para>Verify that you belong to the
<emphasis role=
"bold">system:administrators
</emphasis> group. If necessary, issue the
5162 <emphasis role=
"bold">pts membership
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ587">To display
5163 the members of the system:administrators group
</link>.
<programlisting>
5164 %
<emphasis role=
"bold">pts membership system:administrators
</emphasis>
5165 </programlisting></para>
5169 <para>Issue the
<emphasis role=
"bold">fs setquota
</emphasis> command to set the volume's maximum quota.
<programlisting>
5170 %
<emphasis role=
"bold">fs setquota
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
<emphasis role=
"bold">-max
</emphasis> <<replaceable>max quota in kbytes
</replaceable>>
5171 </programlisting></para>
5173 <para>where
<variablelist>
5175 <term><emphasis role=
"bold">sq
</emphasis></term>
5178 <para>Is an acceptable alias for
<emphasis role=
"bold">setquota
</emphasis>.
</para>
5183 <term><emphasis role=
"bold">dir/file path
</emphasis></term>
5186 <para>Names a file or directory in the volume for which to set the indicated quota. Partial pathnames are
5187 interpreted relative to the current working directory, which is the default if you omit this argument.
</para>
5189 <para>Specify the read/write path to the file or directory, to avoid the failure that results when you attempt to
5190 change a read-only volume. By convention, you indicate the read/write path by placing a period before the cell
5191 name at the pathname's second level (for example,
<emphasis role=
"bold">/afs/.example.com
</emphasis>). For further
5192 discussion of the concept of read/write and read-only paths through the filespace, see
<link
5193 linkend=
"HDRWQ209">The Rules of Mount Point Traversal
</link>.
</para>
5198 <term><emphasis role=
"bold">max quota in kbytes
</emphasis></term>
5201 <para>Sets the volume's quota, expressed in kilobyte blocks (
<emphasis role=
"bold">1024</emphasis> equals a
5202 megabyte). A value of
<emphasis role=
"bold">0</emphasis> grants an unlimited quota, but the size of the partition
5203 imposes an absolute limit. You must include the
<emphasis role=
"bold">-max
</emphasis> switch if omitting the
5204 dir/file path argument (to set the quota on the volume that houses the current working directory).
</para>
5207 </variablelist></para>
5212 <sect2 id=
"Header_251">
5213 <title>To set maximum quota on one or more volumes
</title>
5216 <primary>setting
</primary>
5218 <secondary>volume quota
</secondary>
5220 <tertiary>on multiple volumes
</tertiary>
5224 <primary>volume quota
</primary>
5226 <secondary>setting
</secondary>
5228 <tertiary>on multiple volumes
</tertiary>
5232 <primary>commands
</primary>
5234 <secondary>fs setvol
</secondary>
5238 <primary>fs commands
</primary>
5240 <secondary>setvol
</secondary>
5245 <para>Verify that you belong to the
<emphasis role=
"bold">system:administrators
</emphasis> group. If necessary, issue the
5246 <emphasis role=
"bold">pts membership
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ587">To display
5247 the members of the system:administrators group
</link>.
<programlisting>
5248 %
<emphasis role=
"bold">pts membership system:administrators
</emphasis>
5249 </programlisting></para>
5253 <para>Issue the
<emphasis role=
"bold">fs setvol
</emphasis> command to set the quota on one or more volumes.
5255 %
<emphasis role=
"bold">fs setvol
</emphasis> [
<<replaceable>dir/file path
</replaceable>>+]
<emphasis role=
"bold">-max
</emphasis> <<replaceable>disk space quota in
1K units
</replaceable>>
5256 </programlisting></para>
5258 <para>where
<variablelist>
5260 <term><emphasis role=
"bold">sv
</emphasis></term>
5263 <para>Is an acceptable alias for
<emphasis role=
"bold">setvol
</emphasis>.
</para>
5268 <term><emphasis role=
"bold">dir/file path
</emphasis></term>
5271 <para>Names one file or directory that resides in each volume for which to set the indicated quota. Partial
5272 pathnames are interpreted relative to the current working directory, which is the default if you omit this
5278 <term><emphasis role=
"bold">disk space quota in
1K units
</emphasis></term>
5281 <para>Sets the maximum quota on each volume, expressed in kilobytes blocks (
<emphasis role=
"bold">1024</emphasis>
5282 equals a megabyte). A value of
<emphasis role=
"bold">0</emphasis> grants an unlimited quota, but the size of the
5283 partition does impose an absolute limit.
</para>
5286 </variablelist></para>
5291 <primary>commands
</primary>
5293 <secondary>fs quota
</secondary>
5297 <primary>fs commands
</primary>
5299 <secondary>quota
</secondary>
5303 <primary>displaying
</primary>
5305 <secondary>volume quota
</secondary>
5307 <tertiary>percent used
</tertiary>
5311 <primary>volume quota
</primary>
5313 <secondary>displaying
</secondary>
5315 <tertiary>percent used
</tertiary>
5319 <sect2 id=
"Header_252">
5320 <title>To display percent quota used
</title>
5324 <para>Issue the
<emphasis role=
"bold">fs quota
</emphasis> command.
<programlisting>
5325 %
<emphasis role=
"bold">fs quota
</emphasis> [
<<replaceable>dir/file path
</replaceable>>+]
5326 </programlisting></para>
5328 <para>where
<variablelist>
5330 <term><emphasis role=
"bold">q
</emphasis></term>
5333 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">quota
</emphasis>.
</para>
5338 <term><emphasis role=
"bold">dir/file path
</emphasis></term>
5341 <para>Names a directory or file in each volume for which to display percent quota used. Partial pathnames are
5342 interpreted relative to the current working directory, which is the default if you omit this argument.
</para>
5345 </variablelist></para>
5349 <para>The following example illustrates the output produced by this command:
</para>
5352 %
<emphasis role=
"bold">fs quota /afs/example.com/usr/terry
</emphasis>
5357 <primary>commands
</primary>
5359 <secondary>fs listquota
</secondary>
5363 <primary>fs commands
</primary>
5365 <secondary>listquota
</secondary>
5369 <primary>displaying
</primary>
5371 <secondary>volume quota
</secondary>
5373 <tertiary>with volume size
</tertiary>
5377 <primary>volume quota
</primary>
5379 <secondary>displaying
</secondary>
5381 <tertiary>with volume size
</tertiary>
5385 <primary>displaying
</primary>
5387 <secondary>volume size
</secondary>
5391 <primary>volume
</primary>
5393 <secondary>size, displaying
</secondary>
5397 <sect2 id=
"Header_253">
5398 <title>To display quota, current size, and other information
</title>
5402 <para>Issue the
<emphasis role=
"bold">fs listquota
</emphasis> command.
<programlisting>
5403 %
<emphasis role=
"bold">fs listquota
</emphasis> [
<<replaceable>dir/file path
</replaceable>>+]
5404 </programlisting></para>
5406 <para>where
<variablelist>
5408 <term><emphasis role=
"bold">lq
</emphasis></term>
5411 <para>Is an alias for
<emphasis role=
"bold">listquota
</emphasis>.
</para>
5416 <term><emphasis role=
"bold">dir/file path
</emphasis></term>
5419 <para>Names a directory or file in each volume for which to display quota along with volume name and current space
5420 usage. Partial pathnames are interpreted relative to the current working directory, which is the default if you
5421 omit this argument.
</para>
5424 </variablelist></para>
5428 <para>As illustrated in the following example, the output reports the volume's name, its quota and current size (both in
5429 kilobyte units), the percent quota used, and the percentage of space on the volume's host partition that is used.
</para>
5432 %
<emphasis role=
"bold">fs listquota /afs/example.com/usr/terry
</emphasis>
5433 Volume Name Quota Used % Used Partition
5434 user.terry
15000 5071 34%
86%
5438 <primary>displaying
</primary>
5440 <secondary>volume quota
</secondary>
5442 <tertiary>with volume
& partition info
</tertiary>
5446 <primary>displaying
</primary>
5448 <secondary>volume size
</secondary>
5452 <primary>volume quota
</primary>
5454 <secondary>displaying
</secondary>
5456 <tertiary>with volume
&partition info
</tertiary>
5460 <primary>displaying
</primary>
5462 <secondary>disk partition size
</secondary>
5466 <primary>disk partition
</primary>
5468 <secondary>displaying size of single
</secondary>
5472 <primary>commands
</primary>
5474 <secondary>fs examine
</secondary>
5478 <primary>fs commands
</primary>
5480 <secondary>examine
</secondary>
5484 <sect2 id=
"Header_254">
5485 <title>To display quota, current size, and more partition information
</title>
5489 <para>Issue the
<emphasis role=
"bold">fs examine
</emphasis> command.
<programlisting>
5490 %
<emphasis role=
"bold">fs examine
</emphasis> [
<<replaceable>dir/file path
</replaceable>>+]
5491 </programlisting></para>
5493 <para>where
<variablelist>
5495 <term><emphasis role=
"bold">exa
</emphasis></term>
5498 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">examine
</emphasis>.
</para>
5503 <term><emphasis role=
"bold">dir/file path
</emphasis></term>
5506 <para>Names a directory or file in each volume for which to display quota information and information about the
5507 host partition. Partial pathnames are interpreted relative to the current working directory, which is the default
5508 if you omit this argument.
</para>
5511 </variablelist></para>
5515 <para>As illustrated in the following example, the output displays the volume's volume ID number and name, its quota and
5516 current size (both in kilobyte units), and the free and total number of kilobyte blocks on the volume's host partition.
</para>
5519 %
<emphasis role=
"bold">fs examine /afs/example.com/usr/terry
</emphasis>
5520 Volume status for vid =
50489902 named user.terry
5521 Current maximum quota is
15000
5522 Current blocks used are
5073
5523 The partition has
46383 blocks available out of
333305
5527 <para>The partition-related statistics in this command's output do not always agree with the corresponding values in the
5528 output of the standard UNIX
<emphasis role=
"bold">df
</emphasis> command. The statistics reported by this command can be up
5529 to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency. Also, on
5530 some operating systems, the
<emphasis role=
"bold">df
</emphasis> command's report of partition size includes reserved space
5531 not included in this command's calculation, and so is likely to be about
10% larger.
</para>
5536 <sect1 id=
"HDRWQ235">
5537 <title>Removing Volumes and their Mount Points
</title>
5540 <primary>volume
</primary>
5542 <secondary>removing
</secondary>
5544 <tertiary>basic instructions
</tertiary>
5548 <primary>removing
</primary>
5550 <secondary>mount point
</secondary>
5554 <primary>unmounting
</primary>
5556 <secondary>volume
</secondary>
5560 <primary>mount point
</primary>
5562 <secondary>removing
</secondary>
5566 <primary>removing
</primary>
5568 <secondary>volume
</secondary>
5571 <para>To remove a volume from its site and its record from the VLDB, use the
<emphasis role=
"bold">vos remove
</emphasis>
5572 command. Use it to remove any of the three types of volumes; the effect depends on the type.
<itemizedlist>
5575 <primary>read/write volume
</primary>
5577 <secondary>removing
</secondary>
5579 <tertiary>effect of
</tertiary>
5580 </indexterm> <indexterm>
5581 <primary>backup volume
</primary>
5583 <secondary>removed by read/write removal
</secondary>
5584 </indexterm> If you indicate the read/write volume by specifying the volume's base name without a
<emphasis
5585 role=
"bold">.readonly
</emphasis> or
<emphasis role=
"bold">.backup
</emphasis> extension, the command removes both the
5586 read/write and associated backup volume from the partition that houses them. You do not need to provide the
<emphasis
5587 role=
"bold">-server
</emphasis> and
<emphasis role=
"bold">-partition
</emphasis> arguments, because there can be only one
5588 read/write site. The site information is also removed from the VLDB entry, and the site count (reported by the
<emphasis
5589 role=
"bold">vos examine
</emphasis> and
<emphasis role=
"bold">vos listvldb
</emphasis> commands as
<computeroutput>number of
5590 sites
</computeroutput>) decrements by one. The read/write and backup volume ID numbers no longer appear in the output from
5591 the
<emphasis role=
"bold">vos examine
</emphasis> and
<emphasis role=
"bold">vos listvldb
</emphasis> commands, but they are
5592 preserved internally. Read-only sites, if any, are not affected, but cannot be changed unless a read/write site is again
5593 defined. The entire VLDB entry is removed if there are no read-only sites.
</para>
5595 <para>If there are no read-only copies left, it is best to remove the volume's mount point to prevent attempts to access
5596 the volume's contents. Do not remove the mount point if copies of the read-only volume remain.
</para>
5600 <para>If you indicate a read-only volume by including the
<emphasis role=
"bold">.readonly
</emphasis> extension on its
5601 name, it is removed from the partition that houses it, and the corresponding site information is removed from the VLDB
5602 entry. The site count reported by the
<emphasis role=
"bold">vos examine
</emphasis> and
<emphasis role=
"bold">vos
5603 listvldb
</emphasis> commands as
<computeroutput>number of sites
</computeroutput> decrements by one for each volume you
5607 <primary>read-only volume
</primary>
5609 <secondary>removing
</secondary>
5611 <tertiary>effect of
</tertiary>
5614 <para>If there is more than one read-only site, you must include the
<emphasis role=
"bold">-server
</emphasis> argument
5615 (and optionally
<emphasis role=
"bold">-partition
</emphasis> argument) to specify the site from which to remove the volume.
5616 If there is only one read-only site, the volume name is sufficient; if no read/write volume exists in this case, the
5617 entire VLDB entry is removed.
</para>
5619 <para>It is not generally appropriate to remove the volume's mount point when removing a read-only volume, especially if
5620 the read/write version of the volume still exists. If the read/write version no longer exists, remove the mount point as
5621 described in Step
<link linkend=
"LIWQ239">5</link>of
<link linkend=
"HDRWQ236">To remove a volume and unmount
5626 <para>If you indicate a backup volume by including the
<emphasis role=
"bold">.backup
</emphasis> extension on its name, it
5627 is removed from the partition that houses it and its site information is removed from the VLDB entry. You do not need to
5628 provide the
<emphasis role=
"bold">-server
</emphasis> and
<emphasis role=
"bold">-partition
</emphasis> arguments, because
5629 there can be only one backup site. The backup volume ID number no longer appears in the output from the
<emphasis
5630 role=
"bold">vos examine
</emphasis> or
<emphasis role=
"bold">vos listvldb
</emphasis> command, but is preserved
5633 <para>In the standard configuration, there is a separate mount point for the backup version of a user volume. Remember to
5634 remove the mount point to prevent attempt to access the nonexistent volume's contents.
</para>
5636 </itemizedlist></para>
5638 <sect2 id=
"Header_256">
5639 <title>Other Removal Commands
</title>
5642 <primary>volume
</primary>
5644 <secondary>removing
</secondary>
5646 <tertiary>alternate commands
</tertiary>
5649 <para>The
<emphasis role=
"bold">vos remove
</emphasis> command is almost always the appropriate way to remove a volume, because
5650 it automatically removes a volume's VLDB entry and both the volume header and all data from the partition. If either the VLDB
5651 entry or volume header does not exist, it is sometimes necessary to use other commands that remove only the remaining element.
5652 Do not use these commands in the normal case when both the VLDB entry and the volume header exist, because by definition they
5653 create discrepancies between them. For details on the commands' syntax, see their reference pages in the
<emphasis> OpenAFS
5654 Administration Reference
</emphasis>.
</para>
5657 <primary>commands
</primary>
5659 <secondary>vos zap
</secondary>
5663 <primary>vos commands
</primary>
5665 <secondary>zap
</secondary>
5668 <para>The
<emphasis role=
"bold">vos zap
</emphasis> command removes a volume from its site by removing the volume header and
5669 volume data for which a VLDB entry no longer exists. You can tell a VLDB entry is missing if the
<emphasis role=
"bold">vos
5670 listvol
</emphasis> command displays the volume header but the
<emphasis role=
"bold">vos examine
</emphasis> or
<emphasis
5671 role=
"bold">vos listvldb
</emphasis> command cannot locate the VLDB entry. You must run this command to correct the
5672 discrepancy, because the
<emphasis role=
"bold">vos syncvldb
</emphasis> and
<emphasis role=
"bold">vos syncserv
</emphasis>
5673 commands never remove volume headers.
</para>
5676 <primary>commands
</primary>
5678 <secondary>vos remsite
</secondary>
5682 <primary>vos commands
</primary>
5684 <secondary>remsite
</secondary>
5687 <para>The
<emphasis role=
"bold">vos remsite
</emphasis> command removes a read-only site definition from the VLDB without
5688 affecting the volume on the file server machine. Use this command when you have mistakenly issued the
<emphasis
5689 role=
"bold">vos addsite
</emphasis> command to define a read-only site, but have not yet issued the
<emphasis role=
"bold">vos
5690 release
</emphasis> command to release the volume to the site. If you have actually released a volume to the site, use the
5691 <emphasis role=
"bold">vos remove
</emphasis> command instead.
</para>
5694 <primary>commands
</primary>
5696 <secondary>vos delentry
</secondary>
5700 <primary>vos commands
</primary>
5702 <secondary>delentry
</secondary>
5705 <para>The
<emphasis role=
"bold">vos delentry
</emphasis> command removes the entire VLDB entry that mentions the volume you
5706 specify. If versions of the volume actually exist on file server machines, they are not affected. This command is useful if
5707 you know for certain that a volume removal was not recorded in the VLDB (perhaps you used the
<emphasis role=
"bold">vos
5708 zap
</emphasis> command during an emergency), and do not want to take the time to resynchronize the entire VLDB with the
5709 <emphasis role=
"bold">vos syncvldb
</emphasis> and
<emphasis role=
"bold">vos syncserv
</emphasis> commands.
</para>
5712 <sect2 id=
"HDRWQ236">
5713 <title>To remove a volume and unmount it
</title>
5716 <primary>read/write volume
</primary>
5718 <secondary>removing
</secondary>
5720 <tertiary>instructions
</tertiary>
5725 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
5726 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
5727 display the users in the UserList file
</link>.
<programlisting>
5728 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
5729 </programlisting></para>
5733 <para>If removing the volume's mount point, verify that you have the
<emphasis role=
"bold">d
</emphasis>(
<emphasis
5734 role=
"bold">delete
</emphasis>) permission on its parent directory's ACL. If necessary, issue the
<emphasis role=
"bold">fs
5735 listacl
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
5736 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
5737 </programlisting></para>
5739 <para>Members of the
<emphasis role=
"bold">system:administrators
</emphasis> group always implicitly have the
<emphasis
5740 role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>) and by default also the
<emphasis
5741 role=
"bold">l
</emphasis>(
<emphasis role=
"bold">lookup
</emphasis>) permission on every ACL and can use the
<emphasis
5742 role=
"bold">fs setacl
</emphasis> command to grant other rights as necessary.
</para>
5745 <listitem id=
"LIWQ237">
5747 <para><emphasis role=
"bold">(Optional)
</emphasis> Dump the volume to a file or to tape, in case you want to restore it
5748 later. To copy the volume's contents to a file, use the
<emphasis role=
"bold">vos dump
</emphasis> command as instructed in
5749 <link linkend=
"HDRWQ240">Dumping and Restoring Volumes
</link>. You can then copy the file to tape using a third-party
5750 backup utility or an archiving utility such as the UNIX
<emphasis role=
"bold">tar
</emphasis> command.
</para>
5752 <para>Alternatively, use the AFS Backup System to create a tape copy. In this case, it can be convenient to create a
5753 temporary volume set that includes only the volume of interest. Temporary volume sets are not recorded in the Backup
5754 Database, and so do not clutter database with records for volume sets that you use only once. For instructions, see
<link
5755 linkend=
"HDRWQ301">To create a dump
</link>.
</para>
5758 <primary>commands
</primary>
5760 <secondary>vos remove
</secondary>
5762 <tertiary>basic instructions
</tertiary>
5766 <primary>vos commands
</primary>
5768 <secondary>remove
</secondary>
5770 <tertiary>basic instructions
</tertiary>
5774 <listitem id=
"LIWQ238">
5775 <para>Issue the
<emphasis role=
"bold">vos remove
</emphasis> command to remove the volume. If
5776 removing a read-only volume from multiple sites, repeat the command for each one.
<programlisting>
5777 %
<emphasis role=
"bold">vos remove
</emphasis> [
<emphasis role=
"bold">-server
</emphasis> machine name
>] [
<emphasis role=
"bold">-partition
</emphasis> <<replaceable>partition name
</replaceable>>] \
5778 <emphasis role=
"bold">-id
</emphasis> <<replaceable>volume name or ID
</replaceable>>
5779 </programlisting></para>
5781 <para>where
<variablelist>
5783 <term><emphasis role=
"bold">remo
</emphasis></term>
5786 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">remove
</emphasis>.
</para>
5791 <term><emphasis role=
"bold">-server
</emphasis></term>
5794 <para>Specifies the file server machine on which the volume resides. It is necessary only when the
<emphasis
5795 role=
"bold">-id
</emphasis> argument names a read-only volume that exists at multiple sites.
</para>
5800 <term><emphasis role=
"bold">-partition
</emphasis></term>
5803 <para>Specifies the partition on machine name where the volume resides. It is necessary only when the
<emphasis
5804 role=
"bold">-id
</emphasis> argument names a read-only volume that exists at multiple sites. Provide the
<emphasis
5805 role=
"bold">-server
</emphasis> argument along with this one.
</para>
5810 <term><emphasis role=
"bold">-id
</emphasis></term>
5813 <para>Identifies the volume to remove, either by its complete name or volume ID number. If identifying a read-only
5814 or backup volume by name, include the appropriate extension (
<emphasis role=
"bold">.readonly
</emphasis> or
5815 <emphasis role=
"bold">.backup
</emphasis>).
</para>
5818 </variablelist></para>
5821 <primary>commands
</primary>
5823 <secondary>fs rmmount
</secondary>
5827 <primary>fs commands
</primary>
5829 <secondary>rmmount
</secondary>
5831 <tertiary>when removing volume
</tertiary>
5835 <listitem id=
"LIWQ239">
5836 <para>If you are removing the last existing version of the volume, issue the
<emphasis
5837 role=
"bold">fs rmmount
</emphasis> command remove the corresponding mount point. Complete instructions appear in
<link
5838 linkend=
"HDRWQ236">To remove a volume and unmount it
</link>.
</para>
5840 <para>If you are removing a backup volume that is mounted in the conventional way (at a subdirectory of its read/write
5841 volume's root directory), then removing the source volume's mount point in this step is sufficient to remove the backup
5842 volume's mount point. If you mounted the backup at a completely separate directory, you need to repeat this step for the
5843 backup volume's mount point.
</para>
5846 %
<emphasis role=
"bold">fs rmmount
</emphasis> <<replaceable>directory
</replaceable>>
5851 <para><emphasis role=
"bold">(Optional)
</emphasis> If you created a dump file in Step
<link linkend=
"LIWQ237">3</link>,
5852 transfer it to tape. The preferred method is to use the AFS Backup System, which is described in
<link
5853 linkend=
"HDRWQ248">Configuring the AFS Backup System
</link>and
<link linkend=
"HDRWQ283">Backing Up and Restoring AFS
5860 <sect1 id=
"HDRWQ240">
5861 <title>Dumping and Restoring Volumes
</title>
5864 <primary>dumping
</primary>
5866 <secondary>volumes
</secondary>
5868 <tertiary>without using AFS Backup System
</tertiary>
5872 <primary>volume
</primary>
5874 <secondary>dumping without AFS Backup System
</secondary>
5877 <para><emphasis>Dumping
</emphasis> a volume with the
<emphasis role=
"bold">vos dump
</emphasis> command converts its contents
5878 into ASCII format and writes them to the file you specify. The
<emphasis role=
"bold">vos restore
</emphasis> command places a
5879 dump file's contents into a volume after converting them into the volume format appropriate for the indicated file server
5882 <sect2 id=
"Header_259">
5883 <title>About Dumping Volumes
</title>
5886 <primary>read/write volume
</primary>
5888 <secondary>dumping
</secondary>
5892 <primary>read-only volume
</primary>
5894 <secondary>dumping
</secondary>
5898 <primary>backup volume
</primary>
5900 <secondary>dumping
</secondary>
5904 <primary>availability of data
</primary>
5906 <secondary>interrupted by dumping
</secondary>
5910 <primary>data
</primary>
5912 <secondary>availability interrupted by dumping
</secondary>
5916 <primary>dumping
</primary>
5918 <secondary>volumes
</secondary>
5920 <tertiary>reasons
</tertiary>
5923 <para>Dumping a volume can be useful in several situations, including the following:
<itemizedlist>
5925 <para>You want to back it up to tape, perhaps by using a third-party backup utility. To facilitate this type of backup
5926 operation, the
<emphasis role=
"bold">vos dump
</emphasis> command can write to a named pipe. To learn about using the AFS
5927 Backup System instead, see
<link linkend=
"HDRWQ248">Configuring the AFS Backup System
</link>and
<link
5928 linkend=
"HDRWQ283">Backing Up and Restoring AFS Data
</link>.
</para>
5932 <para>You are removing the volume from your cell (perhaps because its owner is leaving your cell). The
<emphasis
5933 role=
"bold">vos dump
</emphasis> command enables you to create a copy for safekeeping without incurring the overhead of
5934 the Backup System. For complete instructions on removing a volume, see
<link linkend=
"HDRWQ235">Removing Volumes and
5935 their Mount Points
</link>.
</para>
5939 <para>You want to create a copy of the volume for safekeeping on a non-AFS server partition, perhaps while you move the
5940 actual volume to another machine or perform maintenance tasks on the partition that houses the volume.
</para>
5944 <para>You need to replace a corrupted read/write volume. If an uncorrupted read-only or backup version of the volume
5945 exists, dump it and restore the data into the read/write volume, overwriting the corrupted contents.
</para>
5949 <para>You want to copy or transfer the contents of the volume to another cell. You cannot use the
<emphasis
5950 role=
"bold">vos move
</emphasis> command, because AFS supports volume moves only between file server machines that belong
5951 to the same cell.
</para>
5955 <para>You want to have another read/write copy of the volume's contents. The second volume must have a different name
5956 than the original one. If you want the contents of the two volumes to remain identical, you must update them both
5957 manually. AFS provides no facility for keeping read/write volumes synchronized in this way.
</para>
5961 <para>You want a copy of only the files and directories in the volume with modification time stamps after a certain
5962 date. The
<emphasis role=
"bold">vos dump
</emphasis> command can create an incremental dump file as described in Step
5963 <link linkend=
"LIWQ241">3</link>of the following instructions.
</para>
5965 </itemizedlist></para>
5968 <primary>full dump
</primary>
5970 <secondary>creating using vos command
</secondary>
5974 <primary>incremental dump
</primary>
5976 <secondary>creating using vos command
</secondary>
5980 <primary>dumping
</primary>
5982 <secondary>volumes
</secondary>
5984 <tertiary>using vos command
</tertiary>
5987 <para>You can use the
<emphasis role=
"bold">vos dump
</emphasis> command to create a
<emphasis>full dump
</emphasis>, which
5988 contains the complete contents of the volume at the time you issue the command, or an
<emphasis>incremental dump
</emphasis>,
5989 which contains only those files and directories with modification timestamps (as displayed by the
<emphasis role=
"bold">ls
5990 -l
</emphasis> command) that are later than a date and time you specify. See Step
<link linkend=
"LIWQ241">3</link>of the
5991 following instructions.
</para>
5993 <para>Dumping a volume does not change its VLDB entry or permanently affect its status on the file server machine, but the
5994 volume's contents are inaccessible during the dump operation. To avoid interrupting access to the volume, it is generally best
5995 to dump the volume's backup version, just after using the
<emphasis role=
"bold">vos backup
</emphasis> or
<emphasis
5996 role=
"bold">vos backupsys
</emphasis> command to create a new backup version.
</para>
5998 <para>If you do not provide a filename into which to write the dump, the
<emphasis role=
"bold">vos dump
</emphasis> command
5999 directs the output to the standard output stream. You can pipe it directly to the
<emphasis role=
"bold">vos restore
</emphasis>
6000 command if you wish.
</para>
6002 <para>Because a volume dump file is in ASCII format, you can read its contents using a text editor or a command such as the
6003 <emphasis role=
"bold">cat
</emphasis> command. However, dump files sometimes contain special characters that do not have
6004 alphanumeric correlates, which can cause problems for some display programs.
</para>
6006 <para>By default, the
<emphasis role=
"bold">vos
</emphasis> command interpreter consults the Volume Location Database (VLDB) to
6007 learn the volume's location, so the
<emphasis role=
"bold">-server
</emphasis> and
<emphasis role=
"bold">-partition
</emphasis>
6008 arguments are not required. If the
<emphasis role=
"bold">-id
</emphasis> argument identifies a read-only volume that resides at
6009 multiple sites, then the command dumps the version from just one of them (normally, the one listed first in the volume's VLDB
6010 entry as reported by the
<emphasis role=
"bold">vos examine
</emphasis> or
<emphasis role=
"bold">vos listvldb
</emphasis>
6011 command). To dump the read-only volume from a particular site, use the
<emphasis role=
"bold">-server
</emphasis> and
<emphasis
6012 role=
"bold">-partition
</emphasis> arguments to specify the site. To bypass the VLDB lookup entirely, provide a volume ID
6013 number (rather than a volume name) as the value for the
<emphasis role=
"bold">-id
</emphasis> argument, along with the
6014 <emphasis role=
"bold">-server
</emphasis> and
<emphasis role=
"bold">-partition
</emphasis> arguments. This makes it possible to
6015 dump a volume for which there is no VLDB entry.
</para>
6018 <primary>commands
</primary>
6020 <secondary>vos dump
</secondary>
6024 <primary>vos commands
</primary>
6026 <secondary>dump
</secondary>
6030 <sect2 id=
"Header_260">
6031 <title>To dump a volume
</title>
6035 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
6036 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
6037 display the users in the UserList file
</link>.
<programlisting>
6038 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
6039 </programlisting></para>
6043 <para>Verify that you have the permissions necessary to create the dump file. If placing it in AFS, you must have the
6044 <emphasis role=
"bold">i
</emphasis>(
<emphasis role=
"bold">insert
</emphasis>) permission on the ACL of the file's
6045 directory. If necessary, issue the
<emphasis role=
"bold">fs listacl
</emphasis> command, which is fully described in
<link
6046 linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
6047 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
6048 </programlisting></para>
6050 <para>Members of the
<emphasis role=
"bold">system:administrators
</emphasis> group always implicitly have the
<emphasis
6051 role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>) and by default also the
<emphasis
6052 role=
"bold">l
</emphasis>(
<emphasis role=
"bold">lookup
</emphasis>) permission on every ACL and can use the
<emphasis
6053 role=
"bold">fs setacl
</emphasis> command to grant other rights as necessary.
</para>
6056 <listitem id=
"LIWQ241">
6057 <para>Issue the
<emphasis role=
"bold">vos dump
</emphasis> command to dump the volume.
6059 %
<emphasis role=
"bold">vos dump -id
</emphasis> <<replaceable>volume name or ID
</replaceable>> [
<emphasis role=
"bold">-time
</emphasis> <<replaceable>dump from time
</replaceable>>] [
<emphasis
6060 role=
"bold">-file
</emphasis> <<replaceable>arg
</replaceable>>] [
<emphasis role=
"bold">-server
</emphasis> <<replaceable>server
</replaceable>>] [
<emphasis
6061 role=
"bold">-partition
</emphasis> <<replaceable>partition
</replaceable>>]
6062 </programlisting></para>
6064 <para>where
<variablelist>
6066 <term><emphasis role=
"bold">-id
</emphasis></term>
6069 <para>Identifies the volume to be dumped by its complete name or volume ID number. If you want to dump the
6070 read-only or backup version, specify its volume ID number or add the appropriate extension (
<emphasis
6071 role=
"bold">.readonly
</emphasis> or
<emphasis role=
"bold">.backup
</emphasis>) to the name.
</para>
6073 <para>To bypass the normal VLDB lookup of the volume's location, provide the volume ID number and combine this
6074 argument with the
<emphasis role=
"bold">-server
</emphasis> and
<emphasis role=
"bold">-partition
</emphasis>
6080 <term><emphasis role=
"bold">-time
</emphasis></term>
6083 <para>Specifies whether the dump is full or incremental. Omit this argument to create a full dump, or provide one
6084 of three acceptable values:
<itemizedlist>
6086 <para>The value
<emphasis role=
"bold">0</emphasis>(zero) to create a full dump.
</para>
6090 <para>A date in the format mm
<emphasis role=
"bold">/
</emphasis> dd
<emphasis role=
"bold">/
</emphasis> yyyy
6091 (month, day and year) to create an incremental dump that includes only files and directories with
6092 modification timestamps later than midnight (
12:
00 a.m.) on the indicated date. Valid values for the year
6093 range from
<emphasis role=
"bold">1970</emphasis> to
<emphasis role=
"bold">2037</emphasis>; higher values are
6094 not valid because the latest possible date in the standard UNIX representation is in
2038. The command
6095 interpreter automatically reduces later dates to the maximum value. An example is
<emphasis
6096 role=
"bold">01/
13/
1999</emphasis>.
</para>
6100 <para>A date and time in the format
<emphasis role=
"bold">"</emphasis> mm <emphasis role="bold
">/</emphasis>
6101 dd <emphasis role="bold
">/</emphasis> yyyy hh <emphasis role="bold
">:</emphasis> MM <emphasis
6102 role="bold
">"</emphasis> to create an incremental dump that includes only files and directories with
6103 modification timestamps later than the specified date and time. The date format is the same as for a date
6104 alone. Express the time as hours and minutes (hh:MM) in
24-hour format (for example,
<emphasis
6105 role=
"bold">20:
30</emphasis> is
8:
30 p.m.). Surround the entire expression with double quotes (
" ") because
6106 it contains a space. An example is
<emphasis role=
"bold">"01/13/1999 22:30"</emphasis>.
</para>
6108 </itemizedlist></para>
6113 <term><emphasis role=
"bold">-file
</emphasis></term>
6116 <para>Specifies the pathname of the file to which to write the dump. The file can be in AFS, but not in the volume
6117 being dumped. A partial pathname is interpreted relative to the current working directory. Omit this argument to
6118 direct the dump to the standard output stream.
</para>
6123 <term><emphasis role=
"bold">-server
</emphasis></term>
6126 <para>Specifies the file server machine on which the volume resides. Provide the
<emphasis
6127 role=
"bold">-partition
</emphasis> argument along with this one.
</para>
6132 <term><emphasis role=
"bold">-partition
</emphasis></term>
6135 <para>Specifies the partition on which the volume resides. Provide the
<emphasis role=
"bold">-server
</emphasis>
6136 argument along with this one.
</para>
6139 </variablelist></para>
6144 <sect2 id=
"Header_261">
6145 <title>About Restoring Volumes
</title>
6148 <primary>volume
</primary>
6150 <secondary>restoring
</secondary>
6152 <tertiary>with vos restore command
</tertiary>
6156 <primary>restoring
</primary>
6158 <secondary>volumes without using AFS Backup System
</secondary>
6161 <para>Although you can dump any of the three types of volumes (read/write, read-only, or backup), you can restore a dump file
6162 to the file system only as a read/write volume, using the
<emphasis role=
"bold">vos restore
</emphasis> command. The command
6163 automatically translates the dump file's contents from ASCII back into the volume format appropriate for the file server
6164 machine that stores the restored version. As with the
<emphasis role=
"bold">vos dump
</emphasis> command, you can restore a
6165 dump file via a named pipe, which facilitates interoperation with third-party backup utilities.
</para>
6167 <para>You can restore the contents of a dump file in one of two basic ways. In either case, you must restore a full dump of
6168 the volume before restoring any incremental dumps. Any incremental dumps that you then restore must have been created after
6169 the full dump. If there is more than one incremental dump, you must restore them in the order they were created.
<itemizedlist>
6171 <para>You can restore volume data into a brand new volume with a new name and at a location that you specify. See
<link
6172 linkend=
"HDRWQ242">To restore a dump into a new volume and mount it
</link>.
</para>
6174 <para>You can assign a volume ID number as you restore the volume, though it is best to have the Volume Server allocate
6175 a volume number automatically. The most common reason for specifying the volume ID is that a volume's VLDB entry has
6176 disappeared for some reason, but you know the former read/write volume ID number and want to reuse it.
</para>
6180 <para>You can restore volume data into an existing volume (usually the one that was previously dumped), overwriting its
6181 current contents. This is convenient if the current contents are corrupted or otherwise incorrect, because it allows you
6182 to replace them with a coherent version from the past or from one of the volume's clones. See
<link
6183 linkend=
"HDRWQ244">To restore a dump file, overwriting an existing volume
</link>.
</para>
6185 <para>Provide the
<emphasis role=
"bold">-overwrite
</emphasis> argument to preconfirm that you wish to overwrite the
6186 volume's contents, and to specify whether you are restoring a full or incremental dump. If you omit the
<emphasis
6187 role=
"bold">-overwrite
</emphasis> argument, the Volume Server generates the following prompt to confirm that you want to
6188 overwrite the existing volume with either a full (
<emphasis role=
"bold">f
</emphasis>) or incremental (
<emphasis
6189 role=
"bold">i
</emphasis>) dump:
</para>
6192 Do you want to do a full/incremental restore or abort? [fia](a):
6195 <para>If you pipe in the dump file via the standard input stream instead of using the
<emphasis
6196 role=
"bold">-file
</emphasis> argument to name it, you must include the
<emphasis role=
"bold">-overwrite
</emphasis>
6197 argument because there is nowhere for the Volume Server to display the prompt in this case.
</para>
6199 <para>You can move the volume to a new site as you overwrite it with a full dump, by using the
<emphasis
6200 role=
"bold">-server
</emphasis> and
<emphasis role=
"bold">-partition
</emphasis> arguments to specify the new site. You
6201 cannot move the volume when restoring an incremental dump.
</para>
6203 </itemizedlist></para>
6205 <para>The
<emphasis role=
"bold">vos restore
</emphasis> command sets the restored volume's creation date in the volume header
6206 to the time of the restore operation, as reported in the
<computeroutput>Creation
</computeroutput> field in the output from
6207 the
<emphasis role=
"bold">vos examine
</emphasis> and
<emphasis role=
"bold">vos listvol
</emphasis> commands.
</para>
6210 <primary>commands
</primary>
6212 <secondary>vos restore
</secondary>
6216 <primary>vos commands
</primary>
6218 <secondary>restore
</secondary>
6220 <tertiary>to create new volume
</tertiary>
6224 <sect2 id=
"HDRWQ242">
6225 <title>To restore a dump into a new volume and mount it
</title>
6229 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
6230 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
6231 display the users in the UserList file
</link>.
<programlisting>
6232 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
6233 </programlisting></para>
6237 <para>Verify that you have permissions needed to read the dump file and to mount the new volume. If the dump file resides
6238 in AFS, you need the
<emphasis role=
"bold">r
</emphasis>(
<emphasis role=
"bold">read
</emphasis>) permission on the ACL of
6239 its directory. You need the
<emphasis role=
"bold">i
</emphasis>(
<emphasis role=
"bold">insert
</emphasis>) and
<emphasis
6240 role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>) permissions on the ACL of the directory where you
6241 are mounting the new volume. If necessary, issue the
<emphasis role=
"bold">fs listacl
</emphasis> command, which is fully
6242 described in
<link linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
6243 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
6244 </programlisting></para>
6246 <para>Members of the
<emphasis role=
"bold">system:administrators
</emphasis> group always implicitly have the
<emphasis
6247 role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>) and by default also the
<emphasis
6248 role=
"bold">l
</emphasis>(
<emphasis role=
"bold">lookup
</emphasis>) permission on every ACL and can use the
<emphasis
6249 role=
"bold">fs setacl
</emphasis> command to grant other rights as necessary.
</para>
6253 <para>Select a site (disk partition on a file server machine) for the new volume. If your cell groups different types of
6254 volumes onto different file server machines, that can guide your decision. It often makes sense to put the volume on the
6255 emptiest partition that meets your other criteria. To display how much space is available on a file server machine's
6256 partitions, use the
<emphasis role=
"bold">vos partinfo
</emphasis> command, which is described fully in
<link
6257 linkend=
"HDRWQ185">Creating Read/write Volumes
</link>.
<programlisting>
6258 %
<emphasis role=
"bold">vos partinfo
</emphasis> <<replaceable>machine name
</replaceable>> [
<<replaceable>partition name
</replaceable>>]
6259 </programlisting></para>
6262 <listitem id=
"LIWQ243">
6263 <para>Issue the
<emphasis role=
"bold">vos restore
</emphasis> command to create a new volume and
6264 restore the dump file into it. Type it on a single line; it appears on multiple lines here only for legibility.
6266 %
<emphasis role=
"bold">vos restore
</emphasis> <<replaceable>machine name
</replaceable>> <<replaceable>partition name
</replaceable>> \
6267 <<replaceable>name of volume to be restored
</replaceable>> \
6268 [
<emphasis role=
"bold">-file
</emphasis> <<replaceable>dump file
</replaceable>>] [
<emphasis role=
"bold">-id
</emphasis> <<replaceable>volume ID
</replaceable>>]
6269 </programlisting></para>
6271 <para>where
<variablelist>
6273 <term><emphasis role=
"bold">res
</emphasis></term>
6276 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">restore
</emphasis>.
</para>
6281 <term><emphasis role=
"bold">machine name
</emphasis></term>
6284 <para>Names the file server machine on which to create the new volume.
</para>
6289 <term><emphasis role=
"bold">partition name
</emphasis></term>
6292 <para>Names the partition on which to create the new volume.
</para>
6297 <term><emphasis role=
"bold">name of volume to be restored
</emphasis></term>
6300 <para>Names the new read/write volume, which must not already have a VLDB entry. It can be up to
22 characters in
6306 <term><emphasis role=
"bold">-file
</emphasis></term>
6309 <para>Is the dump file to restore. Partial pathnames are interpreted with respect to the current working
6310 directory. Omit this argument if using a pipe to read in the dump file from the standard input stream.
</para>
6315 <term><emphasis role=
"bold">-volume
</emphasis></term>
6318 <para>Specifies the new volume's ID number. It is appropriate only if you are restoring a volume that no longer
6319 exists and want to use the volume ID number it had previously.
</para>
6322 </variablelist></para>
6325 <primary>commands
</primary>
6327 <secondary>fs mkmount
</secondary>
6329 <tertiary>when restoring volume
</tertiary>
6333 <primary>fs commands
</primary>
6335 <secondary>mkmount
</secondary>
6337 <tertiary>when restoring volume
</tertiary>
6342 <para>Issue the
<emphasis role=
"bold">fs mkmount
</emphasis> command to mount the new volume, making its contents
6343 accessible. Complete instructions appear in
<link linkend=
"HDRWQ212">To create a regular or read/write mount point
</link>.
6345 %
<emphasis role=
"bold">fs mkmount
</emphasis> <<replaceable>directory
</replaceable>> <<replaceable>volume name
</replaceable>>
6346 </programlisting></para>
6350 <para><emphasis role=
"bold">(Optional)
</emphasis> Issue the
<emphasis role=
"bold">fs lsmount
</emphasis> command to verify
6351 that the mount point refers to the correct volume. Complete instructions appear in
<link linkend=
"HDRWQ211">To display a
6352 mount point
</link>.
<programlisting>
6353 %
<emphasis role=
"bold">fs lsmount
</emphasis> <<replaceable>directory
</replaceable>>
6354 </programlisting></para>
6359 <primary>commands
</primary>
6361 <secondary>vos restore
</secondary>
6365 <primary>vos commands
</primary>
6367 <secondary>restore
</secondary>
6369 <tertiary>to overwrite volume
</tertiary>
6373 <sect2 id=
"HDRWQ244">
6374 <title>To restore a dump file, overwriting an existing volume
</title>
6378 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
6379 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
6380 display the users in the UserList file
</link>.
<programlisting>
6381 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
6382 </programlisting></para>
6386 <para>Verify that you have permissions needed to read the dump file. If it resides in AFS, you need the
<emphasis
6387 role=
"bold">r
</emphasis>(
<emphasis role=
"bold">read
</emphasis>) permission on the ACL of its directory. If necessary,
6388 issue the
<emphasis role=
"bold">fs listacl
</emphasis> command, which is fully described in
<link
6389 linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
6390 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
6391 </programlisting></para>
6393 <para>Members of the
<emphasis role=
"bold">system:administrators
</emphasis> group always implicitly have the
<emphasis
6394 role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>) and by default also the
<emphasis
6395 role=
"bold">l
</emphasis>(
<emphasis role=
"bold">lookup
</emphasis>) permission on every ACL and can use the
<emphasis
6396 role=
"bold">fs setacl
</emphasis> command to grant other rights as necessary.
</para>
6400 <para>Restore the contents of the dump file into a read/write volume, overwriting the current contents. The volume retains
6401 its current volume ID number. Type it on a single line; it appears on multiple lines here only for legibility.
6403 %
<emphasis role=
"bold">vos restore
</emphasis> <<replaceable>machine name
</replaceable>> <<replaceable>partition name
</replaceable>> \
6404 <<replaceable>name of volume to be restored
</replaceable>> \
6405 [
<emphasis role=
"bold">-file
</emphasis> <<replaceable>dump file
</replaceable>>] [
<emphasis role=
"bold">-id
</emphasis> <<replaceable>volume ID
</replaceable>>]
6406 </programlisting></para>
6408 <para>where
<variablelist>
6410 <term><emphasis role=
"bold">res
</emphasis></term>
6413 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">restore
</emphasis>.
</para>
6418 <term><emphasis role=
"bold">machine name
</emphasis></term>
6421 <para>Names the file server machine where the volume already exists, or the machine to which to move it. In the
6422 latter case, the value for the
<emphasis role=
"bold">-overwrite
</emphasis> argument must be
<emphasis
6423 role=
"bold">full
</emphasis>.
</para>
6428 <term><emphasis role=
"bold">partition name
</emphasis></term>
6431 <para>Names the partition where the volume already exists, or the partition to which to move it. In the latter
6432 case, the value for the
<emphasis role=
"bold">-overwrite
</emphasis> argument must be
<emphasis
6433 role=
"bold">full
</emphasis>.
</para>
6438 <term><emphasis role=
"bold">name of volume to be restored
</emphasis></term>
6441 <para>Names the read/write volume to overwrite with the contents of the dump file.
</para>
6446 <term><emphasis role=
"bold">-file
</emphasis></term>
6449 <para>Is the dump file to restore. Partial pathnames are interpreted with respect to the current working
6450 directory. Omit this argument if using a pipe to read in the dump file from the standard input stream; in this
6451 case, you must provide the
<emphasis role=
"bold">-overwrite
</emphasis> argument.
</para>
6456 <term><emphasis role=
"bold">-overwrite
</emphasis></term>
6459 <para>Preconfirms that you want to overwrite the existing volume and specifies which type of dump file you are
6460 restoring. Provide one of the following values:
<itemizedlist>
6462 <para><emphasis role=
"bold">f
</emphasis> or
<emphasis role=
"bold">full
</emphasis> if restoring a full dump
6467 <para><emphasis role=
"bold">i
</emphasis> or
<emphasis role=
"bold">incremental
</emphasis> if restoring an
6468 incremental dump file. This value is not acceptable if you are moving the volume while restoring it.
</para>
6472 <para><emphasis role=
"bold">a
</emphasis> to terminate the restore operation
</para>
6474 </itemizedlist></para>
6477 </variablelist></para>
6481 <para>If the volume is replicated, issue the
<emphasis role=
"bold">vos release
</emphasis> command to release the newly
6482 restored contents to read-only sites. Complete instructions appear in
<link linkend=
"HDRWQ192">Replicating Volumes
6483 (Creating Read-only Volumes)
</link>.
<programlisting>
6484 %
<emphasis role=
"bold">vos release
</emphasis> <<replaceable>volume name or ID
</replaceable>>
6485 </programlisting></para>
6489 <para>Issue the
<emphasis role=
"bold">vos backup
</emphasis> command to create a new backup version of the volume. Complete
6490 instructions appear in
<link linkend=
"HDRWQ201">Creating Backup Volumes
</link>.
<programlisting>
6491 %
<emphasis role=
"bold">vos backup
</emphasis> <<replaceable>volume name or ID
</replaceable>>
6492 </programlisting></para>
6498 <sect1 id=
"HDRWQ245">
6499 <title>Renaming Volumes
</title>
6502 <primary>renaming
</primary>
6504 <secondary>volume
</secondary>
6508 <primary>volume
</primary>
6510 <secondary>renaming
</secondary>
6514 <primary>changing
</primary>
6516 <secondary>volume name
</secondary>
6520 <primary>volume name
</primary>
6522 <secondary>changing
</secondary>
6524 <tertiary>basic instructions
</tertiary>
6527 <para>You can use the
<emphasis role=
"bold">vos rename
</emphasis> command to rename a volume. For example, it is appropriate to
6528 rename a user's home volume if you use the
<emphasis role=
"bold">user.
</emphasis> username convention for user volume names and
6529 you change the username. (For complete instructions for changing usernames, see
<link linkend=
"HDRWQ518">Changing
6530 Usernames
</link>.)
</para>
6533 <primary>read/write volume
</primary>
6535 <secondary>changing name of
</secondary>
6539 <primary>read-only volume
</primary>
6541 <secondary>changing name of
</secondary>
6545 <primary>backup volume
</primary>
6547 <secondary>changing name of
</secondary>
6550 <para>The
<emphasis role=
"bold">vos rename
</emphasis> command accepts only read/write volume names, but automatically changes
6551 the names of the associated read-only and backup volumes. As directed in the following instructions, you need to replace the
6552 volume's current mount point with a new one that reflects the name change.
</para>
6555 <primary>commands
</primary>
6557 <secondary>vos rename
</secondary>
6559 <tertiary>basic instructions
</tertiary>
6563 <primary>vos commands
</primary>
6565 <secondary>rename
</secondary>
6567 <tertiary>basic instructions
</tertiary>
6570 <sect2 id=
"HDRWQ246">
6571 <title>To rename a volume
</title>
6575 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
6576 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
6577 display the users in the UserList file
</link>.
<programlisting>
6578 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
6579 </programlisting></para>
6583 <para>Verify that you have the
<emphasis role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>),
<emphasis
6584 role=
"bold">d
</emphasis>(
<emphasis role=
"bold">delete
</emphasis>), and
<emphasis role=
"bold">i
</emphasis>(
<emphasis
6585 role=
"bold">insert
</emphasis>) access permissions for the directory in which you are replacing the volume's mount point.
6586 If necessary, issue the
<emphasis role=
"bold">fs listacl
</emphasis> command, which is fully described in
<link
6587 linkend=
"HDRWQ572">Displaying ACLs
</link>.
<programlisting>
6588 %
<emphasis role=
"bold">fs listacl
</emphasis> [
<<replaceable>dir/file path
</replaceable>>]
6589 </programlisting></para>
6591 <para>Members of the
<emphasis role=
"bold">system:administrators
</emphasis> group always implicitly have the
<emphasis
6592 role=
"bold">a
</emphasis>(
<emphasis role=
"bold">administer
</emphasis>) and by default also the
<emphasis
6593 role=
"bold">l
</emphasis>(
<emphasis role=
"bold">lookup
</emphasis>) permission on every ACL and can use the
<emphasis
6594 role=
"bold">fs setacl
</emphasis> command to grant other rights as necessary.
</para>
6597 <listitem id=
"LIVOL-REN">
6598 <para>Issue the
<emphasis role=
"bold">vos rename
</emphasis> command to rename the volume.
6600 %
<emphasis role=
"bold">vos rename
</emphasis> <<replaceable>old volume name
</replaceable>> <<replaceable>new volume name
</replaceable>>
6601 </programlisting></para>
6603 <para>where
<variablelist>
6605 <term><emphasis role=
"bold">ren
</emphasis></term>
6608 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">rename
</emphasis>.
</para>
6613 <term><emphasis role=
"bold">old volume name
</emphasis></term>
6616 <para>Is the current name of a read/write volume.
</para>
6621 <term><emphasis role=
"bold">new volume name
</emphasis></term>
6624 <para>Is the new name for the volume. It cannot be more than
22 characters in length.
</para>
6627 </variablelist></para>
6629 <para>If there is no Volume Location Database (VLDB) entry for the specified current volume name, the command fails with
6630 the following error message:
</para>
6633 vos: Could not find entry for volume old_volume_name.
6637 <primary>commands
</primary>
6639 <secondary>fs rmmount
</secondary>
6643 <primary>fs commands
</primary>
6645 <secondary>rmmount
</secondary>
6647 <tertiary>when renaming volume
</tertiary>
6652 <para>Issue the
<emphasis role=
"bold">fs rmmount
</emphasis> command to remove the mount point that refers to the volume's
6653 old name. Complete instructions appear in
<link linkend=
"HDRWQ215">To remove a mount point
</link>.
<programlisting>
6654 %
<emphasis role=
"bold">fs rmmount
</emphasis> <<replaceable>directory
</replaceable>>
6655 </programlisting></para>
6658 <primary>commands
</primary>
6660 <secondary>fs mkmount
</secondary>
6662 <tertiary>when renaming volume
</tertiary>
6666 <primary>fs commands
</primary>
6668 <secondary>mkmount
</secondary>
6670 <tertiary>when renaming volume
</tertiary>
6675 <para>Issue the
<emphasis role=
"bold">fs mkmount
</emphasis> to create a mount point that indicates the volume's new name.
6676 Complete instructions appear in
<link linkend=
"HDRWQ212">To create a regular or read/write mount point
</link>.
6678 %
<emphasis role=
"bold">fs mkmount
</emphasis> <<replaceable>directory
</replaceable>> <<replaceable>volume name
</replaceable>> [
<emphasis
6679 role=
"bold">-rw
</emphasis>]
6680 </programlisting></para>
6686 <sect1 id=
"HDRWQ247">
6687 <title>Unlocking and Locking VLDB Entries
</title>
6689 <para>As detailed in
<link linkend=
"HDRWQ227">Synchronizing the VLDB and Volume Headers
</link>, The Volume Location (VL) Server
6690 locks the Volume Location Database (VLDB) entry for a volume before the Volume Server executes any operation on it. No other
6691 operation can affect a volume with a locked VLDB entry, so the lock prevents the inconsistency or corruption that can result
6692 from multiple simultaneous operations on a volume.
</para>
6695 <primary>locking
</primary>
6697 <secondary>VLDB entry
</secondary>
6701 <primary>VLDB
</primary>
6703 <secondary>locking/unlocking entry
</secondary>
6707 <primary>entry in VLDB
</primary>
6709 <secondary>locking/unlocking
</secondary>
6713 <primary>unlocking
</primary>
6715 <secondary>VLDB entry
</secondary>
6719 <primary>locked VLDB entry
</primary>
6721 <secondary>unlocking
</secondary>
6724 <para>To verify that a VLDB entry is locked, issue the
<emphasis role=
"bold">vos listvldb
</emphasis> command as described in
6725 <link linkend=
"HDRWQ218">To display VLDB entries
</link>. The command has a
<emphasis role=
"bold">-locked
</emphasis> flag that
6726 displays locked entries only. If the VLDB entry is locked, the string
<computeroutput>Volume is currently
6727 LOCKED
</computeroutput> appears on the last line of the volume's output.
</para>
6729 <para>To lock a VLDB entry yourself, use the
<emphasis role=
"bold">vos lock
</emphasis> command. This is useful when you suspect
6730 something is wrong with a volume and you want to prevent any changes to it while you are investigating the problem.
</para>
6732 <para>To unlock a locked VLDB entry, issue the
<emphasis role=
"bold">vos unlock
</emphasis> command, which unlocks a single VLDB
6733 entry, or the
<emphasis role=
"bold">vos unlockvldb
</emphasis> command, which unlocks potentially many entries. This is useful
6734 when a volume operation fails prematurely and leaves a VLDB entry locked, preventing you from acting to correct the problems
6735 resulting from the failure.
</para>
6738 <primary>commands
</primary>
6740 <secondary>vos lock
</secondary>
6744 <primary>vos commands
</primary>
6746 <secondary>lock
</secondary>
6749 <sect2 id=
"Header_267">
6750 <title>To lock a VLDB entry
</title>
6754 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
6755 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
6756 display the users in the UserList file
</link>.
<programlisting>
6757 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
6758 </programlisting></para>
6762 <para>Issue the
<emphasis role=
"bold">vos lock
</emphasis> to lock the entry.
<programlisting>
6763 %
<emphasis role=
"bold">vos lock
</emphasis> <<replaceable>volume name or ID
</replaceable>>
6764 </programlisting></para>
6766 <para>where
<variablelist>
6768 <term><emphasis role=
"bold">lo
</emphasis></term>
6771 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">lock
</emphasis>.
</para>
6776 <term><emphasis role=
"bold">volume name or ID
</emphasis></term>
6779 <para>Identifies the volume to be locked, either by its complete name or volume ID number. It can be any of the
6780 three versions of the volume.
</para>
6783 </variablelist></para>
6788 <primary>commands
</primary>
6790 <secondary>vos unlock
</secondary>
6794 <primary>vos commands
</primary>
6796 <secondary>unlock
</secondary>
6800 <sect2 id=
"Header_268">
6801 <title>To unlock a single VLDB entry
</title>
6805 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
6806 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
6807 display the users in the UserList file
</link>.
<programlisting>
6808 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
6809 </programlisting></para>
6813 <para>Issue the
<emphasis role=
"bold">vos unlock
</emphasis> command to unlock the entry.
<programlisting>
6814 %
<emphasis role=
"bold">vos unlock
</emphasis> <<replaceable>volume name or ID
</replaceable>>
6815 </programlisting></para>
6817 <para>where
<variablelist>
6819 <term><emphasis role=
"bold">unlock
</emphasis></term>
6822 <para>Must be typed in full.
</para>
6827 <term><emphasis role=
"bold">volume name or ID
</emphasis></term>
6830 <para>Identifies the volume to be unlocked, either by its complete name or volume ID number. It can be any of the
6831 three versions of the volume.
</para>
6834 </variablelist></para>
6839 <primary>commands
</primary>
6841 <secondary>vos unlockvldb
</secondary>
6845 <primary>vos commands
</primary>
6847 <secondary>unlockvldb
</secondary>
6851 <sect2 id=
"Header_269">
6852 <title>To unlock multiple VLDB entries
</title>
6856 <para>Verify that you are listed in the
<emphasis role=
"bold">/usr/afs/etc/UserList
</emphasis> file. If necessary, issue
6857 the
<emphasis role=
"bold">bos listusers
</emphasis> command, which is fully described in
<link linkend=
"HDRWQ593">To
6858 display the users in the UserList file
</link>.
<programlisting>
6859 %
<emphasis role=
"bold">bos listusers
</emphasis> <<replaceable>machine name
</replaceable>>
6860 </programlisting></para>
6864 <para>Issue the
<emphasis role=
"bold">vos unlockvldb
</emphasis> command to unlock the desired entries.
<programlisting>
6865 %
<emphasis role=
"bold">vos unlockvldb
</emphasis> [
<<replaceable>machine name
</replaceable>>] [
<<replaceable>partition name
</replaceable>>]
6866 </programlisting></para>
6868 <para>where
<variablelist>
6870 <term><emphasis role=
"bold">unlockv
</emphasis></term>
6873 <para>Is the shortest acceptable abbreviation of
<emphasis role=
"bold">unlockvldb
</emphasis>.
</para>
6878 <term><emphasis role=
"bold">machine name
</emphasis></term>
6881 <para>Specifies a file server machine. Provide this argument alone to unlock all VLDB entries that mention the
6882 machine in a site definition. Omit both this argument and the partition name argument to unlock all VLDB
6888 <term><emphasis role=
"bold">partition name
</emphasis></term>
6891 <para>Specifies a partition. Provide this argument alone to unlock all VLDB entries that mention the partition (on
6892 any machine) in a site definition. Omit both this argument and the machine name argument to unlock all VLDB
6896 </variablelist></para>