[hcoop/debian/openafs.git] / doc / man-pages / pod1 / vos_listvol.pod.in

=head1 NAME

vos_listvol - Displays information from a volume header

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<vos listvol> S<<< B<-server> <I<machine name>> >>>
    S<<< [B<-partition> <I<partition name>>] >>>
    [B<-fast>] [B<-long>] [B<-quiet>]
    [B<-extended>] [B<-format>]
    S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
    [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
    S<<< [B<-config> <I<config directory>>] >>>
    [B<-help>]

B<vos listvo> S<<< B<-s> <I<machine name>> >>>
    S<<< [B<-p> <I<partition name>>] >>>
    [B<-fa>] [-lon] [B<-q>] [B<-ex>] [B<-fo>]
    S<<< [B<-c> <I<cell name>>] >>>
    [B<-noa>] [B<-loc>] [B<-v>] [B<-en>] [B<-nor>]
    S<<< [B<-co> <I<config directory>>] >>>
    [B<-h>]

=for html
</div>

=head1 DESCRIPTION

The B<vos listvol> command formats and displays the following information
from the volume header of each specified volume: volume name, volume ID,
volume type, size, and status at the server. The actual information
displayed depends on the combination of arguments supplied when the
command is issued. To display volume header information for various
numbers of volumes, combine the command's arguments as indicated:

=over 4

=item *

For every volume on a file server machine, specify the machine's name with
the B<-server> argument.

=item *

For every volume at a particular site, combine the B<-server> argument
with the B<-partition> argument.

=back

To display the Volume Location Database (VLDB) entry for one or more
volumes, use the B<vos listvldb> command. To display both the VLDB entry
and the volume header for a single volume, use the B<vos examine> command.

=head1 OPTIONS

=over 4

=item B<-server> <I<server name>>

Identifies the file server machine that houses volumes for which to
display the header. Provide the machine's IP address or its host name
(either fully qualified or using an unambiguous abbreviation). For
details, see L<vos(1)>.

This argument can be combined with the B<-partition> argument, as well as
the B<-fast>, B<-long>, or B<-extended> flag.

=item B<-partition> <I<partition name>>

Identifies the partition (on the file server machine specified by the
B<-server> argument) that houses volumes for which to display the
header. Provide the partition's complete name with preceding slash (for
example, F</vicepa>) or use one of the three acceptable abbreviated
forms. For details, see L<vos(1)>.

=item B<-fast>

Displays only the volume ID numbers of volumes stored at the site
specified by the B<-server>, and optionally B<-partition>, argument. Do
not combine this flag with the B<-extended> flag.

=item B<-long>

Displays more detailed information about each volume stored at the site
specified by the B<-server>, and optionally B<-partition>, argument. The
information includes the volume IDs of all three volume types associated
with the volume, and the read/write volume's quota, creation date and
update date.

=item B<-quiet>

Suppresses the lines that summarize the number of volumes listed and their
status, which otherwise appear at the beginning and end of the output when
the output includes more than one volume.

=item B<-extended>

Displays extensive statistics about access patterns for each volume stored
at the site specified by the B<-server>, and optionally B<-partition>,
argument. The statistics include the number of reads and writes to files
in the volume, and how recently files and directories have been updated by
their owners or other users. Do not combine this flag with the B<-fast>
flag.

=item B<-format>

Show information in a format suitable for machine parsing.

=include fragments/vos-common.pod

=back

=head1 OUTPUT

The output is ordered alphabetically by volume name and by default
provides the following information on a single line for each volume:

=over 4

=item *

Name

=item *

Volume ID number

=item *

Type (the flag is C<RW> for read/write, C<RO> for read-only, C<BK> for
backup)

=item *

Size in kilobytes (C<1024> equals a megabyte)

=item *

Number of files in the volume, if the B<-extended> flag is provided

=item *

Status on the file server machine, which is one of the following:

=over 4

=item On-line

The volume is completely accessible to Cache Managers.

=item Off-line

The volume is not accessible to Cache Managers, but does not seem to be
corrupted. This status appears while a volume is being dumped, for
example.

=item Off-line**needs salvage**

The volume is not accessible to Cache Managers, because it seems to be
corrupted. Use the B<bos salvage> or B<salvager> command to repair the
corruption.

=back

=back

If the following message appears instead of the previously listed
information, it indicates that a volume is not accessible to Cache
Managers or the B<vos> command interpreter, for example because a clone is
being created.

   **** Volume <volume_ID> is busy ****

If the following message appears instead of the previously listed
information, it indicates that the File Server is unable to attach the
volume, perhaps because it is seriously corrupted. The F<FileLog> and
F<VolserLog> log files in the F</usr/afs/logs> directory on the file
server machine possibly provide additional information; use the B<bos
getlog> command to display them.

   **** Could not attach volume <volume_ID> ****

