''' $Header ''' .de Sh .br .ne 5 .PP \fB\\$1\fR .PP .. .de Sp .if t .sp .5v .if n .sp .. .de Ip .br .ie \\n.$>=3 .ne \\$3 .el .ne 3 .IP "\\$1" \\$2 .. ''' ''' Set up \*(-- to give an unbreakable dash; ''' string Tr holds user defined translation string. ''' Greek uppercase omega is used as a dummy character. ''' .tr \(*W-|\(bv\*(Tr .ie n \{\ .ds -- \(*W- .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch .ds L" "" .ds R" "" .ds L' ' .ds R' ' 'br\} .el\{\ .ds -- \(em\| .tr \*(Tr .ds L" `` .ds R" '' .ds L' ` .ds R' ' 'br\} .TH XNTPD 8 LOCAL .SH NAME xntpd - Network Time Protocol daemon .SH SYNOPSIS .B xntpd [ .B -abdm ] [ .B -c .I conffile ] [ .B -e .I authdelay ] [ .B -f .I driftfile ] [ .B -k .I keyfile ] [ .B -p .I pidfile ] [ .B -r .I broadcastdelay ] [ .B -s .I statsdir ] [ .B -t .I trustedkey ] [ .B -v .I variable ] [ .B -V .I variable ] .SH DESCRIPTION .I xntpd is a daemon which sets and maintains a Unix system time\-of\-day in agreement with Internet standard time servers. .I xntpd is a complete implementation of the Network Time Protocol (NTP) version 3 standard, as defined by RFC 1305, but also retains compatability with version 1 and 2 servers as defined by RFC 1059 and RFC 1119, respectively. .I xntpd does all computations in fixed point arithmetic and requires no floating point code. The computations done in the protocol and clock adjustment code are carried out with high precision and with attention to the details which might introduce systematic bias into the computations, to try to maintain an accuracy suitable for synchronizing with even the most precise external time source. .PP Ordinarily, .I xntpd reads its configuration from a configuration file at startup time. The default configuration file name is .IR /etc/ntp.conf, although this may be overridden from the command line. It is also possible to specify a working, although limited, .I xntpd configuration entirely on the command line, obviating the need for a configuration file. This may be particularly appropriate when .I xntpd is to be configured as a broadcast or multicast client, with all peers being determined by listening to broadcasts at run time. Various internal .I xntpd variables can be displayed and configuration options altered while the daemon is running through use of the .IR ntpq (8) and .IR xntpdc (8) programs. .PP The daemon can operate in any of several modes, including symmetric active/passive, client/server and broadcast/multicast. A broadcast/multicast client can automatically discover remote servers, compute one-way delay correction factors and comfigure itself automatically. This makes it possible to deploy a fleet of workstations without specifying a configuration file or configuration details specific to its environment. .PP The following command line arguments are understood by .I xntpd (see the configuration file description for a more complete functional description): .Ip -a 8 run in \*(L"authenticate\*(R" mode .Ip -b 8 listen for broadcast NTP and sync to this if available .Ip -c 8 specify an alternate configuration file .Ip -d 8 specify debugging mode. This flag may occur multiple times, with each occurance indicating greater detail of display. .Ip -e 8 specify the time (in seconds) it takes to compute the NTP encryption field on this computer .Ip -f driftfile 8 specify the location of the drift file .Ip -k 8 specify the location of the file which contains the NTP authentication keys .Ip -m 8 listen for multicast messages and synchronize to them if available (requires multicast kernel) .Ip -p 8 specify the name of the file to record the daemon's process id .Ip -r 8 ordinarily, the daemon automatically compensates for the network delay between the broadcast/multicast server and the client; if the calibration procedure fails, use the specified the default delay (in seconds) .Ip -s 8 specify the directory to be used for creating statistics files .Ip -t trustedkey 8 add a key number to the trusted key list .Ip -v 8 add a system variable .Ip -V 8 add a system variable listed by default .SH "CONFIGURATION OPTIONS" .I xntpd 's configuration file format is similar to other Unix configuration files. Comments begin with a \*(L"#\*(R" character and extend to the end of the line. Blank lines are ignored. Configuration commands consist of an initial keyword followed by a list of arguments, some of which may be optional, separated by whitespace. These commands may not be continued over multiple lines. Arguments may be host names, host addresses written in numeric, dotted\-quad form, integers, floating point numbers (when specifying times in seconds) and text strings. Optional arguments are delimited by \*(L"[]\*(R" in the following descriptions, while alternatives are separated by \*(L"|\*(R". .PP .B peer .I host_address [ .B key .I # ] [ .B version .I # ] [ .B prefer ] .br .B server .I host_address [ .B key .I # ] [ .B version .I # ] [ .B prefer ] .br .B broadcast .I host_address [ .B key .I # ] [ .B version .I # ] [ .B ttl .I # ] .PP These three commands specify various time servers to be used and/or time services to be provided. The .B peer command specifies that the local server is to operate in \*(L"symmetric active\*(R" mode with the remote server .I host_address named in the command. 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 host may be the better source of time. The .B server command specifies that the local server is to operate in \*(L"client\*(R" mode with the remote server named in the command. 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 .B broadcast command specifies that the local server is to operate in \*(L"broadcast\*(R" mode where the local server sends periodic broadcast messages to a client population at the broadcast/multicast address named in the command. Ordinarily, this specification applies only to the local server operating as a transmitter; for operation as a broadcast client, see the .B broadcastclient or .B multicastclient commands elsewhere in this document. In this mode the .I host_address is usually the broadcast address on [one of] the local network[s] or a multicast address assigned to NTP. The Numbers Czar has assigned the address 224.0.1.1 to NTP; this is presently the only number that should be used. Note that the use of multicast features requires a multicast kernel, which is not yet ubiquitous in vendor products. .PP The .B key option, when included, indicates that all packets sent to the address are to include authentication fields encrypted using the specified key number (the range of which is that of an unsigned 32 bit integer). The default is to not include an encryption field. The .B version option allows one to specify the version number to be used for outgoing NTP packets. Versions 1, 2, and 3 are the choices, version 3 is the default. The .B prefer option marks the host as a preferred host. All other things being equal, this host will be chosen for synchronization among a set of correctly operating hosts. The .B ttl option is used only with the broadcast mode. It specifies the time-to- live (TTL) to use on multicast packets. Selection of the proper value, which defaults to 127, is something of a black art and must be coordinated with the network admistrator(s). .PP .B broadcastclient .PP This directs the local server to listen for broadcast messages on the local network, in order to discover other servers on the same subnet. 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 \*(L"broadcastclient\*(R" 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 must operate using authentication and the same trusted key and key identifier. .PP .B multicastclient [ .I IP address ... ] .PP This command is used in the same way as the .IR broadcastclient command, but operates using IP multicasting. Support for this function requires a multicast kernel and the use of authentication. If one or more IP addresses are given, the server joins the respective multicast group(s). If none are given, the IP address assigned to NTP (224.0.1.1) is assumed. .PP .B driftfile .I filename .PP 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 offset computed by the daemon. If the file does not exist or this command is not given, the initial frequency offset is assumed 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 that the file is updated by first writing the current drift value into a temporary file and then using .IR rename (3) to replace the old version. This implies that .I 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. .PP .B enable auth|bclient|pll|monitor|stats [ .I ... ] .PP Provides a way to enable various server options. Flags not mentioned are unaffected. The \*(L"auth\*(R" flag 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 flag is disable (off). The \*(L"bclient\*(R" flag 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 flag is disable (off). The \*(L"pll\*(R" flag 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 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. The \*(L"monitor\*(R" flag enables the monitoring facility (see elsewhere), with default enable (on). The \*(L"stats\*(R" flag enables statistics facility filegen (see description elsewhere.), with default enable (on). .PP .B disable auth|bclient|pll|monitor|stats [ .I ... ] .PP Provides a way to disable various server options. Flags not mentioned are unaffected. The flags presently available are described under the enable command. .SH "AUTHENTICATION OPTIONS" .PP .B keys .I filename .PP This command specifies the name of a file which contains the encryption keys and key identifiers used by .I xntpd when operating in authenticated mode. The format of this file is described later in this document. .PP .B trustedkey .I # [ .I "# ..." ] .PP This command is used to specify the encryption key identifiers which are trusted for the purposes of authenticating peers suitable for sychonization. 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 arguments are 32 bit unsigned integers. Note, however, that NTP key 0 is fixed and globally known. If meaningful authentication is to be performed the 0 key should not be trusted. .PP .B requestkey .I # .PP This command specifies the key identifier to use with the .IR xntpdc (8) program, which is useful to diagnose and repair problems that affect .IR xntpd (8) operation. The operation of the .I xntpdc program are specific to this particular implementation of xntpd 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 bot the remote program and local server share a common key and key identifier. The argument to this command is a 32 bit unsigned integer. If no .B requestkey command is included in the configuration file, or if the keys don't match, such requests will be ignored. .PP .B controlkey .I # .PP This command specifies the key identifier to use with the .IR ntpq (8) program, which is useful to diagnose and repair problems that affect .IR xntpd (8) operation. The operation of the .IR ntpq program and .I xntpd conform to those specified in RFC 1305. Requests from a remote .I ntpq program which affect the state of the local server must be authenticated, which requires bot the remote program and local server share a common key and key identifier. The argument to this command is a 32 bit unsigned integer. If no .B requestkey command is included in the configuration file, or if the keys don't match, such requests will be ignored. .PP .B authdelay .I seconds .PP Indicates 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 0.0001 seconds to 0.003 seconds, though it is very dependent on the CPU speed of the host computer. The value is usually computed using the .I authspeed program included with the distribution. .SH "ACCESS CONTROL OPTIONS" .B restrict .I address [ .B mask .I numeric_mask ] [ .I flag ] [ .I ... ] .PP .I 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 and'ed with the mask associated with the restriction entry and then compared with the entry's address (which has also been and'ed with the mask) to look for a match. The \*(L"mask\*(R" argument defaults to 255.255.255.255, meaning that the \*(L"address\*(R" 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 \*(L"address\*(R" is normally given in dotted\-quad format, the text string \*(L"default\*(R", with no mask option, may be used to indicate the default entry. .PP In the current implementation, flags always restrict access, i.e. 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 catagories, 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: .Ip ignore 10 Ignore all packets from hosts which match this entry. If this flag is specified neither queries nor time server polls will be responded to. .Ip noquery 10 Ignore all NTP mode 6 and 7 packets (i.e. information queries and configuration requests) from the source. Time service is not affected. .Ip nomodify 10 Ignore all NTP mode 6 and 7 packets which attempt to modify the state of the server (i.e. run time reconfiguration). Queries which return information are permitted. .Ip notrap 10 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. .Ip lowpriotrap 10 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. .Ip noserve 10 Ignore NTP packets whose mode is other than 6 or 7. In effect, time service is denied, though queries may still be permitted. .Ip nopeer 10 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. .Ip notrust 10 Treat these hosts normally in other respects, but never use them as synchronization sources. .Ip limited 10 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, etc.). Only the first \*(L"client_limit\*(R" hosts that have shown up at the server and that have been active during the last \*(L"client_limit_period\*(R" seconds are accepted. Requests from other clients from the same net are rejected. Only time request packets are taken into account. \*(L"Private\*(R", \*(L"control\*(R", and \*(L"broadcast\*(R" packets are not subject to client limitation and therefore are not contributing to client count. History of clients is kept using the monitoring capability of .I xntpd . Thus, monitoring is active as long as there is a restriction entry with the \*(L"limited\*(R" flag. The default value for \*(L"client_limit\*(R" is 3. The default value for \*(L"client_limit_period\*(R" is 3600 seconds. .Ip ntpport 10 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 \*(L"ntpport\*(R" and non\-\*(L"ntpport\*(R" may be specified. The \*(L"ntpport\*(R" is considered more specific and is sorted later in the list. .PP Default restriction list entries, with the flags \*(L"ignore, ntpport\*(R", 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 (i.e. everything besides your own NTP server is unrestricted). .PP The restriction facility was added to allow the current access policies of the time servers running on the NSFnet backbone to be implemented with .I xntpd as well. 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. .PP .B clientlimit .I limit .PP Sets \*(L"client_limit\*(R" to \*(L"limit\*(R", allows configuration of client limitation policy. This variable defines the number of clients from the same network that are allowed to use the server. .PP .B clientperiod .I period .PP Sets \*(L"client_limit_period\*(R", allows configuration of client limitation policy. This variable specifies the number of seconds after which a client is considered inactive and thus no longer is counted for client limit restriction. .SH "MONITORING OPTIONS" .PP .B statsdir .I /directory path/ .PP 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 used for handling statistics logs (see .B filegen statement below). .PP .B statistics .IR name \.\.\. .PP Enables writing of statistics records. Currently, three kinds of statistics are supported. .Ip loopstats 10 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 \*(L"loopstats\*(R": .PP .RS 5 48773 10847.650 0.0001307 17.3478 2 .RE .RS 10 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. .RE .Ip peerstats 10 enables recording of peer statistics information. This includes statistics records of all peers of a NTP server and of the 1-pps signal, where present and configured. Each valid update appends a line of the following form to the current element of a file generation set named \*(L"peerstats\*(R": .PP .RS 5 48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142 .RE .RS 10 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. .RE .Ip clockstats 10 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 \*(L"clockstats\*(R": .PP .RS 5 49213 525.624 127.127.4.1 93 226 00:08:29.606 D .RE .RS 10 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. .RE .PP Statistic files are managed using file generation sets (see .B filegen below). The information obtained by enabling statistics recording allows analysis of temporal properties of a .I xntpd server. It is usually only useful to primary servers or maybe main campus servers. .PP .B filegen .I name [ .B file .I filename ] [ .B type .I typename ] [ .B flag .I flagval ] [ .BR link \| nolink ] [ .BR enable \| disable ] .PP Configures setting of generation file set .IR name . Generation file sets provide a means for handling files that are continously 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 .I 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 risc of desturbing the operation of .I xntpd . (Most important: they can be removed to free space for new data produced.) Filenames of set members are built from three elements. .Ip prefix 10 This is a constant filename path. It is not subject to modifications via the .B filegen statement. 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" filegens can be configured using the .B statsdir statement explained above. .Ip filename 10 This string is directly concatenated to the .I prefix mentioned above (no intervening \*(L'/\*(R' (slash)). This can be modified using the \*(L"file\*(R" argument to the \*(L"filegen\*(R" statement. No \*(L"..\*(R" elements are allowed in this component to prevent filenames referring to parts outside the filesystem hierarchy denoted by \*(L"prefix\*(R". .Ip suffix 10 This part is reflects individual elements of a file set. It is generated according to the .I type of a file set as explained below. .PP A file generation set is characterized by its type. The following types are supported: .Ip none 10 The file set is actually a single plain file. .Ip pid 10 One element of file set is used per incarnation of a .I xntpd server. This type does not perform any changes to file set members during runtime, however it provides an easy way of seperating files belonging to different .I xntpd server incarnations. The set member filename is built by appending a dot (\*(L'.\*(R') to concatentated \*(L"prefix\*(R" and \*(L"filename\*(R" strings, and appending the decimal representation of the process id of the .I xntpd server process. .Ip day 10 One file generation set element is created per day. The term .I day is based on .IR UTC . A day is defined as the period between 00:00 and 24:00 UTC. The file set member suffix consists of a dot \*(L".\*(R" and a day specification in the form .RI < YYYYMMDD >. .I YYYY is a 4 digit year number (e.g. 1992). .I MM is a two digit month number. .I DD is a two digit day number. Thus, all information written at December 10th, 1992 would end up in a file named \*(L".19921210\*(R". .Ip week 10 Any file set member contains data related to a certain week of a year. The term .I week is definied by computing \*(L"day of year\*(R" 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 \*(L"W\*(R", and a two digit week number. For example, information from Jamuary, 10th 1992 would end up in a file with suffix \*(L".1992W1\*(R". .Ip month 10 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. .Ip year 10 One generation file elment is generated per year. The filename suffix consists of a dot and a 4 digit year number. .Ip age 10 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 \*(L"a\*(R", 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. .PP Information is only written to a file generation set when this set is \*(L"enabled\*(R". Output is prevented by specifying \*(L"disabled\*(R". .PP It is convenient to be able to access the .I current element of a file generation set by a fixed name. This feature is enabled by specifying \*(L"link\*(R" and disabled using \*(L"nolink\*(R". If \*(L"link\*(R" is specified, a hard link from the current file set element to a file without 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 \*(L"C\*(R", and the pid of the .I 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. .SH "MISCELLANEOUS OPTIONS" .PP .B precision .I # .PP This command specifies the nominal precision of the local clock. The value is an integer approximately equal to the base 2 logarithm of the local timekeeping precision in seconds. Normally, the daemon determines the precision automatically at startup, so this command is necessary only in special cases when the precision cannot be determined automatically. .PP .B broadcastdelay .I seconds .PP 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. .PP .B trap .I host_address [ .B port .I port_number ] [ .B interface .I interface_addess ] .PP 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 which is that 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. .PP 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. .PP .B setvar .I variable .I [default] .PP 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 from = is followed by the .I default keyword the variable will be listed as part of the default system variables ( .I ntpq rv command). 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 overide any variables defined via the .I setvar mechanism. .PP There are three special variables that contain the names of all variable of the same group. The .I sys_var_list holds the names of all system variables. The .I peer_var_list holds the names of all peer variables and the .I clock_var_list hold the names of the reference clock variables. .PP .B monitor yes|no .B authenticate yes|no .PP These commands have been superseded by the .B enable and .B disable commands. They are listed here for historical purposes. .SH "AUTHENTICATION KEY FILE FORMAT" .PP The NTP standard specifies an extension allowing verification of the authenticity of received NTP packets, and to provide an indication of authenticity in outgoing packets. This is implemented in .I xntpd using the DES or MD5 algorithms to compute a digital signature, or message-digest. The specification allows any one of possibly 4 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 data, though they must each learn the key and key identifer independently. In the case of DES, the keys are 56 bits long with, depending on type, a parity check on each byte. In the case of MD5, the keys are 64 bits (8 bytes). .I xntpd reads its keys from a file specified using the .B -k command line option or the .B keys statement in the configuration file. While key number 0 is fixed by the NTP standard (as 56 zero bits) and may not be changed, one or more of the keys numbered 1 through 15 may be arbitrarily set in the keys file. .PP The key file uses the same comment conventions as the configuration file. Key entries use a fixed format of the form .Ip "" 5 .I "keyno type key" .PP where \*(L"keyno\*(R" is a positive integer, \*(L"type\*(R" is a single character which defines the format the key is given in, and \*(L"key\*(R" is the key itself. .PP The key may be given in one of three different formats, controlled by the \*(L"type\*(R" character. The three key types, and corresponding formats, are listed following. .Ip "S" 5 The \*(L"key\*(R" is a 64 bit hexadecimal number in the format specified in the DES document, that is the high order 7 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 (i.e. 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 .I 0101010101010101 . .Ip "N" 5 The \*(L"key\*(R" 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 .I 8080808080808080 .Ip "A" 5 The \*(L"key\*(R" is a 1\-to\-8 character ASCII string. A key is formed from this by using the lower order 7 bits of the ASCII representation of each character in the string, with zeroes being 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. .Ip "M" 5 The \*(L"key\*(R" 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. .PP One of the keys may be chosen, by way of the configuration file .B requestkey statement, to authenticate run time configuration requests made using the .IR xntpdc (8) program. The latter program obtains the key from the terminal as a password, so it is generally appropriate to specify the key chosen to be used for this purpose in ASCII format. .SH PRIMARY CLOCK SUPPORT .I xntpd can be optionally compiled to include support for a number of types of reference clocks. 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 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. .PP Support for the various reference clock drivers is conditionally compiled using the compiler define codes described elsewhere. An attempt to configure a reference clock when specific support is not available or the hardware port has not been appropriately configured results in a scolding remark to the system log file, but is otherwise non hazardous. .PP For the purposes of configuration, .I xntpd treats reference clocks in a manner analogous to normal NTP peers as much as possible. Reference clocks are referred to by address, much as a normal peer is, though an invalid IP address is used to distinguish them from normal peers. Reference clock addresses are of the form .I 127.127.t.u where .I t is an integer denoting the clock type and .I u indicates the type\-specific unit number. Reference clocks are configured using a .B server statement in the configuration file where the .I host_address is the clock address. The .I key, .I version and .I ttl options are not used for reference clock support; however, the .I prefer option can be useful to persuade the server to cherish a reference clock with somewhat more enthusiasm than other reference clocks or peers, if this is advisable. Clock addresses may generally be used anywhere in the configuration file a normal IP address can be used, for example, in .B restrict statements, although such use would normally be considered strange. .PP Reference clock support provides the .B fudge command, which can be used to configure reference clocks in special ways. Following is the generic format that applies to this command .PP .B fudge .I 127.127.t.u [ .B time1 .I secs ] [ .B time2 .I secs ] [ .B stratum .I int ] [ .B refid .I int ] [ .B flag1 .I 0|1 ] [ .B flag2 .I 0|1 ] [ .B flag3 .I 0|1 ] [ .B flag4 .I 0|1 ] .PP The .I time1 and .B time2 options are specified in fixed point seconds and used in some clock drivers as calibration constants. By convention, and unless indicated otherwise, .B time1 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. The specified offset is in addition to the propagation delay provided by other means, such as internal DIPswitches. The .B stratum option is a number in the range zero to 15 and is used to assign a nonstandard operating stratum to the clock. The .B refid option is an ASCII string in the range one to four characters and is used to assign a nonstandard reference identifier to the clock. Finally, the four binary flags .B flag1, .B flag2, .B flag3 and .B flag4 are used for customizing the clock driver. The interpretation of these values, and whether they are used at all, is a function of the needs of the particular clock driver. However, by convention, and unless indicated otherwise, .B flag3 is used to attach the ppsclock streams module to the configured driver, while .B flag4 is used to enable recording verbose monitoring data to the clockstats file configured with the .I filegen command. Further information on the ppsclock streams module is in the README file in the ./kernel directory in the current xntp3 program distribution. Further information on this feature is available in the ./scripts/stats directory in the same distribution. .PP Ordinarily, the stratum of a reference clock is by default zero. Since the .I xntpd 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 .B stratum option is used for this purpose. Also, in cases involving both a reference clock and a 1-pps discipline signal, it is useful to specify the reference clock identifier as other than the default, depending on the driver. The .I refid option is used for this purpose. Except where noted, these options apply to all clock drivers. .PP .I xntpd on Unix machines currently supports several different types of clock hardware plus a special pseudo\-clock used for backup or when no other clock source is available. In the case of most of the clock drivers, support for a 1-pps precision timing signal is available as described in the README file in the ./doc directory of the xntp3 progam distribution. The clock drivers, and the addresses used to configure them, are described in the README.refclocks in the doc directory of the current program distribution. .PP .SH VARIABLES Most variables used by the NTP protocol can be examined with the .I xntpdc (mode 7 messages) and the .I ntpq (mode 6 messages). Currently very few variables can be modified via mode 6 messages. These variables are either created with the .I setvar directive or the leap warning variables. The leap warning bits that can be set in the .B leapwarning variable (up to one month ahead). Both, the .B leapwarning and in the .B leapindication variable, have a slightly different encoding than the usual .B leap bits interpretation: .P .Ip 00 8 The daemon passes the leap bits of its synchronisation source (usual mode of operation). .Ip 01/10 8 A leap second is added/deleted (operator forced leap second). .Ip 11 8 Leap information from the sychronisation source is ignored (thus LEAP_NOWARNING is passed on). .PP .SH FILES .Ip /etc/ntp.conf 20 the default name of the configuration file .Ip /etc/ntp.drift 20 the conventional name of the drift file .Ip /etc/ntp.keys 20 the conventional name of the key file .SH SEE ALSO .PP .IR xntpdc (8), .IR ntpq (8), .IR ntpdate (8) .SH HISTORY .PP Written by Dennis Ferguson at the University of Toronto. Text amended by David Mills at the University of Delaware. .SH BUGS .PP .I xntpd has gotten rather fat. While not huge, it has gotten larger than might be desireable for an elevated\-priority daemon running on a workstation, particularly since many of the fancy features which consume the space were designed more with a busy primary server, rather than a high stratum workstation, in mind.