chrony.conf(5) Manual Page

The server directive is immediately followed by either the name of the server, or its IP address. The server directive supports the following options:

All options valid in the server directive can be used in this directive too. There is one option specific to the pool directive: maxsources sets the maximum number of sources that can be used from the pool, the default value is 4.

On start, when the pool name is resolved, chronyd will add up to 16 sources, one for each resolved address. When the number of sources from which at least one valid reply was received reaches the number specified by the maxsources option, the other sources will be removed. When a pool source is unreachable, marked as a falseticker, or has a distance larger than the limit set by the maxdistance directive, chronyd will try to replace the source with a newly resolved address from the pool.

An example of the pool directive is

When a key is specified by the key option to enable authentication, both peers must use the same key and the same key number.

Note that the symmetric mode is less secure than the client/server mode. A denial-of-service attack is possible on unauthenticated symmetric associations, i.e. when the peer was specified without the key option. An attacker who does not see network traffic between two hosts, but knows that they are peering with each other, can periodically send them unauthenticated packets with spoofed source addresses in order to disrupt their NTP state and prevent them from synchronising to each other. When the association is authenticated, an attacker who does see the network traffic, but cannot prevent the packets from reaching the other host, can still disrupt the state by replaying old packets. The attacker has effectively the same power as a man-in-the-middle attacker. A partial protection against this attack is implemented in chronyd, which can protect the peers if they are using the same polling interval and they never sent an authenticated packet with a timestamp from future, but it should not be relied on as it is difficult to ensure the conditions are met. If two hosts should be able to synchronise to each other in both directions, it is recommended to use two separate client/server associations (specified by the server directive on both hosts) instead.

On most Unix systems it is not desirable to step the system clock, because many programs rely on time advancing monotonically forwards.

When the chronyd daemon is initially started, it is possible that the system clock is considerably in error. Attempting to correct such an error by slewing might not be sensible, since it might take several hours to correct the error by this means.

The purpose of the initstepslew directive is to allow chronyd to make a rapid measurement of the system clock error at boot time, and to correct the system clock by stepping before normal operation begins. Since this would normally be performed only at an appropriate point in the system boot sequence, no other software should be adversely affected by the step.

If the correction required is less than a specified threshold, a slew is used instead. This makes it safer to restart chronyd whilst the system is in normal operation.

The initstepslew directive takes a threshold and a list of NTP servers as arguments. Each of the servers is rapidly polled several times, and a majority voting mechanism used to find the most likely range of system clock error that is present. A step or slew is applied to the system clock to correct this error. chronyd then enters its normal operating mode.

An example of the use of the directive is:

where 2 NTP servers are used to make the measurement. The 30 indicates that if the system’s error is found to be 30 seconds or less, a slew will be used to correct it; if the error is above 30 seconds, a step will be used.

The initstepslew directive can also be used in an isolated LAN environment, where the clocks are set manually. The most stable computer is chosen as the master, and the other computers are slaved to it. If each of the slaves is configured with the local directive, the master can be set up with an initstepslew directive which references some or all of the slaves. Then, if the master machine has to be rebooted, the slaves can be relied on to act analogously to a flywheel and preserve the time for a short period while the master completes its reboot.

The initstepslew directive is functionally similar to a combination of the makestep and server directives with the iburst option. The main difference is that the initstepslew servers are used only before normal operation begins and that the foreground chronyd process waits for initstepslew to finish before exiting. This is useful to prevent programs started in the boot sequence after chronyd from reading the clock before it has been stepped.

There are four drivers included in chronyd:

Note that the settime command can be enabled at run-time using the manual command in chronyc. (The idea of the two commands is that the manual command controls the manual clock driver’s behaviour, whereas the settime command allows samples of manually entered time to be provided.)

It can be set to the same port as is used by the NTP server (which can be configured with the port directive) to use only one socket for all NTP packets.

An example of the acquisitionport directive is:

This would change the source port used for client requests to UDP port 1123. You could then persuade the firewall administrator to open that port.

For each of the IPv4 and IPv6 protocols, only one bindacqaddress directive can be specified.

All supported systems, with the exception of macOS 10.12 and earlier, have operating system support for setting the rate of gain or loss to compensate for known errors. (On macOS 10.12 and earlier, chronyd must simulate such a capability by periodically slewing the system clock forwards or backwards by a suitable amount to compensate for the error built up since the previous slew.)

