From 06e27b20828af1ec7ef81a70b3f328c79e6a48c8 Mon Sep 17 00:00:00 2001 From: sheldonh Date: Wed, 12 Jan 2000 14:41:00 +0000 Subject: Add selected manual pages transcribed from the HTML documentation. Those pages which have not been transcribed are referenced as gracefully as possible. There is no perfect section for the ntp_* files, which document configuration options for the NTP suite, so I'm putting them in the same section as the pages for the utilities themselves. --- usr.sbin/ntp/doc/Makefile | 3 + usr.sbin/ntp/doc/ntp_acc.8 | 205 ++++++++++++ usr.sbin/ntp/doc/ntp_auth.8 | 419 +++++++++++++++++++++++++ usr.sbin/ntp/doc/ntp_clock.8 | 302 ++++++++++++++++++ usr.sbin/ntp/doc/ntp_conf.8 | 396 ++++++++++++++++++++++++ usr.sbin/ntp/doc/ntp_misc.8 | 180 +++++++++++ usr.sbin/ntp/doc/ntp_mon.8 | 298 ++++++++++++++++++ usr.sbin/ntp/doc/ntpd.8 | 278 +++++++++++++++++ usr.sbin/ntp/doc/ntpdate.8 | 231 ++++++++++++++ usr.sbin/ntp/doc/ntpdc.8 | 721 +++++++++++++++++++++++++++++++++++++++++++ usr.sbin/ntp/doc/ntpq.8 | 588 +++++++++++++++++++++++++++++++++++ usr.sbin/ntp/doc/ntptime.8 | 68 ++++ usr.sbin/ntp/doc/ntptrace.8 | 73 +++++ 13 files changed, 3762 insertions(+) create mode 100644 usr.sbin/ntp/doc/ntp_acc.8 create mode 100644 usr.sbin/ntp/doc/ntp_auth.8 create mode 100644 usr.sbin/ntp/doc/ntp_clock.8 create mode 100644 usr.sbin/ntp/doc/ntp_conf.8 create mode 100644 usr.sbin/ntp/doc/ntp_misc.8 create mode 100644 usr.sbin/ntp/doc/ntp_mon.8 create mode 100644 usr.sbin/ntp/doc/ntpd.8 create mode 100644 usr.sbin/ntp/doc/ntpdate.8 create mode 100644 usr.sbin/ntp/doc/ntpdc.8 create mode 100644 usr.sbin/ntp/doc/ntpq.8 create mode 100644 usr.sbin/ntp/doc/ntptime.8 create mode 100644 usr.sbin/ntp/doc/ntptrace.8 (limited to 'usr.sbin/ntp') diff --git a/usr.sbin/ntp/doc/Makefile b/usr.sbin/ntp/doc/Makefile index aeb1667..1d80540 100644 --- a/usr.sbin/ntp/doc/Makefile +++ b/usr.sbin/ntp/doc/Makefile @@ -17,6 +17,9 @@ HTMLS= accopt.htm assoc.htm authopt.htm biblio.htm build.htm clockopt.htm \ pps.htm prefer.htm quick.htm rdebug.htm refclock.htm release.htm \ tickadj.htm vxworks.htm y2k.htm +MAN8= ntp_acc.8 ntp_auth.8 ntp_clock.8 ntp_conf.8 ntp_misc.8 \ + ntp_mon.8 ntpd.8 ntpdate.8 ntpdc.8 ntpq.8 ntptime.8 ntptrace.8 + beforeinstall: .for file in ${HTMLS} cd ${.CURDIR}/../../../contrib/ntp/html ; \ diff --git a/usr.sbin/ntp/doc/ntp_acc.8 b/usr.sbin/ntp/doc/ntp_acc.8 new file mode 100644 index 0000000..e9aea46 --- /dev/null +++ b/usr.sbin/ntp/doc/ntp_acc.8 @@ -0,0 +1,205 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 12, 2000 +.Dt NTP_ACC 8 +.Os +.Sh NAME +.Nm ntp_acc +.Nd NTP daemon access control options +.Sh SYNOPSIS +.Pa /etc/ntp.conf +.Sh DESCRIPTION +.Xr ntpd 8 +implements a general purpose +address-and-mask based restriction list. +The list is sorted by address and by mask, +and the list is searched in this order for matches, +with the last match found +defining the restriction flags associated with the incoming packets. +The source address of incoming packets is used for the match, +with the 32-bit address being AND'ed with the mask +associated with the restriction entry +and then compared with the entry's address +(which has also been AND'ed with the mask) +to look for a match. +Additional information and examples can be found in the +.Qo +Notes on Configuring NTP and Setting up a NTP Subnet +.Qc +page +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) . +.Pp +The restriction facility was implemented +in conformance with the access policies +for the original NSFnet backbone time servers. +While this facility may be otherwise useful +for keeping unwanted or broken remote time servers +from affecting your own, +it should not be considered an alternative +to the standard NTP authentication facility. +Source address based restrictions are easily circumvented +by a determined cracker. +.Ss Access Control Commands +The following access control commands are available: +.Bl -tag -width indent +.It Xo Ic restrict +.Ar numeric_address +.Op mask Ar numeric_mask +.Op Ar flag +.Op ... +.Xc +The +.Ar numeric_address +argument, expressed in dotted-quad form, +is the address of an host or network. +The +.Ar numeric_mask +argument, also expressed in dotted-quad form, +defaults to 255.255.255.255, +meaning that the +.Ar numeric_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, given the sort algorithm, +is always the first entry in the list. +Note that, while +.Ar numeric_address +is normally given in dotted-quad format, +the text string default, with no mask option, +may be used to indicate the default entry. +.Pp +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: +.Bl -tag -width indent +.It ignore +Ignore all packets from hosts which match this entry. +If this flag is specified neither queries +nor time server polls will be responded to. +.It noquery +Ignore all NTP mode 6 and 7 packets +(i.e. information queries and configuration requests) +from the source. +Time service is not affected. +.It nomodify +Ignore all NTP mode 6 and 7 packets +which attempt to modify the state of the server +(i.e. run time reconfiguration). +Queries which return information are permitted. +.It notrap +Decline to provide mode 6 control message trap service +to matching hosts. +The trap service is a subsystem +of the mode 6 control message protocol +which is intended for use by remote event logging programs. +.It 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. +.It noserve +Ignore NTP packets whose mode is other than 6 or 7. +In effect, +time service is denied, +though queries may still be permitted. +.It nopeer +Provide stateless time service to polling hosts, +but do not allocate peer memory resources to these hosts +even if they otherwise might be considered useful +as future synchronization partners. +.It notrust +Treat these hosts normally in other respects, +but never use them as synchronization sources. +.It limited +These hosts are subject to limitation +of number of clients from the same net. +Net in this context refers to the IP notion of net +(class A, class B, class C, etc.). +Only the first +.Va client_limit +hosts (see below) that have shown up at the server +and that have been active during the last +.Va client_limit_period +seconds (see below) are accepted. +Requests from other clients from the same net are rejected. +Only time request packets are taken into account. +Query packets sent by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +programs are not subject to these limits. +A history of clients is kept using the monitoring capability of +.Xr ntpd 8 . +Thus, monitoring is always active +as long as there is a restriction entry with the limited flag. +.It 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. +.El +.Pp +Default restriction list entries, +with the flags ignore and ntpport, +for each of the local host's interface addresses +are inserted into the table at startup +to prevent the server from attempting to synchronize +to its own time. +A default entry is also always present, +unless if it is otherwise unconfigured; +no flags are associated with the default entry +(i.e. everything besides your own NTP server is unrestricted). +.It clientlimit Ar limit +Set the +.Va client_limit +variable, +which limits the number of simultaneous access-controlled clients. +The default value for this variable is 3. +.It clientperiod Ar period +Set the +.Va client_limit_period +variable, +which specifies the number of seconds +after which a client is considered inactive +and thus no longer is counted for client limit restriction. +The default value for this variable is 3600 seconds. +.El +.Sh SEE ALSO +.Xr ntp_conf 8 , +.Xr ntpd 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.Pp +In addition to the manual pages provided, +comprehensive documentation is available on the world wide web +at +.Li http://www.ntp.org/ . +A snapshot of this documentation is available in HTML format in +.Pa /usr/share/doc/ntp . +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto. +Text amended by +.An David Mills +at the University of Delaware. diff --git a/usr.sbin/ntp/doc/ntp_auth.8 b/usr.sbin/ntp/doc/ntp_auth.8 new file mode 100644 index 0000000..5fbe299 --- /dev/null +++ b/usr.sbin/ntp/doc/ntp_auth.8 @@ -0,0 +1,419 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 11, 2000 +.Dt NTP_AUTH 8 +.Os +.Sh NAME +.Nm ntp_auth +.Nd NTP daemon authentication options +.Sh SYNOPSIS +.Pa /etc/ntp.conf +.Sh DESCRIPTION +Authentication support allows the NTP client to verify +that the server is in fact known and trusted +and not an intruder intending accidentally +or on purpose to masquerade as that server. +The NTPv3 specification RFC 1305 defines a scheme +which provides cryptographic authentication of received NTP packets. +Originally, this was done using the Data Encryption Standard (DES) +operating in Cipher Block Chaining (CBC) mode, +commonly called DES-CBC. +Subsequently, this was augmented by the RSA Message Digest 5 (MD5) +using a private key, commonly called keyed-MD5. +Either algorithm computes a message digest, or one-way hash, +which can be used to verify the server has the correct private key +and key identifier. +NTPv4 retains this scheme and, in addition, +provides a new autokey scheme based on reverse hashing +and public key cryptography. +Authentication can be configured separately for each association +using the key or autokey subcommands on the +.Ic peer Ns , +.Ic server Ns , +.Ic broadcast +and +.Ic manycastclient +commands as described in the +.Xr ntp_conf 8 +page. +.Pp +The authentication options specify the suite of keys, +select the key for each configured association +and manage the configuration operations, +as described below. +The auth flag which controls these functions +can be set or reset by the +.Ic enable and +.Ic disable +configuration commands and also by remote configuration commands +sent by a +.Xr ntpdc 8 +program running in another machine. +If this flag is set, persistent peer associations +and remote configuration commands are effective +only if cryptographically authenticated. +If this flag is disabled, +these operations are effective +even if not cryptographic authenticated. +It should be understood that operating in the latter mode +invites a significant vulnerability +where a rogue hacker can seriously disrupt client operations. +.Pp +The auth flag affects all authentication procedures described below; +however, it operates differently +if cryptographic support is compiled in the distribution. +If this support is available and the flag is enabled, +then persistent associations are mobilized +and remote configuration commands are effective +only if successfully authenticated. +If the support is unavailable and the flag is enabled, +then it is not possible under any conditions +to mobilize persistent associations +or respond to remote configuration commands. +The auth flag normally defaults to set +if cryptographic support is available and to reset otherwise. +.Pp +With the above vulnerabilities in mind, +it is desirable to set the auth flag in all cases. +One aspect which is often confusing +is the name resolution process +which maps server names in the configuration file to IP addresses. +In order to protect against bogus name server messages, +this process is authenticated +using an internally generated key +which is normally invisible to the user. +However, if cryptographic support is unavailable +and the auth flag is enabled, +the name resolution process will fail. +This can be avoided +either by specifying IP addresses instead of host names, +which is generally inadvisable, +or by leaving the flag disabled +and enabling it once the name resolution process is complete. +.Pp +Following is a description +of the two available cryptographic authentication schemes. +.Bl -tag -width indent +.It Private Key Scheme +The original RFC 1305 specification allows any one of possibly +65,536 keys, each distinguished a 32-bit key identifier, +to authenticate an association. +The servers involved must agree on the key +and key identifier to authenticate their messages. +Keys and related information are specified in a key file, +usually called +.Pq ntp.keys +which should be exchanged and stored using secure procedures +beyond the scope of the NTP protocol itself. +Besides the keys used for ordinary NTP associations, +additional ones can be used as passwords for the +.Xr ntpq 8 +and +.Xr ntpdc 8 +utility programs. +.Pp +When +.Xr ntpd 8 +is first started, +it reads the key file and installs the keys in the key cache. +However, the keys must be activated +before they can be used with the trusted command. +This allows, for instance, +the installation of possibly several batches of keys +and then activating or inactivating each batch remotely using +.Xr ntpdc 8 . +This also provides a revocation capability +that can be used if a key becomes compromised. +The +.Ic requestkey +command selects the key used as the password for the +.Xr ntpdc 8 +utility, +while the +.Ic controlkey +command selects the key used as the password for the the +.Xr ntpq 8 +utility. +.It Autokey Scheme +The original NTPv3 authentication scheme +described in RFC 1305 continues to be supported. +In NTPv4, +an additional authentication scheme called autokey is available. +It operates much like the S-KEY scheme, +in that a session key list is constructed +and the entries used in reverse order. +A description of the scheme, +along with a comprehensive security analysis, +is contained in a technical report +available from the IETF web page +.Li http://www.ietf.org/ . +.Pp +The autokey scheme is specifically designed for multicast modes, +where clients normally do not send messages to the server. +In these modes, +the server uses the scheme to generate a key list +by repeated hashing of a secret value. +The list is used in reverse order +to generate a unique session key for each message sent. +The client regenerates the session key +and verifies the hash matches the previous session key. +Each message contains the public values +binding the session key to the secret value, +but these values need to be verified +only when the server generates a new key list +or more than four server messages have been lost. +.Pp +The scheme is appropriate for client/server +and symmetric-peer modes as well. +In these modes, +the client generates a session key as in multicast modes. +The server regenerates the session key +and uses it to formulates a reply using its own public values. +The client verifies +the key identifier of the reply matches the request, +verifies the public values and validates the message. +In peer mode, each peer independently generates a key list +and operates as in the multicast mode. +.Pp +The autokey scheme requires no change to the NTP packet header format +or message authentication code (MAC), which is appended to the header; +however, if autokey is in use, an extensions field is inserted +between the header and MAC. +The extensions field contains a random public value +which is updated at intervals specified by the revoke command, +together with related cryptographic values +used in the signing algorithm. +The format of the extensions field is defined in +Internet Draft +.Li draft-NTP-auth-coexist-00.txt . +The MAC itself is constructed in the same way as NTPv3, +but using the original NTP header +and the extensions field padded to a 64-bit boundary. +Each new public value is encrypted by the host private value. +It is the intent of the design, not yet finalized, +that the public value, encrypted public value, +public key and certificate be embedded in the extensions field +where the client can decrypt as needed. +However, the relatively expensive encryption +and decryption operations are necessary +only when the public value is changed. +.Pp +Note that both the original NTPv3 authentication scheme +and the new NTPv4 autokey scheme +operate separately for each configured association, +so there may be several session key lists +operating independently at the same time. +Since all keys, including session keys, +occupy the same key cache, +provisions have been made to avoid collisions, +where some random roll happens to collide +with another already generated. +Since something like four billion different session key identifiers +are available, +the chances are small that this might happen. +If it happens during generation, +the generator terminates the current session key list. +By the time the next list is generated, +the collided key will probably have been expired or revoked. +.Pp +While permanent keys have lifetimes that expire +only when manually revoked, +random session keys have a lifetime +specified at the time of generation. +When generating a key list for an association, +the lifetime of each key is set to expire +one poll interval later than it is scheduled to be used. +The maximum lifetime of any key in the list +is specified by the +.Ic autokey +command. +Lifetime enforcement is a backup +to the normal procedure that revokes the last-used key +at the time the next key on the key list is used. +.El +.Ss Authentication Commands +The following authentication commands are available: +.Bl -tag -width indent +.It Ic keys Ar keyfile +Specifies the file name containing the encryption keys and +key identifiers used by +.Xr ntpd 8 , +.Xr ntpq 8 +and +.Xr ntpdc 8 +when operating in authenticated mode. +The format of this file is described later in this document. +.It Xo Ic trustedkey +.Ar key +.Op ... +.Xc +Specifies the encryption key identifiers which are trusted +for the purposes of authenticating peers +suitable for synchronization, as well as keys used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +programs. +The authentication procedures require that +both the local and remote servers share the same key +and key identifier for this purpose, +although different keys can be used with different servers. +The +.Ar trustedkey +arguments are 32-bit unsigned integers +with values less than 65,536. +Note that NTP key 0 is used to indicate an invalid key +and/or key identifier, +so should not be used for any other purpose. +.It Ic requestkey Ar key +Specifies the key identifier to use with the +.Xr ntpdc 8 +program, +which uses a proprietary protocol +specific to this implementation of +.Xr ntpd 8 . +This program is useful to diagnose and repair problems +that affect +.Xr ntpd 8 +operation. +The +.Ar key +argument to this command is a 32-bit key identifier +for a previously defined trusted key. +If no +.Ic requestkey +command is included in +the configuration file, +or if the keys don't match, +any request to change a server variable with be denied. +.It Ic controlkey Ar key +Specifies the key identifier to use with the +.Xr ntpq 8 +program, +which uses the standard protocol defined in RFC 1305. +This program is useful to diagnose and repair problems +that affect +.Xr ntpd 8 +operation. +The +.Ar key +argument to this command is a 32-bit key identifier +for a trusted key in the key cache. +If no +.Ic controlkey +command is included in the configuration file, +or if the keys don't match, +any request to change a server variable with be denied. +.El +.Ss Authentication Key File Format +In the case of DES, the keys are 56 bits long with, +depending on type, a parity check on each byte. +In the case of MD5, the keys are 64 bits (8 bytes). +.Xr ntpd 8 +reads its keys from a file specified using the +.Fl k +command line option or the +.Ic keys +statement in the configuration file. +While key number 0 is fixed by the NTP standard +(as 56 zero bits) +and may not be changed, +one or more of the keys numbered 1 through 15 +may be arbitrarily set in the keys file. +.Pp +The key file uses the same comment conventions +as the configuration file. +Key entries use a fixed format of the form +.Pp +.Dl keyno type key +.Pp +where +.Ar keyno +is a positive integer, +.Ar type +is a single character which defines the key format, +and +.Ar key +is the key itself. +.Pp +The +.Ar key +may be given in one of three different formats, +controlled by the +.Ar type +character. +The three key types, and corresponding formats, +are listed following. +.Bl -tag -width indent +.It S +The +.Ar key +is a 64-bit hexadecimal number in the format +specified in the DES specification; +that is, the high order seven bits of each octet are used +to form the 56-bit key +while the low order bit of each octet is given a value +such that odd parity is maintained for the octet. +Leading zeroes must be specified +(i.e. the key must be exactly 16 hex digits long) +and odd parity must be maintained. +Hence a zero +.Ar key , +in standard format, would be given as +.Li 0101010101010101 . +.It N +The +.Ar key +is a 64-bit hexadecimal number in the format +specified in the NTP standard. +This is the same as the DES format, +except the bits in each octet have been rotated one bit right +so that the parity bit is now the high order bit of the octet. +Leading zeroes must be specified and odd parity must be maintained. +A zero +.Ar key +in NTP format would be specified as +.Li 8080808080808080 . +.It A +The +.Ar key +is a 1-to-8 character ASCII string. +A key is formed from this by using the low order 7 bits +of each ASCII character in the string, +with zeroes added on the right +when necessary to form a full width 56-bit key, +in the same way that encryption keys are formed from Unix passwords. +.It M +The +.Ar key +is a 1-to-8 character ASCII string, +using the MD5 authentication scheme. +Note that both the keys and the authentication schemes (DES or MD5) +must be identical between a set of peers sharing the same key number. +.El +.Pp +Note that the keys used by the +.Xr ntpq 8 +and +.Xr ntpdc 8 +programs are checked against passwords +requested by the programs and entered by hand, +so it is generally appropriate to specify these keys in ASCII format. +.Sh SEE ALSO +.Xr ntp_conf 8 , +.Xr ntpd 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 3) +.%O RFC1305 +.Re +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto. +Text amended by +.An David Mills +at the University of Delaware. diff --git a/usr.sbin/ntp/doc/ntp_clock.8 b/usr.sbin/ntp/doc/ntp_clock.8 new file mode 100644 index 0000000..7a3b43b --- /dev/null +++ b/usr.sbin/ntp/doc/ntp_clock.8 @@ -0,0 +1,302 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 12, 2000 +.Dt NTP_CLOCK 8 +.Os +.Sh NAME +.Nm ntp_clock +.Nd NTP daemon clock options +.Sh SYNOPSIS +.Pa /etc/ntp.conf +.Sh DESCRIPTION +The NTP Version 4 daemon supports many different radio, +satellite and modem reference clocks +plus a special pseudo-clock used for backup +or when no other clock source is available. +Detailed descriptions of individual device drivers +and options can be found in the +.Qo +Reference Clock Drivers +.Qc +page +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) . +Additional information can be found in the pages referenced there, +including the +.Qo +Debugging Hints for Reference Clock Drivers +.Qc +and +.Qo +How To Write a Reference Clock Driver +.Qc +pages. +In many drivers, +support for a PPS signal is available as described in the +.Qo +Pulse-per-second (PPS) Signal Interfacing +.Qc +page. +Many drivers support special line discipline/streams modules +which can significantly improve the accuracy using the driver. +These are described in the +.Qo +Line Disciplines and Streams Drivers +.Qc +page. +.Pp +A reference clock will generally (though not always) +be a radio timecode receiver +which is synchronized to a source of standard time +such as the services offered by the NRC in Canada +and NIST and USNO in the United States. +The interface between the computer and the timecode receiver +is device dependent, but is usually a serial port. +A device driver specific to each reference clock +must be selected and compiled in the distribution; +however, most common radio, satellite and modem clocks +are included by default. +Note that an attempt to configure a reference clock +when the driver has not been included +or the hardware port has not been appropriately configured +results in a scalding remark to the system log file, +but is not otherwise hazardous. +.Pp +For the purposes of configuration, +.Xr ntpd 8 +treats reference clocks in a manner +analogous to normal NTP peers as much as possible. +Reference clocks are identified by a syntactically correct +but invalid IP address, +in order to distinguish them from normal NTP peers. +Reference clock addresses are of the form 127.127.t.u, +where +.Ar t +is an integer denoting the clock type and +.Ar u +indicates the unit number. +While it may seem overkill, +it is in fact sometimes useful +to configure multiple reference clocks of the same type, +in which case the unit numbers must be unique. +.Pp +The +.Ic server +command is used to configure a reference clock, +where the address argument in that command is the clock address. +The key, +version and ttl options are not used for reference clock support. +The mode option is added for reference clock support, +as described below. +The prefer option can be useful +to persuade the server to cherish a reference clock +with somewhat more enthusiasm than other reference clocks or peers. +Further information on this option can be found in the +.Qo +Mitigation Rules and the prefer Keyword +.Qc +page. +The minpoll and maxpoll options have meaning +only for selected clock drivers. +See the individual clock driver document pages +for additional information. +.Pp +The stratum number of a reference clock is by default zero. +Since the +.Xr ntpd 8 +daemon adds one to the stratum of each peer, +a primary server ordinarily displays stratum 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. +.Ss Reference Clock Commands +.Bl -tag -width indent +.It Xo Ic server No 127.127. Ns Xo +.Ar t Ns No . Ns Xo +.Ar u +.Op prefer +.Op mode Ar int +.Op minpoll Ar int +.Op maxpoll Ar int +.Xc +.Xc +.Xc +This command can be used to configure reference clocks +in special ways. +The options are interpreted as follows: +.Bl -tag -width indent +.It prefer +Marks the reference clock as preferred. +All other things being equal, +this host will be chosen for synchronization +among a set of correctly operating hosts. +See the +.Qo +Mitigation Rules and the prefer Keyword +.Qc +page +for further information. +.It mode Ar int +Specifies a mode number +which is interpreted in a device-specific fashion. +For instance, it selects a dialing protocol in the ACTS driver +and a device subtype in the parse drivers. +.It minpoll Ar int +.It maxpoll Ar int +These options specify the minimum and maximum polling interval +for reference clock messages, in seconds to the power of two. +For most directly connected reference clocks, +both minpoll and maxpoll default to 6 (64 s). +For modem reference clocks, +minpoll defaults to 10 (17.1 m) +and maxpoll defaults to 14 (4.5 h). +The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. +.El +.It Xo Ic fudge No 127.127. Ns Xo +.Ar t Ns No . Ns Xo +.Ar u +.Op time1 Ar sec +.Op time2 Ar sec +.Op stratum Ar int +.Op refid Ar string +.Op mode Ar int +.Op flag1 Ar 0 Ns | Ns Ar 1 +.Op flag2 Ar 0 Ns | Ns Ar 1 +.Op flag3 Ar 0 Ns | Ns Ar 1 +.Op flag4 Ar 0 Ns | Ns Ar 1 +.Xc +.Xc +.Xc +This command can be used to configure reference clocks +in special ways. +It must immediately follow the +.Ic server +command which configures the driver. +Note that the same capability is possible at run time +using the +.Xr ntpdc 8 +program. +The options are interpreted as follows: +.Bl -tag -width indent +.It time1 Ar sec +Specifies a constant to be added to the time offset produced +by the driver, a fixed-point decimal number in seconds. +This is used as a calibration constant +to adjust the nominal time offset of a particular clock +to agree with an external standard, +such as a precision PPS signal. +It also provides a way to correct a systematic error +or bias due to serial port latencies, +different cable lengths or receiver internal delay. +The specified offset is in addition to the propagation delay +provided by other means, such as internal DIPswitches. +Where a calibration for an individual system +and driver is available, +an approximate correction is noted +in the driver documentation pages. +.It time2 Ar secs +Specifies a fixed-point decimal number in seconds, +which is interpreted in a driver-dependent way. +See the descriptions of specific drivers in the +.Qo +Reference Clock Drivers +.Qc +page. +.It stratum Ar int +Specifies the stratum number assigned to the driver, +an integer between 0 and 15. +This number overrides the default stratum number +ordinarily assigned by the driver itself, usually zero. +.It refid Ar string +Specifies an ASCII string from one to four characters +which defines the reference identifier used by the driver. +This string overrides the default identifier +ordinarily assigned by the driver itself. +.It mode Ar int +Specifies a mode number which is interpreted +in a device-specific fashion. +For instance, +it selects a dialing protocol in the ACTS driver +and a device subtype in the parse drivers. +.It flag1 flag2 flag3 flag4 +These four flags are used for customizing the clock driver. +The interpretation of these values, +and whether they are used at all, +is a function of the particular clock driver. +However, by convention +flag4 is used to enable recording monitoring data +to the clockstats file configured with the +.Ic filegen +command. +When a PPS signal is available, +a special automatic calibration facility is provided. +If the flag1 switch is set +and the PPS signal is actively disciplining the system time, +the calibration value is automatically adjusted +to maintain a residual offset of zero. +Further information on the +.Ic filegen +command can be found in the +.Xr ntp_mon 8 +page. +.El +.It Ic pps device [assert|clear] [hardpps] +Specifies the name and options for the serial port device +to which the PPS signal is connected. +Note, this command replaces use of fudge flag3, +which was used for the same purpose in NTPv3. +Note that this command should preceed the +.Ic server +and +.Ic fudge +commands for the same device. +Note also that the assert, +clear and hardpps options are only available +if the ppsapi standard PPS interface is available. +.Bl -tag -width indent +.It device +Specify the device name associated with the PPS signal. +The name must match exactly the link name specified +in the driver documentation page. +.Ic assert +.Ic clear +Using assert or clear specifies +if the high going or low going edge +of the signal must be used. +The default is assert. +.Ic hardpps +This flag is used to tell the kernel that the signal +from this device must be used to drive hardpps(). +The assert, clear and hardpps options are only available +if the PPSAPI is used. +.El +.El +.Sh SEE ALSO +.Xr ntp_conf 8 , +.Xr ntpd 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.Pp +In addition to the manual pages provided, +comprehensive documentation is available on the world wide web +at +.Li http://www.ntp.org/ . +A snapshot of this documentation is available in HTML format in +.Pa /usr/share/doc/ntp . +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto. +Text amended by +.An David Mills +at the University of Delaware. diff --git a/usr.sbin/ntp/doc/ntp_conf.8 b/usr.sbin/ntp/doc/ntp_conf.8 new file mode 100644 index 0000000..6fffa6b --- /dev/null +++ b/usr.sbin/ntp/doc/ntp_conf.8 @@ -0,0 +1,396 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 11, 2000 +.Dt NTP_CONF 8 +.Os +.Sh NAME +.Nm ntp_conf +.Nd NTP daemon configuration options +.Sh SYNOPSIS +.Pa /etc/ntp.conf +.Sh DESCRIPTION +Following is a description of the configuration commands in NTPv4. +These commands have the same basic functions as in NTPv3 +and in some cases new functions and new operands. +The various modes are determined by the command keyword +and the type of the required IP address. +Addresses are classed by type as +(s) a remote server or peer (IP class A, B and C), +(b) the broadcast address of a local interface, +(m) a multicast address (IP class D), +or (r) a reference clock address (127.127.x.x). +Note that, +while autokey and burst modes are supported by these commands, +their effect in some weird mode combinationscan be meaningless +or even destructive. +.Bl -tag -width indent +.It Xo Ic peer +.Ar address +.Op autokey | key Ar key +.Op burst +.Op version Ar version +.Op prefer +.Op minpoll Ar minpoll +.Op maxpoll Ar maxpoll +.Xc +.It Xo Ic server +.Ar address +.Op autokey | key Ar key +.Op burst +.Op version Ar version +.Op prefer +.Op minpoll Ar minpoll +.Op maxpoll Ar maxpoll +.Xc +.It Xo Ic broadcast +.Ar address +.Op autokey | key Ar key +.Op burst +.Op version Ar version +.Op minpoll Ar minpoll +.Op maxpoll Ar maxpoll +.Op ttl Ar ttl +.Xc +.It Xo Ic manycastclient +.Ar address +.Op autokey | key Ar key +.Op burst +.Op version Ar version +.Op minpoll Ar minpoll +.Op maxpoll Ar maxpoll +.Op ttl Ar ttl +.Xc +These four commands specify the time server name or address +to be used and the mode in which to operate. +The address can be +either a DNS name +or an IP address in dotted-quad notation. +Additional information on association behavior can be found in +the +.Qo +Association Management +.Qc +page +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) . +.Bl -tag -width indent +.It Ic peer +For type s addresses (only), +this operates as the current peer command, +which mobilizes a persistent symmetric-active mode association, +except that additional modes are available. +This command should +.Em not +be used for type b, m or r addresses. +.Pp +The +.Ic peer +command specifies that the local server is to operate +in symmetric active mode with the remote server. +In this mode, +the local server can be synchronized to the remote server +and, in addition, +the remote server can be synchronized by the local server. +This is useful in a network of servers where, +depending on various failure scenarios, +either the local or remote server may be the better source of time. +.It Ic server +For type s and r addresses, +this operates as the NTPv3 server command, +which mobilizes a persistent client mode association. +The server command specifies +that the local server is to operate in client mode +with the specified remote server. +In this mode, +the local server can be synchronized to the remote server, +but the remote server can never be synchronized to the local server. +.It Ic broadcast +For type b and m addresses (only), +this is operates as the current NTPv3 broadcast command, +which mobilizes a persistent broadcast mode association, +except that additional modes are available. +Multiple commands can be used +to specify multiple local broadcast interfaces (subnets) +and/or multiple multicast groups. +Note that local broadcast messages go only to the interface +associated with the subnet specified, +but multicast messages go to all interfaces. +In the current implementation, +the source address used for these messages +is the Unix host default address. +.Pp +In broadcast mode, +the local server sends periodic broadcast messages +to a client population at the address specified, +which is usually the broadcast address +on (one of) the local network(s) +or a multicast address assigned to NTP. +The IANA has assigned the multicast group address 224.0.1.1 +exclusively to NTP, +but other non-conflicting addresses can be used +to contain the messages within administrative boundaries. +Ordinarily, this specification applies +only to the local server operating as a sender; +for operation as a broadcast client, +see the +.Ic broadcastclient +or +.Ic multicastclient +commands below. +.It Ic manycastclient +For type m addresses (only), +this mobilizes a manycast client-mode association +for the multicast address specified. +In this case a specific address must be supplied +which matches the address used on the +.Ic manycastserver +command for the designated manycast servers. +The NTP multicast address 224.0.1.1 assigned by the IANA should +.Em not +be used, +unless specific means are taken +to avoid spraying large areas of the Internet +with these messages +and causing a possibly massive implosion of replies at the sender. +.Pp +The +.Ic manycastclient +command specifies +that the local server is to operate in client mode +with the remote servers +that are discovered as the result of broadcast/multicast messages. +The client broadcasts a request message +to the group address associated with the specified address +and specifically enabled servers respond to these messages. +The client selects the servers providing the best time +and continues as with the +.Ic server +command. +The remaining servers are discarded as if never heard. +.El +.Pp +The following options to these commands are available: +.Bl -tag -width indent +.It autokey +All packets sent to the address +are to include authentication fields +encrypted using the autokey scheme. +.It burst +At each poll interval, +send a burst of eight packets spaced, +instead of the usual one. +.It key Ar key +All packets sent to the address +are to include authentication fields +encrypted using the specified key identifier, +which is an unsigned 32-bit integer +less than 65536. +The default is to include no encryption field. +.It version Ar version +Specifies the version number to be used for outgoing NTP packets. +Versions 1-4 are the choices, with version 4 the default. +.It prefer +Marks the server as preferred. +All other things being equal, +this host will be chosen for synchronization +among a set of correctly operating hosts. +See the +.Qo +Mitigation Rules and the prefer Keyword +.Qc +page +for further information. +.It ttl Ar ttl +This option is used only with broadcast mode. +It specifies the time-to-live (TTL) to use +on multicast packets. +Selection of the proper value, +which defaults to 127, +is something of a black art +and must be coordinated with the network administrator. +.It minpoll Ar minpoll +.It maxpoll Ar maxpoll +These options specify the minimum +and maximum polling intervals for NTP messages, +in seconds to the power of two. +The default range is 6 (64 s) to 10 (1,024 s). +The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. +.El +.It Ic broadcastclient +This command directs the local server to listen for and respond +to broadcast messages received on any local interface. +Upon hearing a broadcast message for the first time, +the local server measures the nominal network delay +using a brief client/server exchange with the remote server, +then enters the broadcastclient mode, +in which it listens for +and synchronizes to succeeding broadcast messages. +Note that, +in order to avoid accidental or malicious disruption in this mode, +both the local and remote servers should operate +using authentication and the same trusted key and key identifier. +.It Xo Ic multicastclient +.Op Ar address +.Op ... +.Xc +This command directs the local serverto listen for +multicast messages at the group address(es) +of the global network. +The default address is that assigned by the Numbers Czar +to NTP (224.0.1.1). +This command operates in the same way as the +.Ic broadcastclient +command, but uses IP multicasting. +Support for this command requires a multicast kernel. +.It Ic driftfile Ar driftfile +This command specifies the name of the file used +to record the frequency offset of the local clock oscillator. +If the file exists, +it is read at startup in order to set the initial frequency offset +and then updated once per hour with the current frequency offset +computed by the daemon. +If the file does not exist or this command is not given, +the initial frequency offset is assumed zero. +In this case, +it may take some hours for the frequency to stabilize +and the residual timing errors to subside. +.Pp +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 +.Nm +must have write permission for the directory +the drift file is located in, +and that file system links, symbolic or otherwise, should be avoided. +.It Xo Ic manycastserver +.Ar address +.Op ... +.Xc +This command directs the local server to listen for +and respond to broadcast messages received on any local interface, +and in addition enables the server to respond +to client mode messages to the multicast group address(es) +(type m) specified. +At least one address is required, +but the NTP multicast address 224.0.1.1 +assigned by the IANA should +.Em not +be used, +unless specific means are taken to limit the span of the reply +and avoid a possibly massive implosion at the original sender. +.It Xo Ic revoke +.Op Ar logsec +.Xc +Specifies the interval between recomputations +of the private value used with the autokey feature, +which ordinarily requires an expensive public-key computation. +The default value is 12 (65,536 s or about 18 hours). +For poll intervals above the specified interval, +a new private value will be recomputed for every message sent. +.It Xo Ic autokey +.Op Ar logsec +.Xc +Specifies the interval between regenerations +of the session key list used with the autokey feature. +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. +.It Xo Ic enable +.Op Ar flag +.Op ... +.Xc +.It Xo Ic disable +.Op Ar flag +.Op ... +.Xc +Provides a way to enable or disable various server options. +Flags not mentioned are unaffected. +Note that all of these flags can be controlled remotely +using the +.Xr ntpdc 8 +utility program. +Following is a description of the flags. +.Bl -tag -width indent +.It auth +Enables the server to synchronize with unconfigured peers +only if the peer has been correctly authenticated +using a trusted key and key identifier. +The default for this flag is enable. +.It bclient +When enabled, this is identical to the broadcastclient +command. +The default for this flag is disable. +.It kernel +Enables the precision-time kernel support +for the +.Xr ntp_adjtime 2 +system call, if implemented. +Ordinarily, support for this routine is detected automatically +when the NTP daemon is compiled, +so it is not necessary for the user to worry about this flag. +It provided primarily so that this support can be disabled +during kernel development. +.It monitor +Enables the monitoring facility. +See the +.Ic monlist +command of the +.Xr ntpdc 8 +program +further information. +The default for this flag is enable. +.It ntp +Enables the server to adjust its local clock by means of NTP. +If disabled, +the local clock free-runs at its intrinsic time and frequency offset. +This flag is useful in case the local clock is controlled +by some other device or protocol and NTP is used +only to provide synchronization to other clients. +In this case, +the local clock driver can be used to provide this function +and also certain time variables for error estimates +and leap-indicators. +See the +.Qo +Reference Clock Drivers +.Qc +page +for further information. +The default for this flag is enable. +.It stats +Enables the statistics facility. +See the +.Xr ntp_mon 8 +page +for further information. +The default for this flag is enable. +.El +.El +.Sh SEE ALSO +.Xr ntp_mon 8 , +.Xr ntpd 8 , +.Xr ntpdc 8 +.Pp +In addition to the manual pages provided, +comprehensive documentation is available on the world wide web +at +.Li http://www.ntp.org/ . +A snapshot of this documentation is available in HTML format in +.Pa /usr/share/doc/ntp . +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto. +Text amended by +.An David Mills +at the University of Delaware. diff --git a/usr.sbin/ntp/doc/ntp_misc.8 b/usr.sbin/ntp/doc/ntp_misc.8 new file mode 100644 index 0000000..4e59aa7 --- /dev/null +++ b/usr.sbin/ntp/doc/ntp_misc.8 @@ -0,0 +1,180 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 12, 2000 +.Dt NTP_MISC 8 +.Os +.Sh NAME +.Nm ntp_misc +.Nd NTP daemon miscellaneous options +.Sh SYNOPSIS +.Pa /etc/ntp.conf +.Sh DESCRIPTION +The following miscellaneous configuration options are available: +.Bl -tag -width indent +.It Ic broadcastdelay Ar 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 local and remote servers. +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. +.It Xo Ic trap +.Ar host_address +.Op port Ar port_number +.Op interface Ar interface_address +.Xc +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. +.It Ic setvar Ar variable Op 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 +.Va name += +.Ar value +is followed by the default keyword, +the variable will be listed +as part of the default system variables +(see the +.Xr ntpq 8 +.Ic 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 +.Ic setvar +mechanism. +There are three special variables +that contain the names of all variables of the same group. +The +.Va sys_var_list +holds the names of all system variables. +The +.Va peer_var_list +holds the names of all peer variables and the +.Va clock_var_list +holds the names of the reference clock variables. +.It Ic logfile Ar logfile +This command specifies the location of an alternate log file +to be used instead of the default system +.Xr syslog 3 +facility. +.It Ic logconfig Ar configkeyword +This command controls the amount and type of output +written to the system +.Xr syslog 3 +facility or the alternate +.Ic logfile +log file. +By default, all output is turned on. +All +.Ar configkeyword +keywords can be prefixed with =, + and -, +where = sets the syslogmask, ++ adds and - removes messages. +.Xr syslog 3 +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) control configuration information. +Event messages (events) control logging of events +(reachability, synchronization, alarm conditions). +Statistical output is controlled with the +.Ic statistics +keyword. +The final message group is the status messages. +This describes mainly the synchronizations status. +.Pp +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. +Thus, a minimal log configuration could look like this: +.Pp +.Dl logconfig = syncstatus +sysevents +.Pp +This would just list the synchronizations state of +.Xr ntpd 8 +and the major system events. +For a simple reference server, +the following minimum message configuration could be useful: +.Pp +.Dl logconfig = syncall +clockall +.Pp +This configuration will list all clock information +and synchronization information. +All other events and messages about peers, +system events and so on is suppressed. +.El +.Ss Variables +Most variables used by the NTP protocol +can be examined with +.Xr ntpdc 8 +(mode 7 messages) and +.Xr ntpq 8 (mode 6 messages). +Currently, very few variables can be modified via mode 6 messages. +These variables are either created with the +.Ic setvar +directive or the leap warning bits. +The leap warning bits can be set in the +.Va leapwarning +variable up to one month ahead. +Both the +.Va leapwarning +and +.Va leapindication +variables have a slightly different encoding +than the usual leap bits interpretation: +.Pp +.Bl -tag -width indent -compact +.It 00 +The daemon passes the leap bits of its synchronization source +(usual mode of operation). +.It 01 +.It 10 +A leap second is added/deleted (operator forced leap second). +.It 11 +Leap information from the synchronizations source is ignored +(thus +.Dv LEAP_NOWARNING +is passed on). +.El +.Sh SEE ALSO +.Xr ntp_conf 8 , +.Xr ntpd 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto. +Text amended by +.An David Mills +at the University of Delaware. diff --git a/usr.sbin/ntp/doc/ntp_mon.8 b/usr.sbin/ntp/doc/ntp_mon.8 new file mode 100644 index 0000000..c7b36a7 --- /dev/null +++ b/usr.sbin/ntp/doc/ntp_mon.8 @@ -0,0 +1,298 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 12, 2000 +.Dt NTP_MON 8 +.Os +.Sh NAME +.Nm ntp_mon +.Nd NTP daemon monitoring options +.Sh SYNOPSIS +.Pa /etc/ntp.conf +.Sh DESCRIPTION +Xr ntpd 8 +includes a comprehensive monitoring facility +suitable for continuous, long term recording +of server and client timekeeping performance. +See the +.Ic statistics +command below for a listing +and example of each type of statistics currently supported. +Statistic files are managed using file generation sets +and scripts in the +.Pa ./scripts +directory of the source distribution. +Using these facilities and Unix +.Xr cron 8 +jobs, +the data can be automatically summarized and archived +for retrospective analysis. +.Ss Monitoring Commands +The following monitoring commands are available: +.Bl -tag -width indent +.It Xo Ic statistics +.Ar name +.Op ... +.Xc +Enables writing of statistics records. +Currently, four kinds of +.Ar name +statistics are supported. +.Bl -tag -width indent +.It loopstats +Enables recording of loop filter statistics information. +Each update of the local clock outputs +a line of the following form +to the file generation set named loopstats: +.Pp +.Dl 50935 75440.031 0.000006019 13.778190 0.000351733 0.013380 6 +.Pp +The first two fields show the date (Modified Julian Day) +and time (seconds and fraction past UTC midnight). +The next five fields show time offset (seconds), +frequency offset (parts per million - PPM), RMS jitter (seconds), +Allan deviation (PPM) and clock discipline time constant. +.It peerstats +Enables recording of peer statistics information. +This includes statistics records of all peers of a NTP server +and of special signals, where present and configured. +Each valid update appends a line of the following form to +the current element of a file generation set named peerstats: +.Pp +.Dl 48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142 +.Pp +The first two fields show the date (Modified Julian Day) +and time (seconds and fraction past UTC midnight). +The next two fields show the peer address in dotted-quad notation +and status, respectively. +The status field is encoded in hex in the format +described in Appendix A of the NTP specification RFC 1305. +The final three fields show the offset, delay and RMS jitter, +all in seconds. +.It clockstats +Enables recording of clock driver statistics information. +Each update received from a clock driver appends a line +of the following form to the file generation set named clockstats: +.Pp +.Dl 49213 525.624 127.127.4.1 93 226 00:08:29.606 D +.Pp +The first two fields show the date (Modified Julian Day) +and time (seconds and fraction past UTC midnight). +The next field shows the clock address in dotted-quad notation. +The final field shows the last timecode received from the clock +in decoded ASCII format, where meaningful. +In some clock drivers +a good deal of additional information can be gathered and displayed +as well. +See information specific to each clock for further details. +.It rawstats +Enables recording of raw-timestamp statistics information. +This includes statistics records of all peers of a NTP server +and of special signals, where present and configured. +Each NTP message received from a peer or clock driver +appends a line of the following form +to the file generation set named rawstats: +.Pp +.Bd -ragged -offset indent +.Li 50928 +.Li 2132.543 +.Li 128.4.1.1 +.\" +.\" XXX The next field is unaccounted for in the descriptive text +.\" that follows. +.\" +.Li 128.4.1.20 +.Li 3102453281.584327000 +.Li 3102453281.58622800031 +.Li 02453332.540806000 +.Li 3102453332.541458000 +.Ed +.Pp +The first two fields show the date (Modified Julian Day) +and time (seconds and fraction past UTC midnight). +The next field shows the peer or clock address +in dotted-quad notation. +The final four fields show the originate, +receive, transmit and final NTP timestamps in order. +The timestamp values are as received and before processing +by the various data smoothing and mitigation algorithms. +.El +.It Ic statsdir Ar directory_path +Indicates the full path of a directory +where statistics files should be created (see below). +This keyword allows the +(otherwise constant) filegen filename prefix to be modified +for file generation sets, +which is useful for handling statistics logs. +.It Xo Ic filegen +.Ar name +.Op file Ar filename +.Op type Ar typename +.Op link | nolink +.Op enable | disable +.Xc +Configures setting of generation file set name. +Generation file sets provide a means for handling files +that are continuously growing during the lifetime of a server. +Server statistics are a typical example for such files. +Generation file sets provide +access to a set of files used to store the actual data. +At any time at most one element of the set is being written to. +The type given specifies when and how data will be directed +to a new element of the set. +This way, information stored in elements of a file set +that are currently unused are available for administrative operations +without the risk of disturbing the operation of +.Xr ntpd 8 . +Most importantly, +they can be removed to free space for new data produced. +.Pp +Note that this command can be sent from the +.Xr ntpdc 8 +program running at a remote location. +.Bl -tag -width indent +.It name +This is the type of the statistics records, +as shown in the +.Ic statistics +command. +.It file Ar filename +This is the file name for the statistics records. +Filenames of set members are built from three elements: +.Bl -tag -width indent +.It prefix +This is a constant filename path. +It is not subject to modifications via the +.Ic filegen +option. +It is defined by the server, +usually specified as a compile-time constant. +It may, however, be configurable for individual file generation sets +via other commands. +For example, the prefix used with loopstats and peerstats generation +can be configured using the +.Ic statsdir +option explained above. +.Ar filename +This string is directly concatenated to the prefix mentioned above +(no intervening +.Qq / +(slash)) . +This can be modified using the +.Ar filename +argument to the +.Ic filegen +statement. +No +.Qq .. +elements are allowed in this component +to prevent filenames referring to parts +outside the filesystem hierarchy denoted by prefix. +.Ic suffix +This part is reflects individual elements of a file set. +It is generated according to the type of a file set. +.El +.It type Ar typename +A file generation set is characterized by its type. +The following types are supported: +.Bl -tag -width indent +.It none +The file set is actually a single plain file. +.It pid +One element of file set is used per incarnation of a +.Xr ntpd 8 +server. +This type does not perform any changes +to file set members during runtime, +however it provides an easy way of separating files +belonging to different +.Xr ntpd 8 +server incarnations. +The set member filename is built by appending a +.Qq \&. +(dot) to concatenated prefix and +.Ar filename +strings, +and appending the decimal representation +of the process ID of the +.Xr ntpd 8 +server process. +.It day +One file generation set element is created per day. +A day is defined as the period between 00:00 and 24:00 UTC. +The file set member suffix consists of a +.Qq \&. +(dot) and a day specification in the form YYYYMMDD. +YYYY is a 4-digit year number (e.g. 1992). +MM is a two digit month number. +DD is a two digit day number. +Thus, all information written at 10 December 1992 +would end up in a file named +.Pa .19921210 . +.It week +Any file set member contains data +related to a certain week of a year. +The term week is defined by computing the day of the year modulo 7. +Elements of such a file generation set are distinguished +by appending the following suffix to the file set +.Ar filename +base: +A dot, a 4-digit year number, the letter W, +and a 2-digit week number. +For example, information from January, 10th 1992 +would end up in a file with suffix .1992W1. +.It month +One generation file set element is generated per month. +The file name suffix consists of a dot, a 4-digit year number, +and a 2-digit month. +.It year +One generation file element is generated per year. +The filename suffix consists of a dot and a 4 digit year number. +.It age +This type of file generation sets changes to a new element +of the file set every 24 hours of server operation. +The filename suffix consists of a dot, the letter a, +and an 8-digit number. +This number is taken to be the number of seconds +the server has been running +at the start of the corresponding 24-hour period. +Information is only written to a file generation +by specifying enable; output is prevented by specifying disable. +.It link | nolink +It is convenient to be able to access the current element +of a file generation set by a fixed name. +This feature is enabled by specifying link +and disabled using nolink. +If link is specified, +a hard link from the current file set element +to a file without suffix is created. +When there is already a file with this name +and the number of links of this file is one, +it is renamed appending a dot, the letter C, +and the pid of the +.Xr 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. +.It enable | disable +Enables or disables the recording function. +.El +.El +.Sh SEE ALSO +.Xr ntp_conf 8 , +.Xr ntpd 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 3) +.%O RFC1305 +.Re +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto. +Text amended by +.An David Mills +at the University of Delaware. diff --git a/usr.sbin/ntp/doc/ntpd.8 b/usr.sbin/ntp/doc/ntpd.8 new file mode 100644 index 0000000..91e35a1 --- /dev/null +++ b/usr.sbin/ntp/doc/ntpd.8 @@ -0,0 +1,278 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 10, 2000 +.Dt NTPD 8 +.Os +.Sh NAME +.Nm ntpd +.Nd Network Time Protocol (NTP) daemon +.Sh SYNOPSIS +.Nm ntpd +.Op Fl aAbdm +.Op Fl c Ar conffile +.Op Fl f Ar driftfile +.Op Fl k Ar keyfile +.Op Fl l Ar logfile +.Op Fl p Ar pidfile +.Op Fl r Ar broadcastdelay +.Op Fl s Ar statsdir +.Op Fl t Ar trustedkey +.Op Fl v Ar variable +.Op Fl V Ar variable +.Sh DESCRIPTION +.Nm +is an operating system daemon +which sets and maintains the system time-of-day +in synchronism with Internet standard time servers. +.Nm +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. +.Nm +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 nanosecond CPU clocks and gigabit LANs. +.Pp +The daemon can operate in any of several modes, +including symmetric active/passive, +client/server broadcast/multicast and manycast. +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. +.Pp +Ordinarily, +.Nm +reads the +.Pa 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 appropriate +when the local host is to be configured +as a broadcast/multicast client or manycast client, +with all peers being determined +by listening to broadcasts at run time. +.Pp +If NetInfo support is built into +.Nm Ns , +then +.Nm +will attempt to read its configuration from the NetInfo +if the default configuration file cannot be read +and no file is specified by the +.Fl c +option. +.Pp +Various +internal +.Nm +variables can be displayed and configuration options altered +while the daemon is running +through use of the +.Xr ntpq 8 +and +.Xr ntpdc 8 +programs. +.Pp +When +.Nm +starts it looks at the value of +.Xr umask 2 +and if it is zero, +.Nm +will set it to 022. +.Pp +The following command line options are available: +.Bl -tag -width indent +.It Fl a +Enable authentication mode (default). +.It Fl A +Disable authentication mode. +.It Fl b +Synchronize using NTP broadcast messages. +.It Fl c Ar conffile +Specify the name and path of the configuration file. +.It Fl d +Specify debugging mode. +This flag may occur multiple times, +with each occurrence indicating greater detail of display. +.It Fl D Ar level +Specify debugging level directly. +.It Fl f Ar driftfile +Specify the name and path of the drift file. +.It Fl g +Normally, the daemon exits +if the offset exceeds a 1000 s sanity limit. +This option overrides this limit +and allows the time to be set to any value without restriction. +.It Fl k Ar keyfile +Specify the name and path of the file +containing the NTP authentication keys. +.It Fl l Ar logfile +Specify the name and path of the log file. +The default is the system log facility. +.It Fl m +Synchronize using NTP multicast messages +on the IP multicast group address 224.0.1.1 +(requires multicast kernel). +.It Fl p Ar pidfile +Specify the name and path to record the daemon's process ID. +.It Fl P +Override the priority limit set by the operating system. +Not recommended for sissies. +.It Fl r Ar broadcastdelay +Specify the default propagation delay +between the broadcast/multicast server and this computer. +This is necessary +only if the delay cannot be computed automatically by the protocol. +.It Fl s Ar statsdir +Specify the directory path for files created by the statistics +facility. +.It Fl t Ar key +Add a key number to the trusted key list. +.It Fl v Ar variable +.It Fl V Ar variable +Add a system variable listed by default. +.It Fl x +Ordinarily, if the time is to be adjusted more than 128 ms, +it is stepped, not gradually slewed. +This option forces the time to be slewed in all cases. +Note: since the slew rate is limited to 0.5 ms/s, +each second of adjustment requires an amortization interval of 2000 s. +Thus, an adjustment of many seconds can take hours or days to amortize. +.El +.Ss The Configuration File +The +.Nm +configuration file is read at initial startup by the +.Xr ntpd 8 +daemon in order to specify the synchronization sources, +modes and other related information. +Usually, it is installed in the +.Pa /etc +directory, +but could be installed elsewhere +(see the daemon's +.Fl c +command line option). +.Pp +The file format is similar to other Unix configuration files. +Comments begin with a +.Qq # +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. +.Pp +See the following pages for configuration and control options. +While there is a rich set of options available, +the only required option is one or more +.Ic server , +.Ic peer , +.Ic broadcast +or +.Ic manycastclient +commands +described in +.Xr ntp_conf 8 . +.Pp +.Bl -tag -width ntp_clockX8X -compact +.It Xr ntp_conf 8 +Configuration Options +.It Xr ntp_auth 8 +Authentication Options +.It Xr ntp_mon 8 +Monitoring Options +.It Xr ntp_acc 8 +Access Control Options +.It Xr ntp_clock 8 +Reference Clock Options +.It Xr ntp_misc 8 +Miscellaneous Options +.Pp +.El +The +.Qo +Notes on Configuring NTP and Setting up a NTP Subnet +.Qc +page +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) +contains an extended discussion of these options. +.Sh FILES +.Bl -tag -width /etc/ntp.drift -compact +.It Pa /etc/ntp.conf +the default name of the configuration file +.It Pa /etc/ntp.drift +the default name of the drift file +.It Pa /etc/ntp.keys +the default name of the key file +.El +.Sh SEE ALSO +.Xr ntp_acc 8 , +.Xr ntp_auth 8 , +.Xr ntp_clock 8 , +.Xr ntp_conf 8 , +.Xr ntp_misc 8 , +.Xr ntp_mon 8 , +.Xr ntpdate 8 , +.Xr ntpdc 8 , +.Xr ntpq 8 +.Pp +In addition to the manual pages provided, +comprehensive documentation is available on the world wide web +at +.Li http://www.ntp.org/ . +A snapshot of this documentation is available in HTML format in +.Pa /usr/share/doc/ntp . +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 1) +.%O RFC1059 +.Re +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 2) +.%O RFC1119 +.Re +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 3) +.%O RFC1305 +.Re +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto. +Text amended by +.An David Mills +at the University of Delaware. +.Sh BUGS +.Nm +has gotten rather fat. +While not huge, it has gotten larger than might +be desireable for an elevated-priority daemon running on a workstation, +particularly since many of the fancy features which consume the space +were designed more with a busy primary server, rather than a high +stratum workstation, in mind. diff --git a/usr.sbin/ntp/doc/ntpdate.8 b/usr.sbin/ntp/doc/ntpdate.8 new file mode 100644 index 0000000..2049d15 --- /dev/null +++ b/usr.sbin/ntp/doc/ntpdate.8 @@ -0,0 +1,231 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 6, 2000 +.Dt NTPDATE 8 +.Os +.Sh NAME +.Nm ntpdate +.Nd set the date and time via NTP +.Sh SYNOPSIS +.Nm +.Op Fl bBdqsuv +.Op Fl a Ar key +.Op Fl e Ar authdelay +.Op Fl k Ar keyfile +.Op Fl o Ar version +.Op Fl p Ar samples +.Op Fl t Ar timeout +.Ar server +.Op Ar ... +.Sh DESCRIPTION +.Nm +sets the local date and time by polling the Network Time Protocol (NTP) +server(s) given as the +.Ar server +arguments to determine +the correct time. It must be run as root on the local host. A number +of samples are obtained from each of the servers specified +and a subset of the NTP clock filter and selection algorithms +are applied to select the best of these. +Note that the accuracy and reliability of +.Nm +depends on the number of servers, +the number of polls each time it is run +and the interval between runs. +.Pp +.Nm +can be run manually as necessary to set the host clock, +or it can be run from the host startup script +to set the clock at boot time. +This is useful in some cases to set the clock initially +before starting the NTP daemon +.Xr ntpd 8 . +It is also possible to run +.Nm +from a +.Xr cron 8 +script. +However, it is important to note that +.Nm +with contrived cron scripts is no substitute for the NTP daemon, +which uses sophisticated algorithms to maximize accuracy and reliability +while minimizing resource use. +Finally, since +.Nm +does not discipline the host clock frequency as does +.Xr ntpd 8 , +the accuracy using +.Nm +is limited. +.Pp +Time adjustments are made by +.Nm +in one of two ways. If +.Nm +determines the clock is in error more than 0.5 second it will simply +step the time by calling the system +.Xr settimeofday 2 +routine. +If the error is less than 0.5 seconds, it will slew the time +by calling the system +.Xr adjtime 2 +routine. +The latter technique is less disruptive and more +accurate when the error is small, and works quite well when +.Nm +is run by +.Xr cron 8 +every hour or two. +.Pp +.Nm +will decline to set the date if an NTP server daemon +(e.g., +.Xr ntpd 8 ) +is running on the same host. +When running +.Nm +on a regular basis from +.Xr cron 8 +as an alternative to running a daemon, +doing so once every hour or two +will result in precise enough timekeeping +to avoid stepping the clock. +.Pp +If NetInfo support is compiled into +.Nm Ns , +then the server argument is optional if +.Nm +can find a time server in the NetInfo configuration for +.Xr ntpd 8 . +.Pp +The following options are available: +.Bl -tag -width indent +.It Fl a Ar key +Enable the authentication function +and specify the key identifier to be used +for authentication as the argument +.Ar key . +The keys and key identifiers must match +in both the client and server key files. +The default is to disable the authentication function. +.It Fl B +Force the time to always be slewed using the +.Xr adjtime 2 +system call, +even if the measured offset is greater than +-128 ms. +The default is to step the time using +.Xr settimeofday 2 +if the offset is greater than +-128 ms. +Note that, +if the offset is much greater than +-128 ms in this case, +it can take a long time (hours) +to slew the clock to the correct value. +During this time, +the host should not be used to synchronize clients. +.It Fl b +Force the time to be stepped using the +.Xr settimeofday 2 +system call, +rather than slewed (default) using the +.Xr adjtime 2 +system call. +This option should be used +when called from a startup file at boot time. +.It Fl d +Enable the debugging mode, +in which +.Nm +will go through all the steps, +but not adjust the local clock. +Information useful for general debugging will also be printed. +.It Fl e Ar authdelay +Specify the processing delay +to perform an authentication function as the value +.Ar authdelay , +in seconds and fraction +(see +.Xr ntpd 8 +for details). +This number is usually small enough +to be negligible for most purposes, +though specifying a value +may improve timekeeping on very slow CPU's. +.It Fl k Ar keyfile +Specify the path for the authentication key file +as the string +.Ar keyfile . +The default is +.Pa /etc/ntp.keys . +This file should be in the format described in +.Xr ntpd 8 . +.It Fl o Ar version +Specify the NTP version for outgoing packets as the integer +.Ar version , +which can be 1 or 2. +The default is 3. +This allows +.Nm +to be used with older NTP versions. +.It Fl p Ar samples +Specify the number of samples to be acquired from each server +as the integer +.Ar samples , +with values from 1 to 8 inclusive. +The default is 4. +.It Fl q +Query only - don't set the clock. +.It Fl s +Divert logging output from the standard output (default) +to the system +.Xr syslog 3 +facility. +This is designed primarily for convenience of +.Xr cron 8 +scripts. +.It Fl t timeout +Specify the maximum time waiting for a server response +as the value +.Ar timeout , +in seconds and fraction. +The value is rounded to a multiple of 0.2 seconds. +The default is 1 second, +a value suitable for polling across a LAN. +.It Fl u +Direct +.Nm +to use an unprivileged port for outgoing packets. +This is most useful when behind a firewall +that blocks incoming traffic to privileged ports, +and you want to synchronise with hosts beyond the firewall. +Note that the +.Fl d +option always uses unprivileged ports. +.It Fl v +Be verbose. +This option will cause +.Nm Ns 's +version identification string to be logged. +.El +.Sh FILES +.Bl -tag -width /etc/ntp.keys -compact +.It Pa /etc/ntp.keys +contains the encryption keys used by +.Nm Ns . +.El +.Sh SEE ALSO +.Xr ntpd 8 +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto +.Sh BUGS +The slew adjustment is actually 50% larger than the measured offset, +since this (it is argued) +will tend to keep a badly drifting clock more accurate. +This is probably not a good idea +and may cause a troubling hunt +for some values of the kernel variables +.Va tick +and +.Va tickadj . diff --git a/usr.sbin/ntp/doc/ntpdc.8 b/usr.sbin/ntp/doc/ntpdc.8 new file mode 100644 index 0000000..dece29e --- /dev/null +++ b/usr.sbin/ntp/doc/ntpdc.8 @@ -0,0 +1,721 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 7, 2000 +.Dt NTPDC 8 +.Os +.Sh NAME +.Nm ntpdc +.Nd special NTP query program +.Sh SYNOPSIS +.Nm ntpdc +.Op Fl ilnps +.Op Fl c Ar command +.Op Ar host ... +.Sh DESCRIPTION +.Nm +is used to query the +.Xr ntpd 8 +daemon about its current state and to request changes in that state. +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 start up using +.Xr ntpd 8 Ns 's +configuration file may also be specified at run time using +.Nm Ns . +.Pp +If one or more request options is 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 +.Dq 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 +.Dq localhost +when no other host is specified. +.Nm +will prompt for commands if the standard input is a terminal device. +.Pp +.Nm +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. +.Nm +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 +is 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 +program 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 +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. +The following options are available: +.Bl -tag -width indent +.It Fl c Ar command +The +.Ar command +argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified +host(s). +Multiple +.Fl c +options may be given. +.It Fl i +Force +.Nm +to operate in interactive mode. +Prompts will be written to the standard +output and commands read from the standard input. +.It Fl l +Obtain a list of peers which are known to the server(s). +This switch is equivalent to +.Dq Li -c listpeers . +.It Fl n +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.It Fl p +Print a list of the peers known to the server as well as a summary of +their state. +This is equivalent to +.Dq Li -c peers . +.It Fl s +Print a list of the peers known to the server as well as a summary of +their state, but in a slightly different format than the +.Fl p +switch. +This is equivalent to +.Dq Li -c dmpeers . +.El +.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 +.Qq > , +followed by a +file name, to the command line. +.Pp +A number of interactive format commands are executed entirely within the +.Nm +program 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 ? Op Ar command_keyword +.It Ic help Op Ar command_keyword +A +.Ic ? +by itself will print a list of all the command keywords +known to this incarnation of +.Nm Ns . +A +.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 +.Nm +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. +The +.Ar hostname +supplied +may be either a host name or a numeric +address. +.It Ic hostnames Ar yes | Ar no +If +.Ar yes +is specified, host names are printed in information +displays. +If +.Ar no +is given, numeric addresses are printed +instead. +The default is +.Ar 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 Ns . +.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 5000 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 +.Qq read-only +commands in that they make no modification of the server configuration +state. +.Bl -tag -width indent +.It Ic listpeers +Obtain and print 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 +Obtain 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. +In addition, the character in the left margin indicates the +mode this peer entry is operating in. +A +.Qq + +denotes symmetric +active, a +.Qq - +indicates symmetric passive, a +.Qq = +means +the remote server is being polled in client mode, a +.Qq ^ +indicates that the server is broadcasting to this address, a +.Qq ~ +denotes that the remote peer is sending broadcasts and a +.Qq * +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 +.Dq Li REFCLK(, ) . +On hostnames no +only IP addresses will be displayed. +.It Ic dmpeers +A slightly different peer summary list. +Identical to the output of the +.Em 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 +.Qq \&. +indicates that this peer was cast off +in the falseticker detection, while a +.Qq + +indicates that the +peer made it through. +A +.Qq * +denotes the peer the server is +currently synchronizing with. +.It Xo Ic showpeer +.Ar peer_address +.Op Ar ... +.Xc +Show 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 Xo Ic pstats +.Ar peer_address +.Op Ar ... +.Xc +Show per-peer statistic counters associated with the specified peer(s). +.It Xo Ic clockinfo +.Ar clock_peer_address +.Op Ar ... +.Xc +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 Ar oneline | Ar 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 +.Qq offset +is the last offset given to the loop filter by the +packet processing code. +The +.Qq frequency +is the frequency error +of the local clock in parts-per-million (ppm). +The +.Qq time_const +controls the +.Qq stiffness +of the phase-lock loop and thus the speed at +which it can adapt to oscillator drift. +The +.Qq watchdog timer +value is the number of seconds which have elapsed since the last sample +offset was given to the loop filter. +The +.Ar oneline +and +.Ar multiline +options specify the format in which this information +is to be printed, with +.Ar 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. +The +.Qq 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 auth, bclient, monitor, pll, pps and stats flags, +as described below under the +.Ic enable +command in the +.Sx Runtime Configuration Requests +section. +There are two additional flags which are read only, +the kernel_pll and kernel_pps. +These flags indicate the synchronization status +when the precision time kernel modifications are in use. +The kernel_pll indicates +that the local clock is being disciplined by the kernel, +while the kernel_pps indicates +the kernel discipline is provided by the PPS signal. +.Pp +The +.Qq 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 +.Qq tick +may be incorrect. +.Pp +The +.Qq broadcastdelay +shows the default broadcast delay, as set by +the +.Qq broadcastdelay +configuration option, while the +.Qq authdelay +shows the default authentication delay, as set by +the +.Qq authdelay +configuration option. +.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 Xo Ic clkbug +.Ar clock_peer_address +.Op Ar ... +.Xc +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 Ns . +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 Ar 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 +.Ar 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 Ar prefer +.Xc +Identical to the +.Ic addpeer +command, except that the operating mode is client. +.It Xo Ic broadcast +.Ar peer_address +.Op Ar keyid +.Op Ar version +.Xc +Identical to the +.Ic 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 Xo Ic unconfig +.Ar peer_address +.Op Ar ... +.Xc +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 Ar time1 +.Op Ar 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 +.Ar flag +.Op Ar ... +.Xc +.It Xo Ic disable +.Ar flag +.Op Ar ... +.Xc +These commands operate in the same way as the +.Qq enable +and +.Qq disable +configuration file commands of +.Xr ntpd 8 . +Following is a description of the flags. +Note that only the auth, bclient, monitor, pll, pps and stats flags +can be set by +.Nm Ns ; +the pll_kernel and pps_kernel flags are read-only. +.Bl -tag -width indent +.It auth +Enables the server to synchronize +with unconfigured peers only if the peer has been correctly +authenticated using a trusted key and key identifier. +The default for this flag is enable. +.It bclient +Enables the server +to listen for a message from a broadcast or multicast server, +as in the +.Qq mutlicastclient +configuration option with default address. +The default for this flag is disable. +.It pll +Enables +the server to adjust its local clock by means of NTP. +If disabled, +the local clock free-runs at its intrinsic time and frequency +offset. +This flag is useful in case the local clock is controlled by +some other device or protocol and +NTP is used only to provide +synchronization to other clients. +In this case, the local clock driver is used. +See the +.Qo +Reference Clock Drivers +.Qc +page +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) +for further information. +The default for this flag is enable. +.It monitor +Enables the monitoring facility for the +.Ic monlist +command. +The default for this flag is enable. +.Ic pll +Enables the server to adjust its local clock by means of NTP. +If disabled, +the local clock free-runs at its intrinsic time and frequency offset. +This flag is useful +in case the local clock is controlled +by some other device or protocol +and NTP is used only to provide synchronization to other clients. +In this case, the local clock driver is used. +See the +.Qo +Reference Clock Drivers +.Qc +page for further information. +The default for this flag is enable. +.Ic pps +Enables the pulse-per-second (PPS) signal +when frequency and time is disciplined +by the precision time kernel modifications. +See the +.Qo +A Kernel Model for Precision Timekeeping +.Qc +page +for further information. +The default for this flag is disable. +.Ic stats +Enables the statistics facility. +See the +.Xr ntp_mon 8 +page +for further information. +The default for this flag is enable. +.Ic pll_kernel +When the precision time kernel modifications are installed, +this indicates the kernel controls the clock discipline; +otherwise, the daemon controls the clock discipline. +.Ic pps_kernel +When the precision time kernel modifications are installed +and a pulse-per-second (PPS) signal is available, +this indicates the PPS signal controls the clock discipline; +otherwise, the daemon or kernel controls the clock discipline, +as indicated by the pll_kernel flag. +.El +.It Xo Ic restrict +.Ar address +.Ar mask +.Ar flag +.Op Ar flag +.Xc +This command operates in the same was as the +.Qq restrict +configuration option of +.Xr ntpd 8 . +.It Xo Ic unrestrict +.Ar address +.Ar mask +.Ar flag +.Op Ar flag +.Xc +Unrestrict the matching entry from the restrict list. +.It Xo Ic delrestrict +.Ar address +.Ar mask +.Op Ar ntpport +.Xc +Delete the matching entry from the restrict list. +.It Ic readkeys +Cause 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 Xo Ic trustkey +.Ar keyid +.Op Ar ... +.Xc +.It Xo Ic untrustkey +.Ar keyid +.Op Ar ... +.Xc +These commands operate in the same way as the +.Qq trustedkey +and +.Qq untrustkey +configuration options 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 reset Ar counter Op Ar ... +Clear the statistics counters in various modules of the server. +See the source listing for further information. +.El +.Sh SEE ALSO +.Xr ntp_mon 8 , +.Xr ntpd 8 +.Rs +.%A David L. Mills +.%T Network Time Protocol (Version 3) +.%O RFC1305 +.Re +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto. +.Sh BUGS +.Nm +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. diff --git a/usr.sbin/ntp/doc/ntpq.8 b/usr.sbin/ntp/doc/ntpq.8 new file mode 100644 index 0000000..b19bce0 --- /dev/null +++ b/usr.sbin/ntp/doc/ntpq.8 @@ -0,0 +1,588 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 7, 2000 +.Dt NTPQ 8 +.Os +.Sh NAME +.Nm ntpq +.Nd standard NTP query program +.Sh SYNOPSIS +.Nm +.Op Fl inp +.Op Fl c Ar command +.Op Ar host ... +.Sh DESCRIPTION +.Nm +is used to query NTP servers which implement the recommended NTP mode 6 +control message format about current state and to request changes in +that state. +The program may 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. +.Nm +can also obtain and print a list of peers in a common format by sending +multiple queries to the server. +.Pp +If one or more request options is 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 +.Dq 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 +.Dq localhost +when no other host is specified. +.Nm +will prompt for commands if the standard input is a terminal device. +.Pp +.Nm +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. +.Nm +makes one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout time. +.Pp +Command line options are described following. 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. +The following options are available: +.Bl -tag -width indent +.It Fl c Ar command +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). +Multiple +.Fl c +options may be given. +.It Fl i +Force +.Nm +to operate in interactive mode. +Prompts will be written to the standard +output and commands read from the standard input. +.It Fl n +Output all host addresses in dotted-quad numeric format rather than +converting to the canonical host names. +.It Fl p +Print a list of the peers known to the server as well as a summary of +their state. +This is equivalent to the +.Ic peers +interactive command. +.El +.Ss 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 +.Qq > , +followed by a file name, to the command line. +A number of interactive format commands are executed entirely within the +.Nm +program itself and do not result in NTP mode 6 requests being sent to a +server. +These are described following. +.Bl -tag -width indent +.It Ic ? Op Ar command_keyword +.It Ic help Op Ar command_keyword +A +.Ic ? +by itself will print a list of all the command keywords +known to this incarnation of +.Nm Ns . +A +.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 +.Nm +than this manual page. +.\" +.\" XXX Both variable_name and value below should be arguments, +.\" not angle-quoted text. +.\" +.It Xo Ic addvars +.Aq variable_name Ns +.Op = Ns Aq value Ns +.Op ,... +.Xc +.It Xo Ic rmvars +.Aq variable_name Ns +.Op ,... +.Xc +.It Ic clearvars +The data carried by NTP mode 6 messages consists of a list of items of +the form +.Xo Aq variable_name Ns +.Pf = Aq value +.Xc +where the +.Qq = Ns Aq value +is ignored, and can be omitted, in requests +to the server to read variables. +.Nm +maintains an internal list in which data to be included in control +messages can be assembled, and sent using the +.Ic readlist +and +.Ic writelist +commands described below. The +.Ic 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 +.Ic rmvars +command can be used to remove individual variables from the list, while +the +.Ic clearvars +command removes all variables from the list. +.It Ic authenticate Ar yes | Ar no +Normally +.Nm +does not authenticate requests unless they are write requests. +The command +.Dq Li authenticate yes +causes +.Nm +to send authentication with all requests it makes. +Authenticated requests cause some servers +to handle requests slightly differently, +and can occasionally melt the CPU in fuzzballs if you turn +authentication on before doing a peer display. +.It Ic cooked +Causes output from query commands to be +.Qq cooked Ns . +Variables +which are recognized by the server will have their values reformatted +for human consumption. +Variables which +.Nm +thinks should have a decodeable value but didn't are marked with a +trailing +.Qq ? Ns . +.It Ic debug Ar more | Ar less | Ar off +Turn internal query program debugging on and off. +.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. +The +.Ar hostname +supplied +may be either a host name or a numeric +address. +.It Ic hostnames Ar yes | Ar no +If +.Ar yes +is specified, host names are printed in information +displays. +If +.Ar no +is given, numeric addresses are printed +instead. +The default is +.Ar 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 ntpversion Ar 1 | Ar 2 | Ar 3 | Ar 4 +Set the NTP version number which +.Nm +claims in packets. +Defaults to 3. +Note that mode 6 control messages +(and modes, for that matter) +didn't exist in NTP version 1. +There appear to be no servers left which demand version 1. +.It Ic quit +Exit +.Nm Ns . +.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 raw +Cause all output from query commands +to be printed as received from the remote server. +The only formatting and intepretation done on the data is to +transform non-ASCII data into a printable (but barely understandable) +form. +.It Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. The default +is about 5000 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 +Each peer known to an NTP server has a 16 bit integer +association identifier +assigned to it. +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. +.Pp +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 +.Ic peers +command, +which will send a preprogrammed series of messages to obtain +the data it needs, and the +.Ic mreadlist +and +.Ic mreadvar +commands, which will iterate over a range of associations. +.Bl -tag -width indent +.It Ic 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. +Note that the data returned by the +.Ic associations +command is cached internally in +.Nm Ns . +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 +.Dq Li &index +may be used as an alternative. +.\" +.\" XXX Both variable_name and value below should be arguments, +.\" not angle-quoted text. +.\" +.It Xo Ic clockvar +.Op Ar assocID Ns +.Pf [ Aq variable_name Ns +.Op = Ns Aq value Ns +.Op ,...] +.Xc +.It Xo Ic cv +.Op Ar assocID Ns +.Pf [ Aq variable_name Ns +.Op = Ns Aq value Ns +.Op ,...] +.Xc +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 +.Qq 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. +.It Ic lassocations +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 +.Ic 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 +.Ic associations +command is used, but are included in the +output of +.Ic lassociations Ns . +.It Ic lpassociations +Print data for all associations, including out-of-spec client +associations, from the internally cached list of associations. +This command differs from +.Ic passociations +only when dealing with fuzzballs. +.It Ic lpeers +Like +.Ic 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. +.It Ic mreadlist Ar assocID assocID +.It Ic mrl Ar assocID assocID +Like the +.Ic 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 +.Ic associations +command. +.It Xo Ic mreadvar +.Ar assocID assocID [ +.Aq variable_name Ns +.Op = Ns Aq value Ns +.Op ,...] +.Xc +.It Xo Ic mrv +.Ar assocID assocID [ +.Aq variable_name Ns +.Op = Ns Aq value Ns +.Op ,...] +.Xc +Like the +.Ic 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 +.Ic associations +command. +.It Ic opeers +An old form of the +.Ic peers +command with the reference ID +replaced by the local interface address. +.It Ic passociations +Print association data concerning in-spec peers from the internally +cached list of associations. +This command performs identically to the +.Ic associations +except that it displays the internally stored +data rather than making a new query. +.It Ic peers +Obtains a list of in-spec 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. +.Pp +The character in the left margin indicates the fate of this peer in the +clock selection process. +Following is a list of these characters, +the pidgeon used in the +.Ic rv +command, +and a short explanation of the condition revealed. +.Bl -tag -width indent +.It space +.Pq reject +The peer is discarded as unreachable, +synchronized to this server (synch loop) +or outrageous synchronization distance. +.It x +.Pq falsetick +The peer is discarded by the intersection algorithm +as a falseticker. +.It . +.Pq 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. +.It - +.Pq outlyer +The peer is discarded by the clustering algorithm as an outlyer. +.It + +.Pq candidate +The peer is a survivor and a candidate for the combining algorithm. +.It # +.Pq selected +The peer is a survivor, +but not among the first six peers sorted by synchronization distance. +If the assocation is ephemeral, +it may be demobilized to conserve resources. +.It * +.Pq sys.peer +The peer has been declared the system peer +and lends its variables to the system variables. +.It o +.Pq pps.peer +The peer has been declared the system peer +and lends its variables to the system 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. +.El +.Pp +The flash variable is not defined in the NTP specification, +but is included as a valuable debugging aid. +It displays the results of the packet sanity checks +defined in the NTP specification TEST1 through TEST9. +The bits for each test read in increasing sequency +from the least significant bit +and are defined as follows. +.Pp +The following TEST1 through TEST4 enumerate procedure errors. +The packet timestamps may or may not be believed, +but the remaining header data are ignored. +.Bl -tag -width indent +.It TEST1 +Duplicate packet. +A copy from somewhere. +.It TEST2 +Bogus packet. +It is not a reply to a message previously sent. +This can happen when the NTP daemon is restarted +and before a peer notices. +.It TEST3 +Unsynchronized. +One or more timestamp fields are missing. +This normally happens when the first packet from a peer is received. +.It TEST4 +Either peer delay or peer dispersion is greater than one second. +You must be joking. +.El +.Pp +The following TEST5 through TEST10 +enumerate errors in the packet header. +The packet is discarded without inspecting its contents. +.Bl -tag -width indent +.It TEST5 +Cryptographic authentication fails. +See the +.Xr ntp_auth 8 +page. +.It TEST6 +Peer is unsynchronized. +Wind up its clock first. +.It TEST7 +Peer stratum is greater than 15. +The peer is probably unsynchronized. +.It TEST8 +Either root delay or root dispersion is greater than one second. +Too far from home. +.It TEST9 +Peer cryptographic authentication fails. +Either the key identifier or key is wrong +or somebody trashed our packet. +.It TEST10 +Access is denied. +See the +.Xr ntp_acc 8 +page. +.El +.It Ic pstatus Ar assocID +Send 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. +.It Ic readlist Op Ar assocID +.It Ic rl Op Ar 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. +.\" +.\" XXX Both variable_name and value below should be arguments, +.\" not angle-quoted text. +.\" +.It Xo Ic readvar +.Op Ar assocID Ns +.Pf [ Aq variable_name Ns +.Op = Ns Aq value Ns +.Op ,...] +.Xc +.It Xo Ic rv +.Op Ar assocID Ns +.Pf [ Aq variable_name Ns +.Op = Ns Aq value Ns +.Op ,...] +.Xc +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. +.It Xo Ic writevar +.Ar assocID +.Aq variable_name Ns +.Pf = Ns Aq value Ns +.Op ,... +.Xc +Like the +.Ic readvar +request, except the specified variables are written instead of read. +.It Ic writelist Op Ar assocID +Like the +.Ic readlist +request, except the internal list variables are written instead of read. +.El +.Sh SEE ALSO +.Xr ntp_acc 8 , +.Xr ntp_auth 8 +.Sh HISTORY +Written by +.An Dennis Ferguson +at the University of Toronto. +.Sh BUGS +The +.Ic 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. diff --git a/usr.sbin/ntp/doc/ntptime.8 b/usr.sbin/ntp/doc/ntptime.8 new file mode 100644 index 0000000..2978312 --- /dev/null +++ b/usr.sbin/ntp/doc/ntptime.8 @@ -0,0 +1,68 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 7, 2000 +.Dt NTPTIME 8 +.Os +.Sh NAME +.Nm ntptime +.Nd read kernel time variables +.Sh SYNOPSIS +.Nm ntptime +.Op Fl chr +.Op Fl e Ar est_error +.Op Fl f Ar frequency +.Op Fl m Ar max_error +.Op Fl o Ar offset +.Op Fl s Ar status +.Op Fl t Ar time_constant +.Sh DESCRIPTION +This program is useful only with special kernels +described in the +.Qo +A Kernel Model for Precision Timekeeping +.Qc +page +(available as part of the HTML documentation +provided in +.Pa /usr/share/doc/ntp ) . +It reads and displays time-related kernel variables +using the +.Xr ntp_gettime 2 +and +.Xr ntp_adjtime 2 +system calls if available. +A similar display can be obtained using the +.Xr ntpdc 8 +program's +.Ic kerninfo +command. +The following options are available: +.Bl -tag -width indent +.It Fl c +Display the execution time of +.Nm +itself. +.It Fl e Ar est_error +Specify estimated error, in microseconds. +.It Fl f Ar frequency +Specify frequency offset, in parts per million. +.It Fl h +Display times in Unix timeval format. +Default is NTP format. +.It Fl l +Specify the leap bits as a code from 0 to 3. +.It Fl m Ar max_error +Display help information. +.It Fl o Ar offset +Specify clock offset, in microseconds. +.It Fl r +Display Unix and NTP times in raw format. +.It Fl s Ar status +.It Fl t Ar time_constant +Specify time constant, an integer in the range 0-4. +.El +.Sh SEE ALSO +.Xr ntp_adjtime 2 , +.Xr ntp_gettime 2 , +.Xr ntpdc 8 diff --git a/usr.sbin/ntp/doc/ntptrace.8 b/usr.sbin/ntp/doc/ntptrace.8 new file mode 100644 index 0000000..b063be4 --- /dev/null +++ b/usr.sbin/ntp/doc/ntptrace.8 @@ -0,0 +1,73 @@ +.\" +.\" $FreeBSD$ +.\" +.Dd January 6, 2000 +.Dt NTPTRACE 8 +.Os +.Sh NAME +.Nm ntptrace +.Nd trace a chain of NTP servers back to the primary source +.Sh SYNOPSIS +.Nm ntptrace +.Op Fl vdn +.Op Fl r Ar retries +.Op Fl t Ar timeout +.Op Ar server +.Sh DESCRIPTION +.Nm +determines where a given Network Time Protocol (NTP) server gets +its time from, and follows the chain of NTP servers back to their +master time source. +If given no arguments, it starts with +.Dq localhost . +.Pp +Here is an example of the output from +.Nm Ns : +.Bd -literal +% ntptrace +localhost: stratum 4, offset 0.0019529, synch distance 0.144135 +server2ozo.com: stratum 2, offset 0.0124263, synch distance 0.115784 +usndh.edu: stratum 1, offset 0.0019298, synch distance 0.011993, refid 'WWVB' +.Ed +.Pp +On each line, the fields are (left to right): the host name, the +host stratum, +the time offset between that host and the local host +(as measured by +.Nm Ns ; +this is why it is not always zero for +.Dq localhost ) , +the host +synchronization distance , +and (only for stratum-1 servers) the reference clock ID. All times +are given in seconds. +Note that the stratum is the server hop count to the primary source, +while the synchronization distance is the estimated error +relative to the primary source. +These terms are precisely defined in RFC 1305. +.Pp +The following options are available: +.Bl -tag -width indent +.It Fl d +Turn on some debugging output. +.It Fl n +Turn off the printing of host names; instead, host IP addresses +are given. This may be necessary if a nameserver is down. +.It Fl r Ar retries +Set the number of retransmission attempts for each host; the default is 5. +.It Fl t Ar timeout +Set the retransmission timeout (in seconds); the default is 2. +.It Fl v +Print verbose information about the NTP servers. +.El +.Sh SEE ALSO +.Xr xntpd 8 , +.Xr xntpdc 8 +.Rs +.%A D L Mills +.%T Network Time Protocol (Version 3) +.%O RFC1305 +.Re +.Sh BUGS +This program makes no attempt to improve accuracy by doing multiple +samples. -- cgit v1.1