doc/man-pages/pod1/vos_dump.pod.in

   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.