time_zone
time_zone sets the node's time zone with timedatectl on the node. The
time zone decides the local time that the node's programs show and log.
Keeping the clock itself right is the job of the node's time service,
systemd-timesyncd or chronyd. Manage the time service with an ordinary
systemd_service node task.
Inputs
name(string; required): a name from the time zone database, such as Europe/Berlin or UTC; a name the node's /usr/share/zoneinfo does not have fails before any change
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangevalue.time_zone_beforevalue.time_zone_after
What a dryrun reports
Supported; reads the time zone and reports the one that would be set; an unknown name fails.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Set the time zone
- time_zone:
name: Europe/Berlin
On the node, MMX reads the time zone from the link /etc/localtime. When the
node's time zone differs from Europe/Berlin, MMX sets Europe/Berlin with
timedatectl and reports the old and new time zones. When the node already
uses Europe/Berlin, the time_zone node task reports unchanged.
How it works
nameis a name from the time zone database, such asEurope/Berlin,America/New_York, orUTC.timedatectl list-timezoneson a node lists all names in the time zone database. A name that the node's/usr/share/zoneinfodoes not have fails the node task before anything changes, in a dryrun too.- MMX reads the time zone from the link
/etc/localtime, which programs use, not fromtimedatectl. A node without that link usesUTC. - Results and dryrun show
time_zone_beforeandtime_zone_afterin.this_node_task.value.time_zone_beforeis empty on a node whose/etc/localtimeis a copy of a time zone file instead of a link to one. - Running services read the time zone when they start. Changing the node's time zone does not restart running services. If a service must use the new time zone, explicitly restart the service, for example from a restart playbook.
Errors and what they mean
| The reason holds | What the error means, and what to do |
|---|---|
... is not a time zone in the time zone database /usr/share/zoneinfo; ... |
Check the spelling against timedatectl list-timezones. Nothing was changed. |
timedatectl is not installed; install the package systemd first |
Install the systemd package in an earlier node task. A dryrun reports the time_zone node task not checked, because an earlier node task may install systemd. |
the time zone database /usr/share/zoneinfo is not installed; install the package tzdata first |
Install tzdata in an earlier node task. A dryrun reports the time_zone node task not checked. |
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, AlmaLinux 10.
The suite tests/integration/node_settings.py runs on Debian 12 and 13, Ubuntu 24.04 and 26.04, Rocky Linux 9, and AlmaLinux 10, in containers on the first four and in virtual machines on the last two. The
validation record
has the latest results.
Why it works this way
- MMX reads the time zone from
/etc/localtime, not fromtimedatectl. After aset-timezonethat could not write the link (SELinux on a node whose files lack their labels),timedatedreports the new name while the node keeps the old one, and a retry took that for done.
This page is docs/reference/modules/time_zone.md in the MMX repository.