Time

Start by asking timed, the service that keeps the machine's clock, what it is doing:

$ clock status
$ clock sources

These commands inspect the clock; they do not change it. In clock status, read state, time zone, following, accuracy and the age of the last update. In clock sources, look for a chosen source, contributing candidates, authentication and any failure notes. The clock command reference explains each field and the command's exit statuses.

Choose the next step from what you find:

• The displayed time is in the wrong zone: check the effective time zone before changing the machine clock. The clock runs in UTC; a zone changes how programs show it. Follow the time-zone procedure.
• The machine is unsynchronised or sources are failing: inspect the configured policy and each source's state in configuring time sources. If status says Automatic is 0: the clock is set by hand, automatic time is disabled.
• The state is settling or spike: timed is still converging or checking a large change. Read the status meanings before intervening.
• There is no suitable time server: use the manual-time procedure. Check the zone and the consequences of a clock jump first.

After a change, run both inspection commands again. A saved setting or a successful reload does not by itself establish synchronisation. Check the effective zone, source list, authentication, state, accuracy and fresh updates rather than relying only on the displayed wall time.

Setting the clock needs SeSystemtimePrivilege. timed's service identity holds it, and so do Administrators. timed runs from boot and keeps the clock from network time servers. Changing it behind timed's back can lead to a correction or a refusal of an excessive offset; see why not just set the clock. Registry changes and timed control requests have separate permission checks.

Why this is worth caring about #

A wrong clock does not look like a wrong clock. It looks like:

• certificates that are expired, or not yet valid, and TLS that fails for reasons that make no sense;
• Kerberos tickets refused across a domain, because Kerberos treats a clock skew as evidence of a replay;
• logs from two machines that cannot be put in order, which is exactly when you most need them to be.

So time is not a convenience. It is something several other things quietly depend on, and an attacker who can move it has more than a wrong clock.

Sources are not trusted individually #

timed compares several servers. Each one reports not just a time but an interval in which it estimates the true time lies, and timed looks for the largest set of intervals that overlap. A server outside that overlap is a falseticker and is discarded, however confident it sounded.

This can reject a wrong source whose narrow interval disagrees with the others. It is not a guarantee that the agreeing sources are correct: shared upstream clocks, operators or network failures can give several sources the same error. Authentication identifies a source; it does not prove that source's clock is right.

Configure at least three sources with independent failure modes. With one, there is nothing to compare it against. With two that disagree, timed reports itself unsynchronised rather than choosing between them. Three can let an agreeing, correct majority exclude one wrong source, provided those assumptions hold. Counting three names alone does not establish that independence.

Every source is authenticated #

By default timed will not use a source that cannot prove who it is. That is NTS (RFC 8915): a TLS handshake on port 4460 establishes a pair of keys, and every NTP packet afterwards carries a tag computed with them. Forging a reply requires the key.

The certificate is validated against the machine's trust store, over trustd's socket — so a certificate authority you distrust is distrusted here too, immediately, without timed needing to be restarted.

When timed needs a new NTS handshake, a network that blocks port 4460 prevents that exchange. Cached cookies can avoid a fresh handshake, as explained below; blocking the port does not by itself mean existing authenticated time is lost. If no usable sources remain, the machine reports itself unsynchronised. AllowUnauthenticated exists for networks where that is not acceptable; see configuring sources for what you give up.

The default sources #

The documented shipped fallback set uses four names in our own zone, when no earlier source selection supplies a list:

0.time.peios.org    →  time.cloudflare.com
1.time.peios.org    →  nts.netnod.se
2.time.peios.org    →  ptbtime1.ptb.de
3.time.peios.org    →  ptbtime2.ptb.de

The list is intended to span three operators in three jurisdictions: a commercial network, a Swedish national infrastructure operator, and Germany's national metrology institute. Two of the names are from the same operator; four names are not four independent sources. Operator variety reduces a shared failure risk, but is not proof of independent upstream clocks or correct time. Check clock sources for what the machine actually selected and can reach.

The indirection through time.peios.org is deliberate. If an operator withdraws its service, that is a DNS change rather than a new image for every machine.

Two circles, and how they are broken #

Both are worth knowing about, because both look like bugs when you meet them.

