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

=head1 NAME

vos_listvldb - Displays a volume's VLDB entry

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<vos listvldb> S<<< [B<-name> <I<volume name or ID>>] >>>
    S<<< [B<-server> <I<machine name>>] >>>
    S<<< [B<-partition> <I<partition name>>] >>>
    [B<-locked>] [B<-quiet>] [B<-nosort>]
    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 listvl> S<<< [B<-na> <I<volume name or ID>>] >>>
    S<<< [B<-s> <I<machine name>>] >>>
    S<<< [B<-p> <I<partition name>>] >>>
    [B<-lock>] [B<-q>] [B<-nos>] S<<< [B<-c> <I<cell name>>] >>>
    [B<-noa>] [B<-loca>] [B<-v>] [B<-e>] [B<-nor>]
    S<<< [B<-co> <I<config directory>>] >>>
    [B<-h>]

=for html
</div>

=head1 DESCRIPTION

The B<vos listvldb> command formats and displays information from the
Volume Location Database (VLDB) entry for each volume specified.  The
output depends on the combination of options supplied on the command
line. Combine options as indicated to display the desired type of VLDB
entries:

=over 4

=item *

Every entry in the VLDB: provide no options.

=item *

Every VLDB entry that mentions a certain file server machine as the site
for a volume: specify the machine's name as the B<-server> argument.

=item *

Every VLDB entry that mentions a certain partition on any file server
machine as the site for a volume: specify the partition name as the
B<-partition> argument.

=item *

Every VLDB entry that mentions a certain partition on a certain file
server machine as the site for a volume: combine the B<-server> and
B<-partition> arguments.

=item *

A single VLDB entry: specify a volume name or ID number with the B<-name>
argument.

=item *

The VLDB entry only for the volumes with locked VLDB entries found at a
certain site: combine the B<-locked> flag with any of arguments that
define sites.

=back

=head1 OPTIONS

=over 4

=item B<-name> <I<volume name or ID>>

Specifies either the complete name or volume ID number of a volume of any
of the three types.

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

Identifies the file server machine listed as a site in each VLDB entry to
display. 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, the
B<-locked> flag, or both.

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

Identifies the partition (on the file server machine specified by the
B<-server> argument) listed as a site in each VLDB entry to
display. Provide the partition's complete name with preceding slash (for
example, C</vicepa>) or use one of the three acceptable abbreviated
forms. For details, see L<vos(1)>.

This argument can be combined with the B<-server> argument, the B<-locked>
flag, or both.

=item B<-locked>

Displays only locked VLDB entries. This flag can be combined with the
B<-server> argument, the B<-partition> argument, or both.

=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<-nosort>

Suppresses the default sorting of volume entries alphabetically by volume
name.

=include fragments/vos-common.pod

=back

=head1 OUTPUT

If the output includes more than one VLDB entry, by default the first line
reports which file server machine, partition, or both, houses the
volumes. The final line of output reports the total number of entries
displayed. Including the B<-quiet> flag suppresses these lines.

By default, volumes are sorted alphabetically by volume name.  Including
the B<-nosort> flag skips the sorting step, which can speed up the
production of output if there are a large number of entries.

The VLDB entry for each volume includes the following information:

=over 4

=item *

The base (read/write) volume name. The read-only and backup versions have
the same name with a C<.readonly> and C<.backup> extension, respectively.

=item *

The volume ID numbers allocated to the versions of the volume that
actually exist, in fields labeled C<RWrite> for the read/write, C<ROnly>
for the read-only, C<Backup> for the backup, and C<RClone> for the
ReleaseClone. (If a field does not appear, the corresponding version of
the volume does not exist.) The appearance of the C<RClone> field normally
indicates that a release operation did not complete successfully; the
C<Old release> and C<New release> flags often also appear on one or more
of the site definition lines described just following.

=item *

The number of sites that house a read/write or read-only copy of the
volume, following the string C<< number of sites -> >>.

=item *

