Description: This write-up explains how to configure your Syslog installation to accept log messages from your canary console.

NB! There has been some confusion around the source of Syslog messages. Often it is assumed that Syslog traffic will originate from the Canaries themselves, and while this is a perfectly valid assumption, it is not the way we've implemented it.

Syslog messages will originate from your console. We do it this way for a few reasons:

1. Multiple related events will get consolidated into a single incident by the console, reducing the number of alerts you'll receive.
2. When a large number of Canaries are deployed, especially across different geographical locations for a single organisation, it makes sense for Syslog traffic to originate from a single source to simplify networking.
3. We want to run as little software on the birds as possible to make sure that they continue to do what they're meant to do, well.

We support (and recommend) TLS encryption for Syslog, and because all traffic will originate from your console, it is easy to ignore-list its domain and drop connection attempts from other hosts.

Getting Syslog running

The Canary Console runs RSyslog and emits log messages over TCP or UDP, with the optional RELP extension. It is also possible to use TLS to encrypt the message channel.

In preparation to receive alerts via syslog, you'll need:

1. A configured and correctly working Syslog or RSyslog endpoint that can receive packets from your Canary Console.
2. Connection details (hostname or IP, port number).
3. Protocol details (UDP / TCP, TLS certificates and keys if relevant, RELP is supported too.)
4. Send a support request to support@canary.tools with this information.

Consuming Syslog

The alerts are sent to local0 facility and CRITICAL loglevel.

The messages are formatted using a tab-separated key=value format.

Sample receiving configurations

A basic configuration to accept log messages over TCP may look something like this:

module(load="imuxsock")
module(load="imtcp”)
input(type="imtcp” port="10514")

if ( $programname == "canary-tools”) then /var/log/canary.log

A configuration using RELP may look something like this:

module(load="imuxsock")
module(load="imrelp”)
input(type="imrelp” port="10514")

if ( $programname == "canary-tools”) then /var/log/canary.log

A configuration using both RELP and TLS may look like the following:

module(load="imuxsock")
module(load="imrelp")
input(
    type="imrelp" 
    port="10514"
    tls="on"
    tls.caCert="/home/logger/rsyslog_certs/ca.pem"
    tls.myCert="/home/logger/rsyslog_certs/serv-cert.pem"
    tls.myPrivKey="/home/logger/rsyslog_certs/serv-key.pem"
    tls.authMode="name"
    tls.permittedpeer=[“hostname”]
)

Troubleshooting

• If you are using Splunk you may need to specify the timezone. The timezone of the Syslog messages will be UTC. Setting TZ=GMT in the props.conf file on the indexer will ensure messages show up correctly.