from Alice's Adventures in Wonderland, Lewis Carroll
The mushroom knows all the command line options.
Last update:
The ntpd program is an operating system daemon which sets and maintains the system time of day in synchronism with Internet standard time servers. It is a complete implementation of the Network Time Protocol (NTP) version 4, but also retains compatibility with version 3, as defined by RFC-1305, and version 1 and 2, as defined by RFC-1059 and RFC-1119, respectively. ntpd does most computations in 64-bit floating-point arithmetic and does relatively clumsy 64-bit fixed-point operations only when necessary to preserve the ultimate precision, about 232 picoseconds. While the ultimate precision is not achievable with ordinary workstations and networks of today, it may be required with future gigahertz CPU clocks and gigabit LANs.
The ntpd program operates by exchanging messages with one or more configured servers at designated poll intervals. When started, whether for the first or subsequent times, the program requires several exchanges from the majority of these servers so the signal processing and mitigation algorithms can accumulate and groom the data to set the clock. In order to protect the network from bunching, the initial poll interval for each server is delayed an interval randomized over a few seconds. At the default initial poll interval of 64 s, several minutes can elapse before the clock is set. The initial delay to set the clock can be reduced using the iburst keyword with the server configuration command, as described on the Server Options page.
Most operating systems and hardware of today incorporate a time-of-year (TOY) chip to maintain the time during periods when the power is off. When the machine is booted, the chip is used to initialize the operating system time. After the machine has synchronized to a NTP server, the operating system corrects the chip from time to time. In case there is no TOY chip or for some reason its time is more than 1000 s, called the panic threshold, from the server time, ntpd assumes something must be terribly wrong and the only reliable action is for the operator to intervene and set the clock by hand. This causes ntpd to exit with a panic message to the system log. The -g option overrides this check and the clock will be set to the server time regardless of the chip time. However, and to protect against broken hardware, such as when the CMOS battery fails or the clock counter becomes defective, once the clock has been set, an error greater than 1000 s will cause ntpd to exit anyway.
Under ordinary conditions, ntpd adjusts the clock in small steps so that the timescale is effectively continuous and never runs backwards. Under conditions of extreme network congestion, the roundtrip delay jitter can exceed three seconds and the synchronization distance, which is equal to one-half the roundtrip delay plus error budget terms, can become very large. The ntpd algorithms discard offsets exceeding 128 ms, called the step threshold, unless the interval during which no sample offset is less than 128 ms exceeds 900 s, called the stepout threshold. The first sample after that, no matter what the offset, steps the clock to the indicated time. In practice this reduces the false alarm rate where the clock is stepped in error to a vanishingly low incidence.
As the result of this behavior, once the clock has been set, it very rarely strays more than 128 ms, even under extreme cases of network congestion and jitter. Sometimes, in particular when ntpd is first started, the error might exceed 128 ms. This may on occasion cause the clock to be set backwards if the local clock time is more than 128 s in the future relative to the server. In some applications, this behavior may be unacceptable. If the -x option is included on the command line, the clock will always be slewed unless the offset exceeds 600 s (10 minutes), in which case it will be stepped.
The issues should be carefully explored before deciding to use the -x option. The maximum slew rate possible is limited to 500 parts-per-million (PPM) as a consequence of the correctness principles on which the NTP protocol and algorithm design are based. As a result, the local clock can take a long time to converge to an acceptable offset, about 2,000 s for each second the clock is outside the acceptable range. During this interval the local clock will not be consistent with any other network clock and the system cannot be used for distributed applications that require correctly synchronized network time.
The ntpd behavior at startup depends on whether the frequency file, usually called ntp.drift, exists. This file contains the latest estimate of clock frequency offset. When ntpd is started and the file does not exist, ntpd enters a special mode designed to directly measure the particular clock frequency offset. This takes 15 minutes, after which the time and frequency are set to nominal values and ntpd enters normal mode, where the time and frequency are continuously adjusted.
After one hour the frequency file is created and the current frequency offset written to it. When ntpd is started and the file does exist, ntpd initializes the frequency from the file and then enters normal mode immediately. In either case the current frequency offset is written to the file at hourly intervals.
ntpd can operate in any of several modes, including symmetric active/passive, client/server broadcast/multicast and manycast, as described in the Association Management page. It normally operates continuously while adjusting the system clock time and frequency with respect to external sources. In some cases it may not be practical to run ntpd continuously. A common workaround has been to run the ntpdate program from a cron job at designated times. However, this program does not have the crafted signal processing, error checking and mitigation algorithms of ntpd. If the -q option is specified on the command line, ntpd will operate as in continous mode, but exit just after setting the clock for the first time. Most applications will probably want to specify the iburst keyword with the server configuration command. With this keyword a volley of messages is exchanged to groom the data and set the clock in about 10 s. If nothing is heard after a couple of minutes, the daemon times out and exits.
A broadcast/multicast or manycast client can discover remote servers, compute server-client propagation delay correction factors and configure itself automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment. An alternative to broadcast/multicast is manycast mode, in which a client broadcasts a request and one or more servers in range offer service. Further details are on the Automatic NTP Configuration Options page.
By default, ntpd runs in continuous mode where each of possibly several external servers is polled at intervals determined by an intricate phase/frequncy-lock feedback loop. The feedback loop measures the incidental clock offset jitter and oscillator frequency wander and determines the best poll interval using a heuristic algorithm. Ordinarily, and in most operating environments, the feedback loop will start with 64 s poll intervals and eventually increase in steps to 1024 s. A small amount of random variation is introduced in order to avoid bunching. In addition, should a server become unreachable for some time, the poll interval is increased in steps to 1024 s in order to reduce network overhead.
NTP uses an intricate clock discipline algorithm to automatically control the poll interval for maximum accuracy consistent with minimum network load. The default minimum interval is 64 s and the maximum 1024 s, which is suitable for most conditions. The default minimum and maximum intervals can be changed using the tinker minpoll and tinker maxpoll commands, respectively. These values are used for all configured associations, unless overridden by the minpoll or minpoll options on the serverconfiguration command.
In some cases involving dial-up or ISDN toll services, it may be useful to set the minimum interval to 12 (4096 s) and maximum interval to 17 (36 h). Under normal operation conditions, once the clock discipline loop has stabilized the interval will be increased in steps from the minimum to the maximum. However, this assumes the residual clock frequency error is small enough for the discipline loop to capture and correct it. The capture range of the loop is 500 PPM with a 64-s interval decreasing by a factor of two for each interval doubling. At a 36-hr interval, for example, the capture range is only 0.24 PPM. If the frequency changes abruptly, due for instance a large change in temperature, one or more step adjustments may occur.is greater than this, the frequency file ntp.drift
In scenarios where a considerable amount of data are to be downloaded or uploaded over telephone modems, timekeeping quality can be seriously degraded. This occurs because the differential delays on the two directions of transmission can be quite large. In many cases the apparent time errors are so large as to exceed the step threshold and a step correction can occur during and after the data transfer is in progress.
The huff-n'-puff filter is designed to correct the apparent time offset in these cases. It depends on knowledge of the propagation delay when no other traffic is present. In common scenarios this occurs during other than work hours. The filter maintains a shift register that remembers the minimum delay over the most recent interval measured usually in hours. Under conditions of severe delay, the filter corrects the apparent offset using the sign of the offset and the difference between the apparent delay and minimum delay. The name of the filter reflects the negative (huff) and positive (puff) correction, which depends on the sign of the offset.
The filter is activated by the tinker huffpuff command, as described in the Miscellaneous Options page.
As provided by international agreement, an extra second is sometimes inserted in Coordinated Universal Time (UTC) at the end of a selected month, usually June or December. The National Institutes of Standards and Technology (NIST) provides an historic leapseconds file at time.nist.gov for retrieval via FTP. When this file, usually called ntp.leap, is installed, ntpd reads it at startup and initializes three leapsecond values, the offset of International Atomic Time (TAI) after the last leap in the file, the NTP seconds of that leap and the NTP seconds when the leapseconds file expires.
If a host does not have the leapsecond values, they can be obtained over the net using the Autokey security protocol. Ordinarily, the leapseconds file is installed on the primary servers and the values flow from them to dependent servers and eventually clients. When multiple servers are involved, the values with the latest expiration time are used.
If the latest leap is in the past, nothing further is done other than to install the TAI offset in the kernel where it can be retrieved by the ntp_gettimeofday() system call. If the leap is in the future less than 28 days, the leap warning bits are set to insert one second. If in the future less than 23 hours, the kernel is armed to insert one second at the end of the current day. If the kernel is enabled, the leap is done automatically at that time; otherwise, the clock is stepped back one second at that time.
Dependent servers and clients tally the leap warning bits of surviving servers and reference clocks. When a majority of the survivors show warning, a leap is programmed at the end of the current month. During the month and day of insertion, they operate as above. In this way the leap is propagated at all dependent servers and clients.
If ntpd, is configured with NetInfo support, it will attempt to read its configuration from the NetInfo service if the default ntp.conf file cannot be read and no file is specified by the -c option.
In contexts where a host name is expected, a -4 qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a -6 qualifier forces DNS resolution to the IPv6 namespace.
Various internal ntpd variables can be displayed and configuration options altered while the ntpd is running using the ntpq and ntpdc utility programs.
When ntpd starts it looks at the value of umask, and if zero ntpd will set the umask to 022.
Ordinarily, ntpd reads the ntp.conf configuration file at startup time in order to determine the synchronization sources and operating modes. It is also possible to specify a working, although limited, configuration entirely on the command line, obviating the need for a configuration file. This may be particularly useful when the local host is to be configured as a broadcast/multicast client, with all peers being determined by listening to broadcasts at run time.
Usually, the configuration file is installed in the /etc directory, but could be installed elsewhere (see the -c conffile command line option). The file format is similar to other Unix configuration files - comments begin with a # character and extend to the end of the line; blank lines are ignored.
Configuration commands consist of an initial keyword followed by a list of arguments, some of which may be optional, separated by whitespace. Commands may not be continued over multiple lines. Arguments may be host names, host addresses written in numeric, dotted-quad form, integers, floating point numbers (when specifying times in seconds) and text strings. Optional arguments are delimited by [ ] in the following option pages, while alternatives are separated by |. The notation [ ... ] means an optional, indefinite repetition of the last item before the [ ... ].
Server Options
Authentication Options
Monitoring Options
Access Control Options
Automatic NTP Configuration Options
Reference Clock Options
Miscellaneous Options
| File | Default | Option | Command |
| configuration file | /etc/ntp.conf | -c | none |
| frequency file | /etc/ntp.drift | -f | driftfile |
| process ID file | none | -p | pidfile |
| log file | system log | -l | logfile |
| include file | none | none | includefile |
| statistics path | /var/NTP | -s | statsdir |
| keys path | /usr/local/etc | -k | keysdir |