absolute path of dd binary. used if GNU cpio is not detected.
=item B
name of remote host to write archive.
=item B
device file to write archive. mutually exclusive with B.
=item B
disk file to write archive. mutually exclusive with B.
=item B
positive integer that sets I/O block size to (n * 512) bytes.
=item B
set to 1 to reset file access time after file is read by cpio.
=item B
directory to write backup log.
=item B
tapeset number, 1-99999.
=item B
number of days to keep backup logs of specified tapeset, 0-99999. setting to
0 disables logging.
=item B
absolute path of alternate transport. used if GNU cpio is not detected.
=item B
floating-point number that sets maximum archive size in MB. used only if
archive is a device. set to 0 to disable.
=item B
directory where B writes timestamp files.
=item B
sets cpio header type. must be one of B, B, B, B, B,
B or B.
=item B
email address(es) to send error report. requires '/bin/mail' and properly
configured MTA. multiple addresses can be separated by whitespace.
=item B
absolute path of compression utility used to compress backup log. if set to
1 B will use compress.
=item B
set to 1 to display verbose output to STDERR.
=item B
set to 1 to display very verbose output to STDERR.
=back
=head2 [DIRLIST]
list of subdirectories relative to the B to be backed up. if this
section is empty B will archive all files and directories under
the B. note, directories must be specified relative to the
B. using absolute paths will break the file-finding routine.
=head2 [EXCLUDES]
list of subdirectories relative to the B to be excluded from the
archive. if this section is empty B will not exclude any files.
note, directories must be specified relative to the B.
=head2 SAMPLE CONFIGURATION
# cpiotool level 2 config
[CONF]
root-dir /home/nickb
cpio /usr/local/bin/cpio
level 2
#remote-host
device /dev/fd0
#file
block-size 20
logdir /var/log/backup
set 3
keep-logs 14
conf-dir /usr/local/backup/conf
header ustar
notify ops@domain.org backup@domain.org
maxsize 1.44
ziplog /usr/local/bin/bzip2
verbose 1
[DIRLIST]
# relative to root-dir
GNUstep/Library/AfterStep
site
[EXCLUDE]
GNUstep/Library/AfterStep/non-configurable
GNUstep/Library/AfterStep/start/Applications/Editors
trash
unused
# end config
=head1 MULTIPLE-VOLUME ARCHIVES
the cpio binary supports archives that span multiple volumes. B
implements this in one of 3 ways, provided the archive is written to a
device:
=over 4
=item 1.
if B is unspecified, the cpio binary will detect end of media
and send a request to the controlling terminal. this is easiest but requires
the backup to be run manually from a terminal. it is also time-consuming
and error-prone in the event a restore is needed, as each tape in the series
must be read in order to restore a file at the end of the archive. if
one of the tapes in the set is corrupt, it's possible that all data on
subsequent tapes in the archive will be inaccessible.
=item 2.
if B is specified but B is unspecified or a mailer
is not found, B will estimate the total size of all cpio headers
and keep a running total of the number of bytes written to the device.
when the number approaches B, IO to the cpio binary is closed
and a request for media is printed to standard out. sending a HUP signal
to B continues the backup. this option still requires the
backup to be run manually from a terminal, but has the advantage of writing
archives separately to individual tapes rather than writing one large archive
across multiple tapes. this decreases time required for restores and reduces
the potential for data loss.
=item 3.
if B and B are specified, and a mailer is found,
B writes archives in the same manner as B<2> above, but sends
media requests to the email address specified in B. this
allows some degree of automation as no interaction with a terminal is
required.
=back
=head1 VOLUME MANAGEMENT
not supported (yet). eventually B will store tape information in
a mysql database, but this is a project for the distant future.
=head1 INCREMENTAL BACKUPS
the simplified concept of tapesets, along with the use of timestamp files,
determines which files to archive for incremental (level 1-9) backups.
if a configuration directory is specified B writes a timestamp file
called C. the last modification time of every
file in each directory in the [DIRLIST] is compared to the last
modification time of the timestamp file to determine if the file should be
archived. timestamp files are simply zero-length files with a naming
convention recognized by B. creating, removing, or changing the
modification times of timestamp files will affect the behavior of
B.
=head1 README
backup script that uses cpio
=head1 PREREQUISITES
perl 5.6.0 or newer
=head1 VERSION
B v0.65a, Copyright (C) 2001 Assentive Solutions
=head1 AUTHOR
Nick Balthaser
=head1 OSNAMES
freebsd
solaris
=head1 BUGS
=over 4
=item *
if the remote transport (rsh or ssh) hangs up while using non-GNU cpio,
IO stops and cpiotool exits.
=item *
when running in a terminal in the background and writing to a remote host with
dd, sending SIGINT by pressing ^C can have unpredictable
results, even if B is running under a subshell or nohup.
=item *
error "dd: unexpected short write, wrote 0 bytes, expected " while writing
to remote device. the remote dd detected end of media and quit prematurely.
this can mean the B value is greater than the capacity of the
media. now that _padTrailer() is in place this should happen far less
often. adjusting B can compensate for this in the interim.
=item *
no error checking on the B value. if an incorrect value is
specified, the cpio binary and/or dd may reach end-of-media before the
byte-counter. this will cause dd to hang up abruptly on remote backups
or conflicting media requests on local backups.
=item *
if a single file being backed up is larger than the media capacity,
the cpio binary could reach end-of-media before the byte-counter and
conflicting media requests would be sent. currently an exception is thrown
and the script exits if this happens. the only solution currently
is to disable B by setting it to 0 or leaving it unspecified.
this allows the cpio binary to create a single archive that spans multiple
tapes, which can be unreliable. see B above.
=item *
the number of bytes subtracted from the B value to allow for
headers is an (improving) rough estimate and may be inaccurate. in the
meantime adjusting B can compensate.
=item *
the log-remover might not recognize logs with a compressed suffix (e.g.
.gz, .bz2).
=item *
for full functionality B relies on the presence of mail or mailx,
dd, and rsh or ssh. dd always exits on SIGINT. it's not always possible
to trap SIGINT.
=item *
no database interface, reliance on easily-manipulated timestamp files.
=back
=head1 SCRIPT CATEGORIES
UNIX/System_administration
=cut