diff options
Diffstat (limited to 'usr.sbin/xntpd/doc/xntpd.8')
| -rw-r--r-- | usr.sbin/xntpd/doc/xntpd.8 | 1622 |
1 files changed, 624 insertions, 998 deletions
diff --git a/usr.sbin/xntpd/doc/xntpd.8 b/usr.sbin/xntpd/doc/xntpd.8 index 84b785b..77f64f9 100644 --- a/usr.sbin/xntpd/doc/xntpd.8 +++ b/usr.sbin/xntpd/doc/xntpd.8 @@ -1,5 +1,5 @@ ''' $Header -''' +''' .de Sh .br .ne 5 @@ -46,9 +46,9 @@ xntpd - Network Time Protocol daemon .SH SYNOPSIS .B xntpd [ -.B -ab +.B -abdm ] [ -.B -c +.B -c .I conffile ] [ .B -e @@ -60,14 +60,11 @@ xntpd - Network Time Protocol daemon .B -k .I keyfile ] [ -.B -l -.I loopfile -] [ .B -p .I pidfile ] [ .B -r -.I broaddelay +.I broadcastdelay ] [ .B -s .I statsdir @@ -82,42 +79,52 @@ xntpd - Network Time Protocol daemon .I variable ] .SH DESCRIPTION -.I Xntpd -is a daemon which maintains a Unix system's time\-of\-day in agreement -with Internet standard time servers. -.I Xntpd +.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 and 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 is entirely free of -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 integrations, -to try to maintain an accuracy suitable for synchronizing with even the +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 file at startup time. The default configuration -file is -.I /etc/ntp.conf, -though this may be overridden from the command line. It is also possible to -specify a working, though limited, +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 xntpd is -to be configured as a broadcast client, with all peers being determined -by listening to broadcasts at run time. Various internal +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 +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 @@ -129,42 +136,46 @@ listen for broadcast NTP and sync to this if available .Ip -c 8 specify an alternate configuration file .Ip -d 8 -specify debugging options +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 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 +specify the location of the file which contains the NTP authentication +keys .Ip -m 8 -listen for multicast NTP and sync to this if available (requires multicast -kernel) +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 -specify the default round trip delay (in seconds) -to be used when synchronizing to broadcasts +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 a directory to be used for creating statistics files -.Ip -t 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 FILE OPTIONS" -.IR Xntpd 's -configuration file is relatively free format. Comments, which may be -freely inserted, begin with a \*(L"#\*(R" character -and extend to the end of the line. Blank lines are ignored. Configuration -statements include an initial keyword followed by white space separated -arguments, some of which may be optional. Configuration statements -may not be continued over multiple lines. Arguments may be network -numbers (which must be 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". +.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 @@ -199,163 +210,150 @@ descriptions, while alternatives are separated by \*(L"|\*(R". .B version .I # ] [ -.B prefer +.B ttl +.I # ] .PP -These three statements specify various time servers to be used and/or -time services to be provided. The +These three commands specify various time servers to be used and/or time +services to be provided. The .B peer -statement specifies that the given host is to be polled in -\*(L"symmetric active\*(R" mode, i.e. that the host is requested to -provide time which you might synchronize to and, in addition, indicates -that you are willing to have to remote host synchronize to your time -if need be. The +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 -statement specifies that the given host is to be polled in -\*(L"client\*(R" mode, i.e. that the host is requested to provide -time which you might synchronize with but that you are unwilling to have -the remote host synchronize to your own time. The +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 -statement requests your local daemon to transmit broadcast NTP to -the specified address. The latter is usually the broadcast address -on [one of] your 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 requires a multicast kernel. +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 +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 +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. -.PP -.B precision -.I # +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 -Indicates the precision of local timekeeping. The value is an integer -which is approximately the base 2 logarithm of the local timekeeping -precision in seconds. By default this value is set to -6. +.B broadcastclient .PP -The precision declared by an implementation can affect several aspects -of server operation, and can be used as a tuning parameter for your -synchronization subnet. It should probably not be changed from the -default value, however, unless there is a good reason to do so. +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 logfile -.I filename +.B multicastclient +[ +.I IP address ... +] .PP -Gives the file which is to be used instead of syslog output. This -configuration option is also a compile time option (SYSLOG_FILE). -So in order to be able to use this xntpd must be compiled with --DSYSLOG_FILE. +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 -Specifies the name of the file used to record the \*(L"drift\*(R" (or -frequency error) value -.I xntpd -has computed. If the file exists on startup, it is read and the value -used to initialize -.IR xntpd 's -internal value of the frequency error. The file is then updated once -every hour by replacing the old file with a new one containing the -current value of the frequency error. Note that the file is updated -by first writing the current drift value into a temporary file and -then using +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 +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 monitor yes|no -.PP -Indicates whether the -.I xntpd -traffic monitoring function should be enabled or not. When enabled, -this causes the origin address of each packet received by the server -to be recorded along with a limited amount of additional information, such -as the mode of the request and whether it originated from an NTP server port -or not. Traffic monitoring data may be inspected using the -.IR xntpdc (8) -.I monlist -command. The default is \*(L"no\*(R", i.e. traffic monitoring should not -be done. -.PP -Note that the traffic monitoring facility will increase the CPU used -by -.IR xntpd , -as well as increasing the daemon's memory utilization by as much as -8.5 kilobytes. This facility is normally useful for the detection of -peers with malfunctioning software or which are sending bogus data. It -is primarily intended for very popular servers which exchange time with -large numbers of peers, though it may also be useful for access monitoring -of local servers if you are willing to accept the overhead. -.PP -.B broadcastclient -.PP -This directs the local server should listen for, and attempt to -synchonize to, broadcast NTP. Note that authentication is required in -this mode. -.PP -.B multicastclient +.B enable auth|bclient|pll|monitor|stats [ -.I IP address ... +.I ... ] .PP -This directs the local server should listen for, and attempt to -synchonize to, multicast NTP. 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. If none are given, the default address assigned to -NTP (224.0.1.1) is assumed. -.PP -.B broadcastdelay -.I seconds -.PP -Specifies the default round trip delay to the host whose broadcasts -are being synchronized to. The value is specified in seconds and is -typically (for ethernet) a number between 0.007 and 0.015 seconds. This -initial estimate may be improved by polling each server to determine a -more accurate value. Defaults to 0.008 seconds. -.PP -.B authenticate yes|no -.PP -Indicates whether the local server should operate in authenticate mode -or not. If \*(L"yes\*(R", only peers which include an authentication field -encrypted with one of our trusted keys (see below) will be considered -as candidates for synchonizing to. The default is \*(L"no\*(R". -.PP -.B authdelay -.I seconds +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 -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. +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 -Specifies the name of a file which contains the encryption keys which -are to be used by -.IR xntpd . -The format of this file is described below. +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 # @@ -363,43 +361,67 @@ The format of this file is described below. .I "# ..." ] .PP -Allows the specification of the encryption key numbers which are trusted -for the purposes of determining peers suitable for time sychonization, -when authentication is enabled. Only peers using one of these keys for -encryption of the authentication field, and whose authenticity can be -verified by successful decryption, will be considered as synchonization -candidates. 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. +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 -.I Xntpd -allows run time reconfiguration to be performed using the +This command specifies the key identifier to use with the .IR xntpdc (8) -program. Such requests must be authenticated. The -.B requestkey -statement allows the specification of a 32 bit unsigned integer -key number to be used for authenticating such requests. Note that -if no +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 -statement is included in the configuration file the run time reconfiguration -facility will be disabled. +command is included in the configuration file, or if the keys don't +match, such requests will be ignored. .PP .B controlkey .I # .PP -Certain changes can be made to the +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 -server via mode 6 control messages, in particular the setting of -leap second indications in a server with a radio clock. -The -.B controlkey -statement specifies an encription key number to be used for authenticating -such messages. Omitting this statement will cause control messages -which would change the state of the server to be ignored. +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 [ @@ -411,202 +433,125 @@ which would change the state of the server to be ignored. .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 +.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 +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 as a dotted\-quad address, 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: +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. +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. +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. +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 +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. +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. +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. +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 -.IR 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. +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 +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). +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 +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. +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. +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. -.PP -.B trap -.I host_address -[ -.B port -.I port_number -] [ -.B interface -.I interface_addess -] -.PP -Configures a trap receiver at the given host address and port number, -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 maxskew -.I seconds -.PP -This command is obsolete and not available in this version of -.I xntpd. -.PP -.B select -.I algorithm_number -.PP -This command is obsolete and not available in this version of -.I xntpd. -.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 <name>=<value> is followed by the -.I default -keyword the variable will be 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 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 resolver -.I /path/xntpres -.PP -Normally, names requiring resolution (rather than numeric addresses) -in the configuration file are resolved by code internal to -.I xntpd; -However, in those cases that require it, the code can be installed -in a standalone program called -.I xntpres. -In these cases the full path to the -.I xntpres -program is given as the argument the command. -As -.I xntpres -makes use of mode 7 runtime reconfiguration, this facility must also be -enabled if the procedure is to exceed (see the -.B requestkey -and -.B keys -statements above). +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 +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). @@ -614,41 +559,41 @@ statement below). .B statistics .IR name \.\.\. .PP -Enables writing of statistics records. -Currently, three kinds of statistics are supported. +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": +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. +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": +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. +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 @@ -656,23 +601,23 @@ 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 +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 +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. +and displayed as well. See information specific to each clock for +further details. .RE .PP -Statistic files are managed using file generation sets (see +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 +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. @@ -700,43 +645,41 @@ 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 +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 -.IR xntpd . +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. +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 +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 +"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 +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". +denoted by \*(L"prefix\*(R". .Ip suffix 10 This part is reflects individual elements of a file set. It is generated -according to the +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: +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 @@ -744,42 +687,41 @@ 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 +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 +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 +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 +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 +is a two digit day number. Thus, all information written at December +10th, 1992 would end up in a file named \*(L"<prefix><filename>.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". +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 @@ -789,145 +731,232 @@ 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. +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". +\*(L"enabled\*(R". Output is prevented by specifying \*(L"disabled\*(R". .PP -It is convenient to be able to access the +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 +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. +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 <name>=<value> 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 +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 -using the DES encryption algorithm. The specification -allows any one of a possible 4 billion keys, numbered with 32 bit unsigned -integers, to be used to -authenticate an association. The servers involved in an association -must agree on the value of the key used to authenticate their data, though -they must each learn the key independently. The keys are standard 56 bit -DES keys. -.PP -Addionally, a new experimental authentication algorithm is available which -uses an MD5 message digest to compute an authenticator. Currently the length -of the key or password is limited to 8 characters, but this will eventually -be changed to accomodate an effectively unlimited password phrase. -.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 +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 +file. Key entries use a fixed format of the form .Ip "" 5 -.I "keyno type key" +.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. +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 +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 +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 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 +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 +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 +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 +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. +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 -.PP -.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. +.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 +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 normally -enabled by configuring the clock as a server using a +indicates the type\-specific unit number. Reference clocks are +configured using a .B server -statement in the configuration file which references the clock's -address (configuring a reference clock with a -.B peer -statement can also be done, though with some clock drivers this may cause -the clock to be treated somewhat differently and by convention is used -for debugging purposes). Clock addresses may generally -be used anywhere else in the configuration file a normal IP address -can be used, for example in +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. +statements, although such use would normally be considered strange. .PP -There is one additional configuration statement which becomes valid -when reference clock support has been compiled in. Its format is: +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 @@ -938,10 +967,10 @@ when reference clock support has been compiled in. Its format is: .B time2 .I secs ] [ -.B value1 +.B stratum .I int ] [ -.B value2 +.B refid .I int ] [ .B flag1 @@ -949,502 +978,106 @@ when reference clock support has been compiled in. Its format is: ] [ .B flag2 .I 0|1 +] [ +.B flag3 +.I 0|1 +] [ +.B flag4 +.I 0|1 ] .PP -There are two times (whose values are specified in fixed point seconds), -two integral values and two binary flags available for customizing -the operation of a clock. The interpretation of these values, and -whether they are used at all, is a function of the needs of the particular -clock driver. -.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 -pps.txt file in the doc directory of the xntp3 distribution. -The clock drivers, and the addresses used to configure -them, are described following: -.PP -.B 127.127.1.u -\- Local synchronization clock driver -.PP -This driver doesn't support an actual clock, but rather allows the -server to synchronize to its own clock, in essence to free run without -its stratum increasing to infinity. This can be used to run an -isolated NTP synchronization network where no standard time source is -available, by allowing a free running clock to appear as if it has -external synchronization to other servers. By running the local clock -at an elevated stratum it can also be used to prevent a server's stratum -from rising above a fixed value, this allowing a synchronization subnet -to synchonize to a single local server for periods when connectivity -to the primary servers is lost. -.PP -The unit number of the clock (the least significant octet in the address) -must lie in the range 0 through 15 inclusive and is used as the stratum -the local clock will run at. Note that the server, when synchronized -to the local clock, will advertise a stratum one greater than the clock -peer's stratum. More than one local clock may be configured (indeed all -16 units may be active at once), though this hardly seems useful. -.PP -The local clock driver uses only the fudge time1 parameter. This parameter -provides read and write access to the local clock drift compensation -register. This value, which actually provides a fine resolution speed -adjustment for the local clock, is settable but will remain unchanged -from any set value -when the clock is free running without external synchronization. The -fudge time1 parameter thus provides a way to manually adjust the speed of the -clock to maintain reasonable synchronization with, say, a voice -time announcement. It is actually more useful to manipulate this value -with the -.IR xntpdc (8) -program. -.PP -.B 127.127.3.u -\- Precision Standard Time/Traconex 1010/1020 WWV/H Receiver -.PP -This driver can be used with a PST/Traconex Time Source 1010 or 1020 WWV/WWVH -Synchronized Clock connected via a serial port. Up to -four units, with unit numbers in the range 0 through 3, can be -configured. The driver assumes the serial port device name is -/dev/pst%d (i.e. unit 1, at 127.127.3.1, opens the clock at -/dev/pst1) and that the clock is configured for 9600-baud operation. -.PP -The fudge time1 and time2 parameters are configured directly into the receiver -as nominal propagation delays when synchronized to WWV and WWVH, -respectively; the internal DIPswitches ordinarily used for that purpose -are disabled. The default values are 0.0075 and 0.0265 seconds, -respectively, which are about right for Toronto. Values for other -locations can be calculated using the -.I propdelay -program in the util directory of the xntp3 distribution or equivalent -means described in the user's manual. -.PP -The fudge value1 parameter can be used to set the stratum at which -the peer operates. The default is 0, which is correct if you want the -clock to be considered for synchonization whenever it is operating, though -higher values may be assigned if you only want the clock to provide backup -service when all other primary sources have failed. The value2 parameter -is set to the number of minutes which the daemon will allow the clock to go -without synchronization before it starts disbelieving it. The default -is 20, which is suitable if you have good quality backup NTP peers. If -your network is isolated or your network connections are poor it might -be advantageous to increase this value substantially. -.PP -The fudge flag1 can be used to modifiy the averaging algorithm used -to smooth the clock indications. Ordinarily, the algorithm picks the -median of a set of samples, which is appropriate under conditions -of poor to fair radio propagation conditions. If the clock is located -relatively close to the WWV or WWVH transmitters, setting this flag -will cause the algorithm to average the set of samples, which can -reduce the residual jitter and improve accuracy. -.PP -The fudge flag2 can be used to force the driver to send to -the clock the commands required to reprogram the current WWV and WWVH fudge -delays into it. This is normally done only when the values are to be changed, -such as during inital setup and calibration. Setting -the (otherwise undocumented) fudge flag3 will cause the driver to reset -the clock. The latter two flags are generally useful primarily for debugging. -.PP -127.127.4.u -\- Spectracom 8170 and Netclock/2 WWVB Synchronized Clocks -.PP -This driver can be used with a Spectracom 8170 or Netclock/2 WWVB -Synchronized Clock connected via a serial port. Up to -four units, with unit numbers in the range 0 through 3, can be -configured. The driver assumes the serial port device name is -/dev/wwvb%d (i.e., unit 1 at 127.127.4.1 opens the clock at -/dev/wwvb1) and that the clock is configured for 9600-baud operation. -.PP -The fudge time1 parameter can be used to compensate for inherent -latencies in the serial port hardware and operating system. -The value, which defaults to zero, is in addition to the value -programmed by the propagation switches on the receiver. The -fudge value1 parameter can be used to specify the stratum of the clock -in the same way described above for the WWV/WWVH clock 127.127.3.u. -.PP -.B 127.127.5.u -\- Kinemetrics/TrueTime Timing Receivers -.PP -This driver can be used with at least two models of Kinemetrics/TrueTime -Timing Receivers, the 468-DC MK III GOES Synchronized Clock and GPS-DC -MK III GPS Synchronized Clock and very likely others in the same model -family that use the same timecode formats. The clocks are connected -via a serial port. Up to -four units, with unit numbers in the range 0 through 3, can be -configured. The driver assumes the serial port device name is -/dev/goes%d (i.e., unit 1 at 127.127.5.1 opens the clock at -/dev/goes1) and that the clock is configured for 9600-baud operation. -.PP -The fudge time1 parameter can be used to compensate for inherent -latencies in the serial port hardware and operating system in the same -way as described above for the WWVB clock 127.127.4.u. -The fudge value1 parameter can be used to specify the stratum of the clock -in the same way described above for the WWV/WWVH clock 127.127.3.u. -.PP -.B 127.127.6.0 -\- IRIG-B Audio Decoder -.PP -This driver can be used in conjuction with the Inter-Range Instrumentation -Group standard time-distribution signal IRIG-B. This signal is generated -by several radio clocks, including those made by Austron, TrueTime, Odetics -and Spectracom, among others, although it is generally an add-on option. -The signal is connected via an attenuator box and cable to the audio -codec input on a Sun SPARCstation and requires a specially modified -kernel audio driver. Details are in the irig.txt file in the doc -directory of the xntp3 distribution. As only a single audio codec -is built into a workstation, the driver assumes the device name is /dev/irig. -.PP -Timing jitter using the decoder and a Sun IPC is in the order of a few -microseconds, although the overal timing accuracy is limited by the -wander of the CPU oscillator used for timing purposes to a few hundred -microseconds. These figures are comparable with what can be achieved -using the 1-pps signal described in the pps.txt file in the doc -directory of the xntp3 distribution. -.PP -.B 127.127.7.u -\- CHU Modem Decoder -.PP -This driver can be used with a shortwave receiver and special modem -circuitry described in the gadget directory of the xntp3 distribution. -It requires the chu-clk line discipline or chu_clk STREAMS module -described in the kernel directory of that distribution. It is connected -via a serial port operating at 300 baud. Up to -four units, with unit numbers in the range 0 through 3, can be -configured. The driver assumes the serial port device name is -/dev/chu%d (i.e., unit 1 at 127.127.7.1 opens the clock at -/dev/chu1). -.PP -Unlike the NIST time services, whose timecode requires quite specialized -hardware to interpret, the CHU timecode can be received directly via -a serial port after demodulation. While there are currently no commercial -CHU receivers, the hardware required to receive the CHU timecode is fairly -simple to build. While it is possible to configure several CHU units -simultaneously this is not recommended as the character interrupts from all -units will be occuring at the same time and will interfere with each other. -.PP -The fudge time1 parameter is used to specify the propagation delay between -the CHU transmitter at Ottawa, Ontario, and the receiver. The default -value is 0.0025 seconds, which is about right for Toronto. Values for other -locations can be calculated using the -.I propdelay -program in the util directory of the xntp3 distribution or equivalent -means. -The fudge time2 -parameter is used to compensate for inherent latencies in the modem, -serial port hardware and operating system in the same way as described -above for the WWVB clock 127.127.4.u. The default value is -0.0002 seconds, which is about right for typical telephone modem chips. -The fudge value1 parameter can be used to specify the stratum of the clock -in the same way described above for the WWV/WWVH clock 127.127.3.u. -The fudge flag1 can be used to modify the averaging algorithm in the -same way as described for that clock. -.PP -.B 127.127.8.u -\- Synchronisation to several receivers (DCF77, GPS) -.PP -The timecode of -the receivers will be sampled via a STREAMS module in the kernel (The STREAMS module -has been designed for use with SUN Systems under SunOS 4.1.x. It can be -linked directly into the kernel or loaded via the loadable driver mechanism) -This STREAMS module can be adepted to be able to convert different time code -formats. -If the daemon is compiled without the STREAM definition synchronisation -will work without the Sun streams module, though accuracy is significantly -degraded. -.br -The actual receiver status is mapped into various synchronisation -states generally used by receivers. The STREAMS module is configured to -interpret the time codes of DCF U/A 31, PZF535, GPS166, Trimble SV6 GPS, ELV DCF7000, -Schmid and low cost receivers (see list below). -.br -The reference clock support in xntp contains the necessary configuration tables -for those receivers. In addition to supporting up to 32 different clock types and -4 devices the generation a a PPS signal is also provided as an configuration -option. The PPS configuration option uses the receiver generated time stamps -for feeding the PPS loopfilter control for much finer clock synchronisation. -.br -CAUTION: The PPS configuration option is different from the hardware PPS signal, -which is also supported (see below), as it controls the way xntpd is synchronised -to the reference clock, while the hardware PPS signal controls the way time -offsets are determined. -.br -The use of the PPS option requires receivers with an accuracy of better than 1ms. -.PP -Fudge factors -.PP -Only two fudge factors are utilized. The -.I time1 -fudge factor defines the phase offset of the sychnronisation character to the actual -time. -On the availability of PPS information the -.I time2 -fudge factor defines the skew between the PPS time stamp and the reception -time stamp of the PPS signal. This parameter is usually 0 as usually -the PPS signal is believed in time and OS delays should be corrected -in the machine specific section of the kernel driver. -.I time2 -needs only be set when the actial PPS signal is delayed for some -reason. The -.I flag0 -enables input filtering. This a median filter with continuous sampling. The -.I flag1 -selects averaging of the samples remaining after the filtering. Leap second -handling is controlled with the -.I flag2. -When set a leap second will be deleted on receipt of a leap second indication -from the receiver. Otherwise the leap second will be added (which is the default). +.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 ntpq -timecode variable -.PP -The ntpq read clock variables command list several variables. These -hold followinf information: -.I refclock_time -is the local time with the offset to UTC (format HHMM). -The currently active receiver flags are listed in -.I refclock_status. -Additional feature flags of the receiver are optionally listed in paranthesis. -The actual time code is listed in -.I timecode. -A qualification of the decoded time code format is following in -.I refclock_format. -The last piece of information is the overall running time and the accumulated -times for the clock event states in -.I refclock_states. -When PPS information is present additional variable are available. -.I refclock_ppstime -lists then the PPS timestamp and -.I refclock_ppsskew -lists the difference between RS232 derived timestamp and the PPS timestamp. -.PP -Unit encoding -.PP -The unit field <u> encodes the device, clock type and the PPS generation option. -There are 4 possible devices which are encoded in the lower 2 bits of the <u> -field. The devices are named -.IR /dev/refclock-0 -through -.IR /dev/refclock-3 . -Bits 2 thru 6 encode the clock type. The fudge factors -of the clock type are take from a table -.I clockinfo -in refclock_parse.c. The generation of PPS information for disciplining the -local NTP clock is encoded in bit 7 of <u>. -.PP -Currently nine clock types (devices /dev/refclock-0 - /dev/refclock-3) are supported. -.Ip 127.127.8.0-3 16 -Meinberg PZF535 receiver (FM demodulation/TCXO / 50us) -.Ip 127.127.8.4-7 16 -Meinberg PZF535 receiver (FM demodulation/OCXO / 50us) -.Ip 127.127.8.8-11 16 -Meinberg DCF U/A 31 receiver (AM demodulation / 4ms) -.Ip 127.127.8.12-15 16 -ELV DCF7000 (sloppy AM demodulation / 50ms) -.Ip 127.127.8.16-19 16 -Walter Schmid DCF receiver Kit (AM demodulation / 1ms) -.Ip 127.127.8.20-23 16 -RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module / 5ms) -.Ip 127.127.8.24-27 16 -RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module / 5ms) -.Ip 127.127.8.28-31 16 -Meinberg GPS166 receiver (GPS / <<1us) -.Ip 127.127.8.32-35 16 -Trimble SV6 GPS receiver (GPS / <<1us) -.PP -The reference clock support carefully monitors the state transitions of -the receiver. All state changes and exceptional events such as loss of time code -transmission are logged via the -.I syslog -facility. -Every hour a summary of the accumulated times for the clock states is -listed via syslog. -.PP -PPS support is only available when the receiver is completely -synchronised. The receiver is believed to deliver correct time for an additional -period of time after losing sychronisation unless a disruption in time code -transmission is detected (possible power loss). The trust period is dependent -on the receiver oscillator and thus a function of clock type. This is one of -the parameters in the -.I clockinfo -field of the reference clock implementation. This parameter cannot be -configured by xntpdc. -.PP -In addition to the PPS loopfilter control a true PPS hardware signal can be applied -on Sun Sparc stations via the CPU serial ports on the CD pin. This signal is -automatically detected and will be used for offset calculation. The input signal -must be the time mark for the following time code. (The edge sensitivity can be -selected - look into the appropriate kernel/parsestreams.c for details). -Meinberg receivers can be connected by feeding the PPS pulse of the receiver via -a 1488 level converter to Pin 8 (CD) of a Sun serial zs\-port. -.PP -There exists a special firmware release for the PZF535 Meinberg receivers. -This release (PZFUERL 4.6 (or higher - The UERL is important)) is absolutely -recommended for XNTP use, as it provides LEAP warning, time code time zone information -and alternate antenna indication. Please check with Meinberg for this -firmware release. -For the Meinberg GPS166 receiver is also a special firmaware release available -(Uni-Erlangen). This release must be used for proper operation. -.PP -The raw DCF77 pulses can be fed via a level converter directly into Pin 3 (Rx) -of the Sun. The telegrams will be decoded an used for synchronisation. -AM DCF77 receivers are running as low as $25. The accuracy is dependent on -the receiver and is somewhere between 2ms (expensive) to 10ms (cheap). -Upon bad signal reception of DCF77 sychronisation will cease as no backup -oscillator is available as usually found in other reference clock receivers. -So it is important to have a good place for the DCF77 antenna. For transmitter -shutdowns you are out of luck unless you have other NTP servers with alternate -time sources available. -.PP -127.127.9.u -\- Magnavox MX4200 Navigation Receiver used as GPS Synchronized Clocks -.PP -This driver can be used with a Magnavox MX4200 Navigation Receiver -adapted to precision timing applications. This requires an interface -box described in the ppsclock directory of the xntp3 distribution. -It is connected via a serial port and requires the ppsclock STREAMS -module described in the same directory. Up to -four units, with unit numbers in the range 0 through 3, can be -configured. The driver assumes the serial port device name is -/dev/gps%d (i.e., unit 1 at 127.127.9.1 opens the clock at -/dev/gps1) and that the clock is configured for 9600-baud operation. -.PP -The fudge time1 parameter can be used to compensate for inherent -latencies in the serial port hardware and operating system in the -same way described above for the WWVB clock 127.127.4.u. The -fudge value1 parameter can be used to specify the stratum of the clock -in the same way described above for the WWV/WWVH clock 127.127.3.u. -.PP -127.127.10.u -\- Austron 2200A/2201A GPS/LORAN Synchronized Clock and Timing Receiver -.PP -This driver can be used with an Austron 2200A/2201A GPS/LORAN Synchronized -Clock and Timing Receiver connected via a serial port. It supports -several special features of the clock, including the Input Burffer Module, -Output Buffer Module, IRIG-B Interface Module and LORAN Assist Module. It -requires the RS232 Serial Interface module for communication with -the driver. Up to four units (which hardly seems affordable), with unit -numbers in the range 0 through 3, can be -configured. The driver assumes the serial port device name is -/dev/gps%d (i.e., unit 1 at 127.127.10.1 opens the clock at -/dev/gps1) and that the clock is configured for 9600-baud operation. -.PP -The fudge time1 parameter can be used to compensate for inherent -latencies in the serial port hardware and operating system in the -same way described above for the WWVB clock 127.127.4.u. The -fudge value1 parameter can be used to specify the stratum of the clock -in the same way described above for the WWV/WWVH clock 127.127.3.u. -.PP -This receiver is capable of a comprehensive and large volume of -statistics and operational data. The specific data-collection -commands and attributes are embedded in the driver source code; -however, the collection process can be enabled or disabled -using the flag4 flag. If set, collection is enabled; if not, -which is the default, it is disabled. A comprehensive suite of data reduction -and summary scripts is in the ./scripts/stats directory of the xntp -distribution. -.PP -127.127.11.u -\- Kinemetrics/TrueTime OMEGA-DC OMEGA Synchronized Clock -.PP -This driver can be used with a Kinemetrics/TrueTime OMEGA-DC OMEGA -Synchronized Clock connected via a serial port. This clock is -sufficiently different than other Kinemetrics/TrueTime models -to require a separate driver. Up to -four units, with unit numbers in the range 0 through 3, can be -configured. The driver assumes the serial port device name is -/dev/omega%d (i.e., unit 1 at 127.127.11.1 opens the clock at -/dev/omega1) and that the clock is configured for 9600-baud operation. -.PP -The fudge time1 parameter can be used to compensate for inherent -latencies in the serial port hardware and operating system in the -same way described above for the WWVB clock 127.127.4.u. The -fudge value1 parameter can be used to specify the stratum of the clock -in the same way described above for the WWV/WWVH clock 127.127.3.u. -.PP -127.127.12.0 -\- KSI/Odeteics TPRO IRIG-B Decoder -.PP -This driver can be used with a KSI/Odeteics TPRO or TPRO-SAT IRIG-B -Decoder, which is a module connected directly to the SBus of a -Sun workstation. The module works with the IRIG-B signal generated -by several radio clocks, including those made by Austron, TrueTime, Odetics -and Spectracom, among others, although it is generally an add-on option. -In the case of the TPRO-SAT, the module is an integral part of a GPS -receiver, which serves as the primary timing source. -As only a single module of this type can be -used on a single workstation, only the unit number 0 is acceptable. -The driver assumes the device name is /dev/tpro0. -.PP -The fudge time1 parameter can be used to compensate for inherent -latencies in the serial port hardware and operating system in the -same way described above for the WWVB clock 127.127.4.u. The -fudge value1 parameter can be used to specify the stratum of the clock -in the same way described above for the WWV/WWVH clock 127.127.3.u. -.PP -127.127.13.u -\- Leitch CSD 500 Controller with HP 5061A Atomic Clock -.PP -This driver can be used with a Leitch CSD 500 Controller -connected to an HP 5061A Atomic Clock or equivalent primary timing source -and connected via a serial port. Up to -four units, with unit numbers in the range 0 through 3, can be -configured. The driver assumes the serial port device name is -/dev/leitch%d (i.e., unit 1 at 127.127.13.1 opens the clock at -/dev/leitch1) and that the clock is configured for 300-baud operation. -.PP -The fudge time1 parameter can be used to compensate for inherent -latencies in the serial port hardware and operating system in the -same way described above for the WWVB clock 127.127.4.u. The -fudge value1 parameter can be used to specify the stratum of the clock -in the same way described above for the WWV/WWVH clock 127.127.3.u. -.PP -127.127.14.u -\- EES M201 MSF receiver -.PP -This driver can be used with an EES M201 MSF receiver connected -to a Sun running SunOS 4.x with the "ppsclock" STREAMS module. -.PP -The fudge time1 and time2 parameters can be used to compensate for -inherent latencies in the serial port hardware and operating system -respectively in the same way described above for the WWVB clock 127.127.4.u. -The bottom 4 bits of fudge value1 parameter can be used to specify -the stratum of the clock in the same way described above for the -WWV/WWVH clock 127.127.3.u. -The fudge value2 parameter can be used to specify the debug mask. -bit 0x1 causes logging of smoothing processing. -bit 0x4 causes the clock buffer to be dumped. -If flag1 is set, then the system clock is assumed to be sloppy -(e.g. Sun4 with 20ms clock), so samples are averaged. -If flag2 is set, then leaphold is set. -If flag3 is set, then the sample information is dumped. -If flag4 is set, then the input data is smoothed, and all data -points are used. +.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 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 +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 +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 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). +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). +Leap information from the sychronisation source is ignored (thus +LEAP_NOWARNING is passed on). .PP .SH FILES .Ip /etc/ntp.conf 20 @@ -1460,20 +1093,13 @@ the conventional name of the key file .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. +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. This will eventually be corrected -either by adopting the -.I ntpd -daemon as an alternative when it becomes able to match -.IR xntpd 's -performance, or if not than by producing a stripped down version of .I xntpd -specifically for workstation use. +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. |
