From 954cb68c03233d0882114cdb452c1c9ecd010d2b Mon Sep 17 00:00:00 2001 From: "Lucas B. Cohen" Date: Wed, 9 Dec 2009 16:23:36 +0100 Subject: [PATCH] - 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. --- bacula/manpages/bacula-dir.8 | 32 ++++---- bacula/manpages/bacula-fd.8 | 33 ++++---- bacula/manpages/bacula-sd.8 | 30 +++---- bacula/manpages/bconsole.8 | 11 ++- bacula/manpages/bsmtp.1 | 147 +++++++++++++++++++++++------------ bacula/manpages/btraceback.8 | 67 ++++++++++++++-- 6 files changed, 218 insertions(+), 102 deletions(-) diff --git a/bacula/manpages/bacula-dir.8 b/bacula/manpages/bacula-dir.8 index 5a33aad95b..50056e8b10 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 +.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 . +.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 diff --git a/bacula/manpages/bacula-fd.8 b/bacula/manpages/bacula-fd.8 index 1754af87ba..2dfbf9ed57 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 +.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 . +This manual page was written by Jose Luis Tallon . diff --git a/bacula/manpages/bacula-sd.8 b/bacula/manpages/bacula-sd.8 index fee1b84d8a..dde7279025 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 +.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). diff --git a/bacula/manpages/bconsole.8 b/bacula/manpages/bconsole.8 index 843712d43f..46b0cc79a9 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. diff --git a/bacula/manpages/bsmtp.1 b/bacula/manpages/bsmtp.1 index fa3cf52361..fee6162c5b 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 <...> + .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 = sysadmin@site.domain.com = all, !skipped + operator = sysop@site.domain.com = 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 -. +, revised and edited by Lucas B. Cohen +.nh +. +.SH SEE ALSO +.BR "bacula-dir" "(8) " \ No newline at end of file diff --git a/bacula/manpages/btraceback.8 b/bacula/manpages/btraceback.8 index e560490160..8e2004a791 100644 --- a/bacula/manpages/btraceback.8 +++ b/bacula/manpages/btraceback.8 @@ -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 -. +This manual page was written by Lucas B. Cohen +.nh + +.SH SEE ALSO +.BR "bsmtp" "(1) " + -- 2.39.5