doc: vos manpage fixes
[openafs.git] / doc / man-pages / pod1 / vos_listvol.pod.in
1 =head1 NAME
2
3 vos_listvol - Displays information from a volume header
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos listvol> S<<< B<-server> <I<machine name>> >>>
11     S<<< [B<-partition> <I<partition name>>] >>>
12     [B<-fast>] [B<-long>] [B<-quiet>]
13     [B<-extended>] [B<-format>]
14     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
15     [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
16     S<<< [B<-config> <I<config directory>>] >>>
17     [B<-help>]
18
19 B<vos listvo> S<<< B<-s> <I<machine name>> >>>
20     S<<< [B<-p> <I<partition name>>] >>>
21     [B<-fa>] [-lon] [B<-q>] [B<-ex>] [B<-fo>]
22     S<<< [B<-c> <I<cell name>>] >>>
23     [B<-noa>] [B<-loc>] [B<-v>] [B<-en>] [B<-nor>]
24     S<<< [B<-co> <I<config directory>>] >>>
25     [B<-h>]
26
27 =for html
28 </div>
29
30 =head1 DESCRIPTION
31
32 The B<vos listvol> command formats and displays the following information
33 from the volume header of each specified volume: volume name, volume ID,
34 volume type, size, and status at the server. The actual information
35 displayed depends on the combination of arguments supplied when the
36 command is issued. To display volume header information for various
37 numbers of volumes, combine the command's arguments as indicated:
38
39 =over 4
40
41 =item *
42
43 For every volume on a file server machine, specify the machine's name with
44 the B<-server> argument.
45
46 =item *
47
48 For every volume at a particular site, combine the B<-server> argument
49 with the B<-partition> argument.
50
51 =back
52
53 To display the Volume Location Database (VLDB) entry for one or more
54 volumes, use the B<vos listvldb> command. To display both the VLDB entry
55 and the volume header for a single volume, use the B<vos examine> command.
56
57 =head1 OPTIONS
58
59 =over 4
60
61 =item B<-server> <I<server name>>
62
63 Identifies the file server machine that houses volumes for which to
64 display the header. Provide the machine's IP address or its host name
65 (either fully qualified or using an unambiguous abbreviation). For
66 details, see L<vos(1)>.
67
68 This argument can be combined with the B<-partition> argument, as well as
69 the B<-fast>, B<-long>, or B<-extended> flag.
70
71 =item B<-partition> <I<partition name>>
72
73 Identifies the partition (on the file server machine specified by the
74 B<-server> argument) that houses volumes for which to display the
75 header. Provide the partition's complete name with preceding slash (for
76 example, F</vicepa>) or use one of the three acceptable abbreviated
77 forms. For details, see L<vos(1)>.
78
79 =item B<-fast>
80
81 Displays only the volume ID numbers of volumes stored at the site
82 specified by the B<-server>, and optionally B<-partition>, argument. Do
83 not combine this flag with the B<-extended> flag.
84
85 =item B<-long>
86
87 Displays more detailed information about each volume stored at the site
88 specified by the B<-server>, and optionally B<-partition>, argument. The
89 information includes the volume IDs of all three volume types associated
90 with the volume, and the read/write volume's quota, creation date and
91 update date.
92
93 =item B<-quiet>
94
95 Suppresses the lines that summarize the number of volumes listed and their
96 status, which otherwise appear at the beginning and end of the output when
97 the output includes more than one volume.
98
99 =item B<-extended>
100
101 Displays extensive statistics about access patterns for each volume stored
102 at the site specified by the B<-server>, and optionally B<-partition>,
103 argument. The statistics include the number of reads and writes to files
104 in the volume, and how recently files and directories have been updated by
105 their owners or other users. Do not combine this flag with the B<-fast>
106 flag.
107
108 =item B<-format>
109
110 Show information in a format suitable for machine parsing.
111
112 =include fragments/vos-common.pod
113
114 =back
115
116 =head1 OUTPUT
117
118 The output is ordered alphabetically by volume name and by default
119 provides the following information on a single line for each volume:
120
121 =over 4
122
123 =item *
124
125 Name
126
127 =item *
128
129 Volume ID number
130
131 =item *
132
133 Type (the flag is C<RW> for read/write, C<RO> for read-only, C<BK> for
134 backup)
135
136 =item *
137
138 Size in kilobytes (C<1024> equals a megabyte)
139
140 =item *
141
142 Number of files in the volume, if the B<-extended> flag is provided
143
144 =item *
145
146 Status on the file server machine, which is one of the following:
147
148 =over 4
149
150 =item On-line
151
152 The volume is completely accessible to Cache Managers.
153
154 =item Off-line
155
156 The volume is not accessible to Cache Managers, but does not seem to be
157 corrupted. This status appears while a volume is being dumped, for
158 example.
159
160 =item Off-line**needs salvage**
161
162 The volume is not accessible to Cache Managers, because it seems to be
163 corrupted. Use the B<bos salvage> or B<salvager> command to repair the
164 corruption.
165
166 =back
167
168 =back
169
170 If the following message appears instead of the previously listed
171 information, it indicates that a volume is not accessible to Cache
172 Managers or the B<vos> command interpreter, for example because a clone is
173 being created.
174
175    **** Volume <volume_ID> is busy ****
176
177 If the following message appears instead of the previously listed
178 information, it indicates that the File Server is unable to attach the
179 volume, perhaps because it is seriously corrupted. The F<FileLog> and
180 F<VolserLog> log files in the F</usr/afs/logs> directory on the file
181 server machine possibly provide additional information; use the B<bos
182 getlog> command to display them.
183
184    **** Could not attach volume <volume_ID> ****
185
186 The information about individual volumes is bracketed by summary
187 lines. The first line of output specifies the number of volumes in the
188 listing. The last line of output summarizes the number of volumes that are
189 online, offline, and busy. These lines do not appear if the B<-quiet> flag
190 is used.
191
192 If the B<-fast> flag is added, the output displays only the volume ID
193 number of each volume, arranged in increasing numerical order. The final
194 line (which summarizes the number of online, offline, and busy volumes) is
195 omitted.
196
197 If the B<-long> flag is included, the output for each volume includes all
198 of the information in the default listing plus the following. Each item in
199 this list corresponds to a separate line of output:
200
201 =over 4
202
203 =item *
204
205 The file server machine and partition that house the volume, as determined
206 by the command interpreter as the command runs, rather than derived from the
207 VLDB or the volume header.
208
209 =item *
210
211 The volume ID numbers associated with the various versions of the volume:
212 read/write (C<RWrite>), read-only (C<ROnly>), backup (C<Backup>), and
213 ReleaseClone (C<RClone>). One of them matches the volume ID number that
214 appears on the first line of the volume's output. If the value in the
215 C<RWrite>, C<ROnly>, or C<Backup> field is C<0> (zero), there is no volume
216 of that type. If there is currently no ReleaseClone, the C<RClone> field
217 does not appear at all.
218
219 =item *
220
221 The maximum space quota allotted to the read/write copy of the volume,
222 expressed in kilobyte blocks in the C<MaxQuota> field.
223
224 =item *
225
226 The date and time the volume was created, in the C<Creation> field. If the
227 volume has been restored with the B<backup diskrestore>, B<backup
228 volrestore>, or B<vos restore> command, this is the restore time.
229
230 =item *
231
232 The date and time when the contents of the volume last changed, in the
233 C<Last Update> field. For read-only and backup volumes, it matches the
234 timestamp in the C<Creation> field.
235
236 =item *
237
238 The number of times the volume has been accessed for a fetch or store
239 operation since the later of the two following times:
240
241 =over 4
242
243 =item *
244
245 12:00 a.m. on the day the command is issued
246
247 =item *
248
249 The last time the volume changed location
250
251 =back
252
253 =back
254
255 If the B<-extended> flag is included, the output for each volume includes
256 all of the information reported with the B<-long> flag, plus two tables of
257 statistics:
258
259 =over 4
260
261 =item *
262
263 The table labeled C<Raw Read/Write Stats> table summarizes the number of
264 times the volume has been accessed for reading or writing.
265
266 =item *
267
268 The table labeled C<Writes Affecting Authorship> table contains
269 information on writes made to files and directories in the specified
270 volume.
271
272 =back
273
274 =head1 EXAMPLES
275
276 The following example shows the output for the F</vicepb> partition on the
277 file server machine C<fs2.example.com> when no flags are provided:
278
279    % vos listvol -server fs2.example.com -partition b
280    Total number of volumes on server fs2.example.com partition /vicepb : 66
281    sys                  1969534847 RW       1582 K On-line
282    sys.backup           1969535105 BK       1582 K On-line
283          .                   .     .         .   .    .
284          .                   .     .         .   .    .
285    user.pat             1969534536 RW      17518 K On-line
286    user.pat.backup      1969534538 BK      17537 K On-line
287    Total volumes onLine 66 ; Total volumes offLine 0 ;  Total busy 0
288
289 The following example shows the output when the B<-fast> flag is added:
290
291    % vos listvol -server fs2.example.com -partition b -fast
292    Total number of volumes on server fs2.example.com partition /vicepb : 66
293     1969516782
294     1969516784
295         .
296         .
297     1969535796
298
299 The following example shows two volumes from the output that appears when
300 the B<-long> flag is added:
301
302    % vos listvol -server fs2.example.com -partition b -long
303    Total number of volumes on server fs2.example.com partition /vicepb: 66
304          .                   .      .         .   .    .
305          .                   .      .         .   .    .
306    user.pat             1969534536 RW      17518 K On-line
307         fs2.example.com /vicepb
308         RWrite 1969534536 ROnly 0        Backup 1969534538
309         MaxQuota      20000 K
310         Creation    Mon Jun 12 09:02:25 1989
311         Last Update Thu May 20 17:39:34 1999
312         1573 accesses in the past day (i.e., vnode references)
313    user.pat.backup      1969534538 BK      17537 K On-line
314         fs2.example.com /vicepb
315         RWrite 1969534536 ROnly 0        Backup 1969534538
316         MaxQuota      20000 K
317         Creation    Tue Jun 13 04:37:59 1989
318         Last Update Wed May 19 06:37:59 1999
319         0 accesses in the past day (i.e., vnode references)
320           .                   .      .         .   .    .
321           .                   .      .         .   .    .
322    Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0
323
324 =head1 PRIVILEGE REQUIRED
325
326 None
327
328 =head1 SEE ALSO
329
330 L<backup_diskrestore(8)>,
331 L<backup_volrestore(8)>,
332 L<bos_getlog(8)>,
333 L<bos_salvage(8)>,
334 L<salvager(8)>,
335 L<vos(1)>,
336 L<vos_examine(1)>,
337 L<vos_listvldb(1)>,
338 L<vos_restore(1)>
339
340 =head1 COPYRIGHT
341
342 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
343
344 This documentation is covered by the IBM Public License Version 1.0.  It was
345 converted from HTML to POD by software written by Chas Williams and Russ
346 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.