From: Dave Hart Date: Sun, 11 Apr 2010 23:13:44 +0000 (+0000) Subject: Documentation updates for 4.2.7p22 changes and additions, updating X-Git-Tag: NTP_4_2_7P24~2^2~3^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d1f5aff1192fc414f149a8bdf4601f3879d04fb1;p=thirdparty%2Fntp.git Documentation updates for 4.2.7p22 changes and additions, updating ntpdc.html, ntpq.html, accopt.html, confopt.html, manyopt.html, miscopt.html, and miscopt.txt. Modify full MRU list preemption when full to match "discard monitor" documentation, by removing exception for count == 1. bk: 4bc257a8rNUmzaSA90ISm8cUxJ5Qmg --- diff --git a/ChangeLog b/ChangeLog index a391f0a28..4afcf1e80 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +* Documentation updates for 4.2.7p22 changes and additions, updating + ntpdc.html, ntpq.html, accopt.html, confopt.html, manyopt.html, + miscopt.html, and miscopt.txt. +* Modify full MRU list preemption when full to match "discard monitor" + documentation, by removing exception for count == 1. (4.2.7p23) 2010/04/04 Released by Harlan Stenn * [Bug 1516] unpeer by IP address fails, DNS name works. * [Bug 1517] ntpq and ntpdc should verify reverse DNS before use. diff --git a/html/accopt.html b/html/accopt.html index f1f8cb37b..3497d0118 100644 --- a/html/accopt.html +++ b/html/accopt.html @@ -24,7 +24,7 @@

The skunk watches for intruders and sprays.

Last update: -30-Sep-2009 17:16 +11-Apr-2010 22:57 UTC


@@ -72,7 +72,7 @@ restrict time.nist.gov # allow access
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 + that violate these limits are discarded. If, in addition, the kod flag is present, a kiss-o'-death packet is returned.
@@ -86,21 +86,27 @@ time) in log2 s with default 3.
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 +
Specify the probability of being recorded for packets that overflow the MRU list + size limit set by mru maxmem or mru maxdepth. This is a + performance optimization for servers with aggregate arrivals of 1000 packets per second or more.
-
restrict address [mask mask] [flag][...]
+
restrict default [flag][...]
+ restrict source [flag][...]
+ 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.
+ IPv4 or IPv6 numeric address form defaults to all mask bits on, 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 for IPv4 and address :: mask + :: for IPv6) is always the first entry in the list. + restrict default, with no mask option, modifies both IPv4 and IPv6 + default entries. restrict source configures a template restriction + automatically added at runtime for each association, whether configured, + ephemeral, or preemptible, and removed when the association is demobilized.
Some flags have the effect to deny service, some have the effect to enable service and some are conditioned by other flags. The flags. are @@ -124,9 +130,10 @@ time) in log2 s with default 3.
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. - If this flag is not present, packets that violate the rate limits are discarded.
+ If the kod flag is used in a restriction which does not have the limited + flag, no KoD responses will result. -
limited
+
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.
diff --git a/html/confopt.html b/html/confopt.html index 05847c2ee..f64b03b39 100644 --- a/html/confopt.html +++ b/html/confopt.html @@ -12,7 +12,7 @@ Walt Kelly

The chicken is getting configuration advice.

Last update: - 25-Nov-2009 4:46 + 11-Apr-2010 23:07


Related Links

@@ -78,11 +78,12 @@ Walt Kelly the address must match the address specified on the manycastserver command of one or more designated manycast servers.
pool
-
For type s messages (only) this command mobilizes a client mode association - for servers implementing the pool automatic server discovery scheme described - on the Association Management page. The address - is a DNS name in the form area.pool.ntp.org, where area is - a qualifier designating the server geographic area such as us or europe.
+
For type s addresses (only) this command mobilizes a pool client mode association + for the DNS name specified. The DNS name must resolve to one or more IPv4 or + IPv6 addresses. The pool automatic server discovery scheme is described on the + Automatic Server Discovery page. + www.pool.ntp.org describes a compatible pool + of public NTP servers.
unpeer
This command removes a previously configured association. An address or association ID can be used to identify the association. Either an IP address or DNS name can be used. This diff --git a/html/manyopt.html b/html/manyopt.html index a236f4fca..c747661c3 100644 --- a/html/manyopt.html +++ b/html/manyopt.html @@ -14,7 +14,7 @@ giffrom Alice's Adventures in Wonderland, Lewis Carroll

