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