Syslogd2 Wiki
High capacity syslog data collection, filtering, and management.
Brought to you by:
efreesmeyer
Menu
▾
▴
FacPri Reference
Contents:
Input ConnectionSpec Syntax
Return to top
There is no syntax to follow in traditional syslog processing for specifying input other than from default sources. Syslogd2 follows what little tradition exists through application of the default connection ports and the traditional defaults for IP (IP and IP forwarding disabled) and for enabllng IP support (-r). The rest of the syntax (for defining Linux sockets, tailfiles, and non-default IP sockets) must be created.
Syslogd2 has 3 command-line options for specifying input sources. Collectively, these threadpool-types are referred to as "Reader Threadpools". The command-line options are --input (for IP & Linux Sockets), --tailfile (for text-file sources) and --kernel (for kernel input). Socket (input) threadpools are a core component of Syslogd2.
The --input and --tailfile threadpool types share a series of non-negative identfiers. Because of the conflict with default threadpool 0, the --tailfile default threadpool is internally moved from a numeric value of zero to a numeric value of -2. Other than the default threadpools, threadpool-ids for --input and --tailfile may be EITHER designated for socket input or tailfile input but not both. This is a result of the two thraadpool types executing different algorithms for different source-input types.
if the CAP_WORKERTHREADS symbol is defined at compile-time, "worker threadpools" become available. Worker threadpools use a separate (dedicated) series of non-negative identifiers with zero as the designated default threadpool-id.
if the CAP_OUTPUTTHREADS symbol is defined at compile-time, "output threadpools" become available. Output threadpools use a separate (dedicated) series of non-negative identifiers with zero as the designated default threadpool-id.
The User Threadpool (if defined) is a unique output-type threadpool with a fixed (default) threadpool-id value of 0.
The Kernel Threadpool (if defined) is unique reader-type threadpool with a fixed (default) threadpool-id value of 0.
<Input-ConnectionSpec> ::= <command-line keyword>=<PrimarySource> [, <comma-separated option-list>]
<command-line keyword> ::= one of (or an alias for): (--input, --tailfile or --kernel
<PrimarySource> ::= The primary value for the applicable keyword is in column 2 of the Command-Line Option Table.
<option-list> ::= a mix of keyword-specific options and common input options
Examples: (all examples are assumed to be located in the config file due to length and complexity)
~ --input=/tmp/syslogInput.socket, stream, id=1, filter=AppInputFilter, facility=extra8, noheader, hostname=App.myhost.mydomain.com
~ --input = fec0::8:123:84, tcp, port=1023, id=0 ## spaces are ignored around equal-signs
~ --input 10.2.13.4 ## uses default values of UDP, port=514, and threadpool 0 ## '=' and ' ' are usually interchangeable after keywords.
~ --tailfile /var/log/mysql/logs/mysql.err, hostname=mysql.myhost.mydomain.com, priority=extra6.err, filter=mysqlFilter ## mysql error log as input
~ --kernel id=1, filter=kernelFilter, ## '=' sign after cmd-line option is usually extraneous. Initial comma in option-list is extraneous when primary parameter is not used.
Output Line Syntax
Return to top
Traditional output-line syntax (assuming in-line comments are supported by the parser):
<output-line>::= <selector-string> <destination> [#In-LIne Comment]
<output-line>::= <selector-string> <destination-spec (without-comment-character)> [##In-Line Comment]
<output-line>::= <selector-string> <destination-spec (with-comment-character)> [#In-Line Comment]
<output-line>::= #<selector-string> <destination-spec (without-comment-character)> [#In-Line Comment]
<selector>::= <selector-string> ... [<selector-option-list>]
<selector-option-list>::= [<selector-option>] [,<selector-option>] [,...] (To be combined with <destionation-options> after <destination-spec>)
<selector-option>::= (See reference table).
<selector-string>::= <selector-element> [;<selector-element>] [;...]
<selector-element>::= <facility-element> + '.' + <priority-element> [;<facility-element> + '.' + <priority-element>] [;...]
<facility-element>::= <facilityName> [,<facilityName>] [,...]
<facilityName>::= See table
<priority-element>::= [<priority-modifier-string>] <priorityName>
<priority-modifier-string>::= Zero or more of (in any order):
<none>::= Default is "Numerically less than or equal to" ('.<=' or simply '.').
'<'::= "Numerically less than"
'='::= "Numerically equal to" only
'>'::= "Numerically greater than"
'!'::= "Logical not". ('.!=warn' is intuitive, '.!>warn' is same as '.<=warn' is same as just '.warn')
'~'(tilde)::= "Negate" -- Clear selected priority-selection bits instead of setting them.
<priorityName>::= See table.
Selector-string notes:
(1): Selector strings are terminated at the first white-space character or at end-of-line.
(1): Some priority modifiers may appear redundant, but have value when building CAP_FILTERS* selector-strings.
(2): <Priority-modifier> values of "!*" and "!none" produce no-op <selector-elements> meaning "Set no bits" and "clear no bits" respectively.
(3): The <priority-element> 'none' is an alias for the <priority-element> '~*'. A <priority-element> of '~none' evaluates to '*'.
<destination-spec> ::= [-] <destination-type-symbol><destination-location> [#] [,<option-list>] '-'::= For file-types only, prevents flushing data to disk after each write". Flushing files to disk after each write is safer, but can cause performance issues. <destination-symbol> ::= one of: '@'::= IP or Linux socket (Selection of UDP/TCP (for IP) or streaming/datagram (for Linux sockets) is made via destination options). '|'::= pipe <none>::= <user-list>, <all logged-in users>, <character-device>, <pipe>, <Linux-socket-path> or <file-path> <destination-location> ::= one of the following as appropriate for the <destination-symbol>: <user-list>::= A comma-separated list of users. '*'::= All logged-in users. <Pipe, file or Linux socket>::= An absolute file-path to (and including) the designated filesystem entry. </dev/...>::= User-specified terminal, console or tty output. /dev/console::= Special case of the above. The special device(s) designated as consoles on the kernel command-line. /dev/tty::= Special case of the above. The special device that spawned the 'init' process. (Usually the system console.) <IP Socket>:: =hostname or IP address. <option-list>::= A comma-separated list of <output-line> options. Contains both <selector> and <destination> options.
Destination Notes:
(1): The maximum length of a Linux socket path is system-limited to 104 char.
(2): Syslogd2 treats all <destination-location> pathnames in the */dev* filesystem as terminal devices.
Facility / Priority Table
| Numeric Val | Facility Names | Priority Names |
|---|---|---|
| <wildcard> | * (Selects All facilities) | * (Selects All priorities) |
| <wildcard> | 'none' (A "No-Op" entry) | 'none' (Clears all priorities for associated facility. Alias for "negate all" (.~*). |
| 0 | kern | emerg / panic |
| 1 | user | alert |
| 2 | crit | |
| 3 | daemon | err / error |
| 4 | auth / security | warn / warning |
| 5 | syslog | notice |
| 6 | lpr | info |
| 7 | news | debug |
| 8 | uucp | |
| 9 | cron | |
| 10 | authpriv | |
| 11 | ftp | |
| 12 - 15 | reserved0 - reserved3 (<-- Actual, usable Syslogd2 facility-name extensions) | |
| 16 - 23 | local0 - local7 | |
| 24 - 1023 | extra0 - extra999 (Default range is extra0 - extra15 if not otherwise specified at compile-time) | |
Command-Line Options
Return to top
All option names and keywords are non-case-sensitive except short-form (single-letter) option aliases.
Values that require a CAP_* declaration are shown in red.
Blue text on white background indicates options that cannot be moved into the configuration file.
| Option [aliases] | Primary Parameter | Basic Sub-Option(s) | Comments / Notes |
|---|---|---|---|
| --configfile (-c) |
Absolute pathname to alternate configuration file | No sub-options apply | The default configuration file is /etc/syslog.conf. Valid on actual command-line only. |
| --help (--usage) (-?) (-h) |
No parameters are required | No sub-options apply | Valid on actual command-line only. (Exits after printing help page) |
| --version (-v) |
This option takes no parameters. | No sub-options apply | Prints version, the number of "extra" facilities and the status of all CAP_* values before exiting. |
| --TestConfig (-T) |
Optional, comma-separated list of values | No sub-options apply | Example call: -T "s,0x107,other," or -T |
| --Network (-N) |
Semi-colon-separated list of network-state keywords | No sub-options apply | The --Network keyword is the only command-line option that MUST be placed in the configuration file |
| --Input (--Socket) (-i) See also Common Input-ConnectionSpec Options. |
IP Hostname IPv4-Address IPv6-Address |
UDP (U)
- or - TCP (T) -- (TCP requires CAP_STREAMIN)
Default: UDP
port = <IP-port name-or-numeric-value> Defaults: UDP: 514 ("syslog") , TCP:<none>
version (ver)= (4 | 6 | 46) Default: 46 |
Declares an IP input socket Version selects allowed address families for IP-hostnames. It is ignored for IP-Addresses. ToggleCache and ToggleDNS reverse the respective global settings for this IP socket. Keyword TCP is an alias for Stream. UDP is an alias for Datagram |
|
--Input (--Socket) (-i) See also Common Input-ConnectionSpec Options. |
Absolute Linux socket path |
Datagram: (d)
- or - Stream (s) -- (Stream requires CAP_STREAMIN)
Default: Datagram Linux Socket Options:
uid: Set owner of socket's filesystem entry |
Declares a Linux input socket Keyword TCP is an alias for Stream. UDP is an alias for Datagram |
|
--TailFile (--inputTailFile) (--tail) (-t) See also Common Input-ConnectionSpec Options. |
Absolute filename of input source. (Spaces are allowed either in directories or filename) |
poll: Force "polling mode" for this file. pollInterval (pollTime)-<seconds to wait after a no-data read before checking again> append: Start reading at end-of-file instead of beginning of file. hostname= <hostname-field-contents> for data from this source. |
Declares a text (ASCII) file to be an input source Once implemented, the default file-monitoring mode will be via the Linux inotify facility that will provide more responsive notifications of file-updates. 'Poll' will then have a purpose. Until then, all tailfile operation is via polling. |
|
--kernel (-k) See also Common Input-ConnectionSpec Options. |
No primary value | procfs (pfs): Use the /proc filesystem instead of system-call to read kernel data. Default: procfs | Selects kernel-input read-method. When CAP_KERNELTHREADS is declared and enabled, the default method is to use system-calls to directly read the kernel syslog-buffer. The system-call method does not require /proc to be mounted. If CAP_KERNELTHREADS is not declared or not enabled, this option has no effect. Example call: --kernel=procfs=no |
| --stderr (-E) |
Absolute pathname to user-defined error file | Comma-separated list of:
uid= Set owner of socket's filesystem entry (numeric or string value) |
Spaces are allowed in the directory path or in the file name. Not defining an error file disables logging of errors. Setting level < 0 also disables error logging. Place on actual command-line or at top of file to maximize amount of logging recorded. --stderr and --stdout are the only directives processed as soon as they are parsed. |
| --stdout (-O) |
Absolute pathname to user-defined output (log) file. | Comma-separated list of:
uid= Set owner of socket's filesystem entry (numeric or string value) |
Spaces are allowed in the directory path or in the file name. Not defining an output (log) file prevents run-time logging of buffer overflows (level==7) and use of "output" option for --testconfig.. Place on actual command-line or at top of file to maximize amount of logging recorded. --stderr and --stdout are the only directives processed as soon as they are parsed. |
| --cachefile (--cache) |
Filename relative to ConfigDir or absolute filepath to cache-file | No sub-options Apply | The CAP_CACHE CAP_*-ability must be defined for this option to be valid. |
| --CheckNetConfig= (--CNConfig) (-C) |
<N/A> | No sub-options apply | This option is not currently used. It is a placeholder for a future upgrade. |
| --defaults (-d) |
No primary value | A comma-separated list of <name>=<value> pairs. | This command-line option is the primary option for setting global run-time values and for over-riding compiled-in values. |
| --enable (-e) --disable (--suppress) (--no) (-n) |
No primary value | Comma-separated list of <name>[=<value>]. Optional values are:
'y', 'yes', 1 ==> TRUE |
Enable or Disable global boolean run-time values. |
| --threadmaps (--threads) (--maps) (-m) |
No primary value | Semi-colon-separated list of thread-pool resource parameters | Multiple instances of the --ThreadMaps option may exist (either on the command-line, in the configuration file or a mix of both). |
| --localhosts (-l [ell]) |
No primary value | Semi-colon-separated list of Fully-Qualified-Domain-Names (FQDNs) to be logged as host-name only when logging to local files. | Does not apply to traffic sent to other than local files |
| --stripdomains (-s) |
No primary value | Semi-colon-separated list of sub-domains to be stripped before logging to local files. | This option removes all or some of the (sub-)domain-namecomponents of FQDN names when logging to local files. Sub-domains are matched from right to left. Does not apply to traffic sent to other than local files |
| --remote (-r) |
No primary value | No sub-options apply | This macro is a backwards-compatibility alias for "--enable inet, forwarding". |
| --IncludeConfig | Optional <absolute-directory-name> or <absolute-filename> | No sub-options apply | If no parameter, assumes currently-parsed value of ConfigDir. Parses <absolute-filename> or *.conf in specified directory. |
Thread-Map Parameters
Return to top
Return to ThreadMaps Option-Table Entry
A "Thread-Maps Parameter list" is composed of the information required to configure a single thread-pool. This information is summarized in the table below for each threadpool type. The parameters in each parameter list are separated by commas. Multiple parameter-lists are separated by semi-colons. A type keyword is required for every threadpool definition.
Any other parameters that are omitted will default to the compiled-in or --defaults settings.
Thread-pool types supported by the --ThreadMaps command-line option in Syslogd2 are: Socket Input,
TailFile, Kernel, Worker, Output, HouseKeeping, User
All Keywords in the table below are non-case-sensitive and may be provided in any order.
| ThreadPool Type: (Type keywords) |
Pre-Requisites | Valid Parameters | Comments |
|---|---|---|---|
| Socket Input Thread-Pools: (input) (in) |
CAP_WORKERTHREADS for QueueId. |
ThreadPoolId (id, i)=<Non-Negative Integer> (Default: 0) Readers (r)= <Positive Integer> Queueid (queue, q)=<Non-Negative Integer> (Default: 0) |
Example: "id=1, readers=3, in" If CAP_WORKERTHREADS is defined, QueueId identifies the worker-threadpool to queue data to: "id=0, Input, r=3, q=1" |
| Tailfile Thread-Pools: (tailfile) (tail) |
CAP_TAILFILES |
ThreadPoolId (id, i)=<Non-Negative Integer> (Default: 0) Readers (r)= <Positive Integer> Queueid (queue, q)=<Non-Negative Integer> (Default: 0) |
Example: "ID=0, readers=3, TailFile" If CAP_WORKERTHREADS is defined, QueueId identifies the worker-threadpool to queue data to: "tail, id=1, r=3, q=1" |
| Kernel Thread-Pool: (kernel) |
CAP_TAILFILES or CAP_KERNELTHREADS |
Readers (r)= <Positive Integer> Queueid (queue, q)=<Non-Negative Integer> (Default: 0) |
There is never more than one kernel threadpool, so the id parameter does not apply Until the CAP_KERNELTHREADS code is implemented define kernel input via CAP_TAILFILES. Example: "readers=3, Kernel, queue=0" If CAP_WORKERTHREADS is defined, QueueId identifies the worker-threadpool to queue data to: "Kernel, r=3, q=0" |
| Worker Thread-Pool: (worker) (work) |
CAP_WORKERTHREADS |
ThreadPoolId (id, i)=<Non-Negative Integer> (Default: 0) Workers (w)= <Positive Integer> Lines (l [ell])= <Positive Integer> |
Example: "worker, id=0, workers=8, lines=1000" "work, id=1, w=20, l=5000" |
| Output Thread-Pool: (output) (out) |
CAP_OUTPUTTHREADS |
ThreadPoolId (id, i)=<Non-Negative Integer> (Default: 0) Workers (w)= <Positive Integer> Lines (l [ell])= <Positive Integer> |
Example: "output, id=0, workers=8, lines=600" "id=1, w=4, l=50, out" |
| User Thread-Pool: (user) |
CAP_USERTHREADS |
Workers (w)= <Positive Integer> Lines (l [ell])= <Positive Integer> |
There is never more than one user threadpool, so the id parameter does not apply Example: "user, workers=2, lines=10" "w=3, user" |
| HouseKeeping Thread-Pool: (housekeeping) (house) |
CAP_HOUSEKEEPING |
Workers (w)= <Positive Integer> |
There is never more than one housekeeping threadpool, so the id parameter does not apply The housekeeping threadpool does not utilize a FIFO queue, so the lines parameter does not apply Example: "housekeeping, workers=4" "house, w=3" |
Return to ThreadMaps Option-Table Entry
Return to top
Global Boolean Variables
Return to top
Return to --Enable / --Disable Command-Line-Option-Table Entry
| Keywords | Scope, Default and Pre-Requisites | Comments |
|---|---|---|
|
AllMessages EveryMsg AllMsgs a |
Scope: Global Default: Disabled |
When logging to files, the default action is to count duplicate messages and report "Message repeated <n> times..." when logging to local files. This option causes each individual message to be logged. Applies to local files only. Output to sockets, pipes and users internally enables this setting. |
| ApplicationMode A |
Scope: Global Default: Disabled |
A macro-shortcut for "--enable inet, forwarding, AllMessages, Syslog=no, KernelLogging=no, UserLogging=no, Console=no" |
| NameCache cachefile cache C |
Scope: Global Default: Disabled Requires CAP_CACHE |
When enabled allows use of the internal name-cache to resolve incoming-event Source-IP addresses to IP-hostnames. |
| DNS d |
Scope: Global Default: Disabled |
When enabled, allows use of DNS to resolve incoming-event Source-IP addresses to IP-hostnames. |
| Inet Internet IP i |
Scope: Global Default: Disabled |
Enables IP support for input and output of message traffic |
| Forwarding forward f |
Scope: Global Default: Disabled |
Enables forwarding of messages received from remote IP sources to IP destinations. |
| ForcePrintable printable p |
Scope: Global Default: Disabled |
Converts any non-printable character in messages to either control-char format (^C) or octal (\0772) format. |
| AltQueues q |
Scope: Global Default Disabled Requires any of: CAP_WORKERTHREADS, CAP_OUTPUTTHREADS or CAP_USERTHREADS |
Selects alternate action if any FIFO queue that becomes full. Default is to discard current message in order to process newer incoming data. Alternate action is to wait for space in the queue to become available with a risk of losing newer incoming data. |
| HouseKeeping h |
Scope: Global Default: Disabled Requires CAP_HOUSEKEEPING |
Enables run-time use of housekeeping threads. |
| IPv4 4 |
Scope: Global Default: Enabled |
Provides facility to administratively disable support for IPv4 even if an IPv4 address is detected on an IP interface. |
| IPv6 6 |
Scope: Global Default: Enabled |
Provides facility to administratively disable support for IPv6 even if an IPv6 address is detected on an IP interface. |
| Console c |
Scope: Global Default: Enabled |
Allows output to the console device to be administratively disabled -- even if configured and otherwise accessible. |
| KernelLog KernelLogging Klog k |
Scope: Global Default: Enabled |
Administratively enables or disables all kernel-message logging -- even if otherwise configured to do so. |
| KernelThreads | Scope: Global Default: Enabled |
Enable or disable the use of the specialized kernel-reader-threads if CAP_KERNELTHREADS is declared. |
| Syslog s |
Scope: Global Default: Enabled |
Creates and enables the Linux default log socket at _PATH_LOG (/dev/log for Linux -- may vary on other systems). Creates and enables a default UDP/IP input socket on syslog port 514 for all interfaces ('*') if inet is enabled. Disabling this value does not prevent the user from defining either socket manually. |
| UserLogging user |
Scope: Global Default: Enabled |
Enables sending messages to user-terminals including (pseudo-terminals) When disabled, no user messages will be processed (even if configured to do so). |
| UserThreads | Scope: Global Default: Enabled Requires CAP_USERTHREADS |
Creates & uses a dedicated user-threadpool to write log messages to user terminals. If disabled, prevents creation of a dedicated threadpool for user traffic. (User traffic will then be handled by generic output processing threads.) |
| SoftComment | Scope: Global (Parsing only) Default: Disabled Enables/Disables Soft-Comment Policy parsing mode. When disabled, 1st '#' in a line is a 'hard' comment. |
Enables alternate comment parsing until end-of-file or disabled. Effective as soon as it is encountered in the file or cmd-line. May be enabled/disabled as many times as desired during file parsing to 'hide' Syslogd2 extensions. |
Return to --Enable / --Disable Command-Line-Option-Table Entry
Return to top
Sub-Option Table for --defaults
Return to top
Return to Command-Line-Option Table Entry
All option names and keywords are non-case-sensitive except short-form (single-letter) option aliases.
Values that require a CAP_* declaration are shown in red.
| Name | Value, Default and Prerequisites | Comments |
|---|---|---|
| ConfigDir cd |
Absolute pathname of directory containing ancillary input files. Default: /etc/syslog.d Required with CAP_FILTERSIN, CAP_FILTERSOUT or CAP_CACHE |
Defines location of ancillary input files. Syslogd2 treats this directory and its contents as read-only. |
| SpoolDir sd |
Absolute pathname of read/write working directory for spoolfile storage.
Default is /var/spool/syslog Required with CAP_SPOOLFILES. |
|
| MaxSpoolFileSize msfs |
Size-String Default: 2g Requires CAP_SPOOLFILES |
The size at which a spoolfile becomes eligible for the SpoolFileAction to be taken the next time it is checked. (Once a file exceeds this size, it may continue to grow until the next time CheckDestinations is run to actually stop the spooling process.) |
| SpoolFileAction sfa |
Positive numeric value indicating the action to take when spool file reaches maximum size. Default: 1. (one) Requires CAP_SPOOLFILES |
1: Stop Spooling 2 and higher: Undefined Other possible actions would use the higher numeric values. |
| MaxFileSize mfs |
Size-String Default: 2g Requires CAP_FILEROTATE |
The size at which an output file becomes eligible for rotation the next time RotateFiles is run. |
| FileCheckInterval fci f |
Interval in seconds between function calls to check for and rotate large output files.
Default: 300 (5 minutes) Requires CAP_FILEROTATE |
Minimum interval between checks for large output files. Any file that has passed its MaxFileSize since the previous check will be rotated. To disable automatic file rotation, set this value to 0 (zero). |
| MarkInterval mi m |
Time-String Default: 1h. |
Interval in minutes between functions calls to write '-- Mark --' messages to output files. Applies to output files only. To disable Mark message, set this value to 0 (zero). |
| StatInterval si |
Interval in seconds between gathering and printing of performance statistics. Default: 0 (zero) (disabled) |
Stats are currently only displayed via the command-tool. This code is experimental and (while safe to use) has not been verified as useful in production environments. |
| SourceCheckIntervals sci |
A schedule for the CheckSources routine. Space-separated array of integer intervals (in seconds) between passes of the CheckSources connection-maintenance routine. Time intervals are expressed as a minimal number of seconds between checks for each individual Source. Default: 30 30 60 |
The 1st entry determines the interval between executions of the CheckSources routine. The entire schedule determines how often an individual Source that has failed at least one (re-)open attempt is re-tried. Upon successful re-opening, the index (contained in each source record) is reset. On failure, the index is incremented and the re-open attempt is rescheduled. The CheckSources also checks for (and recreates) filesystem entries for Linux sockets and looks for (tail-)files it could not previously open for input each time it is run. |
| DestinationCheckIntervals dci |
A schedule for the CheckDestinations routine. Space-separated array of integer intervals (in seconds) between passes of the CheckDestinations connection-maintenance routine. Time intervals are expressed as a minimal number of seconds between checks for each individual destination. Default: 30 60 120 |
The 1st entry determines the interval between executions of the CheckReconfig routine. The entire schedule determines how often input and output definitions that could not be previously opened/resolved are re-tried. If an environmental change was detected, the global index is reset. On failure, the index is incremented. |
| ReconfigCheckIntervals rci |
A schedule for the CheckReconfig routine. Space-separated array of integer intervals (in seconds) between passes of the CheckReconfig connection-maintenance routine. Time intervals are expressed as a minimal number of seconds between checks for each individual destination. Default: 30 30 60 |
The 1st entry determines the interval between executions of the CheckDestinations routine. The entire schedule determines how often an individual output definition that has failed at least one (re-)connection attempt is re-tried. Upon successful re-connection, the index (contained in each output record) is reset and any accumulated spoolfile is flushed. On failure, the index is incremented and the connection rescheduled. |
| FlushIntervals fi |
A schedule for flushing messages via the "Message repeated <n> times code. Space-separated array of integer timeout intervals. If the timeout value for any given output file (files only) has expired and data (and data-count) is still in storage, the message and count are written out, the count is reset, and the index is incremented (leaving the same (duplicated) message in the storage buffer. Each time an entry is written to the file (because a different message arrived), the index is reset. Time intervals are expressed as a minimal number of seconds between timeouts. Default: 30 60 90 120 |
Set the first entry to zero to disable this "flush-on-timeout" action. Set the "AllMessages" flag to disable the "duplicate message" reports in local files. |
| HostName hn |
Default: The hostname portion of the return string from gethostname(). | This setting allows the user to over-ride the local host name used in local log files or user terminals, tty and console devices. When transmitting locally-generated data to another process, the hostname/domainname is omitted and the remote host will use its own DNS / cache-file resolution. |
| DomainName dn |
Default: The domain-name portion of the return string from gethostname(). | This setting allows the user to over-ride the local domain name used in local log files or user terminals, tty and console devices. When transmitting locally-generated data to another process, the hostname/domainname is omitted and the remote host will use its own DNS / cache-file resolution. |
| LogFacility LogFac |
A facility.priority setting that Syslogd2 use for error logging, statistical output, etc. | This setting is currently unused. Statistical output is still being designed and logging errors via syslog (ie: the syslog daemon itself) needs more study. |
| UserFacility UserFac |
Default facility.priority value for all un-marked user messages. Default: user.notice |
This setting should not be confused with the "facility" or "priority" connection-spec settings. This is a default (fall-back) setting. The others are over-ride settings. |
| KernelFacility KernFac |
Default facility.priority value for all unmarked kernel messages. Default: kern.notice |
|
| KLogFile kFile |
Absolute filename of file to use as system's "kernel file" when using the tailfile input method. Default: /proc/kmsg |
This setting exists to allow specification of an alternate filename from which to read kernel input or to specify a file if not system-defined on a non-Linux host. Default value: The system-defined _PATH_KLOG variable. For Linux this is "/proc/kmsg". |
| PollInterval PollTime |
Pause-time in seconds between last --tailfile read-pass that found no data and next attempt to read data from the threadpool's list of files. Default: 60 seconds. Requires CAP_TAILFILES. |
This value resets the compiled-in value and can be over-ridden on a per-connection basis if individual tailfile connection-specs set a lower polltime value. |
| SelfAddress Self |
A semi-colon-separated list of Self-Address entries -- each of which is <IP-Address> + "=" + <space-separated list of hostnames> Default: None. This setting will not normally be required for Linux hosts. |
Defines IP input addresses and host-names that cannot be found by broken system-calls. If an --input IP-address is not detectable on any network interface or via a SelfAddress specification, Syslogd2 will reject the input definition. Example: ~ --defaults = self = fec0:2::90=hostname.sample.com hostname2.sample.com; fec0:3::80=hostname3.sample.com |
| FileOwner FileUid |
Default owner name-string or uid for output files and pipes. Default: root (0 [zero]) |
|
| FileGroup FileGid |
Default group name-string or gid for output files and pipes. Default: 0 [zero] (The group string for zero may vary by distribution or host OS) |
|
| FileMode fMode |
Default file permissions for output files and pipes. (expressed in octal) Default: 600 |
|
| SocketOwner SocketUid |
Default owner name-string or uid for input Linux-socket filesystem entries. Default: root (0 [zero]) |
|
| SocketGroup SocketGid |
Default group name-string or gid for input Linux-socket filesystem entries. Default: 0 [zero] (The group string for zero may vary by distribution or host OS) |
|
| SocketMode sMode |
Default file permissions for input Linux-socket filesystem entries. (expressed in octal) Default: 666 |
|
| User-Configurable Interrupt Settings | ||
| SigHup | Background function-name to execute when a SIGHUP signal is received. Default: "RotateFiles" | |
| SigInt | Background function-name to execute when a SIGINT signal is received. Default: "CheckFilters" | |
| SigUsr1 | Background function-name to execute when a SIGUSR1 signal is received. Default: "FlushSpoolFiles" | |
| SigUsr2 | Background function-name to execute when a SIGUSR2 signal is received. Default: "CheckReconfig" | |
| Buffer-Length Control Settings | ||
| MaxMsgLength | Positive Integer >= 15 Default: 1024 chars |
Maximum length of the message-component of a syslog event-string. (15 byte minimum is due to internal processing requirements.) |
| MaxFQDNLength | Positive Int >= 40. Default: MAXHOSTNAMELEN (255 if MAXHOSTNAMELEN is not system-defined) | MAXHOSTNAMELEN is defined as 255 for Linux & Mac. This value is the maximum length of the host-name field in a syslog message string. |
| MaxInputLineLength | Positive Integer. (50 + MaxMsgLength + MaxFQDNLength) or direct user setting -- whichever is greater. (Default: 1500) |
Max length of a raw input-string buffer. Input strings that exceed this length will be truncated. Calculation Explanation: 50 bytes are allocated for max length of priority field, version field & time field plus separators, a terminator and a small "safety" buffer. [6 (priority-field) + 2 (version-field) + 29 (time-field) + 2 (spaces) + 1 (string-terminator) + 10-byte "safety" buffer]. |
| MaxOutputLineLength | Positive Integer. Maximum of (50 + MaxMsgLength + MaxFQDNLength) or direct user setting. (Default: 1500) |
Max length of a raw output-string buffer. Output strings that exceed this length will be truncated. Note that due to force-printable expansions or filter string-replacement, this value may easily differ from the value for MaxInputLineLength. |
| MaxMsgSavedLength MaxMsgSaveLength |
Non-Negative Integer. (Default: 0) Value of 0 sets to MaxMsgLength. One of these buffers is allocated whenever an output file stores a message as part of "repeat-count" processing. |
Allows user to specify length of buffer used to identify & store duplicate (repeated) messages. Set to 0 for MaxMsgLength or set the AllMessages boolean to disable this processing (and buffer allocations). |
| ThreadPool Control Settings | ||
| Readers r |
Positive integer. Default: 2 |
Default thread-count for --input and --tailfile reader-threadpools. |
| Workers w |
Positive integer. Default: 2 Requires CAP_WORKERTHREADS |
Default thread-count for all worker-threadpools. |
| OutputWorkers o |
Positive integer. Default: 2 Requires CAP_OUTPUTTHREADS |
Default thread-count for all output-threadpools. |
| InputLines il [eye ell] |
Positive integer. Default: 500 Requires CAP_WORKERTHREADS |
Number of "message slots" in worker-thread-pool FIFO queues. |
| OutputLines ol [oh - ell] |
Positive integer. Default: 500 Requires CAP_OUTPUTTHREADS |
Number of "message slots" in output-thread-pool FIFO queues. |
| UserQueueLines uql [you - 'q' - ell] |
Positive integer. Default: 50 Requires CAP_USERTHREADS |
Number of "message slots" in dedicated user--thread-pool FIFO queue. The user-threadpool can be disabled with --disable UserThreads |
| UserQueueWorkers uqw |
Positive integer. Default: 2 Requires CAP_USERTHREADS |
Default thread-count for the (optional and dedicated) user-threadpool. |
| KernelReaders kr |
Positive integer. Default: 2 Requires CAP_KERNELTHREADS |
Default thread-count for the (optional and dedicated) kernel reader-threadpool. |
| HouseKeeping hk |
Positive integer. Default: 2 Requires CAP_HOUSEKEEPING |
Default thread-count for the (optional and dedicated) housekeeping threadpool. |
Return to Command-Line-Option Table Entry
Return to top
Signal-Function Names
Return to top
Return to Command-Line-Option Table Entry
| Function Name | Comments |
|---|---|
| NoOp | Do nothing |
| CheckSources | Reopen closed input sockets and return them to service. |
| CheckDestinations | Re-establish closed output connections and return them to service. Flush spool files as required. |
| Mark | Send "-- Mark --" messages to all files immediately. |
| ResetCache | Requires CAP_CACHE. Clear and re-set the cache file from the defined cachefile and the /etc/hosts file. |
| RotateFiles | Requires CAP_FILEROTATE. Immediately rotate all files that are eligible for rotation. |
| CheckReconfig | Check for changes and update the actively running configuration as necessary. |
| CheckFilters | Requires CAP_FILTERSIN or CAP_FILTERSOUT. Immediately check for and reparse modified filters based on last-modified time of the filter file(s). |
| DisplayConfig | Requires CAP_WHATIF. Write the run-time configuration to the defined --stdout file. |
| FlushSpoolFiles | Requires CAP_SPOOLFILES. Checks for existing spool-files with valid output connections and flushes them to the remote host. Deletes the spool-file on success. |
Return to --Defaults Command-Line-Option-Table Entry
Return to top
Common Input-ConnectionSpec Options
Return to top
Return to Option Table Entry
| Keyword | Value | Comments |
|---|---|---|
| ThreadPool Control | If a non-existant thread-pool id is referenced, that threadpool-id will be created with default values and appropriate type. | Final thread-pool parameters are the max of:
(1) Default values (either compiled-in or as over-ridden by the --defaults option) |
| id (i [eye]) | =<Non-Negative Integer>. Optional. Default: 0 [zero] | Sets thread-pool membership for this input source |
| readers (r) | <Positive Integer>. Optional. Default: omitted. | Minimum number of reader threads in the threadpool this source belongs to. |
| workers (w) | <Positive Integer>. Optional. Default: omitted. | Minimum number of worker threads for the worker threadpool identified by the queue keyword. |
| lines (l [ell]) | <Positive Integer>. Optional. Default: omitted. | Minimum number of FIFO message-slots in the worker threadpool identifed by the queue keyword. |
| queue (q) | <Non-Negative Integer>. Optional. Default: 0. | Identifies the worker threadpool-id to which this input source will queue raw data |
| Other common keywords for Input ConnectionSpecs: | Boolean values take no paraemter. They are off when omitted and set when present. | |
| noheader (nh) | Boolean. Default: FALSE: Header parsing is enabled. |
Skips the normal search for (and parsing of) timestamp-and-hostname "headers" in each message. Use "noheader" when you are sure that incoming data has no timestamp/hostname to save processing cycles & time. |
| forceprintable (fp) | Boolean. Default: Binary conversion to printable values is disabled. | Scans each message, converting ctrl & 8-bit chars to printable form (^X for control-chars or octal values: \177) for 8-bit values). |
| facility(fac) | String value. (<facility-name>). | Forces the facility component of every message read by this source to the specified value. This has no impact on the priority component. |
| priority(pri) | String value. (<priority>) | Forces the priority component of every message read by this source to the specified value. This has no impact on the facility component value. |
| priority(pri) | String value. (<facility.priority>) | Forces both facility and priority components of every message read by this source to the specified values. |
| filter (f) | String. <relative-filename>. Relative to ConfigDir. Requires CAP_FILTERSIN |
The filename value contains the set of filters to be applied to each message received from this source Filter is applied after all msg components are resolved and just before the message is routed to destinations based on facility/priority values. |
| network(net) | <semi-colon-separated list of network keywords>. Default: any. Requires CAP_NETWORK | Specifies the network states in which this input source is considered valid. |
| ignore | <semi-colon-separated list of keywords>. Default: <empty-list>. Options: Facility, Priority, Hostname | Ignore any existing data in selected input fields of incoming Linux-socket or tail-file syslog messages. Since ignore is processed before facility, priority, or hostname options it converts 'default' values into 'over-ride' values for a given input source. |
| nohost | Boolean. Default: FALSE. Host-name field is not expected in tailfile and linux-socket input when a date-time field is recognized. |
Specifies that if a time-field is found, the next non-whitespace word is NOT a hostname/address, but part of the msg string. Useful to parse log files starting with time-field but containing no host-field. |
Return to Option Table Entry
Return to top
Sub-Option Table for Output-Lines (Destination-Specs)
Return to top
Output-line syntax
| Name | Value, Default Value and Pre-requisites | Comments |
|---|---|---|
| ThreadPool Control (Requires CAP_OUTPUTTHREADS) |
||
| ThreadpoolId (id) |
Non-Negative Integer. Default: 0 | Assigns this destination to the designated output threadpool |
|
WorkerThreads (workers) (w) |
Positive Integer. Default: omitted. (inherited) | Minimum thread-count for the threadpool specified by the id keyword. |
|
QueueLines (Lines) (l [ell]) |
Positive Integer. Default:500a | Minimum number of FIFO message-slots in the output threadpool identifed by the threadpoolid keyword. |
| Common to all Destination-Types | ||
|
filterfile (filter) (f) |
Relative filename. Relative to ConfigDir. Default: None. Applies to Selector. Requires CAP_FILTERSOUT. |
Specifies the file continaining the filter-set to be applied to messages that match this selector-string. |
|
network (net) (n) |
<semi-colon-separated list of network keywords>. Default: any. Requires CAP_NETWORK | Specifies the network states in which this destination is considered valid. |
|
relay (r) |
Boolean setting. No parameters. Default disabled. |
For eacier parsing (and complete time data) for applciations (via pipes & sockets), the time field is changed to '{' + <utc (system-clock)="" time="" as="" a="" numeric="" integer="" +="" '}'.="" since="" utc="" is="" used,="" time-zone="" differences="" disappear="" and="" dst="" can="" be="" ignored.="" <="" td=""> </utc> |
| Streaming Destinations: (TCP, Streaming Linux Sockets, Named-Pipes) |
||
|
SpoolFile (SpoolFile) |
Optional filename parameter. No Default. Applies to Selecor. If given, filename is relative to SpoolDir and is a suggestion only. Requires CAP_SPOOLFILES |
If file is not given or in conflict a name lie "LineXXXSeqYYY" will be used as the spoolfile name. This selector-option specifies whether matching (non-tranmittable) events are to spool to a file. The Destination component controls the state of the connection and when spooling may be required. |
|
SpoolFileMaxSize (SpoolFileMax) (sfmax) |
Size-String Default: 2g |
Maximum size of spool file before a SpooFileAction is taken. |
|
SpoolFileAction (sfa) |
Positive Integer: Default: 1 (stop spooling) 1 ::= Stop spooling. No other actions defined. |
Additional spool-file actions may be defined in future. |
| Files and Named-Pipes Only | ||
|
Uid (u) |
Owner-string or numeric uid for this destination's filesystem entry. | |
|
Gid (g) |
Group-string or numeric gid for this destination's filesystem entry. | |
|
Mode (m) |
File-System permission setting for this destination's filesystem entry. Default: inherited. 3 octal digits. Example: 666 |
|
| Other Options | ||
|
AllMessages (AllMsgs) (EveryMsg) |
Boolean setting. No parameters. Default inherited from global value. Files Only. |
Logs duplicate messages immediately instead of calculating duplicate-message counts. This option replaces the "Last message repeated...." messages with the actual duplicate messages. |
|
Datagram (Dgram) (d) (UDP) (U) Stream (s) (TCP) (T) |
Boolean values (no parameter values apply). |
Defnes the protocol of the Linux socket or IP connection for this destination. |
| port (p) |
IP connections only Default for UDP/IP connections: 514. For TCP/IP: none. |
|
| version (ver) (v) |
one of (4 | 6 | 46) Default: 46 |
Selects allowable address families for IP hostnames. IP-addresses do not use this setting as the address family for the connection is known |
Discussion
Anonymous
