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