brought man pages up to date.

4 files changed, 210 insertions, 104 deletions

diff --git a/docs/changelog b/docs/changelog
index afd3097..871c939 100644
--- a/docs/changelog
+++ b/docs/changelog
@@ -7,7 +7,10 @@ version 0.9 -- unreleased
 	changed direct grep of /etc/passwd to getent passwd.
 	rdiff helper has much better information on failed ssh attempt
 		(patch from cmccallum@thecsl.org).
-    	
+    rdiff handler now supports remote source and local dest. 
+    	(patch from cmccallum@thecsl.org).
+    man pages are greatly improved.
+
 version 0.8 -- September 15 2005
 	added pgsql (PostgreSQL) handler, with vservers support.
 	added vservers support to duplicity handler
diff --git a/docs/man/backup.d.5 b/docs/man/backup.d.5
new file mode 100644
index 0000000..34a2d92
--- /dev/null
+++ b/docs/man/backup.d.5
@@ -0,0 +1,106 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH BACKUP.D 5 "October 10, 2005" "riseup" "backupninja package"
+.SH NAME 
+BACKUP.D \- Action configuration files for \fBbackupninja(1)\fP.
+
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh        disable hyphenation
+.\" .hy        enable hyphenation
+.\" .ad l      left justify
+.\" .ad b      justify to both left and right margins
+.\" .nf        disable filling
+.\" .fi        enable filling
+.\" .br        insert line break
+.\" .sp <n>    insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.br
+.SH SYNOPSIS
+.B "/etc/backup.d/* "
+.br
+.SH DESCRIPTION
+
+To preform the actual backup actions, backupninja processes each action configuration file in
+/etc/backup.d according to the file's suffix.
+
+.IP .sh 10
+run this file as a shell script.
+.IP .rdiff
+backup action for rdiff-backup.
+.IP .dup
+backup action for duplicity.
+.IP .maildir
+backup action for slow, incremental rsyncs of tens of thousands of maildirs.
+.IP .mysql
+backup action for safe MySQL dumps.
+.IP .pgsql
+backup action for safe PostgreSQL dumps.
+.IP .ldap
+backup action for safe OpenLdap dumps.
+.IP .sys
+backup action for general system reports and hardware information.
+.IP .svn
+backup action for safe backups of subversion repositories.
+.IP .trac
+backup action for safe backups of trac repositories.
+.IP .makecd
+backup action for burning backups to CD/DVD or creating ISOs.
+
+.TP
+These files must be owned by root and must not be world or group readable/writable. Support for additional configuration types can be added by dropping bash scripts with the name of the suffix into /usr/share/backupninja. 
+.TP
+The configuration files are processed in alphabetical order. However, it is suggested that you name the config files in "sysvinit style." 
+.TP
+For example:
+ 10-disabled.ldap.disabled
+ 15-runthisfirst.sh
+ 20-runthisnext.mysql
+ 90-runthislast.rdiff
+.TP
+Typically, you will put a '.rdiff' config file last, so that any database dumps you make are included in the filesystem backup. Action configurations which begin end with .disabled are skipped.
+.TP
+Example templates for the action configuration files can be found in /usr/share/doc/backupninja/examples. You can also use \fBninjahelper(1)\fP, a console based "wizard" for creating backup actions.
+
+.SH SCHEDULING
+
+By default, each configuration file is processed everyday at 01:00 (1 AM). This can be changed by specifying the 'when' option in a backup action's config file or in the global configuration file. 
+
+For example:
+  when = sundays at 02:00
+  when = 30th at 22
+  when = 30 at 22:00
+  when = everyday at 01
+  when = Tuesday at 05:00
+  when = hourly
+
+These values for "when" are invalid:
+  when = tuesday at 2am
+  when = tuesday at 2
+  when = tues at 02
+
+A configuration file will be processed at the time(s) specified by the "when" option. If multiple "when" options are present, then they all apply. If two configurations files are scheduled to run in the same hour, then we fall back on the alphabetical ordering specified above. The "when" must occur before any sections in the action configuration file. 
+
+.SH FILE FORMAT
+
+The file format of the action configuration files is "ini style." Sections are created by using square bracket. Long lines are connected with a backslash. For example:
+
+   # this is a comment
+   [fishes]
+   fish = red
+   fish = blue
+   [fruit]
+   apple = yes
+   pear = no thanks \\
+   i will not have a pear.
+
+.SH SEE ALSO
+.BR backupninja (1), 
+.BR ninjahelper (1), 
+.BR backupninja.conf (5), 
+.br
+.SH AUTHOR
+BACKUPNINJA was written by the riseup.net collective.
diff --git a/docs/man/backupninja.1 b/docs/man/backupninja.1
index 5c6f2a1..f9d2ecc 100644
--- a/docs/man/backupninja.1
+++ b/docs/man/backupninja.1
@@ -2,7 +2,7 @@
 .\" First parameter, NAME, should be all caps
 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
 .\" other parameters are allowed: see man(7), man(1)
