Files Reference

ntp.conf File

Purpose

Controls how the Network Time Protocol (NTP) daemon xntpd operates and behaves.

Description

The ntp.conf file is a basic configuration file controlling the xntpd daemon.

The following options are discussed in this article:

Configuration Options

In the ntp.conf file, comments begin with a # character and extend to the end of the line. Blank lines are ignored. Options consist of an initial keyword followed by a list of arguments, which may be optional, separated by whitespace. These options may not be continued over multiple lines. Arguments may be host names, host addresses written in numeric (dotted decimal) form, integers, floating point numbers (when specifying times in seconds) and text strings.

Option	Description
peer [ HostAddress ] [ key Number ] [ version Number ] [ prefer ]
	Specifies that the local server operate in symmetric active mode with the remote server specified by HostAddress. In this mode, the local server can be synchronized to the remote server, or the remote server can be synchronized to the local server. Use this method in a network of servers where, depending on various failure scenarios, either the local or remote server host may be the better source of time. The key Number specifies that all packets sent to HostAddress include authentication fields encrypted using the specified key number. The value of KeyNumber is the range of an unsigned 32 bit integer. The version Number specifies the version number to use for outgoing NTP packets. The values for Version can be 1 or 2. The default is NTP version 3 implementation. The prefer option marks the host as a preferred host. This host is not subject to preliminary filtering.
server [ HostAddress ] [ key Number ] [ version Number ] [ prefer ] [ mode Number ]
Specifies that the local server operate in client mode with the remote server specified by HostAddress. In this mode, the local server can be synchronized to the remote server, but the remote server can never be synchronized to the local server. The key Number specifies that all packets sent to HostAddress include authentication fields encrypted using the specified key number. The value of KeyNumber is the range of an unsigned 32 bit integer. The version Number specifies the version number to use for outgoing NTP packets. The values for Version can be 1 or 2. The default is NTP version 3 implementation. The prefer argument marks the host as a preferred host. This host is not subject to preliminary filtering.
broadcast [ HostAddress ] [ key Number ] [ version Number ] [ ttl Number ]
	Specifies that the local server operate in broadcast mode where the local server sends periodic broadcast messages to a client population at the broadcast/multicast address specified by HostAddress. Ordinarily, this specification applies only to the local server operating as a transmitter. In this mode, HostAddress is usually the broadcast address on [one of] the local network[s] or a multicast address. The address assigned to NTP is 224.0.1.1; presently, this is the only number that should be used. The key Number specifies that all packets sent to HostAddress include authentication fields encrypted using the specified key number. The value of Number is the range of an unsigned 32 bit integer. The version Number specifies the version number to use for outgoing NTP packets. The values for Version can be 1 or 2. The default is NTP version 3 implementation. The ttl Number is used only with the broadcast mode. It specifies the time-to-live (TTL) to use on multicast packets. This value defaults to 127.
broadcastclient	Specifies that the local server listen for broadcast messages on the local network in order to discover other servers on the same subnet. When the local server hears a broadcast message for the first time, it measures the nominal network delay using a brief client/server exchange with the remote server, then enters the broadcastclient mode, where it listens for and synchronizes to succeeding broadcast messages.
multicastclient [ IPAddress ... ]	Works like broadcastclient configuration option, but operates using IP multicasting. If you give one or more IP addresses, the server joins the respective multicast group(s). If you do not give an IP address, the IP address assumed is the one assigned to NTP (224.0.1.1).
driftfile Filename	Specifies the name of the file used to record the frequency offset of the local clock oscillator. The xntpd daemon reads this file at startup, if it exists, in order to set the initial frequency offset and then updates it once per hour with the current offset computed by the daemon. If the file does not exist or you do not give this option, the initial frequency offset assumed is zero. In this case, it may take some hours for the frequency to stabilize and the residual timing errors to subside. The file contains a single floating point value equal to the offset in parts-per-million (ppm). Note The update of the file occurs by first writing the current drift value into a temporary file and then using rename??? to replace the old version. The xntpd daemon must have write permission in the directory of the drift file, and you should avoid file system links, symbolic or otherwise.
enable auth \| bclient \| pll \| monitor \| stats [ ... ]
	Enables various server options. Does not affect arguments not mentioned. The auth option causes the server to synchronize with unconfigured peers only if the peer has been correctly authenticated using a trusted key and key identifier. The default for this argument is disable (off). The bclient option causes the server to listen for a message from a broadcast or multicast server, following which an association is automatically instantiated for that server. The default for this argument is disable (off). The pll option enables the server to adjust its local clock, with default enable (on). If not set, the local clock free-runs at its intrinsic time and frequency offset. This option is useful when the local clock is controlled by some other device or protocol and NTP is used only to provide synchronization to other clients. The monitor option enables the monitoring facility, with default enable (on). The stats option enables statistics facility filegen, with default enable (on).
