X-Git-Url: http://git.rot13.org/?p=BackupPC.git;a=blobdiff_plain;f=doc-src%2FBackupPC.pod;h=e8e8c0a1460dcce873762cd90dafa6842f6c0bd0;hp=4b6e6401c0641c57143801d0d92df881c8951b2f;hb=5729095faa3ef12dc5d4f02538c3650ac81912ef;hpb=c6cebe03e53dcc49f889cf15ccda5b0fe3acd235 diff --git a/doc-src/BackupPC.pod b/doc-src/BackupPC.pod index 4b6e640..e8e8c0a 100644 --- 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, -currently prodiving English, French and Spanish. +currently providing English, French, German and Spanish. =item * @@ -346,7 +346,7 @@ implementation effort. The program xdelta (v1) on SourceForge (see L) 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 @@ -407,8 +407,8 @@ compression is on. =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. +version 5.6.0, 5.6.1 and 5.8.0. If you don't have perl, please +see L. =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. -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 -version 2.5.5 on each client machine. See L. -Use "rsync --version" to check your version. +version 2.5.5 or higher on each client machine. See +L. 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. Version 0.31 or later is required. +L. Version 0.44 or later is required. =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. -Version 0.31 or later is required. +Version 0.44 or later is required. =back @@ -754,9 +755,9 @@ Here's a simple example of a hosts file: =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 @@ -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.) -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. 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 @@ -1248,7 +1257,7 @@ you should turn it off: 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: PerlModule Apache::Registry @@ -1261,10 +1270,31 @@ to Apache's httpd.conf file: +Apache 2.0.44 with Perl 5.8.0 on RedHat 7.1, Don Silvia reports that +this works: + + LoadModule perl_module modules/mod_perl.so + PerlModule Apache2 + + + 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 + + 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. =back @@ -1300,9 +1330,14 @@ One alternative is to use LDAP. In Apache's http.conf add these lines: require valid-user -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: # <--- change path as needed Setenv REMOTE_USER www @@ -1311,11 +1346,14 @@ to hardcode the user to www you could add this to httpd.conf: 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 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 @@ -1401,6 +1439,46 @@ but does respond to a request directed to its IP address: =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 @@ -1534,40 +1612,144 @@ can now re-start BackupPC. =head2 Debugging installation problems This section will probably grow based on the types of questions on -the BackupPC mail list. +the BackupPC mail list. Eventually the FAQ at +L will include more details +than this section. + +=over 4 + +=item Check log files 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. +specific to that host. Always check both log files. -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. +=item CGI script doesn't run -You should run smbclient manually and verify that you can connect to -the host in interactive mode, eg: +Perhaps the most common program with the installation is getting the +CGI script to run. Often the setuid isn't configured correctly, or +doesn't work on your system. - smbclient '\\hostName\shareName' -U userName +First, try running BackupPC_Admin manually as the BackupPC user, eg: -shareName should match the $Conf{SmbShareName} setting and userName -should match the the $Conf{SmbShareUserName} setting. + su __BACKUPPCUSER__ + __CGIDIR__/BackupPC_Admin -You will be prompted for the password. You should then see this prompt: +Now try running it as the httpd user (which ever user apache runs as); - smb: \> + su httpd + __CGIDIR__/BackupPC_Admin -Verify that "ls" works and then type "quit" to exit. +In both cases do you get normal html output? + +If the first case works but the second case fails with an error that +the wrong user is running the script then you have a setuid problem. +(This assumes you are running BackupPC_Admin without mod_perl, and +you therefore need seduid to work. If you are using mod_perl then +apache should run as user __BACKUPPCUSER__.) + +First you should make sure the cgi-bin directory is on a file system +that doesn't have the "nosuid" mount option. + +Next, experiment by creating this script: + + #!/bin/perl + + printf("My userid is $> (%s)\n", (getpwuid($>))[0]); + +then chown it to backuppc and chmod u+s: + + root# chown backuppc testsetuid + root# chmod u+s testsetuid + root# chmod a+x testsetuid + root# ls -l testsetuid + -rwsr-xr-x 1 backuppc wheel 76 Aug 26 09:46 testsetuid* + +Now run this program as a normal user. What uid does it print? +Try changing the first line of the script to directly call sperl: + + #!/usr/bin/sperl5.8.0 + +(modify according to your version and path). Does this work +instead? + +Finally, you should invoke the CGI script from a browser, using +a URL like: + + http://myHost/cgi-bin/BackupPC/BackupPC_Admin + +You should make sure REMOTE_USER is being set by apache (see the +earlier section) so that user authentication works. Make sure +the config settings $Conf{CgiAdminUserGroup} and $Conf{CgiAdminUsers} +correctly specify the privileged administrator users. -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: +=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. + +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: nmblookup -A hostName @@ -1584,6 +1766,50 @@ Verify that the host name is printed. The output might look like: The first name, converted to lower case, is used for the host name. +=item Transport method doesn't work + +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__ + __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 +will be created. This is the stderr output from the transport program. +You can view this file via the CGI interface, or manually uncompress it +with; + + __INSTALLDIR__/bin/BackupPC_zcat __TOPDIR__/pc/$host/XferLOG.bad.z | more + +The first line will show the full command that was run (eg: rsync, tar +or smbclient). 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 try running the command manually to see what happens. +For example, for smbclient you should it 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. + +=back + =head1 Restore functions BackupPC supports several different methods for restoring files. The @@ -2585,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. +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 @@ -2840,13 +3070,14 @@ the appropriate config 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 @@ -2901,7 +3132,9 @@ for v1.5.0. He also contributed the first skeleton of BackupPC_restore. Guillaume Filion wrote BackupPC_zipCreate and added the CGI support for zip download, in addition to some CGI cleanup, for v1.5.0. -Javier provided the Spanish translation, es.pm. +Javier Gonzalez provided the Spanish translation, es.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.