sbin/dump/dump.8

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"      Regents of the University of California.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgment:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)dump.8      8.3 (Berkeley) 5/1/95
  34 .\" $FreeBSD$
  35 .\"
  36 .Dd May 1, 1995
  37 .Dt DUMP 8
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm dump ,
  41 .Nm rdump
  42 .Nd filesystem backup
  43 .Sh SYNOPSIS
  44 .Nm dump
  45 .Op Fl 0123456789acknu
  46 .Op Fl B Ar records
  47 .Op Fl b Ar blocksize
  48 .Op Fl d Ar density
  49 .Op Fl f Ar file
  50 .Op Fl h Ar level
  51 .Op Fl s Ar feet
  52 .Op Fl T Ar date
  53 .Ar filesystem
  54 .Nm dump
  55 .Op Fl W Li \&| Fl w
  56 .Pp
  57 .in -\\n(iSu
  58 (The
  59 .Bx 4.3
  60 option syntax is implemented for backward compatibility, but
  61 is not documented here.)
  62 .Sh DESCRIPTION
  63 .Nm Dump
  64 examines files
  65 on a filesystem
  66 and determines which files
  67 need to be backed up.
  68 These files
  69 are copied to the given disk, tape or other
  70 storage medium for safe keeping (see the
  71 .Fl f
  72 option below for doing remote backups).
  73 A dump that is larger than the output medium is broken into
  74 multiple volumes.
  75 On most media the size is determined by writing until an
  76 end-of-media indication is returned.  This can be enforced
  77 by using the
  78 .Fl a
  79 option.
  80 .Pp
  81 On media that cannot reliably return an end-of-media indication
  82 (such as some cartridge tape drives)
  83 each volume is of a fixed size;
  84 the actual size is determined by the tape size and density and/or
  85 block count options below.
  86 By default, the same output file name is used for each volume
  87 after prompting the operator to change media.
  88 .Pp
  89 The following options are supported by
  90 .Nm Ns :
  91 .Bl -tag -width Ds
  92 .It Fl 0\-9
  93 Dump levels.
  94 A level 0, full backup,
  95 guarantees the entire file system is copied
  96 (but see also the
  97 .Fl h
  98 option below).
  99 A level number above 0,
 100 incremental backup,
 101 tells dump to
 102 copy all files new or modified since the
 103 last dump of any lower level.
 104 The default level is 0.
 105 .It Fl B Ar records
 106 The number of 1 KB blocks per volume.
 107 This option overrides the calculation of tape size
 108 based on length and density.
 109 .It Fl a
 110 .Dq auto-size .
 111 Bypass all tape length considerations, and enforce writing
 112 until an end-of-media indication is returned.  This fits best
 113 for most modern tape drives.  Use of this option is particularly
 114 recommended when appending to an existing tape, or using a tape
 115 drive with hardware compression (where you can never be sure about
 116 the compression ratio).
 117 .It Fl b Ar blocksize
 118 The number of kilobytes per dump record.
 119 .It Fl c
 120 Change the defaults for use with a cartridge tape drive, with a density
 121 of 8000 bpi, and a length of 1700 feet.
 122 .It Fl h Ar level
 123 Honor the user
 124 .Dq nodump
 125 flag
 126 .Dp Dv UF_NODUMP
 127 only for dumps at or above the given
 128 .Ar level .
 129 The default honor level is 1,
 130 so that incremental backups omit such files
 131 but full backups retain them.
 132 .It Fl d Ar density
 133 Set tape density to
 134 .Ar density .
 135 The default is 1600BPI.
 136 .It Fl f Ar file
 137 Write the backup to
 138 .Ar file ;
 139 .Ar file
 140 may be a special device file
 141 like
 142 .Pa /dev/rsa0
 143 (a tape drive),
 144 .Pa /dev/rfd1
 145 (a floppy disk drive),
 146 an ordinary file,
 147 or
 148 .Ql Fl
 149 (the standard output).
 150 Multiple file names may be given as a single argument separated by commas.
 151 Each file will be used for one dump volume in the order listed;
 152 if the dump requires more volumes than the number of names given,
 153 the last file name will used for all remaining volumes after prompting
 154 for media changes.
 155 If the name of the file is of the form
 156 .Dq host:file ,
 157 or
 158 .Dq user@host:file ,
 159 .Nm
 160 writes to the named file on the remote host using
 161 .Xr rmt 8 .
 162 The default path name of the remote
 163 .Xr rmt 8
 164 program is
 165 .\" rmt path, is the path on the remote host
 166 .Pa /etc/rmt ;
 167 this can be overridden by the environment variable
 168 .Ev RMT .
 169 .It Fl k
 170 Use Kerberos authentication to talk to remote tape servers.  (Only
 171 available if this option was enabled when
 172 .Nm
 173 was compiled.)
 174 .It Fl n
 175 Whenever
 176 .Nm
 177 requires operator attention,
 178 notify all operators in the group
 179 .Dq operator
 180 by means similar to a
 181 .Xr wall 1 .
 182 .It Fl s Ar feet
 183 Attempt to calculate the amount of tape needed
 184 at a particular density.
 185 If this amount is exceeded,
 186 .Nm
 187 prompts for a new tape.
 188 It is recommended to be a bit conservative on this option.
 189 The default tape length is 2300 feet.
 190 .ne 1i
 191 .It Fl T Ar date
 192 Use the specified date as the starting time for the dump
 193 instead of the time determined from looking in
 194 .Pa /etc/dumpdates .
 195 The format of date is the same as that of
 196 .Xr ctime 3 .
 197 This option is useful for automated dump scripts that wish to
 198 dump over a specific period of time.
 199 The
 200 .Fl T
 201 option is mutually exclusive from the
 202 .Fl u
 203 option.
 204 .It Fl u
 205 Update the file
 206 .Pa /etc/dumpdates
 207 after a successful dump.
 208 The format of
 209 .Pa /etc/dumpdates
 210 is readable by people, consisting of one
 211 free format record per line:
 212 filesystem name,
 213 increment level
 214 and
 215 .Xr ctime 3
 216 format dump date.
 217 There may be only one entry per filesystem at each level.
 218 The file
 219 .Pa /etc/dumpdates
 220 may be edited to change any of the fields,
 221 if necessary.
 222 .It Fl W
 223 .Nm Dump
 224 tells the operator what file systems need to be dumped.
 225 This information is gleaned from the files
 226 .Pa /etc/dumpdates
 227 and
 228 .Pa /etc/fstab .
 229 The
 230 .Fl W
 231 option causes
 232 .Nm
 233 to print out, for each file system in
 234 .Pa /etc/dumpdates
 235 the most recent dump date and level,
 236 and highlights those file systems that should be dumped.
 237 If the
 238 .Fl W
 239 option is set, all other options are ignored, and
 240 .Nm
 241 exits immediately.
 242 .It Fl w
 243 Is like W, but prints only those filesystems which need to be dumped.
 244 .El
 245 .Pp
 246 .Nm Dump
 247 requires operator intervention on these conditions:
 248 end of tape,
 249 end of dump,
 250 tape write error,
 251 tape open error or
 252 disk read error (if there are more than a threshold of 32).
 253 In addition to alerting all operators implied by the
 254 .Fl n
 255 key,
 256 .Nm
 257 interacts with the operator on
 258 .Em dump's
 259 control terminal at times when
 260 .Nm
 261 can no longer proceed,
 262 or if something is grossly wrong.
 263 All questions
 264 .Nm
 265 poses
 266 .Em must
 267 be answered by typing
 268 .Dq yes
 269 or
 270 .Dq no ,
 271 appropriately.
 272 .Pp
 273 Since making a dump involves a lot of time and effort for full dumps,
 274 .Nm
 275 checkpoints itself at the start of each tape volume.
 276 If writing that volume fails for some reason,
 277 .Nm
 278 will,
 279 with operator permission,
 280 restart itself from the checkpoint
 281 after the old tape has been rewound and removed,
 282 and a new tape has been mounted.
 283 .Pp
 284 .Nm Dump
 285 tells the operator what is going on at periodic intervals,
 286 including usually low estimates of the number of blocks to write,
 287 the number of tapes it will take, the time to completion, and
 288 the time to the tape change.
 289 The output is verbose,
 290 so that others know that the terminal
 291 controlling
 292 .Nm
 293 is busy,
 294 and will be for some time.
 295 .Pp
 296 In the event of a catastrophic disk event, the time required
 297 to restore all the necessary backup tapes or files to disk
 298 can be kept to a minimum by staggering the incremental dumps.
 299 An efficient method of staggering incremental dumps
 300 to minimize the number of tapes follows:
 301 .Bl -bullet -offset indent
 302 .It
 303 Always start with a level 0 backup, for example:
 304 .Bd -literal -offset indent
 305 /sbin/dump -0u -f /dev/nrsa0 /usr/src
 306 .Ed
 307 .Pp
 308 This should be done at set intervals, say once a month or once every two months,
 309 and on a set of fresh tapes that is saved forever.
 310 .It
 311 After a level 0, dumps of active file
 312 systems are taken on a daily basis,
 313 using a modified Tower of Hanoi algorithm,
 314 with this sequence of dump levels:
 315 .Bd -literal -offset indent
 316 3 2 5 4 7 6 9 8 9 9 ...
 317 .Ed
 318 .Pp
 319 For the daily dumps, it should be possible to use a fixed number of tapes
 320 for each day, used on a weekly basis.
 321 Each week, a level 1 dump is taken, and
 322 the daily Hanoi sequence repeats beginning with 3.
 323 For weekly dumps, another fixed set of tapes per dumped file system is
 324 used, also on a cyclical basis.
 325 .El
 326 .Pp
 327 After several months or so, the daily and weekly tapes should get
 328 rotated out of the dump cycle and fresh tapes brought in.
 329 .Sh ENVIRONMENT
 330 The environment variable
 331 .Ev RMT
 332 will be used to determine the pathname of the remote
 333 .Xr rmt 8
 334 program.
 335 .Sh FILES
 336 .Bl -tag -width /etc/dumpdates -compact
 337 .It Pa /dev/rsa0
 338 default tape unit to dump to
 339 .It Pa /etc/dumpdates
 340 dump date records
 341 .It Pa /etc/fstab
 342 dump table: file systems and frequency
 343 .It Pa /etc/group
 344 to find group
 345 .Em operator
 346 .El
 347 .Sh SEE ALSO
 348 .Xr fstab 5 ,
 349 .Xr restore 8 ,
 350 .Xr rmt 8
 351 .Sh DIAGNOSTICS
 352 Many, and verbose.
 353 .Pp
 354 Dump exits with zero status on success.
 355 Startup errors are indicated with an exit code of 1;
 356 abnormal termination is indicated with an exit code of 3.
 357 .Sh BUGS
 358 Fewer than 32 read errors on the filesystem are ignored.
 359 .Pp
 360 Each reel requires a new process, so parent processes for
 361 reels already written just hang around until the entire tape
 362 is written.
 363 .Pp
 364 Currently,
 365 .Xr physio 9
 366 slices all requests into chunks of 64 KB.  Therefore, it is
 367 impossible to use a larger tape blocksize, so
 368 .Nm
 369 will prevent this from happening.
 370 .Pp
 371 .Nm Dump
 372 with the
 373 .Fl W
 374 or
 375 .Fl w
 376 options does not report filesystems that have never been recorded
 377 in
 378 .Pa /etc/dumpdates ,
 379 even if listed in
 380 .Pa /etc/fstab .
 381 .Pp
 382 It would be nice if
 383 .Nm
 384 knew about the dump sequence,
 385 kept track of the tapes scribbled on,
 386 told the operator which tape to mount when,
 387 and provided more assistance
 388 for the operator running
 389 .Xr restore .
 390 .Pp
 391 .Nm Dump
 392 cannot do remote backups without being run as root, due to its
 393 security history.  This will be fixed in a later version of
 394 .Fx .
 395 Presently, it works if you set it setuid (like it used to be), but this
 396 might constitute a security risk.
 397 .Sh HISTORY
 398 A
 399 .Nm
 400 command appeared in
 401 .At v6 .