* A failed full dump is now saved as a partial (incomplete) dump,

[BackupPC.git] / doc-src / BackupPC.pod

diff --git a/doc-src/BackupPC.pod b/doc-src/BackupPC.pod
index ea46308..e8e8c0a 100644 (file)
--- a/doc-src/BackupPC.pod
+++ b/doc-src/BackupPC.pod
@@ -41,7 +41,7 @@ cancel backups and browse and restore files from backups.
 =item *
 
 The http/cgi user interface has internationalization (i18n) support,
 =item *
 
 The http/cgi user interface has internationalization (i18n) support,

-currently prodiving English, French and Spanish.
+currently providing English, French, German and Spanish.

 
 =item *
 
 
 =item *
 


@@ -346,7 +346,7 @@ 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.  Rather than using an external
 program, File::RsyncP will eventually get the necessary delta
 L<http://sourceforge.net/projects/xdelta>) uses an rsync algorithm for
 doing efficient binary file deltas.  Rather than using an external
 program, File::RsyncP will eventually get the necessary delta

-generataion code from rsync.
+generation code from rsync.

 
 =back
 
 
 =back
 


@@ -407,8 +407,8 @@ compression is on.
 =item *
 
 Perl version 5.6.0 or later. BackupPC has been tested with
 =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.0, 5.6.1 and 5.8.0. If you don't have perl, please
+see L<http://www.cpan.org>.

 
 =item *
 
 
 =item *
 


@@ -441,17 +441,18 @@ If you are using tar to backup linux/unix machines you should have version
 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>.
 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 February 2003 the latest version 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
 
 =item *
 
 If you are using rsync to backup linux/unix machines you should have

-version 2.5.5 on each client machine.  See L<http://rsync.samba.org>.
-Use "rsync --version" to check your version.
+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
 
 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.31 or later is required.
+L<http://perlrsync.sourceforge.net>.  Version 0.44 or later is required.

 
 =item *
 
 
 =item *
 


@@ -531,7 +532,7 @@ You can run "perldoc Archive::Zip" to see if this module is installed.
 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>.
 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.31 or later is required.
+Version 0.44 or later is required.

 
 =back
 
 
 =back
 


@@ -754,9 +755,9 @@ Here's a simple example of a hosts file:
 
 =head2 Step 5: Client Setup
 
 
 =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 is the preferred method for WinXX clients and tar is preferred
+method 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
 
 The transfer method is set using the $Conf{XferMethod} configuration
 setting. If you have a mixed environment (ie: you will use smb for some


@@ -779,11 +780,19 @@ The preferred setup for WinXX clients is to set $Conf{XferMethod} to "smb".
 prepared to run rsync/cygwin on your WinXX client.  More information
 about this will be provided via the FAQ.)
 
 prepared to run rsync/cygwin on your WinXX client.  More information
 about this will be provided via the FAQ.)
 

-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.
+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.
+
+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
 
 If this machine uses DHCP you will also need to make sure the
 NetBios name is set.  Go to Control Panel|System|Network Identification


@@ -1261,8 +1270,6 @@ to Apache's 1.x httpd.conf file:
        </Location>
     </IfModule>
 
        </Location>
     </IfModule>
 

-For Apache 2.x and perl 5.8.x
-

 Apache 2.0.44 with Perl 5.8.0 on RedHat 7.1, Don Silvia reports that
 this works:
 
 Apache 2.0.44 with Perl 5.8.0 on RedHat 7.1, Don Silvia reports that
 this works:
 


@@ -1323,9 +1330,14 @@ One alternative is to use LDAP.  In Apache's http.conf add these lines:
       require valid-user
     </Location>
 
       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
 
     <Location /cgi-bin/BackupPC/BackupPC_Admin>   # <--- change path as needed
         Setenv REMOTE_USER www


@@ -1340,6 +1352,8 @@ 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.
 
 up.  You should make sure that $Conf{CgiImageDirURL} is the correct
 URL for the image directory.
 

+See the section L<Debugging installation problems|debugging 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
 =head2 How BackupPC Finds Hosts
 
 Starting with v2.0.0 the way hosts are discovered has changed.  In most


@@ -1425,6 +1439,46 @@ but does respond to a request directed to its IP address:
 
 =over 4
 
 
 =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
 =item Copying the pool
 
 If the pool disk requirements grow you might need to copy the entire


@@ -1630,11 +1684,69 @@ earlier section) so that user authentication works.  Make sure
 the config settings $Conf{CgiAdminUserGroup} and $Conf{CgiAdminUsers}
 correctly specify the privileged administrator users.
 
 the config settings $Conf{CgiAdminUserGroup} and $Conf{CgiAdminUsers}
 correctly specify the privileged administrator users.
 