Make sure who your friends are.

Last update: - 25-Nov-2009 + 11-Apr-2010 23:09 UTC


Related Links

@@ -46,21 +46,34 @@

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 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 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 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 associations 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 future unicast client/server associations.

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 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 using the NTP mitigation algorithms.

+

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

+ mobilizes some or all of them, similar to the manycast discovery scheme, and casts + off the excess. Unlike manycastclient, cryptographic authentication is + not required. The pool scheme solicits a single server at a time, compared to + manycastclient which solicits all servers with a multicast TTL limit + simultaneously. Otherwise, the pool server discovery scheme operates as manycast + does.

+

The pool scheme is configured using one or pool commands with DNS names + indicating the pool from which to draw. 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. The NTP Pool + Project offers instructions on using the pool with the server + command, which is suboptimal but works with older versions of ntpd + predating the pool command. With recent ntpd, consider replacing the + multiple server commands in their example with a single pool + command.

- \ No newline at end of file + diff --git a/html/miscopt.html b/html/miscopt.html index 800a4f21f..6cfd0ca60 100644 --- a/html/miscopt.html +++ b/html/miscopt.html @@ -13,7 +13,7 @@ giffrom Pogo, Walt Kelly

We have three, now looking for more.

Last update: - 13-Nov-2009 19:08 + 11-Apr-2010 22:56 UTC


Related Links

@@ -27,9 +27,9 @@
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]
- 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. +
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 ntpq and ntpdc utility programs.
auth
Enables the server to synchronize with unconfigured peers only if the peer has been correctly authenticated using either public key or private key cryptography. The default for this flag is enable.
@@ -40,7 +40,10 @@
kernel
Enables the kernel time discipline, if available. The default for this flag is enable if support is available, otherwise disable.
monitor
-
Enables the monitoring facility. See the ntpdc program and the monlist command or further information. The default for this flag is enable.
+
Enables the monitoring facility. See the ntpq program and the monstats and + mrulist commands, as well as the Access Control Options for details. + The monitoring facility is also enabled by the presence of limited + in any restrict commands. The default for this flag is enable.
ntp
Enables time and frequency discipline. In effect, this switch opens and closes the feedback loop, which is useful for testing. The default for this flag is enable.
stats
@@ -60,10 +63,38 @@
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
+
logconfig=syncall +clockall
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.
+
mru [maxdepth count | maxmem kilobytes | mindepth count | maxage seconds | initalloc count | initmem kilobytes | incalloc count | incmem kilobytes]
+
Controls size limits of the monitoring facility Most Recently Used (MRU) list of client addresses, which is also used by the rate control facility. +
+
maxdepth count
+ maxmem kilobytes
+
Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes. The actual + limit will be up to incalloc entries or incmem kilobytes larger. As with all + of the mru options offered in units of entries or kilobytes, if both maxdepth + and maxmem are used, the last one used controls. The default is 1024 kilobytes.
+
mindepth count
+
Lower limit on the MRU list size. When the MRU list has fewer than mindepth entries, + existing entries are never removed to make room for newer ones, regardless of their age. + The default is 600 entries.
+
maxage seconds
+
Once the MRU list has mindepth entries and an additional client address is to be added + to the list, if the oldest entry was updated more than maxage seconds ago, that entry + is removed and its storage reused. If the oldest entry was updated more recently, the MRU list + is grown, subject to maxdepth/maxmem. The default is 64 seconds.
+
initalloc count
+ initmem kilobytes
+
Initial memory allocation at the time the monitoring facility is first enabled, in terms of + entries or kilobytes. The default is 4 kilobytes.
+
incalloc count
+ incmem kilobytes
+
Size of additional memory allocations when growing the MRU list, in entries or kilobytes. + The default is 4 kilobytes.
+
+
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.
saveconfigdir directory_path
diff --git a/html/ntpdc.html b/html/ntpdc.html index e56d341f0..cdb503ff5 100644 --- a/html/ntpdc.html +++ b/html/ntpdc.html @@ -13,7 +13,7 @@