For such systems, it is possible to save the measurement history across restarts of chronyd (assuming no changes are made to the system clock behaviour whilst it is not running). The dumpdir directive defines the directory where the measurement histories are saved when chronyd exits, or the dump command in chronyc is issued.

An example of the directive is:

A source whose IP address is 1.2.3.4 would have its measurement history saved in the file /var/run/chrony/1.2.3.4.dat. History of reference clocks is saved to files named by their reference ID in form of refid:XXXXXXXX.dat.

The combinelimit directive limits which sources are included in the combining algorithm. Their synchronisation distance has to be shorter than the distance of the selected source multiplied by the value of the limit. Also, their measured frequencies have to be close to the frequency of the selected source.

By default, the limit is 3. Setting the limit to 0 effectively disables the source combining algorithm and only the selected source will be used to control the system clock.

By default, the maximum root distance is 3 seconds.

Setting maxdistance to a larger value can be useful to allow synchronisation with a server that only has a very infrequent connection to its sources and can accumulate a large dispersion between updates of its clock.

By default, the maximum jitter is 1 second.

Setting this option to a larger number can be used to improve the reliability. More sources will have to agree with each other and the clock will not be updated when only one source (which could be serving incorrect time) is reachable.

By default, the weight is 0.001 seconds. This means that the stratum of the sources in the selection process matters only when the differences between the distances are in milliseconds.

The corrtimeratio directive sets the ratio between the duration in which the clock is slewed for an average correction according to the source history and the interval in which the corrections are done (usually the NTP polling interval). Corrections larger than the average take less time and smaller corrections take more time, the amount of the correction and the correction time are inversely proportional.

Increasing corrtimeratio improves the overall frequency error of the system clock, but increases the overall time error as the corrections take longer.

By default, the ratio is set to 3, the time accuracy of the clock is preferred over its frequency accuracy.

The maximum allowed slew rate can be set by the maxslewrate directive. The current remaining correction is shown in the tracking report as the System time value.

Whenever chronyd computes a new value of the gain or loss rate, it is desirable to record it somewhere. This allows chronyd to begin compensating the system clock at that rate whenever it is restarted, even before it has had a chance to obtain an equally good estimate of the rate during the new run. (This process can take many minutes, at least.)

The driftfile directive allows a file to be specified into which chronyd can store the rate information. Two parameters are recorded in the file. The first is the rate at which the system clock gains or loses time, expressed in parts per million, with gains positive. Therefore, a value of 100.0 indicates that when the system clock has advanced by a second, it has gained 100 microseconds in reality (so the true time has only advanced by 999900 microseconds). The second is an estimate of the error bound around the first value in which the true rate actually lies.

An example of the driftfile directive is:

The directive specifies the minimum and maximum interval since the last clock update to switch between fallback drifts. They are defined as a power of 2 (in seconds). The syntax is as follows:

In this example, the minimum interval is 16 (18 hours) and the maximum interval is 19 (6 days). The system clock frequency will be set to the first fallback 18 hours after last clock update, to the second after 36 hours, and so on. This might be a good setting to cover frequency changes due to daily and weekly temperature fluctuations. When the frequency is set to a fallback, the state of the clock will change to ‘Not synchronised’.

By default (or if the specified maximum or minimum is 0), no fallbacks are used and the clock frequency changes only with new measurements from NTP sources, reference clocks, or manual input.

For computer clocks that is a problem. The Unix time is defined as number of seconds since 00:00:00 UTC on 1 January 1970 without leap seconds. The system clock cannot have time 23:59:60, every minute has 60 seconds and every day has 86400 seconds by definition. The inserted leap second is skipped and the clock is suddenly ahead of UTC by one second. The leapsecmode directive selects how that error is corrected. There are four options:

When serving time to NTP clients that cannot be configured to correct their clocks for a leap second by slewing, or to clients that would correct at slightly different rates when it is necessary to keep them close together, the slew mode can be combined with the smoothtime directive to enable a server leap smear.

When smearing a leap second, the leap status is suppressed on the server and the served time is corrected slowly be slewing instead of stepping. The clients do not need any special configuration as they do not know there is any leap second and they follow the server time which eventually brings them back to UTC. Care must be taken to ensure they use only NTP servers which smear the leap second in exactly the same way for synchronisation.