NTS needs TLS; TLS needs a clock. A machine with a dead RTC battery may boot reading 1970. Otherwise valid certificates can then appear "not yet valid", blocking the handshake that would obtain authenticated time. timed sets a lower bound at its own build timestamp, reported as floor in clock status. The clock-step event reference calls this boot-floor and explicitly says the real time is not yet known.

The floor is a bootstrap aid, not current time or a guarantee that TLS will succeed. A remote server's certificate still has to be valid at the clock's reading and trusted by the machine. Reachability, authentication and source agreement still matter, so do not assume the first poll will fix the clock. If it remains on the floor, inspect the source failure notes rather than treating the build date as a verified time.

A fresh handshake needs a clock too. So the cookies from the last one are kept under /var/state/timed, and a reboot usually needs no handshake at all. The startup hook establishes a complete protected, inheritable descriptor before creating the cookie directory: SYSTEM, Administrators and timed's service SID have access. Inherited public read grants are removed from the state directory; a Unix mode on a cookie file is not the security boundary.

Steering, not jumping #

Once the time is known, timed slews the clock: it changes the rate slightly so the error is absorbed over the next few minutes. A great deal of software quietly assumes the clock only goes forwards, and stepping it backwards breaks timers, file timestamps and anything measuring a duration.

The documented automatic discipline permits steps in these situations:

• at startup, once, however large the correction, when usable sources agree;
• after fifteen minutes of consistent disagreement, when the offset is too large to slew away. Fifteen minutes because a congested network or a server having a moment looks exactly like a genuine step until time passes, and stepping the clock on a transient is worse than being slow to correct a real one.

An offset larger than a thousand seconds appearing after the machine was synchronised is refused outright and logged loudly. A machine that far out has a problem a time client should not paper over.

Manual sets and the boot floor are also clock steps. Turning automatic time back on starts the sources afresh and can cause an initial correction of any size. Plan for that jump before re-enabling it; source changes and reloads are not a promise of uninterrupted wall-clock time.

Every step is recorded in the event log as a timed.clock.stepped event, with the clock's reading just before and just after it, so a jump in the times of other records can be explained. Its operation.name says which step it was: automatic for timed's own, manual for a clock set by hand, and boot-floor for the clock raised to the build's timestamp at startup (see Two circles, and how they are broken). Its subject.token.sid is whoever acted: the person who asked, for a manual set, and timed's own service SID for the other two. Slewing is not recorded. The event is essential, so the emission policy cannot switch it off.

Learning the crystal #

The clock is a crystal running at the wrong rate — consistently wrong, by some tens of parts per million. timed learns that rate and writes it to /var/state/timed/drift, so the next boot starts with the previously learned rate rather than learning it entirely from scratch. This can shorten settling time; it does not guarantee a particular accuracy after one poll.

The rate estimate also helps when the network goes away. Holdover still depends on how stable the crystal remains and how accurate that estimate was. Use the reported state and accuracy rather than assuming a fixed period of correct time without sources.

What timed does not do #

It is not a time server. It listens on no network port and initiates every conversation it takes part in. Serving time to other machines will be a separate, unprivileged package — the client holds the dangerous privilege, and a server is exposed to the whole network and needs no privilege at all. Keeping them apart is the point.

It does not touch the hardware clock directly. Once timed reports the clock as synchronised, the kernel writes it back to the RTC every eleven minutes on its own.

It does not decide how the time is shown. The clock runs in UTC. The time zone, Machine\System\Time TimeZone, sets the machine's default local zone; timed copies the chosen zone into /etc/localtime as the default local-zone data. For command-specific UTC or TZ choices, see the time-zone guide.

Inspect the clock and the sources before changing policy:

$ clock status
$ clock sources
$ reg get Machine/System/Time

clock shows timed's current state; reg get reads the effective registry values. Check Automatic, Servers, AllowUnauthenticated and UseFromDHCP against the sources actually shown. If status says Automatic is 0: the clock is set by hand, follow the manual and automatic time procedure before expecting source updates. A wrong displayed zone is a time-zone setting, not by itself a reason to replace sources.

