Skip to content
Documentation
State Modules
timezone

timezone

Manages the system timezone. The declaration name is the desired IANA zone (e.g. America/New_York, UTC, Etc/GMT+5); it takes no module parameters. Idempotent: re-applying an already-set zone reports no change.

Category: System config

States

StateMeaning
presentThe system timezone is set to the declared zone (/etc/localtime symlinks into the zoneinfo tree).

Examples

Set the system timezone to UTC 

timezone:
  UTC:
    state: present

Set a region/city zone

The declaration name carries the IANA zone name.

timezone:
  America/New_York:
    state: present

Order after a package install

The require requisite applies the zone after tzdata is present.

timezone:
  Europe/London:
    state: present
    require:
      - package: tzdata

Notes

  • Linux only; non-Linux platforms return an unsupported-OS error.
  • timedatectl is used when present (validates the zone, updates the symlink and running offset); otherwise the module symlinks /etc/localtime to the zoneinfo file and writes /etc/timezone, which is what Alpine and systemd-less Debian expect.
  • The zone must exist as /usr/share/zoneinfo/<zone> on the target host; a missing zone fails at apply time.
  • Takes no module parameters beyond the reserved severity override; the zone is the declaration name.
  • Out of scope for v0.1: NTP-sync coupling (timedatectl set-ntp), localtime copy mode (copying the zoneinfo file instead of symlinking), and macOS.
sysctlarchive