-.TH BACKUPNINJA 1 "January 2, 2005" "riseup" "backupninja package"
+.TH BACKUPNINJA 1 "October 10, 2005" "riseup" "backupninja package"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -21,7 +21,7 @@ BACKUPNINJA \- A lightweight, extensible meta-backup system
 .I
 "a silent flower blossom death strike to lost data."
 .SH SYNOPSIS
-.B "backupninja [ \-h ] [ \-d ] [ \-f filename]"
+.B "backupninja [ \-h ] [ \-d ] [ \-n ] [ \-t ] [ \-f filename ] [ \-\-run filename ]"
 .br
 .SH DESCRIPTION
 .B Backupninja 
@@ -33,17 +33,34 @@ coordinate many different backup utilities.
 .PP
 
 .SH FEATURES
- - easy to read ini style configuration files.
- - secure, remote, incremental filesytem backup (via rdiff-backup).
-   incremental data is compressed. permissions are retained even
-   with an unprivileged backup user.
- - backup of mysql databases (via mysqlhotcopy and mysqldump).
- - backup of ldap databases (via slapcat and ldapsearch).
- - passwords are never sent via the command line to helper programs.
- - you can drop in scripts to handle new types of backups.
- - backup actions can be scheduled
- - you can choose when status report emails are mailed to you
-   (always, on warning, on error, never).
+.IP - 2
+easy to read ini style configuration files.
+.IP -
+you can drop in scripts to handle new types of backups.
+.IP -
+backup actions can be scheduled.
+.IP -
+you can choose when status report emails are mailed to you (always, on warning, on error, never).
+.IP -
+console-based wizard (ninjahelper) makes it easy to create backup action configuration files.
+.IP -
+passwords are never sent via the command line to helper programs.
+.IP -
+in order to backup a db or sql database, you cannot simply copy database files. backupninja helps you safely export the data to a format which you can backup.
+.IP -
+works with Linux-Vservers. 
+
+.B Backup types include:
+.IP - 2
+secure, remote, incremental filesytem backup (via rdiff-backup). incremental data is compressed. permissions are retained even with an unpriviledged backup user.
+.IP -
+basic system and hardware information.
+.IP -
+encrypted remote backups (via duplicity).
+.IP -
+safe backup of MySQL, PostgreSQL, OpenLDAP, and subversion databases.
+.IP -
+burn CD/DVDs or create ISOs. 
 	 
 .\" TeX users may be more comfortable with the \fB<whatever>\fP and
 .\" \fI<whatever>\fP escape sequences to invoke bold face and italics, 
@@ -57,16 +74,27 @@ Show summary of options
 .B \-d, \-\-debug          
 Run in debug mode, where all log messages are output to the current shell.
 .TP
-.B \-f, \-\-conffile FILE  
-Use FILE for the main configuration instead of /etc/backupninja.conf
+.B \-f, \-\-conffile CONF_FILE  
+Use CONF_FILE for the main configuration instead of /etc/backupninja.conf
 .TP
 .B \-t, \-\-test           
 Run in test mode, no actions are actually taken.
 .TP
 .B \-n, \-\-now            
-Perform actions now, instead of when they  might be scheduled.
+Perform actions now, instead of when they might be scheduled.
+.TP
+.B \-\-run ACTION_FILE
+Runs the action configuration ACTION_FILE and exits.
+
+.SH CONFIGURATION
+
+General settings are configured in /etc/backupninja.conf. In this file you
+can set the log level and change the default directory locations. See \fBbackupnina.conf(5)\fP.
 
