6.5 XNTPD

XNTPD is an operating system daemon that sets and maintains the system time of day in synchronization with Internet standard time servers.

The daemon can operate in any of several modes, including client-server and broadcast/multicast mode, as described in RFC-1305. A broadcast/multicast client can discover remote servers, compute client-server propagation delay correction factors, and configure itself automatically. This makes it possible to deploy numerous workstations without specifying configuration details specific to the local environment.

Ordinarily, XNTPD reads the ntp.conf configuration file at startup 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 might 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 XNTPD variables can be displayed and configuration options altered while the daemon is running using the NTPQ and XNTPDC utility programs.

Usage:

XNTPD [ -aAbdhm ] [ -c configfile ] [ -f driftfile ] [ -k keyfile ] [ -l logfile ] [-n log file limit] [ -p pidfile ] [ -r broadcastdelay ] [ -s statsdir ] [ -t trustkey ] [ -v variable ] [ -V defaultvariable ] [-T noncp/slp ] [-S]

Table 6-7 XNTPD Parameters

Parameter

Description

-a

Enables authentication mode. The default is enabled, so this option is obsolete now.

-A

Disables authentication mode.

-b

Synchronizes by using NTP broadcast messages.

-c configfile

Specifies the name and path of the configuration file.

NOTE:Novell® Remote Manager does not understand this user-defined configuration file, so it opens the default sys:\etc\ntp.conf file.

-d

Specifies the debugging mode. This flag might occur multiple times, with each occurrence indicating greater detail of display.

-f driftfile

Specifies the name and path of the drift file.

-h

Displays the help.

-k keyfield

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

-l logfile

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

NOTE:If the -S option (see -S for more information) is enabled along with -l option, the NTPDate events are also logged into the log file (ntpdate.log).

-n

Indicates the log file limit.

-m

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

-p pidfile

Specifies the name and path to record the daemon’s process ID.

-r broadcastdelay

Specifies 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

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

-t key

Adds a key number to the trusted key list.

-v variable

Adds a system variable.

-V defaultvariable

Adds a system variable listed by default.

-T noncp

Provides Timesync migration or backward compatibility options.

Prevents running of the NCP™ engine on XNTPD, which services all NCP time requests from NetWare® 4, Novell clients, and dsrepair.

-T slp

Enables NTP to automatically discover SLP advertising a Timesync SINGLE server on the network and add the Timesync SINGLE server’s IP address in the ntp.conf configuration file as a time provider.

WARNING:Do not use this option in the sys:\system\timeserv.ncf file.

-S

XNTPD steps the clock to the time of the best available server by calling NTPDate with the server list from the NTP configuration file (ntp.conf). This sets the clock status to "nearly in sync", meaning that time is synchronized in as close as 0.5 seconds. This basically helps XNTPD to synchronize† quickly.

6.5.1 The Configuration File

The XNTPD configuration file (ntp.conf) is read at initial startup in order to specify the synchronization sources, modes and other related information. It is installed in the sys:\system directory, but could be installed elsewhere (see -c configfile).

The ntp.conf looks similar to the following:

# sys:\etc\ntp.conf

#

# This configuration file is used by xntpd.nlm. 

# xntpd.nlm is the NTPv3 Time Daemon used for 

# synchronization of servers.

#

# Note : Please make a copy of 

#    this file before modification 

#    for further reference.

#

# Local Clock used as Time Provider - Self Synchronized Mode

#

# server 127.127.1.0

# fudge 127.127.1.0 stratum 3

#

# Client-Server Mode

# <IP Address> : Time provider IP address

# 

# Time Provider

# server <IP Address>

#

# Time Provider

# server <IP Address>

#

# Peer-Peer Mode

# <IP Address> : Peer IP address

#

# peer <IP Address>

#

# To Configure this NetWare box to Broadcast the "time service" 

#

# broadcast <Subnet broadcast Address> key <key_id>

#               or

# broadcast 255.255.255.255 key <key_id>

#

# To Configure this NetWare box to Multicast the "time service" 

#

# broadcast 224.0.1.1 key <key_id>

#

# To Configure NTP Broadcast Client

#

# broadcastclient

#

# To Configure NTP Multicast Client

#

# multicastclient

#

# Authentication Options

#

# enable auth monitor

# keys sys:\etc\ntp.keys

# trustedkey 0

# requestkey 0

# controlkey 0

#

# Backward Compatibility with Timesync

#

# Switch off the Timesync NCP service

# noncp 

# Step the time to the source clock for slewing

# stepclock

#

# Monitoring/Logging Options

#

  driftfile sys:\system\drift.ntp

# statsdir sys:\system\

# logfile sys:\system\ntp.log

