Commit | Line | Data |
---|---|---|
805e021f CE |
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. |