+* 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 <stenn@ntp.org>
* [Bug 1335] Broadcast client degraded by wildcard default change.
(4.2.5p230-RC) 2009/10/09 Released by Harlan Stenn <stenn@ntp.org>
</dd>
<dt id="includefile"><tt>includefile <i>includefile</i></tt></dt>
<dd>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 <tt>ntpd</tt> on multiple hosts, with (mostly) common options (e.g., a restriction list).</dd>
- <dt id="interface"><tt>interface [listen | ignore | drop] [all | ipv4 | ipv6 | <i>name</i> | <i>address</i>[/<i>prefixlen</i>]]</tt></dt>
- <dd>This command controls which network addresses <tt>ntpd</tt> 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, <tt><i>prefixlen</i></tt> determines how many bits must match for this rule to apply. The <tt>ignore</tt> action prevents opening matching addresses, in contrast, <tt>drop</tt> causes <tt>ntpd</tt> to open the interface and drop all received packets without examination. Multiple <tt>interface</tt> commands can be used. The last rule which matches a particular address determines the action for it. The <tt>nic</tt> command is an alias for <tt>interface</tt>.</dd>
+ <dt id="interface"><tt>interface [listen | ignore | drop] [all | ipv4 | ipv6 | wildcard | <i>name</i> | <i>address</i>[/<i>prefixlen</i>]]</tt></dt>
+ <dd>This command controls which network addresses <tt>ntpd</tt> 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, <tt><i>prefixlen</i></tt> determines how many bits must match for this rule to apply. <tt>ignore</tt> prevents opening matching addresses, <tt>drop</tt> causes <tt>ntpd</tt> to open the address and drop all received packets without examination. Multiple <tt>interface</tt> commands can be used. The last rule which matches a particular address determines the action for it. <tt>interface</tt> commands are disabled if any <a href="ntpd.html#--interface"><tt>-I</tt></a>, <a href="ntpd.html#--interface"><tt>--interface</tt></a>, <a href="ntpd.html#--novirtualips"><tt>-L</tt></a>, or <a href="ntpd.html#--novirtualips"><tt>--novirtualips</tt></a> command-line options are used. If none of those options are used and no <tt>interface</tt> actions are specified in the configuration file, all available network addresses are opened. The <tt>nic</tt> command is an alias for <tt>interface</tt>.</dd>
<dt id="leapfile"><tt>leapfile <i>leapfile</i></tt></dt>
<dd>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 <tt>ftp</tt> as the ASCII file <tt>pub/leap-seconds</tt>.</dd>
<dd>While not strictly a security function, the Autokey protocol provides means to securely retrieve the current or updated leapsecond values from a server.</dd>
<dd>This command specifies the location of an alternate log file to be used instead of the default system <tt>syslog</tt> facility. This is the same operation as the <tt>-l </tt>command line option.</dd>
<dt id="phone"><tt>phone <i>dial</i>1 <i>dial</i>2 ...</tt></dt>
<dd>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.</dd>
+ <dt id="saveconfigdir"><tt>saveconfigdir <i>directory_path</i></tt></dt>
+ <dd>Specify the directory in which to write configuration snapshots requested with <tt>ntpq</tt>'s <a href="ntpq.html#saveconfig">saveconfig</a> command. If <tt>saveconfigdir</tt> does not appear in the configuration file, saveconfig requests are rejected by ntpd.</dd>
<dt id="setvar"><tt>setvar <i>variable</i> [default]</tt></dt>
<dd>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 <tt><i>name</i> = <i>value</i></tt> is followed by the <tt>default</tt> keyword, the variable will be listed as part of the default system variables (<tt>ntpq rv</tt> 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 <tt>setvar</tt> mechanism. There are three special variables that contain the names of all variable of the same group. The <tt>sys_var_list</tt> holds the names of all system variables. The <tt>peer_var_list</tt> holds the names of all peer variables and the <tt>clock_var_list</tt> holds the names of the reference clock variables.</dd>
<dt id="tinker"><tt>tinker [ allan <i>allan</i> | dispersion <i>dispersion</i> | freq <i>freq</i> | huffpuff <i>huffpuff</i> | panic <i>panic</i> | step <i>step</i> | stepout <i>stepout</i> ]</tt></dt>
<dd>Normally, <tt>ntpd</tt> 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, <tt>ntpd</tt> will exit with a message to the system log. This option can be used with the <tt>-q</tt> and <tt>-x</tt> options. See the <tt>tinker</tt> command for other options.
<dt><tt>-i <i>jaildir</i></tt>
<dd>Chroot the server to the directory <i><tt>jaildir</tt></i>. 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 <tt>-u</tt> option.
+ <dt id="--interface"><tt>-I [<i>address</i> | <i>interface name</i>]</tt>
+ <dd>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 <a href="miscopt.html#interface">interface</a> command, which is more versatile.
<dt><tt>-k <i>keyfile</i></tt>
- <dd>Specify the name and path of the symmetric key file, default <tt>/etc/ntp.keys</tt>. This is the same operation as the <tt>keys <i>keyfile</i></tt> command.<dt><tt>-l <i>logfile</i></tt>
- <dd>Specify the name and path of the log file. The default is the system log file. This is the same operation as the <tt>logfile <i>logfile</i></tt> command.<dt><tt>-L</tt>
- <dd>Do not listen to virtual IPs. The default is to listen.
+ <dd>Specify the name and path of the symmetric key file, default <tt>/etc/ntp.keys</tt>. This is the same operation as the <tt>keys <i>keyfile</i></tt> command.
+ <dt><tt>-l <i>logfile</i></tt>
+ <dd>Specify the name and path of the log file. The default is the system log file. This is the same operation as the <tt>logfile <i>logfile</i></tt> command.
+ <dt id="--novirtualips"><tt>-L</tt>
+ <dd>Do not listen to virtual interfaces, defined as those with names containing a colon. This option is deprecated. Please consider using the configuration file <a href="miscopt.html#interface">interface</a> command, which is more versatile.
<dt><tt>-M</tt>
<dd>Raise scheduler precision to its maximum (1 msec) using timeBeginPeriod. (Windows only)
<dt><tt>-n</tt>
<h4>Description</h4>
<p>The <tt>ntpq</tt> utility program is used to monitor NTP daemon <tt>ntpd</tt> 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.</p>
<p>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 <tt>ntpq</tt> can also obtain and print a list of peers in a common format by sending multiple queries to the server.</p>
- <p>If one or more request options is included on the command line when <tt>ntpq</tt> 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, <tt>ntpq</tt> 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. <tt>ntpq</tt>will prompt for commands if the standard input is a terminal device.</p>
+ <p>If one or more request options is included on the command line when <tt>ntpq</tt> 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, <tt>ntpq</tt> 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. <tt>ntpq</tt> will prompt for commands if the standard input is a terminal device.</p>
<p><tt>ntpq</tt> 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. <tt>ntpq</tt> makes one attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable timeout time.</p>
<p>Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p>
<p>For examples and usage, see the <a href="debug.html">NTP Debugging Techniques</a> page.</p>
<dd>Output all host addresses in dotted-quad numeric format rather than converting to the canonical host names.
<dt><tt>-p</tt>
<dd>Print a list of the peers known to the server as well as a summary of their state. This is equivalent to the <tt>peers</tt> interactive command.
+ <dt><tt>--old-rv</tt>
+ <dd>When querying a single variable, such as <tt>ntpq -c 'rv 0 version'</tt>, precede the requested variable with a status line.
</dl>
<h4>Internal Commands</h4>
<p>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 <tt>></tt>, followed by a file name, to the command line. A number of interactive format commands are executed entirely within the <tt>ntpq</tt> program itself and do not result in NTP mode-6 requests being sent to a server. These are described following.</p>
<dt id="rv"><tt>readvar <i>assocID</i> <i>name</i> [ = <i>value</i> ] [,...]</tt><br>
<tt>rv <i>assocID</i> [ <i>name</i> ] [,...]</tt>
<dd>Display the specified variables. If the association ID is omitted or is given as zero, the variables are from the <a href="#system">system variables</a> name space, otherwise they are from the <a href="#peer">peer variables</a> 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.
- <dt><tt>saveconfig <i>filename</i></tt>
- <dd>Write the current configuration, including any runtime modifications given with <tt>:config</tt> or <tt>config-from-file</tt>, to the ntpd host's file <i>filename</i>. A single period given for <i>filename</i> is shorthand for the startup configuration file. <i>filename</i> can use strftime() format specifiers to substitute the current date and time, for example, <tt>saveconfig ntp-%Y%m%d-%H%M%S.conf</tt>. The filename used is stored in system variable <tt>savedconfig</tt>. Authentication is required.
+ <dt id="saveconfig"><tt>saveconfig <i>filename</i></tt>
+ <dd>Write the current configuration, including any runtime modifications given with <tt>:config</tt> or <tt>config-from-file</tt>, to the ntpd host's file <i>filename</i>. This command will be rejected by the server unless <a href="miscopt.html#saveconfigdir">saveconfigdir</a> appears in the <tt>ntpd</tt> configuration file. <i>filename</i> can use strftime() format specifiers to substitute the current date and time, for example, <tt>saveconfig ntp-%Y%m%d-%H%M%S.conf</tt>. The filename used is stored in system variable <tt>savedconfig</tt>. Authentication is required.
<dt><tt>writevar <i>assocID</i> <i>name</i> = <i>value</i> [,...]</tt>
<dd>Write the specified variables. If the association ID is omitted or is given as zero, the variables are from the <a href="#system">system variables</a> name space, otherwise they are from the <a href="#peer">peer variables</a> name space.</dl>
<h4 id="status">Status Words and Kiss Codes</h4>
<li class='inline'><a href='miscopt.html#logconfig'>logconfig - configure log file</a><br>\
<li class='inline'><a href='miscopt.html#interface'>nic - alias for interface</a><br>\
<li class='inline'><a href='miscopt.html#phone'>phone - specify modem phone numbers</a><br>\
+<li class='inline'><a href='miscopt.html#saveconfigdir'>saveconfigdir - specify saveconfig directory</a><br>\
<li class='inline'><a href='miscopt.html#setvar'>setvar - set system variables</a><br>\
<li class='inline'><a href='miscopt.html#tinker'>tinker - modify sacred system parameters (dangerous)</a><br>\
<li class='inline'><a href='miscopt.html#tos'>tos - modify service parameters</a><br>\
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_;
};
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_;
};
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_;
};
projects / thirdparty / ntp.git / commitdiff
