1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
5 >Managing Volumes</TITLE
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
10 TITLE="AFS Administration Guide"
11 HREF="book1.html"><LINK
13 TITLE="Managing File Server Machines"
14 HREF="p3023.html"><LINK
16 TITLE="Monitoring and Controlling Server Processes"
17 HREF="c6449.html"><LINK
19 TITLE="Configuring the AFS Backup System"
20 HREF="c12776.html"></HEAD
31 SUMMARY="Header navigation table"
40 >AFS Administration Guide: Version 3.6</TH
77 >Chapter 5. Managing Volumes</H1
79 >This chapter explains how to manage the volumes stored on file server machines. The volume is the designated unit of
80 administration in AFS, so managing them is a large part of the administrator's duties.</P
87 >Summary of Instructions</A
90 >This chapter explains how to perform the following tasks by using the indicated commands:</P
105 >Create read/write volume</TD
117 >Create read-only volume</TD
142 >Create backup volume</TD
154 >Create many backup volumes at once</TD
166 >Examine VLDB entry</TD
178 >Examine volume header</TD
190 >Examine both VLDB entry and volume header</TD
202 >Display volume's name</TD
227 >Display volume's ID number</TD
264 >Display partition's size and space available</TD
276 >Display volume's location</TD
301 >Create mount point</TD
313 >Remove mount point</TD
325 >Display mount point</TD
337 >Move read/write volume</TD
349 >Synchronize VLDB with volume headers</TD
374 >Set volume quota</TD
399 >Display volume quota</TD
436 >Display volume's current size</TD
461 >Display list of volumes on a machine/partition</TD
473 >Remove read/write volume</TD
498 >Remove read-only volume</TD
510 >Remove backup volume</TD
535 >Remove volume; no VLDB change</TD
547 >Remove read-only site definition</TD
559 >Remove VLDB entry; no volume change</TD
583 >Restore dumped volume</TD
637 >Unlock multiple volumes</TD
678 > is a logical unit of disk space that functions like a container for the files in an AFS
679 directory, keeping them all together on one partition of a file server machine. To make a volume's contents visible in the
680 cell's file tree and accessible to users, you mount the volume at a directory location in the AFS filespace. The association
681 between the volume and its location in the filespace is called a <SPAN
687 >, and because of AFS's internal
688 workings it looks and acts just like a standard directory element. Users can access and manipulate a volume's contents in the
689 same way they access and manipulate the contents of a standard UNIX directory. For more on the relationship between volumes and
691 HREF="c8420.html#HDRWQ183"
692 >About Mounting Volumes</A
695 >Many of an administrator's daily activities involve manipulating volumes, since they are the basic storage and
696 administrative unit of AFS. For a discussion of some of the ways volumes can make your job easier, see <A
697 HREF="c8420.html#HDRWQ179"
698 >How Volumes Improve AFS Efficiency</A
706 >The Three Types of Volumes</A
709 >There are three types of volumes in AFS, as described in the following list: <UL
718 > version of a volume houses the modifiable versions of the files and
719 directories in that volume. It is often referred to as the <SPAN
725 > source because volumes of the
726 other two types are derived from it by a copying procedure called <SPAN
732 >. For instructions on
733 creating read/write volumes, see <A
734 HREF="c8420.html#HDRWQ185"
735 >Creating Read/write Volumes</A
746 > volume is a copy of the read/write source volume and can exist at multiple
753 > (a site is a particular partition on a particular file server machine). Placing the same data
754 at more than one site is called <SPAN
761 HREF="c8420.html#HDRWQ179"
762 >How Volumes Improve AFS
764 >. As the name suggests, a read-only volume's contents do not change automatically as the read/write
765 source changes, but only when an administrator issues the <SPAN
772 users to have a consistent view of the AFS filespace, all copies of the read-only volume must match each other and their
773 read/write source. All read-only volumes share the same name, which is derived by adding the <SPAN
779 > extension to the read/write source's name. For instructions on creating of read-only
781 HREF="c8420.html#HDRWQ192"
782 >Replicating Volumes (Creating Read-only Volumes)</A
793 > volume is a clone of the read/write source volume and is stored at the same site as
794 the source. A backup version is useful because it records the state of the read/write source at a certain time, allowing
795 recovery of data that is later mistakenly changed or deleted (for further discussion see <A
796 HREF="c8420.html#HDRWQ179"
798 Volumes Improve AFS Efficiency</A
799 >). A backup volume's name is derived by adding the <SPAN
805 > extension to the read/write source's name. For instructions on creating of backup
807 HREF="c8420.html#HDRWQ201"
808 >Creating Backup Volumes</A
817 >A backup volume is not the same as the backup of a volume transferred to tape using the AFS Backup System,
818 although making a backup version of a volume is usually a stage in the process of backing up the volume to tape. For
819 information on backing up a volume using the AFS Backup System, see <A
820 HREF="c15383.html#HDRWQ296"
830 >As noted, the three types of volumes are related to one another: read-only and backup volumes are both derived from a
831 read/write volume through a process called cloning. Read-only and backup volumes are exact copies of the read/write source at
832 the time they are created.</P
840 >How Volumes Improve AFS Efficiency</A
843 >Volumes make your cell easier to manage and more efficient in the following three ways: <UL
846 >Volumes are easy to move between partitions, on the same or different machines, because they are by definition
847 smaller than a partition. Perhaps the most common reasons to move volumes are to balance the load among file server
848 machines or to take advantage of greater disk capacity on certain machines. You can move volumes as often as necessary
849 without disrupting user access to their contents, because the move procedure makes the contents unavailable for only a
850 few seconds. The automatic tracking of volume locations in the Volume Location Database (VLDB) assures that access
851 remains transparent. For instructions on moving volumes, see <A
852 HREF="c8420.html#HDRWQ226"
858 >Volumes are the unit of replication in AFS. <SPAN
864 > refers to creating a read-only clone
865 from the read/write source and distributing of the clone to one or more sites. Replication improves system efficiency
866 because more than one machine can fill requests for popular files. It also boosts system reliability by helping to keep
867 data available in the face of machine or server process outage. In general, volumes containing popular application
868 programs and other files that do not change often are the best candidates for replication, but you can replicate any
869 read/write volume. See <A
870 HREF="c8420.html#HDRWQ192"
871 >Replicating Volumes (Creating Read-only Volumes)</A
876 >Volumes are the unit of backup in AFS, in two senses. You can create a backup volume version to preserves the
877 state of a read/write source volume at a specified time. You can mount the backup version in the AFS filespace, enabling
878 users to restore data they have accidentally changed or deleted without administrator assistance, which frees you for
879 more important jobs. If you make a new backup version of user volumes once a day (presumably overwriting the former
880 backup), then users are always be able to retrieve the previous day's version of a file. For instructions, see <A
881 HREF="c8420.html#HDRWQ201"
882 >Creating Backup Volumes</A
885 >Backup also refers to using the AFS Backup System to store permanent copies of volume contents on tape or in a
886 special backup data. See <A
888 >Configuring the AFS Backup System</A
891 >Backing Up and Restoring AFS Data</A
903 >Volume Information in the VLDB</A
906 >The Volume Location Database (VLDB) includes entries for every volume in a cell. Perhaps the most important information
907 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
908 Manager consults the Volume Location (VL) Server, which maintains the VLDB, for a list of the file server machines that house
909 the volume containing the file. The Cache Manager then requests the file from the File Server running on one of the relevant
910 file server machines. The file location procedure is invisible to the user, who only needs to know the file's pathname.</P
912 >The VLDB volume entry for a read/write volume also contains the pertinent information about the read-only and backup
913 versions, which do not have their own VLDB entries. (The rare exception is a read-only volume that has its own VLDB entry
914 because its read/write source has been removed.) A volume's VLDB entry records the volume's name, the unique volume ID number
915 for each version (read/write, read-only, backup, and releaseClone), a count of the number of sites that house a read/write or
916 read-only version, and a list of the sites.</P
918 >To display the VLDB entry for one or more volumes, use the <SPAN
926 HREF="c8420.html#HDRWQ218"
927 >To display VLDB entries</A
928 >. To display the VLDB entry for a single volume along with
941 > command as described in <A
942 HREF="c8420.html#HDRWQ222"
943 >To display one volume's VLDB entry and volume header</A
944 >. (See the following section for a description
945 of the volume header.)</P
953 >The Information in Volume Headers</A
956 >Whereas all versions of a volume share one VLDB entry, each volume on an AFS server partition has its own volume header,
957 a data structure that maps the files and directories in the volume to physical memory addresses on the partition that stores
958 them. The volume header binds the volume's contents into a logical unit without requiring that they be stored in contiguous
959 memory blocks. The volume header also records the following information about the volume, some of it redundant with the VLDB
960 entry: name, volume ID number, type, size, status (online, offline, or busy), space quota, timestamps for creation date and
961 date of last modification, and number of accesses during the current day.</P
963 >To display the volume headers on one or more partitions, use the <SPAN
971 HREF="c8420.html#HDRWQ220"
972 >To display volume headers</A
973 >. To display the VLDB entry for a single volume along
974 with its volume header, use the <SPAN
980 > command as described in <A
981 HREF="c8420.html#HDRWQ222"
982 >To display one volume's VLDB entry and volume header</A
991 >Keeping the VLDB and Volume Headers Synchronized</A
994 >It is vital that the information in the VLDB correspond to the status of the actual volumes on the servers (as recorded
995 in volume headers) as much of the time as possible. If a volume's location information in the VLDB is incorrect, the Cache
996 Manager cannot find access its contents. Whenever you issue a <SPAN
1002 > command that changes a
1003 volume's status, the Volume Server and VL Server cooperate to keep the volume header and VLDB synchronized. In rare cases, the
1004 header and VLDB can diverge, for instance because a <SPAN
1010 > operation halts prematurely. For
1011 instructions on resynchronizing them, see <A
1012 HREF="c8420.html#HDRWQ227"
1013 >Synchronizing the VLDB and Volume Headers</A
1022 >About Mounting Volumes</A
1025 >To make a volume's contents visible in the cell's file tree and accessible to users, you mount the volume at a directory
1026 location in the AFS filespace. The association between the volume and its location in the filespace is called a
1033 >. An AFS mount point looks and functions like a regular UNIX file system directory, but
1034 structurally it is more like a symbolic link that tells the Cache Manager the name of the volume associated with the
1035 directory. A mount point looks and acts like a directory only because the Cache Manager knows how to interpret it.</P
1037 >Consider the common case where the Cache Manager needs to retrieve a file requested by an application program. The Cache
1038 Manager traverses the file's complete pathname, starting at the AFS root (by convention mounted at the <SPAN
1044 > directory) and continuing to the file. When the Cache Manager encounters (or
1051 >) a mount point during the traversal, it reads it to learn the name of the volume mounted at that
1052 directory location. After obtaining location information about the volume from the Volume Location (VL) Server, the Cache
1053 Manager fetches the indicated volume and opens its <SPAN
1059 >. The root directory of a volume lists
1060 all the files, subdirectories, and mount points that reside in it. The Cache Manager scans the root directory listing for the
1061 next element in the pathname. It continues down the path, using this method to interpret any other mount points it encounters,
1062 until it reaches the volume that houses the requested file.</P
1064 >Mount points act as the glue that connects the AFS file space, creating the illusion of a single, seamless file tree
1065 even when volumes reside on many different file server machines. A volume's contents are visible and accessible when the
1066 volume is mounted at a directory location, and are not accessible at all if the volume is not mounted.</P
1068 >You can mount a volume at more than one location in the file tree, but this is not recommended for two reasons. First,
1069 it distorts the hierarchical nature of the filespace. Second, the Cache Manager can become confused about which pathname it
1070 followed to reach the file (causing unpredictable output from the <SPAN
1076 > command, for example).
1077 However, if you mount a volume at more than one directory, the access control list (ACL) associated with the volume's root
1078 directory applies to all of the mount points.</P
1080 >There are several types of mount points, each of which the Cache Manager handles in a different way and each of which is
1081 appropriate for a different purpose. See <A
1082 HREF="c8420.html#HDRWQ208"
1083 >Mounting Volumes</A
1092 >About Volume Names</A
1095 >A read/write volume's name can be up to 22 characters in length. The Volume Server automatically adds the <SPAN
1107 > extensions to read-only and backup volumes
1108 respectively. Do not explicitly add the extensions to volume names, even if they are appropriate.</P
1110 >It is conventional for a volume's name to indicate the type of data it houses. For example, it is conventional to name
1111 all user volumes <SPAN
1117 >.username where username is the user's login name. Similarly, many cells
1118 elect to put system binaries in volumes with names that begin with the system type code. For a list of other naming
1120 HREF="c667.html#HDRWQ44"
1121 >Creating Volumes to Simplify Administration</A
1131 >Creating Read/write Volumes</A
1134 >A read/write volume is the most basic type of volume, and must exist before you can create read-only or backup versions of
1135 it. When you issue the <SPAN
1141 > command to create a read/write volume, the VL Server creates
1142 a VLDB entry for it which records the name you specify, assigns a read/write volume ID number, and reserves the next two
1143 consecutive volume ID numbers for read-only and backup versions that possibly are to be created later. At the same time, the
1144 Volume Server creates a volume header at the site you designate, allocating space on disk to record the name of the volume's
1145 root directory. The name is filled in when you issue the <SPAN
1151 > command to mount the
1152 volume, and matches the mount point name. The following is also recorded in the volume header: <UL
1155 >An initial ACL associated with the volume's root directory. By default it grants all seven AFS access permissions to
1160 >system:administrators</B
1162 > group. After you mount the volume, you can use the <SPAN
1168 > command to add other entries and to remove or change the entry for the <SPAN
1172 >system:administrators</B
1175 HREF="c31274.html#HDRWQ573"
1176 >Setting ACL Entries</A
1181 >A space quota, which limits the amount of disk space the read/write version of the volume can use on the file server
1182 partition. The default is of 5000 kilobyte blocks, but you can use the <SPAN
1195 > command to set a different quota.</P
1197 >To change the quota after creation, use the <SPAN
1203 > command as described in
1205 HREF="c8420.html#HDRWQ234"
1206 >Setting and Displaying Volume Quota and Current Size</A
1217 >To create (and mount) a read/write volume</A
1223 >Verify that you are listed in the <SPAN
1227 >/usr/afs/etc/UserList</B
1229 > file. If necessary, issue
1236 > command, which is fully described in <A
1237 HREF="c32432.html#HDRWQ593"
1239 display the users in the UserList file</A
1241 CLASS="programlisting"
1257 >Verify that you have the <SPAN
1293 >) permissions on the ACL of the directory where you plan to mount the volume. If necessary,
1300 > command, which is fully described in <A
1301 HREF="c31274.html#HDRWQ572"
1304 CLASS="programlisting"
1320 >Members of the <SPAN
1324 >system:administrators</B
1326 > group always implicitly have the <SPAN
1338 >) and by default also the <SPAN
1350 >) permission on every ACL and can use the <SPAN
1356 > command to grant other rights as necessary.</P
1363 >Select a site (disk partition on a file server machine) for the new volume. To verify that
1364 the site has enough free space to house the volume (now, or if it grows to use its entire quota), issue the <SPAN
1378 >The partition-related statistics in this command's output do not always agree with the corresponding values in the
1379 output of the standard UNIX <SPAN
1385 > command. The statistics reported by this command can be
1386 up to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency.
1387 Also, on some operating systems, the <SPAN
1393 > command's report of partition size includes
1394 reserved space not included in this command's calculation, and so is likely to be about 10% larger.</P
1398 CLASS="programlisting"
1420 CLASS="variablelist"
1432 >Is the shortest acceptable abbreviation of <SPAN
1450 >Specifies the file server machine for which to display partition size and usage.</P
1462 >Names one partition for which to display partition size and usage. If you omit it, the output displays the
1463 size and space available for all partitions on the machine.</P
1474 >Select a volume name, taking note of the information in <A
1475 HREF="c8420.html#HDRWQ184"
1491 > command to create the volume.
1493 CLASS="programlisting"
1505 >partition name</VAR
1518 >initial quota (KB)</VAR
1524 CLASS="variablelist"
1536 >Is the shortest acceptable abbreviation of <SPAN
1554 >Specifies the file server machine on which to place the volume.</P
1566 >Specifies the disk partition on which to place the volume.</P
1578 >Names the volume. It can be up to 22 alphanumeric and punctuation characters in length. Your cell possibly
1579 has naming conventions for volumes, such as beginning user volume names with the string <SPAN
1585 > and using the period to separate parts of the name.</P
1597 >Sets the volume's quota, as a number of kilobyte blocks. If you omit this argument, the quota is set to 5000
1622 the volume in the filespace. For complete syntax, see <A
1623 HREF="c8420.html#HDRWQ212"
1624 >To create a regular or read/write mount
1627 CLASS="programlisting"
1664 that the mount point refers to the correct volume. Complete instructions appear in <A
1665 HREF="c8420.html#HDRWQ211"
1669 CLASS="programlisting"
1706 > argument to record auxiliary information about the volume in its volume
1707 header. For example, you can record who owns the volume or where you have mounted it in the filespace. To display the
1708 information, use the <SPAN
1715 CLASS="programlisting"
1733 >offline message</VAR
1739 CLASS="variablelist"
1751 >Is an acceptable alias for <SPAN
1764 the shortest acceptable abbreviation).</P
1776 >Names the mount point of the volume with which to associate the message. Partial pathnames are interpreted
1777 relative to the current working directory.</P
1779 >Specify the read/write path to the mount point, to avoid the failure that results when you attempt to change
1780 a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at
1781 the pathname's second level (for example, <SPAN
1787 >). For further discussion
1788 of the concept of read/write and read-only paths through the filespace, see <A
1789 HREF="c8420.html#HDRWQ209"
1791 Mount Point Traversal</A
1804 >Specifies up to 128 characters of auxiliary information to record in the volume header.</P
1819 >About Clones and Cloning</A
1822 >To create a backup or read-only volume, the Volume Server begins by <SPAN
1828 > the read/write source
1829 volume to create a <SPAN
1835 >. The Volume Server creates the clone automatically when you issue the <SPAN
1847 > command (for a backup volume) or the
1854 > command (for a read-only volume). No special action is required on your
1857 >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
1864 >. The vnode index is a table of pointers between the files and directories in the volume and the
1865 physical disk blocks on the partition where the data resides. From the clone, backup and read-only volumes are created in the
1866 following manner: <UL
1869 >A read-only volume that occupies the same partition as its read/write source (also known as a <SPAN
1876 >), and a backup volume, are created by attaching a volume header to the clone. These volumes initially
1877 consume very little disk space, because the clone portion (the vnode index) points to exactly the same files as the
1878 read/write volume, as illustrated in <A
1879 HREF="c8420.html#FIGWQ191"
1881 >. The file sharing is possible only because
1882 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
1883 not actually removed from the partition, because the backup or read-only clone still points to it. Similarly, when a file
1884 in the read/write is changed, the entire original file is preserved on disk because the clone still points to it, and the
1885 read/write volume's vnode index changes to point to newly space for the changed file. When this happens, the backup or
1886 read-only volume is said to grow or start occupying actual disk space.</P
1890 >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
1891 the data in the read/write source volume. It occupies the same amount of disk space as the read/write volume did at the
1892 time the read-only volume was created.</P
1909 >Figure 1. File Sharing Between the Read/write Source and a Clone Volume</B
1919 >Replicating Volumes (Creating Read-only Volumes)</A
1928 > refers to creating a read-only copy of a read/write volume and distributing the copy to
1929 one or more additional file server machines. Replication makes a volume's contents accessible on more than one file server
1930 machine, which increases data availability. It can also increase system efficiency by reducing load on the network and File
1931 Server. Network load is reduced if a client machine's server preference ranks lead the Cache Manager to access the copy of a
1932 volume stored on the closest file server machine. Load on the File Server is reduced because it issues only one callback for all
1933 data fetched from a read-only volume, as opposed to a callback for each file fetched from a read/write volume. The single
1934 callback is sufficient for an entire read-only volume because the volume does not change except in response to administrator
1935 action, whereas each read/write file can change at any time.</P
1937 >Replicating a volume requires issuing two commands. First, use the <SPAN
1944 add one or more read-only site definitions to the volume's VLDB entry (a <SPAN
1950 > is a particular partition on
1951 a file server machine). Then use the <SPAN
1957 > command to clone the read/write source volume
1958 and distribute the clone to the defined read-only sites. You issue the <SPAN
1965 for each read-only site, but must reissue the <SPAN
1971 > command every time the read/write
1972 volume's contents change and you want to update the read-only volumes.</P
1974 >For users to have a consistent view of the file system, the release of updated volume contents to read-only sites must be
1975 atomic: either all read-only sites receive the new version of the volume, or all sites keep the version they currently have. The
1982 > command is designed to ensure that all copies of the volume's read-only version
1983 match both the read/write source and each other. In cases where problems such as machine or server process outages prevent
1984 successful completion of the release operation, AFS uses two mechanisms to alert you.</P
1986 >First, the command interpreter generates an error message on the standard error stream naming each read-only site that did
1987 not receive the new volume version. Second, during the release operation the Volume Location (VL) Server marks site definitions
1988 in the VLDB entry with flags (<SAMP
1989 CLASS="computeroutput"
1992 CLASS="computeroutput"
1995 that indicate whether or not the site has the new volume version. If any flags remain after the operation completes, it was not
1996 successful. The Cache Manager refuses to access a read-only site marked with the <SAMP
1997 CLASS="computeroutput"
2000 flag, which potentially imposes a greater load on the sites marked with the <SAMP
2001 CLASS="computeroutput"
2004 It is important to investigate and eliminate the cause of the failure and then to issue the <SPAN
2011 > command as many times as necessary to complete the release without errors.</P
2013 >The pattern of site flags remaining in the volume's VLDB entry after a failed release operation can help determine the
2014 point at which the operation failed. Use the <SPAN
2027 > command to display the VLDB entry. The VL Server sets the flags in concert with the Volume Server's
2028 operations, as follows: <OL
2032 >Before the operation begins, the VL Server sets the <SAMP
2033 CLASS="computeroutput"
2036 read/write site definition in the VLDB entry and the <SAMP
2037 CLASS="computeroutput"
2039 > flag on read-only site
2040 definitions (unless the read-only site has been defined since the last release operation and has no actual volume, in
2041 which case its site flag remains <SAMP
2042 CLASS="computeroutput"
2048 >If necessary, the Volume Server creates a temporary copy (a <SPAN
2054 >) of the read/write source
2055 called the ReleaseClone (see the following discussion of when the Volume Server does or does not create a new
2056 ReleaseClone.) It assigns the ReleaseClone its own volume ID number, which the VL Server records in the
2058 CLASS="computeroutput"
2060 > field of the source volume's VLDB entry.</P
2064 >The Volume Server distributes a copy of the ReleaseClone to each read-only site defined in the VLDB entry. As the
2065 site successfully receives the new clone, the VL Server sets the site's flag in the VLDB entry to <SAMP
2066 CLASS="computeroutput"
2073 >When all the read-only copies are successfully released, the VL Server clears all the <SAMP
2074 CLASS="computeroutput"
2077 > site flags. The ReleaseClone is no longer needed, so the Volume Server deletes it and the VL
2078 Server erases its ID from the VLDB entry.</P
2083 >By default, the Volume Server determines automatically whether or not it needs to create a new ReleaseClone: <UL
2086 >If there are no flags (<SAMP
2087 CLASS="computeroutput"
2090 CLASS="computeroutput"
2094 CLASS="computeroutput"
2096 >) on site definitions in the VLDB entry, the previous <SPAN
2102 > command completed successfully and all read-only sites currently have the same volume.
2103 The Volume Server infers that the current <SPAN
2109 > command was issued because the
2110 read/write volume has changed. The Volume Server creates a new ReleaseClone and distributes it to all of the read-only
2115 >If any site definition in the VLDB entry is marked with a flag, either the previous release operation did not
2116 complete successfully or a new read-only site was defined since the last release. The Volume Server does not create a new
2117 ReleaseClone, instead distributing the existing ReleaseClone to sites marked with the <SAMP
2118 CLASS="computeroutput"
2122 CLASS="computeroutput"
2124 > flag. As previously noted, the VL Server marks
2125 each VLDB site definition with the <SAMP
2126 CLASS="computeroutput"
2128 > flag as the site receives the
2129 ReleaseClone, and clears all flags after all sites successfully receive it.</P
2134 >To override the default behavior, forcing the Volume Server to create and release a new ReleaseClone to the read-only
2135 sites, include the <SPAN
2141 > flag. This is appropriate if, for example, the data at the read/write
2142 site has changed since the existing ReleaseClone was created during the previous release operation.</P
2149 >Using Read-only Volumes Effectively</A
2152 >For maximum effectiveness, replicate only volumes that satisfy two criteria: <UL
2155 >The volume's contents are heavily used. Examples include a volume housing binary files for text editors or other
2156 popular application programs, and volumes mounted along heavily traversed directory paths such as the paths leading to
2157 user home directories. It is an inefficient use of disk space to replicate volumes for which the demand is low enough
2158 that a single File Server can easily service all requests.</P
2162 >The volume's contents change infrequently. As noted, file system consistency demands that the contents of
2163 read-only volumes must match each other and their read/write source at all times. Each time the read/write volume
2164 changes, you must issue the <SPAN
2170 > command to update the read-only volumes. This
2171 can become tedious (and easy to forget) if the read/write volume changes frequently.</P
2176 >Explicitly mounting a read-only volume (creating a mount point that names a volume with a <SPAN
2182 > extension) is not generally necessary or appropriate. The Cache Manager has a built-in bias
2183 to access the read-only version of a replicated volume whenever possible. As described in more detail in <A
2184 HREF="c8420.html#HDRWQ209"
2185 >The Rules of Mount Point Traversal</A
2186 >, when the Cache Manager encounters a mount point it reads the
2187 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
2188 mount point resides in a read-only volume and names a read/write volume (one that does not have a <SPAN
2200 > extension), the Cache Manager always attempts to
2201 access a read-only copy of the volume. Thus there is normally no reason to force the Cache Manager to access a read-only
2202 volume by mounting it explicitly.</P
2204 >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
2205 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
2207 HREF="c8420.html#HDRWQ190"
2208 >About Clones and Cloning</A
2209 >). Only if a large number of files are removed or changed in
2210 the read/write volume does the read-only copy occupy much disk space. That normally does not happen because the appropriate
2211 response to changes in a replicated read/write volume is to reclone it. The other reason to place a read-only volume at the
2212 read/write site is that the Cache Manager does not attempt to access the read/write version of a replicated volume if all
2213 read-only copies become inaccessible. If the file server machine housing the read/write volume is the only accessible machine,
2214 the Cache Manager can access the data only if there is a read-only copy at the read/write site.</P
2216 >The number of read-only sites to define depends on several factors. Perhaps the main trade-off is between the level of
2217 demand for the volume's contents and how much disk space you are willing to use for multiple copies of the volume. Of course,
2218 each prospective read-only site must have enough available space to accommodate the volume. The limit on the number of
2219 read-only copies of a volume is determined by the maximum number of site definitions in a volume's VLDB entry, which is
2220 defined in the <SPAN
2224 > IBM AFS Release Notes</I
2226 >. The site housing the read/write and backup versions of the volume
2227 counts as one site, and each read-only site counts as an additional site (even the read-only site defined on the same file
2228 server machine and partition as the read/write site counts as a separate site). Note also that the Volume Server permits only
2229 one read-only copy of a volume per file server machine.</P
2237 >Replication Scenarios</A
2240 >The instructions in the following section explain how to replicate a volume for which no read-only sites are currently
2241 defined. However, you can also use the instructions in other common situations: <UL
2244 >If you are releasing a new clone to sites that already exist, you can skip Step <A
2245 HREF="c8420.html#LIWQ196"
2248 It can still be useful to issue the <SPAN
2254 > command, however, to verify that the
2255 desired read-only sites are defined.</P
2259 >If you are adding new read-only sites to existing ones, perform all of the steps. In Step <A
2260 HREF="c8420.html#LIWQ197"
2268 > command for the new sites
2273 >If you are defining sites but do not want to release a clone to them yet, stop after Step <A
2274 HREF="c8420.html#LIWQ197"
2276 >and continue when you are ready.</P
2280 >If you are removing one or more sites before releasing a new clone to the remaining sites, follow the instructions
2281 for site removal in <A
2282 HREF="c8420.html#HDRWQ235"
2283 >Removing Volumes and their Mount Points</A
2284 >and then start with Step
2286 HREF="c8420.html#LIWQ198"
2299 >To replicate a read/write volume (create a read-only volume)</A
2308 >Verify that you are listed in the <SPAN
2312 >/usr/afs/etc/UserList</B
2315 file. If necessary, issue the <SPAN
2321 > command, which is fully described in <A
2322 HREF="c32432.html#HDRWQ593"
2323 >To display the users in the UserList file</A
2325 CLASS="programlisting"
2344 >Select one or more sites at which to replicate the volume. There are several factors to
2348 >How many sites are already defined. As previously noted, it is usually appropriate to define a read-only site
2349 at the read/write site. Also, the Volume Server permits only one read-only copy of a volume per file server machine.
2350 To display the volume's current sites, issue the <SPAN
2357 described fully in <A
2358 HREF="c8420.html#HDRWQ221"
2359 >Displaying One Volume's VLDB Entry and Volume Header</A
2362 CLASS="programlisting"
2371 >volume name or ID</VAR
2376 >The final lines of output display the volume's site definitions from the VLDB.</P
2380 >Whether your cell dedicates any file server machines to housing read-only volumes only. In general, only very
2381 large cells use read-only server machines.</P
2385 >Whether a site has enough free space to accommodate the volume. A read-only volume requires the same amount of
2386 space as the read/write version (unless it is at the read/write site itself). The first line of output from the
2393 > command displays the read/write volume's current size in kilobyte
2394 blocks, as shown in <A
2395 HREF="c8420.html#HDRWQ221"
2396 >Displaying One Volume's VLDB Entry and Volume Header</A
2399 >To display the amount of space available on a file server machine's partitions, use the <SPAN
2405 > command, which is described fully in <A
2406 HREF="c8420.html#HDRWQ185"
2408 Read/write Volumes</A
2411 CLASS="programlisting"
2423 >partition name</VAR
2441 > command to define each new read-only
2442 site in the VLDB. <PRE
2443 CLASS="programlisting"
2455 >partition name</VAR
2458 >volume name or ID</VAR
2464 CLASS="variablelist"
2476 >Is the shortest acceptable abbreviation of <SPAN
2494 >Defines the file server machine for the new site.</P
2506 >Names a disk partition on the machine machine name.</P
2513 >volume name or ID</B
2518 >Identifies the read/write volume to be replicated, either by its complete name or its volume ID
2536 > Verify that the <SPAN
2542 > process (which incorporates the Volume Server) is functioning normally on each file server
2543 machine where you have defined a read-only site, and that the <SPAN
2550 Volume Location Server) is functioning correctly on each database server machine. Knowing that they are functioning
2551 eliminates two possible sources of failure for the release. Issue the <SPAN
2558 on each file server machine housing a read-only site for this volume and on each database server machine. The command is
2559 described fully in <A
2560 HREF="c6449.html#HDRWQ158"
2561 >Displaying Process Status and Information from the BosConfig File</A
2564 CLASS="programlisting"
2595 > command to clone the read/write source
2596 volume and distribute the clone to each read-only site. <PRE
2597 CLASS="programlisting"
2606 >volume name or ID</VAR
2618 CLASS="variablelist"
2630 >Is the shortest acceptable abbreviation of <SPAN
2643 >volume name or ID</B
2648 >Identifies the read/write volume to clone, either by its complete name or volume ID number. The read-only
2649 version is given the same name with a <SPAN
2655 > extension. All read-only copies
2656 share the same read-only volume ID number.</P
2668 >Creates and releases a brand new clone.</P
2692 that no site definition in the VLDB entry is marked with an <SAMP
2693 CLASS="computeroutput"
2697 CLASS="computeroutput"
2699 > flag. The command is described fully in <A
2700 HREF="c8420.html#HDRWQ221"
2702 One Volume's VLDB Entry and Volume Header</A
2704 CLASS="programlisting"
2713 >volume name or ID</VAR
2720 >If any flags appear in the output from Step <A
2721 HREF="c8420.html#LIWQ200"
2724 HREF="c8420.html#LIWQ198"
2727 HREF="c8420.html#LIWQ199"
2729 >until the Volume Server does not produce any error messages
2730 during the release operation and the flags no longer appear. Do not issue the <SPAN
2737 command when you know that the read/write site or any read-only site is inaccessible due to network, machine or server process
2747 >Creating Backup Volumes</A
2756 > is a clone that resides at the same site as its read/write source (to review the
2757 concept of cloning, see <A
2758 HREF="c8420.html#HDRWQ190"
2759 >About Clones and Cloning</A
2760 >). Creating a backup version of a volume has two
2764 >It is by convention the first step when dumping a volume's contents to tape with the AFS Backup System. A volume is
2765 inaccessible while it is being dumped, so instead of dumping the read/write volume, you create and dump a backup version.
2766 Users do not normally access the backup version, so it is unlikely that the dump will disturb them. For more details, see
2768 HREF="c15383.html#HDRWQ296"
2774 >It enables users to restore mistakenly deleted or changed data themselves, freeing you for more crucial tasks. The
2775 backup version captures the state of its read/write source at the time the backup is made, and its contents cannot change.
2776 Mount the backup version in the filespace so that users can restore a file to its state at the time you made the backup.
2778 HREF="c8420.html#HDRWQ204"
2779 >Making the Contents of Backup Volumes Available to Users</A
2790 >Backing Up Multiple Volumes at Once</A
2799 > command creates a backup version of many read/write volumes at once.
2800 This command is useful when preparing for large-scale backups to tape using the AFS Backup System.</P
2802 >To clone every read/write volume listed in the VLDB, omit all of the command's options. Otherwise, combine the command's
2803 options to clone various groups of volumes. The options use one of two basic criteria to select volumes: location (the
2816 > arguments) or presence in the volume
2817 name of one of a set of specified character strings (the <SPAN
2837 >To clone only volumes that reside on one file server machine, include the <SPAN
2844 argument. To clone only volumes that reside on one partition, combine the <SPAN
2857 > arguments. The <SPAN
2863 > argument can also be
2864 used alone to clone volumes that reside on the indicated partition on every file server machine. These arguments can be
2865 combined with those that select volumes based on their names.</P
2885 > options (with or without the <SPAN
2897 > arguments) in the indicated ways to select volumes based on character strings contained in
2901 >To clone every read/write volume at the specified location whose name includes one of a set of specified character
2902 strings (for example, begins with <SPAN
2908 > or includes the string <SPAN
2920 > argument or combine the <SPAN
2936 >To clone every read/write volume at the specified location except those whose name includes one of a set of
2937 specified character strings, use the <SPAN
2943 > argument or combine the <SPAN
2959 >To clone every read/write volume at the specified location whose name includes one of one of a set of specified
2960 character strings, except those whose names include one of a different set of specified character strings, combine the
2973 > arguments. The command creates a
2974 list of all volumes that match the <SPAN
2980 > argument and then removes from the list the
2981 volumes that match the <SPAN
2987 > argument. For effective results, the strings specified
2994 > argument must designate a subset of the volumes specified by the
3009 > flag is combined with the <SPAN
3021 > arguments, the command creates a list of
3022 all volumes that do not match the <SPAN
3028 > argument and then adds to the list any
3029 volumes that match the <SPAN
3035 > argument. As when the <SPAN
3041 > flag is not used, the result is effective only if the strings specified by the <SPAN
3047 > argument designate a subset of the volumes specified by the <SPAN
3070 > arguments both accept
3071 multiple values, which can be used to define disjoint groups of volumes. Each value can be one of two types: <OL
3075 >A simple character string, which matches volumes whose name begin with the string. All characters are interpreted
3076 literally (that is, characters that potentially have special meaning to the command shell, such as the period, have only
3077 their literal meaning).</P
3081 >A regular expression, which matches volumes whose names contain the expressions. Place a caret ( <SPAN
3087 >) at the beginning of the expression, and enclose the entire string in single quotes ( <SPAN
3099 >). Explaining regular expressions is outside the scope of
3100 this reference page; see the UNIX manual page for <SPAN
3108 HREF="c12776.html#HDRWQ265"
3109 >Defining and Displaying Volume Sets and Volume Entries</A
3110 >. As an example, the
3111 following expression matches volumes that have the string <SPAN
3117 > anywhere in their names:
3119 CLASS="programlisting"
3124 >-prefix '^.*aix'</B
3133 >To display a list of the volumes to be cloned, without actually cloning them, include the <SPAN
3139 > flag. To display a statement that summarizes the criteria being used to select volume, include
3148 >To back up a single volume, use the <SPAN
3154 > command, which employs a more
3155 streamlined technique for finding a single volume.</P
3163 >Automating Creation of Backup Volumes</A
3166 >Most cells find that it is best to make a new backup version of relevant volumes each day. It is best to create the
3167 backup versions at a time when usage is low, because the backup operation causes the read/write volume to be unavailable
3170 >You can either issue the necessary the <SPAN
3183 > commands at the console or create a <SPAN
3189 > entry in the <SPAN
3195 > file on a file server machine, which eliminates the need for an administrator to initiate the
3196 backup operation.</P
3198 >The following example command creates a <SPAN
3204 > process called <SPAN
3214 >/usr/afs/local/BosConfig</B
3216 > file on the machine
3223 >. The process runs every day at 1:00 a.m. to create a backup version of every
3224 volume in the cell whose name starts with the string <SPAN
3236 > flag enables the process to invoke the privileged <SPAN
3243 > command while unauthenticated. Note that the <SPAN
3249 > argument specifies a
3250 complete pathname for the <SPAN
3256 > binary, because the PATH environment variable for the BOS
3257 Server (running as the local superuser <SPAN
3263 >) generally does not include the path to AFS
3265 CLASS="programlisting"
3270 >bos create fs3.abc.com backupusers cron</B
3277 >-cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" "1:00"</B
3289 >Making the Contents of Backup Volumes Available to Users</A
3292 >As noted, a backup volume preserves the state of the read/write source at the time the backup is created. Many cells
3293 choose to mount backup volumes so that users can access and restore data they have accidentally deleted or changed since the
3294 last backup was made, without having to request help from administrators. The most sensible place to mount the backup version
3295 of a user volume is at a subdirectory of the user's home directory. Suitable names for this directory include <SPAN
3307 >. The subdirectory looks just like the user's own
3308 home directory as it was at the time the backup was created, with all files and subdirectories in the same relative
3311 >If you do create and mount backup volumes for your users, inform users of their existence. The <SPAN
3318 > does not mention backup volumes because making them available to users is optional. Explain to users how
3319 often you make a new backup, so they know what they can recover. Remind them also that the data in their backup volume cannot
3320 change; however, they can use the standard UNIX <SPAN
3326 > command to copy it into their home volume
3327 and modify it there. Reassure users that the data in their backup volumes does not count against their read/write volume
3336 >To create and mount a backup volume</A
3342 >Verify that you are listed in the <SPAN
3346 >/usr/afs/etc/UserList</B
3348 > file. If necessary, issue
3355 > command, which is fully described in <A
3356 HREF="c32432.html#HDRWQ593"
3358 display the users in the UserList file</A
3360 CLASS="programlisting"
3376 >Verify that you have the <SPAN
3400 >) permissions on the ACL of the directory in which
3401 you wish to mount the volume. If necessary, issue the <SPAN
3407 > command, which is fully
3409 HREF="c31274.html#HDRWQ572"
3412 CLASS="programlisting"
3426 >Members of the <SPAN
3430 >system:administrators</B
3432 > group always implicitly have the <SPAN
3444 >) and by default also the <SPAN
3456 >) permission on every ACL and can use the <SPAN
3462 > command to grant other rights as necessary.</P
3475 > command to create a backup version of a
3476 read/write source volume. The message shown confirms the success of the backup operation. <PRE
3477 CLASS="programlisting"
3486 >volume name or ID</VAR
3487 >> Created backup volume for volume name or ID
3492 CLASS="variablelist"
3504 >Must be typed in full.</P
3511 >volume name or ID</B
3516 >Identifies the read/write volume to back up, either by its complete name or volume ID number. The backup
3517 volume has the same name with the addition of the <SPAN
3523 > extension. It has its
3524 own volume ID number.</P
3548 > to mount the backup volume. While this step is optional, Cache Managers cannot access the volume's
3549 contents if it is not mounted. <PRE
3550 CLASS="programlisting"
3574 CLASS="variablelist"
3586 >Is the shortest acceptable abbreviation of <SPAN
3604 >Names the mount point to create. Do not create a file or directory of the same name beforehand. Partial
3605 pathnames are interpreted relative to the current working directory. For the backup version of a user volume, the
3606 conventional location is the user's home directory.</P
3618 >Is the full name of the backup volume.</P
3639 that the mount point refers to the correct volume. Complete instructions appear in <A
3640 HREF="c8420.html#HDRWQ211"
3644 CLASS="programlisting"
3666 >To create multiple backup volumes at once</A
3672 >Verify that you are listed in the <SPAN
3676 >/usr/afs/etc/UserList</B
3678 > file. If necessary, issue
3685 > command, which is fully described in <A
3686 HREF="c32432.html#HDRWQ593"
3688 display the users in the UserList file</A
3690 CLASS="programlisting"
3712 > command to create a backup version of every read/write
3713 volume that shares the same prefix or site. The effects of combining the three arguments are described in <A
3714 HREF="c8420.html#HDRWQ202"
3715 >Backing Up Multiple Volumes at Once</A
3717 CLASS="programlisting"
3732 >common prefix on volume(s)</VAR
3751 >partition name</VAR
3767 >negative prefix on volume(s)</VAR
3786 CLASS="variablelist"
3798 >Is the shortest acceptable abbreviation of <SPAN
3816 >Specifies one or more simple character strings or regular expressions of any length; a volume whose name
3817 includes the string is placed on the list of volumes to be cloned. Include field separators (such as periods) if
3818 appropriate. This argument can be combined with any combination of the <SPAN
3855 >Specifies the file server machine housing the volumes to backup. Can be combined with any combination of the
3892 >Specifies the partition housing the volumes you wish to backup. Can be combined with any combination of the
3929 >Indicates that all volumes except those indicated with the <SPAN
3936 are to be backed up. The <SPAN
3942 > argument must be provided along with this one.
3943 Can also be combined with any combination of the <SPAN
3961 > arguments; or with both the
3974 > arguments, but not with the
3981 > argument alone.</P
3993 >Specifies one or more simple character strings or regular expressions of any length; a volume whose name
3994 does not include the string is placed on the list of volumes to be cloned. Can be combined with any combination of
4013 > arguments; in addition, it can be combined with both the <SPAN
4025 > options, but not with the <SPAN
4043 >Displays on the standard output stream a list of the volumes to be cloned, without actually cloning
4056 >Displays on the standard output stream a statement that summarizes the criteria being used to select
4057 volumes, if combined with the <SPAN
4063 > flag; otherwise, traces the cloning
4064 operation for each volume.</P
4079 >Mounting Volumes</A
4082 >Mount points make the contents of AFS volumes visible and accessible in the AFS filespace, as described in <A
4083 HREF="c8420.html#HDRWQ183"
4084 >About Mounting Volumes</A
4085 >. This section discusses in more detail how the Cache Manager handles mount
4086 points as it traverses the filespace. It describes the three types of mount points, their purposes, and how to distinguish
4087 between them, and provides instructions for creating, removing, and examining mount points.</P
4094 >The Rules of Mount Point Traversal</A
4097 >The Cache Manager observes three basic rules as it traverses the AFS filespace and encounters mount points:
4107 > Access Backup and Read-only Volumes When Specified</P
4109 >When the Cache Manager encounters a mount point that specifies a volume with either a <SPAN
4121 > extension, it accesses that type of
4122 volume only. If a mount point does not have either a <SPAN
4134 > extension, the Cache Manager uses Rules 2 and 3.</P
4136 >For example, the Cache Manager never accesses the read/write version of a volume if the mount point names the
4137 backup version. If the specified version is inaccessible, the Cache Manager reports an error.</P
4147 > Follow the Read-only Path When Possible</P
4149 >If a mount point resides in a read-only volume and the volume that it references is replicated, the Cache Manager
4150 attempts to access a read-only copy of the volume; if the referenced volume is not replicated, the Cache Manager
4151 accesses the read/write copy. The Cache Manager is thus said to prefer a <SPAN
4158 filespace, accessing read-only volumes when they are available.</P
4160 >The Cache Manager starts on the read-only path in the first place because it always accesses a read-only copy of
4167 > volume if it exists; the volume is mounted at the root of a cell's AFS
4168 filespace (named <SPAN
4174 > by convention). That is, if the <SPAN
4180 > volume is replicated, the Cache Manager attempts to access a read-only copy of it rather
4181 than the read/write copy. This rule then keeps the Cache Manager on a read-only path as long as each successive volume
4182 is replicated. The implication is that both the <SPAN
4194 > volumes must be replicated for the Cache Manager to access replicated volumes mounted
4195 below them in the AFS filespace. The volumes are conventionally mounted at the <SPAN
4211 > directories, respectively.</P
4221 > Once on a Read/write Path, Stay There</P
4223 >If a mount point resides in a read/write volume and the volume name does not have a <SPAN
4235 > extension, the Cache Manager attempts to
4236 access only the a read/write version of the volume. The access attempt fails with an error if the read/write version is
4237 inaccessible, even if a read-only version is accessible. In this situation the Cache Manager is said to be on a
4244 > and cannot switch back to the read-only path unless mount point explicitly names a
4251 > extension. (Cellular mount points are an important exception to
4252 this rule, as explained in the following discussion.</P
4263 >The Three Types of Mount Points</A
4266 >AFS uses three types of mount points, each appropriate for a different purpose because of how the Cache Manager handles
4270 >When the Cache Manager crosses a <SPAN
4276 > mount point, it obeys all three of the mount point
4277 traversal rules previously described.</P
4279 >AFS performs best when the vast majority of mount points in the filespace are regular, because the mount point
4280 traversal rules promote the most efficient use of both replicated and nonreplicated volumes. Because there are likely to
4281 be multiple read-only copies of a replicated volume, it makes sense for the Cache Manager to access one of them rather
4282 than the single read/write version, and the second rule leads it to do so. If a volume is not replicated, the third rule
4283 means that the Cache Manager still accesses the read/write volume when that is the only type available. In other words,
4284 a regular mount point does not force the Cache Manager always to access read-only volumes (it is explicitly not a
4285 "read-only mount point").</P
4287 >To create a regular mount point, use the <SPAN
4293 > command as described in <A
4294 HREF="c8420.html#HDRWQ212"
4295 >To create a regular or read/write mount point</A
4304 >To enable the Cache Manager to access the read-only version of a replicated volume named by a regular mount
4305 point, all volumes that are mounted above it in the pathname must also be replicated. That is the only way the Cache
4306 Manager can stay on a read-only path to the target volume.</P
4312 >When the Cache Manager crosses a <SPAN
4318 > mount point, it attempts to access only the
4319 volume version named in the mount point. If the volume name is the base (read/write) form, without a <SPAN
4331 > extension, the Cache Manager accesses the
4332 read/write version of the volume, even if it is replicated. In other words, the Cache Manager disregards the second
4333 mount point traversal rule when crossing a read/write mount point: it switches to the read/write path through the
4336 >It is conventional to create only one read/write mount point in a cell's filespace, using it to mount the cell's
4343 > volume just below the AFS filespace root (by convention, <SPAN
4352 >). As indicated, it is conventional to place a period at
4353 the start of the read/write mount point's name (for example, <SPAN
4360 distinguishes the read/write mount point from the regular mount point for the <SPAN
4367 volume at the same level. This is the only case in which it is conventional to create two mount points for the same
4368 volume. A desirable side effect of this naming convention for this read/write mount point is that it does not appear in
4369 the output of the UNIX <SPAN
4375 > command unless the <SPAN
4382 is included, essentially hiding it from regular users who have no use for it.</P
4384 >The existence of a single read/write mount point at this point in the filespace provides access to the read/write
4385 version of every volume when necessary, because it puts the Cache Manager on a read/write path right at the top of the
4386 filespace. At the same time, the regular mount point for the <SPAN
4393 Cache Manager on a read-only path most of the time.</P
4395 >Using a read/write mount point for a read-only or backup volume is acceptable, but unnecessary. The first rule of
4396 mount point traversal already specifies that the Cache Manager accesses them if the volume name in a regular mount point
4411 >To create a read/write mount point, use the <SPAN
4423 > command as described in <A
4424 HREF="c8420.html#HDRWQ212"
4425 >To create a regular or read/write
4431 >When the Cache Manager crosses a <SPAN
4437 > mount point, it accesses the indicated volume in
4438 the specified cell, which is normally a foreign cell. (If the mount point does not name a cell along with the volume,
4439 the Cache Manager accesses the volume in the cell where the mount point resides.) When crossing a regular cellular mount
4440 point, the Cache Manager disregards the third mount point traversal rule. Instead, it accesses a read-only version of
4441 the volume if it is replicated, even if the volume that houses the mount point is read/write.</P
4443 >It is inappropriate to circumvent this behavior by creating a read/write cellular mount point, because traversing
4444 the read/write path imposes an unfair load on the foreign cell's file server machines. The File Server must issue a
4445 callback for each file fetched from the read/write volume, rather than single callback required for a read-only volume.
4446 In any case, only a cell's own administrators generally need to access the read/write versions of replicated
4449 >It is conventional to create cellular mount points only at the second level in a cell's filespace, using them to
4450 mount foreign cells' <SPAN
4456 > volumes just below the AFS filespace root (by
4457 convention, at <SPAN
4465 >foreign_cellname</VAR
4467 enables local users to access the foreign cell's filespace, assuming they have the necessary permissions on the ACL of
4468 the volume's root directory and that there is an entry for the foreign cell in each local client machine's <SPAN
4472 >/usr/vice/etc/CellServDB</B
4474 > file, as described in <A
4475 HREF="c21473.html#HDRWQ406"
4476 >Maintaining Knowledge of
4477 Database Server Machines</A
4480 >Creating cellular mount points at other levels in the filespace and mounting foreign volumes other than the
4487 > volume is not generally appropriate. It can be confusing to users if the
4488 Cache Manager switches between cells at various points in a pathname.</P
4490 >To create a regular cellular mount point, use the <SPAN
4496 > argument to specify the
4497 cell name, as described in <A
4498 HREF="c8420.html#HDRWQ213"
4499 >To create a cellular mount point</A
4505 >To examine a mount point, use the <SPAN
4511 > command as described in <A
4512 HREF="c8420.html#HDRWQ211"
4513 >To display a mount point</A
4514 >. The command's output uses distinct notation to identify regular,
4515 read/write, and cellular mount points. To remove a mount point, use the <SPAN
4523 HREF="c8420.html#HDRWQ215"
4524 >To remove a mount point</A
4533 >Creating a mount point in a foreign cell</A
4536 >Creating a mount point in a foreign cell's filespace (as opposed to mounting a foreign volume in the local cell) is
4537 basically the same as creating a mount point in the local filespace. The differences are that the <SPAN
4544 > command's directory argument specifies a pathname in the foreign cell rather than the local cell, and you
4545 must have the required permissions on the ACL of the foreign directory where you are creating the mount point. The <SPAN
4557 > argument always specifies the cell in which
4558 the volume resides, not the cell in which to create the mount point.</P
4566 >To display a mount point</A
4579 CLASS="programlisting"
4594 CLASS="variablelist"
4606 >Is the shortest acceptable abbreviation of <SPAN
4624 >Names the mount point to display.</P
4632 >If the specified directory is a mount point, the output is of the following form:</P
4634 CLASS="programlisting"
4635 > 'directory' is a mount point for volume 'volume name'
4638 >For a regular mount point, a number sign (<SAMP
4639 CLASS="computeroutput"
4641 >) precedes the volume name string, as in the
4642 following example command issued on a client machine in the <SPAN
4650 CLASS="programlisting"
4655 >fs lsmount /afs/abc.com/usr/terry</B
4658 '/afs/abc.com/usr/terry' is a mount point for volume '#user.terry'
4661 >For a read/write mount point, a percent sign (<SAMP
4662 CLASS="computeroutput"
4664 >) precedes the volume name string, as in
4665 the following example command issued on a client machine in the <SPAN
4672 administrators have followed the convention of preceding the read/write mount point's name with a period.</P
4674 CLASS="programlisting"
4679 >fs lsmount /afs/.abc.com</B
4682 '/afs/.abc.com' is a mount point for volume '%root.cell'
4685 >For a cellular mount point, a cell name and colon (<SAMP
4686 CLASS="computeroutput"
4688 >) follow the number or percent sign
4689 and precede the volume name string, as in the following example command issued on a client machine in the <SPAN
4697 CLASS="programlisting"
4702 >fs lsmount /afs/ghi.gov</B
4705 '/afs/ghi.gov' is a mount point for volume '#ghi.gov:root.cell'
4708 >For a symbolic link to a mount point, the output is of the form shown in the following example command issued on a
4709 client machine in the <SPAN
4717 CLASS="programlisting"
4722 >fs lsmount /afs/abc</B
4725 '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
4728 >If the directory is not a mount point or is not in AFS, the output reads as follows.</P
4730 CLASS="programlisting"
4731 > 'directory' is not a mount point.
4734 >If the output is garbled, it is possible that the mount point has become corrupted in the local cache. Use the <SPAN
4740 > command as described in <A
4741 HREF="c21473.html#HDRWQ413"
4742 >To flush one or more mount
4744 >. This forces the Cache Manager to refetch the mount point.</P
4752 >To create a regular or read/write mount point</A
4758 >Verify that you have the <SPAN
4782 >) permissions on the ACL of the directory where you
4783 are placing the mount point. If necessary, issue the <SPAN
4789 > command, which is fully
4791 HREF="c31274.html#HDRWQ572"
4794 CLASS="programlisting"
4816 > command to create the mount point. Include the <SPAN
4822 > flag if creating a read/write mount point. <PRE
4823 CLASS="programlisting"
4847 CLASS="variablelist"
4859 >Is the shortest acceptable abbreviation for <SPAN
4877 >Names the mount point to create. A file or directory with the same name cannot already exist. A partial
4878 pathname is interpreted relative to the current working directory.</P
4880 >Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create
4881 a new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period
4882 before the cell name at the pathname's second level (for example, <SPAN
4889 For further discussion of the concept of read/write and read-only paths through the filespace, see <A
4890 HREF="c8420.html#HDRWQ209"
4891 >The Rules of Mount Point Traversal</A
4904 >Specifies the volume's full name, including the <SPAN
4916 > extension for a backup or read-only volume, if appropriate.</P
4928 >Creates a read/write mount point.</P
4942 >To create a cellular mount point</A
4948 >Verify that you have the <SPAN
4972 >) permissions on the ACL of the directory where you
4973 are placing the mount point. If necessary, issue the <SPAN
4979 > command, which is fully
4981 HREF="c31274.html#HDRWQ572"
4984 CLASS="programlisting"
5003 >If you are mounting one or more foreign cells' <SPAN
5010 volume at the second level in your filespace and your cell's <SPAN
5017 replicated, you must create a temporary mount point for the <SPAN
5023 > volume's read/write
5024 version in a directory on which the ACL grants you the <SPAN
5036 > permissions. The following command creates a mount point called <SPAN
5042 > in your cell's <SPAN
5052 directory (the entry point to the read/write path in your cell).</P
5054 >Substitute your cell's name for cellname.</P
5056 CLASS="programlisting"
5071 >fs mkmount new_cells root.afs</B
5091 > command with the <SPAN
5098 argument to create a cellular mount point. Repeat the command for each cellular mount point as required. <PRE
5099 CLASS="programlisting"
5126 CLASS="variablelist"
5138 >Is the shortest acceptable abbreviation for <SPAN
5156 >Names the mount point to create. A file or directory with the same name cannot already exist. A partial
5157 pathname is interpreted relative to the current working directory. If you are mounting a foreign cell's <SPAN
5163 > volume, the standard value for this argument is the cell's complete Internet
5176 >Specifies the volume's full name, usually <SPAN
5182 > for a cellular mount
5195 >Specifies the complete Internet domain name of the cell in which the volume resides.</P
5203 >If you performed the instructions in Step <A
5204 HREF="c8420.html#LIWQ214"
5213 > command to release the new version of the <SPAN
5220 read-only sites. (This command requires that you be listed in your cell's <SPAN
5224 >/usr/afs/etc/UserList</B
5226 > file. If necessary, verify by issuing the <SPAN
5233 > command, which is fully described in <A
5234 HREF="c32432.html#HDRWQ593"
5235 >To display the users in the UserList
5239 >Also issue the <SPAN
5245 > command to force the local Cache Manager to access
5246 the new replica of the <SPAN
5252 > volume. If desired, you can also remove the temporary
5259 > mount point from the <SPAN
5270 CLASS="programlisting"
5275 >vos release root.afs</B
5299 >fs rmmount new_cells</B
5304 >For your users to access a newly mounted foreign cell, you must also create an entry for it in each client machine's
5309 >/usr/vice/etc/CellServDB</B
5311 > file and either reboot the machine or use the <SPAN
5317 > command to insert the entry directly into its kernel memory. See the instructions in
5319 HREF="c21473.html#HDRWQ406"
5320 >Maintaining Knowledge of Database Server Machines</A
5331 >To remove a mount point</A
5337 >Verify that you have the <SPAN
5350 the ACL of the directory from which you are removing the mount point. If necessary, issue the <SPAN
5357 > command, which is fully described in <A
5358 HREF="c31274.html#HDRWQ572"
5361 CLASS="programlisting"
5375 >Members of the <SPAN
5379 >system:administrators</B
5381 > group always implicitly have the <SPAN
5393 >) and by default also the <SPAN
5405 >) permission on every ACL and can use the <SPAN
5411 > command to grant other rights as necessary.</P
5421 > command to remove the mount point. The volume still exists,
5422 but its contents are inaccessible if this is the only mount point for it. <PRE
5423 CLASS="programlisting"
5438 CLASS="variablelist"
5450 >Is the shortest acceptable abbreviation of <SPAN
5468 >Names the mount point to remove. A partial pathname is interpreted relative to the current working
5471 >Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete
5472 a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before
5473 the cell name at the pathname's second level (for example, <SPAN
5480 further discussion of the concept of read/write and read-only paths through the filespace, see <A
5481 HREF="c8420.html#HDRWQ209"
5482 >The Rules of Mount Point Traversal</A
5498 >Displaying Information About Volumes</A
5501 >This section explains how to display information about volumes. If you know a volume's name or volume ID number, there are
5502 commands for displaying its VLDB entry, its volume header, or both. Other commands display the name or location of the volume
5503 that contains a specified file or directory.</P
5505 >For instructions on displaying a volume's quota, see <A
5506 HREF="c8420.html#HDRWQ234"
5507 >Setting and Displaying Volume Quota and
5516 >Displaying VLDB Entries</A
5525 > command displays the VLDB entry for the volumes indicated by the
5526 combination of arguments you provide. The possibilities are listed here from most to least inclusive: <UL
5529 >To display every entry in the VLDB, provide no arguments. It can take a long time to generate the output,
5530 depending on the number of entries.</P
5534 >To display every VLDB entry that mentions a specific file server machine as the site of a volume, specify the
5535 machine's name with the <SPAN
5545 >To display every VLDB entry that mentions a certain partition on any file server machine as the site of a volume,
5546 specify the partition name with the <SPAN
5556 >To display every VLDB entry that mentions a certain partition on a certain file server machine as the site of a
5557 volume, combine the <SPAN
5574 >To display a single VLDB entry, specify a volume name or ID number with the <SPAN
5585 >To display the VLDB entry only for volumes with locked VLDB entries, use the <SPAN
5591 > flag with any of the site definitions mentioned previously.</P
5602 >To display VLDB entries</A
5615 CLASS="programlisting"
5630 >volume name or ID</VAR
5649 >partition name</VAR
5661 CLASS="variablelist"
5673 >Is the shortest acceptable abbreviation of <SPAN
5691 >Identifies one volume either by its complete name or volume ID number. Do not combine this argument with the
5716 >Specifies a file server machine. Combine this argument with the <SPAN
5723 argument if desired, but not with the <SPAN
5741 >Specifies a partition. Combine this argument with the <SPAN
5748 desired, but not with the <SPAN
5766 >Displays only locked VLDB entries. Combine this flag with any of the other options.</P
5774 >The VLDB entry for each volume includes the following information: <UL
5777 >The base (read/write) volume name. The read-only and backup versions have the same name with a <SPAN
5789 > extension, respectively.</P
5793 >The volume ID numbers allocated to the versions of the volume that actually exist, in fields labeled
5795 CLASS="computeroutput"
5797 > for the read/write, <SAMP
5798 CLASS="computeroutput"
5800 > for the read-only,
5802 CLASS="computeroutput"
5804 > for the backup, and <SAMP
5805 CLASS="computeroutput"
5808 ReleaseClone. (If a field does not appear, the corresponding version of the volume does not exist.) The appearance of
5810 CLASS="computeroutput"
5812 > field normally indicates that a release operation did not complete
5813 successfully; the <SAMP
5814 CLASS="computeroutput"
5817 CLASS="computeroutput"
5820 often also appear on one or more of the site definition lines described just following.</P
5824 >The number of sites that house a read/write or read-only copy of the volume, following the string
5826 CLASS="computeroutput"
5827 >number of sites -></SAMP
5832 >A line for each site that houses a read/write or read-only copy of the volume, specifying the file server machine,
5833 partition, and type of volume (<SAMP
5834 CLASS="computeroutput"
5836 > for read/write or <SAMP
5837 CLASS="computeroutput"
5840 for read-only). If a backup version exists, it is understood to share the read/write site. Several flags can appear with
5841 a site definition: <DIV
5842 CLASS="variablelist"
5846 CLASS="computeroutput"
5851 >Indicates that the <SPAN
5857 > command has not been issued since the
5864 > command was used to define the read-only site.</P
5868 CLASS="computeroutput"
5873 >Indicates that a <SPAN
5879 > command did not complete successfully,
5880 leaving the previous, obsolete version of the volume at this site.</P
5884 CLASS="computeroutput"
5889 >Indicates that a <SPAN
5895 > command did not complete successfully, but
5896 that this site did receive the correct new version of the volume.</P
5904 >If the VLDB entry is locked, the string <SAMP
5905 CLASS="computeroutput"
5906 >Volume is currently LOCKED</SAMP
5912 >For further discussion of the <SAMP
5913 CLASS="computeroutput"
5916 CLASS="computeroutput"
5920 HREF="c8420.html#HDRWQ192"
5921 >Replicating Volumes (Creating Read-only Volumes)</A
5924 >An example of this command and its output for a single volume:</P
5926 CLASS="programlisting"
5931 >vos listvldb user.terry</B
5935 RWrite: 50489902 Backup: 50489904
5936 number of sites -> 1
5937 server fs3.abc.com partition /vicepc RW Site
5946 >Displaying Volume Headers</A
5955 > command displays the volume header for every volume on one or all
5956 partitions on a file server machine. The <SPAN
5962 > command interpreter obtains the information from
5963 the Volume Server on the specified machine. You can control the amount of information displayed by including one of the
5982 > flags described following the instructions in <A
5983 HREF="c8420.html#HDRWQ220"
5988 >To display a single volume's volume header of one volume only, use the <SPAN
5995 command as described in <A
5996 HREF="c8420.html#HDRWQ221"
5997 >Displaying One Volume's VLDB Entry and Volume Header</A
6006 >To display volume headers</A
6019 CLASS="programlisting"
6031 >partition name</VAR
6055 CLASS="variablelist"
6067 >Is the shortest acceptable abbreviation of <SPAN
6085 >Names the file server machine for which to display volume headers. Provide this argument alone or with the
6086 partition name argument.</P
6098 >Names one partition on the file server machine named by the machine name argument, which must be provided
6099 along with this one.</P
6111 >Displays only the volume ID numbers of relevant volumes. Do not combine this flag with the <SPAN
6135 >Displays more detailed information about each volume. Do not combine this flag with the <SPAN
6159 >Displays all of the information displayed by the <SPAN
6165 > flag, plus tables of
6166 statistics about reads and writes to the files in the volume. Do not combine this flag with the <SPAN
6186 >The output is ordered alphabetically by volume name and by default provides the following information on a single line
6187 for each volume: <UL
6194 >Volume ID number</P
6198 >Type (the flag is <SAMP
6199 CLASS="computeroutput"
6201 > for read/write, <SAMP
6202 CLASS="computeroutput"
6206 CLASS="computeroutput"
6212 >Size in kilobytes (<SAMP
6213 CLASS="computeroutput"
6215 > equals a megabyte)</P
6219 >Number of files in the volume, if the <SPAN
6225 > flag is provided</P
6229 >Status on the file server machine, which is one of the following: <DIV
6230 CLASS="variablelist"
6234 CLASS="computeroutput"
6239 >The volume is completely accessible to Cache Managers.</P
6243 CLASS="computeroutput"
6248 >The volume is not accessible to Cache Managers, but does not seem to be corrupted. This status appears
6249 while a volume is being dumped, for example.</P
6253 CLASS="computeroutput"
6254 >Off-line**needs salvage**</SAMP
6258 >The volume is not accessible to Cache Managers, because it seems to be corrupted. Use the <SPAN
6270 > command to repair the
6280 >If the following message appears instead of the previously listed information, it indicates that a volume is not
6281 accessible to Cache Managers or the <SPAN
6287 > command interpreter, for example because a clone is
6290 CLASS="programlisting"
6291 > **** Volume volume_ID is busy ****
6294 >If the following message appears instead of the previously listed information, it indicates that the File Server is
6295 unable to attach the volume, perhaps because it is seriously corrupted. The <SPAN
6308 > log files in the <SPAN
6315 file server machine possibly provide additional information; use the <SPAN
6324 CLASS="programlisting"
6325 > **** Could not attach volume volume_ID ****
6328 >(For instructions on salvaging a corrupted or unattached volume, see <A
6329 HREF="c8420.html#HDRWQ232"
6334 >The information about individual volumes is bracketed by summary lines. The first line of output specifies the number of
6335 volumes in the listing. The last line of output summarizes the number of volumes that are online, offline, and busy, as in the
6336 following example:</P
6338 CLASS="programlisting"
6343 >vos listvol fs2.abc.com /vicepb</B
6346 Total number of volumes on server fs2.abc.com \
6347 partition /vicepb : 66
6348 sys 1969534847 RW 1582 K On-line
6349 sys.backup 1969535105 BK 1582 K On-line
6352 user.pat 1969534536 RW 17518 K On-line
6353 user.pat.backup 1969534538 BK 17537 K On-line
6354 Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
6361 >Output with the -fast Flag</B
6365 >If you include the <SPAN
6371 > flag displays only the volume ID number of each volume,
6372 arranged in increasing numerical order, as in the following example. The final line (which summarizes the number of on-line,
6373 off-line, and busy volumes) is omitted.</P
6375 CLASS="programlisting"
6380 >vos listvol fs3.abc.com /vicepa -f</B
6383 Total number of volumes on server fs3.abc.com \
6384 partition /vicepa: 37
6397 >Output with the -long Flag</B
6401 >When you include the <SPAN
6407 > flag, , the output for each volume includes all of the
6408 information in the default listing plus the following. Each item in this list corresponds to a separate line of output:
6412 >The file server machine and partition that house the volume, as determined by the command interpreter as the
6413 command runs, rather than derived from the VLDB or the volume header.</P
6417 >The volume ID numbers associated with the various versions of the volume: read/write
6419 CLASS="computeroutput"
6421 >), read-only (<SAMP
6422 CLASS="computeroutput"
6426 CLASS="computeroutput"
6428 >), and ReleaseClone (<SAMP
6429 CLASS="computeroutput"
6432 matches the volume ID number that appears on the first line of the volume's output. If the value in the
6434 CLASS="computeroutput"
6437 CLASS="computeroutput"
6441 CLASS="computeroutput"
6444 CLASS="computeroutput"
6446 > (zero), there is no volume of that
6447 type. If there is currently no ReleaseClone, the <SAMP
6448 CLASS="computeroutput"
6450 > field does not appear at
6455 >The maximum space quota allotted to the read/write copy of the volume, expressed in kilobyte blocks in the
6457 CLASS="computeroutput"
6463 >The date and time the volume was created, in the <SAMP
6464 CLASS="computeroutput"
6466 > field. If the volume
6467 has been restored with the <SPAN
6471 >backup diskrestore</B
6486 > command, this is the restore time.</P
6490 >The date and time when the contents of the volume last changed, in the <SAMP
6491 CLASS="computeroutput"
6494 > field. For read-only and backup volumes, it matches the timestamp in the
6496 CLASS="computeroutput"
6502 >The number of times the volume has been accessed for a fetch or store operation since the later of the two
6503 following times: <UL
6506 >12:00 a.m. on the day the command is issued</P
6510 >The last time the volume changed location</P
6518 >An example of the output when the <SPAN
6524 > flag is included:</P
6526 CLASS="programlisting"
6531 >vos listvol fs2.abc.com b -long</B
6534 Total number of volumes on server fs2.abc.com
6535 partition /vicepb: 66
6538 user.pat 1969534536 RW 17518 K On-line
6540 RWrite 1969534536 ROnly 0 Backup 1969534538
6542 Creation Mon Jun 12 09:02:25 1989
6543 Last Update Thu Jan 4 17:39:34 1990
6544 1573 accesses in the past day (i.e., vnode references)
6545 user.pat.backup 1969534538 BK 17537 K On-line
6547 RWrite 1969534536 ROnly 0 Backup 1969534538
6549 Creation Fri Jan 5 06:37:59 1990
6550 Last Update Fri Jan 5 06:37:59 1990
6551 0 accesses in the past day (i.e., vnode references)
6554 Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
6561 >Output with the -extended Flag</B
6565 >When you include the <SPAN
6571 > flag, the output for each volume includes all of the
6572 information reported with the <SPAN
6578 > flag, plus two tables of statistics: <UL
6581 >The table labeled <SAMP
6582 CLASS="computeroutput"
6583 >Raw Read/Write Stats</SAMP
6584 > table summarizes the number of times the
6585 volume has been accessed for reading or writing.</P
6589 >The table labeled <SAMP
6590 CLASS="computeroutput"
6591 >Writes Affecting Authorship</SAMP
6592 > table contains information on
6593 writes made to files and directories in the specified volume.</P
6598 >An example of the output when the <SPAN
6604 > flag is included:</P
6606 CLASS="programlisting"
6611 >vos listvol fs3.abc.com a -extended</B
6614 common.bboards 1969535592 RW 23149 K used 9401 files On-line
6616 RWrite 1969535592 ROnly 0 Backup 1969535594
6618 Creation Mon Mar 8 14:26:05 1999
6619 Last Update Mon Apr 26 09:20:43 1999
6620 11533 accesses in the past day (i.e., vnode references)
6621 Raw Read/Write Stats
6622 |-------------------------------------------|
6623 | Same Network | Diff Network |
6624 |----------|----------|----------|----------|
6625 | Total | Auth | Total | Auth |
6626 |----------|----------|----------|----------|
6627 Reads | 151 | 151 | 1092 | 1068 |
6628 Writes | 3 | 3 | 324 | 324 |
6629 |-------------------------------------------|
6630 Writes Affecting Authorship
6631 |-------------------------------------------|
6632 | File Authorship | Directory Authorship|
6633 |----------|----------|----------|----------|
6634 | Same | Diff | Same | Diff |
6635 |----------|----------|----------|----------|
6636 0-60 sec | 92 | 0 | 100 | 4 |
6637 1-10 min | 1 | 0 | 14 | 6 |
6638 10min-1hr | 0 | 0 | 19 | 4 |
6639 1hr-1day | 1 | 0 | 13 | 0 |
6640 1day-1wk | 1 | 0 | 1 | 0 |
6641 > 1wk | 0 | 0 | 0 | 0 |
6642 |-------------------------------------------|
6651 >Displaying One Volume's VLDB Entry and Volume Header</A
6660 > command displays information from both the VLDB and the volume header
6661 for a single volume. There is some redundancy in the information from the two sources, which allows you to compare the VLDB
6662 and volume header.</P
6664 >Because the volume header for each version of a volume (read/write, read-only, and backup) is different, you can specify
6665 which one to display. Include the <SPAN
6678 extension on the volume name or ID argument as appropriate. The information from the VLDB is the same for all three
6687 >To display one volume's VLDB entry and volume header</A
6700 CLASS="programlisting"
6709 >volume name or ID</VAR
6715 CLASS="variablelist"
6727 >Is the shortest acceptable abbreviation of <SPAN
6740 >volume name or ID</B
6745 >Identifies one volume either by its complete name or volume ID number. It can be a read/write, read-only, or
6746 backup type. Use the <SPAN
6759 extension if appropriate.</P
6767 >The top part of the output displays the same information from a volume header as the <SPAN
6774 > command with the <SPAN
6780 > flag, as described following the instructions in
6782 HREF="c8420.html#HDRWQ220"
6783 >To display volume headers</A
6784 >. If you specify the read-only version of the volume and it exists at
6785 more than one site, the output includes all of them. The bottom part of the output lists the same information from the VLDB as
6792 > command, as described following the instructions in <A
6793 HREF="c8420.html#HDRWQ218"
6794 >To display VLDB entries</A
6797 >Below is an example for a volume whose VLDB entry is currently locked.</P
6799 CLASS="programlisting"
6804 >vos examine user.terry</B
6807 user.terry 536870981 RW 3459 K On-line
6809 Write 5360870981 ROnly 0 Backup 536870983
6811 Creation Mon Jun 12 15:22:06 1989
6812 Last Update Fri Jun 16 09:34:35 1989
6813 5719 accesses in the past day (i.e., vnode references)
6814 RWrite: 5360870981 Backup: 536870983
6815 number of sites -> 1
6816 server fs3.abc.com partition /vicepa RW Site
6817 Volume is currently LOCKED
6826 >Displaying the Name or Location of the Volume that Contains a File</A
6829 >This section explains how to learn the name, volume ID number, or location of the volume that contains a file or
6832 >You can also use one piece of information about a volume (for example, its name) to obtain other information about it
6833 (for example, its location). The following list points you to the relevant instructions: <UL
6836 >To use a volume's name to learn the volume ID numbers of all its existing versions, use the <SPAN
6842 > command as described in <A
6843 HREF="c8420.html#HDRWQ222"
6844 >To display one volume's VLDB entry
6845 and volume header</A
6848 >You can also use the command to learn a volume's name by providing its ID number.</P
6852 >To use a volume's name or ID number to learn its location, use the <SPAN
6859 command as described in <A
6860 HREF="c8420.html#HDRWQ218"
6861 >To display VLDB entries</A
6872 >To display the name of the volume that contains a file</A
6885 CLASS="programlisting"
6900 CLASS="variablelist"
6912 >Is an acceptable alias for <SPAN
6924 > the shortest acceptable abbreviation).</P
6936 >Names a directory or file housed in the volume for which to display the name. Partial pathnames are
6937 interpreted relative to the current working directory, which is the default if this argument is omitted.</P
6945 >The following is an example of the output:</P
6947 CLASS="programlisting"
6952 >fs listquota /afs/abc.com/usr/terry</B
6955 Volume Name Quota Used % Used Partition
6956 user.terry 15000 5071 34% 86%
6965 >To display the ID number of the volume that contains a file</A
6978 CLASS="programlisting"
6993 CLASS="variablelist"
7005 >Is the shortest acceptable abbreviation of <SPAN
7023 >Names a directory or file housed in the volume for which to display the volume ID. Partial pathnames are
7024 interpreted relative to the current working directory, which is the default if this argument is omitted.</P
7032 >The following example illustrates how the output reports the volume ID number in the
7034 CLASS="computeroutput"
7038 CLASS="programlisting"
7043 >fs examine /afs/abc.com/usr/terry</B
7046 Volume status for vid = 50489902 named user.terry
7047 Current maximum quota is 15000
7048 Current blocks used are 5073
7049 The partition has 46383 blocks available out of 333305
7058 >The partition-related statistics in this command's output do not always agree with the corresponding values in the
7059 output of the standard UNIX <SPAN
7065 > command. The statistics reported by this command can be up
7066 to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency. Also, on
7067 some operating systems, the <SPAN
7073 > command's report of partition size includes reserved space
7074 not included in this command's calculation, and so is likely to be about 10% larger.</P
7084 >To display the location of the volume that contains a file</A
7096 > command to display the name of the file server machine that
7097 houses the volume containing a file or directory. <PRE
7098 CLASS="programlisting"
7113 CLASS="variablelist"
7125 >Is the shortest acceptable abbreviation of <SPAN
7143 >Names a directory or file for which to report the location. Partial pathnames are interpreted relative to
7144 the current working directory, which is the default if this argument is omitted.</P
7150 >The output displays the file server machine that houses the volume containing the file, as in the following
7153 CLASS="programlisting"
7158 >fs whereis /afs/abc.com/user/terry</B
7161 File /afs/abc.com/usr/terry is on host fs2.abc.com
7166 >If you also want to know which partition houses the volume, first issue the <SPAN
7173 > command to display the volume's name. For complete syntax, see <A
7174 HREF="c8420.html#HDRWQ224"
7176 the name of the volume that contains a file</A
7178 CLASS="programlisting"
7192 >Then issue the <SPAN
7198 > command, providing the volume name as the volume name
7199 or ID argument. For complete syntax and a description of the output, see <A
7200 HREF="c8420.html#HDRWQ218"
7205 CLASS="programlisting"
7214 >volume name or ID</VAR
7231 >There are three main reasons to move volumes: <UL
7234 >To place volumes on other partitions or machines temporarily while repairing or replacing a disk or file server
7239 > To free space on a partition that is becoming overcrowded. One symptom of overcrowding is that users cannot
7240 to save files even though the relevant volume is below its quota. The following error message confirms the problem:
7242 CLASS="programlisting"
7243 > afs: failed to store file (partition full)
7247 >You can track available space on AFS server partitions by using the <SPAN
7260 > programs described in <A
7262 >Monitoring and Auditing AFS
7268 >A file server machine is becoming overloaded because it houses many more volumes than other machines of the same
7269 size, or has volumes with more popular files in them.</P
7274 >To move a read/write volume, use the <SPAN
7280 > command as described in the following
7281 instructions. Before attempting to move the volume, the <SPAN
7287 > command interpreter verifies that
7288 there is enough free space for it on the destination partition. If not, it does not attempt the move operation and prints the
7289 following message.</P
7291 CLASS="programlisting"
7292 > vos: no space on target partition destination_part to move volume volume
7295 >To move a read-only volume, you actually remove the volume from the current site by issuing the <SPAN
7302 > command as described in <A
7303 HREF="c8420.html#HDRWQ236"
7304 >To remove a volume and unmount it</A
7305 >. Then define a new
7306 site and release the volume to it by issuing the <SPAN
7319 > commands as described in <A
7320 HREF="c8420.html#HDRWQ194"
7321 >To replicate a read/write volume (create a read-only
7325 >A backup volume always resides at the same site as its read/write source volume, so you cannot move a backup volume except
7326 as part of moving the read/write source. The <SPAN
7332 > command automatically deletes the backup
7333 version when you move a read/write volume. To create a new backup volume at the new site as soon as the move operation
7334 completes, issue the <SPAN
7340 > command as described in <A
7341 HREF="c8420.html#HDRWQ205"
7343 mount a backup volume</A
7351 >To move a read/write volume</A
7357 >Verify that you are listed in the <SPAN
7361 >/usr/afs/etc/UserList</B
7363 > file. If necessary, issue
7370 > command, which is fully described in <A
7371 HREF="c32432.html#HDRWQ593"
7373 display the users in the UserList file</A
7375 CLASS="programlisting"
7397 > command to move the volume. Type it on a single line; it appears
7398 on multiple lines here only for legibility. <PRE
7399 CLASS="programlisting"
7408 >volume name or ID</VAR
7411 >machine name on source</VAR
7415 >partition name on source </VAR
7418 >machine name on destination</VAR
7419 >> <partition name on
7425 CLASS="variablelist"
7437 >Is the shortest acceptable abbreviation of <SPAN
7450 >volume name or ID</B
7455 >Specifies the name or volume ID number of the read/write volume to move.</P
7462 >machine name on source</B
7467 >Names the file server machine currently housing the volume.</P
7474 >partition name on source</B
7479 >Names the partition currently housing the volume.</P
7486 >machine name on destination</B
7491 >Names the file server machine to which to move the volume.</P
7498 >partition name on destination</B
7503 >Names the partition to which to move the volume.</P
7515 >It is best not to halt a <SPAN
7521 > operation before it completes, because parts of
7522 the volume can be left on both the source and destination machines. For more information, see the command's reference
7527 > IBM AFS Administration Reference</I
7548 confirm the success of the move. Complete instructions appear in <A
7549 HREF="c8420.html#HDRWQ218"
7550 >To display VLDB entries</A
7553 CLASS="programlisting"
7562 >volume name or ID</VAR
7569 >If a backup version existed at the read/write volume's previous site, create a new backup at the new site by issuing
7576 > command, which is fully described in <A
7577 HREF="c8420.html#HDRWQ205"
7579 and mount a backup volume</A
7581 CLASS="programlisting"
7590 >volume name or ID</VAR
7604 >Synchronizing the VLDB and Volume Headers</A
7607 >AFS can provide transparent file access because the Volume Location Database (VLDB) constantly tracks volume locations.
7608 When the Cache Manager needs a file, it contacts the Volume Location (VL) Server, which reads the VLDB for the current location
7609 of the volume containing the file. Therefore, the VLDB must accurately reflect the state of volumes on the file server machines
7610 at all times. The Volume Server and VL Server automatically update a volume's VLDB entry when its status changes during a
7617 > operation, by performing the following series of steps. <OL
7624 >The VL Server locks the VLDB entry. The lock advises other operations not to manipulate any
7625 of the volume versions (read/write, read-only, or backup), which prevents the inconsistency that can result from multiple
7626 simultaneous operations.</P
7633 >The VL Server sets an <SPAN
7639 > in the VLDB entry that
7640 indicates the kind of operation to be performed. This flag never appears in VLDB listings because it is for internal use
7641 only. In case the operation terminates prematurely, this flag tells the Salvager which operation was interrupted. (The
7642 Salvager then determines the steps necessary either to complete the operation or return the volume to a previous
7643 consistent state. For more information on salvaging, see <A
7644 HREF="c8420.html#HDRWQ232"
7645 >Salvaging Volumes</A
7653 >The Volume Server manipulates the volume. It usually sets the
7655 CLASS="computeroutput"
7657 > flag in the volume header, which makes the volume inaccessible to the File
7658 Server and other Volume Server operations during the manipulation. When the operation completes, the volume is again
7660 CLASS="computeroutput"
7669 >The VL Server records any changes resulting from the operation in the VLDB entry. Once the
7670 operation is complete, it removes the intention flag set in Step <A
7671 HREF="c8420.html#LIWQ229"
7673 >and releases the lock set
7675 HREF="c8420.html#LIWQ228"
7688 > operation fails while the Volume Server is manipulating the volume
7689 (corresponding to Step <A
7690 HREF="c8420.html#LIWQ230"
7692 >), the volume can be left in an intermediate state, which is termed
7699 >. In this case, the <SAMP
7700 CLASS="computeroutput"
7703 CLASS="computeroutput"
7706 > marker usually appears at the end of the first line of output from the <SPAN
7713 > command. To repair the corruption, run the Salvager before attempting to resynchronize the VLDB and volume
7714 headers. For salvaging instructions, see <A
7715 HREF="c8420.html#HDRWQ232"
7716 >Salvaging Volumes</A
7719 >More commonly, an interruption while flags are being set or removed (corresponding to Step <A
7720 HREF="c8420.html#LIWQ228"
7723 HREF="c8420.html#LIWQ229"
7726 HREF="c8420.html#LIWQ231"
7729 discrepancy between the VLDB and volume headers. To resynchronize the VLDB and volumes, use the <SPAN
7742 > commands. To achieve complete VLDB consistency, it is best
7749 > command on all file server machines in the cell, and then run the
7756 > command on all file server machines in the cell.</P
7758 >There are several symptoms that indicate a volume operation failed: <UL
7761 >Error messages on the standard error stream or in server process log files indicate that an operation terminated
7762 abnormally. Perhaps you had to halt the operation before it completed (for instance, by using a signal such as <SPAN
7768 >), or a file server machine or server process was not functioning when the operation ran. To
7769 determine if a machine or process is still not functioning, issue the <SPAN
7777 HREF="c6449.html#HDRWQ158"
7778 >Displaying Process Status and Information from the BosConfig File</A
7789 > operation fails because a previous failure left a VLDB entry
7790 locked. Sometimes an error message reports that a volume is locked. To display a list of locked volumes, use the <SPAN
7802 > command as described in <A
7803 HREF="c8420.html#HDRWQ217"
7804 >Displaying VLDB Entries</A
7807 >If the only problem with a volume is that its VLDB entry is locked, you probably do not need to synchronize the
7808 entire VLDB. Instead use the <SPAN
7821 > command to unlock the entry, as described in <A
7822 HREF="c8420.html#HDRWQ247"
7823 >Unlocking and Locking VLDB
7835 > operation fails because a previous failure left a volume marked as
7836 offline. To check a volume's current status, check the first line of output from the <SPAN
7843 > command as described in <A
7844 HREF="c8420.html#HDRWQ221"
7845 >Displaying One Volume's VLDB Entry and Volume
7858 > command corrects the information in the Volume Location Database (VLDB)
7859 either about all volumes housed on a file server machine, about the volumes on just one partition, or about a single volume. If
7860 checking about one or more partitions, the command contacts the Volume Server to obtain a list of the volumes that actually
7861 reside on each partition. It then obtains the VLDB entry for each volume from the VL Server. It changes the VLDB entry as
7862 necessary to reflect the state of the volume on the partition. For example, it creates or updates a VLDB entry when it finds a
7863 volume for which the VLDB entry is missing or incomplete. However, if there is already a VLDB entry that defines a different
7864 location for the volume, or there are irreconcilable conflicts with other VLDB entries, it instead writes a message about the
7865 conflict to the standard error stream. The command never removes volumes from the file server machine.</P
7867 >When checking a single volume's VLDB entry, the command also automatically performs the operations invoked by the
7874 > command: it not only verifies that the VLDB entry is correct for the specified
7875 volume type (read/write, backup, or read-only), but also checks that any related volume types mentioned in the VLDB entry
7876 actually exist at the site listed in the entry.</P
7884 > command verifies that each volume type (read/write, read-only, and
7885 backup) mentioned in a VLDB entry actually exists at the site indicated in the entry. It checks all VLDB entries that mention a
7886 site either on any of a file server machine's partitions or on one partition. Note that command can end up inspecting sites
7887 other than on the specified machine or partition, if there are read-only versions of the volume at sites other than the
7890 >The command alters any incorrect information in the VLDB, unless there is an irreconcilable conflict with other VLDB
7891 entries. In that case, it writes a message to the standard error stream instead. The command never removes volumes from their
7899 >To synchronize the VLDB with volume headers</A
7905 >Verify that you are listed in the <SPAN
7909 >/usr/afs/etc/UserList</B
7911 > file. If necessary, issue
7918 > command, which is fully described in <A
7919 HREF="c32432.html#HDRWQ593"
7921 display the users in the UserList file</A
7923 CLASS="programlisting"
7948 > command to make the VLDB reflect
7949 the true state of all volumes on a machine or partition, or the state of one volume.</P
7957 >To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your
7964 > argument in turn and omitting the <SPAN
7976 > arguments, before proceeding to Step
7978 HREF="c8420.html#LIVOL-SYNCSR"
7984 CLASS="programlisting"
7989 >vos syncvldb -server</B
8002 >partition name</VAR
8012 >volume name or ID</VAR
8017 >-verbose >></B
8023 CLASS="variablelist"
8035 >Is the shortest acceptable abbreviation of <SPAN
8053 >Names the file server machine housing the volumes for which to verify VLDB entries. If you are also
8060 > argument, this argument must name the machine where the
8061 volume actually resides.</P
8073 >Identifies the partition (on the file server machine specified by the <SPAN
8079 > argument) housing the volumes for which to verify VLDB entries. In general, it is
8080 best to omit this argument so that either the VLDB entries for all volumes on a server machine are corrected (if
8081 you do not provide the <SPAN
8087 > argument), or so that you do not need to guarantee
8088 that the partition actually houses the volume named by the <SPAN
8107 >Specifies the name or volume ID number of a single volume for which to verify the VLDB entry.</P
8114 >-verbose >> file</B
8119 >Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the
8120 machine on which you are issuing the command. The command often writes a large amount of output to the standard
8121 output stream; writing it to a file enables you to examine the output more carefully.</P
8138 > command to inspect each volume
8139 for which the VLDB lists a version at the specified site.</P
8147 >To synchronize the VLDB completely, issue the command repeatedly, substituting each file server machine in your
8148 cell for the machine name argument in turn and omitting the partition name argument.</P
8152 CLASS="programlisting"
8164 >partition name</VAR
8175 CLASS="variablelist"
8187 >Is the shortest acceptable abbreviation of <SPAN
8205 >Names the file server machine mentioned in each VLDB entry to check.</P
8217 >Identifies the partition mentioned in each VLDB entry to check. If synchronizing the entire VLDB, omit this
8225 >-v >> file</B
8230 >Directs a detailed trace to the file called file, which can be either in AFS or on the local disk of the
8231 machine on which you are issuing the command. The command often writes a large amount of output to the standard
8232 output stream; writing it to a file enables you to examine the output more carefully.</P
8247 >Salvaging Volumes</A
8250 >An unexpected interruption while the Volume Server or File Server is manipulating the data in a volume can leave the
8251 volume in an intermediate state (<SPAN
8257 >), rather than just creating a discrepancy between the
8258 information in the VLDB and volume headers. For example, the failure of the operation that saves changes to a file (by
8259 overwriting old data with new) can leave the old and new data mixed together on the disk.</P
8261 >If an operation halts because the Volume Server or File Server exits unexpectedly, the BOS Server automatically shuts down
8262 all components of the <SPAN
8268 > process and invokes the Salvager. The Salvager checks for and repairs
8269 any inconsistencies it can. Sometimes, however, there are symptoms of the following sort, which indicate corruption serious
8270 enough to create problems but not serious enough to cause the File Server component to fail. In these cases you can invoke the
8271 Salvager yourself by issuing the <SPAN
8286 > A file appears in the output of the <SPAN
8293 command, but attempts to access the file fail with messages indicating that it does not exist.</P
8301 > The Volume Server or File Server exited in the middle of a
8302 file-creation operation, after changing the directory structure, but before actually storing data. (Other possible causes
8303 are that the ACL on the directory does not grant the permissions you need to access the file, or there is a process,
8304 machine, or network outage. Check for these causes before assuming the file is corrupted.)</P
8310 >Salvager's solution:</B
8312 > Remove the file's entry from the directory structure.</P
8322 > A volume is marked <SAMP
8323 CLASS="computeroutput"
8339 attempts to access the volume fail.</P
8347 > Two files or versions of a file are sharing the same disk blocks
8348 because of an interrupted operation. The File Server and Volume Server normally refuse to attach volumes that exhibit this
8349 type of corruption, because it can be very dangerous. If the Volume Server or File Server do attach the volume but are
8350 unsure of the status of the affected disk blocks, they sometimes try to write yet more data there. When they cannot
8351 perform the write, the data is lost. This effect can cascade, causing loss of all data on a partition.</P
8357 >Salvager's solution:</B
8359 > Delete the data from the corrupted disk blocks in preference
8360 to losing an entire partition.</P
8370 > There is less space available on the partition than you expect based on
8371 the size statistic reported for each volume by the <SPAN
8385 > There are orphaned files and directories. An
8392 > element is completely inaccessible because it is not referenced by any directory that can
8393 act as its parent (is higher in the file tree). An orphaned element is not counted in the calculation of a volume's size
8394 (or against its quota), even though it occupies space on the server partition.</P
8400 >Salvager's solution:</B
8402 > By default, print a message to the <SPAN
8406 >/usr/afs/logs/SalvageLog</B
8408 > file reporting how many orphans were found and the approximate number of
8409 kilobytes they are consuming. You can use the <SPAN
8415 > argument to remove or attach
8416 orphaned elements instead. See <A
8417 HREF="c8420.html#HDRWQ233"
8418 >To salvage volumes</A
8424 >When you notice symptoms such as these, use the <SPAN
8430 > command to invoke the
8431 Salvager before corruption spreads. (Even though it operates on volumes, the command belongs to the <SPAN
8437 > suite because the BOS Server must coordinate the shutdown and restart of the Volume Server and File
8438 Server with the Salvager. It shuts them down before the Salvager starts, and automatically restarts them when the salvage
8439 operation finishes.)</P
8441 >All of the AFS data stored on a file server machine is inaccessible during the salvage of one or more partitions. If you
8442 salvage just one volume, it alone is inaccessible.</P
8444 >When processing one or more partitions, the command restores consistency to corrupted read/write volumes where possible.
8445 For read-only or backup volumes, it inspects only the volume header: <UL
8448 >If the volume header is corrupted, the Salvager removes the volume completely and records the removal in its log
8453 >/usr/afs/logs/SalvageLog</B
8468 > command to create the read-only or backup volume again.</P
8472 >If the volume header is intact, the Salvager skips the volume (does not check for corruption in the contents).
8473 However, if the File Server notices corruption as it initializes, it sometimes refuses to attach the volume or bring it
8474 online. In this case, it is simplest to remove the volume by issuing the <SPAN
8487 > command. Then issue the <SPAN
8499 > command to create it again.</P
8510 > command's arguments as indicated to salvage different numbers of
8514 >To salvage all volumes on a file server machine, combine the <SPAN
8531 >To salvage all volumes on one partition, combine the <SPAN
8547 >To salvage only one read/write volume, combine the <SPAN
8565 > arguments. Only that volume is
8566 inaccessible to Cache Managers, because the BOS Server does not shutdown the File Server and Volume Server processes
8567 during the salvage of a single volume. Do not name a read-only or backup volume with the <SPAN
8573 > argument. Instead, remove the volume, using the <SPAN
8586 > command. Then create a new copy of the volume with the <SPAN
8603 >The Salvager always writes a trace to the <SPAN
8607 >/usr/afs/logs/SalvageLog</B
8610 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
8611 where you issue the <SPAN
8617 > command), name the file with the <SPAN
8623 > argument. Or, to display the trace on the standard output stream as it is written to the <SPAN
8627 >/usr/afs/logs/SalvageLog</B
8629 > file, include the <SPAN
8637 >By default, multiple Salvager subprocesses run in parallel: one for each partition up to four, and four subprocesses for
8638 four or more partitions. To increase or decrease the number of subprocesses running in parallel, provide a positive integer
8647 >If there is more than one server partition on a physical disk, the Salvager by default salvages them serially to avoid the
8648 inefficiency of constantly moving the disk head from one partition to another. However, this strategy is often not ideal if the
8649 partitions are configured as logical volumes that span multiple disks. To force the Salvager to salvage logical volumes in
8650 parallel, provide the string <SPAN
8656 > as the value for the <SPAN
8662 > argument. Provide a positive integer to specify the number of subprocesses to run in parallel
8669 > for five subprocesses), or omit the integer to run up to four
8670 subprocesses, depending on the number of logical volumes being salvaged.</P
8672 >The Salvager creates temporary files as it runs, by default writing them to the partition it is salvaging. The number of
8673 files can be quite large, and if the partition is too full to accommodate them, the Salvager terminates without completing the
8674 salvage operation (it always removes the temporary files before exiting). Other Salvager subprocesses running at the same time
8675 continue until they finish salvaging all other partitions where there is enough disk space for temporary files. To complete the
8676 interrupted salvage, reissue the command against the appropriate partitions, adding the <SPAN
8683 argument to redirect the temporary files to a local disk directory that has enough space.</P
8691 > argument controls how the Salvager handles orphaned files and directories
8692 that it finds on server partitions it is salvaging. An orphaned element is completely inaccessible because it is not referenced
8693 by the vnode of any directory that can act as its parent (is higher in the filespace). Orphaned objects occupy space on the
8694 server partition, but do not count against the volume's quota.</P
8696 >During the salvage, the output of the <SPAN
8702 > command reports the following auxiliary
8703 status for the <SPAN
8711 CLASS="programlisting"
8712 > Salvaging file system
8720 >To salvage volumes</A
8726 >Verify that you are listed in the <SPAN
8730 >/usr/afs/etc/UserList</B
8732 > file. If necessary, issue
8739 > command, which is fully described in <A
8740 HREF="c32432.html#HDRWQ593"
8742 display the users in the UserList file</A
8744 CLASS="programlisting"
8766 > command to salvage one or more volumes. <PRE
8767 CLASS="programlisting"
8772 >bos salvage -server</B
8785 >salvage partition</VAR
8795 >salvage volume number or volume name</VAR
8803 > salvage log output file] [<SPAN
8824 ># of max parallel partition salvaging</VAR
8834 >directory to place tmp files</VAR
8865 CLASS="variablelist"
8877 >Names the file server machine on which to salvage volumes. This argument can be combined either with the
8890 > argument, or both the
8915 >Names a single partition on which to salvage all volumes. The <SPAN
8922 argument must be provided along with this one.</P
8934 >Specifies the name or volume ID number of one read/write volume to salvage. Combine this argument with the
8959 >Specifies the complete pathname of a file into which to write a trace of the salvage operation, in addition
8964 >/usr/afs/logs/SalvageLog</B
8966 > file on the server machine. If the file pathname
8967 is local, the trace is written to the specified file on the local disk of the machine where the <SPAN
8973 > command is issued. If the <SPAN
8980 included, the file can be in AFS, though not in the volume being salvaged. Do not combine this argument with the
8999 >Salvages all volumes on all of the partitions on the machine named by the <SPAN
9017 >Displays the trace of the salvage operation on the standard output stream, as well as writing it to the
9022 >/usr/afs/logs/SalvageLog</B
9036 >Specifies the maximum number of Salvager subprocesses to run in parallel. Provide one of three values:
9040 >An integer from the range <SPAN
9059 > means that a single Salvager process salvages the partitions
9070 > to run up to four Salvager subprocesses in parallel on
9071 partitions formatted as logical volumes that span multiple physical disks. Use this value only with such
9082 > followed immediately (with no intervening space) by an
9083 integer from the range <SPAN
9096 specified number of Salvager subprocesses in parallel on partitions formatted as logical volumes. Use this
9097 value only with such logical volumes.</P
9102 >The BOS Server never starts more Salvager subprocesses than there are partitions, and always starts only one
9103 process to salvage a single volume. If this argument is omitted, up to four Salvager subprocesses run in
9116 >Specifies the full pathname of a local disk directory to which the Salvager process writes temporary files
9117 as it runs. By default, it writes them to the partition it is currently salvaging.</P
9129 >Controls how the Salvager handles orphaned files and directories. Choose one of the following three values:
9131 CLASS="variablelist"
9143 >Leaves the orphaned objects on the disk, but prints a message to the <SPAN
9147 >/usr/afs/logs/SalvageLog</B
9149 > file reporting how many orphans were found and the
9150 approximate number of kilobytes they are consuming. This is the default if you omit the <SPAN
9168 >Removes the orphaned objects, and prints a message to the <SPAN
9172 >/usr/afs/logs/SalvageLog</B
9174 > file reporting how many orphans were removed and the
9175 approximate number of kilobytes they were consuming.</P
9187 >Attaches the orphaned objects by creating a reference to them in the vnode of the volume's root
9188 directory. Since each object's actual name is now lost, the Salvager assigns each one a name of the
9189 following form: <TABLE
9198 >_ _ORPHANFILE_ _.</B
9200 > index for files</TD
9208 >_ _ORPHANDIR_ _.</B
9210 > index for directories</TD
9216 >where index is a two-digit number that uniquely identifies each object. The orphans are charged
9217 against the volume's quota and appear in the output of the <SPAN
9224 issued against the volume's root directory.</P
9243 >Setting and Displaying Volume Quota and Current Size</A
9246 >Every AFS volume has an associated quota which limits the volume's size. The default quota for a newly created volume is
9247 5,000 kilobyte blocks (slightly less that 5 MB). When a volume reaches its quota, the File Server rejects attempts to create new
9248 files or directories in it. If an application is writing data into an existing file in a full volume, the File Server allows a
9249 defined overage (by default, 1 MB). (You can use the <SPAN
9267 > argument to change the default overage; see the
9268 command's reference page in the <SPAN
9272 > IBM AFS Administration Reference</I
9276 >To set a quota other than 5000 KB as you create a volume, include the <SPAN
9289 > command, as described in <A
9290 HREF="c8420.html#HDRWQ185"
9291 >Creating Read/write
9293 >. To modify an existing volume's quota, issue either the <SPAN
9306 > command as described in the following instructions. Do not set an existing volume's
9307 quota lower than its current size.</P
9309 >In general, smaller volumes are easier to administer than larger ones. If you need to move volumes, say for load-balancing
9310 purposes, it is easier to find enough free space on other partitions for small volumes. Move operations complete more quickly
9311 for small volumes, reducing the potential for outages or other errors to interrupt the move. AFS supports a maximum volume size,
9312 which can vary for different AFS releases; see the <SPAN
9316 > IBM AFS Release Notes</I
9318 > for the version you are using.
9319 Also, the size of a partition or logical places an absolute limit on volume size, because a volume cannot span multiple
9320 partitions or logical volumes.</P
9322 >It is generally safe to overpack partitions by putting more volumes on them than can actually fit if all the volumes reach
9323 their maximum quota. However, only experience determines to what degree overpacking works in your cell. It depends on what kind
9324 of quota you assign to volumes (particularly user volumes, which are more likely than system volumes to grow unpredictably) and
9325 how much information people generate and store in comparison to their quota.</P
9327 >There are several commands that display a volume's quota, as described in the following instructions. They differ in how
9328 much related information they produce.</P
9335 >To set quota for a single volume</A
9341 >Verify that you belong to the <SPAN
9345 >system:administrators</B
9347 > group. If necessary, issue the
9354 > command, which is fully described in <A
9355 HREF="c32432.html#HDRWQ587"
9357 the members of the system:administrators group</A
9359 CLASS="programlisting"
9364 >pts membership system:administrators</B
9378 > command to set the volume's maximum quota. <PRE
9379 CLASS="programlisting"
9397 >max quota in kbytes</VAR
9403 CLASS="variablelist"
9415 >Is an acceptable alias for <SPAN
9433 >Names a file or directory in the volume for which to set the indicated quota. Partial pathnames are
9434 interpreted relative to the current working directory, which is the default if you omit this argument.</P
9436 >Specify the read/write path to the file or directory, to avoid the failure that results when you attempt to
9437 change a read-only volume. By convention, you indicate the read/write path by placing a period before the cell
9438 name at the pathname's second level (for example, <SPAN
9445 discussion of the concept of read/write and read-only paths through the filespace, see <A
9446 HREF="c8420.html#HDRWQ209"
9447 >The Rules of Mount Point Traversal</A
9455 >max quota in kbytes</B
9460 >Sets the volume's quota, expressed in kilobyte blocks ( <SPAN
9467 megabyte). A value of <SPAN
9473 > grants an unlimited quota, but the size of the partition
9474 imposes an absolute limit. You must include the <SPAN
9480 > switch if omitting the
9481 dir/file path argument (to set the quota on the volume that houses the current working directory).</P
9495 >To set maximum quota on one or more volumes</A
9501 >Verify that you belong to the <SPAN
9505 >system:administrators</B
9507 > group. If necessary, issue the
9514 > command, which is fully described in <A
9515 HREF="c32432.html#HDRWQ587"
9517 the members of the system:administrators group</A
9519 CLASS="programlisting"
9524 >pts membership system:administrators</B
9538 > command to set the quota on one or more volumes.
9540 CLASS="programlisting"
9558 >disk space quota in 1K units</VAR
9564 CLASS="variablelist"
9576 >Is an acceptable alias for <SPAN
9594 >Names one file or directory that resides in each volume for which to set the indicated quota. Partial
9595 pathnames are interpreted relative to the current working directory, which is the default if you omit this
9603 >disk space quota in 1K units</B
9608 >Sets the maximum quota on each volume, expressed in kilobytes blocks ( <SPAN
9615 equals a megabyte). A value of <SPAN
9621 > grants an unlimited quota, but the size of the
9622 partition does impose an absolute limit.</P
9636 >To display percent quota used</A
9649 CLASS="programlisting"
9664 CLASS="variablelist"
9676 >Is the shortest acceptable abbreviation of <SPAN
9694 >Names a directory or file in each volume for which to display percent quota used. Partial pathnames are
9695 interpreted relative to the current working directory, which is the default if you omit this argument.</P
9703 >The following example illustrates the output produced by this command:</P
9705 CLASS="programlisting"
9710 >fs quota /afs/abc.com/usr/terry</B
9722 >To display quota, current size, and other information</A
9735 CLASS="programlisting"
9750 CLASS="variablelist"
9762 >Is an alias for <SPAN
9780 >Names a directory or file in each volume for which to display quota along with volume name and current space
9781 usage. Partial pathnames are interpreted relative to the current working directory, which is the default if you
9782 omit this argument.</P
9790 >As illustrated in the following example, the output reports the volume's name, its quota and current size (both in
9791 kilobyte units), the percent quota used, and the percentage of space on the volume's host partition that is used.</P
9793 CLASS="programlisting"
9798 >fs listquota /afs/abc.com/usr/terry</B
9801 Volume Name Quota Used % Used Partition
9802 user.terry 15000 5071 34% 86%
9811 >To display quota, current size, and more partition information</A
9824 CLASS="programlisting"
9839 CLASS="variablelist"
9851 >Is the shortest acceptable abbreviation of <SPAN
9869 >Names a directory or file in each volume for which to display quota information and information about the
9870 host partition. Partial pathnames are interpreted relative to the current working directory, which is the default
9871 if you omit this argument.</P
9879 >As illustrated in the following example, the output displays the volume's volume ID number and name, its quota and
9880 current size (both in kilobyte units), and the free and total number of kilobyte blocks on the volume's host partition.</P
9882 CLASS="programlisting"
9887 >fs examine /afs/abc.com/usr/terry</B
9890 Volume status for vid = 50489902 named user.terry
9891 Current maximum quota is 15000
9892 Current blocks used are 5073
9893 The partition has 46383 blocks available out of 333305
9902 >The partition-related statistics in this command's output do not always agree with the corresponding values in the
9903 output of the standard UNIX <SPAN
9909 > command. The statistics reported by this command can be up
9910 to five minutes old, because the Cache Manager polls the File Server for partition information at that frequency. Also, on
9911 some operating systems, the <SPAN
9917 > command's report of partition size includes reserved space
9918 not included in this command's calculation, and so is likely to be about 10% larger.</P
9929 >Removing Volumes and their Mount Points</A
9932 >To remove a volume from its site and its record from the VLDB, use the <SPAN
9939 command. Use it to remove any of the three types of volumes; the effect depends on the type. <UL
9942 > If you indicate the read/write volume by specifying the volume's base name without a <SPAN
9954 > extension, the command removes both the
9955 read/write and associated backup volume from the partition that houses them. You do not need to provide the <SPAN
9967 > arguments, because there can be only one
9968 read/write site. The site information is also removed from the VLDB entry, and the site count (reported by the <SPAN
9981 CLASS="computeroutput"
9984 >) decrements by one. The read/write and backup volume ID numbers no longer appear in the output from
9997 > commands, but they are
9998 preserved internally. Read-only sites, if any, are not affected, but cannot be changed unless a read/write site is again
9999 defined. The entire VLDB entry is removed if there are no read-only sites.</P
10001 >If there are no read-only copies left, it is best to remove the volume's mount point to prevent attempts to access
10002 the volume's contents. Do not remove the mount point if copies of the read-only volume remain.</P
10006 >If you indicate a read-only volume by including the <SPAN
10013 name, it is removed from the partition that houses it, and the corresponding site information is removed from the VLDB
10014 entry. The site count reported by the <SPAN
10027 > commands as <SAMP
10028 CLASS="computeroutput"
10029 >number of sites</SAMP
10030 > decrements by one for each volume you
10033 >If there is more than one read-only site, you must include the <SPAN
10040 (and optionally <SPAN
10046 > argument) to specify the site from which to remove the volume.
10047 If there is only one read-only site, the volume name is sufficient; if no read/write volume exists in this case, the
10048 entire VLDB entry is removed.</P
10050 >It is not generally appropriate to remove the volume's mount point when removing a read-only volume, especially if
10051 the read/write version of the volume still exists. If the read/write version no longer exists, remove the mount point as
10052 described in Step <A
10053 HREF="c8420.html#LIWQ239"
10056 HREF="c8420.html#HDRWQ236"
10057 >To remove a volume and unmount
10063 >If you indicate a backup volume by including the <SPAN
10069 > extension on its name, it
10070 is removed from the partition that houses it and its site information is removed from the VLDB entry. You do not need to
10083 > arguments, because
10084 there can be only one backup site. The backup volume ID number no longer appears in the output from the <SPAN
10096 > command, but is preserved
10099 >In the standard configuration, there is a separate mount point for the backup version of a user volume. Remember to
10100 remove the mount point to prevent attempt to access the nonexistent volume's contents.</P
10110 >Other Removal Commands</A
10119 > command is almost always the appropriate way to remove a volume, because
10120 it automatically removes a volume's VLDB entry and both the volume header and all data from the partition. If either the VLDB
10121 entry or volume header does not exist, it is sometimes necessary to use other commands that remove only the remaining element.
10122 Do not use these commands in the normal case when both the VLDB entry and the volume header exist, because by definition they
10123 create discrepancies between them. For details on the commands' syntax, see their reference pages in the <SPAN
10128 Administration Reference</I
10138 > command removes a volume from its site by removing the volume header and
10139 volume data for which a VLDB entry no longer exists. You can tell a VLDB entry is missing if the <SPAN
10146 > command displays the volume header but the <SPAN
10158 > command cannot locate the VLDB entry. You must run this command to correct the
10159 discrepancy, because the <SPAN
10172 commands never remove volume headers.</P
10180 > command removes a read-only site definition from the VLDB without
10181 affecting the volume on the file server machine. Use this command when you have mistakenly issued the <SPAN
10187 > command to define a read-only site, but have not yet issued the <SPAN
10194 > command to release the volume to the site. If you have actually released a volume to the site, use the
10201 > command instead.</P
10209 > command removes the entire VLDB entry that mentions the volume you
10210 specify. If versions of the volume actually exist on file server machines, they are not affected. This command is useful if
10211 you know for certain that a volume removal was not recorded in the VLDB (perhaps you used the <SPAN
10218 > command during an emergency), and do not want to take the time to resynchronize the entire VLDB with the
10239 >To remove a volume and unmount it</A
10245 >Verify that you are listed in the <SPAN
10249 >/usr/afs/etc/UserList</B
10251 > file. If necessary, issue
10258 > command, which is fully described in <A
10259 HREF="c32432.html#HDRWQ593"
10261 display the users in the UserList file</A
10263 CLASS="programlisting"
10271 CLASS="replaceable"
10279 >If removing the volume's mount point, verify that you have the <SPAN
10291 >) permission on its parent directory's ACL. If necessary, issue the <SPAN
10298 > command, which is fully described in <A
10299 HREF="c31274.html#HDRWQ572"
10300 >Displaying ACLs</A
10302 CLASS="programlisting"
10310 CLASS="replaceable"
10311 >dir/file path</VAR
10316 >Members of the <SPAN
10320 >system:administrators</B
10322 > group always implicitly have the <SPAN
10334 >) and by default also the <SPAN
10346 >) permission on every ACL and can use the <SPAN
10352 > command to grant other rights as necessary.</P
10365 > Dump the volume to a file or to tape, in case you want to restore it
10366 later. To copy the volume's contents to a file, use the <SPAN
10372 > command as instructed in
10374 HREF="c8420.html#HDRWQ240"
10375 >Dumping and Restoring Volumes</A
10376 >. You can then copy the file to tape using a third-party
10377 backup utility or an archiving utility such as the UNIX <SPAN
10385 >Alternatively, use the AFS Backup System to create a tape copy. In this case, it can be convenient to create a
10386 temporary volume set that includes only the volume of interest. Temporary volume sets are not recorded in the Backup
10387 Database, and so do not clutter database with records for volume sets that you use only once. For instructions, see <A
10388 HREF="c15383.html#HDRWQ301"
10389 >To create a dump</A
10403 > command to remove the volume. If
10404 removing a read-only volume from multiple sites, repeat the command for each one. <PRE
10405 CLASS="programlisting"
10418 > machine name>] [<SPAN
10425 CLASS="replaceable"
10426 >partition name</VAR
10435 CLASS="replaceable"
10436 >volume name or ID</VAR
10442 CLASS="variablelist"
10454 >Is the shortest acceptable abbreviation of <SPAN
10472 >Specifies the file server machine on which the volume resides. It is necessary only when the <SPAN
10478 > argument names a read-only volume that exists at multiple sites.</P
10490 >Specifies the partition on machine name where the volume resides. It is necessary only when the <SPAN
10496 > argument names a read-only volume that exists at multiple sites. Provide the <SPAN
10502 > argument along with this one.</P
10514 >Identifies the volume to remove, either by its complete name or volume ID number. If identifying a read-only
10515 or backup volume by name, include the appropriate extension ( <SPAN
10539 >If you are removing the last existing version of the volume, issue the <SPAN
10545 > command remove the corresponding mount point. Complete instructions appear in <A
10546 HREF="c8420.html#HDRWQ236"
10547 >To remove a volume and unmount it</A
10550 >If you are removing a backup volume that is mounted in the conventional way (at a subdirectory of its read/write
10551 volume's root directory), then removing the source volume's mount point in this step is sufficient to remove the backup
10552 volume's mount point. If you mounted the backup at a completely separate directory, you need to repeat this step for the
10553 backup volume's mount point.</P
10555 CLASS="programlisting"
10563 CLASS="replaceable"
10576 > If you created a dump file in Step <A
10577 HREF="c8420.html#LIWQ237"
10580 transfer it to tape. The preferred method is to use the AFS Backup System, which is described in <A
10582 >Configuring the AFS Backup System</A
10585 >Backing Up and Restoring AFS
10598 >Dumping and Restoring Volumes</A
10607 > a volume with the <SPAN
10613 > command converts its contents
10614 into ASCII format and writes them to the file you specify. The <SPAN
10621 dump file's contents into a volume after converting them into the volume format appropriate for the indicated file server
10629 >About Dumping Volumes</A
10632 >Dumping a volume can be useful in several situations, including the following: <UL
10635 >You want to back it up to tape, perhaps by using a third-party backup utility. To facilitate this type of backup
10636 operation, the <SPAN
10642 > command can write to a named pipe. To learn about using the AFS
10643 Backup System instead, see <A
10645 >Configuring the AFS Backup System</A
10648 >Backing Up and Restoring AFS Data</A
10653 >You are removing the volume from your cell (perhaps because its owner is leaving your cell). The <SPAN
10659 > command enables you to create a copy for safekeeping without incurring the overhead of
10660 the Backup System. For complete instructions on removing a volume, see <A
10661 HREF="c8420.html#HDRWQ235"
10662 >Removing Volumes and
10663 their Mount Points</A
10668 >You want to create a copy of the volume for safekeeping on a non-AFS server partition, perhaps while you move the
10669 actual volume to another machine or perform maintenance tasks on the partition that houses the volume.</P
10673 >You need to replace a corrupted read/write volume. If an uncorrupted read-only or backup version of the volume
10674 exists, dump it and restore the data into the read/write volume, overwriting the corrupted contents.</P
10678 >You want to copy or transfer the contents of the volume to another cell. You cannot use the <SPAN
10684 > command, because AFS supports volume moves only between file server machines that belong
10685 to the same cell.</P
10689 >You want to have another read/write copy of the volume's contents. The second volume must have a different name
10690 than the original one. If you want the contents of the two volumes to remain identical, you must update them both
10691 manually. AFS provides no facility for keeping read/write volumes synchronized in this way.</P
10695 >You want a copy of only the files and directories in the volume with modification time stamps after a certain
10702 > command can create an incremental dump file as described in Step
10704 HREF="c8420.html#LIWQ241"
10706 >of the following instructions.</P
10711 >You can use the <SPAN
10717 > command to create a <SPAN
10724 contains the complete contents of the volume at the time you issue the command, or an <SPAN
10728 >incremental dump</I
10731 which contains only those files and directories with modification timestamps (as displayed by the <SPAN
10738 > command) that are later than a date and time you specify. See Step <A
10739 HREF="c8420.html#LIWQ241"
10742 following instructions.</P
10744 >Dumping a volume does not change its VLDB entry or permanently affect its status on the file server machine, but the
10745 volume's contents are inaccessible during the dump operation. To avoid interrupting access to the volume, it is generally best
10746 to dump the volume's backup version, just after using the <SPAN
10758 > command to create a new backup version.</P
10760 >If you do not provide a filename into which to write the dump, the <SPAN
10767 directs the output to the standard output stream. You can pipe it directly to the <SPAN
10774 command if you wish.</P
10776 >Because a volume dump file is in ASCII format, you can read its contents using a text editor or a command such as the
10783 > command. However, dump files sometimes contain special characters that do not have
10784 alphanumeric correlates, which can cause problems for some display programs.</P
10786 >By default, the <SPAN
10792 > command interpreter consults the Volume Location Database (VLDB) to
10793 learn the volume's location, so the <SPAN
10806 arguments are not required. If the <SPAN
10812 > argument identifies a read-only volume that resides at
10813 multiple sites, then the command dumps the version from just one of them (normally, the one listed first in the volume's VLDB
10814 entry as reported by the <SPAN
10827 command). To dump the read-only volume from a particular site, use the <SPAN
10839 > arguments to specify the site. To bypass the VLDB lookup entirely, provide a volume ID
10840 number (rather than a volume name) as the value for the <SPAN
10846 > argument, along with the
10859 > arguments. This makes it possible to
10860 dump a volume for which there is no VLDB entry.</P
10868 >To dump a volume</A
10874 >Verify that you are listed in the <SPAN
10878 >/usr/afs/etc/UserList</B
10880 > file. If necessary, issue
10887 > command, which is fully described in <A
10888 HREF="c32432.html#HDRWQ593"
10890 display the users in the UserList file</A
10892 CLASS="programlisting"
10900 CLASS="replaceable"
10908 >Verify that you have the permissions necessary to create the dump file. If placing it in AFS, you must have the
10921 >) permission on the ACL of the file's
10922 directory. If necessary, issue the <SPAN
10928 > command, which is fully described in <A
10929 HREF="c31274.html#HDRWQ572"
10930 >Displaying ACLs</A
10932 CLASS="programlisting"
10940 CLASS="replaceable"
10941 >dir/file path</VAR
10946 >Members of the <SPAN
10950 >system:administrators</B
10952 > group always implicitly have the <SPAN
10964 >) and by default also the <SPAN
10976 >) permission on every ACL and can use the <SPAN
10982 > command to grant other rights as necessary.</P
10995 > command to dump the volume.
10997 CLASS="programlisting"
11005 CLASS="replaceable"
11006 >volume name or ID</VAR
11014 CLASS="replaceable"
11015 >dump from time</VAR
11023 CLASS="replaceable"
11032 CLASS="replaceable"
11041 CLASS="replaceable"
11048 CLASS="variablelist"
11060 >Identifies the volume to be dumped by its complete name or volume ID number. If you want to dump the
11061 read-only or backup version, specify its volume ID number or add the appropriate extension ( <SPAN
11075 >To bypass the normal VLDB lookup of the volume's location, provide the volume ID number and combine this
11076 argument with the <SPAN
11101 >Specifies whether the dump is full or incremental. Omit this argument to create a full dump, or provide one
11102 of three acceptable values: <UL
11111 >(zero) to create a full dump.</P
11115 >A date in the format mm <SPAN
11128 (month, day and year) to create an incremental dump that includes only files and directories with
11129 modification timestamps later than midnight (12:00 a.m.) on the indicated date. Valid values for the year
11142 >; higher values are
11143 not valid because the latest possible date in the standard UNIX representation is in 2038. The command
11144 interpreter automatically reduces later dates to the maximum value. An example is <SPAN
11154 >A date and time in the format <SPAN
11185 > to create an incremental dump that includes only files and directories with
11186 modification timestamps later than the specified date and time. The date format is the same as for a date
11187 alone. Express the time as hours and minutes (hh:MM) in 24-hour format (for example, <SPAN
11193 > is 8:30 p.m.). Surround the entire expression with double quotes (" ") because
11194 it contains a space. An example is <SPAN
11198 >"01/13/1999 22:30"</B
11215 >Specifies the pathname of the file to which to write the dump. The file can be in AFS, but not in the volume
11216 being dumped. A partial pathname is interpreted relative to the current working directory. Omit this argument to
11217 direct the dump to the standard output stream.</P
11229 >Specifies the file server machine on which the volume resides. Provide the <SPAN
11235 > argument along with this one.</P
11247 >Specifies the partition on which the volume resides. Provide the <SPAN
11254 argument along with this one.</P
11268 >About Restoring Volumes</A
11271 >Although you can dump any of the three types of volumes (read/write, read-only, or backup), you can restore a dump file
11272 to the file system only as a read/write volume, using the <SPAN
11278 > command. The command
11279 automatically translates the dump file's contents from ASCII back into the volume format appropriate for the file server
11280 machine that stores the restored version. As with the <SPAN
11286 > command, you can restore a
11287 dump file via a named pipe, which facilitates interoperation with third-party backup utilities.</P
11289 >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
11290 the volume before restoring any incremental dumps. Any incremental dumps that you then restore must have been created after
11291 the full dump. If there is more than one incremental dump, you must restore them in the order they were created. <UL
11294 >You can restore volume data into a brand new volume with a new name and at a location that you specify. See <A
11295 HREF="c8420.html#HDRWQ242"
11296 >To restore a dump into a new volume and mount it</A
11299 >You can assign a volume ID number as you restore the volume, though it is best to have the Volume Server allocate
11300 a volume number automatically. The most common reason for specifying the volume ID is that a volume's VLDB entry has
11301 disappeared for some reason, but you know the former read/write volume ID number and want to reuse it.</P
11305 >You can restore volume data into an existing volume (usually the one that was previously dumped), overwriting its
11306 current contents. This is convenient if the current contents are corrupted or otherwise incorrect, because it allows you
11307 to replace them with a coherent version from the past or from one of the volume's clones. See <A
11308 HREF="c8420.html#HDRWQ244"
11309 >To restore a dump file, overwriting an existing volume</A
11318 > argument to preconfirm that you wish to overwrite the
11319 volume's contents, and to specify whether you are restoring a full or incremental dump. If you omit the <SPAN
11325 > argument, the Volume Server generates the following prompt to confirm that you want to
11326 overwrite the existing volume with either a full ( <SPAN
11332 >) or incremental ( <SPAN
11340 CLASS="programlisting"
11341 > Do you want to do a full/incremental restore or abort? [fia](a):
11344 >If you pipe in the dump file via the standard input stream instead of using the <SPAN
11350 > argument to name it, you must include the <SPAN
11357 argument because there is nowhere for the Volume Server to display the prompt in this case.</P
11359 >You can move the volume to a new site as you overwrite it with a full dump, by using the <SPAN
11371 > arguments to specify the new site. You
11372 cannot move the volume when restoring an incremental dump.</P
11383 > command sets the restored volume's creation date in the volume header
11384 to the time of the restore operation, as reported in the <SAMP
11385 CLASS="computeroutput"
11387 > field in the output from
11408 >To restore a dump into a new volume and mount it</A
11414 >Verify that you are listed in the <SPAN
11418 >/usr/afs/etc/UserList</B
11420 > file. If necessary, issue
11427 > command, which is fully described in <A
11428 HREF="c32432.html#HDRWQ593"
11430 display the users in the UserList file</A
11432 CLASS="programlisting"
11440 CLASS="replaceable"
11448 >Verify that you have permissions needed to read the dump file and to mount the new volume. If the dump file resides
11449 in AFS, you need the <SPAN
11461 >) permission on the ACL of
11462 its directory. You need the <SPAN
11486 >) permissions on the ACL of the directory where you
11487 are mounting the new volume. If necessary, issue the <SPAN
11493 > command, which is fully
11495 HREF="c31274.html#HDRWQ572"
11496 >Displaying ACLs</A
11498 CLASS="programlisting"
11506 CLASS="replaceable"
11507 >dir/file path</VAR
11512 >Members of the <SPAN
11516 >system:administrators</B
11518 > group always implicitly have the <SPAN
11530 >) and by default also the <SPAN
11542 >) permission on every ACL and can use the <SPAN
11548 > command to grant other rights as necessary.</P
11552 >Select a site (disk partition on a file server machine) for the new volume. If your cell groups different types of
11553 volumes onto different file server machines, that can guide your decision. It often makes sense to put the volume on the
11554 emptiest partition that meets your other criteria. To display how much space is available on a file server machine's
11555 partitions, use the <SPAN
11561 > command, which is described fully in <A
11562 HREF="c8420.html#HDRWQ185"
11563 >Creating Read/write Volumes</A
11565 CLASS="programlisting"
11573 CLASS="replaceable"
11576 CLASS="replaceable"
11577 >partition name</VAR
11593 > command to create a new volume and
11594 restore the dump file into it. Type it on a single line; it appears on multiple lines here only for legibility.
11596 CLASS="programlisting"
11604 CLASS="replaceable"
11607 CLASS="replaceable"
11608 >partition name</VAR
11611 CLASS="replaceable"
11612 >name of volume to be restored</VAR
11621 CLASS="replaceable"
11630 CLASS="replaceable"
11637 CLASS="variablelist"
11649 >Is the shortest acceptable abbreviation of <SPAN
11667 >Names the file server machine on which to create the new volume.</P
11679 >Names the partition on which to create the new volume.</P
11686 >name of volume to be restored</B
11691 >Names the new read/write volume, which must not already have a VLDB entry. It can be up to 22 characters in
11704 >Is the dump file to restore. Partial pathnames are interpreted with respect to the current working
11705 directory. Omit this argument if using a pipe to read in the dump file from the standard input stream.</P
11717 >Specifies the new volume's ID number. It is appropriate only if you are restoring a volume that no longer
11718 exists and want to use the volume ID number it had previously.</P
11732 > command to mount the new volume, making its contents
11733 accessible. Complete instructions appear in <A
11734 HREF="c8420.html#HDRWQ212"
11735 >To create a regular or read/write mount point</A
11738 CLASS="programlisting"
11746 CLASS="replaceable"
11749 CLASS="replaceable"
11769 > command to verify
11770 that the mount point refers to the correct volume. Complete instructions appear in <A
11771 HREF="c8420.html#HDRWQ211"
11775 CLASS="programlisting"
11783 CLASS="replaceable"
11797 >To restore a dump file, overwriting an existing volume</A
11803 >Verify that you are listed in the <SPAN
11807 >/usr/afs/etc/UserList</B
11809 > file. If necessary, issue
11816 > command, which is fully described in <A
11817 HREF="c32432.html#HDRWQ593"
11819 display the users in the UserList file</A
11821 CLASS="programlisting"
11829 CLASS="replaceable"
11837 >Verify that you have permissions needed to read the dump file. If it resides in AFS, you need the <SPAN
11849 >) permission on the ACL of its directory. If necessary,
11856 > command, which is fully described in <A
11857 HREF="c31274.html#HDRWQ572"
11858 >Displaying ACLs</A
11860 CLASS="programlisting"
11868 CLASS="replaceable"
11869 >dir/file path</VAR
11874 >Members of the <SPAN
11878 >system:administrators</B
11880 > group always implicitly have the <SPAN
11892 >) and by default also the <SPAN
11904 >) permission on every ACL and can use the <SPAN
11910 > command to grant other rights as necessary.</P
11914 >Restore the contents of the dump file into a read/write volume, overwriting the current contents. The volume retains
11915 its current volume ID number. Type it on a single line; it appears on multiple lines here only for legibility.
11917 CLASS="programlisting"
11925 CLASS="replaceable"
11928 CLASS="replaceable"
11929 >partition name</VAR
11932 CLASS="replaceable"
11933 >name of volume to be restored</VAR
11942 CLASS="replaceable"
11951 CLASS="replaceable"
11958 CLASS="variablelist"
11970 >Is the shortest acceptable abbreviation of <SPAN
11988 >Names the file server machine where the volume already exists, or the machine to which to move it. In the
11989 latter case, the value for the <SPAN
11995 > argument must be <SPAN
12013 >Names the partition where the volume already exists, or the partition to which to move it. In the latter
12014 case, the value for the <SPAN
12020 > argument must be <SPAN
12033 >name of volume to be restored</B
12038 >Names the read/write volume to overwrite with the contents of the dump file.</P
12050 >Is the dump file to restore. Partial pathnames are interpreted with respect to the current working
12051 directory. Omit this argument if using a pipe to read in the dump file from the standard input stream; in this
12052 case, you must provide the <SPAN
12070 >Preconfirms that you want to overwrite the existing volume and specifies which type of dump file you are
12071 restoring. Provide one of the following values: <UL
12086 > if restoring a full dump
12104 incremental dump file. This value is not acceptable if you are moving the volume while restoring it.</P
12114 > to terminate the restore operation</P
12125 >If the volume is replicated, issue the <SPAN
12131 > command to release the newly
12132 restored contents to read-only sites. Complete instructions appear in <A
12133 HREF="c8420.html#HDRWQ192"
12134 >Replicating Volumes
12135 (Creating Read-only Volumes)</A
12137 CLASS="programlisting"
12145 CLASS="replaceable"
12146 >volume name or ID</VAR
12159 > command to create a new backup version of the volume. Complete
12160 instructions appear in <A
12161 HREF="c8420.html#HDRWQ201"
12162 >Creating Backup Volumes</A
12164 CLASS="programlisting"
12172 CLASS="replaceable"
12173 >volume name or ID</VAR
12187 >Renaming Volumes</A
12190 >You can use the <SPAN
12196 > command to rename a volume. For example, it is appropriate to
12197 rename a user's home volume if you use the <SPAN
12203 > username convention for user volume names and
12204 you change the username. (For complete instructions for changing usernames, see <A
12205 HREF="c27596.html#HDRWQ518"
12216 > command accepts only read/write volume names, but automatically changes
12217 the names of the associated read-only and backup volumes. As directed in the following instructions, you need to replace the
12218 volume's current mount point with a new one that reflects the name change.</P
12225 >To rename a volume</A
12231 >Verify that you are listed in the <SPAN
12235 >/usr/afs/etc/UserList</B
12237 > file. If necessary, issue
12244 > command, which is fully described in <A
12245 HREF="c32432.html#HDRWQ593"
12247 display the users in the UserList file</A
12249 CLASS="programlisting"
12257 CLASS="replaceable"
12265 >Verify that you have the <SPAN
12301 >) access permissions for the directory in which you are replacing the volume's mount point.
12302 If necessary, issue the <SPAN
12308 > command, which is fully described in <A
12309 HREF="c31274.html#HDRWQ572"
12310 >Displaying ACLs</A
12312 CLASS="programlisting"
12320 CLASS="replaceable"
12321 >dir/file path</VAR
12326 >Members of the <SPAN
12330 >system:administrators</B
12332 > group always implicitly have the <SPAN
12344 >) and by default also the <SPAN
12356 >) permission on every ACL and can use the <SPAN
12362 > command to grant other rights as necessary.</P
12375 > command to rename the volume.
12377 CLASS="programlisting"
12385 CLASS="replaceable"
12386 >old volume name</VAR
12388 CLASS="replaceable"
12389 >new volume name</VAR
12395 CLASS="variablelist"
12407 >Is the shortest acceptable abbreviation of <SPAN
12420 >old volume name</B
12425 >Is the current name of a read/write volume.</P
12432 >new volume name</B
12437 >Is the new name for the volume. It cannot be more than 22 characters in length.</P
12443 >If there is no Volume Location Database (VLDB) entry for the specified current volume name, the command fails with
12444 the following error message:</P
12446 CLASS="programlisting"
12447 > vos: Could not find entry for volume old_volume_name.
12458 > command to remove the mount point that refers to the volume's
12459 old name. Complete instructions appear in <A
12460 HREF="c8420.html#HDRWQ215"
12461 >To remove a mount point</A
12463 CLASS="programlisting"
12471 CLASS="replaceable"
12485 > to create a mount point that indicates the volume's new name.
12486 Complete instructions appear in <A
12487 HREF="c8420.html#HDRWQ212"
12488 >To create a regular or read/write mount point</A
12491 CLASS="programlisting"
12499 CLASS="replaceable"
12502 CLASS="replaceable"
12523 >Unlocking and Locking VLDB Entries</A
12527 HREF="c8420.html#HDRWQ227"
12528 >Synchronizing the VLDB and Volume Headers</A
12529 >, The Volume Location (VL) Server
12530 locks the Volume Location Database (VLDB) entry for a volume before the Volume Server executes any operation on it. No other
12531 operation can affect a volume with a locked VLDB entry, so the lock prevents the inconsistency or corruption that can result
12532 from multiple simultaneous operations on a volume.</P
12534 >To verify that a VLDB entry is locked, issue the <SPAN
12540 > command as described in
12542 HREF="c8420.html#HDRWQ218"
12543 >To display VLDB entries</A
12544 >. The command has a <SPAN
12551 displays locked entries only. If the VLDB entry is locked, the string <SAMP
12552 CLASS="computeroutput"
12553 >Volume is currently
12555 > appears on the last line of the volume's output.</P
12557 >To lock a VLDB entry yourself, use the <SPAN
12563 > command. This is useful when you suspect
12564 something is wrong with a volume and you want to prevent any changes to it while you are investigating the problem.</P
12566 >To unlock a locked VLDB entry, issue the <SPAN
12572 > command, which unlocks a single VLDB
12573 entry, or the <SPAN
12579 > command, which unlocks potentially many entries. This is useful
12580 when a volume operation fails prematurely and leaves a VLDB entry locked, preventing you from acting to correct the problems
12581 resulting from the failure.</P
12588 >To lock a VLDB entry</A
12594 >Verify that you are listed in the <SPAN
12598 >/usr/afs/etc/UserList</B
12600 > file. If necessary, issue
12607 > command, which is fully described in <A
12608 HREF="c32432.html#HDRWQ593"
12610 display the users in the UserList file</A
12612 CLASS="programlisting"
12620 CLASS="replaceable"
12634 > to lock the entry. <PRE
12635 CLASS="programlisting"
12643 CLASS="replaceable"
12644 >volume name or ID</VAR
12650 CLASS="variablelist"
12662 >Is the shortest acceptable abbreviation of <SPAN
12675 >volume name or ID</B
12680 >Identifies the volume to be locked, either by its complete name or volume ID number. It can be any of the
12681 three versions of the volume.</P
12695 >To unlock a single VLDB entry</A
12701 >Verify that you are listed in the <SPAN
12705 >/usr/afs/etc/UserList</B
12707 > file. If necessary, issue
12714 > command, which is fully described in <A
12715 HREF="c32432.html#HDRWQ593"
12717 display the users in the UserList file</A
12719 CLASS="programlisting"
12727 CLASS="replaceable"
12741 > command to unlock the entry. <PRE
12742 CLASS="programlisting"
12750 CLASS="replaceable"
12751 >volume name or ID</VAR
12757 CLASS="variablelist"
12769 >Must be typed in full.</P
12776 >volume name or ID</B
12781 >Identifies the volume to be unlocked, either by its complete name or volume ID number. It can be any of the
12782 three versions of the volume.</P
12796 >To unlock multiple VLDB entries</A
12802 >Verify that you are listed in the <SPAN
12806 >/usr/afs/etc/UserList</B
12808 > file. If necessary, issue
12815 > command, which is fully described in <A
12816 HREF="c32432.html#HDRWQ593"
12818 display the users in the UserList file</A
12820 CLASS="programlisting"
12828 CLASS="replaceable"
12842 > command to unlock the desired entries. <PRE
12843 CLASS="programlisting"
12851 CLASS="replaceable"
12854 CLASS="replaceable"
12855 >partition name</VAR
12861 CLASS="variablelist"
12873 >Is the shortest acceptable abbreviation of <SPAN
12891 >Specifies a file server machine. Provide this argument alone to unlock all VLDB entries that mention the
12892 machine in a site definition. Omit both this argument and the partition name argument to unlock all VLDB
12905 >Specifies a partition. Provide this argument alone to unlock all VLDB entries that mention the partition (on
12906 any machine) in a site definition. Omit both this argument and the machine name argument to unlock all VLDB
12921 WIDTH="100%"><TABLE
12922 SUMMARY="Footer navigation table"
12961 >Monitoring and Controlling Server Processes</TD
12975 >Configuring the AFS Backup System</TD
git://git.openafs.org / openafs.git / blob