diff options
Diffstat (limited to 'usr.sbin/ntp/doc/ntpdc.8')
| -rw-r--r-- | usr.sbin/ntp/doc/ntpdc.8 | 811 |
1 files changed, 811 insertions, 0 deletions
diff --git a/usr.sbin/ntp/doc/ntpdc.8 b/usr.sbin/ntp/doc/ntpdc.8 new file mode 100644 index 0000000..74129c4 --- /dev/null +++ b/usr.sbin/ntp/doc/ntpdc.8 @@ -0,0 +1,811 @@ +.Dd October 21 2015 +.Dt NTPDC 8 User Commands +.Os +.\" EDIT THIS FILE WITH CAUTION (ntpdc-opts.mdoc) +.\" +.\" $FreeBSD$ +.\" +.\" It has been AutoGen-ed October 21, 2015 at 12:38:57 PM by AutoGen 5.18.5 +.\" From the definitions ntpdc-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntpdc +.Nd vendor-specific NTPD control program +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Op Ar value +.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc +[ host ...] +.Pp +.Sh DESCRIPTION +.Nm +is deprecated. +Please use +.Xr ntpq 8 instead \- it can do everything +.Nm +used to do, and it does so using a much more sane interface. +.Pp +.Nm +is a utility program used to query +.Xr ntpd 8 +about its +current state and to request changes in that state. +It uses NTP mode 7 control message formats described in the source code. +The program may +be run either in interactive mode or controlled using command line +arguments. +Extensive state and statistics information is available +through the +.Nm +interface. +In addition, nearly all the +configuration options which can be specified at startup using +ntpd's configuration file may also be specified at run time using +.Nm . +.Sh "OPTIONS" +.Bl -tag +.It Fl 4 , Fl \-ipv4 +Force IPv4 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv6. +.sp +Force DNS resolution of following host names on the command line +to the IPv4 namespace. +.It Fl 6 , Fl \-ipv6 +Force IPv6 DNS name resolution. +This option must not appear in combination with any of the following options: +ipv4. +.sp +Force DNS resolution of following host names on the command line +to the IPv6 namespace. +.It Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd +run a command and exit. +This option may appear an unlimited number of times. +.sp +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +.It Fl d , Fl \-debug\-level +Increase debug verbosity level. +This option may appear an unlimited number of times. +.sp +.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number +Set the debug verbosity level. +This option may appear an unlimited number of times. +This option takes an integer number as its argument. +.sp +.It Fl i , Fl \-interactive +Force ntpq to operate in interactive mode. +This option must not appear in combination with any of the following options: +command, listpeers, peers, showpeers. +.sp +Force ntpq to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input. +.It Fl l , Fl \-listpeers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary of +their state. This is equivalent to the 'listpeers' interactive command. +.It Fl n , Fl \-numeric +numeric host addresses. +.sp +Output all host addresses in dotted\-quad numeric format rather than +converting to the canonical host names. +.It Fl p , Fl \-peers +Print a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +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. +.It Fl s , Fl \-showpeers +Show a list of the peers. +This option must not appear in combination with any of the following options: +command. +.sp +Print a list of the peers known to the server as well as a summary +of their state. This is equivalent to the 'dmpeers' interactive command. +.It Fl \&? , Fl \-help +Display usage information and exit. +.It Fl \&! , Fl \-more\-help +Pass the extended usage information through a pager. +.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc +Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP +configuration file listed in the \fBOPTION PRESETS\fP section, below. +The command will exit after updating the config file. +.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts +Load options from \fIcfgfile\fP. +The \fIno\-load\-opts\fP form will disable the loading +of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early, +out of order. +.It Fl \-version Op Brq Ar v|c|n +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPDC_<option\-name>\fP or \fBNTPDC\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh USAGE +If one or more request options are included on the command line +when +.Nm +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, +.Nm +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. +The +.Nm +utility will prompt for +commands if the standard input is a terminal device. +.Pp +The +.Nm +utility uses NTP mode 7 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. +The +.Nm +utility makes +no attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. +.Pp +The operation of +.Nm +are specific to the particular +implementation of the +.Xr ntpd 8 +daemon and can be expected to +work only with this and maybe some previous versions of the daemon. +Requests from a remote +.Nm +utility which affect the +state of the local server must be authenticated, which requires +both the remote program and local server share a common key and key +identifier. +.Pp +Note that in contexts where a host name is expected, a +.Fl 4 +qualifier preceding the host name forces DNS resolution to the IPv4 namespace, +while a +.Fl 6 +qualifier forces DNS resolution to the IPv6 namespace. +Specifying a command line option other than +.Fl i +or +.Fl n +will cause the specified query (queries) to be sent to +the indicated host(s) immediately. +Otherwise, +.Nm +will +attempt to read interactive format commands from the standard +input. +.Ss "Interactive 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 +.Ql \&> , +followed by a file name, to the command line. +.Pp +A number of interactive format commands are executed entirely +within the +.Nm +utility itself and do not result in NTP +mode 7 requests being sent to a server. +These are described +following. +.Bl -tag -width indent +.It Ic \&? Ar command_keyword +.It Ic help Ar command_keyword +A +.Sq Ic \&? +will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Sq Ic \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Xr ntpq 8 +than this manual +page. +.It Ic delay Ar 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. +.It Ic host Ar hostname +Set the host to which future queries will be sent. +Hostname may +be either a host name or a numeric address. +.It Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +.Fl n +switch. +.It Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.It Ic quit +Exit +.Nm . +.It Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.It Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 8000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.El +.Ss "Control Message Commands" +Query commands result in NTP mode 7 packets containing requests for +information being sent to the server. +These are read\-only commands +in that they make no modification of the server configuration +state. +.Bl -tag -width indent +.It Ic listpeers +Obtains and prints a brief list of the peers for which the +server is maintaining state. +These should include all configured +peer associations as well as those peers whose stratum is such that +they are considered by the server to be possible future +synchronization candidates. +.It Ic peers +Obtains a list of peers for which the server is maintaining +state, along with a summary of that state. +Summary information +includes the address of the remote peer, the local interface +address (0.0.0.0 if a local address has yet to be determined), the +stratum of the remote peer (a stratum of 16 indicates the remote +peer is unsynchronized), the polling interval, in seconds, the +reachability register, in octal, and the current estimated delay, +offset and dispersion of the peer, all in seconds. +.Pp +The character in the left margin indicates the mode this peer +entry is operating in. +A +.Ql \&+ +denotes symmetric active, a +.Ql \&\- +indicates symmetric passive, a +.Ql \&= +means the +remote server is being polled in client mode, a +.Ql \&^ +indicates that the server is broadcasting to this address, a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&~ +denotes that the remote peer is sending broadcasts and a +.Ql \&* +marks the peer the server is currently synchronizing +to. +.Pp +The contents of the host field may be one of four forms. +It may +be a host name, an IP address, a reference clock implementation +name with its parameter or +.Fn REFCLK "implementation_number" "parameter" . +On +.Ic hostnames +.Cm no +only IP\-addresses +will be displayed. +.It Ic dmpeers +A slightly different peer summary list. +Identical to the output +of the +.Ic peers +command, except for the character in the +leftmost column. +Characters only appear beside peers which were +included in the final stage of the clock selection algorithm. +A +.Ql \&. +indicates that this peer was cast off in the falseticker +detection, while a +.Ql \&+ +indicates that the peer made it +through. +A +.Ql \&* +denotes the peer the server is currently +synchronizing with. +.It Ic showpeer Ar peer_address Oo Ar ... Oc +Shows a detailed display of the current peer variables for one +or more peers. +Most of these values are described in the NTP +Version 2 specification. +.It Ic pstats Ar peer_address Oo Ar ... Oc +Show per\-peer statistic counters associated with the specified +peer(s). +.It Ic clockstat Ar clock_peer_address Oo Ar ... Oc +Obtain and print information concerning a peer clock. +The +values obtained provide information on the setting of fudge factors +and other clock performance information. +.It Ic kerninfo +Obtain and print kernel phase\-lock loop operating parameters. +This information is available only if the kernel has been specially +modified for a precision timekeeping function. +.It Ic loopinfo Op Cm oneline | Cm multiline +Print the values of selected loop filter variables. +The loop +filter is the part of NTP which deals with adjusting the local +system clock. +The +.Sq offset +is the last offset given to the +loop filter by the packet processing code. +The +.Sq frequency +is the frequency error of the local clock in parts\-per\-million +(ppm). +The +.Sq time_const +controls the stiffness of the +phase\-lock loop and thus the speed at which it can adapt to +oscillator drift. +The +.Sq watchdog timer +value is the number +of seconds which have elapsed since the last sample offset was +given to the loop filter. +The +.Cm oneline +and +.Cm multiline +options specify the format in which this +information is to be printed, with +.Cm multiline +as the +default. +.It Ic sysinfo +Print a variety of system state variables, i.e., state related +to the local server. +All except the last four lines are described +in the NTP Version 3 specification, RFC\-1305. +.Pp +The +.Sq system flags +show various system flags, some of +which can be set and cleared by the +.Ic enable +and +.Ic disable +configuration commands, respectively. +These are +the +.Cm auth , +.Cm bclient , +.Cm monitor , +.Cm pll , +.Cm pps +and +.Cm stats +flags. +See the +.Xr ntpd 8 +documentation for the meaning of these flags. +There +are two additional flags which are read only, the +.Cm kernel_pll +and +.Cm kernel_pps . +These flags indicate +the synchronization status when the precision time kernel +modifications are in use. +The +.Sq kernel_pll +indicates that +the local clock is being disciplined by the kernel, while the +.Sq kernel_pps +indicates the kernel discipline is provided by the PPS +signal. +.Pp +The +.Sq stability +is the residual frequency error remaining +after the system frequency correction is applied and is intended for +maintenance and debugging. +In most architectures, this value will +initially decrease from as high as 500 ppm to a nominal value in +the range .01 to 0.1 ppm. +If it remains high for some time after +starting the daemon, something may be wrong with the local clock, +or the value of the kernel variable +.Va kern.clockrate.tick +may be +incorrect. +.Pp +The +.Sq broadcastdelay +shows the default broadcast delay, +as set by the +.Ic broadcastdelay +configuration command. +.Pp +The +.Sq authdelay +shows the default authentication delay, +as set by the +.Ic authdelay +configuration command. +.It Ic sysstats +Print statistics counters maintained in the protocol +module. +.It Ic memstats +Print statistics counters related to memory allocation +code. +.It Ic iostats +Print statistics counters maintained in the input\-output +module. +.It Ic timerstats +Print statistics counters maintained in the timer/event queue +support code. +.It Ic reslist +Obtain and print the server's restriction list. +This list is +(usually) printed in sorted order and may help to understand how +the restrictions are applied. +.It Ic monlist Op Ar version +Obtain and print traffic counts collected and maintained by the +monitor facility. +The version number should not normally need to be +specified. +.It Ic clkbug Ar clock_peer_address Oo Ar ... Oc +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. +.El +.Ss "Runtime Configuration Requests" +All requests which cause state changes in the server are +authenticated by the server using a configured NTP key (the +facility can also be disabled by the server by not configuring a +key). +The key number and the corresponding key must also be made +known to +.Nm . +This can be done using the +.Ic keyid +and +.Ic passwd +commands, the latter of which will prompt at the terminal for a +password to use as the encryption key. +You will also be prompted +automatically for both the key number and password the first time a +command which would result in an authenticated request to the +server is given. +Authentication not only provides verification that +the requester has permission to make such changes, but also gives +an extra degree of protection again transmission errors. +.Pp +Authenticated requests always include a timestamp in the packet +data, which is included in the computation of the authentication +code. +This timestamp is compared by the server to its receive time +stamp. +If they differ by more than a small amount the request is +rejected. +This is done for two reasons. +First, it makes simple +replay attacks on the server, by someone who might be able to +overhear traffic on your LAN, much more difficult. +Second, it makes +it more difficult to request configuration changes to your server +from topologically remote hosts. +While the reconfiguration facility +will work well with a server on the local host, and may work +adequately between time\-synchronized hosts on the same LAN, it will +work very poorly for more distant hosts. +As such, if reasonable +passwords are chosen, care is taken in the distribution and +protection of keys and appropriate source address restrictions are +applied, the run time reconfiguration facility should provide an +adequate level of security. +.Pp +The following commands all make authenticated requests. +.Bl -tag -width indent +.It Xo Ic addpeer Ar peer_address +.Op Ar keyid +.Op Ar version +.Op Cm prefer +.Xc +Add a configured peer association at the given address and +operating in symmetric active mode. +Note that an existing +association with the same peer may be deleted when this command is +executed, or may simply be converted to conform to the new +configuration, as appropriate. +If the optional +.Ar keyid +is a +nonzero integer, all outgoing packets to the remote server will +have an authentication field attached encrypted with this key. +If +the value is 0 (or not given) no authentication will be done. +The +.Ar version +can be 1, 2 or 3 and defaults to 3. +The +.Cm prefer +keyword indicates a preferred peer (and thus will +be used primarily for clock synchronisation if possible). +The +preferred peer also determines the validity of the PPS signal \- if +the preferred peer is suitable for synchronisation so is the PPS +signal. +.It Xo Ic addserver Ar peer_address +.Op Ar keyid +.Op Ar version +.Op Cm prefer +.Xc +Identical to the addpeer command, except that the operating +mode is client. +.It Xo Ic broadcast Ar peer_address +.Op Ar keyid +.Op Ar version +.Op Cm prefer +.Xc +Identical to the addpeer command, except that the operating +mode is broadcast. +In this case a valid key identifier and key are +required. +The +.Ar peer_address +parameter can be the broadcast +address of the local network or a multicast group address assigned +to NTP. +If a multicast address, a multicast\-capable kernel is +required. +.It Ic unconfig Ar peer_address Oo Ar ... Oc +This command causes the configured bit to be removed from the +specified peer(s). +In many cases this will cause the peer +association to be deleted. +When appropriate, however, the +association may persist in an unconfigured mode if the remote peer +is willing to continue on in this fashion. +.It Xo Ic fudge Ar peer_address +.Op Cm time1 +.Op Cm time2 +.Op Ar stratum +.Op Ar refid +.Xc +This command provides a way to set certain data for a reference +clock. +See the source listing for further information. +.It Xo Ic enable +.Oo +.Cm auth | Cm bclient | +.Cm calibrate | Cm kernel | +.Cm monitor | Cm ntp | +.Cm pps | Cm stats +.Oc +.Xc +.It Xo Ic disable +.Oo +.Cm auth | Cm bclient | +.Cm calibrate | Cm kernel | +.Cm monitor | Cm ntp | +.Cm pps | Cm stats +.Oc +.Xc +These commands operate in the same way as the +.Ic enable +and +.Ic disable +configuration file commands of +.Xr ntpd 8 . +.Bl -tag -width indent +.It Cm 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. +.It Cm bclient +Enables the server to listen for a message from a broadcast or +multicast server, as in the multicastclient command with +default address. +The default for this flag is disable. +.It Cm calibrate +Enables the calibrate feature for reference clocks. +The default for this flag is disable. +.It Cm kernel +Enables the kernel time discipline, if available. +The default for this flag is enable if support is available, otherwise disable. +.It Cm monitor +Enables the monitoring facility. +See the documentation here about the +.Cm monlist +command or further information. +The default for this flag is enable. +.It Cm 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. +.It Cm pps +Enables the pulse\-per\-second (PPS) signal when frequency +and time is disciplined by the precision time kernel modifications. +See the +.Qq A Kernel Model for Precision Timekeeping +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) +page for further information. +The default for this flag is disable. +.It Cm stats +Enables the statistics facility. +See the +.Sx Monitoring Options +section of +.Xr ntp.conf 5 +for further information. +The default for this flag is disable. +.El +.It Xo Ic restrict Ar address Ar mask +.Ar flag Oo Ar ... Oc +.Xc +This command operates in the same way as the +.Ic restrict +configuration file commands of +.Xr ntpd 8 . +.It Xo Ic unrestrict Ar address Ar mask +.Ar flag Oo Ar ... Oc +.Xc +Unrestrict the matching entry from the restrict list. +.It Xo Ic delrestrict Ar address Ar mask +.Op Cm ntpport +.Xc +Delete the matching entry from the restrict list. +.It Ic readkeys +Causes the current set of authentication keys to be purged and +a new set to be obtained by rereading the keys file (which must +have been specified in the +.Xr ntpd 8 +configuration file). +This +allows encryption keys to be changed without restarting the +server. +.It Ic trustedkey Ar keyid Oo Ar ... Oc +.It Ic untrustedkey Ar keyid Oo Ar ... Oc +These commands operate in the same way as the +.Ic trustedkey +and +.Ic untrustedkey +configuration file +commands of +.Xr ntpd 8 . +.It Ic authinfo +Returns information concerning the authentication module, +including known keys and counts of encryptions and decryptions +which have been done. +.It Ic traps +Display the traps set in the server. +See the source listing for +further information. +.It Xo Ic addtrap Ar address +.Op Ar port +.Op Ar interface +.Xc +Set a trap for asynchronous messages. +See the source listing +for further information. +.It Xo Ic clrtrap Ar address +.Op Ar port +.Op Ar interface +.Xc +Clear a trap for asynchronous messages. +See the source listing +for further information. +.It Ic reset +Clear the statistics counters in various modules of the server. +See the source listing for further information. +.El +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "FILES" +See \fBOPTION PRESETS\fP for configuration files. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 " (EXIT_SUCCESS)" +Successful program execution. +.It 1 " (EXIT_FAILURE)" +The operation failed or the command syntax was not valid. +.It 66 " (EX_NOINPUT)" +A specified configuration file could not be loaded. +.It 70 " (EX_SOFTWARE)" +libopts had an internal operational error. Please report +it to autogen\-users@lists.sourceforge.net. Thank you. +.El +.Sh "SEE ALSO" +.Xr ntp.conf 5 , +.Xr ntpd 8 +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 3) +.%O RFC1305 +.Re +.Sh AUTHORS +The formatting directives in this document came from FreeBSD. +.Sh "COPYRIGHT" +Copyright (C) 1992\-2015 The University of Delaware and Network Time Foundation all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. +.Sh BUGS +The +.Nm +utility is a crude hack. +Much of the information it shows is +deadly boring and could only be loved by its implementer. +The +program was designed so that new (and temporary) features were easy +to hack in, at great expense to the program's ease of use. +Despite +this, the program is occasionally useful. +.Pp +Please report bugs to http://bugs.ntp.org . +.Pp +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.Sh "NOTES" +This manual page was \fIAutoGen\fP\-erated from the \fBntpdc\fP +option definitions. |