Everything about where a machine gets its time is under Machine\System\Time. There is no configuration file, and clock writes no policy. Change it with reg, or System Settings' Time Servers group in Time & Date, which writes the same values.

Policy changes need registry write access to Machine\System\Time. clock reload and clock set separately need the control right on timed's control object. Having one does not imply the other; see when reload is refused. Inspection through clock is available to everyone under the default descriptor.

When something is wrong #

$ clock sources
  source                   state        auth   str reach     offset     delay     last
* 0.time.peios.org         system-peer  nts      3   377   -1.204ms   14.2ms       31s
+ 1.time.peios.org         candidate    nts      2   377   -0.918ms   22.7ms       44s
x 2.time.peios.org         falseticker  nts      2   377   +4.102s    18.1ms       12s
  3.time.peios.org         unreachable  nts     16     0       +0ns       0ns         -
    NTS-KE failed: connecting to 192.0.2.9:4460: Connection refused

• falseticker — this server disagrees with the others. Investigate it and the agreement among the other sources; disagreement is not by itself proof of which clock is correct.
• unreachable — no reply for eight polls. The note says why.
• reach is the last eight polls in octal, newest in the low bit: 377 is eight for eight, 376 means the newest poll was missed, and 0 means no replies in that window.

In the example, the final source failed to connect for NTS key exchange on port 4460. Investigate the reported failure before changing authentication policy. A source missing from the list may have a malformed configuration entry; check the log for a warning. The clock reference describes the other states, authentication, poll history and failure notes.

If clock cannot reach timed, the command failed to inspect the clock; that is different from a successful query reporting no usable sources. Keep the error and check the exit status before deciding what to change.

Naming your own servers #

Each entry is a host, optionally host:port, optionally followed by option words:

prefer breaks ties and nothing more. A preferred source that disagrees with the majority is still discarded — a preference is a statement about which server to lean on, not a licence to be wrong.

A misspelled option is an error and the entry is ignored with a warning in the log, rather than silently doing nothing. clock sources will show the entry missing.

Choose NTS-capable servers unless you have deliberately accepted the tradeoff in turning authentication off. Source changes affect future corrections, so plan for their effect on work that depends on timestamps. A successful reload does not guarantee that the clock will only slew; see steering, not jumping.

For example, to replace the source list with three servers you operate, pass multi: one comma-separated data token, as in reg's value syntax:

$ reg set Machine/System/Time Servers multi:'dc01.corp.example,dc02.corp.example,ntp3.corp.example'
$ clock reload

Precedence is first match, not merge #

Servers  →  DHCP, if enabled and offered  →  the shipped fallback set

That is the selection order in the inspected timed 0.1.10 source. A separate domain-discovery tier is mentioned as a future version in its configuration comments; it is not implemented in this selector. A domain policy that writes Servers still takes effect as registry configuration. This is a pinned source finding, not verification of an installed image.

The first nonempty list is the whole list. Servers means entries that parsed successfully; if all are malformed, there is no explicit list and selection continues. A valid explicit list replaces the fallback set. Authentication filtering happens after selection: if the selected list contains only plain-NTP sources and AllowUnauthenticated is 0, those sources are excluded without falling through to public NTS servers.

To remove an explicit override, delete the value. This restores selection by the chain above: DHCP can take precedence when enabled and offered, and the shipped fallback is used only if no earlier choice supplies a list. Deletion does not necessarily select public servers:

$ reg del Machine/System/Time Servers
$ clock reload

Turning authentication off #

AllowUnauthenticated is 0 by default: a source must prove who it is or it is not used.

What you give up is worth being clear about. Without NTS, the only thing standing between you and a forged reply is that the server must echo the exact 64 bits timed put in its request — a random number, so an attacker who cannot see the request cannot guess it. An attacker who can see it can forge freely and move your clock wherever they like.

The reason to think twice is that a wrong clock is not a self-contained problem: certificate validity, Kerberos, and the ordering of your logs all rest on it.

Reasonable uses: an isolated network with its own stratum-1 appliance; a lab; a machine behind a firewall that blocks port 4460 where you control the path anyway.

