### `ntpd` - Network Time Protocol (NTP) daemon

from Alice's Adventures in Wonderland, Lewis Carroll

The mushroom knows all the command line options.

Last update: 19:27 UTC Sunday, July 01, 2007

#### Related Links

#### Table of Contents

- Synopsis
- Description
- How NTP Operates
- Frequency Discipline
- Operating Modes
- Poll Interval Control
- Leap Second Processing
- Additional Features
- Command Line Options
- The Configuration File
- Configuration Options
- Files

#### Synopsis

`ntpd [ -46aAbdDgLmnNqx ] [ -c conffile ] [ -f driftfile ] [ -i jaildir ] [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -P priority ] [ -r broadcastdelay ] [ -s statsdir ] [ -t key ] [ -u user[:group] ] [ -U interface_update_interval ] [ -v variable ] [ -V variable ]`

#### Description

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.

#### How NTP Operates

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.

#### Frequency Discipline

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.

#### Operating Modes

`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.

#### Poll Interval Control

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 `server`configuration 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`

#### The huff-n'-puff Filter

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.

#### Leap Second Processing

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.

#### Additional Features

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`.

#### Command Line Options

`-a`
  Require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is the default.
`-A`
  Do not require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is almost never a good idea.
`-b`
  Enable the client to synchronize to broadcast servers.
`-c conffile`
  Specify the name and path of the configuration file, default `/etc/ntp.conf`.
`-d`
  Specify debugging mode. This option may occur more than once, with each occurrence indicating greater detail of display.
`-D level`
  Specify debugging level directly.
`-f driftfile`
  Specify the name and path of the frequency file, default `/etc/ntp.drift`. This is the same operation as the `driftfile driftfile` configuration command.
`-g`
  Normally, `ntpd` exits with a message to the system log if the offset exceeds the panic threshold, which is 1000 s by default. This option allows the time to be set to any value without restriction; however, this can happen only once. If the threshold is exceeded after that, `ntpd` will exit with a message to the system log. This option can be used with the `-q` and `-x` options. See the `tinker` command for other options.
`-i jaildir`
  Chroot the server to the directory jaildir. This option also implies that the server attempts to drop root privileges at startup (otherwise, chroot gives very little additional security), and it is only available if the OS supports to run the server without full root privileges. You may need to also specify a `-u` option.
`-k keyfile`
  Specify the name and path of the symmetric key file, default `/etc/ntp.keys`. This is the same operation as the `keys keyfile` configuration command.
`-l logfile`
  Specify the name and path of the log file. The default is the system log file. This is the same operation as the `logfile logfile` configuration command.
`-L`
  Do not listen to virtual IPs. The default is to listen.
`-n`
  Don't fork.
`-N`
  To the extent permitted by the operating system, run the `ntpd` at the highest priority.
`-p pidfile`
  Specify the name and path of the file used to record the `ntpd` process ID. This is the same operation as the `pidfile pidfile` configuration command.
`-P priority`
  To the extent permitted by the operating system, run the `ntpd` at the specified priority.
`-q`
  Exit the `ntpd` just after the first time the clock is set. This behavior mimics that of the `ntpdate` program, which is to be retired. The `-g` and `-x` options can be used with this option. Note: The kernel time discipline is disabled with this option.
`-r broadcastdelay`
  Specify the default propagation delay from the broadcast/multicast server to this client. This is necessary only if the delay cannot be computed automatically by the protocol.
`-s statsdir`
  Specify the directory path for files created by the statistics facility. This is the same operation as the `statsdir statsdir` configuration command.
`-t key`
  Add a key number to the trusted key list. This option can occur more than once.
`-u user[:group]`
  Specify a user, and optionally a group, to switch to. This option is only available if the OS supports to run the server without full root privileges. Currently, this option is supported under NetBSD (configure with --enable-clockctl) and Linux (configure with --enable-linuxcaps).
`-U interface update interval`
  Number of seconds to wait between interface list scans to pick up new and delete network interface. Set to 0 to disable dynamic interface list updating. The default is to scan every 5 minutes.
`-v variable`
`-V variable`
  Add a system variable listed by default.
`-x`
  Normally, the time is slewed if the offset is less than the step threshold, which is 128 ms by default, and stepped if above the threshold. This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s. Thus, an adjustment as much as 600 s will take almost 14 days to complete. This option can be used with the `-g` and `-q` options. See the `tinker` command for other options. Note: The kernel time discipline is disabled with this option.

#### The Configuration File

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 `[ ... ]`.

#### Configuration Options

Server Options
Authentication Options
Monitoring Options
Access Control Options
Automatic NTP Configuration Options
Reference Clock Options
Miscellaneous Options

#### Files

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`