DEBOPS.TIMESYNCD(5)

NAME
debops.timesyncd - Manage time synchronization using systemd-timesyncd

SYNOPSIS

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

DESCRIPTION

THe systemd-timesyncd(8) <https://manpages.debian.org/systemd-timesyncd(8)> service is a lightweight SNTP and NTP (Network Time Protocol) client developed as a part of the systemd <https://www.freedesktop.org/wiki/Software/systemd/> project. It provides time synchronization with NTP server network on hardware and virtualized hosts.

The debops.timesyncd Ansible role can be used to configure the systemd-timesyncd service. It will detect presence of alternative NTP clients/servers installed on the host and back off when they are detected, so that users can easily switch to a different service provider if they wish.

GETTING STARTED

  Configuration of preferred NTP servers

The systemd-timesyncd service can use NTP servers provided via DHCP or configured in the systemd-networkd service to perform time synchronization. If both cases are not defined, the service uses the NTP= and FallbackNTP= configuration options to find the preferred NTP servers. By default, Debian installation defines a list of {0,3}.debian.pool.ntp.org NTP servers to use if no others are specified.

Users can define their own preferred NTP servers in the Ansible inventory:

---
# File: ansible/inventory/group_vars/all/timesyncd.yml
# Needed to enable custom configuration deployment
timesyncd__deploy_state: 'present'
timesyncd__configuration:
  - name: 'NTP'
    value:
      - '0.pool.ntp.org'
      - '1.pool.ntp.org'
      - '2.pool.ntp.org'
      - '3.pool.ntp.org'
    state: 'present'

Timezone configuration is performed using the debops.tzdata Ansible role, via the tzdata__timezone variable.

  Support for container environments

The systemd-timesyncd.service unit contains a conditional check for a containerized environment (LXC, Docker, nspawn). Such environments don't have complete control over system clock, therefore inside of them the time daemon will not be started.

  Support for other NTP services

The role checks if one of the APT packages listed in the timesyncd__skip_packages variable is already installed on the host before doing any modifiaction on the system. If such package is detected, the role will skip further tasks to avoid messing up existing configuration.

  Example inventory

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

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

  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::timesyncd
    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.timesyncd default variables have more extensive configuration than simple strings or lists, here you can find documentation and examples for them.

  timesyncd__configuration

The timesyncd__*_configuration default variables define the configuration of the systemd-timesyncd service. You can find more details about systemd-timesyncd configuration in the timesyncd.conf(5) <https://manpages.debian.org/timesyncd.conf(5)> manual page.

The generated configuration will be located in the /etc/systemd/timesyncd.conf.d/ansible.conf config file. This file is not generated by default to fall back on the default configuration provided in the OS packages; to generate it the timesyncd__deploy_state variable needs to be set to present.

  Examples

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

  Syntax

The role uses the Universal Configuration system to configure systemd-timesyncd daemon. 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. FallbackNTP, PollIntervalMinSec), 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-timesyncd configuration file parameter. The case is important and should be the same as specified in the configuration file or the timesyncd.conf(5) <https://manpages.debian.org/timesyncd.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, an empty string or a YAML list which will be joined together using the space character.

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-timesyncd.service(8) <https://manpages.debian.org/systemd-timesyncd.service(8)>, timedatectl(1) <https://manpages.debian.org/timedatectl(1)>

•   Arch Linux Wiki: systemd-timesyncd <https://wiki.archlinux.org/title/systemd-timesyncd>

AUTHOR
Maciej Delmanowski

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