For an explicitly configured plain-NTP source, both the per-source unauthenticated (or noauth) word and the machine-wide AllowUnauthenticated value are needed. The word identifies the plain source; the value permits its use. Setting AllowUnauthenticated back to 0 excludes all unauthenticated sources, including per-source exceptions; it does not disable authenticated sources.

The following example replaces the entire source list with one unauthenticated server. Use it only if that is the intended policy; it provides no comparison against independent sources:

$ reg set Machine/System/Time AllowUnauthenticated dword:1
$ reg set Machine/System/Time Servers multi:'ntp.lan unauthenticated'
$ clock reload

DHCP time servers #

UseFromDHCP is 0 by default, as on Windows. DHCP sources are eligible only when no successfully parsed explicit Servers list supplies names, according to the source-qualified precedence above. They are unauthenticated, so they also require AllowUnauthenticated to be 1. Enabling UseFromDHCP alone does not meet that authentication policy.

Before enabling this, decide whether you trust the network's time servers. On a network you do not control, a DHCP server can offer an attacker's time source. The setting follows the machine to other networks; it is most appropriate for a machine that only attaches to networks you run. The authentication tradeoff applies.

$ reg set Machine/System/Time UseFromDHCP dword:1

This changes eligibility; it does not override a valid Servers list, enable unauthenticated time by itself, or prove DHCP offered a usable source. netd's resolver channel reports DHCP option 42 time servers independently of Dns.Offered; timed decides whether to use them under its own policy. Reload after the intended policy changes and verify the selected list and auth column. Do not delete a working explicit list merely to make DHCP take precedence.

Poll intervals #

MinPoll   default 6    64 seconds
MaxPoll   default 10   about 17 minutes

Both are powers of two seconds, and both are clamped to the range 4 to 17. timed lengthens the interval towards MaxPoll while the clock is being held steadily and shortens it when the offset starts moving.

There is rarely a reason to change either. Lowering MinPoll makes recovery from a disturbance faster and costs the servers more traffic; a long interval measures the crystal's rate better than a short one measures its phase, and it is the rate estimate that holds the clock right between polls anyway.

The floor of 4 is not negotiable. A configuration error must not be able to turn a machine into a nuisance at somebody else's public server.

Doing it from a domain #

Every value here is an ordinary registry write, so distributing time policy to a fleet is an ordinary policy push. There is no separate mechanism and nothing timed-specific to learn.

Reload and verify #

After the intended registry changes, ask timed to reread them and inspect the result:

$ clock reload
$ clock status
$ clock sources

Check that the expected sources are present, their authentication matches the policy, and the failure notes are resolved. Then check the state, following source, accuracy and age of the last update. settling can be normal while the frequency estimate converges; inspect again as polls arrive rather than treating a successful reload as synchronisation.

If reload is refused, preserve the exact error and check the separate control permission. Do not assume a failed reload undid a registry write. If sources are missing or still rejected, return to when something is wrong and compare stored policy with timed's reported state before making another change.

The clock always runs in UTC. The time zone is how the time is shown: the offset from UTC, and when summer time starts and ends, for one place. The machine has a default time zone. Programs can show time in another zone: use date -u for UTC, or env for a one-command TZ override in programs that honor it.

Before changing the machine's default, inspect clock status and clock sources: a wrong zone changes the display, while an unsynchronised clock needs a source or manual-time correction. Inspect the reported zone and any timed errors rather than assuming a saved choice took effect. An unexpected UTC report can also mean that timed could not identify the existing file; see the terminal checks.

To choose a 12- or 24-hour display for your own top-bar clock, use Desktop Settings' Time Format.

In System Settings #

System Settings, from the launcher, has the machine's time in its Time & Date section. A choice from a list or a switch applies the moment it is made; one that can't be is put back, and the line along the bottom of the window says why.

• At the top is the time here, the zone and how far it is from UTC, and whether the clock is synchronised, and with which time server.
• Time Zone lists the zones by region and chooses the machine's default. The desktop's clock shows the chosen zone from the next minute. UTC takes it away.
• Set Time Automatically is on until you turn it off. Then a date and a time open under it, in the zone chosen, with Set Clock. Turning the switch on again goes back to the time servers. It starts them afresh and can jump the clock by any size when sources agree. Plan for the effect on timers, file timestamps and log ordering before switching it on.
• Time Servers are where the time comes from: Change… opens the list under its row, and Allow Unauthenticated Servers, Use Network Time Servers and the minimum and maximum poll intervals apply as they are changed. See configuring time sources. Server Status lists each server: whether it is in use, a candidate, or rejected, whether it is authenticated (NTS), its offset, and when it was last heard.

