Network Time Protocol (NTP) daemon


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

Runs on:



Force DNS resolution of hosts to the IP4 namespace.
Force DNS resolution of hosts to the IP6 namespace.
Require cryptographic authentication for broadcast client, multicast client, and symmetric passive associations. This is the default.
Don't require cryptographic authentication for broadcast client, multicast client, and symmetric passive associations.
Enable the client to synchronize to broadcast servers.
-c conffile
Specify the name and path of the configuration file; the default is /etc/ntp/ntp.conf. For information about this file, see its entry in the FreeBSD documentation.
Use debugging mode. You can specify this option more than once, with each occurrence producing a greater amount of detail
-D level
Specify the debugging level directly.
-f driftfile
Specify the name and path of the frequency file; the default is as specified by driftfile driftfile configuration command, if present in the ntp.conf file.
Set the panic threshold to any value without any restriction. If the offset exceeds the default value (1000 s) of this panic threshold, ntpd exits with a message to the system log. You can use this option with the -q and -x options. See the tinker command for other options.
-i jaildir
Change the server's root directory to be jaildir. This option also implies that the server attempts to drop root privileges at startup (otherwise, changing the root directory gives little additional security), and it's available only if the OS supports running the server without full root privileges. You may need to also specify the -u option.
-k keyfile
Specify the name and path of the symmetric key file; the default is /etc/ntp/ntp.keys. This is the same operation as the keys keyfile configuration command. For information about this file, see its entry in the FreeBSD documentation.
-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.
Don't listen to virtual IPs. The default is to listen.
Enable the client to synchronize the multicast servers at the IPv4 multicast group address
Don't fork.
Run the ntpd utility 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
Run the ntpd utility at the given priority.
Exit the ntpd utility just after the first time the clock is set. You can use the -g and -x options with this option.
-r broadcastdelay
Specify the default propagation delay from the broadcast/multicast server to this client. This is necessary if the protocol can't automatically compute the delay.
-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.
-v variable
-V variable
Add the given system variable.
Set the step threshold to 600 s. The default value is 128 ms. If the offset is less than (or above) the step threshold, the time is adjusted (or stepped up). You can use this option with the -g and -q options. Please also see the tinker command.


Use the ntpd utility to set and maintain the system time of day in synchronism with the Internet standard time servers. This utility is an operating system daemon that conforms to the NTP (Network Time Protocol) version 4 specification. It also retains compatibility with version 3, as defined by RFC 1305, and version 1 and 2, as defined by RFC 1059 and RFC 1119. Using the 64-bit floating point arithmetic, the ntpd utility attempts to preserve the ultimate precision, which is about 232 picoseconds. While the ultimate precision isn't achievable with today's workstations and networks, it's required for future gigahertz CPU clocks and gigabit LANs.

The ntpd utility normally reads the ntp.conf file for its configuration. For information about this file, see its entry in the FreeBSD documentation.

Basic operation of the ntpd utility

The ntpd utility exchanges messages with one or more configured hosts at designated poll intervals. This is done to groom data and set the clock. Although the default initial poll interval is 64 seconds, the poll interval for each server is delayed by an interval randomized over few seconds, in order to protect the network from bursts.

In order to maintain time during periods when the power is off, today's hardware incorporates a time-of-year (TOY) chip. 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 time gets synchronized and corrected from time to time.

Note: This doesn't set the hardware clock; you can use the rtc utility to set the time on the chip.

Under ordinary conditions, ntpd adjusts the clock in small steps so that the time scale is continuous. Under conditions of extreme network congestion, the ntpd algorithms discard sample offsets exceeding 128 ms, because:

When there is no TOY chip, and the client time is more than 1000 seconds from the server time, you should intervene and set the clock by hand — causing the ntpd utility to exit with a panic message to the system log.

Frequency discipline

