1DUMP(8)                   System management commands                   DUMP(8)
2
3
4

NAME

6       dump - ext2/3/4 filesystem backup
7

SYNOPSIS

9       dump  [-level#]  [-ackMnqSuv] [-A file] [-B records] [-b blocksize] [-d
10       density] [-D file] [-e inode numbers] [-E file] [-f file]  [-F  script]
11       [-h  level]  [-I  nr errors] [-jcompression level] [-L label] [-Q file]
12       [-s feet] [-T date] [-y] [-zcompression level] files-to-dump
13
14       dump [-W | -w]
15

DESCRIPTION

17       Dump examines files on an  ext2/3/4  filesystem  and  determines  which
18       files  need  to be backed up. These files are copied to the given disk,
19       tape or other storage medium for safe keeping (see the -f option  below
20       for doing remote backups). A dump that is larger than the output medium
21       is broken into multiple volumes. On most media the size  is  determined
22       by writing until an end-of-media indication is returned.
23
24       On  media  that cannot reliably return an end-of-media indication (such
25       as some cartridge tape drives), each volume is of  a  fixed  size;  the
26       actual  size  is  determined  by specifying cartridge media, or via the
27       tape size, density and/or block count options below.  By  default,  the
28       same output file name is used for each volume after prompting the oper‐
29       ator to change media.
30
31       files-to-dump is either a mountpoint of a filesystem or a list of files
32       and  directories  to  be  backed up as a subset of a filesystem. In the
33       former case, either the path to a mounted filesystem or the  device  of
34       an  unmounted  filesystem  can  be  used.  In  the latter case, certain
35       restrictions are placed on the backup: -u is not allowed, the only dump
36       level  that  is  supported  is 0 and all the files and directories must
37       reside on the same filesystem.
38

OPTIONS

