FreeBSD Time Zone Operations: Keep Wall Clocks, Logs, and Schedules Consistent

A FreeBSD host has a clock value and a policy for displaying that value. The kernel keeps time independently of the local civil-time zone; utilities render it using the installed time-zone database, normally selected by /etc/localtime. Changing a zone changes presentation and civil-time rules, not the instant stored by the clock. Keeping that distinction clear prevents an operator from “fixing” a display problem by manually moving a correctly synchronized system clock.

Time-zone errors show up in rotated logs, cron schedules, database timestamps, certificates, and incident timelines. A good change therefore verifies more than the abbreviation shown by date. It confirms the intended IANA zone, checks UTC and local output, examines the hardware-clock policy, and tests the applications whose schedules matter. Time synchronization is a separate system: ntpd or another time service disciplines the clock, while the zone controls local rendering.

Record the clock state before changing policy

Collect the release, current zone selection, UTC time, and local rendering before running an interactive setup tool:

freebsd-version -kru
date
date -u
ls -l /etc/localtime
readlink /etc/localtime

On some installations /etc/localtime is a regular copied file rather than a symbolic link, so readlink can legitimately produce no path. The file itself and the output of date remain useful evidence. Do not assume the system is on UTC because a server is physically located in a UTC region; administrators sometimes select another zone for application compatibility or legacy scheduling.

Choose one authoritative source for local-zone policy. A global /etc/localtime is appropriate when the machine is intended to have one system-wide presentation zone. Per-command or per-service TZ settings are useful when a specific program needs a different display convention, but they should be documented as an exception. A process environment can override the default zone and make its output differ from an interactive shell without changing the host configuration.

Select a supported zone with tzsetup

The supported system utility for selecting the local zone is tzsetup(8). Run it from a console or a stable administrative session and select the region and city whose civil rules match the system’s intended jurisdiction:

tzsetup

The utility reads the installed time-zone data, presents a menu, installs the selected zone as the system default, and considers whether an adjustment is needed when the hardware clock does not keep UTC. Record the selected region/city identifier, not only an abbreviation such as CST or IST. Abbreviations are reused for unrelated zones and can change meaning across contexts; an IANA name such as America/Argentina/Cordoba communicates the rule set more precisely.

For a noninteractive repair workflow, inspect the installed tzsetup manual before using its flags. In particular, -n is a no-write mode and -r reinstalls the zone selected previously according to the recorded selection. Those are not interchangeable with an ordinary zone change. Avoid copying /etc/localtime from another machine: that can silently import the wrong jurisdiction or an older database revision. Use the operating system’s installed zone data so that the selected name and rules remain interpretable.

After the selection, inspect the local-time output and compare it with UTC:

date '+%Y-%m-%d %H:%M:%S %Z %z'
date -u '+%Y-%m-%d %H:%M:%S UTC'
env TZ=America/Argentina/Cordoba date '+%Y-%m-%d %H:%M:%S %Z %z'

The final command is a process-scoped rendering test. It does not change /etc/localtime or the system clock. Replace the sample zone with the intended IANA identifier. If the first and third outputs unexpectedly differ, inspect shell startup files, login-class environment, service definitions, and scheduled-job environments for TZ overrides. If the local output falls back to UTC or shows an unexpected abbreviation, verify that the zone file is valid and that the installed time-zone database contains the expected name.

Separate wall-clock discipline from time-zone rendering

Time zone and NTP solve different problems. NTP compares the host clock with configured time sources and adjusts clock error; it does not select the site’s civil-time zone. Conversely, tzsetup does not make an inaccurate clock accurate. Check both independently:

date -u
service ntpd status
ntpq -pn

The exact time daemon and its tools depend on the host’s configuration. A host may use another NTP client, an appliance-provided clock service, or a virtual-machine time source. Inspect the enabled service and its actual logs rather than treating an absent ntpd process as proof that the clock is unsynchronized. The FreeBSD FAQ’s advice to use tzsetup addresses the zone selection, while the ntpd manual describes network time synchronization.

