DEBOPS.SYSTEMD(5)

NAME
debops.systemd - Configure system and service manager using Ansible

SYNOPSIS

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

DESCRIPTION

The systemd <https://www.freedesktop.org/wiki/Software/systemd/> project is a system and service manager, a replacement for the traditional /bin/init daemon started by the kernel after the boot process is complete. systemd focuses on the intermediate layer between the "kernel space" and "userspace", so called "system" layer. The project itself is composed from multiple separate services which can be enabled or disabled as needed.

The debops.systemd Ansible role focuses on management of the systemd service itself; other Ansible roles included in the DebOps project can be used to manage disparate components like journald via the debops.journald role. This role manages the "system" instance of systemd, as well as the global configuration of the systemd --user instances and the configuration of the systemd-logind login manager.

GETTING STARTED

  Example inventory

The debops.systemd 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.systemd role:

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

  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::systemd
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

DEFAULT VARIABLE DETAILS

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

  systemd__configuration

The systemd__*_configuration default variables define the configuration of the systemd service itself. There are separate sets of variables for the "system" instance, as well as a separate set of systemd__user_*_configuration variables for the global configuration of the systemd --user instances - both use the same configuration format. You can find more details about systemd configuration in the systemd-system.conf(5) <https://manpages.debian.org/systemd-system.conf(5)> manual page.

The systemd__logind_*_configuration variables define the configuration of the systemd-logind service. See loginf.conf(5) <https://manpages.debian.org/loginf.conf(5)> for more details about its configuration options.

The generated configuration will be located in the /etc/systemd/system,user,logind.conf.d/ansible.conf config files. These files are not generated by default to fall back on the default configuration provided in the OS packages; to generate them the systemd__deploy_state variable needs to be set to present.

  Examples

You can check the systemd__default_configuration, systemd__user_default_configuration and the systemd__logind_default_configuration variables for the default contents of the configuration files.

  Syntax

The role uses the Universal Configuration system to configure systemd. 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. LogLevel, NUMAPolicy), 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 systemd configuration file parameter. The case is important and should be the same as specified in the configuration file or the systemd-system.conf(5) <https://manpages.debian.org/systemd-system.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.

  systemd__units

The systemd__*_units default variables can be used to manage systemd units (services, timers, etc.). The role supports management of the system-wide units stored in the /etc/systemd/system/ directory, as well as the systemd --user instance units defined globally, stored in the /etc/systemd/user/ directory (using systemd__user_*_units variables). You can find more information about the units themselves in the systemd.unit(5) <https://manpages.debian.org/systemd.unit(5)> manual page.

  Examples

Restart an existing service when the debops.systemd Ansible role is applied on the host (without changing the configuration, this will be performed on each role execution):

systemd__units:
  - name: 'systemd-sysctl.service'
    state: 'restarted'

Configure the network card on the system boot to permit Wake-On-LAN packets to boot the host. The service will be created and executed on the next boot:

systemd__units:
  - name: 'wol.service'
    raw: |
      [Unit]
      Description=Configure Wake on LAN
      [Service]
      Type=oneshot
      ExecStart=/sbin/ethtool -s eth0 wol g
      [Install]
      WantedBy=basic.target
    state: 'present'

Create an example daemon which does nothing, ensure that it's started:

systemd__units:
  - name: 'sleeper.service'
    raw: |
      [Unit]
      Description=An example daemonized sleep command
      [Service]
      Type=simple
      ExecStart=/usr/bin/sleep 3600
      [Install]
      WantedBy=multi-user.target
    state: 'started'

Create an override for a specific service and change its description. Ensure that the service is restarted when its configuration is changed:

systemd__units:
  - name: 'sleeper.service.d/description.conf'
    raw: |
      [Unit]
      Description=GSV Sleeper Service
    state: 'present'
    restart: 'sleeper.service'

Remove a specific unit override file without removing the whole service. The service will be restarted to apply the changed configuration:

