Ansible Role: rsyslog

This Ansible role allows you to install rsyslog and manage its configuration.

For more information about rsyslog, please check the official project page.

This page should also help you understand the basics of rsyslog and thus the configuration options of this Ansible role: Configuration : basic structure.

IMPORTANT: this role should be able to manage the configuration for clients, relayers and/or central servers.

Role variables

Variables and properties in bold are mandatory. Others are optional.

Variable name	Description	Default value
rsyslog_additional_packages	List of additional packages to install with rsyslog. (i.e. rsyslog-imrelp)	[]
rsyslog_working_dir	Path to the directory where rsyslog must store the queue files.	/var/spool/rsyslog
rsyslog_tls	A rsyslog_tls dict. See rsyslog_tls properties below.	{}
rsyslog_templates	A list of template.	[]
rsyslog_rulesets	A list of ruleset.	[]
rsyslog_inputs	A list of input.	[]
rsyslog_outputs	A list of output.	[]

As you can see, the default configuration does nothing. It's just an empty shell.

rsyslog_tls properties

rsyslog_tls is a dict that stores some paths to the needed certificates and keys needed for TLS to work.

If you plan to use TLS (be it with imtcp or with imrelp), you have to specify all 3 properties.

Property name	Description
cacert	Path to the CA certificate.
cert	Path to the machine certificate (this certificate must be signed by the CA.
key	Path to the private key corresponding to rsyslog_tls.cert.

template properties

Property name	Description
name	Name of the template. Must be unique.
string	Template.

❗ Notes:

• For now we only support string templates. list templates, subtree templates and plugin templates are not supported. options aren't either.

📗 Documentation:

• Templates documentation

ruleset properties

Property name	Description
name	Name of the ruleset.
script	Instructions to execute when the ruleset is reached. Please see official documentation for further details.

📗 Documentation:

• Ruleset documentation
• RainerScript documentation

input properties

Property name	Description
module	Name of the module to load.
parameters	A dict of parameters passed when loading the module.
listeners	A list of listeners.

❗ Notes:

• Only modules that have at least one listener will be loaded. If you don't provide at least one listener, the module will be ignored.
• The parameters dict doesn't follow a strict, fixed schema. Keys are basically the names of the options supported by the module. Values must be set accordingly. If an option accept an array, you have to provide a list. The template will transform it into the expected array. Please also be aware that some modules have mandatory options. Please refer to the module documentation.

📗 Documentation:

• List of input modules

listener properties

A listener consists in a set of options for the input. It is represented as a dict.

A module can have multiple listeners defined with different options. For example, you may want to accept logs coming on UDP ports 541, 542 and 543 and apply a different ruleset in each case. In this particular example, you would have to define 3 different listeners for the same module :

---

#[snip]

rsyslog_inputs:
  - module: imudp
    parameters: {}
    listeners:
      - port: 541
        ruleset: "UDP541"
      - port: 542
        ruleset: "UDP542"
      - port: 543
        ruleset: "UDP543"
...

Listener properties depends on the options supported by the module. So, keys are basically the names of the options supported by the module. Please note that some modules have mandatory options. Please refer to the module documentation.

We strongly advise to use rulesets to keep your configuration clean.

📗 Documentation:

• Input documentation

output properties

Property name	Description
module	Name of the module to load.
actions	A list of actions.

📗 Documentation:

• List of output modules

action properties

Property name	Description
selector	Selector that catches the message.
parameters	A dict of parameters for the filter.

❗ Notes:

• The parameters dict doesn't follow a strict, fixed scheme. Keys are basically the names of the options supported by the module. Values must be set accordingly. If an option accepts an array, you have to provide a list. The template will transform it into the expected array. Please also be aware that some modules have mandatory options. Please refer to the module documentation.

📗 Documentation:

• Selector documentation

Examples

Server

In this first example, we want to setup a loghost that centralizes logs of several clients.

1. It accepts logs via TCP,
2. only over TLS,
3. on port 6514.
4. It outputs the received logs in a file,
5. that is specific for each client,
6. in RFC5424 format.

---
rsyslog_additional_packages:
  # For TLS:
  - "rsyslog-gnutls"
  # For SELinux:
  # CentOS:
  - "policycoreutils-python"
  # Debian:
  - "policycoreutils-python-utils"

rsyslog_working_dir: "/var/spool/rsyslog"

rsyslog_tls:
  cacert: "/etc/ssl/ca.cert"
  cert: "/etc/ssl/loghost.cert"
  key: "/etc/ssl/private/loghost.pem"

rsyslog_templates:
  - name: "fromRemote"
    string: "/var/log/remote/%fromhost%.log"
  - name: "rfc5424Format"
    string: "<%PRI%>%PROTOCOL-VERSION% %TIMESTAMP:::date-rfc3339% %HOSTNAME% %APP-NAME% %PROCID% %MSGID% %STRUCTURED-DATA% %msg%\\n"

rsyslog_rulesets:
  - name: "remote"
    script: |-4
            action(
                type="omfile"
                dynaFile="fromRemote"
                template="rfc5424Format"
            )
            stop

rsyslog_inputs:
  - module: imtcp
    parameters:
      streamdriver.name: "gtls"
      streamdriver.mode: 1
      streamdriver.authmode: "x509/name"
      permittedpeer:
        - "client001"
    listeners:
      - port: 6514
        ruleset: "remote"

rsyslog_outputs: []
...

Client

In this second example, we want to setup a client that forwards all its logs to the previously configured loghost.

1. It sends logs via TCP,
2. only over TLS,
3. on port 6514.

---
rsyslog_additional_packages:
  # For TLS:
  - "rsyslog-gnutls"

rsyslog_working_dir: "/var/spool/rsyslog"

rsyslog_tls:
  cacert: "/etc/ssl/ca.cert"    # MUST be the same as the one used on the loghost.
  cert: "/etc/ssl/client.cert"
  key: "/etc/ssl/private/client.pem"

rsyslog_templates: []
rsyslog_rulesets: []

rsyslog_outputs:
  - module: omfwd
    actions:
      - selector: "*.*"
        parameters:
          target: "loghost.localdomain"
          port: 6514
          protocol: "tcp"
          streamdriver: "gtls"
          streamdrivermode: 1
          streamdriverauthmode: "x509/name"
          streamdriverpermittedpeers: "loghost.localdomain"
...

Contributing