SYSLOGRELAY

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
SEE ALSO
BUGS
COPYRIGHT

NAME

syslogrelay - forward syslog messages to remote server

SYNOPSIS

syslogrelay [-Vdhn] [-H HOSTNAME] [-O FILE] [-R HOST[:PORT]] [-l SEVERITY] [-p SOCKET] [-q SIZE] [-W PARAM] [URL]

DESCRIPTION

Syslogrelay provides system log forwarding facility for confined environments. It listens for incoming system log messages on the UNIX socket file /dev/log and forwards them to the remote server specified by the URL.

The URL consists of a scheme, which selects the output channel to use, and argument, specifying the actual destination. The two parts are separated by ://. Some output channels can take additional parameters, which can be supplied using the -W option.

The following output channels are supported:
file://FILE

Write messages to a disk file. The FILE argument gives the file name.

This channel understands the prio= parameter, which controls whether and how the message priority is reflected on the output. Its possible values are:

	none		Priority is not output. This is the default.
	keep		Priority is retained as is, i.e. as a decimal number in angle brackets at the start of a message.
	decode		Priority is printed in human-readable form as syslog facility and message severity delimited by a single dot and enclosed in angle brackets. The facility and severity names used are as described in syslog(3), but without the LOG_ prefix.

pri:///DIR

Distribute messages to two disk files located in directory DIR. The name of the file to write to is selected depending on the message severity. Messages with severity greater than LOG_ERR are directed to file 1 (out file), messages with severity less than or equal to LOG_ERR are directed to file 2 (err file).

This channel understands the following parameters:
severity=SEVERITY

Sets the name of the delimiting severity. Messages with severity less than or equal to that value will be directed to the err file. (DIR/2, by default).

errfile=NAME

Sets the name of the err file.

outfile=NAME

Sets the name of the out file.

prio=none | keep | decode

Controls whether and how the message priority is reflected on the output. For details, see the description of the channel file: above.

Default settings correspond to:

-Wseverity=err -Werrfile=2 -Woutfile=1 -Wprio=none

udp://HOST[:PORT]

Forward messages to the given host using the standard UDP transport (RFC 5426). HOST must be an IP address (both IPv4 and IPv6 are allowed), or a domain name, that resolves to exactly one IP address. PORT defaults to 514.

Parameters:
bind=IP

Bind socket to the given IP address - either an IPv4 address or IPv6 enclosed in square brackets.

tcp://HOST:PORT

Forward messages to the given host using the TCP transport (RFC 6587). The PORT part is mandatory. See above for the syntax of HOST. This channel implements the Octet Counting message transfer method. See udp for a list of available parameters.

tcp+tls://HOST[:PORT]

Forward messages to the given host using TLS over TCP (RFC 5425). For the syntax of the HOST part, refer to udp:// above. The default PORT is 6514. The following parameters can be used with this channel:
bind=IP

Bind socket to the given IP address - either an IPv4 address or IPv6 enclosed in square brackets.

cafile=FILE

Specifies the certificate authority file to use for certificate verification during the handshake. Without this parameter, certificate verification is disabled.

cert=FILE

Specifies the certificate file for client authentication. The key= parameter must be used as well.

key=FILE

Specifies the key file for certificate supplied with the cert= parameter.

priority=STRING

Specifies the TLS session’s handshake algorithms and options to use. The argument is a GnuTLS priority string as discussed in <https://gnutls.org/manual/html_node/Priority-Strings.html>.

Two shortcuts are implemented to simplify URL syntax in the two most often used cases. First, if URL begins with a slash character, it is assumed to be the name of the local file. That is,

syslogrelay /WORD

is equivalent to

syslogrelay file:///WORD

Any other URL not starting with a scheme is assumed to define a udp:// channel. That is, syslogrelay 127.0.0.1 is equivalent to syslogrelay udp://127.0.0.1.

Finally, for compatibility with busybox syslog, the -O and -R options are provided. When either of them is given, URL may not be used. The option -O FILE is equivalent to the URL file://FILE. The option -R HOST is equivalent to udp://HOST.

If URL is omitted and neither compatibility option is given, syslogrelay assumes file:///var/log/messages. This default channel can be changed at compile time. To be sure, inspect the output of syslogrelay -h.

Message queue
The program maintains a message queue, which is used to temporarily hold the messages while the selected channel is not able to receive them. When the receiver is back online again, the messages from the queue are transmitted to it. If the receiver is down for too long, the queue can get filled up. In this case, syslogrelay will start dropping messages from the head of the queue, i.e. the ones that sit there for the longest time. Each dropped message is logged on the standard error.

Notice that the above procedure is effective for TCP-based channels only.

The default queue size is 128 messages and can be modified using the -q command line option.

Message normalization
Before forwarding, received messages are normalized as described in RFC 3164, section 4.3. In particular, hostname part is inserted to messages lacking it. The hostname to use is determined using the gethostname(2) call. If the result is not satisfactory, it can be overridden with the -H option. Hostname insertion can be disabled using the -S option.

If the message text contains ASCII control characters (ASCII 0 to 31), these are replaced with their caret notation, i.e. a caret character followed by the character value XORed with 0100. Thus, horizontal tabulation (ASCII 9) becomes ^I, carriage return (ASCII 13) becomes ^M, etc. By default the newline character is exempt from this translation. Instead, it is substituted with horizontal space (ASCII 32).

The -Wcontrol_chars=MODE option can be used to alter this processing. Possible values for MODE are:

caret

Replace all control characters with their caret notation. The newline character is represented as ^J.

caretnl

The default algorithm as described above.

	octal		Replace control characters with their octal representation.
	raw		Reproduce control characters verbatim.

OPTIONS

-H HOSTNAME

Assume HOSTNAME as the current hostname.

	-S		When processing incoming messages, don’t insert hostname to the header, even if it is missing.
	-d		Reserved for future use.
	-h		Displays a short usage summary.
	-l N		Silently drop messages with the severity value greater than N. Argument is either a numerical value of the severity (0 through 7), or one of symbolic names: emerg, alert, crit, err, warning, notice, info, debug (case-insensitive).

-p SOCKET

Listen on the given socket file, instead of the default /dev/log.

	-q N		Modify the message queue size.
	-V		Print program version and exit.

-W PARAM=VALUE

Set the channel-specific parameter. See DESCRIPTION above for the list of these.

Compatibility options
The following options are provided for compatibility with busybox syslog.
-O FILE

Write messages to FILE. Same as specifying file://FILE URL as argument.

-R HOST[:PORT]

Forward messages to HOST at UDP port PORT. This is the same as specifying udp://HOST[:PORT] URL.

-n

Ignored.

Obviously, it is an error to use -O or -R together with an explicit URL argument.

BUGS

Multiple UNIX sockets are not supported. If the HOST part of the URL argument is a symbolic host name, it must resolve to exactly one IP address.

COPYRIGHT

Copyright © 2022 Sergey Poznyakoff <gray@gnu.org>
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

Manpage server at man.gnu.org.ua.