Compare machine timestamps in UTC when correlating events across hosts. UTC avoids a presentation shift when machines use different local zones and avoids confusion during civil-time changes. Keep local time for operator-facing reports when that is the team’s convention, but preserve offsets or use unambiguous timestamp formats in logs and incident records. A string like “01:30” without a date, offset, or zone can refer to two distinct instants during a fall-back transition.

Validate daylight-saving and civil-time rules

Do not hard-code a permanent UTC offset for a geographic zone. The installed time-zone rules represent historical and future civil-time changes, including regions that change policy. If a jurisdiction abolishes daylight saving or changes its offset, the operating system may need updated tzdata from its supported update channel. Installing a new package or base update is a change-management action; first identify whether this host gets time-zone data from the base system or an installed package, then apply the corresponding documented update procedure.

Validate representative dates with process-scoped conversions rather than changing the system clock. The date utility accepts TZ for the output zone and can parse an input with -j and -f without setting the live clock. Use the date manual’s exact input format, and record that ambiguous or nonexistent local wall times near a clock transition may not map to a single intuitive instant:

TZ=UTC date -j -f '%Y-%m-%dT%H:%M:%SZ' '2026-01-15T12:00:00Z' '+%Y-%m-%dT%H:%M:%S%z'
TZ=America/Argentina/Cordoba date -j -f '%Y-%m-%dT%H:%M:%SZ' '2026-01-15T12:00:00Z' '+%Y-%m-%dT%H:%M:%S%z'

Both commands parse the same UTC instant but request different output zones. Compare the result against the time-zone database version and an authoritative civil-time source if exact legal scheduling matters. A passing test proves only that the installed rules render that sample; it does not prove that a recurring task behaves correctly through every future rule change.

For cron, at, application schedulers, and database jobs, identify whether the schedule is expressed in local wall time or UTC and consult that scheduler’s manual for behavior when local time jumps forward or backward. A task scheduled for a skipped wall-clock minute may not run at the expected apparent time; a repeated minute may be observed twice depending on the scheduler’s policy. Do not infer exactly-once scheduling from a timestamp string. Prefer UTC scheduling for elapsed-time automation when the business requirement is a stable interval, and use the explicitly intended local zone for human-calendar events.

Diagnose conflicting timestamps without changing the clock

When one log disagrees with another, determine the producing process and timestamp format before modifying the host. Capture date, date -u, the process environment where available, the service configuration, and the raw log record. Applications can emit UTC, local time, or an offset-bearing timestamp independent of the shell’s current setting. A syslog receiver may also apply its own parsing or presentation rules.

Check whether the event is a clock error, a zone-policy difference, or a formatting ambiguity. If UTC values disagree by a persistent offset, inspect clock synchronization and virtual-machine host time. If UTC agrees but local labels differ, inspect TZ and /etc/localtime. If the record lacks a numeric offset and occurs near a daylight transition, the data may be ambiguous even if both clocks are correct. Preserve original logs before applying changes so the incident record remains auditable.

Do not run date with a set-time operand to repair a zone display. Manually stepping a production clock can disrupt certificate validation, leases, database transactions, log ordering, and scheduled work. Correct the zone with tzsetup; correct synchronization using the approved time service; coordinate any real clock correction with the service owner and verify its impact.

Operational acceptance and change record

An accepted change has a documented intended zone name, a valid installed zone definition, expected local output, correct UTC output, and a verified process-level override policy. The host clock should remain synchronized by its designated service, and scheduled applications should use a documented time basis. Test at least one date in each relevant seasonal rule period and review the plan for DST-boundary jobs.

Record the FreeBSD release, chosen IANA zone, before-and-after date output with offset, time-service state, any TZ overrides discovered, and the source used to validate civil-time rules. If the server hosts applications that persist local timestamps, coordinate with their operators before changing global policy. A successful date command alone does not prove that every daemon has reloaded its environment or that a database’s time-zone tables match the operating system.

Keep the distinction between instant and representation explicit in runbooks. Store event instants in UTC where supported, retain the offset when presenting a local timestamp, and never use an ambiguous abbreviation as the only zone identifier. These habits make FreeBSD hosts easier to compare across regions and reduce avoidable ambiguity during incident response.

Related:

Sources: