ntpd(ADMN)

Syntax

Description

The daemon can operate in any of several modes, including symmetric active/passive, client/server and broadcast/multicast, as described in RFC 1305. A broadcast/multicast 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.

Ordinarily, ntpd reads the /etc/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 appropriate when the local host is to be configured as a broadcast or multicast client, with all peers being determined by listening to broadcasts at run time. Various internal ntpd variables can be displayed and configuration options altered while the daemon is running using the ntpq(ADMN) and ntpdc(ADMN) utility programs.

ntpd checks the value of umask at startup. If it is zero, ntpd sets the value to 022.

Options

-a

Enable authentication mode. This default is enabled, so this option is now obsolete.

-A

Disable authentication mode.

-b

Synchronize using NTP broadcast messages.

-c conffile

Specify the name and path of the configuration file.

-d

Specify debugging mode. This flag may occur multiple times, with each occurrence indicating a greater detail of display.

-D level

Specify debugging level directly.

-f driftfile

Specify the name and path of the drift file.

-g

Normally, ntpd will refuse to correct a clock which is determined to be off by more than 1000 seconds; in that case, ntpd would log an error message and quit. This flag tells ntpd to go ahead and attempt to correct any clock offset, no matter how large.

-k keyfile

Specify the name and path of the file containing the NTP authentication keys.

-l logfile

Specify the name and path of the log file. The default is the system log facility.

-L

Listen to virtual IP's.

-m

Synchronize using NTP multicast messages on the IP multicast group address 224.0.1.1 (requires multicast kernel).

-n

Don't fork.

-N high

To the extent permitted by the operating system, run the daemon at a high priority.

-p pidfile

Specify the name and path to record the daemon's process ID.

-P

Override the priority limit set by the operating system; use with caution.

-r broadcastdelay

Specify the default propagation delay from the broadcast/multicast server and this computer. This is used only if the delay cannot be computed automatically by the protocol.

-s statsdir

Specify the directory path for files created by the statistics facility.

-t key

Add a key number to the trusted key list.

-v variable

Add a system variable.

-V variable

Add a system variable listed by default.

-x

Prevents ntpd from ever stepping the clock backwards in time.

The configuration file

While there is a rich set of options available, the only required option is one or more server, peer, broadcast or manycastclient commands described in ``Configuration options'' (below). More information on these options can be found in ``Configuring the Network Time Protocol (NTP)'' in the Networking Guide.

Configuration options

The various modes are determined by the command keyword and the type of the required IP address. Addresses are classed by type as (s) a remote server or peer (IP class A, B and C), (b) the broadcast address of a local interface, (m) a multicast address (IP class D), or (r) a reference clock address (127.127.x.x). Note that only those options applicable to each command are listed below. Use of options not listed may not be caught as an error, but may result in some weird and even destructive behavior.

The following three commands specify the time server name or address to be used, and the mode in which to operate. The address can either be a DNS name or an IP address in dotted-quad notation. Additional information on association behavior can be found in the Association Management page.

peer address [key key] [version version] [prefer] [minpoll int] [maxpoll int]

For type s addresses (only), this command mobilizes a persistent symmetric-active mode association with the specified remote peer. In this mode the local clock can be synchronized to the remote peer or the remote peer can be synchronized to the local clock. This is useful in a network of servers where, depending on various failure scenarios, either the local or remote peer may be the better source of time. This command should NOT be used for type b, m or r addresses.

server address [key key] [version version] [prefer] [mode mode]

For type s and r addresses, this command mobilizes a persistent client mode association with the specified remote server or local radio clock. In this mode the local clock can synchronized to the remote server, but the remote server can never be synchronized to the local clock. This command should NOT be used for type b or m addresses.

broadcast address [key key] [version version] [ttl ttl]

For type b and m addresses (only), this command mobilizes a persistent broadcast mode association. Multiple commands can be used to specify multiple local broadcast interfaces (subnets) and/or multiple multicast groups. Note that local broadcast messages go only to the interface associated with the subnet specified, but multicast messages go to all interfaces.