disable auth \| bclient \| pll \| monitor \| stats [ ... ]
	Disables various server options. Does not affect arguments not mentioned. The options are described under the enable subcommand.

Configuration Authentication Options

Option	Description
keys Filename	Specifies the name of a file which contains the encryption keys and key identifiers used by the xntpd daemon when operating in authenticated mode.
trustedkey Number [ Number ... ]	Specifies the encryption key identifiers which are trusted for the purposes of authenticating peers suitable for synchronization. The authentication procedures require that both the local and remote servers share the same key and key identifier for this purpose, although you can use different keys with different servers. Each Number is a 32 bit unsigned integer. Note The NTP key 0 is fixed and globally known. To perform meaningful authentication, the 0 key should not be trusted.
requestkey Number	Specifies the key identifier to use with the xntpdc query/control program that diagnoses and repairs problems that affect the operation of the xntpd daemon. The operation of the xntpdc query/control program is specific to this particular implementation of the xntpd daemon and can be expected to work only with this and previous versions of the daemon. Requests from a remote xntpdc program which affect the state of the local server must be authenticated, which requires both the remote program and local server share a common key and key identifier. The value of Number is a 32 bit unsigned integer. If you do not include requestkey in the configuration file, or if the keys do not match, such requests are ignored.
controlkey Number	Specifies the key identifier to use with the ntpq query program, that diagnoses problems that affect the operation of the xntpd daemon. The operation of the ntpq query program and the xntpd daemon conform to those specified in RFC 1305. Requests from a remote ntpq program which affect the state of the local server must be authenticated, which requires both the remote program and local server share a common key and key identifier. The value of Number is a 32 bit unsigned integer. If you do not include controlkey in the configuration file, or if the keys do not match, such requests are ignored.
authdelay Seconds	Specifies the amount of time it takes to encrypt an NTP authentication field on the local computer. This value corrects transmit timestamps when using authentication on outgoing packets. The value usually lies somewhere in the range 0.0001 seconds to 0.003 seconds, though it is very dependent on the CPU speed of the host computer.

Configuration Access Control Options

The xntpd daemon inserts default restriction list entries, with the parameters ignore and ntpport, for each of the local host's interface addresses into the table at startup to prevent the server from attempting to synchronize to its own time. A default entry is also always present, though if it is otherwise unconfigured it does not associate parameters with the default entry (everything besides your own NTP server is unrestricted).

While this facility may be useful for keeping unwanted or broken remote time servers from affecting your own, do not consider it an alternative to the standard NTP authentication facility.

restrict Address [ mask Number | default ] [ Parameter ... ]

Specifies the restrictions to use on the given address. The xntpd daemon implements a general purpose address-and-mask based restriction list. The xntpd daemon sorts this list by address and by mask, and searches the list in this order for matches, with the last match found defining the restriction flags associated with the incoming packets. The xntpd daemon uses the source address of incoming packets for the match, doing a logical and operation with the 32 bit address and the mask associated with the restriction entry. It then compares it with the entry's address (which has also been and'ed with the mask) to look for a match. The mask option defaults to 255.255.255.255, meaning that Address is treated as the address of an individual host. A default entry (address 0.0.0.0, mask 0.0.0.0) is always included and is always the first entry in the list. The text string default, with no mask option, may be used to indicate the default entry.

In the current implementation, Parameter always restricts access. An entry with no Parameter gives free access to the server. More restrictive Parameters will often make less restrictive ones redundant. The Parameters generally restrict time service or restrict informational queries and attempts to do run time reconfiguration of the server. You can specify one or more of the following value for Parameter:

