NTP.TOML(5)

📦
version 1.9.0 · 6 versions
, in arch rolling, nixpkgs unstable, ubuntu stonking

💖 NAME 💖

ntp.toml — bestie, this is the configuration file for the ntpd-rs ntp-daemon. That's it, that's the whole vibe check. 💅

✨ DESCRIPTION ✨

Okay so, configuring ntpd-rs happens in the ntp.toml configuration format. The TOML format is in lots of ways similar to a simple INI with several extensions allowing a JSON-like syntax. fr fr, it's giving INI's cooler cousin who went to art school. 🎀

The ntpd-rs configuration file consists of several sections, each of which configures a separate part of the ntp-daemon process. Each of the sections is described in the rest of this document. Many settings will have defaults, which will be indicated by each configuration setting shown. So whenever you see a default in parentheses next to a setting, that's the little guy who shows up if you don't say anything. 🫶

The NTP daemon only supports unicast client-server connections. Most NTP traffic, especially across the public internet, almost exclusively uses this mode, so it is not considered a practical limitation for most scenarios. Not me worried about missing modes — it's literally fine, this is the mode everybody uses anyway. 😌

🌈 SOURCE MODES 🌈

Different types of sources (see the section below for details) are supported by the NTP daemon. To set the type of the source, you can configure the mode field with any of these options:

  • server — A server source connects to a single specific NTP server. If a connection is lost, attempts will be made to reconnect to the source. Loyal, monogamous, one-server energy. 💖
  • pool — A pool source retrieves multiple NTP servers by resolving a hostname via DNS. It then attempts to connect to multiple of these servers at the same time. If a connection is lost, a new server will be retrieved from the pool. It's giving group chat, not a situationship.
  • nts — Connect to a single Network Time Security (NTS) source. The NTS protocol uses a TLS handshake to exchange secrets with a server to allow verifying that NTP messages have not been tampered with. Note that the TLS protocol requires that both the client and server have a rough idea of the current time. Security girlies, this one's for you. 🔐✨
  • nts-pool — Connect to a pool of Network Time Security (NTS) sources. This is currently experimental, and may change in backwards incompatible ways. Okay so it's in its beta era, don't get attached to the exact behaviour. 🙈
  • sock — A sock source connects to a GPSd socket to get timing data from GPS receivers. Note that GPSd must be (re-)started after starting ntpd-rs for GPSd to connect to the socket. Yes, the restart order is a whole thing. Don't skip it. 💀
  • pps — A PPS source connects to a Pulse Per Second device, which is by default assumed to send a pulse every rounded second. As these devices only provide periodic data, they do not count towards minimum-agreeing-sources. Important!!! They literally don't get a vote. 👑

🛠️ CONFIGURATION 🛠️

🌸 [source-defaults] 🌸

Some of the behavior of a source is configurable. You can set defaults for those settings in the [source-defaults] section. Think of it as the setting the vibe for every source so you don't have to repeat yourself forty times. 🧚

  • poll-interval-limits = { min = min, max = max } ({ min = 4, max = 10}) — Specifies the limit on how often a source is queried for a new time. For most instances the defaults will be adequate. The min and max are given as the log2 of the number of seconds (i.e. two to the power of the interval). An interval of 4 equates to 16 seconds, 10 results in an interval of 1024 seconds. If specified, both min and max must be specified. No half-sending, bestie. Both or nothing.
  • initial-poll-interval = interval (4) — Initial poll interval used on startup. The value is given as the log2 of the number of seconds (i.e. two to the power of the interval). The default value of 4 results in an interval of 16 seconds. First-impressions interval fr.

🌟 [[source]] 🌟