In broadcast mode the local server sends periodic broadcast messages to a client population at the address specified, which is usually the broadcast address on (one of) the local network(s) or a multicast address assigned to NTP. The IANA has assigned the multicast group address 224.0.1.1 exclusively to NTP, but other nonconflicting addresses can be used to contain the messages within administrative boundaries. Ordinarily, this specification applies only to the local server operating as a sender; for operation as a broadcast client, see the broadcastclient or multicastclient commands below.

manycastclient address [key key | autokey] [version version] [minpoll minpoll] [maxpoll maxpoll] [ttl ttl]

For type m addresses (only), this command mobilizes a manycast client mode association for the multicast address specified. In this case a specific address must be supplied which matches the address used on the manycastserver command for the designated manycast servers. The NTP multicast address 224.0.1.1 assigned by the IANA should NOT be used, unless specific means are taken to avoid spraying large areas of the Internet with these messages and causing a possibly massive implosion of replies at the sender.

The manycast command specifies that the local server is to operate in client mode with the remote servers that are discovered as the result of broadcast/multicast messages. The client broadcasts a request message to the group address associated with the specified address and specifically enabled servers respond to these messages. The client selects the servers providing the best time and continues as with the server command. The remaining servers are discarded as if never heard.

Options

key key

All packets sent to the address are to include authentication fields encrypted using the specified key identifier, which is an unsigned 32-bit integer. The default is to not include an encryption field.

minpoll int

