1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3//EN">
3 <TITLE>Administration Guide</TITLE>
4 <!-- Begin Header Records ========================================== -->
5 <!-- /tmp/idwt3191/auagd000.scr converted by idb2h R4.2 (359) ID -->
6 <!-- Workbench Version (AIX) on 5 Nov 1999 at 14:06:34 -->
7 <META HTTP-EQUIV="updated" CONTENT="Fri, 05 Nov 1999 14:06:34">
8 <META HTTP-EQUIV="review" CONTENT="Sun, 05 Nov 2000 14:06:34">
9 <META HTTP-EQUIV="expires" CONTENT="Mon, 05 Nov 2001 14:06:34">
11 <!-- (C) IBM Corporation 2000. All Rights Reserved -->
12 <BODY bgcolor="ffffff">
13 <!-- End Header Records ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>Administration Guide</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd009.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auagd011.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
17 <HR><H1><A NAME="HDRWQ228" HREF="auagd002.htm#ToC_201">Managing Volumes</A></H1>
18 <P>This chapter explains how to manage the volumes stored on
19 file server machines. The volume is the designated unit of
20 administration in AFS, so managing them is a large part of the
21 administrator's duties.
22 <HR><H2><A NAME="HDRWQ229" HREF="auagd002.htm#ToC_202">Summary of Instructions</A></H2>
23 <P>This chapter explains how to perform the following tasks by
24 using the indicated commands:
28 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Create read/write volume
29 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos create</B>
31 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Create read-only volume
32 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos addsite</B> <B> and</B> <B>vos release</B>
34 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Create backup volume
35 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos backup</B>
37 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Create many backup volumes at once
38 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos backupsys</B>
40 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Examine VLDB entry
41 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos listvldb</B>
43 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Examine volume header
44 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos listvol</B>
46 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Examine both VLDB entry and volume header
47 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos examine</B>
49 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Display volume's name
50 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>fs listquota</B> <B>or</B> <B>fs examine</B>
52 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Display volume's ID number
53 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>fs examine</B> <B>or</B> <B>vos examine</B> <B>or</B>
56 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Display partition's size and space available
57 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos partinfo</B>
59 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Display volume's location
60 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>fs whereis</B> <B>or</B> <B>vos examine</B>
62 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Create mount point
63 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>fs mkmount</B>
65 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Remove mount point
66 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>fs rmmount</B>
68 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Display mount point
69 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>fs lsmount</B>
71 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Move read/write volume
72 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos move</B>
74 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Synchronize VLDB with volume headers
75 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos syncvldb</B> <B>and</B> <B>vos syncserv</B>
77 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Set volume quota
78 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>fs setvol</B> <B>or</B> <B>fs setquota</B>
80 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Display volume quota
81 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>fs quota</B> <B>or</B> <B>fs listquota</B> <B>or</B>
84 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Display volume's current size
85 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>fs listquota</B> <B>or</B> <B>fs examine</B>
87 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Display list of volumes on a machine/partition
88 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos listvol</B>
90 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Remove read/write volume
91 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos remove</B> <B>and</B> <B>fs rmmount</B>
93 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Remove read-only volume
94 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos remove</B>
96 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Remove backup volume
97 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos remove</B> <B>and</B> <B>fs rmmount</B>
99 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Remove volume; no VLDB change
100 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos zap</B>
102 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Remove read-only site definition
103 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos remsite</B>
105 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Remove VLDB entry; no volume change
106 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos delentry</B>
108 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Dump volume
109 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos dump</B>
111 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Restore dumped volume
112 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos restore</B>
114 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Rename volume
115 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos rename</B>, <B>fs rmmount</B> <B>and</B> <B>fs
118 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Unlock volume
119 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos unlock</B>
121 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Unlock multiple volumes
122 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos unlockvldb</B>
124 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Lock volume
125 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>vos lock</B>
127 <HR><H2><A NAME="HDRWQ262" HREF="auagd002.htm#ToC_203">About Volumes</A></H2>
128 <A NAME="IDX6430"></A>
129 <P>An AFS <I>volume</I> is a logical unit of disk space that functions
130 like a container for the files in an AFS directory, keeping them all together
131 on one partition of a file server machine. To make a volume's
132 contents visible in the cell's file tree and accessible to users, you
133 mount the volume at a directory location in the AFS filespace. The
134 association between the volume and its location in the filespace is called a
135 <I>mount point</I>, and because of AFS's internal workings it looks
136 and acts just like a standard directory element. Users can access and
137 manipulate a volume's contents in the same way they access and manipulate
138 the contents of a standard UNIX directory. For more on the relationship
139 between volumes and directories, see <A HREF="#HDRWQ268">About Mounting Volumes</A>.
140 <P>Many of an administrator's daily activities involve manipulating
141 volumes, since they are the basic storage and administrative unit of
142 AFS. For a discussion of some of the ways volumes can make your job
143 easier, see <A HREF="#HDRWQ264">How Volumes Improve AFS Efficiency</A>.
144 <P><H3><A NAME="HDRWQ263" HREF="auagd002.htm#ToC_204">The Three Types of Volumes</A></H3>
145 <P>There are three types of volumes in AFS, as described in the
148 <P><LI>The single <I>read/write</I> version of a volume houses the modifiable
149 versions of the files and directories in that volume.
150 <A NAME="IDX6431"></A>
151 It is often referred to as the <I>read/write source</I> because volumes of
152 the other two types are derived from it by a copying procedure called
153 <I>cloning</I>. For instructions on creating read/write volumes,
154 see <A HREF="#HDRWQ270">Creating Read/write Volumes</A>.
155 <P><LI>A <I>read-only</I> volume is a copy of the read/write source volume
156 and can exist at multiple <I>sites</I> (a site is a particular partition
157 on a particular file server machine).
158 <A NAME="IDX6432"></A>
159 <A NAME="IDX6433"></A>
160 <A NAME="IDX6434"></A>
161 Placing the same data at more than one site is called
162 <I>replication</I>; see <A HREF="#HDRWQ264">How Volumes Improve AFS Efficiency</A>. As the name suggests, a
163 read-only volume's contents do not change automatically as the read/write
164 source changes, but only when an administrator issues the <B>vos
165 release</B> command. For users to have a consistent view of the AFS
166 filespace, all copies of the read-only volume must match each other and their
167 read/write source. All read-only volumes share the same name, which is
168 derived by adding the <B>.readonly</B> extension to the read/write
169 source's name. For instructions on creating of read-only volumes,
170 see <A HREF="#HDRWQ277">Replicating Volumes (Creating Read-only Volumes)</A>.
171 <P><LI>A <I>backup</I> volume is a clone of the read/write source volume and
172 is stored at the same site as the source.
173 <A NAME="IDX6435"></A>
174 A backup version is useful because it records the state of the read/write
175 source at a certain time, allowing recovery of data that is later mistakenly
176 changed or deleted (for further discussion see <A HREF="#HDRWQ264">How Volumes Improve AFS Efficiency</A>). A backup volume's name is derived by adding
177 the <B>.backup</B> extension to the read/write source's
178 name. For instructions on creating of backup volumes, see <A HREF="#HDRWQ286">Creating Backup Volumes</A>.
179 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">A backup volume is not the same as the backup of a volume transferred to tape
180 using the AFS Backup System, although making a backup version of a volume is
181 usually a stage in the process of backing up the volume to tape. For
182 information on backing up a volume using the AFS Backup System, see <A HREF="auagd012.htm#HDRWQ411">Backing Up Data</A>.
185 <P>As noted, the three types of volumes are related to one another:
186 read-only and backup volumes are both derived from a read/write volume through
187 a process called cloning. Read-only and backup volumes are exact copies
188 of the read/write source at the time they are created.
189 <P><H3><A NAME="HDRWQ264" HREF="auagd002.htm#ToC_205">How Volumes Improve AFS Efficiency</A></H3>
190 <A NAME="IDX6436"></A>
191 <P>Volumes make your cell easier to manage and more efficient in the following
194 <P><LI>Volumes are easy to move between partitions, on the same or different
195 machines, because they are by definition smaller than a partition.
196 <A NAME="IDX6437"></A>
197 Perhaps the most common reasons to move volumes are to balance the load among
198 file server machines or to take advantage of greater disk capacity on certain
199 machines. You can move volumes as often as necessary without disrupting
200 user access to their contents, because the move procedure makes the contents
201 unavailable for only a few seconds. The automatic tracking of volume
202 locations in the Volume Location Database (VLDB) assures that access remains
203 transparent. For instructions on moving volumes, see <A HREF="#HDRWQ311">Moving Volumes</A>.
204 <P><LI>Volumes are the unit of replication in AFS.
205 <A NAME="IDX6438"></A>
206 <A NAME="IDX6439"></A>
207 <I>Replication</I> refers to creating a read-only clone from the
208 read/write source and distributing of the clone to one or more sites.
209 Replication improves system efficiency because more than one machine can fill
210 requests for popular files. It also boosts system reliability by
211 helping to keep data available in the face of machine or server process
212 outage. In general, volumes containing popular application programs and
213 other files that do not change often are the best candidates for replication,
214 but you can replicate any read/write volume. See <A HREF="#HDRWQ277">Replicating Volumes (Creating Read-only Volumes)</A>.
215 <P><LI>Volumes are the unit of backup in AFS, in two senses.
216 <A NAME="IDX6440"></A>
217 You can create a backup volume version to preserves the state of a read/write
218 source volume at a specified time. You can mount the backup version in
219 the AFS filespace, enabling users to restore data they have accidentally
220 changed or deleted without administrator assistance, which frees you for more
221 important jobs. If you make a new backup version of user volumes once a
222 day (presumably overwriting the former backup), then users are always be able
223 to retrieve the previous day's version of a file. For
224 instructions, see <A HREF="#HDRWQ286">Creating Backup Volumes</A>.
225 <P>Backup also refers to using the AFS Backup System to store permanent copies
226 of volume contents on tape or in a special backup data. See <A HREF="auagd011.htm#HDRWQ333">Configuring the AFS Backup System</A> and <A HREF="auagd012.htm#HDRWQ382">Backing Up and Restoring AFS Data</A>.
228 <P><H3><A NAME="HDRWQ265" HREF="auagd002.htm#ToC_206">Volume Information in the VLDB</A></H3>
229 <P>The Volume Location Database (VLDB) includes entries for
230 every volume in a cell. Perhaps the most important information in the
231 entry is the volume's location, which is key to transparent access to AFS
232 data. When a user opens a file, the Cache Manager consults the Volume
233 Location (VL) Server, which maintains the VLDB, for a list of the file server
234 machines that house the volume containing the file. The Cache Manager
235 then requests the file from the File Server running on one of the relevant
236 file server machines. The file location procedure is invisible to the
237 user, who only needs to know the file's pathname.
238 <A NAME="IDX6441"></A>
239 <A NAME="IDX6442"></A>
240 <A NAME="IDX6443"></A>
241 <P>The VLDB volume entry for a read/write volume also contains the pertinent
242 information about the read-only and backup versions, which do not have their
243 own VLDB entries. (The rare exception is a read-only volume that has
244 its own VLDB entry because its read/write source has been removed.) A
245 volume's VLDB entry records the volume's name, the unique volume ID
246 number for each version (read/write, read-only, backup, and releaseClone), a
247 count of the number of sites that house a read/write or read-only version, and
249 <P>To display the VLDB entry for one or more volumes, use the <B>vos
250 listvldb</B> command as described in <A HREF="#HDRWQ303">To display VLDB entries</A>. To display the VLDB entry for a single volume along
251 with its volume header, use the <B>vos examine</B> command as described in
252 <A HREF="#HDRWQ307">To display one volume's VLDB entry and volume header</A>. (See the following section for a description of the
254 <P><H3><A NAME="HDRWQ266" HREF="auagd002.htm#ToC_207">The Information in Volume Headers</A></H3>
255 <A NAME="IDX6444"></A>
256 <A NAME="IDX6445"></A>
257 <P>Whereas all versions of a volume share one VLDB entry, each volume on an
258 AFS server partition has its own <I>volume header</I>, a data structure
259 that maps the files and directories in the volume to physical memory addresses
260 on the partition that stores them. The volume header binds the
261 volume's contents into a logical unit without requiring that they be
262 stored in contiguous memory blocks. The volume header also records the
263 following information about the volume, some of it redundant with the VLDB
264 entry: name, volume ID number, type, size, status (online, offline, or
265 busy), space quota, timestamps for creation date and date of last
266 modification, and number of accesses during the current day.
267 <P>To display the volume headers on one or more partitions, use the <B>vos
268 listvol</B> command as described in <A HREF="#HDRWQ305">To display volume headers</A>. To display the VLDB entry for a single volume along
269 with its volume header, use the <B>vos examine</B> command as described in
270 <A HREF="#HDRWQ307">To display one volume's VLDB entry and volume header</A>.
271 <P><H3><A NAME="HDRWQ267" HREF="auagd002.htm#ToC_208">Keeping the VLDB and Volume Headers Synchronized</A></H3>
272 <A NAME="IDX6446"></A>
273 <A NAME="IDX6447"></A>
274 <A NAME="IDX6448"></A>
275 <A NAME="IDX6449"></A>
276 <A NAME="IDX6450"></A>
277 <A NAME="IDX6451"></A>
278 <P>It is vital that the information in the VLDB correspond to the status of
279 the actual volumes on the servers (as recorded in volume headers) as much of
280 the time as possible. If a volume's location information in the
281 VLDB is incorrect, the Cache Manager cannot find access its contents.
282 Whenever you issue a <B>vos</B> command that changes a volume's
283 status, the Volume Server and VL Server cooperate to keep the volume header
284 and VLDB synchronized. In rare cases, the header and VLDB can diverge,
285 for instance because a <B>vos</B> operation halts prematurely. For
286 instructions on resynchronizing them, see <A HREF="#HDRWQ312">Synchronizing the VLDB and Volume Headers</A>.
287 <P><H3><A NAME="HDRWQ268" HREF="auagd002.htm#ToC_209">About Mounting Volumes</A></H3>
288 <A NAME="IDX6452"></A>
289 <A NAME="IDX6453"></A>
290 <A NAME="IDX6454"></A>
291 <P>To make a volume's contents visible in the cell's file tree and
292 accessible to users, you mount the volume at a directory location in the AFS
293 filespace. The association between the volume and its location in the
294 filespace is called a <I>mount point</I>. An AFS mount point looks
295 and functions like a regular UNIX file system directory, but structurally it
296 is more like a symbolic link that tells the Cache Manager the name of the
297 volume associated with the directory. A mount point looks and acts like
298 a directory only because the Cache Manager knows how to interpret it.
299 <P>Consider the common case where the Cache Manager needs to retrieve a file
300 requested by an application program. The Cache Manager traverses the
301 file's complete pathname, starting at the AFS root (by convention mounted
302 at the <B>/afs</B> directory) and continuing to the file. When the
303 Cache Manager encounters (or <I>crosses</I>) a mount point during the
304 traversal, it reads it to learn the name of the volume mounted at that
305 directory location. After obtaining location information about the
306 volume from the Volume Location (VL) Server, the Cache Manager fetches the
307 indicated volume and opens its root directory. The <I>root
308 directory</I> of a volume lists all the files, subdirectories, and mount
309 points that reside in it. The Cache Manager scans the root directory
310 listing for the next element in the pathname. It continues down the
311 path, using this method to interpret any other mount points it encounters,
312 until it reaches the volume that houses the requested file.
313 <A NAME="IDX6455"></A>
314 <A NAME="IDX6456"></A>
315 <P>Mount points act as the glue that connects the AFS file space, creating the
316 illusion of a single, seamless file tree even when volumes reside on many
317 different file server machines. A volume's contents are visible
318 and accessible when the volume is mounted at a directory location, and are not
319 accessible at all if the volume is not mounted.
320 <P>You can mount a volume at more than one location in the file tree, but this
321 is not recommended for two reasons. First, it distorts the hierarchical
322 nature of the filespace. Second, the Cache Manager can become confused
323 about which pathname it followed to reach the file (causing unpredictable
324 output from the <B>pwd</B> command, for example). However, if you
325 mount a volume at more than one directory, the access control list (ACL)
326 associated with the volume's root directory applies to all of the mount
328 <A NAME="IDX6457"></A>
329 <A NAME="IDX6458"></A>
330 <P>There are several types of mount points, each of which the Cache Manager
331 handles in a different way and each of which is appropriate for a different
332 purpose. See <A HREF="#HDRWQ293">Mounting Volumes</A>.
333 <P><H3><A NAME="HDRWQ269" HREF="auagd002.htm#ToC_210">About Volume Names</A></H3>
334 <A NAME="IDX6459"></A>
335 <A NAME="IDX6460"></A>
336 <P>A read/write volume's name can be up to 22 characters in
337 length. The Volume Server automatically adds the
338 <B>.readonly</B> and <B>.backup</B> extensions to
339 read-only and backup volumes respectively. Do not explicitly add the
340 extensions to volume names, even if they are appropriate.
341 <P>It is conventional for a volume's name to indicate the type of data it
342 houses. For example, it is conventional to name all user volumes
343 <B>user</B>.<VAR>username</VAR> where <VAR>username</VAR> is the
344 user's login name. Similarly, many cells elect to put system
345 binaries in volumes with names that begin with the system type code.
346 For a list of other naming conventions, see <A HREF="auagd007.htm#HDRWQ44">Creating Volumes to Simplify Administration</A>.
347 <A NAME="IDX6461"></A>
348 <A NAME="IDX6462"></A>
349 <HR><H2><A NAME="HDRWQ270" HREF="auagd002.htm#ToC_211">Creating Read/write Volumes</A></H2>
350 <A NAME="IDX6463"></A>
351 <A NAME="IDX6464"></A>
352 <A NAME="IDX6465"></A>
353 <P>A read/write volume is the most basic type of volume, and must exist before
354 you can create read-only or backup versions of it. When you issue the
355 <B>vos create</B> command to create a read/write volume, the VL Server
356 creates a VLDB entry for it which records the name you specify, assigns a
357 read/write volume ID number, and reserves the next two consecutive volume ID
358 numbers for read-only and backup versions that possibly are to be created
359 later. At the same time, the Volume Server creates a volume header at
360 the site you designate, allocating space on disk to record the name of the
361 volume's root directory. The name is filled in when you issue the
362 <B>fs mkmount</B> command to mount the volume, and matches the mount point
363 name. The following is also recorded in the volume header:
365 <P><LI>An initial ACL associated with the volume's root directory. By
366 default it grants all seven AFS access permissions to the
367 <B>system:administrators</B> group. After you mount the
368 volume, you can use the <B>fs setacl</B> command to add other entries and
369 to remove or change the entry for the <B>system:administrators</B>
370 group. See <A HREF="auagd020.htm#HDRWQ788">Setting ACL Entries</A>.
371 <A NAME="IDX6466"></A>
372 <A NAME="IDX6467"></A>
373 <P><LI>A space quota, which limits the amount of disk space the read/write
374 version of the volume can use on the file server partition. The default
375 is of 5000 kilobyte blocks, but you can use the <B>-maxquota</B> argument
376 to the <B>vos create</B> command to set a different quota.
377 <P>To change the quota after creation, use the <B>fs setquota</B> command
378 as described in <A HREF="#HDRWQ319">Setting and Displaying Volume Quota and Current Size</A>.
379 <A NAME="IDX6468"></A>
380 <A NAME="IDX6469"></A>
382 <P><H3><A NAME="Header_212" HREF="auagd002.htm#ToC_212">To create (and mount) a read/write volume</A></H3>
384 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
385 file. If necessary, issue the <B>bos listusers</B> command, which
386 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
387 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
389 <P><LI>Verify that you have the <B>a</B> (<B>administer</B>),
390 <B>i</B> (<B>insert</B>), and <B>l</B> (<B>lookup</B>)
391 permissions on the ACL of the directory where you plan to mount the
392 volume. If necessary, issue the <B>fs listacl</B> command, which is
393 fully described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
394 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
396 <P>Members of the <B>system:administrators</B> group always
397 implicitly have the <B>a</B> (<B>administer</B>) and by default also
398 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
399 <B>fs setacl</B> command to grant other rights as necessary.
400 <A NAME="IDX6470"></A>
401 <A NAME="IDX6471"></A>
402 <P><LI><A NAME="LIWQ271"></A>Select a site (disk partition on a file server machine) for the
403 new volume. To verify that the site has enough free space to house the
404 volume (now, or if it grows to use its entire quota), issue the <B>vos
405 partinfo</B> command.
406 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">The partition-related statistics in this command's output do not always
407 agree with the corresponding values in the output of the standard UNIX
408 <B>df</B> command. The statistics reported by this command can be
409 up to five minutes old, because the Cache Manager polls the File Server for
410 partition information at that frequency. Also, on some operating
411 systems, the <B>df</B> command's report of partition size includes
412 reserved space not included in this command's calculation, and so is
413 likely to be about 10% larger.
415 <PRE> % <B>vos partinfo</B> <<VAR>machine name</VAR>> [<<VAR>partition name</VAR>>]
421 </B><DD>Is the shortest acceptable abbreviation of <B>partinfo</B>.
422 <P><DT><B><VAR>machine name</VAR>
423 </B><DD>Specifies the file server machine for which to display partition size and
425 <P><DT><B><VAR>partition name</VAR>
426 </B><DD>Names one partition for which to display partition size and usage.
427 If you omit it, the output displays the size and space available for all
428 partitions on the machine.
430 <P><LI><A NAME="LIWQ272"></A>Select a volume name, taking note of the information in <A HREF="#HDRWQ269">About Volume Names</A>.
431 <A NAME="IDX6472"></A>
432 <A NAME="IDX6473"></A>
433 <P><LI><A NAME="LIWQ273"></A>Issue the <B>vos create</B> command to create the
436 % <B>vos create</B> <<VAR>machine name</VAR>> <<VAR>partition name</VAR>> <<VAR>volume name</VAR>> \
437 [<B>-maxquota</B> <<VAR>initial quota (KB)</VAR>>]
443 </B><DD>Is the shortest acceptable abbreviation of <B>create</B>.
444 <P><DT><B><VAR>machine name</VAR>
445 </B><DD>Specifies the file server machine on which to place the volume.
446 <P><DT><B><VAR>partition name</VAR>
447 </B><DD>Specifies the disk partition on which to place the volume.
448 <P><DT><B><VAR>volume name</VAR>
449 </B><DD>Names the volume. It can be up to 22 alphanumeric and punctuation
450 characters in length. Your cell possibly has naming conventions for
451 volumes, such as beginning user volume names with the string <B>user</B>
452 and using the period to separate parts of the name.
454 </B><DD>Sets the volume's quota, as a number of kilobyte blocks. If
455 you omit this argument, the quota is set to 5000 kilobyte blocks.
457 <A NAME="IDX6474"></A>
458 <A NAME="IDX6475"></A>
459 <A NAME="IDX6476"></A>
460 <A NAME="IDX6477"></A>
461 <P><LI><A NAME="LIWQ274"></A><B>(Optional)</B> Issue the <B>fs mkmount</B> command
462 to mount the volume in the filespace. For complete syntax, see <A HREF="#HDRWQ297">To create a regular or read/write mount point</A>.
464 % <B>fs mkmount</B> <<VAR>directory</VAR>> <<VAR>volume name</VAR>>
467 <P><LI><B>(Optional)</B> Issue the <B>fs lsmount</B> command to verify
468 that the mount point refers to the correct volume. Complete
469 instructions appear in <A HREF="#HDRWQ296">To display a mount point</A>.
471 % <B>fs lsmount</B> <<VAR>directory</VAR>>
474 <P><LI><B>(Optional)</B> Issue the <B>fs setvol</B> command with the
475 <B>-offlinemsg</B> argument to record auxiliary information about the
476 volume in its volume header. For example, you can record who owns the
477 volume or where you have mounted it in the filespace. To display the
478 information, use the <B>fs examine</B> command.
479 <PRE> % <B>fs setvol</B> <<VAR>dir/file path</VAR>> <B>-offlinemsg</B> <<VAR>offline message</VAR>>
484 </B><DD>Is an acceptable alias for <B>setvol</B> (and <B>setv</B> the
485 shortest acceptable abbreviation).
486 <P><DT><B><VAR>dir/file path</VAR>
487 </B><DD>Names the mount point of the volume with which to associate the
488 message. Partial pathnames are interpreted relative to the current
490 <P>Specify the read/write path to the mount point, to avoid the failure that
491 results when you attempt to change a read-only volume. By convention,
492 you indicate the read/write path by placing a period before the cell name at
493 the pathname's second level (for example,
494 <B>/afs/.abc.com</B>). For further discussion of the
495 concept of read/write and read-only paths through the filespace, see <A HREF="#HDRWQ294">The Rules of Mount Point Traversal</A>.
496 <P><DT><B>-offlinemsg
497 </B><DD>Specifies up to 128 characters of auxiliary information to record in the
501 <HR><H2><A NAME="HDRWQ275" HREF="auagd002.htm#ToC_213">About Clones and Cloning</A></H2>
502 <A NAME="IDX6478"></A>
503 <A NAME="IDX6479"></A>
504 <A NAME="IDX6480"></A>
505 <A NAME="IDX6481"></A>
506 <P>To create a backup or read-only volume, the Volume Server begins by
507 <I>cloning</I> the read/write source volume to create a
508 <I>clone</I>. The Volume Server creates the clone automatically
509 when you issue the <B>vos backup</B> or <B>vos backupsys</B> command
510 (for a backup volume) or the <B>vos release</B> command (for a read-only
511 volume). No special action is required on your part.
512 <P>A clone is not a copy of the data in the read/write source volume, but
513 rather a copy of the read/write volume's <I>vnode index</I>.
514 The vnode index is a table of pointers between the files and directories in
515 the volume and the physical disk blocks on the partition where the data
516 resides. From the clone, backup and read-only volumes are created in
517 the following manner:
519 <P><LI>A read-only volume that occupies the same partition as its read/write
520 source (also known as a <I>read-only clone</I>), and a backup volume, are
521 created by attaching a volume header to the clone. These volumes
522 initially consume very little disk space, because the clone portion (the vnode
523 index) points to exactly the same files as the read/write volume, as
524 illustrated in <A HREF="#FIGWQ276">Figure 1</A>. The file sharing is possible only because the clone
525 is on the same partition as the read/write source volume. When a file
526 in the read/write volume is deleted, it is not actually removed from the
527 partition, because the backup or read-only clone still points to it.
528 Similarly, when a file in the read/write is changed, the entire original file
529 is preserved on disk because the clone still points to it, and the read/write
530 volume's vnode index changes to point to newly space for the changed
531 file. When this happens, the backup or read-only volume is said to grow
532 or start occupying actual disk space.
533 <P><LI>A read-only volume that does not occupy the same site as the read/write
534 source is a copy of the clone and of all of the data in the read/write source
535 volume. It occupies the same amount of disk space as the read/write
536 volume did at the time the read-only volume was created.
538 <P><B><A NAME="FIGWQ276" HREF="auagd003.htm#FT_FIGWQ276">Figure 1. File Sharing Between the Read/write Source and a Clone Volume</A></B><BR>
539 <TABLE BORDER ><TR><TD><BR>
540 <B><BR><IMG SRC="vnode.gif" ALT="File Sharing Between the Read/write Source and a Clone Volume"><BR></B><BR>
542 <A NAME="IDX6482"></A>
543 <A NAME="IDX6483"></A>
544 <A NAME="IDX6484"></A>
545 <A NAME="IDX6485"></A>
546 <A NAME="IDX6486"></A>
547 <A NAME="IDX6487"></A>
548 <A NAME="IDX6488"></A>
549 <HR><H2><A NAME="HDRWQ277" HREF="auagd002.htm#ToC_214">Replicating Volumes (Creating Read-only Volumes)</A></H2>
550 <P><I>Replication</I> refers to creating a read-only copy
551 of a read/write volume and distributing the copy to one or more additional
552 file server machines. Replication makes a volume's contents
553 accessible on more than one file server machine, which increases data
554 availability. It can also increase system efficiency by reducing load
555 on the network and File Server. Network load is reduced if a client
556 machine's server preference ranks lead the Cache Manager to access the
557 copy of a volume stored on the closest file server machine. Load on the
558 File Server is reduced because it issues only one callback for all data
559 fetched from a read-only volume, as opposed to a callback for each file
560 fetched from a read/write volume. The single callback is sufficient for
561 an entire read-only volume because the volume does not change except in
562 response to administrator action, whereas each read/write file can change at
564 <A NAME="IDX6489"></A>
565 <A NAME="IDX6490"></A>
566 <A NAME="IDX6491"></A>
567 <A NAME="IDX6492"></A>
568 <A NAME="IDX6493"></A>
569 <P>Replicating a volume requires issuing two commands. First, use the
570 <B>vos addsite</B> command to add one or more read-only site definitions
571 to the volume's VLDB entry (a <I>site</I> is a particular partition
572 on a file server machine). Then use the <B>vos release</B> command
573 to clone the read/write source volume and distribute the clone to the defined
574 read-only sites. You issue the <B>vos addsite</B> only once for
575 each read-only site, but must reissue the <B>vos release</B> command every
576 time the read/write volume's contents change and you want to update the
578 <P>For users to have a consistent view of the file system, the release of
579 updated volume contents to read-only sites must be atomic: either all
580 read-only sites receive the new version of the volume, or all sites keep the
581 version they currently have. The <B>vos release</B> command is
582 designed to ensure that all copies of the volume's read-only version
583 match both the read/write source and each other. In cases where
584 problems such as machine or server process outages prevent successful
585 completion of the release operation, AFS uses two mechanisms to alert
587 <A NAME="IDX6494"></A>
588 <A NAME="IDX6495"></A>
589 <A NAME="IDX6496"></A>
590 <A NAME="IDX6497"></A>
591 <A NAME="IDX6498"></A>
592 <A NAME="IDX6499"></A>
593 <A NAME="IDX6500"></A>
594 <A NAME="IDX6501"></A>
595 <A NAME="IDX6502"></A>
596 <A NAME="IDX6503"></A>
597 <A NAME="IDX6504"></A>
598 <A NAME="IDX6505"></A>
599 <A NAME="IDX6506"></A>
600 <A NAME="IDX6507"></A>
601 <P>First, the command interpreter generates an error message on the standard
602 error stream naming each read-only site that did not receive the new volume
603 version. Second, during the release operation the Volume Location (VL)
604 Server marks site definitions in the VLDB entry with flags (<TT>New
605 release</TT> and <TT>Old release</TT>) that indicate whether or not the
606 site has the new volume version. If any flags remain after the
607 operation completes, it was not successful. The Cache Manager refuses
608 to access a read-only site marked with the <TT>Old release</TT> flag, which
609 potentially imposes a greater load on the sites marked with the <TT>New
610 release</TT> flag. It is important to investigate and eliminate the
611 cause of the failure and then to issue the <B>vos release</B> command as
612 many times as necessary to complete the release without errors.
613 <P>The pattern of site flags remaining in the volume's VLDB entry after a
614 failed release operation can help determine the point at which the operation
615 failed. Use the <B>vos examine</B> or <B>vos listvldb</B>
616 command to display the VLDB entry. The VL Server sets the flags in
617 concert with the Volume Server's operations, as follows:
619 <P><LI>Before the operation begins, the VL Server sets the <TT>New release</TT>
620 flag on the read/write site definition in the VLDB entry and the <TT>Old
621 release</TT> flag on read-only site definitions (unless the read-only site
622 has been defined since the last release operation and has no actual volume, in
623 which case its site flag remains <TT>Not released</TT>).
624 <P><LI>If necessary, the Volume Server creates a temporary copy (a
625 <I>clone</I>) of the read/write source called the ReleaseClone (see the
626 following discussion of when the Volume Server does or does not create a new
627 ReleaseClone.) It assigns the ReleaseClone its own volume ID number,
628 which the VL Server records in the <TT>RClone</TT> field of the source
629 volume's VLDB entry.
630 <P><LI>The Volume Server distributes a copy of the ReleaseClone to each read-only
631 site defined in the VLDB entry. As the site successfully receives the
632 new clone, the VL Server sets the site's flag in the VLDB entry to
633 <TT>New release</TT>.
634 <P><LI>When all the read-only copies are successfully released, the VL Server
635 clears all the <TT>New release</TT> site flags. The ReleaseClone is
636 no longer needed, so the Volume Server deletes it and the VL Server erases its
637 ID from the VLDB entry.
639 <P>By default, the Volume Server determines automatically whether or not it
640 needs to create a new ReleaseClone:
642 <P><LI>If there are no flags (<TT>New release</TT>, <TT>Old release</TT>, or
643 <TT>Not released</TT>) on site definitions in the VLDB entry, the previous
644 <B>vos release</B> command completed successfully and all read-only sites
645 currently have the same volume. The Volume Server infers that the
646 current <B>vos release</B> command was issued because the read/write
647 volume has changed. The Volume Server creates a new ReleaseClone and
648 distributes it to all of the read-only sites.
649 <P><LI>If any site definition in the VLDB entry is marked with a flag, either the
650 previous release operation did not complete successfully or a new read-only
651 site was defined since the last release. The Volume Server does not
652 create a new ReleaseClone, instead distributing the existing ReleaseClone to
653 sites marked with the <TT>Old release</TT> or <TT>Not released</TT>
654 flag. As previously noted, the VL Server marks each VLDB site
655 definition with the <TT>New release</TT> flag as the site receives the
656 ReleaseClone, and clears all flags after all sites successfully receive
659 <P>To override the default behavior, forcing the Volume Server to create and
660 release a new ReleaseClone to the read-only sites, include the <B>-f</B>
661 flag. This is appropriate if, for example, the data at the read/write
662 site has changed since the existing ReleaseClone was created during the
663 previous release operation.
664 <P><H3><A NAME="HDRWQ278" HREF="auagd002.htm#ToC_215">Using Read-only Volumes Effectively</A></H3>
665 <A NAME="IDX6508"></A>
666 <A NAME="IDX6509"></A>
667 <A NAME="IDX6510"></A>
668 <A NAME="IDX6511"></A>
669 <P>For maximum effectiveness, replicate only volumes that satisfy two
672 <P><LI>The volume's contents are heavily used. Examples include a
673 volume housing binary files for text editors or other popular application
674 programs, and volumes mounted along heavily traversed directory paths such as
675 the paths leading to user home directories. It is an inefficient use of
676 disk space to replicate volumes for which the demand is low enough that a
677 single File Server can easily service all requests.
678 <P><LI>The volume's contents change infrequently. As noted, file
679 system consistency demands that the contents of read-only volumes must match
680 each other and their read/write source at all times. Each time the
681 read/write volume changes, you must issue the <B>vos release</B> command
682 to update the read-only volumes. This can become tedious (and easy to
683 forget) if the read/write volume changes frequently.
685 <A NAME="IDX6512"></A>
686 <A NAME="IDX6513"></A>
687 <P>Explicitly mounting a read-only volume (creating a mount point that names a
688 volume with a <B>.readonly</B> extension) is not generally
689 necessary or appropriate. The Cache Manager has a built-in bias to
690 access the read-only version of a replicated volume whenever possible.
691 As described in more detail in <A HREF="#HDRWQ294">The Rules of Mount Point Traversal</A>, when the Cache Manager encounters a mount point it reads
692 the volume name inside it and contacts the VL Server for a list of the sites
693 that house the volume. In the normal case, if the mount point resides
694 in a read-only volume and names a read/write volume (one that does not have a
695 <B>.readonly</B> or <B>.backup</B> extension), the Cache
696 Manager always attempts to access a read-only copy of the volume. Thus
697 there is normally no reason to force the Cache Manager to access a read-only
698 volume by mounting it explicitly.
699 <P>It is a good practice to place a read-only volume at the read/write site,
700 for a couple of reasons. First, the read-only volume at the read/write
701 site requires only a small amount of disk space, because it is a clone rather
702 a copy of all of the data (see <A HREF="#HDRWQ275">About Clones and Cloning</A>). Only if a large number of files are removed or
703 changed in the read/write volume does the read-only copy occupy much disk
704 space. That normally does not happen because the appropriate response
705 to changes in a replicated read/write volume is to reclone it. The
706 other reason to place a read-only volume at the read/write site is that the
707 Cache Manager does not attempt to access the read/write version of a
708 replicated volume if all read-only copies become inaccessible. If the
709 file server machine housing the read/write volume is the only accessible
710 machine, the Cache Manager can access the data only if there is a read-only
711 copy at the read/write site.
712 <P>The number of read-only sites to define depends on several factors.
713 Perhaps the main trade-off is between the level of demand for the
714 volume's contents and how much disk space you are willing to use for
715 multiple copies of the volume. Of course, each prospective read-only
716 site must have enough available space to accommodate the volume. The
717 limit on the number of read-only copies of a volume is determined by the
718 maximum number of site definitions in a volume's VLDB entry, which is
719 defined in the <I>AFS Release Notes</I>. The site housing the
720 read/write and backup versions of the volume counts as one site, and each
721 read-only site counts as an additional site (even the read-only site defined
722 on the same file server machine and partition as the read/write site counts as
723 a separate site). Note also that the Volume Server permits only one
724 read-only copy of a volume per file server machine.
725 <P><H3><A NAME="Header_216" HREF="auagd002.htm#ToC_216">Replication Scenarios</A></H3>
726 <A NAME="IDX6514"></A>
727 <A NAME="IDX6515"></A>
728 <A NAME="IDX6516"></A>
729 <P>The instructions in the following section explain how to replicate a volume
730 for which no read-only sites are currently defined. However, you can
731 also use the instructions in other common situations:
733 <P><LI>If you are releasing a new clone to sites that already exist, you can skip
734 Step <A HREF="#LIWQ281">2</A>. It can still be useful to issue the <B>vos
735 examine</B> command, however, to verify that the desired read-only sites are
737 <P><LI>If you are adding new read-only sites to existing ones, perform all of the
738 steps. In Step <A HREF="#LIWQ282">3</A>, issue the <B>vos addsite</B> command for the new sites
740 <P><LI>If you are defining sites but do not want to release a clone to them yet,
741 stop after Step <A HREF="#LIWQ282">3</A> and continue when you are ready.
742 <P><LI>If you are removing one or more sites before releasing a new clone to the
743 remaining sites, follow the instructions for site removal in <A HREF="#HDRWQ320">Removing Volumes and their Mount Points</A> and then start with Step <A HREF="#LIWQ283">4</A>.
745 <P><H3><A NAME="HDRWQ279" HREF="auagd002.htm#ToC_217">To replicate a read/write volume (create a read-only volume)</A></H3>
746 <A NAME="IDX6517"></A>
747 <A NAME="IDX6518"></A>
749 <P><LI><A NAME="LIWQ280"></A>Verify that you are listed in the
750 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
751 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
752 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
754 <P><LI><A NAME="LIWQ281"></A>Select one or more sites at which to replicate the
755 volume. There are several factors to consider:
757 <P><LI>How many sites are already defined. As previously noted, it is
758 usually appropriate to define a read-only site at the read/write site.
759 Also, the Volume Server permits only one read-only copy of a volume per file
760 server machine. To display the volume's current sites, issue the
761 <B>vos examine</B> command, which is described fully in <A HREF="#HDRWQ306">Displaying One Volume's VLDB Entry and Volume Header</A>.
763 % <B>vos examine</B> <<VAR>volume name or ID</VAR>>
766 <P>The final lines of output display the volume's site definitions from
768 <P><LI>Whether your cell dedicates any file server machines to housing read-only
769 volumes only. In general, only very large cells use read-only server
771 <P><LI>Whether a site has enough free space to accommodate the volume. A
772 read-only volume requires the same amount of space as the read/write version
773 (unless it is at the read/write site itself). The first line of output
774 from the <B>vos examine</B> command displays the read/write volume's
775 current size in kilobyte blocks, as shown in <A HREF="#HDRWQ306">Displaying One Volume's VLDB Entry and Volume Header</A>.
776 <P>To display the amount of space available on a file server machine's
777 partitions, use the <B>vos partinfo</B> command, which is described fully
778 in <A HREF="#HDRWQ270">Creating Read/write Volumes</A>.
780 % <B>vos partinfo</B> <<VAR>machine name</VAR>> [<<VAR>partition name</VAR>>]
784 <A NAME="IDX6519"></A>
785 <A NAME="IDX6520"></A>
786 <A NAME="IDX6521"></A>
787 <A NAME="IDX6522"></A>
788 <A NAME="IDX6523"></A>
789 <A NAME="IDX6524"></A>
790 <P><LI><A NAME="LIWQ282"></A>Issue the <B>vos addsite</B> command to define each new
791 read-only site in the VLDB.
793 % <B>vos addsite</B> <<VAR>machine name</VAR>> <<VAR>partition name</VAR>> <<VAR>volume name or ID</VAR>>
799 </B><DD>Is the shortest acceptable abbreviation of <B>addsite</B>.
800 <P><DT><B><VAR>machine name</VAR>
801 </B><DD>Defines the file server machine for the new site.
802 <P><DT><B><VAR>partition name</VAR>
803 </B><DD>Names a disk partition on the machine <VAR>machine name</VAR>.
804 <P><DT><B><VAR>volume name or ID</VAR>
805 </B><DD>Identifies the read/write volume to be replicated, either by its complete
806 name or its volume ID number.
808 <P><LI><A NAME="LIWQ283"></A><B>(Optional)</B> Verify that the <B>fs</B> process
809 (which incorporates the Volume Server) is functioning normally on each file
810 server machine where you have defined a read-only site, and that the
811 <B>vlserver</B> process (the Volume Location Server) is functioning
812 correctly on each database server machine. Knowing that they are
813 functioning eliminates two possible sources of failure for the release.
814 Issue the <B>bos status</B> command on each file server machine housing a
815 read-only site for this volume and on each database server machine. The
816 command is described fully in <A HREF="auagd009.htm#HDRWQ204">Displaying Process Status and Information from the BosConfig File</A>.
818 % <B>bos status</B> <<VAR>machine name</VAR>> <B>fs vlserver</B>
821 <A NAME="IDX6525"></A>
822 <A NAME="IDX6526"></A>
823 <A NAME="IDX6527"></A>
824 <A NAME="IDX6528"></A>
825 <P><LI><A NAME="LIWQ284"></A>Issue the <B>vos release</B> command to clone the
826 read/write source volume and distribute the clone to each read-only
829 % <B>vos release</B> <<VAR>volume name or ID</VAR>> [<B>-f</B>]
835 </B><DD>Is the shortest acceptable abbreviation of <B>release</B>.
836 <P><DT><B><VAR>volume name or ID</VAR>
837 </B><DD>Identifies the read/write volume to clone, either by its complete name or
838 volume ID number. The read-only version is given the same name with a
839 <B>.readonly</B> extension. All read-only copies share the
840 same read-only volume ID number.
842 </B><DD>Creates and releases a brand new clone.
844 <P><LI><A NAME="LIWQ285"></A><B>(Optional)</B> Issue the <B>vos examine</B> command
845 to verify that no site definition in the VLDB entry is marked with an <TT>Old
846 release</TT> or <TT>New release</TT> flag. The command is described
847 fully in <A HREF="#HDRWQ306">Displaying One Volume's VLDB Entry and Volume Header</A>.
849 % <B>vos examine</B> <<VAR>volume name or ID</VAR>>
853 <P>If any flags appear in the output from Step <A HREF="#LIWQ285">6</A>, repeat Steps <A HREF="#LIWQ283">4</A> and <A HREF="#LIWQ284">5</A> until the Volume Server
854 does not produce any error messages during the release operation and the flags
855 no longer appear. Do not issue the <B>vos release</B> command when
856 you know that the read/write site or any read-only site is inaccessible due to
857 network, machine or server process outage.
858 <HR><H2><A NAME="HDRWQ286" HREF="auagd002.htm#ToC_218">Creating Backup Volumes</A></H2>
859 <A NAME="IDX6529"></A>
860 <A NAME="IDX6530"></A>
861 <A NAME="IDX6531"></A>
862 <A NAME="IDX6532"></A>
863 <A NAME="IDX6533"></A>
864 <P>A <I>backup volume</I> is a clone that resides at the same site as its
865 read/write source (to review the concept of cloning, see <A HREF="#HDRWQ275">About Clones and Cloning</A>). Creating a backup version of a volume has two
868 <P><LI>It is by convention the first step when dumping a volume's contents
869 to tape with the AFS Backup System. A volume is inaccessible while it
870 is being dumped, so instead of dumping the read/write volume, you create and
871 dump a backup version. Users do not normally access the backup version,
872 so it is unlikely that the dump will disturb them. For more details,
873 see <A HREF="auagd012.htm#HDRWQ411">Backing Up Data</A>.
874 <P><LI>It enables users to restore mistakenly deleted or changed data themselves,
875 freeing you for more crucial tasks. The backup version captures the
876 state of its read/write source at the time the backup is made, and its
877 contents cannot change. Mount the backup version in the filespace so
878 that users can restore a file to its state at the time you made the
879 backup. See <A HREF="#HDRWQ289">Making the Contents of Backup Volumes Available to Users</A>.
881 <A NAME="IDX6534"></A>
882 <A NAME="IDX6535"></A>
883 <A NAME="IDX6536"></A>
884 <P><H3><A NAME="HDRWQ287" HREF="auagd002.htm#ToC_219">Backing Up Multiple Volumes at Once</A></H3>
885 <P>The <B>vos backupsys</B> command creates a backup
886 version of many read/write volumes at once. This command is useful when
887 preparing for large-scale backups to tape using the AFS Backup System.
888 <P>To clone every read/write volume listed in the VLDB, omit all of the
889 command's options. Otherwise, combine the command's options
890 to clone various groups of volumes. The options use one of two basic
891 criteria to select volumes: location (the <B>-server</B> and
892 <B>-partition</B> arguments) or presence in the volume name of one of a
893 set of specified character strings (the <B>-prefix</B>,
894 <B>-exclude</B>, and <B>-xprefix</B> options).
895 <P>To clone only volumes that reside on one file server machine, include the
896 <B>-server</B> argument. To clone only volumes that reside on one
897 partition, combine the <B>-server</B> and <B>-partition</B>
898 arguments. The <B>-partition</B> argument can also be used alone to
899 clone volumes that reside on the indicated partition on every file server
900 machine. These arguments can be combined with those that select volumes
901 based on their names.
902 <P>Combine the <B>-prefix</B>, <B>-exclude</B>, and
903 <B>-xprefix</B> options (with or without the <B>-server</B> and
904 <B>-partition</B> arguments) in the indicated ways to select volumes based
905 on character strings contained in their names:
907 <P><LI>To clone every read/write volume at the specified location whose name
908 includes one of a set of specified character strings (for example, begins with
909 <B>user.</B> or includes the string <B>afs</B>), use the
910 <B>-prefix</B> argument or combine the <B>-xprefix</B> and
911 <B>-exclude</B> options.
912 <P><LI>To clone every read/write volume at the specified location except those
913 whose name includes one of a set of specified character strings, use the
914 <B>-xprefix</B> argument or combine the <B>-prefix</B> and
915 <B>-exclude</B> options.
916 <P><LI>To clone every read/write volume at the specified location whose name
917 includes one of one of a set of specified character strings, except those
918 whose names include one of a different set of specified character strings,
919 combine the <B>-prefix</B> and <B>-xprefix</B> arguments. The
920 command creates a list of all volumes that match the <B>-prefix</B>
921 argument and then removes from the list the volumes that match the
922 <B>-xprefix</B> argument. For effective results, the strings
923 specified by the <B>-xprefix</B> argument must designate a subset of the
924 volumes specified by the <B>-prefix</B> argument.
925 <P>If the <B>-exclude</B> flag is combined with the <B>-prefix</B> and
926 <B>-xprefix</B> arguments, the command creates a list of all volumes that
927 do not match the <B>-prefix</B> argument and then adds to the list any
928 volumes that match the <B>-xprefix</B> argument. As when the
929 <B>-exclude</B> flag is not used, the result is effective only if the
930 strings specified by the <B>-xprefix</B> argument designate a subset of
931 the volumes specified by the <B>-prefix</B> argument.
933 <P>The <B>-prefix</B> and <B>-xprefix</B> arguments both accept
934 multiple values, which can be used to define disjoint groups of
935 volumes. Each value can be one of two types:
937 <P><LI>A simple character string, which matches volumes whose name begin with the
938 string. All characters are interpreted literally (that is, characters
939 that potentially have special meaning to the command shell, such as the
940 period, have only their literal meaning).
941 <P><LI>A regular expression, which matches volumes whose names contain the
942 expressions. Place a caret ( <B>^</B> ) at the
943 beginning of the expression, and enclose the entire string in single quotes
944 (<B>'</B> <B>'</B>). Explaining regular
945 expressions is outside the scope of this reference page; see the UNIX
946 manual page for <B>regexp(5)</B> or (for a brief introduction) <A HREF="auagd011.htm#HDRWQ364">Defining and Displaying Volume Sets and Volume Entries</A>. As an example, the following expression matches
947 volumes that have the string <B>aix</B> anywhere in their names:
948 <PRE> <B>-prefix '^.*aix'</B>
951 <P>To display a list of the volumes to be cloned, without actually cloning
952 them, include the <B>-dryrun</B> flag. To display a statement that
953 summarizes the criteria being used to select volume, include the
954 <B>-verbose</B> flag.
955 <P>To back up a single volume, use the <B>vos backup</B> command, which
956 employs a more streamlined technique for finding a single volume.
957 <A NAME="IDX6537"></A>
958 <A NAME="IDX6538"></A>
959 <A NAME="IDX6539"></A>
960 <A NAME="IDX6540"></A>
961 <A NAME="IDX6541"></A>
962 <A NAME="IDX6542"></A>
963 <P><H3><A NAME="HDRWQ288" HREF="auagd002.htm#ToC_220">Automating Creation of Backup Volumes</A></H3>
964 <P>Most cells find that it is best to make a new backup version
965 of relevant volumes each day. It is best to create the backup versions
966 at a time when usage is low, because the backup operation causes the
967 read/write volume to be unavailable momentarily.
968 <P>You can either issue the necessary the <B>vos backupsys</B> or <B>vos
969 backup</B> commands at the console or create a <B>cron</B> entry in the
970 <B>BosConfig</B> file on a file server machine, which eliminates the need
971 for an administrator to initiate the backup operation.
972 <P>The following example command creates a <B>cron</B> process called
973 <B>backupusers</B> in the <B>/usr/afs/local/BosConfig</B> file on the
974 machine <B>fs3.abc.com</B>. The process runs every
975 day at 1:00 a.m. to create a backup version of every
976 volume in the cell whose name starts with the string <B>user</B>.
977 The <B>-localauth</B> flag enables the process to invoke the privileged
978 <B>vos backupsys</B> command while unauthenticated. Note that the
979 <B>-cmd</B> argument specifies a complete pathname for the <B>vos</B>
980 binary, because the PATH environment variable for the BOS Server (running as
981 the local superuser <B>root</B>) generally does not include the path to
984 % <B>bos create fs3.abc.com backupusers cron</B> \
985 <B>-cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" "1:00"</B>
988 <A NAME="IDX6543"></A>
989 <A NAME="IDX6544"></A>
990 <A NAME="IDX6545"></A>
991 <P><H3><A NAME="HDRWQ289" HREF="auagd002.htm#ToC_221">Making the Contents of Backup Volumes Available to Users</A></H3>
992 <P>As noted, a backup volume preserves the state of the
993 read/write source at the time the backup is created. Many cells choose
994 to mount backup volumes so that users can access and restore data they have
995 accidentally deleted or changed since the last backup was made, without having
996 to request help from administrators. The most sensible place to mount
997 the backup version of a user volume is at a subdirectory of the user's
998 home directory. Suitable names for this directory include
999 <B>OldFiles</B> and <B>Backup</B>. The subdirectory looks just
1000 like the user's own home directory as it was at the time the backup was
1001 created, with all files and subdirectories in the same relative
1003 <P>If you do create and mount backup volumes for your users, inform users of
1004 their existence. The <I>AFS User Guide</I> does not mention backup
1005 volumes because making them available to users is optional. Explain to
1006 users how often you make a new backup, so they know what they can
1007 recover. Remind them also that the data in their backup volume cannot
1008 change; however, they can use the standard UNIX <B>cp</B> command to
1009 copy it into their home volume and modify it there. Reassure users that
1010 the data in their backup volumes does not count against their read/write
1012 <P><H3><A NAME="HDRWQ290" HREF="auagd002.htm#ToC_222">To create and mount a backup volume</A></H3>
1014 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1015 file. If necessary, issue the <B>bos listusers</B> command, which
1016 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1017 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
1019 <P><LI>Verify that you have the <B>insert</B> (<B>i</B>) and
1020 <B>administer</B> (<B>a</B>) permissions on the ACL of the directory
1021 in which you wish to mount the volume. If necessary, issue the <B>fs
1022 listacl</B> command, which is fully described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
1023 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
1025 <P>Members of the <B>system:administrators</B> group always
1026 implicitly have the <B>a</B> (<B>administer</B>) and by default also
1027 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
1028 <B>fs setacl</B> command to grant other rights as necessary.
1029 <A NAME="IDX6546"></A>
1030 <A NAME="IDX6547"></A>
1031 <P><LI><A NAME="LIWQ291"></A>Issue the <B>vos backup</B> command to create a backup
1032 version of a read/write source volume. The message shown confirms the
1033 success of the backup operation.
1035 % <B>vos backup</B> <<VAR>volume name or ID</VAR>>
1036 Created backup volume for <VAR>volume name or ID</VAR>
1042 </B><DD>Must be typed in full.
1043 <P><DT><B><VAR>volume name or ID</VAR>
1044 </B><DD>Identifies the read/write volume to back up, either by its complete name
1045 or volume ID number. The backup volume has the same name with the
1046 addition of the <B>.backup</B> extension. It has its own
1049 <A NAME="IDX6548"></A>
1050 <A NAME="IDX6549"></A>
1051 <P><LI><A NAME="LIWQ292"></A><B>(Optional)</B> Issue the <B>fs mkmount</B> to mount
1052 the backup volume. While this step is optional, Cache Managers cannot
1053 access the volume's contents if it is not mounted.
1055 % <B>fs mkmount</B> <<VAR>directory</VAR>> <<VAR>volume name</VAR>><B>.backup</B>
1061 </B><DD>Is the shortest acceptable abbreviation of <B>mkmount</B>.
1062 <P><DT><B><VAR>directory</VAR>
1063 </B><DD>Names the mount point to create. Do not create a file or directory
1064 of the same name beforehand. Partial pathnames are interpreted relative
1065 to the current working directory. For the backup version of a user
1066 volume, the conventional location is the user's home directory.
1067 <P><DT><B><VAR>volume name</VAR><B>.backup</B>
1068 </B><DD>Is the full name of the backup volume.
1070 <P><LI><B>(Optional)</B> Issue the <B>fs lsmount</B> command to verify
1071 that the mount point refers to the correct volume. Complete
1072 instructions appear in <A HREF="#HDRWQ296">To display a mount point</A>.
1074 % <B>fs lsmount</B> <<VAR>directory</VAR>>
1078 <A NAME="IDX6550"></A>
1079 <A NAME="IDX6551"></A>
1080 <P><H3><A NAME="Header_223" HREF="auagd002.htm#ToC_223">To create multiple backup volumes at once</A></H3>
1082 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1083 file. If necessary, issue the <B>bos listusers</B> command, which
1084 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1085 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
1087 <P><LI>Issue the <B>vos backupsys</B> command to create a backup version of
1088 every read/write volume that shares the same prefix or site. The
1089 effects of combining the three arguments are described in <A HREF="#HDRWQ287">Backing Up Multiple Volumes at Once</A>.
1090 <PRE> % <B>vos backupsys</B> [<B>-prefix</B> <<VAR>common prefix on volume(s)</VAR>><SUP>+</SUP>] \
1091 [<B>-server</B> <<VAR>machine name</VAR>>] [<B>-partition</B> <<VAR>partition name</VAR>>] \
1092 [<B>-exclude</B>] [<B>-xprefix</B> <<VAR>negative prefix on volume(s)</VAR>><SUP>+</SUP>]
1093 [<B>-dryrun</B>] [<B>-verbose</B>]
1099 </B><DD>Is the shortest acceptable abbreviation of <B>backupsys</B>.
1101 </B><DD>Specifies one or more simple character strings or regular expressions of
1102 any length; a volume whose name includes the string is placed on the list
1103 of volumes to be cloned. Include field separators (such as periods) if
1104 appropriate. This argument can be combined with any combination of the
1105 <B>-server</B>, <B>-partition</B>, <B>-exclude</B>, and
1106 <B>-xprefix</B> options.
1108 </B><DD>Specifies the file server machine housing the volumes to backup.
1109 Can be combined with any combination of the <B>-prefix</B>,
1110 <B>-partition</B>, <B>-exclude</B>, and <B>-xprefix</B>
1112 <P><DT><B>-partition
1113 </B><DD>Specifies the partition housing the volumes you wish to backup. Can
1114 be combined with any combination of the <B>-prefix</B>,
1115 <B>-server</B>, <B>-exclude</B>, and <B>-xprefix</B>
1118 </B><DD>Indicates that all volumes except those indicated with the
1119 <B>-prefix</B> argument are to be backed up. The <B>-prefix</B>
1120 argument must be provided along with this one. Can also be combined
1121 with any combination of the <B>-prefix</B>, <B>-server</B>, and
1122 <B>-partition</B> arguments; or with both the <B>-prefix</B> and
1123 <B>-xprefix</B> arguments, but not with the <B>-xprefix</B> argument
1126 </B><DD>Specifies one or more simple character strings or regular expressions of
1127 any length; a volume whose name does not include the string is placed on
1128 the list of volumes to be cloned. Can be combined with any combination
1129 of the <B>-prefix</B>, <B>-server</B>, and <B>-partition</B>
1130 arguments; in addition, it can be combined with both the
1131 <B>-prefix</B> and <B>-exclude</B> options, but not with the
1132 <B>-exclude</B> flag alone.
1134 </B><DD>Displays on the standard output stream a list of the volumes to be cloned,
1135 without actually cloning them.
1137 </B><DD>Displays on the standard output stream a statement that summarizes the
1138 criteria being used to select volumes, if combined with the <B>-dryrun</B>
1139 flag; otherwise, traces the cloning operation for each volume.
1142 <HR><H2><A NAME="HDRWQ293" HREF="auagd002.htm#ToC_224">Mounting Volumes</A></H2>
1143 <A NAME="IDX6552"></A>
1144 <P>Mount points make the contents of AFS volumes visible and accessible in the
1145 AFS filespace, as described in <A HREF="#HDRWQ268">About Mounting Volumes</A>. This section discusses in more detail how the Cache
1146 Manager handles mount points as it traverses the filespace. It
1147 describes the three types of mount points, their purposes, and how to
1148 distinguish between them, and provides instructions for creating, removing,
1149 and examining mount points.
1150 <P><H3><A NAME="HDRWQ294" HREF="auagd002.htm#ToC_225">The Rules of Mount Point Traversal</A></H3>
1151 <P>The Cache Manager observes three basic rules as it traverses
1152 the AFS filespace and encounters mount points:
1154 <P><LI><B>Rule 1:</B> Access Backup and Read-only Volumes When
1156 <P>When the Cache Manager encounters a mount point that specifies a volume
1157 with either a <B>.readonly</B> or a <B>.backup</B>
1158 extension, it accesses that type of volume only. If a mount point does
1159 not have either a <B>.backup</B> or <B>.readonly</B>
1160 extension, the Cache Manager uses Rules 2 and 3.
1161 <P>For example, the Cache Manager never accesses the read/write version of a
1162 volume if the mount point names the backup version. If the specified
1163 version is inaccessible, the Cache Manager reports an error.
1164 <P><LI><B>Rule 2:</B> Follow the Read-only Path When Possible
1165 <P>If a mount point resides in a read-only volume and the volume that it
1166 references is replicated, the Cache Manager attempts to access a read-only
1167 copy of the volume; if the referenced volume is not replicated, the Cache
1168 Manager accesses the read/write copy. The Cache Manager is thus said to
1169 prefer a <I>read-only path</I> through the filespace, accessing read-only
1170 volumes when they are available.
1171 <P>The Cache Manager starts on the read-only path in the first place because
1172 it always accesses a read-only copy of the <B>root.afs</B> volume
1173 if it exists; the volume is mounted at the root of a cell's AFS
1174 filespace (named <B>/afs</B> by convention). That is, if the
1175 <B>root.afs</B> volume is replicated, the Cache Manager attempts to
1176 access a read-only copy of it rather than the read/write copy. This
1177 rule then keeps the Cache Manager on a read-only path as long as each
1178 successive volume is replicated. The implication is that both the
1179 <B>root.afs</B> and <B>root.cell</B> volumes must be
1180 replicated for the Cache Manager to access replicated volumes mounted below
1181 them in the AFS filespace. The volumes are conventionally mounted at
1182 the <B>/afs</B> and <B>/afs/</B><VAR>cellname</VAR> directories,
1184 <P><LI><B>Rule 3:</B> Once on a Read/write Path, Stay There
1185 <P>If a mount point resides in a read/write volume and the volume name does
1186 not have a <B>.readonly</B> or a <B>.backup</B>
1187 extension, the Cache Manager attempts to access only the a read/write version
1188 of the volume. The access attempt fails with an error if the read/write
1189 version is inaccessible, even if a read-only version is accessible. In
1190 this situation the Cache Manager is said to be on a <I>read/write path</I>
1191 and cannot switch back to the read-only path unless mount point explicitly
1192 names a volume with a <B>.readonly</B> extension. (Cellular
1193 mount points are an important exception to this rule, as explained in the
1194 following discussion.
1196 <P><H3><A NAME="HDRWQ295" HREF="auagd002.htm#ToC_226">The Three Types of Mount Points</A></H3>
1197 <P>AFS uses three types of mount points, each appropriate for a
1198 different purpose because of how the Cache Manager handles them.
1200 <P><LI>When the Cache Manager crosses a <I>regular</I> mount point, it obeys
1201 all three of the mount point traversal rules previously described.
1202 <A NAME="IDX6553"></A>
1203 <A NAME="IDX6554"></A>
1204 <P>AFS performs best when the vast majority of mount points in the filespace
1205 are regular, because the mount point traversal rules promote the most
1206 efficient use of both replicated and nonreplicated volumes. Because
1207 there are likely to be multiple read-only copies of a replicated volume, it
1208 makes sense for the Cache Manager to access one of them rather than the single
1209 read/write version, and the second rule leads it to do so. If a volume
1210 is not replicated, the third rule means that the Cache Manager still accesses
1211 the read/write volume when that is the only type available. In other
1212 words, a regular mount point does not force the Cache Manager always to access
1213 read-only volumes (it is explicitly not a "read-only mount point").
1214 <P>To create a regular mount point, use the <B>fs mkmount</B> command as
1215 described in <A HREF="#HDRWQ297">To create a regular or read/write mount point</A>.
1216 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">To enable the Cache Manager to access the read-only version of a replicated
1217 volume named by a regular mount point, all volumes that are mounted above it
1218 in the pathname must also be replicated. That is the only way the Cache
1219 Manager can stay on a read-only path to the target volume.
1221 <P><LI>When the Cache Manager crosses a <I>read/write</I> mount point, it
1222 attempts to access only the volume version named in the mount point. If
1223 the volume name is the base (read/write) form, without a
1224 <B>.readonly</B> or <B>.backup</B> extension, the Cache
1225 Manager accesses the read/write version of the volume, even if it is
1226 replicated. In other words, the Cache Manager disregards the second
1227 mount point traversal rule when crossing a read/write mount point: it
1228 switches to the read/write path through the filespace.
1229 <A NAME="IDX6555"></A>
1230 <A NAME="IDX6556"></A>
1231 <P>It is conventional to create only one read/write mount point in a
1232 cell's filespace, using it to mount the cell's
1233 <B>root.cell</B> volume just below the AFS filespace root (by
1234 convention, <B>/afs/.</B><VAR>cellname</VAR>). As indicated,
1235 it is conventional to place a period at the start of the read/write mount
1236 point's name (for example,
1237 <B>/afs/.abc.com</B>). The period distinguishes the
1238 read/write mount point from the regular mount point for the
1239 <B>root.cell</B> volume at the same level. This is the only
1240 case in which it is conventional to create two mount points for the same
1241 volume. A desirable side effect of this naming convention for this
1242 read/write mount point is that it does not appear in the output of the UNIX
1243 <B>ls</B> command unless the <B>-a</B> flag is included, essentially
1244 hiding it from regular users who have no use for it.
1245 <P>The existence of a single read/write mount point at this point in the
1246 filespace provides access to the read/write version of every volume when
1247 necessary, because it puts the Cache Manager on a read/write path right at the
1248 top of the filespace. At the same time, the regular mount point for the
1249 <B>root.cell</B> volume puts the Cache Manager on a read-only path
1251 <P>Using a read/write mount point for a read-only or backup volume is
1252 acceptable, but unnecessary. The first rule of mount point traversal
1253 already specifies that the Cache Manager accesses them if the volume name in a
1254 regular mount point has a <B>.readonly</B> or
1255 <B>.backup</B> extension.
1256 <P>To create a read/write mount point, use the <B>-rw</B> flag on the
1257 <B>fs mkmount</B> command as described in <A HREF="#HDRWQ297">To create a regular or read/write mount point</A>.
1258 <P><LI>When the Cache Manager crosses a <I>cellular</I> mount point, it
1259 accesses the indicated volume in the specified cell, which is normally a
1260 foreign cell. (If the mount point does not name a cell along with the
1261 volume, the Cache Manager accesses the volume in the cell where the mount
1262 point resides.) When crossing a regular cellular mount point, the Cache
1263 Manager disregards the third mount point traversal rule. Instead, it
1264 accesses a read-only version of the volume if it is replicated, even if the
1265 volume that houses the mount point is read/write.
1266 <P>It is inappropriate to circumvent this behavior by creating a read/write
1267 cellular mount point, because traversing the read/write path imposes an unfair
1268 load on the foreign cell's file server machines. The File Server
1269 must issue a callback for each file fetched from the read/write volume, rather
1270 than single callback required for a read-only volume. In any case, only
1271 a cell's own administrators generally need to access the read/write
1272 versions of replicated volumes.
1273 <A NAME="IDX6557"></A>
1274 <A NAME="IDX6558"></A>
1275 <A NAME="IDX6559"></A>
1276 <P>It is conventional to create cellular mount points only at the second level
1277 in a cell's filespace, using them to mount foreign cells'
1278 <B>root.cell</B> volumes just below the AFS filespace root (by
1279 convention, at <B>/afs/</B><VAR>foreign_cellname</VAR>). The mount
1280 point enables local users to access the foreign cell's filespace,
1281 assuming they have the necessary permissions on the ACL of the volume's
1282 root directory and that there is an entry for the foreign cell in each local
1283 client machine's <B>/usr/vice/etc/CellServDB</B> file, as described
1284 in <A HREF="auagd015.htm#HDRWQ552">Maintaining Knowledge of Database Server Machines</A>.
1285 <P>Creating cellular mount points at other levels in the filespace and
1286 mounting foreign volumes other than the <B>root.cell</B> volume is
1287 not generally appropriate. It can be confusing to users if the Cache
1288 Manager switches between cells at various points in a pathname.
1289 <P>To create a regular cellular mount point, use the <B>-cell</B> argument
1290 to specify the cell name, as described in <A HREF="#HDRWQ298">To create a cellular mount point</A>.
1292 <P>To examine a mount point, use the <B>fs lsmount</B> command as
1293 described in <A HREF="#HDRWQ296">To display a mount point</A>. The command's output uses distinct notation to
1294 identify regular, read/write, and cellular mount points. To remove a
1295 mount point, use the <B>fs rmmount</B> command as described in <A HREF="#HDRWQ300">To remove a mount point</A>.
1296 <P><H3><A NAME="Header_227" HREF="auagd002.htm#ToC_227">Creating a mount point in a foreign cell</A></H3>
1297 <P>Creating a mount point in a foreign cell's filespace (as opposed
1298 to mounting a foreign volume in the local cell) is basically the same as
1299 creating a mount point in the local filespace. The differences are that
1300 the <B>fs mkmount</B> command's <VAR>directory</VAR> argument specifies
1301 a pathname in the foreign cell rather than the local cell, and you must have
1302 the required permissions on the ACL of the foreign directory where you are
1303 creating the mount point. The <B>fs mkmount</B> command's
1304 <B>-cell</B> argument always specifies the cell in which the volume
1305 resides, not the cell in which to create the mount point.
1306 <P><H3><A NAME="HDRWQ296" HREF="auagd002.htm#ToC_228">To display a mount point</A></H3>
1307 <A NAME="IDX6560"></A>
1308 <A NAME="IDX6561"></A>
1309 <A NAME="IDX6562"></A>
1310 <A NAME="IDX6563"></A>
1311 <A NAME="IDX6564"></A>
1312 <A NAME="IDX6565"></A>
1314 <P><LI>Issue the <B>fs lsmount</B> command.
1316 % <B>fs lsmount</B> <<VAR>directory</VAR>>
1322 </B><DD>Is the shortest acceptable abbreviation of <B>lsmount</B>.
1323 <P><DT><B><VAR>directory</VAR>
1324 </B><DD>Names the mount point to display.
1327 <P>If the specified directory is a mount point, the output is of the following
1329 <PRE> '<VAR>directory</VAR>' is a mount point for volume '<VAR>volume name</VAR>'
1332 <P>For a regular mount point, a number sign (<TT>#</TT>) precedes the
1333 <VAR>volume name</VAR> string, as in the following example command issued on a
1334 client machine in the <B>abc.com</B> cell.
1336 % <B>fs lsmount /afs/abc.com/usr/terry</B>
1337 '/afs/abc.com/usr/terry' is a mount point for volume '#user.terry'
1340 <P>For a read/write mount point, a percent sign (<TT>%</TT>) precedes the
1341 <VAR>volume name</VAR> string, as in the following example command issued on a
1342 client machine in the <B>abc.com</B> cell. The cell's
1343 administrators have followed the convention of preceding the read/write mount
1344 point's name with a period.
1346 % <B>fs lsmount /afs/.abc.com </B>
1347 '/afs/.abc.com' is a mount point for volume '%root.cell'
1350 <P>For a cellular mount point, a cell name and colon (<TT>:</TT>)
1351 follow the number or percent sign and precede the <VAR>volume name</VAR> string,
1352 as in the following example command issued on a client machine in the
1353 <B>abc.com</B> cell.
1355 % <B>fs lsmount /afs/ghi.gov </B>
1356 '/afs/ghi.gov' is a mount point for volume '#ghi.gov:root.cell'
1359 <P>For a symbolic link to a mount point, the output is of the form shown in
1360 the following example command issued on a client machine in the
1361 <B>abc.com</B> cell.
1363 % <B>fs lsmount /afs/abc</B>
1364 '/afs/abc' is a symbolic link, leading to a mount point for volume '#root.cell'
1367 <P>If the directory is not a mount point or is not in AFS, the output reads as
1369 <PRE> '<VAR>directory</VAR>' is not a mount point.
1372 <P>If the output is garbled, it is possible that the mount point has become
1373 corrupted in the local cache. Use the <B>fs flushmount</B> command
1374 as described in <A HREF="auagd015.htm#HDRWQ559">To flush one or more mount points</A>. This forces the Cache Manager to refetch the mount
1376 <P><H3><A NAME="HDRWQ297" HREF="auagd002.htm#ToC_229">To create a regular or read/write mount point</A></H3>
1377 <A NAME="IDX6566"></A>
1378 <A NAME="IDX6567"></A>
1379 <A NAME="IDX6568"></A>
1380 <A NAME="IDX6569"></A>
1381 <A NAME="IDX6570"></A>
1382 <A NAME="IDX6571"></A>
1384 <P><LI>Verify that you have the <B>i</B> (<B>insert</B>) and <B>a</B>
1385 (<B>administer</B>) permissions on the ACL of the directory where you are
1386 placing the mount point. If necessary, issue the <B>fs listacl</B>
1387 command, which is fully described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
1388 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
1390 <P><LI>Issue the <B>fs mkmount</B> command to create the mount point.
1391 Include the <B>-rw</B> flag if creating a read/write mount point.
1393 % <B>fs mkmount</B> <<VAR>directory</VAR>> <<VAR>volume name</VAR>> [<B>-rw</B>]
1399 </B><DD>Is the shortest acceptable abbreviation for <B>mkmount</B>.
1400 <P><DT><B><VAR>directory</VAR>
1401 </B><DD>Names the mount point to create. A file or directory with the same
1402 name cannot already exist. A partial pathname is interpreted relative
1403 to the current working directory.
1404 <P>Specify the read/write path to the mount point, to avoid the failure that
1405 results when you attempt to create a new mount point in a read-only
1406 volume. By convention, you indicate the read/write path by placing a
1407 period before the cell name at the pathname's second level (for example,
1408 <B>/afs/.abc.com</B>). For further discussion of the
1409 concept of read/write and read-only paths through the filespace, see <A HREF="#HDRWQ294">The Rules of Mount Point Traversal</A>.
1410 <P><DT><B><VAR>volume name</VAR>
1411 </B><DD>Specifies the volume's full name, including the
1412 <B>.backup</B> or <B>.readonly</B> extension for a
1413 backup or read-only volume, if appropriate.
1415 </B><DD>Creates a read/write mount point.
1418 <P><H3><A NAME="HDRWQ298" HREF="auagd002.htm#ToC_230">To create a cellular mount point</A></H3>
1419 <A NAME="IDX6572"></A>
1420 <A NAME="IDX6573"></A>
1421 <A NAME="IDX6574"></A>
1423 <P><LI>Verify that you have the <B>i</B> (<B>insert</B>) and <B>a</B>
1424 (<B>administer</B>) permissions on the ACL of the directory where you are
1425 placing the mount point. If necessary, issue the <B>fs listacl</B>
1426 command, which is fully described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
1427 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
1429 <P><LI><A NAME="LIWQ299"></A>If you are mounting one or more foreign cells'
1430 <B>root.cell</B> volume at the second level in your filespace and
1431 your cell's <B>root.afs</B> volume is replicated, you must
1432 create a temporary mount point for the <B>root.afs</B>
1433 volume's read/write version in a directory on which the ACL grants you
1434 the <B>i</B> and <B>a</B> permissions. The following command
1435 creates a mount point called <B>new_cells</B> in your cell's
1436 <B>/afs/.</B><VAR>cellname</VAR> directory (the entry point to the
1437 read/write path in your cell).
1438 <P>Substitute your cell's name for <VAR>cellname</VAR>.
1440 % <B>cd /afs/.</B><VAR>cellname</VAR>
1442 % <B>fs mkmount new_cells root.afs</B>
1444 % <B>cd new_cells</B>
1447 <P><LI>Issue the <B>fs mkmount</B> command with the <B>-cell</B> argument
1448 to create a cellular mount point. Repeat the command for each cellular
1449 mount point as required.
1451 % <B>fs mkmount</B> <<VAR>directory</VAR>> <<VAR>volume name</VAR>> <B>-cell</B> <<VAR>cell name</VAR>>
1457 </B><DD>Is the shortest acceptable abbreviation for <B>mkmount</B>.
1458 <P><DT><B><VAR>directory</VAR>
1459 </B><DD>Names the mount point to create. A file or directory with the same
1460 name cannot already exist. A partial pathname is interpreted relative
1461 to the current working directory. If you are mounting a foreign
1462 cell's <B>root.cell</B> volume, the standard value for this
1463 argument is the cell's complete Internet domain name.
1464 <P><DT><B><VAR>volume name</VAR>
1465 </B><DD>Specifies the volume's full name, usually <B>root.cell</B>
1466 for a cellular mount point.
1468 </B><DD>Specifies the complete Internet domain name of the cell in which the
1471 <P><LI>If you performed the instructions in Step <A HREF="#LIWQ299">2</A>, issue the <B>vos release</B> command to release the new
1472 version of the <B>root.afs</B> volume to its read-only
1473 sites. (This command requires that you be listed in your cell's
1474 <B>/usr/afs/etc/UserList</B> file. If necessary, verify by issuing
1475 the <B>bos listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.)
1476 <P>Also issue the <B>fs checkvolumes</B> command to force the local Cache
1477 Manager to access the new replica of the <B>root.afs</B>
1478 volume. If desired, you can also remove the temporary
1479 <B>new_cells</B> mount point from the
1480 <B>/afs/.</B><VAR>cellname</VAR> directory.
1482 % <B>vos release root.afs</B>
1484 % <B>fs checkvolumes</B>
1486 % <B>cd /afs/.</B><VAR>cellname</VAR>
1488 % <B>fs rmmount new_cells</B>
1492 <P>For your users to access a newly mounted foreign cell, you must also create
1493 an entry for it in each client machine's local
1494 <B>/usr/vice/etc/CellServDB</B> file and either reboot the machine or use
1495 the <B>fs newcell</B> command to insert the entry directly into its kernel
1496 memory. See the instructions in <A HREF="auagd015.htm#HDRWQ552">Maintaining Knowledge of Database Server Machines</A>.
1498 <P><H3><A NAME="HDRWQ300" HREF="auagd002.htm#ToC_231">To remove a mount point</A></H3>
1499 <A NAME="IDX6575"></A>
1500 <A NAME="IDX6576"></A>
1501 <A NAME="IDX6577"></A>
1502 <A NAME="IDX6578"></A>
1503 <A NAME="IDX6579"></A>
1505 <P><LI>Verify that you have the <B>d</B> (<B>delete</B>) permission on
1506 the ACL of the directory from which you are removing the mount point.
1507 If necessary, issue the <B>fs listacl</B> command, which is fully
1508 described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
1509 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
1511 <P>Members of the <B>system:administrators</B> group always
1512 implicitly have the <B>a</B> (<B>administer</B>) and by default also
1513 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
1514 <B>fs setacl</B> command to grant other rights as necessary.
1515 <P><LI>Issue the <B>fs rmmount</B> command to remove the mount point.
1516 The volume still exists, but its contents are inaccessible if this is the only
1519 % <B>fs rmmount</B> <<VAR>directory</VAR>>
1525 </B><DD>Is the shortest acceptable abbreviation of <B>rmmount</B>.
1526 <P><DT><B><VAR>directory</VAR>
1527 </B><DD>Names the mount point to remove. A partial pathname is interpreted
1528 relative to the current working directory.
1529 <P>Specify the read/write path to the mount point, to avoid the failure that
1530 results when you attempt to delete a mount point from a read-only
1531 volume. By convention, you indicate the read/write path by placing a
1532 period before the cell name at the pathname's second level (for example,
1533 <B>/afs/.abc.com</B>). For further discussion of the
1534 concept of read/write and read-only paths through the filespace, see <A HREF="#HDRWQ294">The Rules of Mount Point Traversal</A>.
1537 <HR><H2><A NAME="HDRWQ301" HREF="auagd002.htm#ToC_232">Displaying Information About Volumes</A></H2>
1538 <A NAME="IDX6580"></A>
1539 <A NAME="IDX6581"></A>
1540 <P>This section explains how to display information about volumes. If
1541 you know a volume's name or volume ID number, there are commands for
1542 displaying its VLDB entry, its volume header, or both. Other commands
1543 display the name or location of the volume that contains a specified file or
1545 <P>For instructions on displaying a volume's quota, see <A HREF="#HDRWQ319">Setting and Displaying Volume Quota and Current Size</A>.
1546 <P><H3><A NAME="HDRWQ302" HREF="auagd002.htm#ToC_233">Displaying VLDB Entries</A></H3>
1547 <A NAME="IDX6582"></A>
1548 <A NAME="IDX6583"></A>
1549 <A NAME="IDX6584"></A>
1550 <A NAME="IDX6585"></A>
1551 <P>The <B>vos listvldb</B> command displays the VLDB entry for the volumes
1552 indicated by the combination of arguments you provide. The
1553 possibilities are listed here from most to least inclusive:
1555 <P><LI>To display every entry in the VLDB, provide no arguments. It can
1556 take a long time to generate the output, depending on the number of
1558 <P><LI>To display every VLDB entry that mentions a specific file server machine
1559 as the site of a volume, specify the machine's name with the
1560 <B>-server</B> argument.
1561 <P><LI>To display every VLDB entry that mentions a certain partition on any file
1562 server machine as the site of a volume, specify the partition name with the
1563 <B>-partition</B> argument.
1564 <P><LI>To display every VLDB entry that mentions a certain partition on a certain
1565 file server machine as the site of a volume, combine the <B>-server</B>
1566 and <B>-partition</B> arguments.
1567 <P><LI>To display a single VLDB entry, specify a volume name or ID number with
1568 the <B>-name</B> argument.
1569 <P><LI>To display the VLDB entry only for volumes with locked VLDB entries, use
1570 the <B>-locked</B> flag with any of the site definitions mentioned
1573 <A NAME="IDX6586"></A>
1574 <A NAME="IDX6587"></A>
1575 <P><H3><A NAME="HDRWQ303" HREF="auagd002.htm#ToC_234">To display VLDB entries</A></H3>
1577 <P><LI>Issue the <B>vos listvldb</B> command.
1579 % <B>vos listvldb</B> [<B>-name</B> <<VAR>volume name or ID</VAR>>] [<B>-server</B> <<VAR>machine name</VAR>>] \
1580 [<B>-partition</B> <<VAR>partition name</VAR>>] [<B>-locked</B>]
1586 </B><DD>Is the shortest acceptable abbreviation of <B>listvldb</B>.
1588 </B><DD>Identifies one volume either by its complete name or volume ID
1589 number. Do not combine this argument with the <B>-server</B> or
1590 <B>-partition</B> arguments.
1592 </B><DD>Specifies a file server machine. Combine this argument with the
1593 <B>-partition</B> argument if desired, but not with the <B>-name</B>
1595 <P><DT><B>-partition
1596 </B><DD>Specifies a partition. Combine this argument with the
1597 <B>-server</B> argument if desired, but not with the <B>-name</B>
1600 </B><DD>Displays only locked VLDB entries. Combine this flag with any of
1604 <P>The VLDB entry for each volume includes the following information:
1606 <P><LI>The base (read/write) volume name. The read-only and backup
1607 versions have the same name with a <B>.readonly</B> and
1608 <B>.backup</B> extension, respectively.
1609 <P><LI>The volume ID numbers allocated to the versions of the volume that
1610 actually exist, in fields labeled <TT>RWrite</TT> for the read/write,
1611 <TT>ROnly</TT> for the read-only, <TT>Backup</TT> for the backup, and
1612 <TT>RClone</TT> for the ReleaseClone. (If a field does not appear,
1613 the corresponding version of the volume does not exist.) The appearance
1614 of the <TT>RClone</TT> field normally indicates that a release operation did
1615 not complete successfully; the <TT>Old release</TT> and <TT>New
1616 release</TT> flags often also appear on one or more of the site definition
1617 lines described just following.
1618 <A NAME="IDX6588"></A>
1619 <A NAME="IDX6589"></A>
1620 <P><LI>The number of sites that house a read/write or read-only copy of the
1621 volume, following the string <TT>number of sites -></TT>.
1622 <A NAME="IDX6590"></A>
1623 <A NAME="IDX6591"></A>
1624 <A NAME="IDX6592"></A>
1625 <A NAME="IDX6593"></A>
1626 <A NAME="IDX6594"></A>
1627 <P><LI>A line for each site that houses a read/write or read-only copy of the
1628 volume, specifying the file server machine, partition, and type of volume
1629 (<TT>RW</TT> for read/write or <TT>RO</TT> for read-only). If a
1630 backup version exists, it is understood to share the read/write site.
1631 Several flags can appear with a site definition:
1633 <A NAME="IDX6595"></A>
1634 <P><DT><B><TT>Not released</TT>
1635 </B><DD>Indicates that the <B>vos release</B> command has not been issued
1636 since the <B>vos addsite</B> command was used to define the read-only
1638 <A NAME="IDX6596"></A>
1639 <P><DT><B><TT>Old release</TT>
1640 </B><DD>Indicates that a <B>vos release</B> command did not complete
1641 successfully, leaving the previous, obsolete version of the volume at this
1643 <A NAME="IDX6597"></A>
1644 <P><DT><B><TT>New release</TT>
1645 </B><DD>Indicates that a <B>vos release</B> command did not complete
1646 successfully, but that this site did receive the correct new version of the
1649 <P><LI>If the VLDB entry is locked, the string <TT>Volume is currently
1652 <P>For further discussion of the <TT>New release</TT> and <TT>Old
1653 release</TT> flags, see <A HREF="#HDRWQ277">Replicating Volumes (Creating Read-only Volumes)</A>.
1654 <P>An example of this command and its output for a single volume:
1656 % <B>vos listvldb user.terry</B>
1658 RWrite: 50489902 Backup: 50489904
1659 number of sites -> 1
1660 server fs3.abc.com partition /vicepc RW Site
1663 <P><H3><A NAME="HDRWQ304" HREF="auagd002.htm#ToC_235">Displaying Volume Headers</A></H3>
1664 <A NAME="IDX6598"></A>
1665 <A NAME="IDX6599"></A>
1666 <P>The <B>vos listvol</B> command displays the volume header for every
1667 volume on one or all partitions on a file server machine. The
1668 <B>vos</B> command interpreter obtains the information from the Volume
1669 Server on the specified machine. You can control the amount of
1670 information displayed by including one of the <B>-fast</B>, the
1671 <B>-long</B>, or the <B>-extended</B> flags described following the
1672 instructions in <A HREF="#HDRWQ305">To display volume headers</A>.
1673 <P>To display a single volume's volume header of one volume only, use the
1674 <B>vos examine</B> command as described in <A HREF="#HDRWQ306">Displaying One Volume's VLDB Entry and Volume Header</A>.
1675 <A NAME="IDX6600"></A>
1676 <A NAME="IDX6601"></A>
1677 <P><H3><A NAME="HDRWQ305" HREF="auagd002.htm#ToC_236">To display volume headers</A></H3>
1679 <P><LI>Issue the <B>vos listvol</B> command.
1681 % <B>vos listvol</B> <<VAR>machine name</VAR>> [<<VAR>partition name</VAR>>] [<B>-fast</B>] [<B>-long</B>] [<B>-extended</B>]
1687 </B><DD>Is the shortest acceptable abbreviation of <B>listvol</B>.
1688 <P><DT><B><VAR>machine name</VAR>
1689 </B><DD>Names the file server machine for which to display volume headers.
1690 Provide this argument alone or with the <VAR>partition name</VAR>
1692 <P><DT><B><VAR>partition name</VAR>
1693 </B><DD>Names one partition on the file server machine named by the <VAR>machine
1694 name</VAR> argument, which must be provided along with this one.
1696 </B><DD>Displays only the volume ID numbers of relevant volumes. Do not
1697 combine this flag with the <B>-long</B> or <B>-extended</B>
1700 </B><DD>Displays more detailed information about each volume. Do not
1701 combine this flag with the <B>-fast</B> or <B>-extended</B>
1704 </B><DD>Displays all of the information displayed by the <B>-long</B> flag,
1705 plus tables of statistics about reads and writes to the files in the
1706 volume. Do not combine this flag with the <B>-fast</B> or
1710 <P>The output is ordered alphabetically by volume name and by default provides
1711 the following information on a single line for each volume:
1714 <P><LI>Volume ID number
1715 <A NAME="IDX6602"></A>
1716 <P><LI>Type (the flag is <TT>RW</TT> for read/write, <TT>RO</TT> for
1717 read-only, <TT>BK</TT> for backup)
1718 <P><LI>Size in kilobytes (<TT>1024</TT> equals a megabyte)
1719 <P><LI>Number of files in the volume, if the <B>-extended</B> flag is
1721 <A NAME="IDX6603"></A>
1722 <P><LI>Status on the file server machine, which is one of the following:
1724 <A NAME="IDX6604"></A>
1725 <P><DT><B><TT>On-line</TT>
1726 </B><DD>The volume is completely accessible to Cache Managers.
1727 <A NAME="IDX6605"></A>
1728 <P><DT><B><TT>Off-line</TT>
1729 </B><DD>The volume is not accessible to Cache Managers, but does not seem to be
1730 corrupted. This status appears while a volume is being dumped, for
1732 <A NAME="IDX6606"></A>
1733 <P><DT><B><TT>Off-line**needs salvage**</TT>
1734 </B><DD>The volume is not accessible to Cache Managers, because it seems to be
1735 corrupted. Use the <B>bos salvage</B> or <B>salvager</B>
1736 command to repair the corruption.
1739 <P>If the following message appears instead of the previously listed
1740 information, it indicates that a volume is not accessible to Cache Managers or
1741 the <B>vos</B> command interpreter, for example because a clone is being
1743 <PRE> **** Volume <VAR>volume_ID</VAR> is busy ****
1745 <P>If the following message appears instead of the previously listed
1746 information, it indicates that the File Server is unable to attach the volume,
1747 perhaps because it is seriously corrupted. The <B>FileLog</B> and
1748 <B>VolserLog</B> log files in the <B>/usr/afs/logs</B> directory on
1749 the file server machine possibly provide additional information; use the
1750 <B>bos getlog</B> command to display them.
1751 <PRE> **** Could not attach volume <VAR>volume_ID</VAR> ****
1753 <P>(For instructions on salvaging a corrupted or unattached volume, see <A HREF="#HDRWQ317">Salvaging Volumes</A>.)
1754 <P>The information about individual volumes is bracketed by summary
1755 lines. The first line of output specifies the number of volumes in the
1756 listing. The last line of output summarizes the number of volumes that
1757 are online, offline, and busy, as in the following example:
1759 % <B>vos listvol fs2.abc.com /vicepb</B>
1760 Total number of volumes on server fs2.abc.com \
1761 partition /vicepb : 66
1762 sys 1969534847 RW 1582 K On-line
1763 sys.backup 1969535105 BK 1582 K On-line
1766 user.pat 1969534536 RW 17518 K On-line
1767 user.pat.backup 1969534538 BK 17537 K On-line
1768 Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
1771 <P><B>Output with the -fast Flag</B>
1773 <A NAME="IDX6607"></A>
1774 If you include the <B>-fast</B> flag displays only the volume ID number of
1775 each volume, arranged in increasing numerical order, as in the following
1776 example. The final line (which summarizes the number of on-line,
1777 off-line, and busy volumes) is omitted.
1779 % <B>vos listvol fs3.abc.com /vicepa -f</B>
1780 Total number of volumes on server fs3.abc.com \
1781 partition /vicepa: 37
1790 <P><B>Output with the -long Flag</B>
1791 <A NAME="IDX6608"></A>
1792 <P>When you include the <B>-long</B> flag, , the output for each volume
1793 includes all of the information in the default listing plus the
1794 following. Each item in this list corresponds to a separate line of
1797 <P><LI>The file server machine and partition that house the volume, as determined
1798 by the command interpreter as the command runs, rather than derived from the
1799 VLDB or the volume header.
1800 <A NAME="IDX6609"></A>
1801 <A NAME="IDX6610"></A>
1802 <A NAME="IDX6611"></A>
1803 <A NAME="IDX6612"></A>
1804 <A NAME="IDX6613"></A>
1805 <A NAME="IDX6614"></A>
1806 <A NAME="IDX6615"></A>
1807 <A NAME="IDX6616"></A>
1808 <P><LI>The volume ID numbers associated with the various versions of the
1809 volume: read/write (<TT>RWrite</TT>), read-only (<TT>ROnly</TT>),
1810 backup (<TT>Backup</TT>), and ReleaseClone (<TT>RClone</TT>). One
1811 of them matches the volume ID number that appears on the first line of the
1812 volume's output. If the value in the <TT>RWrite</TT>,
1813 <TT>ROnly</TT>, or <TT>Backup</TT> field is <TT>0</TT> (zero), there is
1814 no volume of that type. If there is currently no ReleaseClone, the
1815 <TT>RClone</TT> field does not appear at all.
1816 <A NAME="IDX6617"></A>
1817 <A NAME="IDX6618"></A>
1818 <P><LI>The maximum space quota allotted to the read/write copy of the volume,
1819 expressed in kilobyte blocks in the <TT>MaxQuota</TT> field.
1820 <A NAME="IDX6619"></A>
1821 <A NAME="IDX6620"></A>
1822 <P><LI>The date and time the volume was created, in the <TT>Creation</TT>
1823 field. If the volume has been restored with the <B>backup
1824 diskrestore</B>, <B>backup volrestore</B>, or <B>vos restore</B>
1825 command, this is the restore time.
1826 <A NAME="IDX6621"></A>
1827 <A NAME="IDX6622"></A>
1828 <P><LI>The date and time when the contents of the volume last changed, in the
1829 <TT>Last Update</TT> field. For read-only and backup volumes, it
1830 matches the timestamp in the <TT>Creation</TT> field.
1831 <A NAME="IDX6623"></A>
1832 <A NAME="IDX6624"></A>
1833 <P><LI>The number of times the volume has been accessed for a fetch or store
1834 operation since the later of the two following times:
1836 <P><LI>12:00 a.m. on the day the command is issued
1837 <P><LI>The last time the volume changed location
1840 <P>An example of the output when the <B>-long</B> flag is included:
1842 % <B>vos listvol fs2.abc.com b -long</B>
1843 Total number of volumes on server fs2.abc.com
1844 partition /vicepb: 66
1847 user.pat 1969534536 RW 17518 K On-line
1849 RWrite 1969534536 ROnly 0 Backup 1969534538
1851 Creation Mon Jun 12 09:02:25 1989
1852 Last Update Thu Jan 4 17:39:34 1990
1853 1573 accesses in the past day (i.e., vnode references)
1854 user.pat.backup 1969534538 BK 17537 K On-line
1856 RWrite 1969534536 ROnly 0 Backup 1969534538
1858 Creation Fri Jan 5 06:37:59 1990
1859 Last Update Fri Jan 5 06:37:59 1990
1860 0 accesses in the past day (i.e., vnode references)
1863 Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
1866 <P><B>Output with the -extended Flag</B>
1867 <A NAME="IDX6625"></A>
1868 <P>When you include the <B>-extended</B> flag, the output for each volume
1869 includes all of the information reported with the <B>-long</B> flag, plus
1870 two tables of statistics:
1872 <P><LI>The table labeled <TT>Raw Read/Write Stats</TT> table summarizes the
1873 number of times the volume has been accessed for reading or writing.
1874 <P><LI>The table labeled <TT>Writes Affecting Authorship</TT> table contains
1875 information on writes made to files and directories in the specified
1878 <P>An example of the output when the <B>-extended</B> flag is
1880 <PRE> % <B>vos listvol fs3.abc.com a -extended</B>
1881 common.bboards 1969535592 RW 23149 K used 9401 files On-line
1883 RWrite 1969535592 ROnly 0 Backup 1969535594
1885 Creation Mon Mar 8 14:26:05 1999
1886 Last Update Mon Apr 26 09:20:43 1999
1887 11533 accesses in the past day (i.e., vnode references)
1889 Raw Read/Write Stats
1890 |-------------------------------------------|
1891 | Same Network | Diff Network |
1892 |----------|----------|----------|----------|
1893 | Total | Auth | Total | Auth |
1894 |----------|----------|----------|----------|
1895 Reads | 151 | 151 | 1092 | 1068 |
1896 Writes | 3 | 3 | 324 | 324 |
1897 |-------------------------------------------|
1899 Writes Affecting Authorship
1900 |-------------------------------------------|
1901 | File Authorship | Directory Authorship|
1902 |----------|----------|----------|----------|
1903 | Same | Diff | Same | Diff |
1904 |----------|----------|----------|----------|
1905 0-60 sec | 92 | 0 | 100 | 4 |
1906 1-10 min | 1 | 0 | 14 | 6 |
1907 10min-1hr | 0 | 0 | 19 | 4 |
1908 1hr-1day | 1 | 0 | 13 | 0 |
1909 1day-1wk | 1 | 0 | 1 | 0 |
1910 > 1wk | 0 | 0 | 0 | 0 |
1911 |-------------------------------------------|
1914 <P><H3><A NAME="HDRWQ306" HREF="auagd002.htm#ToC_237">Displaying One Volume's VLDB Entry and Volume Header</A></H3>
1915 <A NAME="IDX6626"></A>
1916 <A NAME="IDX6627"></A>
1917 <A NAME="IDX6628"></A>
1918 <A NAME="IDX6629"></A>
1919 <A NAME="IDX6630"></A>
1920 <A NAME="IDX6631"></A>
1921 <A NAME="IDX6632"></A>
1922 <P>The <B>vos examine</B> command displays information from both the VLDB
1923 and the volume header for a single volume. There is some redundancy in
1924 the information from the two sources, which allows you to compare the VLDB and
1926 <P>Because the volume header for each version of a volume (read/write,
1927 read-only, and backup) is different, you can specify which one to
1928 display. Include the <B>.readonly</B> or
1929 <B>.backup</B> extension on the <VAR>volume name or ID</VAR> argument
1930 as appropriate. The information from the VLDB is the same for all three
1932 <A NAME="IDX6633"></A>
1933 <A NAME="IDX6634"></A>
1934 <P><H3><A NAME="HDRWQ307" HREF="auagd002.htm#ToC_238">To display one volume's VLDB entry and volume header</A></H3>
1936 <P><LI>Issue the <B>vos examine</B> command.
1938 % <B>vos examine</B> <<VAR>volume name or ID</VAR>>
1944 </B><DD>Is the shortest acceptable abbreviation of <B>examine</B>.
1945 <P><DT><B><VAR>volume name or ID</VAR>
1946 </B><DD>Identifies one volume either by its complete name or volume ID
1947 number. It can be a read/write, read-only, or backup type. Use
1948 the <B>.backup</B> or <B>.readonly</B> extension if
1952 <P>The top part of the output displays the same information from a volume
1953 header as the <B>vos listvol</B> command with the <B>-long</B> flag,
1954 as described following the instructions in <A HREF="#HDRWQ305">To display volume headers</A>. If you specify the read-only version of the volume
1955 and it exists at more than one site, the output includes all of them.
1956 The bottom part of the output lists the same information from the VLDB as the
1957 <B>vos listvldb</B> command, as described following the instructions in <A HREF="#HDRWQ303">To display VLDB entries</A>.
1958 <P>Below is an example for a volume whose VLDB entry is currently
1961 % <B>vos examine user.terry</B>
1962 user.terry 536870981 RW 3459 K On-line
1964 Write 5360870981 ROnly 0 Backup 536870983
1966 Creation Mon Jun 12 15:22:06 1989
1967 Last Update Fri Jun 16 09:34:35 1989
1968 5719 accesses in the past day (i.e., vnode references)
1969 RWrite: 5360870981 Backup: 536870983
1970 number of sites -> 1
1971 server fs3.abc.com partition /vicepa RW Site
1972 Volume is currently LOCKED
1975 <P><H3><A NAME="HDRWQ308" HREF="auagd002.htm#ToC_239">Displaying the Name or Location of the Volume that Contains a File</A></H3>
1976 <P>This section explains how to learn the name, volume ID
1977 number, or location of the volume that contains a file or directory.
1978 <P>You can also use one piece of information about a volume (for example, its
1979 name) to obtain other information about it (for example, its location).
1980 The following list points you to the relevant instructions:
1982 <A NAME="IDX6635"></A>
1983 <A NAME="IDX6636"></A>
1984 <A NAME="IDX6637"></A>
1985 <A NAME="IDX6638"></A>
1986 <A NAME="IDX6639"></A>
1987 <A NAME="IDX6640"></A>
1988 <A NAME="IDX6641"></A>
1989 <A NAME="IDX6642"></A>
1990 <A NAME="IDX6643"></A>
1991 <A NAME="IDX6644"></A>
1992 <P><LI>To use a volume's name to learn the volume ID numbers of all its
1993 existing versions, use the <B>vos examine</B> command as described in <A HREF="#HDRWQ307">To display one volume's VLDB entry and volume header</A>.
1994 <P>You can also use the command to learn a volume's name by providing its
1996 <P><LI>To use a volume's name or ID number to learn its location, use the
1997 <B>vos listvldb</B> command as described in <A HREF="#HDRWQ303">To display VLDB entries</A>.
1998 <A NAME="IDX6645"></A>
1999 <A NAME="IDX6646"></A>
2000 <A NAME="IDX6647"></A>
2001 <A NAME="IDX6648"></A>
2002 <A NAME="IDX6649"></A>
2003 <A NAME="IDX6650"></A>
2005 <A NAME="IDX6651"></A>
2006 <A NAME="IDX6652"></A>
2007 <A NAME="IDX6653"></A>
2008 <A NAME="IDX6654"></A>
2009 <A NAME="IDX6655"></A>
2010 <A NAME="IDX6656"></A>
2011 <P><H4><A NAME="HDRWQ309">To display the name of the volume that contains a file</A></H4>
2013 <P><LI>Issue the <B>fs listquota</B> command.
2015 % <B>fs listquota</B> [<<VAR>dir/file path</VAR>>]
2021 </B><DD>Is an acceptable alias for <B>listquota</B> (and <B>listq</B> the
2022 shortest acceptable abbreviation).
2023 <P><DT><B><VAR>dir/file path</VAR>
2024 </B><DD>Names a directory or file housed in the volume for which to display the
2025 name. Partial pathnames are interpreted relative to the current working
2026 directory, which is the default if this argument is omitted.
2029 <P>The following is an example of the output:
2031 % <B>fs listquota /afs/abc.com/usr/terry</B>
2032 Volume Name Quota Used % Used Partition
2033 user.terry 15000 5071 34% 86%
2036 <A NAME="IDX6657"></A>
2037 <A NAME="IDX6658"></A>
2038 <A NAME="IDX6659"></A>
2039 <A NAME="IDX6660"></A>
2040 <A NAME="IDX6661"></A>
2041 <A NAME="IDX6662"></A>
2042 <P><H4><A NAME="HDRWQ310">To display the ID number of the volume that contains a file</A></H4>
2044 <P><LI>Issue the <B>fs examine</B> command.
2046 % <B>fs examine</B> [<<VAR>dir/file path</VAR>>]
2052 </B><DD>Is the shortest acceptable abbreviation of <B>examine</B>.
2053 <P><DT><B><VAR>dir/file path</VAR>
2054 </B><DD>Names a directory or file housed in the volume for which to display the
2055 volume ID. Partial pathnames are interpreted relative to the current
2056 working directory, which is the default if this argument is omitted.
2059 <P>The following example illustrates how the output reports the volume ID
2060 number in the <TT>vid</TT> field.
2062 % <B>fs examine /afs/abc.com/usr/terry</B>
2063 Volume status for vid = 50489902 named user.terry
2064 Current maximum quota is 15000
2065 Current blocks used are 5073
2066 The partition has 46383 blocks available out of 333305
2069 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">The partition-related statistics in this command's output do not always
2070 agree with the corresponding values in the output of the standard UNIX
2071 <B>df</B> command. The statistics reported by this command can be
2072 up to five minutes old, because the Cache Manager polls the File Server for
2073 partition information at that frequency. Also, on some operating
2074 systems, the <B>df</B> command's report of partition size includes
2075 reserved space not included in this command's calculation, and so is
2076 likely to be about 10% larger.
2078 <A NAME="IDX6663"></A>
2079 <A NAME="IDX6664"></A>
2080 <A NAME="IDX6665"></A>
2081 <A NAME="IDX6666"></A>
2082 <A NAME="IDX6667"></A>
2083 <A NAME="IDX6668"></A>
2084 <A NAME="IDX6669"></A>
2085 <P><H4><A NAME="Header_242">To display the location of the volume that contains a file</A></H4>
2087 <P><LI>Issue the <B>fs whereis</B> command to display the name of the file
2088 server machine that houses the volume containing a file or directory.
2090 % <B>fs whereis</B> [<<VAR>dir/file path</VAR>>]
2096 </B><DD>Is the shortest acceptable abbreviation of <B>whereis</B>.
2097 <P><DT><B><VAR>dir/file path</VAR>
2098 </B><DD>Names a directory or file for which to report the location. Partial
2099 pathnames are interpreted relative to the current working directory, which is
2100 the default if this argument is omitted.
2102 <P>The output displays the file server machine that houses the volume
2103 containing the file, as in the following example:
2105 % <B>fs whereis /afs/abc.com/user/terry</B>
2106 File /afs/abc.com/usr/terry is on host fs2.abc.com
2109 <P><LI>If you also want to know which partition houses the volume, first issue
2110 the <B>fs listquota</B> command to display the volume's name.
2111 For complete syntax, see <A HREF="#HDRWQ309">To display the name of the volume that contains a file</A>.
2113 % <B>fs listquota</B> [<<VAR>dir/file path</VAR>>]
2116 <P>Then issue the <B>vos listvldb</B> command, providing the volume name
2117 as the <VAR>volume name or ID</VAR> argument. For complete syntax and a
2118 description of the output, see <A HREF="#HDRWQ303">To display VLDB entries</A>.
2120 % <B>vos listvldb</B> <<VAR>volume name or ID</VAR>>
2124 <HR><H2><A NAME="HDRWQ311" HREF="auagd002.htm#ToC_243">Moving Volumes</A></H2>
2125 <A NAME="IDX6670"></A>
2126 <A NAME="IDX6671"></A>
2127 <P>There are three main reasons to move volumes:
2129 <P><LI>To place volumes on other partitions or machines temporarily while
2130 repairing or replacing a disk or file server machine.
2131 <P><LI>To free space on a partition that is becoming overcrowded.
2132 <A NAME="IDX6672"></A>
2133 <A NAME="IDX6673"></A>
2134 <A NAME="IDX6674"></A>
2135 <A NAME="IDX6675"></A>
2136 <A NAME="IDX6676"></A>
2137 One symptom of overcrowding is that users cannot to save files even though the
2138 relevant volume is below its quota. The following error message
2139 confirms the problem:
2141 afs: failed to store file (partition full)
2144 <P>You can track available space on AFS server partitions by using the
2145 <B>scout</B> or <B>afsmonitor</B> programs described in <A HREF="auagd013.htm#HDRWQ438">Monitoring and Auditing AFS Performance</A>.
2146 <P><LI>A file server machine is becoming overloaded because it houses many more
2147 volumes than other machines of the same size, or has volumes with more popular
2151 <A NAME="IDX6677"></A>
2152 <A NAME="IDX6678"></A>
2153 To move a read/write volume, use the <B>vos move</B> command as described
2154 in the following instructions. Before attempting to move the volume,
2155 the <B>vos</B> command interpreter verifies that there is enough free
2156 space for it on the destination partition. If not, it does not attempt
2157 the move operation and prints the following message.
2159 vos: no space on target partition <VAR>destination_part</VAR> to move volume <VAR>volume</VAR>
2162 <P>To move a read-only volume, you actually remove the volume from the current
2163 site by issuing the <B>vos remove</B> command as described in <A HREF="#HDRWQ321">To remove a volume and unmount it</A>. Then define a new site and release the volume to it
2164 by issuing the <B>vos addsite</B> and <B>vos release</B> commands as
2165 described in <A HREF="#HDRWQ279">To replicate a read/write volume (create a read-only volume)</A>.
2166 <A NAME="IDX6679"></A>
2167 <A NAME="IDX6680"></A>
2168 <P>A backup volume always resides at the same site as its read/write source
2169 volume, so you cannot move a backup volume except as part of moving the
2170 read/write source. The <B>vos move</B> command automatically
2171 deletes the backup version when you move a read/write volume. To create
2172 a new backup volume at the new site as soon as the move operation completes,
2173 issue the <B>vos backup</B> command as described in <A HREF="#HDRWQ290">To create and mount a backup volume</A>.
2174 <A NAME="IDX6681"></A>
2175 <A NAME="IDX6682"></A>
2176 <P><H3><A NAME="Header_244" HREF="auagd002.htm#ToC_244">To move a read/write volume</A></H3>
2178 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
2179 file. If necessary, issue the <B>bos listusers</B> command, which
2180 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
2181 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
2183 <P><LI>Issue the <B>vos move</B> command to move the volume. Type it
2184 on a single line; it appears on multiple lines here only for
2187 % <B>vos move</B> <<VAR>volume name or ID</VAR>> \
2188 <<VAR>machine name on source</VAR>> <<VAR>partition name on source </VAR>> \
2189 <<VAR>machine name on destination</VAR>> <<VAR>partition name on destination</VAR>>
2195 </B><DD>Is the shortest acceptable abbreviation of <B>move</B>.
2196 <P><DT><B><VAR>volume name or ID</VAR>
2197 </B><DD>Specifies the name or volume ID number of the read/write volume to
2199 <P><DT><B><VAR>machine name on source</VAR>
2200 </B><DD>Names the file server machine currently housing the volume.
2201 <P><DT><B><VAR>partition name on source</VAR>
2202 </B><DD>Names the partition currently housing the volume.
2203 <P><DT><B><VAR>machine name on destination</VAR>
2204 </B><DD>Names the file server machine to which to move the volume.
2205 <P><DT><B><VAR>partition name on destination</VAR>
2206 </B><DD>Names the partition to which to move the volume.
2208 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">It is best not to halt a <B>vos move</B> operation before it completes,
2209 because parts of the volume can be left on both the source and destination
2210 machines. For more information, see the command's reference page
2211 in the <I>AFS Administration Reference</I>.
2213 <P><LI><B>(Optional)</B> Issue the <B>vos listvldb</B> command to confirm
2214 the success of the move. Complete instructions appear in <A HREF="#HDRWQ303">To display VLDB entries</A>.
2216 % <B>vos listvldb</B> <<VAR>volume name or ID</VAR>>
2219 <P><LI>If a backup version existed at the read/write volume's previous site,
2220 create a new backup at the new site by issuing the <B>vos backup</B>
2221 command, which is fully described in <A HREF="#HDRWQ290">To create and mount a backup volume</A>.
2223 % <B>vos backup</B> <<VAR>volume name or ID</VAR>>
2227 <HR><H2><A NAME="HDRWQ312" HREF="auagd002.htm#ToC_245">Synchronizing the VLDB and Volume Headers</A></H2>
2228 <A NAME="IDX6683"></A>
2229 <A NAME="IDX6684"></A>
2230 <A NAME="IDX6685"></A>
2231 <P>AFS can provide transparent file access because the Volume Location
2232 Database (VLDB) constantly tracks volume locations. When the Cache
2233 Manager needs a file, it contacts the Volume Location (VL) Server, which reads
2234 the VLDB for the current location of the volume containing the file.
2235 Therefore, the VLDB must accurately reflect the state of volumes on the file
2236 server machines at all times. The Volume Server and VL Server
2237 automatically update a volume's VLDB entry when its status changes during
2238 a <B>vos</B> operation, by performing the following series of
2241 <P><LI><A NAME="LIWQ313"></A>The VL Server locks the VLDB entry. The lock advises
2242 other operations not to manipulate any of the volume versions (read/write,
2243 read-only, or backup), which prevents the inconsistency that can result from
2244 multiple simultaneous operations.
2245 <P><LI><A NAME="LIWQ314"></A>The VL Server sets an <I>intention flag</I> in the VLDB
2246 entry that indicates the kind of operation to be performed.
2247 <A NAME="IDX6686"></A>
2248 <A NAME="IDX6687"></A>
2249 This flag never appears in VLDB listings because it is for internal use
2250 only. In case the operation terminates prematurely, this flag tells the
2251 Salvager which operation was interrupted. (The Salvager then determines
2252 the steps necessary either to complete the operation or return the volume to a
2253 previous consistent state. For more information on salvaging, see <A HREF="#HDRWQ317">Salvaging Volumes</A>.)
2254 <P><LI><A NAME="LIWQ315"></A>The Volume Server manipulates the volume. It usually
2255 sets the <TT>Off-line</TT> flag in the volume header, which makes the volume
2256 inaccessible to the File Server and other Volume Server operations during the
2257 manipulation. When the operation completes, the volume is again marked
2259 <P><LI><A NAME="LIWQ316"></A>The VL Server records any changes resulting from the operation
2260 in the VLDB entry. Once the operation is complete, it removes the
2261 intention flag set in Step <A HREF="#LIWQ314">2</A> and releases the lock set in Step <A HREF="#LIWQ313">1</A>.
2263 <P>If a <B>vos</B> operation fails while the Volume Server is manipulating
2264 the volume (corresponding to Step <A HREF="#LIWQ315">3</A>), the volume can be left in an intermediate state, which is
2265 termed <I>corruption</I>. In this case, the <TT>Off-line</TT> or
2266 <TT>Off-line**needs salvage**</TT> marker usually appears at the end of the
2267 first line of output from the <B>vos examine</B> command. To repair
2268 the corruption, run the Salvager before attempting to resynchronize the VLDB
2269 and volume headers. For salvaging instructions, see <A HREF="#HDRWQ317">Salvaging Volumes</A>.
2270 <P>More commonly, an interruption while flags are being set or removed
2271 (corresponding to Step <A HREF="#LIWQ313">1</A>, Step <A HREF="#LIWQ314">2</A>, or Step <A HREF="#LIWQ316">4</A>) causes a discrepancy
2272 between the VLDB and volume headers. To resynchronize the VLDB and
2273 volumes, use the <B>vos syncvldb</B> and <B>vos syncserv</B>
2274 commands. To achieve complete VLDB consistency, it is best to run the
2275 <B>vos syncvldb</B> command on all file server machines in the cell, and
2276 then run the <B>vos syncserv</B> command on all file server machines in
2278 <A NAME="IDX6688"></A>
2279 <A NAME="IDX6689"></A>
2280 <A NAME="IDX6690"></A>
2281 <P>There are several symptoms that indicate a volume operation failed:
2283 <P><LI>Error messages on the standard error stream or in server process log files
2284 indicate that an operation terminated abnormally. Perhaps you had to
2285 halt the operation before it completed (for instance, by using a signal such
2286 as <B>Ctrl-c</B>), or a file server machine or server process was not
2287 functioning when the operation ran. To determine if a machine or
2288 process is still not functioning, issue the <B>bos status</B> command as
2289 described in <A HREF="auagd009.htm#HDRWQ204">Displaying Process Status and Information from the BosConfig File</A>.
2290 <P><LI>A subsequent <B>vos</B> operation fails because a previous failure
2291 left a VLDB entry locked. Sometimes an error message reports that a
2292 volume is locked. To display a list of locked volumes, use the
2293 <B>-locked</B> flag on the <B>vos listvldb</B> command as described in
2294 <A HREF="#HDRWQ302">Displaying VLDB Entries</A>.
2295 <P>If the only problem with a volume is that its VLDB entry is locked, you
2296 probably do not need to synchronize the entire VLDB. Instead use the
2297 <B>vos unlock</B> or <B>vos unlockvldb</B> command to unlock the
2298 entry, as described in <A HREF="#HDRWQ332">Unlocking and Locking VLDB Entries</A>.
2299 <P><LI>A subsequent <B>vos</B> operation fails because a previous failure
2300 left a volume marked as offline. To check a volume's current
2301 status, check the first line of output from the <B>vos examine</B> command
2302 as described in <A HREF="#HDRWQ306">Displaying One Volume's VLDB Entry and Volume Header</A>.
2304 <A NAME="IDX6691"></A>
2305 <A NAME="IDX6692"></A>
2306 <A NAME="IDX6693"></A>
2307 <A NAME="IDX6694"></A>
2308 <A NAME="IDX6695"></A>
2309 <P>The <B>vos syncvldb</B> command corrects the information in the Volume
2310 Location Database (VLDB) either about all volumes housed on a file server
2311 machine, about the volumes on just one partition, or about a single
2312 volume. If checking about one or more partitions, the command contacts
2313 the Volume Server to obtain a list of the volumes that actually reside on each
2314 partition. It then obtains the VLDB entry for each volume from the VL
2315 Server. It changes the VLDB entry as necessary to reflect the state of
2316 the volume on the partition. For example, it creates or updates a VLDB
2317 entry when it finds a volume for which the VLDB entry is missing or
2318 incomplete. However, if there is already a VLDB entry that defines a
2319 different location for the volume, or there are irreconcilable conflicts with
2320 other VLDB entries, it instead writes a message about the conflict to the
2321 standard error stream. The command never removes volumes from the file
2323 <P>When checking a single volume's VLDB entry, the command also
2324 automatically performs the operations invoked by the <B>vos syncserv</B>
2325 command: it not only verifies that the VLDB entry is correct for the
2326 specified volume type (read/write, backup, or read-only), but also checks that
2327 any related volume types mentioned in the VLDB entry actually exist at the
2328 site listed in the entry.
2329 <A NAME="IDX6696"></A>
2330 <P>The <B>vos syncserv</B> command verifies that each volume type
2331 (read/write, read-only, and backup) mentioned in a VLDB entry actually exists
2332 at the site indicated in the entry. It checks all VLDB entries that
2333 mention a site either on any of a file server machine's partitions or on
2334 one partition. Note that command can end up inspecting sites other than
2335 on the specified machine or partition, if there are read-only versions of the
2336 volume at sites other than the read/write site.
2337 <P>The command alters any incorrect information in the VLDB, unless there is
2338 an irreconcilable conflict with other VLDB entries. In that case, it
2339 writes a message to the standard error stream instead. The command
2340 never removes volumes from their sites.
2341 <A NAME="IDX6697"></A>
2342 <A NAME="IDX6698"></A>
2343 <A NAME="IDX6699"></A>
2344 <A NAME="IDX6700"></A>
2345 <P><H3><A NAME="Header_246" HREF="auagd002.htm#ToC_246">To synchronize the VLDB with volume headers</A></H3>
2347 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
2348 file. If necessary, issue the <B>bos listusers</B> command, which
2349 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
2350 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
2352 <P><LI><A NAME="LIVOL-SYNCVL"></A>Issue the <B>vos syncvldb</B> command to make the VLDB
2353 reflect the true state of all volumes on a machine or partition, or the state
2355 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">To synchronize the VLDB completely, issue the command repeatedly,
2356 substituting each file server machine in your cell for the <B>-server</B>
2357 argument in turn and omitting the <B>-partition</B> and <B>-volume</B>
2358 arguments, before proceeding to Step <A HREF="#LIVOL-SYNCSR">3</A>.
2360 <PRE> % <B>vos syncvldb -server</B> <<VAR>machine name</VAR>> [<B>-partition</B> <<VAR>partition name</VAR>>] [<B>-volume</B> <<VAR>volume name or ID</VAR>>] [<B>-verbose >></B> <VAR>file</VAR>]
2366 </B><DD>Is the shortest acceptable abbreviation of <B>syncvldb</B>.
2368 </B><DD>Names the file server machine housing the volumes for which to verify VLDB
2369 entries. If you are also providing the <B>-volume</B> argument,
2370 this argument must name the machine where the volume actually resides.
2371 <P><DT><B>-partition
2372 </B><DD>Identifies the partition (on the file server machine specified by the
2373 <B>-server</B> argument) housing the volumes for which to verify VLDB
2374 entries. In general, it is best to omit this argument so that either
2375 the VLDB entries for all volumes on a server machine are corrected (if you do
2376 not provide the <B>-volume</B> argument), or so that you do not need to
2377 guarantee that the partition actually houses the volume named by the
2378 <B>-volume</B> argument.
2380 </B><DD>Specifies the name or volume ID number of a single volume for which to
2381 verify the VLDB entry.
2382 <P><DT><B><B>-verbose >></B> <VAR>file</VAR>
2383 </B><DD>Directs a detailed trace to the file called <VAR>file</VAR>, which can be
2384 either in AFS or on the local disk of the machine on which you are issuing the
2385 command. The command often writes a large amount of output to the
2386 standard output stream; writing it to a file enables you to examine the
2387 output more carefully.
2389 <P><LI><A NAME="LIVOL-SYNCSR"></A>Issue the <B>vos syncserv</B> command to inspect each
2390 volume for which the VLDB lists a version at the specified site.
2392 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">To synchronize the VLDB completely, issue the command repeatedly,
2393 substituting each file server machine in your cell for the <VAR>machine
2394 name</VAR> argument in turn and omitting the <VAR>partition name</VAR>
2397 <PRE> % <B>vos syncserv</B> <<VAR>machine name</VAR>> [<<VAR>partition name</VAR>>] [<B>-v >></B> <VAR>file</VAR>]
2403 </B><DD>Is the shortest acceptable abbreviation of <B>syncserv</B>.
2404 <P><DT><B><VAR>machine name</VAR>
2405 </B><DD>Names the file server machine mentioned in each VLDB entry to
2407 <P><DT><B><VAR>partition name</VAR>
2408 </B><DD>Identifies the partition mentioned in each VLDB entry to check. If
2409 synchronizing the entire VLDB, omit this argument.
2410 <P><DT><B>-v >> <I><VAR>file</VAR></I>
2411 </B><DD>Directs a detailed trace to the file called <VAR>file</VAR>, which can be
2412 either in AFS or on the local disk of the machine on which you are issuing the
2413 command. The command often writes a large amount of output to the
2414 standard output stream; writing it to a file enables you to examine the
2415 output more carefully.
2418 <HR><H2><A NAME="HDRWQ317" HREF="auagd002.htm#ToC_247">Salvaging Volumes</A></H2>
2419 <A NAME="IDX6701"></A>
2420 <A NAME="IDX6702"></A>
2421 <A NAME="IDX6703"></A>
2422 <A NAME="IDX6704"></A>
2423 <A NAME="IDX6705"></A>
2424 <A NAME="IDX6706"></A>
2425 <A NAME="IDX6707"></A>
2426 <A NAME="IDX6708"></A>
2427 <P>An unexpected interruption while the Volume Server or File Server is
2428 manipulating the data in a volume can leave the volume in an intermediate
2429 state (<I>corrupted</I>), rather than just creating a discrepancy between
2430 the information in the VLDB and volume headers. For example, the
2431 failure of the operation that saves changes to a file (by overwriting old data
2432 with new) can leave the old and new data mixed together on the disk.
2433 <P>If an operation halts because the Volume Server or File Server exits
2434 unexpectedly, the BOS Server automatically shuts down all components of the
2435 <B>fs</B> process and invokes the Salvager. The Salvager checks for
2436 and repairs any inconsistencies it can. Sometimes, however, there are
2437 symptoms of the following sort, which indicate corruption serious enough to
2438 create problems but not serious enough to cause the File Server component to
2439 fail. In these cases you can invoke the Salvager yourself by issuing
2440 the <B>bos salvage</B> command.
2442 <P><LI><B>Symptom:</B> A file appears in the output of the
2443 <B>ls</B> command, but attempts to access the file fail with messages
2444 indicating that it does not exist.
2445 <P><B>Possible cause:</B> The Volume Server or File Server exited in
2446 the middle of a file-creation operation, after changing the directory
2447 structure, but before actually storing data. (Other possible causes are
2448 that the ACL on the directory does not grant the permissions you need to
2449 access the file, or there is a process, machine, or network outage.
2450 Check for these causes before assuming the file is corrupted.)
2451 <P><B>Salvager's solution:</B> Remove the file's entry
2452 from the directory structure.
2453 <P><LI><B>Symptom:</B> A volume is marked <TT>Off-line</TT> in the
2454 output from the <B>vos examine</B> and <B>vos listvol</B> commands, or
2455 attempts to access the volume fail.
2456 <P><B>Possible cause:</B> Two files or versions of a file are
2457 sharing the same disk blocks because of an interrupted operation. The
2458 File Server and Volume Server normally refuse to attach volumes that exhibit
2459 this type of corruption, because it can be very dangerous. If the
2460 Volume Server or File Server do attach the volume but are unsure of the status
2461 of the affected disk blocks, they sometimes try to write yet more data
2462 there. When they cannot perform the write, the data is lost.
2463 This effect can cascade, causing loss of all data on a partition.
2464 <P><B>Salvager's solution:</B> Delete the data from the
2465 corrupted disk blocks in preference to losing an entire partition.
2466 <P><LI><B>Symptom:</B> There is less space available on the partition
2467 than you expect based on the size statistic reported for each volume by the
2468 <B>vos listvol</B> command.
2469 <P><B>Possible cause:</B> There are orphaned files and
2470 directories. An orphaned element is completely inaccessible because it
2471 is not referenced by any directory that can act as its parent (is higher in
2472 the file tree). An orphaned element is not counted in the calculation
2473 of a volume's size (or against its quota), even though it occupies space
2474 on the server partition.
2475 <P><B>Salvager's solution:</B> By default, print a message to
2476 the <B>/usr/afs/logs/SalvageLog</B> file reporting how many orphans were
2477 found and the approximate number of kilobytes they are consuming. You
2478 can use the <B>-orphans</B> argument to remove or attach orphaned elements
2479 instead. See <A HREF="#HDRWQ318">To salvage volumes</A>.
2481 <P>When you notice symptoms such as these, use the <B>bos salvage</B>
2482 command to invoke the Salvager before corruption spreads. (Even though
2483 it operates on volumes, the command belongs to the <B>bos</B> suite
2484 because the BOS Server must coordinate the shutdown and restart of the Volume
2485 Server and File Server with the Salvager. It shuts them down before the
2486 Salvager starts, and automatically restarts them when the salvage operation
2488 <P>All of the AFS data stored on a file server machine is inaccessible during
2489 the salvage of one or more partitions. If you salvage just one volume,
2490 it alone is inaccessible.
2491 <P>When processing one or more partitions, the command restores consistency to
2492 corrupted read/write volumes where possible. For read-only or backup
2493 volumes, it inspects only the volume header:
2495 <P><LI>If the volume header is corrupted, the Salvager removes the volume
2496 completely and records the removal in its log file,
2497 <B>/usr/afs/logs/SalvageLog</B>. Issue the <B>vos release</B>
2498 or <B>vos backup</B> command to create the read-only or backup volume
2500 <P><LI>If the volume header is intact, the Salvager skips the volume (does not
2501 check for corruption in the contents). However, if the File Server
2502 notices corruption as it initializes, it sometimes refuses to attach the
2503 volume or bring it online. In this case, it is simplest to remove the
2504 volume by issuing the <B>vos remove</B> or <B>vos zap</B>
2505 command. Then issue the <B>vos release</B> or <B>vos backup</B>
2506 command to create it again.
2508 <P>Combine the <B>bos salvage</B> command's arguments as indicated to
2509 salvage different numbers of volumes:
2511 <P><LI>To salvage all volumes on a file server machine, combine the
2512 <B>-server</B> argument and the <B>-all</B> flag.
2513 <P><LI>To salvage all volumes on one partition, combine the <B>-server</B>
2514 and <B>-partition</B> arguments.
2515 <P><LI>To salvage only one read/write volume, combine the <B>-server</B>,
2516 <B>-partition</B>, and <B>-volume</B> arguments. Only that
2517 volume is inaccessible to Cache Managers, because the BOS Server does not
2518 shutdown the File Server and Volume Server processes during the salvage of a
2519 single volume. Do not name a read-only or backup volume with the
2520 <B>-volume</B> argument. Instead, remove the volume, using the
2521 <B>vos remove</B> or <B>vos zap</B> command. Then create a new
2522 copy of the volume with the <B>vos release</B> or <B>vos backup</B>
2525 <P>The Salvager always writes a trace to the
2526 <B>/usr/afs/logs/SalvageLog</B> file on the file server machine where it
2527 runs. To record the trace in another file as well (either in AFS or on
2528 the local disk of the machine where you issue the <B>bos salvage</B>
2529 command), name the file with the <B>-file</B> argument. Or, to
2530 display the trace on the standard output stream as it is written to the
2531 <B>/usr/afs/logs/SalvageLog</B> file, include the <B>-showlog</B>
2533 <P>By default, multiple Salvager subprocesses run in parallel: one for
2534 each partition up to four, and four subprocesses for four or more
2535 partitions. To increase or decrease the number of subprocesses running
2536 in parallel, provide a positive integer value for the <B>-parallel</B>
2538 <P>If there is more than one server partition on a physical disk, the Salvager
2539 by default salvages them serially to avoid the inefficiency of constantly
2540 moving the disk head from one partition to another. However, this
2541 strategy is often not ideal if the partitions are configured as logical
2542 volumes that span multiple disks. To force the Salvager to salvage
2543 logical volumes in parallel, provide the string <B>all</B> as the value
2544 for the <B>-parallel</B> argument. Provide a positive integer to
2545 specify the number of subprocesses to run in parallel (for example,
2546 <B>-parallel 5all</B> for five subprocesses), or omit the integer to run
2547 up to four subprocesses, depending on the number of logical volumes being
2549 <P>The Salvager creates temporary files as it runs, by default writing them to
2550 the partition it is salvaging. The number of files can be quite large,
2551 and if the partition is too full to accommodate them, the Salvager terminates
2552 without completing the salvage operation (it always removes the temporary
2553 files before exiting). Other Salvager subprocesses running at the same
2554 time continue until they finish salvaging all other partitions where there is
2555 enough disk space for temporary files. To complete the interrupted
2556 salvage, reissue the command against the appropriate partitions, adding the
2557 <B>-tmpdir</B> argument to redirect the temporary files to a local disk
2558 directory that has enough space.
2559 <P>The <B>-orphans</B> argument controls how the Salvager handles orphaned
2560 files and directories that it finds on server partitions it is
2561 salvaging. An <I>orphaned</I> element is completely inaccessible
2562 because it is not referenced by the vnode of any directory that can act as its
2563 parent (is higher in the filespace). Orphaned objects occupy space on
2564 the server partition, but do not count against the volume's quota.
2565 <P>During the salvage, the output of the <B>bos status</B> command reports
2566 the following auxiliary status for the <B>fs</B> process:
2568 Salvaging file system
2571 <A NAME="IDX6709"></A>
2572 <A NAME="IDX6710"></A>
2573 <P><H3><A NAME="HDRWQ318" HREF="auagd002.htm#ToC_248">To salvage volumes</A></H3>
2575 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
2576 file. If necessary, issue the <B>bos listusers</B> command, which
2577 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
2578 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
2580 <P><LI>Issue the <B>bos salvage</B> command to salvage one or more
2583 % <B>bos salvage -server</B> <<VAR>machine name</VAR>> [<B>-partition</B> <<VAR>salvage partition</VAR>>] \
2584 [<B>-volume</B> <<VAR>salvage volume number or volume name</VAR>>] \
2585 [<B>-file</B> <VAR>salvage log output file</VAR>] [<B>-all</B>] [<B>-showlog</B>] \
2586 [<B>-parallel</B> <<VAR># of max parallel partition salvaging</VAR>>] \
2587 [<B>-tmpdir</B> <<VAR>directory to place tmp files</VAR>>] \
2588 [<B>-orphans</B> <<B>ignore</B> | <B>remove</B> | <B>attach</B>>]
2594 </B><DD>Names the file server machine on which to salvage volumes. This
2595 argument can be combined either with the <B>-all</B> flag, the
2596 <B>-partition</B> argument, or both the <B>-partition</B> and
2597 <B>-volume</B> arguments.
2598 <P><DT><B>-partition
2599 </B><DD>Names a single partition on which to salvage all volumes. The
2600 <B>-server</B> argument must be provided along with this one.
2602 </B><DD>Specifies the name or volume ID number of one read/write volume to
2603 salvage. Combine this argument with the <B>-server</B> and
2604 <B>-partition</B> arguments.
2606 </B><DD>Specifies the complete pathname of a file into which to write a trace of
2607 the salvage operation, in addition to the <B>/usr/afs/logs/SalvageLog</B>
2608 file on the server machine. If the file pathname is local, the trace is
2609 written to the specified file on the local disk of the machine where the
2610 <B>bos salvage</B> command is issued. If the <B>-volume</B>
2611 argument is included, the file can be in AFS, though not in the volume being
2612 salvaged. Do not combine this argument with the <B>-showlog</B>
2615 </B><DD>Salvages all volumes on all of the partitions on the machine named by the
2616 <B>-server</B> argument.
2618 </B><DD>Displays the trace of the salvage operation on the standard output stream,
2619 as well as writing it to the <B>/usr/afs/logs/SalvageLog</B> file.
2621 </B><DD>Specifies the maximum number of Salvager subprocesses to run in
2622 parallel. Provide one of three values:
2624 <P><LI>An integer from the range <B>1</B> to <B>32</B>. A value of
2625 <B>1</B> means that a single Salvager process salvages the partitions
2627 <P><LI>The string <B>all</B> to run up to four Salvager subprocesses in
2628 parallel on partitions formatted as logical volumes that span multiple
2629 physical disks. Use this value only with such logical volumes.
2630 <P><LI>The string <B>all</B> followed immediately (with no intervening space)
2631 by an integer from the range <B>1</B> to <B>32</B>, to run the
2632 specified number of Salvager subprocesses in parallel on partitions formatted
2633 as logical volumes. Use this value only with such logical
2636 <P>The BOS Server never starts more Salvager subprocesses than there are
2637 partitions, and always starts only one process to salvage a single
2638 volume. If this argument is omitted, up to four Salvager subprocesses
2641 </B><DD>Specifies the full pathname of a local disk directory to which the
2642 Salvager process writes temporary files as it runs. By default, it
2643 writes them to the partition it is currently salvaging.
2645 </B><DD>Controls how the Salvager handles orphaned files and directories.
2646 Choose one of the following three values:
2649 </B><DD>Leaves the orphaned objects on the disk, but prints a message to the
2650 <B>/usr/afs/logs/SalvageLog</B> file reporting how many orphans were found
2651 and the approximate number of kilobytes they are consuming. This is the
2652 default if you omit the <B>-orphans</B> argument.
2654 </B><DD>Removes the orphaned objects, and prints a message to the
2655 <B>/usr/afs/logs/SalvageLog</B> file reporting how many orphans were
2656 removed and the approximate number of kilobytes they were consuming.
2658 </B><DD>Attaches the orphaned objects by creating a reference to them in the vnode
2659 of the volume's root directory. Since each object's actual
2660 name is now lost, the Salvager assigns each one a name of the following
2663 <DD><P><B>_ _ORPHANFILE_ _.</B><VAR>index</VAR> for files
2664 <DD><P><B>_ _ORPHANDIR_ _.</B><VAR>index</VAR> for directories
2667 <P>where <VAR>index</VAR> is a two-digit number that uniquely identifies each
2668 object. The orphans are charged against the volume's quota and
2669 appear in the output of the <B>ls</B> command issued against the
2670 volume's root directory.
2674 <HR><H2><A NAME="HDRWQ319" HREF="auagd002.htm#ToC_249">Setting and Displaying Volume Quota and Current Size</A></H2>
2675 <A NAME="IDX6711"></A>
2676 <A NAME="IDX6712"></A>
2677 <P>Every AFS volume has an associated <VAR>quota</VAR> which limits the
2678 volume's size. The default quota for a newly created volume is
2679 5,000 kilobyte blocks (slightly less that 5 MB). When a volume reaches
2680 its quota, the File Server rejects attempts to create new files or directories
2681 in it. If an application is writing data into an existing file in a
2682 full volume, the File Server allows a defined overage (by default, 1
2683 MB). (You can use the <B>fileserver</B> command's
2684 <B>-spare</B> or <B>-pctspare</B> argument to change the default
2685 overage; see the command's reference page in the <I>AFS
2686 Administration Reference</I>.)
2687 <P>To set a quota other than 5000 KB as you create a volume, include the
2688 <B>-maxquota</B> argument to the <B>vos create</B> command, as
2689 described in <A HREF="#HDRWQ270">Creating Read/write Volumes</A>. To modify an existing volume's quota, issue
2690 either the <B>fs setquota</B> or the <B>fs setvol</B> command as
2691 described in the following instructions. Do not set an existing
2692 volume's quota lower than its current size.
2693 <P>In general, smaller volumes are easier to administer than larger
2694 ones. If you need to move volumes, say for load-balancing purposes, it
2695 is easier to find enough free space on other partitions for small
2696 volumes. Move operations complete more quickly for small volumes,
2697 reducing the potential for outages or other errors to interrupt the
2698 move. AFS supports a maximum volume size, which can vary for different
2699 AFS releases; see the <I>AFS Release Notes</I> for the version you
2700 are using. Also, the size of a partition or logical places an absolute
2701 limit on volume size, because a volume cannot span multiple partitions or
2703 <P>It is generally safe to overpack partitions by putting more volumes on them
2704 than can actually fit if all the volumes reach their maximum quota.
2705 However, only experience determines to what degree overpacking works in your
2706 cell. It depends on what kind of quota you assign to volumes
2707 (particularly user volumes, which are more likely than system volumes to grow
2708 unpredictably) and how much information people generate and store in
2709 comparison to their quota.
2710 <P>There are several commands that display a volume's quota, as described
2711 in the following instructions. They differ in how much related
2712 information they produce.
2713 <P><H3><A NAME="Header_250" HREF="auagd002.htm#ToC_250">To set quota for a single volume</A></H3>
2714 <A NAME="IDX6713"></A>
2715 <A NAME="IDX6714"></A>
2716 <A NAME="IDX6715"></A>
2717 <A NAME="IDX6716"></A>
2718 <A NAME="IDX6717"></A>
2720 <P><LI>Verify that you belong to the <B>system:administrators</B>
2721 group. If necessary, issue the <B>pts membership</B> command, which
2722 is fully described in <A HREF="auagd021.htm#HDRWQ809">To display the members of the system:administrators group</A>.
2723 <PRE> % <B>pts membership system:administrators</B>
2726 <P><LI>Issue the <B>fs setquota</B> command to set the volume's maximum
2729 % <B>fs setquota</B> [<<VAR>dir/file path</VAR>>] <B>-max</B> <<VAR>max quota in kbytes</VAR>>
2735 </B><DD>Is an acceptable alias for <B>setquota</B>.
2736 <P><DT><B><VAR>dir/file path</VAR>
2737 </B><DD>Names a file or directory in the volume for which to set the indicated
2738 quota. Partial pathnames are interpreted relative to the current
2739 working directory, which is the default if you omit this argument.
2740 <P>Specify the read/write path to the file or directory, to avoid the failure
2741 that results when you attempt to change a read-only volume. By
2742 convention, you indicate the read/write path by placing a period before the
2743 cell name at the pathname's second level (for example,
2744 <B>/afs/.abc.com</B>). For further discussion of the
2745 concept of read/write and read-only paths through the filespace, see <A HREF="#HDRWQ294">The Rules of Mount Point Traversal</A>.
2746 <P><DT><B><VAR>max quota in kbytes</VAR>
2747 </B><DD>Sets the volume's quota, expressed in kilobyte blocks
2748 (<B>1024</B> equals a megabyte). A value of <B>0</B> grants an
2749 unlimited quota, but the size of the partition imposes an absolute
2750 limit. You must include the <B>-max</B> switch if omitting the
2751 <VAR>dir/file path</VAR> argument (to set the quota on the volume that houses
2752 the current working directory).
2755 <P><H3><A NAME="Header_251" HREF="auagd002.htm#ToC_251">To set maximum quota on one or more volumes</A></H3>
2756 <A NAME="IDX6718"></A>
2757 <A NAME="IDX6719"></A>
2758 <A NAME="IDX6720"></A>
2759 <A NAME="IDX6721"></A>
2761 <P><LI>Verify that you belong to the <B>system:administrators</B>
2762 group. If necessary, issue the <B>pts membership</B> command, which
2763 is fully described in <A HREF="auagd021.htm#HDRWQ809">To display the members of the system:administrators group</A>.
2764 <PRE> % <B>pts membership system:administrators</B>
2767 <P><LI>Issue the <B>fs setvol</B> command to set the quota on one or more
2770 % <B>fs setvol</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>] <B>-max</B> <<VAR>disk space quota in 1K units</VAR>>
2776 </B><DD>Is an acceptable alias for <B>setvol</B>.
2777 <P><DT><B><VAR>dir/file path</VAR>
2778 </B><DD>Names one file or directory that resides in each volume for which to set
2779 the indicated quota. Partial pathnames are interpreted relative to the
2780 current working directory, which is the default if you omit this
2782 <P><DT><B><VAR>disk space quota in 1K units</VAR>
2783 </B><DD>Sets the maximum quota on each volume, expressed in kilobytes blocks
2784 (<B>1024</B> equals a megabyte). A value of <B>0</B> grants an
2785 unlimited quota, but the size of the partition does impose an absolute
2789 <A NAME="IDX6722"></A>
2790 <A NAME="IDX6723"></A>
2791 <A NAME="IDX6724"></A>
2792 <A NAME="IDX6725"></A>
2793 <P><H3><A NAME="Header_252" HREF="auagd002.htm#ToC_252">To display percent quota used</A></H3>
2795 <P><LI>Issue the <B>fs quota</B> command.
2797 % <B>fs quota</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>]
2803 </B><DD>Is the shortest acceptable abbreviation of <B>quota</B>.
2804 <P><DT><B><VAR>dir/file path</VAR>
2805 </B><DD>Names a directory or file in each volume for which to display percent
2806 quota used. Partial pathnames are interpreted relative to the current
2807 working directory, which is the default if you omit this argument.
2810 <P>The following example illustrates the output produced by this
2813 % <B>fs quota /afs/abc.com/usr/terry</B>
2817 <A NAME="IDX6726"></A>
2818 <A NAME="IDX6727"></A>
2819 <A NAME="IDX6728"></A>
2820 <A NAME="IDX6729"></A>
2821 <A NAME="IDX6730"></A>
2822 <A NAME="IDX6731"></A>
2823 <P><H3><A NAME="Header_253" HREF="auagd002.htm#ToC_253">To display quota, current size, and other information</A></H3>
2825 <P><LI>Issue the <B>fs listquota</B> command.
2827 % <B>fs listquota</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>]
2833 </B><DD>Is an alias for <B>listquota</B>.
2834 <P><DT><B><VAR>dir/file path</VAR>
2835 </B><DD>Names a directory or file in each volume for which to display quota along
2836 with volume name and current space usage. Partial pathnames are
2837 interpreted relative to the current working directory, which is the default if
2838 you omit this argument.
2841 <P>As illustrated in the following example, the output reports the
2842 volume's name, its quota and current size (both in kilobyte units), the
2843 percent quota used, and the percentage of space on the volume's host
2844 partition that is used.
2846 % <B>fs listquota /afs/abc.com/usr/terry</B>
2847 Volume Name Quota Used % Used Partition
2848 user.terry 15000 5071 34% 86%
2851 <A NAME="IDX6732"></A>
2852 <A NAME="IDX6733"></A>
2853 <A NAME="IDX6734"></A>
2854 <A NAME="IDX6735"></A>
2855 <A NAME="IDX6736"></A>
2856 <A NAME="IDX6737"></A>
2857 <A NAME="IDX6738"></A>
2858 <P><H3><A NAME="Header_254" HREF="auagd002.htm#ToC_254">To display quota, current size, and more partition information</A></H3>
2860 <P><LI>Issue the <B>fs examine</B> command.
2862 % <B>fs examine</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>]
2868 </B><DD>Is the shortest acceptable abbreviation of <B>examine</B>.
2869 <P><DT><B><VAR>dir/file path</VAR>
2870 </B><DD>Names a directory or file in each volume for which to display quota
2871 information and information about the host partition. Partial pathnames
2872 are interpreted relative to the current working directory, which is the
2873 default if you omit this argument.
2876 <P>As illustrated in the following example, the output displays the
2877 volume's volume ID number and name, its quota and current size (both in
2878 kilobyte units), and the free and total number of kilobyte blocks on the
2879 volume's host partition.
2881 % <B>fs examine /afs/abc.com/usr/terry</B>
2882 Volume status for vid = 50489902 named user.terry
2883 Current maximum quota is 15000
2884 Current blocks used are 5073
2885 The partition has 46383 blocks available out of 333305
2888 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">The partition-related statistics in this command's output do not always
2889 agree with the corresponding values in the output of the standard UNIX
2890 <B>df</B> command. The statistics reported by this command can be
2891 up to five minutes old, because the Cache Manager polls the File Server for
2892 partition information at that frequency. Also, on some operating
2893 systems, the <B>df</B> command's report of partition size includes
2894 reserved space not included in this command's calculation, and so is
2895 likely to be about 10% larger.
2897 <HR><H2><A NAME="HDRWQ320" HREF="auagd002.htm#ToC_255">Removing Volumes and their Mount Points</A></H2>
2898 <A NAME="IDX6739"></A>
2899 <A NAME="IDX6740"></A>
2900 <A NAME="IDX6741"></A>
2901 <A NAME="IDX6742"></A>
2902 <A NAME="IDX6743"></A>
2903 <P>To remove a volume from its site and its record from the VLDB, use the
2904 <B>vos remove</B> command. Use it to remove any of the three types
2905 of volumes; the effect depends on the type.
2907 <P><LI>If you indicate the read/write volume by specifying the volume's base
2908 name without a <B>.readonly</B> or <B>.backup</B>
2909 extension, the command removes both the read/write and associated backup
2910 volume from the partition that houses them.
2911 <A NAME="IDX6744"></A>
2912 <A NAME="IDX6745"></A>
2913 You do not need to provide the <B>-server</B> and <B>-partition</B>
2914 arguments, because there can be only one read/write site. The site
2915 information is also removed from the VLDB entry, and the site count (reported
2916 by the <B>vos examine</B> and <B>vos listvldb</B> commands as
2917 <TT>number of sites</TT>) decrements by one. The read/write and
2918 backup volume ID numbers no longer appear in the output from the <B>vos
2919 examine</B> and <B>vos listvldb</B> commands, but they are preserved
2920 internally. Read-only sites, if any, are not affected, but cannot be
2921 changed unless a read/write site is again defined. The entire VLDB
2922 entry is removed if there are no read-only sites.
2923 <P>If there are no read-only copies left, it is best to remove the
2924 volume's mount point to prevent attempts to access the volume's
2925 contents. Do not remove the mount point if copies of the read-only
2927 <P><LI>If you indicate a read-only volume by including the
2928 <B>.readonly</B> extension on its name, it is removed from the
2929 partition that houses it, and the corresponding site information is removed
2930 from the VLDB entry. The site count reported by the <B>vos
2931 examine</B> and <B>vos listvldb</B> commands as <TT>number of
2932 sites</TT> decrements by one for each volume you remove.
2933 <A NAME="IDX6746"></A>
2934 <P>If there is more than one read-only site, you must include the
2935 <B>-server</B> argument (and optionally <B>-partition</B> argument) to
2936 specify the site from which to remove the volume. If there is only one
2937 read-only site, the volume name is sufficient; if no read/write volume
2938 exists in this case, the entire VLDB entry is removed.
2939 <P>It is not generally appropriate to remove the volume's mount point
2940 when removing a read-only volume, especially if the read/write version of the
2941 volume still exists. If the read/write version no longer exists, remove
2942 the mount point as described in Step <A HREF="#LIWQ324">5</A> of <A HREF="#HDRWQ321">To remove a volume and unmount it</A>.
2943 <P><LI>If you indicate a backup volume by including the <B>.backup</B>
2944 extension on its name, it is removed from the partition that houses it and its
2945 site information is removed from the VLDB entry. You do not need to
2946 provide the <B>-server</B> and <B>-partition</B> arguments, because
2947 there can be only one backup site. The backup volume ID number no
2948 longer appears in the output from the <B>vos examine</B> or <B>vos
2949 listvldb</B> command, but is preserved internally.
2950 <P>In the standard configuration, there is a separate mount point for the
2951 backup version of a user volume. Remember to remove the mount point to
2952 prevent attempt to access the nonexistent volume's contents.
2954 <P><H3><A NAME="Header_256" HREF="auagd002.htm#ToC_256">Other Removal Commands</A></H3>
2955 <A NAME="IDX6747"></A>
2956 <P>The <B>vos remove</B> command is almost always the appropriate way to
2957 remove a volume, because it automatically removes a volume's VLDB entry
2958 and both the volume header and all data from the partition. If either
2959 the VLDB entry or volume header does not exist, it is sometimes necessary to
2960 use other commands that remove only the remaining element. Do not use
2961 these commands in the normal case when both the VLDB entry and the volume
2962 header exist, because by definition they create discrepancies between
2963 them. For details on the commands' syntax, see their reference
2964 pages in the <I>AFS Administration Reference</I>.
2965 <P>The <B>vos zap</B> command removes a volume from its site by removing
2966 the volume header and volume data for which a VLDB entry no longer
2968 <A NAME="IDX6748"></A>
2969 <A NAME="IDX6749"></A>
2970 You can tell a VLDB entry is missing if the <B>vos listvol</B> command
2971 displays the volume header but the <B>vos examine</B> or <B>vos
2972 listvldb</B> command cannot locate the VLDB entry. You must run this
2973 command to correct the discrepancy, because the <B>vos syncvldb</B> and
2974 <B>vos syncserv</B> commands never remove volume headers.
2975 <P>The <B>vos remsite</B> command removes a read-only site definition from
2976 the VLDB without affecting the volume on the file server machine.
2977 <A NAME="IDX6750"></A>
2978 <A NAME="IDX6751"></A>
2979 Use this command when you have mistakenly issued the <B>vos addsite</B>
2980 command to define a read-only site, but have not yet issued the <B>vos
2981 release</B> command to release the volume to the site. If you have
2982 actually released a volume to the site, use the <B>vos remove</B> command
2984 <P>The <B>vos delentry</B> command removes the entire VLDB entry that
2985 mentions the volume you specify.
2986 <A NAME="IDX6752"></A>
2987 <A NAME="IDX6753"></A>
2988 If versions of the volume actually exist on file server machines, they are not
2989 affected. This command is useful if you know for certain that a volume
2990 removal was not recorded in the VLDB (perhaps you used the <B>vos zap</B>
2991 command during an emergency), and do not want to take the time to
2992 resynchronize the entire VLDB with the <B>vos syncvldb</B> and <B>vos
2993 syncserv</B> commands.
2994 <P><H3><A NAME="HDRWQ321" HREF="auagd002.htm#ToC_257">To remove a volume and unmount it</A></H3>
2995 <A NAME="IDX6754"></A>
2997 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
2998 file. If necessary, issue the <B>bos listusers</B> command, which
2999 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
3000 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
3002 <P><LI>If removing the volume's mount point, verify that you have the
3003 <B>d</B> (<B>delete</B>) permission on its parent directory's
3004 ACL. If necessary, issue the <B>fs listacl</B> command, which is
3005 fully described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
3006 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
3008 <P>Members of the <B>system:administrators</B> group always
3009 implicitly have the <B>a</B> (<B>administer</B>) and by default also
3010 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
3011 <B>fs setacl</B> command to grant other rights as necessary.
3012 <P><LI><A NAME="LIWQ322"></A><B>(Optional)</B> Dump the volume to a file or to tape, in
3013 case you want to restore it later. To copy the volume's contents
3014 to a file, use the <B>vos dump</B> command as instructed in <A HREF="#HDRWQ325">Dumping and Restoring Volumes</A>. You can then copy the file to tape using a
3015 third-party backup utility or an archiving utility such as the UNIX
3017 <P>Alternatively, use the AFS Backup System to create a tape copy. In
3018 this case, it can be convenient to create a temporary volume set that includes
3019 only the volume of interest. Temporary volume sets are not recorded in
3020 the Backup Database, and so do not clutter database with records for volume
3021 sets that you use only once. For instructions, see <A HREF="auagd012.htm#HDRWQ416">To create a dump</A>.
3022 <A NAME="IDX6755"></A>
3023 <A NAME="IDX6756"></A>
3024 <P><LI><A NAME="LIWQ323"></A>Issue the <B>vos remove</B> command to remove the
3025 volume. If removing a read-only volume from multiple sites, repeat the
3026 command for each one.
3028 % <B>vos remove</B> [<B>-server</B> <VAR>machine name</VAR>>] [<B>-partition</B> <<VAR>partition name</VAR>>] \
3029 <B>-id</B> <<VAR>volume name or ID</VAR>>
3035 </B><DD>Is the shortest acceptable abbreviation of <B>remove</B>.
3037 </B><DD>Specifies the file server machine on which the volume resides. It
3038 is necessary only when the <B>-id</B> argument names a read-only volume
3039 that exists at multiple sites.
3040 <P><DT><B>-partition
3041 </B><DD>Specifies the partition on <VAR>machine name</VAR> where the volume
3042 resides. It is necessary only when the <B>-id</B> argument names a
3043 read-only volume that exists at multiple sites. Provide the
3044 <B>-server</B> argument along with this one.
3046 </B><DD>Identifies the volume to remove, either by its complete name or volume ID
3047 number. If identifying a read-only or backup volume by name, include
3048 the appropriate extension (<B>.readonly</B> or
3051 <A NAME="IDX6757"></A>
3052 <A NAME="IDX6758"></A>
3053 <P><LI><A NAME="LIWQ324"></A>If you are removing the last existing version of the volume,
3054 issue the <B>fs rmmount</B> command remove the corresponding mount
3055 point. Complete instructions appear in <A HREF="#HDRWQ321">To remove a volume and unmount it</A>.
3056 <P>If you are removing a backup volume that is mounted in the conventional way
3057 (at a subdirectory of its read/write volume's root directory), then
3058 removing the source volume's mount point in this step is sufficient to
3059 remove the backup volume's mount point. If you mounted the backup
3060 at a completely separate directory, you need to repeat this step for the
3061 backup volume's mount point.
3063 % <B>fs rmmount</B> <<VAR>directory</VAR>>
3066 <P><LI><B>(Optional)</B> If you created a dump file in Step <A HREF="#LIWQ322">3</A>, transfer it to tape. The preferred method is to use
3067 the AFS Backup System, which is described in <A HREF="auagd011.htm#HDRWQ333">Configuring the AFS Backup System</A> and <A HREF="auagd012.htm#HDRWQ382">Backing Up and Restoring AFS Data</A>.
3069 <HR><H2><A NAME="HDRWQ325" HREF="auagd002.htm#ToC_258">Dumping and Restoring Volumes</A></H2>
3070 <A NAME="IDX6759"></A>
3071 <A NAME="IDX6760"></A>
3072 <P><I>Dumping</I> a volume with the <B>vos dump</B> command converts
3073 its contents into ASCII format and writes them to the file you specify.
3074 The <B>vos restore</B> command places a dump file's contents into a
3075 volume after converting them into the volume format appropriate for the
3076 indicated file server machine.
3077 <P><H3><A NAME="Header_259" HREF="auagd002.htm#ToC_259">About Dumping Volumes</A></H3>
3078 <A NAME="IDX6761"></A>
3079 <A NAME="IDX6762"></A>
3080 <A NAME="IDX6763"></A>
3081 <A NAME="IDX6764"></A>
3082 <A NAME="IDX6765"></A>
3083 <A NAME="IDX6766"></A>
3084 <P>Dumping a volume can be useful in several situations, including the
3087 <P><LI>You want to back it up to tape, perhaps by using a third-party backup
3088 utility. To facilitate this type of backup operation, the <B>vos
3089 dump</B> command can write to a named pipe. To learn about using the
3090 AFS Backup System instead, see <A HREF="auagd011.htm#HDRWQ333">Configuring the AFS Backup System</A> and <A HREF="auagd012.htm#HDRWQ382">Backing Up and Restoring AFS Data</A>.
3091 <P><LI>You are removing the volume from your cell (perhaps because its owner is
3092 leaving your cell). The <B>vos dump</B> command enables you to
3093 create a copy for safekeeping without incurring the overhead of the Backup
3094 System. For complete instructions on removing a volume, see <A HREF="#HDRWQ320">Removing Volumes and their Mount Points</A>.
3095 <P><LI>You want to create a copy of the volume for safekeeping on a non-AFS
3096 server partition, perhaps while you move the actual volume to another machine
3097 or perform maintenance tasks on the partition that houses the volume.
3098 <P><LI>You need to replace a corrupted read/write volume. If an
3099 uncorrupted read-only or backup version of the volume exists, dump it and
3100 restore the data into the read/write volume, overwriting the corrupted
3102 <P><LI>You want to copy or transfer the contents of the volume to another
3103 cell. You cannot use the <B>vos move</B> command, because AFS
3104 supports volume moves only between file server machines that belong to the
3106 <P><LI>You want to have another read/write copy of the volume's
3107 contents. The second volume must have a different name than the
3108 original one. If you want the contents of the two volumes to remain
3109 identical, you must update them both manually. AFS provides no facility
3110 for keeping read/write volumes synchronized in this way.
3111 <P><LI>You want a copy of only the files and directories in the volume with
3112 modification time stamps after a certain date. The <B>vos dump</B>
3113 command can create an incremental dump file as described in Step <A HREF="#LIWQ326">3</A> of the following instructions.
3115 <A NAME="IDX6767"></A>
3116 <A NAME="IDX6768"></A>
3117 <A NAME="IDX6769"></A>
3118 <P>You can use the <B>vos dump</B> command to create a <I>full
3119 dump</I>, which contains the complete contents of the volume at the time you
3120 issue the command, or an <I>incremental dump</I>, which contains only
3121 those files and directories with modification timestamps (as displayed by the
3122 <B>ls -l</B> command) that are later than a date and time you
3123 specify. See Step <A HREF="#LIWQ326">3</A> of the following instructions.
3124 <P>Dumping a volume does not change its VLDB entry or permanently affect its
3125 status on the file server machine, but the volume's contents are
3126 inaccessible during the dump operation. To avoid interrupting access to
3127 the volume, it is generally best to dump the volume's backup version,
3128 just after using the <B>vos backup</B> or <B>vos backupsys</B> command
3129 to create a new backup version.
3130 <P>If you do not provide a filename into which to write the dump, the <B>vos
3131 dump</B> command directs the output to the standard output stream.
3132 You can pipe it directly to the <B>vos restore</B> command if you
3134 <P>Because a volume dump file is in ASCII format, you can read its contents
3135 using a text editor or a command such as the <B>cat</B> command.
3136 However, dump files sometimes contain special characters that do not have
3137 alphanumeric correlates, which can cause problems for some display
3139 <P>By default, the <B>vos</B> command interpreter consults the Volume
3140 Location Database (VLDB) to learn the volume's location, so the
3141 <B>-server</B> and <B>-partition</B> arguments are not
3142 required. If the <B>-id</B> argument identifies a read-only volume
3143 that resides at multiple sites, then the command dumps the version from just
3144 one of them (normally, the one listed first in the volume's VLDB entry as
3145 reported by the <B>vos examine</B> or <B>vos listvldb</B>
3146 command). To dump the read-only volume from a particular site, use the
3147 <B>-server</B> and <B>-partition</B> arguments to specify the
3148 site. To bypass the VLDB lookup entirely, provide a volume ID number
3149 (rather than a volume name) as the value for the <B>-id</B> argument,
3150 along with the <B>-server</B> and <B>-partition</B> arguments.
3151 This makes it possible to dump a volume for which there is no VLDB
3153 <A NAME="IDX6770"></A>
3154 <A NAME="IDX6771"></A>
3155 <P><H3><A NAME="Header_260" HREF="auagd002.htm#ToC_260">To dump a volume</A></H3>
3157 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
3158 file. If necessary, issue the <B>bos listusers</B> command, which
3159 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
3160 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
3162 <P><LI>Verify that you have the permissions necessary to create the dump
3163 file. If placing it in AFS, you must have the <B>i</B>
3164 (<B>insert</B>) permission on the ACL of the file's directory.
3165 If necessary, issue the <B>fs listacl</B> command, which is fully
3166 described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
3167 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
3169 <P>Members of the <B>system:administrators</B> group always
3170 implicitly have the <B>a</B> (<B>administer</B>) and by default also
3171 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
3172 <B>fs setacl</B> command to grant other rights as necessary.
3173 <P><LI><A NAME="LIWQ326"></A>Issue the <B>vos dump</B> command to dump the
3176 % <B>vos dump -id</B> <<VAR>volume name or ID</VAR>> [<B>-time</B> <<VAR>dump from time</VAR>>] [<B>-file</B> <<VAR>arg</VAR>>] [<B>-server</B> <<VAR>server</VAR>>] [<B>-partition</B> <<VAR>partition</VAR>>]
3182 </B><DD>Identifies the volume to be dumped by its complete name or volume ID
3183 number. If you want to dump the read-only or backup version, specify
3184 its volume ID number or add the appropriate extension
3185 (<B>.readonly</B> or <B>.backup</B>) to the name.
3186 <P>To bypass the normal VLDB lookup of the volume's location, provide the
3187 volume ID number and combine this argument with the <B>-server</B> and
3188 <B>-partition</B> arguments.
3190 </B><DD>Specifies whether the dump is full or incremental. Omit this
3191 argument to create a full dump, or provide one of three acceptable
3194 <P><LI>The value <B>0</B> (zero) to create a full dump.
3195 <P><LI>A date in the format
3196 <I>mm</I><B>/</B><I>dd</I><B>/</B><I>yyyy</I> (month, day
3197 and year) to create an incremental dump that includes only files and
3198 directories with modification timestamps later than midnight (12:00
3199 a.m.) on the indicated date. Valid values for the year
3200 range from <B>1970</B> to <B>2037</B>; higher values are not
3201 valid because the latest possible date in the standard UNIX representation is
3202 in 2038. The command interpreter automatically reduces later dates to
3203 the maximum value. An example is <B>01/13/1999</B>.
3204 <P><LI>A date and time in the format
3205 <B>"</B><I>mm</I><B>/</B><I>dd</I><B>/</B><I>yyyy</I>
3206 <I>hh</I><B>:</B><I>MM</I><B>"</B> to create an
3207 incremental dump that includes only files and directories with modification
3208 timestamps later than the specified date and time. The date format is
3209 the same as for a date alone. Express the time as hours and minutes
3210 (<I>hh</I>:<I>MM</I>) in 24-hour format (for example,
3211 <B>20:30</B> is 8:30 p.m.). Surround the
3212 entire expression with double quotes (" ") because it contains a space.
3213 An example is <B>"01/13/1999 22:30"</B>.
3216 </B><DD>Specifies the pathname of the file to which to write the dump. The
3217 file can be in AFS, but not in the volume being dumped. A partial
3218 pathname is interpreted relative to the current working directory. Omit
3219 this argument to direct the dump to the standard output stream.
3221 </B><DD>Specifies the file server machine on which the volume resides.
3222 Provide the <B>-partition</B> argument along with this one.
3223 <P><DT><B>-partition
3224 </B><DD>Specifies the partition on which the volume resides. Provide the
3225 <B>-server</B> argument along with this one.
3228 <P><H3><A NAME="Header_261" HREF="auagd002.htm#ToC_261">About Restoring Volumes</A></H3>
3229 <A NAME="IDX6772"></A>
3230 <A NAME="IDX6773"></A>
3231 <P>Although you can dump any of the three types of volumes (read/write,
3232 read-only, or backup), you can restore a dump file to the file system only as
3233 a read/write volume, using the <B>vos restore</B> command. The
3234 command automatically translates the dump file's contents from ASCII back
3235 into the volume format appropriate for the file server machine that stores the
3236 restored version. As with the <B>vos dump</B> command, you can
3237 restore a dump file via a named pipe, which facilitates interoperation with
3238 third-party backup utilities.
3239 <P>You can restore the contents of a dump file in one of two basic
3240 ways. In either case, you must restore a full dump of the volume before
3241 restoring any incremental dumps. Any incremental dumps that you then
3242 restore must have been created after the full dump. If there is more
3243 than one incremental dump, you must restore them in the order they were
3246 <P><LI>You can restore volume data into a brand new volume with a new name and at
3247 a location that you specify. See <A HREF="#HDRWQ327">To restore a dump into a new volume and mount it</A>.
3248 <P>You can assign a volume ID number as you restore the volume, though it is
3249 best to have the Volume Server allocate a volume number automatically.
3250 The most common reason for specifying the volume ID is that a volume's
3251 VLDB entry has disappeared for some reason, but you know the former read/write
3252 volume ID number and want to reuse it.
3253 <P><LI>You can restore volume data into an existing volume (usually the one that
3254 was previously dumped), overwriting its current contents. This is
3255 convenient if the current contents are corrupted or otherwise incorrect,
3256 because it allows you to replace them with a coherent version from the past or
3257 from one of the volume's clones. See <A HREF="#HDRWQ329">To restore a dump file, overwriting an existing volume</A>.
3258 <P>Provide the <B>-overwrite</B> argument to preconfirm that you wish to
3259 overwrite the volume's contents, and to specify whether you are restoring
3260 a full or incremental dump. If you omit the <B>-overwrite</B>
3261 argument, the Volume Server generates the following prompt to confirm that you
3262 want to overwrite the existing volume with either a full (<B>f</B>) or
3263 incremental (<B>i</B>) dump:
3265 Do you want to do a full/incremental restore or abort? [fia](a):
3268 <P>If you pipe in the dump file via the standard input stream instead of using
3269 the <B>-file</B> argument to name it, you must include the
3270 <B>-overwrite</B> argument because there is nowhere for the Volume Server
3271 to display the prompt in this case.
3272 <P>You can move the volume to a new site as you overwrite it with a full dump,
3273 by using the <B>-server</B> and <B>-partition</B> arguments to specify
3274 the new site. You cannot move the volume when restoring an incremental
3277 <P>The <B>vos restore</B> command sets the restored volume's creation
3278 date in the volume header to the time of the restore operation, as reported in
3279 the <TT>Creation</TT> field in the output from the <B>vos examine</B>
3280 and <B>vos listvol</B> commands.
3281 <A NAME="IDX6774"></A>
3282 <A NAME="IDX6775"></A>
3283 <P><H3><A NAME="HDRWQ327" HREF="auagd002.htm#ToC_262">To restore a dump into a new volume and mount it</A></H3>
3285 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
3286 file. If necessary, issue the <B>bos listusers</B> command, which
3287 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
3288 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
3290 <P><LI>Verify that you have permissions needed to read the dump file and to mount
3291 the new volume. If the dump file resides in AFS, you need the
3292 <B>r</B> (<B>read</B>) permission on the ACL of its directory.
3293 You need the <B>i</B> (<B>insert</B>) and <B>a</B>
3294 (<B>administer</B>) permissions on the ACL of the directory where you are
3295 mounting the new volume. If necessary, issue the <B>fs listacl</B>
3296 command, which is fully described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
3297 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
3299 <P>Members of the <B>system:administrators</B> group always
3300 implicitly have the <B>a</B> (<B>administer</B>) and by default also
3301 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
3302 <B>fs setacl</B> command to grant other rights as necessary.
3303 <P><LI>Select a site (disk partition on a file server machine) for the new
3304 volume. If your cell groups different types of volumes onto different
3305 file server machines, that can guide your decision. It often makes
3306 sense to put the volume on the emptiest partition that meets your other
3307 criteria. To display how much space is available on a file server
3308 machine's partitions, use the <B>vos partinfo</B> command, which is
3309 described fully in <A HREF="#HDRWQ270">Creating Read/write Volumes</A>.
3311 % <B>vos partinfo</B> <<VAR>machine name</VAR>> [<<VAR>partition name</VAR>>]
3314 <P><LI><A NAME="LIWQ328"></A>Issue the <B>vos restore</B> command to create a new volume
3315 and restore the dump file into it. Type it on a single line; it
3316 appears on multiple lines here only for legibility.
3318 % <B>vos restore</B> <<VAR>machine name</VAR>> <<VAR>partition name</VAR>> \
3319 <<VAR>name of volume to be restored</VAR>> \
3320 [<B>-file</B> <<VAR>dump file</VAR>>] [<B>-id</B> <<VAR>volume ID</VAR>>]
3326 </B><DD>Is the shortest acceptable abbreviation of <B>restore</B>.
3327 <P><DT><B><VAR>machine name</VAR>
3328 </B><DD>Names the file server machine on which to create the new volume.
3329 <P><DT><B><VAR>partition name</VAR>
3330 </B><DD>Names the partition on which to create the new volume.
3331 <P><DT><B><VAR>name of volume to be restored</VAR>
3332 </B><DD>Names the new read/write volume, which must not already have a VLDB
3333 entry. It can be up to 22 characters in length.
3335 </B><DD>Is the dump file to restore. Partial pathnames are interpreted with
3336 respect to the current working directory. Omit this argument if using a
3337 pipe to read in the dump file from the standard input stream.
3339 </B><DD>Specifies the new volume's ID number. It is appropriate only
3340 if you are restoring a volume that no longer exists and want to use the volume
3341 ID number it had previously.
3343 <A NAME="IDX6776"></A>
3344 <A NAME="IDX6777"></A>
3345 <P><LI>Issue the <B>fs mkmount</B> command to mount the new volume, making
3346 its contents accessible. Complete instructions appear in <A HREF="#HDRWQ297">To create a regular or read/write mount point</A>.
3348 % <B>fs mkmount</B> <<VAR>directory</VAR>> <<VAR>volume name</VAR>>
3351 <P><LI><B>(Optional)</B> Issue the <B>fs lsmount</B> command to verify
3352 that the mount point refers to the correct volume. Complete
3353 instructions appear in <A HREF="#HDRWQ296">To display a mount point</A>.
3355 % <B>fs lsmount</B> <<VAR>directory</VAR>>
3359 <A NAME="IDX6778"></A>
3360 <A NAME="IDX6779"></A>
3361 <P><H3><A NAME="HDRWQ329" HREF="auagd002.htm#ToC_263">To restore a dump file, overwriting an existing volume</A></H3>
3363 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
3364 file. If necessary, issue the <B>bos listusers</B> command, which
3365 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
3366 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
3368 <P><LI>Verify that you have permissions needed to read the dump file. If
3369 it resides in AFS, you need the <B>r</B> (<B>read</B>) permission on
3370 the ACL of its directory. If necessary, issue the <B>fs listacl</B>
3371 command, which is fully described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
3372 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
3374 <P>Members of the <B>system:administrators</B> group always
3375 implicitly have the <B>a</B> (<B>administer</B>) and by default also
3376 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
3377 <B>fs setacl</B> command to grant other rights as necessary.
3378 <P><LI>Restore the contents of the dump file into a read/write volume,
3379 overwriting the current contents. The volume retains its current volume
3380 ID number. Type it on a single line; it appears on multiple lines
3381 here only for legibility.
3383 % <B>vos restore</B> <<VAR>machine name</VAR>> <<VAR>partition name</VAR>> \
3384 <<VAR>name of volume to be restored</VAR>> \
3385 [<B>-file</B> <<VAR>dump file</VAR>>] \
3386 <B>-overwrite</B> <<B>full</B> | <B>incremental</B>>
3392 </B><DD>Is the shortest acceptable abbreviation of <B>restore</B>.
3393 <P><DT><B><VAR>machine name</VAR>
3394 </B><DD>Names the file server machine where the volume already exists, or the
3395 machine to which to move it. In the latter case, the value for the
3396 <B>-overwrite</B> argument must be <B>full</B>.
3397 <P><DT><B><VAR>partition name</VAR>
3398 </B><DD>Names the partition where the volume already exists, or the partition to
3399 which to move it. In the latter case, the value for the
3400 <B>-overwrite</B> argument must be <B>full</B>.
3401 <P><DT><B><VAR>name of volume to be restored</VAR>
3402 </B><DD>Names the read/write volume to overwrite with the contents of the dump
3405 </B><DD>Is the dump file to restore. Partial pathnames are interpreted with
3406 respect to the current working directory. Omit this argument if using a
3407 pipe to read in the dump file from the standard input stream; in this
3408 case, you must provide the <B>-overwrite</B> argument.
3409 <P><DT><B>-overwrite
3410 </B><DD>Preconfirms that you want to overwrite the existing volume and specifies
3411 which type of dump file you are restoring. Provide one of the following
3414 <P><LI><B>f</B> or <B>full</B> if restoring a full dump file
3415 <P><LI><B>i</B> or <B>incremental</B> if restoring an incremental dump
3416 file. This value is not acceptable if you are moving the volume while
3418 <P><LI><B>a</B> to terminate the restore operation
3421 <P><LI>If the volume is replicated, issue the <B>vos release</B> command to
3422 release the newly restored contents to read-only sites. Complete
3423 instructions appear in <A HREF="#HDRWQ277">Replicating Volumes (Creating Read-only Volumes)</A>.
3425 % <B>vos release</B> <<VAR>volume name or ID</VAR>>
3428 <P><LI>Issue the <B>vos backup</B> command to create a new backup version of
3429 the volume. Complete instructions appear in <A HREF="#HDRWQ286">Creating Backup Volumes</A>.
3431 % <B>vos backup</B> <<VAR>volume name or ID</VAR>>
3435 <HR><H2><A NAME="HDRWQ330" HREF="auagd002.htm#ToC_264">Renaming Volumes</A></H2>
3436 <A NAME="IDX6780"></A>
3437 <A NAME="IDX6781"></A>
3438 <A NAME="IDX6782"></A>
3439 <A NAME="IDX6783"></A>
3440 <P>You can use the <B>vos rename</B> command to rename a volume.
3441 For example, it is appropriate to rename a user's home volume if you use
3442 the <B>user.</B><VAR>username</VAR> convention for user volume names
3443 and you change the username. (For complete instructions for changing
3444 usernames, see <A HREF="auagd018.htm#HDRWQ708">Changing Usernames</A>.)
3446 <A NAME="IDX6784"></A>
3447 <A NAME="IDX6785"></A>
3448 <A NAME="IDX6786"></A>
3449 The <B>vos rename</B> command accepts only read/write volume names, but
3450 automatically changes the names of the associated read-only and backup
3451 volumes. As directed in the following instructions, you need to replace
3452 the volume's current mount point with a new one that reflects the name
3454 <A NAME="IDX6787"></A>
3455 <A NAME="IDX6788"></A>
3456 <P><H3><A NAME="HDRWQ331" HREF="auagd002.htm#ToC_265">To rename a volume</A></H3>
3458 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
3459 file. If necessary, issue the <B>bos listusers</B> command, which
3460 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
3461 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
3463 <P><LI>Verify that you have the <B>a</B> (<B>administer</B>),
3464 <B>d</B> (<B>delete</B>), and <B>i</B> (<B>insert</B>) access
3465 permissions for the directory in which you are replacing the volume's
3466 mount point. If necessary, issue the <B>fs listacl</B> command,
3467 which is fully described in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
3468 <PRE> % <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
3470 <P>Members of the <B>system:administrators</B> group always
3471 implicitly have the <B>a</B> (<B>administer</B>) and by default also
3472 the <B>l</B> (<B>lookup</B>) permission on every ACL and can use the
3473 <B>fs setacl</B> command to grant other rights as necessary.
3474 <P><LI><A NAME="LIVOL-REN"></A>Issue the <B>vos rename</B> command to rename the
3477 % <B>vos rename</B> <<VAR>old volume name</VAR>> <<VAR>new volume name</VAR>>
3483 </B><DD>Is the shortest acceptable abbreviation of <B>rename</B>.
3484 <P><DT><B><VAR>old volume name</VAR>
3485 </B><DD>Is the current name of a read/write volume.
3486 <P><DT><B><VAR>new volume name</VAR>
3487 </B><DD>Is the new name for the volume. It cannot be more than 22
3488 characters in length.
3490 <P>If there is no Volume Location Database (VLDB) entry for the specified
3491 current volume name, the command fails with the following error message:
3494 vos: Could not find entry for volume <VAR>old_volume_name</VAR>.
3497 <A NAME="IDX6789"></A>
3498 <A NAME="IDX6790"></A>
3499 <P><LI>Issue the <B>fs rmmount</B> command to remove the mount point that
3500 refers to the volume's old name. Complete instructions appear in <A HREF="#HDRWQ300">To remove a mount point</A>.
3502 % <B>fs rmmount</B> <<VAR>directory</VAR>>
3505 <A NAME="IDX6791"></A>
3506 <A NAME="IDX6792"></A>
3507 <P><LI>Issue the <B>fs mkmount</B> to create a mount point that indicates the
3508 volume's new name. Complete instructions appear in <A HREF="#HDRWQ297">To create a regular or read/write mount point</A>.
3510 % <B>fs mkmount</B> <<VAR>directory</VAR>> <<VAR>volume name</VAR>> [<B>-rw</B>]
3514 <HR><H2><A NAME="HDRWQ332" HREF="auagd002.htm#ToC_266">Unlocking and Locking VLDB Entries</A></H2>
3515 <P>As detailed in <A HREF="#HDRWQ312">Synchronizing the VLDB and Volume Headers</A>, The Volume Location (VL) Server locks the
3516 Volume Location Database (VLDB) entry for a volume before the Volume Server
3517 executes any operation on it. No other operation can affect a volume
3518 with a locked VLDB entry, so the lock prevents the inconsistency or corruption
3519 that can result from multiple simultaneous operations on a volume.
3520 <A NAME="IDX6793"></A>
3521 <A NAME="IDX6794"></A>
3522 <A NAME="IDX6795"></A>
3523 <A NAME="IDX6796"></A>
3524 <A NAME="IDX6797"></A>
3525 <A NAME="IDX6798"></A>
3526 <P>To verify that a VLDB entry is locked, issue the <B>vos listvldb</B>
3527 command as described in <A HREF="#HDRWQ303">To display VLDB entries</A>. The command has a <B>-locked</B> flag that
3528 displays locked entries only. If the VLDB entry is locked, the string
3529 <TT>Volume is currently LOCKED</TT> appears on the last line of the
3530 volume's output.
3531 <P>To lock a VLDB entry yourself, use the <B>vos lock</B> command.
3532 This is useful when you suspect something is wrong with a volume and you want
3533 to prevent any changes to it while you are investigating the problem.
3534 <P>To unlock a locked VLDB entry, issue the <B>vos unlock</B> command,
3535 which unlocks a single VLDB entry, or the <B>vos unlockvldb</B> command,
3536 which unlocks potentially many entries. This is useful when a volume
3537 operation fails prematurely and leaves a VLDB entry locked, preventing you
3538 from acting to correct the problems resulting from the failure.
3539 <A NAME="IDX6799"></A>
3540 <A NAME="IDX6800"></A>
3541 <P><H3><A NAME="Header_267" HREF="auagd002.htm#ToC_267">To lock a VLDB entry</A></H3>
3543 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
3544 file. If necessary, issue the <B>bos listusers</B> command, which
3545 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
3546 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
3548 <P><LI>Issue the <B>vos lock</B> to lock the entry.
3550 % <B>vos lock</B> <<VAR>volume name or ID</VAR>>
3556 </B><DD>Is the shortest acceptable abbreviation of <B>lock</B>.
3557 <P><DT><B><VAR>volume name or ID</VAR>
3558 </B><DD>Identifies the volume to be locked, either by its complete name or volume
3559 ID number. It can be any of the three versions of the volume.
3562 <A NAME="IDX6801"></A>
3563 <A NAME="IDX6802"></A>
3564 <P><H3><A NAME="Header_268" HREF="auagd002.htm#ToC_268">To unlock a single VLDB entry</A></H3>
3566 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
3567 file. If necessary, issue the <B>bos listusers</B> command, which
3568 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
3569 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
3571 <P><LI>Issue the <B>vos unlock</B> command to unlock the entry.
3572 <PRE> % <B>vos unlock</B> <<VAR>volume name or ID</VAR>>
3578 </B><DD>Must be typed in full.
3579 <P><DT><B><VAR>volume name or ID</VAR>
3580 </B><DD>Identifies the volume to be unlocked, either by its complete name or
3581 volume ID number. It can be any of the three versions of the
3585 <A NAME="IDX6803"></A>
3586 <A NAME="IDX6804"></A>
3587 <P><H3><A NAME="Header_269" HREF="auagd002.htm#ToC_269">To unlock multiple VLDB entries</A></H3>
3589 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
3590 file. If necessary, issue the <B>bos listusers</B> command, which
3591 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
3592 <PRE> % <B>bos listusers</B> <<VAR>machine name</VAR>>
3594 <P><LI>Issue the <B>vos unlockvldb</B> command to unlock the desired
3597 % <B>vos unlockvldb</B> [<<VAR>machine name</VAR>>] [<<VAR>partition name</VAR>>]
3603 </B><DD>Is the shortest acceptable abbreviation of <B>unlockvldb</B>.
3604 <P><DT><B><VAR>machine name</VAR>
3605 </B><DD>Specifies a file server machine. Provide this argument alone to
3606 unlock all VLDB entries that mention the machine in a site definition.
3607 Omit both this argument and the <VAR>partition name</VAR> argument to unlock all
3609 <P><DT><B><VAR>partition name</VAR>
3610 </B><DD>Specifies a partition. Provide this argument alone to unlock all
3611 VLDB entries that mention the partition (on any machine) in a site
3612 definition. Omit both this argument and the <VAR>machine name</VAR>
3613 argument to unlock all VLDB entries.
3616 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd009.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auagd011.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
3617 <!-- Begin Footer Records ========================================== -->
3619 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
3621 <!-- End Footer Records ============================================ -->
3622 <A NAME="Bot_Of_Page"></A>
git://git.openafs.org / openafs.git / blob