Ansible Role: Rsyslog

This role installs and sets up rsyslog on Debian/Ubuntu servers.

It installs the latest version of rsyslog from the official APT repository (for Debian) or the official PPA (for Ubuntu). By default, it will manage the files /etc/rsyslog.conf and /etc/rsyslog.d/50-default.conf.

Requirements

No requirements.

Role Variables

Here are the available variables with their default values (found in defaults/main.yml):

rsyslog_rules: []

This is an array of rules for rsyslog. Each entry will create a unique config file named as $priority-$rule_name.conf. Check defaults/main.yml for an example.

rsyslog_rules:
  - rule_name: "remote-udp"
    priority: 99
    ruleset: |
      module(load="omfwd")
      action(type="omfwd" target="central.server.local" port="514" protocol="udp")
    state: "present"

This shows a complete entry for rsyslog_rules. Note the | for starting the block of ruleset. This part uses basic rsyslog config syntax.

Instead of creating rules one by one in rsyslog_rules, you can use rsyslog_extra_conf_options to add extra options directly to the main /etc/rsyslog.conf file.

rsyslog_extra_conf_options: |
  module(load="imudp")
  input(type="imudp" port="514")

Again, | denotes the block, and the content is plain rsyslog config syntax. You can also set rsyslog_remove_default_rules: true to keep /etc/rsyslog.d/ empty.

There are currently three preconfigured rsyslog rules. Only one of them, called default, is enabled by default and manages /etc/rsyslog.d/50-default.conf. You can disable it by setting state: "absent".

rsyslog_rule_default:
  rule_name: "default"
  priority: 50
  template: "default.conf.j2"

The second is the docker rule, which manages logs for Docker containers on the host, set up in the /etc/rsyslog.d/20-docker.conf file.

rsyslog_rule_docker:
  rule_name: "docker"
  priority: 20
  template: "docker.conf.j2"
rsyslog_rule_docker_tag_all: true

This creates the /var/log/docker directory and stores log files named after the containers (e.g., $CONTAINER_NAME.log). It requires the $syslogtag to include docker/ in its name; otherwise, it will log everything under /var/log/docker/no_tag.log. Also, enabling rsyslog_rule_docker_tag_all allows logs from multiple containers to be aggregated into a single /var/log/docker/all.log. For an example of a container with syslog support, check my hadret.containers role.

containers:
  - name: cadvisor
    image: "google/cadvisor:latest"
    state: started
    log_driver: journald
    log_options:
      tag: docker/cadvisor

journald is automatically managed by rsyslog nowadays.

Lastly, there's the remote rule, which allows for client and server setup for remote logging. It is simple and works with minimal settings.

rsyslog_rule_remote:
  rule_name: "remote"
  role: server
  priority: 99
  template: "remote.conf.j2"
  ruleset_name: "remote"

You must specify at least one remote protocol (relp/tcp/udp). Notably, rsyslog_rule_remote alone will not work without specifying a protocol. The server configuration requires a ruleset_name because that's where the actions for writing logs (using omfile) and template application are defined. The expected outputs include auth.log, syslog.log, rsyslog.log, kern.log, and mail.log.

rsyslog_rule_remote_relp:
  port: 514

Currently, only relp supports TLS setup.

rsyslog_rule_remote_relp:
  address: 0.0.0.0
  port: 514
  tls: true
  tls_cacert: "/tls-certs/ca.pem"
  tls_mycert: "/tls-certs/cert.pem"
  tls_myprivkey: "/tls-certs/key.pem"
  tls_authmode: "fingerprint"

For tcp and udp, you can set the address (optional for server), target (required for client), and port (required for both).

rsyslog_rule_remote_tcp:
  address: 0.0.0.0
  port: 514

rsyslog_rule_remote_udp:
  address: 0.0.0.0
  port: 514

You can define all three types (with different addresses and ports), but each only once. By default, configurations will go to /etc/rsyslog.d/99-remote.conf (for both server and client). A single machine cannot act as both server and client using just rsyslog_rule_remote_relp, but you can use additional rules with rsyslog_extra_conf_options or rsyslog_rules.

rsyslog_rule_remote:
  rule_name: "server"
  role: server
  priority: 99
  template: "remote.conf.j2"
  ruleset_name: "server"

rsyslog_rule_remote_udp:
  port: 514

rsyslog_rules:
  - rule_name: "client"
    priority: 99
    ruleset: |
      module(load="omfwd")
      action(type="omfwd" target="central.server.local" port="514" protocol="tcp")

Note: these preconfigured rsyslog rules are dictionaries, not arrays. Only rsyslog_rules can have multiple definitions.

Extending and Replacing Templates

Not all configurations can be set with variables, which is why I use templates for all rules. This allows for easy expansion, replacement, or full template switching to fit your needs.

rsyslog_conf_template: "rsyslog.conf.j2"
rsyslog_rules_template: "rules.conf.j2"

You can change templates for individual rules as well.

rsyslog_rule_default:
  rule_name: "default"
  priority: 50
  template: "{{ playbook_dir }}/templates/custom-default.conf.j2"

rsyslog_rule_docker:
  rule_name: "docker"
  priority: 20
  template: "{{ playbook_dir }}/templates/custom-docker.conf.j2"

rsyslog_rules:
  - rule_name: "remote-udp"
    priority: 90
    template: "{{ playbook_dir }}/templates/custom-udp.conf.j2"
  - rule_name: "remote-tcp"
    priority: 91
    template: "{{ playbook_dir }}/templates/custom-tcp.conf.j2"

Example: Extending Modules Block in Main Config File

Set rsyslog_conf_template to point to your new file in your playbook directory.

rsyslog_conf_template: "{{ playbook_dir }}/templates/custom-rsyslog.conf.j2"

The custom template file should be in relation to your playbook.yml.

{% extends 'roles/external/hadret.rsyslog/templates/rsyslog.conf.j2' %}

{% block modules %}
$ModLoad imuxsock
$ModLoad imklog
$ModLoad immark

$ModLoad imudp
$UDPServerRun 514

$ModLoad imtcp
$InputTCPServerRun 514
{% endblock %}

The above example replaces or extends the modules block in the main rsyslog config file.

Dependencies

No dependencies.

Example Playbook

hosts: all
  roles:
    - hadret.rsyslog

License

MIT.

Authors

This role was created in 2019 by Filip Chabik.