40       The following options are supported by dump:
41
42       -level#
43              The dump level (any integer). A level 0, full backup,  specified
44              by  -0 guarantees the entire file system is copied (but see also
45              the -h option  below).  A  level  number  above  0,  incremental
46              backup,  tells  dump to copy all files new or modified since the
47              last dump of a lower level. The default level is 0. Historically
48              only  levels 0 to 9 were usable in dump, this version is able to
49              understand any integer as a dump level.
50
51       -a     “auto-size”. Bypass all  tape  length  calculations,  and  write
52              until  an  end-of-media indication is returned.  This works best
53              for most modern tape drives, and is the  default.  Use  of  this
54              option is particularly recommended when appending to an existing
55              tape, or using a tape drive with hardware compression (where you
56              can never be sure about the compression ratio).
57
58       -A archive_file
59              Archive  a  dump table-of-contents in the specified archive_file
60              to be used by restore(8) to determine whether a file is  in  the
61              dump file that is being restored.
62
63       -b blocksize
64              The  number  of kilobytes per dump record. The default blocksize
65              is 10, unless the -d option has been used to specify a tape den‐
66              sity  of 6250BPI or more, in which case the default blocksize is
67              32. Th maximal value is 1024.  Note however that, since  the  IO
68              system slices all requests into chunks of MAXBSIZE (which can be
69              as low as 64kB), you can experience problems  with  dump(8)  and
70              restore(8)  when  using a higher value, depending on your kernel
71              and/or libC versions.
72
73       -B records
74              The number of 1 kB blocks per volume. Not normally required,  as
75              dump  can  detect  end-of-media.  When  the  specified  size  is
76              reached, dump waits for you to change the volume.   This  option
77              overrides  the calculation of tape size based on length and den‐
78              sity. If compression is on this limits  the  size  of  the  com‐
79              pressed  output  per  volume.  Multiple values may be given as a
80              single argument separated by commas.  Each value  will  be  used
81              for  one  dump  volume in the order listed; if dump creates more
82              volumes than the number of values given, the last value will  be
83              used  for  the  remaining volumes. This is useful for filling up
84              already partially filled media (and then  continuing  with  full
85              size volumes on empty media) or mixing media of different sizes.
86
87       -c     Change  the defaults for use with a cartridge tape drive, with a
88              density of 8000 bpi, and a length of  1700  feet.  Specifying  a
89              cartridge drive overrides the end-of-media detection.
90
91       -d density
92              Set tape density to density.  The default is 1600BPI. Specifying
93              a tape density overrides the end-of-media detection.
94
95       -D file
96              Set the path name of the file storing the information about  the
97              previous  full  and  incremental  dumps. The default location is
98              /etc/dumpdates.
99
100       -e inodes
101              Exclude inodes from the dump. The inodes parameter  is  a  comma
102              separated list of inode numbers (you can use stat(1) to find the
103              inode number for a file or directory).
104
105       -E file
106              Read list of inodes to be excluded from the dump from  the  text
107              file  file.  The file file should be an ordinary file containing
108              inode numbers separated by newlines.
109
110       -f file
111              Write the backup to file; file may be a special device file like
112              /dev/st0  (a  tape  drive), /dev/rsd1c (a floppy disk drive), an
113              ordinary file, or - (the standard output). Multiple  file  names
114              may be given as a single argument separated by commas. Each file
115              will be used for one dump volume in the  order  listed;  if  the
116              dump  requires  more volumes than the number of names given, the
117              last file name will used for all remaining volumes after prompt‐
118              ing  for  media  changes. If the name of the file is of the form
119              host:file or user@host:file dump writes to the named file on the
120              remote  host  (which should already exist, dump doesn't create a
121              new remote file) using rmt(8).  The default  path  name  of  the
122              remote rmt(8) program is /etc/rmt; this can be overridden by the
123              environment variable RMT.
124
125       -F script
126              Run script at the end of each tape (except for  the  last  one).
127              The  device name and the current volume number are passed on the
128              command line. The script must return 0 if dump  should  continue
129              without  asking  the  user  to change the tape, 1 if dump should
130              continue but ask the user to change the  tape.  Any  other  exit
131              code  will  cause  dump  to  abort.  For  security reasons, dump
132              reverts back to the real user ID and the real  group  ID  before
133              running the script.
134
135       -h level
136              Honor  the user nodump flag UF_NODUMP only for dumps at or above
137              the given level.  The default honor level is 1, so  that  incre‐
138              mental backups omit such files but full backups retain them.
139
140       -I nr errors
141              By  default,  dump  will  ignore the first 32 read errors on the
142              file system before asking for  operator  intervention.  You  can
143              change  this  using  this flag to any value. This is useful when
144              running dump on an active filesystem where  read  errors  simply
145              indicate  an  inconsistency  between  the  mapping  and  dumping
146              passes.
147
148              A value of 0 means that all read errors will be ignored.
149
150       -jcompression level
151              Compress every block to be  written  on  the  tape  using  bzlib
152              library.  This  option  will work only when dumping to a file or
153              pipe or, when dumping to a tape drive,  if  the  tape  drive  is
154              capable  of  writing  variable  length  blocks. You will need at
155              least the 0.4b24 version of restore in  order  to  extract  com‐
156              pressed  tapes. Tapes written using compression will not be com‐
157              patible with the BSD tape format. The (optional) parameter spec‐
158              ifies the compression level bzlib will use. The default compres‐
159              sion level is 2. If the optional parameter is  specified,  there
160              should  be  no  white  space  between  the option letter and the
161              parameter.
162
163       -k     Use Kerberos authentication to  talk  to  remote  tape  servers.
164              (Only  available  if  this option was enabled when dump was com‐
165              piled.)
166
167       -L label
168              The user-supplied text string label  is  placed  into  the  dump
169              header,  where  tools like restore(8) and file(8) can access it.
170              Note that this label is limited to be at most LBLSIZE (currently
171              16) characters, which must include the terminating \0.
172
173       -m     If  this  flag  is  specified, dump will optimise the output for
174              inodes having been changed but not modified since the last  dump
175              ('changed' and 'modified' have the meaning defined in stat(2) ).
176              For those inodes, dump will save only the metadata,  instead  of
177              saving  the  entire  inode  contents.   Inodes  which are either
178              directories or have been modified since the last dump are  saved
179              in  a regular way. Uses of this flag must be consistent, meaning
180              that either every dump in an incremental dump set have the flag,
181              or no one has it.
182
183              If  you use this option, be aware that many programs that unpack
184              files from archives (e.g. tar, rpm, unzip, dpkg) may set  files'
185              mtimes  to  dates  in the past.  Files installed in this way may
186              not be dumped correctly using "dump -m" if the modified mtime is
187              earlier than the previous level dump.
188
189              Tapes written using such 'metadata only' inodes will not be com‐
190              patible with the BSD tape format or older versions of restore.
191
192       -M     Enable the multi-volume feature. The name specified  with  f  is
193              treated  as a prefix and dump writes in sequence to <prefix>001,
194              <prefix>002 etc. This can be useful when dumping to files on  an
195              ext2/3/4 partition, in order to bypass the 2GB file size limita‐
196              tion.
197
198       -n     Whenever dump requires operator attention, notify all  operators
199              in the group operator by means similar to a wall(1).
200
201       -q     Make  dump  abort  immediately  whenever  operator  attention is
202              required, without  prompting  in  case  of  write  errors,  tape
203              changes etc.
204
205       -Q file
206              Enable  the  Quick  File Access support. Tape positions for each
207              inode are stored into the file file which is used by restore (if
208              called  with parameter -Q and the filename) to directly position
209              the tape at the file restore is currently working on. This saves
210              hours  when restoring single files from large backups, saves the
211              tapes and the drive's head.
212
213              It is recommended to set up the st driver to return logical tape
214              positions  rather than physical before calling dump/restore with
215              parameter -Q.  Since not all tape devices support physical  tape
216              positions those tape devices return an error during dump/restore
217              when the st driver is  set  to  the  default  physical  setting.
218              Please  see  the  st(4) man page, option MTSETDRVBUFFER , or the
219              mt(1) man page, on how to set the driver to return logical  tape
220              positions.
221
222              Before  calling  restore with parameter -Q, always make sure the
223              st driver is set to return the same type of tape  position  used
224              during the call to dump.  Otherwise restore may be confused.
225
226              This  option can be used when dumping to local tapes (see above)
227              or to local files.
228
229       -s feet
230              Attempt to calculate the amount of tape needed at  a  particular
231              density.  If  this  amount  is  exceeded, dump prompts for a new
232              tape. It is recommended to be a bit conservative on this option.
233              The  default  tape length is 2300 feet. Specifying the tape size
234              overrides end-of-media detection.
235
236       -S     Size estimate. Determine the amount of space that is  needed  to
237              perform  the  dump  without  actually  doing it, and display the
238              estimated number of bytes it will  take.  This  is  useful  with
239              incremental dumps to determine how many volumes of media will be
240              needed.
241
242       -T date
243              Use the specified date as the starting time for the dump instead
244              of  the  time  determined  from looking in /etc/dumpdates .  The
245              format of date is the same as that of ctime(3)  followed  by  an
246              rfc822  timezone specification: either a plus or minus sign fol‐
247              lowed by two digits for the number of hours and two  digits  for
248              the  minutes.  For example, -0800 for eight hours west of Green‐
249              wich or +0230 for two hours and a half east of  Greenwich.  This
250              timezone  offset  takes  into  account daylight savings time (if
251              applicable to the timezone): UTC offsets when  daylight  savings
252              time  is  in effect will be different than offsets when daylight
253              savings time is not in effect. For backward compatibility, if no
254              timezone  is specified, a local time is assumed.  This option is
255              useful for automated dump scripts that wish to dump over a  spe‐
256              cific  period  of time. The -T option is mutually exclusive from
257              the -u option.
258
259       -u     Update the file /etc/dumpdates after a successful dump. The for‐
260              mat  of  /etc/dumpdates is readable by people, consisting of one
261              free format record per line: filesystem  name,  increment  level
262              and  ctime(3)  format  dump  date  followed by a rfc822 timezone
263              specification (see the -u option for details).  If  no  timezone
264              offset  is  specified,  times are interpreted as local. Whenever
265              the file is written, all dates in the file are converted to  the
266              local  time  zone,  without changing the UTC times. There may be
267              only one entry per filesystem at each level. The file /etc/dump‐
268              dates may be edited to change any of the fields, if necessary.
269
270       -v     The  -v  (verbose)  makes  dump to print extra information which
271              could be helpful in debug sessions.
272
273       -W     Dump tells the operator what file systems  need  to  be  dumped.
274              This  information  is  gleaned from the files /etc/dumpdates and
275              /etc/fstab.  The -W option causes dump to  print  out,  for  all
276              file  systems in /etc/dumpdates , and recognized file systems in
277              /etc/mtab and /etc/fstab.  the most recent dump date and  level,
278              and  highlights those that should be dumped. If the -W option is
279              set, all other options are ignored, and dump exits immediately.
280
281       -w     Is like -W, but prints only recognized filesystems in  /etc/mtab
282              and /etc/fstab which need to be dumped.
283
284       -y     Compress  every  block  to  be written to the tape using the lzo
285              library.  This doesn't compress as well as the zlib library  but
286              it's  much faster.  This option will work only when dumping to a
287              file or pipe or, when dumping to a tape drive, if the tape drive
288              is  capable of writing variable length blocks.  You will need at
289              least the 0.4b34 version of restore in  order  to  extract  com‐
290              pressed  tapes. Tapes written using compression will not be com‐
291              patible with the BSD tape format.
292
293       -zcompression level
294              Compress every block to  be  written  on  the  tape  using  zlib
295              library.  This  option  will work only when dumping to a file or
296              pipe or, when dumping to a tape drive,  if  the  tape  drive  is
297              capable  of  writing  variable  length  blocks. You will need at
298              least the 0.4b22 version of restore in  order  to  extract  com‐
299              pressed  tapes. Tapes written using compression will not be com‐
300              patible with the BSD tape format. The (optional) parameter spec‐
301              ifies  the compression level zlib will use. The default compres‐
302              sion level is 2. If the optional parameter is  specified,  there
303              should  be  no  white  space  between  the option letter and the
304              parameter.
305
306       Dump requires operator intervention on these conditions: end  of  tape,
307       end  of  dump, tape write error, tape open error or disk read error (if
308       there is more than a threshold of nr errors). In addition  to  alerting
309       all  operators  implied by the -n key, dump interacts with the operator
310       on dump's control terminal at times when dump can no longer proceed, or
311       if  something  is  grossly  wrong.  All  questions  dump  poses must be
312       answered by typing “yes” or “no”, appropriately.
313
314       Since making a dump involves a lot of time and effort for  full  dumps,
315       dump  checkpoints  itself  at the start of each tape volume. If writing
316       that volume fails for some reason, dump will, with operator permission,
317       restart  itself from the checkpoint after the old tape has been rewound
318       and removed, and a new tape has been mounted.
319
320       Dump tells the operator what is going on at periodic intervals, includ‐
321       ing  usually low estimates of the number of blocks to write, the number
322       of tapes it will take, the time to completion, and the time to the tape
323       change.  The  output  is verbose, so that others know that the terminal
324       controlling dump is busy, and will be for some time.
325
326       In the event of a catastrophic disk event, the time required to restore
327       all  the necessary backup tapes or files to disk can be kept to a mini‐
328       mum by staggering the incremental dumps. An efficient method  of  stag‐
329       gering incremental dumps to minimize the number of tapes follows:
330
331       —      Always start with a level 0 backup, for example:
332                     /sbin/dump -0u -f /dev/st0 /usr/src
333
334              This  should  be done at set intervals, say once a month or once
335              every two months, and on a set of fresh tapes that is saved for‐
336              ever.
337
338       —      After  a  level  0,  dumps of active file systems are taken on a
339              daily basis, with this sequence of dump levels:
340                     3 2 5 4 7 6 9 8 9 9 ...
341
342              For the daily dumps, it should be possible to use a fixed number
343              of  tapes  for  each  day,  used on a weekly basis. Each week, a
344              level 1 dump is taken, and  the  daily  Hanoi  sequence  repeats
345              beginning  with  3. For weekly dumps, another fixed set of tapes
346              per dumped file system is used, also on a cyclical basis.
347
348       After several months or so, the  daily  and  weekly  tapes  should  get
349       rotated out of the dump cycle and fresh tapes brought in.
350
351       Another  backup  strategy  is the Tower of Hanoi sequence, which reuses
352       older tapes in a way that for newer dates the available restore  points
353       are     more     frequent,     then     for     older     dates    (see
354       http://en.wikipedia.org/wiki/Backup_rotation_scheme   for    additional
355       information).
356
357       (The 4.3BSD option syntax is implemented for backward compatibility but
358       is not documented here.)
359

