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

=head1 NAME

vos_dump - Converts a volume into ASCII format and writes it to a file

=head1 SYNOPSIS

=for html
<div class="synopsis">

B<vos dump> S<<< B<-id> <I<volume name or ID>> >>>
    S<<< [B<-time> <I<dump from time>>] >>>
    S<<< [B<-file> <I<dump file>>] >>> S<<< [B<-server> <I<server>>] >>>
    S<<< [B<-partition> <I<partition>>] >>> [B<-clone>] [B<-omitdirs>]
    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 du> S<<< B<-i> <I<volume name or ID>> >>>
    S<<< [B<-t> <I<dump from time>>] >>>
    S<<< [B<-f> <I<dump file>>] >>> S<<< [B<-s> <I<server>>] >>>
    S<<< [B<-p> <I<partition>>] >>>
    [B<-cl>] [B<-o>] S<<< [B<-ce> <I<cell name>>] >>> [B<-noa>] [B<-l>]
    [B<-v>] [B<-e>] [B<-nor>]
    S<<< [B<-co> <I<config directory>>] >>>
    [B<-h>]

=for html
</div>

=head1 DESCRIPTION

The B<vos dump> command converts the contents of the indicated volume,
which can be read/write, read-only or backup, into ASCII format. The
Volume Server writes the converted contents to the file named by the
B<-file> argument, or to the standard output stream. In the latter case,
the output can be directed to a named pipe, which enables interoperation
with third-party backup utilities.

To dump the complete contents of a volume (create a I<full dump>), omit
the B<-time> argument or specify the value C<0> (zero) for it. To create
an I<incremental dump>, which includes only the files and directories in
the volume that have modification timestamps later than a certain time,
specify a date and time as the value for the B<-time> argument.

By default, the vos command interpreter consults the Volume Location
Database (VLDB) to learn the volume's location, so the B<-server> and
B<-partition> arguments are not required. If the B<-id> argument
identifies a read-only volume that resides at multiple sites, the command
dumps the version from just one of them (normally, the one listed first in
the volume's VLDB entry as reported by the B<vos examine> or B<vos
listvldb> command). To dump the read-only volume from a particular site,
use the B<-server> and B<-partition> arguments to specify the site. To
bypass the VLDB lookup entirely, provide a volume ID number (rather than a
volume name) as the value for the B<-id> argument, together with the
B<-server> and B<-partition> arguments. This makes it possible to dump a
volume for which there is no VLDB entry.

During the dump operation, the volume is inaccessible both to Cache
Managers and to other volume operations. Dumping a volume does not
otherwise affect its status on the partition or its VLDB entry.

To restore a dumped volume back into AFS, use the B<vos restore> command.

=head1 CAUTIONS

Support for incremental dumps is provided to facilitate interoperation
with third-party backup utilities. The B<vos dump> command does not
provide any of the administrative facilities of an actual backup system,
so the administrator must keep manual records of dump times and the
relationship between full and incremental dumps of a volume. For a
volume's contents to be consistent after restoration of incremental dumps,
there must be no gap between the time at which a prior dump of the volume
was created and the value of the B<-time> argument to the B<vos dump>
command that creates the incremental dump. More specifically, for a
read/write volume, the B<-time> argument must specify the time that the
prior dump was performed, and for a read-only or backup volume it must
specify the time that the volume was last released (using the B<vos
release> command) or cloned (using the B<vos backup> or B<vos backupsys>
command) prior to dumping it. The parent dump can be either a full dump or
another incremental dump.

=head1 OPTIONS

=over 4

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

Specifies either the complete name or volume ID number of the read/write,
read-only, or backup volume to dump.

=item B<-time> <I<dump from time>>

Specifies whether the dump is full or incremental. Omit this argument to
create a full dump, or provide one of three acceptable values:

=over 4

=item *

The value C<0> (zero) to create a full dump.

=item *

A date in the format I<mm>B</>I<dd>B</>I<yyyy> (month, day and year) to
create an incremental dump that includes only files and directories with
modification timestamps later than midnight (12:00 a.m.) on the indicated
date. Valid values for the year range from C<1970> to C<2037>; higher
values are not valid because the latest possible date in the standard UNIX
representation is in 2038. The command interpreter automatically reduces
later dates to the maximum value. An example is C<01/13/1999>.

=item *

A date and time in the format B<">I<mm>B</>I<dd>B</>I<yyyy>
I<hh>B<:>I<MM>B<"> to create an incremental dump that includes only files
and directories with modification timestamps later than the specified date
and time. The date format is the same as for a date alone. Express the
time as hours and minutes (I<hh>:I<MM>) in 24-hour format (for example,
B<20:30> is 8:30 p.m.). Surround the entire expression with double quotes
(C<"">) because it contains a space.  An example is C<"01/13/1999 22:30">.

=back

=item B<-file> <I<dump file>>

Specifies the pathname of the file to which to write the dump. The file
can be in AFS, but not in the volume being dumped. A partial pathname is
interpreted relative to the current working directory. If this argument is
omitted, the dump is directed to the standard output stream.

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

Specifies the file server machine on which the volume resides.  Provide
the B<-partition> argument along with this one.

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