Each [[source]] is a set of one or more time sources for the daemon to retrieve time information from. Any number of sources can be configured by repeating a [[source]] section (note the double brackets) for as many times as required. Each source can be configured to connect to a specific remote location. Multiple modes for connecting to sources are supported. If less than minimum-agreeing-sources time sources have been configured, no time will be synchronized to the local clock. Note that a pool counts as multiple time sources. So yes, the double brackets MATTER, and yes, a pool is a whole squad, not one person. 💅

  • mode = mode — Specify one of the source modes that ntpd-rs supports: server, pool, nts, nts-pool, sock or pps. For a description of the different source modes, see the SOURCE MODES section. Note that sources of type nts-pool are experimental and may change their behavior in backwards-incompatible ways between versions.
  • address = address — Specify the remote address of the source. For server sources this will be the remote address of the NTP server. For pools, this will be the DNS address of the NTP pool and for NTS this will be the address of the key exchange server. The server address may include a port number by appending a colon (:) followed by a port number. If not specified the daemon will connect to server and pool servers via port 123, for nts sources the default port is 4460. Two different default ports, keep up bestie. 🫶
  • certificate-authority = cert — Can only be set on sources with the nts mode. Path to a certificate for an additional certificate authority to use, aside from the certificate authorities specified by the system configuration. Note that this cannot be used to specify a self-signed certificate. Sorry, your homegrown cert isn't invited. 🙈
  • count = number (4) — Can only be set on sources with the pool mode. Specifies the maximum number of servers that the daemon will attempt to connect to from a pool. The daemon will keep retrying to get more sources from the pool when connections are lost, up to the maximum specified by this configuration value.
  • enable-srv-resolution = bool (false) — Can only be set on source with the nts or nts-pool mode. Enables following SRV records when resolving the address of the NTS-ke server. Such records must be DNSSEC signed. Note that this feature is still experimental and may change in backwards incompatible ways.
  • ignore = ip addresses — pool mode only. Specifies a list of IP addresses of servers in the pool which should not be used. For example: ["127.0.0.1"]. Empty by default. Blocked, blocked, blocked. 🚫
  • measurement_noise_estimate = Noise variance (seconds squared) — pps and sock mode only. Deprecated, use precision instead. Old and busted, use the new one, periodt.
  • precision = Noise standard deviation (seconds) — pps and sock mode only. Precision of the source. This should be an estimate of the size of the expected measurement noise. Technically defined as the 1-standard deviation bound on the measurement error. This is needed as sock and pps sources don't have a good way to estimate their own error. So you have to do it for them, generosity 💖
  • accuracy = Uncertainty standard deviation (seconds) — pps and sock mode only. Accuracy of the underlying time source. This should be an estimate of the size of the error in the clock you are synchronizing with, as well as any mostly-unchanging offset in the measurement process. This can be used to deprioritize sources which have large offsets in the measurement process or which are of poorer quality than others. It's giving "we listen and we don't judge, but we do rank". 📉
  • poll-interval-limits = { min = min, max = max } (defaults from [source-defaults]) — Specifies the limit on how often a source is queried for a new time. For most instances the defaults will be adequate. The min and max are given as the log2 of the number of seconds (i.e. two to the power of the interval). An interval of 4 equates to 16 seconds, 10 results in an interval of 1024 seconds. If only one of the two boundaries is specified, the other is inherited from [source-defaults].
  • initial-poll-interval = interval (defaults from [source-defaults]) — Initial poll interval used on startup. The value is given as the log2 of the number of seconds (i.e. two to the power of the interval). The default value of 4 results in an interval of 16 seconds.
  • ntp-version = 4 | 5 | "auto" (4) — Which NTP version to use for this source. By default this uses NTP version 4. You can use 5 to set the protocol version to the draft NTPv5 specification, but your source must support the same draft. To use the experimental upgrade protocol set the NTP version to "auto". This uses a specially constructed NTPv4 packet to attempt an upgrade to the supported draft NTPv5 version if the source also supports the same draft version. NTPv5 support is currently in beta and can still change in a backwards incompatible way. Beta era, handle with care bestie. 🦋

👑 [[server]] 👑