This feature must be used carefully, because the server is intentionally not serving its best estimate of the true time.

A recommended configuration to enable a server leap smear is:

The first directive is necessary to disable the clock step which would reset the smoothing process. The second directive limits the slewing rate of the local clock to 1000 ppm, which improves the stability of the smoothing process when the local correction starts and ends. The third directive enables the server time smoothing process. It will start when the clock gets to 00:00:00 UTC and it will take 17 hours 34 minutes to finish. The frequency offset will be changing by 0.001 ppm per second and will reach a maximum of 31.623 ppm. The leaponly option makes the duration of the leap smear constant and allows the clients to safely synchronise with multiple identically configured leap smearing servers.

When a leap second is announced, the timezone needs to be updated at least 12 hours before the leap second. It is not necessary to restart chronyd.

This directive is useful with reference clocks and other time sources which do not announce leap seconds, or announce them too late for an NTP server to forward them to its own clients. Clients of leap smearing servers must not use this directive.

It is also useful when the system clock is required to have correct TAI-UTC offset. Note that the offset is set only when leap seconds are handled by the kernel, i.e. leapsecmode is set to system.

The specified timezone is not used as an exclusive source of information about leap seconds. If a majority of time sources announce on the last day of June or December that a leap second should be inserted or deleted, it will be accepted even if it is not included in the timezone.

An example of the directive is:

The following shell command verifies that the timezone contains leap seconds and can be used with this directive:

This directive forces chronyd to step the system clock if the adjustment is larger than a threshold value, but only if there were no more clock updates since chronyd was started than a specified limit (a negative value can be used to disable the limit).

This is particularly useful when using reference clocks, because the initstepslew directive works only with NTP sources.

An example of the use of this directive is:

This would step the system clock if the adjustment is larger than 0.1 seconds, but only in the first three clock updates.

An example of the use of this directive is:

After the first clock update, chronyd will check the offset on every clock update, it will ignore two adjustments larger than 1000 seconds and exit on another one.

By default, the maximum error is 1 ppm.

Typical values for error-in-ppm might be 10 for a low quality clock and 0.1 for a high quality clock using a temperature compensated crystal oscillator.

By default, the maximum assumed drift is 500000 ppm, i.e. the adjustment is limited by the system driver rather than this directive.

If the range of error is too large, it probably indicates that the measurements have not settled down yet, and that the estimated gain or loss rate is not very reliable.

The maxupdateskew directive sets the threshold for determining whether an estimate might be so unreliable that it should not be used. By default, the threshold is 1000 ppm.

Typical values for skew-in-ppm might be 100 for a dial-up connection to servers over a phone line, and 5 or 10 for a computer on a LAN.

It should be noted that this is not the only means of protection against using unreliable estimates. At all times, chronyd keeps track of both the estimated gain or loss rate, and the error bound on the estimate. When a new estimate is generated following another measurement from one of the sources, a weighted combination algorithm is used to update the master estimate. So if chronyd has an existing highly-reliable master estimate and a new estimate is generated which has large error bounds, the existing master estimate will dominate in the new master estimate.

For each system there is a maximum frequency offset of the clock that can be set by the driver. On Linux it is 100000 ppm, on FreeBSD, NetBSD and macOS 10.13+ it is 5000 ppm, and on Solaris it is 32500 ppm. Also, due to a kernel limitation, setting maxslewrate on FreeBSD, NetBSD, macOS 10.13+ to a value between 500 ppm and 5000 ppm will effectively set it to 500 ppm.

In early beta releases of macOS 13 this capability is disabled because of a system kernel bug. When the kernel bug is fixed, chronyd will detect this and re-enable the capability (see above limitations) with no recompilation required.

By default, the maximum slew rate is set to 83333.333 ppm (one twelfth).

If there are temperature measurements available from a sensor close to the oscillator, the tempcomp directive can be used to compensate for the changes in the temperature and improve the stability and accuracy of the clock.

The result depends on many factors, including the resolution of the sensor, the amount of noise in the measurements, the polling interval of the time source, the compensation update interval, how well the compensation is specified, and how close the sensor is to the oscillator. When it is working well, the frequency reported in the tracking.log file is more stable and the maximum reached offset is smaller.

