ConfigFile

Return to Home page

Syslogd2 Configuration File Abstract

Enhanced Output-Line Format

Moving Command-Line Options into the Configuration File

##Abstract Return to top

     For several practical reasons, the Syslogd2 configuration file is patterned on the traditional Linux/Unix syslog file format and rules. All Syslogd2 configuration enhancements were designed to be either additions to or to appear as comments to the legacy configuration-file syntax.

     One of the primary goals of Syslgod2's design was to adhere as closely as possible to traditional syslog file formats in order to minimize the "learning curve" of system administrators when converting to Syslogd2. Other than insuring that inactive output entries start with 2 comment-characters instead of just one, the configuration files need no change to be usable by Syslogd2.

     Syslogd2 auto-detects the configuration of IPv4 and IPv6 and will support either or both based on that detection. (Either can be manually disabled with "--disable IPv4" or "--disable IPv6"). When resolving IP hostnames, Syslogd2 will only use IP addresses in enabled IP address-families.

     All Syslogd2 options are activated/defined by means of option-lists added to the end of output-specifications or by means of addiitonal command-line options that can be moved into the configuration file. Syslogd2 default values should be adequate for typical operation even though Syslogd2-specific options are not specified.

There are 3 types of lines in a Syslogd2 configuration file:

Command-line options: This line-type is identified with a tilde ('~') as the first non-whitespace on the line. The tilde is followed by optional whitespace, then command-line parameters (complete with hyphens):
    ~ --stderr=/var/log/syslogd2.err,uid=0,gid=netstaff,mode=640,level=7 --enable inet, forward, dns, cache

Output-line: Syslogd2 identifies this line type by scanning the line until the first non-whitespace, non-comment token is found. If that token is a valid syslog facility name or the symbol "*" or the string "none" the line is assumed to be an output-line and an attempt is made to parse the suspected selector-string into a selector-mask. If the attempt is successful, the rest of the line is parsed as an output-line. If errors occur, they are logged to the error-file as if the line were actually an output-line.

To prevent unintentional errors, actual comments that start with facility names should be hard-comments (using 2 comment-characters instead of one).
Note: When implementing Syslogd2, any output line that is intended to be (or to remain) inactive should have a 2nd comment-character ('#') prepended to it to prevent Syslogd2 from interpreting the line as a soft-comment.

Comment: A Syslogd2 "soft-comment" is any string that follows a single comment-character. A Syslogd2 "hard-comment" is any string that follows a 2nd (possibly non-contiguous) comment-character in the same line.

A hard-comment is a comment to Syslogd2 as well as to other syslog daemons.
A soft-comment is a comment to other syslog daemons, but is normal text to Syslgod2. Soft-comments may be used to "hide" lines or parameter-strings from other daemons that may use the same deployed (standardized) configuration file.

A soft-comment is so-named because it is sometimes treated as a comment and sometimes not. When the first token in a line is a comment-character, the following token is examined. If this token is either a tilde or a facility-name, the original (soft-comment) indicator is noted and the remainder of the line is parsed by Syslgod2. Otherwise, the entire line is ignored as a comment by Syslogd2. The following examples illustrate this concept:

# ~ --enable inet # a hard-comment following a soft-comment command-line string
# extra0.* -/var/log/file1 # a hard-comment following a soft-comment Syslogd2-only output-line
local0.* *# ,id=2, filter=OutputFilter # Syslogd2 extension options to a valid output-line followed by an in-line hard-comment
# anything else is a soft-comment interpreted as a comment.
## a hard-comment

The down-side to this design is that traditional output lines (in existing configuration files) that are intentionally commented out will look like soft-comments to Syslogd2 and will become active unless the line is adjusted to a hard-comment.

# extra0.* -/var/log/file1 should be changed to ##extra0.* -/var/log/file1

On the positive side, however:

-- The soft-comment can be used to mass-deploy and mass-manage syslog configuration files for purposes of updates regardless of which syslog daemon is running on a given Linux or Unix platform.
-- Other than the distinction between hard- and soft- comments, there is no real difference between a legacy syslog configuration file and a Syslogd2 configuration file other than the additions made by Syslogd2.

I don't know how many (or which) syslog daemons support in-line comments, so caution should be used in utilizing in-line comments in mixed-usage files if the presence of an in-line comment might cause the non-Syslogd2 daemon(s) to crash.

Return to top ##Enhanced Output Line Format Return to top

Syslogd2 considers every output-line in the configuration file to consist of 3 distinct components: (1) a selector-string, (2) a localtion-specification and (3) a comma-separated list of options:

<output-line>::= <selector-string> + WS + <location-spec> + <comma-separated-option-list>

<selector-string>::= <selector>[;<selector>][;...]

<selector>::= <facilityName> + '.' + <priority-modifier> + <priorityName>

<facilityName>::= See table
<priority-modifier>::= Zero or more of:

'<'::= All priorities that are numerically less than
'='::= Only the specified priority
'>'::= All priorities that are numerically greater than
'!'::= logical inversion of bits ('!<' becomes '>=', '*' becomes 'none' & vice versa, etc).
'~'::= negate: clears selected bits instead of setting them. (the priority value 'none' is an alias for '~*').

Negate allows for strings like:

user.*;user.~=notice (all user priorities except the 'user.notice' priority)
*.*;user.none (all input except the 'user' facility) (Remember that 'none' is an alias for '.~*' ).

<priorityName>::= See table

<location-spec>::= [-] [<Location-type-symbol>] + <location>

The optional hyphen before the <location-type-symbol> is valid only for file-type outputs.
It suppresses flushing of data to disk after every write.

<location-type-symbol>::= zero or one of the following:

Omitted: The <location-type-symbol> is not specified when specifying locations consisting of terminal devices, files or logged-in users.

All filenames must be absolute pathnames. The leading '/' the location pathname identifies the location to be of type 'file':
    All location pathnames starting with "/dev/" (in the "/dev/" directory) are treated as terminal devices by Syslgod2.
    This includes the traditional devices "/dev/console" and "/dev/tty" as well as arbitrary terminal identifiers such as '/dev/pty/ptty01'.
The asterisk character ('*') identifies the special destination of "all logged-in users".
Any other character is assumed to indicate a list of users.

'|'::= <location> is the absolute file-system path to a named-pipe.
'@'::= Syslogd2 expands the definition of this symbol from "UDP/IP socket to a hostname or address" to simply "a socket connection".

<location>::= The location specifies an absolute filepath, an IP hostname, an IPv4 address or an IPv6 address.
     For socket-type locations, the <output-option-list> specifies the socket protocol (stream/TCP vs datagram/UDP) and the IP address-family (IPv4 vs IPv6) if not specified by the address format.
     For IP-socket-type locations, the <output-option-list> also specifies the remote IP port to connect to. If the IP port and protocol are omitted, the default syslog port (UDP/514) is assumed.
          An IP socket that specifies TCP protocol, but fails to specify a port is an error and will be ignored because there is no defined TCP port for the Syslog protocol.

Return to top ## Moving Command-Line Options into the Configuration File Return to top

Return to top Return to Home page