A line for each site that houses a read/write or read-only copy of the
volume, specifying the file server machine, partition, and type of volume
(C<RW> for read/write or C<RO> for read-only). If a backup version exists,
it is understood to share the read/write site.  Several flags can appear
with a site definition:

=over 4

=item Not released

Indicates that the vos release command has not been issued since the B<vos
addsite> command was used to define the read-only site.

=item Old release

Indicates that a vos release command did not complete successfully,
leaving the previous, obsolete version of the volume at this site.

=item New release

Indicates that a vos release command did not complete successfully, but
that this site did receive the correct new version of the volume.

=back

=item *

If the VLDB entry is locked, the string C<Volume is currently LOCKED>, as
well as (in OpenAFS 1.5.75 and later) one or more of the following strings:

=over 4

=item Volume is locked for a move operation

Indicates that the volume was locked due to a B<vos move> or a B<vos
convertROtoRW> command.

=item Volume is locked for a release operation

Indicates that the volume was locked due to a B<vos release> command.

=item Volume is locked for a backup operation

Indicates that the volume was locked due to a B<vos backup> command.

=item Volume is locked for a delete/misc operation

Indicates that the volume was locked due to a B<vos delentry>, B<vos
addsite>, B<vos remsite>, B<vos changeloc>, B<vos syncvldb>, B<vos
syncserv>, B<vos rename>, or B<vos lock> command.

=item Volume is locked for a dump/restore operation

Indicates that the volume was locked due to a B<vos dump> or B<vos restore>
command.

=back

=back

For further discussion of the C<New release> and C<Old release> flags, see
L<vos_release(1)>.

=head1 EXAMPLES

The following command displays VLDB information for the Example Corporation
volume called C<usr>, which has two read-only replication sites:

   % vos listvldb -name usr
   usr
    RWrite: 5360870981   ROnly: 536870982   Backup: 536870983
    number of sites -> 3
       server fs1.example.com partition /vicepa RO Site
       server fs3.example.com partition /vicepa RO Site
       server fs2.example.com partition /vicepb RW Site

The following example shows entries for two of the volumes that reside on
the file server machine C<fs4.example.com>. The first VLDB entry is currently
locked. There are 508 entries that mention the machine as a volume site.

   % vos listvldb -server fs4.example.com
   VLDB entries for server fs4.example.com
       .       .           .        .
       .       .           .        .
   user.smith
    RWrite: 278541326   ROnly: 278541327   Backup: 278542328
    number of sites -> 1
      server fs4.example.com partition /vicepg RW Site
    Volume is currently LOCKED
      user.terry
    RWrite 354287190   ROnly 354287191   Backup 354287192
    number of sites -> 1
      server fs4.example.com partition /vicepc RW Site
      .       .           .        .
      .       .           .        .
   Total entries: 508

=head1 PRIVILEGE REQUIRED

None

=head1 SEE ALSO