Changing the settings needs write access to Machine\System\Time, which as shipped only Administrators have. Anyone else sees all of it, and the section says once, at the top, why they can't change it. Asking timed to set the clock or reload separately needs its control right, granted by default to SYSTEM and Administrators. The control descriptor and the registry key's write permissions are separate checks.

After a change, check the zone and synchronisation shown at the top, and Server Status when using automatic time. A saved setting is not proof that a source has been accepted or that the clock has synchronised.

In a terminal #

The time zone is Machine\System\Time TimeZone, a name from the tz database such as Europe/London, America/New_York or Asia/Kolkata:

$ reg set Machine/System/Time TimeZone sz:Europe/London
$ clock status | head -2
generation   12
time zone    Europe/London

timed applies the chosen zone to /etc/localtime after observing the registry change. A name that isn't a zone on this machine is refused before the copy and logged, leaving the previous file in place. On restart, timed identifies that previous zone only when its saved name and the installed zone file still match the copy. In the inspected timed 0.1.10 source, an unidentified existing zone file is reported as UTC; see the status limitation. timed tries a refused name again every ten minutes and whenever the time settings change, so a zone that a tzdata update adds is taken up without setting the value again. Deleting the value requests UTC.

If status unexpectedly shows UTC after a restart or a failed zone change, inspect timed's log for zone-copy or saved-name errors before setting a local time. The zone file must already have been prepared by timed's pre-start hook; a failed write is not the same as an invalid zone name. An error after the file was truncated can leave it incomplete, even while status retains the previous name. Do not treat that name as a fresh check of the file after a write failure.

The names are the files under /usr/share/zoneinfo, from the tzdata package. zone1970.tab there lists the ones worth choosing between, one per region whose clocks have agreed since 1970.

To set the clock yourself, first inspect the zone reported by clock status and resolve an unexpected UTC report or zone-copy errors as above. You need registry write access to turn automatic time off and timed's control right to set the clock. A manual set is a jump: plan for its effect on timers, file timestamps and log ordering before proceeding. Then turn off setting it automatically and ask timed:

$ reg set Machine/System/Time Automatic dword:0
$ clock set 2026-10-04 14:05
the clock is set

clock set takes a local time, in the machine's zone. timed refuses while Automatic is 1, since its next poll would put the clock back. Inspect clock status after the set: check the reported zone and the Automatic is 0: the clock is set by hand indication. Manual time is not network synchronisation.

Setting Automatic to 1 again starts the time servers afresh. Once usable sources agree, the initial correction can be of any size. Plan for that clock jump before re-enabling automatic time. Afterwards, run clock status and clock sources and check the selected sources, authentication, state, accuracy and fresh updates. Re-enabling the setting does not itself prove synchronisation.

Why not just set the clock? #

Administrators hold SeSystemtimePrivilege, so date -s would set the clock. timed would then measure the clock as wrong by that much and put it back, and if it was more than 1000 seconds after timed had been keeping the clock, it would refuse to follow its own sources and log it as a problem. Asking timed is what keeps the two in agreement.

A clock set by hand is written to the hardware clock within eleven minutes, so it survives a reboot.

Asking timed also leaves a record. Each set is a timed.clock.stepped event with operation.name manual, the clock's reading just before and just after, and the SID of whoever asked in subject.token.sid. date -s leaves none: the clock moves underneath every record without anything saying so.

clock reads over timed's socket and prints. It writes no policy — time policy is registry configuration, and reg is how a registry value is set. Registry writes and timed's control requests have separate access checks. The two verbs that act are reload, and set, which asks timed to set the clock while it isn't being set automatically; see when reload is refused.

It is called clock and not time because time is a shell keyword: time status would run status and report how long it took.

Verbs #

status is the default, so bare clock is clock status.

Status #