Specifies the partition on which the volume resides. Provide the
B<-server> argument along with this one.

=item B<-clone>

Normally, B<vos dump> locks the volume and dumps it, which blocks writes
to the volume while the dump is in progress.  If this flag is given, B<vos
dump> will instead clone the volume first (similar to what B<vos move>
would do) and then dumps the clone.  This can significantly decrease the
amount of time the volume is kept locked for dumps of large volumes.

=item B<-omitdirs>

By default, B<vos dump> includes all directory objects in an incremental
dump whether they've been changed or not.  If this option is given,
unchanged directories will be omitted.  This will reduce the size of the
dump and not cause problems if the incremental is restored, as expected,
on top of a volume containing the correct directory structure (such as one
created by restoring previous full and incremental dumps).

=include fragments/vos-common.pod

=back

=head1 EXAMPLES

The following command writes a full dump of the volume C<user.terry> to
the file F</afs/example.com/common/dumps/terry.dump>.

   % vos dump -id user.terry -time 0 -file /afs/example.com/common/dumps/terry.dump

The following command writes an incremental dump of the volume
C<user.smith> to the file C<smith.990131.dump> in the current working
directory. Only those files in the volume with modification time stamps
later than 6:00 p.m. on 31 January 1999 are included in the dump.

   % vos dump -id user.smith -time "01/31/1999 18:00" -file smith.990131.dump

=head1 PRIVILEGE REQUIRED

The issuer must be listed in the F</usr/afs/etc/UserList> file on the
machine specified with the B<-server> argument and on each database server
machine. If the B<-localauth> flag is included, the issuer must instead be
logged on to a server machine as the local superuser C<root>.

If the B<-file> argument is included, the issuer must also have permission
to insert and write in the directory that houses the file.

=head1 SEE ALSO

L<restorevol(1)>,
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_dump - Converts a volume into ASCII format and writes it to a file
	4
	5	=head1 SYNOPSIS
	6
	7	=for html
	8	<div class="synopsis">
	9
	10	B<vos dump> S<<< B<-id> <I<volume name or ID>> >>>
	11	S<<< [B<-time> <I<dump from time>>] >>>
	12	S<<< [B<-file> <I<dump file>>] >>> S<<< [B<-server> <I<server>>] >>>
	13	S<<< [B<-partition> <I<partition>>] >>> [B<-clone>] [B<-omitdirs>]
	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 du> S<<< B<-i> <I<volume name or ID>> >>>
	20	S<<< [B<-t> <I<dump from time>>] >>>
	21	S<<< [B<-f> <I<dump file>>] >>> S<<< [B<-s> <I<server>>] >>>
	22	S<<< [B<-p> <I<partition>>] >>>
	23	[B<-cl>] [B<-o>] S<<< [B<-ce> <I<cell name>>] >>> [B<-noa>] [B<-l>]
	24	[B<-v>] [B<-e>] [B<-nor>]
	25	S<<< [B<-co> <I<config directory>>] >>>
	26	[B<-h>]
	27
	28	=for html
	29	</div>
	30
	31	=head1 DESCRIPTION
	32
	33	The B<vos dump> command converts the contents of the indicated volume,
	34	which can be read/write, read-only or backup, into ASCII format. The
	35	Volume Server writes the converted contents to the file named by the
	36	B<-file> argument, or to the standard output stream. In the latter case,
	37	the output can be directed to a named pipe, which enables interoperation
	38	with third-party backup utilities.
	39
	40	To dump the complete contents of a volume (create a I<full dump>), omit
	41	the B<-time> argument or specify the value C<0> (zero) for it. To create
	42	an I<incremental dump>, which includes only the files and directories in
	43	the volume that have modification timestamps later than a certain time,
	44	specify a date and time as the value for the B<-time> argument.
	45
	46	By default, the vos command interpreter consults the Volume Location
	47	Database (VLDB) to learn the volume's location, so the B<-server> and
	48	B<-partition> arguments are not required. If the B<-id> argument
	49	identifies a read-only volume that resides at multiple sites, the command
	50	dumps the version from just one of them (normally, the one listed first in
	51	the volume's VLDB entry as reported by the B<vos examine> or B<vos
	52	listvldb> command). To dump the read-only volume from a particular site,
	53	use the B<-server> and B<-partition> arguments to specify the site. To
	54	bypass the VLDB lookup entirely, provide a volume ID number (rather than a
	55	volume name) as the value for the B<-id> argument, together with the
	56	B<-server> and B<-partition> arguments. This makes it possible to dump a
	57	volume for which there is no VLDB entry.
	58
	59	During the dump operation, the volume is inaccessible both to Cache
	60	Managers and to other volume operations. Dumping a volume does not
	61	otherwise affect its status on the partition or its VLDB entry.
	62
	63	To restore a dumped volume back into AFS, use the B<vos restore> command.
	64