There are two forms of the directive. The first one has six parameters: a path to the file containing the current temperature from the sensor (in text format), the compensation update interval (in seconds), and temperature coefficients T0, k0, k1, k2.

The frequency compensation is calculated (in ppm) as

The result has to be between -10 ppm and 10 ppm, otherwise the measurement is considered invalid and will be ignored. The k0 coefficient can be adjusted to keep the compensation in that range.

An example of the use is:

The measured temperature will be read from the file in the Linux sysfs filesystem every 30 seconds. When the temperature is 26000 (26 degrees Celsius), the frequency correction will be zero. When it is 27000 (27 degrees Celsius), the clock will be set to run faster by 0.183 ppm, etc.

The second form has three parameters: the path to the sensor file, the update interval, and a path to a file containing a list of (temperature, compensation) points, from which the compensation is linearly interpolated or extrapolated.

An example is:

where the /etc/chrony.tempcomp file could have

Valid measurements with corresponding compensations are logged to the tempcomp.log file if enabled by the log tempcomp directive.

The default is that no clients are allowed access, i.e. chronyd operates purely as an NTP client. If the allow directive is used, chronyd will be both a client of its servers, and a server to other clients.

Examples of the use of the directive are as follows:

The first directive allows a node with IPv4 address 1.2.3.4 to be an NTP client of this computer. The second directive allows any node with an IPv4 address of the form 1.2.x.y (with x and y arbitrary) to be an NTP client of this computer. Likewise, the third directive allows any node with an IPv4 address of the form 3.4.5.x to have client NTP access. The fourth and fifth forms allow access from any node with an IPv4 address of the form 6.7.8.x, 6.7.9.x, 6.7.10.x or 6.7.11.x (with x arbitrary), i.e. the value 22 is the number of bits defining the specified subnet. In the fifth form, the final byte is ignored. The sixth form is used for IPv6 addresses. The seventh and eighth forms allow access by any IPv4 and IPv6 node respectively. The ninth forms allows access by any node (IPv4 or IPv6).

A second form of the directive, allow all, has a greater effect, depending on the ordering of directives in the configuration file. To illustrate the effect, consider the two examples:

and

In the first example, the effect is the same regardless of what order the three directives are given in. So the 1.2.x.y subnet is allowed access, except for the 1.2.3.x subnet, which is denied access, however the host 1.2.3.4 is allowed access.

In the second example, the allow all 1.2 directives overrides the effect of any previous directive relating to a subnet within the specified subnet. Within a configuration file this capability is probably rather moot; however, it is of greater use for reconfiguration at run-time via chronyc with the allow all command.

The directive allows a hostname to be specified instead of an IP address, but the name must be resolvable when chronyd is started (i.e. chronyd needs to be started when the network is already up and DNS is working).

Note, if the initstepslew directive is used in the configuration file, each of the computers listed in that directive must allow client access by this computer for it to work.

The syntax is identical.

There is also a deny all directive with similar behaviour to the allow all directive.

An example of the use of the directive is:

Currently, for each of the IPv4 and IPv6 protocols, only one bindaddress directive can be specified. Therefore, it is not useful on computers which should serve NTP on multiple network interfaces.

The syntax is as follows:

In the first example, the destination port defaults to UDP port 123 (the normal NTP port). In the second example, the destination port is specified as 12123. The first parameter in each case (30 or 60 respectively) is the interval in seconds between broadcast packets being sent. The second parameter in each case is the broadcast address to send the packet to. This should correspond to the broadcast address of one of the network interfaces on the computer where chronyd is running.

You can have more than 1 broadcast directive if you have more than 1 network interface onto which you want to send NTP broadcast packets.

chronyd itself cannot act as a broadcast client; it must always be configured as a point-to-point client by defining specific NTP servers and peers. This broadcast server feature is intended for providing a time source to other NTP implementations.

If ntpd is used as the broadcast client, it will try to measure the round-trip delay between the server and client with normal client mode packets. Thus, the broadcast subnet should also be the subject of an allow directive.

In older chrony versions if the limit was set to 0, the memory allocation was unlimited.

An example of the use of this directive is:

This directive is normally used in an isolated network, where computers are required to be synchronised to one another, but not necessarily to real time. The server can be kept vaguely in line with real time by manual input.

The local directive has the following options:

An example of the directive is:

Note that MS-SNTP requests are not authenticated and any client that is allowed to access the server by the allow directive, or the allow command in chronyc, can get an MS-SNTP response signed with a trust account’s password and try to crack the password in a brute-force attack. Access to the server should be carefully controlled.

An example of the directive is:

The default value is 123, the standard NTP port. If set to 0, chronyd will never open the server port and will operate strictly in a client-only mode. The source port used in NTP client requests can be set by the acquisitionport directive.

The ratelimit directive supports a number of options (which can be defined in any order):

An example use of the directive is:

This would reduce the response rate for IP addresses sending packets on average more than once per 2 seconds, or sending packets in bursts of more than 16 packets, by up to 75% (with default leak of 2).

BE WARNED: The server is intentionally not serving its best estimate of the true time. If a large offset has been accumulated, it can take a very long time to smooth it out. This directive should be used only when the clients are not configured to also poll another NTP server, because they could reject this server as a falseticker or fail to select a source completely.

The smoothing process is implemented with a quadratic spline function with two or three pieces. It is independent from any slewing applied to the local system clock, but the accumulated offset and frequency will be reset when the clock is corrected by stepping, e.g. by the makestep directive or the makestep command in chronyc. The process can be reset without stepping the clock by the smoothtime reset command.

The first two arguments of the directive are the maximum frequency offset of the smoothed time to the tracked NTP time (in ppm) and the maximum rate at which the frequency offset is allowed to change (in ppm per second). leaponly is an optional third argument which enables a mode where only leap seconds are smoothed out and normal offset and frequency changes are ignored. The leaponly option is useful in a combination with the leapsecmode slew directive to allow the clients to use multiple time smoothing servers safely.

The smoothing process is activated automatically when 1/10000 of the estimated skew of the local clock falls below the maximum rate of frequency change. It can be also activated manually by the smoothtime activate command, which is particularly useful when the clock is synchronised only with manual input and the skew is always larger than the threshold. The smoothing command can be used to monitor the process.

An example suitable for clients using ntpd and 1024 second polling interval could be:

An example suitable for clients using chronyd on Linux could be:

This directive can also change the path of the Unix domain command socket, which is used by chronyc to send configuration commands. The socket must be in a directory that is accessible only by the root or chrony user. The directory will be created on start if it does not exist. The compiled-in default path of the socket is /var/run/chrony/chronyd.sock. The socket can be disabled by setting the path to /.

By default, chronyd binds to the loopback interface (with addresses 127.0.0.1 and ::1). This blocks all access except from localhost. To listen for command packets on all interfaces, you can add the lines:

to the configuration file.

For each of the IPv4, IPv6, and Unix domain protocols, only one bindcmdaddress directive can be specified.

An example that sets the path of the Unix domain command socket is:

The syntax is identical to the allow directive.

There is also a cmdallow all directive with similar behaviour to the allow all directive (but applying to monitoring access in this case, of course).

Note that chronyd has to be configured with the bindcmdaddress directive to not listen only on the loopback interface to actually allow remote access.

The syntax is identical.

There is also a cmddeny all directive with similar behaviour to the cmdallow all directive.

An example shows the syntax:

This would make chronyd use UDP 257 as its command port. (chronyc would need to be run with the -p 257 switch to inter-operate correctly.)

An example of the use of the directive is:

The compiled-in default value is ''.

An example of the directive is:

This directive is effective only with the rtcfile directive.

An example of the use of this directive is:

This would set the threshold error to 30 seconds.

An example of the directive is:

chronyd saves information in this file when it exits and when the writertc command is issued in chronyc. The information saved is the RTC’s error at some epoch, that epoch (in seconds since January 1 1970), and the rate at which the RTC gains or loses time.

So far, the support for real-time clocks is limited; their code is even more system-specific than the rest of the software. You can only use the RTC facilities (the rtcfile directive and the -s command-line option to chronyd) if the following three conditions apply:

If you keep the RTC on local time and your computer is off when daylight saving (summer time) starts or ends, the computer’s system time will be one hour in error when you next boot and start chronyd.

An alternative is for the RTC to keep Universal Coordinated Time (UTC). This does not suffer from the 1 hour problem when daylight saving starts or ends.