L<vos(1)>,
L<vos_examine(1)>,
L<vos_listvol(1)>,
L<vos_lock(1)>,
L<vos_unlock(1)>,
L<vos_unlockvldb(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_listvldb - Displays a volume's VLDB entry
	4
	5	=head1 SYNOPSIS
	6
	7	=for html
	8	<div class="synopsis">
	9
	10	B<vos listvldb> S<<< [B<-name> <I<volume name or ID>>] >>>
	11	S<<< [B<-server> <I<machine name>>] >>>
	12	S<<< [B<-partition> <I<partition name>>] >>>
	13	[B<-locked>] [B<-quiet>] [B<-nosort>]
	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 listvl> S<<< [B<-na> <I<volume name or ID>>] >>>
	20	S<<< [B<-s> <I<machine name>>] >>>
	21	S<<< [B<-p> <I<partition name>>] >>>
	22	[B<-lock>] [B<-q>] [B<-nos>] S<<< [B<-c> <I<cell name>>] >>>
	23	[B<-noa>] [B<-loca>] [B<-v>] [B<-e>] [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 listvldb> command formats and displays information from the
	33	Volume Location Database (VLDB) entry for each volume specified. The
	34	output depends on the combination of options supplied on the command
	35	line. Combine options as indicated to display the desired type of VLDB
	36	entries:
	37
	38	=over 4
	39
	40	=item *
	41
	42	Every entry in the VLDB: provide no options.
	43
	44	=item *
	45
	46	Every VLDB entry that mentions a certain file server machine as the site
	47	for a volume: specify the machine's name as the B<-server> argument.
	48
	49	=item *
	50
	51	Every VLDB entry that mentions a certain partition on any file server
	52	machine as the site for a volume: specify the partition name as the
	53	B<-partition> argument.
	54
	55	=item *
	56
	57	Every VLDB entry that mentions a certain partition on a certain file
	58	server machine as the site for a volume: combine the B<-server> and
	59	B<-partition> arguments.
	60
	61	=item *
	62
	63	A single VLDB entry: specify a volume name or ID number with the B<-name>
	64	argument.
65
66	=item *
67
68	The VLDB entry only for the volumes with locked VLDB entries found at a
69	certain site: combine the B<-locked> flag with any of arguments that
70	define sites.
71
72	=back
73
74	=head1 OPTIONS
75
76	=over 4
77
78	=item B<-name> <I<volume name or ID>>
79
80	Specifies either the complete name or volume ID number of a volume of any
81	of the three types.
82
83	=item B<-server> <I<server name>>
84
85	Identifies the file server machine listed as a site in each VLDB entry to
86	display. Provide the machine's IP address or its host name (either fully
87	qualified or using an unambiguous abbreviation). For details, see
88	L<vos(1)>.
89
90	This argument can be combined with the B<-partition> argument, the
91	B<-locked> flag, or both.
92
93	=item B<-partition> <I<partition name>>
94
95	Identifies the partition (on the file server machine specified by the
96	B<-server> argument) listed as a site in each VLDB entry to
97	display. Provide the partition's complete name with preceding slash (for
98	example, C</vicepa>) or use one of the three acceptable abbreviated
99	forms. For details, see L<vos(1)>.
100
101	This argument can be combined with the B<-server> argument, the B<-locked>
102	flag, or both.
103
104	=item B<-locked>
105
106	Displays only locked VLDB entries. This flag can be combined with the
107	B<-server> argument, the B<-partition> argument, or both.
108
109	=item B<-quiet>
110
111	Suppresses the lines that summarize the number of volumes listed and their
112	status, which otherwise appear at the beginning and end of the output when
113	the output includes more than one volume.
114
115	=item B<-nosort>
116
117	Suppresses the default sorting of volume entries alphabetically by volume
118	name.
119
120	=include fragments/vos-common.pod
121
122	=back
123
124	=head1 OUTPUT
125
126	If the output includes more than one VLDB entry, by default the first line
127	reports which file server machine, partition, or both, houses the
128	volumes. The final line of output reports the total number of entries
129	displayed. Including the B<-quiet> flag suppresses these lines.
130
131	By default, volumes are sorted alphabetically by volume name. Including
132	the B<-nosort> flag skips the sorting step, which can speed up the
133	production of output if there are a large number of entries.
134
135	The VLDB entry for each volume includes the following information:
136
137	=over 4
138
139	=item *
140
141	The base (read/write) volume name. The read-only and backup versions have
142	the same name with a C<.readonly> and C<.backup> extension, respectively.
143
144	=item *
145
146	The volume ID numbers allocated to the versions of the volume that
147	actually exist, in fields labeled C<RWrite> for the read/write, C<ROnly>
148	for the read-only, C<Backup> for the backup, and C<RClone> for the
149	ReleaseClone. (If a field does not appear, the corresponding version of
150	the volume does not exist.) The appearance of the C<RClone> field normally
151	indicates that a release operation did not complete successfully; the
152	C<Old release> and C<New release> flags often also appear on one or more
153	of the site definition lines described just following.
154
155	=item *
156
157	The number of sites that house a read/write or read-only copy of the
158	volume, following the string C<< number of sites -> >>.
159
160	=item *
161
162	A line for each site that houses a read/write or read-only copy of the
163	volume, specifying the file server machine, partition, and type of volume
164	(C<RW> for read/write or C<RO> for read-only). If a backup version exists,
165	it is understood to share the read/write site. Several flags can appear
166	with a site definition:
167
168	=over 4
169
170	=item Not released
171
172	Indicates that the vos release command has not been issued since the B<vos
173	addsite> command was used to define the read-only site.
174
175	=item Old release
176
177	Indicates that a vos release command did not complete successfully,
178	leaving the previous, obsolete version of the volume at this site.
179
180	=item New release
181
182	Indicates that a vos release command did not complete successfully, but
183	that this site did receive the correct new version of the volume.
184
185	=back
186
187	=item *
188
189	If the VLDB entry is locked, the string C<Volume is currently LOCKED>, as
190	well as (in OpenAFS 1.5.75 and later) one or more of the following strings:
191
192	=over 4
193
194	=item Volume is locked for a move operation
195
196	Indicates that the volume was locked due to a B<vos move> or a B<vos
197	convertROtoRW> command.
198
199	=item Volume is locked for a release operation
200
201	Indicates that the volume was locked due to a B<vos release> command.
202
203	=item Volume is locked for a backup operation
204
205	Indicates that the volume was locked due to a B<vos backup> command.
206
207	=item Volume is locked for a delete/misc operation
208
209	Indicates that the volume was locked due to a B<vos delentry>, B<vos
210	addsite>, B<vos remsite>, B<vos changeloc>, B<vos syncvldb>, B<vos
211	syncserv>, B<vos rename>, or B<vos lock> command.
212
213	=item Volume is locked for a dump/restore operation
214
215	Indicates that the volume was locked due to a B<vos dump> or B<vos restore>
216	command.
217
218	=back
219
220	=back
221
222	For further discussion of the C<New release> and C<Old release> flags, see
223	L<vos_release(1)>.
224
225	=head1 EXAMPLES
226
227	The following command displays VLDB information for the Example Corporation
228	volume called C<usr>, which has two read-only replication sites:
229
230	% vos listvldb -name usr
231	usr
232	RWrite: 5360870981 ROnly: 536870982 Backup: 536870983
233	number of sites -> 3
234	server fs1.example.com partition /vicepa RO Site
235	server fs3.example.com partition /vicepa RO Site
236	server fs2.example.com partition /vicepb RW Site
237
238	The following example shows entries for two of the volumes that reside on
239	the file server machine C<fs4.example.com>. The first VLDB entry is currently
240	locked. There are 508 entries that mention the machine as a volume site.
241
242	% vos listvldb -server fs4.example.com
243	VLDB entries for server fs4.example.com
244	. . . .
245	. . . .
246	user.smith
247	RWrite: 278541326 ROnly: 278541327 Backup: 278542328
248	number of sites -> 1
249	server fs4.example.com partition /vicepg RW Site
250	Volume is currently LOCKED
251	user.terry
252	RWrite 354287190 ROnly 354287191 Backup 354287192
253	number of sites -> 1
254	server fs4.example.com partition /vicepc RW Site
255	. . . .
256	. . . .
257	Total entries: 508
258
259	=head1 PRIVILEGE REQUIRED
260
261	None
262
263	=head1 SEE ALSO
264
265	L<vos(1)>,
266	L<vos_examine(1)>,
267	L<vos_listvol(1)>,
268	L<vos_lock(1)>,
269	L<vos_unlock(1)>,
270	L<vos_unlockvldb(1)>
271
272	=head1 COPYRIGHT
273
274	IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
275
276	This documentation is covered by the IBM Public License Version 1.0. It was
277	converted from HTML to POD by software written by Chas Williams and Russ
278	Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.