From: Harlan Stenn Date: Fri, 14 Jul 2000 17:44:09 +0000 (-0000) Subject: authopt.htm, debug.htm, index.htm, ntpq.htm: X-Git-Tag: NTP_4_0_99_K~12 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a80e94388df323771045570668fbbacbdf43a044;p=thirdparty%2Fntp.git authopt.htm, debug.htm, index.htm, ntpq.htm: * html/ntpq.htm: * html/index.htm: * html/debug.htm: * html/authopt.htm: Reality check. From Dave Mills bk: 396f5169YKWhtCyziR1hQi8V28gJUg --- diff --git a/ChangeLog b/ChangeLog index add4123ae6..72b627893d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2000-07-14 Harlan Stenn + + * html/ntpq.htm: + * html/index.htm: + * html/debug.htm: + * html/authopt.htm: + Reality check. + From Dave Mills + 2000-07-13 Harlan Stenn * Makefile.am (SUBDIRS): Added ElectricFence diff --git a/html/authopt.htm b/html/authopt.htm index c418bce53a..9e9416c0be 100644 --- a/html/authopt.htm +++ b/html/authopt.htm @@ -83,16 +83,16 @@ associations, additional keys can be used as passwords for the ntpq and ntpdc utility programs. -

When ntpd is first started, it reads the key file and -installs the keys in the key cache. However, the keys must be activated -with the trusted command before use. This allows, for instance, -the installation of possibly several batches of keys and then activating -or deactivating each batch remotely using ntpdc. This also -provides a revocation capability that can be used if a key becomes -compromised. The requestkey command selects the key used as the -password for the ntpdc utility, while the controlkey -command selects the key used as the password for the ntpq -utility. +

When ntpd is first started, it reads the key file specified +int he keys command and installs the keys in the key cache. +However, the keys must be activated with the trusted command +before use. This allows, for instance, the installation of possibly +several batches of keys and then activating or deactivating each batch +remotely using ntpdc. This also provides a revocation +capability that can be used if a key becomes compromised. The +requestkey command selects the key used as the password for the +ntpdc utility, while the controlkey command selects +the key used as the password for the ntpq utility.

Public-Key Scheme

@@ -135,18 +135,26 @@ file name.

The ntp.keys file contains the DES/MD5 private keys. It must be distributed by secure means to other servers and clients sharing the -same security compartment and made visible only to root. The -ntpkey file contains the RSA private key. It is useful only to -the machine that generated it and never shared with any other daemon or -application program, so must be made visible only to root. +same security compartment and made visible only to root. While this file +is not used with the autokey scheme, it is needed to authenticate some +remote configuration commands used by the ntpq and ntpdc +utilities. The ntpkey file contains the RSA private key. It is +useful only to the machine that generated it and never shared with any +other daemon or application program, so must be made visible only to +root.

The ntp_dh file contains the agreement parameters. It is necessary that all servers and clients of a security compartment share a single set of parameters, but it does not matter which ntp_dh -file generates them. The servers load the parameters directly from the -file, while the clients load them indirectly from the servers using the -autokey protocol. This file can be also be distributed using insecure -means, since the data are public values. +file generates them. Servers load the parameters directly from the +file, while the clients can load them indirectly from the servers using +the autokey protocol. Note that the parameters will be requested by all +associations, either configured or not; but, none of the associations +can proceed until one of them has received them. Once loaded, the +parameters can be provided on request to other clients and servers. The +ntp_dh file can be also be distributed using insecure means, +since the data are public values.

The ntpkey_host file contains the RSA public key, where host is the name of the host. Each server @@ -173,6 +181,26 @@ Therefore, when the most secure requirements apply, the public keys and agreement parameters should be loaded from files, rather than using the autokey protocol. +

Leapseconds Table + +

The NIST provides a table showing the epoch for all historic +occasions of leap second insertion since 1972. The leapsecond table +shows each epoch of insertion along with the offset of International +Atomic Time (TAI) with respect to Coordinated Universtal Time (UTC), as +disseminated by NTP. The table can be obtained directly from NIST +national time servers using ftp as the ASCII file pub/leap- +seconds. + +

While not strictly a security function, the Autokey scheme provides +means to securely retrieve the leapsecond table from a server or peer. +Servers load the leapsecond table directly from the file specified in +the crypto command, while clients can load the table indirectly +from the servers using the autokey protocol. Note that the table will be +requested by all associations, either configured or not; but, none of +the associations can proceed until one of them has received the table. +Once loaded, the table can be provided on request to other clients and +servers. +

Key Management

All key files are installed by default in /usr/local/etc, @@ -233,7 +261,6 @@ each association depends on this interval and the current poll interval. The default value is 12 (4096 s or about 1.1 hours). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent. -

controlkey key
Specifies the key identifier to use with the ntpq utility, which uses the standard @@ -241,8 +268,8 @@ protocol defined in RFC-1305. The key argument is the key identifier for a trusted key, where the value can be in the range 1 to 65534, inclusive.
-
crypto [privatekey file] [publickey file] [dhparms -file]
+
crypto [flags flags] [privatekey file] [publickey +file] [dhparms file] [leap file]
This command requires the NTP daemon build process be configured with the RSA library. This command activates public-key cryptography and loads the required RSA private and public key files and the optional @@ -252,6 +279,11 @@ below. Following are the subcommands:
+
flags flags +
Specifies optional flag bits. The only flag bit defined at this time +is 0x2 which causes the leapsecond file to be fetched from any +available server or peer.
+
privatekey file
Specifies the location of the RSA private key file, which otherwise defaults to /usr/local/etc/ntpkey.
@@ -265,6 +297,10 @@ defaults to /usr/local/etc/ntpkey_host., where
Specifies the location of the Diffie-Hellman parameters file, which otherwise defaults to /usr/local/etc/ntpkey_dh.
+
leap file +
Specifies the location of the leapsecond table file, +which otherwise defaults to /usr/local/etc/ntpkey_leap.
+
keys keyfile
diff --git a/html/debug.htm b/html/debug.htm index bf16049795..92fb81e9df 100644 --- a/html/debug.htm +++ b/html/debug.htm @@ -8,183 +8,199 @@ NTP Debugging Techniques and bug, Walt Kelly
-

Once the NTP software distribution has been compiled and installed +

Once the NTP software distribution has been compiled and installed and the configuration file constructed, the next step is to verify correct operation and fix any bugs that may result. Usually, the command line that starts the daemon is included in the system startup file, so it is executed only at system boot time; however, the daemon can be stopped and restarted from root at any time. Usually, no command-line arguments are required, unless special actions described in the -ntpd page are required. Once started, -the daemon will begin sending messages, as specified in the -configuration file, and interpreting received messages. +ntpd page are required. Once started, +the daemon will begin sending and receiving messages, as specified in +the configuration file. -

The best way to verify correct operation is using the ntpq and ntpdc +

Initial Startup

+ +

The best way to verify correct operation is using the ntpq and ntpdc utility programs, either on the server itself or from another machine -elsewhere in the network. The ntpq program implements the +elsewhere in the network. The ntpq program implements the management functions specified in Appendix A of the NTP specification -RFC-1305, Appendix A. The ntpdc program implements +HREF= +"http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305c.ps"> +RFC-1305, Appendix A. The ntpdc program implements additional functions not provided in the standard. Both programs can be used to inspect the state variables defined in the specification and, in -the case of ntpdc, additional ones of interest. In addition, -the ntpdc program can be used to selectively enable and disable -some functions of the daemon while the daemon is running. +the case of ntpdc, additional ones of interest. In addition, +the ntpdc program can be used to selectively reconfigure and +enable or disable some functions while the daemon is running. -