+=item You cannot access per-host information in the CGI interface
+
+If you get the error
+
+    Only privileged users can view information about host xyz
+
+it means that BackupPC_Admin is unable to match the user's login
+name (supplied by Apache via the REMOTE_USER environment variable)
+with either that host's user name (in the conf/hosts file) or
+with the administrators specified in the $Conf{CgiAdminUsers}
+or $Conf{CgiAdminUserGroup} settings.
+
+The most common problem is that REMOTE_USER is not set because the
+Apache authentication is not correctly configured.  In this case
+BackupPC_Admin will report this additional error:
+
+    Note: $ENV{REMOTE_USER} is not set, which could mean there is an
+    installation problem.  BackupPC_Admin expects Apache to authenticate
+    the user and pass their user name into this script as the REMOTE_USER
+    environment variable.  See the documentation.
+
+You should review the configuration instructions to setup Apache
+authentication correctly.  To test if REMOTE_USER is being set
+correctly, there is a simple script called printenv that is
+included with Apache.  This is a simple CGI script that prints
+out all the environment variables.  Place this script in the
+same directory as BackupPC_Admin and run it with a URL like:
+
+    http://myHost/cgi-bin/BackupPC/printenv
+
+Check the value of the REMOTE_USER environment variable.
+Here's a copy of the printenv script:
+
+    #!/usr/bin/perl
+    ##
+    ##  printenv -- demo CGI program which just prints its environment
+    ##
+
+    print "Content-type: text/plain\n\n";
+    foreach $var (sort(keys(%ENV))) {
+        $val = $ENV{$var};
+        $val =~ s|\n|\\n|g;
+        $val =~ s|"|\\"|g;
+        print "${var}=\"${val}\"\n";
+    }
+

 =item Can't ping or find host
 
 Please read the section L<How BackupPC Finds Hosts|how backuppc finds hosts>.
 
 =item Can't ping or find host
 
 Please read the section L<How BackupPC Finds Hosts|how backuppc finds hosts>.
 

-You should also verify that nmblookup correctly returns the netbios name.
+The BackupPC_dump command now has a -v option, so the easiest way to
+debug backup problems on a specific host is to run BackupPC_dump
+manually as the BackupPC user:
+
+    su __BACKUPPCUSER__
+    __INSTALLDIR__/bin/BackupPC_dump -v -f hostName
+
+This will run a full dump on hostName (replace with your host name).
+It will show each command (eg: ping, nmblookup and the full dump
+commands) and the output from each command.  Reading the output
+carefully should show you what the problem is.
+
+You can 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:
 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:


@@ -1656,12 +1768,16 @@ The first name, converted to lower case, is used for the host name.
 
 =item Transport method doesn't work
 
 
 =item Transport method doesn't work
 

-The BackupPC_dump command now has a -v option, so the easiest way to
+The BackupPC_dump command has a -v option, so the easiest way to

 debug backup problems on a specific host is to run BackupPC_dump
 manually as the BackupPC user:
 
     su __BACKUPPCUSER__
 debug backup problems on a specific host is to run BackupPC_dump
 manually as the BackupPC user:
 
     su __BACKUPPCUSER__

-    __INSTALLDIR__/bin/BackupPC_zcat
+    __INSTALLDIR__/bin/BackupPC_dump -v -f hostName
+
+This will run a full dump on hostName (replace with your host name)
+and will print all the output from each command, including the log
+output.

 
 The most likely problems will relate to connecting to the smb shares on
 each host.  On each failed backup, a file __TOPDIR__/pc/$host/XferLOG.bad.z
 
 The most likely problems will relate to connecting to the smb shares on
 each host.  On each failed backup, a file __TOPDIR__/pc/$host/XferLOG.bad.z


@@ -2695,6 +2811,10 @@ 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.
 
 knows about this bug and can recover the correct file size.  So smbclient
 transport works up to 4GB file sizes.
 

+Rsync running on Cygwin is limited to either 2GB or 4GB file sizes.
+More testing needs to be done to verify the file size limit for
+rsync on various platforms.
+

 =back
 
 =item Some tape backup systems aren't smart about hard links
 =back
 
 =item Some tape backup systems aren't smart about hard links


@@ -3014,7 +3134,7 @@ for zip download, in addition to some CGI cleanup, for v1.5.0.
 
 Javier Gonzalez provided the Spanish translation, es.pm.
 
 
 Javier Gonzalez provided the Spanish translation, es.pm.
 

-Manfred provided the German translation, de.pm.
+Manfred Herrmann provided the German translation, de.pm.

 
 Many people have reported bugs, made useful suggestions and helped
 with testing; see the ChangeLog and the mail lists.
 
 Many people have reported bugs, made useful suggestions and helped
 with testing; see the ChangeLog and the mail lists.