doc: Make all vos pages =include common options
[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 =include fragments/vos-common.pod
71
72 =back
73
74 =head1 OUTPUT
75
76 The first seven lines of the output show information from the volume
77 header and the remaining lines come from the VLDB. Each item in the
78 following list corresponds to a line of output derived from the volume
79 header.
80
81 =over 4
82
83 =item *
84
85 Basic information about the specified volume (displayed on a single
86 line):
87
88 =over 4
89
90 =item *
91
92 Name
93
94 =item *
95
96 Volume ID number
97
98 =item *
99
100 Type (the flag is C<RW> for read/write, C<RO> for read-only, C<BK> for
101 backup)
102
103 =item *
104
105 Size in kilobytes (C<1024> equals a megabyte)
106
107 =item *
108
109 Number of files in the volume, if the B<-extended> flag is provided
110
111 =item *
112
113 Status on the file server machine, which is one of the following:
114
115 =over 4
116
117 =item On-line
118
119 The volume is completely accessible to Cache Managers.
120
121 =item Off-line
122
123 The volume is not accessible to Cache Managers, but does not seem to be
124 corrupted. This status appears while a volume is being dumped, for
125 example.
126
127 =item Off-line**needs salvage**
128
129 The volume is not accessible to Cache Managers, because it seems to be
130 corrupted. Use the B<bos salvage> or B<salvager> command to repair the
131 corruption.
132
133 =back
134
135 =back
136
137 =item *
138
139 The file server machine and partition that house the volume, as determined
140 by the command interpreter as the command runs, rather than derived from
141 the VLDB or the volume header.
142
143 =item *
144
145 The volume ID numbers associated with the various versions of the volume:
146 read/write (C<RWrite>), read-only (C<ROnly>), backup (C<Backup>), and
147 ReleaseClone (C<RClone>). One of them matches the volume ID number that
148 appears on the first line of the volume's output. If the value in the
149 C<RWrite>, C<ROnly>, or C<Backup> field is C<0> (zero), there is no volume
150 of that type. If there is currently no ReleaseClone, the C<RClone> field
151 does not appear at all.
152
153 =item *
154
155 The maximum space quota allotted to the read/write copy of the volume,
156 expressed in kilobyte blocks in the C<MaxQuota> field.
157
158 =item *
159
160 The date and time the volume was created, in the C<Creation> field. If the
161 volume has been restored with the B<backup diskrestore>, B<backup
162 volrestore>, or B<vos restore> command, this is the restore time. For a
163 read-only volume, this is the last release time.
164
165 =item *
166
167 The date and time this copy of this volume was created, in the C<Copy>
168 field.  This is the time when the volume was created on this server and
169 partition.  For read-only volumes, it is not updated by a release (unlike
170 the Creation date).  The copy date is not stored in volume dumps.
171
172 =item *
173
174 The date and time when the contents of the volume last changed, in the
175 C<Last Update> field. For read-only and backup volumes, it matches the
176 timestamp in the C<Creation> field.
177
178 =item *
179
180 The number of times the volume has been accessed for a fetch or store
181 operation since the later of the two following times:
182
183 =over 4
184
185 =item *
186
187 12:00 a.m. on the day the command is issued
188
189 =item *
190
191 The last time the volume changed location
192
193 =back
194
195 =back
196
197 When the B<-extended> flag is included, two tables appear next:
198
199 =over 4
200
201 =item *
202
203 The table labeled C<Raw Read/Write Stats> contains information on the
204 number of reads (fetches) and writes (stores) made on the specified
205 volume.
206
207 =item *
208
209 The table labeled C<Writes Affecting Authorship> contains information on
210 writes made to files and directories in the specified volume.
211
212 =back
213
214 If the following message appears instead of the previously listed
215 information, it indicates that a volume is not accessible to Cache
216 Managers or the B<vos> command interpreter, for example because a clone is
217 being created.
218
219    **** Volume <volume_ID> is busy ****
220
221 If the following message appears instead of the previously listed
222 information, it indicates that the File Server is unable to attach the
223 volume, perhaps because it is seriously corrupted. The F<FileLog> and
224 F<VolserLog> log files in the F</usr/afs/logs> directory on the file
225 server machine possibly provide additional information; use the B<bos
226 getlog> command to display them.
227
228    **** Could not attach volume <volume_ID> ****
229
230 Following a blank line, information from the VLDB entry appears.  Each
231 item in this list corresponds to a separate line in the output:
232
233 =over 4
234
235 =item *
236
237 The base (read/write) volume name. The read-only and backup versions have
238 the same name with a C<.readonly> and C<.backup> extension, respectively.
239
240 =item *
241
242 The volume ID numbers allocated to the versions of the volume that
243 actually exist, in fields labeled C<RWrite> for the read/write, C<ROnly>
244 for the read-only, C<Backup> for the backup, and C<RClone> for the
245 ReleaseClone. (If a field does not appear, the corresponding version of
246 the volume does not exist.) The appearance of the C<RClone> field normally
247 indicates that a release operation did not complete successfully; the
248 C<Old release> and C<New release> flags often also appear on one or more
249 of the site definition lines described just following.
250
251 =item *
252
253 The number of sites that house a read/write or read-only copy of the
254 volume, following the string C<< number of sites -> >>.
255
256 =item *
257
258 A line for each site that houses a read/write or read-only copy of the
259 volume, 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,
261 it is understood to share the read/write site.  Several flags can appear
262 with a site definition:
263
264 =over 4
265
266 =item Not released
267
268 Indicates that the vos release command has not been issued since the B<vos
269 addsite> command was used to define the read-only site.
270
271 =item Old release
272
273 Indicates that a vos release command did not complete successfully,
274 leaving the previous, obsolete version of the volume at this site.
275
276 =item New release
277
278 Indicates that a vos release command did not complete successfully, but
279 that this site did receive the correct new version of the volume.
280
281 =back
282
283 =item *
284
285 If the VLDB entry is locked, the string C<Volume is currently LOCKED>, as
286 well 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
292 Indicates that the volume was locked due to a B<vos move> or a B<vos
293 convertROtoRW> command.
294
295 =item Volume is locked for a release operation
296
297 Indicates that the volume was locked due to a B<vos release> command.
298
299 =item Volume is locked for a backup operation
300
301 Indicates that the volume was locked due to a B<vos backup> command.
302
303 =item Volume is locked for a delete/misc operation
304
305 Indicates that the volume was locked due to a B<vos delentry>, B<vos
306 addsite>, B<vos remsite>, B<vos changeloc>, B<vos syncvldb>, B<vos
307 syncserv>, B<vos rename>, or B<vos lock> command.
308
309 =item Volume is locked for a dump/restore operation
310
311 Indicates that the volume was locked due to a B<vos dump> or B<vos restore>
312 command.
313
314 =back
315
316 =back
317
318 For further discussion of the C<New release> and C<Old release> flags, see
319 L<vos_release(1)>.
320
321 =head1 EXAMPLES
322
323 The following example shows output for the Example Corporation volume called
324 C<usr> with two read-only replication sites (this volume is mounted at the
325 F</afs/example.com/usr> directory). For the sake of illustration, the output
326 shows 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
344 The following example shows the output for the volume C<user.terry> using
345 the 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
384 None
385
386 =head1 SEE ALSO
387
388 L<backup_diskrestore(8)>,
389 L<backup_volrestore(8)>,
390 L<bos_getlog(8)>,
391 L<bos_salvage(8)>,
392 L<salvager(8)>,
393 L<vos(1)>,
394 L<vos_listvol(1)>,
395 L<vos_listvldb(1)>,
396 L<vos_release(1)>,
397 L<vos_restore(1)>
398
399 =head1 COPYRIGHT
400
401 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
402
403 This documentation is covered by the IBM Public License Version 1.0.  It was
404 converted from HTML to POD by software written by Chas Williams and Russ
405 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.