The NTP daemon can be configured to distribute time via any number of [[server]] sections. If no such sections have been defined, the daemon runs in a client only mode. Any number of servers can be configured by repeating the [[server]] section (note the double brackets) for as many times as required. Each server can serve a specific socket address or listen on all available network interfaces on a specific port. Servers always serve the system clock time. Main character energy: everybody gets your time, you get to just have it. ✨

  • listen = socketaddr — Address of a UDP socket on which the server should listen for incoming NTP requests. Specified as an interface IP address, a colon and a port number. The standard port number for NTP is UDP port 123. Both IPv4 and IPv6 are supported. For example to listen on localhost port 123 in IPv4 you can use 127.0.0.1:123. You can listen on all available network interfaces at once using 0.0.0.0:123 for IPv4 or [::]:123 for IPv6. All the interfaces, all at once, no cap. 🔥
  • rate-limiting-cache-size = size (0) — Number of elements in the rate limiting cache. At most size elements are kept in the cache. This means that if more than size different clients attempt to connect to the server too frequently, the cache size will have reduced functionality, as rate limiting information gets lost when new clients connect to the server. If set to zero, the cache is unused, this is the default. Small cache = short memory, and it WILL forget you. 💀
  • rate-limiting-cutoff-ms = cutoff (0) — Minimum time between two requests from the same client, if a request was sent sooner than the cutoff time, the client will be asked to slow down their requests by the server responding with a packet with the NTP RATE kiss code. No actual time measurement will be returned to the client in that case. If set to zero, no rate limiting is applied, this is the default. It's the politest possible "bestie, chill". 🧊
  • allowlist = { filter = [ subnet, .. ], action = "deny" | "ignore" } (unset) — bestie, this is your VIP list 💅 only the subnets you name in filter are allowed to even breathe on the daemon. Any IP that matches one of the subnets you listed gets to contact this server, and everyone else gets the vibe check. The subnets must be written in CIDR notation, which is an IP address, then a slash, then the number of masked bits — like 127.0.0.1/8 or 192.168.1.1/24 ✨. The action decides what happens to IP addresses that aren't in any of the subnets you listed. When it's deny, an explicit packet carrying the NTP DENY kiss code gets sent back to the sender to let them know they're not allowed to do that 😭. When it's ignore, the messages just get yeeted into the void with no response sent at all 🫥. The default value is equivalent to allowing any IP address, and it would be equivalent to setting the filter to ["0.0.0.0/0", "::/0"], with either action.
  • denylist = { filter = [ subnet, .. ], action = "deny" | "ignore" } (unset) — and this one is the blocklist, the exact opposite energy 🚫. Do not allow any number of filtered subnets to connect to the daemon. Any IP that matches one of the subnets you specify is not allowed to contact this server, periodt. Same CIDR rules as before: an IP address, a slash, and the number of masked bits, for example 127.0.0.1/8 or 192.168.1.1/24 🌸. Now here's the twist — with denylist, the action determines what measure is taken for IP addresses that are in any of the specified subnets. When deny, an explicit packet with the NTP DENY kiss code goes back to the sender telling them nope 💀. When ignore is specified, messages are discarded with no response sent. The default value is equivalent to allowing any IP address, and would be equivalent to setting the filter to [], with either action. Empty list, empty drama.
  • require-nts = true | false | "deny" | "ignore" (false) — do the incoming requests to the server have to have NTS enabled? Iconic question. When it's set to true or "ignore", any non-NTS enabled messages get ignored entirely 🙈. When it's set to "deny", non-NTS enabled messages get explicitly denied with an NTP DENY kiss code. When it's false (that's the default, bestie), normal NTP messages are also allowed — so everyone can come to the party 🎀.
  • accept-ntp-versions = [ 3 | 4 | 5, .. ] ([3, 4]) — an array of the NTP versions the server accepts ⭐. By default only NTPv3 and NTPv4 packets are supported. Wanna also let draft NTPv5 packets in? Set this value to [3, 4, 5]. Fair warning though: NTPv5 support is currently in beta and can still change in a backwards incompatible way ⚠️.

✨ [observability] ✨