In extreme cases with elusive bugs, the daemon can operate in two -modes, depending on the presence of the -d command-line debug +

In extreme cases with elusive bugs, the daemon can operate in two +modes, depending on the presence of the -d command-line debug switch. If not present, the daemon detaches from the controlling -terminal and proceeds autonomously. If one or more -d switches +terminal and proceeds autonomously. If one or more -d switches are present, the daemon does not detach and generates special output useful for debugging. In general, interpretation of this output requires -reference to the sources. However, a single -d does produce +reference to the sources. However, a single -d does produce only mildly cryptic output and can be very useful in finding problems with configuration and network troubles. With a little experience, the -volume of output can be reduced by piping the output to grep -and specifying the keyword of the trace you want to see. - -

Some problems are immediately apparent when the daemon first starts -running. The most common of these are the lack of a ntp (UDP port 123) -in the host /etc/services file. Note that NTP does not use TCP -in any form. Other problems are apparent in the system log file. The log -file should show the startup banner, some cryptic initialization data, -and the computed precision value. The next most common problem is +volume of output can be reduced by piping the output to grep +and specifying the keyword of the trace you want to see. + +

Some problems are immediately apparent when the daemon first starts +running. The most common of these are the lack of a UDP port for NTP +(123) in the Unix /etc/services file. Note that NTP does not +use TCP in any form. Other problems are apparent in the system log file. +The log file should show the startup banner, some cryptic initialization +data and the computed precision value. The next most common problem is incorrect DNS names. Check that each DNS name used in the configuration -file responds to the Unix ping command. - -

When first started, the daemon normally polls the servers listed in -the configuration file at 64-second intervals. In order to allow a -sufficient number of samples for the NTP algorithms to reliably -discriminate between correctly operating servers and possible intruders, -at least four valid messages from at least one server is required before -the daemon can set the local clock. However, if the current local time -is greater than 1000 seconds in error from the server time, the daemon -will not set the local clock; instead, it will plant a message in the -system log and shut down. It is necessary to set the local clock to -within 1000 seconds first, either by a time-of-year hardware clock, by -first using the ntpdate program or -manually be eyeball and wristwatch. - -

After starting the daemon, run the ntpq program using the --n switch, which will avoid possible distractions due to name -resolution problems. Use the pe command to display a billboard +file responds to the Unix ping command. + +

When first started, the daemon normally polls the servers listed in +the configuration file at 64-s intervals. In order to allow a sufficient +number of samples for the NTP algorithms to reliably discriminate +between correctly operating servers and possible intruders, at least +four valid messages from the majority of servers and peers listed in the +configuration file is required before the daemon can set the local +clock. However, if the current system time is greater than 1000 s in +error from the server times, the daemon will not set the local clock; +instead, it will plant a message in the system log and shut down. It is +necessary to set the local clock to within 1000 s first, either by a +time-of-year hardware clock, by first using the ntpdate program or manually be eyeball +and wristwatch. + +

If the initial time error is less than 1000 s but greater than 125 +ms, the daemon will perform a step adjustment; otherwise, it will +gradually slew the clock to the nominal time. However, if a step +adjustment, the clock discipline algorithm will start all over again, +requiring another round of at least four messages as before. This is +necessary so that all servers and peers operate on the same set of time +values. + +

If, as discussed later in this page, for some reason the hardware +clock oscillator frequency error is relatively large, the time errors +upon first startup of the daemon may increase over time until exceeding +125 ms, which requires another step correction. However, due to +provisions that reduce vulnerability to noise spikes, the second +correction will not be done until 900 s have elapsed since the last +adjustment. When the frequency error is very large, it may take a number +of cycles like this until converging on the nominal frequency +correction. After this, the correction is written to the +ntp.drift file, which is read upon subsequent restarts, so the +herky-jerky cycles should not recur. + +

Verifying Correct Operation

+ +

After starting the daemon, run the ntpq program using the +-n switch, which will avoid possible distractions due to name +resolution problems. Use the pe command to display a billboard showing the status of configured peers and possibly other clients poking the daemon. After operating for a few minutes, the display should be something like: -