systemd__units:
  - name: 'sleeper.service.d/description.conf'
    state: 'absent'
    restart: 'sleeper.service'

Remove a service and all of its override files. The state of the service will not be changed (running service stays running until the next host reboot):

systemd__units:
  - name: 'wol.service'
    state: 'absent'
  - name: 'sleeper.service'
    state: 'absent'

  Syntax

The role uses the Universal Configuration system to manage systemd unit files. Each configuration entry in the list is a YAML dictionary, with configuration options defined by specific parameters:

name
    Required. Name of the systemd unit file to manage. The name can be in the form <unit.type> to denote a single systemd.unit(5) <https://manpages.debian.org/systemd.unit(5)>, as well as <unit.type>.d/<override>.conf to denote a single "override" configuration file that changes the configuration of a specific unit.

    Unit files are stored either under the /etc/systemd/system/ or the /etc/systemd/user/ subdirectories, depending on the default variable used. The role will create the <unit.type>.d/ subdirectories as needed.

    The name parameter needs to be unique. Multiple configuration entries with the same name parameter are merged together and override each other.

raw Optional. YAML text block in the INI format, with the systemd configuration options which will be included in the generated configuration file as-is. The text block can contain Jinja statements to generate parts of the configuration dynamically.

    See the systemd.unit(5) <https://manpages.debian.org/systemd.unit(5)> manual page for details about the unit configuration syntax and available options. The generated files are not validated by Ansible before being applied in the systemd configuration at this time.

state
    Optional. If not specified or present (default), a given unit configuration file will be generated by Ansible and placed in the systemd configuration directories. The role will ensure that the unit is enabled in systemd, but the service will not be started by default.

    If started or stopped, the configuration file will be generated and the unit will be enabled. The role will then try to ensure that the unit is in the desired state by starting or stopping it in systemd. Specified actions will not be performed if a given configuration entry defines an unit override file.

    If restarted or reloaded, the configuration file will be generated and the unit will be enabled. The role will tell systemd to restart or reload the unit. This will be repeated on each execution of the role, unless the state parameter is updated. Specified actions will not be performed if a given configuration entry defines an unit override file.

    If absent, the role will remove the specified unit configuration file as well as the override directory if it is present (all override files will be removed, even ones not managed by Ansible). Specific override files can be removed as well if they are defined directly in the name parameter.

    The role will not change the state of a running systemd unit this way. Units will report their configuration as "not found" and will stay active until the next reboot or if they are stopped manually (Ansible currently cannot deal with such case properly via the ansible.builtin.systemd module).

    If init, the configuration entry will be prepared, but no changes will be done on the host itself. This can be done to prepare a unit configuration and activate it conditionally later in the universal configuration pipeline.

    If ignore, a given configuration entry will not be evaluated during role execution.

restart
    Optional. Specify the name of a systemd unit (not the override). If a given entry generates a configuration file for a unit or its override with a "changed" state, or a given override is removed, the role will tell systemd to restart a specified unit. This can be used to automatically restart services when their configuration is changed using unit override files. Because the template system in Ansible is idempotent, subsequent executions of the role should not restart the unit again when this parameter is used. This parameter is supported only for the system-wide unit configuration, not the "global" user configuration.

comment
    Optional. String or YAML text block with comments included in the generated configuration file.

enabled
    Optional, boolean. If True (default), the managed unit will be enabled in systemd to be started on boot. If False, the unit will not be started by default.

masked
    Optional, boolean. If True, the role will tell systemd to "mask" a unit to make it impossible to start, creating a symlink to /dev/null file. If False, a given unit will be "unmasked", so that it can be managed again.

force
    Optional, boolean. If True, instruct the ansible.builtin.systemd module to override existing symlinks.

SEE ALSO

•   Manual pages: systemd(1) <https://manpages.debian.org/systemd(1)>, systemctl(1) <https://manpages.debian.org/systemctl(1)>

•   Debian Wiki: systemd <https://wiki.debian.org/systemd>

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

AUTHOR
Maciej Delmanowski

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