The settings chilling in this section configure how you can observe the behavior of the daemon 👀. Currently, the daemon can be observed either through the logs, or by retrieving several key metrics either through ntp-ctl(8) or through ntp-metrics-exporter(8). Both. Choose your fighter.

  • log-level = "trace" | "debug" | "info" | "warn" | "error" (info) — sets the logging level for messages printed to stdout 🌈. The lowest level, trace, gives you very detailed information about anything going on in the daemon — like, anything. The highest level, error, only logs error conditions in the daemon. And heads up: levels higher than the given log level are logged as well, so it's a floor, not a ceiling 🧚.
  • log-path = path (unset) — the path where the daemon should direct its log output 📁. The file at this location is reopened on SIGHUP. When this isn't present, log output goes to stdout instead.
  • log-path-metrics-exporter = path (unset) — same deal but for the metrics exporter daemon 👑: the path where it should direct its log output. The file at this location is also reopened on SIGHUP. When not present, log output is directed to stdout.
  • ansi-colors = true | false (see note) — controls ANSI escape codes in logs 🎨. By default, ANSI escape codes are used to add some colors and other formatting to the logs when the log target is a terminal. Cute when it's a terminal, cursed when it's a file — you know the deal.
  • observation-path = path (unset) — the path where the daemon will create an observation Unix domain socket 🔌. This socket is what ntp-ctl and ntp-metrics-exporter use to read the current status of the daemon. If it's not set (the default), no observation socket gets created, and it is not possible to use ntp-ctl or ntp-metrics-exporter to observe the daemon 😭. So like... set it, bestie.
  • observation-permissions = mode (0o666) — the file system permissions the observation socket gets created with 🔐. Warning: you should always write this number with the octal prefix 0o, otherwise your permissions might be interpreted wrongly 💀. The default should be OK for most applications however.
  • metrics-exporter-listen = socketaddr (127.0.0.1:9975) — the listen address that is used for the ntp-metrics-exporter(8) 📡.

✨ [keyset] ✨

The keyset configures the internal key infrastructure for NTS packets 🔑. Quick note, bestie: this is separate from the TLS certificate and private key — for those, see the relevant configuration in the [[nts-ke-server]] section. Don't mix them up, iykyk.

  • stale-key-count = count (7) — the maximum number of old keys to retain in the cache 🗝️. Whenever keys are rotated, the old keys become invalid, but clients may still have NTS cookies encrypted with any of the old keys. So we keep a few around. Be nice.
  • key-rotation-interval = seconds (86400) — time between key rotation events ⏰. Every time seconds elapses, a new internal key will be generated for creating NTS cookies. By default this is set to a day. Fresh keys, fresh start 💖.
  • key-storage-path = path (unset) — if set, stores the internal NTS keys in the file indicated by path 💾. This lets your keys survive a server reboot, which is huge. If it's not set, clients using NTS may need to redo a key exchange operation to get new NTS cookies 🥲. Two things to know: the daemon will not create any parent directories if they don't exist, but it will create the file if it doesn't exist.

✨ [[nts-ke-server]] ✨

The daemon can be configured to operate as an NTS key exchange server by repeating any number of [[nts-ke-server]] sections 🔁✨. If no such sections have been defined, the daemon offers no NTS key exchange services. All NTS-KE servers make use of the shared keyset. The whole purpose of the key exchange server is to safely distribute cookies to clients 🍪 — and those cookies can then be used in NTP packets with the normal server to validate that the traffic was not tampered with. Chef's kiss security.

  • listen = socket — address of a TCP socket on which the server should listen for incoming NTS key exchange requests 📥. Specified as an interface IP address, a colon, and a port number. The standard port number for an NTS key exchange server is TCP port 4460. Both IPv4 and IPv6 are supported 🫶. For example, to listen on localhost port 4460 in IPv4 you can use 127.0.0.1:4460. You can listen on all available network interfaces at once using 0.0.0.0:4460 for IPv4 or [::]:4460 for IPv6.
  • certificate-chain-path = path — path to a certificate chain for the public certificate that the server offers to clients 📜.
  • private-key-path = path — path to the private key associated with the server certificate in the certificate chain 🔏.
  • key-exchange-timeout-ms = timeout (1000) — timeout in milliseconds for how long a key exchange may take ⌛. If the timeout is exceeded, the connection gets dropped. No loitering.
  • concurrent-connections = number (512) — maximum number of total concurrent connections the key exchange server will handle 🧮. Any connections above the threshold will be held in an OS level queue. They're waiting in line, respectfully.
  • longlived-connections = number (concurrent-connections/10) — maximum number of concurrent longlived connections from nts pools the key exchange server will handle 🌊. Note that pool support is currently in beta and can still change in backwards incompatible ways ⚠️.
  • ntp-port = port — port number the key exchange server should instruct clients to use 📢. Should be used when the port number of the NTP server is not the default.
  • ntp-server = server-name — server address (either as ip or as domain name) where clients can find the NTP server 🗺️. Should be used when this name does not match the name of the NTS key exchange server.
  • accept-ntp-versions = [ 4 | 5, .. ] ([4]) — an array of NTP versions accepted by the server ⭐. By default only NTS for NTPv4 packets is supported. To also allow negotiating NTS for draft NTPv5 packets, you can set this value to [4, 5]. NTPv5 support is currently in beta and can still change in a backwards incompatible way, so don't be shocked if it shifts 💫.
  • accepted-pool-authentication-tokens = list of keys ([]) — tokens pools can use to authenticate pool-specific requests to this NTS server 🔑. Note that pool support is currently in beta and can still change in a backwards incompatible way 🌀.

