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 with 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.

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. This channel doesn’t take any additional parameters.

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. There are no additional 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:
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 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 the 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. 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.

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 and explicit URL argument.

SEE ALSO

syslog(3), syslogd(8).

RFC 3164, RFC 5425, RFC 5426, RFC 6587.

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.

Powered by mansrv 1.1