65	=head1 CAUTIONS
66
67	Support for incremental dumps is provided to facilitate interoperation
68	with third-party backup utilities. The B<vos dump> command does not
69	provide any of the administrative facilities of an actual backup system,
70	so the administrator must keep manual records of dump times and the
71	relationship between full and incremental dumps of a volume. For a
72	volume's contents to be consistent after restoration of incremental dumps,
73	there must be no gap between the time at which a prior dump of the volume
74	was created and the value of the B<-time> argument to the B<vos dump>
75	command that creates the incremental dump. More specifically, for a
76	read/write volume, the B<-time> argument must specify the time that the
77	prior dump was performed, and for a read-only or backup volume it must
78	specify the time that the volume was last released (using the B<vos
79	release> command) or cloned (using the B<vos backup> or B<vos backupsys>
80	command) prior to dumping it. The parent dump can be either a full dump or
81	another incremental dump.
82
83	=head1 OPTIONS
84
85	=over 4
86
87	=item B<-id> <I<volume name or ID>>
88
89	Specifies either the complete name or volume ID number of the read/write,
90	read-only, or backup volume to dump.
91
92	=item B<-time> <I<dump from time>>
93
94	Specifies whether the dump is full or incremental. Omit this argument to
95	create a full dump, or provide one of three acceptable values:
96
97	=over 4
98
99	=item *
100
101	The value C<0> (zero) to create a full dump.
102
103	=item *
104
105	A date in the format I<mm>B</>I<dd>B</>I<yyyy> (month, day and year) to
106	create an incremental dump that includes only files and directories with
107	modification timestamps later than midnight (12:00 a.m.) on the indicated
108	date. Valid values for the year range from C<1970> to C<2037>; higher
109	values are not valid because the latest possible date in the standard UNIX
110	representation is in 2038. The command interpreter automatically reduces
111	later dates to the maximum value. An example is C<01/13/1999>.
112
113	=item *
114
115	A date and time in the format B<">I<mm>B</>I<dd>B</>I<yyyy>
116	I<hh>B<:>I<MM>B<"> to create an incremental dump that includes only files
117	and directories with modification timestamps later than the specified date
118	and time. The date format is the same as for a date alone. Express the
119	time as hours and minutes (I<hh>:I<MM>) in 24-hour format (for example,
120	B<20:30> is 8:30 p.m.). Surround the entire expression with double quotes
121	(C<"">) because it contains a space. An example is C<"01/13/1999 22:30">.
122
123	=back
124
125	=item B<-file> <I<dump file>>
126
127	Specifies the pathname of the file to which to write the dump. The file
128	can be in AFS, but not in the volume being dumped. A partial pathname is
129	interpreted relative to the current working directory. If this argument is
130	omitted, the dump is directed to the standard output stream.
131
132	=item B<-server> <I<server name>>
133
134	Specifies the file server machine on which the volume resides. Provide
135	the B<-partition> argument along with this one.
136
137	=item B<-partition> <I<partition name>>
138
139	Specifies the partition on which the volume resides. Provide the
140	B<-server> argument along with this one.
141
142	=item B<-clone>
143
144	Normally, B<vos dump> locks the volume and dumps it, which blocks writes
145	to the volume while the dump is in progress. If this flag is given, B<vos
146	dump> will instead clone the volume first (similar to what B<vos move>
147	would do) and then dumps the clone. This can significantly decrease the
148	amount of time the volume is kept locked for dumps of large volumes.
149
150	=item B<-omitdirs>
151
152	By default, B<vos dump> includes all directory objects in an incremental
153	dump whether they've been changed or not. If this option is given,
154	unchanged directories will be omitted. This will reduce the size of the
155	dump and not cause problems if the incremental is restored, as expected,
156	on top of a volume containing the correct directory structure (such as one
157	created by restoring previous full and incremental dumps).
158
159	=include fragments/vos-common.pod
160
161	=back
162
163	=head1 EXAMPLES
164
165	The following command writes a full dump of the volume C<user.terry> to
166	the file F</afs/example.com/common/dumps/terry.dump>.
167
168	% vos dump -id user.terry -time 0 -file /afs/example.com/common/dumps/terry.dump
169
170	The following command writes an incremental dump of the volume
171	C<user.smith> to the file C<smith.990131.dump> in the current working
172	directory. Only those files in the volume with modification time stamps
173	later than 6:00 p.m. on 31 January 1999 are included in the dump.
174
175	% vos dump -id user.smith -time "01/31/1999 18:00" -file smith.990131.dump
176
177	=head1 PRIVILEGE REQUIRED
178
179	The issuer must be listed in the F</usr/afs/etc/UserList> file on the
180	machine specified with the B<-server> argument and on each database server
181	machine. If the B<-localauth> flag is included, the issuer must instead be
182	logged on to a server machine as the local superuser C<root>.
183
184	If the B<-file> argument is included, the issuer must also have permission
185	to insert and write in the directory that houses the file.
186
187	=head1 SEE ALSO
188
189	L<restorevol(1)>,
190	L<vos(1)>,
191	L<vos_examine(1)>,
192	L<vos_listvldb(1)>,
193	L<vos_restore(1)>
194
195	=head1 COPYRIGHT
196
197	IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
198
199	This documentation is covered by the IBM Public License Version 1.0. It was
200	converted from HTML to POD by software written by Chas Williams and Russ
201	Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.