DEBOPS.JOURNALD(5)

NAME
debops.journald - Manage systemd-journald service using Ansible

SYNOPSIS

debops service/journald [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

debops service/journald --tags role::journald:fss:verify [--limit group,host,...] [<ansible-playbook options>] ...

DESCRIPTION

The Journal, part of the systemd <https://www.freedesktop.org/wiki/Software/systemd/> project, is a syslog replacement. On systems that use systemd as the init daemon, the systemd-journald service takes care of receiving, storing and routing the log messages received via the /dev/log device, the logger(1) <https://manpages.debian.org/logger(1)> command or from services managed by the systemd init daemon.

The debops.journald Ansible role can be used to manage the Journal configuration, enable or disable persistent log storage and configure Forward Secure Sealing on the managed hosts.

GETTING STARTED

  Forward Secure Sealing

When the persistent logs are enabled, the debops.journald role configures Forward Secure Sealing functionality of the Journal by default. The verification keys are saved in the secret/journald/fss/ directories on the Ansible Controller. The role can be used in an "alternative" mode where Ansible checks the log integrity by running the command:

debops service/journald --tags role::journald:fss:verify

With this tag, only the task that verifies the logs will be executed.

  Example inventory

The debops.journald role is included by default in the common.yml DebOps playbook; you don't need to add hosts to any Ansible groups to enable it.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.journald role:

---
- name: Manage systemd journal service
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_journald' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: journald
      tags: [ 'role::journald', 'skip::journald' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::journald
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

role::journald:fss:verify
    The role can be used with this tag to use the Forward Secure Sealing funtionality to verify the consistency of the logs stored on the host(s). No other tasks will be performed when this tag is used.

DEFAULT VARIABLE DETAILS

Some of the debops.journald default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  journald__configuration

The journald__*_configuration default variables define the contents of the /etc/systemd/journald.conf.d/ansible.conf configuration file. This file will be automatically parsed by the systemd-journald service and any active options will override the defaults defined in the /etc/systemd/journald.conf configuration file. You can read the journald.conf(5) <https://manpages.debian.org/journald.conf(5)> manual page for more details about supported options.

  Examples

Configure disable persistent storage for the journal logs, using the simple syntax:

journald__configuration:
  - 'Storage': 'volatile'

You can check the journald__default_configuration variable for the default contents of the configuration file.

  Syntax

Each configuration entry in the list is a YAML dictionary. The simple form of the configuration uses the dictionary keys as the parameter names, and dictionary values as the parameter values. Remember that the parameter names need to be specified in the exact case they are used in the documentation (e.g. TTYPath, ReadKMsg), otherwise they will be duplicated in the generated configuration file. It's best to use a single YAML dictionary per configuration option.

If the YAML dictionary contains the name key, the configuration switches to the complex definition mode, with configuration options defined by specific parameters:

name
    Required. Specify the name of the Journal configuration file parameter. The case is important and should be the same as specified in the configuration file or the journald.conf(5) <https://manpages.debian.org/journald.conf(5)> manual page, otherwise the configuration entries will be duplicated.

    Multiple configuration entries with the same name parameter are merged together in order of appearance. This can be used to modify parameters conditionally.

value
    Required. The value of a given configuration option. It can be a string, number, True/False boolean or an empty string.

state
    Optional. If not specified or present, a given configuration parameter will be present in the generated configuration file. If absent, a given parameter will be removed from the configuration file. If comment, the parameter will be present but commented out.

    If the state is init, the parameter will be "primed" in the configuration pipeline, but it will be commented out in the generated configuration file. Any subsequent configuration entry with the same name will switch the state to present - this is used to define the default parameters in the role which can be changed via the Ansible inventory.

    If the state is ignore, a given configuration entry will not be evaluated during role execution. This can be used to activate configuration entries conditionally.

SEE ALSO

•   Manual pages: systemd-journald.service(8) <https://manpages.debian.org/systemd-journald.service(8)>, journald.conf(5) <https://manpages.debian.org/journald.conf(5)>, journalctl(1) <https://manpages.debian.org/journalctl(1)>

•   "Introducing the Journal" (2011) <https://docs.google.com/document/pub?id=1IC9yOXj7j6cdLLxWEBAGRL6wl97tFxgjLUEHIX3MSTs>

•   "systemd for System Administrators, Part XVII" (2012) <http://0pointer.de/blog/projects/journalctl.html>

•   LWN: "Forward Secure Sealing" (2012) <https://lwn.net/Articles/512895/>

•   Arch Linux Wiki: systemd/Journal <https://wiki.archlinux.org/index.php/Systemd/Journal>

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2022, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others