# filegen peerstats file peerstat type none enable

# filegen loopstats file loopstat type none enable

# filegen clockstats file clkstat type none enable

Configuration commands consist of an initial keyword followed by a list of arguments, some of which can be optional, separated by white space. Commands cannot be continued over multiple lines. Arguments can 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 descriptions, while alternatives are separated by |. The notation [ ... ] means an optional, indefinite repetition of the last item before the [ ... ].

See the following for configuration and control options. Although there is a rich set of options available, the only required option is one or more server, peer, or broadcast commands described in Configuration Options.

6.5.2 Files

sys:\etc\ntp.conf. The default name of the configuration file.

sys:\system\ntp.drift. The default name of the drift file.

sys:\etc\ntp.keys. The default name of the key file.

6.5.3 Configuration Options

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

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

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

These three commands specify the time server name or address to be used and the mode in which to operate. The address can be either a DNS name or a IP address in dotted-quad notation. The peer command specifies that the local server is to operate in symmetric active mode with the remote server. In this mode, the local server can be synchronized to the remote server and, in addition, the remote server can be synchronized by the local server. This is useful in a network of servers where, depending on various failure scenarios, either the local or remote server might be the better source of time.

The server command specifies that the local server is to operate in client mode with the specified remote server. 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 broadcast command specifies that the local server is to operate in broadcast mode, where the local server sends periodic broadcast messages to a client population at the broadcast/multicast address specified. 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. In this mode, address is usually the broadcast address on (one of) the local networks or a multicast address assigned to NTP. The IANA organization has assigned the address 224.0.1.1 to NTP; this is presently the only address that should be used.

NOTE:The use of multicast features requires a multicast kernel, which is not yet ubiquitous in vendor products.

For more information on the configuration options, see Table 6-8.

Table 6-8 XNTPD Configuration Options

Parameter

Description

key key

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

version version

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

prefer

Marks the server as preferred. All other things being equal, this host is 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. The default is 127.

minpoll minpoll

This option 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 reference clocks.

maxpoll maxpoll

This option 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 10 (1024 s) for all except reference clocks.

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 by 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. In order to avoid accidental or malicious disruption in this mode, both the local and remote servers should operate by 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 assigned by the IANA organization to NTP (224.0.1.1). This command operates in the same way as the broadcastclient command, but uses IP multicasting. Support for this command requires a multicast kernel.

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 might take several 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). That 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 XNTPD must have write permission for the directory the drift file is located in, 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:All these flags can be controlled remotely by using XNTPDC.

Table 6-9 XNTPD Parameters for Enabling and Disabling Server Options

Parameter

Description

auth

Enables the server to synchronize with unconfigured peers only if the peer has been correctly authenticated by 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 the multicastclient command does with the default address. The default for this flag is disable.

monitor