The information about individual volumes is bracketed by summary
lines. The first line of output specifies the number of volumes in the
listing. The last line of output summarizes the number of volumes that are
online, offline, and busy. These lines do not appear if the B<-quiet> flag
is used.

If the B<-fast> flag is added, the output displays only the volume ID
number of each volume, arranged in increasing numerical order. The final
line (which summarizes the number of online, offline, and busy volumes) is
omitted.

If the B<-long> flag is included, the output for each volume includes all
of the information in the default listing plus the following. Each item in
this list corresponds to a separate line of output:

=over 4

=item *

The file server machine and partition that house the volume, as determined
by the command interpreter as the command runs, rather than derived from the
VLDB or the volume header.

=item *

The volume ID numbers associated with the various versions of the volume:
read/write (C<RWrite>), read-only (C<ROnly>), backup (C<Backup>), and
ReleaseClone (C<RClone>). One of them matches the volume ID number that
appears on the first line of the volume's output. If the value in the
C<RWrite>, C<ROnly>, or C<Backup> field is C<0> (zero), there is no volume
of that type. If there is currently no ReleaseClone, the C<RClone> field
does not appear at all.

=item *

The maximum space quota allotted to the read/write copy of the volume,
expressed in kilobyte blocks in the C<MaxQuota> field.

=item *

The date and time the volume was created, in the C<Creation> field. If the
volume has been restored with the B<backup diskrestore>, B<backup
volrestore>, or B<vos restore> command, this is the restore time.

=item *

The date and time when the contents of the volume last changed, in the
C<Last Update> field. For read-only and backup volumes, it matches the
timestamp in the C<Creation> field.

=item *

The number of times the volume has been accessed for a fetch or store
operation since the later of the two following times:

=over 4

=item *

12:00 a.m. on the day the command is issued

=item *

The last time the volume changed location

=back

=back

If the B<-extended> flag is included, the output for each volume includes
all of the information reported with the B<-long> flag, plus two tables of
statistics:

=over 4

=item *

The table labeled C<Raw Read/Write Stats> table summarizes the number of
times the volume has been accessed for reading or writing.

=item *

The table labeled C<Writes Affecting Authorship> table contains
information on writes made to files and directories in the specified
volume.

=back

=head1 EXAMPLES

The following example shows the output for the F</vicepb> partition on the
file server machine C<fs2.example.com> when no flags are provided:

   % vos listvol -server fs2.example.com -partition b
   Total number of volumes on server fs2.example.com partition /vicepb : 66
   sys                  1969534847 RW       1582 K On-line
   sys.backup           1969535105 BK       1582 K On-line
         .                   .     .         .   .    .
         .                   .     .         .   .    .
   user.pat             1969534536 RW      17518 K On-line
   user.pat.backup      1969534538 BK      17537 K On-line
   Total volumes onLine 66 ; Total volumes offLine 0 ;  Total busy 0

The following example shows the output when the B<-fast> flag is added:

   % vos listvol -server fs2.example.com -partition b -fast
   Total number of volumes on server fs2.example.com partition /vicepb : 66
    1969516782
    1969516784
        .
        .
    1969535796

The following example shows two volumes from the output that appears when
the B<-long> flag is added:

   % vos listvol -server fs2.example.com -partition b -long
   Total number of volumes on server fs2.example.com partition /vicepb: 66
         .                   .      .         .   .    .
         .                   .      .         .   .    .
   user.pat             1969534536 RW      17518 K On-line
        fs2.example.com /vicepb
        RWrite 1969534536 ROnly 0        Backup 1969534538
        MaxQuota      20000 K
        Creation    Mon Jun 12 09:02:25 1989
        Last Update Thu May 20 17:39:34 1999
        1573 accesses in the past day (i.e., vnode references)
   user.pat.backup      1969534538 BK      17537 K On-line
        fs2.example.com /vicepb
        RWrite 1969534536 ROnly 0        Backup 1969534538
        MaxQuota      20000 K
        Creation    Tue Jun 13 04:37:59 1989
        Last Update Wed May 19 06:37:59 1999
        0 accesses in the past day (i.e., vnode references)
          .                   .      .         .   .    .
          .                   .      .         .   .    .
   Total volumes onLine 66 ; Total volumes offLine 0 ; Total busy 0

=head1 PRIVILEGE REQUIRED

None

=head1 SEE ALSO

L<backup_diskrestore(8)>,
L<backup_volrestore(8)>,
L<bos_getlog(8)>,
L<bos_salvage(8)>,
L<salvager(8)>,
L<vos(1)>,
L<vos_examine(1)>,
L<vos_listvldb(1)>,
L<vos_restore(1)>

=head1 COPYRIGHT

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0.  It was
converted from HTML to POD by software written by Chas Williams and Russ
Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.
Commit	Line	Data
805e021f CE	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-lineneeds 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.