diff --git a/usr.sbin/ntp/doc/Makefile b/usr.sbin/ntp/doc/Makefile --- a/usr.sbin/ntp/doc/Makefile +++ b/usr.sbin/ntp/doc/Makefile @@ -24,9 +24,46 @@ MAN= ntp.conf.5 ntp.keys.5 MAN+= ntp-keygen.8 ntpd.8 ntpdate.8 ntpdc.8 ntpq.8 ntptime.8 sntp.8 +CLEANFILES= ntp.conf.5 ntp.keys.5 +CLEANFILES+= ntp-keygen.8 ntpd.8 ntpdc.8 ntpq.8 sntp.8 + +SUFFIXES8= .1ntp-keygenmdoc \ + .1ntpdmdoc \ + .1ntpdcmdoc \ + .1ntpqmdoc \ + .1sntpmdoc + +.SUFFIXES: .html .5 .8 .5mdoc ${SUFFIXES8} + +.5mdoc.5: + sed '/^\.Dt /s/5mdoc/5/' ${.ALLSRC} > ${.TARGET} + +.for s in ${SUFFIXES8} +$s.8: + sed '/^\.Dt /s/1[a-z-][a-z-]*/8/' ${.ALLSRC} > ${.TARGET} +.endfor + +ntp.conf.5: ntp.conf.5mdoc + +ntp.keys.5: ntp.keys.5mdoc + +ntp-keygen.8: ntp-keygen.1ntp-keygenmdoc + +ntpd.8: ntpd.1ntpdmdoc + +ntpdc.8: ntpdc.1ntpdcmdoc + +ntpq.8: ntpq.1ntpqmdoc + +sntp.8: sntp.1sntpmdoc + .PATH: ${SRCTOP}/contrib/ntp/html \ ${SRCTOP}/contrib/ntp/util \ ${SRCTOP}/contrib/ntp/ntpd \ - ${SRCTOP}/contrib/ntp/ntpsnmpd + ${SRCTOP}/contrib/ntp/ntpdc \ + ${SRCTOP}/contrib/ntp/ntpq \ + ${SRCTOP}/contrib/ntp/ntpsnmpd \ + ${SRCTOP}/contrib/ntp/sntp \ + ${SRCTOP}/contrib/ntp/util .include diff --git a/usr.sbin/ntp/doc/ntp-keygen.8 b/usr.sbin/ntp/doc/ntp-keygen.8 deleted file mode 100644 --- a/usr.sbin/ntp/doc/ntp-keygen.8 +++ /dev/null @@ -1,1223 +0,0 @@ -.Dd August 14 2018 -.Dt NTP_KEYGEN 8 User Commands -.Os -.\" EDIT THIS FILE WITH CAUTION (ntp-keygen-opts.mdoc) -.\" -.\" It has been AutoGen-ed August 14, 2018 at 08:30:38 AM by AutoGen 5.18.5 -.\" From the definitions ntp-keygen-opts.def -.\" and the template file agmdoc-cmd.tpl -.Sh NAME -.Nm ntp-keygen -.Nd create a Network Time Protocol host key -.Sh SYNOPSIS -.Nm -.\" Mixture of short (flag) options and long options -.Op Fl flags -.Op Fl flag Op Ar value -.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc -.Pp -All arguments must be options. -.Pp -.Sh DESCRIPTION -This program generates cryptographic data files used by the NTPv4 -authentication and identification schemes. -It can generate message digest keys used in symmetric key cryptography and, -if the OpenSSL software library has been installed, it can generate host keys, -signing keys, certificates, and identity keys and parameters used in Autokey -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 -The message digest symmetric keys file is generated in a format -compatible with NTPv3. -All other files are in PEM\-encoded printable ASCII format, -so they can be embedded as MIME attachments in email to other sites -and certificate authorities. -By default, files are not encrypted. -.Pp -When used to generate message digest symmetric keys, the program -produces a file containing ten pseudo\-random printable ASCII strings -suitable for the MD5 message digest algorithm included in the -distribution. -If the OpenSSL library is installed, it produces an additional ten -hex\-encoded random bit strings suitable for SHA1, AES\-128\-CMAC, and -other message digest algorithms. -The message digest symmetric keys file must be distributed and stored -using secure means beyond the scope of NTP itself. -Besides the keys used for ordinary NTP associations, additional keys -can be defined as passwords for the -.Xr ntpq 8 -and -.Xr ntpdc 8 -utility programs. -.Pp -The remaining generated files are compatible with other OpenSSL -applications and other Public Key Infrastructure (PKI) resources. -Certificates generated by this program are compatible with extant -industry practice, although some users might find the interpretation of -X509v3 extension fields somewhat liberal. -However, the identity keys are probably not compatible with anything -other than Autokey. -.Pp -Some files used by this program are encrypted using a private password. -The -.Fl p -option specifies the read password for local encrypted files and the -.Fl q -option the write password for encrypted files sent to remote sites. -If no password is specified, the host name returned by the Unix -.Xr hostname 1 -command, normally the DNS name of the host, is used as the the default read -password, for convenience. -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 -.Cm pw -option of the -.Ic crypto -.Xr ntpd 8 -configuration command specifies the read -password for previously encrypted local files. -This must match the local read password used by this program. -If not specified, the host name is used. -Thus, if files are generated by this program without an explicit password, -they can be read back by -.Xr ntpd 8 -without specifying an explicit password but only on the same host. -If the write password used for encryption is specified as the host name, -these files can be read by that host with no explicit password. -.Pp -Normally, encrypted files for each host are generated by that host and -used only by that host, although exceptions exist as noted later on -this page. -The symmetric keys file, normally called -.Pa ntp.keys , -is usually installed in -.Pa /etc . -Other files and links are usually installed in -.Pa /usr/local/etc , -which is normally in a shared filesystem in -NFS\-mounted networks and cannot be changed by shared clients. -In these cases, NFS clients can specify the files in another -directory such as -.Pa /etc -using the -.Ic keysdir -.Xr ntpd 8 -configuration file command. -.Pp -This program directs commentary and error messages to the standard -error stream -.Pa stderr -and remote files to the standard output stream -.Pa stdout -where they can be piped to other applications or redirected to files. -The names used for generated files and links all begin with the -string -.Pa ntpkey\&* -and include the file type, generating host and filestamp, -as described in the -.Sx "Cryptographic Data Files" -section below. -.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 -.Ar keys -directory, usually -.Pa /usr/local/etc , -then run the program. -.Pp -To test and gain experience with Autokey concepts, log in as root and -change to the -.Ar keys -directory, usually -.Pa /usr/local/etc . -When run for the first time, or if all files with names beginning with -.Pa ntpkey\&* -have been removed, use the -.Nm -command without arguments to generate a default -.Cm RSA -host key and matching -.Cm RSA\-MD5 -certificate file with expiration date one year hence, -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 without options, the program uses the -existing keys and parameters and generates a new certificate file with -new expiration date one year hence, and soft link. -.Pp -The host key is used to encrypt the cookie when required and so must be -.Cm 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 -.Cm RSA -or -.Cm DSA -type. -By default, the message digest type is -.Cm MD5 , -but any combination -of sign key type and message digest type supported by the OpenSSL library -can be specified, including those using the -.Cm AES128CMAC , MD2 , MD5 , MDC2 , SHA , SHA1 -and -.Cm 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 -.Cm RSA -sign keys; -however, only -.Cm SHA -and -.Cm SHA1 -certificates are compatible with -.Cm 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 -.Xr su 1 -command -to assume root may not work properly, since by default the OpenSSL library -looks for the random seed file -.Pa .rnd -in the user home directory. -However, there should be only one -.Pa .rnd , -most conveniently -in the root directory, so it is convenient to define the -.Ev RANDFILE -environment variable used by the OpenSSL library as the path to -.Pa .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 -.Xr ntpd 8 -configuration file 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 -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 -.Ar hostname -and -.Ar filestamp -file name extensions, the files for an NTP 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, -.Xr ntpd 8 -follows it to the file name to extract the -.Ar filestamp . -If a link is not present, -.Xr ntpd 8 -extracts the -.Ar 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 -.Ar filestamp -extension for all files generated -at one time, so each generation is distinct and can be readily -recognized in monitoring data. -.Pp -Run the command on as many hosts as necessary. -Designate one of them as the trusted host (TH) using -.Nm -with the -.Fl T -option and configure it to synchronize from reliable Internet servers. -Then configure the other hosts to synchronize to the TH directly or -indirectly. -A certificate trail is created when Autokey asks the immediately -ascendant host towards the TH to sign its certificate, which is then -provided to the immediately descendant host on request. -All group hosts should have acyclic certificate trails ending on the TH. -.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. -A different sign key can be assigned using the -.Fl S -option and this can be either -.Cm RSA -or -.Cm DSA -type. -By default, the signature -message digest type is -.Cm MD5 , -but any combination of sign key type and -message digest type supported by the OpenSSL library can be specified -using the -.Fl c -option. -.Pp -The rules say cryptographic media should be generated with proventic -filestamps, which means the host should already be synchronized before -this program is run. -This of course creates a chicken\-and\-egg problem -when the host is started for the first time. -Accordingly, the host time -should be set by some other means, such as eyeball\-and\-wristwatch, at -least so that the certificate lifetime is within the current year. -After that and when the host is synchronized to a proventic source, the -certificate should be re\-generated. -.Pp -Additional information on trusted groups and identity schemes is on the -.Dq Autokey Public\-Key Authentication -page. -.Pp -File names begin with the prefix -.Pa ntpkey Ns _ -and end with the suffix -.Pa _ Ns Ar hostname . Ar filestamp , -where -.Ar hostname -is the owner name, usually the string returned -by the Unix -.Xr hostname 1 -command, 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 Pa ntpkey\&* -command or all files generated -at a specific time can be removed by a -.Ic rm Pa \&* Ns 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. -.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 -.Cm RSA -encryption, -.Cm MD5 -message digest -and -.Cm 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 -.Pa 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 frequent need to do this is when a -.Cm DSA Ns \-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, and soft link. -.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, and soft links. -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 -.Cm TC -identity scheme is vulnerable to a middleman attack. -However, there are more secure identity schemes available, -including -.Cm PC , IFF , GQ -and -.Cm MV -schemes described below. -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 Ns _ Cm RSA Pa key_alice. Ar filestamp -and trusted private certificate file -.Pa ntpkey Ns _ Cm RSA\-MD5 _ Pa cert_alice. Ar filestamp , -and soft links. -Copy both files to all group hosts; -they replace the files which would be generated in other schemes. -On each host -.Ar 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, and recreating the soft links. -.Pp -For the -.Cm IFF -scheme proceed as in the -.Cm TC -scheme to generate keys -and certificates for all group hosts, then for every trusted host in the group, -generate the -.Cm 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_alice. Ns Ar 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_alice -to this file. -If there are no hosts restricted to operate only as clients, -there is nothing further to do. -As the -.Cm 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 email program. -Copy or email this file to all restricted clients. -On these clients install a soft link from the generic -.Pa ntpkey_iff_alice -to this file. -To further protect the integrity of the keys, -each file can be encrypted with a secret password. -.Pp -For the -.Cm GQ -scheme proceed as in the -.Cm TC -scheme to generate keys -and certificates for all group hosts, then for every trusted host -in the group, generate the -.Cm 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_alice. Ns Ar 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_alice -to this file. -In addition, on each host -.Ar bob -install a soft link -from generic -.Pa ntpkey_gq_ Ns Ar bob -to this file. -As the -.Cm GQ -scheme updates the -.Cm GQ -parameters file and certificate -at the same time, keys and certificates can be regenerated as needed. -.Pp -For the -.Cm MV -scheme, proceed as in the -.Cm 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_trish. Ns Ar filestamp -and client key files -.Pa ntpkeys_MVkey Ns Ar d _ Pa trish. Ar 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_alice -to this file. -Copy one of the client key files to alice for later distribution -to her clients. -It does not 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 clients. -On client bob install a soft link from generic -.Pa ntpkey_mvkey_bob -to the client key file. -As the -.Cm 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 b Fl \-imbits Ns = Ar modulus -Set the number of bits in the identity modulus for generating identity keys to -.Ar modulus -bits. -The number of bits in the identity modulus defaults to 256, but can be set to -values from 256 to 2048 (32 to 256 octets). -Use the larger moduli with caution, as this can consume considerable computing -resources and increases the size of authenticated packets. -.It Fl c Fl \-certificate Ns = Ar scheme -Select certificate signature encryption/message digest scheme. -The -.Ar scheme -can be one of the following: -.Cm RSA\-MD2 , RSA\-MD5 , RSA\-MDC2 , RSA\-SHA , RSA\-SHA1 , RSA\-RIPEMD160 , DSA\-SHA , -or -.Cm DSA\-SHA1 . -Note that -.Cm RSA -schemes must be used with an -.Cm RSA -sign key and -.Cm DSA -schemes must be used with a -.Cm DSA -sign key. -The default without this option is -.Cm RSA\-MD5 . -If compatibility with FIPS 140\-2 is required, either the -.Cm DSA\-SHA -or -.Cm DSA\-SHA1 -scheme must be used. -.It Fl C Fl \-cipher Ns = Ar cipher -Select the OpenSSL cipher to encrypt the files containing private keys. -The default without this option is three\-key triple DES in CBC mode, -.Cm des\-ede3\-cbc . -The -.Ic openssl Fl h -command provided with OpenSSL displays available ciphers. -.It Fl d Fl \-debug\-level -Increase debugging verbosity level. -This option displays the cryptographic data produced in eye\-friendly billboards. -.It Fl D Fl \-set\-debug\-level Ns = Ar level -Set the debugging verbosity to -.Ar level . -This option displays the cryptographic data produced in eye\-friendly billboards. -.It Fl e Fl \-id\-key -Write the -.Cm IFF -or -.Cm GQ -public parameters from the -.Ar IFFkey or GQkey -client keys file previously specified -as unencrypted data to the standard output stream -.Pa stdout . -This is intended for automatic key distribution by email. -.It Fl G Fl \-gq\-params -Generate a new encrypted -.Cm GQ -parameters and key file for the Guillou\-Quisquater (GQ) identity scheme. -This option is mutually exclusive with the -.Fl I -and -.Fl V -options. -.It Fl H Fl \-host\-key -Generate a new encrypted -.Cm RSA -public/private host key file. -.It Fl I Fl \-iffkey -Generate a new encrypted -.Cm IFF -key file for the Schnorr (IFF) identity scheme. -This option is mutually exclusive with the -.Fl G -and -Fl V -options. -.It Fl i Fl \-ident Ns = Ar group -Set the optional Autokey group name to -.Ar group . -This is used in the identity scheme parameter file names of -.Cm IFF , GQ , -and -.Cm MV -client parameters files. -In that role, the default is the host name if no group is provided. -The group name, if specified using -.Fl i -or -.Fl s -following an -.Ql @ -character, is also used in certificate subject and issuer names in the form -.Ar host @ group -and should match the group specified via -.Ic crypto Cm ident -or -.Ic server Cm ident -in the ntpd configuration file. -.It Fl l Fl \-lifetime Ns = Ar days -Set the lifetime for certificate expiration to -.Ar days . -The default lifetime is one year (365 days). -.It Fl m Fl \-modulus Ns = Ar bits -Set the number of bits in the prime modulus for generating files to -.Ar bits . -The modulus defaults to 512, but can be set from 256 to 2048 (32 to 256 octets). -Use the larger moduli with caution, as this can consume considerable computing -resources and increases the size of authenticated packets. -.It Fl M Fl \-md5key -Generate a new symmetric keys file containing 10 -.Cm MD5 -keys, and if OpenSSL is available, 10 -.Cm SHA -keys. -An -.Cm MD5 -key is a string of 20 random printable ASCII characters, while a -.Cm SHA -key is a string of 40 random hex digits. -The file can be edited using a text editor to change the key type or key content. -This option is mutually exclusive with all other options. -.It Fl p Fl \-password Ns = Ar passwd -Set the password for reading and writing encrypted files to -.Ar passwd . -These include the host, sign and identify key files. -By default, the password is the string returned by the Unix -.Ic hostname -command. -.It Fl P Fl \-pvt\-cert -Generate a new private certificate used by the -.Cm PC -identity scheme. -By default, the program generates public certificates. -Note: the PC identity scheme is not recommended for new installations. -.It Fl q Fl \-export\-passwd Ns = Ar passwd -Set the password for writing encrypted -.Cm IFF , GQ and MV -identity files redirected to -.Pa stdout -to -.Ar passwd . -In effect, these files are decrypted with the -.Fl p -password, then encrypted with the -.Fl q -password. -By default, the password is the string returned by the Unix -.Ic hostname -command. -.It Fl s Fl \-subject\-key Ns = Ar Oo host Oc Op @ Ar group -Specify the Autokey host name, where -.Ar host -is the optional host name and -.Ar group -is the optional group name. -The host name, and if provided, group name are used in -.Ar host @ group -form as certificate subject and issuer. -Specifying -.Fl s @ Ar group -is allowed, and results in leaving the host name unchanged, as with -.Fl i Ar group . -The group name, or if no group is provided, the host name are also used in the -file names of -.Cm IFF , GQ , -and -.Cm MV -identity scheme client parameter files. -If -.Ar host -is not specified, the default host name is the string returned by the Unix -.Ic hostname -command. -.It Fl S Fl \-sign\-key Ns = Op Cm RSA | DSA -Generate a new encrypted public/private sign key file of the specified type. -By default, the sign key is the host key and has the same type. -If compatibility with FIPS 140\-2 is required, the sign key type must be -.Cm DSA . -.It Fl T Fl \-trusted\-cert -Generate a trusted certificate. -By default, the program generates a non\-trusted certificate. -.It Fl V Fl \-mv\-params Ar nkeys -Generate -.Ar nkeys -encrypted server keys and parameters for the Mu\-Varadharajan (MV) -identity scheme. -This option is mutually exclusive with the -.Fl I -and -.Fl G -options. -Note: support for this option should be considered a work in progress. -.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 -.Pa .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 -.Cm 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 -.Pa .rnd -file in the user home directory. -Since both the -.Nm -program and -.Xr ntpd 8 -daemon must run as root, the logical place to put this file is in -.Pa /.rnd -or -.Pa /root/.rnd . -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 file formats begin with two nonencrypted lines. -The first line contains the file name, including the generated host name -and filestamp, in the format -.Pa ntpkey_ Ns Ar key _ Ar name . Ar filestamp , -where -.Ar key -is the key or parameter type, -.Ar name -is the host or group name and -.Ar filestamp -is the filestamp (NTP seconds) when the file was created. -By convention, -.Ar key -names in generated file names include both upper and lower case -characters, while -.Ar key -names in generated link names include only lower case characters. -The filestamp is not used in generated link names. -The second line contains the datestamp in conventional Unix -.Pa date -format. -Lines beginning with -.Ql # -are considered comments and ignored by the -.Nm -program and -.Xr ntpd 8 -daemon. -.Pp -The remainder of the file contains cryptographic data, encoded first using ASN.1 -rules, then encrypted if necessary, and finally written in PEM\-encoded -printable ASCII text, preceded and followed by MIME content identifier lines. -.Pp -The format of the symmetric keys file, ordinarily named -.Pa ntp.keys , -is somewhat different than the other files in the interest of backward compatibility. -Ordinarily, the file is generated by this program, but it can be constructed -and edited using an ordinary text editor. -.Bd -literal -unfilled -offset center -# ntpkey_MD5key_bk.ntp.org.3595864945 -# Thu Dec 12 19:22:25 2013 -1 MD5 L";Nw<\`.Il0%XXK9O'51VwV MV parameters. -This option takes an integer number as its argument. -.sp -Generate parameters and keys for the Mu\-Varadharajan (MV) -identification scheme. -.It Fl v Ar num , Fl \-mv\-keys Ns = Ns Ar num -update MV keys. -This option takes an integer number as its argument. -.sp -This option has not been fully documented. -.It Fl \&? , Fl \-help -Display usage information and exit. -.It Fl \&! , Fl \-more\-help -Pass the extended usage information through a pager. -.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc -Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP -configuration file listed in the \fBOPTION PRESETS\fP section, below. -The command will exit after updating the config file. -.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts -Load options from \fIcfgfile\fP. -The \fIno\-load\-opts\fP form will disable the loading -of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early, -out of order. -.It Fl \-version Op Brq Ar v|c|n -Output version of program and exit. The default mode is `v', a simple -version. The `c' mode will print copyright information and `n' will -print the full copyright notice. -.El -.Sh "OPTION PRESETS" -Any option that is not marked as \fInot presettable\fP may be preset -by loading values from configuration ("RC" or ".INI") file(s) and values from -environment variables named: -.nf - \fBNTP_KEYGEN_\fP or \fBNTP_KEYGEN\fP -.fi -.ad -The environmental presets take precedence (are processed later than) -the configuration files. -The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". -If any of these are directories, then the file \fI.ntprc\fP -is searched for within those directories. -.Sh USAGE -.Sh "ENVIRONMENT" -See \fBOPTION PRESETS\fP for configuration environment variables. -.Sh "FILES" -See \fBOPTION PRESETS\fP for configuration files. -.Sh "EXIT STATUS" -One of the following exit values will be returned: -.Bl -tag -.It 0 " (EXIT_SUCCESS)" -Successful program execution. -.It 1 " (EXIT_FAILURE)" -The operation failed or the command syntax was not valid. -.It 66 " (EX_NOINPUT)" -A specified configuration file could not be loaded. -.It 70 " (EX_SOFTWARE)" -libopts had an internal operational error. Please report -it to autogen\-users@lists.sourceforge.net. Thank you. -.El -.Sh "AUTHORS" -The University of Delaware and Network Time Foundation -.Sh "COPYRIGHT" -Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved. -This program is released under the terms of the NTP license, . -.Sh BUGS -It can take quite a while to generate some cryptographic values. -.Pp -Please report bugs to http://bugs.ntp.org . -.Pp -Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.Sh NOTES -Portions of this document came from FreeBSD. -.Pp -This manual page was \fIAutoGen\fP\-erated from the \fBntp\-keygen\fP -option definitions. diff --git a/usr.sbin/ntp/doc/ntp.conf.5 b/usr.sbin/ntp/doc/ntp.conf.5 deleted file mode 100644 --- a/usr.sbin/ntp/doc/ntp.conf.5 +++ /dev/null @@ -1,3277 +0,0 @@ -.Dd August 14 2018 -.Dt NTP_CONF 5 File Formats -.Os -.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc) -.\" -.\" It has been AutoGen-ed August 14, 2018 at 08:29:15 AM by AutoGen 5.18.5 -.\" From the definitions ntp.conf.def -.\" and the template file agmdoc-cmd.tpl -.Sh NAME -.Nm ntp.conf -.Nd Network Time Protocol daemon (ntpd) configuration format -.Sh SYNOPSIS -.Nm -.Op Fl \-option\-name -.Op Fl \-option\-name Ar value -.Pp -All arguments must be options. -.Pp -.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 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 an 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 pool , -.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 -.Cm reslist -billboard generated -by -.Xr ntpq 8 -or -.Xr ntpdc 8 , -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 pool Ar address -.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 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 -.Op Cm true -.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 -.Op Cm true -.Op Cm xleave -.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 -.Op Cm xleave -.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 five 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 pool -For type s addresses, this command mobilizes a persistent -client mode association with a number of remote servers. -In this mode the local clock can synchronized to the -remote server, but the remote server can never be synchronized to -the local clock. -.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 -.Ic 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 -.Ic 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 65535, 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 algroithm. -.It Cm preempt -Says the association can be preempted. -.It Cm true -Marks the server as a truechimer. -Use this option only for testing. -.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 true -Forces the association to always survive the selection and clustering algorithms. -This option should almost certainly -.Em only -be used while testing an association. -.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. -.It Cm xleave -Valid in -.Cm peer -and -.Cm broadcast -modes only, this flag enables interleave mode. -.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 . -.It Ic mdnstries Ar number -If we are participating in mDNS, -after we have synched for the first time -we attempt to register with the mDNS system. -If that registration attempt fails, -we try again at one minute intervals for up to -.Ic mdnstries -times. -After all, -.Ic ntpd -may be starting before mDNS. -The default value for -.Ic mdnstries -is 5. -.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 on -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,535 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 1ntpkeygenmdoc -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 destination 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 -.Xr ntpq 8 -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 1ntpkeygenmdoc -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 certain 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,535, 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 8 -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,535, 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,535. -.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 the source code 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, eight 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 -.Xr ntpd 8 -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 -.Ic 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 -.Ic 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 Cm ippeerlimit Ar int -.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. -The -.Cm ippeerlimit -directive limits the number of peer requests for each IP to -.Ar int , -where a value of \-1 means "unlimited", the current default. -A value of 0 means "none". -There would usually be at most 1 peering request per IP, -but if the remote peering requests are behind a proxy -there could well be more than 1 per IP. -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 -.Ic 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 noepeer -Deny ephemeral peer requests, -even if they come from an authenticated source. -Note that the ability to use a symmetric key for authentication may be restricted to -one or more IPs or subnets via the third field of the -.Pa ntp.keys -file. -This restriction is not enabled by default, -to maintain backward compatibility. -Expect -.Cm noepeer -to become the default in ntp\-4.4. -.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 unauthenticated packets which would result in mobilizing a new association. -This includes -broadcast and symmetric active packets -when a configured association does not exist. -It also includes -.Cm pool -associations, so if you want to use servers from a -.Cm pool -directive and also want to use -.Cm nopeer -by default, you'll want a -.Cm "restrict source ..." -line as well that does -.Em not -include the -.Cm nopeer -directive. -.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 -.Xr ntpq 8 -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 -.Ic manycastclient -command, which is similar to the -.Ic 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 -.Ic 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 sntp 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 Broadcast Options -.Bl -tag -width indent -.It Xo Ic tos -.Oo -.Cm bcpollbstep Ar gate -.Oc -.Xc -This command provides a way to delay, -by the specified number of broadcast poll intervals, -believing backward time steps from a broadcast server. -Broadcast time networks are expected to be trusted. -In the event a broadcast server's time is stepped backwards, -there is clear benefit to having the clients notice this change -as soon as possible. -Attacks such as replay attacks can happen, however, -and even though there are a number of protections built in to -broadcast mode, attempts to perform a replay attack are possible. -This value defaults to 0, but can be changed -to any number of poll intervals between 0 and 4. -.El -.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 outlier -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 Ic dscp Ar value -This option specifies the Differentiated Services Control Point (DSCP) value, -a 6\-bit code. -The default value is 46, signifying Expedited Forwarding. -.It Xo Ic enable -.Oo -.Cm auth | Cm bclient | -.Cm calibrate | Cm kernel | -.Cm mode7 | Cm monitor | -.Cm ntp | Cm stats | -.Cm peer_clear_digest_early | -.Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early -.Oc -.Xc -.It Xo Ic disable -.Oo -.Cm auth | Cm bclient | -.Cm calibrate | Cm kernel | -.Cm mode7 | Cm monitor | -.Cm ntp | Cm stats | -.Cm peer_clear_digest_early | -.Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early -.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 mode7 -Enables processing of NTP mode 7 implementation\-specific requests -which are used by the deprecated -.Xr ntpdc 8 -program. -The default for this flag is disable. -This flag is excluded from runtime configuration using -.Xr ntpq 8 . -The -.Xr ntpq 8 -program provides the same capabilities as -.Xr ntpdc 8 -using standard mode 6 requests. -.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 peer_clear_digest_early -By default, if -.Xr ntpd 8 -is using autokey and it -receives a crypto\-NAK packet that -passes the duplicate packet and origin timestamp checks -the peer variables are immediately cleared. -While this is generally a feature -as it allows for quick recovery if a server key has changed, -a properly forged and appropriately delivered crypto\-NAK packet -can be used in a DoS attack. -If you have active noticeable problems with this type of DoS attack -then you should consider -disabling this option. -You can check your -.Cm peerstats -file for evidence of any of these attacks. -The -default for this flag is -.Ic enable . -.It Cm stats -Enables the statistics facility. -See the -.Sx Monitoring Options -section for further information. -The default for this flag is -.Ic disable . -.It Cm unpeer_crypto_early -By default, if -.Xr ntpd 8 -receives an autokey packet that fails TEST9, -a crypto failure, -the association is immediately cleared. -This is almost certainly a feature, -but if, in spite of the current recommendation of not using autokey, -you are -.B still -using autokey -.B and -you are seeing this sort of DoS attack -disabling this flag will delay -tearing down the association until the reachability counter -becomes zero. -You can check your -.Cm peerstats -file for evidence of any of these attacks. -The -default for this flag is -.Ic enable . -.It Cm unpeer_crypto_nak_early -By default, if -.Xr ntpd 8 -receives a crypto\-NAK packet that -passes the duplicate packet and origin timestamp checks -the association is immediately cleared. -While this is generally a feature -as it allows for quick recovery if a server key has changed, -a properly forged and appropriately delivered crypto\-NAK packet -can be used in a DoS attack. -If you have active noticeable problems with this type of DoS attack -then you should consider -disabling this option. -You can check your -.Cm peerstats -file for evidence of any of these attacks. -The -default for this flag is -.Ic enable . -.It Cm unpeer_digest_early -By default, if -.Xr ntpd 8 -receives what should be an authenticated packet -that passes other packet sanity checks but -contains an invalid digest -the association is immediately cleared. -While this is generally a feature -as it allows for quick recovery, -if this type of packet is carefully forged and sent -during an appropriate window it can be used for a DoS attack. -If you have active noticeable problems with this type of DoS attack -then you should consider -disabling this option. -You can check your -.Cm peerstats -file for evidence of any of these attacks. -The -default for this flag is -.Ic enable . -.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 Xo Ic interface -.Oo -.Cm listen | Cm ignore | Cm drop -.Oc -.Oo -.Cm all | Cm ipv4 | Cm ipv6 | Cm wildcard -.Ar name | Ar address -.Oo Cm / Ar prefixlen -.Oc -.Oc -.Xc -The -.Cm interface -directive controls which network addresses -.Xr ntpd 8 -opens, and whether input is dropped without processing. -The first parameter determines the action for addresses -which match the second parameter. -The second parameter specifies a class of addresses, -or a specific interface name, -or an address. -In the address case, -.Ar prefixlen -determines how many bits must match for this rule to apply. -.Cm ignore -prevents opening matching addresses, -.Cm drop -causes -.Xr ntpd 8 -to open the address and drop all received packets without examination. -Multiple -.Cm interface -directives can be used. -The last rule which matches a particular address determines the action for it. -.Cm interface -directives are disabled if any -.Fl I , -.Fl \-interface , -.Fl L , -or -.Fl \-novirtualips -command\-line options are specified in the configuration file, -all available network addresses are opened. -The -.Cm nic -directive is an alias for -.Cm interface . -.It Ic leapfile Ar leapfile -This command loads the IERS leapseconds file and initializes the -leapsecond values for the next leapsecond event, leapfile expiration -time, and TAI offset. -The file can be obtained directly from the IERS at -.Li https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list -or -.Li ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list . -The -.Cm leapfile -is scanned when -.Xr ntpd 8 -processes the -.Cm leapfile directive or when -.Cm ntpd detects that the -.Ar leapfile -has changed. -.Cm ntpd -checks once a day to see if the -.Ar leapfile -has changed. -The -.Xr update\-leap 1update_leapmdoc -script can be run to see if the -.Ar leapfile -should be updated. -.It Ic leapsmearinterval Ar seconds -This EXPERIMENTAL option is only available if -.Xr ntpd 8 -was built with the -.Cm \-\-enable\-leap\-smear -option to the -.Cm configure -script. -It specifies the interval over which a leap second correction will be applied. -Recommended values for this option are between -7200 (2 hours) and 86400 (24 hours). -.Sy DO NOT USE THIS OPTION ON PUBLIC\-ACCESS SERVERS! -See http://bugs.ntp.org/2855 for more information. -.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 -.Fl l -command line option. -.It Xo Ic mru -.Oo -.Cm maxdepth Ar count | Cm maxmem Ar kilobytes | -.Cm mindepth Ar count | Cm maxage Ar seconds | -.Cm initialloc Ar count | Cm initmem Ar kilobytes | -.Cm incalloc Ar count | Cm incmem Ar kilobytes -.Oc -.Xc -Controls size limit of the monitoring facility's Most Recently Used -(MRU) list -of client addresses, which is also used by the -rate control facility. -.Bl -tag -width indent -.It Ic maxdepth Ar count -.It Ic maxmem Ar kilobytes -Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes. -The actual limit will be up to -.Cm incalloc -entries or -.Cm incmem -kilobytes larger. -As with all of the -.Cm mru -options offered in units of entries or kilobytes, if both -.Cm maxdepth -and -.Cm maxmem are used, the last one used controls. -The default is 1024 kilobytes. -.It Cm mindepth Ar count -Lower limit on the MRU list size. -When the MRU list has fewer than -.Cm mindepth -entries, existing entries are never removed to make room for newer ones, -regardless of their age. -The default is 600 entries. -.It Cm maxage Ar seconds -Once the MRU list has -.Cm mindepth -entries and an additional client is to be added to the list, -if the oldest entry was updated more than -.Cm maxage -seconds ago, that entry is removed and its storage is reused. -If the oldest entry was updated more recently the MRU list is grown, -subject to -.Cm maxdepth / moxmem . -The default is 64 seconds. -.It Cm initalloc Ar count -.It Cm initmem Ar kilobytes -Initial memory allocation at the time the monitoringfacility is first enabled, -in terms of the number of entries or kilobytes. -The default is 4 kilobytes. -.It Cm incalloc Ar count -.It Cm incmem Ar kilobytes -Size of additional memory allocations when growing the MRU list, in entries or kilobytes. -The default is 4 kilobytes. -.El -.It Ic nonvolatile Ar threshold -Specify the -.Ar threshold -delta in seconds before an hourly change to the -.Cm driftfile -(frequency file) will be written, with a default value of 1e\-7 (0.1 PPM). -The frequency file is inspected each hour. -If the difference between the current frequency and the last value written -exceeds the threshold, the file is written and the -.Cm threshold -becomes the new threshold value. -If the threshold is not exceeeded, it is reduced by half. -This is intended to reduce the number of file writes -for embedded systems with nonvolatile memory. -.It Ic phone Ar dial ... -This command is used in conjunction with -the ACTS modem driver (type 18) -or the JJY driver (type 40, mode 100 \- 180). -For the ACTS modem driver (type 18), the arguments consist of -a maximum of 10 telephone numbers used to dial USNO, NIST, or European -time service. -For the JJY driver (type 40 mode 100 \- 180), the argument is -one telephone number used to dial the telephone JJY service. -The Hayes command ATDT is normally prepended to the number. -The number can contain other modem control codes as well. -.It Xo Ic reset -.Oo -.Ic allpeers -.Oc -.Oo -.Ic auth -.Oc -.Oo -.Ic ctl -.Oc -.Oo -.Ic io -.Oc -.Oo -.Ic mem -.Oc -.Oo -.Ic sys -.Oc -.Oo -.Ic timer -.Oc -.Xc -Reset one or more groups of counters maintained by -.Cm ntpd -and exposed by -.Cm ntpq -and -.Cm ntpdc . -.It Xo Ic rlimit -.Oo -.Cm memlock Ar Nmegabytes | -.Cm stacksize Ar N4kPages -.Cm filenum Ar Nfiledescriptors -.Oc -.Xc -.Bl -tag -width indent -.It Cm memlock Ar Nmegabytes -Specify the number of megabytes of memory that should be -allocated and locked. -Probably only available under Linux, this option may be useful -when dropping root (the -.Fl i -option). -The default is \-1. --1 means "do not lock the process into memory". -0 means "lock whatever memory the process wants into memory". -.It Cm stacksize Ar N4kPages -Specifies the maximum size of the process stack on systems with the -.Fn mlockall -function. -Defaults to 50 4k pages (200 4k pages in OpenBSD). -.It Cm filenum Ar Nfiledescriptors -Specifies the maximum number of file descriptors ntpd may have open at once. -Defaults to the system default. -.El -.It Ic saveconfigdir Ar directory_path -Specify the directory in which to write configuration snapshots -requested with -.Cm ntpq 's -.Cm saveconfig -command. -If -.Cm saveconfigdir -does not appear in the configuration file, -.Cm saveconfig -requests are rejected by -.Cm ntpd . -.It Ic saveconfig Ar filename -Write the current configuration, including any runtime -modifications given with -.Cm :config -or -.Cm config\-from\-file -to the -.Cm ntpd -host's -.Ar filename -in the -.Cm saveconfigdir . -This command will be rejected unless the -.Cm saveconfigdir -directive appears in -.Cm ntpd 's -configuration file. -.Ar filename -can use -.Xr strftime 3 -format directives to substitute the current date and time, -for example, -.Cm saveconfig\ ntp\-%Y%m%d\-%H%M%S.conf . -The filename used is stored in the system variable -.Cm savedconfig . -Authentication is required. -.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 Cm sysinfo -Display operational summary. -.It Cm sysstats -Show statistics counters maintained in the protocol module. -.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 step | -.Cm stepback Ar stepback | -.Cm stepfwd Ar stepfwd | -.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 stepback Ar stepback -The argument is the step threshold for the backward direction, -which by default is 0.128 s. -It can -be set to any positive number in seconds. -If both the forward and backward step thresholds are set to zero, step -adjustments will never occur. -Note: The kernel time discipline is -disabled if -each direction of step threshold are either -set to zero or greater than .5 second. -.It Cm stepfwd Ar stepfwd -As for stepback, but for the forward direction. -.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 Cm writevar Ar assocID\ name = value [,...] -Write (create or update) the specified variables. -If the -.Cm assocID -is zero, the variablea re from the -system variables -name space, otherwise they are from the -peer variables -name space. -The -.Cm assocID -is required, as the same name can occur in both name spaces. -.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. -.It Cm ttl Ar hop ... -This command specifies a list of TTL values in increasing order. -Up to 8 values can be specified. -In -.Cm manycast -mode these values are used in\-turn in an expanding\-ring search. -The default is eight multiples of 32 starting at 31. -.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 "OPTIONS" -.Bl -tag -.It Fl \-help -Display usage information and exit. -.It Fl \-more\-help -Pass the extended usage information through a pager. -.It Fl \-version Op Brq Ar v|c|n -Output version of program and exit. The default mode is `v', a simple -version. The `c' mode will print copyright information and `n' will -print the full copyright notice. -.El -.Sh "OPTION PRESETS" -Any option that is not marked as \fInot presettable\fP may be preset -by loading values from environment variables named: -.nf - \fBNTP_CONF_\fP or \fBNTP_CONF\fP -.fi -.ad -.Sh "ENVIRONMENT" -See \fBOPTION PRESETS\fP for configuration environment variables. -.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 "EXIT STATUS" -One of the following exit values will be returned: -.Bl -tag -.It 0 " (EXIT_SUCCESS)" -Successful program execution. -.It 1 " (EXIT_FAILURE)" -The operation failed or the command syntax was not valid. -.It 70 " (EX_SOFTWARE)" -libopts had an internal operational error. Please report -it to autogen\-users@lists.sourceforge.net. Thank you. -.El -.Sh "SEE ALSO" -.Xr 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 4) -.%O RFC5905 -.Re -.Sh "AUTHORS" -The University of Delaware and Network Time Foundation -.Sh "COPYRIGHT" -Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved. -This program is released under the terms of the NTP license, . -.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. -.Pp -Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.Sh NOTES -This document was derived from FreeBSD. -.Pp -This manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP -option definitions. diff --git a/usr.sbin/ntp/doc/ntp.keys.5 b/usr.sbin/ntp/doc/ntp.keys.5 deleted file mode 100644 --- a/usr.sbin/ntp/doc/ntp.keys.5 +++ /dev/null @@ -1,174 +0,0 @@ -.Dd August 14 2018 -.Dt NTP_KEYS 5 File Formats -.Os SunOS 5.10 -.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc) -.\" -.\" It has been AutoGen-ed August 14, 2018 at 08:29:18 AM by AutoGen 5.18.5 -.\" From the definitions ntp.keys.def -.\" and the template file agmdoc-file.tpl -.Sh NAME -.Nm ntp.keys -.Nd NTP symmetric key file format - -.Sh NAME -.Nm ntp.keys -.Nd Network Time Protocol symmetric key format -.Sh SYNOPSIS -.Nm -.Op Fl \-option\-name -.Op Fl \-option\-name Ar value -.Pp -All arguments must be options. -.Pp -.Sh DESCRIPTION -This document describes the format of an NTP symmetric key file. -For a description of the use of this type of file, see the -.Qq Authentication Support -section of the -.Xr ntp.conf 5 -page. -.Pp -.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 keys numbered between 1 and 65535 -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 opt_IP_list -.Pp -where -.Ar keyno -is a positive integer (between 1 and 65535), -.Ar type -is the message digest algorithm, -.Ar key -is the key itself, and -.Ar opt_IP_list -is an optional comma\-separated list of IPs -where the -.Ar keyno -should be trusted. -that are allowed to serve time. -Each IP in -.Ar opt_IP_list -may contain an optional -.Cm /subnetbits -specification which identifies the number of bits for -the desired subnet of trust. -If -.Ar opt_IP_list -is empty, -any properly\-authenticated message will be -accepted. -.Pp -The -.Ar key -may be given in a format -controlled by the -.Ar type -field. -The -.Ar type -.Li MD5 -is always supported. -If -.Li ntpd -was built with the OpenSSL library -then any digest library supported by that library may be specified. -However, if compliance with FIPS 140\-2 is required the -.Ar type -must be either -.Li SHA -or -.Li SHA1 . -.Pp -What follows are some key types, and corresponding formats: -.Pp -.Bl -tag -width RMD160 -compact -.It Li MD5 -The key is 1 to 16 printable characters terminated by -an EOL, -whitespace, -or -a -.Li # -(which is the "start of comment" character). -.Pp -.It Li SHA -.It Li SHA1 -.It Li RMD160 -The key is a hex\-encoded ASCII string of 40 characters, -which is truncated as necessary. -.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 "OPTIONS" -.Bl -tag -.It Fl \-help -Display usage information and exit. -.It Fl \-more\-help -Pass the extended usage information through a pager. -.It Fl \-version Op Brq Ar v|c|n -Output version of program and exit. The default mode is `v', a simple -version. The `c' mode will print copyright information and `n' will -print the full copyright notice. -.El -.Sh "OPTION PRESETS" -Any option that is not marked as \fInot presettable\fP may be preset -by loading values from environment variables named: -.nf - \fBNTP_KEYS_\fP or \fBNTP_KEYS\fP -.fi -.ad -.Sh "ENVIRONMENT" -See \fBOPTION PRESETS\fP for configuration environment variables. -.Sh FILES -.Bl -tag -width /etc/ntp.keys -compact -.It Pa /etc/ntp.keys -the default name of the configuration file -.El -.Sh "EXIT STATUS" -One of the following exit values will be returned: -.Bl -tag -.It 0 " (EXIT_SUCCESS)" -Successful program execution. -.It 1 " (EXIT_FAILURE)" -The operation failed or the command syntax was not valid. -.It 70 " (EX_SOFTWARE)" -libopts had an internal operational error. Please report -it to autogen\-users@lists.sourceforge.net. Thank you. -.El -.Sh "SEE ALSO" -.Xr ntp.conf 5 , -.Xr ntpd 8 , -.Xr ntpdate 8 , -.Xr ntpdc 8 , -.Xr sntp 8 -.Sh "AUTHORS" -The University of Delaware and Network Time Foundation -.Sh "COPYRIGHT" -Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved. -This program is released under the terms of the NTP license, . -.Sh "BUGS" -Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.Sh NOTES -This document was derived from FreeBSD. -.Pp -This manual page was \fIAutoGen\fP\-erated from the \fBntp.keys\fP -option definitions. diff --git a/usr.sbin/ntp/doc/ntpd.8 b/usr.sbin/ntp/doc/ntpd.8 deleted file mode 100644 --- a/usr.sbin/ntp/doc/ntpd.8 +++ /dev/null @@ -1,908 +0,0 @@ -.Dd August 14 2018 -.Dt NTPD 8 User Commands -.Os -.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) -.\" -.\" It has been AutoGen-ed August 14, 2018 at 08:29:20 AM by AutoGen 5.18.5 -.\" From the definitions ntpd-opts.def -.\" and the template file agmdoc-cmd.tpl -.Sh NAME -.Nm ntpd -.Nd set clock via Network Time Protocol daemon -.Sh SYNOPSIS -.Nm -.\" Mixture of short (flag) options and long options -.Op Fl flags -.Op Fl flag Op Ar value -.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc -[ ... ] -.Pp -.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, as defined by RFC\-5905, -but also retains compatibility with -version 3, as defined by RFC\-1305, and versions 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 -.Xr umask 2 , -and if zero -.Nm -will set the -.Xr umask 2 -to 022. -.Sh "OPTIONS" -.Bl -tag -.It Fl 4 , Fl \-ipv4 -Force IPv4 DNS name resolution. -This option must not appear in combination with any of the following options: -ipv6. -.sp -Force DNS resolution of following host names on the command line -to the IPv4 namespace. -.It Fl 6 , Fl \-ipv6 -Force IPv6 DNS name resolution. -This option must not appear in combination with any of the following options: -ipv4. -.sp -Force DNS resolution of following host names on the command line -to the IPv6 namespace. -.It Fl a , Fl \-authreq -Require crypto authentication. -This option must not appear in combination with any of the following options: -authnoreq. -.sp -Require cryptographic authentication for broadcast client, -multicast client and symmetric passive associations. -This is the default. -.It Fl A , Fl \-authnoreq -Do not require crypto authentication. -This option must not appear in combination with any of the following options: -authreq. -.sp -Do not require cryptographic authentication for broadcast client, -multicast client and symmetric passive associations. -This is almost never a good idea. -.It Fl b , Fl \-bcastsync -Allow us to sync to broadcast servers. -.sp -.It Fl c Ar string , Fl \-configfile Ns = Ns Ar string -configuration file name. -.sp -The name and path of the configuration file, -\fI/etc/ntp.conf\fP -by default. -.It Fl d , Fl \-debug\-level -Increase debug verbosity level. -This option may appear an unlimited number of times. -.sp -.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number -Set the debug verbosity level. -This option may appear an unlimited number of times. -This option takes an integer number as its argument. -.sp -.It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string -frequency drift file name. -.sp -The name and path of the frequency file, -\fI/etc/ntp.drift\fP -by default. -This is the same operation as the -\fBdriftfile\fP \fIdriftfile\fP -configuration specification in the -\fI/etc/ntp.conf\fP -file. -.It Fl g , Fl \-panicgate -Allow the first adjustment to be Big. -This option may appear an unlimited number of times. -.sp -Normally, -\fBntpd\fP -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, -\fBntpd\fP -will exit with a message to the system log. This option can be used with the -\fB\-q\fP -and -\fB\-x\fP -options. -See the -\fBtinker\fP -configuration file directive for other options. -.It Fl G , Fl \-force\-step\-once -Step any initial offset correction.. -.sp -Normally, -\fBntpd\fP -steps the time if the time offset exceeds the step threshold, -which is 128 ms by default, and otherwise slews the time. -This option forces the initial offset correction to be stepped, -so the highest time accuracy can be achieved quickly. -However, this may also cause the time to be stepped back -so this option must not be used if -applications requiring monotonic time are running. -See the \fBtinker\fP configuration file directive for other options. -.It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string -Jail directory. -.sp -Chroot the server to the directory -\fIjaildir\fP -. -This option also implies that the server attempts to drop root privileges at startup. -You may need to also specify a -\fB\-u\fP -option. -This option is only available if the OS supports adjusting the clock -without full root privileges. -This option is supported under NetBSD (configure with -\fB\-\-enable\-clockctl\fP) or Linux (configure with -\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). -.It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface -Listen on an interface name or address. -This option may appear an unlimited number of times. -.sp -Open the network address given, or all the addresses associated with the -given interface name. This option may appear multiple times. This option -also implies not opening other addresses, except wildcard and localhost. -This option is deprecated. Please consider using the configuration file -\fBinterface\fP command, which is more versatile. -.It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string -path to symmetric keys. -.sp -Specify the name and path of the symmetric key file. -\fI/etc/ntp.keys\fP -is the default. -This is the same operation as the -\fBkeys\fP \fIkeyfile\fP -configuration file directive. -.It Fl l Ar string , Fl \-logfile Ns = Ns Ar string -path to the log file. -.sp -Specify the name and path of the log file. -The default is the system log file. -This is the same operation as the -\fBlogfile\fP \fIlogfile\fP -configuration file directive. -.It Fl L , Fl \-novirtualips -Do not listen to virtual interfaces. -.sp -Do not listen to virtual interfaces, defined as those with -names containing a colon. This option is deprecated. Please -consider using the configuration file \fBinterface\fP command, which -is more versatile. -.It Fl M , Fl \-modifymmtimer -Modify Multimedia Timer (Windows only). -.sp -Set the Windows Multimedia Timer to highest resolution. This -ensures the resolution does not change while ntpd is running, -avoiding timekeeping glitches associated with changes. -.It Fl n , Fl \-nofork -Do not fork. -This option must not appear in combination with any of the following options: -wait\-sync. -.sp -.It Fl N , Fl \-nice -Run at high priority. -.sp -To the extent permitted by the operating system, run -\fBntpd\fP -at the highest priority. -.It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string -path to the PID file. -.sp -Specify the name and path of the file used to record -\fBntpd\fP's -process ID. -This is the same operation as the -\fBpidfile\fP \fIpidfile\fP -configuration file directive. -.It Fl P Ar number , Fl \-priority Ns = Ns Ar number -Process priority. -This option takes an integer number as its argument. -.sp -To the extent permitted by the operating system, run -\fBntpd\fP -at the specified -\fBsched_setscheduler(SCHED_FIFO)\fP -priority. -.It Fl q , Fl \-quit -Set the time and quit. -This option must not appear in combination with any of the following options: -saveconfigquit, wait\-sync. -.sp -\fBntpd\fP -will not daemonize and will exit after the clock is first -synchronized. This behavior mimics that of the -\fBntpdate\fP -program, which will soon be replaced with a shell script. -The -\fB\-g\fP -and -\fB\-x\fP -options can be used with this option. -Note: The kernel time discipline is disabled with this option. -.It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string -Broadcast/propagation delay. -.sp -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 \-saveconfigquit Ns = Ns Ar string -Save parsed configuration and quit. -This option must not appear in combination with any of the following options: -quit, wait\-sync. -.sp -Cause \fBntpd\fP to parse its startup configuration file and save an -equivalent to the given filename and exit. This option was -designed for automated testing. -.It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string -Statistics file location. -.sp -Specify the directory path for files created by the statistics facility. -This is the same operation as the -\fBstatsdir\fP \fIstatsdir\fP -configuration file directive. -.It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey -Trusted key number. -This option may appear an unlimited number of times. -.sp -Add the specified key number to the trusted key list. -.It Fl u Ar string , Fl \-user Ns = Ns Ar string -Run as userid (or userid:groupid). -.sp -Specify a user, and optionally a group, to switch to. -This option is only available if the OS supports adjusting the clock -without full root privileges. -This option is supported under NetBSD (configure with -\fB\-\-enable\-clockctl\fP) or Linux (configure with -\fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP). -.It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number -interval in seconds between scans for new or dropped interfaces. -This option takes an integer number as its argument. -.sp -Give the time in seconds between two scans for new or dropped interfaces. -For systems with routing socket support the scans will be performed shortly after the interface change -has been detected by the system. -Use 0 to disable scanning. 60 seconds is the minimum time between scans. -.It Fl \-var Ns = Ns Ar nvar -make ARG an ntp variable (RW). -This option may appear an unlimited number of times. -.sp -.It Fl \-dvar Ns = Ns Ar ndvar -make ARG an ntp variable (RW|DEF). -This option may appear an unlimited number of times. -.sp -.It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number -Seconds to wait for first clock sync. -This option must not appear in combination with any of the following options: -nofork, quit, saveconfigquit. -This option takes an integer number as its argument. -.sp -If greater than zero, alters \fBntpd\fP's behavior when forking to -daemonize. Instead of exiting with status 0 immediately after -the fork, the parent waits up to the specified number of -seconds for the child to first synchronize the clock. The exit -status is zero (success) if the clock was synchronized, -otherwise it is \fBETIMEDOUT\fP. -This provides the option for a script starting \fBntpd\fP to easily -wait for the first set of the clock before proceeding. -.It Fl x , Fl \-slew -Slew up to 600 seconds. -.sp -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 -\fB\-g\fP -and -\fB\-q\fP -options. -See the -\fBtinker\fP -configuration file directive for other options. -Note: The kernel time discipline is disabled with this option. -.It Fl \-usepcc -Use CPU cycle counter (Windows only). -.sp -Attempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP. -The CPU counter and \fBQueryPerformanceCounter\fP are compared, and if -they have the same frequency, the CPU counter (RDTSC on x86) is -used directly, saving the overhead of a system call. -.It Fl \-pccfreq Ns = Ns Ar string -Force CPU cycle counter use (Windows only). -.sp -Force substitution the CPU counter for \fBQueryPerformanceCounter\fP. -The CPU counter (RDTSC on x86) is used unconditionally with the -given frequency (in Hz). -.It Fl m , Fl \-mdns -Register with mDNS as a NTP server. -.sp -Registers as an NTP server with the local mDNS server which allows -the server to be discovered via mDNS client lookup. -.It Fl \&? , Fl \-help -Display usage information and exit. -.It Fl \&! , Fl \-more\-help -Pass the extended usage information through a pager. -.It Fl \-version Op Brq Ar v|c|n -Output version of program and exit. The default mode is `v', a simple -version. The `c' mode will print copyright information and `n' will -print the full copyright notice. -.El -.Sh "OPTION PRESETS" -Any option that is not marked as \fInot presettable\fP may be preset -by loading values from environment variables named: -.nf - \fBNTPD_\fP or \fBNTPD\fP -.fi -.ad -.Sh USAGE -.Ss "How NTP Operates" -The -.Nm -utility operates by exchanging messages with -one or more configured servers over a range of 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. -This initial delay to set the clock -can be safely and dramatically 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 the default case, if -.Nm -detects that the time on the host -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. -(Reasons for this include there is no TOY chip, -or its battery is dead, or that the TOY chip is just of poor quality.) -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 -(up to 68 years in the past or future \(em -this is a limitation of the NTPv4 protocol). -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 without a valid drift file -on a system with a large intrinsic drift -the error might grow to exceed 128 ms, -which would 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. -There are several solutions, however. -If the -.Fl x -option is included on the command line, the clock will -never be stepped and only slew corrections will be used. -But this choice comes with a cost that -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 -(the host -.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, but -ONLY -when you have permission to do so from the owner of the target host. -.Pp -Finally, -in the past many startup scripts would run -.Xr ntpdate 8 -or -.Xr sntp 8 -to get the system clock close to correct before starting -.Xr ntpd 8 , -but this was never more than a mediocre hack and is no longer needed. -If you are following the instructions in -.Sx "Starting NTP (Best Current Practice)" -and you still need to set the system time before starting -.Nm , -please open a bug report and document what is going on, -and then look at using -.Xr sntp 8 -if you really need to set the clock before starting -.Nm . -.Pp -There is a way to start -.Xr ntpd 8 -that often addresses all of the problems mentioned above. -.Ss "Starting NTP (Best Current Practice)" -First, use the -.Cm iburst -option on your -.Cm server -entries. -.Pp -If you can also keep a good -.Pa ntp.drift -file then -.Xr ntpd 8 -will effectively "warm\-start" and your system's clock will -be stable in under 11 seconds' time. -.Pp -As soon as possible in the startup sequence, start -.Xr ntpd 8 -with at least the -.Fl g -and perhaps the -.Fl N -options. -Then, -start the rest of your "normal" processes. -This will give -.Xr ntpd 8 -as much time as possible to get the system's clock synchronized and stable. -.Pp -Finally, -if you have processes like -.Cm dovecot -or database servers -that require -monotonically\-increasing time, -run -.Xr ntp\-wait 1ntp\-waitmdoc -as late as possible in the boot sequence -(perhaps with the -.Fl v -flag) -and after -.Xr ntp\-wait 1ntp\-waitmdoc -exits successfully -it is as safe as it will ever be to start any process that require -stable time. -.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 -or -.Xr sntp 8 -programs from a -.Xr cron 8 -job at designated -times. -However, these programs do not have the crafted signal -processing, error checking or 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 will 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 "ENVIRONMENT" -See \fBOPTION PRESETS\fP for configuration environment variables. -.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 "EXIT STATUS" -One of the following exit values will be returned: -.Bl -tag -.It 0 " (EXIT_SUCCESS)" -Successful program execution. -.It 1 " (EXIT_FAILURE)" -The operation failed or the command syntax was not valid. -.It 70 " (EX_SOFTWARE)" -libopts had an internal operational error. Please report -it to autogen\-users@lists.sourceforge.net. Thank you. -.El -.Sh "SEE ALSO" -.Xr ntp.conf 5 , -.Xr ntpdate 8 , -.Xr ntpdc 8 , -.Xr ntpq 8 , -.Xr sntp 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 -.Rs -.%A David L. Mills -.%A J. Martin, Ed. -.%A J. Burbank -.%A W. Kasch -.%T Network Time Protocol Version 4: Protocol and Algorithms Specification -.%O RFC5905 -.Re -.Rs -.%A David L. Mills -.%A B. Haberman, Ed. -.%T Network Time Protocol Version 4: Autokey Specification -.%O RFC5906 -.Re -.Rs -.%A H. Gerstung -.%A C. Elliott -.%A B. Haberman, Ed. -.%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4) -.%O RFC5907 -.Re -.Rs -.%A R. Gayraud -.%A B. Lourdelet -.%T Network Time Protocol (NTP) Server Option for DHCPv6 -.%O RFC5908 -.Re -.Sh "AUTHORS" -The University of Delaware and Network Time Foundation -.Sh "COPYRIGHT" -Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved. -This program is released under the terms of the NTP license, . -.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. -.Pp -Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.Sh NOTES -Portions of this document came from FreeBSD. -.Pp -This manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP -option definitions. diff --git a/usr.sbin/ntp/doc/ntpdc.8 b/usr.sbin/ntp/doc/ntpdc.8 deleted file mode 100644 --- a/usr.sbin/ntp/doc/ntpdc.8 +++ /dev/null @@ -1,809 +0,0 @@ -.Dd August 14 2018 -.Dt NTPDC 8 User Commands -.Os -.\" EDIT THIS FILE WITH CAUTION (ntpdc-opts.mdoc) -.\" -.\" It has been AutoGen-ed August 14, 2018 at 08:29:43 AM by AutoGen 5.18.5 -.\" From the definitions ntpdc-opts.def -.\" and the template file agmdoc-cmd.tpl -.Sh NAME -.Nm ntpdc -.Nd vendor-specific NTPD control program -.Sh SYNOPSIS -.Nm -.\" Mixture of short (flag) options and long options -.Op Fl flags -.Op Fl flag Op Ar value -.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc -[ host ...] -.Pp -.Sh DESCRIPTION -.Nm -is deprecated. -Please use -.Xr ntpq 8 instead \- it can do everything -.Nm -used to do, and it does so using a much more sane interface. -.Pp -.Nm -is a utility program used to query -.Xr ntpd 8 -about its -current state and to request changes in that state. -It uses NTP mode 7 control message formats described in the source code. -The program may -be run either in interactive mode or controlled using command line -arguments. -Extensive state and statistics information is available -through the -.Nm -interface. -In addition, nearly all the -configuration options which can be specified at startup using -ntpd's configuration file may also be specified at run time using -.Nm . -.Sh "OPTIONS" -.Bl -tag -.It Fl 4 , Fl \-ipv4 -Force IPv4 DNS name resolution. -This option must not appear in combination with any of the following options: -ipv6. -.sp -Force DNS resolution of following host names on the command line -to the IPv4 namespace. -.It Fl 6 , Fl \-ipv6 -Force IPv6 DNS name resolution. -This option must not appear in combination with any of the following options: -ipv4. -.sp -Force DNS resolution of following host names on the command line -to the IPv6 namespace. -.It Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd -run a command and exit. -This option may appear an unlimited number of times. -.sp -The following argument is interpreted as an interactive format command -and is added to the list of commands to be executed on the specified -host(s). -.It Fl d , Fl \-debug\-level -Increase debug verbosity level. -This option may appear an unlimited number of times. -.sp -.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number -Set the debug verbosity level. -This option may appear an unlimited number of times. -This option takes an integer number as its argument. -.sp -.It Fl i , Fl \-interactive -Force ntpq to operate in interactive mode. -This option must not appear in combination with any of the following options: -command, listpeers, peers, showpeers. -.sp -Force ntpq to operate in interactive mode. Prompts will be written -to the standard output and commands read from the standard input. -.It Fl l , Fl \-listpeers -Print a list of the peers. -This option must not appear in combination with any of the following options: -command. -.sp -Print a list of the peers known to the server as well as a summary of -their state. This is equivalent to the 'listpeers' interactive command. -.It Fl n , Fl \-numeric -numeric host addresses. -.sp -Output all host addresses in dotted\-quad numeric format rather than -converting to the canonical host names. -.It Fl p , Fl \-peers -Print a list of the peers. -This option must not appear in combination with any of the following options: -command. -.sp -Print a list of the peers known to the server as well as a summary -of their state. This is equivalent to the 'peers' interactive command. -.It Fl s , Fl \-showpeers -Show a list of the peers. -This option must not appear in combination with any of the following options: -command. -.sp -Print a list of the peers known to the server as well as a summary -of their state. This is equivalent to the 'dmpeers' interactive command. -.It Fl \&? , Fl \-help -Display usage information and exit. -.It Fl \&! , Fl \-more\-help -Pass the extended usage information through a pager. -.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc -Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP -configuration file listed in the \fBOPTION PRESETS\fP section, below. -The command will exit after updating the config file. -.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts -Load options from \fIcfgfile\fP. -The \fIno\-load\-opts\fP form will disable the loading -of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early, -out of order. -.It Fl \-version Op Brq Ar v|c|n -Output version of program and exit. The default mode is `v', a simple -version. The `c' mode will print copyright information and `n' will -print the full copyright notice. -.El -.Sh "OPTION PRESETS" -Any option that is not marked as \fInot presettable\fP may be preset -by loading values from configuration ("RC" or ".INI") file(s) and values from -environment variables named: -.nf - \fBNTPDC_\fP or \fBNTPDC\fP -.fi -.ad -The environmental presets take precedence (are processed later than) -the configuration files. -The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". -If any of these are directories, then the file \fI.ntprc\fP -is searched for within those directories. -.Sh USAGE -If one or more request options are included on the command line -when -.Nm -is executed, each of the requests will be sent -to the NTP servers running on each of the hosts given as command -line arguments, or on localhost by default. -If no request options -are given, -.Nm -will attempt to read commands from the -standard input and execute these on the NTP server running on the -first host given on the command line, again defaulting to localhost -when no other host is specified. -The -.Nm -utility will prompt for -commands if the standard input is a terminal device. -.Pp -The -.Nm -utility uses NTP mode 7 packets to communicate with the -NTP server, and hence can be used to query any compatible server on -the network which permits it. -Note that since NTP is a UDP protocol -this communication will be somewhat unreliable, especially over -large distances in terms of network topology. -The -.Nm -utility makes -no attempt to retransmit requests, and will time requests out if -the remote host is not heard from within a suitable timeout -time. -.Pp -The operation of -.Nm -are specific to the particular -implementation of the -.Xr ntpd 8 -daemon and can be expected to -work only with this and maybe some previous versions of the daemon. -Requests from a remote -.Nm -utility which affect the -state of the local server must be authenticated, which requires -both the remote program and local server share a common key and key -identifier. -.Pp -Note that in contexts where a host name is expected, a -.Fl 4 -qualifier preceding the host name forces DNS resolution to the IPv4 namespace, -while a -.Fl 6 -qualifier forces DNS resolution to the IPv6 namespace. -Specifying a command line option other than -.Fl i -or -.Fl n -will cause the specified query (queries) to be sent to -the indicated host(s) immediately. -Otherwise, -.Nm -will -attempt to read interactive format commands from the standard -input. -.Ss "Interactive Commands" -Interactive format commands consist of a keyword followed by zero -to four arguments. -Only enough characters of the full keyword to -uniquely identify the command need be typed. -The output of a -command is normally sent to the standard output, but optionally the -output of individual commands may be sent to a file by appending a -.Ql \&> , -followed by a file name, to the command line. -.Pp -A number of interactive format commands are executed entirely -within the -.Nm -utility itself and do not result in NTP -mode 7 requests being sent to a server. -These are described -following. -.Bl -tag -width indent -.It Ic \&? Ar command_keyword -.It Ic help Ar command_keyword -A -.Sq Ic \&? -will print a list of all the command -keywords known to this incarnation of -.Nm . -A -.Sq Ic \&? -followed by a command keyword will print function and usage -information about the command. -This command is probably a better -source of information about -.Xr ntpq 8 -than this manual -page. -.It Ic delay Ar milliseconds -Specify a time interval to be added to timestamps included in -requests which require authentication. -This is used to enable -(unreliable) server reconfiguration over long delay network paths -or between machines whose clocks are unsynchronized. -Actually the -server does not now require timestamps in authenticated requests, -so this command may be obsolete. -.It Ic host Ar hostname -Set the host to which future queries will be sent. -Hostname may -be either a host name or a numeric address. -.It Ic hostnames Op Cm yes | Cm no -If -.Cm yes -is specified, host names are printed in -information displays. -If -.Cm no -is specified, numeric -addresses are printed instead. -The default is -.Cm yes , -unless -modified using the command line -.Fl n -switch. -.It Ic keyid Ar keyid -This command allows the specification of a key number to be -used to authenticate configuration requests. -This must correspond -to a key number the server has been configured to use for this -purpose. -.It Ic quit -Exit -.Nm . -.It Ic passwd -This command prompts you to type in a password (which will not -be echoed) which will be used to authenticate configuration -requests. -The password must correspond to the key configured for -use by the NTP server for this purpose if such requests are to be -successful. -.It Ic timeout Ar milliseconds -Specify a timeout period for responses to server queries. -The -default is about 8000 milliseconds. -Note that since -.Nm -retries each query once after a timeout, the total waiting time for -a timeout will be twice the timeout value set. -.El -.Ss "Control Message Commands" -Query commands result in NTP mode 7 packets containing requests for -information being sent to the server. -These are read\-only commands -in that they make no modification of the server configuration -state. -.Bl -tag -width indent -.It Ic listpeers -Obtains and prints a brief list of the peers for which the -server is maintaining state. -These should include all configured -peer associations as well as those peers whose stratum is such that -they are considered by the server to be possible future -synchronization candidates. -.It Ic peers -Obtains a list of peers for which the server is maintaining -state, along with a summary of that state. -Summary information -includes the address of the remote peer, the local interface -address (0.0.0.0 if a local address has yet to be determined), the -stratum of the remote peer (a stratum of 16 indicates the remote -peer is unsynchronized), the polling interval, in seconds, the -reachability register, in octal, and the current estimated delay, -offset and dispersion of the peer, all in seconds. -.Pp -The character in the left margin indicates the mode this peer -entry is operating in. -A -.Ql \&+ -denotes symmetric active, a -.Ql \&\- -indicates symmetric passive, a -.Ql \&= -means the -remote server is being polled in client mode, a -.Ql \&^ -indicates that the server is broadcasting to this address, a -.Ql \&~ -denotes that the remote peer is sending broadcasts and a -.Ql \&~ -denotes that the remote peer is sending broadcasts and a -.Ql \&* -marks the peer the server is currently synchronizing -to. -.Pp -The contents of the host field may be one of four forms. -It may -be a host name, an IP address, a reference clock implementation -name with its parameter or -.Fn REFCLK "implementation_number" "parameter" . -On -.Ic hostnames -.Cm no -only IP\-addresses -will be displayed. -.It Ic dmpeers -A slightly different peer summary list. -Identical to the output -of the -.Ic peers -command, except for the character in the -leftmost column. -Characters only appear beside peers which were -included in the final stage of the clock selection algorithm. -A -.Ql \&. -indicates that this peer was cast off in the falseticker -detection, while a -.Ql \&+ -indicates that the peer made it -through. -A -.Ql \&* -denotes the peer the server is currently -synchronizing with. -.It Ic showpeer Ar peer_address Oo Ar ... Oc -Shows a detailed display of the current peer variables for one -or more peers. -Most of these values are described in the NTP -Version 2 specification. -.It Ic pstats Ar peer_address Oo Ar ... Oc -Show per\-peer statistic counters associated with the specified -peer(s). -.It Ic clockstat Ar clock_peer_address Oo Ar ... Oc -Obtain and print information concerning a peer clock. -The -values obtained provide information on the setting of fudge factors -and other clock performance information. -.It Ic kerninfo -Obtain and print kernel phase\-lock loop operating parameters. -This information is available only if the kernel has been specially -modified for a precision timekeeping function. -.It Ic loopinfo Op Cm oneline | Cm multiline -Print the values of selected loop filter variables. -The loop -filter is the part of NTP which deals with adjusting the local -system clock. -The -.Sq offset -is the last offset given to the -loop filter by the packet processing code. -The -.Sq frequency -is the frequency error of the local clock in parts\-per\-million -(ppm). -The -.Sq time_const -controls the stiffness of the -phase\-lock loop and thus the speed at which it can adapt to -oscillator drift. -The -.Sq watchdog timer -value is the number -of seconds which have elapsed since the last sample offset was -given to the loop filter. -The -.Cm oneline -and -.Cm multiline -options specify the format in which this -information is to be printed, with -.Cm multiline -as the -default. -.It Ic sysinfo -Print a variety of system state variables, i.e., state related -to the local server. -All except the last four lines are described -in the NTP Version 3 specification, RFC\-1305. -.Pp -The -.Sq system flags -show various system flags, some of -which can be set and cleared by the -.Ic enable -and -.Ic disable -configuration commands, respectively. -These are -the -.Cm auth , -.Cm bclient , -.Cm monitor , -.Cm pll , -.Cm pps -and -.Cm stats -flags. -See the -.Xr ntpd 8 -documentation for the meaning of these flags. -There -are two additional flags which are read only, the -.Cm kernel_pll -and -.Cm kernel_pps . -These flags indicate -the synchronization status when the precision time kernel -modifications are in use. -The -.Sq kernel_pll -indicates that -the local clock is being disciplined by the kernel, while the -.Sq kernel_pps -indicates the kernel discipline is provided by the PPS -signal. -.Pp -The -.Sq stability -is the residual frequency error remaining -after the system frequency correction is applied and is intended for -maintenance and debugging. -In most architectures, this value will -initially decrease from as high as 500 ppm to a nominal value in -the range .01 to 0.1 ppm. -If it remains high for some time after -starting the daemon, something may be wrong with the local clock, -or the value of the kernel variable -.Va kern.clockrate.tick -may be -incorrect. -.Pp -The -.Sq broadcastdelay -shows the default broadcast delay, -as set by the -.Ic broadcastdelay -configuration command. -.Pp -The -.Sq authdelay -shows the default authentication delay, -as set by the -.Ic authdelay -configuration command. -.It Ic sysstats -Print statistics counters maintained in the protocol -module. -.It Ic memstats -Print statistics counters related to memory allocation -code. -.It Ic iostats -Print statistics counters maintained in the input\-output -module. -.It Ic timerstats -Print statistics counters maintained in the timer/event queue -support code. -.It Ic reslist -Obtain and print the server's restriction list. -This list is -(usually) printed in sorted order and may help to understand how -the restrictions are applied. -.It Ic monlist Op Ar version -Obtain and print traffic counts collected and maintained by the -monitor facility. -The version number should not normally need to be -specified. -.It Ic clkbug Ar clock_peer_address Oo Ar ... Oc -Obtain debugging information for a reference clock driver. -This -information is provided only by some clock drivers and is mostly -undecodable without a copy of the driver source in hand. -.El -.Ss "Runtime Configuration Requests" -All requests which cause state changes in the server are -authenticated by the server using a configured NTP key (the -facility can also be disabled by the server by not configuring a -key). -The key number and the corresponding key must also be made -known to -.Nm . -This can be done using the -.Ic keyid -and -.Ic passwd -commands, the latter of which will prompt at the terminal for a -password to use as the encryption key. -You will also be prompted -automatically for both the key number and password the first time a -command which would result in an authenticated request to the -server is given. -Authentication not only provides verification that -the requester has permission to make such changes, but also gives -an extra degree of protection again transmission errors. -.Pp -Authenticated requests always include a timestamp in the packet -data, which is included in the computation of the authentication -code. -This timestamp is compared by the server to its receive time -stamp. -If they differ by more than a small amount the request is -rejected. -This is done for two reasons. -First, it makes simple -replay attacks on the server, by someone who might be able to -overhear traffic on your LAN, much more difficult. -Second, it makes -it more difficult to request configuration changes to your server -from topologically remote hosts. -While the reconfiguration facility -will work well with a server on the local host, and may work -adequately between time\-synchronized hosts on the same LAN, it will -work very poorly for more distant hosts. -As such, if reasonable -passwords are chosen, care is taken in the distribution and -protection of keys and appropriate source address restrictions are -applied, the run time reconfiguration facility should provide an -adequate level of security. -.Pp -The following commands all make authenticated requests. -.Bl -tag -width indent -.It Xo Ic addpeer Ar peer_address -.Op Ar keyid -.Op Ar version -.Op Cm prefer -.Xc -Add a configured peer association at the given address and -operating in symmetric active mode. -Note that an existing -association with the same peer may be deleted when this command is -executed, or may simply be converted to conform to the new -configuration, as appropriate. -If the optional -.Ar keyid -is a -nonzero integer, all outgoing packets to the remote server will -have an authentication field attached encrypted with this key. -If -the value is 0 (or not given) no authentication will be done. -The -.Ar version -can be 1, 2 or 3 and defaults to 3. -The -.Cm prefer -keyword indicates a preferred peer (and thus will -be used primarily for clock synchronisation if possible). -The -preferred peer also determines the validity of the PPS signal \- if -the preferred peer is suitable for synchronisation so is the PPS -signal. -.It Xo Ic addserver Ar peer_address -.Op Ar keyid -.Op Ar version -.Op Cm prefer -.Xc -Identical to the addpeer command, except that the operating -mode is client. -.It Xo Ic broadcast Ar peer_address -.Op Ar keyid -.Op Ar version -.Op Cm prefer -.Xc -Identical to the addpeer command, except that the operating -mode is broadcast. -In this case a valid key identifier and key are -required. -The -.Ar peer_address -parameter can be the broadcast -address of the local network or a multicast group address assigned -to NTP. -If a multicast address, a multicast\-capable kernel is -required. -.It Ic unconfig Ar peer_address Oo Ar ... Oc -This command causes the configured bit to be removed from the -specified peer(s). -In many cases this will cause the peer -association to be deleted. -When appropriate, however, the -association may persist in an unconfigured mode if the remote peer -is willing to continue on in this fashion. -.It Xo Ic fudge Ar peer_address -.Op Cm time1 -.Op Cm time2 -.Op Ar stratum -.Op Ar refid -.Xc -This command provides a way to set certain data for a reference -clock. -See the source listing for further information. -.It Xo Ic enable -.Oo -.Cm auth | Cm bclient | -.Cm calibrate | Cm kernel | -.Cm monitor | Cm ntp | -.Cm pps | Cm stats -.Oc -.Xc -.It Xo Ic disable -.Oo -.Cm auth | Cm bclient | -.Cm calibrate | Cm kernel | -.Cm monitor | Cm ntp | -.Cm pps | Cm stats -.Oc -.Xc -These commands operate in the same way as the -.Ic enable -and -.Ic disable -configuration file commands of -.Xr ntpd 8 . -.Bl -tag -width indent -.It Cm auth -Enables the server to synchronize with unconfigured peers only -if the peer has been correctly authenticated using either public key -or private key cryptography. -The default for this flag is enable. -.It Cm bclient -Enables the server to listen for a message from a broadcast or -multicast server, as in the multicastclient command with -default address. -The default for this flag is disable. -.It Cm calibrate -Enables the calibrate feature for reference clocks. -The default for this flag is disable. -.It Cm kernel -Enables the kernel time discipline, if available. -The default for this flag is enable if support is available, otherwise disable. -.It Cm monitor -Enables the monitoring facility. -See the documentation here about the -.Cm monlist -command or further information. -The default for this flag is enable. -.It Cm ntp -Enables time and frequency discipline. -In effect, this switch opens and closes the feedback loop, -which is useful for testing. -The default for this flag is enable. -.It Cm pps -Enables the pulse\-per\-second (PPS) signal when frequency -and time is disciplined by the precision time kernel modifications. -See the -.Qq A Kernel Model for Precision Timekeeping -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) -page for further information. -The default for this flag is disable. -.It Cm stats -Enables the statistics facility. -See the -.Sx Monitoring Options -section of -.Xr ntp.conf 5 -for further information. -The default for this flag is disable. -.El -.It Xo Ic restrict Ar address Ar mask -.Ar flag Oo Ar ... Oc -.Xc -This command operates in the same way as the -.Ic restrict -configuration file commands of -.Xr ntpd 8 . -.It Xo Ic unrestrict Ar address Ar mask -.Ar flag Oo Ar ... Oc -.Xc -Unrestrict the matching entry from the restrict list. -.It Xo Ic delrestrict Ar address Ar mask -.Op Cm ntpport -.Xc -Delete the matching entry from the restrict list. -.It Ic readkeys -Causes the current set of authentication keys to be purged and -a new set to be obtained by rereading the keys file (which must -have been specified in the -.Xr ntpd 8 -configuration file). -This -allows encryption keys to be changed without restarting the -server. -.It Ic trustedkey Ar keyid Oo Ar ... Oc -.It Ic untrustedkey Ar keyid Oo Ar ... Oc -These commands operate in the same way as the -.Ic trustedkey -and -.Ic untrustedkey -configuration file -commands of -.Xr ntpd 8 . -.It Ic authinfo -Returns information concerning the authentication module, -including known keys and counts of encryptions and decryptions -which have been done. -.It Ic traps -Display the traps set in the server. -See the source listing for -further information. -.It Xo Ic addtrap Ar address -.Op Ar port -.Op Ar interface -.Xc -Set a trap for asynchronous messages. -See the source listing -for further information. -.It Xo Ic clrtrap Ar address -.Op Ar port -.Op Ar interface -.Xc -Clear a trap for asynchronous messages. -See the source listing -for further information. -.It Ic reset -Clear the statistics counters in various modules of the server. -See the source listing for further information. -.El -.Sh "ENVIRONMENT" -See \fBOPTION PRESETS\fP for configuration environment variables. -.Sh "FILES" -See \fBOPTION PRESETS\fP for configuration files. -.Sh "EXIT STATUS" -One of the following exit values will be returned: -.Bl -tag -.It 0 " (EXIT_SUCCESS)" -Successful program execution. -.It 1 " (EXIT_FAILURE)" -The operation failed or the command syntax was not valid. -.It 66 " (EX_NOINPUT)" -A specified configuration file could not be loaded. -.It 70 " (EX_SOFTWARE)" -libopts had an internal operational error. Please report -it to autogen\-users@lists.sourceforge.net. Thank you. -.El -.Sh "SEE ALSO" -.Xr ntp.conf 5 , -.Xr ntpd 8 -.Rs -.%A David L. Mills -.%T Network Time Protocol (Version 3) -.%O RFC1305 -.Re -.Sh AUTHORS -The formatting directives in this document came from FreeBSD. -.Sh "COPYRIGHT" -Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved. -This program is released under the terms of the NTP license, . -.Sh BUGS -The -.Nm -utility is a crude hack. -Much of the information it shows is -deadly boring and could only be loved by its implementer. -The -program was designed so that new (and temporary) features were easy -to hack in, at great expense to the program's ease of use. -Despite -this, the program is occasionally useful. -.Pp -Please report bugs to http://bugs.ntp.org . -.Pp -Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.Sh "NOTES" -This manual page was \fIAutoGen\fP\-erated from the \fBntpdc\fP -option definitions. diff --git a/usr.sbin/ntp/doc/ntpq.8 b/usr.sbin/ntp/doc/ntpq.8 deleted file mode 100644 --- a/usr.sbin/ntp/doc/ntpq.8 +++ /dev/null @@ -1,1055 +0,0 @@ -.Dd August 14 2018 -.Dt NTPQ 8 User Commands -.Os -.\" EDIT THIS FILE WITH CAUTION (ntpq-opts.mdoc) -.\" -.\" It has been AutoGen-ed August 14, 2018 at 08:30:05 AM by AutoGen 5.18.5 -.\" From the definitions ntpq-opts.def -.\" and the template file agmdoc-cmd.tpl -.Sh NAME -.Nm ntpq -.Nd query Network Time Protocol servers -.Sh SYNOPSIS -.Nm -.\" Mixture of short (flag) options and long options -.Op Fl flags -.Op Fl flag Op Ar value -.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc -[ host ...] -.Pp -.Sh DESCRIPTION -.Pp -The -.Nm -utility program is used to query NTP servers to monitor NTP operations -and performance, requesting -information about current state and/or changes in that state. -The program may be run either in interactive mode or controlled using -command line arguments. -Requests to read and write arbitrary -variables can be assembled, with raw and pretty\-printed output -options being available. -The -.Nm -utility can also obtain and print a -list of peers in a common format by sending multiple queries to the -server. -.Pp -If one or more request options is included on the command line -when -.Nm -is executed, each of the requests will be sent -to the NTP servers running on each of the hosts given as command -line arguments, or on 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 -.Nm -uses NTP mode 6 packets to communicate with the -NTP server, and hence can be used to query any compatible server on -the network which permits it. -Note that since NTP is a UDP protocol -this communication will be somewhat unreliable, especially over -large distances in terms of network topology. -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 -Note that in contexts where a host name is expected, a -.Fl 4 -qualifier preceding the host name forces resolution to the IPv4 -namespace, while a -.Fl 6 -qualifier forces resolution to the IPv6 namespace. -For examples and usage, see the -.Dq NTP Debugging Techniques -page. -.Pp -Specifying a -command line option other than -.Fl i -or -.Fl n -will -cause the specified query (queries) to be sent to the indicated -host(s) immediately. -Otherwise, -.Nm -will attempt to read -interactive format commands from the standard input. -.Ss "Internal Commands" -.Pp -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. -.Pp -A -number of interactive format commands are executed entirely within -the -.Nm -utility itself and do not result in NTP -requests being sent to a server. -These are described following. -.Bl -tag -width "help [command]" -compact -offset indent -.It Ic ? Op Ar command -.It Ic help Op Ar command -A -.Ql \&? -by itself will print a list of all the commands -known to -.Nm . -A -.Ql \&? -followed by a command name will print function and usage -information about the command. -.It Ic addvars Ar name Ns Oo \&= Ns Ar value Oc Ns Op ,... -.It Ic rmvars Ar name Ns Op ,... -.It Ic clearvars -.It Ic showvars -The arguments to this command consist of a list of -items of the form -.Ar name Ns Op \&= Ns Ar value , -where the -.No \&= Ns Ar 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 -messages can be assembled, and displayed or set using the -.Ic readlist -and -.Ic writelist -commands described below. -The -.Ic addvars -command allows variables and their optional values to be added to -the list. -If more than one variable is to be added, the list should -be comma\-separated and not contain white space. -The -.Ic rmvars -command can be used to remove individual variables from the list, -while the -.Ic clearvars -command removes all variables from the -list. -The -.Ic showvars -command displays the current list of optional variables. -.It Ic authenticate Op Cm yes Ns | Ns Cm no -Normally -.Nm -does not authenticate requests unless -they are write requests. -The command -.Ic authenticate Cm yes -causes -.Nm -to send authentication with all requests it -makes. -Authenticated requests causes some servers to handle -requests slightly differently. -The command -.Ic authenticate -causes -.Nm -to display whether or not -it is currently authenticating requests. -.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 -could not decode completely are -marked with a trailing -.Ql \&? . -.It Ic debug Op Cm more Ns | Ns Cm less Ns | Ns Cm off -With no argument, displays the current debug level. -Otherwise, the debugging level is changed as indicated. -.It Ic delay Op 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. -Without any arguments, displays the current delay. -.It Ic drefid Op Cm hash Ns | Ns Cm ipv4 -Display refids as IPv4 or hash. -Without any arguments, displays whether refids are shown as IPv4 -addresses or hashes. -.It Ic exit -Exit -.Nm . -.It Ic host Op Ar name -Set the host to which future queries will be sent. -The -.Ar name -may be either a host name or a numeric address. -Without any arguments, displays the current host. -.It Ic hostnames Op Cm yes Ns | Ns 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. -Without any arguments, displays whether host names or numeric addresses -are shown. -.It Ic keyid Op Ar keyid -This command allows the specification of a key number to be -used to authenticate configuration requests. -This must correspond -to the -.Cm controlkey -key number the server has been configured to use for this -purpose. -Without any arguments, displays the current -.Ar keyid . -.It Ic keytype Op Ar digest -Specify the digest algorithm to use for authenticating requests, with default -.Cm MD5 . -If -.Nm -was built with OpenSSL support, and OpenSSL is installed, -.Ar digest -can be any message digest algorithm supported by OpenSSL. -If no argument is given, the current -.Ic keytype Ar digest -algorithm used is displayed. -.It Ic ntpversion Op Cm 1 Ns | Ns Cm 2 Ns | Ns Cm 3 Ns | Ns Cm 4 -Sets the NTP version number which -.Nm -claims in -packets. -Defaults to 3, and note that mode 6 control messages (and -modes, for that matter) didn't exist in NTP version 1. -There appear -to be no servers left which demand version 1. -With no argument, displays the current NTP version that will be used -when communicating with servers. -.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 poll Oo Ar n Oc Op Cm verbose -Poll an NTP server in client mode -.Ar n -times. -Poll not implemented yet. -.It Ic quit -Exit -.Nm . -.It Ic raw -Causes all output from query commands is printed as received -from the remote server. -The only formating/interpretation done on -the data is to transform nonascii data into a printable (but barely -understandable) form. -.It Ic timeout Op Ar milliseconds -Specify a timeout period for responses to server queries. -The -default is about 5000 milliseconds. -Without any arguments, displays the current timeout period. -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. -.It Ic version -Display the version of the -.Nm -program. -.El -.Ss "Control Message Commands" -Association ids are used to identify system, peer and clock variables. -System variables are assigned an association id of zero and system name -space, while each association is assigned a nonzero association id and -peer namespace. -Most control commands send a single message to the server and expect a -single response message. -The exceptions are the -.Ic peers -command, which sends a series of messages, -and the -.Ic mreadlist -and -.Ic mreadvar -commands, which iterate over a range of associations. -.Bl -tag -width "something" -compact -offset indent -.It Ic apeers -Display a list of peers in the form: -.Dl [tally]remote refid assid st t when pool reach delay offset jitter -where the output is just like the -.Ic peers -command except that the -.Cm refid -is displayed in hex format and the association number is also displayed. -.It Ic associations -Display a list of mobilized associations in the form: -.Dl ind assid status conf reach auth condition last_event cnt -.Bl -column -offset indent ".Sy Variable" "see the select field of the peer status word" -.It Sy Variable Ta Sy Description -.It Cm ind Ta index on this list -.It Cm assid Ta association id -.It Cm status Ta peer status word -.It Cm conf Ta Cm yes : No persistent, Cm no : No ephemeral -.It Cm reach Ta Cm yes : No reachable, Cm no : No unreachable -.It Cm auth Ta Cm ok , Cm yes , Cm bad No and Cm none -.It Cm condition Ta selection status \&(see the Cm select No field of the peer status word\&) -.It Cm last_event Ta event report \&(see the Cm event No field of the peer status word\&) -.It Cm cnt Ta event count \&(see the Cm count No field of the peer status word\&) -.El -.It Ic authinfo -Display the authentication statistics counters: -time since reset, stored keys, free keys, key lookups, keys not found, -uncached keys, expired keys, encryptions, decryptions. -.It Ic clocklist Op Ar associd -.It Ic cl Op Ar associd -Display all clock variables in the variable list for those associations -supporting a reference clock. -.It Ic clockvar Oo Ar associd Oc Oo Ar name Ns Oo \&= Ns Ar value Oc Ns Oc Ns Op ,... -.It Ic cv Oo Ar associd Oc Oo Ar name Ns Oo \&= Ns Ar value Oc Ns Oc Ns Op ,... -Display a list of clock variables for those associations supporting a -reference clock. -.It Ic :config Ar "configuration command line" -Send the remainder of the command line, including whitespace, to the -server as a run\-time configuration command in the same format as a line -in the configuration file. -This command is experimental until further notice and clarification. -Authentication is of course required. -.It Ic config\-from\-file Ar filename -Send each line of -.Ar filename -to the server as run\-time configuration commands in the same format as -lines in the configuration file. -This command is experimental until further notice and clarification. -Authentication is required. -.It Ic ifstats -Display status and statistics counters for each local network interface address: -interface number, interface name and address or broadcast, drop, flag, -ttl, mc, received, sent, send failed, peers, uptime. -Authentication is required. -.It Ic iostats -Display network and reference clock I/O statistics: -time since reset, receive buffers, free receive buffers, used receive buffers, -low water refills, dropped packets, ignored packets, received packets, -packets sent, packet send failures, input wakeups, useful input wakeups. -.It Ic kerninfo -Display kernel loop and PPS statistics: -associd, status, pll offset, pll frequency, maximum error, -estimated error, kernel status, pll time constant, precision, -frequency tolerance, pps frequency, pps stability, pps jitter, -calibration interval, calibration cycles, jitter exceeded, -stability exceeded, calibration errors. -As with other ntpq output, times are in milliseconds; very small values -may be shown as exponentials. -The precision value displayed is in milliseconds as well, unlike the -precision system variable. -.It Ic lassociations -Perform the same function as the associations command, except display -mobilized and unmobilized associations, including all clients. -.It Ic lopeers Op Fl 4 Ns | Ns Fl 6 -Display a list of all peers and clients showing -.Cm dstadr -(associated with the given IP version). -.It Ic lpassociations -Display the last obtained list of associations, including all clients. -.It Ic lpeers Op Fl 4 Ns | Ns Fl 6 -Display a list of all peers and clients (associated with the given IP version). -.It Ic monstats -Display monitor facility status, statistics, and limits: -enabled, addresses, peak addresses, maximum addresses, -reclaim above count, reclaim older than, kilobytes, maximum kilobytes. -.It Ic mreadlist Ar associdlo Ar associdhi -.It Ic mrl Ar associdlo Ar associdhi -Perform the same function as the -.Ic readlist -command for a range of association ids. -.It Ic mreadvar Ar associdlo Ar associdhi Oo Ar name Oc Ns Op ,... -This range may be determined from the list displayed by any -command showing associations. -.It Ic mrv Ar associdlo Ar associdhi Oo Ar name Oc Ns Op ,... -Perform the same function as the -.Ic readvar -command for a range of association ids. -This range may be determined from the list displayed by any -command showing associations. -.It Xo Ic mrulist Oo Cm limited | Cm kod | Cm mincount Ns \&= Ns Ar count | -.Cm laddr Ns \&= Ns Ar localaddr | Cm sort Ns \&= Ns Oo \&\- Oc Ns Ar sortorder | -.Cm resany Ns \&= Ns Ar hexmask | Cm resall Ns \&= Ns Ar hexmask Oc -.Xc -Display traffic counts of the most recently seen source addresses -collected and maintained by the monitor facility. -With the exception of -.Cm sort Ns \&= Ns Oo \&\- Oc Ns Ar sortorder , -the options filter the list returned by -.Xr ntpd 8 . -The -.Cm limited -and -.Cm kod -options return only entries representing client addresses from which the -last packet received triggered either discarding or a KoD response. -The -.Cm mincount Ns = Ns Ar count -option filters entries representing less than -.Ar count -packets. -The -.Cm laddr Ns = Ns Ar localaddr -option filters entries for packets received on any local address other than -.Ar localaddr . -.Cm resany Ns = Ns Ar hexmask -and -.Cm resall Ns = Ns Ar hexmask -filter entries containing none or less than all, respectively, of the bits in -.Ar hexmask , -which must begin with -.Cm 0x . -The -.Ar sortorder -defaults to -.Cm lstint -and may be -.Cm addr , -.Cm avgint , -.Cm count , -.Cm lstint , -or any of those preceded by -.Ql \&\- -to reverse the sort order. -The output columns are: -.Bl -tag -width "something" -compact -offset indent -.It Column -Description -.It Ic lstint -Interval in seconds between the receipt of the most recent packet from -this address and the completion of the retrieval of the MRU list by -.Nm . -.It Ic avgint -Average interval in s between packets from this address. -.It Ic rstr -Restriction flags associated with this address. -Most are copied unchanged from the matching -.Ic restrict -command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless -the last packet from this address triggered a rate control response. -.It Ic r -Rate control indicator, either -a period, -.Ic L -or -.Ic K -for no rate control response, -rate limiting by discarding, or rate limiting with a KoD response, respectively. -.It Ic m -Packet mode. -.It Ic v -Packet version number. -.It Ic count -Packets received from this address. -.It Ic rport -Source port of last packet from this address. -.It Ic remote address -host or DNS name, numeric address, or address followed by -claimed DNS name which could not be verified in parentheses. -.El -.It Ic opeers Op Fl 4 | Fl 6 -Obtain and print the old\-style list of all peers and clients showing -.Cm dstadr -(associated with the given IP version), -rather than the -.Cm refid . -.It Ic passociations -Perform the same function as the -.Ic associations -command, -except that it uses previously stored data rather than making a new query. -.It Ic peers -Display a list of peers in the form: -.Dl [tally]remote refid st t when pool reach delay offset jitter -.Bl -tag -width "something" -compact -offset indent -.It Variable -Description -.It Cm [tally] -single\-character code indicating current value of the -.Ic select -field of the -.Lk decode.html#peer "peer status word" -.It Cm remote -host name (or IP number) of peer. -The value displayed will be truncated to 15 characters unless the -.Nm -.Fl w -option is given, in which case the full value will be displayed -on the first line, and if too long, -the remaining data will be displayed on the next line. -.It Cm refid -source IP address or -.Lk decode.html#kiss "'kiss code" -.It Cm st -stratum: 0 for local reference clocks, 1 for servers with local -reference clocks, ..., 16 for unsynchronized server clocks -.It Cm t -.Ic u : -unicast or manycast client, -.Ic b : -broadcast or multicast client, -.Ic p : -pool source, -.Ic l : -local (reference clock), -.Ic s : -symmetric (peer), -.Ic A : -manycast server, -.Ic B : -broadcast server, -.Ic M : -multicast server -.It Cm when -time in seconds, minutes, hours, or days since the last packet -was received, or -.Ql \&\- -if a packet has never been received -.It Cm poll -poll interval (s) -.It Cm reach -reach shift register (octal) -.It Cm delay -roundtrip delay -.It Cm offset -offset of server relative to this host -.It Cm jitter -offset RMS error estimate. -.El -.It Ic pstats Ar associd -Display the statistics for the peer with the given -.Ar associd : -associd, status, remote host, local address, time last received, -time until next send, reachability change, packets sent, -packets received, bad authentication, bogus origin, duplicate, -bad dispersion, bad reference time, candidate order. -.It Ic readlist Op Ar associd -.It Ic rl Op Ar associd -Display all system or peer variables. -If the -.Ar associd -is omitted, it is assumed to be zero. -.It Ic readvar Op Ar associd Ar name Ns Oo Ns = Ns Ar value Oc Op , ... -.It Ic rv Op Ar associd Ar name Ns Oo Ns = Ns Ar value Oc Op , ... -Display the specified system or peer variables. -If -.Ar associd -is zero, the variables are from the -.Sx System Variables -name space, otherwise they are from the -.Sx Peer Variables -name space. -The -.Ar associd -is required, as the same name can occur in both spaces. -If no -.Ar name -is included, all operative variables in the name space are displayed. -In this case only, if the -.Ar associd -is omitted, it is assumed to be zero. -Multiple names are specified with comma separators and without whitespace. -Note that time values are represented in milliseconds -and frequency values in parts\-per\-million (PPM). -Some NTP timestamps are represented in the format -.Ar YYYY Ns Ar MM Ar DD Ar TTTT , -where -.Ar YYYY -is the year, -.Ar MM -the month of year, -.Ar DD -the day of month and -.Ar TTTT -the time of day. -.It Ic reslist -Display the access control (restrict) list for -.Nm . -Authentication is required. -.It Ic saveconfig Ar filename -Save the current configuration, -including any runtime modifications made by -.Ic :config -or -.Ic config\-from\-file , -to the NTP server host file -.Ar filename . -This command will be rejected by the server unless -.Lk miscopt.html#saveconfigdir "saveconfigdir" -appears in the -.Xr ntpd 8 -configuration file. -.Ar filename -can use -.Xr date 1 -format specifiers to substitute the current date and time, for -example, -.D1 Ic saveconfig Pa ntp\-%Y%m%d\-%H%M%S.conf . -The filename used is stored in system variable -.Cm savedconfig . -Authentication is required. -.It Ic sysinfo -Display system operational summary: -associd, status, system peer, system peer mode, leap indicator, -stratum, log2 precision, root delay, root dispersion, -reference id, reference time, system jitter, clock jitter, -clock wander, broadcast delay, symm. auth. delay. -.It Ic sysstats -Display system uptime and packet counts maintained in the -protocol module: -uptime, sysstats reset, packets received, current version, -older version, bad length or format, authentication failed, -declined, restricted, rate limited, KoD responses, -processed for time. -.It Ic timerstats -Display interval timer counters: -time since reset, timer overruns, calls to transmit. -.It Ic writelist Ar associd -Set all system or peer variables included in the variable list. -.It Ic writevar Ar associd Ar name Ns = Ns Ar value Op , ... -Set the specified variables in the variable list. -If the -.Ar associd -is zero, the variables are from the -.Sx System Variables -name space, otherwise they are from the -.Sx Peer Variables -name space. -The -.Ar associd -is required, as the same name can occur in both spaces. -Authentication is required. -.El -.Ss Status Words and Kiss Codes -The current state of the operating program is shown -in a set of status words -maintained by the system. -Status information is also available on a per\-association basis. -These words are displayed by the -.Ic readlist -and -.Ic associations -commands both in hexadecimal and in decoded short tip strings. -The codes, tips and short explanations are documented on the -.Lk decode.html "Event Messages and Status Words" -page. -The page also includes a list of system and peer messages, -the code for the latest of which is included in the status word. -.Pp -Information resulting from protocol machine state transitions -is displayed using an informal set of ASCII strings called -.Lk decode.html#kiss "kiss codes" . -The original purpose was for kiss\-o'\-death (KoD) packets -sent by the server to advise the client of an unusual condition. -They are now displayed, when appropriate, -in the reference identifier field in various billboards. -.Ss System Variables -The following system variables appear in the -.Ic readlist -billboard. -Not all variables are displayed in some configurations. -.Pp -.Bl -tag -width "something" -compact -offset indent -.It Variable -Description -.It Cm status -.Lk decode.html#sys "system status word" -.It Cm version -NTP software version and build time -.It Cm processor -hardware platform and version -.It Cm system -operating system and version -.It Cm leap -leap warning indicator (0\-3) -.It Cm stratum -stratum (1\-15) -.It Cm precision -precision (log2 s) -.It Cm rootdelay -total roundtrip delay to the primary reference clock -.It Cm rootdisp -total dispersion to the primary reference clock -.It Cm refid -reference id or -.Lk decode.html#kiss "kiss code" -.It Cm reftime -reference time -.It Ic clock -date and time of day -.It Cm peer -system peer association id -.It Cm tc -time constant and poll exponent (log2 s) (3\-17) -.It Cm mintc -minimum time constant (log2 s) (3\-10) -.It Cm offset -combined offset of server relative to this host -.It Cm frequency -frequency drift (PPM) relative to hardware clock -.It Cm sys_jitter -combined system jitter -.It Cm clk_wander -clock frequency wander (PPM) -.It Cm clk_jitter -clock jitter -.It Cm tai -TAI\-UTC offset (s) -.It Cm leapsec -NTP seconds when the next leap second is/was inserted -.It Cm expire -NTP seconds when the NIST leapseconds file expires -.El -The jitter and wander statistics are exponentially\-weighted RMS averages. -The system jitter is defined in the NTPv4 specification; -the clock jitter statistic is computed by the clock discipline module. -.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 Autokey dance: -.Bl -tag -width "something" -compact -offset indent -.It Variable -Description -.It Cm host -Autokey host name for this host -.It Cm ident -Autokey group name for this host -.It Cm flags -host flags (see Autokey specification) -.It Cm digest -OpenSSL message digest algorithm -.It Cm signature -OpenSSL digest/signature scheme -.It Cm update -NTP seconds at last signature update -.It Cm cert -certificate subject, issuer and certificate flags -.It Cm until -NTP seconds when the certificate expires -.El -.Ss Peer Variables -The following peer variables appear in the -.Ic readlist -billboard for each association. -Not all variables are displayed in some configurations. -.Pp -.Bl -tag -width "something" -compact -offset indent -.It Variable -Description -.It Cm associd -association id -.It Cm status -.Lk decode.html#peer "peer status word" -.It Cm srcadr -source (remote) IP address -.It Cm srcport -source (remote) port -.It Cm dstadr -destination (local) IP address -.It Cm dstport -destination (local) port -.It Cm leap -leap indicator (0\-3) -.It Cm stratum -stratum (0\-15) -.It Cm precision -precision (log2 s) -.It Cm rootdelay -total roundtrip delay to the primary reference clock -.It Cm rootdisp -total root dispersion to the primary reference clock -.It Cm refid -reference id or -.Lk decode.html#kiss "kiss code" -.It Cm reftime -reference time -.It Cm rec -last packet received time -.It Cm reach -reach register (octal) -.It Cm unreach -unreach counter -.It Cm hmode -host mode (1\-6) -.It Cm pmode -peer mode (1\-5) -.It Cm hpoll -host poll exponent (log2 s) (3\-17) -.It Cm ppoll -peer poll exponent (log2 s) (3\-17) -.It Cm headway -headway (see -.Lk rate.html "Rate Management and the Kiss\-o'\-Death Packet" ) -.It Cm flash -.Lk decode.html#flash "flash status word" -.It Cm keyid -symmetric key id -.It Cm offset -filter offset -.It Cm delay -filter delay -.It Cm dispersion -filter dispersion -.It Cm jitter -filter jitter -.It Cm bias -unicast/broadcast bias -.It Cm xleave -interleave delay (see -.Lk xleave.html "NTP Interleaved Modes" ) -.El -The -.Cm bias -variable is calculated when the first broadcast packet is received -after the calibration volley. -It represents the offset of the broadcast subgraph relative to the -unicast subgraph. -The -.Cm xleave -variable appears only for the interleaved symmetric and interleaved modes. -It represents the internal queuing, buffering and transmission delays -for the preceding packet. -.Pp -When the NTPv4 daemon is compiled with the OpenSSL software library, -additional peer variables are displayed, including the following: -.Bl -tag -width "something" -compact -offset indent -.It Variable -Description -.It Cm flags -peer flags (see Autokey specification) -.It Cm host -Autokey server name -.It Cm flags -peer flags (see Autokey specification) -.It Cm signature -OpenSSL digest/signature scheme -.It Cm initsequence -initial key id -.It Cm initkey -initial key index -.It Cm timestamp -Autokey signature timestamp -.It Cm ident -Autokey group name for this association -.El -.Ss Clock Variables -The following clock variables appear in the -.Ic clocklist -billboard for each association with a reference clock. -Not all variables are displayed in some configurations. -.Bl -tag -width "something" -compact -offset indent -.It Variable -Description -.It Cm associd -association id -.It Cm status -.Lk decode.html#clock "clock status word" -.It Cm device -device description -.It Cm timecode -ASCII time code string (specific to device) -.It Cm poll -poll messages sent -.It Cm noreply -no reply -.It Cm badformat -bad format -.It Cm baddata -bad date or time -.It Cm fudgetime1 -fudge time 1 -.It Cm fudgetime2 -fudge time 2 -.It Cm stratum -driver stratum -.It Cm refid -driver reference id -.It Cm flags -driver flags -.El -.Sh "OPTIONS" -.Bl -tag -.It Fl 4 , Fl \-ipv4 -Force IPv4 name resolution. -This option must not appear in combination with any of the following options: -ipv6. -.sp -Force resolution of following host names on the command line -to the IPv4 namespace. -.It Fl 6 , Fl \-ipv6 -Force IPv6 name resolution. -This option must not appear in combination with any of the following options: -ipv4. -.sp -Force resolution of following host names on the command line -to the IPv6 namespace. -.It Fl c Ar cmd , Fl \-command Ns = Ns Ar cmd -run a command and exit. -This option may appear an unlimited number of times. -.sp -The following argument is interpreted as an interactive format command -and is added to the list of commands to be executed on the specified -host(s). -.It Fl d , Fl \-debug\-level -Increase debug verbosity level. -This option may appear an unlimited number of times. -.sp -.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number -Set the debug verbosity level. -This option may appear an unlimited number of times. -This option takes an integer number as its argument. -.sp -.It Fl i , Fl \-interactive -Force ntpq to operate in interactive mode. -This option must not appear in combination with any of the following options: -command, peers. -.sp -Force \fBntpq\fP to operate in interactive mode. -Prompts will be written to the standard output and -commands read from the standard input. -.It Fl n , Fl \-numeric -numeric host addresses. -.sp -Output all host addresses in dotted\-quad numeric format rather than -converting to the canonical host names. -.It Fl \-old\-rv -Always output status line with readvar. -.sp -By default, \fBntpq\fP now suppresses the \fBassocid=...\fP -line that precedes the output of \fBreadvar\fP -(alias \fBrv\fP) when a single variable is requested, such as -\fBntpq \-c "rv 0 offset"\fP. -This option causes \fBntpq\fP to include both lines of output -for a single\-variable \fBreadvar\fP. -Using an environment variable to -preset this option in a script will enable both older and -newer \fBntpq\fP to behave identically in this regard. -.It Fl p , Fl \-peers -Print a list of the peers. -This option must not appear in combination with any of the following options: -interactive. -.sp -Print a list of the peers known to the server as well as a summary -of their state. This is equivalent to the 'peers' interactive command. -.It Fl r Ar keyword , Fl \-refid Ns = Ns Ar keyword -Set default display type for S2+ refids. -This option takes a keyword as its argument. The argument sets an enumeration value that can -be tested by comparing them against the option value macro. -The available keywords are: -.in +4 -.nf -.na -hash ipv4 -.fi -or their numeric equivalent. -.in -4 -.sp -The default -.Ar keyword -for this option is: -.ti +4 - ipv4 -.sp -Set the default display format for S2+ refids. -.It Fl w , Fl \-wide -Display the full 'remote' value. -.sp -Display the full value of the 'remote' value. If this requires -more than 15 characters, display the full value, emit a newline, -and continue the data display properly indented on the next line. -.It Fl \&? , Fl \-help -Display usage information and exit. -.It Fl \&! , Fl \-more\-help -Pass the extended usage information through a pager. -.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc -Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP -configuration file listed in the \fBOPTION PRESETS\fP section, below. -The command will exit after updating the config file. -.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts -Load options from \fIcfgfile\fP. -The \fIno\-load\-opts\fP form will disable the loading -of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early, -out of order. -.It Fl \-version Op Brq Ar v|c|n -Output version of program and exit. The default mode is `v', a simple -version. The `c' mode will print copyright information and `n' will -print the full copyright notice. -.El -.Sh "OPTION PRESETS" -Any option that is not marked as \fInot presettable\fP may be preset -by loading values from configuration ("RC" or ".INI") file(s) and values from -environment variables named: -.nf - \fBNTPQ_\fP or \fBNTPQ\fP -.fi -.ad -The environmental presets take precedence (are processed later than) -the configuration files. -The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". -If any of these are directories, then the file \fI.ntprc\fP -is searched for within those directories. -.Sh "ENVIRONMENT" -See \fBOPTION PRESETS\fP for configuration environment variables. -.Sh "FILES" -See \fBOPTION PRESETS\fP for configuration files. -.Sh "EXIT STATUS" -One of the following exit values will be returned: -.Bl -tag -.It 0 " (EXIT_SUCCESS)" -Successful program execution. -.It 1 " (EXIT_FAILURE)" -The operation failed or the command syntax was not valid. -.It 66 " (EX_NOINPUT)" -A specified configuration file could not be loaded. -.It 70 " (EX_SOFTWARE)" -libopts had an internal operational error. Please report -it to autogen\-users@lists.sourceforge.net. Thank you. -.El -.Sh "AUTHORS" -The University of Delaware and Network Time Foundation -.Sh "COPYRIGHT" -Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved. -This program is released under the terms of the NTP license, . -.Sh "BUGS" -Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.Sh "NOTES" -This manual page was \fIAutoGen\fP\-erated from the \fBntpq\fP -option definitions. diff --git a/usr.sbin/ntp/doc/sntp.8 b/usr.sbin/ntp/doc/sntp.8 deleted file mode 100644 --- a/usr.sbin/ntp/doc/sntp.8 +++ /dev/null @@ -1,317 +0,0 @@ -.Dd August 14 2018 -.Dt SNTP 8 User Commands -.Os -.\" EDIT THIS FILE WITH CAUTION (sntp-opts.mdoc) -.\" -.\" It has been AutoGen-ed August 14, 2018 at 08:27:40 AM by AutoGen 5.18.5 -.\" From the definitions sntp-opts.def -.\" and the template file agmdoc-cmd.tpl -.Sh NAME -.Nm sntp -.Nd reference Simple Network Time Protocol client -.Sh SYNOPSIS -.Nm -.\" Mixture of short (flag) options and long options -.Op Fl flags -.Op Fl flag Op Ar value -.Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc -[ hostname\-or\-IP ...] -.Pp -.Sh DESCRIPTION -.Nm -can be used as an SNTP client to query a NTP or SNTP server and either display -the time or set the local system's time (given suitable privilege). It can be -run as an interactive command or from a -.Ic cron -job. -NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) -are defined and described by RFC 5905. -.Pp -The default is to write the estimated correct local date and time (i.e. not -UTC) to the standard output in a format like: -.Ic "'1996\-10\-15 20:17:25.123 (+0800) +4.567 +/\- 0.089 [host] IP sN'" -where the -.Ic "'(+0800)'" -means that to get to UTC from the reported local time one must -add 8 hours and 0 minutes, -the -.Ic "'+4.567'" -indicates the local clock is 4.567 seconds behind the correct time -(so 4.567 seconds must be added to the local clock to get it to be correct). -Note that the number of decimals printed for this value will change -based on the reported precision of the server. -.Ic "'+/\- 0.089'" -is the reported -.Em synchronization distance -(in seconds), which represents the maximum error due to all causes. -If the server does not report valid data needed to calculate the -synchronization distance, this will be reported as -.Ic "'+/\- ?'" . -If the -.Em host -is different from the -.Em IP , -both will be displayed. -Otherwise, only the -.Em IP -is displayed. -Finally, the -.Em stratum -of the host is reported -and the leap indicator is decoded and displayed. -.Sh "OPTIONS" -.Bl -tag -.It Fl 4 , Fl \-ipv4 -Force IPv4 DNS name resolution. -This option must not appear in combination with any of the following options: -ipv6. -.sp -Force DNS resolution of the following host names on the command line -to the IPv4 namespace. -.It Fl 6 , Fl \-ipv6 -Force IPv6 DNS name resolution. -This option must not appear in combination with any of the following options: -ipv4. -.sp -Force DNS resolution of the following host names on the command line -to the IPv6 namespace. -.It Fl a Ar auth\-keynumber , Fl \-authentication Ns = Ns Ar auth\-keynumber -Enable authentication with the key \fBauth\-keynumber\fP. -This option takes an integer number as its argument. -.sp -Enable authentication using the key specified in this option's -argument. The argument of this option is the \fBkeyid\fP, a -number specified in the \fBkeyfile\fP as this key's identifier. -See the \fBkeyfile\fP option (\fB\-k\fP) for more details. -.It Fl b Ar broadcast\-address , Fl \-broadcast Ns = Ns Ar broadcast\-address -Listen to the address specified for broadcast time sync. -This option may appear an unlimited number of times. -.sp -If specified \fBsntp\fP will listen to the specified address -for NTP broadcasts. The default maximum wait time -can (and probably should) be modified with \fB\-t\fP. -.It Fl c Ar host\-name , Fl \-concurrent Ns = Ns Ar host\-name -Concurrently query all IPs returned for host\-name. -This option may appear an unlimited number of times. -.sp -Requests from an NTP "client" to a "server" should never be sent -more rapidly than one every 2 seconds. By default, any IPs returned -as part of a DNS lookup are assumed to be for a single instance of -\fBntpd\fP, and therefore \fBsntp\fP will send queries to these IPs -one after another, with a 2\-second gap in between each query. -.sp -The \fB\-c\fP or \fB\-\-concurrent\fP flag says that any IPs -returned for the DNS lookup of the supplied host\-name are on -different machines, so we can send concurrent queries. -.It Fl d , Fl \-debug\-level -Increase debug verbosity level. -This option may appear an unlimited number of times. -.sp -.It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number -Set the debug verbosity level. -This option may appear an unlimited number of times. -This option takes an integer number as its argument. -.sp -.It Fl g Ar milliseconds , Fl \-gap Ns = Ns Ar milliseconds -The gap (in milliseconds) between time requests. -This option takes an integer number as its argument. -The default -.Ar milliseconds -for this option is: -.ti +4 - 50 -.sp -Since we're only going to use the first valid response we get and -there is benefit to specifying a good number of servers to query, -separate the queries we send out by the specified number of -milliseconds. -.It Fl K Ar file\-name , Fl \-kod Ns = Ns Ar file\-name -KoD history filename. -The default -.Ar file\-name -for this option is: -.ti +4 - /var/db/ntp\-kod -.sp -Specifies the filename to be used for the persistent history of KoD -responses received from servers. If the file does not exist, a -warning message will be displayed. The file will not be created. -.It Fl k Ar file\-name , Fl \-keyfile Ns = Ns Ar file\-name -Look in this file for the key specified with \fB\-a\fP. -The default -.Ar file\-name -for this option is: -.ti +4 - /etc/ntp.keys -.sp -This option specifies the keyfile. -\fBsntp\fP will search for the key specified with \fB\-a\fP -\fIkeyno\fP in this file. See \fBntp.keys(5)\fP for more -information. -.It Fl l Ar file\-name , Fl \-logfile Ns = Ns Ar file\-name -Log to specified logfile. -.sp -This option causes the client to write log messages to the specified -\fIlogfile\fP. -.It Fl M Ar number , Fl \-steplimit Ns = Ns Ar number -Adjustments less than \fBsteplimit\fP msec will be slewed. -This option takes an integer number as its argument. -The value of -.Ar number -is constrained to being: -.in +4 -.nf -.na -greater than or equal to 0 -.fi -.in -4 -.sp -If the time adjustment is less than \fIsteplimit\fP milliseconds, -slew the amount using \fBadjtime(2)\fP. Otherwise, step the -correction using \fBsettimeofday(2)\fP. The default value is 0, -which means all adjustments will be stepped. This is a feature, as -different situations demand different values. -.It Fl o Ar number , Fl \-ntpversion Ns = Ns Ar number -Send \fBint\fP as our NTP protocol version. -This option takes an integer number as its argument. -The value of -.Ar number -is constrained to being: -.in +4 -.nf -.na -in the range 0 through 7 -.fi -.in -4 -The default -.Ar number -for this option is: -.ti +4 - 4 -.sp -When sending requests to a remote server, tell them we are running -NTP protocol version \fIntpversion\fP . -.It Fl r , Fl \-usereservedport -Use the NTP Reserved Port (port 123). -.sp -Use port 123, which is reserved for NTP, for our network -communications. -.It Fl S , Fl \-step -OK to 'step' the time with \fBsettimeofday(2)\fP. -.sp -.It Fl s , Fl \-slew -OK to 'slew' the time with \fBadjtime(2)\fP. -.sp -.It Fl t Ar seconds , Fl \-timeout Ns = Ns Ar seconds -The number of seconds to wait for responses. -This option takes an integer number as its argument. -The default -.Ar seconds -for this option is: -.ti +4 - 5 -.sp -When waiting for a reply, \fBsntp\fP will wait the number -of seconds specified before giving up. The default should be -more than enough for a unicast response. If \fBsntp\fP is -only waiting for a broadcast response a longer timeout is -likely needed. -.It Fl \-wait , Fl \-no\-wait -Wait for pending replies (if not setting the time). -The \fIno\-wait\fP form will disable the option. -This option is enabled by default. -.sp -If we are not setting the time, wait for all pending responses. -.It Fl \&? , Fl \-help -Display usage information and exit. -.It Fl \&! , Fl \-more\-help -Pass the extended usage information through a pager. -.It Fl > Oo Ar cfgfile Oc , Fl \-save\-opts Oo Ns = Ns Ar cfgfile Oc -Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP -configuration file listed in the \fBOPTION PRESETS\fP section, below. -The command will exit after updating the config file. -.It Fl < Ar cfgfile , Fl \-load\-opts Ns = Ns Ar cfgfile , Fl \-no\-load\-opts -Load options from \fIcfgfile\fP. -The \fIno\-load\-opts\fP form will disable the loading -of earlier config/rc/ini files. \fI\-\-no\-load\-opts\fP is handled early, -out of order. -.It Fl \-version Op Brq Ar v|c|n -Output version of program and exit. The default mode is `v', a simple -version. The `c' mode will print copyright information and `n' will -print the full copyright notice. -.El -.Sh "OPTION PRESETS" -Any option that is not marked as \fInot presettable\fP may be preset -by loading values from configuration ("RC" or ".INI") file(s) and values from -environment variables named: -.nf - \fBSNTP_\fP or \fBSNTP\fP -.fi -.ad -The environmental presets take precedence (are processed later than) -the configuration files. -The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". -If any of these are directories, then the file \fI.ntprc\fP -is searched for within those directories. -.Sh USAGE -.Bl -tag -width indent -.It Li "sntp ntpserver.somewhere" -is the simplest use of this program -and can be run as an unprivileged command -to check the current time and error in the local clock. -.It Li "sntp \-Ss \-M 128 ntpserver.somewhere" -With suitable privilege, -run as a command -or from a -.Xr cron 8 -job, -.Ic "sntp \-Ss \-M 128 ntpserver.somewhere" -will request the time from the server, -and if that server reports that it is synchronized -then if the offset adjustment is less than 128 milliseconds -the correction will be slewed, -and if the correction is more than 128 milliseconds -the correction will be stepped. -.It Li "sntp \-S ntpserver.somewhere" -With suitable privilege, -run as a command -or from a -.Xr cron 8 -job, -.Ic "sntp \-S ntpserver.somewhere" -will set (step) the local clock from a synchronized specified server, -like the (deprecated) -.Xr ntpdate 8 , -or -.Xr rdate 8 -commands. -.El -.Sh "ENVIRONMENT" -See \fBOPTION PRESETS\fP for configuration environment variables. -.Sh "FILES" -See \fBOPTION PRESETS\fP for configuration files. -.Sh "EXIT STATUS" -One of the following exit values will be returned: -.Bl -tag -.It 0 " (EXIT_SUCCESS)" -Successful program execution. -.It 1 " (EXIT_FAILURE)" -The operation failed or the command syntax was not valid. -.It 66 " (EX_NOINPUT)" -A specified configuration file could not be loaded. -.It 70 " (EX_SOFTWARE)" -libopts had an internal operational error. Please report -it to autogen\-users@lists.sourceforge.net. Thank you. -.El -.Sh AUTHORS -.An "Johannes Maximilian Kuehn" -.An "Harlan Stenn" -.An "Dave Hart" -.Sh "COPYRIGHT" -Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved. -This program is released under the terms of the NTP license, . -.Sh "BUGS" -Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org -.Sh "NOTES" -This manual page was \fIAutoGen\fP\-erated from the \fBsntp\fP -option definitions.