✨ [synchronization] ✨

This section of the configuration focuses on how the time information from the time sources is gathered and applied to the system clock ⏱️👑. This is where the magic actually happens.

  • minimum-agreeing-sources = count (3) — the minimum number of sources that should agree on the current time before the daemon does any steering operation on the clock 🤝. Heads up: if you have configured fewer than this amount of sources, this may result in the daemon never updating the clock 😭💀. So like, count your sources.
  • single-step-panic-threshold = seconds | { forward = forward, backward = backward }** *(1000)* — the threshold in seconds at which the daemon will completely exit (i.e. **panic**) when a single non-startup step occurs 🚨. Generally during normal operation the clock on your system should run somewhat close to the time it's synchronized to, so it is *highly* unlikely that such a large step will take place — and the daemon exits specifically to prevent any accidental mistakes 🙏. If you set it to the value "inf"`, any step will be allowed (chaos mode, your call). You may either configure it as one number of seconds for both forward and backward steps, or as separate values for forward and backward steps.
  • startup-step-panic-threshold = seconds | { forward = forward, backward = backward } (default { forward = “inf”, backward = “86400” }) — the threshold in seconds at which the daemon will literally fully exit (aka panic 💀) when a step happens at startup. The default lets any forward step through, but blocks backward steps bigger than a single day. Why? Because clocks that aren't synced usually run behind true time, not ahead — so if your box is running ahead and then steps back a big chunk of time, that's usually a 🚩 problem. Set it to "inf" and any step gets allowed, no questions asked. You can give it either one number of seconds covering both forward and backward steps, or separate values for forward and backward. And bestie, even with this locked down, ntp-ctl's force-sync command can still manually set the system time past these limits — that's your rescue hatch if the system clock goes rogue 🫶.
  • accumulated-step-panic-threshold = seconds (unset) — every single time the daemon steps the time instead of gently adjusting via frequency changes, this counter goes up by the absolute value of the step (so forward and backward steps both count, no favouritism 💅). Once the threshold is hit, the daemon exits immediately (panic time 😭). During normal operation steps basically shouldn't happen, so any step might mean someone or something is triggering illicit steps 👀. By default though, this panic mechanism is disabled — it stays off if you leave it unset or set it to 0.
  • warn-on-jump = bool (true) — should the daemon yell a warning when it steps the clock? Those jumps can be messy for other software — database servers, I'm looking at you 🍓. Flip this off on systems where steps are expected and harmless to everything else.
  • local-stratum = stratum (16) — sets the NTP clock stratum of the system clock when no NTP time sources are configured, or when the time hasn't been synchronized from an NTP time source yet. Servers can use this to announce that some external mechanism is out here doing the syncing ✨.
  • reference-id = reference-id (XNON) — sets the reported NTP clock reference id, but only when local-statum is set to 1. This is how you tell the world what your time reference actually is (GPS etc.) 🛰️.

🌸 [synchronization.algorithm]

