diff options
Diffstat (limited to 'usr.sbin/ntp/doc')
| -rw-r--r-- | usr.sbin/ntp/doc/Makefile | 33 | ||||
| -rw-r--r-- | usr.sbin/ntp/doc/ntp-keygen.8 | 602 | ||||
| -rw-r--r-- | usr.sbin/ntp/doc/ntp.conf.5 | 2715 | ||||
| -rw-r--r-- | usr.sbin/ntp/doc/ntp.keys.5 | 120 | ||||
| -rw-r--r-- | usr.sbin/ntp/doc/ntpd.8 | 612 | ||||
| -rw-r--r-- | usr.sbin/ntp/doc/ntpdate.8 | 280 | ||||
| -rw-r--r-- | usr.sbin/ntp/doc/ntpdc.8 | 715 | ||||
| -rw-r--r-- | usr.sbin/ntp/doc/ntpq.8 | 851 | ||||
| -rw-r--r-- | usr.sbin/ntp/doc/ntptime.8 | 69 | ||||
| -rw-r--r-- | usr.sbin/ntp/doc/ntptrace.8 | 76 |
10 files changed, 0 insertions, 6073 deletions
diff --git a/usr.sbin/ntp/doc/Makefile b/usr.sbin/ntp/doc/Makefile deleted file mode 100644 index 64e3571..0000000 --- a/usr.sbin/ntp/doc/Makefile +++ /dev/null @@ -1,33 +0,0 @@ -# $FreeBSD$ - -.include <bsd.own.mk> - -FILESDIR= ${SHAREDIR}/doc/ntp - -.if ${MK_HTML} != "no" -FILES= accopt.html assoc.html audio.html authopt.html build.html \ - clockopt.html \ - config.html confopt.html copyright.html debug.html driver1.html \ - driver10.html driver11.html driver12.html driver16.html driver18.html \ - driver19.html driver2.html driver20.html driver22.html \ - driver26.html driver27.html driver28.html driver29.html \ - driver3.html driver30.html driver32.html driver33.html driver34.html \ - driver35.html driver36.html driver37.html \ - driver4.html driver5.html driver6.html driver7.html driver8.html \ - driver9.html extern.html hints.html \ - howto.html index.html kern.html \ - ldisc.html measure.html miscopt.html monopt.html mx4200data.html \ - notes.html ntpd.html ntpdate.html ntpdc.html ntpq.html ntptime.html \ - ntptrace.html parsedata.html parsenew.html patches.html porting.html \ - pps.html prefer.html quick.html rdebug.html refclock.html \ - release.html tickadj.html -.endif - -MAN= ntp.conf.5 ntp.keys.5 -MAN+= ntp-keygen.8 ntpd.8 ntpdate.8 ntpdc.8 ntpq.8 ntptime.8 - -.PATH: ${.CURDIR}/../../../contrib/ntp/html \ - ${.CURDIR}/../../../contrib/ntp/html/build \ - ${.CURDIR}/../../../contrib/ntp/html/drivers - -.include <bsd.prog.mk> diff --git a/usr.sbin/ntp/doc/ntp-keygen.8 b/usr.sbin/ntp/doc/ntp-keygen.8 deleted file mode 100644 index 536900f..0000000 --- a/usr.sbin/ntp/doc/ntp-keygen.8 +++ /dev/null @@ -1,602 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd May 17, 2006 -.Dt NTP-KEYGEN 8 -.Os -.Sh NAME -.Nm ntp-keygen -.Nd key generation program for ntpd -.Sh SYNOPSIS -.Nm -.Op Fl deGgHIMnPT -.Op Fl c Ar scheme -.Op Fl i Ar name -.Op Fl p Ar password -.Op Fl S Op Cm RSA | DSA -.Op Fl s Ar name -.Op Fl v Ar nkeys -.Sh DESCRIPTION -This program generates cryptographic data files used by the NTPv4 -authentication and identification schemes. -It generates MD5 key files used in symmetric key cryptography. -In addition, if the OpenSSL software library has been installed, -it generates keys, certificate and identity files used in public key -cryptography. -These files are used for cookie encryption, -digital signature and challenge/response identification algorithms -compatible with the Internet standard security infrastructure. -.Pp -All files are in PEM-encoded printable ASCII format, -so they can be embedded as MIME attachments in mail to other sites -and certificate authorities. -By default, files are not encrypted. -The -.Fl p Ar password -option specifies the write password and -.Fl q Ar password -option the read password for previously encrypted files. -The -.Nm -program prompts for the password if it reads an encrypted file -and the password is missing or incorrect. -If an encrypted file is read successfully and -no write password is specified, the read password is used -as the write password by default. -.Pp -The -.Xr ntpd 8 -configuration command -.Ic crypto pw Ar password -specifies the read password for previously encrypted files. -The daemon expires on the spot if the password is missing -or incorrect. -For convenience, if a file has been previously encrypted, -the default read password is the name of the host running -the program. -If the previous write password is specified as the host name, -these files can be read by that host with no explicit password. -.Pp -File names begin with the prefix -.Cm ntpkey_ -and end with the postfix -.Ar _hostname.filestamp , -where -.Ar hostname -is the owner name, usually the string returned -by the Unix gethostname() routine, and -.Ar filestamp -is the NTP seconds when the file was generated, in decimal digits. -This both guarantees uniqueness and simplifies maintenance -procedures, since all files can be quickly removed -by a -.Ic rm ntpkey\&* -command or all files generated -at a specific time can be removed by a -.Ic rm -.Ar \&*filestamp -command. -To further reduce the risk of misconfiguration, -the first two lines of a file contain the file name -and generation date and time as comments. -.Pp -All files are installed by default in the keys directory -.Pa /usr/local/etc , -which is normally in a shared filesystem -in NFS-mounted networks. -The actual location of the keys directory -and each file can be overridden by configuration commands, -but this is not recommended. -Normally, the files for each host are generated by that host -and used only by that host, although exceptions exist -as noted later on this page. -.Pp -Normally, files containing private values, -including the host key, sign key and identification parameters, -are permitted root read/write-only; -while others containing public values are permitted world readable. -Alternatively, files containing private values can be encrypted -and these files permitted world readable, -which simplifies maintenance in shared file systems. -Since uniqueness is insured by the hostname and -file name extensions, the files for a NFS server and -dependent clients can all be installed in the same shared directory. -.Pp -The recommended practice is to keep the file name extensions -when installing a file and to install a soft link -from the generic names specified elsewhere on this page -to the generated files. -This allows new file generations to be activated simply -by changing the link. -If a link is present, ntpd follows it to the file name -to extract the filestamp. -If a link is not present, -.Xr ntpd 8 -extracts the filestamp from the file itself. -This allows clients to verify that the file and generation times -are always current. -The -.Nm -program uses the same timestamp extension for all files generated -at one time, so each generation is distinct and can be readily -recognized in monitoring data. -.Ss Running the program -The safest way to run the -.Nm -program is logged in directly as root. -The recommended procedure is change to the keys directory, -usually -.Pa /usr/local/etc , -then run the program. -When run for the first time, -or if all -.Cm ntpkey -files have been removed, -the program generates a RSA host key file and matching RSA-MD5 certificate file, -which is all that is necessary in many cases. -The program also generates soft links from the generic names -to the respective files. -If run again, the program uses the same host key file, -but generates a new certificate file and link. -.Pp -The host key is used to encrypt the cookie when required and so must be RSA type. -By default, the host key is also the sign key used to encrypt signatures. -When necessary, a different sign key can be specified and this can be -either RSA or DSA type. -By default, the message digest type is MD5, but any combination -of sign key type and message digest type supported by the OpenSSL library -can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 -and RIPE160 message digest algorithms. -However, the scheme specified in the certificate must be compatible -with the sign key. -Certificates using any digest algorithm are compatible with RSA sign keys; -however, only SHA and SHA1 certificates are compatible with DSA sign keys. -.Pp -Private/public key files and certificates are compatible with -other OpenSSL applications and very likely other libraries as well. -Certificates or certificate requests derived from them should be compatible -with extant industry practice, although some users might find -the interpretation of X509v3 extension fields somewhat liberal. -However, the identification parameter files, although encoded -as the other files, are probably not compatible with anything other than Autokey. -.Pp -Running the program as other than root and using the Unix -.Ic su -command -to assume root may not work properly, since by default the OpenSSL library -looks for the random seed file -.Cm .rnd -in the user home directory. -However, there should be only one -.Cm .rnd , -most conveniently -in the root directory, so it is convenient to define the -.Cm $RANDFILE -environment variable used by the OpenSSL library as the path to -.Cm /.rnd . -.Pp -Installing the keys as root might not work in NFS-mounted -shared file systems, as NFS clients may not be able to write -to the shared keys directory, even as root. -In this case, NFS clients can specify the files in another -directory such as -.Pa /etc -using the -.Ic keysdir -command. -There is no need for one client to read the keys and certificates -of other clients or servers, as these data are obtained automatically -by the Autokey protocol. -.Pp -Ordinarily, cryptographic files are generated by the host that uses them, -but it is possible for a trusted agent (TA) to generate these files -for other hosts; however, in such cases files should always be encrypted. -The subject name and trusted name default to the hostname -of the host generating the files, but can be changed by command line options. -It is convenient to designate the owner name and trusted name -as the subject and issuer fields, respectively, of the certificate. -The owner name is also used for the host and sign key files, -while the trusted name is used for the identity files. -.Pp -.Ss Trusted Hosts and Groups -Each cryptographic configuration involves selection of a signature scheme -and identification scheme, called a cryptotype, -as explained in the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -The default cryptotype uses RSA encryption, MD5 message digest -and TC identification. -First, configure a NTP subnet including one or more low-stratum -trusted hosts from which all other hosts derive synchronization -directly or indirectly. -Trusted hosts have trusted certificates; -all other hosts have nontrusted certificates. -These hosts will automatically and dynamically build authoritative -certificate trails to one or more trusted hosts. -A trusted group is the set of all hosts that have, directly or indirectly, -a certificate trail ending at a trusted host. -The trail is defined by static configuration file entries -or dynamic means described on the -.Sx Automatic NTP Configuration Options -section of -.Xr ntp.conf 5 . -.Pp -On each trusted host as root, change to the keys directory. -To insure a fresh fileset, remove all -.Cm ntpkey -files. -Then run -.Nm -.Fl T -to generate keys and a trusted certificate. -On all other hosts do the same, but leave off the -.Fl T -flag to generate keys and nontrusted certificates. -When complete, start the NTP daemons beginning at the lowest stratum -and working up the tree. -It may take some time for Autokey to instantiate the certificate trails -throughout the subnet, but setting up the environment is completely automatic. -.Pp -If it is necessary to use a different sign key or different digest/signature -scheme than the default, run -.Nm -with the -.Fl S Ar type -option, where -.Ar type -is either -.Cm RSA -or -.Cm DSA . -The most often need to do this is when a DSA-signed certificate is used. -If it is necessary to use a different certificate scheme than the default, -run -.Nm -with the -.Fl c Ar scheme -option and selected -.Ar scheme -as needed. -If -.Nm -is run again without these options, it generates a new certificate -using the same scheme and sign key. -.Pp -After setting up the environment it is advisable to update certificates -from time to time, if only to extend the validity interval. -Simply run -.Nm -with the same flags as before to generate new certificates -using existing keys. -However, if the host or sign key is changed, -.Xr ntpd 8 -should be restarted. -When -.Xr ntpd 8 -is restarted, it loads any new files and restarts the protocol. -Other dependent hosts will continue as usual until signatures are refreshed, -at which time the protocol is restarted. -.Ss Identity Schemes -As mentioned on the Autonomous Authentication page, -the default TC identity scheme is vulnerable to a middleman attack. -However, there are more secure identity schemes available, -including PC, IFF, GQ and MV described on the -.Qq Identification Schemes -page -(maybe available at -.Li http://www.eecis.udel.edu/%7emills/keygen.html ) . -These schemes are based on a TA, one or more trusted hosts -and some number of nontrusted hosts. -Trusted hosts prove identity using values provided by the TA, -while the remaining hosts prove identity using values provided -by a trusted host and certificate trails that end on that host. -The name of a trusted host is also the name of its sugroup -and also the subject and issuer name on its trusted certificate. -The TA is not necessarily a trusted host in this sense, but often is. -.Pp -In some schemes there are separate keys for servers and clients. -A server can also be a client of another server, -but a client can never be a server for another client. -In general, trusted hosts and nontrusted hosts that operate -as both server and client have parameter files that contain -both server and client keys. -Hosts that operate -only as clients have key files that contain only client keys. -.Pp -The PC scheme supports only one trusted host in the group. -On trusted host alice run -.Nm -.Fl P -.Fl p Ar password -to generate the host key file -.Pa ntpkey_RSAkey_ Ns Ar alice.filestamp -and trusted private certificate file -.Pa ntpkey_RSA-MD5_cert_ Ns Ar alice.filestamp . -Copy both files to all group hosts; -they replace the files which would be generated in other schemes. -On each host bob install a soft link from the generic name -.Pa ntpkey_host_ Ns Ar bob -to the host key file and soft link -.Pa ntpkey_cert_ Ns Ar bob -to the private certificate file. -Note the generic links are on bob, but point to files generated -by trusted host alice. -In this scheme it is not possible to refresh -either the keys or certificates without copying them -to all other hosts in the group. -.Pp -For the IFF scheme proceed as in the TC scheme to generate keys -and certificates for all group hosts, then for every trusted host in the group, -generate the IFF parameter file. -On trusted host alice run -.Nm -.Fl T -.Fl I -.Fl p Ar password -to produce her parameter file -.Pa ntpkey_IFFpar_ Ns Ar alice.filestamp , -which includes both server and client keys. -Copy this file to all group hosts that operate as both servers -and clients and install a soft link from the generic -.Pa ntpkey_iff_ Ns Ar alice -to this file. -If there are no hosts restricted to operate only as clients, -there is nothing further to do. -As the IFF scheme is independent -of keys and certificates, these files can be refreshed as needed. -.Pp -If a rogue client has the parameter file, it could masquerade -as a legitimate server and present a middleman threat. -To eliminate this threat, the client keys can be extracted -from the parameter file and distributed to all restricted clients. -After generating the parameter file, on alice run -.Nm -.Fl e -and pipe the output to a file or mail program. -Copy or mail this file to all restricted clients. -On these clients install a soft link from the generic -.Pa ntpkey_iff_ Ns Ar alice -to this file. -To further protect the integrity of the keys, -each file can be encrypted with a secret password. -.Pp -For the GQ scheme proceed as in the TC scheme to generate keys -and certificates for all group hosts, then for every trusted host -in the group, generate the IFF parameter file. -On trusted host alice run -.Nm -.Fl T -.Fl G -.Fl p Ar password -to produce her parameter file -.Pa ntpkey_GQpar_ Ns Ar alice.filestamp , -which includes both server and client keys. -Copy this file to all group hosts and install a soft link -from the generic -.Pa ntpkey_gq_ Ns Ar alice -to this file. -In addition, on each host bob install a soft link -from generic -.Pa ntpkey_gq_ Ns Ar bob -to this file. -As the GQ scheme updates the GQ parameters file and certificate -at the same time, keys and certificates can be regenerated as needed. -.Pp -For the MV scheme, proceed as in the TC scheme to generate keys -and certificates for all group hosts. -For illustration assume trish is the TA, alice one of several trusted hosts -and bob one of her clients. -On TA trish run -.Nm -.Fl V Ar n -.Fl p Ar password , -where -.Ar n -is the number of revokable keys (typically 5) to produce -the parameter file -.Pa ntpkeys_MVpar_ Ns Ar trish.filestamp -and client key files -.Pa ntpkeys_MVkeyd_ Ns Ar trish.filestamp -where -.Ar d -is the key number (0 \&< -.Ar d -\&< -.Ar n ) . -Copy the parameter file to alice and install a soft link -from the generic -.Pa ntpkey_mv_ Ns Ar alice -to this file. -Copy one of the client key files to alice for later distribution -to her clients. -It doesn't matter which client key file goes to alice, -since they all work the same way. -Alice copies the client key file to all of her cliens. -On client bob install a soft link from generic -.Pa ntpkey_mvkey_ Ns Ar bob -to the client key file. -As the MV scheme is independent of keys and certificates, -these files can be refreshed as needed. -.Ss Command Line Options -.Bl -tag -width indent -.It Fl c Ar scheme -Select certificate message digest/signature encryption scheme. -The -.Ar scheme -can be one of the following: -. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , -or -.Cm DSA-SHA1 . -Note that RSA schemes must be used with a RSA sign key and DSA -schemes must be used with a DSA sign key. -The default without this option is -.Cm RSA-MD5 . -.It Fl d -Enable debugging. -This option displays the cryptographic data produced in eye-friendly billboards. -.It Fl e -Write the IFF client keys to the standard output. -This is intended for automatic key distribution by mail. -.It Fl G -Generate parameters and keys for the GQ identification scheme, -obsoleting any that may exist. -.It Fl g -Generate keys for the GQ identification scheme -using the existing GQ parameters. -If the GQ parameters do not yet exist, create them first. -.It Fl H -Generate new host keys, obsoleting any that may exist. -.It Fl I -Generate parameters for the IFF identification scheme, -obsoleting any that may exist. -.It Fl i Ar name -Set the suject name to -.Ar name . -This is used as the subject field in certificates -and in the file name for host and sign keys. -.It Fl M -Generate MD5 keys, obsoleting any that may exist. -.It Fl P -Generate a private certificate. -By default, the program generates public certificates. -.It Fl p Ar password -Encrypt generated files containing private data with -.Ar password -and the DES-CBC algorithm. -.It Fl q -Set the password for reading files to password. -.It Fl S Oo Cm RSA | DSA Oc -Generate a new sign key of the designated type, -obsoleting any that may exist. -By default, the program uses the host key as the sign key. -.It Fl s Ar name -Set the issuer name to -.Ar name . -This is used for the issuer field in certificates -and in the file name for identity files. -.It Fl T -Generate a trusted certificate. -By default, the program generates a non-trusted certificate. -.It Fl V Ar nkeys -Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. -.El -.Ss Random Seed File -All cryptographically sound key generation schemes must have means -to randomize the entropy seed used to initialize -the internal pseudo-random number generator used -by the library routines. -The OpenSSL library uses a designated random seed file for this purpose. -The file must be available when starting the NTP daemon and -.Nm -program. -If a site supports OpenSSL or its companion OpenSSH, -it is very likely that means to do this are already available. -.Pp -It is important to understand that entropy must be evolved -for each generation, for otherwise the random number sequence -would be predictable. -Various means dependent on external events, such as keystroke intervals, -can be used to do this and some systems have built-in entropy sources. -Suitable means are described in the OpenSSL software documentation, -but are outside the scope of this page. -.Pp -The entropy seed used by the OpenSSL library is contained in a file, -usually called -.Cm .rnd , -which must be available when starting the NTP daemon -or the -.Nm -program. -The NTP daemon will first look for the file -using the path specified by the -.Ic randfile -subcommand of the -.Ic crypto -configuration command. -If not specified in this way, or when starting the -.Nm -program, -the OpenSSL library will look for the file using the path specified -by the -.Ev RANDFILE -environment variable in the user home directory, -whether root or some other user. -If the -.Ev RANDFILE -environment variable is not present, -the library will look for the -.Cm .rnd -file in the user home directory. -If the file is not available or cannot be written, -the daemon exits with a message to the system log and the program -exits with a suitable error message. -.Ss Cryptographic Data Files -All other file formats begin with two lines. -The first contains the file name, including the generated host name -and filestamp. -The second contains the datestamp in conventional Unix date format. -Lines beginning with # are considered comments and ignored by the -.Nm -program and -.Xr ntpd 8 -daemon. -Cryptographic values are encoded first using ASN.1 rules, -then encrypted if necessary, and finally written PEM-encoded -printable ASCII format preceded and followed by MIME content identifier lines. -.Pp -The format of the symmetric keys file is somewhat different -than the other files in the interest of backward compatibility. -Since DES-CBC is deprecated in NTPv4, the only key format of interest -is MD5 alphanumeric strings. -Following hte heard the keys are -entered one per line in the format -.D1 Ar keyno type key -where -.Ar keyno -is a positive integer in the range 1-65,535, -.Ar type -is the string MD5 defining the key format and -.Ar key -is the key itself, -which is a printable ASCII string 16 characters or less in length. -Each character is chosen from the 93 printable characters -in the range 0x21 through 0x7f excluding space and the -.Ql # -character. -.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 human readable ASCII format. -.Pp -The -.Nm -program generates a MD5 symmetric keys file -.Pa ntpkey_MD5key_ Ns Ar hostname.filestamp . -Since the file contains private shared keys, -it should be visible only to root and distributed by secure means -to other subnet hosts. -The NTP daemon loads the file -.Pa ntp.keys , -so -.Nm -installs a soft link from this name to the generated file. -Subsequently, similar soft links must be installed by manual -or automated means on the other subnet hosts. -While this file is not used with the Autokey Version 2 protocol, -it is needed to authenticate some remote configuration commands -used by the -.Xr ntpq 8 -and -.Xr ntpdc 8 -utilities. -.Sh Bugs -It can take quite a while to generate some cryptographic values, -from one to several minutes with modern architectures -such as UltraSPARC and up to tens of minutes to an hour -with older architectures such as SPARC IPC. diff --git a/usr.sbin/ntp/doc/ntp.conf.5 b/usr.sbin/ntp/doc/ntp.conf.5 deleted file mode 100644 index a04f16e..0000000 --- a/usr.sbin/ntp/doc/ntp.conf.5 +++ /dev/null @@ -1,2715 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd December 21, 2006 -.Dt NTP.CONF 5 -.Os -.Sh NAME -.Nm ntp.conf -.Nd Network Time Protocol (NTP) daemon configuration file -.Sh SYNOPSIS -.Nm /etc/ntp.conf -.Sh DESCRIPTION -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 -.Pa /etc/rc.d/ntpdate -script reads this file to get a list of NTP servers to use if the -variable -.Dq Li ntpdate_hosts -was not declared. -Refer to the -.Xr rc.conf 5 -man page for further info about this. -.Pp -The file format is similar to other -.Ux -configuration files. -Comments begin with a -.Ql # -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 -The rest of this page describes the configuration and control options. -The -.Qq Notes on Configuring NTP and Setting up a NTP Subnet -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) -contains an extended discussion of these options. -In addition to the discussion of general -.Sx Configuration Options , -there are sections describing the following supported functionality -and the options used to control it: -.Bl -bullet -offset indent -.It -.Sx Authentication Support -.It -.Sx Monitoring Support -.It -.Sx Access Control Support -.It -.Sx Automatic NTP Configuration Options -.It -.Sx Reference Clock Support -.It -.Sx Miscellaneous Options -.El -.Pp -Following these is a section describing -.Sx Miscellaneous 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. -.Sh Configuration Support -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 arguments. -There are two -classes of commands, configuration commands that configure a -persistent association with a remote server or peer or reference -clock, and auxiliary commands that specify environmental variables -that control various related operations. -.Ss Configuration Commands -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 (IPv4 class A, B and C), (b) the -broadcast address of a local interface, (m) a multicast address (IPv4 -class D), or (r) a reference clock address (127.127.x.x). -Note that -only those options applicable to each command are listed below. -Use -of options not listed may not be caught as an error, but may result -in some weird and even destructive behavior. -.Pp -If the Basic Socket Interface Extensions for IPv6 (RFC-2553) -is detected, support for the IPv6 address family is generated -in addition to the default support of the IPv4 address family. -In a few cases, including the reslist billboard generated -by ntpdc, IPv6 addresses are automatically generated. -IPv6 addresses can be identified by the presence of colons -.Dq \&: -in the address field. -IPv6 addresses can be used almost everywhere where -IPv4 addresses can be used, -with the exception of reference clock addresses, -which are always IPv4. -.Pp -Note that in contexts where a host name is expected, a -.Fl 4 -qualifier preceding -the host name forces DNS resolution to the IPv4 namespace, -while a -.Fl 6 -qualifier forces DNS resolution to the IPv6 namespace. -See IPv6 references for the -equivalent classes for that address family. -.Bl -tag -width indent -.It Xo Ic server Ar address -.Op Cm key Ar key \&| Cm autokey -.Op Cm burst -.Op Cm iburst -.Op Cm version Ar version -.Op Cm prefer -.Op Cm minpoll Ar minpoll -.Op Cm maxpoll Ar maxpoll -.Xc -.It Xo Ic peer Ar address -.Op Cm key Ar key \&| Cm autokey -.Op Cm version Ar version -.Op Cm prefer -.Op Cm minpoll Ar minpoll -.Op Cm maxpoll Ar maxpoll -.Xc -.It Xo Ic broadcast Ar address -.Op Cm key Ar key \&| Cm autokey -.Op Cm version Ar version -.Op Cm prefer -.Op Cm minpoll Ar minpoll -.Op Cm ttl Ar ttl -.Xc -.It Xo Ic manycastclient Ar address -.Op Cm key Ar key \&| Cm autokey -.Op Cm version Ar version -.Op Cm prefer -.Op Cm minpoll Ar minpoll -.Op Cm maxpoll Ar maxpoll -.Op Cm ttl Ar ttl -.Xc -.El -.Pp -These four commands specify the time server name or address to -be used and the mode in which to operate. -The -.Ar 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 -.Qq Association Management -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -.Bl -tag -width indent -.It Ic server -For type s and r addresses, this command mobilizes a persistent -client mode association with the specified remote server or local -radio clock. -In this mode the local clock can synchronized to the -remote server, but the remote server can never be synchronized to -the local clock. -This command should -.Em not -be used for type -b or m addresses. -.It Ic peer -For type s addresses (only), this command mobilizes a -persistent symmetric-active mode association with the specified -remote peer. -In this mode the local clock can be synchronized to -the remote peer or the remote peer can be synchronized to the local -clock. -This is useful in a network of servers where, depending on -various failure scenarios, either the local or remote peer may be -the better source of time. -This command should NOT be used for type -b, m or r addresses. -.It Ic broadcast -For type b and m addresses (only), this -command mobilizes a persistent broadcast mode association. -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 broadcast mode the local server sends periodic broadcast -messages to a client population at the -.Ar 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 IPv4 224.0.1.1 and -IPv6 ff05::101 (site local) exclusively to -NTP, but other nonconflicting 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 command 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 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. -The -.Ic manycastserver -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 -.Ar 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 -Options: -.Bl -tag -width indent -.It Cm autokey -All packets sent to and received from the server or peer are to -include authentication fields encrypted using the autokey scheme -described in -.Sx Authentication Options . -.It Cm burst -when the server is reachable, send a burst of eight packets -instead of the usual one. -The packet spacing is normally 2 s; -however, the spacing between the first and second packets -can be changed with the calldelay command to allow -additional time for a modem or ISDN call to complete. -This is designed to improve timekeeping quality -with the -.Ic server -command and s addresses. -.It Cm iburst -When the server is unreachable, send a burst of eight packets -instead of the usual one. -The packet spacing is normally 2 s; -however, the spacing between the first two packets can be -changed with the calldelay command to allow -additional time for a modem or ISDN call to complete. -This is designed to speed the initial synchronization -acquisition with the -.Ic server -command and s addresses and when -.Xr ntpd 8 -is started with the -.Fl q -option. -.It Cm key Ar key -All packets sent to and received from the server or peer are to -include authentication fields encrypted using the specified -.Ar key -identifier with values from 1 to 65534, inclusive. -The -default is to include no encryption field. -.It Cm minpoll Ar minpoll -.It Cm maxpoll Ar maxpoll -These options specify the minimum and maximum poll intervals -for NTP messages, as a power of 2 in seconds -The maximum poll -interval defaults to 10 (1,024 s), but can be increased by the -.Cm maxpoll -option to an upper limit of 17 (36.4 h). -The -minimum poll interval defaults to 6 (64 s), but can be decreased by -the -.Cm minpoll -option to a lower limit of 4 (16 s). -.It Cm noselect -Marks the server as unused, except for display purposes. -The server is discarded by the selection algorithm. -.It Cm 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 -.Qq Mitigation Rules and the prefer Keyword -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) -for further information. -.It Cm ttl Ar ttl -This option is used only with broadcast server and manycast -client modes. -It specifies the time-to-live -.Ar ttl -to -use on broadcast server and multicast server and the maximum -.Ar ttl -for the expanding ring search with manycast -client packets. -Selection of the proper value, which defaults to -127, is something of a black art and should be coordinated with the -network administrator. -.It Cm 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. -.El -.Ss Auxiliary Commands -.Bl -tag -width indent -.It Ic broadcastclient -This command enables reception of broadcast server messages to -any local interface (type b) address. -Upon receiving a message for -the first time, the broadcast client measures the nominal server -propagation delay using a brief client/server exchange with the -server, then enters the broadcast client mode, in which it -synchronizes to succeeding broadcast messages. -Note that, in order -to avoid accidental or malicious disruption in this mode, both the -server and client should operate using symmetric-key or public-key -authentication as described in -.Sx Authentication Options . -.It Ic manycastserver Ar address ... -This command enables reception of manycast client 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 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. -Note that, in order to avoid -accidental or malicious disruption in this mode, both the server -and client should operate using symmetric-key or public-key -authentication as described in -.Sx Authentication Options . -.It Ic multicastclient Ar address ... -This command enables reception of multicast server messages to -the multicast group address(es) (type m) specified. -Upon receiving -a message for the first time, the multicast client measures the -nominal server propagation delay using a brief client/server -exchange with the server, then enters the broadcast client mode, in -which it synchronizes to succeeding multicast messages. -Note that, -in order to avoid accidental or malicious disruption in this mode, -both the server and client should operate using symmetric-key or -public-key authentication as described in -.Sx Authentication Options . -.El -.Sh Authentication Support -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) algorithm -operating in Cipher Block Chaining (CBC) mode, commonly called -DES-CBC. -Subsequently, this was replaced by the RSA Message Digest -5 (MD5) algorithm 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. -.Pp -NTPv4 retains the NTPv3 scheme, properly described as symmetric key -cryptography and, in addition, provides a new Autokey scheme -based on public key cryptography. -Public key cryptography is generally considered more secure -than symmetric key cryptography, since the security is based -on a private value which is generated by each server and -never revealed. -With Autokey all key distribution and -management functions involve only public values, which -considerably simplifies key distribution and storage. -Public key management is based on X.509 certificates, -which can be provided by commercial services or -produced by utility programs in the OpenSSL software library -or the NTPv4 distribution. -.Pp -While the algorithms for symmetric key cryptography are -included in the NTPv4 distribution, public key cryptography -requires the OpenSSL software library to be installed -before building the NTP distribution. -Directions for doing that -are on the Building and Installing the Distribution page. -.Pp -Authentication is configured separately for each association -using the -.Cm key -or -.Cm autokey -subcommand on the -.Ic peer , -.Ic server , -.Ic broadcast -and -.Ic manycastclient -configuration commands as described in -.Sx Configuration Options -page. -The authentication -options described below specify the locations of the key files, -if other than default, which symmetric keys are trusted -and the interval between various operations, if other than default. -.Pp -Authentication is always enabled, -although ineffective if not configured as -described below. -If a NTP packet arrives -including a message authentication -code (MAC), it is accepted only if it -passes all cryptographic checks. -The -checks require correct key ID, key value -and message digest. -If the packet has -been modified in any way or replayed -by an intruder, it will fail one or more -of these checks and be discarded. -Furthermore, the Autokey scheme requires a -preliminary protocol exchange to obtain -the server certificate, verify its -credentials and initialize the protocol -.Pp -The -.Cm auth -flag controls whether new associations or -remote configuration commands require cryptographic authentication. -This flag can be set or reset by the -.Ic enable -and -.Ic disable -commands and also by remote -configuration commands sent by a -.Xr ntpdc 8 -program running in -another machine. -If this flag is enabled, which is the default -case, new broadcast client and symmetric passive associations and -remote configuration commands must be cryptographically -authenticated using either symmetric key or public key cryptography. -If this -flag is disabled, these operations are effective -even if not cryptographic -authenticated. -It should be understood -that operating with the -.Ic auth -flag disabled invites a significant vulnerability -where a rogue hacker can -masquerade as a falseticker and seriously -disrupt system timekeeping. -It is -important to note that this flag has no purpose -other than to allow or disallow -a new association in response to new broadcast -and symmetric active messages -and remote configuration commands and, in particular, -the flag has no effect on -the authentication process itself. -.Pp -An attractive alternative where multicast support is available -is manycast mode, in which clients periodically troll -for servers as described in the -.Sx Automatic NTP Configuration Options -page. -Either symmetric key or public key -cryptographic authentication can be used in this mode. -The principle advantage -of manycast mode is that potential servers need not be -configured in advance, -since the client finds them during regular operation, -and the configuration -files for all clients can be identical. -.Pp -The security model and protocol schemes for -both symmetric key and public key -cryptography are summarized below; -further details are in the briefings, papers -and reports at the NTP project page linked from -.Li http://www.ntp.org/ . -.Ss Symmetric-Key Cryptography -The original RFC-1305 specification allows any one of possibly -65,534 keys, each distinguished by a 32-bit key identifier, to -authenticate an association. -The servers and clients involved must -agree on the key and key identifier to -authenticate NTP packets. -Keys and -related information are specified in a key -file, usually called -.Pa ntp.keys , -which must be distributed and stored using -secure means beyond the scope of the NTP protocol itself. -Besides the keys used -for ordinary NTP associations, -additional keys 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 specified in the -.Ic keys -configuration command and installs the keys -in the key cache. -However, -individual keys must be activated with the -.Ic trusted -command before use. -This -allows, for instance, the installation of possibly -several batches of keys and -then activating or deactivating 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 -.Xr ntpq 8 -utility. -.Ss Public Key Cryptography -NTPv4 supports the original NTPv3 symmetric key scheme -described in RFC-1305 and in addition the Autokey protocol, -which is based on public key cryptography. -The Autokey Version 2 protocol described on the Autokey Protocol -page verifies packet integrity using MD5 message digests -and verifies the source with digital signatures and any of several -digest/signature schemes. -Optional identity schemes described on the Identity Schemes -page and based on cryptographic challenge/response algorithms -are also available. -Using all of these schemes provides strong security against -replay with or without modification, spoofing, masquerade -and most forms of clogging attacks. -.\" .Pp -.\" The cryptographic means necessary for all Autokey operations -.\" is provided by the OpenSSL software library. -.\" This library is available from http://www.openssl.org/ -.\" and can be installed using the procedures outlined -.\" in the Building and Installing the Distribution page. -.\" Once installed, -.\" the configure and build -.\" process automatically detects the library and links -.\" the library routines required. -.Pp -The Autokey protocol has several modes of operation -corresponding to the various NTP modes supported. -Most modes use a special cookie which can be -computed independently by the client and server, -but encrypted in transmission. -All modes use in addition a variant of the S-KEY scheme, -in which a pseudo-random key list is generated and used -in reverse order. -These schemes are described along with an executive summary, -current status, briefing slides and reading list on the -.Sx Autonomous Authentication -page. -.Pp -The specific cryptographic environment used by Autokey servers -and clients is determined by a set of files -and soft links generated by the -.Xr ntp-keygen 8 -program. -This includes a required host key file, -required certificate file and optional sign key file, -leapsecond file and identity scheme files. -The -digest/signature scheme is specified in the X.509 certificate -along with the matching sign key. -There are several schemes -available in the OpenSSL software library, each identified -by a specific string such as -.Cm md5WithRSAEncryption , -which stands for the MD5 message digest with RSA -encryption scheme. -The current NTP distribution supports -all the schemes in the OpenSSL library, including -those based on RSA and DSA digital signatures. -.Pp -NTP secure groups can be used to define cryptographic compartments -and security hierarchies. -It is important that every host -in the group be able to construct a certificate trail to one -or more trusted hosts in the same group. -Each group -host runs the Autokey protocol to obtain the certificates -for all hosts along the trail to one or more trusted hosts. -This requires the configuration file in all hosts to be -engineered so that, even under anticipated failure conditions, -the NTP subnet will form such that every group host can find -a trail to at least one trusted host. -.Ss Naming and Addressing -It is important to note that Autokey does not use DNS to -resolve addresses, since DNS can't be completely trusted -until the name servers have synchronized clocks. -The cryptographic name used by Autokey to bind the host identity -credentials and cryptographic values must be independent -of interface, network and any other naming convention. -The name appears in the host certificate in either or both -the subject and issuer fields, so protection against -DNS compromise is essential. -.Pp -By convention, the name of an Autokey host is the name returned -by the Unix -.Xr gethostname 2 -system call or equivalent in other systems. -By the system design -model, there are no provisions to allow alternate names or aliases. -However, this is not to say that DNS aliases, different names -for each interface, etc., are constrained in any way. -.Pp -It is also important to note that Autokey verifies authenticity -using the host name, network address and public keys, -all of which are bound together by the protocol specifically -to deflect masquerade attacks. -For this reason Autokey -includes the source and destinatino IP addresses in message digest -computations and so the same addresses must be available -at both the server and client. -For this reason operation -with network address translation schemes is not possible. -This reflects the intended robust security model where government -and corporate NTP servers are operated outside firewall perimeters. -.Ss Operation -A specific combination of authentication scheme (none, -symmetric key, public key) and identity scheme is called -a cryptotype, although not all combinations are compatible. -There may be management configurations where the clients, -servers and peers may not all support the same cryptotypes. -A secure NTPv4 subnet can be configured in many ways while -keeping in mind the principles explained above and -in this section. -Note however that some cryptotype -combinations may successfully interoperate with each other, -but may not represent good security practice. -.Pp -The cryptotype of an association is determined at the time -of mobilization, either at configuration time or some time -later when a message of appropriate cryptotype arrives. -When mobilized by a -.Ic server -or -.Ic peer -configuration command and no -.Ic key -or -.Ic autokey -subcommands are present, the association is not -authenticated; if the -.Ic key -subcommand is present, the association is authenticated -using the symmetric key ID specified; if the -.Ic autokey -subcommand is present, the association is authenticated -using Autokey. -.Pp -When multiple identity schemes are supported in the Autokey -protocol, the first message exchange determines which one is used. -The client request message contains bits corresponding -to which schemes it has available. -The server response message -contains bits corresponding to which schemes it has available. -Both server and client match the received bits with their own -and select a common scheme. -.Pp -Following the principle that time is a public value, -a server responds to any client packet that matches -its cryptotype capabilities. -Thus, a server receiving -an unauthenticated packet will respond with an unauthenticated -packet, while the same server receiving a packet of a cryptotype -it supports will respond with packets of that cryptotype. -However, unconfigured broadcast or manycast client -associations or symmetric passive associations will not be -mobilized unless the server supports a cryptotype compatible -with the first packet received. -By default, unauthenticated associations will not be mobilized -unless overridden in a decidedly dangerous way. -.Pp -Some examples may help to reduce confusion. -Client Alice has no specific cryptotype selected. -Server Bob has both a symmetric key file and minimal Autokey files. -Alice's unauthenticated messages arrive at Bob, who replies with -unauthenticated messages. -Cathy has a copy of Bob's symmetric -key file and has selected key ID 4 in messages to Bob. -Bob verifies the message with his key ID 4. -If it's the -same key and the message is verified, Bob sends Cathy a reply -authenticated with that key. -If verification fails, -Bob sends Cathy a thing called a crypto-NAK, which tells her -something broke. -She can see the evidence using the ntpq program. -.Pp -Denise has rolled her own host key and certificate. -She also uses one of the identity schemes as Bob. -She sends the first Autokey message to Bob and they -both dance the protocol authentication and identity steps. -If all comes out okay, Denise and Bob continue as described above. -.Pp -It should be clear from the above that Bob can support -all the girls at the same time, as long as he has compatible -authentication and identity credentials. -Now, Bob can act just like the girls in his own choice of servers; -he can run multiple configured associations with multiple different -servers (or the same server, although that might not be useful). -But, wise security policy might preclude some cryptotype -combinations; for instance, running an identity scheme -with one server and no authentication with another might not be wise. -.Ss Key Management -The cryptographic values used by the Autokey protocol are -incorporated as a set of files generated by the -.Xr ntp-keygen 8 -utility program, including symmetric key, host key and -public certificate files, as well as sign key, identity parameters -and leapseconds files. -Alternatively, host and sign keys and -certificate files can be generated by the OpenSSL utilities -and certificates can be imported from public certificate -authorities. -Note that symmetric keys are necessary for the -.Xr ntpq 8 -and -.Xr ntpdc 8 -utility programs. -The remaining files are necessary only for the -Autokey protocol. -.Pp -Certificates imported from OpenSSL or public certificate -authorities have certian limitations. -The certificate should be in ASN.1 syntax, X.509 Version 3 -format and encoded in PEM, which is the same format -used by OpenSSL. -The overall length of the certificate encoded -in ASN.1 must not exceed 1024 bytes. -The subject distinguished -name field (CN) is the fully qualified name of the host -on which it is used; the remaining subject fields are ignored. -The certificate extension fields must not contain either -a subject key identifier or a issuer key identifier field; -however, an extended key usage field for a trusted host must -contain the value -.Cm trustRoot ; . -Other extension fields are ignored. -.Ss Authentication Commands -.Bl -tag -width indent -.It Ic autokey Op Ar logsec -Specifies the interval between regenerations of the session key -list used with the Autokey protocol. -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 Ic controlkey Ar key -Specifies the key identifier to use with the -.Xr ntpq 8 -utility, which uses the standard -protocol defined in RFC-1305. -The -.Ar key -argument is -the key identifier for a trusted key, where the value can be in the -range 1 to 65,534, inclusive. -.It Xo Ic crypto -.Op Cm cert Ar file -.Op Cm leap Ar file -.Op Cm randfile Ar file -.Op Cm host Ar file -.Op Cm sign Ar file -.Op Cm gq Ar file -.Op Cm gqpar Ar file -.Op Cm iffpar Ar file -.Op Cm mvpar Ar file -.Op Cm pw Ar password -.Xc -This command requires the OpenSSL library. -It activates public key -cryptography, selects the message digest and signature -encryption scheme and loads the required private and public -values described above. -If one or more files are left unspecified, -the default names are used as described above. -Unless the complete path and name of the file are specified, the -location of a file is relative to the keys directory specified -in the -.Ic keysdir -command or default -.Pa /usr/local/etc . -Following are the subcommands: -.Bl -tag -width indent -.It Cm cert Ar file -Specifies the location of the required host public certificate file. -This overrides the link -.Pa ntpkey_cert_ Ns Ar hostname -in the keys directory. -.It Cm gqpar Ar file -Specifies the location of the optional GQ parameters file. -This -overrides the link -.Pa ntpkey_gq_ Ns Ar hostname -in the keys directory. -.It Cm host Ar file -Specifies the location of the required host key file. -This overrides -the link -.Pa ntpkey_key_ Ns Ar hostname -in the keys directory. -.It Cm iffpar Ar file -Specifies the location of the optional IFF parameters file.This -overrides the link -.Pa ntpkey_iff_ Ns Ar hostname -in the keys directory. -.It Cm leap Ar file -Specifies the location of the optional leapsecond file. -This overrides the link -.Pa ntpkey_leap -in the keys directory. -.It Cm mvpar Ar file -Specifies the location of the optional MV parameters file. -This -overrides the link -.Pa ntpkey_mv_ Ns Ar hostname -in the keys directory. -.It Cm pw Ar password -Specifies the password to decrypt files containing private keys and -identity parameters. -This is required only if these files have been -encrypted. -.It Cm randfile Ar file -Specifies the location of the random seed file used by the OpenSSL -library. -The defaults are described in the main text above. -.It Cm sign Ar file -Specifies the location of the optional sign key file. -This overrides -the link -.Pa ntpkey_sign_ Ns Ar hostname -in the keys directory. -If this file is -not found, the host key is also the sign key. -.El -.It Ic keys Ar keyfile -Specifies the complete path and location of the MD5 key file -containing the keys and key identifiers used by -.Xr ntpd 8 , -.Xr ntpq 8 -and -.Xr ntpdc -when operating with symmetric key cryptography. -This is the same operation as the -.Fl k -command line option. -.It Ic keysdir Ar path -This command specifies the default directory path for -cryptographic keys, parameters and certificates. -The default is -.Pa /usr/local/etc/ . -.It Ic requestkey Ar key -Specifies the key identifier to use with the -.Xr ntpdc 8 -utility program, which uses a -proprietary protocol specific to this implementation of -.Xr ntpd 8 . -The -.Ar key -argument is a key identifier -for the trusted key, where the value can be in the range 1 to -65,534, inclusive. -.It Ic revoke Ar logsec -Specifies the interval between re-randomization of certain -cryptographic values used by the Autokey scheme, as a power of 2 in -seconds. -These values need to be updated frequently in order to -deflect brute-force attacks on the algorithms of the scheme; -however, updating some values is a relatively expensive operation. -The default interval is 16 (65,536 s or about 18 hours). -For poll -intervals above the specified interval, the values will be updated -for every message sent. -.It Ic trustedkey Ar key ... -Specifies the key identifiers which are trusted for the -purposes of authenticating peers with symmetric key cryptography, -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 key -arguments are 32-bit unsigned -integers with values from 1 to 65,534. -.El -.Ss Error Codes -The following error codes are reported via the NTP control -and monitoring protocol trap mechanism. -.Bl -tag -width indent -.It 101 -.Pq bad field format or length -The packet has invalid version, length or format. -.It 102 -.Pq bad timestamp -The packet timestamp is the same or older than the most recent received. -This could be due to a replay or a server clock time step. -.It 103 -.Pq bad filestamp -The packet filestamp is the same or older than the most recent received. -This could be due to a replay or a key file generation error. -.It 104 -.Pq bad or missing public key -The public key is missing, has incorrect format or is an unsupported type. -.It 105 -.Pq unsupported digest type -The server requires an unsupported digest/signature scheme. -.It 106 -.Pq mismatched digest types -Not used. -.It 107 -.Pq bad signature length -The signature length does not match the current public key. -.It 108 -.Pq signature not verified -The message fails the signature check. -It could be bogus or signed by a -different private key. -.It 109 -.Pq certificate not verified -The certificate is invalid or signed with the wrong key. -.It 110 -.Pq certificate not verified -The certificate is not yet valid or has expired or the signature could not -be verified. -.It 111 -.Pq bad or missing cookie -The cookie is missing, corrupted or bogus. -.It 112 -.Pq bad or missing leapseconds table -The leapseconds table is missing, corrupted or bogus. -.It 113 -.Pq bad or missing certificate -The certificate is missing, corrupted or bogus. -.It 114 -.Pq bad or missing identity -The identity key is missing, corrupt or bogus. -.El -.Sh Monitoring Support -.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 this distribution. -Using -these facilities and -.Ux -.Xr cron 8 -jobs, the data can be -automatically summarized and archived for retrospective analysis. -.Ss Monitoring Commands -.Bl -tag -width indent -.It Ic statistics Ar name ... -Enables writing of statistics records. -Currently, four kinds of -.Ar name -statistics are supported. -.Bl -tag -width indent -.It Cm 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 -.Cm clockstats : -.Bd -literal -49213 525.624 127.127.4.1 93 226 00:08:29.606 D -.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 -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 Cm cryptostats -This option requires the OpenSSL cryptographic software library. -It -enables recording of cryptographic public key protocol information. -Each message received by the protocol module appends a line of the -following form to the file generation set named -.Cm cryptostats : -.Bd -literal -49213 525.624 127.127.4.1 message -.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 -address in dotted-quad notation, The final message field includes the -message type and certain ancillary information. -See the -.Sx Authentication Options -section for further information. -.It Cm 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 -.Cm loopstats : -.Bd -literal -50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 -.Ed -.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 Cm 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 -.Cm peerstats : -.Bd -literal -48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 -.Ed -.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 four fields show the offset, -delay, dispersion and RMS jitter, all in seconds. -.It Cm 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 -.Cm rawstats : -.Bd -literal -50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 -.Ed -.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 remote peer or clock address followed by the local 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. -.It Cm sysstats -Enables recording of ntpd statistics counters on a periodic basis. -Each -hour a line of the following form is appended to the file generation -set named -.Cm sysstats : -.Bd -literal -50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 -.Ed -.Pp -The first two fields show the date (Modified Julian Day) and time -(seconds and fraction past UTC midnight). -The remaining ten fields show -the statistics counter values accumulated since the last generated -line. -.Bl -tag -width indent -.It Time since restart Cm 36000 -Time in hours since the system was last rebooted. -.It Packets received Cm 81965 -Total number of packets received. -.It Packets processed Cm 0 -Number of packets received in response to previous packets sent -.It Current version Cm 9546 -Number of packets matching the current NTP version. -.It Previous version Cm 56 -Number of packets matching the previous NTP version. -.It Bad version Cm 71793 -Number of packets matching neither NTP version. -.It Access denied Cm 512 -Number of packets denied access for any reason. -.It Bad length or format Cm 540 -Number of packets with invalid length, format or port number. -.It Bad authentication Cm 10 -Number of packets not verified as authentic. -.It Rate exceeded Cm 147 -Number of packets discarded due to rate limitation. -.El -.It Cm 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) -.Cm filegen -filename prefix to be modified for file generation sets, which -is useful for handling statistics logs. -.It Cm filegen Ar name Xo -.Op Cm file Ar filename -.Op Cm type Ar typename -.Op Cm link | nolink -.Op Cm 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 administrational -operations without the risk of disturbing the operation of ntpd. -(Most important: 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 Cm name -This is the type of the statistics records, as shown in the -.Cm statistics -command. -.It Cm file Ar filename -This is the file name for the statistics records. -Filenames of set -members are built from three concatenated elements -.Ar Cm prefix , -.Ar Cm filename -and -.Ar Cm suffix : -.Bl -tag -width indent -.It Cm prefix -This is a constant filename path. -It is not subject to -modifications via the -.Ar 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 -.Ar loopstats -and -.Ar peerstats -generation can be configured using the -.Ar statsdir -option explained above. -.It Cm filename -This string is directly concatenated to the prefix mentioned -above (no intervening -.Ql / ) . -This can be modified using -the file argument to the -.Ar filegen -statement. -No -.Pa .. -elements are -allowed in this component to prevent filenames referring to -parts outside the filesystem hierarchy denoted by -.Ar prefix . -.It Cm suffix -This part is reflects individual elements of a file set. -It is -generated according to the type of a file set. -.El -.It Cm type Ar typename -A file generation set is characterized by its type. -The following -types are supported: -.Bl -tag -width indent -.It Cm none -The file set is actually a single plain file. -.It Cm pid -One element of file set is used per incarnation of a ntpd -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 -.Ql \&. -to concatenated -.Ar prefix -and -.Ar filename -strings, and -appending the decimal representation of the process ID of the -.Xr ntpd 8 -server process. -.It Cm 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 -.Ql \&. -and a day specification in -the form -.Cm YYYYMMdd . -.Cm YYYY -is a 4-digit year number (e.g., 1992). -.Cm MM -is a two digit month number. -.Cm dd -is a two digit day number. -Thus, all information written at 10 December 1992 would end up -in a file named -.Ar prefix -.Ar filename Ns .19921210 . -.It Cm week -Any file set member contains data related to a certain week of -a year. -The term week is defined by computing day-of-year -modulo 7. -Elements of such a file generation set are -distinguished by appending the following suffix to the file set -filename base: A dot, a 4-digit year number, the letter -.Cm W , -and a 2-digit week number. -For example, information from January, -10th 1992 would end up in a file with suffix -.No . Ns Ar 1992W1 . -.It Cm 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 Cm year -One generation file element is generated per year. -The filename -suffix consists of a dot and a 4 digit year number. -.It Cm 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 -.Cm a , -and an 8-digit number. -This number is taken to be the number of seconds the server is -running at the start of the corresponding 24-hour period. -Information is only written to a file generation by specifying -.Cm enable ; -output is prevented by specifying -.Cm disable . -.El -.It Cm 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 -.Cm link -and disabled using -.Cm 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 -.Cm C , -and the pid of the 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 Cm enable \&| Cm disable -Enables or disables the recording function. -.El -.El -.El -.Sh Access Control Support -The -.Xr ntpd 8 -daemon implements a general purpose address/mask based restriction -list. -The list contains address/match entries sorted first -by increasing address values and and then by increasing mask values. -A match occurs when the bitwise AND of the mask and the packet -source address is equal to the bitwise AND of the mask and -address in the list. -The list is searched in order with the -last match found defining the restriction flags associated -with the entry. -Additional information and examples can be found in the -.Qq Notes on Configuring NTP and Setting up a NTP Subnet -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. -Later the facility was expanded to deflect -cryptographic and clogging attacks. -While this facility may -be useful for keeping unwanted or broken or malicious clients -from congesting innocent servers, it should not be considered -an alternative to the NTP authentication facilities. -Source address based restrictions are easily circumvented -by a determined cracker. -.Pp -Clients can be denied service because they are explicitly -included in the restrict list created by the restrict command -or implicitly as the result of cryptographic or rate limit -violations. -Cryptographic violations include certificate -or identity verification failure; rate limit violations generally -result from defective NTP implementations that send packets -at abusive rates. -Some violations cause denied service -only for the offending packet, others cause denied service -for a timed period and others cause the denied service for -an indefinite period. -When a client or network is denied access -for an indefinite period, the only way at present to remove -the restrictions is by restarting the server. -.Ss The Kiss-of-Death Packet -Ordinarily, packets denied service are simply dropped with no -further action except incrementing statistics counters. -Sometimes a -more proactive response is needed, such as a server message that -explicitly requests the client to stop sending and leave a message -for the system operator. -A special packet format has been created -for this purpose called the "kiss-of-death" (KoD) packet. -KoD packets have the leap bits set unsynchronized and stratum set -to zero and the reference identifier field set to a four-byte -ASCII code. -If the -.Cm noserve -or -.Cm notrust -flag of the matching restrict list entry is set, -the code is "DENY"; if the -.Cm limited -flag is set and the rate limit -is exceeded, the code is "RATE". -Finally, if a cryptographic violation occurs, the code is "CRYP". -.Pp -A client receiving a KoD performs a set of sanity checks to -minimize security exposure, then updates the stratum and -reference identifier peer variables, sets the access -denied (TEST4) bit in the peer flash variable and sends -a message to the log. -As long as the TEST4 bit is set, -the client will send no further packets to the server. -The only way at present to recover from this condition is -to restart the protocol at both the client and server. -This -happens automatically at the client when the association times out. -It will happen at the server only if the server operator cooperates. -.Ss Access Control Commands -.Bl -tag -width indent -.It Xo Ic discard -.Op Cm average Ar avg -.Op Cm minimum Ar min -.Op Cm monitor Ar prob -.Xc -Set the parameters of the -.Cm limited -facility which protects the server from -client abuse. -The -.Cm average -subcommand specifies the minimum average packet -spacing, while the -.Cm minimum -subcommand specifies the minimum packet spacing. -Packets that violate these minima are discarded -and a kiss-o'-death packet returned if enabled. -The default -minimum average and minimum are 5 and 2, respectively. -The monitor subcommand specifies the probability of discard -for packets that overflow the rate-control window. -.It Xo Ic restrict address -.Op Cm mask Ar mask -.Op Ar flag ... -.Xc -The -.Ar address -argument expressed in -dotted-quad form is the address of a host or network. -Alternatively, the -.Ar address -argument can be a valid host DNS name. -The -.Ar mask -argument expressed in dotted-quad form defaults to -.Cm 255.255.255.255 , -meaning that the -.Ar address -is treated as the address of an individual host. -A default entry (address -.Cm 0.0.0.0 , -mask -.Cm 0.0.0.0 ) -is always included and is always the first entry in the list. -Note that text string -.Cm default , -with no mask option, may -be used to indicate the default entry. -In the current implementation, -.Cm 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 -categories, 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 Cm ignore -Deny packets of all kinds, including -.Xr ntpq 8 -and -.Xr ntpdc 8 -queries. -.It Cm kod -If this flag is set when an access violation occurs, a kiss-o'-death -(KoD) packet is sent. -KoD packets are rate limited to no more than one -per second. -If another KoD packet occurs within one second after the -last one, the packet is dropped. -.It Cm limited -Deny service if the packet spacing violates the lower limits specified -in the discard command. -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 -.Cm limited -flag. -.It Cm 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 Cm nomodify -Deny -.Xr ntpq 8 -and -.Xr ntpdc 8 -queries which attempt to modify the state of the -server (i.e., run time reconfiguration). -Queries which return -information are permitted. -.It Cm noquery -Deny -.Xr ntpq 8 -and -.Xr ntpdc 8 -queries. -Time service is not affected. -.It Cm nopeer -Deny packets which would result in mobilizing a new association. -This -includes broadcast and symmetric active packets when a configured -association does not exist. -.It Cm noserve -Deny all packets except -.Xr ntpq 8 -and -.Xr ntpdc 8 -queries. -.It Cm notrap -Decline to provide mode 6 control message trap service to matching -hosts. -The trap service is a subsystem of the ntpdq control message -protocol which is intended for use by remote event logging programs. -.It Cm notrust -Deny service unless the packet is cryptographically authenticated. -.It Cm 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 -.Cm ntpport -and -.Cm non-ntpport -may -be specified. -The -.Cm ntpport -is considered more specific and -is sorted later in the list. -.It Cm version -Deny packets that do not match the current NTP version. -.El -.Pp -Default restriction list entries with the flags ignore, interface, -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, though if it is -otherwise unconfigured; no flags are associated -with the default entry (i.e., everything besides your own -NTP server is unrestricted). -.El -.Sh Automatic NTP Configuration Options -.Ss Manycasting -Manycasting is a automatic discovery and configuration paradigm -new to NTPv4. -It is intended as a means for a multicast client -to troll the nearby network neighborhood to find cooperating -manycast servers, validate them using cryptographic means -and evaluate their time values with respect to other servers -that might be lurking in the vicinity. -The intended result is that each manycast client mobilizes -client associations with some number of the "best" -of the nearby manycast servers, yet automatically reconfigures -to sustain this number of servers should one or another fail. -.Pp -Note that the manycasting paradigm does not coincide -with the anycast paradigm described in RFC-1546, -which is designed to find a single server from a clique -of servers providing the same service. -The manycast paradigm is designed to find a plurality -of redundant servers satisfying defined optimality criteria. -.Pp -Manycasting can be used with either symmetric key -or public key cryptography. -The public key infrastructure (PKI) -offers the best protection against compromised keys -and is generally considered stronger, at least with relatively -large key sizes. -It is implemented using the Autokey protocol and -the OpenSSL cryptographic library available from -.Li http://www.openssl.org/ . -The library can also be used with other NTPv4 modes -as well and is highly recommended, especially for broadcast modes. -.Pp -A persistent manycast client association is configured -using the manycastclient command, which is similar to the -server command but with a multicast (IPv4 class -.Cm D -or IPv6 prefix -.Cm FF ) -group address. -The IANA has designated IPv4 address 224.1.1.1 -and IPv6 address FF05::101 (site local) for NTP. -When more servers are needed, it broadcasts manycast -client messages to this address at the minimum feasible rate -and minimum feasible time-to-live (TTL) hops, depending -on how many servers have already been found. -There can be as many manycast client associations -as different group address, each one serving as a template -for a future ephemeral unicast client/server association. -.Pp -Manycast servers configured with the -.Ic manycastserver -command listen on the specified group address for manycast -client messages. -Note the distinction between manycast client, -which actively broadcasts messages, and manycast server, -which passively responds to them. -If a manycast server is -in scope of the current TTL and is itself synchronized -to a valid source and operating at a stratum level equal -to or lower than the manycast client, it replies to the -manycast client message with an ordinary unicast server message. -.Pp -The manycast client receiving this message mobilizes -an ephemeral client/server association according to the -matching manycast client template, but only if cryptographically -authenticated and the server stratum is less than or equal -to the client stratum. -Authentication is explicitly required -and either symmetric key or public key (Autokey) can be used. -Then, the client polls the server at its unicast address -in burst mode in order to reliably set the host clock -and validate the source. -This normally results -in a volley of eight client/server at 2-s intervals -during which both the synchronization and cryptographic -protocols run concurrently. -Following the volley, -the client runs the NTP intersection and clustering -algorithms, which act to discard all but the "best" -associations according to stratum and synchronization -distance. -The surviving associations then continue -in ordinary client/server mode. -.Pp -The manycast client polling strategy is designed to reduce -as much as possible the volume of manycast client messages -and the effects of implosion due to near-simultaneous -arrival of manycast server messages. -The strategy is determined by the -.Ic manycastclient , -.Ic tos -and -.Ic ttl -configuration commands. -The manycast poll interval is -normally eight times the system poll interval, -which starts out at the -.Cm minpoll -value specified in the -.Ic manycastclient , -command and, under normal circumstances, increments to the -.Cm maxpolll -value specified in this command. -Initially, the TTL is -set at the minimum hops specified by the ttl command. -At each retransmission the TTL is increased until reaching -the maximum hops specified by this command or a sufficient -number client associations have been found. -Further retransmissions use the same TTL. -.Pp -The quality and reliability of the suite of associations -discovered by the manycast client is determined by the NTP -mitigation algorithms and the -.Cm minclock -and -.Cm minsane -values specified in the -.Ic tos -configuration command. -At least -.Cm minsane -candidate servers must be available and the mitigation -algorithms produce at least -.Cm minclock -survivors in order to synchronize the clock. -Byzantine agreement principles require at least four -candidates in order to correctly discard a single falseticker. -For legacy purposes, -.Cm minsane -defaults to 1 and -.Cm minclock -defaults to 3. -For manycast service -.Cm minsane -should be explicitly set to 4, assuming at least that -number of servers are available. -.Pp -If at least -.Cm minclock -servers are found, the manycast poll interval is immediately -set to eight times -.Cm maxpoll . -If less than -.Cm minclock -servers are found when the TTL has reached the maximum hops, -the manycast poll interval is doubled. -For each transmission -after that, the poll interval is doubled again until -reaching the maximum of eight times -.Cm maxpoll . -Further transmissions use the same poll interval and -TTL values. -Note that while all this is going on, -each client/server association found is operating normally -it the system poll interval. -.Pp -Administratively scoped multicast boundaries are normally -specified by the network router configuration and, -in the case of IPv6, the link/site scope prefix. -By default, the increment for TTL hops is 32 starting -from 31; however, the -.Ic ttl -configuration command can be -used to modify the values to match the scope rules. -.Pp -It is often useful to narrow the range of acceptable -servers which can be found by manycast client associations. -Because manycast servers respond only when the client -stratum is equal to or greater than the server stratum, -primary (stratum 1) servers fill find only primary servers -in TTL range, which is probably the most common objective. -However, unless configured otherwise, all manycast clients -in TTL range will eventually find all primary servers -in TTL range, which is probably not the most common -objective in large networks. -The -.Ic tos -command can be used to modify this behavior. -Servers with stratum below -.Cm floor -or above -.Cm ceiling -specified in the -.Ic tos -command are strongly discouraged during the selection -process; however, these servers may be temporally -accepted if the number of servers within TTL range is -less than -.Cm minclock . -.Pp -The above actions occur for each manycast client message, -which repeats at the designated poll interval. -However, once the ephemeral client association is mobilized, -subsequent manycast server replies are discarded, -since that would result in a duplicate association. -If during a poll interval the number of client associations -falls below -.Cm minclock , -all manycast client prototype associations are reset -to the initial poll interval and TTL hops and operation -resumes from the beginning. -It is important to avoid -frequent manycast client messages, since each one requires -all manycast servers in TTL range to respond. -The result could well be an implosion, either minor or major, -depending on the number of servers in range. -The recommended value for -.Cm maxpoll -is 12 (4,096 s). -.Pp -It is possible and frequently useful to configure a host -as both manycast client and manycast server. -A number of hosts configured this way and sharing a common -group address will automatically organize themselves -in an optimum configuration based on stratum and -synchronization distance. -For example, consider an NTP -subnet of two primary servers and a hundred or more -dependent clients. -With two exceptions, all servers -and clients have identical configuration files including both -.Ic multicastclient -and -.Ic multicastserver -commands using, for instance, multicast group address -239.1.1.1. -The only exception is that each primary server -configuration file must include commands for the primary -reference source such as a GPS receiver. -.Pp -The remaining configuration files for all secondary -servers and clients have the same contents, except for the -.Ic tos -command, which is specific for each stratum level. -For stratum 1 and stratum 2 servers, that command is -not necessary. -For stratum 3 and above servers the -.Cm floor -value is set to the intended stratum number. -Thus, all stratum 3 configuration files are identical, -all stratum 4 files are identical and so forth. -.Pp -Once operations have stabilized in this scenario, -the primary servers will find the primary reference source -and each other, since they both operate at the same -stratum (1), but not with any secondary server or client, -since these operate at a higher stratum. -The secondary -servers will find the servers at the same stratum level. -If one of the primary servers loses its GPS receiver, -it will continue to operate as a client and other clients -will time out the corresponding association and -re-associate accordingly. -.Pp -Some administrators prefer to avoid running -.Xr ntpd 8 -continuously and run either -.Xr ntpdate 8 -or -.Xr ntpd 8 -.Fl q -as a cron job. -In either case the servers must be -configured in advance and the program fails if none are -available when the cron job runs. -A really slick -application of manycast is with -.Xr ntpd 8 -.Fl q . -The program wakes up, scans the local landscape looking -for the usual suspects, selects the best from among -the rascals, sets the clock and then departs. -Servers do not have to be configured in advance and -all clients throughout the network can have the same -configuration file. -.Ss Manycast Interactions with Autokey -Each time a manycast client sends a client mode packet -to a multicast group address, all manycast servers -in scope generate a reply including the host name -and status word. -The manycast clients then run -the Autokey protocol, which collects and verifies -all certificates involved. -Following the burst interval -all but three survivors are cast off, -but the certificates remain in the local cache. -It often happens that several complete signing trails -from the client to the primary servers are collected in this way. -.Pp -About once an hour or less often if the poll interval -exceeds this, the client regenerates the Autokey key list. -This is in general transparent in client/server mode. -However, about once per day the server private value -used to generate cookies is refreshed along with all -manycast client associations. -In this case all -cryptographic values including certificates is refreshed. -If a new certificate has been generated since -the last refresh epoch, it will automatically revoke -all prior certificates that happen to be in the -certificate cache. -At the same time, the manycast -scheme starts all over from the beginning and -the expanding ring shrinks to the minimum and increments -from there while collecting all servers in scope. -.Ss Manycast Options -.Bl -tag -width indent -.It Xo Ic tos -.Oo -.Cm ceiling Ar ceiling | -.Cm cohort { 0 | 1 } | -.Cm floor Ar floor | -.Cm minclock Ar minclock | -.Cm minsane Ar minsane -.Oc -.Xc -This command affects the clock selection and clustering -algorithms. -It can be used to select the quality and -quantity of peers used to synchronize the system clock -and is most useful in manycast mode. -The variables operate -as follows: -.Bl -tag -width indent -.It Cm ceiling Ar ceiling -Peers with strata above -.Cm ceiling -will be discarded if there are at least -.Cm minclock -peers remaining. -This value defaults to 15, but can be changed -to any number from 1 to 15. -.It Cm cohort Bro 0 | 1 Brc -This is a binary flag which enables (0) or disables (1) -manycast server replies to manycast clients with the same -stratum level. -This is useful to reduce implosions where -large numbers of clients with the same stratum level -are present. -The default is to enable these replies. -.It Cm floor Ar floor -Peers with strata below -.Cm floor -will be discarded if there are at least -.Cm minclock -peers remaining. -This value defaults to 1, but can be changed -to any number from 1 to 15. -.It Cm minclock Ar minclock -The clustering algorithm repeatedly casts out outlyer -associations until no more than -.Cm minclock -associations remain. -This value defaults to 3, -but can be changed to any number from 1 to the number of -configured sources. -.It Cm minsane Ar minsane -This is the minimum number of candidates available -to the clock selection algorithm in order to produce -one or more truechimers for the clustering algorithm. -If fewer than this number are available, the clock is -undisciplined and allowed to run free. -The default is 1 -for legacy purposes. -However, according to principles of -Byzantine agreement, -.Cm minsane -should be at least 4 in order to detect and discard -a single falseticker. -.El -.It Cm ttl Ar hop ... -This command specifies a list of TTL values in increasing -order, up to 8 values can be specified. -In manycast mode these values are used in turn -in an expanding-ring search. -The default is eight -multiples of 32 starting at 31. -.El -.Sh Reference Clock Support -The NTP Version 4 daemon supports some three dozen 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 -.Qq Reference Clock Drivers -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -Additional information can be found in the pages linked -there, including the -.Qq Debugging Hints for Reference Clock Drivers -and -.Qq How To Write a Reference Clock Driver -pages -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -In addition, support for a PPS -signal is available as described in the -.Qq Pulse-per-second (PPS) Signal Interfacing -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -Many -drivers support special line discipline/streams modules which can -significantly improve the accuracy using the driver. -These are -described in the -.Qq Line Disciplines and Streams Drivers -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -.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 US. -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 compiled -or the hardware port has not been appropriately configured results -in a scalding remark to the system log file, but is otherwise non -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 -.Sm off -.Li 127.127. Ar t . Ar u , -.Sm on -where -.Ar t -is an integer -denoting the clock type and -.Ar u -indicates the unit -number in the range 0-3. -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 -.Ar address -argument in that command -is the clock address. -The -.Cm key , -.Cm version -and -.Cm ttl -options are not used for reference clock support. -The -.Cm mode -option is added for reference clock support, as -described below. -The -.Cm 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 -.Qq Mitigation Rules and the prefer Keyword -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) -page. -The -.Cm minpoll -and -.Cm maxpoll -options have -meaning only for selected clock drivers. -See the individual clock -driver document pages for additional information. -.Pp -The -.Ic fudge -command is used to provide additional -information for individual clock drivers and normally follows -immediately after the -.Ic server -command. -The -.Ar address -argument specifies the clock address. -The -.Cm refid -and -.Cm stratum -options can be used to -override the defaults for the device. -There are two optional -device-dependent time offsets and four flags that can be included -in the -.Ic fudge -command as well. -.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 an external stratum of -one. -In order to provide engineered backups, it is often useful to -specify the reference clock stratum as greater than zero. -The -.Cm 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 -.Cm 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 -.Sm off -.Li 127.127. Ar t . Ar u -.Sm on -.Op Cm prefer -.Op Cm mode Ar int -.Op Cm minpoll Ar int -.Op Cm maxpoll Ar int -.Xc -This command can be used to configure reference clocks in -special ways. -The options are interpreted as follows: -.Bl -tag -width indent -.It Cm 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 -.Qq Mitigation Rules and the prefer Keyword -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) -for further information. -.It Cm 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 Cm minpoll Ar int -.It Cm maxpoll Ar int -These options specify the minimum and maximum polling interval -for reference clock messages, as a power of 2 in seconds -For -most directly connected reference clocks, both -.Cm minpoll -and -.Cm maxpoll -default to 6 (64 s). -For modem reference clocks, -.Cm minpoll -defaults to 10 (17.1 m) and -.Cm 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 -.Sm off -.Li 127.127. Ar t . Ar u -.Sm on -.Op Cm time1 Ar sec -.Op Cm time2 Ar sec -.Op Cm stratum Ar int -.Op Cm refid Ar string -.Op Cm mode Ar int -.Op Cm flag1 Cm 0 \&| Cm 1 -.Op Cm flag2 Cm 0 \&| Cm 1 -.Op Cm flag3 Cm 0 \&| Cm 1 -.Op Cm flag4 Cm 0 \&| Cm 1 -.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 Cm 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 or operating system -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. -Note: in order to facilitate calibration when more than one -radio clock or PPS signal is supported, a special calibration -feature is available. -It takes the form of an argument to the -.Ic enable -command described in -.Sx Miscellaneous Options -page and operates as described in the -.Qq Reference Clock Drivers -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -.It Cm 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 -.Qq Reference Clock Drivers -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -.It Cm 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 Cm refid Ar string -Specifies an ASCII string of 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 Cm 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 Cm flag1 Cm 0 \&| Cm 1 -.It Cm flag2 Cm 0 \&| Cm 1 -.It Cm flag3 Cm 0 \&| Cm 1 -.It Cm flag4 Cm 0 \&| Cm 1 -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 -.Cm flag4 -is used to enable recording monitoring -data to the -.Cm clockstats -file configured with the -.Ic filegen -command. -Further information on the -.Ic filegen -command can be found in -.Sx Monitoring Options . -.El -.El -.Sh Miscellaneous Options -.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 client and server. -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 Ic calldelay Ar delay -This option controls the delay in seconds between the first and second -packets sent in burst or iburst mode to allow additional time for a modem -or ISDN call to complete. -.It Ic driftfile Ar driftfile -This command specifies the complete path and name of the file used to -record the frequency of the local clock oscillator. -This is the same -operation as the -.Fl f -command line option. -If the file exists, it is read at -startup in order to set the initial frequency and then updated once per -hour with the current frequency computed by the daemon. -If the file name is -specified, but the file itself does not exist, the starts with an initial -frequency of zero and creates the file when writing it for the first time. -If this command is not given, the daemon will always start with an initial -frequency of zero. -.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 -.Xr ntpd 8 -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 enable -.Oo -.Cm auth | Cm bclient | -.Cm calibrate | Cm kernel | -.Cm monitor | Cm ntp | -.Cm pps | Cm stats -.Oc -.Xc -.It Xo Ic disable -.Oo -.Cm auth | Cm bclient | -.Cm calibrate | Cm kernel | -.Cm monitor | Cm ntp | -.Cm pps | Cm stats -.Oc -.Xc -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. -.Bl -tag -width indent -.It Cm auth -Enables the server to synchronize with unconfigured peers only if the -peer has been correctly authenticated using either public key or -private key cryptography. -The default for this flag is -.Ic enable . -.It Cm bclient -Enables the server to listen for a message from a broadcast or -multicast server, as in the -.Ic multicastclient -command with default -address. -The default for this flag is -.Ic disable . -.It Cm calibrate -Enables the calibrate feature for reference clocks. -The default for -this flag is -.Ic disable . -.It Cm kernel -Enables the kernel time discipline, if available. -The default for this -flag is -.Ic enable -if support is available, otherwise -.Ic disable . -.It Cm monitor -Enables the monitoring facility. -See the -.Xr ntpdc 8 -program -and the -.Ic monlist -command or further information. -The -default for this flag is -.Ic enable . -.It Cm ntp -Enables time and frequency discipline. -In effect, this switch opens and -closes the feedback loop, which is useful for testing. -The default for -this flag is -.Ic enable . -.It Cm pps -Enables the pulse-per-second (PPS) signal when frequency and time is -disciplined by the precision time kernel modifications. -See the -.Qq A Kernel Model for Precision Timekeeping -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) -page for further information. -The default for this flag is -.Ic disable . -.It Cm stats -Enables the statistics facility. -See the -.Sx Monitoring Options -section for further information. -The default for this flag is -.Ic disable . -.El -.It Ic includefile Ar includefile -This command allows additional configuration commands -to be included from a separate file. -Include files may -be nested to a depth of five; upon reaching the end of any -include file, command processing resumes in the previous -configuration file. -This option is useful for sites that run -.Xr ntpd 8 -on multiple hosts, with (mostly) common options (e.g., a -restriction list). -.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 -.Ql = , -.Ql + -and -.Ql - , -where -.Ql = -sets the -.Xr syslog 3 -priority mask, -.Ql + -adds and -.Ql - -removes -messages. -.Xr syslog 3 -messages can be controlled in four -classes -.Po -.Cm clock , -.Cm peer , -.Cm sys -and -.Cm sync -.Pc . -Within these classes four types of messages can be -controlled: informational messages -.Po -.Cm info -.Pc , -event messages -.Po -.Cm events -.Pc , -statistics messages -.Po -.Cm statistics -.Pc -and -status messages -.Po -.Cm status -.Pc . -.Pp -Configuration keywords are formed by concatenating the message class with -the event class. -The -.Cm all -prefix can be used instead of a message class. -A -message class may also be followed by the -.Cm all -keyword to enable/disable all -messages of the respective message class.Thus, a minimal log configuration -could look like this: -.Bd -literal -logconfig =syncstatus +sysevents -.Ed -.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: -.Bd -literal -logconfig =syncall +clockall -.Ed -.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. -.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. -This is the same operation as the -l command line option. -.It Ic setvar Ar variable Op Cm 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 -.Sm off -.Va name = Ar value -.Sm on -is followed by the -.Cm default -keyword, the -variable will be listed as part of the default system variables -.Po -.Xr ntpq 8 -.Ic rv -command -.Pc ) . -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 variable 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 Xo Ic tinker -.Oo -.Cm allan Ar allan | -.Cm dispersion Ar dispersion | -.Cm freq Ar freq | -.Cm huffpuff Ar huffpuff | -.Cm panic Ar panic | -.Cm step Ar srep | -.Cm stepout Ar stepout -.Oc -.Xc -This command can be used to alter several system variables in -very exceptional circumstances. -It should occur in the -configuration file before any other configuration options. -The -default values of these variables have been carefully optimized for -a wide range of network speeds and reliability expectations. -In -general, they interact in intricate ways that are hard to predict -and some combinations can result in some very nasty behavior. -Very -rarely is it necessary to change the default values; but, some -folks cannot resist twisting the knobs anyway and this command is -for them. -Emphasis added: twisters are on their own and can expect -no help from the support group. -.Pp -The variables operate as follows: -.Bl -tag -width indent -.It Cm allan Ar allan -The argument becomes the new value for the minimum Allan -intercept, which is a parameter of the PLL/FLL clock discipline -algorithm. -The value in log2 seconds defaults to 7 (1024 s), which is also the lower -limit. -.It Cm dispersion Ar dispersion -The argument becomes the new value for the dispersion increase rate, -normally .000015 s/s. -.It Cm freq Ar freq -The argument becomes the initial value of the frequency offset in -parts-per-million. -This overrides the value in the frequency file, if -present, and avoids the initial training state if it is not. -.It Cm huffpuff Ar huffpuff -The argument becomes the new value for the experimental -huff-n'-puff filter span, which determines the most recent interval -the algorithm will search for a minimum delay. -The lower limit is -900 s (15 m), but a more reasonable value is 7200 (2 hours). -There -is no default, since the filter is not enabled unless this command -is given. -.It Cm panic Ar panic -The argument is the panic threshold, normally 1000 s. -If set to zero, -the panic sanity check is disabled and a clock offset of any value will -be accepted. -.It Cm step Ar step -The argument is the step threshold, which by default is 0.128 s. -It can -be set to any positive number in seconds. -If set to zero, step -adjustments will never occur. -Note: The kernel time discipline is -disabled if the step threshold is set to zero or greater than the -default. -.It Cm stepout Ar stepout -The argument is the stepout timeout, which by default is 900 s. -It can -be set to any positive number in seconds. -If set to zero, the stepout -pulses will not be suppressed. -.El -.It Xo Ic trap Ar host_address -.Op Cm port Ar port_number -.Op Cm 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. -.Pp -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 Cm hop Ar ... -This command specifies a list of TTL values in increasing order, up to 8 -values can be specified. -In manycast mode these values are used in turn in -an expanding-ring search. -The default is eight multiples of 32 starting at -31. -.El -.Sh FILES -.Bl -tag -width /etc/ntp.drift -compact -.It Pa /etc/ntp.conf -the default name of the configuration file -.It Pa ntp.keys -private MD5 keys -.It Pa ntpkey -RSA private key -.It Pa ntpkey_ Ns Ar host -RSA public key -.It Pa ntp_dh -Diffie-Hellman agreement parameters -.El -.Sh SEE ALSO -.Xr rc.conf 5 , -.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 . -.Rs -.%A David L. Mills -.%T Network Time Protocol (Version 3) -.%O RFC1305 -.Re -.Sh BUGS -The syntax checking is not picky; some combinations of -ridiculous and even hilarious options and modes may not be -detected. -.Pp -The -.Pa ntpkey_ Ns Ar host -files are really digital -certificates. -These should be obtained via secure directory -services when they become universally available. diff --git a/usr.sbin/ntp/doc/ntp.keys.5 b/usr.sbin/ntp/doc/ntp.keys.5 deleted file mode 100644 index dc9531c..0000000 --- a/usr.sbin/ntp/doc/ntp.keys.5 +++ /dev/null @@ -1,120 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd January 13, 2000 -.Dt NTP.KEYS 5 -.Os -.Sh NAME -.Nm ntp.keys -.Nd NTP daemon key file format -.Sh SYNOPSIS -.Nm /etc/ntp.keys -.Sh DESCRIPTION -Following is a description of the format of NTP key files. -For a description of the use of these files, see the -.Qq Authentication Support -section of the -.Xr ntp.conf 5 -page. -.Pp -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 -.D1 Ar 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 four different formats, -controlled by the -.Ar type -character. -The four key types, and corresponding formats, -are listed following. -.Bl -tag -width X -.It Li S -The 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 key, in standard format, would be given as -.Ql 0101010101010101 . -.It Li N -The 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 key in NTP format would be specified as -.Ql 8080808080808080 . -.It Li A -The 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 -.Ux -passwords. -.It Li M -The 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 FILES -.Bl -tag -width /etc/ntp.drift -compact -.It Pa /etc/ntp.keys -the default name of the configuration file -.El -.Sh SEE ALSO -.Xr ntp.conf 5 , -.Xr ntpd 8 , -.Xr ntpdate 8 , -.Xr ntpdc 8 -.Sh BUGS -.Xr ntpd 8 -has gotten rather fat. -While not huge, it has gotten larger than might -be desirable 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/ntpd.8 b/usr.sbin/ntp/doc/ntpd.8 deleted file mode 100644 index 069ef42..0000000 --- a/usr.sbin/ntp/doc/ntpd.8 +++ /dev/null @@ -1,612 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd May 18, 2010 -.Dt NTPD 8 -.Os -.Sh NAME -.Nm ntpd -.Nd Network Time Protocol (NTP) daemon -.Sh SYNOPSIS -.Nm -.Op Fl aAbDdgLmnPqx -.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 key -.Op Fl v Ar variable -.Op Fl V Ar variable -.Sh DESCRIPTION -The -.Nm -utility is an operating system daemon which sets -and maintains the system time of day in synchronism with Internet -standard time servers. -It 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. -.Pp -The -.Nm -utility 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 gigahertz CPU clocks and gigabit LANs. -.Pp -Ordinarily, -.Nm -reads the -.Xr ntp.conf 5 -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 useful when the local host is to be configured as a -broadcast/multicast client, with all peers being determined by -listening to broadcasts at run time. -.Pp -If NetInfo support is built into -.Nm , -then -.Nm -will attempt to read its configuration from the -NetInfo if the default -.Xr ntp.conf 5 -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 -.Nm -is running -using the -.Xr ntpq 8 -and -.Xr ntpdc 8 -utility programs. -.Pp -When -.Nm -starts it looks at the value of -.Cm umask 2 , -and if zero -.Nm -will set the -.Cm umask 2 -to 022. -.Pp -The following options are available: -.Bl -tag -width indent -.It Fl a -Require cryptographic authentication for broadcast client, -multicast client and symmetric passive associations. -This is the default. -.It Fl A -Do not require cryptographic authentication for broadcast client, -multicast client and symmetric passive associations. -This is almost never a good idea. -.It Fl b -Enable the client to synchronize to broadcast servers. -.It Fl c Ar conffile -Specify the name and path of the configuration file, default -.Pa /etc/ntp.conf . -.It Fl d -Specify debugging mode. -This option may occur more than once, -with each occurrence indicating greater detail of display. -You need to compile -.Nm -with DEBUG in order to use this. -.It Fl D Ar level -Specify debugging level directly. -.It Fl f Ar driftfile -Specify the name and path of the frequency file, default -.Pa /etc/ntp.drift . -This is the same operation as the -.Ic driftfile Ar driftfile -configuration command. -.It Fl g -Normally, -.Nm -exits with a message to the system log if the offset exceeds -the panic threshold, which is 1000 s by default. -This option allows the time to be set to any value without restriction; -however, this can happen only once. -If the threshold is exceeded after that, -.Nm -will exit with a message to the system log. -This option can be used with the -.Fl q -and -.Fl x -options. -See the -.Ic tinker -command for other options. -.It Fl k Ar keyfile -Specify the name and path of the symmetric key file, default -.Pa /etc/ntp.keys . -This is the same operation as the -.Ic keys Ar keyfile -configuration command. -.It Fl l Ar logfile -Specify the name and path of the log file. -The default is the system log file. -This is the same operation as the -.Ic logfile Ar logfile -configuration command. -.It Fl L -Do not listen to virtual IPs. -The default is to listen. -.It Fl m -Enable the client to synchronize to multicast servers at the IPv4 multicast -group address 224.0.1.1. -.It Fl n -Do not fork. -.It Fl N -To the extent permitted by the operating system, run the -.Nm -at the highest priority. -.It Fl p Ar pidfile -Specify the name and path of the file used to record the -.Nm -process ID. -This is the same operation as the -.Ic pidfile Ar pidfile -configuration command. -.It Fl P Ar priority -To the extent permitted by the operating system, run the -.Nm -at the specified priority. -.It Fl q -Exit the -.Nm -just after the first time the clock is -set. -This behavior mimics that of the -.Xr ntpdate 8 -program, -which is to be retired. -The -.Fl g -and -.Fl x -options can -be used with this option. -Note: The kernel time discipline is disabled with this option. -.It Fl r Ar broadcastdelay -Specify the default propagation delay from the -broadcast/multicast server to this client. -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. -This is the same operation as the -.Ic statsdir Ar statsdir -configuration command. -.It Fl t Ar key -Add a key number to the trusted key list. -This option can occur more than once. -.It Fl v Ar variable -.It Fl V Ar variable -Add a system variable listed by default. -.It Fl x -Normally, the time is slewed if the offset is less than the -step threshold, which is 128 ms by default, and stepped if above -the threshold. -This option sets the threshold to 600 s, -which is well within the accuracy window to set the clock manually. -Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, -each second of adjustment requires an amortization interval of 2000 s. -Thus, an adjustment as much as 600 s will take almost 14 days to complete. -This option can be used with the -.Fl g -and -.Fl q -options. -See the -.Ic tinker -command for other options. -Note: The kernel time discipline is disabled with this option. -.El -.Ss "How NTP Operates" -The -.Nm -utility operates by exchanging messages with -one or more configured servers at designated poll intervals. -When -started, whether for the first or subsequent times, the program -requires several exchanges from the majority of these servers so -the signal processing and mitigation algorithms can accumulate and -groom the data and set the clock. -In order to protect the network -from bursts, the initial poll interval for each server is delayed -an interval randomized over a few seconds. -At the default initial poll -interval of 64s, several minutes can elapse before the clock is -set. -The initial delay to set the clock can be reduced using the -.Cm iburst -keyword with the -.Ic server -configuration -command, as described in -.Xr ntp.conf 5 . -.Pp -Most operating systems and hardware of today incorporate a -time-of-year (TOY) chip to maintain the time during periods when -the power is off. -When the machine is booted, the chip is used to -initialize the operating system time. -After the machine has -synchronized to a NTP server, the operating system corrects the -chip from time to time. -In case there is no TOY chip or for some -reason its time is more than 1000s from the server time, -.Nm -assumes something must be terribly wrong and the only -reliable action is for the operator to intervene and set the clock -by hand. -This causes -.Nm -to exit with a panic message to -the system log. -The -.Fl g -option overrides this check and the -clock will be set to the server time regardless of the chip time. -However, and to protect against broken hardware, such as when the -CMOS battery fails or the clock counter becomes defective, once the -clock has been set, an error greater than 1000s will cause -.Nm -to exit anyway. -.Pp -Under ordinary conditions, -.Nm -adjusts the clock in -small steps so that the timescale is effectively continuous and -without discontinuities. -Under conditions of extreme network -congestion, the roundtrip delay jitter can exceed three seconds and -the synchronization distance, which is equal to one-half the -roundtrip delay plus error budget terms, can become very large. -The -.Nm -algorithms discard sample offsets exceeding 128 ms, -unless the interval during which no sample offset is less than 128 -ms exceeds 900s. -The first sample after that, no matter what the -offset, steps the clock to the indicated time. -In practice this -reduces the false alarm rate where the clock is stepped in error to -a vanishingly low incidence. -.Pp -As the result of this behavior, once the clock has been set, it -very rarely strays more than 128 ms, even under extreme cases of -network path congestion and jitter. -Sometimes, in particular when -.Nm -is first started, the error might exceed 128 ms. -This -may on occasion cause the clock to be set backwards if the local -clock time is more than 128 s in the future relative to the server. -In some applications, this behavior may be unacceptable. -If the -.Fl x -option is included on the command line, the clock will -never be stepped and only slew corrections will be used. -.Pp -The issues should be carefully explored before deciding to use -the -.Fl x -option. -The maximum slew rate possible is limited -to 500 parts-per-million (PPM) as a consequence of the correctness -principles on which the NTP protocol and algorithm design are -based. -As a result, the local clock can take a long time to -converge to an acceptable offset, about 2,000 s for each second the -clock is outside the acceptable range. -During this interval the -local clock will not be consistent with any other network clock and -the system cannot be used for distributed applications that require -correctly synchronized network time. -.Pp -In spite of the above precautions, sometimes when large -frequency errors are present the resulting time offsets stray -outside the 128-ms range and an eventual step or slew time -correction is required. -If following such a correction the -frequency error is so large that the first sample is outside the -acceptable range, -.Nm -enters the same state as when the -.Pa ntp.drift -file is not present. -The intent of this behavior -is to quickly correct the frequency and restore operation to the -normal tracking mode. -In the most extreme cases -( -.Cm time.ien.it -comes to mind), there may be occasional -step/slew corrections and subsequent frequency corrections. -It -helps in these cases to use the -.Cm burst -keyword when -configuring the server. -.Ss "Frequency Discipline" -The -.Nm -behavior at startup depends on whether the -frequency file, usually -.Pa ntp.drift , -exists. -This file -contains the latest estimate of clock frequency error. -When the -.Nm -is started and the file does not exist, the -.Nm -enters a special mode designed to quickly adapt to -the particular system clock oscillator time and frequency error. -This takes approximately 15 minutes, after which the time and -frequency are set to nominal values and the -.Nm -enters -normal mode, where the time and frequency are continuously tracked -relative to the server. -After one hour the frequency file is -created and the current frequency offset written to it. -When the -.Nm -is started and the file does exist, the -.Nm -frequency is initialized from the file and enters normal mode -immediately. -After that the current frequency offset is written to -the file at hourly intervals. -.Ss "Operating Modes" -The -.Nm -utility can operate in any of several modes, including -symmetric active/passive, client/server broadcast/multicast and -manycast, as described in the -.Qq Association Management -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -It normally operates continuously while -monitoring for small changes in frequency and trimming the clock -for the ultimate precision. -However, it can operate in a one-time -mode where the time is set from an external server and frequency is -set from a previously recorded frequency file. -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 -By default, -.Nm -runs in continuous mode where each of -possibly several external servers is polled at intervals determined -by an intricate state machine. -The state machine measures the -incidental roundtrip delay jitter and oscillator frequency wander -and determines the best poll interval using a heuristic algorithm. -Ordinarily, and in most operating environments, the state machine -will start with 64s intervals and eventually increase in steps to -1024s. -A small amount of random variation is introduced in order to -avoid bunching at the servers. -In addition, should a server become -unreachable for some time, the poll interval is increased in steps -to 1024s in order to reduce network overhead. -.Pp -In some cases it may not be practical for -.Nm -to run -continuously. -A common workaround has been to run the -.Xr ntpdate 8 -program from a -.Xr cron 8 -job at designated -times. -However, this program does not have the crafted signal -processing, error checking and mitigation algorithms of -.Nm . -The -.Fl q -option is intended for this purpose. -Setting this option will cause -.Nm -to exit just after -setting the clock for the first time. -The procedure for initially -setting the clock is the same as in continuous mode; most -applications will probably want to specify the -.Cm iburst -keyword with the -.Ic server -configuration command. -With this -keyword a volley of messages are exchanged to groom the data and -the clock is set in about 10 s. -If nothing is heard after a -couple of minutes, the daemon times out and exits. -After a suitable -period of mourning, the -.Xr ntpdate 8 -program may be -retired. -.Pp -When kernel support is available to discipline the clock -frequency, which is the case for stock Solaris, Tru64, Linux and -.Fx , -a useful feature is available to discipline the clock -frequency. -First, -.Nm -is run in continuous mode with -selected servers in order to measure and record the intrinsic clock -frequency offset in the frequency file. -It may take some hours for -the frequency and offset to settle down. -Then the -.Nm -is -stopped and run in one-time mode as required. -At each startup, the -frequency is read from the file and initializes the kernel -frequency. -.Ss "Poll Interval Control" -This version of NTP includes an intricate state machine to -reduce the network load while maintaining a quality of -synchronization consistent with the observed jitter and wander. -There are a number of ways to tailor the operation in order enhance -accuracy by reducing the interval or to reduce network overhead by -increasing it. -However, the user is advised to carefully consider -the consequences of changing the poll adjustment range from the -default minimum of 64 s to the default maximum of 1,024 s. -The -default minimum can be changed with the -.Ic tinker -.Cm minpoll -command to a value not less than 16 s. -This value is used for all -configured associations, unless overridden by the -.Cm minpoll -option on the configuration command. -Note that most device drivers -will not operate properly if the poll interval is less than 64 s -and that the broadcast server and manycast client associations will -also use the default, unless overridden. -.Pp -In some cases involving dial up or toll services, it may be -useful to increase the minimum interval to a few tens of minutes -and maximum interval to a day or so. -Under normal operation -conditions, once the clock discipline loop has stabilized the -interval will be increased in steps from the minimum to the -maximum. -However, this assumes the intrinsic clock frequency error -is small enough for the discipline loop correct it. -The capture -range of the loop is 500 PPM at an interval of 64s decreasing by a -factor of two for each doubling of interval. -At a minimum of 1,024 -s, for example, the capture range is only 31 PPM. -If the intrinsic -error is greater than this, the drift file -.Pa ntp.drift -will -have to be specially tailored to reduce the residual error below -this limit. -Once this is done, the drift file is automatically -updated once per hour and is available to initialize the frequency -on subsequent daemon restarts. -.Ss "The huff-n'-puff Filter" -In scenarios where a considerable amount of data are to be -downloaded or uploaded over telephone modems, timekeeping quality -can be seriously degraded. -This occurs because the differential -delays on the two directions of transmission can be quite large. -In -many cases the apparent time errors are so large as to exceed the -step threshold and a step correction can occur during and after the -data transfer is in progress. -.Pp -The huff-n'-puff filter is designed to correct the apparent time -offset in these cases. -It depends on knowledge of the propagation -delay when no other traffic is present. -In common scenarios this -occurs during other than work hours. -The filter maintains a shift -register that remembers the minimum delay over the most recent -interval measured usually in hours. -Under conditions of severe -delay, the filter corrects the apparent offset using the sign of -the offset and the difference between the apparent delay and -minimum delay. -The name of the filter reflects the negative (huff) -and positive (puff) correction, which depends on the sign of the -offset. -.Pp -The filter is activated by the -.Ic tinker -command and -.Cm huffpuff -keyword, as described in -.Xr ntp.conf 5 . -.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.conf 5 , -.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 BUGS -The -.Nm -utility has gotten rather fat. -While not huge, it has gotten -larger than might be desirable for an elevated-priority -.Nm -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 deleted file mode 100644 index f361f17..0000000 --- a/usr.sbin/ntp/doc/ntpdate.8 +++ /dev/null @@ -1,280 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd May 17, 2006 -.Dt NTPDATE 8 -.Os -.Sh NAME -.Nm ntpdate -.Nd set the date and time via NTP -.Sh SYNOPSIS -.Nm -.Op Fl 46bBdoqsuv -.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 ... -.Sh DESCRIPTION -.Pp -.Em Note : -The functionality of this program is now available -in the -.Xr ntpd 8 -program. -See the -.Fl q -command line -option in the -.Xr ntpd 8 -page. -After a suitable period of -mourning, the -.Nm -utility is to be retired from this -distribution. -.Pp -The -.Nm -utility 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 -The following options are available: -.Bl -tag -width indent -.It Fl 4 -Force DNS resolution of following host names on the command line to the -IPv4 namespace. -.It Fl 6 -Force DNS resolution of following host names on the command line to the -IPv6 namespace. -.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 - do not 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 Ar 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 -.Pp -The -.Nm -utility 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 -.Xr cron 8 -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 -The -.Nm -utility 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 -Note that in contexts where a host name is expected, a -.Fl 4 -qualifier preceding the host name forces DNS resolution to the -IPv4 namespace, while a -.Fl 6 -qualifier forces DNS resolution to the IPv6 namespace. -.Pp -If NetInfo support is compiled into -.Nm , -then the -.Cm server -argument is optional if -.Nm -can find a -time server in the NetInfo configuration for -.Xr ntpd 8 . -.Sh FILES -.Bl -tag -width /etc/ntp.keys -compact -.It Pa /etc/ntp.keys -contains the encryption keys used by -.Nm . -.El -.Sh SEE ALSO -.Xr ntpd 8 -.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 kern.clockrate.tick -and -.Va kern.clockrate.tickadj . diff --git a/usr.sbin/ntp/doc/ntpdc.8 b/usr.sbin/ntp/doc/ntpdc.8 deleted file mode 100644 index 35ea7aa..0000000 --- a/usr.sbin/ntp/doc/ntpdc.8 +++ /dev/null @@ -1,715 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd May 17, 2006 -.Dt NTPDC 8 -.Os -.Sh NAME -.Nm ntpdc -.Nd special NTP query program -.Sh SYNOPSIS -.Nm -.Op Fl 46ilnps -.Op Fl c Ar command -.Op Ar host -.Op Ar ... -.Sh DESCRIPTION -The -.Nm -utility 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 startup using -ntpd's configuration file may also be specified at run time using -.Nm . -.Pp -The following options are available: -.Bl -tag -width indent -.It Fl 4 -Force DNS resolution of following host names on the command line to the -IPv4 namespace. -.It Fl 6 -Force DNS resolution of following host names on the command line to the -IPv6 namespace. -.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 l -Obtain a list of peers which are known to the server(s). -This -switch is equivalent to -.Ql Fl c Ar 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 -.Ql Fn c Ar 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 -.Ql Fl c Ar dmpeers . -.El -.Pp -If one or more request options are included on the command line -when -.Nm -is executed, each of the requests will be sent -to the NTP servers running on each of the hosts given as command -line arguments, or on localhost by default. -If no request options -are given, -.Nm -will attempt to read commands from the -standard input and execute these on the NTP server running on the -first host given on the command line, again defaulting to localhost -when no other host is specified. -The -.Nm -utility will prompt for -commands if the standard input is a terminal device. -.Pp -The -.Nm -utility uses NTP mode 7 packets to communicate with the -NTP server, and hence can be used to query any compatible server on -the network which permits it. -Note that since NTP is a UDP protocol -this communication will be somewhat unreliable, especially over -large distances in terms of network topology. -The -.Nm -utility makes -no attempt to retransmit requests, and will time requests out if -the remote host is not heard from within a suitable timeout -time. -.Pp -The operation of -.Nm -are specific to the particular -implementation of the -.Xr ntpd 8 -daemon and can be expected to -work only with this and maybe some previous versions of the daemon. -Requests from a remote -.Nm -utility which affect the -state of the local server must be authenticated, which requires -both the remote program and local server share a common key and key -identifier. -.Pp -Note that in contexts where a host name is expected, a -.Fl 4 -qualifier preceding the host name forces DNS resolution to the IPv4 namespace, -while a -.Fl 6 -qualifier forces DNS resolution to the IPv6 namespace. -Specifying a command line option other than -.Fl i -or -.Fl n -will cause the specified query (queries) to be sent to -the indicated host(s) immediately. -Otherwise, -.Nm -will -attempt to read interactive format commands from the standard -input. -.Ss "Interactive Commands" -Interactive format commands consist of a keyword followed by zero -to four arguments. -Only enough characters of the full keyword to -uniquely identify the command need be typed. -The output of a -command is normally sent to the standard output, but optionally the -output of individual commands may be sent to a file by appending a -.Ql \&> , -followed by a file name, to the command line. -.Pp -A number of interactive format commands are executed entirely -within the -.Nm -utility itself and do not result in NTP -mode 7 requests being sent to a server. -These are described -following. -.Bl -tag -width indent -.It Ic \&? Ar command_keyword -.It Ic help Ar command_keyword -A -.Sq Ic \&? -will print a list of all the command -keywords known to this incarnation of -.Nm . -A -.Sq Ic \&? -followed by a command keyword will print function and usage -information about the command. -This command is probably a better -source of information about -.Xr ntpq 8 -than this manual -page. -.It Ic delay Ar milliseconds -Specify a time interval to be added to timestamps included in -requests which require authentication. -This is used to enable -(unreliable) server reconfiguration over long delay network paths -or between machines whose clocks are unsynchronized. -Actually the -server does not now require timestamps in authenticated requests, -so this command may be obsolete. -.It Ic host Ar hostname -Set the host to which future queries will be sent. -Hostname may -be either a host name or a numeric address. -.It Ic hostnames Op Cm yes | Cm no -If -.Cm yes -is specified, host names are printed in -information displays. -If -.Cm no -is specified, numeric -addresses are printed instead. -The default is -.Cm yes , -unless -modified using the command line -.Fl n -switch. -.It Ic keyid Ar keyid -This command allows the specification of a key number to be -used to authenticate configuration requests. -This must correspond -to a key number the server has been configured to use for this -purpose. -.It Ic quit -Exit -.Nm . -.It Ic passwd -This command prompts you to type in a password (which will not -be echoed) which will be used to authenticate configuration -requests. -The password must correspond to the key configured for -use by the NTP server for this purpose if such requests are to be -successful. -.It Ic timeout Ar milliseconds -Specify a timeout period for responses to server queries. -The -default is about 8000 milliseconds. -Note that since -.Nm -retries each query once after a timeout, the total waiting time for -a timeout will be twice the timeout value set. -.El -.Ss "Control Message Commands" -Query commands result in NTP mode 7 packets containing requests for -information being sent to the server. -These are read-only commands -in that they make no modification of the server configuration -state. -.Bl -tag -width indent -.It Ic listpeers -Obtains and prints a brief list of the peers for which the -server is maintaining state. -These should include all configured -peer associations as well as those peers whose stratum is such that -they are considered by the server to be possible future -synchronization candidates. -.It Ic peers -Obtains a list of peers for which the server is maintaining -state, along with a summary of that state. -Summary information -includes the address of the remote peer, the local interface -address (0.0.0.0 if a local address has yet to be determined), the -stratum of the remote peer (a stratum of 16 indicates the remote -peer is unsynchronized), the polling interval, in seconds, the -reachability register, in octal, and the current estimated delay, -offset and dispersion of the peer, all in seconds. -.Pp -The character in the left margin indicates the mode this peer -entry is operating in. -A -.Ql \&+ -denotes symmetric active, a -.Ql \&- -indicates symmetric passive, a -.Ql \&= -means the -remote server is being polled in client mode, a -.Ql \&^ -indicates that the server is broadcasting to this address, a -.Ql \&~ -denotes that the remote peer is sending broadcasts and a -.Ql \&* -marks the peer the server is currently synchronizing -to. -.Pp -The contents of the host field may be one of four forms. -It may -be a host name, an IP address, a reference clock implementation -name with its parameter or -.Fn REFCLK "implementation_number" "parameter" . -On -.Ic hostnames -.Cm no -only IP-addresses -will be displayed. -.It Ic dmpeers -A slightly different peer summary list. -Identical to the output -of the -.Ic peers -command, except for the character in the -leftmost column. -Characters only appear beside peers which were -included in the final stage of the clock selection algorithm. -A -.Ql \&. -indicates that this peer was cast off in the falseticker -detection, while a -.Ql \&+ -indicates that the peer made it -through. -A -.Ql \&* -denotes the peer the server is currently -synchronizing with. -.It Ic showpeer Ar peer_address Oo Ar ... Oc -Shows a detailed display of the current peer variables for one -or more peers. -Most of these values are described in the NTP -Version 2 specification. -.It Ic pstats Ar peer_address Oo Ar ... Oc -Show per-peer statistic counters associated with the specified -peer(s). -.It Ic clockinfo Ar clock_peer_address Oo Ar ... Oc -Obtain and print information concerning a peer clock. -The -values obtained provide information on the setting of fudge factors -and other clock performance information. -.It Ic kerninfo -Obtain and print kernel phase-lock loop operating parameters. -This information is available only if the kernel has been specially -modified for a precision timekeeping function. -.It Ic loopinfo Op Cm oneline | Cm multiline -Print the values of selected loop filter variables. -The loop -filter is the part of NTP which deals with adjusting the local -system clock. -The -.Sq offset -is the last offset given to the -loop filter by the packet processing code. -The -.Sq frequency -is the frequency error of the local clock in parts-per-million -(ppm). -The -.Sq time_const -controls the stiffness of the -phase-lock loop and thus the speed at which it can adapt to -oscillator drift. -The -.Sq watchdog timer -value is the number -of seconds which have elapsed since the last sample offset was -given to the loop filter. -The -.Cm oneline -and -.Cm multiline -options specify the format in which this -information is to be printed, with -.Cm multiline -as the -default. -.It Ic sysinfo -Print a variety of system state variables, i.e., state related -to the local server. -All except the last four lines are described -in the NTP Version 3 specification, RFC-1305. -.Pp -The -.Sq system flags -show various system flags, some of -which can be set and cleared by the -.Ic enable -and -.Ic disable -configuration commands, respectively. -These are -the -.Cm auth , -.Cm bclient , -.Cm monitor , -.Cm pll , -.Cm pps -and -.Cm stats -flags. -See the -.Xr ntpd 8 -documentation for the meaning of these flags. -There -are two additional flags which are read only, the -.Cm kernel_pll -and -.Cm kernel_pps . -These flags indicate -the synchronization status when the precision time kernel -modifications are in use. -The -.Sq kernel_pll -indicates that -the local clock is being disciplined by the kernel, while the -.Sq kernel_pps -indicates the kernel discipline is provided by the PPS -signal. -.Pp -The -.Sq stability -is the residual frequency error remaining -after the system frequency correction is applied and is intended for -maintenance and debugging. -In most architectures, this value will -initially decrease from as high as 500 ppm to a nominal value in -the range .01 to 0.1 ppm. -If it remains high for some time after -starting the daemon, something may be wrong with the local clock, -or the value of the kernel variable -.Va kern.clockrate.tick -may be -incorrect. -.Pp -The -.Sq broadcastdelay -shows the default broadcast delay, -as set by the -.Ic broadcastdelay -configuration command. -.Pp -The -.Sq authdelay -shows the default authentication delay, -as set by the -.Ic authdelay -configuration command. -.It Ic sysstats -Print statistics counters maintained in the protocol -module. -.It Ic memstats -Print statistics counters related to memory allocation -code. -.It Ic iostats -Print statistics counters maintained in the input-output -module. -.It Ic timerstats -Print statistics counters maintained in the timer/event queue -support code. -.It Ic reslist -Obtain and print the server's restriction list. -This list is -(usually) printed in sorted order and may help to understand how -the restrictions are applied. -.It Ic monlist Op Ar version -Obtain and print traffic counts collected and maintained by the -monitor facility. -The version number should not normally need to be -specified. -.It Ic clkbug Ar clock_peer_address Oo Ar ... Oc -Obtain debugging information for a reference clock driver. -This -information is provided only by some clock drivers and is mostly -undecodable without a copy of the driver source in hand. -.El -.Ss "Runtime Configuration Requests" -All requests which cause state changes in the server are -authenticated by the server using a configured NTP key (the -facility can also be disabled by the server by not configuring a -key). -The key number and the corresponding key must also be made -known to -.Nm . -This can be done using the -.Ic keyid -and -.Ic passwd -commands, the latter of which will prompt at the terminal for a -password to use as the encryption key. -You will also be prompted -automatically for both the key number and password the first time a -command which would result in an authenticated request to the -server is given. -Authentication not only provides verification that -the requester has permission to make such changes, but also gives -an extra degree of protection again transmission errors. -.Pp -Authenticated requests always include a timestamp in the packet -data, which is included in the computation of the authentication -code. -This timestamp is compared by the server to its receive time -stamp. -If they differ by more than a small amount the request is -rejected. -This is done for two reasons. -First, it makes simple -replay attacks on the server, by someone who might be able to -overhear traffic on your LAN, much more difficult. -Second, it makes -it more difficult to request configuration changes to your server -from topologically remote hosts. -While the reconfiguration facility -will work well with a server on the local host, and may work -adequately between time-synchronized hosts on the same LAN, it will -work very poorly for more distant hosts. -As such, if reasonable -passwords are chosen, care is taken in the distribution and -protection of keys and appropriate source address restrictions are -applied, the run time reconfiguration facility should provide an -adequate level of security. -.Pp -The following commands all make authenticated requests. -.Bl -tag -width indent -.It Xo Ic addpeer Ar peer_address -.Op Ar keyid -.Op Ar version -.Op Cm prefer -.Xc -Add a configured peer association at the given address and -operating in symmetric active mode. -Note that an existing -association with the same peer may be deleted when this command is -executed, or may simply be converted to conform to the new -configuration, as appropriate. -If the optional -.Ar keyid -is a -nonzero integer, all outgoing packets to the remote server will -have an authentication field attached encrypted with this key. -If -the value is 0 (or not given) no authentication will be done. -The -.Ar version -can be 1, 2 or 3 and defaults to 3. -The -.Cm prefer -keyword indicates a preferred peer (and thus will -be used primarily for clock synchronisation if possible). -The -preferred peer also determines the validity of the PPS signal - if -the preferred peer is suitable for synchronisation so is the PPS -signal. -.It Xo Ic addserver Ar peer_address -.Op Ar keyid -.Op Ar version -.Op Cm prefer -.Xc -Identical to the addpeer command, except that the operating -mode is client. -.It Xo Ic broadcast Ar peer_address -.Op Ar keyid -.Op Ar version -.Op Cm prefer -.Xc -Identical to the addpeer command, except that the operating -mode is broadcast. -In this case a valid key identifier and key are -required. -The -.Ar peer_address -parameter can be the broadcast -address of the local network or a multicast group address assigned -to NTP. -If a multicast address, a multicast-capable kernel is -required. -.It Ic unconfig Ar peer_address Oo Ar ... Oc -This command causes the configured bit to be removed from the -specified peer(s). -In many cases this will cause the peer -association to be deleted. -When appropriate, however, the -association may persist in an unconfigured mode if the remote peer -is willing to continue on in this fashion. -.It Xo Ic fudge Ar peer_address -.Op Cm time1 -.Op Cm time2 -.Op Ar stratum -.Op Ar refid -.Xc -This command provides a way to set certain data for a reference -clock. -See the source listing for further information. -.It Xo Ic enable -.Oo -.Cm auth | Cm bclient | -.Cm calibrate | Cm kernel | -.Cm monitor | Cm ntp | -.Cm pps | Cm stats -.Oc -.Xc -.It Xo Ic disable -.Oo -.Cm auth | Cm bclient | -.Cm calibrate | Cm kernel | -.Cm monitor | Cm ntp | -.Cm pps | Cm stats -.Oc -.Xc -These commands operate in the same way as the -.Ic enable -and -.Ic disable -configuration file commands of -.Xr ntpd 8 . -.Bl -tag -width indent -.It Cm auth -Enables the server to synchronize with unconfigured peers only -if the peer has been correctly authenticated using either public key -or private key cryptography. -The default for this flag is enable. -.It Cm bclient -Enables the server to listen for a message from a broadcast or -multicast server, as in the multicastclient command with -default address. -The default for this flag is disable. -.It Cm calibrate -Enables the calibrate feature for reference clocks. -The default for this flag is disable. -.It Cm kernel -Enables the kernel time discipline, if available. -The default for this flag is enable if support is available, otherwise disable. -.It Cm monitor -Enables the monitoring facility. -See the -.Xr ntpdc 8 . -program and the monlist command or further information. -The default for this flag is enable. -.It Cm ntp -Enables time and frequency discipline. -In effect, this switch opens and closes the feedback loop, -which is useful for testing. -The default for this flag is enable. -.It Cm pps -Enables the pulse-per-second (PPS) signal when frequency -and time is disciplined by the precision time kernel modifications. -See the -.Qq A Kernel Model for Precision Timekeeping -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) -page for further information. -The default for this flag is disable. -.It Cm stats -Enables the statistics facility. -See the -.Sx Monitoring Options -section of -.Xr ntp.conf 5 -for further information. -The default for this flag is disable. -.El -.It Xo Ic restrict Ar address Ar mask -.Ar flag Oo Ar ... Oc -.Xc -This command operates in the same way as the -.Ic restrict -configuration file commands of -.Xr ntpd 8 . -.It Xo Ic unrestrict Ar address Ar mask -.Ar flag Oo Ar ... Oc -.Xc -Unrestrict the matching entry from the restrict list. -.It Xo Ic delrestrict Ar address Ar mask -.Op Cm ntpport -.Xc -Delete the matching entry from the restrict list. -.It Ic readkeys -Causes the current set of authentication keys to be purged and -a new set to be obtained by rereading the keys file (which must -have been specified in the -.Xr ntpd 8 -configuration file). -This -allows encryption keys to be changed without restarting the -server. -.It Ic trustedkey Ar keyid Oo Ar ... Oc -.It Ic untrustedkey Ar keyid Oo Ar ... Oc -These commands operate in the same way as the -.Ic trustedkey -and -.Ic untrustedkey -configuration file -commands of -.Xr ntpd 8 . -.It Ic authinfo -Returns information concerning the authentication module, -including known keys and counts of encryptions and decryptions -which have been done. -.It Ic traps -Display the traps set in the server. -See the source listing for -further information. -.It Xo Ic addtrap Ar address -.Op Ar port -.Op Ar interface -.Xc -Set a trap for asynchronous messages. -See the source listing -for further information. -.It Xo Ic clrtrap Ar address -.Op Ar port -.Op Ar interface -.Xc -Clear a trap for asynchronous messages. -See the source listing -for further information. -.It Ic reset -Clear the statistics counters in various modules of the server. -See the source listing for further information. -.El -.Sh SEE ALSO -.Xr ntp.conf 5 , -.Xr ntpd 8 -.Rs -.%A David L. Mills -.%T Network Time Protocol (Version 3) -.%O RFC1305 -.Re -.Sh BUGS -The -.Nm -utility is a crude hack. -Much of the information it shows is -deadly boring and could only be loved by its implementer. -The -program was designed so that new (and temporary) features were easy -to hack in, at great expense to the program's ease of use. -Despite -this, the program is occasionally useful. diff --git a/usr.sbin/ntp/doc/ntpq.8 b/usr.sbin/ntp/doc/ntpq.8 deleted file mode 100644 index 0a47c76..0000000 --- a/usr.sbin/ntp/doc/ntpq.8 +++ /dev/null @@ -1,851 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd May 17, 2006 -.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 -.Op Ar ... -.Sh DESCRIPTION -The -.Nm -utility is used to monitor NTP daemon -.Xr ntpd 8 -operations and determine performance. -It uses the standard NTP mode 6 control message formats -defined in Appendix B of the NTPv3 specification RFC1305. -The same formats are used in NTPv4, although some of the variables -have changed and new ones added. -The description on this page is for the NTPv4 variables. -.Pp -The program can be run either in interactive mode or controlled -using command line arguments. -Requests to read and write arbitrary variables can be assembled, -with raw and pretty-printed output options being available. -The -.Nm -can also obtain and print a list of peers in a common format -by sendingmultiple 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 localhost by default. -If no request options -are given, -.Nm -will attempt to read commands from the -standard input and execute these on the NTP server running on the -first host given on the command line, again defaulting to localhost -when no other host is specified. -The -.Nm -utility will prompt for -commands if the standard input is a terminal device. -.Pp -The -.Nm -utility uses NTP mode 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. -The -.Nm -utility 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 -For examples and usage, see the -.Qq NTP Debugging Techniques -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -.Pp -The following options are available: -.Bl -tag -width indent -.It Fl 4 -Force DNS resolution of following host names on the command line to the -IPv4 namespace. -.It Fl 6 -Force DNS resolution of following host names on the command line to the -IPv6 namespace. -.It Fl c -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 d -Turn on debugging mode. -.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 -.Pp -Note that in contexts where a host name is expected, a -.Fl 4 -qualifier preceding the host name forces DNS resolution to the -IPv4 namespace, while a -.Fl 6 -qualifier forces DNS resolution to the IPv6 namespace. -Specifying a -command line option other than -.Fl i -or -.Fl n -will -cause the specified query (queries) to be sent to the indicated -host(s) immediately. -Otherwise, -.Nm -will attempt to read -interactive format commands from the standard input. -.Ss "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 -.Ql \&> , -followed by a file name, to the command line. -A -number of interactive format commands are executed entirely within -the -.Nm -utility 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 -.Sq Ic \&? -by itself will print a list of all the command -keywords known to this incarnation of -.Nm . -A -.Sq Ic \&? -followed by a command keyword will print function and usage -information about the command. -This command is probably a better -source of information about -.Nm -than this manual -page. -.It Xo Ic addvars -.Ar variable_name Ns Op = Ns Ar value ... -.Xc -.It Ic rmvars Ar variable_name ... -.It Ic clearvars -The data carried by NTP mode 6 messages consists of a list of -items of the form -.Ql variable_name=value , -where the -.Ql =value -is ignored, and can be omitted, -in requests to the server to read variables. -The -.Nm -utility 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 clearlist -command removes all variables from the -list. -.It Ic cooked -Causes output from query commands to be "cooked", so that -variables which are recognized by -.Nm -will have their -values reformatted for human consumption. -Variables which -.Nm -thinks should have a decodable value but did not are -marked with a trailing -.Ql \&? . -.It Xo Ic debug -.Cm more | -.Cm less | -.Cm off -.Xc -Turns 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. -Hostname may -be either a host name or a numeric address. -.It Ic hostnames Cm yes | Cm no -If -.Cm yes -is specified, host names are printed in -information displays. -If -.Cm no -is specified, numeric -addresses are printed instead. -The default is -.Cm yes , -unless -modified using the command line -.Fl n -switch. -.It Ic keyid Ar keyid -This command specifies the 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 Xo Ic ntpversion -.Cm 1 | -.Cm 2 | -.Cm 3 | -.Cm 4 -.Xc -Sets the NTP version number which -.Nm -claims in -packets. -Defaults to 3, Note that mode 6 control messages (and -modes, for that matter) did not exist in NTP version 1. -There appear -to be no servers left which demand version 1. -.It Ic passwd -This command prompts for a password (which will not be echoed) which will -be used to authenticate configuration requests. -The password must -correspond to the key configured for NTP server for this purpose. -.It Ic quit -Exit -.Nm . -.It Ic raw -Causes all output from query commands is printed as received -from the remote server. -The only formatting/interpretation done on -the data is to transform nonascii 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 association known to an NTP server has a 16 bit integer association -identifier. -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 peers command, which will send a preprogrammed -series of messages to obtain the data it needs, and the mreadlist -and 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. -See the peers command -for a decode of the -.Sq condition -field. -Note that the data -returned by the -.Ic associations -command is cached internally -in -.Nm . -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 and index may be -used as an alternative. -.It Xo Ic clockvar Op Ar assocID -.Oo -.Ar variable_name Ns Op = Ns Ar value ... -.Oc -.Ar ... -.Xc -.It Xo Ic cv Op Ar assocID -.Oo -.Ar variable_name Ns Op = Ns Ar value ... -.Oc -.Ar ... -.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 -.Sq 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 lassociations -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 . -.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 R 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 Ar assocID -.It Ic mrl Ar assocID Ar 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 Ar assocID -.Oo -.Ar variable_name Ns Op = Ns Ar value ... -.Oc -.Xc -.It Xo Ic mrv Ar assocID Ar assocID -.Oo -.Ar variable_name Ns Op = Ns Ar value ... -.Oc -.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 -Displays 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 current list 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. -The character at the left margin of each line shows the -synchronization status of the association and is a valuable -diagnostic tool. -The encoding and meaning of this character, -called the tally code, is given later in this page. -.It Ic pstatus Ar assocID -Sends 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 Ar assocID -.It Ic rl 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. -.It Xo Ic readvar Ar assocID -.Ar variable_name Ns Op = Ns Ar value -.Ar ... -.Xc -.It Xo Ic rv Ar assocID -.Ar variable_name Ns Op = Ns Ar value -.Ar ... -.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. -The -encoding and meaning of the variables derived from NTPv3 is given in -RFC-1305; the encoding and meaning of the additional NTPv4 variables are -given later in this page. -.It Xo Ic writevar Ar assocID -.Ar variable_name Ns Op = Ns Ar value -.Ar ... -.Xc -Like the readvar request, except the specified variables are -written instead of read. -.It Ic writelist Op Ar assocID -Like the readlist request, except the internal list variables -are written instead of read. -.El -.Ss Tally Codes -The character in the left margin in the -.Sq peers -billboard, -called the tally code, shows the fate of each association -in the clock selection process. -Following is a list of these characters, the pigeon 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 candidat -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 association 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 -.Ss System Variables -The -.Cm status , -.Cm leap , -.Cm stratum , -.Cm precision , -.Cm rootdelay , -.Cm rootdispersion , -.Cm refid , -.Cm reftime , -.Cm poll , -.Cm offset , -and -.Cm frequency -variables are described in RFC-1305 -specification. -Additional NTPv4 system variables include the following. -.Bl -tag -width indent -.It version -Everything you might need to know about the software version and generation -time. -.It processor -The processor and kernel identification string. -.It system -The operating system version and release identifier. -.It state -The state of the clock discipline state machine. -The values are described -in the architecture briefing on the NTP Project page linked from -www.ntp.org. -.It peer -The internal integer used to identify the association currently designated -the system peer. -.It jitter -The estimated time error of the system clock measured as an exponential -average of RMS time differences. -.It stability -The estimated frequency stability of the system clock measured as an -exponential average of RMS frequency differences. -.El -.Pp -When the NTPv4 daemon is compiled with the OpenSSL software library, additional -system variables are displayed, including some or all of the following, -depending on the particular dance: -.Bl -tag -width indent -.It flags -The current flags word bits and message digest algorithm identifier (NID) -in hex format. -The high order 16 bits of the four-byte word contain the NID -from the OpenSSL ligrary, while the low-order bits are interpreted as -follows: -.Bl -tag -width indent -.It 0x01 -autokey enabled -.It 0x02 -NIST leapseconds file loaded -.It 0x10 -PC identity scheme -.It 0x20 -IFF identity scheme -.It 0x40 -GQ identity scheme -.El -.It hostname -The name of the host as returned by the Unix -.Fn gethostname -library -function. -.It hostkey -The NTP filestamp of the host key file. -.It cert -A list of certificates held by the host. -Each entry includes the subject, -issuer, flags and NTP filestamp in order. -The bits are interpreted as -follows: -.Bl -tag -width indent -.It 0x01 -certificate has been signed by the server -.It 0x02 -certificate is trusted -.It 0x04 -certificate is private -.It 0x08 -certificate contains errors and should not be trusted -.El -.It leapseconds -The NTP filestamp of the NIST leapseconds file. -.It refresh -The NTP timestamp when the host public cryptographic values were refreshed -and signed. -.It signature -The host digest/signature scheme name from the OpenSSL library. -.It tai -The TAI-UTC offset in seconds obtained from the NIST leapseconds table. -.El -.Ss Peer Variables -The -.Cm status , -.Cm srcadr , -.Cm srcport , -.Cm dstadr , -.Cm dstport , -.Cm leap , -.Cm stratum , -.Cm precision , -.Cm rootdelay , -.Cm rootdispersion , -.Cm readh , -.Cm hmode , -.Cm pmode , -.Cm hpoll , -.Cm ppoll , -.Cm offset , -.Cm delay , -.Cm dspersion , -.Cm reftime -variables are described in the RFC-1305 specification, as -are the timestamps -.Cm org , -.Cm rec -and -.Cm xmt . -Additional NTPv4 system variables include -the following. -.Bl -tag -width indent -.It flash -The flash code for the most recent packet received. -The encoding and -meaning of these codes is given later in this page. -.It jitter -The estimated time error of the peer clock measured as an exponential -average of RMS time differences. -.It unreach -The value of the counter which records the number of poll intervals since -the last valid packet was received. -.El -.Pp -When the NTPv4 daemon is compiled with the OpenSSL software library, additional -peer variables are displayed, including the following: -.Bl -tag -width indent -.It flags -The current flag bits. -This word is the server host status word with -additional bits used by the Autokey state machine. -See the source code for -the bit encoding. -.It hostname -The server host name. -.It initkey Ar key -The initial key used by the key list generator in the Autokey protocol. -.It initsequence Ar index -The initial index used by the key list generator in the Autokey protocol. -.It signature -The server message digest/signature scheme name from the OpenSSL software -library. -.It timestamp Ar time -The NTP timestamp when the last Autokey key list was generated and signed. -.El -.Ss Flash Codes -The -.Cm flash -code is a valuable debugging aid displayed in the peer variables -list. -It shows the results of the original sanity checks defined in the NTP -specification RFC-1305 and additional ones added in NTPv4. -There are 12 tests -designated -.Sy TEST1 -through -.Sy TEST12 . -The tests are performed in a certain order -designed to gain maximum diagnostic information while protecting against -accidental or malicious errors. -The -.Sy flash -variable is initialized to zero as -each packet is received. -If after each set of tests one or more bits are set, -the packet is discarded. -.Pp -Tests -.Sy TEST1 -through -.Sy TEST3 -check the packet timestamps from which the offset and -delay are calculated. -If any bits are set, the packet is discarded; otherwise, -the packet header variables are saved. -.Sy TEST4 -and -.Sy TEST5 -are associated with -access control and cryptographic authentication. -If any bits are set, the -packet is discarded immediately with nothing changed. -.Pp -Tests -.Sy TEST6 -through -.Sy TEST8 -check the health of the server. -If any bits are set, -the packet is discarded; otherwise, the offset and delay relative to the server -are calculated and saved. -TEST9 checks the health of the association itself. -If -any bits are set, the packet is discarded; otherwise, the saved variables are -passed to the clock filter and mitigation algorithms. -.Pp -Tests -.Sy TEST10 -through -.Sy TEST12 -check the authentication state using Autokey -public-key cryptography, as described in the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -If -any bits are set and the association has previously been marked reachable, the -packet is discarded; otherwise, the originate and receive timestamps are saved, -as required by the NTP protocol, and processing continues. -.Pp -The -.Cm flash -bits for each test are defined as follows. -.Bl -tag -width indent -.It 0x001 -.Pq TEST1 -Duplicate packet. -The packet is at best a casual retransmission and at -worst a malicious replay. -.It 0x002 -.Pq TEST2 -Bogus packet. -The packet is not a reply to a message previously sent. -This -can happen when the NTP daemon is restarted and before somebody else -notices. -.It 0x004 -.Pq TEST3 -Unsynchronized. -One or more timestamp fields are invalid. -This normally -happens when the first packet from a peer is received. -.It 0x008 -.Pq TEST4 -Access is denied. -See the -.Sx Access Control Support -section of -.Xr ntp.conf 5 . -.It 0x010 -.Pq TEST5 -Cryptographic authentication fails. -See the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -.It 0x020 -.Pq TEST6 -The server is unsynchronized. -Wind up its clock first. -.It 0x040 -.Pq TEST7 -The server stratum is at the maximum than 15. -It is probably unsynchronized -and its clock needs to be wound up. -.It 0x080 -.Pq TEST8 -Either the root delay or dispersion is greater than one second, which is -highly unlikely unless the peer is unsynchronized to Mars. -.It 0x100 -.Pq TEST9 -Either the peer delay or dispersion is greater than one second, which is -higly unlikely unless the peer is on Mars. -.It 0x200 -.Pq TEST10 -The autokey protocol has detected an authentication failure. -See the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -.It 0x400 -.Pq TEST11 -The autokey protocol has not verified the server or peer is proventic and -has valid public key credentials. -See the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -.It 0x800 -.Pq TEST12 -A protocol or configuration error has occurred in the public key algorithms -or a possible intrusion event has been detected. -See the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -.El -.Sh SEE ALSO -.Xr ntp.conf 5 , -.Xr ntpd 8 , -.Xr ntpdc 8 -.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 does not. diff --git a/usr.sbin/ntp/doc/ntptime.8 b/usr.sbin/ntp/doc/ntptime.8 deleted file mode 100644 index f130307..0000000 --- a/usr.sbin/ntp/doc/ntptime.8 +++ /dev/null @@ -1,69 +0,0 @@ -.\" -.\" $FreeBSD$ -.\" -.Dd January 7, 2000 -.Dt NTPTIME 8 -.Os -.Sh NAME -.Nm ntptime -.Nd read kernel time variables -.Sh SYNOPSIS -.Nm -.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 -The -.Nm -utility 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 -.Fn gettime -and -.Xr adjtime 2 -system calls if available. -A similar display can be obtained using the -.Xr ntpdc 8 -program's -.Ic kerninfo -command. -.Pp -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 help information. -.It Fl l -Specify the leap bits as a code from 0 to 3. -.It Fl m Ar max_error -Specify max possible errors, in microseconds. -.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 adjtime 2 , -.Xr ntpdc 8 diff --git a/usr.sbin/ntp/doc/ntptrace.8 b/usr.sbin/ntp/doc/ntptrace.8 deleted file mode 100644 index 554a3c0..0000000 --- a/usr.sbin/ntp/doc/ntptrace.8 +++ /dev/null @@ -1,76 +0,0 @@ -.\" -.\" $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 -.Op Fl vdn -.Op Fl r Ar retries -.Op Fl t Ar timeout -.Op Ar server -.Sh DESCRIPTION -The -.Nm -utility 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 : -.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 ; -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 ntpd 8 , -.Xr ntpdc 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. |
