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