The Sysadmin & CLI Time Zone Guide
Under the hood of every Linux server, container host, and macOS workstation sits the IANA time zone toolchain.
Here is the production guide to compiling rules, dumping transition tables, troubleshooting NTP clock drift,
and controlling the POSIX TZ environment variable.
Compiles human-readable rule text into binary TZif files in /usr/share/zoneinfo/.
Disassembles and prints every historical clock shift, gap, and overlap for any zone.
Queries and configures system clock, RTC local/UTC state, and NTP network synchronization.
Audits stratum, root delay, offset error, and frequency drift in parts per million.
Interactive CLI Command Generator
Bash, Zsh & POSIX Shelltimedatectl status Unix Time Toolchain Reference
Production Patternstimedatectl • Modern Linux Clock Control
# Check current system time, UTC, RTC, and NTP synchronization
timedatectl status
# List all available IANA time zones
timedatectl list-timezones | grep -i tokyo
# Set system time zone (requires root / sudo)
sudo timedatectl set-timezone Asia/Tokyo zdump • Transition Table Dumper
# Dump all historical and future transitions for a zone
zdump -v America/New_York
# Limit dump to a specific historical year window (e.g., 2020 to 2030)
zdump -v -c 2020,2030 Europe/London zic • Zone Information Compiler
# Compile tzdb source files into /usr/share/zoneinfo directory
sudo zic -d /usr/share/zoneinfo northamerica europe
# Compile with strict 64-bit TZif3 output and POSIX string footer
zic -b fat -d ./build/zoneinfo custom_rules.tz POSIX TZ Variable Overrides
# Execute a single command under another time zone without changing system state
TZ="Asia/Tokyo" date
# Run a Node.js or Python backend in a specific time zone
TZ="America/New_York" node server.js
# Explicit POSIX rule syntax without filesystem lookup (std, offset, dst, rules)
TZ="EST5EDT,M3.2.0,M11.1.0" date chronyc • Network Time Protocol Audit
# Check Chrony NTP synchronization sources, stratum, and jitter
chronyc sources -v
# Inspect system tracking drift in parts per million (PPM)
chronyc tracking Filesystem Architecture & Symlinks
How OS Locates Zone Data| Path | Role & File Type | Platform | Description |
|---|---|---|---|
| /etc/localtime | Symlink to /usr/share/zoneinfo | Linux • macOS • BSD | The system-wide canonical time zone definition read by C standard library functions (tzset, localtime). |
| /etc/timezone | Plaintext file (legacy) | Debian • Ubuntu (Legacy) | Contains the raw IANA string name (e.g. America/New_York). Largely superseded by systemd. |
| /usr/share/zoneinfo/ | Directory of binary TZif files | Unix • Linux • macOS | Hierarchical tree of pre-compiled time zone binaries created by the zic compiler. |
| /usr/share/zoneinfo/leapseconds | Plaintext table | Linux • IANA tzdb | List of historical leap seconds applied to TAI to maintain UTC synchronization with Earth's rotation. |