ntpq>pe
-remote      refid       st t when poll reach   delay  offset   disp
-===================================================================
-+128.4.2.6  132.249.16.1 2 u  131  256   373    9.89   16.28  23.25
-*128.4.1.20 .WWVB.       1 u  137  256   377  280.62   21.74  20.23
--128.8.2.88 128.8.10.1   2 u  49   128   376  294.14    5.94  17.47
-+128.4.2.17 .WWVB.       1 u  173  256   377  279.95   20.56  16.40
-
- -The host addresses shown in the remote column should agree with -the DNS entries in the configuration file, plus any peers not mentioned -in the file at the same or lower than your stratum that happen to be -configured to peer with you. Be prepared for surprises in cases where -the peer has multiple addresses or multiple names. The refid -entry shows the current source of synchronization for each peer, while -the st reveals the stratum, t the type (u = -unicast, m = multicast, l = local, - = don't -know), and poll the polling interval in seconds. The -when entry shows the time since the peer was last heard, -normally in seconds, while the reach entry shows the status of -the reachability register (see RFC-1305) in octal. The remaining entries -show the latest delay, offset and dispersion computed for the peer in -milliseconds. Note that in NTP Version 4 the dispersion entry includes -only the RMS error component; earlier versions included all components. - -

The tattletale character at the left margin displays the -synchronization status of each peer. The currently selected peer is -marked *, while additional peers designated acceptable for -synchronization, but not currently selected, are marked +. -Peers marked * and + are included in a weighted -average computation to set the local clock; the data produced by peers -marked with other symbols are discarded. See the ntpq -documentation for the meaning of these symbols. - -

Additional details for each peer separately can be determined by the -following procedure. First, use the as command to display an +

ntpq> pe
+     remote      refid       st t when poll reach delay offset jitter
+=====================================================================
+-isipc6.cairn.ne .GPS1.        1 u  18  64  377  65.592 -5.891  0.044
++saicpc-isiepc2. pogo.udel.edu 2 u 241 128  370  10.477 -0.117  0.067
++uclpc.cairn.net pogo.udel.edu 2 u  37  64  177 212.111 -0.551  0.187
+*pogo.udel.edu   .GPS1.        1 u  95 128  377   0.607  0.123  0.027
+
+ +

The host names or addresses shown in the remote column +correspond to the server and peer entries listed in the configuration +file; however, the DNS names might not agree if the names listed are not +the canonical DNS names. The refid column shows the current +source of synchronization, while the st column reveals the +stratum, t the type (u = unicast, m = +multicast, l = local, - = don't know), and +poll the poll interval in seconds. The when column +shows the time since the peer was last heard in seconds, while the +reach column shows the status of the reachability register (see +RFC-1305) in octal. The remaining entries show the latest delay, offset +and jitter in milliseconds. Note that in NTP Version 4 what used to be +the dispersion column has been replaced by the jitter +column. + +

The tattletale symbol at the left margin displays the synchronization +status of each peer. The currently selected peer is marked *, +while additional peers designated acceptable for synchronization, but +not currently selected, are marked +. Peers marked * +and + are included in the weighted average computation to set +the local clock; the data produced by peers marked with other symbols +are discarded. See the ntpq page for the meaning of these +symbols. + +

Additional details for each peer separately can be determined by the +following procedure. First, use the as command to display an index of association identifiers, such as -

ntpq>as
-ind assID status conf reach auth condition last_event cnt
-=========================================================
- 1  11670   7414   no   yes   ok candidate  reachable   1
- 2  11673   7614   no   yes   ok sys.peer   reachable   1
- 3  11833   7314   no   yes   ok outlyer    reachable   1
- 4  11868   7414   no   yes   ok candidate  reachable   1
-
- -Each line in this billboard is associated with the corresponding line -the pe billboard above. Next, use the rv command and -the respective identifier to display a detailed synopsis of the selected -peer, such as - -
ntpq>rv 11670
-status=7414 reach, auth, sel_sync, 1 event, event_reach
-srcadr=128.4.2.6, srcport=123, dstadr=128.4.2.7, dstport=123, keyid=1,
-stratum=2, precision=-10, rootdelay=362.00, rootdispersion=21.99,
-refid=132.249.16.1,
-reftime=af00bb44.849b0000 Fri, Jan 15 1993 4:25:40.517,
-delay= 9.89, offset= 16.28,
-dispersion=23.25, reach=373, valid=8,
-hmode=2, pmode=1, hpoll=8, ppoll=10, leap=00, flash=0x0,
-org=af00bb48.31a90000 Fri, Jan 15 1993 4:25:44.193,
-rec=af00bb48.305e3000 Fri, Jan 15 1993 4:25:44.188,
-xmt=af00bb1e.16689000 Fri, Jan 15 1993 4:25:02.087,
-filtdelay=  16.40 9.89  140.08  9.63  9.72  9.22 10.79 122.99,
-filtoffset= 13.24 16.28 -49.19 16.04 16.83 16.49 16.95 -39.43,
-filterror=  16.27 20.17  27.98 31.89 35.80 39.70 43.61  47.52
-
- -A detailed explanation of the fields in this billboard are beyond the -scope of this discussion; however, most variables defined in the -specification RFC-1305 can be found. The most useful portion for -debugging is the last three lines, which give the roundtrip delay, clock -offset and dispersion for each of the last eight measurement rounds, all -in milliseconds. Note that the dispersion, which is an estimate of the +

ntpq> as
+ind assID status  conf reach auth condition  last_event cnt
+===========================================================
+  1 50252  f314   yes   yes   ok    outlyer   reachable  1
+  2 50253  f414   yes   yes   ok   candidat   reachable  1
+  3 50254  f414   yes   yes   ok   candidat   reachable  1
+  4 50255  f614   yes   yes   ok   sys.peer   reachable  1
+
+ +

Each line in this billboard is associated with the corresponding line +in the pe billboard above. The assID shows the unique +identifier for each mobilized association, while the status +column shows the peer status word in hex, as defined in the NTP +specification. Next, use the rv command and the respective +assID identifier to display a detailed synopsis for the +selected peer, such as + +

ntpq> rv 50253
+status=f414 reach, conf, auth, sel_candidat, 1 event, event_reach,
+srcadr=saicpc-isiepc2.cairn.net, srcport=123, dstadr=140.173.1.46,
+dstport=123, keyid=3816249004, stratum=2, precision=-27,
+rootdelay=10.925, rootdispersion=12.848, refid=pogo.udel.edu,
+reftime=bd11b225.133e1437  Sat, Jul  8 2000 13:59:01.075, delay=10.550,
+offset=-1.357, jitter=0.074, dispersion=1.444, reach=377, valid=7,
+hmode=1, pmode=1, hpoll=6, ppoll=7, leap=00, flash=00 ok,
+org=bd11b23c.01385836  Sat, Jul  8 2000 13:59:24.004,
+rec=bd11b23c.02dc8fb8  Sat, Jul  8 2000 13:59:24.011,
+xmt=bd11b21a.ac34c1a8  Sat, Jul  8 2000 13:58:50.672,
+filtdelay=   10.45  10.50  10.63  10.40  10.48  10.43  10.49  11.26,
+filtoffset=  -1.18  -1.26  -1.26  -1.35  -1.35  -1.42  -1.54  -1.81,
+filtdisp=     0.51   1.47   2.46   3.45   4.40   5.34   6.33   7.28,
+hostname="miro.time.saic.com", publickey=3171359012, pcookie=0x6629adb2,
+hcookie=0x61f99cdb, initsequence=61, initkey=0x287b649c,
+timestamp=3172053041
+
+ +

A detailed explanation of the fields in this billboard are beyond the +scope of this discussion; however, most variables defined in the NTP +Version 3 specification RFC-1305 are available along with others defined +for NTP Version 4. This particular example was chosen to illustrate +probably the most complex configuration involving symmetric modes and +public-key cryptography. As the result of debugging experience, the +names and values of these variables may change from time to time. An +explanation of the current set is on the ntpq page. + +

A useful indicator of miscellaneous problems is the flash +value, which reveals the state of the various sanity tests on incoming +packets. There are currently eleven bits, one for each test, numbered +from the right, which is for test 1. If the test fails, the +corresponding bit is set to one and zero otherwise. If any bit is set +following each processing step, the packet is discarded. The meaning of +each test is described on the ntpq page. + +

The three lines identified as filtdelay, filtoffset +and filtdisp reveal the roundtrip delay, clock offset and +dispersion for each of the last eight measurement rounds, all in +milliseconds. Note that the dispersion, which is an estimate of the error, increases as the age of the sample increases. From these data, it is usually possible to determine the incidence of severe packet loss, network congestion, and unstable local clock oscillators. There are no hard and fast rules here, since every case is unique; however, if one or -more of the rounds show zeros, or if the clock offset changes -dramatically in the same direction for each round, cause for alarm -exists. - -

Finally, the state of the local clock can be determined using the -rv command (without the argument), such as - -

ntpq>rv
-status=0664 leap_none, sync_ntp, 6 events, event_peer/strat_chg
-system="UNIX", leap=00, stratum=2, rootdelay=280.62,
-rootdispersion=45.26, peer=11673, refid=128.4.1.20,
-reftime=af00bb42.56111000 Fri, Jan 15 1993 4:25:38.336,
-poll=8, clock=af00bbcd.8a5de000 Fri, Jan 15 1993 4:27:57.540,
-phase=21.147, freq=13319.46, compliance=2
-
- -The most useful data in this billboard show when the clock was last -adjusted reftime, together with its status and most recent -exception event. An explanation of these data is in the specification -RFC-1305. - -

When nothing seems to happen in the pe billboard after some -minutes, there may be a network problem. The most common network problem -is an access controlled router on the path to the selected peer. No -known public NTP time server selectively restricts access at this time, -although this may change in future; however, many private networks do. -It also may be the case that the server is down or running in -unsynchronized mode due to a local problem. Use the ntpq -program to spy on its own variables in the same way you can spy on your -own. - -

Once the daemon has set the local clock, it will continuously track +more of the rounds show large values or change radically from one round +to another, the network is probably congested or lossy. + +

Once the daemon has set the local clock, it will continuously track the discrepancy between local time and NTP time and adjust the local clock accordingly. There are two components of this adjustment, time and frequency. These adjustments are automatically determined by the clock @@ -195,18 +211,86 @@ of the local clock hardware oscillator that normally occur in practice. However, when started for the first time, the algorithm may take some time to converge on the intrinsic frequency error of the host machine. -

It has sometimes been the experience that the local clock oscillator -frequency error is too large for the NTP discipline algorithm, which can -correct frequency errors as large as 43 seconds per day. There are two -possibilities that may result in this problem. First, the hardware time- -of-year clock chip must be disabled when using NTP, since this can -destabilize the discipline process. This is usually done using the -tickadj program and the -s -command line argument, but other means may be necessary. For instance, -in the Sun Solaris kernel, this can be done using a command in the -system startup file. - -

Normally, the daemon will adjust the local clock in small steps in +

The frequency tolerance of computer clock oscillators can vary +widely, which can put a strain on the daemon's ability to compensate for +the intrinsic frequency error. While the daemon can handle frequency +errors up to 500 parts-per-million (PPM), or 43 seconds per day, values +much above 100 PPM reduce the headroom and increase the time to learn +the particular value and record it in the ntp.drift file. In +extreme cases before the particular oscillator frequency error has been +determined, the residual system time offsets can sweep from one extreme +to the other of the 128-ms tracking window only for the behavior to +repeat at 900-s intervals until the measurements have converged. + +

In order to determine if excessive frequency error is a problem, +observe the nominal filtoffset values for a number of rounds +and divide by the poll interval. If the result is something approaching +500 PPM, there is a good chance that NTP will not work properly until +the frequency error is reduced by some means. A common cause is the +hardware time-of-year (TOY) clock chip, which must be disabled when NTP +disciplines the software clock. For some systems this can be done using +the tickadj utility and the - +s command line argument. For other systems this can be done using a +command in the system startup file. + +

If the TOY chip is not the cause, the problem may be that the +hardware clock frequency may simply be too slow or two fast. In some +systems this might require tweaking a trimmer capacitor on the +motherboard. For other systems the clock frequency can be adjusted in +increments of 100 PPM using the tickadj utility and the - +t command line argument. Note that the tickadj alters +certain kernel variables and, while the utility attempts to figure out +an acceptable way to do this, there are many cases where +tickadj is incompatible with a running kernel. + +

The state of the local clock itself can be determined using the +rv command (without the argument), such as + +

ntpq> rv
+status=0644 leap_none, sync_ntp, 4 events, event_peer/strat_chg,
+version="ntpd 4.0.99j4-r Fri Jul  7 23:38:17 GMT 2000 (1)",
+processor="i386", system="FreeBSD3.4-RELEASE", leap=00, stratum=2,
+precision=-27, rootdelay=0.552, rootdispersion=12.532, peer=50255,
+refid=pogo.udel.edu,
+reftime=bd11b220.ac89f40a  Sat, Jul  8 2000 13:58:56.673, poll=6,
+clock=bd11b225.ee201472  Sat, Jul  8 2000 13:59:01.930, state=4,
+phase=0.179, frequency=44.298, jitter=0.022, stability=0.001,
+hostname="barnstable.udel.edu", publickey=3171372095, params=3171372095,
+refresh=3172016539
+
+ +

An explanation about most of these variables is in the RFC-1305 +specification. The most useful ones include clock, which shows +when the clock was last adjusted, and reftime, which shows when +the server clock of refid was last adjusted. The +version, processor and system values are very +helpful when included in bug reports. The mean millisecond time offset +(phase) and deviation (jitter) monitor the clock +quality, while the mean PPM frequency offset (frequency) and +deviation (stability) monitor the clock stability and serve as +a useful diagnostic tool. It has been the experience of NTP operators +over the years that these data represent useful environment and hardware +alarms. If the motherboard fan freezes up or some hardware bit sticks, +the system clock is usually the first to notice it. + +

Among the new variables added for NTP Version 4 are the +hostname, publickey, params and +refresh, which are used for the Autokey public-key cryptography +described on the Authentication Options page. +The values show the filestamps, in NTP seconds, that the associated +values were created. These are useful in diagnosing problems with +cryptographic key consistency and ordering principles. + +

When nothing seems to happen in the pe billboard after some +minutes, there may be a network problem. One common network problem +is an access controlled router on the path to the selected peer or an +access controlled server using methods described on the Access Control Options page. Another common problem +is that the server is down or running in unsynchronized mode due to a +local problem. Use the ntpq program to spy on the server +variables in the same way you can spy on your own. + +

Normally, the daemon will adjust the local clock in small steps in such a way that system and user programs are unaware of its operation. The adjustment process operates continuously as long as the apparent clock error exceeds 128 milliseconds, which for most Internet paths is a @@ -221,65 +305,55 @@ upon the epoch of a leap second.

Debugging Checklist

-If the ntpq or ntpdc programs do not show that +If the ntpq or ntpdc programs do not show that messages are being received by the daemon or that received messages do not result in correct synchronization, verify the following:
    -

  1. Verify the /etc/services file host machine is configured -to -accept UDP packets on the NTP port 123. NTP is specifically designed to -use UDP and does not respond to TCP.
    2. - -

  2. Check the system log for ntpd messages about -configuration -errors, name-lookup failures or initialization problems.
    3. - -

  3. Using the ntpdc program and iostats command, -verify that the received packets and packets sent counters are -incrementing. If the packets send counter does not increment and the -configuration file includes designated servers, something may be wrong -in the network configuration of the ntpd host. If this counter does -increment and packets are actually being sent to the network, but the -received packets counter does not increment, something may be wrong in -the network or the server may not be responding.
    4. - -

  4. If both the packets sent counter and received packets counter do -increment, but the rec timestamp in the pe billboard -shows far from the current date, received packets are probably being -discarded for some reason. There is a handy, undocumented state variable -flash visible in the pebillboard. The value is in hex -and normally has the value zero (OK). However, if something is wrong, -the bits of this variable, reading from the right, correspond to the -sanity checks listed in Section 3.4.3 of the NTP specification RFC-1305. A bit other than zero indicates the associated sanity -check failed.
    5. - -

  5. If the org, rec and xmt timestamps in the -pe billboard appear current, but the local clock is not set, as -indicated by a stratum number less than 16 in the rv command -without arguments, verify that valid clock offset, roundtrip delay and -dispersion are displayed for at least one peer. The clock offset should -be less than 1000 seconds, the roundtrip delay less than one second and -the dispersion less than one second.
    6. - - -

  6. While the algorithm can tolerate a relatively large frequency -error (up to 500 parts per million or 43 seconds per day), various -configuration errors (and in some cases kernel bugs) can exceed this -tolerance, leading to erratic behavior. This can result in frequent loss -of synchronization, together with wildly swinging offsets. Use the -ntpdc program (or temporary configuration file) and disable -pll command to prevent the ntpd daemon from setting the -clock. Using the ntpq or ntpdc programs, watch the -apparent offset as it varies over time to determine the intrinsic -frequency error. If the error increases by more than 22 milliseconds per -64-second poll interval, the intrinsic frequency must be reduced by some -means. The easiest way to do this is with the tickadj program and the -t -command line argument.
    7. +

  7. Verify the /etc/services file host machine is configured +to accept UDP packets on the NTP port 123. NTP is specifically designed +to use UDP and does not respond to TCP.
    8. + +

  8. Check the system log for ntpd messages about +configuration errors, name-lookup failures or initialization +problems.
    9. + +

  9. Verify using ping or other utility that packets actually +do make the round trip between the client and server. Verify using +nslookup or other utility that the DNS server names do exist +and resolve to valid Internet addresses. + +

  10. Using the ntpdc program, verify that the packets +received and packets sent counters are incrementing. If the sent counter +does not increment and the configuration file includes configured +servers, something may be wrong in the host network or interface +configuration. If this counter does increment, but the received counter +does not increment, something may be wrong in the network or the server +NTP daemon may not be running or the server itself may be down or not +responding.
    11. + +

  11. If both the sent and received counters do increment, but the +reach values in the pe billboard with ntpq +continues to show zero, received packets are probably being discarded +for some reason. If this is the case, the cause should be evident from +the flash variable as discussed above and on the ntpq +page.
    12. + +

  12. If the reach values in the pe billboard show +the servers are alive and responding, note the tattletale symbols at the +left margin, which indicate the status of each server resulting from the +various grooming and mitigation algorithms. The interpretation of these +symbols is discussed on the ntpq page. After a few minutes of +operation, one or another of the reachable server candidates should show +a * tattletale symbol. If this doesn't happen, the intersection +algorithm, which classifies the servers as truechimers or falsetickers, +may be unable to find a majority of truechimers among the server +population.
    13. + +

  13. If all else fails, see the FAQ and/or the discussion and +briefings at Network +Time Synchronization Project.
diff --git a/html/index.htm b/html/index.htm index 36a88b578e..2ea8eb54e5 100644 --- a/html/index.htm +++ b/html/index.htm @@ -35,7 +35,9 @@ year-2000 issues can be found in the Year 2000 Conformance Statement page. Background information, bibliography and briefing slides suitable for presentations can be found in the Network Time -Synchronization Project page. +Synchronization Project page. Additional information can be found at +the NTP web site www.ntp.org. Please send bug reports to <bugs@mail.ntp.org>.

Building and Installing NTP

@@ -62,6 +64,7 @@ somewhat, individual drivers can be included or excluded using the configure utility documented in the Configuration Options page.

Configuring Clients and Servers

+

NTP is by its very nature a complex distributed network application and can be configured and used for a great many widely divergent timekeeping scenarios. The documentation presented on these pages diff --git a/html/ntpq.htm b/html/ntpq.htm index 80261a1365..9f0382f5e5 100644 --- a/html/ntpq.htm +++ b/html/ntpq.htm @@ -10,266 +10,500 @@ ntpq - standard NTP query program

Description

-The ntpq utility program is used to query NTP servers which implement the recommended NTP mode 6 control message format about current state and to request changes in that state. The program may be run either in interactive mode or controlled using command line arguments. Requests to read and write arbitrary variables can be assembled, with raw and pretty-printed output options being available. ntpq can also obtain and print a list of peers in a common format by sending multiple queries to the server. - -

If one or more request options is included on the command line when ntpq is executed, each of the requests will be sent to the NTP servers running on each of the hosts given as command line arguments, or on localhost by default. If no request options are given, ntpq will attempt to read commands from the standard input and execute these on the NTP server running on the first host given on the command line, again defaulting to localhost when no other host is specified. ntpqwill prompt for commands if the standard input is a terminal device. - -

ntpq uses NTP mode 6 packets to communicate with the NTP server, and hence can be used to query any compatable server on the network which permits it. Note that since NTP is a UDP protocol this communication will be somewhat unreliable, especially over large distances in terms of network topology. ntpq makes one attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable +The ntpq utility program is used to query NTP servers which +implement the recommended NTP mode 6 control message format about +current state and to request changes in that state. The program may be +run either in interactive mode or controlled using command line +arguments. Requests to read and write arbitrary variables can be +assembled, with raw and pretty-printed output options being available. +ntpq can also obtain and print a list of peers in a common +format by sending multiple queries to the server. + +

If one or more request options is included on the command line when +ntpq is executed, each of the requests will be sent to the NTP +servers running on each of the hosts given as command line arguments, or +on localhost by default. If no request options are given, ntpq +will attempt to read commands from the standard input and execute these +on the NTP server running on the first host given on the command line, +again defaulting to localhost when no other host is specified. +ntpqwill prompt for commands if the standard input is a +terminal device. + +

ntpq uses NTP mode 6 packets to communicate with the NTP +server, and hence can be used to query any compatible server on the +network which permits it. Note that since NTP is a UDP protocol this +communication will be somewhat unreliable, especially over large +distances in terms of network topology. ntpq makes one attempt +to retransmit requests, and will time requests out if the remote host is +not heard from within a suitable timeout time. -

Command line options are described following. Specifying a command line option other than -i or -n will cause the specified query (queries) to be sent to the indicated host(s) immediately. Otherwise, ntpq will attempt to read interactive format commands from the standard input. +

For examples and usage, see the NTP Debugging +Techniques page. + +

Command line options are described following. Specifying a command +line option other than -i or -n will cause the +specified query (queries) to be sent to the indicated host(s) +immediately. Otherwise, ntpq will attempt to read interactive +format commands from the standard input.

-c
-
The following argument is interpreted as an interactive format command and is added to the list of commands to be executed on the specified host(s). Multiple -c options may be given.
+
The following argument is interpreted as an interactive format +command and is added to the list of commands to be executed on the +specified host(s). Multiple -c options may be given.
-i
-
Force ntpq to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input.
+
Force ntpq to operate in interactive mode. Prompts will be +written to the standard output and commands read from the standard +input.
-n
-
Output all host addresses in dotted-quad numeric format rather than converting to the canonical host names.
- +
Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names.
-p
-
Print a list of the peers known to the server as well as a summary of their state. This is equivalent to the peers interactive command.
+
Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the peers interactive +command.

Internal Commands

-Interactive format commands consist of a keyword followed by zero to four arguments. Only enough characters of the full keyword to uniquely identify the command need be typed. The output of a command is normally sent to the standard output, but optionally the output of individual commands may be sent to a file by appending a <, followed by a file name, to the command line. A number of interactive format commands are executed entirely within the ntpq program itself and do not result in NTP mode 6 requests being sent to a server. These are described following. +Interactive format commands consist of a keyword followed by zero to +four arguments. Only enough characters of the full keyword to uniquely +identify the command need be typed. The output of a command is normally +sent to the standard output, but optionally the output of individual +commands may be sent to a file by appending a <, followed by +a file name, to the command line. A number of interactive format +commands are executed entirely within the ntpq program itself +and do not result in NTP mode 6 requests being sent to a server. These +are described following.
? [command_keyword]

helpl [command_keyword] -
A ? by itself will print a list of all the command keywords known to this incarnation of ntpq. A ? followed by a command keyword will print funcation and usage information about the command. This command is probably a better source of information about ntpq than this manual page.
+
A ? by itself will print a list of all the command keywords +known to this incarnation of ntpq. A ? followed by a +command keyword will print function and usage information about the +command. This command is probably a better source of information about +ntpq than this manual page.
addvars variable_name [ = value] [...]

rmvars variable_name [...]
clearvars -
The data carried by NTP mode 6 messages consists of a list of items of the form variable_name = value, where the = value is ignored, and can be omitted, in requests to the server to read variables. ntpq maintains an internal list in which data to be included in control messages can be assembled, and sent using the readlist and writelist commands described below. The addvars command allows variables and their optional values to be added to the list. If more than one variable is to be added, the list should be comma-separated and not contain white space. The rmvars command can be used to remove individual variables from the list, while the clearlist command removes all variables from the list.
+
The data carried by NTP mode 6 messages consists of a list of items +of the form variable_name = value, where the += value is ignored, and can be omitted, in requests to the +server to read variables. ntpq maintains an internal list in +which data to be included in control messages can be assembled, and sent +using the readlist and writelist commands described +below. The addvars command allows variables and their optional +values to be added to the list. If more than one variable is to be +added, the list should be comma-separated and not contain white space. +The rmvars command can be used to remove individual variables +from the list, while the clearlist command removes all +variables from the list.
authenticate yes | no
-
Normally ntpq does not authenticate requests unless they are write requests. The command authenticate yes causes ntpq to send authentication with all requests it makes. Authenticated requests causes some servers to handle requests slightly differently, and can occasionally melt the CPU in fuzzballs if you turn authentication on before doing a peer display. [I didn't know that - Ed.]
+
Normally ntpq does not authenticate requests unless they +are write requests. The command authenticate yes causes +ntpq to send authentication with all requests it makes. +Authenticated requests causes some servers to handle requests slightly +differently, and can occasionally melt the CPU in fuzzballs if you turn +authentication on before doing a peer display. [I didn't know +that - Ed.]
cooked
-
Causes output from query commands to be "cooked", so that variables which are recognized by ntpq will have their values reformatted for human consumption. Variables which ntpq thinks should have a decodeable value but didn't are marked with a trailing ?.
+
Causes output from query commands to be "cooked", so that variables +which are recognized by ntpq will have their values reformatted +for human consumption. Variables which ntpq thinks should have +a decodable value but didn't are marked with a trailing +?.
debug more | less | off
Turns internal query program debugging on and off.
delay milliseconds
-
Specify a time interval to be added to timestamps included in requests which require authentication. This is used to enable (unreliable) server reconfiguration over long delay network paths or between machines whose clocks are unsynchronized. Actually the server does not now require timestamps in authenticated requests, so this command may be obsolete.
+
Specify a time interval to be added to timestamps included in +requests which require authentication. This is used to enable +(unreliable) server reconfiguration over long delay network paths or +between machines whose clocks are unsynchronized. Actually the server +does not now require timestamps in authenticated requests, so this +command may be obsolete.
host hostname
-
Set the host to which future queries will be sent. Hostname may be either a host name or a numeric address.
+
Set the host to which future queries will be sent. Hostname may be +either a host name or a numeric address.
hostnames [yes | no]
-
If yes is specified, host names are printed in information displays. If no is specified, numeric addresses are printed instead. The default is yes, unless modified using the command line -n switch.
+
If yes is specified, host names are printed in information +displays. If no is specified, numeric addresses are printed +instead. The default is yes, unless modified using the command +line -n switch.
keyid keyid
-
This command allows the specification of a key number to be used to authenticate configuration requests. This must correspond to a key number the server has been configured to use for this purpose.
+
This command allows the specification of a key number to be used to +authenticate configuration requests. This must correspond to a key +number the server has been configured to use for this purpose.
ntpversion 1 | 2 | 3 | 4
-
Sets the NTP version number which ntpq claims in packets. Defaults to 3, Note that mode 6 control messages (and modes, for that matter) didn't exist in NTP version 1. There appear to be no servers left which demand version 1.
+
Sets the NTP version number which ntpq claims in packets. +Defaults to 3, Note that mode 6 control messages (and modes, for that +matter) didn't exist in NTP version 1. There appear to be no servers +left which demand version 1.
quit
Exit ntpq.
passwd
-
This command prompts you to type in a password (which will not be echoed) which will be used to authenticate configuration requests. The password must correspond to the key configured for use by the NTP server for this purpose if such requests are to be successful.
+
This command prompts you to type in a password (which will not be +echoed) which will be used to authenticate configuration requests. The +password must correspond to the key configured for use by the NTP server +for this purpose if such requests are to be successful.
raw
-
Causes all output from query commands is printed as received from the remote server. The only formating/intepretation done on the data is to transform nonascii data into a printable (but barely understandable) form.
+
Causes all output from query commands is printed as received from +the remote server. The only formating/interpretation done on the data is +to transform nonascii data into a printable (but barely understandable) +form.
timeout millseconds
-
Specify a timeout period for responses to server queries. The default is about 5000 milliseconds. Note that since ntpq retries each query once after a timeout, the total waiting time for a timeout will be twice the timeout value set.
+
Specify a timeout period for responses to server queries. The +default is about 5000 milliseconds. Note that since ntpq +retries each query once after a timeout, the total waiting time for a +timeout will be twice the timeout value set.

Control Message Commands

-Each peer known to an NTP server has a 16 bit integer association identifier assigned to it. NTP control messages which carry peer variables must identify the peer the values correspond to by including its association ID. An association ID of 0 is special, and indicates the variables are system variables, whose names are drawn from a separate name space. - -

Control message commands result in one or more NTP mode 6 messages being sent to the server, and cause the data returned to be printed in some format. Most commands currently implemented send a single message and expect a single response. The current exceptions are the peers command, which will send a preprogrammed series of messages to obtain the data it needs, and the mreadlist and mreadvar commands, which will iterate over a range of associations. - +Each peer known to an NTP server has a 16 bit integer association +identifier assigned to it. NTP control messages which carry peer +variables must identify the peer the values correspond to by including +its association ID. An association ID of 0 is special, and indicates the +variables are system variables, whose names are drawn from a separate +name space. + +

Control message commands result in one or more NTP mode 6 messages +being sent to the server, and cause the data returned to be printed in +some format. Most commands currently implemented send a single message +and expect a single response. The current exceptions are the peers +command, which will send a preprogrammed series of messages to obtain +the data it needs, and the mreadlist and mreadvar commands, which will +iterate over a range of associations.

-
associations
-
Obtains and prints a list of association identifiers and peer statuses for in-spec peers of the server being queried. The list is printed in columns. The first of these is an index numbering the associations from 1 for internal use, the second the actual association identifier returned by the server and the third the status word for the peer. This is followed by a number of columns containing data decoded from the status word See the peers command for a decode of the condition field. Note that the data returned by the associations" command is cached internally in ntpq. The index is then of use when dealing with stupid servers which use association identifiers which are hard for humans to type, in that for any subsequent commands which require an association identifier as an argument, the form and index may be used as an alternative.
- -
clockvar [assocID] [variable_name [ = value [...]] [...]
- -
cv [assocID] [variable_name [ = value [...] ][...]
-
Requests that a list of the server's clock variables be sent. Servers which have a radio clock or other external synchronization will respond positively to this. If the association identifier is omitted or zero the request is for the variables of the system clock and will generally get a positive response from all servers with a clock. If the server treats clocks as pseudo-peers, and hence can possibly have more than one clock connected at once, referencing the appropriate peer association ID will show the variables of a particular clock. Omitting the variable list will cause the server to return a default variable display.
+
Obtains and prints a list of association identifiers and peer +statuses for in-spec peers of the server being queried. The list is +printed in columns. The first of these is an index numbering the +associations from 1 for internal use, the second the actual association +identifier returned by the server and the third the status word for the +peer. This is followed by a number of columns containing data decoded +from the status word See the peers command for a decode of the +condition field. Note that the data returned by the +associations" command is cached internally in ntpq. +The index is then of use when dealing with stupid servers which use +association identifiers which are hard for humans to type, in that for +any subsequent commands which require an association identifier as an +argument, the form and index may be used as an alternative.
+ +
clockvar [assocID] [variable_name [ = value +[...]] [...]
+ +
cv [assocID] [variable_name [ = value [...] +][...]
+
Requests that a list of the server's clock variables be sent. +Servers which have a radio clock or other external synchronization will +respond positively to this. If the association identifier is omitted or +zero the request is for the variables of the system clock and +will generally get a positive response from all servers with a clock. If +the server treats clocks as pseudo-peers, and hence can possibly have +more than one clock connected at once, referencing the appropriate peer +association ID will show the variables of a particular clock. Omitting +the variable list will cause the server to return a default variable +display.
lassocations
-
Obtains and prints a list of association identifiers and peer statuses for all associations for which the server is maintaining state. This command differs from the associations command only for servers which retain state for out-of-spec client associations (i.e., fuzzballs). Such associations are normally omitted from the display when the associations command is used, but are included in the output of lassociations.
+
Obtains and prints a list of association identifiers and peer +statuses for all associations for which the server is maintaining state. +This command differs from the associations command only for +servers which retain state for out-of-spec client associations (i.e., +fuzzballs). Such associations are normally omitted from the display when +the associations command is used, but are included in the +output of lassociations.
lpassociations
-
Print data for all associations, including out-of-spec client associations, from the internally cached list of associations. This command differs from passociations only when dealing with fuzzballs.
+
Print data for all associations, including out-of-spec client +associations, from the internally cached list of associations. This +command differs from passociations only when dealing with +fuzzballs.
lpeers
-
Like R peers, except a summary of all associations for which the server is maintaining state is printed. This can produce a much longer list of peers from fuzzball servers.
+
Like R peers, except a summary of all associations for which the +server is maintaining state is printed. This can produce a much longer +list of peers from fuzzball servers.
mreadlist assocID assocID

mrl assocID assocID -
Like the readlist command, except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent associations command.
- -
mreadvar assocID assocID [ variable_name [ = value[ ... ]
-
mrv assocID assocID [ variable_name [ = value[ ... ] -
Like the readvar command, except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent associations command.
+
Like the readlist command, except the query is done for +each of a range of (nonzero) association IDs. This range is determined +from the association list cached by the most recent +associations command.
+ +
mreadvar assocID assocID [ variable_name [ += value[ ... ]
+
mrv assocID assocID [ variable_name [ = +value[ ... ] +
Like the readvar command, except the query is done for each +of a range of (nonzero) association IDs. This range is determined from +the association list cached by the most recent associations +command.
opeers
-
An old form of the peers command with the reference ID replaced by the local interface address.
+
An old form of the peers command with the reference ID +replaced by the local interface address.
passociations
-
Displays association data concerning in-spec peers from the internally cached list of associations. This command performs identically to the associations except that it displays the internally stored data rather than making a new query.
+
Displays association data concerning in-spec peers from the +internally cached list of associations. This command performs +identically to the associations except that it displays the +internally stored data rather than making a new query.
peers
-
Obtains a current list peers of the server, along with a summary of each peer's state. Summary information includes the address of the remote peer, the reference ID (0.0.0.0 if this is unknown), the stratum of the remote peer, the type of the peer (local, unicast, multicast or broadcast), when the last packet was received, the polling interval, in seconds, the reachability register, in octal, and the current estimated delay, offset and dispersion of the peer, all in milliseconds.
- -
The character in the left margin indicates the fate of this peer in the clock selection process. Folowing is a list of these characters, the pidgeon used in the rv command, and a short explanation of the condition revealed.
+
Obtains a current list peers of the server, along with a summary of +each peer's state. Summary information includes the address of the +remote peer, the reference ID (0.0.0.0 if this is unknown), the stratum +of the remote peer, the type of the peer (local, unicast, multicast or +broadcast), when the last packet was received, the polling interval, in +seconds, the reachability register, in octal, and the current estimated +delay, offset and dispersion of the peer, all in milliseconds.
+ +
The character in the left margin indicates the fate of this peer in +the clock selection process. Following is a list of these characters, +the +pigeon used in the rv command, and a short explanation of the +condition revealed.
space reject
-
The peer is discarded as unreachable, synchronized to this server (synch loop) or outrageous synchronization distance.
+
The peer is discarded as unreachable, synchronized to this server +(synch loop) or outrageous synchronization distance.
x  falsetick
-
The peer is discarded by the intersection algorithm as a falseticker.
+
The peer is discarded by the intersection algorithm as a +falseticker.
.  excess
-
The peer is discarded as not among the first ten peers sorted by synchronization distance and so is probably a poor candidate for further consideration.
+
The peer is discarded as not among the first ten peers sorted by +synchronization distance and so is probably a poor candidate for further +consideration.
-  outlyer
-
The peer is discarded by the clustering algorithm as an outlyer.
+
The peer is discarded by the clustering algorithm as an +outlyer.
+  candidat
-
The peer is a survivor and a candidate for the combining algorithm.
+
The peer is a survivor and a candidate for the combining +algorithm.
#  selected
-
The peer is a survivor, but not among the first six peers sorted by synchronization distance. If the assocation is ephemeral, it may be demobilized to conserve resources.
+
The peer is a survivor, but not among the first six peers sorted by +synchronization distance. If the assocation is ephemeral, it may be +demobilized to conserve resources.
*  sys.peer
-
The peer has been declared the system peer and lends its variables to the system variables.
+
The peer has been declared the system peer and lends its variables +to the system variables.
o  pps.peer
-
The peer has been declared the system peer and lends its variables to thesystem variables. However, the actual system synchronization is derived from a pulse-per-second (PPS) signal, either indirectly via the PPS reference clock driver or directly via kernel interface.
+
The peer has been declared the system peer and lends its variables +to thesystem variables. However, the actual system synchronization is +derived from a pulse-per-second (PPS) signal, either indirectly via the +PPS reference clock driver or directly via kernel interface.
- -

The flash variable is not defined in the NTP specification, but is included as a valuable debugging aid. It displays the results of the original sanity checks defined in the NTP specification RFC-1305 and additional ones added since then. There are eleven tests named TEST1 through TEST11. Tests TEST1 through TEST5 represent checks on the basic header data from which the offset and delay are calculated. If any of these tests fail, the packet is discarded without further processing. Tests TEST6 through TEST9 represent checks on the remaining header values. Tests TEST10 and TEST11 represent checks using public key cryptography. They have meaning only if support for the autokey public key support has been configured in the system. If any of these tests fail, the basic header data are captured, but the packet is then discarded. The bits for each test read in increasing order from the least significant bit are defined as follows.
- -

The following TEST1 through TEST4 enumerate procedure errors. The packet timestamps may or may not be believed, but the remaining header data are ignored.
+

The flash variable is a valuable debugging aid. It +displays the results of the original sanity checks defined in the NTP +specification RFC-1305 and additional ones added in NTP Version 4. There +are eleven tests called TEST1 through TEST11. The +tests are performed in a certain order designed to gain maximum +diagnostic information while protecting against accidental or malicious +errors. The flash variable is first initialized to zero. If +after each set of tests one or more bits are set, the packet is +discarded. + +

Tests TEST4 and TEST5 check the access permissions +and cryptographic message digest. If any bits are set after that, the +packet is discarded. Tests TEST10 and TEST11 check the +authentication state using Autokey public-key cryptography, as described +in the Authentication Options page. If any bits +are set and the association has previously been marked reachable, the +packet is discarded; otherwise, the originate and receive timestamps are +saved, as required by the NTP protocol, and processing continues. + +

Tests TEST1 through TEST3 check the packet +timestamps from which the offset and delay are calculated. If any bits +are set, the packet is discarded; otherwise, the packet header variables +are saved. Tests TEST6 through TEST8 check the health +of the server. If any bits are set, the packet is discarded; otherwise, +the offset and delay relative to the server are calculated and saved. +Test TEST9 checks the health of the association itself. If any +bits are set, the packet is discarded; otherwise, the saved variables +are passed to the clock filter and mitigation algorithms. + +

The flash bits for each test read in increasing order from +the least significant bit are defined as follows.

TEST1
-
Duplicate packet. The packet is at best a casual retransmission and at worst a malicious replay.
+
Duplicate packet. The packet is at best a casual retransmission and +at worst a malicious replay.
TEST2
-
Bogus packet. The packet is not a reply to a message previously sent. This can happen when the NTP daemon is restarted and before somebody else notices.
+
Bogus packet. The packet is not a reply to a message previously +sent. This can happen when the NTP daemon is restarted and before +somebody else notices.
TEST3
-
Unsynchronized. One or more timestamp fields are invalid. This normally happens when the first packet from a peer is received.
+
Unsynchronized. One or more timestamp fields are invalid. This +normally happens when the first packet from a peer is received.
TEST4
-
Access is denied. See the Access Control Options page.
+
Access is denied. See the Access Control +Options page.
TEST5
-
Cryptographic authentication fails. See the Authentication Options page.
+
Cryptographic authentication fails. See the Authentication Options page.
TEST6
The server is unsynchronized. Wind up its clock first.
TEST7
-
The server stratum is greater than 15. It is probably unsynchronized and its clock needs to be wound up.
+
The server stratum is at the maximum than 15. It is probably +unsynchronized and its clock needs to be wound up.
TEST8
-
Either the root delay or dispersion is greater than one second, which is highly unlikely unless the peer is synchronized to Mars.
- +
Either the root delay or dispersion is greater than one second, +which is highly unlikely unless the peer is synchronized to Mars.
TEST9
-
Either the peer delay or dispersion is greater than one second, which is higly unlikely unless the peer is on Mars.
+
Either the peer delay or dispersion is greater than one second, +which is higly unlikely unless the peer is on Mars.
TEST10
-
The autokey protocol has detected an authentication failure. See the Authentication Options page.
+
The autokey protocol has detected an authentication failure. See the +Authentication Options page.
TEST11
-
The autokey protocol has not verified the server or peer is authentic with public key credentials. See the Authentication Options page.
+
The autokey protocol has not verified the server or peer is +authentic and has valid public key credentials. See the Authentication Options page.
-

Additional system variables not defined in the NTP specification -RFC-1305 are used by the autokey public key support. They include the following: +

Additional system variables used by the NTP Version 4 Autokey +support include the following:
-
privatekey filename/
-
Specifies the name of the RSA private key file.
+
leaptable filestamp/
+
Shows the NTP seconds when the NIST leapsecond table file was +created.
-
publickey filename/
-
Specifies the name of the RSA public key file.
+
hostname host/
+
Shows the name of the host as returned by the Unix +gethostname() library function.
-
dhparams filename/
-
Specifies the name of the Diffie-Hellman parameter file.
+
params filestamp/
+
Shows the NTP seconds when the Diffie-Hellman agreement parameter +file was created.
-
hostname host/
-
Specifies the name of the host.
+
publickey filestamp/
+
Shows the NTP seconds when the RSA public/private key files were +created.
-
revoketime host/
-
Specifies the last time the public and private values used in the agreement algorithm were refreshed.
+
refresh timestamp/
+
Shows the NTP seconds when the public cryptographic values were +refreshed and signed.
-

Additional peer variables not defined in the NTP specification -RFC-1305 are used by the autokey public key support. They include the following: +

Additional peer variables used by the NTP Version 4 Autokey +support include the following:
-
pcookie hex/
-
Specifies the peer cookie used in the key agreement algorithm.
-
hcookie hex/
-
Specifies the host cookie used in the key agreement algorithm.
+
Shows the host cookie used in the key agreement algorithm.
+ +
initkey key/
+
Shows the initial key used by the key list generator in the autokey +protocol.
initsequence index/
-
Specifies the initial index used by the key list generator in the autokey protocol.
+
Shows the initial index used by the key list generator in the +autokey protocol.
-
initkey key/
-
Specifies the initial key used by the key list generator in the autokey protocol.
+
pcookie hex/
+
Specifies the peer cookie used in the key agreement algorithm.
timestamp time/
-
Specifies the NTP time (seconds) when the last autokey message was recieved.
- +
Shows the NTP seconds when the last autokey key list was generated +and signed.
-
pstatus assocID
-
Sends a read status request to the server for the given association. The names and values of the peer variables returned will be printed. Note that the status word from the header is displayed preceding the variables, both in hexidecimal and in pidgeon English.
+
Sends a read status request to the server for the given association. +The names and values of the peer variables returned will be printed. +Note that the status word from the header is displayed preceding the +variables, both in hexidecimal and in pidgeon English.
readlist [ assocID ]

rl [ assocID ] -
Requests that the values of the variables in the internal variable list be returned by the server. If the association ID is omitted or is 0 the variables are assumed to be system variables. Otherwise they are treated as peer variables. If the internal variable list is empty a request is sent without data, which should induce the remote server to return a default display.
- -
readvar assocID variable_name [ = value ] [ ...]
-
rv assocID [ variable_name [ = value ] [ ...] -
Requests that the values of the specified variables be returned by the server by sending a read variables request. If the association ID is omitted or is given as zero the variables are system variables, otherwise they are peer variables and the values returned will be those of the corresponding peer. Omitting the variable list will send a request with no data which should induce the server to return a default display.
- -
writevar assocID variable_name [ = value [ ...]
-
Like the readvar request, except the specified variables are written instead of read.
+
Requests that the values of the variables in the internal variable +list be returned by the server. If the association ID is omitted or is 0 +the variables are assumed to be system variables. Otherwise they are +treated as peer variables. If the internal variable list is empty a +request is sent without data, which should induce the remote server to +return a default display.
+ +
readvar assocID variable_name [ = value ] [ +...]
+
rv assocID [ variable_name [ = value ] [ +...] +
Requests that the values of the specified variables be returned by +the server by sending a read variables request. If the association ID is +omitted or is given as zero the variables are system variables, +otherwise they are peer variables and the values returned will be those +of the corresponding peer. Omitting the variable list will send a +request with no data which should induce the server to return a default +display.
+ +
writevar assocID variable_name [ = value [ +...]
+
Like the readvar request, except the specified variables are written +instead of read.
writelist [ assocID ]
-
Like the readlist request, except the internal list variables are written instead of read.
+
Like the readlist request, except the internal list variables are +written instead of read.

Bugs

-The peers command is non-atomic and may occasionally result in spurious +

The peers command is non-atomic and may occasionally result in +spurious error messages about invalid associations occurring and terminating the -command. The timeout time is a fixed constant, which means you wait a long time for timeouts since it assumes sort of a worst case. The program should improve the timeout estimate as it sends queries to a particular host, but doesn't. +command. The timeout time is a fixed constant, which means you wait a +long time for timeouts since it assumes sort of a worst case. The +program should improve the timeout estimate as it sends queries to a +particular host, but doesn't.

David L. Mills <mills@udel.edu>