-.SH EXAMPLES
+To preform the actual backup actions, backupninja processes each action configuration file in
+/etc/backup.d according to the file's suffix. See \fBbackup.d(5)\fP.
+
+.SH EXAMPLE USAGE
 .TP
 Backupninja can be used to impliment whatever backup strategy you choose. It is intended, however, to be used like so:
 .TP
@@ -74,22 +102,13 @@ First, databases are safely copied or exported to /var/backups.  Often, you cann
 .TP
 Then, vital parts of the file system, including /var/backups, are nightly pushed to a remote, off-site, hard disk (using rdiff-backup). The local user is root, but the remote user is not privileged. Hopefully, the remote filesystem is encrypted.
 .TP
-There are many different backup strategies out there, including "pull style", magnetic tape, rsync + hard links, etc. We believe that the strategy outlined above is the way to go because: (1) hard disks are very cheap these days, (2) pull style backups are no good, because then the backup server must have root on the production server, and (3) rdiff-backup is more space efficient and featureful than using rsync + hard links.
-
-.SH SSH KEYS
-.TP
-In order for rdiff-backup to sync files over ssh unattended, you must create ssh keys on the source server and copy the public key to the remote user's authorized keys file. For example:
-
+In order for this to work (ie for diff-backup to run unattended), you must create ssh keys on the source server and copy the public key to the remote user's authorized keys file. For example:
 .br
 root@srchost# ssh-keygen -t dsa
 .br
 root@srchost# ssh-copy-id -i /root/.ssh/id_dsa.pub backup@desthost
-
-.TP
-Now, you should be able to ssh from user 'root' on srchost to user 'backup' on desthost without specifying a password.
-
 .TP
-Note: when prompted for a password by ssh-keygen, just leave it blank by hitting return.
+Now, you should be able to ssh from user 'root' on srchost to user 'backup' on desthost without specifying a password. When prompted for a password by ssh-keygen, just leave it blank by hitting return. The "wizard" \fBninjahelper(1)\fP will walk you through these steps.
 
 .SH FILES
 .PD 0
@@ -97,7 +116,7 @@ Note: when prompted for a password by ssh-keygen, just leave it blank by hitting
 .br
 \fB/etc/backupninja.conf\fP        main configuration file; general options
 .br
-\fB/etc/cron.d/backupninja\fP      runs main script nightly
+\fB/etc/cron.d/backupninja\fP      runs main script hourly
 .br
 \fB/etc/logrotate.d/backupninja\fP rotates backupninja.log
 .br
@@ -105,14 +124,14 @@ Note: when prompted for a password by ssh-keygen, just leave it blank by hitting
 .br
 \fB/usr/share/backupninja\fP       directory for handler scripts
 .br
+\fB/usr/share/doc/backupninja/examples\fP       example action configuration files.
+.br
 .PD
 
 .SH SEE ALSO
+.BR ninjahelper (1), 
 .BR backupninja.conf (5), 
+.BR backup.d (5), 
 .br
 .SH AUTHOR
-BACKUPNINJA was written by <elijah@riseup.net>.
-.br 
-BACKUPNINJA was packaged by <micah@riseup.net>.
-.PP
-This manual page was written by stefani <stefani@riseup.net>.
+BACKUPNINJA was written by the riseup.net collective.
diff --git a/docs/man/backupninja.conf.5 b/docs/man/backupninja.conf.5
index ba7d421..f96c931 100644
--- a/docs/man/backupninja.conf.5
+++ b/docs/man/backupninja.conf.5
@@ -2,7 +2,7 @@
 .\" First parameter, NAME, should be all caps
 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
 .\" other parameters are allowed: see man(7), man(1)
-.TH BACKUPNINJA.CONF 5 "January 2, 2005" "riseup" "backupninja package"
+.TH BACKUPNINJA.CONF 5 "October 10, 2005" "riseup" "backupninja package"
 .SH NAME 
 BACKUPNINJA.CONF \- Configuration file(s) for \fBbackupninja (1)\fP.
 
@@ -22,98 +22,76 @@ BACKUPNINJA.CONF \- Configuration file(s) for \fBbackupninja (1)\fP.
 .SH SYNOPSIS
 .B "/etc/backupninja.conf "
 .br
