From: Dave Hart Date: Tue, 13 Oct 2009 02:24:57 +0000 (+0000) Subject: Documentation updates for ntpq --oldrv, saveconfig, saveconfigdir, X-Git-Tag: NTP_4_2_5P232_RC~2^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=11b5ea68d063f2dcdf475fedf6a6f6db9d14ed28;p=thirdparty%2Fntp.git Documentation updates for ntpq --oldrv, saveconfig, saveconfigdir, ntpd -I -L and -M switches and interface/nic directive bk: 4ad3e4f9bMmhMyiIw5m9_YE3Ak5iXg --- diff --git a/ChangeLog b/ChangeLog index f86a5be54..aed621047 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,5 @@ +* Update documentation for ntpq --old-rv, saveconfig, saveconfigdir, + ntpd -I -L and -M, and interface/nic rules. (From Dave Hart) (4.2.5p231-RC) 2009/10/10 Released by Harlan Stenn * [Bug 1335] Broadcast client degraded by wildcard default change. (4.2.5p230-RC) 2009/10/09 Released by Harlan Stenn diff --git a/html/miscopt.html b/html/miscopt.html index ffcd0641f..dd51e2eec 100644 --- a/html/miscopt.html +++ b/html/miscopt.html @@ -49,8 +49,8 @@
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).
-
interface [listen | ignore | drop] [all | ipv4 | ipv6 | name | address[/prefixlen]]
-
This command controls which network addresses ntpd opens, and whether input is dropped without processing. The first parameter determines the action for addresses which match the second parameter. That parameter specifies a class of addresses, or a specific interface name, or an address. In the address case, prefixlen determines how many bits must match for this rule to apply. The ignore action prevents opening matching addresses, in contrast, drop causes ntpd to open the interface and drop all received packets without examination. Multiple interface commands can be used. The last rule which matches a particular address determines the action for it. The nic command is an alias for interface.
+
interface [listen | ignore | drop] [all | ipv4 | ipv6 | wildcard | name | address[/prefixlen]]
+
This command controls which network addresses ntpd opens, and whether input is dropped without processing. The first parameter determines the action for addresses which match the second parameter. That parameter specifies a class of addresses, or a specific interface name, or an address. In the address case, prefixlen determines how many bits must match for this rule to apply. ignore prevents opening matching addresses, drop causes ntpd to open the address and drop all received packets without examination. Multiple interface commands can be used. The last rule which matches a particular address determines the action for it. interface commands are disabled if any -I, --interface, -L, or --novirtualips command-line options are used. If none of those options are used and no interface actions are specified in the configuration file, all available network addresses are opened. The nic command is an alias for interface.
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.
@@ -66,6 +66,8 @@
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.
+
saveconfigdir directory_path
+
Specify the directory in which to write configuration snapshots requested with ntpq's saveconfig command. If saveconfigdir does not appear in the configuration file, saveconfig requests are rejected by ntpd.
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 ]
diff --git a/html/ntpd.html b/html/ntpd.html index 3f66daaca..450408bc6 100644 --- a/html/ntpd.html +++ b/html/ntpd.html @@ -105,10 +105,14 @@
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. +
-I [address | interface name] +
Open the network address given, or all the addresses associated with the given interface name. This option may appear multiple times. This option also implies not opening other addresses, except wildcard and localhost. This option is deprecated. Please consider using the configuration file interface command, which is more versatile.
-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 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. +
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 interfaces, defined as those with names containing a colon. This option is deprecated. Please consider using the configuration file interface command, which is more versatile.
-M
Raise scheduler precision to its maximum (1 msec) using timeBeginPeriod.  (Windows only)
-n diff --git a/html/ntpq.html b/html/ntpq.html index 45d72cc8b..4b06c42ca 100644 --- a/html/ntpq.html +++ b/html/ntpq.html @@ -23,7 +23,7 @@

Description

The ntpq utility program is used to monitor NTP daemon ntpd operations and determine performance. It uses the standard NTP mode 6 control message formats defined in Appendix B of the NTPv3 specification RFC1305. The same formats are used in NTPv4, although some of the variables have changed and new ones added. The description on this page is for the NTPv4 variables.

The program can be run either in interactive mode or controlled using command line arguments. Requests to read and write arbitrary variables can be assembled, with raw and pretty-printed output options being available. The ntpq can also obtain and print a list of peers in a common format by sending multiple queries to the server.

-

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

+

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

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

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.

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

@@ -43,6 +43,8 @@
Output all host addresses in dotted-quad numeric format rather than converting to the canonical host names.
-p
Print a list of the peers known to the server as well as a summary of their state. This is equivalent to the peers interactive command. +
--old-rv +
When querying a single variable, such as ntpq -c 'rv 0 version', precede the requested variable with a status line.

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.

@@ -189,8 +191,8 @@
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. -
saveconfig filename -
Write the current configuration, including any runtime modifications given with :config or config-from-file, to the ntpd host's file filename. A single period given for filename is shorthand for the startup configuration file. filename can use strftime() format specifiers to substitute the current date and time, for example, saveconfig ntp-%Y%m%d-%H%M%S.conf. The filename used is stored in system variable savedconfig. Authentication is required. +
saveconfig filename +
Write the current configuration, including any runtime modifications given with :config or config-from-file, to the ntpd host's file filename. This command will be rejected by the server unless saveconfigdir appears in the ntpd configuration file. filename can use strftime() format specifiers to substitute the current date and time, for example, saveconfig ntp-%Y%m%d-%H%M%S.conf. The filename used is stored in system variable savedconfig. Authentication is required.
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.

Status Words and Kiss Codes

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

Miscellaneous Commands

    \
  • logconfig - configure log file
    \
  • nic - alias for interface
    \
  • phone - specify modem phone numbers
    \ +
  • saveconfigdir - specify saveconfig directory
    \
  • setvar - set system variables
    \
  • tinker - modify sacred system parameters (dangerous)
    \
  • tos - modify service parameters
    \ diff --git a/ntpd/ntpdbase-opts.def b/ntpd/ntpdbase-opts.def index b2e04e2a0..21425556f 100644 --- a/ntpd/ntpdbase-opts.def +++ b/ntpd/ntpdbase-opts.def @@ -161,11 +161,16 @@ flag = { name = interface; value = I; arg-type = string; - descrip = "Listen on the specified interface or IP"; + descrip = "Listen on an interface name or address"; max = NOLIMIT; arg-name = iface; stack-arg; doc = <<- _EndOfDoc_ + Open the network address given, or all the addresses associated with the + given interface name. This option may appear multiple times. This option + also implies not opening other addresses, except wildcard and localhost. + This option is deprecated. Please consider using the configuration file + interface command, which is more versatile. _EndOfDoc_; }; @@ -201,9 +206,12 @@ flag = { flag = { name = novirtualips; value = L; - descrip = "Do not listen to virtual IPs"; + descrip = "Do not listen to virtual interfaces"; doc = <<- _EndOfDoc_ - Do not listen to virtual IPs. The default is to listen. + Do not listen to virtual interfaces, defined as those with + names containing a colon. This option is deprecated. Please + consider using the configuration file interface command, which + is more versatile. _EndOfDoc_; }; @@ -213,7 +221,9 @@ flag = { value = M; descrip = "Modify Multimedia Timer (Windows only)"; doc = <<- _EndOfDoc_ - Set the Windows Multimedia Timer to highest resolution. + Set the Windows Multimedia Timer to highest resolution. This + ensures the resolution does not change while ntpd is running, + avoiding timekeeping glitches associated with changes. _EndOfDoc_; };