I wrote:
> Hi,
>
> Not all Bacula man pages are up to date with the new options introduced
> in v3.0, or older options, or were somewhat inconsistent with other
> manpages, or their interactive (--help) equivalent.
>
> All the options were taken from v3.0.3's interactive help, so there
> could be some more missing; but the patches were made against the latest
> versions.
>
> Also, the pages for bsmtp doesn't seem to go by the usual manpage
> sections, and btraceback's is still in its infancy. Maybe it's why they
> got removed from the Debian distribution, so I'm thinking of rewriting
> and reformatting them to make a shinier package. Are there objections or
> guidelines to this ?
Here are
- five more updates to manpages options I had forgotten in a corner,
- a reformated and edited page for bsmtp
- a brand new one for btraceback, based on the Problem Resolution Guide
and discussions (to be continued?) on this list.
The patches try to use the DEP-3 headers [1], a proposal designed to
help distributions track and manage patches. They also contain dpatch
information, for the same purpose. All of this is just comments
prepended can be stripped off with no harm, the actual patch is in
standard git format.
[1] http://dep.debian.net/deps/dep3/
#! /bin/sh /usr/share/dpatch/dpatch-run
# 27_dbcheck-consistency.manpage.dpatch
#
# Description: adds missing and new options in the dbcheck utility's
# manpage. Introduces stricter consistency across the different
# Bacula manpages.
# Origin: vendor, file:///dev/null
# Bug-Debian: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=499619
# Forwarded:
http://sourceforge.net/mailarchive/message.php?msg_id=4B0E54F7.70108%40free.fr
# Author: Lucas B. Cohen <[email protected]>
# Last-Update: 2009-12-07
#
@DPATCH@
diff --git a/bacula/manpages/dbcheck.8 b/bacula/manpages/dbcheck.8
index 9e3a6f1..98b470d 100644
--- a/bacula/manpages/dbcheck.8
+++ b/bacula/manpages/dbcheck.8
@@ -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 DBCHECK 8 "26 September 2009" "Kern Sibbald" "Network backup, recovery and
verification"
+.TH DBCHECK 8 "6 December 2009" "Kern Sibbald" "Network backup, recovery and
verification"
.\" Please adjust this date whenever revising the manpage.
.\"
.SH NAME
@@ -40,12 +40,12 @@ Usage: dbcheck [-c config] [-C catalog name] [-d
debug_level] []
-b batch mode
-C catalog name in the director conf file
-c director conf filename
- -B print catalog configuration and exit
+ -B print catalog configuration
-dnn set debug level to nn
-dt print timestamp in debug output
-f fix inconsistencies
-v verbose
- -? print this message
+ -? show version and usage of program
If the -c option is given with the Director's conf file, there is no
need to enter any of the command line arguments, in particular the working
#! /bin/sh /usr/share/dpatch/dpatch-run
# 28_bconsole-v3-missing-edited-consistency-opts.manpage.dpatch
#
# Description: adds missing and new options in the bconsole utility's
# manpage. Also introduces better consistency between the Bacula
# utilities manpages.
# Origin: vendor, file:///dev/null
# Bug-Debian: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=499619
# Forwarded: yes
# Author: Lucas B. Cohen <[email protected]>
# Last-Update: 2009-12-07
#
# created by Lucas B. Cohen <[email protected]> with dpatch v2.0.31
@DPATCH@
diff --git a/bacula/manpages/bconsole.8 b/bacula/manpages/bconsole.8
index 843712d..c940545 100644
--- a/bacula/manpages/bconsole.8
+++ b/bacula/manpages/bconsole.8
@@ -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 CONSOLE 8 "26 September 2009" "Kern Sibbald" "Network backup, recovery and
verification"
+.TH CONSOLE 8 "4 December 2009" "Kern Sibbald" "Network backup, recovery and
verification"
.\" Please adjust this date whenever revising the manpage.
.\"
.SH NAME
@@ -25,13 +25,16 @@ Specify configuration file.
Set debug level to \fInn\fP.
.TP
.BI \-dt
-Print a timestamp in debug output.
+Print timestamp in debug output.
+.TP
+.B \-n
+No conio (for debugging).
.TP
.B \-s
-No signals.
+No signals (for debugging).
.TP
.B \-t
-Test config mode: read configuration and exit.
+Test the configuration file and report errors.
.TP
.B \-?
Show version and usage of program.
#! /bin/sh /usr/share/dpatch/dpatch-run
# 29_bacula-dir-v3-missing-edited-consistency-opts.manpage.dpatch
# Description: adds missing and new options in the bacula-dir manpage.
# Introduces stricter consistency across the different Bacula
# manpages.
# Origin: vendor, file:///dev/null
# Bug-Debian: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=499619
# Forwarded:
http://sourceforge.net/mailarchive/message.php?msg_id=4B0E54F7.70108%40free.fr
# Author: Lucas B. Cohen <[email protected]>
# Last-Update: 2009-12-07
#
@DPATCH@
diff --git a/bacula/manpages/bacula-dir.8 b/bacula/manpages/bacula-dir.8
index 5a33aad..50056e8 100644
--- a/bacula/manpages/bacula-dir.8
+++ b/bacula/manpages/bacula-dir.8
@@ -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 BACULA\-DIR 8 "26 September 2009" "Kern Sibbald" "Network backup,
recovery&verification"
+.TH BACULA\-DIR 8 "6 December 2009" "Kern Sibbald" "Network backup,
recovery&verification"
.\" Please adjust this date whenever revising the manpage.
.\"
.SH NAME
@@ -22,36 +22,38 @@ network backup system: it is responsible for scheduling and
coordinating backups across the network.
.SH OPTIONS
.TP
-.B \-c\ config
-Change location to read \fIbacula\-sd.conf\fP from (default $CWD)
+.BI \-c\ file
+Specify the configuration file to use.
.TP
-.B \-d <nn>
+.BI \-d\ nn
Set debug level to \fInn\fP.
.TP
-.B \-dt
-Print a timestamp in debug output
+.BI \-dt
+Print timestamp in debug output.
.TP
-.B \-f
-Run in the foreground (for debuggin)
+.BI \-f
+Run in foreground (for debugging).
.TP
.BI \-g\ group
Set the group/gid to run as.
.TP
-.B \-s
-No signals. Used in debugging only.
+.BI \-r\ job
+Run <job>.
+.TP
+.BI \-s
+No signals (for debugging).
.TP
.B \-t
-Test config mode: read configuration and exit.
+Test the configuration file and report errors.
.TP
.BI \-u\ user
Set the username/uid to run as.
.TP
-.B \-v
-Verbose user messages
+.BI \-v
+Set verbose mode.
.TP
-.B \-?
+.BI \-?
Show version and usage of program.
-
.SH TCP-WRAPPERS CONFIGURATION
Tcpwrappers looks for the service name of the bacula daemons in
.I hosts.allow
#! /bin/sh /usr/share/dpatch/dpatch-run
# 30_bacula-sd-v3-missing-edited-consistency-opts.manpagedpatchh
#
# Description: adds missing and new options in the bacula-sd manpage.
# Introduces stricter consistency across the different Bacula
# manpages.
# Origin: vendor, file:///dev/null
# Bug-Debian: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=499619
# Forwarded:
http://sourceforge.net/mailarchive/message.php?msg_id=4B0E54F7.70108%40free.fr
# Author: Lucas B. Cohen <[email protected]>
# Last-Update: 2009-12-07
#
@DPATCH@
diff --git a/bacula/manpages/bacula-sd.8 b/bacula/manpages/bacula-sd.8
index fee1b84..dde7279 100644
--- a/bacula/manpages/bacula-sd.8
+++ b/bacula/manpages/bacula-sd.8
@@ -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 BACULA\-SD 8 "26 September 2009" "Kern Sibbald" "Network backup, recovery
& verification"
+.TH BACULA\-SD 8 "6 December 2009" "Kern Sibbald" "Network backup, recovery &
verification"
.\" Please adjust this date whenever revising the manpage.
.\"
.SH NAME
@@ -22,36 +22,38 @@ network backup system and a tape drive/autochanger or
filesystem where
the backups will be stored.
.SH OPTIONS
.TP
-.B \-c\ config
-Change location to read \fIbacula\-sd.conf\fP from (default $CWD)
+.BI \-c\ file
+Specify the configuration file to use.
.TP
-.B \-d <nn>
+.BI \-d\ nn
Set debug level to \fInn\fP.
.TP
-.B \-dt
-Print a timestamp in debug output
+.BI \-dt
+Print timestamp in debug output.
.TP
-.B \-f
-Run in the foreground (for debuggin)
+.BI \-f
+Run in foreground (for debugging).
.TP
.BI \-g\ group
Set the group/gid to run as.
.TP
-.B \-s
-No signals. Used in debugging only.
+.BI \-p
+Proceed inspite of I/O errors
+.TP
+.BI \-s
+No signals (for debugging).
.TP
.B \-t
-Test config mode: read configuration and exit.
+Test the configuration file and report errors.
.TP
.BI \-u\ user
Set the username/uid to run as.
.TP
-.B \-v
-Verbose user messages
+.BI \-v
+Set verbose mode.
.TP
.B \-?
Show version and usage of program.
-
.SH SEE ALSO
.BR bacula\-dir (8),
.BR bacula\-fd (8).
#! /bin/sh /usr/share/dpatch/dpatch-run
# 31_bacula-fd-v3-missing-edited-consistency.manpage.dpatch
#
# Description: adds missing and new options in the bacula-sd manpage.
# Introduces stricter consistency across the different Bacula
# manpages.
# Origin: vendor, file:///dev/null
# Bug-Debian: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=499619
# Forwarded:
http://sourceforge.net/mailarchive/message.php?msg_id=4B0E54F7.70108%40free.fr
# Author: Lucas B. Cohen <[email protected]>
# Last-Update: 2009-12-07
#
@DPATCH@
diff --git a/bacula/manpages/bacula-fd.8 b/bacula/manpages/bacula-fd.8
index 1754af8..2dfbf9e 100644
--- a/bacula/manpages/bacula-fd.8
+++ b/bacula/manpages/bacula-fd.8
@@ -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 BACULA\-FD 8 "26 September 2009" "Kern Sibbald" "Network backup, recovery
& verification"
+.TH BACULA\-SD 8 "6 December 2009" "Kern Sibbald" "Network backup, recovery &
verification"
.\" Please adjust this date whenever revising the manpage.
.\"
.SH NAME
@@ -24,35 +24,38 @@ backup'd/verified/restored. Network transfer can optionally
be
compressed.
.SH OPTIONS
.TP
-.B \-c\ config
-Change location to read \fIbacula\-sd.conf\fP from (default $CWD)
+.BI \-c\ file
+Specify the configuration file to use.
.TP
-.B \-d <nn>
+.BI \-d\ nn
Set debug level to \fInn\fP.
.TP
-.B \-dt
-Print a timestamp in debug output
+.BI \-dt
+Print timestamp in debug output.
.TP
-.B \-f
-Run in the foreground (for debuggin)
+.BI \-f
+Run in foreground (for debugging).
.TP
.BI \-g\ group
Set the group/gid to run as.
.TP
+.BI \-p
+Proceed inspite of I/O errors
+.TP
.BI \-k
-Keep readall permission when dropping privilege.
+Keep readall permission when dropping privileges.
.TP
-.B \-s
-No signals. Used in debugging only.
+.BI \-s
+No signals (for debugging).
.TP
.B \-t
-Test config mode: read configuration and exit.
+Test the configuration file and report errors.
.TP
.BI \-u\ user
Set the username/uid to run as.
.TP
-.B \-v
-Verbose user messages
+.BI \-v
+Set verbose mode.
.TP
.B \-?
Show version and usage of program.
@@ -61,4 +64,4 @@ Show version and usage of program.
.BR bacula\-sd (8).
.br
.SH AUTHOR
-This manual page was written by Jose Luis Tallon
<[email protected]\-solutions.net>.
+This manual page was written by Jose Luis Tallon <jltal...@adv\-solutions.net>.
#! /bin/sh /usr/share/dpatch/dpatch-run
# 32_bsmtp-reformat-edit.manpage.dpatch
#
# Description: stricter formatting, factual check, and edition
# of the bsmtp manpage.
# Origin: vendor, file:///dev/null
# Bug-Debian: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=519573
# Forwarded: yes
# Author: Lucas B. Cohen <[email protected]>
# Last-Update: 2009-12-07
#
@DPATCH@
diff --git a/bacula/manpages/bsmtp.1 b/bacula/manpages/bsmtp.1
index fa3cf52..fee6162 100644
--- a/bacula/manpages/bsmtp.1
+++ b/bacula/manpages/bsmtp.1
@@ -1,67 +1,118 @@
.\" Hey, EMACS: -*- nroff -*-
-.TH BACULA\-SMTP 1 "26 September 2009" "Kern Sibbald" "Network backup"
+.\" 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 BSMTP 1 "6 December 2009" "Kern Sibbald" "Network backup, recovery and
verification"
.\" Please adjust this date whenever revising the manpage.
+.\"
.SH NAME
- bsmtp \- Bacula's SMTP (mail delivery program)
+ bsmtp \- Bacula's SMTP client (mail submission program)
+
+.SH SYNOPSIS
+.B bsmtp
+.RI [ options ]
+.I <recipient> <...>
+
.SH DESCRIPTION
-bsmtp is a simple mail transport program that permits more flexibility
-than the standard mail programs typically found on Unix systems. It can even
-be used on Windows machines.
+.B bsmtp
+is a simple mail user agent designed to permit more flexibility
+than the standard mail programs typically found on Unix systems, and to
+ease portability. It can even run on Windows machines. It is used
+by the Director daemon to send notifications and requests to the
+operator.
-It is called:
+.SH OPTIONS
+.TP
+.B \-8
+Encode the mail in UTF-8.
+.TP
+.B \-c
+Set the \fBCc:\fR header.
+.TP
+.BI \-d\ nn
+Set debug level to \fInn\fP.
+.TP
+.BI \-dt
+Print timestamp in debug output.
+.TP
+.B \-f
+Set the \fBFrom:\fR header. If not specified,
+.B bsmtp
+will try to use your username.
+.TP
+.BI \-h\ mailhost:port
+Use mailhost:port as the SMTP server. (default port: 25)
+.TP
+.B \-s
+Set the \fBSubject:\fR header.
+.TP
+.B \-r
+Set the \fBReply-To:\fR: header.
+.TP
+.B \-l
+Set the maximum number of lines to be sent. (default: unlimited)
+.TP
+.B \-?
+Show version and usage of program.
-Usage: bsmtp [-f from] [-h mailhost] [-s subject] [-c copy] [recipient ...]
- -8 set the charset to UTF-8
- -c set the Cc: field
- -dnn set debug level to nn
- -dt print a timestamp in debug output
- -f set the From: field
- -h use mailhost:port as the bsmtp server
- -s set the Subject: field
- -r set the Reply-To: field
- -l set the maximum number of lines that should be sent
(default: unlimited)
- -? print this message.
+.SH USAGE
+\fIrecipients\fR is a space separated list of email addresses.
-If the -f option is not specified, bsmtp will use your userid. If
-the option is not specified bsmtp will use the value in the environment
-variable bsmtpSERVER or if there is none localhost. By default
-port 25 is used.
+The body of the email message is read from standard input. Message is
+ended by sending the EOF character (Ctrl-D on many systems) on the
+start of a new line, much like many 'mail' commands.
-recipients is a space separated list of email recipients.
+The actual, automated behavior of \fBbsmtp\fR will depend on the
+mail-related configuration of the Director in the \fIMessages\fR ressource
+of \fIbacula-dir.conf\fR.
-The body of the email message is read from standard input.
+Interactive use of \fBbsmtp\fR is pertinent to manually test and ensure these
+configuration bits are valid. This is highly recommended.
-An example of the use of bsmtp would be to put the following statement
-in the Messages resource of your bacula-dir.conf file. Note, these
-commands should appear on a single line each.
+.SH CONFIGURATION
+These commands should each appear on a single line in the configuration
+file.
- mailcommand = "/home/bacula/bin/bsmtp -h mail.domain.com -f \"\(Bacula\) %r\"
- -s \"Bacula: %t %e of %c %l\" %r"
- operatorcommand = "/home/bacula/bin/bsmtp -h mail.domain.com -f \"\(Bacula\)
%r\"
- -s \"Bacula: Intervention needed for %j\" %r"
+Messages {
+ Name = Standard
+ mailcommand = "/home/bacula/bin/bsmtp -h mail.domain.com -f \"\(Bacula\)
%r\"
+ -s \"Bacula: %t %e of %c %l\" %r"
+ operatorcommand = "/home/bacula/bin/bsmtp -h mail.domain.com -f \"\(Bacula\)
%r\"
+ -s \"Bacula: Intervention needed for %j\" %r"
+ mail = [email protected] = all, !skipped
+ operator = [email protected] = mount
+ console = all, !skipped, !saved
+ }
-Where you replace home/bacula/bin with the path to your Bacula
-binary directory, and you replace mail.domain.com with the fully
-qualified name of your bsmtp (email) server, which normally listens on port
+\fIhome/bacula/bin\fR is replaced with the path to the Bacula
+binary directory, and mail.domain.com is replaced with the fully
+qualified name of an SMTP server, which usually listen on port 25.
-It is HIGHLY recommended that you test one or two cases by hand to make sure
-that the mailhost that you specified is correct and that it will accept
-your email requests. Since bsmtp always uses a TCP connection rather
-than writing in the spool file, you may find that your from address is
-being rejected because it does not contain a valid domain, or because your
-message is caught in your spam filtering rules. Generally, you should specify
-a fully qualified domain name in the from field, and depending on
-whether your bsmtp gateway is Exim or Sendmail, you may need to modify the
-syntax of the from part of the message. Please test.
+.SH ENVIRONMENT
+If the \fB-h\fR option is not specified, \fBbsmtp\fR will use environment
variable \fBSMTPSERVER\fR, or 'localhost' if not set.
-When running bsmtp by hand, you will need to terminate the message by
-entering a ctl-d in column 1 of the last line.
+.SH NOTES
+Since \fBbsmtp\fR always uses a TCP connection rather than writing to a
+spool file, you may find that your \fBFrom:\fR address is being rejected
+because it does not contain a valid domain, or because your
+message has gotten caught in spam filtering rules. Generally, you
+should specify a fully qualified domain name in the from field, and
+depending on whether your SMTP gateway is Exim or Sendmail, you may
+need to modify the syntax of the from part of the message.
+If \fBbsmtp\fR cannot connect to the specified mail host, it will retry
+to connect to \fBlocalhost\fR.
+
+.SH BUGS
If you are getting incorrect dates (e.g. 1970) and you are
-running with a non-English language setting, you might try adding
-a LANG="en_US" immediately before the bsmtp call.
-.br
+running with a non-English locale, you might try setting the
+\fBLANG="en_US"\fR environment variable.
+
.SH AUTHOR
This manual page was written by Jose Luis Tallon
.nh
-<jltal...@adv\-solutions.net>.
+<jltal...@adv\-solutions.net>, revised and edited by Lucas B. Cohen
+.nh
+<[email protected]>.
+.SH SEE ALSO
+.BR "bacula-dir" "(8) "
\ No newline at end of file#! /bin/sh /usr/share/dpatch/dpatch-run
# 33_btraceback_new.manpage.dpatch
#
# Description: btraceback manpage from skeleton.
# Origin: vendor, file:///dev/null
# Forwarded: yes
# Author: Lucas B. Cohen <[email protected]>
# Last-Update: 2009-12-07
#
@DPATCH@
diff -urNad a/bacula/manpages/btraceback.8 b/bacula/manpages/btraceback.8
--- a/bacula/manpages/btraceback.8 2009-12-02 00:59:28.000000000 +0100
+++ b/bacula/manpages/btraceback.8 2009-12-06 17:35:36.000000000 +0100
@@ -1,11 +1,66 @@
.\" Hey, EMACS: -*- nroff -*-
-.TH BTRACEBACK 8 "26 May 2006" "Kern Sibbald" "Network backup"
+.\" 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 BTRACEBACK 1 "6 December 2009" "Kern Sibbald" "Network backup, recovery
and verification"
.\" Please adjust this date whenever revising the manpage.
+.\"
.SH NAME
- btraceback \- Produce a traceback on the event of a 'Kaboom'
+ btraceback \- wrapper script around gdb and bsmtp
+
+.SH SYNOPSIS
+.B btraceback
+.I /path/to/binary
+.I pid
+
.SH DESCRIPTION
-.br
+\fBbtraceback\fR is a simple wrapper shellscript around the \fBgdb\fR debugger
+(or \fBdbx\fR on Solaris systems) and \fBbsmtp\fR, provided for debugging
purposes.
+
+.SH USAGE
+\fBbtraceback\fR is called solely by the exception handlers of the Bacula
daemons upon
+an imminent crash. It can also be called interactively to view the
+current state of the threads belonging to a process.
+
+.SH NOTES
+In order to work properly, debugging symbols must be available to the
+debugger on the system, and gdb, or dbx (on Solaris systems) must be
+available in the \fB$PATH\fR.
+
+If the Director or Storage daemon runs under a non-root uid, it will
+most likely be needed to modify the \fBbtraceback\fR script to elevate
+privileges for the call to \fBgdb\fR/\fBdbx\fR, to ensure it has the proper
+permissions to debug.
+
+Interactive use of \fBbtraceback\fR is subject to the same risks than live
+debugging of any program, which means it could cause Bacula to crash under
+rare and abnormal circumstances. Interactive use is not recommended in
+production environments.
+
+.SH ENVIRONMENT
+\fBbtracback\fR relies on \fB$PATH\fR to find the debugger.
+
+.SH FILES
+.TP
+.I /usr/lib/bacula/btraceback
+.RS
+The script itself.
+.RE
+.TP
+.I /usr/sbin/btraceback
+.RS
+symbolic link to \fI/usr/lib/bacula/btraceback\fR
+.RE
+.TP
+.I /etc/bacula/scripts/btraceback.gdb
+.RS
+the GDB command batch used to output a stack trace
+.RE
+
.SH AUTHOR
-This manual page was written by Jose Luis Tallon
-.nh
-<jltal...@adv\-solutions.net>.
+This manual page was written by Lucas B. Cohen
+.nh
+<[email protected]>
+.SH SEE ALSO
+.BR "bsmtp" "(1) "
+
+
------------------------------------------------------------------------------
Join us December 9, 2009 for the Red Hat Virtual Experience,
a free event focused on virtualization and cloud computing.
Attend in-depth sessions from your desk. Your couch. Anywhere.
http://p.sf.net/sfu/redhat-sfdev2dev
_______________________________________________
Bacula-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/bacula-devel