$ clock status
generation   118
time zone    Europe/London
state        synchronised
following    1.time.peios.org (stratum 3)
offset       -412.0us
frequency    -12.750 ppm
jitter       +180.3us
accuracy     within 31.4ms
  root delay      28.2ms
  root dispersion 4.10ms
sources      4 configured, 3 contributing
updates      118 (last 22s ago)
stepped      +2.1d in total since start
floor        1788142329 (the build timestamp; the clock is never set below it)

time zone is the name timed has recorded for /etc/localtime. In the inspected timed 0.1.10 source, restart identification requires the saved name and zone data to match that file. If identification fails, the command prints UTC (none chosen) even though the file may contain another zone. A later successful apply restores the reported name. After a copy failure, the retained name is not a fresh verification of the file either. Check timed's log and the time-zone procedure before relying on an unexpected display. This is source inspection, not installed-image validation.

state is the field to read first:

accuracy is timed's estimate of how wrong this machine's time might be, combining the reported uncertainties between here and the reference clock. Check it when investigating Kerberos clock skew. It depends on the source measurements and is not independent proof that the time is right.

frequency is what the crystal is doing, in parts per million, and it is persistent — it is written to /var/state/timed/drift and read back at the next boot. Tens of ppm is an ordinary machine. Approaching ±500 means the hardware is at the edge of what the discipline can correct.

stepped can be non-zero after a boot on a machine whose clock was wrong. Later growth means there have been further steps; check whether these followed a manual set or re-enabling automatic time. Unexpected or repeated growth warrants investigation. The clock-step event reference explains how to tell manual, automatic and boot-floor steps apart.

floor is the build timestamp, the lower bound timed will use. If the clock remains there after boot, it may not yet have acquired real time. The floor does not establish synchronisation or guarantee a successful TLS handshake; inspect the source notes and see the bootstrap explanation.

Sources #

$ clock sources
  source                   state        auth   str reach     offset     delay     last
* 1.time.peios.org         system-peer  nts      2   377   -0.918ms   22.7ms       44s
+ 0.time.peios.org         candidate    nts      3   377   -1.204ms   14.2ms       31s
- 3.time.peios.org         outlier      nts      2   377   +8.221ms   61.0ms       58s
x 2.time.peios.org         falseticker  nts      2   377   +4.102s    18.1ms       12s

* system peer  + candidate  - outlier  x falseticker  ? unusable

auth is nts or none. none means anyone on the path can forge that source's replies.

reach is the last eight polls as an octal bitmask, newest in the low bit — the classic NTP display. 377 is eight for eight; 376 means the most recent poll was missed; 0 means nothing for eight polls, at which point the source's stored measurements are discarded rather than left to vote with stale numbers.

last is how long ago the source answered. It exceeding the poll interval by much is the first sign of trouble.

A source that is not contributing prints a note underneath saying why.

Setting the clock #

$ clock set 2026-10-04 14:05
the clock is set
$ clock set 2026-10-04T14:05:30
$ clock set @1791122700

The time is local, in the machine's time zone, to the minute or the second, or @ and a number of seconds since 1970 in UTC. timed sets the clock only while Machine\System\Time Automatic is 0; otherwise it keeps the clock from its sources, the next poll would put it back, and it refuses:

$ clock set 2026-10-04 14:05
clock: the clock is kept from its sources; set Automatic to 0 to set it by hand

Like reload, it needs the control right. Changing Automatic needs registry write access separately. A manual set jumps the clock and changes the basis of later timestamps. Check the zone and plan for that jump before setting it, then inspect clock status; see the complete procedure.

Exit statuses #

The separation of 2 from 1 is what lets a script tell "this machine has no time sources" from "I could not find out".

When reload is refused #

$ clock reload
clock: not permitted

reload and set need the control right on timed's control object. Reading does not: what time the machine thinks it is, and how well it knows, is not a secret, and a program deciding whether the clock is trustworthy enough to validate a certificate should not need a privilege to find out.

The descriptor is Machine\System\Time ControlSecurity; by default SYSTEM and Administrators may control, and everybody may query. This is distinct from write access to the registry key: a successful policy write does not prove that the caller may reload or set the clock, and a refused reload does not undo that write.