ignore: Specifies to ignore all packets from hosts which match this entry. Does not respond to queries nor time server polls.
limited: Specifies that these hosts are subject to limitation of number of clients from the same net. Net in this context refers to the IP notion of net (class A, class B, class C, and so on). Only accepts the first client_limit hosts that have shown up at the server and that have been active during the last client_limit_period seconds. Rejects requests from other clients from the same net. Only takes into account time request packets. Private, control, and broadcast packets are not subject to client limitation and therefore do not contribute to client count. The monitoring capability of the xntpd daemon keeps a history of clients. When you use this option, monitoring remains active. The default value for client_limit is 3. The default value for client_limit_period is 3600 seconds.
lowpriotrap: Specifies to declare traps set by matching hosts to low-priority status. The server can maintain a limited number of traps (the current limit is 3), assigned on a first come, first served basis, and denies service to later trap requestors. This parameter modifies the assignment algorithm by allowing later requests for normal priority traps to override low-priority traps.
nomodify: Specifies to ignore all NTP mode 6 and 7 packets which attempt to modify the state of the server (run time reconfiguration). Permits queries which return information.
nopeer: Specifies to provide stateless time service to polling hosts, but not to allocate peer memory resources to these hosts.
noquery: Specifies to ignore all NTP mode 6 and 7 packets (information queries and configuration requests) from the source. Does not affect time service.
noserve: Specifies to ignore NTP packets whose mode is not 6 or 7. This denies time service, but permits queries.
notrap: Specifies to decline to provide mode 6 control message trap service to matching hosts. The trap service is a subsystem of the mode 6 control message protocol intended for use by remote event-logging programs.
notrust: Specifies to treat these hosts normally in other respects, but never use them as synchronization sources.
ntpport: Specifies to match the restriction entry only if the source port in the packet is the standard NTP UDP port (123).

clientlimit Number

Sets client_limit. Specifies the number of clients from the same network allowed to use the server. Allows the configuration of client limitation policy.

clientperiod Seconds

Sets client_limit_period. Specifies the number of seconds to before considering if a client is inactive and no longer counted for client limit restriction. Allows the configuration of client limitation policy.

Configuration Monitoring Options

File generation sets manage statistical files. The information obtained by enabling statistical recording allows analysis of temporal properties of a server running the xntpd daemon. It is usually only useful to primary servers.

statsdir DirectoryPath

Specifies the full path of the directory in which to create statistical files. Allows modification of the otherwise constant filegen filename prefix for file generation sets used for handling statistical logs.

statistics Type...

Enables writing of statistical records. The following are the types of statistics supported:

loopstats

Enables recording of loop filter statistical information. Each update of the local clock outputs a line of the following format to the file generation set named loopstats:

48773 10847.650 0.0001307 17.3478 2

The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next three fields show time offset in seconds, frequency offset in parts-per-million and time constant of the clock-discipline algorithm at each update of the clock.

peerstats

Enables recording of peer statistical information. This includes statistical records of all peers of an NTP server and of the 1-pps signal, where present and configured. Each valid update appends a line of the following format to the current element of a file generation set named peerstats:

48773 10847.650 127.127.4.1 9714 -0.001605 
0.00000 0.00142

The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next two fields show the peer address in dotted-quad notation and status, respectively. The status field is encoded in hex in the format described in Appendix A of the NTP specification RFC 1305. The final three fields show the offset, delay and dispersion, all in seconds.

clockstats

Enables recording of clock driver statistical information. Each update received from a clock driver outputs a line of the following form to the file generation set named clockstats:

49213 525.624 127.127.4.1 93 226 
00:08:29.606 D

The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next field shows the clock address in dotted-quad notation, The final field shows the last timecode received from the clock in decoded ASCII format, where meaningful. You can gather and display a good deal of additional information in some clock drivers.

filegen Name [ file FileName ] [ type TypeName ] [ flag flagval ] [ link ] [ nolink ] [ enable ] [ disabled ]

Configures setting of generation fileset name. Generation filesets provide a means for handling files that are continuously growing during the lifetime of a server. Server statistics are a typical example for such files. Generation filesets provide access to a set of files used to store the actual data. A file generation set is characterized by its type. At any time, at most one element of the set is being written to. Filenames of set members are built from three elements:

Prefix

This is a constant filename path. It is not subject to modifications with the filegen option. It is defined by the server, usually specified as a compile time constant. You can, however, configure it for individual file generation sets with other commands. For example, you can configure the prefix used with loopstats and peerstats filegens using the statsdir option.

file FileName

The string FileName is directly concatenated to the prefix with no intervening slash (/). You can modify this by using the file argument to the filegen option. To prevent filenames referring to parts outside the filesystem hierarchy denoted by prefix, ".." elements are not allowed in this component

Suffix

This part reflects individual elements of a fileset. It is generated according to the type of a fileset.

type TypeName

Specifies when and how to direct data to a new element of the set. This way, information stored in elements of a fileset that are currently unused are available for administrational operations without the risk of disturbing the operation of the xntpd daemon. Most important, you can remove them to free space for new data produced. The following types are supported:

none: Specifies that the fileset is actually a single plain file.
pid: Specifies the use of one element of fileset per server running the xntpd daemon. This type does not perform any changes to fileset members during runtime; however, it provides an easy way of separating files belonging to different servers running the xntpd daemon. The set member filename is built by appending a dot (.) to concatenated prefix and strings denoted in file Name, and appending the decimal representation of the process id of the xntpd server process.
day: Specifies the creation of one file generation set element per day. The term day is based on UTC. A day is the period between 00:00 and 24:00 UTC. The fileset member suffix consists of a dot (.) and a day specification in the form YYYYMMDD. where YYYY is a 4 digit year number, MM is a two digit month number, and, DD is a two digit day number. For example, all information written at January 10th, 1992 would end up in a file named PrefixFileName.19920110.
week: Specifies the creation of one file generation set element per week. A week is computed as day-of-year modulo 7. The fileset member suffix consists of a dot (.), a four digit year number, the letter W, and a two digit week number. For example, all information written at January, 10th 1992 would end up in a file named PrefixFileName.1992W1.
month: Specifies the creation of one file generation set element per month. The fileset member suffix consists of a dot (.), a four digit year number, and a two digit month number. For example, all information written at January, 1992 would end up in a file named PrefixFileName.199201.
year: Specifies the creation of one file generation set element per year. The fileset member suffix consists of a dot (.) and a four digit year number. For example, all information written at January, 1992 would end up in a file named PrefixFileName.1992.
age: Specifies the creation of one file generation set element every 24 hours of server operation. The fileset member suffix consists of a dot (.), the letter a, and an eight digit number. This number is the number of seconds of run-time of the server since the start of the corresponding 24 hour period.

enable

Enables the writing of information to a file generation set.

disabled

Disables the writing of information to a file generation set.

link

Enables the access of the current element of a file generation set by a fixed name by creating a hard link from the current fileset element to a file without Suffix. If a file with this name already exists and the number of links of this file is one, it is renamed by appending a dot (.), the letter C, and the pid of the xntpd server process. If the number of links is greater than one, the file is unlinked. This allows access of the current file by a constant name.

nolink

Disables access the current element of a file generation set by a fixed name.

Miscellaneous Configuration Options

Option	Description
precision Number	Specifies the nominal precision of the local clock. The Number is an integer approximately equal to the base 2 logarithm of the local timekeeping precision in seconds. Normally, the xntpd daemon determines the precision automatically at startup, so use this option when the xntpd daemon cannot determine the precision automatically.
broadcastdelay Seconds	Specifies the default delay to use when in broadcast or multicast modes. These modes require a special calibration to determine the network delay between the local and remote servers. Normally, this is done automatically by the initial protocol exchanges between the local and remote servers. In some cases, the calibration procedure may fail due to network or server access controls, for example. Typically for Ethernet, a number between 0.003 and 0.007 seconds is appropriate. The default is 0.004 seconds.
trap HostAddress [ port Number ] [ interface Addess ]
Configures a trap receiver at the given host address and port number for sending messages with the specified local interface address. If you do not specify the port number, the value defaults to 18447. If you do not specify the interface address, the value defaults to the source address of the local interface. Note On a multihomed host, the interface used may vary from time to time with routing changes. Normally, the trap receiver logs event messages and other information from the server in a log file. While such monitor programs may also request their own trap dynamically, configuring a trap receiver ensures that when the server starts, no messages are lost.
setvar Variable [ default ]	Specifies to add an additional system variable. You can use these variables to distribute additional information such as the access policy. If default follows a variable of the from Name=Value , then the variable becomes part of the default system variables, as if you used the ntpq rv command. These additional variables serve informational purposes only; they are not related to the protocol variables. The known protocol variables always override any variables defined with setvar. There are three special variables that contain the names of all variables of the same group. The sys_var_list holds the names of all system variables, the peer_var_list holds the names of all peer variables, and the clock_var_list holds the names of the reference clock variables.
logconfig Key	Controls the amount of output written to syslog or the logfile. By default all output is turned on. You can prefix all KeyWords with = (equal), + (plus) and - (dash). You can control four classes of messages: sys, peer, clock, and sync. Within these classes, you can control four types of messages: info Outputs informational messages that control configuration information. events Outputs event messages that control logging of events (reachability, synchronization, alarm conditions). status Outputs statistical messages that describe mainly the synchronization status. all Outputs all messages having to do with the specified class and suppresses all other events and messages of the classes not specified. You form the KeyWord by concatenating the message class with the event class. To just list the synchronization state of xntp and the major system events, enter: logconfig =syncstatus +sysevents To list all clock information and synchronization information and have all other events and messages about peers, system events and so on suppressed, enter: logconfig =syncall +clockall

Files

/etc/ntp.conf

Specifies the path to the file.

Related Information

The xntpdc command, the xntpd daemon.

The ntp.keys file.