ENVIRONMENT

361       TAPE   If no -f option was specified, dump will use the  device  speci‐
362              fied via TAPE as the dump device.  TAPE may be of the form tape‐
363              name, host:tapename, or user@host:tapename.
364
365       RMT    The environment variable RMT will be used to determine the path‐
366              name of the remote rmt(8) program.
367
368       RSH    Dump uses the contents of this variable to determine the name of
369              the remote shell command to use when doing remote backups  (rsh,
370              ssh  etc.).  If  this variable is not set, rcmd(3) will be used,
371              but only root will be able to do remote backups.
372

FILES

374       /dev/st0
375              default tape unit to dump to
376
377       /etc/dumpdates
378              dump date records
379
380       /etc/fstab
381              dump table: file systems and frequency
382
383       /etc/mtab
384              dump table: mounted file systems
385
386       /etc/group
387              to find group operator
388

SEE ALSO

390       fstab(5), restore(8), rmt(8)
391

DIAGNOSTICS

393       Many, and verbose.
394

COMPATIBILITY

396       The format of the /etc/dumpdates file has changed  in  release  0.4b34,
397       however,  the  file  will  be  read correctly with either pre-0.4b34 or
398       0.4b34 and later versions of dump provided that the  machine  on  which
399       dump  is  run  did  not change timezones (which should be a fairly rare
400       occurrence).
401

