![[image of the Head of a GNU]](/graphics/gnu-head-sm.jpg)
|
|
SLB |
Simple Load Balancer |
Sergey Poznyakoff |
| SLB User Manual (split by chapter): |  |
 |
 |
 |
 |
 |
 |
? |
Upon startup, slb reads its settings from the
configuration file ‘slb.conf’. This file is normally located
in $sysconfidr (i.e., in most cases ‘/usr/local/etc’, or
‘/etc’), but an alternative location can be specified using the
‘--config’ command line option (see section config-file).
If any errors are encountered in the configuration file, the program reports them on its error output and exits with a non-zero status.
To test the configuration file without starting the server use the ‘--lint’ (‘-t’) command line option. It instructs the program to check configuration file for syntax errors and other inconsistencies and to exit with status 0 if no errors were detected, and with status 1 otherwise.
Before parsing, the configuration file is preprocessed using
m4 (see section Preprocessor). To see the preprocessed
configuration without actually parsing it, use the ‘-E’ command
line option. To disable preprocessing, use the
‘--no-preprocessor’ option.
The rest of this section describes the configuration file syntax in
detail. You can receive a concise summary of all configuration
directives any time by running slb --config-help.
The configuration file consists of statements and comments.
There are three classes of lexical tokens: keywords, values, and separators. Blanks, tabs, newlines and comments, collectively called white space are ignored except as they serve to separate tokens. Some white space is required to separate otherwise adjacent keywords and values.
Comments may appear anywhere where white space may appear in the configuration file. There are two kinds of comments: single-line and multi-line comments. Single-line comments start with ‘#’ or ‘//’ and continue to the end of the line:
# This is a comment // This too is a comment |
Multi-line or C-style comments start with the two characters ‘/*’ (slash, star) and continue until the first occurrence of ‘*/’ (star, slash).
Multi-line comments cannot be nested. However, single-line comments may well appear within multi-line ones.
Pragmatic comments are similar to usual single-line comments,
except that they cause some changes in the way the configuration is
parsed. Pragmatic comments begin with a ‘#’ sign and end with the
next physical newline character. The version 1.0 of slb,
understands the following pragmatic comments:
#include <file>#include fileInclude the contents of the file file. If file is an absolute file name, both forms are equivalent. Otherwise, the form with angle brackets searches for the file in the include search path, while the second one looks for it in the current working directory first, and, if not found there, in the include search path.
The default include search path is:
where prefix is the installation prefix.
New directories can be appended in front of it using ‘-I’ (‘--include-directory’) command line option (see section include-directory).
#include_once <file>#include_once file Same as #include, except that, if the file has already
been included, it will not be included again.
#line num#line num "file" This line causes slb to believe, for purposes of error
diagnostics, that the line number of the next source line is given by
num and the current input file is named by file.
If the latter is absent, the remembered file name does not change.
# num "file" This is a special form of #line statement, understood for
compatibility with the C preprocessor.
In fact, these statements provide a rudimentary preprocessing features. For more sophisticated ways to modify configuration before parsing, see Preprocessor.
A simple statement consists of a keyword and value separated by any amount of whitespace. Simple statement is terminated with a semicolon (‘;’).
The following is a simple statement:
standalone yes; pidfile /var/run/slb.pid; |
A keyword begins with a letter and may contain letters, decimal digits, underscores (‘_’) and dashes (‘-’). Examples of keywords are: ‘expression’, ‘output-file’.
A value can be one of the following:
A number is a sequence of decimal digits.
A boolean value is one of the following: ‘yes’, ‘true’, ‘t’ or ‘1’, meaning true, and ‘no’, ‘false’, ‘nil’, ‘0’ meaning false.
An unquoted string may contain letters, digits, and any of the following characters: ‘_’, ‘-’, ‘.’, ‘/’, ‘@’, ‘*’, ‘:’.
A quoted string is any sequence of characters enclosed in double-quotes (‘"’). A backslash appearing within a quoted string introduces an escape sequence, which is replaced with a single character according to the following rules:
| Sequence | Replaced with |
| \a | Audible bell character (ASCII 7) |
| \b | Backspace character (ASCII 8) |
| \f | Form-feed character (ASCII 12) |
| \n | Newline character (ASCII 10) |
| \r | Carriage return character (ASCII 13) |
| \t | Horizontal tabulation character (ASCII 9) |
| \v | Vertical tabulation character (ASCII 11) |
| \\ | A single backslash (‘\’) |
| \" | A double-quote. |
Table 5.1: Backslash escapes
In addition, the sequence ‘\newline’ is removed from the string. This allows to split long strings over several physical lines, e.g.:
"a long string may be\ split over several lines" |
If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued.
Two or more adjacent quoted strings are concatenated, which gives another way to split long strings over several lines to improve readability. The following fragment produces the same result as the example above:
"a long string may be" " split over several lines" |
A here-document is a special construct that allows to introduce strings of text containing embedded newlines.
The <<word construct instructs the parser to read all
the following lines up to the line containing only word, with
possible trailing blanks. Any lines thus read are concatenated
together into a single string. For example:
<<EOT A multiline string EOT |
The body of a here-document is interpreted the same way as a double-quoted string, unless word is preceded by a backslash (e.g. ‘<<\EOT’) or enclosed in double-quotes, in which case the text is read as is, without interpretation of escape sequences.
If word is prefixed with - (a dash), then all leading
tab characters are stripped from input lines and the line containing
word. Furthermore, if - is followed by a single space,
all leading whitespace is stripped from them. This allows to indent
here-documents in a natural fashion. For example:
<<- TEXT
The leading whitespace will be
ignored when reading these lines.
TEXT
|
It is important that the terminating delimiter be the only token on its line. The only exception to this rule is allowed if a here-document appears as the last element of a statement. In this case a semicolon can be placed on the same line with its terminating delimiter, as in:
help-text <<-EOT
A sample help text.
EOT;
|
A block statement introduces a logical group of statements. It consists of a keyword, followed by an optional value, and a sequence of statements enclosed in curly braces, as shown in the example below:
server srv1 {
host 10.0.0.1;
community "foo";
}
|
The closing curly brace may be followed by a semicolon, although this is not required.
Before actual parsing, the configuration file is preprocessed.
The built-in preprocessor handles only file inclusion
and #line statements (see section Pragmatic Comments), while the
rest of traditional preprocessing facilities, such as macro expansion,
is supported via m4, which serves as external preprocessor.
The detailed description of m4 facilities lies far beyond
the scope of this document. You will find a complete user manual in
http://www.gnu.org/software/m4/manual.
For the rest of this subsection we assume the reader is sufficiently
acquainted with m4 macro processor.
The external preprocessor is invoked with ‘-s’ flag, which instructs it to include line synchronization information in its output. This information is then used by the parser to display meaningful diagnostic.
An initial set of macro definitions is supplied by the ‘pp-setup’ file, located in ‘$prefix/share/slb/version/include’ directory (where version means the version of SLB).
The default ‘pp-setup’ file renames all m4 built-in
macro names so they all start with the prefix ‘m4_’. This
is similar to GNU m4 ‘--prefix-builtin’ options, but has an
advantage that it works with non-GNU m4 implementations as
well.
Additional control over the preprocessor is provided via the following command line options:
Define the preprocessor symbol name as having value, or empty.
Add dir to the list of directories searched for preprocessor include files.
Disable preprocessor.
Use command instead of the default preprocessor.
When running in standalone mode slb normally uses
syslog to print diagnostic messages. By default, the program uses the
‘daemon’ facility. The syslog statement allows to change that:
syslog {
facility local1;
tag slb;
print-priority yes;
}
|
Configures the syslog facility to use. Allowed values are: ‘auth’, ‘authpriv’, ‘cron’, ‘daemon’, ‘ftp’, ‘local0’ through ‘local7’, and ‘mail’.
This statement sets the syslog tag, a string identifying each message issued by the program. By default, it is the name of the program with the directory parts removed.
In addition to priority segregation, provided by syslog,
you can instruct slb to prefix each syslog message with
its priority. To do so, set:
print-priority yes; |
The following statements configure slb activities in
daemon mode.
Enables or disables standalone daemon mode. The standalone mode is enabled by default. It is disabled either by setting
standalone no; |
in the configuration file, or by using the ‘--cron’ command line option (see option–cron).
Do not detach from the controlling terminal. See option–foreground.
Store master process PID in file. Default pidfile location is ‘/var/run/slb.pid’.
Sets wake-up interval in seconds. SLB will recompute the server load table each number seconds.
Suppress output during the first number wakeups. This statement is reserved mostly for debugging purposes.
The following statement creates a named expression:
Define the expression name to be expr.
Named expressions can be used as load estimation functions in
server statements (see section expression) and invoked from
the output format string (see section Output Format String).
Declares the default expression. The name refers to a named expression declared elsewhere in the configuration file.
The default expression is used to compute relative load of servers whose ‘server’ declaration lacks explicit ‘expression’ definition (see server-expression).
The expr in the ‘expression’ statement is an arithmetical expression, which evaluates to a floating point number. The expression consists of terms, function calls and operators. The terms are floating point numbers, variable and constant names. The names refer to constants or SNMP variables defined in the definition of the server, for which this expression is being evaluated.
The following operations are allowed in expression:
Addition
Subtraction
Multiplication
Division
Power
A named expression reference is a reference to an expression defined by a ‘expression’ statement elsewhere in the configuration file. The reference has the following syntax:
@name |
where name is the name of the expression as given by the first argument of its definition (see section Expression).
The ternary conditional operator is used to select a value based on a condition. It has the following form:
cond ? expr1 : expr2 |
The ternary operator evaluates to expr1 if cond yields ‘true’ (i.e. returns a non-null value) and to expr2 otherwise.
The condition cond is an expression which, apart from the arithmetic operators above, can use the following comparison and logical operations:
True if a equals b
True if the operands are not equal.
True if a is less than b.
True if a is less than or equal to b.
True if a is greater than b.
True if a is greater than or equal to b.
True if expr is false.
Logical and: true if both a and b are true, false otherwise.
Logical or: true if at least one of a or b are true.
Both logical ‘and’ and ‘or’ implement boolean shortcut evaluation: their second argument (b) is evaluated only when the first one is not sufficient to compute the result.
The following table lists all operators in order of decreasing precedence:
| Operators | Description |
|---|---|
| (...) | Grouping |
| ? | Ternary operator |
| ** | Power (right-associative) |
| - | Unary negation |
| * / | Multiplication, division |
| + - | Addition, subtraction |
| < <= >= > | Relational operators (non-associative) |
| == != | Equality comparison (non-associative) |
| ! | Boolean negation |
| && | Logical ‘and’. |
| || | Logical ‘or’ |
When operators of equal precedence are used together they are evaluated from left to right (i.e., they are left-associative), except for comparison operators, which are non-associative and for the power operator, which is right-associative (these are explicitly marked as such in the above table). This means, for example that you cannot write:
(5 <= x <= 10) ? x : y |
Instead, you should write:
(5 <= x && x <= 10) ? x : y |
Function calls have the following syntax:
name(arglist) |
where name stands for the function name and arglist denotes the argument list: a comma-separated list of expressions which are evaluated and supply actual arguments for the function.
The following functions are supported by SLB version 1.0:
Returns the derivative of x, i.e. the speed of its change per
second, measured between the two last wakeups of slb
(see section wakeup).
Notice, that this function is available only in standalone mode (see section standalone mode).
Returns the maximum value of its arguments. Any number of arguments can be given.
Returns the minimum value of its arguments.
Returns the average value of its arguments.
Returns the natural logarithm of x.
Returns the decimal logarithm of x.
Returns the value of e (the base of natural logarithms) raised to the power of x.
Returns the value of x raised to the power of y. This function is provided for the sake of completeness, as it is entirely equivalent to ‘x ** y’.
Returns the non-negative square root of x.
Returns the absolute value of x.
Returns the smallest integral value that is not less than x.
ceil(0.5) ⇒ 1.0 ceil(-0.5) ⇒ 0 |
Returns the largest integral value that is not greater than x.
floor(0.5) ⇒ 0.0 floor(-0.5) ⇒ -1.0 |
Rounds x to the nearest integer not larger in absolute value.
Rounds x to the nearest integer, but round halfway cases away from zero:
round(0.5) ⇒ 1.0 round(-0.5) ⇒ -1.0 |
Adds dir to the list of directories searched for the MIB definition files.
Reads MIB definitions from file.
server id {
enable bool;
host string;
timeout number;
retries number;
community string;
expression expr;
variable name oid;
constant name value;
macro name expansion;
assert oid op pattern;
}
|
Creates a new entry in the database of monitored servers. The id parameter supplies the server identifier, an arbitrary string which will be used in log messages related to that server. Its value is also available in output format string as format specifier ‘%i’ (see section Output Format String).
Other parameters of the server are defined in the substatements, as described below.
If bool is ‘no’, this server is disabled, i.e. it is not polled nor taken account of in load calculations. Use this statement if you want to temporarily disable a server.
Sets the IP address (or hostname) of this server.
Sets the timeout for SNMP requests to that server.
Sets the maximum number of retries for that server, after which a timeout is reported.
Sets SNMP community.
Defines load estimation function for this server. See section Expression, for a description of the syntax of string. If this statement is absent, the default expression will be used (see default-expression). If it is not declared as well, an error is reported.
Defines a variable name to have the value returned by oid. The latter must return a numeric value.
Any occurrence of name in the expression (as defined in the ‘expression’ statement) is replaced with this value.
Defines a constant name to have the value returned by oid.
Notice that expression variables and constants share the same namespace, therefore it is an error to have both a ‘variable’ and a ‘constant’ statement defining the same name.
Defines a macro name to expand to expansion. Macros allow to customize output formats on a per-server basis. See macro.
Ensures that the value of SNMP variable oid matches pattern. The type of match is given by the op argument:
The value must match pattern exactly.
The value must not match pattern.
If the assertion fails, the server is excluded from the load table.
Use this statement to ensure that a variable used in the computation refers to a correct entity. For example, if your expression refers to ‘IF-MIB::ifInOctets.3’ (number of input octets on network interface 3), it would be wise to ensure that the 3rd row refers to the interface in question (say ‘eth1’):
assert "IF-MIB::ifDescr.3" eq "STRING: eth1"; |
Notice, that pattern must include the data type.
The statement discussed in this section configure formatting of the server load table on output.
Print at most number entries from the top of the table, i.e. the number of the less loaded server entries.
Print at most number entries from the bottom of the table, i.e. the number of the most loaded server entries.
Send output to the channel, identified by string. Unless string starts with a pipe sign, it is taken as a literal name of the file. If this file does not exist, it is created. If it exists, it is truncated. The file name can refer to a regular file, symbolic link or named pipe.
If string starts with a ‘|’ (pipe), the rest of the string
is taken as the name of an external program and its command line
arguments. The program is started before slb enters its
main loop and the formatted load table is piped on its standard input.
Defines the text to be output before the actual load table contents. The string is taken literally. For example, if you want it to appear on a line by itself, put ‘\n’ at the end of it (see backslash-interpretation).
Defines the text to be output after the actual load table contents. The string is taken literally.
Defines format for outputting load table entries. See the subsection below (see section Output Format String), for a description of available format specifications.
The format string is composed of zero or more directives: ordinary characters (not ‘%’), which are copied unchanged to the output; and conversion specifications, each of which is replaced with the result of a corresponding conversion. Each conversion specification is introduced by the character ‘%’, and ends with a conversion specifier. In between there may be (in this order) zero or more flags, an optional minimum field width and an optional precision.
The value should be zero padded. This affects all floating-point conversions, i.e. ‘w’ and ‘{...}’, for which the resulting value is padded on the left with zeros rather than blanks. If the ‘0’ and ‘-’ flags both appear, the ‘0’ flag is ignored. If a precision is given with a floating-point conversion, the ‘0’ flag is ignored. For other conversions, the behavior is undefined.
The converted value is to be left adjusted on the field boundary. (The default is right justification.) Normally, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A ‘-’ overrides a ‘0’ if both are given.
A blank should be left before a positive number (or empty string) produced by conversion.
An optional decimal digit string (with non-zero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the ‘-’ flag has been given).
In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.
An optional precision, in the form of a period (‘.’) followed by an optional decimal digit string. If the precision is given as just ‘.’, or the precision is negative, the precision is taken to be zero. This gives the number of digits to appear after the radix character for floating-point conversions or the maximum number of characters to be printed from a string, for string conversions.
A character or a sequence of characters that specifies the type of conversion to be applied. The conversion specifiers are replaced in the resulting output string as described in the table below:
The server identifier.
The server hostname, as set by the host configuration
directive.
Computed relative load.
The value of the variable var.
The result of evaluating expression expr-name in the context of the current server.
Expansion of the macro.
The percent character.
|
|
 |
|
|
? |
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.