If the rtconutc directive appears, it means the RTC is required to keep UTC. The directive takes no arguments. It is equivalent to specifying the -u switch to the Linux hwclock program.

Note that this setting is overridden when the hwclockfile directive is specified.

On Linux, the RTC copy is performed by the kernel every 11 minutes.

On macOS, chronyd will perform the RTC copy every 60 minutes when the system clock is in a synchronised state.

On other systems this directive does nothing.

The logbanner directive specifies after how many entries in the log file should be the banner written. The default is 32, and 0 can be used to disable it entirely.

By default, the threshold is 1 second.

An example of the use is:

which would cause a syslog message to be generated if a system clock error of over 0.1 seconds starts to be compensated.

An example of the use of this directive is:

An example of the use of this directive is:

This would send a mail message to root if a change of more than 0.5 seconds were applied to the system clock.

This directive cannot be used when a system call filter is enabled by the -F option as the chronyd process will not be allowed to fork and execute the sendmail binary.

This directive is supported on Linux 3.19 and newer. The NIC must support HW timestamping, which can be verified with the ethtool -T command. The list of capabilities should include SOF_TIMESTAMPING_RAW_HARDWARE, SOF_TIMESTAMPING_TX_HARDWARE, and SOF_TIMESTAMPING_RX_HARDWARE. Receive filter HWTSTAMP_FILTER_ALL, or HWTSTAMP_FILTER_NTP_ALL, is necessary for timestamping of received packets. Timestamping of packets received from bridged and bonded interfaces is supported on Linux 4.13 and newer. When chronyd is running, no other process (e.g. a PTP daemon) should be working with the NIC clock.

If the kernel supports software timestamping, it will be enabled for all interfaces. The source of timestamps (i.e. hardware, kernel, or daemon) is indicated in the measurements.log file if enabled by the log measurements directive, and the ntpdata report in chronyc.

If the specified interface is *, chronyd will try to enable HW timestamping on all available interfaces.

The hwtimestamp directive has the following options:

Examples of the directive are:

An example of the directive is:

The format of the directive is shown in the example below:

The argument is simply the name of the file containing the ID-key pairs. The format of the file is shown below:

Each line consists of an ID, name of an authentication hash function (optional), and a password. The ID can be any unsigned integer in the range 1 through 2^32-1. The default hash function is MD5, which is always supported.

If chronyd was built with enabled support for hashing using a crypto library (nettle, nss, or libtomcrypt), the following functions are available: MD5, SHA1, SHA256, SHA384, SHA512. Depending on which library and version is chronyd using, some or all of the following functions may also be available: SHA3-224, SHA3-256, SHA3-384, SHA3-512, RMD128, RMD160, RMD256, RMD320, TIGER, WHIRLPOOL.

The password can be specified as a string of characters not containing white space with an optional ASCII: prefix, or as a hexadecimal number with the HEX: prefix. The maximum length of the line is 2047 characters.

The password is used with the hash function to generate and verify a message authentication code (MAC) in NTP packets. It is recommended to use SHA1, or stronger, hash function with random passwords specified in the hexadecimal format that have at least 128 bits. chronyd will log a warning to syslog on start if a source is specified in the configuration file with a key that has password shorter than 80 bits.

The keygen command of chronyc can be used to generate random keys for the key file. By default, it generates 160-bit MD5 or SHA1 keys.

On Linux, this directive uses the sched_setscheduler() system call to instruct the kernel to use the SCHED_FIFO first-in, first-out real-time scheduling policy for chronyd with the specified priority. This means that whenever chronyd is ready to run it will run, interrupting whatever else is running unless it is a higher priority real-time process. This should not impact performance as chronyd resource requirements are modest, but it should result in lower and more consistent latency since chronyd will not need to wait for the scheduler to get around to running it. You should not use this unless you really need it. The sched_setscheduler(2) man page has more details.

On macOS, this directive uses the thread_policy_set() kernel call to specify real-time scheduling. As noted for Linux, you should not use this directive unless you really need it.

On Linux, chronyd needs to be compiled with support for the libcap library. On macOS, FreeBSD, NetBSD and Solaris chronyd forks into two processes. The child process retains root privileges, but can only perform a very limited range of privileged system calls on behalf of the parent.

The compiled-in default value is root.