Import Upstream version 1.8.5
[hcoop/debian/openafs.git] / doc / man-pages / pod1 / vos_examine.pod.in
CommitLineData
805e021f
CE
1=head1 NAME
2
3vos_examine - Shows volume header and VLDB entry information for a volume
4
5=head1 SYNOPSIS
6
7=for html
8<div class="synopsis">
9
10B<vos examine> S<<< B<-id> <I<volume name or ID>> >>> [B<-extended>]
11 [B<-format>] S<<< [B<-cell> <I<cell name>>] >>>
12 [B<-noauth>] [B<-localauth>] [B<-verbose>]
13 [B<-encrypt>] [B<-noresolve>]
14 S<<< [B<-config> <I<config directory>>] >>>
15 [B<-help>]
16
17B<vos e> S<<< B<-i> <I<volume name or ID>> >>> [B<-ex>] [B<-f>]
18 S<<< [B<-c> <I<cell name>>] >>>
19 [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>]
20 S<<< [B<-co> <I<config directory>>] >>>
21 [B<-h>]
22
23B<vos volinfo> S<<< B<-id> <I<volume name or ID>> >>> [B<-extended>]
24 [B<-format>] S<<< [B<-cell> <I<cell name>>] >>>
25 [B<-noauth>] [B<-localauth>] [B<-verbose>]
26 [B<-encrypt>] [B<-noresolve>]
27 S<<< [B<-config> <I<config directory>>] >>>
28 [B<-help>]
29
30B<vos v> S<<< B<-i> <I<volume name or ID>> >>> [B<-ex>] [B<-f>]
31 S<<< [B<-c> <I<cell name>>] >>>
32 [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>]
33 S<<< [B<-co> <I<config directory>>] >>>
34 [B<-h>]
35
36=for html
37</div>
38
39=head1 DESCRIPTION
40
41The B<vos examine> command formats and displays information from the
42Volume Location Database (VLDB) entry and the volume header of the volume
43specified by the B<-id> argument.
44
45To display the volume header only, use the B<vos listvol> command. To
46display information from the VLDB only, use the B<vos listvldb> command.
47
48=head1 CAUTIONS
49
50=include fragments/volsize-caution.pod
51
52=head1 OPTIONS
53
54=over 4
55
56=item B<-id> <I<volume name or ID>>
57
58Specifies either the complete name or volume ID number of the volume,
59which can be read/write, read-only, or backup.
60
61=item B<-extended>
62
63Displays statistics about read and write operations on files and
64directories in the volume.
65
66=item B<-format>
67
68Shows information in a format suitable for machine parsing.
69
70=include fragments/vos-common.pod
71
72=back
73
74=head1 OUTPUT
75
76The first seven lines of the output show information from the volume
77header and the remaining lines come from the VLDB. Each item in the
78following list corresponds to a line of output derived from the volume
79header.
80
81=over 4
82
83=item *
84
85Basic information about the specified volume (displayed on a single
86line):
87
88=over 4
89
90=item *
91
92Name
93
94=item *
95
96Volume ID number
97
98=item *
99
100Type (the flag is C<RW> for read/write, C<RO> for read-only, C<BK> for
101backup)
102
103=item *
104
105Size in kilobytes (C<1024> equals a megabyte)
106
107=item *
108
109Number of files in the volume, if the B<-extended> flag is provided
110
111=item *
112
113Status on the file server machine, which is one of the following:
114
115=over 4
116
117=item On-line
118
119The volume is completely accessible to Cache Managers.
120
121=item Off-line
122
123The volume is not accessible to Cache Managers, but does not seem to be
124corrupted. This status appears while a volume is being dumped, for
125example.
126
127=item Off-line**needs salvage**
128
129The volume is not accessible to Cache Managers, because it seems to be
130corrupted. Use the B<bos salvage> or B<salvager> command to repair the
131corruption.
132
133=back
134
135=back
136
137=item *
138
139The file server machine and partition that house the volume, as determined
140by the command interpreter as the command runs, rather than derived from
141the VLDB or the volume header.
142
143=item *
144
145The volume ID numbers associated with the various versions of the volume:
146read/write (C<RWrite>), read-only (C<ROnly>), backup (C<Backup>), and
147ReleaseClone (C<RClone>). One of them matches the volume ID number that
148appears on the first line of the volume's output. If the value in the
149C<RWrite>, C<ROnly>, or C<Backup> field is C<0> (zero), there is no volume
150of that type. If there is currently no ReleaseClone, the C<RClone> field
151does not appear at all.
152
153=item *
154
155The maximum space quota allotted to the read/write copy of the volume,
156expressed in kilobyte blocks in the C<MaxQuota> field.
157
158=item *
159
160The date and time the volume was created, in the C<Creation> field. If the
161volume has been restored with the B<backup diskrestore>, B<backup
162volrestore>, or B<vos restore> command, this is the restore time. For a
163read-only volume, this is the last release time.
164
165=item *
166
167The date and time this copy of this volume was created, in the C<Copy>
168field. This is the time when the volume was created on this server and
169partition. For read-only volumes, it is not updated by a release (unlike
170the Creation date). The copy date is not stored in volume dumps.
171
172=item *
173
174The date and time when the contents of the volume last changed, in the
175C<Last Update> field. For read-only and backup volumes, it matches the
176timestamp in the C<Creation> field.
177
178=item *
179
180The number of times the volume has been accessed for a fetch or store
181operation since the later of the two following times:
182
183=over 4
184
185=item *
186
18712:00 a.m. on the day the command is issued
188
189=item *
190
191The last time the volume changed location
192
193=back
194
195=back
196
197When the B<-extended> flag is included, two tables appear next:
198
199=over 4
200
201=item *
202
203The table labeled C<Raw Read/Write Stats> contains information on the
204number of reads (fetches) and writes (stores) made on the specified
205volume.
206
207=item *
208
209The table labeled C<Writes Affecting Authorship> contains information on
210writes made to files and directories in the specified volume.
211
212=back
213
214If the following message appears instead of the previously listed
215information, it indicates that a volume is not accessible to Cache
216Managers or the B<vos> command interpreter, for example because a clone is
217being created.
218
219 **** Volume <volume_ID> is busy ****
220
221If the following message appears instead of the previously listed
222information, it indicates that the File Server is unable to attach the
223volume, perhaps because it is seriously corrupted. The F<FileLog> and
224F<VolserLog> log files in the F</usr/afs/logs> directory on the file
225server machine possibly provide additional information; use the B<bos
226getlog> command to display them.
227
228 **** Could not attach volume <volume_ID> ****
229
230Following a blank line, information from the VLDB entry appears. Each
231item in this list corresponds to a separate line in the output:
232
233=over 4
234
235=item *
236
237The base (read/write) volume name. The read-only and backup versions have
238the same name with a C<.readonly> and C<.backup> extension, respectively.
239
240=item *
241
242The volume ID numbers allocated to the versions of the volume that
243actually exist, in fields labeled C<RWrite> for the read/write, C<ROnly>
244for the read-only, C<Backup> for the backup, and C<RClone> for the
245ReleaseClone. (If a field does not appear, the corresponding version of
246the volume does not exist.) The appearance of the C<RClone> field normally
247indicates that a release operation did not complete successfully; the
248C<Old release> and C<New release> flags often also appear on one or more
249of the site definition lines described just following.
250
251=item *
252
253The number of sites that house a read/write or read-only copy of the
254volume, following the string C<< number of sites -> >>.
255
256=item *
257
258A line for each site that houses a read/write or read-only copy of the
259volume, specifying the file server machine, partition, and type of volume
260(C<RW> for read/write or C<RO> for read-only). If a backup version exists,
261it is understood to share the read/write site. Several flags can appear
262with a site definition:
263
264=over 4
265
266=item Not released
267
268Indicates that the vos release command has not been issued since the B<vos
269addsite> command was used to define the read-only site.
270
271=item Old release
272
273Indicates that a vos release command did not complete successfully,
274leaving the previous, obsolete version of the volume at this site.
275
276=item New release
277
278Indicates that a vos release command did not complete successfully, but
279that this site did receive the correct new version of the volume.
280
281=back
282
283=item *
284
285If the VLDB entry is locked, the string C<Volume is currently LOCKED>, as
286well as (in OpenAFS 1.5.75 and later) one or more of the following strings:
287
288=over 4
289
290=item Volume is locked for a move operation
291
292Indicates that the volume was locked due to a B<vos move> or a B<vos
293convertROtoRW> command.
294
295=item Volume is locked for a release operation
296
297Indicates that the volume was locked due to a B<vos release> command.
298
299=item Volume is locked for a backup operation
300
301Indicates that the volume was locked due to a B<vos backup> command.
302
303=item Volume is locked for a delete/misc operation
304
305Indicates that the volume was locked due to a B<vos delentry>, B<vos
306addsite>, B<vos remsite>, B<vos changeloc>, B<vos syncvldb>, B<vos
307syncserv>, B<vos rename>, or B<vos lock> command.
308
309=item Volume is locked for a dump/restore operation
310
311Indicates that the volume was locked due to a B<vos dump> or B<vos restore>
312command.
313
314=back
315
316=back
317
318For further discussion of the C<New release> and C<Old release> flags, see
319L<vos_release(1)>.
320
321=head1 EXAMPLES
322
323The following example shows output for the Example Corporation volume called
324C<usr> with two read-only replication sites (this volume is mounted at the
325F</afs/example.com/usr> directory). For the sake of illustration, the output
326shows the volume as locked.
327
328 % vos examine usr
329 usr 536870981 RW 3459 K On-line
330 fs2.example.com /vicepb
331 RWrite 5360870981 ROnly 536870982 Backup 536870983
332 MaxQuota 40000 K
333 Creation Mon Jun 12 15:22:06 1989
334 Copy Mon Jun 12 15:22:06 1989
335 Last Update Fri Jun 16 09:34:35 1989
336 5719 accesses in the past day (i.e., vnode references)
337 RWrite: 5360870981 ROnly: 536870982 Backup: 536870983
338 number of sites -> 3
339 server fs1.example.com partition /vicepa RO Site
340 server fs3.example.com partition /vicepa RO Site
341 server fs2.example.com partition /vicepb RW Site
342 Volume is currently LOCKED
343
344The following example shows the output for the volume C<user.terry> using
345the B<-extended> flag. The volume has no read-only replication sites.
346
347 % vos examine -id user.terry -extended
348 user.terry 354287190 RW 2302 K used 119 files On-line
349 fs4.example.com /vicepc
350 RWrite 354287190 ROnly 0 Backup 354287192
351 MaxQuota 5000 K
352 Creation Wed Nov 25 17:38:57 1992
353 Copy Wed Nov 25 17:38:57 1992
354 Last Update Tue Dec 15 10:46:20 1992
355 598 accesses in the past day (i.e., vnode references)
356 Raw Read/Write Stats
357 |-------------------------------------------|
358 | Same Network | Diff Network |
359 |----------|----------|----------|----------|
360 | Total | Auth | Total | Auth |
361 |----------|----------|----------|----------|
362 Reads | 55 | 55 | 38 | 38 |
363 Writes | 95 | 95 | 0 | 0 |
364 |-------------------------------------------|
365 Writes Affecting Authorship
366 |-------------------------------------------|
367 | File Authorship | Directory Authorship|
368 |----------|----------|----------|----------|
369 | Same | Diff | Same | Diff |
370 |----------|----------|----------|----------|
371 0-60 sec | 38 | 0 | 21 | 1 |
372 1-10 min | 2 | 0 | 7 | 0 |
373 10min-1hr | 0 | 0 | 1 | 0 |
374 1hr-1day | 1 | 0 | 5 | 1 |
375 1day-1wk | 0 | 0 | 0 | 0 |
376 > 1wk | 0 | 0 | 0 | 0 |
377 |-------------------------------------------|
378 RWrite: 354287190 Backup: 354287192
379 number of sites -> 1
380 server fs4.example.com partition /vicepc RW Site
381
382=head1 PRIVILEGE REQUIRED
383
384None
385
386=head1 SEE ALSO
387
388L<backup_diskrestore(8)>,
389L<backup_volrestore(8)>,
390L<bos_getlog(8)>,
391L<bos_salvage(8)>,
392L<salvager(8)>,
393L<vos(1)>,
394L<vos_listvol(1)>,
395L<vos_listvldb(1)>,
396L<vos_release(1)>,
397L<vos_restore(1)>
398
399=head1 COPYRIGHT
400
401IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
402
403This documentation is covered by the IBM Public License Version 1.0. It was
404converted from HTML to POD by software written by Chas Williams and Russ
405Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.