From: Harlan Stenn Date: Tue, 13 May 2008 09:18:04 +0000 (-0400) Subject: Changes from Dave Mills (some backward-incompatible changes) X-Git-Tag: NTP_4_2_5P114~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=475f796e8ffe6266bc075744601c62a89209f32d;p=thirdparty%2Fntp.git Changes from Dave Mills (some backward-incompatible changes) bk: 48295cccFAuJBiCrIo1fcuawau6kOQ --- diff --git a/ChangeLog b/ChangeLog index 202e3b914..9d8b985c5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,74 @@ +* Updates and cleanup from Dave Mills: + I've now spent eleven months of a sabbatical year - 7 days a week, 6-10 + hours most days - working on NTP. I have carefully reviewed every major + algorithm, examined its original design and evolution from that design. + I've trimmed off dead code and briar patches and did zillions of tests + contrived to expose evil vulnerabilities. The development article is in + rather good shape and should be ready for prime time. + + 1. The protostats statistics files have been very useful in exposing + little twitches and turns when something hiccups, like a broken PPS + signal. Most of what used to be syslog messages are now repackaged as + protostats messages with optional syslog as well. These can also be sent + as traps which might be handy to tiggle a beeper or celltext. These, the + sysstats files and cryptostats files reveal the ambient health of a busy + server, monitor traffic and error counts and spot crypto attacks. + + 2. Close inspection of the clock discipline behavior at long poll + intervals (36 h) showed it not doing as well as it should. I redesigned + the FLL loop to improve nominal accuracy from several tens of + milliseconds to something less than ten milliseconds. + + 3. Autokey (again). The enhanced error checking was becoming a major + pain. I found a way to toss out gobs of ugly fat code and replace the + function with a much simpler and more comprehensive scheme. It resists + bait-and-switch attacks and quickly detect cases when the protocol is + not correctly synchronized. + + 4. The interface code for the kernel PPS signal was not in sync with the + kernel code itself. Some error checks were duplicated and some + ineffective. I found none of the PPS-capable drivers, including the atom + driver, do anything when the prefer peer fails; the kernel PPS signal + remains in control. The atom driver now disables the kernel PPS when the + prefer peer comes bum. This is important when the prefer peer is not a + reference clock but a remote NTP server. + + 5. The flake restrict bit turned out to be really interesting, + especially with symmtric modes and of those especially those using + Autokey. Small changes in the recovery procedures when packets are lost + now avoid almost all scenarios which previously required protocol resets. + + 6. I've always been a little uncomfortable when using the clock filter + with long poll intervals because the samples become less and less + correlated as the sample age exceeds the Allan intercept. Various + schemes have been used over the years to cope with this fact. The latest + one and the one that works the best is to use a modified sort metric + where the delay is used when the age of the sample is less than the + intercept and the sum of delay and dispersion above that. The net result + is that, at small poll intervals the algorithm operates as a minimum + filter, while at larger poll intervals it morphs to FIFO. Left + unmodified, a sample could be used when twelve days old. This along with + the FLL modifications has made a dramatic improvement at large poll + intervals. + +- [Backward Incompatible] The 'state' variable is no longer reported or + available via ntpq output. The following system status bit names + have been changed: + - sync_alarm -> leap_alarm + - sync_atomic -> sync_pps + - sync_lf_clock -> sync_lf_radio + - sync_hf_clock -> sync_hf_radio + - sync_uhf_clock -> sync_uhf_radio + - sync_local_proto -> sync_local + - sync_udp/time -> sync_other + Other names have been changed as well. See the change history for + libntp/statestr.c for more details. + Other backward-incompatible changes in ntpq include: + - assID -> associd + - rootdispersion -> rootdisp + - pkt_head -> pkt_neader + See the change history for other details. + * Updates and cleanup from Dave Mills. * [Bug 995] Remove spurious ; from ntp-keygen.c. * More cleanup and changes from Dave Mills. diff --git a/html/accopt.html b/html/accopt.html index 62caf3ef6..99fdb0acc 100644 --- a/html/accopt.html +++ b/html/accopt.html @@ -13,53 +13,61 @@

Access Control Options

giffrom Pogo, Walt Kelly

The skunk watches for intruders and sprays.

-

Last update: 15:56 UTC Wednesday, January 02, 2008

+

Last update: 18:08 UTC Sunday, May 04, 2008


Related Links

+

Table of Contents

Access Control Support

- The ntpd daemon implements a general purpose address/mask based restriction list. The list contains address/match entries sorted first by increasing address values and and then by increasing mask values. A match occurs when the bitwise AND of the mask and the packet source address is equal to the bitwise AND of the mask and address in the list. The list is searched in order with the last match found defining the restriction flags associated with the entry. -

The restriction facility was implemented in conformance with the access policies for the original NSFnet backbone time servers. Later the facility was expanded to deflect cryptographic and clogging attacks. While this facility may be useful for keeping unwanted or broken or malicious clients from congesting innocent servers, it should not be considered an alternative to the NTP authentication facilities. Source address based restrictions are easily circumvented by a determined cracker.

-

Clients can be denied service because they are explicitly included in the restrict list created by the restrict command or implicitly as the result of cryptographic or rate limit violations. Cryptographic violations include certificate or identity verification failure; rate limit violations generally result from defective NTP implementations that send packets at abusive rates. Some violations cause denied service only for the offending packet, others cause denied service for a timed period and others cause the denied service for an indefinate period. When a client or network is denied access for an indefinate period, the only way at present to remove the restrictions is by restarting the server.

-

The Kiss-of-Death Packet

-

Ordinarily, packets denied service are simply dropped with no further action except incrementing statistics counters. Sometimes a more proactive response is needed, such as a server message that explicitly requests the client to stop sending and leave a message for the system operator. A special packet format has been created for this purpose called the "kiss-o'-death" (KoD) packet. KoD packets have the leap bits set unsynchronized and stratum set to zero and the reference identifier field set to a four-byte ASCII code. If the noserve or notrust flag of the matching restrict list entry is set, the code is "DENY"; if the limited flag is set and the rate limit is exceeded, the code is "RATE". Finally, if a cryptographic violation occurs, the code is "CRYP".

-

A client receiving a KoD performs a set of sanity checks to minimize security exposure, then updates the stratum and reference identifier peer variables, sets the access denied (TEST4) bit in the peer flash variable and sends a message to the log. As long as the TEST4 bit is set, the client will send no further packets to the server. The only way at present to recover from this condition is to restart the protocol at both the client and server. This happens automatically at the client when the association times out. It will happen at the server only if the server operator cooperates.

+ The ntpd daemon implements a general purpose access control list (ACL) containing address/match entries sorted first by increasing address values and and then by increasing mask values. A match occurs when the bitwise AND of the mask and the packet source address is equal to the bitwise AND of the mask and address in the list. The list is searched in order with the last match found defining the restriction flags associated with the entry. +

An example may clarify how it works. Our campus has two class-B networks, 128.4 for the ECE and CIS deparements and 128.175 for the rest of campus. Subnet 128.4.1 homes critical services like class rosters and spread sheets. A suitable ACL might be

+
+restrict default nopeer # deny new association
+restrict 128.175.0.0 255.255.0.0 # allow campus access
+restrict 128.4.0.0 255.255.0.0 none # allow ECE and CIS access
+restrict 128.4.1.0 255.255.255.0 notrust # require auth
+restrict time.nist.gov # allow access
+
+

While this facility may be useful for keeping unwanted, broken or malicious clients from congesting innocent servers, it should not be considered an alternative to the NTP authentication facilities. Source address based restrictions are easily circumvented by a determined cracker.

Access Control Commands

-
discard [ average avg ][ minimum min ] [ monitor prob ] -
Set the parameters of the limited facility which protects the server from client abuse. The average subcommand specifies the minimum average packet spacing, while the minimum subcommand specifies the minimum packet spacing. Packets that violate these minima are discarded and a kiss-o'-death packet returned if enabled. The default minimum average and minimum are 5 and 2, respectively. The monitor subcommand specifies the probability of discard for packets that overflow the rate-control window. -
restrict address [mask mask] [flag][...] -
The address argument expressed in dotted-quad form is the address of a host or network. Alternatively, the address argument can be a valid host DNS name. The mask argument expressed in dotted-quad form defaults to 255.255.255.255, meaning that the address is treated as the address of an individual host. A default entry (address 0.0.0.0, mask 0.0.0.0) is always included and is always the first entry in the list. Note that text string default, with no mask option, may be used to indicate the default entry. -
In the current implementation, flag always restricts 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: +
discard [ average avg ][ minimum min ] [ monitor prob ] +
Set the parameters of the rate control facility which protects the server from client abuse. If the limited flag is present in the ACL, packets that violate these limits are discarded. If in addition the kod restriction is present, a kiss-o'-death packet is returned.
-
ignore +
average avg +
Sspecify the minimum average interpacket spacing (minimum average headway time) in log2 s with default 3.
minimum min +
Specify the minimum interpacket spacing (guard time) in log2 s with default 1.
monitor +
Specify the probability of discard for packets that overflow the rate-control window. This is a performance optimization for servers with aggregate arrivals of 1000 packets per second or more.
+ + +
restrict address [mask mask] [flag][...] +
The address argument expressed in dotted-quad form is the address of a host or network. Alternatively, the address argument can be a valid host DNS name. The mask argument expressed in dotted-quad form defaults to 255.255.255.255, meaning that the address is treated as the address of an individual host. A default entry (address 0.0.0.0, mask 0.0.0.0) is always included and is always the first entry in the list. Note that the text string default, with no mask option, may be used to indicate the default entry. +
In the current implementation, flag always restricts access, i.e., an entry with no flags indicates no restrictions. 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:
+
frac +
Discard received NTP packets with probability 0.1; that is, on average drop one packet in ten. This is for testing and amusement. The name comes from Bob Braden's flakeway, which once did a similar thing for early Internet testing.
ignore
Deny packets of all kinds, including ntpq and ntpdc queries.
kod -
If this flag is set when an access violation occurs, a kiss-o'-death (KoD) packet is sent. KoD packets are rate limited to no more than one per second. If another KoD packet occurs within one second after the last one, the packet is dropped -
limited -
Deny service if the packet spacing violates the lower limits specified in the discard command. A history of clients is kept using the monitoring capability of ntpd. Thus, monitoring is always active as long as there is a restriction entry with the limited flag. -
lowpriotrap +
Send a kiss-o'-death (KoD) packet if the limited flag is present and a packet violates the rate limits established by the discard command. KoD packets are themselves rate limited for each source address separately. Packets that violate the rate limit are discarded.
limited +
Deny time service if the packet violates the rate limits established by the discard command. This does not apply to ntpq and ntpdc queries.
lowpriotrap
Declare traps set by matching hosts to be low priority. The number of traps a server can maintain is limited (the current limit is 3). Traps are usually assigned on a first come, first served basis, with later trap requestors being denied service. This flag modifies the assignment algorithm by allowing low priority traps to be overridden by later requests for normal priority traps.
nomodify
Deny ntpq and ntpdc queries which attempt to modify the state of the server (i.e., run time reconfiguration). Queries which return information are permitted.
noquery -
Deny ntpq and ntpdc queries. Time service is not affected. -
nopeer +
Deny ntpq and ntpq queries. Time service is not affected.
nopeer
Deny packets which would result in mobilizing a new association.  This includes broadcast, symmetric-active and manycast client packets when a configured association does not exist.
noserve
Deny all packets except ntpq and ntpdc queries.
notrap
Decline to provide mode 6 control message trap service to matching hosts. The trap service is a subsystem of the ntpdq control message protocol which is intended for use by remote event logging programs.
notrust -
Deny packets unless the packet is cryptographically authenticated. -
ntpport +
Deny packets that are not cryptographically authenticated.
ntpport +
non-ntpport
This is actually a match algorithm modifier, rather than a restriction flag. Its presence causes the restriction entry to be matched only if the source port in the packet is the standard NTP UDP port (123). Both ntpport and non-ntpport may be specified. The ntpport is considered more specific and is sorted later in the list.
version
Deny packets that do not match the current NTP version. diff --git a/html/authopt.html b/html/authopt.html index a193b2502..25e57e9d9 100644 --- a/html/authopt.html +++ b/html/authopt.html @@ -13,13 +13,14 @@

Authentication Options

giffrom Alice's Adventures in Wonderland, Lewis Carroll

Our resident cryptographer; now you see him, now you don't.

-

Last update: 15:56 UTC Wednesday, January 02, 2008

+

Last update: 02:38 UTC Monday, March 17, 2008


Related Links

+

Table of Contents

-

Authentication Support

+

Introduction

+

This page describes the various cryptographic authentication provisions in NTPv4. Details about the configuration commands and options are given on the Configuration Options page. Details about the cryptographic authentication schemes are given on the Authentication Options page. Details about the automatic server discovery schemes are described on the Automatic Server Discovery Schemes page. Additional information is available in the papers, reports, memoranda and briefings on the NTP Project page.

Authentication support allows the NTP client to verify that servers are in fact known and trusted and not intruders intending accidentally or intentionally to masquerade as a legitimate server. The NTPv3 specification RFC-1305 defines a scheme using the Data Encryption Standard (DES) algorithm, commonly called DES-CBC. Subsequently, this scheme was replaced by the RSA Message Digest 5 (MD5) algorithm, commonly called keyed-MD5. Either algorithm computes a message digest or one-way hash which can be used to verify the client has the same key as the server.

NTPv4 includes the NTPv3 scheme, properly described as symmetric key cryptography and, in addition a new scheme based on public key cryptography and called Autokey. Public key cryptography is generally considered more secure than symmetric key cryptography, since the security is based on private and public values which are generated by each participant and where the private value is never revealed. Autokey uses X.509 public certificates, which can be produced by commercial services, utility programs in the OpenSSL software library or a utility program in the NTP software distribution.

While the algorithms for symmetric key cryptography are included in the NTPv4 software distribution, Autokey cryptography requires the OpenSSL software library to be installed before building the NTP distribution. This library is available from http://www.openssl.org and can be installed using the procedures outlined in the Building and Installing the Distribution page. Once installed, the configure and build process automatically detects the library and links the library routines required.

-

Authentication is configured separately for each association separately using the key or autokey option on the peer, server, broadcast or manycastclient configuration commands, as described in the Server Options page, and the options described on this page. The ntp-keygen page describes the files required for the various authentication schemes. Further details are in the briefings, papers and reports at the NTP project page linked from www.ntp.org.

+

Authentication is configured separately for each association using the key or autokey option of the server command, as described in the Server Options page, and the options described on this page. The ntp-keygen page describes the files required for the various authentication schemes. Further details are in the briefings, papers and reports at the NTP project page linked from www.ntp.org.

Symmetric Key Cryptography

The original RFC-1305 specification allows any one of possibly 65,534 keys (excluding zero), each distinguished by a 32-bit key ID, to authenticate an association. The servers and clients involved must agree on the key and key ID to authenticate NTP packets. If an NTP packet includes a message authentication code (MAC), consisting of a key ID and message digest, it is accepted only if the key ID matches a trusted key and the message digest is verified with this key.

Keys and related information are specified in a keys file, usually called ntp.keys, which must be distributed and stored using secure means beyond the scope of the NTP protocol itself. Besides the keys used for ordinary NTP associations, additional keys can be used as passwords for the ntpq and ntpdc utility programs. Ordinarily, the ntp.keys file is generated by the ntp-keygen program, but it can be constructed using an ordinary text editor.

-

When ntpd is first started, it reads the key file specified by the keys configuration command and installs the keys in the key cache. However, individual keys must be activated with the trustedkey command before use. This allows, for instance, the installation of possibly several batches of keys and then activating a key remotely using ntpdc. The requestkey command selects the key ID used as the password for the ntpdc utility, while the controlkey command selects the key ID used as the password for the ntpq utility.

+

When ntpd is first started, it reads the key file specified by the keys command and installs the keys in the key cache. However, individual keys must be activated with the trustedkey command before use. This allows, for instance, the installation of possibly several batches of keys and then activating a key remotely using ntpdc. The requestkey command selects the key ID used as the password for the ntpdc utility, while the controlkey command selects the key ID used as the password for the ntpq utility.

Public Key Cryptography

-

NTPv4 supports the Autokey security protocol, which is based on public key cryptography. The Autokey Version 2 protocol described on the Autokey Protocol page verifies packet integrity using MD5 message digests and verifies the source using digital signatures and any of several digest/signature schemes. Optional identity schemes described on the Autokey Identity Schemes page are based on cryptographic challenge/response exchanges. Using these schemes provides strong security against replay with or without modification, spoofing, masquerade and most forms of clogging attacks. These schemes are described along with an executive summary, current status, briefing slides and reading list on the Autonomous Authentication page.

+

NTPv4 supports the Autokey security protocol, which is based on public key cryptography. The Autokey Version 2 protocol described on the Autokey Protocol page verifies packet integrity using MD5 message digests and verifies the source using digital signatures and any of several digest/signature schemes. Optional identity schemes described on the Autokey Identity Schemes page are based on cryptographic challenge/response exchanges. These schemes provide strong security against replay with or without message modification, spoofing, masquerade and most forms of clogging attacks. These schemes are described along with an executive summary, current status, briefing slides and reading list on the Autonomous Authentication page.

Autokey authenticates individual packets using cookies bound to the IP source and destination addresses. The cookies must have the same addresses at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers are operated outside firewall perimeters.

+

There are three timeouts associated with the Autokey scheme. The key list timeout, which defaults to about 1.1 h, specifies the interval between generating new key lists. The revoke timeout, which defaults to about 36 h, specifies the interval between generating new private values. The restart timeout, with default about 5 d, specifies the interval between protocol restarts to refresh public values. In general, the behavior when these timeouts expire is not affected by the issues discussed on this page.

NTP Secure Groups

-

NTP secure groups are used to define cryptographic compartments and security hierarchies. All hosts belonging to a secure group have the same group name but different host names. The string specified in the host option of the crypto command is the name of the host and in the name of the host key, sign key and certificate files. The string specified in the ident option of the crypto comand is the group name of all group hosts and in the name of the identity files. The file naming conventions are described on the ntp-keygen page.

-

Each group includes one or more trusted hosts (THs) operating at the root, or lowest stratum in the group. The group name is used in the subject and issuer fields of the TH trusted certificate. The host name is used in these fields for hosts other than THs.

+

NTP secure groups are used to define cryptographic compartments and security hierarchies. All hosts belonging to a secure group have the same group name but different host names. The string specified in the host option of the crypto command is the name of the host and the name of the host key, sign key and certificate files. The string specified in the ident option of the crypto comand is the group name of all group hosts and the name of the identity files. The file naming conventions are described on the ntp-keygen page.

+

Each group includes one or more trusted hosts (THs) operating at the root, or lowest stratum in the group. The group name is used in the subject and issuer fields of the TH trusted certificate. The host name is used in these fields for all other hosts.

All group hosts are configured to provide an unbroken path, called a certificate trail, from each host, possibly via intermediate hosts and ending at a TH. When a host starts up, it recursively retrieves the certificates along the trail in order to verify group membership and avoid masquerade and middleman attacks.

Secure groups can be configured as hierarchies where a TH of one group can be a client of one or more other groups operating at a lower stratum. In one scenario, groups RED and GREEN can be cryptographically distinct, but both be clients of group BLUE operating at a lower stratum. In another scenario, group CYAN can be a client of multiple groups YELLOW and MAGENTA, both operating at a lower stratum. There are many other scenarios, but all must be configured to include only acyclic certificate trails.

Identity Schemes and Cryptotypes

-

All configurations include a public/private host key pair and matching certificate. Absent an identity scheme, this is a Trusted Certificate (TC) scheme. There are three identity schemes, IFF, GQ and MV described on the Identity Schemes page. With these schemes all servers in the group have encrypted server identity keys, while clients have nonencrypted client identity parameters. The client parameters can be obtained from a trusted agent (TA), usually one of the THs of the lower stratum group. Further information on identity schemes is on the Autokey Identity Schemes page.

+

All configurations include a public/private host key pair and matching certificate. Absent an identity scheme, this is a Trusted Certificate (TC) scheme. There are three identity schemes, IFF, GQ and MV described on the Identity Schemes page. With these schemes all servers in the group have encrypted server identity keys, while clients have nonencrypted client identity parameters. The client parameters can be obtained from a trusted agent (TA), usually one of the THs of the lower stratum group. Further information on identity schemes is on the Autokey Identity Schemes page.

A specific combination of authentication and identity schemes is called a cryptotype, which applies to clients and servers separately. A group can be configured using more than one cryptotype combination, although not all combinations are interoperable. Note however that some cryptotype combinations may successfully interoperate with each other, but may not represent good security practice. The server and client cryptotypes are defined by the the following codes.

NONE @@ -115,9 +118,9 @@

* These combinations are not valid if the restriction list includes the notrust option.

Configuration

-

Autokey has an intimidating number of configuration options, most of which are not necessary in typical scenarios. The simplest scenario consists of a secure group with one TH at the lowest stratum. For the simplest identity scheme TC, the TH generates host key and trusted certificate files using the ntp-keygen -T command, while the remaining group hosts use the same command with no options. All hosts use the crypto configuration command with no options. Configuration with passwords is described in the ntp-keygen page

-

When an identity scheme is included, for example IFF, the TH generates host key, trusted certificate and private identity keys files using the ntp-keygen -T -I -i group command, where group is the group name. The remaining group hosts use the same command with no options. All hosts use the crypto ident group configuration command.

-

Hosts with no dependent clients can retrieve public identity parameters from an archive or web page. The ntp-keygen can export these data using the -e option. Hosts with dependent clients other than the TH must retrieve copies of the TH private identity keys using secure means. The ntp-keygen can export these data using the -q option. In either case the data are installed as a file and then renamed using the name given as the first line in the file, but without the filestamp.

+