Specifies the minimum polling interval for NTP messages, in seconds to the power of two. The allowable range is 4 (16 s to 14 (16384 s) inclusive. The default is 6 (64 s) for all except modem reference clocks, where the default is 10 (1024 s).

maxpoll int

Specifies the maximum polling interval for NTP messages, in seconds to the power of two. The allowable range is 4 (16 s to 14 (16384 s) inclusive. The default is 6 (64 s) for all except modem reference clocks, where the default is 14 (16384 s).

version version

Specifies the version number to be used for outgoing NTP packets. Versions 1, 2, and 3 are the choices, with version 3 being the default.

prefer

Marks the server as preferred. All other things being equal, this host will be chosen for synchronization among a set of correctly operating hosts.

ttl ttl

This option is used only with broadcast mode. It specifies the time-to-live ttl to use on multicast packets. Selection of the proper value (which defaults to 127) must be coordinated with the network administrators.

broadcastclient [address]

This command directs the local server to listen for broadcast messages at the broadcast address address of the local network. The default address is the subnet address with the host field bits set to ones. Upon hearing a broadcast message for the first time, the local server measures the nominal network delay using a brief client/server exchange with the remote server, then enters the broadcastclient mode, in which it listens for, and synchronizes to, succeeding broadcast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the local and remote servers should operate using authentication and the same trusted key and key identifier.

multicastclient [address] [...]

This command directs the local server to listen for multicast messages at the group addresses of the global network. The default address is that assigned to NTP (224.0.1.1). This command operates in the same way as the broadcastclient command, but uses IP multicasting.

driftfile driftfile

This command specifies the name of the file used to record the frequency offset of the local clock oscillator. If the file exists, it is read at startup in order to set the initial frequency offset and then updated once per hour with the current frequency offset computed by the daemon. If the file does not exist or this command is not given, the initial frequency offset is assumed to be zero. In this case, it may take some hours for the frequency to stabilize and the residual timing errors to subside.

The ntp.drift file format consists of a single line containing a single floating point number, which records the frequency offset measured in parts-per-million (ppm). The file is updated once per hour by first writing the current drift value into a temporary file and then renaming this file to replace the old version. This implies that ntpd must have write permission for the directory in which the drift file is located, and that file system links (symbolic or otherwise) should probably be avoided.

enable auth | bclient | monitor | pll | pps | stats

disable auth | bclient | monitor | pll | pps | stats

Provides a way to enable or disable various server options. Flags not mentioned are unaffected. Note that all of these flags can be controlled remotely using the ntpdc(ADMN) utility program.

auth

Enables 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 flag is enable.

bclient

Enables the server to listen for a message from a broadcast or multicast server, as in the multicastclient command with default address. The default for this flag is disable.

monitor

Enables the monitoring facility. See the ntpdc program and the monlist command for further information. The default for this flag is enable.

pll

Enables the server to adjust its local clock by means of NTP. If disabled, the local clock free-runs at its intrinsic time and frequency offset. This flag is useful in case the local clock is controlled by some other device or protocol, and NTP is used only to provide synchronization to other clients. In this case, the local clock driver is used. See ``Reference clock options'' for further information. The default for this flag is enable.

pps

Enables the pulse-per-second (PPS) signal when frequency and time is disciplined by the precision time kernel modifications. The default for this flag is disable.

stats

Enables the statistics facility. The default for this flag is enable. For further information, see ``Monitoring options''.

tick value

If no value for tick can be found from the kernel, use this value. This is the "normalized" value; if your system keeps tick in nanoseconds you must divide your value by 1000. The expected range of the value is between 900 and 11,000 (do not use the comma in the config file).

tickadj value

If no value for tickadj can be found in the kernel, use this value. The value must be "normalized"; if your system keeps tickadj in nanoseconds you must divide your value by 1000. The expected range of the value is between 1 and 50.

broadcastclient This command enables reception of broadcast server messages to any local interface (type b) address. Upon receiving a message for the first time, the broadcast client measures the nominal server propagation delay using a brief client/server exchange with the server, then enters the broadcast client mode, in which it synchronizes to succeeding broadcast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric-key or public-key authentication as described in the Authentication Options page. manycastserver address [...] This command enables reception of manycast client messages to the multicast group address(es) (type m) specified. At least one address is required, but The NTP multicast address 224.0.1.1 assigned by the IANA should NOT be used, unless specific means are taken to limit the span of the reply and avoid a possibly massive implosion at the original sender. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric-key or public-key authentication as described in the Authentication Options page. multicastclient [address] [...] This command enables reception of multicast server messages to the multicast group address(es) (type m) specified. Upon receiving a message for the first time, the multicast client measures the nominal server propagation delay using a brief client/server exchange with the server, then enters the broadcast client mode, in which it synchronizes to succeeding multicast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric-key or public-key authentication as described in the Authentication Options page.

Authentication options

Authentication support

Keys and related information are specified in a key file, which should be exchanged and stored using secure procedures beyond the scope of the protocol. There are three classes of keys involved in the current implementation. One class is used for ordinary NTP associations, another for the ntpq(ADMN) utility program, and the third for the ntpdc(ADMN) utility program.

Authentication commands

keys keyfile

Specifies the filename containing the encryption keys and key identifiers used by ntpd, ntpq(ADMN) and ntpdc(ADMN) when operating in authenticated mode. The format of this file is described in ``Authentication key file format''.

trustedkey key [...]

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 different keys can be used with different servers. The key arguments are 32-bit unsigned integers. Note that NTP key 0 is fixed and globally known. If meaningful authentication is to be performed, then the 0 key should not be trusted.

requestkey key

Specifies the key identifier to use with the ntpdc program, which uses a proprietary protocol specific to this implementation of ntpd. This program is useful to diagnose and repair problems that affect ntpd operation. The key argument to this command is a 32-bit unsigned integer. If no requestkey command is included in the configuration file, or if the keys do not match, then such requests will be ignored.

controlkey key

Specifies the key identifier to use with the ntpd program, which uses the standard protocol defined in RFC 1305. This program is useful to diagnose and repair problems that affect ntpd operation. The key argument to this command is a 32-bit unsigned integer. If no requestkey command is included in the configuration file, or if the keys do not match, such requests will be ignored.

authdelay delay

Specifies the amount of time it takes to encrypt an NTP authentication field on the local computer. This value is used to correct transmit timestamps when the authentication is used on outgoing packets. The value usually lies somewhere in the range of 0.0001 seconds to 0.003 seconds, though it is very dependent on the CPU speed of the host computer.

Authentication key file format

The key file uses the same comment conventions as the configuration file. Key entries use a fixed format of the form:

keyno type key

where keyno is a positive integer, type is a single character which defines the key format, and key is the key itself.

The key may be given in one of four different formats, controlled by the type character. The four key types, and corresponding formats, are:

S

The key is a 64-bit hexadecimal number in the format specified in the DES specification; that is, the high order seven bits of each octet are used to form the 56-bit key while the low-order bit of each octet is given a value such that odd parity is maintained for the octet. Leading zeroes must be specified (that is, the key must be exactly 16 hex digits long) and odd parity must be maintained. Hence a zero key, in standard format, would be given as 0101010101010101.

N

The key is a 64-bit hexadecimal number in the format specified in the NTP standard. This is the same as the DES format, except the bits in each octet have been rotated one bit right so that the parity bit is now the high-order bit of the octet. Leading zeroes must be specified and odd parity must be maintained. A zero key in NTP format would be specified as 8080808080808080.

A

The key is a 1 to 8 character ASCII string. A key is formed from this by using the low-order 7 bits of each ASCII character in the string, with zeroes added on the right when necessary to form a full width 56-bit key, in the same way that encryption keys are formed from Unix passwords.

M

The key is a 1 to 8 character ASCII string, using the MD5 authentication scheme. Note that both the keys and the authentication schemes (DES or MD5) must be identical between a set of peers sharing the same key number.

Monitoring options

Monitoring support

Monitoring commands

statistics name [...]

Enables writing of statistics records. Currently, three kinds of name statistics are supported:

loopstats

Enables recording of loop filter statistics information. Each update of the local clock outputs a line of the following form 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 statistics information. This includes statistics records of all peers of a NTP server and of special signals, where present and configured. Each valid update appends a line of the following form 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 statistics 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. In some clock drivers a good deal of additional information can be gathered and displayed as well. See information specific to each clock for further details.

statsdir directory_path

Indicates the full path of a directory where statistics files should be created (see below). This keyword allows the (otherwise constant) filegen filename prefix to be modified for file generation sets, which is useful for handling statistics logs.

filegen name [file filename] [type typename] [flag flagval] [link | nolink] [enable | disable]

Configures setting of generation file set name. Generation file sets 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 file sets provide access to a set of files used to store the actual data. At any time, at most one element of the set is being written to. The type given specifies when and how data will be directed to a new element of the set. This way, information stored in elements of a file set that are currently unused are available for administrational operations without the risk of disturbing the operation of ntpd. (Most important: they can be removed to free space for new data produced.)

Filenames of set members are built from three elements:

prefix

This is a constant filename path. It is not subject to modifications via the filegen option. It is defined by the server, usually specified as a compile-time constant. It may, however, be configurable for individual file generation sets via other commands. For example, the prefix used with loopstats and peerstats generation can be configured using the statsdir option explained above.

filename

This string is directly concatenated to the prefix mentioned above (no intervening ``/''). This can be modified using the file argument to the filegen statement. No ``..'' elements are allowed in this component to prevent filenames referring to parts outside the filesystem hierarchy denoted by prefix.

suffix

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

A file generation set is characterized by its type. The following types are supported:

none

The file set is actually a single plain file.

pid

One element of file set is used per incarnation of an ntpd server. This type does not perform any changes to file set members during runtime, however it provides an easy way of separating files belonging to different ntpd server incarnations. The set member filename is built by appending a ``.'' to concatenated prefix and filename strings, and appending the decimal representation of the process ID of the ntpd server process.

day

One file generation set element is created per day. A day is defined as the period between 00:00 and 24:00 UTC. The file set member suffix consists of a ``.'' and a day specification in the form YYYYMMDD, where YYYY is a four-digit year number; MM is a two-digit month number and DD is a two-digit day number. Thus, all information written at 10 December 1992 would end up in a file named prefix filename.19921210.

week

Any file set member contains data related to a certain week of a year. The term week is defined by computing day-of-year modulo 7. Elements of such a file generation set are distinguished by appending the following suffix to the file set filename base: a dot, a four-digit year number, the letter ``W'', and a two-digit week number. For example, information from January, 10th 1992 would end up in a file with suffix .1992W1.

month

One generation file set element is generated per month. The file name suffix consists of a dot, a four-digit year number, and a two-digit month.

year

One generation file element is generated per year. The filename suffix consists of a dot and a four-digit year number.

age

This type of file generation sets changes to a new element of the file set every 24 hours of server operation. The filename suffix consists of a dot, the letter ``a'', and an eight-digit number. This number is taken to be the number of seconds the server is running at the start of the corresponding 24-hour period.

Information is only written to a file generation by specifying enable; output is prevented by specifying disable.

It is convenient to be able to access the current element of a file generation set by a fixed name. This feature is enabled by specifying link and disabled using nolink. If link is specified, a hard link from the current file set element to a file without a suffix is created. When there is already a file with this name and the number of links to this file is one, it is renamed appending a dot, the letter ``C'', and the PID of the ntpd server process. When the number of links is greater than one, the file is unlinked. This allows the current file to be accessed by a constant name.

Access control options

Access control support

The restriction facility was implemented in conformance with the access policies for the original NSFnet backbone time servers. While this facility may be otherwise useful for keeping unwanted or broken remote time servers from affecting your own, it should not be considered an alternative to the standard NTP authentication facility. Source address based restrictions are easily circumvented by a determined cracker.

Access control commands

restrict numeric_address [mask numeric_mask] [flag] [...]

The numeric_address argument, expressed in dotted-quad form, is the address of a host or network. The numeric_mask argument, also expressed in dotted-quad form, defaults to 255.255.255.255, meaning that the numeric_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 given the sort algorithm, is always the first entry in the list. Note that, while numeric_address is normally given in dotted-quad format, the keyword default, with no mask option, may be used to indicate the default entry.

In the current implementation, flag always restricts access: that is, an entry with no flags indicates that free access to the server is to be given. The flags are not orthogonal, in that more restrictive flags will often make less restrictive ones redundant. The flags can generally be classed into two categories, those which restrict time service and those which restrict informational queries and attempts to do run-time reconfiguration of the server.

One or more of the following flags may be specified:

ignore

Ignore all packets from hosts which match this entry. If this flag is specified neither queries nor time server polls will be responded to.

noquery

Ignore all NTP mode 6 and 7 packets (that is, information queries and configuration requests) from the source. Time service is not affected.

nomodify

Ignore all NTP mode 6 and 7 packets which attempt to modify the state of the server (that is, run time reconfiguration). Queries which return information are permitted.

notrap

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 which is intended for use by remote event logging programs.

lowpriotrap

Declare traps set by matching hosts to be low priority. The number of traps a server can maintain is limited (the current limit is 3). Traps are usually assigned on a first come, first served basis, with later trap requestors being denied service. This flag modifies the assignment algorithm by allowing low priority traps to be overridden by later requests for normal priority traps.

noserve

Ignore NTP packets whose mode is not 6 or 7. In effect, time service is denied, though queries may still be permitted.

nopeer

Provide stateless time service to polling hosts, but do not allocate peer memory resources to these hosts even if they otherwise might be considered useful as future synchronization partners.

notrust

Treat these hosts normally in other respects, but never use them as synchronization sources.

limited

These hosts are subject to limitation of number of clients from the same net. A net in this context refers to the IP notion of net (class A, class B, class C and so on). Only the first client_limit hosts that have shown up at the server and that have been active during the last client_limit_period seconds are accepted. Requests from other clients from the same net are rejected. Only time request packets are taken into account. Query packets sent by the ntpq and ntpdc programs are not subject to these limits. A history of clients is kept using the monitoring capability of ntpd. Thus, monitoring is always active as long as there is a restriction entry with the limited flag.

ntpport

This is a match algorithm modifier, rather than a restriction flag. Its presence causes the restriction entry to be matched only if the source port in the packet is the standard NTP UDP port (123). Both ntpport and non-ntpport may be specified. The ntpport is considered more specific and is sorted later in the list.

Default restriction list entries, with the flags ignore, ntpport, for each of the local host's interface addresses are inserted 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; no flags are associated with the default entry (that is, everything besides your own NTP server is unrestricted).

clientlimit limit

Set the client_limit variable, which limits the number of simultaneous access-controlled clients. The default value for this variable is 3.

clientperiod period

Set the client_limit_period variable, which specifies the number of seconds after which a client is considered inactive and thus is no longer counted for client limit restriction. The default value for this variable is 3600 seconds.

Reference clock options

Reference clock support

A reference clock will generally (though not always) be a radio timecode receiver which is synchronized to a source of standard time such as the services offered by the NRC in Canada and NIST and USNO in the U.S. The interface between the computer and the timecode receiver is device dependent and will vary, but is often a serial port. A device driver specific to each clock must be selected and compiled in the distribution; however, most common radio, satellite and modem clocks are included by default. Note that an attempt to configure a reference clock when the driver has not been included or the hardware port has not been appropriately configured results in a scalding remark to the system log file, but is otherwise non-hazardous.

For the purposes of configuration, ntpd treats reference clocks in a manner analogous to normal NTP peers as much as possible. Reference clocks are identified by a syntactically correct but invalid IP address, in order to distinguish them from normal NTP peers. Reference clock addresses are of the form:

127.127.t.u

where t is an integer denoting the clock type and u indicates the type-specific unit number. The server command is used to configure a reference clock, where the address argument in that command is the clock address. The key, version and ttl options are not used for reference clock support. The prefer option can be useful to persuade the server to favour a particular reference clock over other reference clocks or peers.

The stratum of a reference clock is zero by default. Since the ntpd daemon adds one to the stratum of each peer, a primary server ordinarily displays stratum one. In order to provide engineered backups, it is often useful to specify the reference clock stratum as greater than zero. The stratum option is used for this purpose. Also, in cases involving both a reference clock and a pulse-per-second (PPS) discipline signal, it is useful to specify the reference clock identifier as other than the default, depending on the driver. The refid option is used for this purpose. Except where noted, these options apply to all clock drivers.

Reference clock commands

The options are interpreted as follows:

prefer

Marks the reference clock as preferred. All other things being equal, this host will be chosen for synchronization among a set of correctly operating hosts.

mode int

Specifies a mode number which is interpreted in a device-specific fashion. For instance, it selects a dialing protocol in the ACTS driver and a device subtype in the <code>parse</code> drivers.

minpoll int

Specifies the minimum polling interval for NTP messages, in seconds to the power of two. The allowable range is 4 (16 s to 14 (16384 s) inclusive. The default is 6 (64 s) for all except modem reference clocks, where the default is 10 (1024 s).

maxpoll int

Specifies the maximum polling interval for NTP messages, in seconds to the power of two. The allowable range is 4 (16 s to 14 (16384 s) inclusive. The default is 6 (64 s) for all except modem reference clocks, where the default is 14 (16384 s).

The fudge command can aslo be used to configure reference clocks in special ways. It must immediately follow the server command which configures the driver. Note that the same capability is possible at run time using the ntpdc program:

fudge 127.127.t.u [time1 secs] [time2 secs] [stratum int]

[refid string] [mode int] [flag1 0 | 1 ] [flag2 0 | 1]

The options are interpreted as follows:

time1 secs

Specifies a constant to be added to the time offset produced by the driver, a fixed-point decimal number in seconds. This is used as a calibration constant to adjust the nominal time offset of a particular clock to agree with an external standard, such as a precision PPS signal. It also provides a way to correct a systematic error or bias due to serial port latencies, different cable lengths or receiver internal delay. The specified offset is in addition to the propagation delay provided by other means, such as internal DIP switches.

time2 secs

Specifies a fixed-point decimal number in seconds, which is interpreted in a driver-dependent way.

stratum int

Specifies the stratum number assigned to the driver, an integer between 0 and 15. This number overrides the default stratum number ordinarily assigned by the driver itself, usually zero.

refid string

Specifies an ASCII string of from one to four characters which defines the reference identifier used by the driver. This string overrides the default identifier ordinarily assigned by the driver itself.

mode int

Specifies a mode number which is interpreted in a device-specific fashion. For instance, it selects a dialing protocol in the ACTS driver and a device subtype in the parse drivers.

flag1 flag2 flag3 flag4

These four flags are used for customizing the clock driver. The interpretation of these values, and whether they are used at all, is a function of the particular clock driver. However, by convention, and unless indicated otherwise, flag3 is used to attach the ppsclock STREAMS module to the configured driver, while flag4 is used to enable recording verbose monitoring data to the clockstats file configured with the filegen command. Further information on the filegen command can be found in ``Monitoring options''.

Miscellaneous options

Miscellaneous commands

broadcastdelay seconds

The broadcast and multicast modes require a special calibration to determine the network delay between the local and remote servers. Ordinarily, 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. This command specifies the default delay to be used under these circumstances. Typically (for Ethernet), a number between 0.003 and 0.007 seconds is appropriate. The default when this command is not used is 0.004 seconds.

trap host_address [port port_number] [interface interface_address]

This command configures a trap receiver at the given host address and port number for sending messages with the specified local interface address. If the port number is unspecified, a value of 18447 is used. If the interface address is not specified, the message is sent with a source address of the local interface the message is sent through. Note that on a multihomed host the interface used may vary from time to time with routing changes.

The trap receiver will generally log 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 will ensure that no messages are lost when the server is started.

setvar variable [default]

This command adds an additional system variable. These variables can be used to distribute additional information such as the access policy. If the variable of the form name = value is followed by the default keyword, the variable will be listed as part of the default system variables (using ntpq rv). These additional variables serve informational purposes only. They are not related to the protocol other that they can be listed. The known protocol variables will always override any variables defined via the setvar mechanism.

There are three special variables that contain the names of all variable 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.

logfile logfile

This command specifies the location of an alternate log file to be used instead of the default system syslog(SLIB) facility.

logconfig configkeyword

This command controls the amount and type of output written to the system syslog facility or the alternate logfile log file. By default, all output is turned on. All configkeyword keywords can be prefixed with:

=

sets the syslogmask

+

adds messages

-

removes messages

syslog messages can be controlled in four classes (clock, peer, sys and sync). Within these classes four types of message can be controlled.

Informational messages (info) control configuration information. Event messages (events) control logging of events (reachability, synchronization, alarm conditions). Statistical output is controlled with the statistics keyword. The final message group is the status messages. This describes mainly the synchronization status. Configuration keywords are formed by concatenating the message class with the event class. The all prefix can be used instead of a message class. A message class may also be followed by the all keyword to enable/disable all messages of the respective message class.

Thus, a minimal log configuration could look like this:

logconfig = syncstatus +sysevents

This would just list the synchronization state of ntpd and the major system events. For a simple reference server, the following minimum message configuration could be useful:

logconfig = syncall +clockall

This configuration will list all clock information and synchronization information. All other events and messages about peers, system events and so on are suppressed.

Variables

00

the daemon passes the leap bits of its synchronization source (usual mode of operation)

01
10

a leap second is added (operator-forced leap second)/deleted

11

leap information from the synchronization source is ignored (thus LEAP_NOWARNING is passed on)

Files

/etc/ntp.conf

the default name of the configuration file

/etc/ntp.drift

the default name of the drift file

/etc/ntp.keys

the default name of the key file

See also

``Configuring the Network Time Protocol (NTP)'' in the Networking Guide

RFC 1059, RFC 1119, RFC 1305