diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-04-25 12:28:00 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-04-25 12:28:00 +0300 |
commit | f997bbeb356818e9fc808dfe2ed803432aa1c870 (patch) | |
tree | 15bfee55f73728c3d0f8cb6bab03c4875b95f6be | |
parent | e68bb718eb37adc37d9fc13ec0cd4299429ed87c (diff) | |
download | slb-f997bbeb356818e9fc808dfe2ed803432aa1c870.tar.gz slb-f997bbeb356818e9fc808dfe2ed803432aa1c870.tar.bz2 |
Update the docs.
-rw-r--r-- | doc/config.texi | 5 | ||||
-rw-r--r-- | doc/slb.8 | 139 | ||||
-rw-r--r-- | doc/slb.texi | 226 |
3 files changed, 345 insertions, 25 deletions
diff --git a/doc/config.texi b/doc/config.texi index 4e8ef8d..b7af0dc 100644 --- a/doc/config.texi +++ b/doc/config.texi @@ -446,7 +446,7 @@ print-priority yes; @node daemon @section Daemon Configuration - The following statements configure @command{sld} activities in + The following statements configure @command{slb} activities in daemon mode. @deffn {Config} daemon bool @@ -626,7 +626,7 @@ The following functions are supported by SLB version @value{VERSION}: @anchor{derivative} @deffn {function} d (x) Returns the derivative of @var{x}, i.e. the speed of its change per -second, measured between the two last wakeups of @command{sld} +second, measured between the two last wakeups of @command{slb} (@FIXME-pxref{wakeup}). Notice, that this function is available only in daemon mode @@ -849,6 +849,7 @@ Print at most @var{number} entries from the bottom of the table, i.e. the @var{number} of the most loaded server entries. @end deffn +@anchor{output-file} @deffn {Config} output-file string Send output to the channel, identified by @var{string}. Unless @var{string} starts with a pipe sign, it is taken as a literal name of @@ -13,17 +13,24 @@ .\" .\" You should have received a copy of the GNU General Public License .\" along with SLB. If not, see <http://www.gnu.org/licenses/>. -.TH SLB "8" "April 20, 2011" "SLB" "" +.TH SLB "8" "April 25, 2011" "SLB" "" .SH NAME \fBslb\fR \- Simple Load Balancer .SH SYNOPSIS \fBslb\fR [\-EVehnt] [\-D \fISYMBOL[=VALUE]\fR] [\-I \fIDIR\fR]\ - [\-c \fIFILE\fR] [\-d \fICAT\fR[.\fILEVEL\fR]] [--config-file=\fIFILE\fR]\ + [\-o \fIFILE\fR] [\-c \fIFILE\fR] [\-d \fICAT\fR[.\fILEVEL\fR]] [--config-file=\fIFILE\fR]\ [\-\-config-help] [\-\-cron] [\-\-debug=\fICAT\fR[.\fILEVEL\fR]] [\-\-define=\fISYMBOL[=VALUE]\fR]\ [\-\-dry-run] [\-\-foreground]\ [\-\-help] [\-\-include-directory=\fIDIR\fR] [\-\-lint] [\-\-no-preprocessor]\ - [\-\-preprocessor=\fICOMMAND\fR] [\-\-stderr] [\-\-syslog] [\-\-usage] [\-\-version] + [\-\-output-file=\fIFILE\fR] [\-\-preprocessor=\fICOMMAND\fR] [\-\-stderr]\ + [\-\-syslog] [\-\-usage] [\-\-version] +.br +\fBslb\fR \-\-eval=\fINAME\fR [variable=\fIvalue\fR...] +.br +\fBslb\fR \-T [\fIFILE\fR] +.br +\fBslb\fR \-\-test [\fIFILE\fR] .SH DESCRIPTION \fBSlb\fR is a tool designed to simplify the task of load balancing @@ -60,15 +67,43 @@ source. .SH OPTIONS .TP -\fB\-E\fR -Preprocess config and exit. -.TP \fB-c\fR \fIFILE\fR, \fB\-\-config-file\fR=\fIFILE\fR Read \fIFILE\fR instead of the default configuration file. .TP \fB\-\-cron\fR Cron mode: run load estimation loop once and exit. .TP +\fB\-\-eval\fR=\fINAME\fR +Evaluate the expression \fINAME\fR, print its result and exit. +The expression must be defined in the configuration file with +the \fBexpression\fR statement (see \fBCONFIGURATION FILE\fR below). +Actual values for the variables used in the expression can be supplied +in the form of assignments in the command line, e.g.: + + slb --eval=loadavg la1=10 outbytes=1800 + +Several values can be supplied for a single variable as in: +in: + + slb --eval=loadavg la1=10,11 outbytes=1800,3000,4500 + +In this case the expression will be evaluated as many times as the +maximum number of values, the result of each evaluation being +printed to the standard output. In the example above, the expression +is evaluated three times, with the following values as input: + + la1=10 outbytes=1800 + la1=11 outbytes=3000 + la1=11 outbytes=4500 + +This form is useful if the expression contains the \fBd\fR() function, +which requires at least a pair of data to compute a meaningful value. +.TP +\fB\-E\fR +Preprocess config and exit. +.TP +\fB\ +.TP \fB\-\-foreground\fR Do not detach from the controlling terminal, run in foreground. .TP @@ -80,6 +115,37 @@ have otherwise been printed on the output file. This option implies .TP \fB\-t\fR, \fB\-\-lint\fR Parse the configuration file and exit. +.TP +\fB-T\fR, \fB\-\-test\fR +Read SNMP variables and their values from a file and act as if they +were returned by SNMP. The output is directed to the standard output, +unless the \fB\-\-output-file\fR option is also given. + +The input file name is taken from the first non-option argument. If +it is \fB-\fR (a dash) or if no arguments are given, the standard +input will be read. + +The input file consists of sections separated by exactly one empty +line. A section contains assignments to SNMP variables in the style +of \fBsnmpset(1)\fR. Such assignments form several server groups, each +group being preceded by a single word on a line, followed by a +semicolon. This word indicates the \fBID\fR of the server to which +the data in the group belong. For example: + + srv01: + UCD-SNMP-MIB::laLoadFloat.1 F 0.080000 + IF-MIB::ifOutUcastPkts.3 c 346120120 + srv02: + UCD-SNMP-MIB::laLoadFloat.1 F 0.020000 + IF-MIB::ifOutUcastPkts.3 c 2357911693 + +This section supplies data for two servers, named \(aqsrv01\(aq and +\(aqsrv02\(aq. +.TP +\fB\-o\fR, \fB\-\-output-file\fR=\fIFILE\fR +Direct output to \fIFILE\fR. This option overrides the +\fBoutput-file\fR configuration statement (see below). The format of +\fIFILE\fR argument is the same as for that statement. .SS Logging .TP \fB-e\fR, \fB--stderr\fR @@ -298,6 +364,9 @@ Multiplication. .TP \fB/\fR Division. +.TP +\fB**\fR +Power. .PP A \fBsubexpression reference\fR is a construct in the form: @@ -363,7 +432,7 @@ The following functions are supported: .TP \fBd\fR(\fIx\fR) Returns the derivative of \fIx\fR, i.e. the speed of its change per -second, measured between the two last wakeups of \fBsld\fR. +second, measured between the two last wakeups of \fBslb\fR. Notice, that this function is available only in daemon mode. .TP @@ -444,9 +513,10 @@ value is padded on the right with blanks, rather than on the left with blanks or zeros. A \fB-\fR overrides a \fB0\fR if both are given. .TP -' ' (a space) -A blank should be left before a positive number (or empty string) -produced by conversion. +.B \(aq \(aq +(a space) A blank should be left before a positive number +(or empty string) produced by a conversion. + .SS The field width An optional decimal digit string (with non-zero first digit) specifying a minimum field width. If the converted value has fewer @@ -491,6 +561,55 @@ Expansion of the \fImacro\fR. \fB%\fR The percent character. +.SH SIGNALS +The program handles a set of signals. To send a signal to +\fBslb\fR use the following command: + + kill -\fBSIGNAL\fR `cat /var/run/slb.pid` + +Replace \fI/var/run/slb.pid\fR with the actual pathname to the +PID-file, if it was set using the \fBpidfile\fR configuration +statement. + +.TP +.B SIGHUP +Instructs the running instance of the program +to restart itself. It is possible only if \fBslb\fR was started using +its full pathname. +.TP +.BR SIGTERM ", " SIGQUIT ", " \fBSIGINT\fR +\fBslb\fR terminates gracefully. + +.SH EXIT CODES +The following exit codes are defined: +.RS +.PD 0 +.TP 3 +.I 0 +Normal termination. +.TP 3 +.I 64 +Invalid command line usage. +.TP 3 +.I 65 +Input data were invalid or malformed. This error code is returned +only when \fBslb\fR is used with \fB\-\-test\fR or +\fB\-\-eval\fR options. +.TP 3 +.I 69 +Some error occurred. For example, the program was unable to open +output file, etc. +.TP 3 +.I 70 +Internal software error. This usually means hitting a bug in the +program, so please report it. +.TP 3 +.I 98 +Program terminated due to errors in configuration file. +.PD +.RE +If a non-0 code is returned the exact cause of failure is +reported on the currently selected logging channel. .SH AUTHORS Sergey Poznyakoff diff --git a/doc/slb.texi b/doc/slb.texi index 19cdcd0..c16c32d 100644 --- a/doc/slb.texi +++ b/doc/slb.texi @@ -76,6 +76,8 @@ documents SLB Version @value{VERSION}. * Tutorial:: * Invocation:: SLB Command Line Syntax. * Configuration:: SLB Configuration. +* Exit Codes:: SLB Exit Codes. +* Signals:: * Reporting Bugs:: How to Report a Bug. @@ -166,13 +168,102 @@ familiar with the package. @node Tutorial @chapter Tutorial -@WRITEME +@UNREVISED + +@menu +* Option Basics:: +* Configuration Basics:: +@end menu + +@node Option Basics +@section Option Basics +Options start with a dash. Most of them have two forms, called short and +long forms. Both forms are absolutely identical in function; they are +interchangeable. + +@cindex short options +@cindex options, short + The @dfn{short} form is a traditional form for UNIX utilities. +In this form, the option consists of a single dash, followed by a +single letter, e.g. @option{-c}. + + Short options which require arguments take their arguments +immediately following the option letter, optionally separated by white +space. For example, you might write @option{-o name}, or @option{-oname}. +Here, @option{-o} is the option, and @option{name} is its argument. + + Short options' letters may be clumped together, but you are not +required to do this. When short options are clumped as a set, use one +(single) dash for them all, e.g. @option{-ne} is equivalent to @option{-n +-e}. However, only options that do not take arguments may be +clustered this way. If an option takes an argument, it can only be +the last option in such a cluster, otherwise it would be impossible to +specify the argument for it. Anyway, it is much more readable to +specify such options separated. + +@cindex options, long +@cindex long options + The @dfn{long} options consist of two dashes, followed by a +multi-letter option name, which is usually selected to be a mnemonics +for the operation it requests. Long option names can be abbreviated, +provided that such an abbreviation is unique among the options +understood by the program. + + Arguments to long options follow the option name being separated +from it either by an equal sign, or by any amount of white space +characters. For example, the option @option{--eval} with the +argument @samp{test} can be written either as @option{--eval=test} or +as @option{--eval test}. + +@node Configuration Basics +@section Configuration Basics +The @dfn{configuration file} defines most parameters needed for the normal +operation of @command{slb}. The program will not start if its +configuration file does not exist, cannot be read, or contains some errors. + +@xopindex{config-file, introduced} +The configuration file is located in your system configuration +directory (normally @file{/etc}) and is named @file{slb.conf}. You +can place it elsewhere as well, but in this case you will need to +explicitly inform @command{slb} about its actual location, using the +@option{--config-file} (@option{-c}) command line option: + +@example +slb --config-file ./new.conf +@end example + + +For a detailed discussion of configuration format, see +@ref{Configuration}. + @node Invocation @chapter SLB Command Line Syntax -@UNREVISED + The format of @command{slb} invocation is: + +@example +slb @var{options} @var{args} +@end example + +@noindent +where @var{options} are command line options and @var{args} are +non-optional arguments. + +Non-optional arguments are allowed only if either @option{--test} +or @option{--eval} option is used in @var{options}. + +@menu +* program mode:: +* modifier options:: +* preprocessor control options:: +* logging control options:: +* debugging options:: +* informational options:: +@end menu + +@node program mode +@section Program Mode Options -@subheading Program Mode Options @table @option @opsummary{config-file} @item --config-file=@var{file} @@ -196,22 +287,48 @@ does not work in this mode. @sopindex{n, summary} @item --dry-run @itemx -n -Run in foreground mode and print on the standard output what would -have otherwise been printed on the output file. This option implies +Run in foreground mode and print to the standard output what would +have otherwise been printed to the output file. This option implies @option{--stderr --debug snmp.1 --debug output.1}. Use additional @option{--debug} options to get even more info. The @samp{pidfile} configuration statement is ignored in dry run mode (@pxref{pidfile}). +@opsummary{eval} +@item --eval=@var{name} +Evaluate the named expression @var{name}, print its result and exit. +Arguments for the expression can be supplied in the form of +assignments in the command line, e.g.: + +@example +slb --eval=loadavg la1=10 x=18 +@end example + +@FIXME-xref{eval}, for a detailed discussion of the expression evaluation +mode. + +@opsummary{test} +@sopindex{T, summary} +@item --test +Test mode. Instead of polling servers via SNMP, @command{slb} reads +data from the file given as the first non-option argument on the +command line (or from the standard input, if no arguments are given). +The output is directed to the standard output, unless the +@option{--output-file} option is also given. + +@FIXME-xref{test mode}, for a detailed information about the test +mode, including a description of the input format. + +Example usage: +@example +slb --test input.slb +@end example + @sopindex{E, summary} @item -E Show preprocessed configuration and exit. -@opsummary{foreground} -@item --foreground -Remain in the foreground. Useful for debugging purposes. - @opsummary{lint} @sopindex{t, summary} @item --lint @@ -220,7 +337,32 @@ Parse configuration file, report any errors on the standard error and exit with code 0, if the syntax is OK, and with code 1 otherwise. @end table -@subheading Logging Control Options +@node modifier options +@section Modifier Options + +@table @option +@opsummary{foreground} +@item --foreground +Remain in the foreground. Useful for debugging purposes. + +@opsummary{output-file} +@sopindex{o, summary} +@item --output-file=@var{file} +@itemx -o @var{file} +Direct output to @var{file}. This option overrides the +@samp{output-file} setting in the configuration file. +@xref{output-file}, for a discussion of @var{file} syntax. +@end table + +@ignore +@opindex efmt +@item --efmt=@var{format} +This option is deliberately left undocumented. This text is here +to pacify `make check-options'. +@end ignore + +@node logging control options +@section Logging Control Options @table @option @opsummary{stderr} @sopindex{e, summary} @@ -233,7 +375,8 @@ Log to the standard error. Log all diagnostics to syslog. @end table -@subheading Preprocessor Control Options +@node preprocessor control options +@section Preprocessor Control Options @table @option @opsummary{define} @item --define=@var{name}[=@var{value}] @@ -258,7 +401,8 @@ Disable preprocessor. @pxref{Preprocessor}. Use @var{command} instead of the default preprocessor. @pxref{Preprocessor}. @end table -@subheading Debugging Options +@node debugging options +@section Debugging Options @table @option @opsummary{debug} @sopindex{d, summary} @@ -306,7 +450,8 @@ Configuration file grammar. Configuration file lexer. @end table -@subheading Informational Options +@node informational options +@section Informational Options @table @option @opsummary{config-help} @item --config-help @@ -331,6 +476,61 @@ Print the program version and exit. @chapter SLB Configuration File @include config.texi +@node Exit Codes +@chapter Exit Codes +@cindex exit code +When SLB terminates, it reports the result of its invocation in form +of exit code. Exit code of 0 indicates normal termination. Non-zero +exit codes indicate some kind of error. In this case the exact cause +of failure will be reported on the currently selected logging channel. + +The exit codes are as follows: + +@table @asis +@item 0 (EX_OK) +Normal termination. + +@item 64 (EX_USAGE) +The program was invoked incorrectly. + +@item 65 EX_DATAERR +Input data were invalid or malformed. This error code is returned +only when @command{slb} is used with @option{--test} or +@option{--eval} options (@FIXME-pxref{}). + +@item 69 EX_UNAVAILABLE +Some error occurred. For example, the program was unable to open +output file, etc. + +@item 70 EX_SOFTWARE +Internal software error. This usually means hitting a bug in the +program, so please report it (@pxref{Reporting Bugs}). + +@item 98 EX_CONFIG +Program terminated due to errors in configuration file. +@end table + +@node Signals +@chapter Signals + +The program handles a set of signals. To send a signal to +@command{slb} use the following command: + +@example +kill -@var{signal} `cat /var/run/slb.pid` +@end example + +Replace @file{/var/run/slb.pid} with the actual pathname of the +PID-file, if it was set using the @samp{pidfile} configuration +statement. + +The @samp{SIGHUP} signal instructs the running instance of the program +to restart itself. It is possible only if @command{slb} was started using +its full pathname. + +The signals @samp{SIGTERM}, @samp{SIGQUIT}, and @samp{SIGINT} cause +immediate termination of the program. + @node Reporting Bugs @chapter How to Report a Bug |