Autokey has an intimidating number of configuration options, most of which are not necessary in typical scenarios. The simplest scenario consists of an unnamed secure group with one TH at the lowest stratum. For the simplest identity scheme TC, the TH generates host key and trusted certificate files using the ntp-keygen -T command, while the remaining group hosts use the same command with no options to generate the host key and public certificate files. All hosts use the crypto configuration command with no options. Configuration with passwords is described in the ntp-keygen page

+

When an identity scheme is included, for example IFF, the TH generates host key, trusted certificate and private server identity files using the ntp-keygen -T -I -i group command, where group is the group name. The reemaining group hosts use the same command as above. The client identity files are obtained separately. All hosts use the crypto ident group configuration command.

+

Hosts with no dependent clients can retrieve client files from an archive or web page. The ntp-keygen can export these data using the -e option. Hosts with dependent clients other than the TH must retrieve copies of the server files using secure means. The ntp-keygen can export these data using the -q option. In either case the data are installed as a file and then renamed using the name given as the first line in the file, but without the filestamp.

Examples

Consider a scenario involving three secure groups RED, GREEN and BLUE. RED and BLUE are typical of national laboratories providing certified time to the Internet at large. TH mort of RED and TH macabre of BLUE run NTP symmetric mode with each other for monitoring or backup. GREEN is typical of a large university providing certified time to the campus community. TH howland of GREEN is a client of both RED and BLUE. BLUE uses the IFF scheme, while both RED and GREEN use the GQ scheme, but with different keys.

BLUE TH macabre uses configuration commands

@@ -137,18 +140,29 @@

crypto pw yyy ident green
server mort autokey
server macabre autokey

-

where yyy is the password for mort files. It generates GREEN files using the commands

+

where yyy is the password for howland files. It generates GREEN files using the commands

ntp-keygen -p yyy -T -G -i green
ntp-keygen -p yyy -e >ntpkey_gqpar_green
- ntp-keygen -p yyy -v zzz >zzz_ntpkey_gqkey_green

+ ntp-keygen -p yyy -q zzz >zzz_ntpkey_gqkey_green

The first two lines serve the same purpose as the preceeding examples. The third line generats a copy of the private GREEN server file for use on another server in the same group, but encrypted with the zzz pasword.

-

Each TH in a group acting as a client of another group retrieves the public client file for that group from a public archive or web page using nonsecure means. In addition, each server in a group retrieves the private server file from the TH of that group, but it is encrypted and so can be sent using nonsecured means. The files are installed in the keys directory with name taken from the first line in the file, but without the filestamp

+

A client of GREEN, for example, uses the configuration commands

+

crypto pw abc ident green
+ server howland autokey

+

where abc is the password for its files. It generates files using the command

+

ntp-keygen -p abc

+

The client retrieves the client file for that group from a public archive or web page using nonsecure means. In addition, each server in a group retrieves the private server file from the TH of that group, but it is encrypted and so can be sent using nonsecured means. The files are installed in the keys directory with name taken from the first line in the file, but without the filestamp.

+

In another example mort and macabre are operated as broadcast servers and howland as a broadcast client. Replace the server configuration command for both mort and macabre with the two commands

+

broadcast ipaddr autokey
+ broadcastclient

+

where ipaddr is the broadast address, and replace the two server commands for howland with the single command

+

broadcastclient

+

Note that if servers of different groups, in this case RED and BLUE, share the same broadcast media, each server must have client files for all groups other than its own, while each client must have client files for all groups.

Authentication Commands

-
autokey [logsec] -
Specifies the interval between regenerations of the session key list used with the Autokey protocol. Note that the size of the key list for 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 ID to use with the ntpq utility, which uses the standard protocol defined in RFC-1305. The key argument is the key ID for a trusted key, where the value can be in the range 1 to 65,534, inclusive.
crypto [randfile file] [host name] [ident name] [pw password] +
autokey [logsec] +
Specifies the interval between regenerations of the session key list used with the Autokey protocol, as a power of 2 in seconds. Note that the size of the key list for each association depends on this interval and the current poll interval. The default interval is 12 (about 1.1 h). 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 ID to use with the ntpq utility, which uses the standard protocol defined in RFC-1305. The key argument is the key ID for a trusted key, where the value can be in the range 1 to 65,534, inclusive. +
crypto [randfile file] [host name] [ident name] [pw password]
This command requires the OpenSSL library. It activates public key cryptography and loads the required host key and public certificat. If one or more files are left unspecified, the default names are used as described below. Unless the complete path and name of the file are specified, the location of a file is relative to the keys directory specified in the keysdir configuration command or default /usr/local/etc. Following are the options.
host name @@ -159,13 +173,13 @@
randfile file
Specifies the location of the random seed file used by the OpenSSL library. The defaults are described on the ntp-keygen page.
-
keys keyfile +
keys keyfile
Specifies the complete path to the MD5 key file containing the keys and key IDs used by ntpd, ntpq and ntpdc when operating with symmetric key cryptography. This is the same operation as the -k command line option. -
keysdir path +
keysdir path
This command specifies the default directory path for cryptographic keys, parameters and certificates. The default is /usr/local/etc/. -
requestkey key -
Specifies the key ID to use with the ntpdc utility program, which uses a proprietary protocol specific to this implementation of ntpd. The key argument is a key ID for the trusted key, where the value can be in the range 1 to 65,534, inclusive.
revoke [logsec] -
Specifies the interval between re-randomization of certain cryptographic values used by the Autokey scheme, as a power of 2 in seconds. These values need to be updated frequently in order to deflect brute-force attacks on the algorithms; however, updating some values is a relatively expensive operation. The default interval is 16 (65,536 s or about 18 hours). For poll intervals above the specified interval, the values will be updated for every message sent.
trustedkey key [...] +
requestkey key +
Specifies the key ID to use with the ntpdc utility program, which uses a proprietary protocol specific to this implementation of ntpd. The key argument is a key ID for the trusted key, where the value can be in the range 1 to 65,534, inclusive.
revoke [logsec] +
Specifies the interval between re-randomization of certain cryptographic values used by the Autokey scheme, as a power of 2 in seconds. These values need to be updated frequently in order to deflect brute-force attacks on the algorithms; however, updating some values is a relatively expensive operation. The default interval is 17 (about 36 h). For poll intervals above the specified interval, the values will be updated for every message sent.
trustedkey key [...]
Specifies the key ID which are trusted for the purposes of authenticating peers with symmetric key cryptography, as well as keys used by the ntpq and ntpdc programs. The authentication procedures require that both the local and remote servers share the same key and key ID for this purpose, although different keys can be used with different servers.

Error Codes

Errors can occur due to mismatched configurations, unexpected restarts, expired certificates and unfriendly people. In most cases the protocol state machine recovers automatically by retransmission, timeout and restart, where necessary. Some errors are due to mismatched keys, digest schemes or identity schemes and must be corrected by installing the correct media and/or correcting the configuration file. One of the most common errors is expired certificates, which must be regenerated and signed at least once per year using the ntp-keygen program.

diff --git a/html/bugs.html b/html/bugs.html index ac7e3e224..8251590c5 100644 --- a/html/bugs.html +++ b/html/bugs.html @@ -13,14 +13,14 @@

NTP Bug Reporting Procedures

giffrom Alice's Adventures in Wonderland, Lewis Carroll

The rabbit toots to make sure you read this.

-

Last update: 20:52 UTC Saturday, February 02, 2008

+

Last update: 04:05 UTC Sunday, March 02, 2008

.

Security Bug Reporting Procedures

If you find or suspect a security related program bug in this distribution, please send a report to security@ntp.org. Please do not contact developers directly.

Non-Security Bug Reporting Procedures

If you find or suspect a non-security related program bug in this distribution, please send a report to the NTP Public Service Project Bug Tracking System (Bugzilla) at http://bugs.ntp.org/. Bugs reported this way are immediately forwarded to the developers. Please do not contact the developers directly.

-

If you find or suspect an error in the program documention pages, please send a report directly to the editor David Mills at mills@udel.edu. The master documentation pages are not controlled by the bug tracking system. You are invited to contribute new or revised pages in similar style and DOS format.

+

If you find or suspect an error in the program documention pages, please send a report directly to the editor David Mills at mills@udel.edu. The master documentation pages are not controlled by the bug tracking system. You are invited to contribute new or revised pages in similar style and format.

If you wish to send a report via electronic mail, please remember that your report will be held until one of our volunteers enters it in Bugzilla. The email address for these reports is bugs@ntp.org. You will need to register at http://bugs.ntp.org/ so that you may participate directly in any e-mail discussion regarding your report.

diff --git a/html/build.html b/html/build.html index 4ecf8de28..d0f1fe31f 100644 --- a/html/build.html +++ b/html/build.html @@ -13,7 +13,7 @@

Building and Installing the Distribution

giffrom Pogo, Walt Kelly

For putting out compiler fires.

-

Last update: 21:11 UTC Saturday, January 19, 2008

+

Last update: 16:45 UTC Sunday, March 02, 2008


Related Links

@@ -25,21 +25,20 @@
  • Configuration
  • If You Have Problems
  • Additional make Commands -

    Building and Installing the Distribution

    -

    It is not possible in a software distribution such as this to support every individual computer and operating system with a common executable, even with the same system but different versions. Therefore, it is necessary to configure, build and install for each system and version. In almost all cases, these procedures are completely automatic, The user types ./configure, make and install in that order and the autoconfigure system does the rest. There are some exceptions, as noted below and on the Hints and Kinks pages.

    -

    If available, the OpenSSL library from http://www.openssl.org is used to support public key cryptography. The library must be built and installed prior to building NTPv4. The procedures for doing that are included in the OpenSSL documentation. The library is found during the normal NTPv4 configure phase and the interface routines compiled automatically. Only the libcrypto.a library file and openssl header files are needed. If the library is not available or disabled, this step is not required.

    -

    The Configuration Options page describes a number of options that determine whether debug support is included, whether and which reference clock drivers are included and the locations of the executables and library files, if not the default. By default debugging options and all reference clock drivers are included.

    +

    It is not possible in a software distribution such as this to support every individual computer and operating system with a common executable, even with the same system but different versions and options. Therefore, it is necessary to configure, build and install for each system and version. In almost all cases, these procedures are completely automatic, The user types ./configure, make and install in that order and the autoconfigure system does the rest. There are some exceptions, as noted below and on the Hints and Kinks pages.

    +

    If available, the OpenSSL library from http://www.openssl.org is used to support public key cryptography. The library must be built and installed prior to building NTP. The procedures for doing that are included in the OpenSSL documentation. The library is found during the normal NTP configure phase and the interface routines compiled automatically. Only the libcrypto.a library file and openssl header files are needed. If the library is not available or disabled, this step is not required.

    +

    The Build Options page describes a number of options that determine whether debug support is included, whether and which reference clock drivers are included and the locations of the executables and library files, if not the default. By default debugging options and all reference clock drivers are included.

    Building and Installing for Unix

    -

    This distribution uses common compilers and tools that come with most Unix distributions. Not all of these tools exist in the standard distribution of modern Unix versions (compilers are likely to be an add-on product). If this is the case, consider using the GNU tools and gcc compiler included as freeware in some products. For a successful build, all of these tools should be accessible via the current path.

    -

    The first thing to do is uncompress the distribution and extract the source tree. In the distribution base directory use the ./configure command to perform an automatic configuration procedure. This command inspects the hardware and software environment and configures the build process accordingly. Use the make command to compile and link the distribution and the install command to install the executables by default in /usr/local/bin.

    -

    If your site supports multiple architectures and uses NFS to share files, you can use a single source tree to build executables for multiple architectures. While running on a particular architecture, change to the base directory and create a subdirectory using a command like mkdir A.machine which will create an architecture-specific directory, then change to this directory and mumble ../configure. The remaining steps are the same whether building in the base directory or in the subdirectory.

    +

    This distribution uses common compilers and tools that come with most Unix distributions. Not all of these tools exist in the standard distribution of modern Unix versions (compilers are likely to be an add-on product). If this is the case, consider using the GNU tools and gcc compiler included as freeware in some systems. For a successful build, all of these tools should be accessible via the current path.

    +

    The first thing to do is uncompress the distribution and extract the source tree. In the distribution base directory use the ./configure command to perform an automatic configuration procedure. This command inspects the hardware and software environment and configures the build process accordingly. Use the make command to compile and link the distribution and the install command to install the executables by default in /usr/local/bin.

    +

    If your site supports multiple architectures and uses NFS to share files, you can use a single source tree to build executables for multiple architectures. While running on a particular architecture, change to the base directory and create a subdirectory using a command like mkdir A.machine, which will create an architecture-specific directory, then change to this directory and mumble ../configure. The remaining steps are the same whether building in the base directory or in the subdirectory.

    Building and Installing for Windows

    -

    NTP supports Windows Vista, XP, NT4 and 2000 systems. See hints/winnt.htm for directions to compile the sources and install the executables. A precompiled executable is available.

    +

    NTP supports Windows Vista, XP, NT4 and 2000 systems. See the NTP 4.x for Windows NT page for directions to compile the sources and install the executables. A precompiled executable is available.

    Configuration

    -

    You are now ready to configure the daemon. You will need to create a NTP configuration file by default in n/etc/ntp.conf. Newbies should see the Quick Start page for orientation. Seasoned veterans can start with the ntpd - Network Time Protocol (NTP) daemon page and move on to the specific configuration option pages from there.

    +

    You are now ready to configure the daemon. You will need to create a NTP configuration file by default in /etc/ntp.conf. Newbies should see the Quick Start page for orientation. Seasoned veterans can start with the ntpd - Network Time Protocol (NTP) daemon page and move on to the specific configuration option pages from there.

    If You Have Problems

    If you have problems with your hardware and software environment (e.g. operating system-specific issues), browse the Hints and Kinks pages. For other problems a tutorial on debugging technique is in the NTP Debugging Technique page. A list of important system log messages is on the ntpd System Log Messages page.

    The first line of general assistance is the NTP web site www.ntp.org and the helpful documents resident there. Requests for assistance of a general nature and of interest to other timekeepers should be sent to the NTP newsgroup comp.protocols.time.ntp.

    diff --git a/html/clockopt.html b/html/clockopt.html index e18d35cde..475082d9f 100644 --- a/html/clockopt.html +++ b/html/clockopt.html @@ -11,13 +11,13 @@

    Reference Clock Options

    - gif -

    See the radios, all in a row.

    -

    Last update: 16:01 UTC Wednesday, January 02, 2008

    + gifMaster Time Facility at the UDel Internet Research Laboratory +

    Last update: 16:09 UTC Sunday, March 02, 2008


    Related Links

    +

    Table of Contents

    • Reference Clock Support @@ -33,7 +33,7 @@

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

      Reference Clock Commands

      -
      server 127.127.t.u [prefer] [mode int] [minpoll int] [maxpoll int] +
      server 127.127.t.u [prefer] [mode int] [minpoll int] [maxpoll int]
      This command can be used to configure reference clocks in special ways. The options are interpreted as follows:
      prefer @@ -44,7 +44,7 @@
      maxpoll int
      These options specify the minimum and maximum polling interval for reference clock messages in seconds, interpreted as dual logarithms (2 ^ x). For most directly connected reference clocks, both minpoll and maxpoll default to 6 (2^16 = 64 s). For modem reference clocks, minpoll defaults to 10 (2^10 = 1024 s = 17.1 m) and maxpoll defaults to 14 (2^14 = 16384 s = 4.5 h). The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
      -
      fudge 127.127.t.u [time1 sec] [time2 sec] [stratum int] [refid string] [mode int] [flag1 0|1] [flag2 0|1] [flag3 0|1] [flag4 0|1] +
      fudge 127.127.t.u [time1 sec] [time2 sec] [stratum int] [refid string] [mode int] [flag1 0|1] [flag2 0|1] [flag3 0|1] [flag4 0|1]
      This command can be used to configure reference clocks in special ways. It must immediately follow the server command which configures the driver. Note that the same capability is possible at run time using the ntpdc program. The options are interpreted as follows:
      time1 sec diff --git a/html/comdex.html b/html/comdex.html new file mode 100644 index 000000000..e18984905 --- /dev/null +++ b/html/comdex.html @@ -0,0 +1,30 @@ + + + + + + + + Command Index + + + + +

      Command Index

      + giffrom Alice's Adventures in Wonderland, Lewis Carrol +

      The Mad Hatter says "Bring it on".

      +

      Last update: 15:17 UTC Sunday, March 02, 2008

      +
      +

      Related Links

      + + + + + + +
      +
      + + + + \ No newline at end of file diff --git a/html/config.html b/html/config.html index 9e50d8050..0891d2340 100644 --- a/html/config.html +++ b/html/config.html @@ -5,19 +5,19 @@ - Configuration Options + Build Options -

      Configuration Options

      +

      Build Options

      giffrom Pogo, Walt Kelly

      Gnu autoconfigure tools are in the backpack.

      -

      Last update: 03:07 AM UTC Monday, October 13, 2003

      +

      Last update: 04:01 UTC Sunday, March 02, 2008


      Table of Contents

      -

      Basic Configuration Options - the configure utility

      +

      Basic Build Options - the configure Utility

      The following options are for compiling and installing a working version of the NTP distribution. In most cases, the build process is completely automatic. In some cases where memory space is at a premium, or the binaries are to be installed in a different place, it is possible to tailor the configuration to remove such features as reference clock driver support, debugging support, and so forth.

      Configuration options are specified as arguments to the configure script. Following is a summary of the current options, as of the 4.0.99m version:

      Usage: configure [options] [host]
      diff --git a/html/confopt.html b/html/confopt.html index 847f9008c..437e96865 100644 --- a/html/confopt.html +++ b/html/confopt.html @@ -13,10 +13,11 @@

      Server Options

      giffrom Pogo, Walt Kelly

      The chicken is getting configuration advice.

      -

      Last update: 00:57 UTC Saturday, November 24, 2007

      +

      Last update: 02:18 UTC Sunday, March 02, 2008


      Related Links

      +

      Table of Contents

      • Configuration Commands @@ -30,7 +31,7 @@

        If the Basic Socket Interface Extensions for IPv6 (RFC-2553) is detected, support for the IPv6 address family is generated in addition to the default IPv4 address family. IPv6 addresses can be identified by the presence of colons ":" in the address field. IPv6 addresses can be used almost everywhere where IPv4 addresses can be used, with the exception of reference clock addresses, which are always IPv4. Note that in contexts where a host name is expected, a -4 qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a -6 qualifier forces DNS resolution to the IPv6 namespace.

        Configuration Commands

        -
        server address [options ...]
        +
        server address [options ...]
        peer address [options ...]
        broadcast address [options ...]
        manycastclient address [options ...]
        @@ -52,7 +53,6 @@
        iburst
        When the server is unreachable, send a burst of eight packets instead of the usual one. The packet spacing is normally 2 s; however, the spacing between the first and second packets can be changed with the calldelay command to allow additional time for a modem or ISDN call to complete. This option is valid only with the server command and type s addresses. It is a recommended option with this command.
        key key
        Send and receive packets authenticated by the symmetric key scheme described in the Authentication Options page. This option is valid only with server and peer commands and type s addresses. The key specifies the key identifier with values from 1 to 65534, inclusive. This option is incompatible with the autokey option. -
        minpoll minpoll
        maxpoll maxpoll
        These options specify the minimum and maximum poll intervals for NTP messages, in seconds as a power of two. The maximum poll interval defaults to 10 (1024 s), but can be increased by the maxpoll option to an upper limit of 17 (36 h). The minimum poll interval defaults to 6 (64 s), but can be decreased by the minpoll option to a lower limit of 4 (16 s). These option are valid only with the server and peer commands and type s addresses. @@ -69,10 +69,11 @@
        Allows a server/peer to be configured even if it is not reachable at configuration time. It is assumed that at some point in the future the network environment changes so that this server/peer can be reached. This option is useful to configure servers/peers on mobile systems with intermittent network access (e.g. wlan clients). Note: the current implemenation does not support this option.

        Auxilliary Commands

        -
        broadcastclient [novolley] -
        Enable reception of broadcast server messages to any local interface (type b address). Ordinarily, upon receiving a message for the first time, the broadcast client measures the nominal server propagation delay using a brief client/server exchange, after which it continues in listen-only mode. If the novolley keyword is present, the exchange is not used and the value specified in the broadcastdelay command is used or, if the broadcastdelay command is not used, the default 4.0 ms. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the Authentication Options page. Note that the novolley keyword is incompatible with public key authentication.
        manycastserver address [...] +
        broadcastclient [novolley] +
        Enable reception of broadcast server messages to any local interface (type b address). Ordinarily, upon receiving a message for the first time, the broadcast client measures the nominal server propagation delay using a brief client/server exchange, after which it continues in listen-only mode. If the novolley keyword is present, the exchange is not used and the value specified in the broadcastdelay command is used or, if the broadcastdelay command is not used, the default 4.0 ms. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the Authentication Options page. Note that the novolley keyword is incompatible with public key authentication. +
        manycastserver address [...]
        Enable reception of manycast client messages (type m)to the multicast group address(es) (type m) specified. At least one address is required. Note that, in order to avoid accidental or malicious disruption, both the server and client should operate using symmetric key or public key authentication as described in the Authentication Options page. -
        multicastclient address [...] +
        multicastclient address [...]
        Enable reception of multicast server messages to the multicast group address(es) (type m) specified. Upon receiving a message for the first time, the multicast client measures the nominal server propagation delay using a brief client/server exchange with the server, then enters the broadcast client mode, in which it synchronizes to succeeding multicast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the Authentication Options page.

        Bugs

        diff --git a/html/copyright.html b/html/copyright.html index e5e99ecab..8bd828a61 100644 --- a/html/copyright.html +++ b/html/copyright.html @@ -10,8 +10,7 @@

        Copyright Notice

        - jpg "Clone me," says Dolly sheepishly -

        Last update: 21:32 UTC Monday, December 31, 2007

        + jpg "Clone me," says Dolly sheepishly.

        Last update: 15:19 UTC Sunday, March 02, 2008


        The following copyright notice applies to all files collectively called the Network Time Protocol Version 4 Distribution. Unless specifically declared otherwise in an individual file, this notice applies as if the text was explicitly included in the file.

        diff --git a/html/debug.html b/html/debug.html index 94119c841..d6d959a1a 100644 --- a/html/debug.html +++ b/html/debug.html @@ -13,133 +13,32 @@

        NTP Debugging Techniques

        giffrom Pogo, Walt Kelly

        We make house calls and bring our own bugs.

        -

        Last update: 00:58 UTC Saturday, November 24, 2007

        +

        Last update: 02:37 UTC Monday, March 24, 2008


        More Help

        -

        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 - Network Time Protocol (NTP) daemon page are required. Once started, the daemon will begin sending and receiving messages, as specified in the configuration file.

        Initial Startup

        -

        When started for the first time, the frequency file, usually called ntp.drift, has not yet been created. The daemon switches to a special training routine designed to quickly determine the system clock frequency offset of the particular machine. The routine first measures the current clock offset and sets the clock, then continues for up to twenty minutes before measuring the clock offset, which might involve setting the clock again. The two measurements are used to compute the initial frequency offset and the daemon continues in regular operation, during which the frequency offset is continuously updated. Once each hour the daemon writes the current frequency offset to the ntp.drift file. When restarted after that, the daemon reads the frequency offset from the ntp.drift file and avoids the training routine.

        -

        Note that the daemon requires at least four packet exchanges when first started in any case. This is required in order for the mitigation algorithms to insure valid and accurate measurements and defend against network delay spikes and accidental or malicious errors induced by the servers selected in the configuration file. It normally takes less than four minutes to set the clock when first started, but this can be reduced to less than ten seconds with the iburst configuration option.

        -

        The best way to verify correct operation is using the ntpq - standard NTP query program and ntpdc - special NTP query program utility programs, either on the server itself or from another machine elsewhere in the network. The ntpq program implements the management functions specified in the NTP specification 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 intended for serious debugging. 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 switch. If not present, the daemon detaches from the controlling 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 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 UDP port for NTP (123) in the Unix /etc/services file (or equivalent in some systems). Note that NTP does not use TCP in any form. Also note that NTP requires 123 for both source and destination ports. These facts should be pointed out to firewall administrators.

        -

        Other problems are apparent in the system log, which ordinarily shows the startup banner, some cryptic initialization data and the computed precision value. Error messages at startup and during regular operation are sent to the system log. In real emergencies the daemon will sent a terminal error message to the system log and then cease operation.

        -

        The next most common problem is incorrect DNS names. Check that each DNS name used in the configuration file exists and that the address responds to the Unix ping command. The Unix traceroute or Windows tracert utility can be used to verify a partial or complete path exists. Most problems reported to the NTP newsgroup are not NTP problems, but problems with the network or firewall configuration.

        -

        When first started, the daemon 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 truechimer servers and possible falsetickers, at least four valid messages from at least one server or peer listed in the configuration file is required before the daemon can set the clock. However, if the difference between the client time and server time is greater than the panic threshold, which defaults to 1000 s, the daemon sends a message to the system log and shuts down without setting the clock. It is necessary to set the local clock to within the panic threshold first, either manually by eyeball and wristwatch and the Unix date command, or by the ntpdate or ntpd -q commands. The panic threshold can be changed by the tinker panic command discribed on the Miscellaneous Options page. The panic threshold can be disabled for the first measurement by the -g command line option described on the ntpd - Network Time Protocol (NTP) daemon page.

        -

        If the difference between local time and server time is less than the panic threshold but greater than the step threshold, which defaults to 128 ms, the daemon will perform a step adjustment; otherwise, it will gradually slew the clock to the nominal time. Step adjustments are extremely rare in ordinary operation, usually as the result of reboot or hardware failure. The step threshold can be changed to 300 s using the -x command line option described on the ntpd page. This is usually sufficient to avoid a step after reboot or when the operator has set the system clock to within five minutes by eyeball-and-wristwatch. In extreme cases the step threshold can be changed by the tinker step command discribed on the Miscellaneous Options page. If set to zero, the clock will never be stepped; however, users should understand the implications for doing this in a distributed data network where all processing must be tightly synchronized. See the NTP Timescale and Leap Seconds page for further information. If a step adjustment is made, 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.

        -

        The clock discipline algorithm is designed to avoid large noise spikes that might occur on a congested network or access line. If an offset sample exceeds the step threshold, it is ignored and a timer started. If a later sample is below the step threshold, the counter is reset and operation continues normally. However, if the counter is greater than the stepout interval, which defaults to 900 s, the next sample will step the time as directed. The stepout threshold can be changed by the tinker stepout command discribed on the Miscellaneous Options page.

        -

        If for some reason the hardware clock oscillator frequency error is very large, say over 400 PPM, the time offset when the daemon is started for the first time may increase over time until exceeding the step threshold, which requires a frequency adjustment and another step correction. However, due to provisions that reduce vulnerability to noise spikes, the second correction will not be done until after the stepout threshold. When the frequency error is very large, it may take a number of cycles like this until converging to the nominal frequency correction and writing the ntp.drift file. If the frequency error is over 500 PPM, convergence will never occur and occasional step adjustments will occur indefinitely.

        +

        This page discusses ntpd program monitoring and debugging techniques using the ntpq - standard NTP query program, either on the local server or from a remote machine. In special circumstances the ntpdc - special NTP query program, can be useful, but its use is not covered here. The ntpq program implements the management functions specified in the NTP specification RFC-1305, Appendix A. It is used to read and write the variables defined in the NTP Version 4 specification now navigating the standards process. In addition, the program can be used to send remote configuration commands to the server.

        +

        The ntpd daemon can operate in two modes, depending on the presence of the -d command-line option. Without the option the daemon detaches from the controlling terminal and proceeds autonomously. With one or more -d options the daemon does not detach and generates special trace output useful for debugging. In general, interpretation of this output requires 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.

        +

        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 (or equivalent in some systems). Note that NTP does not use TCP in any form. Also note that NTP requires port 123 for both source and destination ports. These facts should be pointed out to firewall administrators.

        +

        Other problems are apparent in the system log, which ordinarily shows the startup banner, some cryptic initialization data and the computed precision value. Event messages at startup and during regular operation are sent to the optional protostats monitor file, as described on the Event Messages and Status Words page. These and other error messages are sent to the system log, as described on the ntpd System Log Messages page. In real emergencies the daemon will sent a terminal error message to the system log and then cease operation.

        +

        The next most common problem is incorrect DNS names. Check that each DNS name used in the configuration file exists and that the address responds to the Unix ping command. The Unix traceroute or Windows tracert utility can be used to verify a partial or complete path exists. Most problems reported to the NTP newsgroup are not NTP problems, but problems with the network or firewall configuration.

        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 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. IPv4 addresses are shown in dotted quad notation, while IPv6 addresses are shown alarmingly. 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.

        -

        As per the NTP specification RFC-1305, when the stratum is between 0 and 15 for a NTP server, the refid field shows the server DNS name or, if not found, the IP address in dotted-quad. When the stratum is any value for a reference clock, this field shows the identification string assigned to the clock. However, until the client has synchronized to a server, or when the stratum for a NTP server is 0 (appears as 16 in the billboards), the status cannot be determined. As a help in debugging, the refid field is set to a four-character string called the kiss code. The current kiss codes are as as follows.

        -

        Peer Kiss Codes

        -

        ACST

        -
        -
        The association belongs to a anycast server. -
        AUTH -
        Server authentication failed. Please wait while the association is restarted. -
        AUTO -
        Autokey sequence failed. Please wait while the association is restarted. -
        BCST -
        The association belongs to a broadcast server. -
        CRYP -
        Cryptographic authentication or identification failed. The details should be in the system log file or the cryptostats statistics file, if configured. No further messages will be sent to the server. -
        DENY -
        Access denied by remote server. No further messages will be sent to the server. -
        DROP -
        Lost peer in symmetric mode. Please wait while the association is restarted. -
        RSTR -
        Access denied due to local policy. No further messages will be sent to the server. -
        INIT -
        The association has not yet synchronized for the first time. -
        MCST -
        The association belongs to a manycast server. -
        NKEY -
        No key found. Either the key was never installed or is not trusted. -
        RATE -
        Rate exceeded. The server has temporarily denied access because the client exceeded the rate threshold. -
        RMOT -
        Somebody is tinkering with the association from a remote host running ntpdc. Not to worry unless some rascal has stolen your keys. -
        STEP -
        A step change in system time has occurred, but the association has not yet resynchronized. -
        -

        System Kiss Codes

        -
        -
        INIT -
        The system clock has not yet synchronized for the first time. -
        STEP -
        A step change in system time has occurred, but the system clock has not yet resynchronized. -
        -

        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 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 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", signature=md5WithRSAEncryption, flags=0x83f01, 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 NTPv4 on the ntpq page. 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.

        -

        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 12 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 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 discipline algorithm, which functions as a hybrid phase/frequency feedback loop. The behavior of this algorithm is carefully controlled to minimize residual errors due to network jitter and frequency variations 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.

        -

        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", signature=md5WithRSAEncryption,
