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