CommandLine

Return to Home page

The Syslogd2 Command-Line

The Syslogd2 command-line can range from just a handful of options to well over 8K bytes in length based on the complexity and purpose of the configuration. Syslogd2 fully supports spaces in directory and file names so care must be taken to insure any spaces are not confused with parameter-delimiters by the system command-line parser.

Each Syslogd2 command-line option has one or more non-case-sensitive "long-form" names. Most also have a "short-form" consisting of a single (case-sensitive) letter. Because Syslogd2 uses its own parser, it can be forgiving when parsing values. Nevertheless, it is recommended that standard (quoting rule) syntax be utilized when using the actual command-line.

When values are on the actual command-line quotes should be used whenever whitespace is found in a parameter value (this includes between entries in comma-separated lists).

Value strings with no spaces or tabs can be quoted or not as desired.

When specifying commands using the long-form, two hyphens are required and the option keyword is separated from the value by an equal-sign by whitespace or both:

--enable = "dns, inet, forwarding, cache = no"

Short-form names use a single hyphen and (because the 'name' is a single letter) need no delimiter between the identifier and the value:

-ecache,dns,inet,forwarding,cache=no

Boolean Values

Boolean command-line values may default to on or off. Enabling a value that defaults to on has no effect nor does disabling a value that defaults to off. Use the --enable and --disable commands to set and clear boolean values.
Boolean values optionally accept a parameter of "yes/no" or "1/0" (one/zero) (non-case-sensitive) as in "--enable dns=no"

A value of 'y[es]' (or 'Y[es]' or 1) is the same as no value at all. (--disable <x>=y is the same as --disable <x>).
A value of 'n[o]' (or 'N[o]' or 0) (intuitively) reverses the command's intent ("--disable dns=n" is the same as "--enable dns" or "--enable=dns").

Values valid only on the command-line

Because Syslogd2 command-line can so easily exceed the length of the Linux command-line buffer, Syslogd2 allows most command-line options to be moved into the configuration file. There are some exceptions:
--configfile= (-c): This specifies the location of an alternate configuration file to use. The default is /etc/syslog.conf.
--help (--usage or -h or -?): This prints a command-summary to the screen and immediately exits (in the config-file, this would be counter-productive).
--version (-v): Prints version information and exits -- like --help, this would be counter-productive in the config-file.
--TestConfig= (-T): Prints configuration summary and exists. The parameter value is a comma-separated list of:

1. A snapshot point-in-time: (If omitted, "AsStaged" is assumed.)

AsParsed (p): After parsing and before building the working config.
AsBuilt (b): After building the working config and before de-conflicting entries to stage to the production data structures.
AsStaged (s):After staging deconflicted data to production and before initializing threadpool structures.

2. An output location:

stderr (err): Defined stderr file.
logfile (log, stdout, out): Defined stdout (log) file.
<NULL>: If omitted, output will go to the terminal screen.

3. A network state to emulate:

any: Only includes entries not marked for specific network states.
down: Configuration as it would look when the network is down.
local: Configuration as it would look when the network has only the loopback interface.
other: Configuration as it would look when the network is fully available (does not validate against interface addresses or attempt to open sockets). Includes any entries marked for network name "other".
<NULL>: If omitted, the display is based on the currently-detected network state.

4. Which configuration components to display: This is a bitmap that is most easily expressed as a hex value (0xNNN). If omitted or given as value 0 (zero), all components will be displayed.

Each section displayed contains a header-line giving the required hexadecimal flag bit (0x100) and corresponding decimal value (4) that selected that section.

Moving command-line options into the configuration file

Moving command-line options from the command-line to the configuration file is a straightforward process:

Command-line entries in the configuration file may not be on the same line as output entries.
Command-line entries are identified by a tilde ('~') as the 1st non-whitespace, non-comment-character in the line.
Command-line entries (and the tilde) may be preceded by a comment-character ('#') so other syslog parsers will see the line as a comment.
Command-line entries may be followed by an in-line comment following either one or two comment-characters (as long as the comment start after the 2nd one). The comment extends to end-of-line.
All command-line values are to be unquoted and spaces un-esacaped when moved to the configuration file. (The parser will know the end of each command-line option-string by the hyphen(s) at the start of the next command-line entry).

Note: quoting concurrent spaces in parameters on the command-line is required because the command-line parser does not keep or pass the number or value of whitespace characters).
This means that without quotes, a program has no way to know whether a command-line parameter has one or multiple spaces-or-tabs in the value.
After moving (and unquoting) command-line values into the config file, Syslogd2 can read the correct (and complete) string from the file content.

Differences between command-line and command-line-in-config-file

Other than the syntax difference of unquoting all command-line values and starting each line containing command-line options with a tilde, there are operational differences to be considered between the actual command-line and the command-line-in-config-file

Syslogd2 tracks and warns about duplicate entries in the configuration file. When conflicts (duplicates or conflicting IP ports / filesystem entries, etc) occur, Syslogd2 resolves them by keeping the lowest line-number entry. For this purpose, the actual command-line is considered to be line 0 (zero) of the file. All lines are parsed left-to-right, so the first duplicated entry in a given line will be used.

The second operational impact is that if CAP_RECONFIG is defined and enabled, the configuration file's last-modified date is tracked for purposes of determining changes. When changes occur, the configuration file is re-parsed and the newly-parsed configuration is made active. The actual command-line is exempt from this re-parsing as it is unchangeable once the program is up-and-running.

Command-line differences for different syslog daemons must be handled external to Syslogd2 and can get cumbersome to manipulate. Putting entries into the configuration file (where they can be documented with comments) is often more convenient. (There is also no limit to the length of the "command-line" when it is written as configuration lines in the configuration file)
Return to Home page