-.B "/etc/backup.d/* "
-.br
 .SH DESCRIPTION
 .B backupninja.conf
 is the general configuration file. In this file you can set the log level and change the default directory locations.  You can force a different general configuration file with "backupninja -f /path/to/conf".
 
-.TP
-To perform the actual backup, backupninja processes each configuration file in /etc/backup.d according to the file's suffix:
-.br
-  .sh      --  run this file as a shell script.
-  .rdiff   --  this is a configuration for rdiff-backup
-  .maildir --  this is a configuration to backup maildirs
-  .mysql   --  mysql backup configuration
-  .ldap    --  ldap backup configuration
-  .sys     --  general system reports
+.SH OPTIONS
 
 .TP
-Support for additional configuration types can be added by dropping bash scripts with the name of the suffix into /usr/share/backupninja.
+.B loglevel
+How verbose to make the logs. 
+.br
+5 = Debugging messages
+.br
+4 = Informational messages
+.br
+3 = Warnings
+.br
+2 = Errors
+.br
+1 = Fatal errors 
 
 .TP
-The configuration files are processed in alphabetical order. However, it is suggested that you name the config files in "sysvinit style."
+.B reportemail
+Send a summary of the backup status to this email address
 
 .TP
-For example:
-  00-disabled.ldap
-  10-runthisfirst.sh
-  20-runthisnext.mysql
-  90-runthislast.rdiff
+.B reportsuccess
+If set to 'yes', a report email will be generated even if all modules reported success.
 
 .TP
-Typically, you will put a '.rdiff' config file last, so that any database dumps you make are included in the filesystem backup.  Configurations files which begin with 0 (zero) are skipped.
+.B reportwarning
+If set to 'yes', a report email will be generated even if there was no error.
 
 .TP
-Unless otherwise specified, the config file format is "ini style."
+.B logfile
+The path of the logfile.
 
 .TP
-For example:
-
- # this is a comment
+.B configdirectory
+The directory where all the backup action configuration files live.
 
- [fishes]
- fish = red
- fish = blue
-
- [fruit]
- apple = yes
- pear = no thanks \
- i will not have a pear.
+.TP 
+.B scriptdirectory 
+Where backupninja handler scripts are found
 
+.TP
+.B usecolors
+If set to 'yes', use colors in the log file and debug output.
 
-.PP
+.SH DEFAULTS
 
-.SH SCHEDULING
+loglevel = 4
 .br
-By default, each configuration file is processed everyday at 01:00 (1
-AM). This can be changed by specifying the 'when' in a config file.
-
-For example:
-
-  when = sundays at 02:00
-  when = 30th at 22
-  when = 30 at 22:00
-  when = everyday at 01            <-- the default
-  when = Tuesday at 05:00
-
-A configuration file will be processed at the time(s) specified by the
-"when" option. If multiple "when" options are present, then they all
-apply. If two configurations files are scheduled to run in the same
-hour, then we fall back on the alphabetical ordering specified above.
-If two configurations files are scheduled close to one another in
-time, it is possible to have multiple copies of backupninja running if
-the first instance is not finished before the next one starts.
-
-These values for 'when' are equivalent:
-
-  when = tuesday at 05:30
-  when = TUESDAYS at 05
-
-These values for 'when' are invalid:
-  
-  when = tuesday at 2am
-  when = tuesday at 2
-  when = tues at 02
+reportemail = root
+.br
+reportsuccess = yes
 .br
+reportwarning = yes
+.br
+logfile = /var/log/backupninja.log
+.br
+configdirectory = /etc/backup.d
+.br
+scriptdirectory = /usr/share/backupninja
+.br
+usecolors = yes 
 
 .SH SEE ALSO
 .BR backupninja (1), 
+.BR ninjahelper (1), 
+.BR backup.d (5), 
 .br
 .SH AUTHOR
-BACKUPNINJA was written by <elijah@riseup.net>.
-.br
-BACKUPNINJA was packaged by <micah@riseup.net>.
-.br
-.PP
-This manual page was written by  <stefani@riseup.net>.
+BACKUPNINJA was written by the riseup.net collective.