EXIT STATUS

403       Dump exits with zero status on success. Startup  errors  are  indicated
404       with  an exit code of 1; abnormal termination is indicated with an exit
405       code of 3.
406

BUGS

408       It might be considered a bug that this version of dump can only  handle
409       ext2/3/4 filesystems.  Specifically, it does not work with FAT filesys‐
410       tems.
411
412       Fewer than 32 read errors (change this with -I) on the  filesystem  are
413       ignored. If noticing read errors is important, the output from dump can
414       be parsed to look for lines that contain the text 'read error'.
415
416       When a read error occurs, dump prints out  the  corresponding  physical
417       disk  block and sector number and the ext2/3/4 logical block number. It
418       doesn't print out the corresponding file name or even the inode number.
419       The user has to use debugfs(8), commands ncheck and icheck to translate
420       the ext2blk number printed out by dump into an inode number, then  into
421       a file name.
422
423       Each reel requires a new process, so parent processes for reels already
424       written just hang around until the entire tape is written.
425
426       The estimated number of tapes is not correct if compression is on.
427
428       It would be nice if dump knew about the dump sequence,  kept  track  of
429       the tapes scribbled on, told the operator which tape to mount when, and
430       provided more assistance for the operator running restore.
431
432       Dump cannot do remote backups without being run as  root,  due  to  its
433       security  history.   Presently,  it works if you set it setuid (like it
434       used to be), but this might constitute a security risk. Note  that  you
435       can set RSH to use a remote shell program instead.
436

AUTHOR

438       The  dump/restore  backup  suite  was ported to Linux's Second Extended
439       File System by Remy Card <card@Linux.EU.Org>. He maintained the initial
440       versions of dump (up and including 0.4b4, released in January 1997).
441
442       Starting    with   0.4b5,   the   new   maintainer   is   Stelian   Pop
443       <stelian@popies.net>.
444

AVAILABILITY

446       The dump/restore backup suite is  available  from  <http://dump.source
447       forge.net>
448

HISTORY

450       A dump command appeared in Version 6 AT&T UNIX.
451
452
453
454BSD                           version 0.4b46 of                        DUMP(8)
Impressum