=head1 BackupPC Introduction
-This documentation describes BackupPC version 1.5.0,
-released on 2 Aug 2002.
+This documentation describes BackupPC version __VERSION__,
+released on __RELEASEDATE__.
=head2 Overview
BackupPC is a high-performance, enterprise-grade system for backing up
-Linux and WinXX PCs, desktops and laptops to a server's disk. BackupPC
-is highly configurable and easy to install and maintain.
+Unix, Linux and WinXX PCs, desktops and laptops to a server's disk.
+BackupPC is highly configurable and easy to install and maintain.
Given the ever decreasing cost of disks and raid systems, it is now
-practical and cost effective to backup a large number of machines onto a
-server's local disk or network storage. For some sites this might be
+practical and cost effective to backup a large number of machines onto
+a server's local disk or network storage. For some sites this might be
the complete backup solution. For other sites additional permanent
archives could be created by periodically backing up the server to tape.
=item *
+The http/cgi user interface has internationalization (i18n) support,
+currently providing English, French, German, Spanish, Italian
+and Dutch.
+
+=item *
+
No client-side software is needed. On WinXX the standard smb
protocol is used to extract backup data. On linux or unix clients,
-tar over ssh/rsh/nfs is used to extract backup data (or alternatively
-Samba can be installed on the linux or unix client to provide smb shares).
+rsync or tar (over ssh/rsh/nfs) is used to extract backup data.
+Alternatively, rsync can also be used on WinXX (using cygwin),
+and Samba could be installed on the linux or unix client to
+provide smb shares).
=item *
any backup directly from the CGI interface. Zip or Tar archives
for selected files or directories from any backup can also be
downloaded from the CGI interface. Finally, direct restore to
-the client machine (using SMB or tar) for selected files or
+the client machine (using smb or tar) for selected files or
directories is also supported from the CGI interface.
=item *
=item Full Backup
-A full backup is a complete backup of a share. BackupPC can be configured to
-do a full backup at a regular interval (often weekly). BackupPC can also
-be configured to keep a certain number of full backups, and to keep
-a smaller number of very old full backups.
+A full backup is a complete backup of a share. BackupPC can be
+configured to do a full backup at a regular interval (typically
+weekly). BackupPC can be configured to keep a certain number
+of full backups. Exponential expiry is also supported, allowing
+full backups with various vintages to be kept (for example, a
+settable number of most recent weekly fulls, plus a settable
+number of older fulls that are 2, 4, 8, or 16 weeks apart).
=item Incremental Backup
-An incremental backup is a backup of files that have changed (based on their
-modification time) since the last successful full backup. To be safe,
-BackupPC backups all files that have changed since one hour prior to the
-start of the last successful full backup. BackupPC can also be configured
-to keep a certain number of incremental backups, and to keep a smaller
-number of very old incremental backups. (BackupPC does not support
-multi-level incremental backups, although it would be easy to do so.)
+An incremental backup is a backup of files that have changed (based on
+their modification time) since the last successful full backup. For
+SMB and tar, BackupPC backups all files that have changed since one
+hour prior to the start of the last successful full backup. Rsync is
+more clever: any files whose attributes have changed (ie: uid, gid,
+mtime, modes, size) since the last full are backed up. Deleted, new
+files and renamed files are detected by Rsync incrementals.
+In constrast, SMB and tar incrementals are not able to detect deleted
+files, renamed files or new files whose modification time is prior to
+the last full dump.
+
+BackupPC can also be configured to keep a certain number of incremental
+backups, and to keep a smaller number of very old incremental backups.
+(BackupPC does not support multi-level incremental backups, although it
+will in a future version.)
BackupPC's CGI interface "fills-in" incremental backups based on the
last full backup, giving every backup a "full" appearance. This makes
browsing and restoring backups easier.
+=item Partial Backup
+
+When a full backup fails or is canceled, and some files have already
+been backed up, BackupPC keeps a partial backup containing just the
+files that were backed up successfully. The partial backup is removed
+when the next successful backup completes, or if another full backup
+fails resulting in a newer partial backup. A failed full backup
+that has not backed up any files, or any failed incremental backup,
+is removed; no partial backup is saved in these cases.
+
+The partial backup may be browsed or used to restore files just like
+a successful full or incremental backup.
+
+With the rsync transfer method the partial backup is used to resume
+the next full backup, avoiding the need to retransfer the file data
+already in the partial backup.
+
=item Identical Files
BackupPC pools identical files using hardlinks. By "identical
likely means an exact image of a linux/unix file system can be made.
BackupPC saves backups onto disk. Because of pooling you can relatively
-economically keep several weeks of old backups. But BackupPC does not
-provide permanent storage to tape. Other Open Source applications can do
-this by backing up BackupPC's pool directories to tape.
+economically keep several weeks of old backups.
At some sites the disk-based backup will be adequate, without a
secondary tape backup. This system is robust to any single failure: if a
restore files. If the server disk fails, BackupPC can be restarted on a
fresh file system, and create new backups from the clients. The chance
of the server disk failing can be made very small by spending more money
-on increasingly better RAID systems.
+on increasingly better RAID systems. However, there is still the risk
+of catastrophic events like fires or earthquakes that can destroy
+both the BackupPC server and the clients it is backing up if they
+are physically nearby.
-At other sites a secondary tape backup will be required. This tape
-backup can be done perhaps weekly from the BackupPC pool file system.
+Some sites might choose to do periodic backups to tape or cd/dvd.
+This backup can be done perhaps weekly using the archive function of
+BackupPC.
-One comment: in the US in particular, permanent backups of things like
-email are becoming strongly discouraged by lawyers because of discovery
-prior to possible litigation. Using BackupPC without tape backup allows
-recent file changes or losses to be restored, but without keeping a
-history more than a month or two old (although this doesn't avoid the
-problem of old emails languishing in user's email folders forever).
+Other users have reported success with removable disks to rotate the
+BackupPC data drives, or using rsync to mirror the BackupPC data pool
+offsite.
=back
This page has links to the current releases of BackupPC.
+=item BackupPC FAQ
+
+BackupPC has a FAQ at L<http://backuppc.sourceforge.net/faq>.
+
=item Mail lists
-Two BackupPC mailing lists exist for announcements (backuppc-announce)
-and reporting information, asking questions, discussing development or
-any other topic relevant to BackupPC (backuppc-users).
+Three BackupPC mailing lists exist for announcements (backuppc-announce),
+developers (backuppc-devel), and a general user list for support, asking
+questions or any other topic relevant to BackupPC (backuppc-users).
+
+The lists are archived on SourceForge and Gmane. The SourceForge lists
+are not always up to date and the searching is limited, so Gmane is
+a good alternative. See:
+
+ http://news.gmane.org/index.php?prefix=gmane.comp.sysutils.backup.backuppc
+ http://sourceforge.net/mailarchive/forum.php?forum_id=503
-You are encouraged to subscribe to either the backuppc-announce
-or backuppc-users mail list on sourceforge.net at either:
+You can subscribe to these lists by visiting:
http://lists.sourceforge.net/lists/listinfo/backuppc-announce
http://lists.sourceforge.net/lists/listinfo/backuppc-users
+ http://lists.sourceforge.net/lists/listinfo/backuppc-devel
The backuppc-announce list is moderated and is used only for
important announcements (eg: new versions). It is low traffic.
-You only need to subscribe to one list: backuppc-users also
-receives any messages on backuppc-announce.
+You only need to subscribe to one of backuppc-announce and
+backuppc-users: backuppc-users also receives any messages on
+backuppc-announce.
+
+The backuppc-devel list is only for developers who are working on BackupPC.
+Do not post questions or support requests there. But detailed technical
+discussions should happen on this list.
To post a message to the backuppc-users list, send an email to
=item Other Programs of Interest
If you want to mirror linux or unix files or directories to a remote server
-you should look at rsync, L<http://rsync.samba.org>.
-
-Two popular open source packages that do tape backup are
-Amanda (L<http://www.amanda.org>) and
-afbackup (L<http://sourceforge.net/projects/afbackup>).
+you should consider rsync, L<http://rsync.samba.org>. BackupPC now uses
+rsync as a transport mechanism; if you are already an rsync user you
+can think of BackupPC as adding efficient storage (compression and
+pooling) and a convenient user interface to rsync.
+
+Unison is a utility that can do two-way, interactive, synchronization.
+See L<http://www.cis.upenn.edu/~bcpierce/unison>.
+
+Three popular open source packages that do tape backup are
+Amanda (L<http://www.amanda.org>),
+afbackup (L<http://sourceforge.net/projects/afbackup>), and
+Bacula (L<http://www.bacula.org>).
Amanda can also backup WinXX machines to tape using samba.
These packages can be used as back ends to BackupPC to backup the
BackupPC server data to tape.
-=back
-
-=head2 Road map
-
-Here are some ideas for new features that might appear in future
-releases of BackupPC:
-
-=over 4
-
-=item *
-
-Adding support for rsync as a transport method, in addition to
-smb and tar. This will give big savings in network traffic for
-linux/unix clients. I haven't decided whether to save the pool file
-rsync checksums (that would double the number of files in the pool, but
-eliminate most server disk reads), or recompute them every time. I expect
-to use native rsync on the client side. On the server, rsync would
-need to understand the compressed file format, the file name mangling
-and the attribute files, so I will either have to add features to rsync
-or emulate rsync on the server side in perl.
-
-=item *
-
-Adding a trip wire feature for notification when files below certain
-directories change. For example, if you are backing up a DMZ machine,
-you could request that you get sent email if any files below /bin,
-/sbin or /usr change.
-
-=item *
+Various programs and scripts use rsync to provide hardlinked backups.
+See, for example, Mike Rubel's site (L<http://www.mikerubel.org/computers/rsync_snapshots>),
+JW Schultz's dirvish (L<http://www.dirvish.org>),
+Ben Escoto's rdiff-backup (L<http://rdiff-backup.stanford.edu>),
+and John Bowman's rlbackup (L<http://www.math.ualberta.ca/imaging/rlbackup>).
-Resuming incomplete completed full backups. Useful if a machine
-(eg: laptop) is disconnected from the network during a backup,
-or if the user manually stops a backup. This would work by
-excluding directories that were already complete.
+BackupPC provides many additional features, such as compressed storage,
+hardlinking any matching files (rather than just files with the same name),
+and storing special files without root privileges. But these other scripts
+provide simple and effective solutions and are worthy of consideration.
-=item *
+=back
-More speculative: Storing binary file deltas (in fact, reverse deltas)
-for files that have the same name as a previous backup, but that aren't
-already in the pool. This will save storage for things like mailbox
-files or documents that change slightly between backups. Running some
-benchmarks on a large pool suggests that the potential savings are
-around 15-20%, which isn't spectacular, and likely not worth the
-implementation effort. The program xdelta (v1) on SourceForge (see
-L<http://sourceforge.net/projects/xdelta>) uses an rsync algorithm for
-doing efficient binary file deltas.
+=head2 Road map
-=back
+The new features planned for future releases of BackupPC
+are at L<http://backuppc.sourceforge.net/faq/roadMap.html>.
Comments and suggestions are welcome.
BackupPC already has more than enough features for my own needs. The
main compensation for continuing to work on BackupPC is knowing that
more and more people find it useful. So feedback is certainly
-appreciated. Even negative feedback is helpful, for example "We
-evaluated BackupPC but didn't use it because it doesn't ...".
+appreciated, both positive and negative.
Beyond being a satisfied user and telling other people about it, everyone
-is encouraged to add links to backuppc.sourceforge.net (I'll see then
-via Google) or otherwise publicize BackupPC. Unlike the commercial
-products in this space, I have a zero budget (in both time and money)
-for marketing, PR and advertising, so it's up to all of you!
+is encouraged to add links to L<http://backuppc.sourceforge.net>
+(I'll see then via Google) or otherwise publicize BackupPC. Unlike
+the commercial products in this space, I have a zero budget (in both
+time and money) for marketing, PR and advertising, so it's up to
+all of you! Feel free to vote for BackupPC at
+L<http://freshmeat.net/projects/backuppc>.
Also, everyone is encouraged to contribute patches, bug reports, feature
-and design suggestions, code, and documentation corrections or
-improvements.
+and design suggestions, new code, FAQs, and documentation corrections or
+improvements. Answering questions on the mail list is a big help too.
=head1 Installing BackupPC
you can run. You should be able to run 4-8 simultaneous backups on a
moderately configured server.
+Several users have reported significantly better performance using
+reiser compared to ext3 for the BackupPC data file system. It is
+also recommended you consider either an LVM or raid setup (either
+in HW or SW; eg: 3Ware RAID5) so that you can expand the
+file system as necessary.
+
When BackupPC starts with an empty pool, all the backup data will be
written to the pool on disk. After more backups are done, a higher
percentage of incoming files will already be in the pool. BackupPC is
=item *
Perl version 5.6.0 or later. BackupPC has been tested with
-version 5.6.0 and 5.6.1. If you don't have perl, please see
-L<http://www.cpan.org>.
+version 5.6.x, and 5.8.x. If you don't have perl, please
+see L<http://www.cpan.org>.
=item *
-Perl modules Compress::Zlib and Archive::Zip. Try "perldoc Compress::Zlib"
-and "perldoc Archive::Zip" to see if you have these modules. If not,
-fetch them from L<http://www.cpan.org> and see the instructions below
-for how to build and install them.
+Perl modules Compress::Zlib, Archive::Zip and File::RsyncP. Try "perldoc
+Compress::Zlib" and "perldoc Archive::Zip" to see if you have these
+modules. If not, fetch them from L<http://www.cpan.org> and see the
+instructions below for how to build and install them.
+
+The File::RsyncP module is available from L<http://perlrsync.sourceforge.net>
+or CPAN. You'll need to install the File::RsyncP module if you want to use
+Rsync as a transport method.
=item *
If you are using smb to backup WinXX machines you need smbclient and
nmblookup from the samba package. You will also need nmblookup if
you are backing up linux/unix DHCP machines. See L<http://www.samba.org>.
-Version >= 2.2.0 of Samba is required (smbclient's tar feature in
-2.0.8 and prior has bugs for file path lengths around 100 characters
-and generates bad output when file lengths change during the backup).
+Version 2.2.0 or later of Samba is required.
+Samba versions 3.x are stable and now recommended instead of 2.x.
See L<http://www.samba.org> for source and binaries. It's pretty easy to
fetch and compile samba, and just grab smbclient and nmblookup, without
1.13.7 at a minimum, with version 1.13.20 or higher recommended. Use
"tar --version" to check your version. Various GNU mirrors have the newest
versions of tar, see for example L<http://www.funet.fi/pub/gnu/alpha/gnu/tar>.
-As of July 2002 the latest versons is 1.13.25.
+As of June 2003 the latest version is 1.13.25.
+
+=item *
+
+If you are using rsync to backup linux/unix machines you should have
+version 2.5.5 or higher on each client machine. See
+L<http://rsync.samba.org>. Use "rsync --version" to check your version.
+
+For BackupPC to use Rsync you will also need to install the perl
+File::RsyncP module, which is available from
+L<http://perlrsync.sourceforge.net>.
+Version 0.52 or later is required.
=item *
1200GB of raw data. Because of pooling and compression, only 150GB
is needed.
-Here's a rule of thumb. Add up the C drive usage of all the machines you
+Here's a rule of thumb. Add up the disk usage of all the machines you
want to backup (210GB in the first example above). This is a rough
minimum space estimate that should allow a couple of full backups and at
least half a dozen incremental backups per machine. If compression is on
cannot be read by smbclient whenever Outlook is running. See the
L<Limitations|limitations> section for more discussion of this problem.
+In addition to total disk space, you shold make sure you have
+plenty of inodes on your BackupPC data partition. Some users have
+reported running out of inodes on their BackupPC data partition.
+So even if you have plenty of disk space, BackupPC will report
+failures when the inodes are exhausted. This is a particular
+problem with ext2/ext3 file systems that have a fixed number of
+inodes when the file system is built. Use "df -i" to see your
+inode usage.
+
=head2 Step 1: Getting BackupPC
-Download the latest version from L<http://backuppc.sourceforge.net>.
+Some linux distributions now include BackupPC. The Debian
+distribution, supprted by Ludovic Drolez, can be found at
+L<http://packages.debian.org/backuppc>; it should be included
+in the next stable Debian release. On Debian, BackupPC can
+be installed with the command:
+
+ apt-get install backuppc
+
+In the future there might be packages for Gentoo and other
+linux flavors. If the packaged version is older than the
+released version then you will probably want to install the
+lastest version as described below.
+
+Otherwise, manually fetching and installing BackupPC is easy.
+Start by downloading the latest version from
+L<http://backuppc.sourceforge.net>. Hit the "Code" button,
+then select the "backuppc" or "backuppc-beta" package and
+download the latest version.
=head2 Step 2: Installing the distribution
-First off, to enable compression, you will need to install Compress::Zlib
-from L<http://www.cpan.org>. It is optional, but strongly recommended.
-Also, to support restore via Zip archives you will need to install
-Archive::Zip, also from L<http://www.cpan.org>. You can run
-"perldoc Compress::Zlib" to see if this module is installed.
-To build and install these packages you should run these commands:
+First off, there are three perl modules you should install.
+These are all optional, but highly recommended:
+
+=over 4
+
+=item Compress::Zlib
+
+To enable compression, you will need to install Compress::Zlib
+from L<http://www.cpan.org>.
+You can run "perldoc Compress::Zlib" to see if this module is installed.
+
+=item Archive::Zip
+
+To support restore via Zip archives you will need to install
+Archive::Zip, also from L<http://www.cpan.org>.
+You can run "perldoc Archive::Zip" to see if this module is installed.
+
+=item File::RsyncP
+
+To use rsync and rsyncd with BackupPC you will need to install File::RsyncP.
+You can run "perldoc File::RsyncP" to see if this module is installed.
+File::RsyncP is available from L<http://perlrsync.sourceforge.net>.
+Version 0.52 or later is required.
+
+=back
+
+To build and install these packages, fetch the tar.gz file and
+then run these commands:
tar zxvf Archive-Zip-1.01.tar.gz
cd Archive-Zip-1.01
make test
make install
+The same sequence of commands can be used for each module.
+
Now let's move onto BackupPC itself. After fetching
-BackupPC-1.5.0.tar.gz, run these commands as root:
+BackupPC-__VERSION__.tar.gz, run these commands as root:
- tar zxf BackupPC-1.5.0.tar.gz
- cd BackupPC-1.5.0
+ tar zxf BackupPC-__VERSION__.tar.gz
+ cd BackupPC-__VERSION__
perl configure.pl
-You will be prompted for the full paths of various executables, and
-you will be prompted for the following information:
+In the future this release might also have patches available on the
+SourceForge site. These patch files are text files, with a name of
+the form
+
+ BackupPC-__VERSION__plN.diff
+
+where N is the patch level, eg: pl5 is patch-level 5. These
+patch files are cumulative: you only need apply the last patch
+file, not all the earlier patch files. If a patch file is
+available, eg: BackupPC-__VERSION__pl5.diff, you should apply
+the patch after extracting the tar file:
+
+ # fetch BackupPC-__VERSION__.tar.gz
+ # fetch BackupPC-__VERSION__pl5.diff
+ tar zxf BackupPC-__VERSION__.tar.gz
+ cd BackupPC-__VERSION__
+ patch -p0 < ../BackupPC-__VERSION__pl5.diff
+ perl configure.pl
+
+A patch file includes comments that describe that bug fixes
+and changes. Feel free to review it before you apply the patch.
+
+The configure.pl script also accepts command-line options if you
+wish to run it in a non-interactive manner. It has self-contained
+documentation for all the command-line options, which you can
+read with perldoc:
+
+ perldoc configure.pl
+
+When you run configure.pl you will be prompted for the full paths
+of various executables, and you will be prompted for the following
+information:
=over 4
After running configure.pl, browse through the config file,
__INSTALLDIR__/conf/config.pl, and make sure all the default settings
are correct. In particular, you will need to decide whether to use
-smb or tar transport (or whether to set it on a per-PC basis),
-set the smb share password (if using smb), set the backup policies
-and modify the email message headers and bodies.
-
-BackupPC needs to know the smb share user name and password for each PC
-that uses smb (ie: all the WinXX clients). The user name is specified
-in $Conf{SmbShareUserName}. There are four ways to tell BackupPC the smb
-share password:
-
-=over 4
-
-=item *
-
-As an environment variable PASSWD set before BackupPC starts. If you
-start BackupPC manually this PASSWD must be set manually first.
-
-=item *
-
-Alternatively the PASSWD setting can be included in /etc/init.d/backuppc,
-in which case you must make sure this file is not world (other) readable.
-
-=item *
-
-As a configuration variable $Conf{SmbSharePasswd} in
-__TOPDIR__/conf/config.pl. If you put the password
-here you must make sure this file is not world (other) readable.
-
-=item *
-
-As a configuration variable $Conf{SmbSharePasswd} in the per-PC
-configuration file, __TOPDIR__/pc/$host/config.pl. You will have to
-use this option if the smb share password is different for each host.
-If you put the password here you must make sure this file is not
-world (other) readable.
-
-=back
-
-Placement and protection of the smb share password is a possible
-security risk, so please double-check the file and directory
-permissions. In a future version there might be support for
-encryption of this password, but a private key will still have to
-be stored in a protected place. Suggestions are welcome.
+smb, tar or rsync transport (or whether to set it on a per-PC basis)
+and set the relevant parameters for that transport method.
+See the section L<Client Setup|step 5: client setup> for more details.
=head2 Step 4: Setting up the hosts file
=item Host name
-If this host is a static IP address this must the machine's IP host name
-(ie: something that can be looked up using nslookup or DNS). If this is
-a host with a dynamic IP address (ie: DHCP flag is 1) then the host
-name must be the netbios name of the machine. The host name should
-be in lower case.
+This is typically the host name or NetBios name of the client machine
+and should be in lower case. The host name can contain spaces (escape
+with a backslash), but it is not recommended.
+
+Please read the section L<How BackupPC Finds Hosts|how backuppc finds hosts>.
+
+In certain cases you might want several distinct clients to refer
+to the same physical machine. For example, you might have a database
+you want to backup, and you want to bracket the backup of the database
+with shutdown/restart using $Conf{DumpPreUserCmd} and $Conf{DumpPostUserCmd}.
+But you also want to backup the rest of the machine while the database
+is still running. In the case you can specify two different clients in
+the host file, using any mnemonic name (eg: myhost_mysql and myhost), and
+use $Conf{ClientNameAlias} in myhost_mysql's config.pl to specify the
+real host name of the machine.
=item DHCP flag
-Set to 0 if this host has a static IP address (meaning it can be looked
-up by name in the DNS). If the host's IP address is dynamic (eg, it is
-assigned by DHCP) then set this flag to 1.
+Starting with v2.0.0 the way hosts are discovered has changed and now
+in most cases you should specify 0 for the DHCP flag, even if the host
+has a dynamically assigned IP address.
+Please read the section L<How BackupPC Finds Hosts|how backuppc finds hosts>
+to understand whether you need to set the DHCP flag.
+
+You only need to set DHCP to 1 if your client machine doesn't
+respond to the NetBios multicast request:
+
+ nmblookup myHost
-The hosts with dhcp = 1 are backed up as follows. If you have
-configured a DHCP address pool ($Conf{DHCPAddressRanges}) then
-BackupPC will check the NetBIOS name of each machine in the
-range. Any hosts that have a valid NetBIOS name (ie: matching
-an entry in the hosts file) will be backed up.
+but does respond to a request directed to its IP address:
+
+ nmblookup -A W.X.Y.Z
+
+If you do set DHCP to 1 on any client you will need to specify the range of
+DHCP addresses to search is specified in $Conf{DHCPAddressRanges}.
+
+Note also that the $Conf{ClientNameAlias} feature does not work for
+clients with DHCP set to 1.
=item User name
receive email or be allowed to stop/start/browse/restore backups
for this host. Administrators will still have full permissions.
+=item More users
+
+Additional user names, separate by commas and with no white space,
+can be specified. These users will also have full permission in
+the CGI interface to stop/start/browse/restore backups for this host.
+These users will not be sent email about this host.
+
=back
The first non-comment line of the hosts file is special: it contains
Here's a simple example of a hosts file:
- host dhcp user
- farside 0 craig
- larson 1 gary
-
-The range of DHCP addresses to search is specified in
-$Conf{DHCPAddressRanges}.
+ host dhcp user moreUsers
+ farside 0 craig jim,dave
+ larson 1 gary andy
=head2 Step 5: Client Setup
-Two methods for getting backup data from a client are
-supported: smb and tar. Smb is the preferred method for WinXX clients
-and tar is preferred method for linux/unix clients.
+Two methods for getting backup data from a client are supported: smb and
+tar. Smb or rsync are the preferred methods for WinXX clients and rsync or
+tar are the preferred methods for linux/unix clients.
The transfer method is set using the $Conf{XferMethod} configuration
setting. If you have a mixed environment (ie: you will use smb for some
=item WinXX
The preferred setup for WinXX clients is to set $Conf{XferMethod} to "smb".
-
-You need to create shares for the data you want to backup.
-Open "My Computer", right click on the drive (eg: C), and
-select "Sharing..." (or select "Properties" and select the
-"Sharing" tab). In this dialog box you can enable sharing,
-select the share name and permissions.
+(Actually, for v2.0.0, rsyncd is the better method for WinXX if you are
+prepared to run rsync/cygwin on your WinXX client. More information
+about this will be provided via the FAQ.)
+
+If you want to use rsyncd for WinXX clients you can find a pre-packaged
+zip file on L<http://backuppc.sourceforge.net>. The package is called
+cygwin-rsync. It contains rsync.exe, template setup files and the
+minimal set of cygwin libraries for everything to run. The README file
+contains instructions for running rsync as a service, so it starts
+automatically everytime you boot your machine.
+
+If you build your own rsync, for rsync 2.6.2 it is strongly
+recommended you apply the patch in the cygwin-rsync package on
+L<http://backuppc.sourceforge.net>. This patch adds the --checksum-seed
+option for checksum caching, and also sends all errors to the client,
+which is important so BackupPC can log all file access errors.
+
+Otherwise, to use SMB, you need to create shares for the data you want
+to backup. Open "My Computer", right click on the drive (eg: C), and
+select "Sharing..." (or select "Properties" and select the "Sharing"
+tab). In this dialog box you can enable sharing, select the share name
+and permissions. Many machines will be configured by default to share
+the entire C drive as C$ using the administrator password.
If this machine uses DHCP you will also need to make sure the
NetBios name is set. Go to Control Panel|System|Network Identification
Connection|Properties|Internet Protocol (TCP/IP)|Properties|Advanced|WINS
and verify that NetBios is not disabled.
+The relevant configuration settings are $Conf{SmbShareName},
+$Conf{SmbShareUserName}, $Conf{SmbSharePasswd}, $Conf{SmbClientPath},
+$Conf{SmbClientFullCmd}, $Conf{SmbClientIncrCmd} and
+$Conf{SmbClientRestoreCmd}.
+
+BackupPC needs to know the smb share user name and password for a
+client machine that uses smb. The user name is specified in
+$Conf{SmbShareUserName}. There are four ways to tell BackupPC the
+smb share password:
+
+=over 4
+
+=item *
+
+As an environment variable BPC_SMB_PASSWD set before BackupPC starts.
+If you start BackupPC manually the BPC_SMB_PASSWD variable must be set
+manually first. For backward compatibility for v1.5.0 and prior, the
+environment variable PASSWD can be used if BPC_SMB_PASSWD is not set.
+Warning: on some systems it is possible to see environment variables of
+running processes.
+
+=item *
+
+Alternatively the BPC_SMB_PASSWD setting can be included in
+/etc/init.d/backuppc, in which case you must make sure this file
+is not world (other) readable.
+
+=item *
+
+As a configuration variable $Conf{SmbSharePasswd} in
+__TOPDIR__/conf/config.pl. If you put the password
+here you must make sure this file is not world (other) readable.
+
+=item *
+
+As a configuration variable $Conf{SmbSharePasswd} in the per-PC
+configuration file, __TOPDIR__/pc/$host/config.pl. You will have to
+use this option if the smb share password is different for each host.
+If you put the password here you must make sure this file is not
+world (other) readable.
+
+=back
+
+Placement and protection of the smb share password is a possible
+security risk, so please double-check the file and directory
+permissions. In a future version there might be support for
+encryption of this password, but a private key will still have to
+be stored in a protected place. Suggestions are welcome.
+
As an alternative to setting $Conf{XferMethod} to "smb" (using
smbclient) for WinXX clients, you can use an smb network filesystem (eg:
ksmbfs or similar) on your linux/unix server to mount the share,
mounted file system).
Also, to make sure that file names with 8-bit characters are correctly
-transferred by smbclient you should add this to samba's smb.conf file:
+transferred by smbclient you should add this to samba's smb.conf file
+for samba 2.x:
[global]
# Accept the windows charset
client code page = 850
character set = ISO8859-1
+For samba 3.x this should instead be:
+
+ [global]
+ unix charset = ISO8859-1
+
This setting should work for western europe.
See L<http://www.oreilly.com/catalog/samba/chapter/book/ch08_03.html>
for more information about settings for other languages.
=item Linux/Unix
The preferred setup for linux/unix clients is to set $Conf{XferMethod}
-to "tar".
+to "rsync", "rsyncd" or "tar".
-You can use either smb or tar for linux/unix machines. Smb requires that
-the Samba server (smbd) be run to provide the shares. Since the smb
+You can use either rsync, smb, or tar for linux/unix machines. Smb requires
+that the Samba server (smbd) be run to provide the shares. Since the smb
protocol can't represent special files like symbolic links and fifos,
-tar is the recommended transport method for linux/unix machines.
+tar and rsync are the better transport methods for linux/unix machines.
(In fact, by default samba makes symbolic links look like the file or
directory that they point to, so you could get an infinite loop if a
symbolic link points to the current or parent directory. If you really
need to use Samba shares for linux/unix backups you should turn off the
"follow symlinks" samba config setting. See the smb.conf manual page.)
-The rest of this section describes the tar setup.
+The requirements for each Xfer Method are:
+
+=over 4
+
+=item tar
You must have GNU tar on the client machine. Use "tar --version"
or "gtar --version" to verify. The version should be at least
-1.13.7, and 1.13.20 or greater is recommended.
+1.13.7, and 1.13.20 or greater is recommended. Tar is run on
+the client machine via rsh or ssh.
+
+The relevant configuration settings are $Conf{TarClientPath},
+$Conf{TarShareName}, $Conf{TarClientCmd}, $Conf{TarFullArgs},
+$Conf{TarIncrArgs}, and $Conf{TarClientRestoreCmd}.
+
+=item rsync
+
+You should have at least rsync 2.5.5, and the latest version 2.5.6
+is recommended. Rsync is run on the remote client via rsh or ssh.
-For linux/unix machines you should no backup "/proc". This directory
+The relevant configuration settings are $Conf{RsyncClientPath},
+$Conf{RsyncClientCmd}, $Conf{RsyncClientRestoreCmd}, $Conf{RsyncShareName},
+$Conf{RsyncArgs}, and $Conf{RsyncRestoreArgs}.
+
+=item rsyncd
+
+You should have at least rsync 2.5.5, and the latest version 2.6.2
+is recommended. In this case the rsync daemon should be running on
+the client machine and BackupPC connects directly to it.
+
+The relevant configuration settings are $Conf{RsyncdClientPort},
+$Conf{RsyncdUserName}, $Conf{RsyncdPasswd}, $Conf{RsyncdAuthRequired},
+$Conf{RsyncShareName}, $Conf{RsyncArgs}, and $Conf{RsyncRestoreArgs}.
+$Conf{RsyncShareName} is the name of an rsync module (ie: the thing
+in square brackets in rsyncd's conf file -- see rsyncd.conf), not a
+file system path.
+
+Be aware that rsyncd will remove the leading '/' from path names in
+symbolic links if you specify "use chroot = no" in the rsynd.conf file.
+See the rsyncd.conf manual page for more information.
+
+=back
+
+For linux/unix machines you should not backup "/proc". This directory
contains a variety of files that look like regular files but they are
special files that don't need to be backed up (eg: /proc/kcore is a
regular file that contains physical memory). See $Conf{BackupFilesExclude}.
(eg: backing up /dev/hda5 just saves the block-special file information,
not the contents of the disk).
+Alternatively, rather than backup all the file systems as a single
+share ("/"), it is easier to restore a single file system if you backup
+each file system separately. To do this you should list each file system
+mount point in $Conf{TarShareName} or $Conf{RsyncShareName}, and add the
+--one-file-system option to $Conf{TarClientCmd} or add --one-file-system
+(note the different punctuation) to $Conf{RsyncArgs}. In this case there
+is no need to exclude /proc explicitly since it looks like a different
+file system.
+
Next you should decide whether to run tar over ssh, rsh or nfs. Ssh is
the preferred method. Rsh is not secure and therefore not recommended.
Nfs will work, but you need to make sure that the BackupPC user (running
files. Ssh is setup so that BackupPC on the server (an otherwise low
privileged user) can ssh as root on the client, without being prompted
for a password. There are two common versions of ssh: v1 and v2. Here
-are some instructions for one way to setup ssh v2:
-
-=over 4
-
-=item Key generation
-
-As root on the client machine, use ssh2-keygen to generate a
-public/private key pair, without a pass-phrase:
-
- ssh-keygen2 -t rsa -P
-
-This will save the public key in /.ssh2/id_rsa_1024_a.pub and the private
-key in /.ssh2/id_rsa_1024_a.
-
-=item Identification
+are some instructions for one way to setup ssh. (Check which version
+of SSH you have by typing "ssh" or "man ssh".)
-Create the identification file /.ssh2/identification:
+=item Mac OS X
- echo "IdKey id_rsa_1024_a" > /.ssh2/identification
+In general this should be similar to Linux/Unix machines.
+Mark Stosberg reports that you can also use hfstar.
+See L<http://fink.sourceforge.net/pdb/package.php/hfstar>.
-=item BackupPC setup
+=item SSH Setup
-Repeat the above steps for the BackupPC user (__BACKUPPCUSER__) on the server.
-Rename the key files to recognizable names, eg:
+SSH is a secure way to run tar or rsync on a backup client to extract
+the data. SSH provides strong authentication and encryption of
+the network data.
- ssh-keygen2 -t rsa -P
- mv ~/.ssh2/id_rsa_1024_a.pub ~/.ssh2/BackupPC_id_rsa_1024_a.pub
- mv ~/.ssh2/id_rsa_1024_a ~/.ssh2/BackupPC_id_rsa_1024_a
- echo "IdKey BackupPC_id_rsa_1024_a" > ~/.ssh2/identification
+Note that if you run rsyncd (rsync daemon), ssh is not used.
+In this case, rsyncd provides its own authentication, but there
+is no encryption of network data. If you want encryption of
+network data you can use ssh to create a tunnel, or use a
+program like stunnel. If someone submits instructions I
-Based on your ssh2 configuration, you might also need to turn off
-StrictHostKeyChecking and PasswordAuthentication:
+Setup instructions for ssh are at
+L<http://backuppc.sourceforge.net/faq/ssh.html>.
- touch ~/.ssh2/ssh2_config
- echo "StrictHostKeyChecking ask" >> ~/.ssh2/ssh2_config
- echo "PasswordAuthentication no" >> ~/.ssh2/ssh2_config
+=item Clients that use DHCP
-=item Key exchange
+If a client machine uses DHCP BackupPC needs some way to find the
+IP address given the host name. One alternative is to set dhcp
+to 1 in the hosts file, and BackupPC will search a pool of IP
+addresses looking for hosts. More efficiently, it is better to
+set dhcp = 0 and provide a mechanism for BackupPC to find the
+IP address given the host name.
-To allow BackupPC to ssh to the client as root, you need to place
-BackupPC's public key into root's authorized list on the client.
-Copy BackupPC's public key (BackupPC_id_rsa_1024_a.pub) to the
-/.ssh2 directory on the client. Add the following line to the
-/.ssh2/authorization file on the client (as root):
+For WinXX machines BackupPC uses the NetBios name server to determine
+the IP address given the host name.
+For unix machines you can run nmbd (the NetBios name server) from
+the Samba distribution so that the machine responds to a NetBios
+name request. See the manual page and Samba documentation for more
+information.
- touch /.ssh2/authorization
- echo "Key BackupPC_id_rsa_1024_a.pub" >> /.ssh2/authorization
+Alternatively, you can set $Conf{NmbLookupFindHostCmd} to any command
+that returns the IP address given the host name.
-=item Fix permissions
-
-You will probably need to make sure that all the files
-in /.ssh2 have no group or other read/write permission:
-
- chmod -R go-rwx /.ssh2
-
-You should do the same thing for the BackupPC user on the server.
-
-=item Testing
-
-As the BackupPC user on the server, verify that this command:
-
- ssh2 -l root clientHostName whoami
-
-prints
-
- root
-
-You might be prompted the first time to accept the client's host key and
-you might be prompted for root's password on the client. Make sure that
-this command runs cleanly with no prompts after the first time. You
-might need to check /etc/hosts.equiv on the client. Look at the
-man pages for more information. The "-v" option to ssh2 is a good way
-to get detailed information about what fails.
-
-=item ssh version 1 instructions
-
-The concept is identical and the steps are similar, but the specific
-commands and file names are slightly different.
-
-First, run ssh-keygen on the client (as root) and server (as the BackupPC
-user) and simply hit enter when prompted for the pass-phrase:
-
- ssh-keygen
-
-This will save the public key in /.ssh/identity.pub and the private
-key in /.ssh/identity.
-
-Next, append BackupPC's ~/.ssh/identity.pub (from the server) to root's
-/.ssh/authorized_keys file on the client. It's a single long line that
-you can cut-and-paste with an editor (make sure it remains a single line).
-
-Next, force protocol version 1 by adding:
-
- Protocol 1
-
-to BackupPC's ~/.ssh/config on the server.
-
-Next, run "chmod -R go-rwx ~/.ssh" on the server and "chmod -R go-rwx /.ssh"
-on the client.
-
-Finally, test using:
-
- ssh -l root clientHostName whoami
-
-=back
-
-Finally, if this machine uses DHCP you will need to run nmbd (the
-NetBios name server) from the Samba distribution so that the machine
-responds to a NetBios name request. See the manual page and Samba
-documentation for more information.
+Please read the section L<How BackupPC Finds Hosts|how backuppc finds hosts>
+for more details.
=back
flavors of unix and linux.
To see if your perl has setuid emulation, see if there is a program
-called sperl5.6.0 or sperl5.6.1 in the place where perl is installed.
-If you can't find this program, then you have two options: rebuild
-and reinstall perl with the setuid emulation turned on (answer "y" to
-the question "Do you want to do setuid/setgid emulation?" when you
-run perl's configure script), or switch to the mod_perl alternative
-for the CGI script (which doesn't need setuid to work).
+called sperl5.6.0 (or sperl5.8.2 etc, based on your perl version)
+in the place where perl is installed. If you can't find this program,
+then you have two options: rebuild and reinstall perl with the setuid
+emulation turned on (answer "y" to the question "Do you want to do
+setuid/setgid emulation?" when you run perl's configure script), or
+switch to the mod_perl alternative for the CGI script (which doesn't
+need setuid to work).
=item Mod_perl Setup
chmod u-s __CGIDIR__/BackupPC_Admin
To tell Apache to use mod_perl to execute BackupPC_Admin, add this
-to Apache's httpd.conf file:
+to Apache's 1.x httpd.conf file:
<IfModule mod_perl.c>
PerlModule Apache::Registry
+ PerlTaintCheck On
<Location /cgi-bin/BackupPC/BackupPC_Admin> # <--- change path as needed
SetHandler perl-script
PerlHandler Apache::Registry
Options ExecCGI
+ PerlSendHeader On
</Location>
</IfModule>
+Apache 2.0.44 with Perl 5.8.0 on RedHat 7.1, Don Silvia reports that
+this works (with tweaks from Michael Tuzi):
+
+ LoadModule perl_module modules/mod_perl.so
+ PerlModule Apache2
+
+ <Directory /path/to/cgi/>
+ SetHandler perl-script
+ PerlResponseHandler ModPerl::Registry
+ PerlOptions +ParseHeaders
+ Options +ExecCGI
+ Order deny,allow
+ Deny from all
+ Allow from 192.168.0
+ AuthName "Backup Admin"
+ AuthType Basic
+ AuthUserFile /path/to/user_file
+ Require valid-user
+ </Directory>
+
There are other optimizations and options with mod_perl. For
example, you can tell mod_perl to preload various perl modules,
which saves memory compared to loading separate copies in every
-Apache process after they are forked. See Stas's definitive
+Apache process after they are forked. See Stas's definitive
mod_perl guide at L<http://perl.apache.org/guide>.
=back
require valid-user
</Location>
-If you want to defeat the user authentication you can force a
-particular user name by getting Apache to set REMOTE_USER, eg,
-to hardcode the user to www you could add this to httpd.conf:
+If you want to disable the user authentication you can set
+$Conf{CgiAdminUsers} to '*', which allows any user to have
+full access to all hosts and backups. In this case the REMOTE_USER
+environment variable does not have to be set by Apache.
+
+Alternatively, you can force a particular user name by getting Apache
+to set REMOTE_USER, eg, to hardcode the user to www you could add
+this to Apache's httpd.conf:
<Location /cgi-bin/BackupPC/BackupPC_Admin> # <--- change path as needed
Setenv REMOTE_USER www
Finally, you should also edit the config.pl file and adjust, as necessary,
the CGI-specific settings. They're near the end of the config file. In
particular, you should specify which users or groups have administrator
-(privileged) access. Also, the configure.pl script placed various
+(privileged) access: see the config settings $Conf{CgiAdminUserGroup}
+and $Conf{CgiAdminUsers}. Also, the configure.pl script placed various
images into $Conf{CgiImageDir} that BackupPC_Admin needs to serve
up. You should make sure that $Conf{CgiImageDirURL} is the correct
URL for the image directory.
+See the section L<Fixing installation problems|fixing installation problems> for suggestions on debugging the Apache authentication setup.
+
+=head2 How BackupPC Finds Hosts
+
+Starting with v2.0.0 the way hosts are discovered has changed. In most
+cases you should specify 0 for the DHCP flag in the conf/hosts file,
+even if the host has a dynamically assigned IP address.
+
+BackupPC (starting with v2.0.0) looks up hosts with DHCP = 0 in this manner:
+
+=over 4
+
+=item *
+
+First DNS is used to lookup the IP address given the client's name
+using perl's gethostbyname() function. This should succeed for machines
+that have fixed IP addresses that are known via DNS. You can manually
+see whether a given host have a DNS entry according to perls'
+gethostbyname function with this command:
+
+ perl -e 'print(gethostbyname("myhost") ? "ok\n" : "not found\n");'
+
+=item *
+
+If gethostbyname() fails, BackupPC then attempts a NetBios multicast to
+find the host. Provided your client machine is configured properly,
+it should respond to this NetBios multicast request. Specifically,
+BackupPC runs a command of this form:
+
+ nmblookup myhost
+
+If this fails you will see output like:
+
+ querying myhost on 10.10.255.255
+ name_query failed to find name myhost
+
+If this success you will see output like:
+
+ querying myhost on 10.10.255.255
+ 10.10.1.73 myhost<00>
+
+Depending on your netmask you might need to specify the -B option to
+nmblookup. For example:
+
+ nmblookup -B 10.10.1.255 myhost
+
+If necessary, experiment on the nmblookup command that will return the
+IP address of the client given its name. Then update
+$Conf{NmbLookupFindHostCmd} with any necessary options to nmblookup.
+
+=back
+
+For hosts that have the DHCP flag set to 1, these machines are
+discovered as follows:
+
+=over 4
+
+=item *
+
+A DHCP address pool ($Conf{DHCPAddressRanges}) needs to be specified.
+BackupPC will check the NetBIOS name of each machine in the range using
+a command of the form:
+
+ nmblookup -A W.X.Y.Z
+
+where W.X.Y.Z is each candidate address from $Conf{DHCPAddressRanges}.
+Any host that has a valid NetBIOS name returned by this command (ie:
+matching an entry in the hosts file) will be backed up. You can
+modify the specific nmblookup command if necessary via $Conf{NmbLookupCmd}.
+
+=item *
+
+You only need to use this DHCP feature if your client machine doesn't
+respond to the NetBios multicast request:
+
+ nmblookup myHost
+
+but does respond to a request directed to its IP address:
+
+ nmblookup -A W.X.Y.Z
+
+=back
+
=head2 Other installation topics
=over 4
+=item Removing a client
+
+If there is a machine that no longer needs to be backed up (eg: a retired
+machine) you have two choices. First, you can keep the backups accessible
+and browsable, but disable all new backups. Alternatively, you can
+completely remove the client and all its backups.
+
+To disable backups for a client there are two special values for
+$Conf{FullPeriod} in that client's per-PC config.pl file:
+
+=over 4
+
+=item -1
+
+Don't do any regular backups on this machine. Manually
+requested backups (via the CGI interface) will still occur.
+
+=item -2
+
+Don't do any backups on this machine. Manually requested
+backups (via the CGI interface) will be ignored.
+
+=back
+
+This will still allow that client's old backups to be browsable
+and restorable.
+
+To completely remove a client and all its backups, you should remove its
+entry in the conf/hosts file, and then delete the __TOPDIR__/pc/$host
+directory. Whenever you change the hosts file, you should send
+BackupPC a HUP (-1) signal so that it re-reads the hosts file.
+If you don't do this, BackupPC will automatically re-read the
+hosts file at the next regular wakeup.
+
+Note that when you remove a client's backups you won't initially recover
+a lot of disk space. That's because the client's files are still in
+the pool. Overnight, when BackupPC_nightly next runs, all the unused
+pool files will be deleted and this will recover the disk space used
+by the client's backups.
+
=item Copying the pool
If the pool disk requirements grow you might need to copy the entire
=back
-=head2 Debugging installation problems
-
-This section will probably grow based on the types of questions on
-the BackupPC mail list.
+=head2 Fixing installation problems
-Assuming BackupPC can start correctly you should inspect __TOPDIR__/log/LOG
-for any errors. Assuming backups for a particular host start, you
-should be able to look in __TOPDIR__/pc/$host/LOG for error messages
-specific to that host.
-
-The most likely problems will relate to connecting to the smb shares on
-each host. On each failed backup, a file __TOPDIR__/pc/$host/XferERR will
-be created. This is the stderr output from smbclient. The first line
-will show the full smbclient command that was run. Based on the error
-messages you should figure out what is wrong. Possible errors on the
-server side are invalid host, invalid share name, bad username or password.
-Possible errors on the client side are misconfiguration of the share,
-username or password.
-
-You should run smbclient manually and verify that you can connect to
-the host in interactive mode, eg:
-
- smbclient '\\hostName\shareName' -U userName
-
-shareName should match the $Conf{SmbShareName} setting and userName
-should match the the $Conf{SmbShareUserName} setting.
-
-You will be prompted for the password. You should then see this prompt:
-
- smb: \>
-
-Verify that "ls" works and then type "quit" to exit.
-
-Secondly, you should also verify that nmblookup correctly returns
-the netbios name. This is essential for DHCP hosts, and depending
-upon the setting of $Conf{FixedIPNetBiosNameCheck} might also be
-required for fixed IP address hosts too. Run this command:
-
- nmblookup -A hostName
-
-Verify that the host name is printed. The output might look like:
-
- received 7 names
- DELLLS13 <00> - P <ACTIVE>
- DOMAINNAME <00> - <GROUP> P <ACTIVE>
- DELLLS13 <20> - P <ACTIVE>
- DOMAINNAME <1e> - <GROUP> P <ACTIVE>
- DELLLS13 <03> - P <ACTIVE>
- DELLLS13$ <03> - P <ACTIVE>
- CRAIG <03> - P <ACTIVE>
-
-The first name, converted to lower case, is used for the host name.
+Please see the FAQ at L<http://backuppc.sourceforge.net/faq> for
+debugging suggestions.
=head1 Restore functions
before you commit. When you give the final go ahead the restore
operation will be queued like a normal backup job, meaning that it
will be deferred if there is a backup currently running for that host.
-When the restore job is run, smbclient or tar is used (depending upon
-$Conf{XferMethod}) to actually restore the files. Sorry, there is
-currently no option to cancel a restore that has been started.
+When the restore job is run, smbclient, tar, rsync or rsyncd is used
+(depending upon $Conf{XferMethod}) to actually restore the files.
+Sorry, there is currently no option to cancel a restore that has been
+started.
A record of the restore request, including the result and list of
files and directories, is kept. It can be browsed from the host's
home page. $Conf{RestoreInfoKeepCnt} specifies how many old restore
status files to keep.
+Note that for direct restore to work, the $Conf{XferMethod} must
+be able to write to the client. For example, that means an SMB
+share for smbclient needs to be writable, and the rsyncd module
+needs "read only" set to "false". This creates additional security
+risks. If you only create read-only SMB shares (which is a good
+idea), then the direct restore will fail. You can disable the
+direct restore option by setting $Conf{SmbClientRestoreCmd},
+$Conf{TarClientRestoreCmd} and $Conf{RsyncRestoreArgs} to undef.
+
=item Option 2: Download Zip archive
With this option a zip file containing the selected files and directories
It's your responsibility to make sure the file is really compressed:
BackupPC_zcat doesn't check which backup the requested file is from.
+BackupPC_zcat returns a non-zero status if it fails to uncompress
+a file.
=item BackupPC_tarCreate
The usage is:
BackupPC_tarCreate [-t] [-h host] [-n dumpNum] [-s shareName]
- [-r pathRemove] [-p pathAdd]
+ [-r pathRemove] [-p pathAdd] [-b BLOCKS] [-w writeBufSz]
files/directories...
The command-line files and directories are relative to the specified
new path prefix
-=back
+=item -b BLOCKS
-The -h, -n and -s options specify which dump is used to generate
-the tar archive. The -r and -p options can be used to relocate
+the tar block size, default is 20, meaning tar writes data in 20 * 512
+bytes chunks.
+
+=item -w writeBufSz
+
+write buffer size, default 1048576 (1MB). You can increase this if
+you are trying to stream to a fast tape device.
+
+=back
+
+The -h, -n and -s options specify which dump is used to generate
+the tar archive. The -r and -p options can be used to relocate
the paths in the tar archive so extracted files can be placed
in a location different from their original location.
Each of these programs reside in __INSTALLDIR__/bin.
+=head1 Archive functions
+
+BackupPC supports archiving to removable media. For users that require
+offsite backups, BackupPC can create archives that stream to tape
+devices, or create files of specified sizes to fit onto cd or dvd media.
+
+Each archive type is specified by a BackupPC host with its XferMethod
+set to 'archive'. This allows for multiple configurations at sites where
+there might be a combination of tape and cd/dvd backups being made.
+
+BackupPC provides a menu that allows one or more hosts to be archived.
+The most recent backup of each host is archived using BackupPC_tarCreate,
+and the output is optionally compressed and split into fixed-sized
+files (eg: 650MB).
+
+The archive for each host is done by default using
+__INSTALLDIR__/BackupPC_archiveHost. This script can be copied
+and customized as needed.
+
+=head2 Configuring an Archive Host
+
+To create an Archive Host, add it to the hosts file just as any other host
+and call it a name that best describes the type of archive, e.g. ArchiveDLT
+
+To tell BackupPC that the Host is for Archives, create a config.pl file in
+the Archive Hosts's pc directory, adding the following line:
+
+$Conf{XferMethod} = 'archive';
+
+To further customise the archive's parameters you can adding the changed
+parameters in the host's config.pl file. The parameters are explained in
+the config.pl file. Parameters may be fixed or the user can be allowed
+to change them (eg: output device).
+
+The per-host archive command is $Conf{ArchiveClientCmd}. By default
+this invokes
+
+ __INSTALLDIR__/BackupPC_archiveHost
+
+which you can copy and customize as necessary.
+
+=head2 Starting an Archive
+
+In the web interface, click on the Archive Host you wish to use. You will see a
+list of previous archives and a summary on each. By clicking the "Start Archive"
+button you are presented with the list of hosts and the approximate backup size
+(note this is raw size, not projected compressed size) Select the hosts you wish
+to archive and press the "Archive Selected Hosts" button.
+
+The next screen allows you to adjust the parameters for this archive run.
+Press the "Start the Archive" to start archiving the selected hosts with the
+parameters displayed.
+
=head1 BackupPC Design
=head2 Some design issues
Identical files on multiples backups are represented by hard links.
Hardlinks are used so that identical files all refer to the same
physical file on the server's disk. Also, hard links maintain
-reference counts so that BackupPC knows when to deleted unused files
+reference counts so that BackupPC knows when to delete unused files
from the pool.
For the computer-science majors among you, you can think of the pooling
=item 2
For each PC, BackupPC_dump is forked. Several of these may be run in
-parallel, based on the configuration. First a ping is done to see if the
-machine is alive. If this is a DHCP address, nmblookup is run to get
-the netbios name, which is used as the host name. The file
-__TOPDIR__/pc/$host/backups is read to decide whether a full or
-incremental backup needs to be run. If no backup is scheduled, or the ping
-to $host fails, then BackupPC_dump exits.
-
-The backup is done using samba's smbclient or tar over ssh/rsh/nfs piped
-into BackupPC_tarExtract, extracting the backup into __TOPDIR__/pc/$host/new.
-The smbclient or tar output is put into __TOPDIR__/pc/$host/XferLOG.
-
-As BackupPC_tarExtract extracts the files from smbclient, it checks each
-file in the backup to see if it is identical to an existing file from
-any previous backup of any PC. It does this without needed to write the
-file to disk. If the file matches an existing file, a hardlink is
-created to the existing file in the pool. If the file does not match any
-existing files, the file is written to disk and the file name is saved
-in __TOPDIR__/pc/$host/NewFileList for later processing by
-BackupPC_link. BackupPC_tarExtract can handle arbitrarily large
-files and multiple candidate matching files without needing to
-write the file to disk in the case of a match. This significantly
-reduces disk writes (and also reads, since the pool file comparison
-is done disk to memory, rather than disk to disk).
+parallel, based on the configuration. First a ping is done to see if
+the machine is alive. If this is a DHCP address, nmblookup is run to
+get the netbios name, which is used as the host name. If DNS lookup
+fails, $Conf{NmbLookupFindHostCmd} is run to find the IP address from
+the host name. The file __TOPDIR__/pc/$host/backups is read to decide
+whether a full or incremental backup needs to be run. If no backup is
+scheduled, or the ping to $host fails, then BackupPC_dump exits.
+
+The backup is done using the specified XferMethod. Either samba's smbclient
+or tar over ssh/rsh/nfs piped into BackupPC_tarExtract, or rsync over ssh/rsh
+is run, or rsyncd is connected to, with the incoming data
+extracted to __TOPDIR__/pc/$host/new. The XferMethod output is put
+into __TOPDIR__/pc/$host/XferLOG.
+
+The letter in the XferLOG file shows the type of object, similar to the
+first letter of the modes displayed by ls -l:
+
+ d -> directory
+ l -> symbolic link
+ b -> block special file
+ c -> character special file
+ p -> pipe file (fifo)
+ nothing -> regular file
+
+The words mean:
+
+=over 4
+
+=item create
+
+new for this backup (ie: directory or file not in pool)
+
+=item pool
+
+found a match in the pool
+
+=item same
+
+file is identical to previous backup (contents were
+checksummed and verified during full dump).
+
+=item skip
+
+file skipped in incremental because attributes are the
+same (only displayed if $Conf{XferLogLevel} >= 2).
+
+=back
+
+As BackupPC_tarExtract extracts the files from smbclient or tar, or as
+rsync runs, it checks each file in the backup to see if it is identical
+to an existing file from any previous backup of any PC. It does this
+without needed to write the file to disk. If the file matches an
+existing file, a hardlink is created to the existing file in the pool.
+If the file does not match any existing files, the file is written to
+disk and the file name is saved in __TOPDIR__/pc/$host/NewFileList for
+later processing by BackupPC_link. BackupPC_tarExtract and rsync can handle
+arbitrarily large files and multiple candidate matching files without
+needing to write the file to disk in the case of a match. This
+significantly reduces disk writes (and also reads, since the pool file
+comparison is done disk to memory, rather than disk to disk).
Based on the configuration settings, BackupPC_dump checks each
old backup to see if any should be removed. Any expired backups
is new, a hard link to the file is made in the pool area, so that this
file is available for checking against each new file and new backup.
-Then, assuming $Conf{IncrFill} is set, for each incremental backup,
-hard links are made in the new backup to all files that were not extracted
-during the incremental backups. The means the incremental backup looks
-like a complete image of the PC (with the exception that files
-that were removed on the PC since the last full backup will still
-appear in the backup directory tree).
-
-As of v1.03, the CGI interface knows how to merge unfilled
-incremental backups will the most recent prior filled (full)
-backup, giving the incremental backups a filled appearance. The
-default for $Conf{IncrFill} is off, since there is now no need to
-fill incremental backups. This saves some level of disk activity,
-since lots of extra hardlinks are no longer needed (and don't have
-to be deleted when the backup expires).
+Then, if $Conf{IncrFill} is set (note that the default setting is
+off), for each incremental backup, hard links are made in the new
+backup to all files that were not extracted during the incremental
+backups. The means the incremental backup looks like a complete
+image of the PC (with the exception that files that were removed on
+the PC since the last full backup will still appear in the backup
+directory tree).
+
+The CGI interface knows how to merge unfilled incremental backups will
+the most recent prior filled (full) backup, giving the incremental
+backups a filled appearance. The default for $Conf{IncrFill} is off,
+since there is no need to fill incremental backups. This saves
+some level of disk activity, since lots of extra hardlinks are no
+longer needed (and don't have to be deleted when the backup expires).
=item 4
any files in the pool that only have a single hard link (meaning no backups
are using that file). Again, to avoid race conditions, BackupPC_nightly
is only run when there are no BackupPC_dump or BackupPC_link processes
-running.
+running. Therefore, when it is time to run BackupPC_nightly, no new
+backups are started and BackupPC waits until all backups have finished.
+Then BackupPC_nightly is run, and until it finishes no new backups are
+started. If BackupPC_nightly is slow, the settings
=back
=item XferERR or XferERR.z
-Output from the transport program (ie: smbclient or tar)
+Output from the transport program (ie: smbclient, tar or rsync)
for the most recent failed backup.
=item new
=item XferLOG or XferLOG.z
-Output from the transport program (ie: smbclient or tar)
+Output from the transport program (ie: smbclient, tar or rsync)
for the current backup.
=item nnn (an integer)
=item XferLOG.nnn or XferLOG.nnn.z
-Output from the transport program (ie: smbclient or tar)
+Output from the transport program (ie: smbclient, tar or rsync)
corresponding to backup number nnn.
=item RestoreInfo.nnn
=item RestoreLOG.nnn.z
-Output from smbclient or tar during restore #nnn. (Note that the restore
+Output from smbclient, tar or rsync during restore #nnn. (Note that the restore
numbers are not related to the backup number.)
+=item ArchiveInfo.nnn
+
+Information about archive request #nnn including who, what, when, and
+why. This file is in Data::Dumper format. (Note that the archive
+numbers are not related to the restore or backup number.)
+
+=item ArchiveLOG.nnn.z
+
+Output from archive #nnn. (Note that the archive numbers are not related
+to the backup or restore number.)
+
=item config.pl
Optional configuration settings specific to this host. Settings in this
=item nFiles
-Number of files backed up (as reported by smbclient or tar).
+Number of files backed up (as reported by smbclient, tar or rsync).
=item size
-Total file size backed up (as reported by smbclient or tar).
+Total file size backed up (as reported by smbclient, tar or rsync).
=item nFilesExist
=item xferErrs
-Number of errors or warnings from smbclient (zero for tar).
+Number of errors or warnings from smbclient, tar or rsync.
=item xferBadFile
-Number of errors from smbclient that were bad file errors (zero for tar).
+Number of errors from smbclient that were bad file errors (zero otherwise).
=item xferBadShare
-Number of errors from smbclient that were bad share errors (zero for tar).
+Number of errors from smbclient that were bad share errors (zero otherwise).
=item tarErrs
true for backups in v1.4.0 and above. False for all backups prior
to v1.4.0.
+=item xferMethod
+
+Set to the value of $Conf{XferMethod} when this dump was done.
+
+=item level
+
+The level of this dump. A full dump is level 0. Currently incrementals
+are 1. But when multi-level incrementals are supported this will reflect
+each dump's incremental level.
+
=back
=item restores
=item xferErrs
-Number of errors from smbclient or tar during restore.
+Number of errors from smbclient, tar or rsync during restore.
+
+=back
+
+=item archives
+
+A tab-delimited ascii table listing information about each requested
+archive, one per row. The columns are:
+
+=over 4
+
+=item num
+
+Archive number (matches the suffix of the ArchiveInfo.nnn and
+ArchiveLOG.nnn.z file), unrelated to the backup or restore number.
+
+=item startTime
+
+Start time of the restore in unix seconds.
+
+=item endTime
+
+End time of the restore in unix seconds.
+
+=item result
+
+Result (ok or failed).
+
+=item errorMsg
+
+Error message if archive failed.
=back
BackupPC_zcat can be found in __INSTALLDIR__/bin. For each
file name argument it inflates the file and writes it to stdout.
+=head2 Rsync checksum caching
+
+An incremental backup with rsync compares attributes on the client
+with the last full backup. Any files with identical attributes
+are skipped. A full backup with rsync sets the --ignore-times
+option, which causes every file to be examined independent of
+attributes.
+
+Each file is examined by generating block checksums (default 2K
+blocks) on the receiving side (that's the BackupPC side), sending
+those checksums to the client, where the remote rsync matches those
+checksums with the corresponding file. The matching blocks and new
+data is sent back, allowing the client file to be reassembled.
+A checksum for the entire file is sent to as an extra check the
+the reconstructed file is correct.
+
+This results in significant disk IO and computation for BackupPC:
+every file in a full backup, or any file with non-matching attributes
+in an incremental backup, needs to be uncompressed, block checksums
+computed and sent. Then the receiving side reassembles the file and
+has to verify the whole-file checksum. Even if the file is identical,
+prior to 2.1.0, BackupPC had to read and uncompress the file twice,
+once to compute the block checksums and later to verify the whole-file
+checksum.
+
+Starting in 2.1.0, BackupPC supports optional checksum caching,
+which means the block and file checksums only need to be computed
+once for each file. This results in a significant performance
+improvement. This only works for compressed pool files.
+It is enabled by adding
+
+ '--checksum-seed=32761',
+
+to $Conf{RsyncArgs} and $Conf{RsyncRestoreArgs}.
+
+Rsync versions prior to and including rsync-2.6.2 need a small patch to
+add support for the --checksum-seed option. This patch is available in
+the cygwin-rsyncd package at L<http://backuppc.sourceforge.net>.
+This patch is already included in rsync CVS, so it will be standard
+in future versions of rsync.
+
+When this option is present, BackupPC will add block and file checksums
+to the compressed pool file the next time a pool file is used and it
+doesn't already have cached checksums. The first time a new file is
+written to the pool, the checksums are not appended. The next time
+checksums are needed for a file, they are computed and added. So the
+full performance benefit of checksum caching won't be noticed until the
+third time a pool file is used (eg: the third full backup).
+
+With checksum caching enabled, there is a risk that should a file's contents
+in the pool be corrupted due to a disk problem, but the cached checksums
+are still correct, the corruption will not be detected by a full backup,
+since the file contents are no longer read and compared. To reduce the
+chance that this remains undetected, BackupPC can recheck cached checksums
+for a fraction of the files. This fraction is set with the
+$Conf{RsyncCsumCacheVerifyProb} setting. The default value of 0.01 means
+that 1% of the time a file's checksums are read, the checksums are verified.
+This reduces performance slightly, but, over time, ensures that files
+contents are in sync with the cached checksums.
+
+The format of the cached checksum data can be discovered by looking at
+the code. Basically, the first byte of the compressed file is changed
+to denote that checksums are appended. The block and file checksum
+data, plus some other information and magic word, are appended to the
+compressed file. This allows the cache update to be done in-place.
+
=head2 File name mangling
Backup file names are stored in "mangled" form. Each node of
space if all the files in a directory have the same attributes across
multiple backups, which is common.
-=head2 Limitations
-
-BackupPC isn't perfect (but it is getting better). Here are some
-limitations of BackupPC:
-
-=over 4
-
-=item Non-unix file attributes not backed up
-
-smbclient doesn't extract the WinXX ACLs, so file attributes other than
-the equivalent (as provided by smbclient) unix attributes are not
-backed up.
+=head2 Optimizations
-=item Locked files are not backed up
+BackupPC doesn't care about the access time of files in the pool
+since it saves attribute meta-data separate from the files. Since
+BackupPC mostly does reads from disk, maintaining the access time of
+files generates a lot of unnecessary disk writes. So, provided
+BackupPC has a dedicated data disk, you should consider mounting
+BackupPC's data directory with the noatime attribute (see mount(1)).
-Under WinXX a locked file cannot be read by smbclient. Such files will
-not be backed up. This includes the WinXX system registry files.
-
-This is especially troublesome for Outlook, which stores all its data
-in a single large file and keeps it locked whenever it is running.
-Since many users keep Outlook running all the time their machine
-is up their Outlook file will not be backed up. Sadly, this file
-is the most important file to backup. How do commercial backup
-systems solve this problem?
-
-Similarly, all of the data for WinXX services like SQL databases,
-Exchange etc won't be backed up.
-
-So far, the best that BackupPC can do is send warning emails to
-the user saying that their outlook files haven't been backed up in
-X days. (X is configurable.) The message invites the user to
-exit Outlook and gives a URL to manually start a backup.
-
-I suspect there is a way of mirroring the outlook.pst file so
-that at least the mirror copy can be backed up. Or perhaps a
-manual copy can be started at login. Does some WinXX expert
-know how to do this?
-
-Comment: two users have noted that there are commercial OFM (open file
-manager) products that are designed to solve this problem, for example
-from St. Bernard or Columbia Data Products. Apparently Veritas and
-Legato bundle this product with their commercial products. See for
-example L<http://www.stbernard.com/products/docs/ofm_whitepaperV8.pdf>.
-If anyone tries these programs with BackupPC please tell us whether or
-not they work.
-
-=item Don't expect to reconstruct a complete WinXX drive
-
-The conclusion from the last few items is that BackupPC is not intended
-to allow a complete WinXX disk to be re-imaged from the backup. Our
-approach to system restore in the event of catastrophic failure is to
-re-image a new disk from a generic master, and then use the BackupPC
-archive to restore user files.
-
-It is likely that linux/unix backups done using tar (rather than
-smb) can be used to reconstruct a complete file system, although
-I haven't tried it.
-
-=item Maximum Backup File Sizes
-
-BackupPC can backup and manage very large file sizes, probably as large
-as 2^51 bytes (when a double-precision number's mantissa can no longer
-represent an integer exactly). In practice, several things outside
-BackupPC limit the maximum individual file size. Any one of the
-following items will limit the maximum individual file size:
-
-=over 4
-
-=item Perl
-
-Perl needs to be compiled with uselargefiles defined. Check your
-installation with:
-
- perl -V | egrep largefiles
-
-Without this, the maximum file size will be 2GB.
-
-=item File system
-
-The BackupPC pool and data directories must be on a file system that
-supports large files.
-
-Without this, the maximum file size will be 2GB.
-
-=item Transport
-
-The transport mechanism also limits the maximum individual file size.
-
-GNU tar maximum file size is limited by the tar header format. The tar
-header uses 11 octal digits to represent the file size, which is 33 bits
-or 8GB. I vaguely recall (but I haven't recently checked) that GNU tar
-uses an extra octal digit (replacing a trailing delimiter) if necessary,
-allowing 64GB files. So tar transport limits the maximum file size to
-8GB or perhaps 64GB. It is possible that files >= 8GB don't work; this
-needs to be looked into.
-
-Smbclient is limited to 4GB file sizes. Moreover, a bug in smbclient
-(mixing signed and unsigned 32 bit values) causes it to incorrectly
-do the tar octal conversion for file sizes from 2GB-4GB. BackupPC_tarExtract
-knows about this bug and can recover the correct file size. So smbclient
-transport works up to 4GB file sizes.
-
-=back
-
-=item Some tape backup systems aren't smart about hard links
-
-If you backup the BackupPC pool to tape you need to make sure that the
-tape backup system is smart about hard links. For example, if you
-simply try to tar the BackupPC pool to tape you will backup a lot more
-data than is necessary.
-
-Using the example at the start of the installation section, 65 hosts are
-backed up with each full backup averaging 3.2GB. Storing one full backup
-and two incremental backups per laptop is around 240GB of raw data. But
-because of the pooling of identical files, only 87GB is used (with
-compression the total is lower). If you run du or tar on the data
-directory, there will appear to be 240GB of data, plus the size of the
-pool (around 87GB), or 327GB total.
-
-If your tape backup system is not smart about hard links an alternative
-is to periodically backup just the last successful backup for each host
-to tape. Another alternative is to do a low-level dump of the pool
-file system (ie: /dev/hda1 or similar) using dump(1).
-
-Supporting more efficient tape backup is an area for further
-development.
-
-=item Incremental backups might included deleted files
-
-To make browsing and restoring backups easier, incremental backups
-are "filled-in" from the last complete backup when the backup is
-browsed or restored.
-
-However, if a file was deleted by a user after the last full backup, that
-file will still appear in the "filled-in" incremental backup. This is not
-really a specific problem with BackupPC, rather it is a general issue
-with the full/incremental backup paradigm. This minor problem could be
-solved by having smbclient list all files when it does the incremental
-backup. Volunteers anyone?
-
-=back
+=head2 Limitations
-Comments or suggestions on these issues are welcome.
+BackupPC isn't perfect (but it is getting better). Please see
+L<http://backuppc.sourceforge.net/faq/limitations.html> for a
+discussion of some of BackupPC's limitations.
=head2 Security issues
-Please read this section and consider each of the issues carefully.
-
-=over 4
-
-=item Smb share password
-
-An important security risk is the manner in which the smb share
-passwords are stored. They are in plain text. As described in
-L<Step 3: Setting up config.pl|step 3: setting up config.pl> there are four
-ways to tell BackupPC the smb share password (manually setting an environment
-variable, setting the environment variable in /etc/init.d/backuppc,
-putting the password in __TOPDIR__/conf/config.pl, or putting the
-password in __TOPDIR__/pc/$host/config.pl). In the latter 3 cases the
-smb share password appears in plain text in a file.
-
-If you use any of the latter three methods please make sure that the file's
-permission is appropriately restricted. If you also use RCS or CVS, double
-check the file permissions of the config.pl,v file.
-
-In future versions there will probably be support for encryption of the
-smb share password, but a private key will still have to be stored in a
-protected place. Comments and suggestions are welcome.
-
-=item BackupPC socket server
-
-In v1.5.0 the primary method for communication between the CGI program
-(BackupPC_Admin) and the server (BackupPC) is via a unix-domain socket.
-Since this socket has restricted permissions, no local user should be
-able to connect to this port. No backup or restore data passes through
-this interface, but an attacker can start or stop backups and get status
-through this port.
-
-If the Apache server and BackupPC_Admin run on a different host to
-BackupPC then a TCP port must be enabled by setting $Conf{ServerPort}.
-Anyone can connect to this port. To avoid possible attacks via the TCP
-socket interface, every client message is protected by an MD5 digest.
-The MD5 digest includes four items:
-
-=over 4
-
-=item *
-
-a seed that is sent to the client when the connection opens
-
-=item *
-
-a sequence number that increments for each message
-
-=item *
-
-a shared secret that is stored in $Conf{ServerMesgSecret}
-
-=item *
-
-the message itself.
-
-=back
-
-The message is sent in plain text preceded by the MD5 digest. A
-snooper can see the plain-text seed sent by BackupPC and plain-text
-message from the client, but cannot construct a valid MD5 digest since
-the secret in $Conf{ServerMesgSecret} is unknown. A replay attack is
-not possible since the seed changes on a per-connection and
-per-message basis.
-
-So if you do enable the TCP port, please set $Conf{ServerMesgSecret}
-to some hard-to-guess string. A denial-of-service attack is possible
-with the TCP port enabled. Someone could simply connect many times
-to this port, until BackupPC had exhausted all its file descriptors,
-and this would cause new backups and the CGI interface to fail. The
-most secure solution is to run BackupPC and Apache on the same machine
-and disable the TCP port.
-
-By the way, if you have upgraded from a version of BackupPC prior to
-v1.5.0 you should set $Conf{ServerPort} to -1 to disable the TCP port.
-
-=item Installation permissions
-
-It is important to check that the BackupPC scripts in __INSTALLDIR__/bin
-and __INSTALLDIR__/lib cannot be edited by normal users. Check the
-directory permissions too.
-
-=item Pool permissions
-
-It is important to check that the data files in __TOPDIR__/pool,
-__TOPDIR__/pc and __TOPDIR__/trash cannot be read by normal users.
-Normal users should not be able to see anything below __TOPDIR__.
-
-=item Host shares
-
-Enabling shares on hosts carries security risks. If you are on a private
-network and you generally trust your users then there should not be a
-problem. But if you have a laptop that is sometimes on public networks
-(eg: broadband or even dialup) you should be concerned. A conservative
-approach is to use firewall software, and only enable the netbios and
-smb ports (137 and 139) on connections from the host running BackupPC.
-
-=item SSH key security
-
-Using ssh for linux/unix clients is quite secure, but the security is
-only as good as the protection of ssh's private keys. If an attacker can
-devise a way to run a shell as the BackupPC user then they will have
-access to BackupPC's private ssh keys. They can then, in turn, ssh to
-any client machine as root (or whichever user you have configured
-BackupPC to use). This represents a serious compromise of your entire
-network. So in vulnerable networks, think carefully about how to protect
-the machine running BackupPC and how to prevent attackers from gaining
-shell access (as the BackupPC user) to the machine.
-
-=item CGI interface
-
-The CGI interface, __CGIDIR__/BackupPC_Admin, needs access to the pool
-files so it is installed setuid to __BACKUPPCUSER__. The permissions of
-this file need to checked carefully. It should be owned by
-__BACKUPPCUSER__ and have user and group (but not other) execute
-permission. To allow apache/httpd to execute it, the group ownership
-should be something that apache/httpd belongs to.
-
-The Apache configuration should be setup for AuthConfig style,
-using a .htaccess file so that the user's name is passed into
-the script as $ENV{REMOTE_USER}.
-
-If normal users could directly run BackupPC_Admin then there is a serious
-security hole: since it is setuid to __BACKUPPCUSER__ any user can
-browse and restore any backups. Be aware that anyone who is allowed to
-edit or create cgi scripts on your server can execute BackupPC_Admin as
-any user! They simply write a cgi script that sets $ENV{REMOTE_USER} and
-then execs BackupPC_Admin. The exec succeeds since httpd runs the first
-script as user httpd/apache, which in turn has group permission to
-execute BackupPC_Admin.
-
-While this setup should be safe, a more conservative approach is to
-run a dedicated Apache as user __BACKUPPCUSER__ on a different port.
-Then BackupPC_Admin no longer needs to be setuid, and the cgi
-directories can be locked down from normal users. Moreover, this
-setup is exactly the one used to support mod_perl, so this provides
-both the highest performance and the lowest security risk.
-
-=back
-
-Comments and suggestions are welcome.
+Please see L<http://backuppc.sourceforge.net/faq/security.html> for a
+discussion of some of various security issues.
=head1 Configuration File
ln -s ../../conf/ConfigWinDesktop.pl config.pl
or, better yet, create a config.pl file in __TOPDIR__/pc/$host
-that contains this line:
+that includes the default config.pl file using perl's "do"
+command:
- do "../../conf/ConfigWinDesktop.pl";
+ do "__TOPDIR__/conf/ConfigWinDesktop.pl";
This alternative allows you to set other configuration options
-specific to each host (perhaps even overriding the settings in
-the included file).
+specific to each host after the "do" command (perhaps even
+overriding the settings in the included file).
Note that you could also include snippets of configuration settings
from the main configuration file. However, be aware that the
All configuration settings in the second through fifth groups can
be overridden by the per-PC config.pl file.
-=head2 General server configuration
-
-=over 4
-
-=item $Conf{ServerHost} = '';
-
-Host name on which the BackupPC server is running.
-
-=item $Conf{ServerPort} = -1;
-
-TCP port number on which the BackupPC server listens for and accepts
-connections. Normally this should be disabled (set to -1). The TCP
-port is only needed if apache runs on a different machine from BackupPC.
-In that case, set this to any spare port number over 1024 (eg: 2359).
-If you enable the TCP port, make sure you set $Conf{ServerMesgSecret}
-too!
-
-=item $Conf{ServerMesgSecret} = '';
-
-Shared secret to make the TCP port secure. Set this to a hard to guess
-string if you enable the TCP port (ie: $Conf{ServerPort} > 0).
-
-To avoid possible attacks via the TCP socket interface, every client
-message is protected by an MD5 digest. The MD5 digest includes four
-items:
- - a seed that is sent to the client when the connection opens
- - a sequence number that increments for each message
- - a shared secret that is stored in $Conf{ServerMesgSecret}
- - the message itself.
-
-The message is sent in plain text preceded by the MD5 digest. A
-snooper can see the plain-text seed sent by BackupPC and plain-text
-message from the client, but cannot construct a valid MD5 digest since
-the secret $Conf{ServerMesgSecret} is unknown. A replay attack is
-not possible since the seed changes on a per-connection and
-per-message basis.
-
-=item $Conf{MyPath} = '/bin';
-
-PATH setting for BackupPC. An explicit value is necessary
-for taint mode. Value shouldn't matter too much since
-all execs use explicit paths. However, taint mode in perl
-will complain if this directory is world writable.
-
-=item $Conf{UmaskMode} = 027;
-
-Permission mask for directories and files created by BackupPC.
-Default value prevents any access from group other, and prevents
-group write.
-
-=item $Conf{WakeupSchedule} = [1..23];
-
-Times at which we wake up, check all the PCs, and schedule necessary
-backups. Times are measured in hours since midnight. Can be
-fractional if necessary (eg: 4.25 means 4:15am).
-
-If the hosts you are backing up are always connected to the network
-you might have only one or two wakeups each night. This will keep
-the backup activity after hours. On the other hand, if you are backing
-up laptops that are only intermittently connected to the network you
-will want to have frequent wakeups (eg: hourly) to maximized the chance
-that each laptop is backed up.
-
-Examples:
-
- $Conf{WakeupSchedule} = [22.5]; # once per day at 10:30 pm.
- $Conf{WakeupSchedule} = [1..23]; # every hour except midnight
- $Conf{WakeupSchedule} = [2,4,6,8,10,12,14,16,18,20,22]; # every 2 hours
-
-The default value is every hour except midnight.
-
-=item $Conf{MaxBackups} = 4;
-
-Maximum number of simultaneous backups to run. If there
-are no user backup requests then this is the maximum number
-of simultaneous backups.
-
-=item $Conf{MaxUserBackups} = 4;
-
-Additional number of simultaneous backups that users can run.
-As many as $Conf{MaxBackups} + $Conf{MaxUserBackups} requests can
-run at the same time.
-
-=item $Conf{MaxPendingCmds} = 10;
-
-Maximum number of pending link commands. New backups will only be
-started if there are no more than $Conf{MaxPendingCmds} plus
-$Conf{MaxBackups} number of pending link commands, plus running jobs.
-This limit is to make sure BackupPC doesn't fall too far behind in
-running BackupPC_link commands.
-
-=item $Conf{MaxOldLogFiles} = 14;
-
-Maximum number of log files we keep around in log directory.
-These files are aged nightly. A setting of 14 means the log
-directory will contain about 2 weeks of old log files, in
-particular at most the files LOG, LOG.0, LOG.1, ... LOG.13
-(except today's LOG, these files will have a .z extension if
-compression is on).
-
-If you decrease this number after BackupPC has been running for a
-while you will have to manually remove the older log files.
-
-=item $Conf{DfPath} = '/bin/df';
-
-Full path to the df command. Security caution: normal users
-should not allowed to write to this file or directory.
-
-=item $Conf{DfMaxUsagePct} = 95;
-
-Maximum threshold for disk utilization on the __TOPDIR__ filesystem.
-If the output from $Conf{DfPath} reports a percentage larger than
-this number then no new regularly scheduled backups will be run.
-However, user requested backups (which are usually incremental and
-tend to be small) are still performed, independent of disk usage.
-Also, currently running backups will not be terminated when the disk
-usage exceeds this number.
-
-=item $Conf{TrashCleanSleepSec} = 300;
-
-How long BackupPC_trashClean sleeps in seconds between each check
-of the trash directory. Once every 5 minutes should be reasonable.
-
-=item $Conf{DHCPAddressRanges} = [];
-
-List of DHCP address ranges we search looking for PCs to backup.
-This is an array of hashes for each class C address range.
-
-Examples:
-
- # to specify 192.10.10.20 to 192.10.10.250 as the DHCP address pool
- $Conf{DHCPAddressRanges} = [
- {
- ipAddrBase => '192.10.10',
- first => 20,
- last => 250,
- },
- ];
- # to specify two pools (192.10.10.20-250 and 192.10.11.10-50)
- $Conf{DHCPAddressRanges} = [
- {
- ipAddrBase => '192.10.10',
- first => 20,
- last => 250,
- },
- {
- ipAddrBase => '192.10.11',
- first => 10,
- last => 50,
- },
- ];
-
-=item $Conf{BackupPCUser} = '';
-
-=item $Conf{CgiDir} = '';
-
-=item $Conf{InstallDir} = '';
-
-These configuration settings aren't used by BackupPC, but simply
-remember a few settings used by configure.pl during installation.
-These are used by configure.pl when upgrading to new versions of
-BackupPC.
-
-=item $Conf{BackupPCUserVerify} = 1;
-
-Whether BackupPC and the CGI script BackupPC_Admin verify that they
-are really running as user $Conf{BackupPCUser}. If this flag is set
-and the effective user id (euid) differs from $Conf{BackupPCUser}
-then both scripts exit with an error. This catches cases where
-BackupPC might be accidently started as root or the wrong user,
-or if the CGI script is not installed correctly.
-
-=back
-
-=head2 What to backup and when to do it
-
-=over 4
-
-=item $Conf{SmbShareName} = 'C$';
-
-Name of the host share that is backed up when using SMB. This can be a
-string or an array of strings if there are multiple shares per host.
-Examples:
-
-
- $Conf{SmbShareName} = 'c'; # backup 'c' share
- $Conf{SmbShareName} = ['c', 'd']; # backup 'c' and 'd' shares
-
-This setting only matters if $Conf{XferMethod} = 'smb'.
-
-=item $Conf{SmbShareUserName} = '';
-
-Smbclient share user name. This is passed to smbclient's -U argument.
-
-This setting only matters if $Conf{XferMethod} = 'smb'.
-
-=item $Conf{SmbSharePasswd} = '';
-
-Smbclient share password. This is passed to smbclient via the PASSWD
-environment variable. There are several ways you can tell BackupPC
-the smb share password. In each case you should be very careful about
-security. If you put the password here, make sure that this file is
-not readable by regular users! See the "Setting up config.pl" section
-in the documentation for more information.
-
-This setting only matters if $Conf{XferMethod} = 'smb'.
-
-=item $Conf{TarShareName} = '/';
-
-Which host directories to backup when using tar transport. This can be a
-string or an array of strings if there are multiple directories to
-backup per host. Examples:
-
-
- $Conf{TarShareName} = '/'; # backup everything
- $Conf{TarShareName} = '/home'; # only backup /home
- $Conf{TarShareName} = ['/home', '/src']; # backup /home and /src
-
-The fact this parameter is called 'TarShareName' is for historical
-consistency with the Smb transport options. You can use any valid
-directory on the client: there is no need for it to correspond to
-any Smb share or device mount point.
-
-Note also that you can also use $Conf{BackupFilesOnly} to specify
-a specific list of directories to backup. It's more efficient to
-use this option instead of $Conf{TarShareName} since a new tar is
-run for each entry in $Conf{TarShareName}.
-
-This setting only matters if $Conf{XferMethod} = 'tar'.
-
-=item $Conf{FullPeriod} = 6.97;
-
-Minimum period in days between full backups. A full dump will only be
-done if at least this much time has elapsed since the last full dump,
-and at least $Conf{IncrPeriod} days has elapsed since the last
-successful dump.
-
-Typically this is set slightly less than an integer number of days. The
-time taken for the backup, plus the granularity of $Conf{WakeupSchedule}
-will make the actual backup interval a bit longer.
-
-=item $Conf{IncrPeriod} = 0.97;
-
-Minimum period in days between incremental backups (a user requested
-incremental backup will be done anytime on demand).
-
-Typically this is set slightly less than an integer number of days. The
-time taken for the backup, plus the granularity of $Conf{WakeupSchedule}
-will make the actual backup interval a bit longer.
-
-=item $Conf{FullKeepCnt} = 1;
-
-Number of full backups to keep. Must be >= 1.
-
-In the steady state, each time a full backup completes successfully
-the oldest one is removed. If this number is decreased, the
-extra old backups will be removed.
-
-If filling of incremental dumps is off the oldest backup always
-has to be a full (ie: filled) dump. This might mean an extra full
-dump is kept until the second oldest (incremental) dump expires.
-
-=item $Conf{FullKeepCntMin} = 1;
-
-=item $Conf{FullAgeMax} = 60;
-
-Very old full backups are removed after $Conf{FullAgeMax} days. However,
-we keep at least $Conf{FullKeepCntMin} full backups no matter how old
-they are.
-
-=item $Conf{IncrKeepCnt} = 6;
-
-Number of incremental backups to keep. Must be >= 1.
-
-In the steady state, each time an incr backup completes successfully
-the oldest one is removed. If this number is decreased, the
-extra old backups will be removed.
-
-=item $Conf{IncrKeepCntMin} = 1;
-
-=item $Conf{IncrAgeMax} = 30;
-
-Very old incremental backups are removed after $Conf{IncrAgeMax} days.
-However, we keep at least $Conf{IncrKeepCntMin} incremental backups no
-matter how old they are.
-
-=item $Conf{IncrFill} = 0;
-
-Whether incremental backups are filled. "Filling" means that the
-most recent full (or filled) dump is merged into the new incremental
-dump using hardlinks. This makes an incremental dump look like a
-full dump. Prior to v1.03 all incremental backups were filled.
-In v1.4.0 and later the default is off.
-
-BackupPC, and the cgi interface in particular, do the right thing on
-un-filled incremental backups. It will correctly display the merged
-incremental backup with the most recent filled backup, giving the
-un-filled incremental backups a filled appearance. That means it
-invisible to the user whether incremental dumps are filled or not.
-
-Filling backups takes a little extra disk space, and it does cost
-some extra disk activity for filling, and later removal. Filling
-is no longer useful, since file mangling and compression doesn't
-make a filled backup very useful. It's likely the filling option
-will be removed from future versions: filling will be delegated to
-the display and extraction of backup data.
-
-If filling is off, BackupPC makes sure that the oldest backup is
-a full, otherwise the following incremental backups will be
-incomplete. This might mean an extra full backup has to be
-kept until the following incremental backups expire.
-
-The default is off. You can turn this on or off at any
-time without affecting existing backups.
-
-=item $Conf{RestoreInfoKeepCnt} = 10;
-
-Number of restore logs to keep. BackupPC remembers information about
-each restore request. This number per client will be kept around before
-the oldest ones are pruned.
-
-Note: files/dirs delivered via Zip or Tar downloads don't count as
-restores. Only the first restore option (where the files and dirs
-are written to the host) count as restores that are logged.
-
-=item $Conf{BackupFilesOnly} = undef;
-
-List of directories or files to backup. If this is defined, only these
-directories or files will be backed up.
-
-For Smb, only one of $Conf{BackupFilesExclude} and $Conf{BackupFilesOnly}
-can be specified per share. If both are set for a particular share, then
-$Conf{BackupFilesOnly} takes precedence and $Conf{BackupFilesExclude}
-is ignored.
-
-This can be set to a string, an array of strings, or, in the case
-of multiple shares, a hash of strings or arrays. A hash is used
-to give a list of directories or files to backup for each share
-(the share name is the key). If this is set to just a string or
-array, and $Conf{SmbShareName} contains multiple share names, then
-the setting is assumed to apply to only the first share name.
-
-Examples:
-
- $Conf{BackupFilesOnly} = '/myFiles';
- $Conf{BackupFilesOnly} = ['/myFiles']; # same as first example
- $Conf{BackupFilesOnly} = ['/myFiles', '/important'];
- $Conf{BackupFilesOnly} = {
- 'c' => ['/myFiles', '/important'], # these are for 'c' share
- 'd' => ['/moreFiles', '/archive'], # these are for 'd' share
- }
-
-=item $Conf{BackupFilesExclude} = undef;
-
-List of directories or files to exclude from the backup. For Smb,
-only one of $Conf{BackupFilesExclude} and $Conf{BackupFilesOnly}
-can be specified per share. If both are set for a particular share,
-then $Conf{BackupFilesOnly} takes precedence and
-$Conf{BackupFilesExclude} is ignored.
-
-This can be set to a string, an array of strings, or, in the case
-of multiple shares, a hash of strings or arrays. A hash is used
-to give a list of directories or files to exclude for each share
-(the share name is the key). If this is set to just a string or
-array, and $Conf{SmbShareName} contains multiple share names, then
-the setting is assumed to apply to only the first share name.
-
-The exact behavior is determined by the underlying transport program,
-smbclient or tar. For smbclient the exlclude file list is passed into
-the X option. Simple shell wild-cards using "*" or "?" are allowed.
-
-For tar, if the exclude file contains a "/" it is assumed to be anchored
-at the start of the string. Since all the tar paths start with "./",
-BackupPC prepends a "." if the exclude file starts with a "/". Note
-that GNU tar version >= 1.3.7 is required for the exclude option to
-work correctly. For linux or unix machines it is recommended to add
-"/proc" to $Conf{BackupFilesExclude}.
-
-Examples:
-
- $Conf{BackupFilesExclude} = '/temp';
- $Conf{BackupFilesExclude} = ['/temp']; # same as first example
- $Conf{BackupFilesExclude} = ['/temp', '/winnt/tmp'];
- $Conf{BackupFilesExclude} = {
- 'c' => ['/temp', '/winnt/tmp'], # these are for 'c' share
- 'd' => ['/junk', '/dont_back_this_up'], # these are for 'd' share
- }
-
-=item $Conf{BlackoutBadPingLimit} = 3;
-
-=item $Conf{BlackoutGoodCnt} = 7;
-
-PCs that are always or often on the network can be backed up after
-hours, to reduce PC, network and server load during working hours. For
-each PC a count of consecutive good pings is maintained. Once a PC has
-at least $Conf{BlackoutGoodCnt} consecutive good pings it is subject
-to "blackout" and not backed up during hours and days specified by
-$Conf{BlackoutWeekDays}, $Conf{BlackoutHourBegin} and
-$Conf{BlackoutHourEnd}.
-
-To allow for periodic rebooting of a PC or other brief periods when a
-PC is not on the network, a number of consecutive bad pings is allowed
-before the good ping count is reset. This parameter is
-$Conf{BlackoutBadPingLimit}.
-
-Note that bad and good pings don't occur with the same interval. If a
-machine is always on the network, it will only be pinged roughly once
-every $Conf{IncrPeriod} (eg: once per day). So a setting for
-$Conf{BlackoutGoodCnt} of 7 means it will take around 7 days for a
-machine to be subject to blackout. On the other hand, if a ping is
-failed, it will be retried roughly every time BackupPC wakes up, eg,
-every one or two hours. So a setting for $Conf{BlackoutBadPingLimit} of
-3 means that the PC will lose its blackout status after 3-6 hours of
-unavailability.
-
-To disable the blackout feature set $Conf{BlackoutGoodCnt} to a negative
-value. A value of 0 will make all machines subject to blackout. But
-if you don't want to do any backups during the day it would be easier
-to just set $Conf{WakeupSchedule} to a restricted schedule.
-
-=item $Conf{BlackoutHourBegin} = 7.0;
-
-=item $Conf{BlackoutHourEnd} = 19.5;
-
-=item $Conf{BlackoutWeekDays} = [1, 2, 3, 4, 5];
-
-The default settings specify the blackout period from 7:00am to
-7:30pm local time on Mon-Fri. For $Conf{BlackoutWeekDays},
-0 is Sunday, 1 is Monday etc.
-
-=back
-
-=head2 General per-PC configuration settings
-
-=over 4
-
-=item $Conf{XferMethod} = 'smb';
-
-What transport method to use to backup each host. If you have
-a mixed set of WinXX and linux/unix hosts you will need to override
-this in the per-PC config.pl.
-
-The valid values are:
-
- - 'smb': use smbclient and the SMB protocol. Only choice for WinXX.
-
- - 'tar': use tar, tar over ssh, rsh or nfs. Best choice for
- linux/unix.
-
-A future version should support 'rsync' as a transport method for
-more efficient backup of linux/unix machines (and perhaps WinXX??).
-
-=item $Conf{SmbClientPath} = '/usr/bin/smbclient';
-
-Full path for smbclient. Security caution: normal users should not
-allowed to write to this file or directory.
-
-smbclient is from the Samba distribution. smbclient is used to
-actually extract the incremental or full dump of the share filesystem
-from the PC.
-
-This setting only matters if $Conf{XferMethod} = 'smb'.
-
-=item $Conf{SmbClientArgs} = '';
-
-Additional optional arguments to smbclient.
-
-Some users have reported that the -b option can be used to improve
-performance of smbclient. The default value is 4096, and if you
-find smbclient has low throughput you might try a value of 2048, eg:
-
- $Conf{SmbClientArgs} = '-b 2048';
-
-This setting only matters if $Conf{XferMethod} = 'smb'.
-
-=item $Conf{TarClientCmd} = '$sshPath -q -n -l root $host' ...
-
-Full command to run tar on the client. GNU tar is required. You will
-need to fill in the correct paths for ssh2 on the local host (server)
-and GNU tar on the client. Security caution: normal users should not
-allowed to write to these executable files or directories.
-
-See the documentation for more information about setting up ssh2 keys.
-
-If you plan to use NFS then tar just runs locally and ssh2 is not needed.
-For example, assuming the client filesystem is mounted below /mnt/hostName,
-you could use something like:
-
- $Conf{TarClientCmd} = '$tarPath -c -v -f - -C /mnt/$host/$shareName'
- . ' --totals';
-
-In the case of NFS or rsh you need to make sure BackupPC's privileges
-are sufficient to read all the files you want to backup. Also, you
-will probably want to add "/proc" to $Conf{BackupFilesExclude}.
-
-Several variables are substituted at run-time. The following variables
-are substituted at run-time:
-
- $host host name
- $hostIP host's IP address
- $incrDate newer-than date for incremental backups
- $shareName share name to backup (ie: top-level directory path)
- $fileList specific files to backup or exclude
- $tarPath same as $Conf{TarClientPath}
- $sshPath same as $Conf{SshPath}
-
-If a variable is followed by a "+" it is shell escaped. This is
-necessary for the command part of ssh or rsh, since it ends up
-getting passed through the shell.
-
-This setting only matters if $Conf{XferMethod} = 'tar'.
-
-=item $Conf{TarFullArgs} = '$fileList+';
-
-Extra tar arguments for full backups. Several variables are substituted at
-run-time. See $Conf{TarClientCmd} for the list of variable substitutions.
-
-This setting only matters if $Conf{XferMethod} = 'tar'.
-
-=item $Conf{TarIncrArgs} = '--newer=$incrDate+ $fileList+';
-
-Extra tar arguments for incr backups. Several variables are substituted at
-run-time. See $Conf{TarClientCmd} for the list of variable substitutions.
-
-Note that GNU tar has several methods for specifying incremental backups,
-including:
-
- --newer-mtime $incrDate+
- This causes a file to be included if the modification time is
- later than $incrDate (meaning its contents might have changed).
- But changes in the ownership or modes will not qualify the
- file to be included in an incremental.
-
- --newer=$incrDate+
- This causes the file to be included if any attribute of the
- file is later than $incrDate, meaning either attributes or
- the modification time. This is the default method. Do
- not use --atime-preserve in $Conf{TarClientCmd} above,
- otherwise resetting the atime (access time) counts as an
- attribute change, meaning the file will always be included
- in each new incremental dump.
-
-This setting only matters if $Conf{XferMethod} = 'tar'.
-
-=item $Conf{TarClientRestoreCmd} = '$sshPath -q -l root $host' ...
-
-Full command to run tar for restore on the client. GNU tar is required.
-This can be the same as $Conf{TarClientCmd}, with tar's -c replaced by -x
-and ssh's -n removed.
-
-See $Conf{TarClientCmd} for full details.
-
-This setting only matters if $Conf{XferMethod} = "tar".
-
-=item $Conf{TarClientPath} = '/bin/tar';
-
-Full path for tar on the client. Security caution: normal users should not
-allowed to write to this file or directory.
-
-This setting only matters if $Conf{XferMethod} = 'tar'.
-
-=item $Conf{SshPath} = '/usr/bin/ssh';
-
-Full path for ssh. Security caution: normal users should not
-allowed to write to this file or directory.
-
-=item $Conf{NmbLookupPath} = '/usr/bin/nmblookup';
-
-Full path for nmblookup. Security caution: normal users should not
-allowed to write to this file or directory.
-
-nmblookup is from the Samba distribution. nmblookup is used to get the
-netbios name, necessary for DHCP hosts.
-
-=item $Conf{FixedIPNetBiosNameCheck} = 0;
-
-For fixed IP address hosts, BackupPC_dump can also verify the netbios
-name to ensure it matches the host name. An error is generated if
-they do not match. Typically this flag is off. But if you are going
-to transition a bunch of machines from fixed host addresses to DHCP,
-setting this flag is a great way to verify that the machines have
-their netbios name set correctly before turning on DCHP.
-
-=item $Conf{PingPath} = '/bin/ping';
-
-Full path to the ping command. Security caution: normal users
-should not be allowed to write to this file or directory.
-
-If you want to disable ping checking, set this to some program
-that exits with 0 status, eg:
-
- $Conf{PingPath} = '/bin/echo';
-
-=item $Conf{PingArgs} = '-c 1 $host';
-
-Options for the ping command.
-
-=item $Conf{CompressLevel} = 0;
-
-Compression level to use on files. 0 means no compression. Compression
-levels can be from 1 (least cpu time, slightly worse compression) to
-9 (most cpu time, slightly better compression). The recommended value
-is 3. Changing to 5, for example, will take maybe 20% more cpu time
-and will get another 2-3% additional compression. See the zlib
-documentation for more information about compression levels.
-
-Changing compression on or off after backups have already been done
-will require both compressed and uncompressed pool files to be stored.
-This will increase the pool storage requirements, at least until all
-the old backups expire and are deleted.
-
-It is ok to change the compression value (from one non-zero value to
-another non-zero value) after dumps are already done. Since BackupPC
-matches pool files by comparing the uncompressed versions, it will still
-correctly match new incoming files against existing pool files. The
-new compression level will take effect only for new files that are
-newly compressed and added to the pool.
-
-If compression was off and you are enabling compression for the first
-time you can use the BackupPC_compressPool utility to compress the
-pool. This avoids having the pool grow to accommodate both compressed
-and uncompressed backups. See the documentation for more information.
-
-Note: compression needs the Compress::Zlib perl library. If the
-Compress::Zlib library can't be found then $Conf{CompressLevel} is
-forced to 0 (compression off).
-
-=item $Conf{PingMaxMsec} = 20;
-
-Maximum round-trip ping time in milliseconds. This threshold is set
-to avoid backing up PCs that are remotely connected through WAN or
-dialup connections. The output from ping -s (assuming it is supported
-on your system) is used to check the round-trip packet time. On your
-local LAN round-trip times should be much less than 20msec. On most
-WAN or dialup connections the round-trip time will be typically more
-than 20msec. Tune if necessary.
-
-=item $Conf{SmbClientTimeout} = 7200;
-
-Timeout in seconds when listening for the transport program's
-(smbclient, tar etc) stdout. If no output is received during this
-time, then it is assumed that something has wedged during a backup,
-and the backup is terminated.
-
-Note that stdout buffering combined with huge files being backed up
-could cause longish delays in the output from smbclient that
-BackupPC_dump sees, so in rare cases you might want to increase
-this value.
-
-Despite the name, this parameter sets the timeout for all transport
-methods (tar, smb etc).
-
-=item $Conf{MaxOldPerPCLogFiles} = 12;
-
-Maximum number of log files we keep around in each PC's directory
-(ie: pc/$host). These files are aged monthly. A setting of 12
-means there will be at most the files LOG, LOG.0, LOG.1, ... LOG.11
-in the pc/$host directory (ie: about a years worth). (Except this
-month's LOG, these files will have a .z extension if compression
-is on).
-
-If you decrease this number after BackupPC has been running for a
-while you will have to manually remove the older log files.
-
-=back
-
-=head2 Email reminders, status and messages
-
-=over 4
-
-=item $Conf{SendmailPath} = '/usr/sbin/sendmail';
-
-Full path to the sendmail command. Security caution: normal users
-should not allowed to write to this file or directory.
-
-=item $Conf{EMailNotifyMinDays} = 2.5;
-
-Minimum period between consecutive emails to a single user.
-This tries to keep annoying email to users to a reasonable
-level. Email checks are done nightly, so this number is effectively
-rounded up (ie: 2.5 means a user will never receive email more
-than once every 3 days).
-
-=item $Conf{EMailFromUserName} = '';
-
-Name to use as the "from" name for email. Depending upon your mail
-handler this is either a plain name (eg: "admin") or a fully-qualified
-name (eg: "admin@mydomain.com").
-
-=item $Conf{EMailAdminUserName} = '';
-
-Destination address to an administrative user who will receive a
-nightly email with warnings and errors. If there are no warnings
-or errors then no email will be sent. Depending upon your mail
-handler this is either a plain name (eg: "admin") or a fully-qualified
-name (eg: "admin@mydomain.com").
-
-=item $Conf{EMailNoBackupEverMesg} = ...;
-
-This message is sent to a user if their PC has never been backed up.
-If your mailer needs a fully-qualified To name, then change "$user"
-to "$user@mydomain.com" in the template, eg:
-
- To: $user@mydomain.com
-
-=item $Conf{EMailNotifyOldBackupDays} = 7.0;
-
-How old the most recent backup has to be before notifying user.
-When there have been no backups in this number of days the user
-is sent an email.
-
-=item $Conf{EMailNoBackupRecentMesg} = ...;
-
-This message is sent to a user if their PC has not recently been
-backed up (ie: more than $Conf{EMailNotifyOldBackupDays} days ago).
-
-If your mailer needs a fully-qualified To name, then change "$user"
-to "$user@mydomain.com" in the template, eg:
-
- To: $user@mydomain.com
-
-=item $Conf{EMailNotifyOldOutlookDays} = 5.0;
-
-How old the most recent backup of Outlook files has to be before
-notifying user.
-
-=item $Conf{EMailOutlookBackupMesg} = ...;
-
-This message is sent to a user if their Outlook files have not
-recently been backed up (ie: more than $Conf{EMailNotifyOldOutlookDays}
-days ago).
-
-If your mailer needs a fully-qualified To name, then change "$user"
-to "$user@mydomain.com" in the template, eg:
-
- To: $user@mydomain.com
-
-=back
-
-=head2 CGI user interface configuration settings
-
-=over 4
-
-=item $Conf{CgiAdminUserGroup} = '';
-
-=item $Conf{CgiAdminUsers} = '';
-
-Normal users can only access information specific to their host.
-They can start/stop/browse/restore backups.
-
-Administrative users have full access to all hosts, plus overall
-status and log information.
-
-The administrative users are the union of the unix/linux group
-$Conf{CgiAdminUserGroup} and the manual list of users, separated
-by spaces, in $Conf{CgiAdminUsers}. If you don't want a group or
-manual list of users set the corresponding configuration setting
-to undef or an empty string.
-
-If you want every user to have admin privileges (careful!), set
-$Conf{CgiAdminUsers} = '*'.
-
-Examples:
-
- $Conf{CgiAdminUserGroup} = 'admin';
- $Conf{CgiAdminUsers} = 'craig celia';
- --> administrative users are the union of group admin, plus
- craig and celia.
-
- $Conf{CgiAdminUserGroup} = '';
- $Conf{CgiAdminUsers} = 'craig celia';
- --> administrative users are only craig and celia'.
-
-=item $Conf{CgiUserHomePageCheck} = '';
-
-=item $Conf{CgiUserUrlCreate} = 'mailto:%s';
-
-User names that are rendered by the CGI interface can be turned
-into links into their home page or other information about the
-user. To set this up you need to create two sprintf() strings,
-that each contain a single '%s' that will be replaced by the user
-name. The default is a mailto: link.
-
-$Conf{CgiUserHomePageCheck} should be an absolute file path that
-is used to check (via "-f") that the user has a valid home page.
-Set this to undef or an empty string to turn off this check.
-
-$Conf{CgiUserUrlCreate} should be a full URL that points to the
-user's home page. Set this to undef or an empty string to turn
-off generation of URLs for user names.
-
-Example:
-
- $Conf{CgiUserHomePageCheck} = '/var/www/html/users/%s.html';
- $Conf{CgiUserUrlCreate} = 'http://myhost/users/%s.html';
- --> if /var/www/html/users/craig.html exists, then 'craig' will
- be rendered as a link to http://myhost/users/craig.html.
-
-=item $Conf{CgiDateFormatMMDD} = 1;
-
-Date display format for CGI interface. True for US-style dates (MM/DD)
-and zero for international dates (DD/MM).
-
-=item $Conf{CgiHeaderFontType} = 'arial';
-
-=item $Conf{CgiHeaderFontSize} = '3';
-
-Header font and size for CGI interface
-
-=item $Conf{CgiNavBarBgColor} = '#ddeeee';
-
-=item $Conf{CgiHeaderBgColor} = '#99cc33';
-
-Color scheme for CGI interface. Default values give a very light blue
-for the background navigation color and green for the header background.
-(You call tell I'm a better programmer than graphical designer.)
-
-=item $Conf{CgiHeaders} = '<meta http-equiv="pragma" content="no-cache">';
-
-Additional CGI header text. For example, if you wanted each CGI page
-to auto refresh every 900 seconds, you could add this text:
-
- <meta http-equiv="refresh" content="900">
-
-=item $Conf{CgiImageDir} = '';
-
-Directory where images are stored. This directory should be below
-Apache's DocumentRoot. This value isn't used by BackupPC but is
-used by configure.pl when you upgrade BackupPC.
-
-Example:
-
- $Conf{CgiImageDir} = '/usr/local/apache/htdocs/BackupPC';
-
-=item $Conf{CgiImageDirURL} = '';
-
-URL (without the leading http://host) for BackupPC's image directory.
-The CGI script uses this value to serve up image files.
-
-Example:
-
- $Conf{CgiImageDirURL} = '/BackupPC';
-
-=back
-
+__CONFIGPOD__
=head1 Version Numbers
-Starting with v1.4.0 BackupPC switched to a X.Y.Z version numbering
-system, instead of X.0Y. The first digit is for major new releases, the
-middle digit is for significant feature releases and improvements (most
-of the releases have been in this category), and the last digit is for
+Starting with v1.4.0 BackupPC uses a X.Y.Z version numbering system,
+instead of X.0Y. The first digit is for major new releases, the middle
+digit is for significant feature releases and improvements (most of
+the releases have been in this category), and the last digit is for
bug fixes. You should think of the old 1.00, 1.01, 1.02 and 1.03 as
-1.0.0, 1.1.0, 1.2.0 and 1.3.0.
+1..0, 1.1.0, 1.2.0 and 1.3.0.
+
+Additionally, patches might be made available. A patched version
+number is of the form X.Y.ZplN (eg: 2.1.0pl2), where N is the
+patch level.
=head1 Author
=head1 Copyright
-Copyright (C) 2001-2002 Craig Barratt
+Copyright (C) 2001-2004 Craig Barratt
=head1 Credits
Ryan Kucera contributed the directory navigation code and images
-for v1.5.0. He also contributed the first skeleton of BackupPC_restore.
+for v1.5.0. He contributed the first skeleton of BackupPC_restore.
+He also added a significant revision to the CGI interface, including
+CSS tags, in v2.1.0, and designed the BackupPC logo.
+
+Xavier Nicollet, with additions from Guillaume Filion, added the
+internationalization (i18n) support to the CGI interface for v2.0.0.
+Xavier provided the French translation fr.pm, with additions from
+Guillaume.
Guillaume Filion wrote BackupPC_zipCreate and added the CGI support
for zip download, in addition to some CGI cleanup, for v1.5.0.
+Guillaume continues to support fr.pm updates for each new version.
+
+Josh Marshall implemented the Archive feature in v2.1.0.
+
+Ludovic Drolez supports the BackupPC Debian package.
+
+Javier Gonzalez provided the Spanish translation, es.pm for v2.0.0.
+
+Manfred Herrmann provided the German translation, de.pm for v2.0.0.
+Manfred continues to support de.pm updates for each new version,
+together with some help frmo Ralph Paßgang.
+
+Lorenzo Cappelletti provided the Italian translation, it.pm for v2.1.0.
+
+Lieven Bridts provided the Dutch translation, nl.pm, for v2.1.0,
+with some tweaks from Guus Houtzager.
-Several people have reported bugs or made useful suggestions; see the
-ChangeLog.
+Many people have reported bugs, made useful suggestions and helped
+with testing; see the ChangeLog and the mail lists.
Your name could appear here in the next version!
projects / BackupPC.git / blobdiff