-flags=0x80011, hostkey=3171372095, refresh=3172016539
-cert="grundoon.udel.edu grundoon.udel.edu 0x3 3233600829"
-cert="whimsy.udel.edu whimsy.udel.edu 0x5 3233682156"
-
        -

        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, signature, flags, hostkey, refresh and cert, which are used for the Autokey public-key cryptography described on the Authentication Options page. The numeric values show the filestamps, in NTP seconds, that the associated media files 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 unless the apparent clock error exceeds the step threshold for a period longer than the stepout threshold, which for most Internet paths is a very rare event. If the event is simply an outlyer due to an occasional network delay spike, the correction is simply discarded; however, if the apparent time error persists for longer than the stepout threshold of about 17 minutes, the local clock is stepped or slewed to the new value as directed. This behavior is designed to resist errors due to severely congested network paths, as well as errors due to confused radio clocks upon the epoch of a leap second.

        +

        Unless using the iburst option, the client normally takes a few minutes to synchronize to a server. If the client time at startup happens to be more thatn 1000 s distant from NTP time, the daemon exits with a message to the system log directing the operator to manually set the time within 1000 s and restart. If the time is less than 1000 s but more than 128 s distant, a step correction occurs and the daemon restarts automatically.

        +

        When started for the first time and a frequency file is not present, the daemon enters a special mode in order to calibrate the frequency. This takes 900 s during which the time is not desciplined. When calibration is complete, the daemon creates the frequency file and enters normal mode to amortize whatever residual offset remains.

        +

        The ntpq commands pe, as and rv are normally sufficient to verify correct operation and assess nominal performace. The pe command displays a list showing the DNS name or IP address for each association along with selected status and statistics variables. The first character in each line is the tally code, which shows which associations are candidates to set the system clock and of these which one is the system peer. The encoding is shown in the source field of the system status word.

        +

        The as command displays a list of associations and association identifiers. Note the condition column, which reflects the tally code. The rv command displays the system variables billboard, including the system status word. The rv assocID command, where assocID is the association ID, displays the peer variables billboard, including the peer status word. Note that, except for explicit calendar dates, times are in milliseconds and frequencies are in parts-per-million (PPM).

        +

        A detailed explanation of the system, peer and clock variables in the billboards is beyond the scope of this page; however, a comprehensive explanation for each one is in the NTPv4 protocol specification. The following observations will be useful in debugging and monitoring.

        +
          +
        1. The server has successfull synchronized to its sources if the leap peer variable has value other than zero. The client has successfully synchronized to the server when the leap system variable has value other than zero. +
        2. The reach peer variable is an 8-bit shift register displayed in octal format. When a valid packet is received, the rightmost bit is lit. When a packet is sent, the register is shifted left one bit with 0 replacing the rightmost bit. If the reach value is nonzero, the server is reachable; otherwise, it is unreachable. Note that, even if all servers become unreachable, the system continues to show valid time to dependent applications. +
        3. A useful indicator of miscellaneous problems is the flash peer variable, which shows the result of 13 sanity tests. It contains the flash status word bits, commonly called flashers, which displays the current errors for the association. These bits should all be zero for a valid server. +
        4. The three peer variables filtdelay, filtoffset and filtdisp show the delay, offset and jitter statistics for each of the last eight measurement rounds. These statistics and their trends are valuable performance indicators for the server, client and the network. For instance, large fluctuations in delay and jitter suggest network congestion. Missing clock filter stages suggest packet losses in the network. +
        5. The synchronization distance, defined as one-half the delay plus the dispersion, represents the maximum error statistic. The jitter represents the expected error statistic. The maximum error and expected error calculated from the peer variables represents the quality metric for the server. The maximum error and expected error calculated from the system variables represents the quality metric for the client. If the root synchronization distance for any server exceeds 1.5 s, called the select threshold, the server is considered invalid.

        Large Frequency Errors

        -

        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 frequency tolerance of computer clock oscillators varies widely, sometimes above 500 PPM. While the daemon can handle frequency errors up to 500 PPM, or 43 seconds per day, values much above 100 PPM reduce the headroom, especially at the lowest poll intervals. To determine the particular oscillator frequency, start ntpd using the noselect option with the server configuration command.

        +

        Record the time of day and offset displayed by the ntpq pe command. Wait for an hour or so and record the time of day and offset. Calculate the frequency as the offset difference divided by the time difference. If the frequency is much above 100 PPM, the tickadj program might be useful to adjust the kernel clock frequency below that value. For systems that do not support this program, this might be one using a command in the system startup file.

        Access Controls

        Provisions are included in ntpd for access controls which deflect unwanted traffic from selected hosts or networks. The controls described on the Access Control Options include detailed packet filter operations based on source address and address mask. Normally, filtered packets are dropped without notice other than to increment tally counters. However, the server can be configured to send a "kiss-o'-death" (KOD) packet to the client either when explicitly configured or when cryptographic authentication fails for some reason. The client association is permanently disabled, the access denied bit (TEST4) is set in the flash variable and a message is sent to the system log.

        The access control provisions include a limit on the packet rate from a host or network. If an incoming packet exceeds the limit, it is dropped and a KOD sent to the source. If this occurs after the client association has synchronized, the association is not disabled, but a message is sent to the system log. See the Access Control Options page for further informatin.

        @@ -159,7 +58,7 @@ cert="whimsy.udel.edu whimsy.udel.edu 0x5 3233682156"
      • 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.
      • Check the system log for ntpd messages about configuration errors, name-lookup failures or initialization problems. Common system log messages are summarized on the ntpd System Log Messages page. Check to be sure that only one copy of ntpd is running.
      • 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. -
      • Check that the remote NTP server is up and running. The usual evidence that it is not is a Connection refused message. +
      • Check that the remote NTP server is up and running. The usual evidence that it is not is a Connection refused message.
      • 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.
      • 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. It could be that the server has disabled access for the client address, in which case the refid field in the ntpq pe billboard will show a kiss code. See earlier on this page for a list of kiss codes and their meaning.
      • 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. diff --git a/html/decode.html b/html/decode.html new file mode 100644 index 000000000..93a59b083 --- /dev/null +++ b/html/decode.html @@ -0,0 +1,681 @@ + + + + + + ntpd System Log Messages + + + +

        Event Messages and Status Words

        + giffrom Alice's Adventures in Wonderland, Lewis Carroll +

        Caterpillar knows all the error codes, which is more than most of us do.

        +

        Last update: 04:18 UTC Tuesday, May 06, 2008

        +
        +

        Related Links

        +

        +

        Table of Contents

        + +
        +

        Introduction

        +

        This page lists the status and event messages and error codes used for status reporting and monitoring. Status words are used to display the current status of the running program. There is one system status word and a peer status word for each association. There is a clock status word for each association that supports a reference clock driver. There is a flash code for each association which shows errors found in the last packet received (pkt) and during protocol processing (peer). These are commonly viewed using the ntpq program.

        +

        Sinificant changes in program state are reported as events. There is one set of system events and a set of peer events for each association. In adition, there is a set of clock events for each association that supports a reference clock driver. Events are normally reported to the protostats file and optionally to the system log. In addition, if the trap facility is configured, traps can be reported to a remote program that can page an administrator.

        +

        This page also includes a description of the error messages produced by the Autokey protocol. These messages are normally sent to the cryptostats file.

        +

        In the following tables the Code Field is the status or event code assigned and the Message Field a short string used for display and event reporting. The Description field contains a longer explanation of the status or event. Some messages include additional information useful for error diagnosis and performance assessment.

        +

        System Status Word

        +

        The system status word consists of four fields LI (0-1), Source (2-7), Count (8-11) and Code (12-15). It is reported in the first line of the ntpd rv display.

        + + + + + + + +
        +
        Leap
        +         		+
        + Source
        +         		+
        + Count
        +         		+
        + Code
        +
        +

        The Leap Field displays the system leap indicator bits coded as follows:

        + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeMessageDescription
        0leap_nonenormal synchronized state
        1leap_add_secinsert second after 23:59:59 of the current day
        2leap_del_secdelete second 23:59:59 of the current day
        3leap_alarmnever synchronized
        +

        The Source Field displays the current synchronization source coded as follows:.

        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeMessageDescription
        0sync_unspecnot yet synchronized
        1sync_ppspulse-per-second signal (Cs, Ru, GPS, etc.)
        2sync_lf_radioVLF/LF radio (WWVB, DCF77, etc.)
        3sync_hf_radioMF/HF radio (WWV, etc.)
        4sync_uhf_radioVHF/UHF radio/satellite (GPS, Galileo, etc.)
        5sync_locallocal timecode (IRIG, LOCAL driver, etc.)
        6sync_ntpNTP
        7sync_otherother (IEEE 1588, openntp, crony, etc.)
        8sync_wristwatcheyeball and wristwatch
        9sync_telephonetelephone modem (ACTS, PTB, etc.)
        +

        The Count Field displays the number of events since the last rv command while the Event Field displays the most recent event message coded as follows:

        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeMessageDescription
        0unspecifiedunspecified
        1freq_not_setfrequency file not available
        2freq_setfrequency set from frequency file
        3spike_detectspike detected
        4freq_modeinitial frequency training mode
        5clock_syncclock synchronized
        6restartprogram restart
        7panic_stopclock error more than 600 s
        8no_system_peerno system peer
        9leap_armedleap second armed from file or Autokey
        10leap_disarmedleap second disarmed
        11leap_eventleap event
        12clock_stepclock stepped
        13kernkernel information message
        +

        Peer Status Word

        +

        The peer status word consists of four fields: Status (0-4, Select (5-7), Count (8-11) and Code (12-15). It is reported in the first line of the ntpd rv associd display.

        + + + + + + + +
        +
        + Status
        +         		+
        Select
        +         		+
        + Count
        +         		+
        + Code
        +
        +

        The Status Field displays the peer status code bits in hexadecimal as follows:

        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeMessageDescription
        08bcstbroadcast association
        10reachhost reachable
        20authenbauthentication enabled
        40authauthentication ok
        80configpersistent association
        The Select Field displays the current selection. status The T Field displays the tally codes beginning the ntpq peers display. The values are coded as follows: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeMessageTDescription
        0sel_rejectdiscarded as not valid (TEST10-TEST13)
        1sel_falsetickxdiscarded by intersection algorithm
        2sel_excess.discarded by table overflow (not used)
        3sel_outlyer-discarded by the cluster algorithm
        4sel_candidate+included by the combine algorithm
        5sel_backup#backup (more than tinker maxclock sources)
        6sel_sys.peer*system peer
        7sel_pps.peeroPPS peer (when the prefer peer is valid)
        +

        The Count Field displays the number of events since the last rv command, while the Event Field displays the most recent event message coded as follows:

        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeMessageDescription
        1mobilizeassociation mobilized
        2demobilizeassociation demobilized
        3unreachableserver unreachable
        4reachableserver reachable
        5restartassociation restart
        6no_replyno server found (ntpdate mode)
        7rate_exceededrate exceeded (kiss code RATE)
        8access_deniedaccess denied (kiss code DENY)
        9leap_armedleap armed from server LI code
        10sys_peernew system peer
        11clockreference clock message (see clock status word)
        +

        Clock Status Word

        +

        The clock status word consists of four fields: Unused (0-7), Count (8-11) and Code (12-15). It is reported in the first line of the ntpd clockvar associd display.

        + + + + + + +
        +
        + Unused
        +         		+
        + Count
        +         		+
        + Code
        +
        +

        The Count Field displays the number of events since the last clockvar command, while the Event Field displays the most recent event message coded as follows:

        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeMessageDescription
        0clk_unspenominal
        1clk_noreplyno reply to poll
        2clk_badformatbad timecode format
        3clk_faulthardware or software fault
        4clk_bad_signalsignal loss
        5clk_bad_datebad date format
        6clk_bad_timebad time format
        +

        When the clock driver sets the code to a new value, a clock_alarm (11) peer event is reported.

        +

        Flash Status Word

        +

        The flash status word is displayed by the ntpq program rv command. It consists of a number of bits coded in hexadecimal as follows:

        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeTagMessageDescription
        0001TEST1pkt_dupduplicate packet
        0002TEST2pkt_bogusbogus packet
        0004TEST3pkt_unsyncprotocol unsynchronized
        0008TEST4pkt_deniedaccess denied
        0010TEST5pkt_authbad authentication
        0020TEST6pkt_stratumbad synch or stratum
        0040TEST7pkt_headerbad header
        0080TEST8pkt_autokeybad autokey
        0100TEST9pkt_cryptobad crypto
        0200TEST10peer_stratumpeer bad synch or stratum
        0400TEST11peer_distpeer distance exceeded
        0800TEST12peer_looppeer synchronization loop
        1000TEST13peer_unreachpeer unreachable
        +

        Kiss Codes

        + Kiss codes are used in kiss-o'-death (koD) packets, billboard displays and log messages. They consist of a string of four zero-padded ASCII charactes. In practice they are informal and tend to change with time and implementation. Some of these codes can appear in the reference identifier field in ntpq billboards. Following is the current list: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeDescription
        ACSTmanycast server
        AUTHauthentication error
        AUTOAutokey sequence error
        BCSTbroadcast server
        CRYPTAutokey protocol error
        DENYaccess denied by server
        INITassociation initialized
        MCSTmulticast server
        RATErate exceeded
        TIMEassociation timeout
        STEPstep time change
        +

        Crypto Messages

        +

        These messages are sent to the cryptostats file when an error is detected in the Autokey protocol.

        + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        CodeMessageDescription
        1bad_formatbad extension field format or length
        2bad_timestampbad timestamp
        3bad_filestampbad filestamp
        4bad_public_keybad or missing public key
        5bad_digestunsupported digest type
        6bad_identityunsupported identity type
        7bad_siglengthbad signature length
        8bad signatureextension field signature not verified
        9cert_not_verifiedcertificate signature not verified
        10cert_expiredhost certificate expired
        11bad_cookiebad or missing cookie
        12bad_leapsecondsbad or misssing leapseconds values
        13cert_missingbad or missing certificate
        14bad_group_keybad or missing group key
        15proto_errorprotocol error
        +
        + +

        + + + \ No newline at end of file diff --git a/html/genkeys.html b/html/genkeys.html index e6659c032..286751038 100644 --- a/html/genkeys.html +++ b/html/genkeys.html @@ -13,7 +13,7 @@

        ntp-keygen - Generate Public and Private Keys Files

        giffrom Alice's Adventures in Wonderland, Lewis Carroll

        Alice holds the key.

        -

        Last update: 20:57 UTC Saturday, December 22, 2007

        +

        Last update: 02:27 UTC Monday, March 03, 2008


        Related Links

        diff --git a/html/hints/winnt.html b/html/hints/winnt.html index dfd883a84..49d9cbc22 100644 --- a/html/hints/winnt.html +++ b/html/hints/winnt.html @@ -12,9 +12,10 @@

        NTP 4.x for Windows NT

        Introduction

        -

        The NTP 4 distribution runs as service on Windows Vista, Windows NT 4.0, Windows 2000, Windows XP, Windows .NET Server 2003. It will NOT run on Windows 95, 98, ME, etc. The binaries work on multi-processor systems. This port has not been tested on the Alpha platform. This release now uses OpenSSL for authentication. IPv6 is not implemented yet for Win32 platforms. A ready-to-run install distribution is available from Meinberg at http://www.meinberg.de/english/sw/ntp.htm

        -

        Authentication Keys

        -

        With this release ntp-keygen is supported. See the ntp keygen documentation for details on how to use ntp-keygen.

        +

        The NTP 4 distribution runs as service on Windows Vista, Windows NT 4.0, Windows 2000, Windows XP, Windows .NET Server 2003. It will NOT run on Windows 95, 98, ME, etc. The binaries work on multi-processor systems. This port has not been tested on the Alpha platform. This release now uses OpenSSL for authentication. IPv6 is not implemented yet for Win32 platforms. A ready-to-run install distribution is available from Meinberg at http://www.meinberg.de/english/sw/ntp.htm.

        +

        Users should note that the stock Windows client sends requests as mode-1 packets, which can have unintended consequences and create a security risk. The client should send requests as mode-3 (client) packets, which conform to the protocol specification. The issues and resolution are described in Microsoft KB 875424. A less desirable alternative that avoids changing registry keys is to use the --with-wintime option when building the executable.

        +

        Authentication Keys

        +

        With this release ntp-keygen is supported. See the ntp keygen documentation for details on how to use ntp-keygen.

        ntpd can now use the generated keys in the same way as on Unix platforms. Please refer to the Authentication Options for details on how to use these.

        NOTE: ntpd and ntp-keygen both use OpenSSL which requires a random character file called .rnd by default. Both of these programs will automatically generate this file if they are not found. The programs will look for an environmental variable called RANDFILE and use that for the name of the random character file if the variable exists. If it does not exist it will look for an environmental variable called HOME and use that directory to search for a file called .rnd in that directory. Finally, if neither RANDFILE nor HOME exists it will look in C:\ for a .rnd file. In each case it will search for and create the file if the environmental variable exists or in the C:\ directory if it doesn't.

        diff --git a/html/index.html b/html/index.html index 23a6b5337..5d64cbd69 100644 --- a/html/index.html +++ b/html/index.html @@ -13,11 +13,12 @@

        The Network Time Protocol (NTP) Distribution

        gifP.T. Bridgeport Bear; from Pogo, Walt Kelly

        Pleased to meet you.

        -

        Last update: 21:11 UTC Saturday, January 19, 2008

        +

        Last update: 16:21 UTC Wednesday, March 12, 2008

        Note: These pages are being updated and may appear a little scruffy for awhile.


        Related Links

        -
          A list of all links is on the Site Map page. +
            +
          • A list of all links is on the Site Map page.

          Table of Contents

            @@ -44,7 +45,7 @@

            The most important factor in providing accurate, reliable time is the selection of modes and servers in the configuration file. A discussion on the available modes is on the Association Management page. The current public server list is maintained at the www.ntp.org web site. In many cases the configuration can be automated using the schemes described on the Automatic Server Discovery Schemes page.

            Features and Options

            This distribution includes a statistics data recording facility which can record performance statistics and events of various types for retrospective analysis. These include time and frequency statistics, significant events and usage statistics described on the Monitoring Options page.

            -

            Some programs included in this distribution use cryptographic algorithms to verify server authenticity. Where local security policy permits relatively weak symmetric key cryptography, the required software is included in this distribution. Where local policy requires stronger public key cryptography, the OpenSSL library available from http://www.openssl.org is required. This library is also used by the Secure Shell facility, so is often already installed. NTP public key cryptography is described on the Authentication Options page.

            +

            Some programs included in this distribution use cryptographic algorithms to verify server authenticity. Where local security policy permits relatively weak symmetric key cryptography, the required software is included in this distribution. Where local policy requires stronger public key cryptography, the OpenSSL library available from http://www.openssl.org is required. This library is also used by the Secure Shell facility, so is often already installed. Additional details are on the Authentication Options page.

            This distribution includes features that can restrict access in various ways as described on the Access Control Options page. This can be used to deny service if not authenticated, deny service requiring persistent resources or deny service altogether.

            This distribution includes a simulation framework in which substantially all the runtime NTP operations and most features can be tested and evaluated. This has been very useful in exploring invitro response to unusal circumstances or over time periods impractical invivo. Details are on the Network Time Protocol (NTP) Simulator page.

            Resolving Problems

            @@ -52,7 +53,7 @@

            The NTP Debugging Techniques and Hints and Kinks pages contain useful information for identifying problems and devising solutions. Additional information on reference clock driver construction and debugging is in the Debugging Hints for Reference Clock Drivers page.

            Users are invited to report bugs and offer suggestions via the NTP Bug Reporting Procedures page.

            Further Information

            -

            The Site Map page contains a list of document collections arranged by topic. The Program Manual Pages collection may be the best place to start, followed by the Configuration Commands and Options collection. A great wealth of additional information is available via the External Links collection, including a book and numerous background papers and briefing presentations.

            +

            The Site Map page contains a list of document collections arranged by topic. The Program Manual Pages collection may be the best place to start, followed by the Configuration Commands and Options collection. The Command Index collection contains a list of all configuration file commands together with a short function description. A great wealth of additional information is available via the External Links collection, including a book and numerous background papers and briefing presentations.

            gif
            diff --git a/html/kern.html b/html/kern.html index 3187d2fa1..a7f4bbd3f 100644 --- a/html/kern.html +++ b/html/kern.html @@ -12,8 +12,8 @@

            Kernel Model for Precision Timekeeping

            gif from Pogo, Walt Kelly

            -

            Alice touched the kernel and it exploded.

            -

            Last update: 19:25 UTC Tuesday, January 01, 2008

            +

            Alice finds the kernel a house of cards.

            +

            Last update: 15:42 UTC Sunday, March 02, 2008


            Related Links

            diff --git a/html/kernpps.html b/html/kernpps.html index 7db03ee9d..43ebcb11c 100644 --- a/html/kernpps.html +++ b/html/kernpps.html @@ -10,6 +10,9 @@

            PPSAPI Interface for Precision Time Signals

            + giffrom NBS Special Publication 432, 1979 (out of print) +

            Last update: 15:40 UTC Sunday, March 02, 2008

            +

            Related Links

            diff --git a/html/manyopt.html b/html/manyopt.html index 31373e7bc..a7d577d04 100644 --- a/html/manyopt.html +++ b/html/manyopt.html @@ -5,15 +5,15 @@ - Automatic Server Discovery Schemes + Automatic Server Discovery -

            Automatic Server Discovery Schemes

            +

            Automatic Server Discovery

            giffrom Alice's Adventures in Wonderland, Lewis Carroll

            Make sure who your friends are.

            -

            Last update: 21:48 UTC Friday, December 28, 2007

            +

            Last update: 01:56 UTC Monday, March 17, 2008


            Related Links

            @@ -26,30 +26,33 @@

            Introduction

            This page describes the automatic server discovery schemes provided in NTPv4. Details about the configuration commands and options are described on the Configuration Options page. Details about the cryptographic authentication schemes are described on the Authentication Options page. Details about the other modes not directly involved in these schemes are described on the Association Management page. Additional information is available in the papers, reports, memoranda and briefings on the NTP Project page.

            -

            There are three automatic server discovery schemes: broadcast/multicast, manycast and server pool described on this page. The broadcast/multicast and manycast schemes utilize the ubiquitous broadcast or one-to-many paradigm native to IPv4 and IPv6. The server pool scheme uses DNS to resolve addresses of multiple volunteer servers scattered throughout the world. All three schemes work in much the same way and might be described as grab-n'-drop. Through one means or another they grab at least the number of potential servers specified by the tos maxclock configuration command, order them from best to worst using the NTP algorithms, then cast off from the end of the list until no more than the number of survivors specified in the tos minclock command remain.

            -

            This process is handled using a set of counters, one for each preemptible association. Once each poll interval the counter is increased by one. It the counter reaches a cutoff value of 10, it is preempted and demobilized. However, the counters for the survivors at the beginning of the list are set to zero.

            -

            Any of the schemes can use a stratum filter to select just those servers with stratum considered useful. This can avoid large numbers of clients ganging up on a small number of low-stratum servers and avoid servers above a certain stratum level. The range of acceptable strata range from the number specified by the tos floor command, inclusive, to the number specified by the tos ceiling command, exclusive. Potential servers operating at the same stratum as the client will be avoided unless the tos cohort command is present.

            -

            -

            Since an intruder can impersonate a broadcast or multicast server and inject false time values, broadcast mode should always be cryptographically authenticated.

            +

            There are three automatic server discovery schemes: broadcast/multicast, manycast and server pool described on this page. The broadcast/multicast and manycast schemes utilize the ubiquitous broadcast or one-to-many paradigm native to IPv4 and IPv6. The server pool scheme uses DNS to resolve addresses of multiple volunteer servers scattered throughout the world. All three schemes work in much the same way and might be described as grab-n'-prune. Through one means or another they grab a number of associations either directly or indirectly from the configuration file, order them from best to worst according to a defined metric, then cast off the associations with the lowest metric until no more than the number specified by the maxclock option of the tos command remain.

            +

            Association Management

            +

            All schemes use a stratum filter to select just those servers with stratum considered useful. This can avoid large numbers of clients ganging up on a small number of low-stratum servers and avoid servers below or above specified stratum levels. By default, servers of all strata are acceptable; however, the tos command can be used to restrict the acceptable range from the floor option, inclusive, to the ceiling option, exclusive. Potential servers operating at the same stratum as the client will be avoided, unless the cohort option is present.

            +

            The pruning process is handled using a set of counters, one for each preemptible association. Once each poll interval the counter is increased by one. If the association survives the selection and clustering algorithms; that is, it is a candidate for synchronization, the counter is reset to zero. If not and the counter reaches a defined threshold and the number of assocations is greater than maxclock, the association becomes a candidate for pruning. The pruning algorithm assigns to each association a metric ranging from the lowest, corresponding to no possibility of synchronization, to the highest, corresponding to a very likely possibility of synchronization. Upon reaching the threshold, an association is demobilized if it has the lowest metric of all associations. Operation continues in this way until the number of remaining associations is not greater than maxclock.

            Following is a summary of each scheme. Note that reference to option applies to the commands described on the Configuration Options page. See that page for applicability and defaults.

            Broadcast/Multicast Scheme

            -

            A broadcast server generates messages continuously at intervals by default 64 s and time-to-live by default 127. These defaults can be overriden by the minpoll and ttl options, respectively. Not all kernels support the ttl command. A broadcast client responds to the first message received by waiting a randomized interval to avoid implosion at the server. It then polls the server in client/server mode and using the iburst opion in order to quickly authenticate the server, set the host clock and calibrate the broadcast message propagation delay. This normally results in a volley of six client/server exchanges at 2-s intervals during which both the synchronization and cryptographic protocols run concurrently.

            -

            Following the volley, the server continues in listen-only mode and sends no further messages. If for some reason the broadcast server does not respond to these messages, the client will cease transmission and continue in listen-only mode with a default propagation delay. The volley can be avoided by using the authdelay configuration command with nonzero argument.

            +

            A broadcast server generates messages continuously at intervals by default 64 s and time-to-live by default 127. These defaults can be overriden by the minpoll and ttl options, respectively. Not all kernels support the ttl option. A broadcast client responds to the first message received by waiting a randomized interval to avoid implosion at the server. It then polls the server in client/server mode using the iburst option in order to quickly authenticate the server, calibrate the propagation delay and set the host clock. This normally results in a volley of six client/server exchanges at 2-s intervals during which both the synchronization and cryptographic protocols run concurrently.

            +

            Following the volley, the server continues in listen-only mode and sends no further messages. If for some reason the broadcast server does not respond to these messages, the client will cease transmission and continue in listen-only mode with a default propagation delay. The volley can be avoided by using the authdelay command with nonzero argument.

            A server is configured in broadcast mode using the broadcast command and specifying the broadcast address of a local interface. If two or more local interfaces are installed with different broadcast addresses, a broadcast command is needed for each address. This provides a way to limit exposure in a firewall, for example. A broadcast client is configured using the broadcastclient command.

            -

            NTP multicast mode can be used to extend the scope of a timekeeping using IPv4 multicast or IPv6 broadcast with defined span. The IANA has assigned IPv4 multicast address 224.0.1.1 and IPv6 address FF05::101 (site local) to NTP, but these addresses should be used only where the multicast span can be reliably constrained to protect neighbor networks. In general, administratively scoped IPv4 group addresses should be used, as described in RFC-2365, or GLOP group addresses, as described in RFC-2770.

            -

            A multicast server is configured using the broadcast command, but specifying a multicast address instead of a broadcast address. A multicast client is configured using the multicastclient command specifying a list of one or more multicast addresses. Note that there is a subtle distinction between the IPv4 and IPv6 address families. The IPv4 broadcast or mulitcast mode is determined by the IPv4 class. For IPv6 the same distinction can be made using the link-local prefix FF02 for each interface and site-local prefix FF05 for all interfacesl.

            -

            In both broadcast and multicast versions the client association is demobilized in case of timeout.

            +

            NTP multicast mode can be used to extend the scope using IPv4 multicast or IPv6 broadcast with defined span. The IANA has assigned IPv4 multicast address 224.0.1.1 and IPv6 address FF05::101 (site local) to NTP, but these addresses should be used only where the multicast span can be reliably constrained to protect neighbor networks. In general, administratively scoped IPv4 group addresses should be used, as described in RFC-2365, or GLOP group addresses, as described in RFC-2770.

            +

            A multicast server is configured using the broadcast command, but specifying a multicast address instead of a broadcast address. A multicast client is configured using the multicastclient command specifying a list of one or more multicast addresses. Note that there is a subtle distinction between the IPv4 and IPv6 address families. The IPv4 broadcast or mulitcast mode is determined by the IPv4 class. For IPv6 the same distinction can be made using the link-local prefix FF02 for each interface and site-local prefix FF05 for all interfaces.

            +

            It is possible and frequently useful to configure a host as both broadcast client and broadcast server. A number of hosts configured this way and sharing a common broadcast address will automatically organize themselves in an optimum configuration based on stratum and synchronization distance.

            +

            Since an intruder can impersonate a broadcast server and inject false time values, broadcast mode should always be cryptographically authenticated. By default, a broadcast association will not be mobilized unless cryptographically authenticated. If necessary, the auth option of the disable command will disable this feature. The feature can be selectively enabled using the notrust option of the restrict command.

            +

            With symmetric key cryptography each broadcast server can use the same or different keys. In one scenario on a broadcast LAN, a set of broadcast clients and servers share the same key along with another set that share a different key. Only the clients with matching key will respond to a server broadcast.

            +

            Public key cryptography can be used with some restrictions. If multiple servers belonging to different secure groups share the same broadcast LAN, the clients on that LAN must have the client keys for all of them. This scenario is illustrated in the example on the Authentication Options page.

            Manycast Scheme

            -

            Manycast is a automatic server discovery and configuration paradigm new to NTPv4. It is intended as a means for a client to troll the nearby network neighborhood to find cooperating servers, validate them using cryptographic means and evaluate their time values with respect to other servers that might be lurking in the vicinity. It uses the grab-n'-drop paradigm with the additional feature that active means are used to grab additional servers should the number of survivors fall below the minclock threshold.

            +

            Manycast is a automatic server discovery and configuration paradigm new to NTPv4. It is intended as a means for a client to troll the nearby network neighborhood to find cooperating servers, validate them using cryptographic means and evaluate their time values with respect to other servers that might be lurking in the vicinity. It uses the grab-n'-drop paradigm with the additional feature that active means are used to grab additional servers should the number of survivors fall below the minclock option of the tos command.

            The manycast paradigm is not the anycast paradigm described in RFC-1546, which is designed to find a single server from a clique of servers providing the same service. The manycast paradigm is designed to find a plurality of redundant servers satisfying defined optimality criteria.

            -

            A manycast clients is configured using the manycastclient configuration command, which is similar to the server configuration command. It sends ordinary client mode messages, but with a broadcast address rather than a unicast address and sends only if less than minclock survivors remain and then only at the minimum feasible rate and minimum feasible time-to-live (TTL) hops. The polling strategy is designed to reduce as much as possible the volume of broadcast messages and the effects of implosion due to near-simultaneous arrival of manycast server messages. There can be as many manycast client associations as different addresses, each one serving as a template for a future unicast client/server association.

            +

            A manycast clients is configured using the manycastclient configuration command, which is similar to the server configuration command. It sends ordinary client mode messages, but with a broadcast address rather than a unicast address and sends only if less than minclock associateons remain and then only at the minimum feasible rate and minimum feasible time-to-live (TTL) hops. The polling strategy is designed to reduce as much as possible the volume of broadcast messages and the effects of implosion due to near-simultaneous arrival of manycast server messages. There can be as many manycast client associations as different addresses, each one serving as a template for a future unicast client/server association.

            A manycast server is configured using the manycastserver command, which listens on the specified broadcast address for manycast client messages. If a manycast server is in scope of the current TTL and is itself synchronized to a valid source and operating at a stratum level equal to or lower than the manycast client, it replies with an ordinary unicast server message.

            The manycast client receiving this message mobilizes a preemptable client association according to the matching manycast client template, but only if cryptographically authenticated and the server stratum is less than or equal to the client stratum.

            -

            It is possible and frequently useful to configure a host as both manycast client and manycast server. A number of hosts configured this way and sharing a common group address will automatically organize themselves in an optimum configuration based on stratum and synchronization distance.

            +

            It is possible and frequently useful to configure a host as both manycast client and manycast server. A number of hosts configured this way and sharing a common multicast group address will automatically organize themselves in an optimum configuration based on stratum and synchronization distance.

            +

            The use of cryptograpic authentication is always a good idea in any server descovery scheme. Both symmetric key and public key cryptography can be used in the same scenarios as described above for the broadast/multicast scheme.

            Server Pool Scheme

            -

            The idea of targeting servers on a random basis to distribute and balance the load is not a new one; however, the NTP pool scheme puts this on steroids. At present, several hundred operators around the globe have volunteered their servers for public access. In general, NTP is a lightweight service and servers used for other purposes don't mind an additional small load. The trick is to randomize over the population and minimize the load on any one server while retaining the advantages of multiple servers with the NTP mitigation algorithms.

            -

            To support this service the DNS for some volunteer servers as been modified to collect a number of the volunteer servers and return a randomized list in response to a query. The client receiving this list modbilizes some or all of them just as in the other discovery schemes and casts off the excess.

            -

            The pool scheme is configured using one or pool commands with the DNS name region.pool.ntp.org, where region is a region of the world, country of the region or state of the country or even the whole world if absent. The pool command can be used more than once; duplicate servers are detected and discarded. In principle, it is possible to use a configuration file containing a single line pool.ntp.org.

            +

            The idea of targeting servers on a random basis to distribute and balance the load is not a new one; however, the NTP pool scheme puts this on steroids. At present, several hundred operators around the globe have volunteered their servers for public access. In general, NTP is a lightweight service and servers used for other purposes don't mind an additional small load. The trick is to randomize over the population and minimize the load on any one server while retaining the advantages of multiple servers using the NTP mitigation algorithms.

            +

            To support this service the DNS for some volunteer servers as been modified to collect a number of other volunteer servers and return a randomized list in response to a DNS query. The client receiving this list modbilizes some or all of them just as in the other discovery schemes and casts off the excess.

            +

            The pool scheme is configured using one or pool commands with the DNS name region.pool.ntp.org, where region is a region of the world, country of the region or state of the country or even the whole world if absent. The pool command can be used more than once; duplicate servers are detected and discarded. In principle, it is possible to use a configuration file containing a single line pool pool.ntp.org.

            diff --git a/html/miscopt.html b/html/miscopt.html index f7436b78a..5e326bbf3 100644 --- a/html/miscopt.html +++ b/html/miscopt.html @@ -12,21 +12,20 @@

            Miscellaneous Options

            giffrom Pogo, Walt Kelly

            We have three, now looking for more.

            -

            Last update: 19:43 UTC Saturday, February 02, 2008

            +

            Last update: 23:15 UTC Wednesday, March 12, 2008


            Related Links

            +
            -
            broadcastdelay seconds -
            The broadcast and multicast modes require a special calibration to determine the network delay between the local and remote servers. Ordinarily, this is done automatically by the initial protocol exchanges between the client and server. 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. - -
            driftfile driftfile { tolerance ] -
            This command specifies the complete path and name of the file used to record the frequency of the local clock oscillator. This is the same operation as the -f command linke option. If the file exists, it is read at startup in order to set the initial frequency and then updated once per hour with the current frequency computed by the daemon. If the file name is specified, but the file itself does not exist, the starts with an initial frequency of zero and creates the file when writing it for the first time. If this command is not given, the daemon will always start with an initial frequency of zero. +
            broadcastdelay seconds +
            The broadcast and multicast modes require a special calibration to determine the network delay between the local and remote servers. Ordinarily, this is done automatically by the initial protocol exchanges between the client and server. 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. +
            driftfile driftfile { tolerance ] +
            This command specifies the complete path and name of the file used to record the frequency of the local clock oscillator. This is the same operation as the -f command linke option. If the file exists, it is read at startup in order to set the initial frequency and then updated once per hour or more with the current frequency computed by the daemon. If the file name is specified, but the file itself does not exist, the starts with an initial frequency of zero and creates the file when writing it for the first time. If this command is not given, the daemon will always start with an initial frequency of zero.

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

            - -

            The parameter tolerance is the wander threshold to skip writing the new value. If the value of wander computed from recent frequency changes is greater than this threshold the file will be updated once per hour. If below the threshold, the file will not be written.

            -
            enable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]
            +

            The parameter tolerance is the wander threshold to skip writing the new value. If the value of wander computed from recent frequency changes is greater than this threshold the file will be updated once per hour. If below the threshold, the file will not be written.

            +
            enable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]
            disable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats ]
            Provides a way to enable or disable various system options. Flags not mentioned are unaffected. Note that all of these flags can be controlled remotely using the ntpdc utility program.
            @@ -47,88 +46,67 @@
            stats
            Enables the statistics facility. See the Monitoring Options page for further information. The default for this flag is disable
            -
            includefile includefile +
            includefile includefile
            This command allows additional configuration commands to be included from a separate file. Include files may be nested to a depth of five; upon reaching the end of any include file, command processing resumes in the previous configuration file. This option is useful for sites that run ntpd on multiple hosts, with (mostly) common options (e.g., a restriction list). -
            leapfile leapfile +
            leapfile leapfile
            This command loads the NIST leapseconds file and initializes the leapsecond values for the next leapsecond time, expiration time and TAI offset. The file 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 protocol provides means to securely retrieve the current or updated leapsecond values from a server.

            - -
            logconfig configkeyword +
            logconfig configkeyword
            This command controls the amount and type of output written to the system syslog facility or the alternate logfile log file. All configkeyword keywords can be prefixed with =, + and -, where = sets the syslogmask, + adds and - removes messages. syslog messages can be controlled in four classes (clock, peer, sys and sync). Within these classes four types of messages can be controlled: informational messages (info), event messages (events), statistics messages (statistics) and status messages (status).

            Configuration keywords are formed by concatenating the message class with the event class. The all prefix can be used instead of a message class. A message class may also be followed by the all keyword to enable/disable all messages of the respective message class. By default, logconfig output is set to allsync. -

            Thus, a minimal log configuration could look like this:

            +

            +

            Thus, a minimal log configuration could look like this:

            logconfig=syncstatus +sysevents

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

            -
            -

            logconfig=allsync +allclock

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

            -
            -
            logfile logfile -
            -
            -

            This command specifies the location of an alternate log file to be used instead of the default system syslog facility. This is the same operation as the -l command line option.

            - -
            -
            phone dial1 dial2 ... -
            -
            This command is used in conjunction with the ACTS modem driver (type 18). The arguments consist of a maximum of 10 telephone numbers used to dial USNO, NIST or European time services. The Hayes command ATDT is normally prepended to the number, which can contain other modem control codes as well. -
            -
            setvar variable [default] +
            logfile logfile +
            This command specifies the location of an alternate log file to be used instead of the default system syslog facility. This is the same operation as the -l command line option. +
            phone dial1 dial2 ... +
            This command is used in conjunction with the ACTS modem driver (type 18). The arguments consist of a maximum of 10 telephone numbers used to dial USNO, NIST or European time services. The Hayes command ATDT is normally prepended to the number, which can contain other modem control codes as well. +
            setvar variable [default]
            This command adds an additional system variable. These variables can be used to distribute additional information such as the access policy. If the variable of the form name = value is followed by the default keyword, the variable will be listed as part of the default system variables (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 override any variables defined via the setvar mechanism. There are three special variables that contain the names of all variable of the same group. The sys_var_list holds the names of all system variables. The peer_var_list holds the names of all peer variables and the clock_var_list holds the names of the reference clock variables. -
            tinker [ allan allan | dispersion dispersion | freq freq | huffpuff huffpuff | panic panic | step step | stepout stepout ] -
            This command can be used to alter several system variables in very exceptional circumstances. It should occur in the configuration file before any other configuration options. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. In general, they interact in intricate ways that are hard to predict and some combinations can result in some very nasty behavior. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs anyway and this command is for them. Emphasis added: twisters are on their own and can expect no help from the support group. -

            The variables operate as follows:

            +
            tinker [ allan allan | dispersion dispersion | freq freq | huffpuff huffpuff | panic panic | step step | stepout stepout ] +
            This command alters certain system variables used by the clock discipline algorithm. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs. The options are as follows: +

            allan allan

            -
            allan allan -
            The argument becomes the new value for the Allan intercept, which is a parameter of the PLL/FLL clock discipline algorithm. The value is in seconds with default 1500 s, which is appropriate for most computer clocks.
            dispersion dispersion -
            The argument becomes the new value for the dispersion increase rate, normally .000015 s/s. -
            freq freq -
            The argument becomes the initial value of the frequency offset in parts-per-million. This overrides the value in the frequency file, if present, and avoids the initial training state if it is not. -
            huffpuff huffpuff -
            The argument becomes the new value for the experimental huff-n'-puff filter span, which determines the most recent interval the algorithm will search for a minimum delay. The lower limit is 900 s (15 m), but a more reasonable value is 7200 (2 hours). There is no default, since the filter is not enabled unless this command is given. -
            panic panic -
            The argument is the panic threshold, by default 1000 s. If set to zero, the panic sanity check is disabled and a clock offset of any value will be accepted. -
            step step -
            The argument is the step threshold, by default 0.128 s. It can be set to any positive number in seconds. If set to zero, step adjustments will never occur. Note: The kernel time discipline is disabled if the step threshold is set to zero or greater than the default. -
            stepout stepout -
            The argument is the stepout timeout, by default 900 s. It can be set to any positive number in seconds. If set to zero, the stepout pulses will not be suppressed. -
            -
            tos [ ceiling ceiling | cohort {0 | 1} | floor floor | orphan orphan | maxdistance maxdistance | minclock minclock | minsane minsane ] -
            This command affects the clock selection and clustering algorithms. It can be used to select the quality and quantity of peers used to synchronize the system clock and is most useful in manycast mode. The variables operate as follows: -
            beacon beacon -
            The manycast server sends packets at intervals of 64 s if less than maxclock servers are available. Otherwise, it sends packets at the beacon interval in seconds. The default is 3600 s.
            ceiling ceiling -
            Servers with stratum at or above ceiling will be discarded if there are at least minclock peers remaining. This value defaults to 15, but can be changed to any number from 1 to 15. -
            cohort { 0 | 1 } -
            This is a binary flag which enables (0) or disables (1) manycast server replies to manycast clients with the same stratum level. This is useful to reduce implosions where large numbers of clients with the same stratum level are present. The default is to enable these replies. -
            floor floor -
            Peers with strata below floor will be discarded if there are at least minclock peers remaining. This value defaults to 1, but can be changed to any number from 1 to 15. -
            orphan stratum -
            If stratum is set at some value less than 16 a special orphan mode is enterred when no outside source of synchronization is available. To use orphan mode a number of participants are identically configured both as broadcast client and as broadcast server. One or more participants are configured to use an outside source, either a reference clock or another Internet server. When the source or sources fail, the system stratum is set at stratum and a leader is elected to serve as the reference source. When an outside source of synchronization is again available, the orphan mode is disabled.
            mindist mindistance -
            The slection algorithm normally pads each intersection a minimum of one millisecond to avoid needless classification. In some cases, such as reference clocks with high jitter and a PPS signal, it is useful to increase the padding. This command can be used for that purpose. As a general rule, set the mindistance to the maximum expected offset plus the maxiumum expected jitter, in seconds. +
            Spedifies the Allan intercept, which is a parameter of the PLL/FLL clock discipline algorithm, in seconds with default 1500 s. +
            dispersion dispersion +
            Specifies the dispersion increase rate in parts-per-million (PPM) with default 15 PPM.
            freq freq +
            Spedifies the frequency offset in parts-per-million (PPM) with default the value in the frequency file.
            huffpuff huffpuff +
            Spedifies the huff-n'-puff filter span, which determines the most recent interval the algorithm will search for a minimum delay. The lower limit is 900 s (15 m), but a more reasonable value is 7200 (2 hours).
            panic panic +
            Spedifies the panic threshold in seconds with default 1000 s. If set to zero, the panic sanity check is disabled and a clock offset of any value will be accepted.
            step step +
            Spedifies the step threshold in seconds with default 0.128 s. If set to zero, step adjustments will never occur. Note: The kernel time discipline is disabled if the step threshold is set to zero or greater than the default.
            stepout stepout +
            Specifies the stepout threshold in seconds with default 900 s. It If set to zero, popcorn spikes will not be suppressed.
            +
            tos [ beacon beacon | ceiling ceiling | cohort {0 | 1} | floor floor | maxclock maxclock | maxdist maxdist | minclock minclock | mindist mindist | minsane minsane | orphan stratum ]
            This command alters certain system variables used by the the clock selection and clustering algorithms. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs. It can be used to select the quality and quantity of peers used to synchronize the system clock and is most useful in dynamic server discovery schemes. The options are as follows: +
            +
            beacon beacon +
            The manycast server sends packets at intervals of 64 s if less than maxclock servers are available. Otherwise, it sends packets at the beacon interval in seconds. The default is 3600 s. See the Automatic Server Discovery page for further details.
            ceiling ceiling +
            Specify the maximum stratum (exclusive) for acceptable server packets. The default is 16. See the Automatic Server Discovery page for further details.
            cohort { 0 | 1 } +
            Specify whether (1) or whether not (0) a server packet will be accepted for the same stratum as the client. The default is 0. See the Automatic Server Discovery page for further details. +
            floor floo r +
            Specify the minimum stratum (inclusive) for acceptable server packest. The default is 1. See the Automatic Server Discovery page for further details. +
            maxclock maxclock
            Specify the maximum number of servers retained by the server discovery schemes. The default is 10. See the Automatic Server Discovery page for further details.
            maxdist maxdistance -
            The selection algorithm accumulates a number of packets before setting the clock in order to use the best data available. The number is determined by the synchronization distance for each association and a limit called the distance threshold. The synchronization distance starts at 16, then drops by a factor of about two as each packet is received. The default distance threshold is 1.0, which usually results in four packets. Setting maxdistance to some value between 1 and 16 can be used to change the number of packets required. For instance, setting it to 16 will set the clock on the first packet received; howver, setting it to this value essentially disables the mitigation and grooming algorithms. -
            minclock minclock -
            The clustering algorithm repeatedly casts out outlyer associations until no more than minclock associations remain. This value defaults to 3, but can be changed to any number from 1 to the number of configured sources. -
            minsane minsane -
            This is the minimum number of candidates available to the clock selection algorithm in order to produce one or more truechimers for the clustering algorithm. If fewer than this number are available, the clock is undisciplined and allowed to run free. The default is 1 for legacy purposes. However, according to principles of Byzantine agreement, minsane should be at least 4 in order to detect and discard a single falseticker. -
            -
            ttl hop ... -
            This command specifies a list of TTL values in increasing order. up to 8 values can be specified. In manycast mode these values are used in turn in an expanding-ring search. The default is eight multiples of 32 starting at 31. -
            trap host_address [port port_number] [interface interface_address] +
            Specify the synchronization distance threshold used by the clock selection algorithm. The default is 1.5 s. This determines both the minimum number of packets to set the system clock and the maximum roundtrip delay. It can be decreased to improve reliability or increased to synchronize clocks on the Moon or planets.
            minclock minclock +
            Specify the number of servers used by the clustering algorithm as the minimum to include on the candidate list. The default is 3. This is also the number of servers to be averaged by the combining algorithm.
            mindist mindistance +
            Specify the increment used by the selection algorithm to augment the correctness interval. The default is .005 s. In some cases, such as reference clocks with high jitter and a PPS signal, it is useful to increase the increment to insure the intersection interval is always nonempty.
            minsane minsane +
            Specify the number of servers used by the selection algorithm as the minimum to set the system clock. The default is 1 for legacy purposes; however, for critical applications the value should be somewhat higher but less than minclock. +
            orphan stratum +
            Specify the orphan stratum with default 16. If less than 16 this is the stratum assumed by the root servers. See the Association Management page for further details. +
            trap host_address [port port_number] [interface interface_address]
            This command configures a trap receiver at the given host address and port number for sending messages with the specified local interface address. If the port number is unspecified, a value of 18447 is used. If the interface address is not specified, the message is sent with a source address of the local interface the message is sent through. Note that on a multihomed host the interface used may vary from time to time with routing changes.

            The trap receiver will generally log event messages and other information from the server in a log file. While such monitor programs may also request their own trap dynamically, configuring a trap receiver will ensure that no messages are lost when the server is started.

            -
            ttl hop ... +
            ttl hop ...
            This command specifies a list of TTL values in increasing order. up to 8 values can be specified. In manycast mode these values are used in turn in an expanding-ring search. The default is eight multiples of 32 starting at 31.
      -
      diff --git a/html/monopt.html b/html/monopt.html index 278702014..96ab605dc 100644 --- a/html/monopt.html +++ b/html/monopt.html @@ -12,387 +12,452 @@

      Monitoring Options

      giffrom Pogo, Walt Kelly -

      The pig watches the logs.

      -

      Last update: 22:27 UTC Friday, February 01, 2008

      +

      Pig was hired to watch the logs.

      +

      Last update: 19:47 UTC


      Related Links

      +

      Table of Contents

      +
    +

    Introduction

    -

    ntpd includes a comprehensive monitoring facility which collects statistical data of various types and writes the data to files associated with each type at defined intervals. The files associated with a particular type are collectively called the generation file set for that type. The files in the file set are the members of that set.

    File sets have names specific to the type and generation epoch. The names are constructed from three concatenated elements prefix, filename and suffix:

    +

    The ntpd includes a comprehensive monitoring facility which collects statistical data of various types and writes the data to files associated with each type at defined events or intervals. The files associated with a particular type are collectively called the generation file set for that type. The files in the file set are the members of that set.

    +

    File sets have names specific to the type and generation epoch. The names are constructed from three concatenated elements prefix, filename and suffix:

    -
    prefix +
    prefix
    The directory path specified in the statsdir command. +
    name
    The name specified by the file option of the filegen command. +
    suffix -
    A string of elements bdginning with . (dot) followed by a string of elementes depending on the particular file set type. +
    A string of elements bdginning with . (dot) followed by a number of elements depending on the file set type.

    Statistics files can be managed using scripts, examples of which are in the ./scripts directory. Using these or similar scripts and Unix cron jobs, the files can be automatically summarized and archived for retrospective analysis.

    Monitoring Commands

    -
    filegen name file filename [type type] [link | nolink] [enable | disable] -
    -
    name -
    Specifies the file set type from the list in the next section. -
    file filename -
    Specfies the file set name. -
    type typename -
    Specifies the file set interval. The following intervals are supported with default day: +
    filegen name file filename [type type] [link | nolink] [enable | disable] +
    -
    none -
    The file set is actually a single plain file. -
    pid -
    One file set member is created for every incarnation of ntpd. . The file name suffix is the string .n, where n is the process ID of the ntpd server process. -
    day -
    One file set member is created per day. A day is defined as the period between 00:00 and 24:00 UTC. The file name suffix is the string .yyyymmdd, where yyyy is the year, mm the month of the year and dd the day of the month. Thus, member created on 10 December 1992 would have suffix .19921210. -
    week -
    One file set member is created per week. The week is defined as the day of year modulo 7. The file name suffix is the string .yyyyWww, where yyyy is the year, W stands for itself and ww the week number. For example, The member created on 10 January 1992 would have suffix .1992W1. -
    month -
    One file set member is created per month. The file name suffix is the string .yyyymm, where yyyy is the year and mm the month of the year. For example, The member created on 10 January 1992 would have suffix .199201. -
    year -
    One file set member is generated per year. The file name suffix is the string .yyyy, where yyyy is the year. For example, The member created on 1 January 1992 would have suffix .1992.
    age -
    One file set member is generated every 24 hours of ntpd operation. The filename suffix is the string .adddddddd, where a stands for itself and dddddddd is the ntpd running time in seconds at the start of the corresponding 24-hour period. +
    name +
    Specifies the file set type from the list in the next section. + +
    file filename +
    Specfies the file set name. + +
    type typename +
    Specifies the file set interval. The following intervals are supported with default day: +
    +
    none +
    The file set is actually a single plain file. + +
    pid +
    One file set member is created for every incarnation of ntpd. The file name suffix is the string .n, where n is the process ID of the ntpd server process. + +
    day +
    One file set member is created per day. A day is defined as the period between 00:00 and 23:59 UTC. The file name suffix is the string .yyyymmdd, where yyyy is the year, mm the month of the year and dd the day of the month. Thus, member created on 10 December 1992 would have suffix .19921210. + +
    week +
    One file set member is created per week. The week is defined as the day of year modulo 7. The file name suffix is the string .yyyyWww, where yyyy is the year, W stands for itself and ww the week number starting from 0. For example, The member created on 10 January 1992 would have suffix .1992W1. + +
    month +
    One file set member is created per month. The file name suffix is the string .yyyymm, where yyyy is the year and mm the month of the year starting from 1. For example, The member created on 10 January 1992 would have suffix .199201. + +
    year +
    One file set member is generated per year. The file name suffix is the string .yyyy, where yyyy is the year. For example, The member created on 1 January 1992 would have suffix .1992. + +
    age +
    One file set member is generated every 24 hours of ntpd operation. The filename suffix is the string .adddddddd, where a stands for itself and dddddddd is the ntpd running time in seconds at the start of the corresponding 24-hour period. + +
    +
    link | nolink +
    It is convenient to be able to access the current file set members by file name, but without the suffix. This feature is enabled by link and disabled by nolink. If enabled, which is the default, a hard link from the current file set member to a file without suffix is created. When there is already a file with this name and the number of links to this file is one, it is renamed by appending a dot, the letter C, and the pid of the ntpd server process. When the number of links is greater than one, the file is unlinked. This allows the current file to be accessed by a constant name. + +
    enable | disable +
    Enable or disable the recording function, with default enable. These options are intended for remote configutation commands. +
    -
    link | nolink -
    It is convenient to be able to access the current file set members by file name, but without the suffix. This feature is enabled by link and disabled by nolink. If enabled, which is the default, a hard link from the current file set member to a file without suffix is created. When there is already a file with this name and the number of links to this file is one, it is renamed by appending a dot, the letter C, and the pid of the ntpd server process. When the number of links is greater than one, the file is unlinked. This allows the current file to be accessed by a constant name. -
    enable | disable -
    Enable or disable the recording function, with default enable. These options are intended for remote configutation commands. -
    statsdir directory_path
    Specify the directory path prefix for statistics file names. +

    File Set Types

    -
    clockstats -
    Record reference clock statistics. Each update received from a reference clock driver appends one line to the clockstats file set:
    49213 525.624 127.127.4.1 93 226 00:08:29.606 D +
    +
    clockstats +
    Record reference clock statistics. Each update received from a reference clock driver appends one line to the clockstats file set: + +
    49213 525.624 127.127.4.1 93 226 00:08:29.606 D +
    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ItemUnitsDescription
    49213MJDdate
    525.624stime past midnight
    127.127.4.1IPreference clock address
    messagetextlog message
    +
    The message field includes the last timecode received in decoded ASCII format, where meaningful. In some cases a good deal of additional information is displayed. See information specific to each reference clock for further details. + +
    cryptostats +
    Record significant events in the Autokey protocol. This option requires the OpenSSL cryptographic software library. Each event appends one line to the cryptostats file set: +
    49213 525.624 128.4.1.1 message +
    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ItemUnitsDescription
    49213MJDdate
    525.624stime past midnight
    128.4.1.1IPsource address (0.0.0.0 for system)
    messagetextlog message
    +
    The message field includes the message type and certain ancillary information. See the Authentication Options page for further information. + +
    loopstats +
    Record clock discipline loop statistics. Each system clock update appends one line to the loopstats oopstats file set: +
    50935 75440.031 0.000006019 13.778 0.000351733 0.013380 6 +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ItemUnitsDescription
    50935MJDdate
    75440.031stime past midnight
    0.000006019sclock offset
    13.778PPMfrequency offset
    0.000351733sRMS jitter
    0.013380PPMRMS wander
    6 log2 sclock discipline loop time constant
    +
    peerstats +
    Record peer statistics. Each NTP packet or reference clock update received appends one line to the peerstats file set: +
    48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ItemUnitsDescription
    48773MJDdate
    10847.650stime past midnight
    127.127.4.1IPsource address
    9714hexstatus word
    -0.001605376sclock offset
    0.000000000 sroundtrip delay
    0.001424877sdispersion
    0.000958674sRMS jitter
    +
    The status field is encoded in hex format as described in Appendix B of the NTP specification RFC 1305. + +
    protostats +
    Record significant peer, system and clock events. Each significant event appends one line to the cryptostats file set: +
    49213 525.624 128.4.1.1 message
    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ItemUnitsDescription
    49213MJDdate
    525.624stime past midnight
    127.127.4.1IPreference clock address
    messagetextlog message
    -

    The message field includes the last timecode received in decoded ASCII format, where meaningful. In some cases a good deal of additional information is displayed. See information specific to each reference clock for further details.

    -
    cryptostats -
    Record significant events in the Autokey protocol. This option requires the OpenSSL cryptographic software library. Each event of the protocol module appends one line to the cryptostats file set:
    49213 525.624 128.4.1.1 message -
    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ItemUnitsDescription
    49213MJDdate
    525.624stime past midnight
    128.4.1.1IPsource address
    messagetextlog message
    -

    The message field includes the message type and certain ancillary information. See the Authentication Options page for further information.

    -
    loopstats -
    Record clock disiplilne loop statistics. Each system clock update appends one line to the loopstats file set:
    50935 75440.031 0.000006019 13.778 0.000351733 0.013380 6 -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ItemUnitsDescription
    50935MJDdate
    75440.031stime past midnight
    0.000006019sclock offset
    13.778PPMfrequency offset
    0.000351733hexRMS jitter
    0.013380PPMRMS wander
    6 log2 sclock discipline loop time constant
    -
    peerstats -
    Record peer statistics. Each NTP packet or reference clock update received appends one line to the peerstats file set:
    48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ItemUnitsDescription
    48773MJDdate
    10847.650stime past midnight
    127.127.4.1IPsource address
    128.4.1.20IPdestination address
    9714hexstatus word
    -0.001605376sclock offset
    0.000000000 sroundtrip delay
    0.001424877sdispersion
    0.000958674sRMS jitter
    -

    The status field is encoded in hex format as described in Appendix B of the NTP specification RFC 1305.

    -
    rawstats -
    Record timestamp statistics. Each NTP packet received appends one line to the rawstats file set:
    50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
    ItemUnitsDescription
    50928MJDdate
    2132.543stime past midnight
    128.4.1.1IPsource address
    128.4.1.20IPdestination address
    3102453281.584327000NTP soriginate timestamp
    3102453281.586228000NTP sreceive timestamp
    3102453332.540806000 NTP stransmit timestamp
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    ItemUnitsDescription
    49213MJDdate
    525.624stime past midnight
    128.4.1.1IPsource address (0.0.0.0 for system)
    messagetextlog message
    +
    The message field includes the message type and certain ancillary information. +
    rawstats +
    Record timestamp statistics. Each NTP packet received appends one line to the rawstats file set: + +
    50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ItemUnitsDescription
    50928MJDdate
    2132.543stime past midnight
    128.4.1.1IPsource address
    128.4.1.20IPdestination address
    3102453281.584327000NTP soriginate timestamp
    3102453281.586228000NTP sreceive timestamp
    3102453332.540806000 NTP stransmit timestamp
    3102453332.541458000 NTP s destination timestamp
    -
    sysstats -
    Record system statistics. Each hour one line is appended to the sysstats file set in the following format:
    50928 2132.543 36 81965 0 9546 56 512 540 10 147 1 -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
    sysstats +
    Record system statistics. Each hour one line is appended to the sysstats file set in the following format: +
    50928 2132.543 3600 81965 0 9546 56 512 540 10 4 147 1 +
    +
    ItemUnitsDescription
    50928MJDdate
    2132.543stime past midnight
    36htime since restart
    81965#total packets received last hour
    0#packets received for this host last hour
    9546#current version packets last hour
    56#previous version packets last hour
    512#access denied packets last hour
    540#bad length or format packets last hour
    10#bad authentication packets last hour
    147#rate exceeded packets last hour
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - +
    ItemUnitsDescription
    50928MJDdate
    2132.543stime past midnight
    3600stime since reset
    81965#packets received
    0#packets for this host
    9546#current versions
    56#old version
    512#access denied
    540#bad length or format
    10#bad authentication
    4#declined
    147#rate exceeded
    1 #kiss-o'-death packets sent last hourkiss-o'-death packets sent
    -
    timingstats -
    (Only available when the deamon is compiled with process time debugging support (--enable-debug-timing - costs performance). Record processing time statistics for various selected code paths.
    53876 36.920 10.0.3.5 1 0.000014592 input processing delay -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    ItemUnitsDescription
    53876MJDdate
    36.920stime past midnight
    10.0.3.5IPserver address
    1#event count
    0.000014592stotal time
    messagetextcode path description (see source)
    -
    +
    timingstats +
    (Only available when the deamon is compiled with process time debugging support (--enable-debug-timing - costs performance). Record processing time statistics for various selected code paths. +
    53876 36.920 10.0.3.5 1 0.000014592 input processing delay +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ItemUnitsDescription
    53876MJDdate
    36.920stime past midnight
    10.0.3.5IPserver address
    1#event count
    0.000014592stotal time
    messagetextcode path description (see source)
    +
    - + - + + \ No newline at end of file diff --git a/html/msyslog.html b/html/msyslog.html index f5ace49db..476cad27b 100644 --- a/html/msyslog.html +++ b/html/msyslog.html @@ -8,9 +8,9 @@

    ntpd System Log Messages

    - giffrom Alice's Adventures in Wonderland, Lewis Carroll -

    The mushroom knows all the error codes, which is more than most of us do.

    -

    Last update: 01:09 UTC Saturday, November 24, 2007

    + giffrom Alice's Adventures in Wonderland, Lewis Carroll +

    The log can be shrill at times.

    +

    Last update: 02:22 UTC Monday, March 03, 2008


    Related Links

    @@ -33,7 +33,10 @@

    LOG_INFO

    proto_config: illegal item ?, value ?
    Program error. Bugs can be reported here. -
    pps sync enabled +
    receive: autokey requires two-way communication +
    Configuration error on the broadcastclient command. +
    receive: server server maaximum rate exceeded +
    A kiss-o'death packet has been received. The transmit rate is automatically reduced.
    pps sync enabled
    The PPS signal has been detected and enabled.
    transmit: encryption key ? not found
    The encryption key is not defined or not trusted. diff --git a/html/ntp_conf.html b/html/ntp_conf.html index 520ce45c9..5eb520d0b 100644 --- a/html/ntp_conf.html +++ b/html/ntp_conf.html @@ -11,9 +11,9 @@

    Configuration File Definition (Advanced)

    - giffrom Pogo, Walt Kelly -

    A typical NTP monitoring packet

    -

    Last update: 19:46 UTC Friday, June 16, 2006

    + giffrom Pogo, Walt Kelly +

    Racoon is shooting configuration bugs.

    +

    Last update: 02:20 UTC Monday, March 03, 2008


    Table of Contents

    diff --git a/html/ntpd.html b/html/ntpd.html index 99a4c09ff..07cf89ebd 100644 --- a/html/ntpd.html +++ b/html/ntpd.html @@ -11,73 +11,61 @@

    ntpd - Network Time Protocol (NTP) daemon

    - giffrom Alice's Adventures in Wonderland, Lewis Carroll -

    The mushroom knows all the command line options.

    -

    Last update: 01:10 UTC Saturday, November 24, 2007

    + giffrom The Wizard of Oz, L. Frank Baum +

    You need help from the monkeys.

    +

    Last update: 19:34 UTC Saturday, March 22, 2008


    Related Links

    Table of Contents

    Synopsis

    ntpd [ -46aAbdDgLmnNqx ] [ -c conffile ] [ -f driftfile ] [ -i jaildir ] [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -P priority ] [ -r broadcastdelay ] [ -s statsdir ] [ -t key ] [ -u user[:group] ] [ -U interface_update_interval ] [ -v variable ] [ -V variable ]

    Description

    -

    The ntpd program is an operating system daemon which sets and maintains the system time of day in synchronism with Internet standard time servers. It is a complete implementation of the Network Time Protocol (NTP) version 4, but also retains compatibility with version 3, as defined by RFC-1305, and version 1 and 2, as defined by RFC-1059 and RFC-1119, respectively. ntpd does most computations in 64-bit floating-point arithmetic and does relatively clumsy 64-bit fixed-point operations only when necessary to preserve the ultimate precision, about 232 picoseconds. While the ultimate precision is not achievable with ordinary workstations and networks of today, it may be required with future gigahertz CPU clocks and gigabit LANs.

    -

    How NTP Operates

    -

    The ntpd program operates by exchanging messages with one or more configured servers at designated poll intervals. When started, whether for the first or subsequent times, the program requires several exchanges from the majority of these servers so the signal processing and mitigation algorithms can accumulate and groom the data to set the clock. In order to protect the network from bunching, the initial poll interval for each server is delayed an interval randomized over a few seconds. At the default initial poll interval of 64 s, several minutes can elapse before the clock is set. The initial delay to set the clock can be reduced using the iburst keyword with the server configuration command, as described on the Server Options page.

    -

    Most operating systems and hardware of today incorporate a time-of-year (TOY) chip to maintain the time during periods when the power is off. When the machine is booted, the chip is used to initialize the operating system time. After the machine has synchronized to a NTP server, the operating system corrects the chip from time to time. In case there is no TOY chip or for some reason its time is more than 1000 s, called the panic threshold, from the server time, ntpd assumes something must be terribly wrong and the only reliable action is for the operator to intervene and set the clock by hand. This causes ntpd to exit with a panic message to the system log. The -g option overrides this check and the clock will be set to the server time regardless of the chip time. However, and to protect against broken hardware, such as when the CMOS battery fails or the clock counter becomes defective, once the clock has been set, an error greater than 1000 s will cause ntpd to exit anyway.

    -

    Under ordinary conditions, ntpd adjusts the clock in small steps so that the timescale is effectively continuous and never runs backwards. Under conditions of extreme network congestion, the roundtrip delay jitter can exceed three seconds and the synchronization distance, which is equal to one-half the roundtrip delay plus error budget terms, can become very large. The ntpd algorithms discard offsets exceeding 128 ms, called the step threshold, unless the interval during which no sample offset is less than 128 ms exceeds 900 s, called the stepout threshold. The first sample after that, no matter what the offset, steps the clock to the indicated time. In practice this reduces the false alarm rate where the clock is stepped in error to a vanishingly low incidence.

    -

    As the result of this behavior, once the clock has been set, it very rarely strays more than 128 ms, even under extreme cases of network congestion and jitter. Sometimes, in particular when ntpd is first started, the error might exceed 128 ms. This may on occasion cause the clock to be set backwards if the local clock time is more than 128 s in the future relative to the server. In some applications, this behavior may be unacceptable. If the -x option is included on the command line, the clock will always be slewed unless the offset exceeds 600 s (10 minutes), in which case it will be stepped.

    -

    The issues should be carefully explored before deciding to use the -x option. The maximum slew rate possible is limited to 500 parts-per-million (PPM) as a consequence of the correctness principles on which the NTP protocol and algorithm design are based. As a result, the local clock can take a long time to converge to an acceptable offset, about 2,000 s for each second the clock is outside the acceptable range. During this interval the local clock will not be consistent with any other network clock and the system cannot be used for distributed applications that require correctly synchronized network time.

    -

    Frequency Discipline

    -

    The ntpd behavior at startup depends on whether the frequency file, usually called ntp.drift, exists. This file contains the latest estimate of clock frequency offset. When ntpd is started and the file does not exist, ntpd enters a special mode designed to directly measure the particular clock frequency offset. This takes 15 minutes, after which the time and frequency are set to nominal values and ntpd enters normal mode, where the time and frequency are continuously adjusted.

    -

    After one hour the frequency file is created and the current frequency offset written to it. When ntpd is started and the file does exist, ntpd initializes the frequency from the file and then enters normal mode immediately. In either case the current frequency offset is written to the file at hourly intervals.

    +

    The ntpd program is an operating system daemon that synchronises the system clock with remote NTP time servers or local reference clocks. It is a complete implementation of the Network Time Protocol (NTP) version 4, but also retains compatibility with version 3, as defined by RFC-1305, and version 1 and 2, as defined by RFC-1059 and RFC-1119, respectively. The program can operate in any of several modes, as described on the Association Management page, and with both symmetric key and public key cryptography, as described on the Authentication Options page.

    +

    The ntpd program ordinarily requires a configuration file as desccribe on the Configuration Commands and Options collection above. However a client can discover remote servers and configure them automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment. Further details are on the Automatic Server Discovery page.

    +

    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. Once started, the daemon will begin sending and receiving messages, as specified in the configuration file.

    +

    Setting the Time and Frequency

    +

    The ntpd program operates by exchanging messages with one or more servers at designated intervals ranging from about one minute to about 17 minutes. When started, the program requires several exchanges while the algorithms accumulate and groom the data before setting the clock. The initial delay to set the clock can be reduced using options on the Server Options page.

    +

    Most compters today incorporate a time-of-year (TOY) chip to maintain the time during periods when the power is off. When the machine is booted, the chip is used to initialize the operating system time. In case there is no TOY chip or the TOY time is more than 1000 s from the server time, ntpd assumes something must be terribly wrong and exits with a panic message to the system operator. With the -g option the clock will be initially set to the server time regardless of the chip time. However, once the clock has been set, an error greater than 1000 s will cause ntpd to exit anyway.

    +

    Under ordinary conditions, ntpd slews the clock so that the time is effectively continuous and never runs backwards. If due to extreme network congestion an error spike exceeds the step threshold, by default 128 ms, the spike is discarded. However, if the error persists for more than the stepout threshold, by default 900 s, the system clock is stepped to the correct value. In practice the need for a step has is extremely rare and almost always the result of a hardware failure. With the -x option the step threshold is increased to 600 s. Other options are available using the tinker command on the Miscellaneous Options page.

    +

    The issues should be carefully considered before using these options. The maximum slew rate possible is limited to 500 parts-per-million (PPM) by the Unix kernel. As a result, the clock can take 2000 s for each second the clock is outside the acceptable range. During this interval the clock will not be consistent with any other network clock and the system cannot be used for distributed applications that require correctly synchronized network time.

    +

    The frequency file, usually called ntp.drift, contains the latest estimate of clock frequency. If this file does not exist when ntpd is started, it enters a special mode designed to measure the particular frequency directly. The measurement takes 15 minutes, after which the frequency is set and ntpd resumes normal mode where the time and frequency are continuously adjusted. The frequency file is updated at intervals of an hour or more depending on the measured clock stability.

    Operating Modes

    -

    ntpd can operate in any of several modes, including symmetric active/passive, client/server broadcast/multicast and manycast, as described in the Association Management page. It normally operates continuously while adjusting the system clock time and frequency with respect to external sources. In some cases it may not be practical to run ntpd continuously. A common workaround has been to run the ntpdate program from a cron job at designated times. However, this program does not have the crafted signal processing, error checking and mitigation algorithms of ntpd. If the -q option is specified on the command line, ntpd will operate as in continous mode, but exit just after setting the clock for the first time. Most applications will probably want to specify the iburst keyword with the server configuration command. With this keyword a volley of messages is exchanged to groom the data and set the clock in about 10 s. If nothing is heard after a couple of minutes, the daemon times out and exits.

    -

    A broadcast/multicast or manycast client can discover remote servers, compute server-client propagation delay correction factors and configure itself automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment. An alternative to broadcast/multicast is manycast mode, in which a client broadcasts a request and one or more servers in range offer service. Further details are on the Automatic NTP Configuration Options page.

    -

    By default, ntpd runs in continuous mode where each of possibly several external servers is polled at intervals determined by an intricate phase/frequncy-lock feedback loop. The feedback loop measures the incidental clock offset jitter and oscillator frequency wander and determines the best poll interval using a heuristic algorithm. Ordinarily, and in most operating environments, the feedback loop will start with 64 s poll intervals and eventually increase in steps to 1024 s. A small amount of random variation is introduced in order to avoid bunching. In addition, should a server become unreachable for some time, the poll interval is increased in steps to 1024 s in order to reduce network overhead.

    +

    The ntpd program normally operates continuously while adjusting the time and frequency, but in some cases it may not be practical to run it continuously. With the -q option ntpd operates as in continous mode, but exits just after setting the clock for the first time. Most applications will probably want to specify the iburst option with the server command. With this option a volley of messages is exchanged to groom the data and set the clock in about 10 s. If nothing is heard after a few minutes, the daemon times out and exits.

    Poll Interval Control

    -

    NTP uses an intricate clock discipline algorithm to automatically control the poll interval for maximum accuracy consistent with minimum network load. The default minimum interval is 64 s and the maximum 1024 s, which is suitable for most conditions. The default minimum and maximum intervals can be changed using the tinker minpoll and tinker maxpoll commands, respectively. These values are used for all configured associations, unless overridden by the minpoll or minpoll options on the serverconfiguration command.

    -

    In some cases involving dial-up or ISDN toll services, it may be useful to set the minimum interval to 12 (4096 s) and maximum interval to 17 (36 h). Under normal operation conditions, once the clock discipline loop has stabilized the interval will be increased in steps from the minimum to the maximum. However, this assumes the residual clock frequency error is small enough for the discipline loop to capture and correct it. The capture range of the loop is 500 PPM with a 64-s interval decreasing by a factor of two for each interval doubling. At a 36-hr interval, for example, the capture range is only 0.24 PPM. If the frequency changes abruptly, due for instance a large change in temperature, one or more step adjustments may occur.is greater than this, the frequency file ntp.drift

    +

    NTP uses an intricate heuristic algorithm to automatically control the poll interval for maximum accuracy consistent with minimum network overhead. The algorithm measures the incidental offset and jitter to determine the best poll interval. When ntpd starts, the interval is the default minimum 64 s. Under normal conditions when the clock discipline has stabilized, the interval increases in steps to the default maximum 1024 s. In addition, should a server become unreachable after some time, the interval increases in steps to the maximum in order to reduce network overhead.

    +

    The default poll interval range is suitable for most conditions, but can be changed using options on the Server Options and Miscellaneous Options pages. However, when using maximum intervals much larger than the default, the residual clock frequency error must be small enough for the discipline loop to capture and correct. The capture range is 500 PPM with a 64-s interval decreasing by a factor of two for each interval doubling. At a 36-hr interval, for example, the capture range is only 0.24 PPM.

    The huff-n'-puff Filter

    -

    In scenarios where a considerable amount of data are to be downloaded or uploaded over telephone modems, timekeeping quality can be seriously degraded. This occurs because the differential delays on the two directions of transmission can be quite large. In many cases the apparent time errors are so large as to exceed the step threshold and a step correction can occur during and after the data transfer is in progress.

    -

    The huff-n'-puff filter is designed to correct the apparent time offset in these cases. It depends on knowledge of the propagation delay when no other traffic is present. In common scenarios this occurs during other than work hours. The filter maintains a shift register that remembers the minimum delay over the most recent interval measured usually in hours. Under conditions of severe delay, the filter corrects the apparent offset using the sign of the offset and the difference between the apparent delay and minimum delay. The name of the filter reflects the negative (huff) and positive (puff) correction, which depends on the sign of the offset.

    -

    The filter is activated by the tinker huffpuff command, as described in the Miscellaneous Options page.

    +

    In scenarios where a considerable amount of data are to be downloaded or uploaded over telephone modems, timekeeping quality can be seriously degraded. This occurs because the differential delays on the two directions of transmission can be quite large. In many cases the apparent time errors are so large as to exceed the step threshold and a step correction can occur during and after the data transfer.

    +

    The huff-n'-puff filter is designed to correct the apparent time offset in these cases. It depends on knowledge of the propagation delay when no other traffic is present, such as during other than work hours. The filter remembers the minimum delay over the most recent interval measured usually in hours. Under conditions of severe delay, the filter corrects the apparent offset using the sign of the offset and the difference between the apparent delay and minimum delay. The name of the filter reflects the negative (huff) and positive (puff) correction, which depends on the sign of the offset. The filter is activated by the tinker huffpuff command, as described in the Miscellaneous Options page.

    Leap Second Processing

    -

    As provided by international agreement, an extra second is sometimes inserted in Coordinated Universal Time (UTC) at the end of a selected month, usually June or December. The National Institutes of Standards and Technology (NIST) provides an historic leapseconds file at time.nist.gov for retrieval via FTP. When this file, usually called ntp.leap, is installed, ntpd reads it at startup and initializes three leapsecond values, the offset of International Atomic Time (TAI) after the last leap in the file, the NTP seconds of that leap and the NTP seconds when the leapseconds file expires.

    -

    If a host does not have the leapsecond values, they can be obtained over the net using the Autokey security protocol. Ordinarily, the leapseconds file is installed on the primary servers and the values flow from them to dependent servers and eventually clients. When multiple servers are involved, the values with the latest expiration time are used.

    -

    If the latest leap is in the past, nothing further is done other than to install the TAI offset in the kernel where it can be retrieved by the ntp_gettimeofday() system call. If the leap is in the future less than 28 days, the leap warning bits are set to insert one second. If in the future less than 23 hours, the kernel is armed to insert one second at the end of the current day. If the kernel is enabled, the leap is done automatically at that time; otherwise, the clock is stepped back one second at that time.

    +

    As provided by international agreement, an extra second is sometimes inserted in Coordinated Universal Time (UTC) at the end of a selected month, usually June or December. The National Institutes of Standards and Technology (NIST) provides an historic leapseconds file at time.nist.gov for retrieval via FTP. When this file, usually called ntp.leapseconds, is installed, ntpd reads it at startup and initializes three leapsecond values: the NTP seconds at the next leap event, the offset of UTC relative to International Atomic Time (TAI) after the leap and the NTP seconds when the leapseconds file expires.

    +

    If a host does not have the leapsecond values, they can be obtained over the net using the Autokey security protocol. Ordinarily, the leapseconds file is installed on the primary servers and the values flow from them via secondary servers to the clients. When multiple servers are involved, the values with the latest expiration time are used.

    +

    If the latest leap is in the past, nothing further is done other than to install the TAI offset. If the leap is in the future less than 28 days, the leap warning bits are set. If in the future less than 23 hours, the kernel is armed to insert one second at the end of the current day. If the kernel is enabled, the leap is done automatically at that time; otherwise, the clock is effectively stopped for one second at the leap. Additional details are in the The NTP Timescale and Leap Seconds white paper

    Dependent servers and clients tally the leap warning bits of surviving servers and reference clocks. When a majority of the survivors show warning, a leap is programmed at the end of the current month. During the month and day of insertion, they operate as above. In this way the leap is propagated at all dependent servers and clients.

    Additional Features

    -

    If ntpd, is configured with NetInfo support, it will attempt to read its configuration from the NetInfo service if the default ntp.conf file cannot be read and no file is specified by the -c option.

    +

    If ntpd, is configured with NetInfo support, it will attempt to read its configuration from the NetInfo service if the default ntp.conf file cannot be read and no file is specified by the -c option.

    In contexts where a host name is expected, a -4 qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a -6 qualifier forces DNS resolution to the IPv6 namespace.

    Various internal ntpd variables can be displayed and configuration options altered while the ntpd is running using the ntpq and ntpdc utility programs.

    When ntpd starts it looks at the value of umask, and if zero ntpd will set the umask to 022.

    Command Line Options

    -a -
    Require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is the default. -
    -A -
    Do not require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is almost never a good idea. -
    -b +
    Require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is the same operation as the enable auth command and is the default.
    -A +
    Do not require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is the same operation as the disable auth command and almost never a good idea.
    -b
    Enable the client to synchronize to broadcast servers.
    -c conffile
    Specify the name and path of the configuration file, default /etc/ntp.conf. @@ -86,36 +74,29 @@
    -D level
    Specify debugging level directly.
    -f driftfile -
    Specify the name and path of the frequency file, default /etc/ntp.drift. This is the same operation as the driftfile driftfile configuration command. -
    -g +
    Specify the name and path of the frequency file, default /etc/ntp.drift. This is the same operation as the driftfile driftfile command.
    -g
    Normally, ntpd exits with a message to the system log if the offset exceeds the panic threshold, which is 1000 s by default. This option allows the time to be set to any value without restriction; however, this can happen only once. If the threshold is exceeded after that, ntpd will exit with a message to the system log. This option can be used with the -q and -x options. See the tinker command for other options.
    -i jaildir -
    Chroot the server to the directory jaildir. This option also implies that the server attempts to drop root privileges at startup (otherwise, chroot gives very little additional security), and it is only available if the OS supports to run the server without full root privileges. You may need to also specify a -u option. +
    Chroot the server to the directory jaildir. This option also implies that the server attempts to drop root privileges at startup (otherwise, chroot gives very little additional security), and it is only available if the OS supports to run the server without full root privileges. You may need to also specify a -u option.
    -k keyfile -
    Specify the name and path of the symmetric key file, default /etc/ntp.keys. This is the same operation as the keys keyfile configuration command. -
    -l logfile -
    Specify the name and path of the log file. The default is the system log file. This is the same operation as the logfile logfile configuration command. -
    -L +
    Specify the name and path of the symmetric key file, default /etc/ntp.keys. This is the same operation as the keys keyfile command.
    -l logfile +
    Specify the name and path of the log file. The default is the system log file. This is the same operation as the logfile logfile command.
    -L
    Do not listen to virtual IPs. The default is to listen.
    -n
    Don't fork.
    -N
    To the extent permitted by the operating system, run the ntpd at the highest priority.
    -p pidfile -
    Specify the name and path of the file used to record the ntpd process ID. This is the same operation as the pidfile pidfile configuration command. -
    -P priority +
    Specify the name and path of the file used to record the ntpd process ID. This is the same operation as the pidfile pidfile command.
    -P priority
    To the extent permitted by the operating system, run the ntpd at the specified priority.
    -q
    Exit the ntpd just after the first time the clock is set. This behavior mimics that of the ntpdate program, which is to be retired. The -g and -x options can be used with this option. Note: The kernel time discipline is disabled with this option.
    -r broadcastdelay
    Specify the default propagation delay from the broadcast/multicast server to this client. This is necessary only if the delay cannot be computed automatically by the protocol.
    -s statsdir -
    Specify the directory path for files created by the statistics facility. This is the same operation as the statsdir statsdir configuration command. -
    -t key -
    Add a key number to the trusted key list. This option can occur more than once. -
    -u user[:group] -
    Specify a user, and optionally a group, to switch to. This option is only available if the OS supports to run the server without full root privileges. Currently, this option is supported under NetBSD (configure with --enable-clockctl) and Linux (configure with --enable-linuxcaps). -
    -U interface update interval +
    Specify the directory path for files created by the statistics facility. This is the same operation as the statsdir statsdir command.
    -t key +
    Add a key number to the trusted key list. This option can occur more than once. This is the same operation as the trustedkey key command.
    -u user[:group] +
    Specify a user, and optionally a group, to switch to. This option is only available if the OS supports running the server without full root privileges. Currently, this option is supported under NetBSD (configure with --enable-clockctl) and Linux (configure with --enable-linuxcaps).
    -U interface update interval
    Number of seconds to wait between interface list scans to pick up new and delete network interface. Set to 0 to disable dynamic interface list updating. The default is to scan every 5 minutes.
    -v variable
    -V variable @@ -124,17 +105,9 @@
    Normally, the time is slewed if the offset is less than the step threshold, which is 128 ms by default, and stepped if above the threshold. This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s. Thus, an adjustment as much as 600 s will take almost 14 days to complete. This option can be used with the -g and -q options. See the tinker command for other options. Note: The kernel time discipline is disabled with this option.

    The Configuration File

    -

    Ordinarily, ntpd reads the ntp.conf configuration file at startup time in order to determine the synchronization sources and operating modes. It is also possible to specify a working, although limited, configuration entirely on the command line, obviating the need for a configuration file. This may be particularly useful when the local host is to be configured as a broadcast/multicast client, with all peers being determined by listening to broadcasts at run time.

    -

    Usually, the configuration file is installed in the /etc directory, but could be installed elsewhere (see the -c conffile command line option). The file format is similar to other Unix configuration files - comments begin with a # 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. 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 [ ] in the following option pages, while alternatives are separated by |. The notation [ ... ] means an optional, indefinite repetition of the last item before the [ ... ].

    -

    Configuration Options

    -

    Server Options
    - Authentication Options
    - Monitoring Options
    - Access Control Options
    - Automatic NTP Configuration Options
    - Reference Clock Options
    - Miscellaneous Options

    +

    Ordinarily, ntpd reads the ntp.conf configuration file at startup in order to determine the synchronization sources and operating modes. It is also possible to specify a working, although limited, configuration entirely on the command line, obviating the need for a configuration file. This may be particularly useful when the local host is to be configured as a broadcast client, with servers determined by listening to broadcasts at run time.

    +

    Usually, the configuration file is installed as/etc/ntp.conf, but could be installed elsewhere (see the -c conffile command line option). The file format is similar to other Unix configuration files - comments begin with a # character and extend to the end of the line; blank lines are ignored.

    +

    Configuration commands consist of an initial command keyword followed by a list of option keywords separated by whitespace. Commands may not be continued over multiple lines. Options 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 [ ] in the options pages, while alternatives are separated by |. The notation [ ... ] means an optional, indefinite repetition of the last item before the [ ... ].

    Files

    @@ -151,10 +124,16 @@ - + + + + + + + diff --git a/html/ntpdsim.html b/html/ntpdsim.html index 3ae33b565..2fcfebf5f 100644 --- a/html/ntpdsim.html +++ b/html/ntpdsim.html @@ -11,9 +11,9 @@

    ntpdsim - Network Time Protocol (NTP) simulator

    - giffrom Alice's Adventures in Wonderland, Lewis Carroll -

    The mushroom knows all the command line options.

    -

    Last update: 01:12 UTC Saturday, November 24, 2007

    + giffrom The Wizard of Oz, L. Frank Baum +

    All in a row.

    +

    Last update: 15:55 UTC Sunday, March 02, 2008


    Related Links

    diff --git a/html/ntpdsim_new.html b/html/ntpdsim_new.html index 76706fd39..c8b319955 100644 --- a/html/ntpdsim_new.html +++ b/html/ntpdsim_new.html @@ -11,9 +11,9 @@

    ntpdsim - Network Time Protocol (NTP) Simulator

    - giffrom Alice's Adventures in Wonderland, Lewis Carroll -

    The mushroom knows all the command line options.

    -

    Last update: 19:45 UTC Saturday, January 19, 2008

    + giffrom The Wizard of Oz, L. Frank Baum +

    All in a row.

    +

    Last update: 15:56 UTC Sunday, March 02, 2008


    Related Links

    diff --git a/html/ntpq.html b/html/ntpq.html index 85ead196d..e53bf7a80 100644 --- a/html/ntpq.html +++ b/html/ntpq.html @@ -13,7 +13,7 @@

    ntpq - standard NTP query program

    giffrom Pogo, Walt Kelly

    A typical NTP monitoring packet

    -

    Last update: 01:13 UTC Saturday, November 24, 2007

    +

    Last update: 23:58 UTC Friday, April 04, 2008


    More Help

    @@ -45,218 +45,481 @@
    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 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 [...]
    +
    A ? by itself will print a list of all the command keywords known to ntpq. A ? followed by a command keyword will print function and usage information about the command. +
    addvars name [ = value] [...]
    + rmvars 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 arguments to this command consist of a list of items of the form name = value, where the = value is ignored, and can be omitted in read requests. 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 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.
    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 decodable value but didn't are marked with a trailing ?. -
    debug more | less | off +
    Display server messages in prettyprint format.
    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. -
    host hostname -
    Set the host to which future queries will be sent. Hostname may be either a host name or a numeric address. -
    hostnames [yes | no] +
    host name +
    Set the host to which future queries will be sent. The name may be either a DNS 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.
    keyid keyid
    This command specifies the 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 2, Note that mode 6 control messages (and modes, for that matter) didn't exist in NTP version 1. -
    passwd -
    This command prompts for a password (which will not be echoed) which will be used to authenticate configuration requests. The password must correspond to the key configured for NTP server for this purpose. -
    quit +
    Sets the NTP version number which ntpq claims in packets. Defaults to 2, Note that mode-6 control messages (and modes, for that matter) didn't exist in NTP version 1.
    passwd +
    This command prompts for a password to authenticate configuration requests. The password must correspond to the key configured for NTP server for this purpose.
    quit
    Exit ntpq.
    raw -
    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 +
    Display server messages as received and without reformatting.
    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.

    Control Message Commands

    -

    Each association known to an NTP server has a 16 bit integer association identifier. 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.

    +

    Association IDs are used to identify system, peer and clock variables. System variables are assigned an association ID of zero and system name space, while each association is assigned a nonzero association ID and peer namespace. Most control commands send a single mode-6 message to the server and expect a single response message. The exceptions are the peers command, which sends a series of messages, and the mreadlist and mreadvar commands, which 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 &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. -
    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. -
    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. -
    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[ ... ]
    +
    associations +
    Display a list of mobilized associations in the form
    ind assid status conf reach auth condition last_event cnt +
    +
    frequency file/etc/ntp.driftnone -f driftfile
    leapseconds filenoneleapfile
    process ID file none
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VariableDescription
    indindex on this list
    assidassociation ID
    statuspeer status word
    confyes: persistent, no: ephemeral
    reachyes: reachable, no: unreachable
    authok, yes, bad and none
    conditionsource (see peer status word)
    last_eventevent report (see peer status word)
    cntevent count (see peer status word)
    +
    clockvar [assocID] [name [ = value [...]] [...] +
    cv [assocID] [name [ = value [...] ][...] +
    Display a list of clock variables for those assocations supporting a reference clock. +
    keyid +
    Specify the key ID to use for write requests.
    lassociations +
    Perform the same function as the associations command, execept display mobilized and unmobilized associations.
    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. +
    Perform the same function as the readvar command, except for a range of association IDs. This range is determined from the association list cached by the most recent associations command.
    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. -
    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 at the left margin of each line shows the synchronization status of the association and is a valuable diagnostic tool. The encoding and meaning of this character, called the tally code, is given later in this page. -
    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 hexadecimal 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. The encoding and meaning of the variables derived from NTPv3 is given in RFC-1305; the encoding and meaning of the additional NTPv4 variables are given later in this page. -
    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. -
    • -

    Tally Codes

    -

    The character in the left margin in the peers billboard, called the tally code, shows the fate of each association 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. -
    x  falsetick -
    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. -
    -  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. -
    #  selected -
    The peer is a survivor, but not among the first six peers sorted by synchronization distance. If the association 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. -
    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. -
    -

    System Variables

    -

    The status, leap, stratum, precision, rootdelay, rootdispersion, refid, reftime, poll, offset, and frequency variables are described in RFC-1305 specification. Additional NTPv4 system variables include the following.

    -
    -
    version -
    Everything you might need to know about the software version and generation time. -
    processor -
    The processor and kernel identification string. -
    system -
    The operating system version and release identifier. -
    state -
    The state of the clock discipline state machine. The values are described in the architecture briefing on the NTP Project page linked from www.ntp.org. -
    peer -
    The internal integer used to identify the association currently designated the system peer. -
    jitter -
    The estimated time error of the system clock measured as an exponential average of RMS time differences. -
    stability -
    The estimated frequency stability of the system clock measured as an exponential average of RMS frequency differences. -
    -

    When the NTPv4 daemon is compiled with the OpenSSL software library, additional system variables are displayed, including some or all of the following, depending on the particular dance:

    -
    -
    flags -
    The current flags word bits and message digest algorithm identifier (NID) in hex format. The high order 16 bits of the four-byte word contain the NID from the OpenSSL ligrary, while the low-order bits are interpreted as follows: -
    -
    -
    0x01 -
    autokey enabled -
    0x02 -
    NIST leapseconds file loaded -
    0x10 -
    PC identity scheme -
    0x20 -
    IFF identity scheme -
    0x40 -
    GQ identity scheme -
    -
    hostname -
    The name of the host as returned by the Unix gethostname() library function. -
    hostkey -
    The NTP filestamp of the host key file. -
    cert -
    A list of certificates held by the host. Each entry includes the subject, issuer, flags and NTP filestamp in order. The bits are interpreted as follows: +
    Perform the same function as the associations command, except that it uses previously stored data rather than making a new query. +
    passwd +
    Specify the password to use for write requests. +
    peers +
    Display a list of associations in the form +
    ind assid status conf reach auth condition last_event cnt
    -
    -
    0x01 -
    certificate has been signed by the server -
    0x02 -
    certificate is trusted -
    0x04 -
    certificate is private -
    0x08 -
    certificate contains errors and should not be trusted -
    -
    leapseconds -
    The NTP filestamp of the NIST leapseconds file. -
    refresh -
    The NTP timestamp when the host public cryptographic values were refreshed and signed. -
    signature -
    The host digest/signature scheme name from the OpenSSL library. -
    tai -
    The TAI-UTC offset in seconds obtained from the NIST leapseconds table. -
    -

    Peer Variables

    -

    The status, srcadr, srcport, dstadr, dstport, leap, stratum, precision, rootdelay, rootdispersion, readh, hmode, pmode, hpoll, ppoll, offset, delay, dspersion, reftime variables are described in the RFC-1305 specification, as are the timestamps org, rec and xmt. Additional NTPv4 system variables include the following.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VariableDescription
    remoteindex on this list
    refidassociation ID or kiss code
    stpeer status word
    tu: unicast, b: broadcast, l: local
    whensec/min/hr since last received packet
    pollpoll interval (log2 s)
    reachreach shift register (octal)
    delayroundtrip delay
    offsetoffset
    jitterjitter
    +
    readvar assocID name [ = value ] [,...]
    + rv assocID [ name ] [,...] +
    Display the specified variables. If the association ID is omitted or is given as zero, the variables are from the system variables name space, otherwise they are from the peer variables name space. If no name is included, all operative variables in the name space are displayed. Multiple names are specified with comma separators and without whitespace. Note that time values are represented in milliseconds and frequency values in parts-per-million (PPM). Some NTP timestamps are represented in the format YYYYMMDDTTTT, where YYYY is the year, MM the month of year, DD the day of month and TTTT the time of day.
    writevar assocID name = value [,...] +
    Write the specified variables. If the association ID is omitted or is given as zero, the variables are from the system variables name space, otherwise they are from the peer variables name space. +
    :config [...] +
    Send the remainder of the command line, including whitespace, to the server as a run-time configuration command in the same format as the configuration file. This command is experimental until further notice and clarification. Authentication is of course required.
    +

    Status Words and Kiss Codes

    +

    The current state of the operating program is shown in a set of status words maintained by the system and each association separately. These words are displayed in the rv and as commands both in hexadecimal and decoded short tip strings. The codes, tips and short explanations are on the Event Messages and Status Words page. The page also includes a list of system and peer messages, the code for the latest of which is included in the status word.

    +

    Information resulting from protocol machine state transitions is displayed using an informal set of ASCII strings called kiss codes. The original purpose was for kiss-o'-death (KoD) packets sent by the server to advise the client of an unusual condition. They are now displayed, when appropriate, in the reference identifier field in various billboards.

    +

    System Variables

    +

    The following system variables apear in the rv billboard. Not all variables are displayed in some configurations.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VariableDescription
    statussystem status word
    versionNTP software version and build time
    processorhardware platform and version
    systemoperating system and version
    leapleap warning indicator (0-3)
    stratumstratum (1-15)
    precisionprecision (log2 s)
    rootdelaytotal roundtrip delay to the primary reference clock
    rootdisptotal dispersion to the primary reference clock
    peersystem peer association ID
    tctime constant and poll exponent (log2 s) (3-17)
    mintcminimum time constant (log2 s) (3-10)
    clockdate and time of day
    refidreference ID or kiss code
    reftimereference time
    offsetcombined time offset
    sys_jittercombined system jitter
    frequencyclock frequency offset (PPM)
    clk_wanderclock frequency wander (PPM)
    clk_jitterclock jitter
    taiTAI-UTC offset (s)
    leapsecNTP seconds when the next leap second is/was inserted
    expireNTP seconds when the NIST leapseconds file expires
    -
    flash -
    The flash code for the most recent packet received. The encoding and meaning of these codes is given later in this page. -
    jitter -
    The estimated time error of the peer clock measured as an exponential average of RMS time differences. -
    unreach -
    The value of the counter which records the number of poll intervals since the last valid packet was received. -
    +
    When the NTPv4 daemon is compiled with the OpenSSL software library, additional system variables are displayed, including some or all of the following, depending on the particular Autokey dance:
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VariableDescription
    hostAutokey host name
    groupAutokey group name
    flagshost flags (see Autokey specification)
    signatureOpenSSL digest/signature scheme
    updateNTP seconds at last signature update
    certcertificate subject, issuer and certificate flags
    untilNTP seconds when the certificate expires
    +

    Peer Variables

    +

    The following system variables apear in the rv billboard for each association. Not all variables are displayed in some configurations.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VariableDescription
    associdassociation ID
    statuspeer status word
    srcadr
    + srcport    		source (remote) IP address and port
    dstadr
    + dstport    		destination (local) IP address and port
    leapleap indicator (0-3)
    stratumstratum (0-15)
    precisionprecision (log2 s)
    rootdelaytotal roundtrip delay to the primary reference clock
    rootdisptotal root dispersion to the primary reference clock
    refidreference ID or kiss code
    reftimereference time
    reachreach register (octal)
    unreachunreach counter
    hmodehost mode (1-6)
    pmodepeer mode (1-5)
    hpollhost poll exponent (log2 s) (3-17)
    ppollpeer poll exponent (log2 s) (3-17)
    headwayheadway (s)
    flashflash status word
    offsetfilter offset
    delayfilter delay
    dispersionfilter dispersion
    jitterfilter jitter

    When the NTPv4 daemon is compiled with the OpenSSL software library, additional peer variables are displayed, including the following:

    -
    -
    flags -
    The current flag bits. This word is the server host status word with additional bits used by the Autokey state machine. See the source code for the bit encoding. -
    hostname -
    The server host name. -
    initkey key -
    The initial key used by the key list generator in the Autokey protocol. -
    initsequence index -
    The initial index used by the key list generator in the Autokey protocol. -
    signature -
    The server message digest/signature scheme name from the OpenSSL software library. -
    timestamp time -
    The NTP timestamp when the last Autokey key list was generated and signed. -
    -

    Flash Codes

    -

    The flash code is a valuable debugging aid displayed in the peer variables list. It shows the results of the original sanity checks defined in the NTP specification RFC-1305 and additional ones added in NTPv4. There are 12 tests designated TEST1 through TEST12. 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 initialized to zero as each packet is received. If after each set of tests one or more bits are set, the packet is discarded.

    -

    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. TEST4 and TEST5 are associated with access control and cryptographic authentication. If any bits are set, the packet is discarded immediately with nothing changed.

    -

    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. 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.

    -

    Tests TEST10 through TEST12 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.

    -

    The flash bits for each test are defined as follows.

    -
    -
    0x001 TEST1 -
    Duplicate packet. The packet is at best a casual retransmission and at worst a malicious replay. -
    0x002 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. -
    0x004 TEST3 -
    Unsynchronized. One or more timestamp fields are invalid. This normally happens when the first packet from a peer is received. -
    0x008 TEST4 -
    Access is denied. See the Access Control Options page. -
    0x010 TEST5 -
    Cryptographic authentication fails. See the Authentication Options page. -
    0x020TEST6 -
    The server is unsynchronized. Wind up its clock first. -
    0x040 TEST7 -
    The server stratum is at the maximum than 15. It is probably unsynchronized and its clock needs to be wound up. -
    0x080 TEST8 -
    Either the root delay or dispersion is greater than one second, which is highly unlikely unless the peer is unsynchronized to Mars. -
    0x100 TEST9 -
    Either the peer delay or dispersion is greater than one second, which is higly unlikely unless the peer is on Mars. -
    0x200 TEST10 -
    The autokey protocol has detected an authentication failure. See the Authentication Options page. -
    0x400 TEST11 -
    The autokey protocol has not verified the server or peer is proventic and has valid public key credentials. See the Authentication Options page. -
    0x800 TEST12 -
    A protocol or configuration error has occurred in the public key algorithms or a possible intrusion event has been detected. See the Authentication Options page. -
    -

    Bugs

    -

    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.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VariableDescription
    flagspeer flags (see Autokey specification)
    hostAutokey server name
    signatureinitial session key ID
    initsequenceinitial key ID
    initkeyinitial key index
    timestampAutokey signature timestamp
    +

    Clock Variables

    +

    The following clock variables apear in the cv billboard for each association with a reference clock. Not all variables are displayed in some configurations.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    VariableDescription
    associdassociation ID
    statusclock status word
    devicedevice description
    timecodeASCII timecode string (specific to device)
    pollpoll messages sent
    noreplyno reply
    badformatbad format
    baddatabad date or time
    fudgetime1fudge time 1
    fudgetime2fudge time 2
    stratumdriver stratum
    refiddriver reference ID
    flagsdriver flags
    diff --git a/html/ntptime.html b/html/ntptime.html index a9ea33b5f..11da1fbb3 100644 --- a/html/ntptime.html +++ b/html/ntptime.html @@ -5,15 +5,15 @@ - ntptime - read kernel time variables + ntptime - read and set kernel time variables -

    ntptime - read kernel time variables

    +

    ntptime - read and set kernel time variables

    giffrom Pogo, Walt Kelly

    The turtle has been swimming in the kernel.

    -

    Last update: 18:46 UTC Thursday, July 28, 2005

    +

    Last update: 16:40 UTC Wednesday, March 12, 2008


    Synopsis

    diff --git a/html/pic/alice15.gif b/html/pic/alice15.gif new file mode 100644 index 000000000..e17b5fdf1 Binary files /dev/null and b/html/pic/alice15.gif differ diff --git a/html/pic/flatheads.gif b/html/pic/flatheads.gif new file mode 100644 index 000000000..707cb8cc3 Binary files /dev/null and b/html/pic/flatheads.gif differ diff --git a/html/pic/pogo7.gif b/html/pic/pogo7.gif new file mode 100644 index 000000000..36befe7a6 Binary files /dev/null and b/html/pic/pogo7.gif differ diff --git a/html/pic/tonea.gif b/html/pic/tonea.gif index 17f48fced..195a3df6c 100644 Binary files a/html/pic/tonea.gif and b/html/pic/tonea.gif differ diff --git a/html/pic/tribeb.gif b/html/pic/tribeb.gif new file mode 100644 index 000000000..59e8a7c48 Binary files /dev/null and b/html/pic/tribeb.gif differ diff --git a/html/pic/wingdorothy.gif b/html/pic/wingdorothy.gif index bb0d19dd8..3f2e0be66 100644 Binary files a/html/pic/wingdorothy.gif and b/html/pic/wingdorothy.gif differ diff --git a/html/quick.html b/html/quick.html index 69939e311..261094437 100644 --- a/html/quick.html +++ b/html/quick.html @@ -13,17 +13,17 @@

    Quick Start

    gifFAX test image for SATNET (1979).

    The baby panda was scanned at University College London and used as a FAX test image for a demonstration of the DARPA Atlantic SATNET Program and the first transatlantic Internet connection in 1978. The computing system used for that demonstration was called the Fuzzball. As it happened, this was also the first Internet multimedia presentation and the first to use NTP in regular operation. The image was widely copied and used for testing purpose throughout much of the 1980s.

    -

    Last update: 20:02 UTC Monday, December 31, 2007

    +

    Last update: 16:25 UTC Sunday, March 02, 2008

    Related Links

    For the rank amateur the sheer volume of the documentation collection must be intimidating. However, it doesn't take much to fly the ntpd daemon with a simple configuration where a workstation needs to synchronize to some server elsewhere in the Internet. The first thing is to build the distribution for the particular workstation and install in the usual place. The Building and Installing the Distribution page describes how to do this.

    -

    While it is possible that certain configurations do not need a configuration file, most do. The file, called by default /etc/ntp.conf, need only contain one line specifying a remote server, for instance

    +

    While it is possible that certain configurations do not need a configuration file, most do. The file, called by default /etc/ntp.conf, need only contain one command specifying a remote server, for instance

    server foo.bar.com

    Choosing an appropriate remote server is somewhat of a black art, but a suboptimal choice is seldom a problem. There are about two dozen public time servers operated by the National Institutes of Science and Technology (NIST), US Naval Observatory (USNO), Canadian Metrology Centre (CMC) and many others available on the Internet. Lists of public primary and secondary NTP servers maintained on the Public NTP Time Servers page, which is updated frequently.The lists are sorted by country and, in the case of the US, by state. Usually, the best choice is the nearest in geographical terms, but the terms of engagement specified in each list entry should be carefully respected.

    -

    During operation ntpd measures and corrects for incidental clock frequency error and writes the current value to a file specified by the

    +

    During operation ntpd measures and corrects for incidental clock frequency error and occasionally writes the current value to a file specified by the

    driftfile /etc/ntp.drift

    -

    command in the configuration file. If ntpd is stopped and restarted, it initializes the frequency from this file. In this way the potentially lengthy interval to relearn the frequency error is avoided.

    +

    configuration command. If ntpd is stopped and restarted, it initializes the frequency from this file and avoids the potentially lengthy interval to relearn the correction.

    That's all there is to it, unless some problem in network connectivity or local operating system configuration occurs. The most common problem is some firewall between the workstation and server. System administrators should understand NTP uses UDP port 123 as both the source and destination port and that NTP does not involve any operating system interaction other than to set the system clock. While almost all modern Unix systems have included NTP and UDP port 123 defined in the services file, this should be checked if ntpd fails to come up at all.

    The best way to confirm NTP is working is using the ntpq utility, although the ntpdc utility may be useful in extreme cases. See the documentation pages for further information. Don't forget to check for system log messages. In the most extreme cases the -d option on the ntpd command line results in a blow-by-blow trace of the daemon operations. While the trace output can be cryptic, to say the least, it gives a general idea of what the program is doing and, in particular, details the arriving and departing packets and any errors found.

    diff --git a/html/rate.html b/html/rate.html index 0528b15ce..31249405e 100644 --- a/html/rate.html +++ b/html/rate.html @@ -11,9 +11,9 @@

    Rate Management and the Kiss-o'-Death Packet

    - giffrom Alice's Adventures in Wonderland, Lewis Carroll -

    Packet blizzard

    -

    Last update: 06:03 UTC Saturday, February 02, 2008

    + giffrom Pogo, Walt Kelly +

    Our junior managers and the administrators.

    +

    Last update: 02:39 UTC Monday, March 24, 2008


    Related Links

    @@ -24,35 +24,39 @@
  • Burst Control
  • Average Headway Time
  • Guard Time -
  • The Kiss-o'-Death Packet +
  • The Kiss-o'-Death Packet

    Introduction

    +

    This page describes the various rate management provisions in NTPv4. Details about the configuration commands and options are given on the Configuration Options page. Details about the cryptographic authentication schemes are given on the Authentication Options page. Details about the automatic server discovery schemes are described on the Automatic Server Discovery Schemes page. Additional information is available in the papers, reports, memoranda and briefings on the NTP Project page.

    Some national time metrology laboratories, including NIST and USNO, use the ntpd reference implementation in their very busy public time servers. They operate multiple servers behind load-balancing devices to support aggregate rates up to several thousand packets per second. The servers need to defend themselves against all manner of broken implementations that can clog the server and and network infrastructure. On the other hand, friendly ntpd clients need to avoid configurations that can result in unfriendly rates.

    There are several features in ntpd designed to defend the servers, clients and network against accidental or intentional flood attack. On the other hand these features are also used to insure ntpd is a good citizen, even if configured in unfriendly ways. The ground rules are:

    Rate management involves four algorithms to manage resources: (1) poll rate control, (2) burst control, (3) average headway time and (4) guard time. These are described in following sections.

    Poll Rate Control

    -

    In the ntpd design control of the poll interval is an intricate balance between nominal errors and network load. As a rule of thumb, the nominal errors double for a fourfold increase in poll interval. As the poll interval increases from 64 s to 1024 s, for example, the nominal errors ecrease by a factor of four. Nevertheless and unless the lowest possible nominal error is required, the well mannered NTP client should allow the interval to increase to the maximum when possible.

    -

    The poll interval is proportional to the time constant of the feedback loop which disciplines the system clock. The optimum time constant depends on the network time jitter and the clock oscillator frequency wander. Errors due to jitter are reduced as the time constant increases, while errors due to wander are decreased as the time constant decreases. The two error characteristics intersect at a point called the Allan intercept, which represents the ideal time constant. The ntpd poll interval algorithms slowly increases the poll interval when jitter dominates the error budget, but quickly reduces the interval when wander dominates it.

    -

    In ntpd the poll interval is represented in log2 s, so the actual values span the range 6-10. The algorithm uses a jiggle counter which operates over the range from -30 to +30 and is initialized at 0. If the measured offset is less than four times the measured average jitter, the counter is increased by the poll interval; if not, it is decreased by twice the poll interval. If the counter reaches +30, the poll interval is incremented by 1; if the counter reaches -30, the poll interval is decremented by 1. In either case the counter is set to 0.

    +

    Control of the poll interval is an intricate balance between expected acuracy and network load. The poll interval is constrained by the lower limit minpoll and upper limit maxpoll options of the server command and represented by the poll exponent in log2 s units. The limits default to 6 (64 s) and 10 (1024 s), respectively, which are appropriate for the vast majority of cases. The default limits can be changed with these options to a minimum set by the average option of the discard command (see below) to a maximum of 17 (36 h). Unless the best possible accuracy is required, the well mannered NTP client automatically increases the poll interval to the maximum when possible, whether or not the server is reachable. The current poll interval for each association is displayed by the ntpq program pe command. The global poll interval/time constant is displayed as the poll system variable by the rv command. The minimum global poll interval/time constant is displayed as the minpoll system variable by the rv command.

    +

    As a rule of thumb, the expected errors increase by a factor of two as the poll interval increases by a factor of four. The ntpd poll interval algorithm slowly increases the poll interval when jitter dominates the error budget, but quickly reduces the interval when wander dominates it. The algorithm uses a jiggle counter which operates over the range from -30 to +30 and is initialized at 0. If the measured offset is less than four times the measured average jitter, the counter is increased by the pollcurrent exponent; if not, it is decreased by twice the poll exponent. If the counter reaches +30, the poll exponent is incremented by 1; if the counter reaches -30, the exponent is decremented by 1. In either case the counter is set to 0.

    +

    The poll interval is proportional to the time constant of the feedback loop which disciplines the system clock. The optimum time constant depends on the network time jitter and the clock oscillator frequency wander. Errors due to jitter decrease as the time constant increases, while errors due to wander decrease as the time constant decreases. The two error characteristics intersect at a point called the Allan intercept, which represents the ideal time constant. With a compromise Allan intercept of 2000 s, the optimim poll interval is about 64 s, which corresponds to a poll exponent of 6.

    +

    There is normally no need to change the poll limits, as the poll interval is managed automatically as a function of prevailing jitter and wander. The most common exceptions are the following.

    +

    Burst Control

    -

    Occasionally it is necessary to send packets at intervals less than the poll interval. For instance, with the burst and iburst options, the poll algorithm sends a burst of several packets at 2-s intervals. The ntpd poll algorithm avoids sending needless packets if the server is not responding. If a burst is to be sent, the client sends only a single packet. When the first packet is received from the server, the client continues with the remaining packets in the burst. If the first packet is not received within 64 s, it will be sent again for two additional retries before giving up. The result is to minimize network load if the server is not responding.

    -

    For the iburst option the number of packets in the burst is six, which is the number normally needed to synchronize the clock; for the burst option, the number of packets in the burst is determined by the difference between the poll interval and the minimum poll interval set by the minpoll option of the server command. For instance, at a poll interval of 6 (64 s), only a single packet is sent for every poll, while the full number of eight packets is sent at poll intervals of 9 (512 s) or more.

    +

    Occasionally it is necessary to send packets at intervals less than the poll interval. For instance, with the burst and iburst options of the server command, the poll algorithm sends a burst of several packets at 2-s intervals. The ntpd poll algorithm avoids sending needless packets if the server is not responding. The client begins a burst with a single packet. When the first packet is received from the server, the client continues with the remaining packets in the burst. If the first packet is not received within 64 s, it will be sent again for two additional retries before beginning backoff. The result is to minimize network load if the server is not responding.

    +

    For the iburst option the number of packets in the burst is six, which is the number normally needed to synchronize the clock; for the burst option, the number of packets in the burst is determined by the difference between the poll interval and the minimum poll interval set by the minpoll option of the server command. For instance, with a poll exponent of 6 (64 s), only a single packet is sent for every poll, while the full number of eight packets is sent at poll intervals of 9 (512 s) or more.

    Average Headway Time

    -

    There are features in ntpd to manage the interval between one packet and the next. These features make use of a set of counters: an output counter for each client association and an input counter for each distinct client address. Each counter increments by a value called the headway when a packet is processed and decrements by one each second. The default headway in ntpd is 16 s, but this can be changed using the average option of the discard command.

    -

    If the iburst or burst options are present, the poll algorithm sends a burst of packets instead of a single packet at each poll opportunity. The NTPv4 specification requires that bursts contain no more than eight packets; so, starting from an output counter value of zero, the maximum counter value or ouput ceiling can be no more than eight times the minimum poll interval set by the minpoll option of the server command. However, if the burst starts with a counter value other than zero, there is a potential to exceed the ceiling. The poll algorithm avoids this by computing an additional headway time so that the next packet sent will not exceed the ceiling. Additional headway time can result from Autokey protocol operations. Designs such as this are often called leaky buckets.

    -

    The ntpd input packet routine uses a special list of entries, one for each distinct client address found. Each entry includes an IP address, input counter and time of the most recent arrival. The entries are ordered by time of arrival, most recent first. As each packet arrives, the IP source address is compared to the IP address in each entry in turn. If a match is found the entry is removed and inserted first on the list. If the IP source address does not match any entry, a new entry is created and inserted first, possibly discarding the last entry on the list if it is full. Observers will note this is the same algorithm used for page replacement in virtual memory systems.

    -

    In the virtual memory algorithm the entry of interest is the last, whereas here the entry of interest is the first. The input counter is decreased by the time since it was last referenced, but not below zero. If the value of the counter plus the headway is greater than the input ceiling set by the average option of the discard command, the packet is discarded. Otherwise, the counter is increased by the headway and the packet is processed. The result is, if the client maintains a maximum average headway not less than the input ceiling and transmits no more than eight packets in a burst, the input counter will not exceed the input ceiling.

    +

    There are two features in ntpd to manage the interval between one packet and the next. These features make use of a set of counters: a client output counter for each association and a server input counter for each distinct client address. Each counter increments by a value called the headway when a packet is processed and decrements by one each second. The default minimum average headway in ntpd is 8 s, but this can be changed using the average option of the discard command, but not less than 3 (8 s).

    +

    If the iburst or burst options are present, the poll algorithm sends a burst of packets instead of a single packet at each poll opportunity. The NTPv4 specification requires that bursts contain no more than eight packets; so, starting from an output counter value of zero, the maximum counter value or ouput ceiling can be no more than eight times the minimum poll interval set by the minpoll option of the server command. However, if the burst starts with a counter value other than zero, there is a potential to exceed the ceiling. The poll algorithm avoids this by computing an additional headway time so that the next packet sent will not exceed the ceiling. Additional headway time can result from Autokey protocol operations. Designs such as this are often called leaky buckets. The current headway is displayed as the headway peer variable by the ntpq rv command.

    +

    The ntpd input packet routine uses a special list of entries, one for each distinct client address found. Each entry includes an IP address, input counter and interval since the last packet arrival. The entries are ordered by interval from the smallest to the largest. As each packet arrives, the IP source address is compared to the IP address in each entry in turn. If a match is found the entry is removed and inserted first on the list. If the IP source address does not match any entry, a new entry is created and inserted first, possibly discarding the last entry on the list if it is full. Observers will note this is the same algorithm used for page replacement in virtual memory systems.

    +

    In the virtual memory algorithm the entry of interest is the last, whereas here the entry of interest is the first. The input counter is decreased by the interval since it was last referenced, but not below zero. If the value of the counter plus the headway is greater than the input ceiling set by the average option, the packet is discarded. Otherwise, the counter is increased by the headway and the packet is processed. The result is, if the client maintains a maximum average headway not less than the input ceiling and transmits no more than eight packets in a burst, the input counter will not exceed the ceiling.

    Guard Time

    -

    A review of past client abuse incidence shows the most frequent scenario is a broken client that attempts to send a number of packets at rates of one per second or more. There have been occasions where this abuse has persisted for days at a time. These scenarios are the most damaging, as they can threaten not only the victim server but the network infrastructure as well.

    -

    In the ntpd server design the minimum headway between the last packet received and the current packet is called the guard time. If the headway is less than the guard time, the packet is discarded. The guard time defaults to 2 s, but this can be changed using the minimum option of the discard ommand.

    -

    The Kiss-o'-Death Packet

    -

    As an optional feature ntpd can send a special packet called the Kiss-o'-Death (KoD) packet when either the average headway or guard time is violated. The KoD is a packet with leap bits 11, stratum 0 and reference ID field other than 0. In this case the reference ID field is a four-character ASCII string, called the kiss code, showing the reason for the KoD. The KoD is enabled by the limited kod options to the restrict command.

    -

    At present, only one kiss code RATE is used to tell the client to slow down. In order to make sure the client notices the KoD, the receive and transmit timestamps are set to the transmit timestamp of the client packet and all other fields left as in the client packet. Thus, even if the client ignores the KoD, it cannot do any useful time computations. KoDs themselves are rate limited in the same way as arriving packets in order to deflect a flood attack.

    -

    There is some controversy about the KoD provisions. The nature of the datagram service supporting NTP provides no way to throttle clients other than behaving badly. Clients are strongly advised to support the KoD, but there are no legal or societal statutes requiring it. The reference implementation responds to a KoD by temporarily increasing the ouptut counter and thus the headway.

    +

    A review of past client abuse incidence shows the most frequent scenario is a broken client that attempts to send a number of packets at rates of one per second or more. On one occasion due to a defective client design, over 750,000 clients fell into this mode. There have been occasions where this abuse has persisted for days at a time. These scenarios are the most damaging, as they can threaten not only the victim server but the network infrastructure as well.

    +

    In the ntpd design the minimum headway between the last packet received and the current packet is called the guard time. If the headway is less than the guard time, the packet is discarded. The guard time defaults to 2 s, but this can be changed using the minimum option of the discard ommand.

    +

    The Kiss-of-Death Packet

    +

    Ordinarily, packets denied service are simply dropped with no further action except incrementing statistics counters. Sometimes a more proactive response is needed to cause the client to slow down. A special packet format has been created for this purpose called the kiss-o'-death (KoD) packet. KoD packets have leap indicator 3, stratum 0 and the reference identifier set to a four-byte ASCII code. At present, only one code RATE is sent by the server if the limited and kod flags are set in the restrict command and the rate limit is exceeded.

    +

    A client receiving a KoD packet is expected to slow down; however, no explicit mechanism is specified in the protocol to do this. In the current reference implementation, the server sets the packet poll to the greater of (a) minimum average headway and (b) client packet poll. The client sets the peer poll field to the maximum of (a) minimum average headway and (b) server packet poll. For KoD packets (only), the minimum peer poll is clamped not less than the peer poll and the headway temporarily increased.

    +

    At present there is only one KoD packet with code RATE. In order to make sure the client notices the KoD, the receive and transmit timestamps are set to the transmit timestamp of the client packet and all other fields left as in the client packet. Thus, even if the client ignores the KoD, it cannot do any useful time computations. KoDs themselves are rate limited in the same way as arriving packets in order to deflect a flood attack.

    diff --git a/html/release.html b/html/release.html index a10a71abf..d75b5083f 100644 --- a/html/release.html +++ b/html/release.html @@ -12,8 +12,8 @@

    NTP Version 4 Release Notes

    giffrom Alice's Adventures in Wonderland, Lewis Carroll -

    The rabbit toots to make sure you read this

    -

    Last update: 19:47 UTC Tuesday, January 01, 2008

    +

    The rabbit toots to make sure you read this.

    +

    Last update: 16:10 UTC Sunday, March 02, 2008

    .

    NTP Version 4 Release Notes

    diff --git a/html/scripts/accopt.txt b/html/scripts/accopt.txt new file mode 100644 index 000000000..36d7333cb --- /dev/null +++ b/html/scripts/accopt.txt @@ -0,0 +1,5 @@ +document.write("

    Access Control Commands

    ") \ No newline at end of file diff --git a/html/scripts/authopt.txt b/html/scripts/authopt.txt new file mode 100644 index 000000000..b313ad637 --- /dev/null +++ b/html/scripts/authopt.txt @@ -0,0 +1,11 @@ +document.write("

    Authentication Commands

    ") \ No newline at end of file diff --git a/html/scripts/clockopt.txt b/html/scripts/clockopt.txt new file mode 100644 index 000000000..290ad4e8d --- /dev/null +++ b/html/scripts/clockopt.txt @@ -0,0 +1,5 @@ +document.write("

    Reference Clock Commands

    ") \ No newline at end of file diff --git a/html/scripts/command.txt b/html/scripts/command.txt index 8714cf69d..9d5f64b20 100644 --- a/html/scripts/command.txt +++ b/html/scripts/command.txt @@ -1,4 +1,5 @@ document.write("