ntpdc - special NTP query program

giffrom Alice's Adventures in Wonderland, Lewis Carroll

This program is a big puppy.

-

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

+

Last update: 20:17 UTC Sunday, April 11, 2010


More Help

@@ -122,7 +122,7 @@
ifreload
Force rescan of current system interfaces. Outputs interface statistics for interfaces that could possibly change. Marks unchanged interfaces with ., added interfaces with + and deleted interfaces with -.
monlist [ version ] -
Obtain and print traffic counts collected and maintained by the monitor facility. The version number should not normally need to be specified. +
Obtain and print traffic counts collected and maintained by the monitor facility. The version number should not normally need to be specified. At most, 600 entries are displayed by monlist. To display the entire MRU list, use the ntpq program's mrulist command.
clkbug clock_peer_address [...]
Obtain debugging information for a reference clock driver. This information is provided only by some clock drivers and is mostly undecodable without a copy of the driver source in hand.
diff --git a/html/ntpq.html b/html/ntpq.html index 38018d015..0c6ea58f1 100644 --- a/html/ntpq.html +++ b/html/ntpq.html @@ -14,7 +14,7 @@ giffrom Pogo, Walt Kelly

A typical NTP monitoring packet

Last update: - 05-Feb-2010 17:13 + 11-Apr-2010 20:18 UTC


More Help

@@ -145,6 +145,67 @@
Specify the key ID to use for write requests.
lassociations
Perform the same function as the associations command, execept display mobilized and unmobilized associations.
+
monstats
+
Display monitor facility statistics.
+
mrulist [limited | kod | mincount=count | laddr=localaddr | sort=sortorder | resany=hexmask | resall=hexmask]
+
Obtain and print traffic counts collected and maintained by the monitor facility. With the exception of + sort=sortorder, the options filter the list returned by ntpd. The limited + and kod options return only entries representing client addresses from which the last packet + received triggered either discarding or a KoD response. The mincount=count option filters entries + representing less than count packets. The laddr=localaddr option filters entries + for packets received on any local address other than localaddr. resany=hexmask and + resall=hexmask filter entries containing none or less than all, respectively, of the bits in + hexmask, which must begin with 0x.
The sortorder defaults to + lstint and may be any of addr, count, avgint, lstint, or any of + those preceded by a minus sign (hyphen) to reverse the sort order. The output columns are: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ColumnDescription
lstintInterval in s between the receipt of the most recent packet from this address and the completion of the + retrieval of the MRU list by ntpq.
avgintAverage interval in s between packets from this address.
rstrRestriction flags associated with this address. Most are copied unchanged from the matching restrict + command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this + address triggered a rate control response.
rRate control indicator, either a period, L or K for no rate control response, + rate limiting by discarding, or rate limiting with a KoD response, respectively.
mPacket mode. +
vPacket version number.
countPackets received from this address.
rportSource port of last packet from this address.
remote addressDNS name, numeric address, or address followed by claimed DNS name which + could not be verified in parentheses. +
+
mreadvar assocID assocID [ variable_name [ = value[ ... ]
mrv assocID assocID [ variable_name [ = value[ ... ]
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.
@@ -229,6 +290,8 @@ broadcast server, M: multicast server
Write the specified variables. If the assocID is zero, the variables are from the system variables name space, otherwise they are from the peer variables name space. The assocID is required, as the same name can occur in both spaces.
+
sysstats +
Print statistics counters maintained in the protocol module.

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.

diff --git a/html/scripts/miscopt.txt b/html/scripts/miscopt.txt index 3506c4d6b..49e7c586a 100644 --- a/html/scripts/miscopt.txt +++ b/html/scripts/miscopt.txt @@ -8,6 +8,7 @@ document.write("

Miscellaneous Commands