Enables the monitoring facility. See the XNTPDC program and the monlist command or 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 if 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. 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.

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 (don’t 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.

The XNTPD -S and -T noncp options can also be added in the configuration file as stepclock and noncp respectively.

Table 6-10 Stepclock and Noncp

Parameter

Description

stepclock

XNTPD steps the clock to the time of the best available server by calling NTPDate with the server list from the NTP configuration file (ntp.conf). This sets the clock status to "nearly in sync", meaning that time is synchronized as close as 0.5 seconds. This helps XNTPD to synchronize quickly.

noncp

Prevents running of the NCP engine on XNTPD, which services all NCP time requests from NetWare 4, Novell clients, and dsrepair.

6.5.4 Authentication Options

The NTP standard specifies an extension that provides cryptographic authentication of received NTP packets. This is implemented in XNTPD by using the DES or MD5 algorithms to compute a digital signature, or message digest. The specification allows any one of possibly four billion keys, numbered with 32-bit key identifiers, to be used to authenticate an association. The servers involved in an association must agree on the key and key identifier used to authenticate their messages.

Keys and related information are specified in a key file that should be exchanged and stored by 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 is used for the NTPQ utility program, and the third is used for the XNTPDC utility program.

Table 6-11 XNTPD Authentication Command Options

Parameter

Description

keys keyfile

Specifies the filename containing the encryption keys and key identifiers used by XNTPD, NTPQ and XNTPDC when operating in authenticated mode. For ntp.keys file format see ntp.keys.

trustedkey key [ ... ]

Specifies the encryption key identifiers that 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. NTP key 0 is fixed and globally known. If meaningful authentication is to be performed, the 0 key should not be trusted.

requestkey key

Specifies the key identifier to use with the XNTPDC program, which uses a proprietary protocol specific to this implementation of XNTPD. This program is useful to diagnose and repair problems that affect XNTPD 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 don’t match, such requests are ignored.

controlkey key

Specifies the key identifier to use with the NTPQ program, which uses the standard protocol defined in RFC-1305. This program is useful to diagnose and repair problems that affect the XNTPD 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 don’t match, such requests are ignored.

For DES, the keys are 56 bits long with, depending on type, a parity check on each byte. For MD5, the keys are 64 bits (8 bytes). XNTPD reads its keys from a file specified by using the -k command line option or the keys statement in the configuration file. Although the key number 0 is fixed by the NTP standard (as 56 zero bits) and cannot be changed, one or more of the keys numbered 1 through 15 can be arbitrarily set in the keys file.

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 that defines the key format, and key is the key itself.

The key can be given in one of three different formats, controlled by the type character. The three key types, and corresponding formats, are listed in the following table:

Table 6-12 XNTPD Key File Parameters

Parameter

Description

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 so 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. 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. both the keys and the authentication schemes (DES or MD5) must be identical between a set of peers sharing the same key number.

The keys used by the NTPQ and XNTPDC programs are checked against passwords requested by the programs and entered by hand, so it is generally appropriate to specify these keys in ASCII format.

6.5.5 Monitoring Options

XNTPD includes a comprehensive monitoring facility suitable for continuous, long-term recording of server and client timekeeping performance. See the statistics commands below for a listing and example of each type of statistics currently supported. Statistics files are managed by using file generation sets and scripts in the ./scripts directory of this distribution. Using these facilities and UNIX cron jobs, the data can be automatically summarized and archived for retrospective analysis.

Table 6-13 XNTPD Monitoring Command Parameters

Parameter

Description

statistics name [ ... ]

Enables writing of statistics records. Three kinds of name statistics are supported. They are loopstats, peerstats, clockstats.

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 the status. The status field is encoded in hex format. 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, additional information can also be gathered and displayed. 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. 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 the 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, one element of the set is being written to. The type given specifies when and how data is directed to a new element of the set. This way, information stored in elements of a file set that are currently unused is available for administrative operations without the risk of disturbing the operation of XNTPD. (In addition, 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 can 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 / (slash)). This can be modified by 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 XNTPD 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 XNTPD server incarnations. The set member filename is built by appending a . (dot) to concatenated prefix and filename strings, and appending the decimal representation of the process ID of the XNTPD 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 . (dot) and a day specification in the form YYYYMMDD. YYYY is a 4-digit year number (e.g., 1992). MM is a two digit month number. 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 4-digit year number, the letter W, and a 2-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 filename suffix consists of a dot, a 4-digit year number, and a 2-digit month.

filegen name [ file filename ] [ type typename ] [ flag flagval ] [ link | nolink ] [ enable | disable ] (cont'd.)

  • year: One generation file element is generated per year. The filename suffix consists of a dot and a 4-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 8-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 by 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 of this file is one, it is renamed appending a dot, the letter C, and the pid of the XNTPD 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.

6.5.6 Access Control Options

XNTPD implements a general purpose address-and-mask-based restriction list. The list is sorted by address and by mask, and the list is searched in this order for matches, with the last match found defining the restriction flags associated with the incoming packets. The source address of incoming packets is used for the match, with the 32-bit address being added with the mask associated with the restriction entry and then compared with the entry’s address (which has also been added with the mask) to look for a match.

The restriction facility was implemented in conformance with the access policies for the original NSFnet backbone time servers. Although this facility might 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.

Table 6-14 XNTPD Access Control Parameters

Parameter

Description

ntpport

This is actually 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 can 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, although if it is otherwise unconfigured; no flags are associated with the default entry (i.e., 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.

6.5.7 Miscellaneous Options

Table 6-15 Miscellaneous XNTPD Parameters

Parameter

Description

broadcastdelay 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:On a multihomed host, the interface used can 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 is listed as part of the default system variables (NTPQ rv command). These additional variables serve informational purposes only. They are not related to the protocol other than being listed. The known protocol variables always override any variables defined via the setvar mechanism.

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.

logfile logfile

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

6.5.8 Variables

Most variables used by the NTP protocol can be examined with the XNTPDC (mode 7 messages) and the NTPQ (mode 6 messages). Currently, very few variables can be modified via mode 6 messages. These variables are either created with the setvar directive or the leap warning bits. The leap warning bits can be set in the leapwarning variable up to one month ahead. Both the leapwarning and leapindication variables have a slightly different encoding than the usual leap bits interpretation:

  • 00: The daemon passes the leap bits of its synchronization source (usual mode of operation).

  • 01/10: A leap second is added/deleted (operator forced leap second).

  • 11: Leap information from the synchronization source is ignored (so LEAP_NOWARNING is passed on).