The behavior of the ntpd utility at startup depends on the existence of ntp.drift frequency file. This file contains the latest estimate of the clock frequency error. If this file doesn't exist, the ntpd utility enters a special mode designed to quickly adapt to system clock oscillator time and frequency error. After approximately 15 minutes, when the time and frequency are set to nominal values, the ntpd utility starts tracking the time and frequency relative to the server. After one hour, the current frequency offset is written to ntp.drift frequency file. Since the ntpd frequency is initialized from this file, the ntpd utility enters into normal mode immediately during startup. Subsequently, the current frequency offset is written to the ntp.drift frequency file at hourly intervals.

Operating modes

The ntpd utility operates continuously while monitoring for small changes in frequency, trimming the clock for ultimate precision. It operates in one of several modes:

The ntpd utility also operates in one-time mode where the time is set from an external server, and the frequency is set from a previously recorded frequency file. When a client operates in broadcast/multicast or manycast mode, it first discovers the remote server, and then configures itself automatically — after computing the server-client propagation delay correction factors. You can now deploy a fleet of workstations without specifying configuration details that are specific to your local environment.

When the ntpd utility runs in continuous mode, each of the external servers is polled at intervals determined by an intricate state machine. The state machine determines the poll interval using a heuristic algorithm, after measuring the incidental roundtrip delay jitter and oscillator frequency wander. In most operating environments, the state machine starts with intervals of 64 seconds that increase to 1024 seconds, in steps. A small amount of random variation is also introduced, in order to avoid bunching at the servers.

In some cases, it may not be practical for ntpd to run continuously. A common workaround has been to run the ntpdate utility from a cron job at designated times. This utility, however, doesn't have the signal processing, error checking, and mitigation algorithms of the ntpd utility. The -q option is intended for this purpose.

In QNX Neutrino, an useful feature is available to discipline the clock frequency. First, the ntpd utility is run in continuous mode with selected servers in order to measure and record the intrinsic clock frequency offset. This may take hours (for the frequency and offset) to settle down. Then, the ntpd utility is stopped and run in one-time mode as required. At each startup, ntpd reads the frequency from the file and initializes the kernel frequency.

Poll interval control

The state machine for ntpd maintains synchronization consistent with the observed jitter and wander. You have several ways to tailor the operation of the ntpd utility, for example, either by reducing or increasing the poll interval. You must be careful, however, to consider the consequences of changing the adjustment range for poll intervals.

Note: The default minimum for poll interval is 64 seconds, and the default maximum is 1,024 seconds.

You can change the default minimum with the tinker minpoll command to a value not less than 16 seconds. This value is used for all configured associations, unless overridden by the minpoll option on the configuration command. Most of the device drivers don't operate properly if the poll interval is less than 64 seconds.

In some cases involving dialup or toll services, you may also increase the minimum interval to a few tens of minutes and the maximum interval to a day or so. Under normal operating conditions, once the clock discipline loop has stabilized, the interval is increased in steps from the minimum to the maximum value. This assumes, however, that the intrinsic clock frequency error is small enough for the discipline loop to correct it. The capture range of the loop is 500 PPM at an interval of 64 seconds, decreasing by a factor of two for each doubling of interval. At a minimum of 1,024 seconds, for example, the capture range is only 31 PPM. If the intrinsic error is greater than this, the ntp.drift drift file is specially tailored to reduce the residual error below this limit. Once this is done, the drift file is automatically updated once every hour and is available to initialize the frequency on subsequent daemon restarts.

The huff-n'-puff filter

Timekeeping quality may seriously degrade in certain scenarios, for example, when a considerable amount of data is to be downloaded or uploaded over telephone modems. This occurs because differential delays during transmission on two directions can be quite large. Sometimes, time errors even exceed the step threshold, resulting in step correction during and after the data transfer.

Use the huff-n'-puff filter to correct the time offset in these cases. It uses the knowledge of the propagation delay when no other traffic is present, i.e. during other than work hours. The filter maintains a shift register that remembers the minimum delay over the most recent interval that is measured 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 command and huffpuff keyword.

See also:

ntpdate, ntpdc, ntpq, ntptrace, rtc

ntp.conf, ntp.keys in the FreeBSD documentation

Based on RFC 1059, RFC 1119, RFC 1305