.\" .\" .\" pibu.1 - Manual Page for pibu Command .\" Copyright (C) 1997 Alexis Huxley .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or .\" (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; if not, write to the Free Software .\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. .\" .\" .\" $Id: pibu.1,v 1.5 1997/03/06 12:47:04 alexis Exp $ .\" .\" .TH PIBU 1 "1 March 1997" .SH NAME pibu \- Perl Incremental Backup .br .\" .\" we don't need a .br/.ne 5 here since there .\" isn't any chance really, that we're already .\" anywhere near the end of the first page. .\" .SH SYNOPSIS .B "pibu -V" .br .B "pibu -l" .br .B pibu [ .B \-v | .B \-d .I dbglvl ] [ .B \-dc .I cfgdir ] [ .B \-dl .I logdir ] [ .B \-ds .I sttdir ] [ .B \-dp .I prgdir ] [ .B \-cg | .B \-cc | .B \-cn ] [ .B \-N ] [ .B \-B | .B \-L .I bkuplvl ] .I fileset mediaid .br .\" .\" we don't need a .br/.ne 5 here since there .\" isn't any chance really, that we're already .\" anywhere near the end of the first page. .\" .SH DESCRIPTION This man page documents .I pibu version PATCHLEVEL_MARKER. .PP .I Pibu is a Perl script (see .I perl\fR(1)), for running full or incremental backups. .I Pibu is highly configurable. Note that .I pibu is not a restore program. .PP Required parameter .I fileset indexes a configuration file. .PP Required parameter .I mediaid refers to the media's identity label. It is currently only used in the generation of user backup log entries and system backup log file names. .PP The configuration file is used to specify various parameters of a backup. The configuration file is named .I fileset\fB.cfg\fR and by default is in directory .B /usr/local/etc/pibu\fR. .ne 4 It may contain blank lines, comment lines starting with the hash character and configuration directives of the form .br .sp .I keyword\fB:\fI value .sp .br Valid keywords together with an explanation of the associated value are: .TP 25 .B title A single line of free text used to identify the backup to humans. .TP .B device The destination backup device. This must be of the form .B \%/dev/\fIspecial-file or .I \%host\fB:/dev/\fIspecial-filefR. .TP .B method Used to index a method in the methods file (see below). .TP .B pre Absolute pathname of a program to be invoked without parameters before the backup commences. Its return code is currently ignored. .TP .B post Absolute pathname of a program to be invoked without parameters after the backup has completed. Its return code is currently ignored. .ne 6 .TP .B size Absolute pathname of a program to be invoked that will print to the standard output a message of the form .br .sp .I 999 units .br .sp where .I 999 represents the expected size of the backup measured in .I units\fR. .TP .B order Absolute pathname of a program to be invoked that will read a list of pathnames from the standard input, reorder them according to some user-defined criteria, and write the reordered list to the standard output. Filese will be backed up in this latter order. .TP .B options currently the only supported option is .B tapechecks which will result in calling .I mt\fR(1) to rewind .I device and to perform a write test. .TP .B root \fRor\fB roots Specifies directories or individual that should be candidates for backups, subject to subsequent .B include and .B exclude directives. .TP .B exclude \fR or \fBexcludes Specifies that candidate files or directories matching the given regular expressions should no longer be candidates to be backed up, subject to subsequent .B include and .B exclude directives. .TP .B include \fR or \fBincludes Specifies that files or directories, previously excluded from the backup, matching the given regular expressions should be candidates for backup, subject to subsequent .B include and .B exclude directives. .TP .B cycle .ne 6 A sequence of numbers in the range 0 to 9 which define the backup cycle. The rather cryptic meaning of the levels is: .br .sp 0 is a full backup .br 1-9 are backups of all files that have been changed or are under a directory that has changed since the last backup of the same or numerically lower level. EXAMPLES below). .PD .PP The methods file is used to define the format in which files are backed up to the media. It is named .B methods and by default is in directory .B /usr/local/etc/pibu\fR. .ne 4 It may contain blank lines, comment lines starting with the hash character and method definitions of the form .br .sp .I method\fB:\fI command .br .sp where .I method is a single word, and .I command is a command that reads a list of files from the standard input and backs them up. The command may make use of the following substitution markers which will be substituted for the following things: .TP 25 .B %D The destination device as specified by the .B device entry if present in the configuration file. .PD .PP The media file is used to define the situations of usability and availability of media. It is named .B media and by default is in directory .B /usr/local/etc/pibu\fR. .ne 4 It may contain blank lines, comment lines starting with the hash character and media specifications of the form .br .sp .I mediarngs\fB:\fI capacity filesets device bkuplvlrngs .sp .br where: .TP 25 .I mediarngs is a comma-separated list of .I mediarng\fR, and .I mediarng is a hyphen-separated pair or a single media identity label, which in turn, is a single word indentifying an instance of a media, such as 'disk53' or 'tape-monday' .TP .I capacity is the capacity of the media with capacity units .TP .I device is the backup destination device; this will be ignored if a device is not specified in the configuration file .TP .I bkuplvlrngs is a command-separated list of .I bkuplvlrng\fR, and .I bkuplvlrng is a hyphen-separated pair or a single backup level, which in turn, is a number in the range 0 to 9. .PD .br .ne 5 .SH OPTIONS .\" This indents everything after the next line by 25 some-things. .TP 25 .B \-V Print the version number and exit. .TP .B \-l List when each fileset for which there is a configuration file was last backed up and exit. .TP .B \-v Sets the verbosity level to allow informational messages in addition to the standard warnings and errors. .TP .B \-d \fIdbglvl Sets the verbosity level to .I dbglvl\fR. 0 results in only internal errors being reported, 1 to only errors, 2 to the default which is to report errors and warnings, higher values will supply debugging messages. .TP .B \-dc \fIcfgdir Sets the configuration directory to .I cfgdir\fR. The default is .B /usr/local/etc/pibu\fR. .TP .B \-dl \fIlogdir Sets the log directory to .I logdir\fR. The default is .B /var/log/pibu\fR. .TP .B \-ds \fIsttdir Sets the program state directory to .I sttdir\fR. The default is .B /var/local/pibu\fR. .TP .B \-dp \fIprgdir Sets the support programs directory to .I prgdir\fR. The default is .B /usr/local/lib/pibu\fR. .TP .B \-cg Log files should be compressed with .I gzip\fR(1). .TP .B \-cc Log files should be compressed with .I compress\fR(1). .TP .B \-cn Log files should not be compressed. .TP .B \-N No backup is performed, state information is not updated, but in all other respects .I pibu behaves as normal. .TP .B \-B No backup is performed but state information is updated as if a backup had been performed. .TP .B \-L \fIbkuplvl A backup at the specified level is performed. This may require reference to previously recorded state information, but does not update state information itself. This can be regarded as an unscheduled backup. .br .ne 5 .SH EXAMPLES Please refer to the files in .B /usr/local/etc/pibu/examples for example configuration files and support programs. .PP There are four basic approaches to backup cycles. They are covered here. The first approach is to always make full backups. The configuration file .ne 4 entry for this cycle is: .IP .nf .B cycle: 0 .fi .PP The second approach is to make a full backup and then a sequence of incremental backups which each back up what has changed since the full backup. At the end of the sequence of incremental backups the whole cycle is repeated. The incremental backups will get larger, but restores will require only the full backup media and the most recent of the incremental backups. The configuration file entry for such a cycle might be: .ne 4 .IP .nf .B cycle: 0 1 1 1 1 1 .fi .PP The third approach is to make a full backup followed by a sequence of incremental backups which each backup only what has changed since the most recent incremental backup. The incremental backups will remain around the same size but restores will require the full backup media and all subsequent .ne 4 backup media. The configuration file entry for such a cycle might be: .IP .nf .B cycle: 0 1 2 3 4 5 .fi .PP The fourth approach is a balance between the second and third approach. It starts with a full backup but then the backup intervals are repeatedly divided by an incremental backup of the next numerically higher level. Such as .ne 4 with this cycle: .IP .nf .B cycle: 0 3 2 3 1 3 2 3 .fi .PP For example, having done fourteen backups with this cycle to tapes labeled A to H, a file is accidentally deleted. It is uncertain which media will contain the latest version of the file. It would be necessary to restore, in this order, tapes A, E and F. .PP For further explanation of backup levels see .I dump\fR(8). Note that Linux does not currently have this command although other versions of Unix do. .br .ne 5 .SH FILES .PD 0 .TP 25 .B /usr/local/bin/pibu The backup program .TP .B /usr/local/lib/pibu/pibu-writer Wrapper to the method command .TP .B /usr/local/etc/pibu/\fIfileset\fB.cfg Default configuration file the fileset .I fileset\fR. .TP .B /usr/local/etc/pibu/methods Default location of methods definition file .TP .B /usr/local/etc/pibu/media Default location of media definition file .TP .B /usr/local/etc/pibu/examples Default location of example media, methods and configuration files .TP .B /usr/local/lib/pibu Default location of support programs .TP .B /usr/local/lib/pibu/examples Default location of example support programs .TP .B /var/log/pibu/\fIfileset\fB.\fIYYMMDDhhmm\fB.\fIbkuplvl\fB.\fImediaid\fB.idx.\fIext\fB Default location of backup log file; .I YYMMDDhhmm is the time the backup was started, .I bkuplvl is the level of the backup according to the cycle or command line parameters, .I mediaid is the media identity and .I ext is the file extension associated with the log compression method .TP .B /var/local/pibu/\fIfileset\fB.count Default location of file containing the number of backups of .I fileset that have been made to date .TP .B /var/local/pibu/\fIfileset\fB.last\fIbkuplvl\fB Unix time (see .I time\fR(2)) of the last backup of .I fileset at level .I bkuplvl .PD .br .ne 5 .SH ENVIRONMENT VARIABLES .PD 0 .TP 25 .B PIBU_*_CMD A set of variables used to override the hard-coded locations of the programs that .I pibu uses. See the source code for more details. .PD .br .ne 5 .SH DIAGNOSTICS .PD 0 .TP 25 .B configuration error: define \fIperl_variable\fB in pibu or set \fI\%environment_variable\fB environment variable .I Pibu has not been able to ascertain the location of a program it needs to run. Either of the specified actions may be taken to correct the problem. .TP .B can't execute \fIprogram\fB The specified program does not exist or is not executable by the current user. .TP .B wrongly named program .I Pibu has two valid names; .I pibu and .I pibu-writer\fR, one normally being a symbolic link to the other. For one reason or another, .I pibu has been invoked using a different name. You should invoke it only by the name .I pibu\fR. .I Pibu itself invokes itself as .I pibu-writer\fR. .TP .B can't \fIverb file\fB: \fIexplanation\fB The specified file or directory does not exist or could not have the specified action performed upon it by the current user. .TP .B invalid methods file entry: \fIentry\fB The specified entry does not conform to the required format (see the description of the methods file above). .TP .B invalid media file entry: \fIentry\fB The specified entry does not conform to the required format (see the description of the media file above). .TP .B invalid config option: \fIoption\fB The specified configuration file option is not supported. (See the description of the configuration file above). .TP .B invalid configuration file entry: \fIentry\fB The specified configuration file entry is not valid. (See the description of the configuration file above). .TP .B no \fIkeyword\fB entry found in \fIconfigfile\fB The specified keyword is required in the configuration file and is not present. .TP .B undefined method: \fImethod\fB The specified method mentioned in a configuration file could not be found in the methods file. Either the configuration file specifies the wrong method, or the methods file needs to be corrected because of an incorrectly spelled or missing method. .TP .B no 'device' entry found in config file The backup method used by the configuration file includes the device substitution marker '%D', but no device entry was specified in the configuration file. .TP .B can't read count from \fIcountfile\fB The number of backups of this fileset made could not be read from the specified file. The file should either be manually edited or removed. .TP .B can't rewind tape The option .B tapechecks was read from the configuration file, but could the media in the backup device could not be rewound. .TP .B write-protected tape The option .B tapechecks was read from the configuration file, but could the media is write-protected. .TP .B can't fork: \fIexplanation\fB The system could not create a new process. The explanation should shed some light as to why. .TP .B can't open pipe to \fIcommand\fB: \fIexplanation\fB The specified command could not be called. The explanation should shed some light as to why. .TP .B you are not root! This may not be a problem depending on whether the whole system's files are being backed up or just a particular users. But if you are not root and you are using system wide configuration, state, log and support program files, then it is unlikely that the backup will be successful. .TP .B superfluous 'device' entry in config file or missing %D in \%methods file a 'device' entry was found in the config file, but there was no '%D' substitution marker found in the methods file. This would indicate that either there should be a '%D' in the methods file and there isn't, or there is no need for a .B device entry to be supplied in the config file but one nevertheless has been. .TP .B level \fIbkuplvl\fB run file corrupt the file containing the last time a backup of the specified level and for the current fileset does not contain a valid Unix time. You should abort the backup and correct the problem either by manually fixing the state file or by removing it. .TP .B assuming method specifies device The configuration file does not contain a .B device entry, and the chosen method does not contain the .B %D substitution marker. It is assumed that the method itself specifies the backup device. .PD Remaining informational messages are self-explanatory. .br .ne 5 .SH CAVEATS None. .br .ne 5 .SH SEE ALSO perl(1), time(2), mt(1), gzip(1), compress(1), cpio(1). .br .ne 5 .SH AUTHOR Alexis Huxley .br .ne 5 .SH STATUS Recently ported to Perl 5, it is slowly stabilizing. .br .ne 5 .SH BUGS No known bugs. .br .ne 5 .SH COPYRIGHT & DISTRIBUTION POLICY Copyright (C) 1997 Alexis Huxley .PP This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. .PP This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. .PP You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.