⚠️ Warning bestie: the algorithm section is mostly internal algorithm tweaks that you generally should not be touching. They're offered here for specific use cases, but these settings are considered implementation details — meaning they may change in future ntpd-rs versions. Don't get attached 💀.
  • precision-low-probability = probability (1/3) — the probability bound below which we start moving towards decreasing our precision estimate. Unit: probability, 0-1.
  • precision-high-probability = probability (2/3) — the probability bound above which we start moving towards increasing our precision estimate. Unit: probability, 0-1.
  • precision-hysteresis = hysteresis (16) — how much hysteresis there is in changing the precision estimate. Unit: count, 1+.
  • precision-minimum-weight = weight (0.1) — lower bound on how much effect our precision estimate has on the total noise estimate before we allow the precision estimate to decrease. Unit: weight, 0-1.
  • poll-interval-low-weight = weight (0.4) — how much a measurement contributes to the state, below which we start increasing the poll interval. Unit: weight, 0-1.
  • poll-interval-high-weight = weight (0.6) — how much a measurement contributes to the state, above which we start decreasing the poll-interval interval. Unit: weight, 0-1.
  • poll-interval-hysteresis = hysteresis (16) — how much hysteresis there is in changing the poll interval. Unit: count, 1+.
  • poll-interval-step-threshold = threshold (1e-6) — the probability threshold for when a measurement counts as a significant enough outlier that we decide something weird is going on and we need to take more measurements 🔍. Unit: probability, 0-1.
  • delay-outlier-threshold = threshold (5.0) — the threshold (in number of standard deviations) above which measurements with a significantly larger network delay get rejected. Unit: standard deviations, 0+.
  • initial-wander = wander (1e-8) — the initial estimate of the clock wander from the combination of our local clock and the source's clock. Unit: s/s^2.
  • initial-frequency-uncertainty = uncertainty (100e-6) — the initial uncertainty of the frequency difference between our clock and the source's clock. Unit: s/s.
  • maximum-source-uncertainty = uncertainty (0.25) — the maximum source uncertainty before we start disregarding it. Heads up: this is the combined uncertainty from noise plus possible asymmetry error (see the weights below too 🫶). Unit: seconds.
  • range-statistical-weight = weight (2.0) — the weight of statistical uncertainty when constructing overlap ranges. Unit: standard deviations, 0+.
  • range-delay-weight = weight (0.25) — the weight of delay uncertainty when constructing overlap ranges. Unit: weight, 0-1.
  • steer-offset-threshold = threshold (2.0) — how far from 0 (in multiples of the uncertainty) the offset should be before we correct it. Unit: standard deviations, 0+.
  • steer-offset-leftover = stddev (1.0) — how many standard deviations do we leave behind after offset correction? Unit: standard deviations, 0+.
  • steer-frequency-threshold = threshold (0.0) — how far from 0 (in multiples of the uncertainty) the frequency estimate should be before we correct it. Unit: standard deviations, 0+.
  • steer-frequency-leftover = stddev (0.0) — how many standard deviations do we leave behind after frequency correction? Unit: standard deviations, 0+.
  • step-threshold = threshold (0.010) — from what offset should we step the clock instead of trying to adjust gradually? Unit: seconds, 0+.
  • slew-maximum-frequency-offset = offset (200e-6) — what's the maximum frequency offset during a slew? Unit: s/s.
  • slew-minimum-duration = duration (8.0) — what's the minimum duration of a slew? Unit: seconds.
  • maximum-frequency-steer = frequency (495e-6) — the absolute maximum frequency correction. Unit: s/s.
  • ignore-server-dispersion = bool (false) — ignore a server's advertised dispersion when synchronizing. This can improve synchronization quality with servers reporting overly conservative root dispersion 👑.
  • meddling-threshold = threshold (5.0) — the threshold for detecting external clock meddling 👀🔎. Unit: seconds.

👀✨ SEE ALSO ✨👀

and that's the whole page bestie!! 💖 this one's NTP.TOML(5) from ntpd-rs version 1.9.0 — that's the source and version stamped on it, and the date slot at the bottom is just sitting there empty, no date, nothing, an absolute icon of leaving the date field blank 🎀. go configure your clocks, you got this, periodt 🦋💅

📦 where this page comes from