diff options
author | sjg <sjg@FreeBSD.org> | 2015-05-27 01:19:58 +0000 |
---|---|---|
committer | sjg <sjg@FreeBSD.org> | 2015-05-27 01:19:58 +0000 |
commit | 65145fa4c81da358fcbc3b650156dab705dfa34e (patch) | |
tree | 55c065b6730aaac2afb6c29933ee6ec5fa4c4249 /usr.sbin/ntp/doc | |
parent | 60ff4eb0dff94a04d75d0d52a3957aaaf5f8c693 (diff) | |
parent | e6b664c390af88d4a87208bc042ce503da664c3b (diff) | |
download | FreeBSD-src-65145fa4c81da358fcbc3b650156dab705dfa34e.zip FreeBSD-src-65145fa4c81da358fcbc3b650156dab705dfa34e.tar.gz |
Merge sync of head
Diffstat (limited to 'usr.sbin/ntp/doc')
-rw-r--r-- | usr.sbin/ntp/doc/Makefile | 39 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/drivers/Makefile | 21 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/drivers/icons/Makefile | 13 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/drivers/scripts/Makefile | 13 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/hints/Makefile | 17 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/icons/Makefile | 13 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/ntp-keygen.8 | 558 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/ntp.conf.5 | 380 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/ntp.keys.5 | 170 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/ntpd.8 | 607 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/ntpdc.8 | 242 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/ntpq.8 | 1399 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/ntptime.8 | 4 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/ntptrace.8 | 149 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/pic/Makefile | 27 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/scripts/Makefile | 15 | ||||
-rw-r--r-- | usr.sbin/ntp/doc/sntp.8 | 313 |
17 files changed, 2766 insertions, 1214 deletions
diff --git a/usr.sbin/ntp/doc/Makefile b/usr.sbin/ntp/doc/Makefile index 9c42b09..283d6ab 100644 --- a/usr.sbin/ntp/doc/Makefile +++ b/usr.sbin/ntp/doc/Makefile @@ -2,32 +2,33 @@ .include <src.opts.mk> +SUBDIR= drivers hints icons pic scripts + FILESDIR= ${SHAREDIR}/doc/ntp .if ${MK_HTML} != "no" -FILES= accopt.html assoc.html audio.html authopt.html build.html \ - clockopt.html \ - config.html confopt.html copyright.html debug.html driver1.html \ - driver10.html driver11.html driver12.html driver16.html driver18.html \ - driver19.html driver2.html driver20.html driver22.html \ - driver26.html driver27.html driver28.html driver29.html \ - driver3.html driver30.html driver32.html driver33.html driver34.html \ - driver35.html driver36.html driver37.html \ - driver4.html driver5.html driver6.html driver7.html driver8.html \ - driver9.html extern.html hints.html \ - howto.html index.html kern.html \ - ldisc.html measure.html miscopt.html monopt.html mx4200data.html \ - notes.html ntpd.html ntpdate.html ntpdc.html ntpq.html ntptime.html \ - ntptrace.html parsedata.html parsenew.html patches.html porting.html \ - pps.html prefer.html quick.html rdebug.html refclock.html \ - release.html tickadj.html +FILES= access.html accopt.html assoc.html audio.html authentic.html \ + authopt.html autokey.html bugs.html build.html clock.html \ + clockopt.html cluster.html comdex.html config.html confopt.html \ + copyright.html debug.html decode.html discipline.html discover.html \ + extern.html filter.html hints.html history.html howto.html \ + huffpuff.html index.html kern.html kernpps.html keygen.html leap.html \ + miscopt.html monopt.html msyslog.html ntp-keygen.html ntp-wait.html \ + ntp.conf.html ntp.keys.html ntp_conf.html ntpd.html ntpdate.html \ + ntpdc.html ntpdsim.html ntpdsim_new.html ntpq.html ntpsnmpd.html \ + ntptime.html ntptrace.html orphan.html parsedata.html \ + parsenew.html poll.html pps.html prefer.html quick.html rate.html \ + rdebug.html refclock.html release.html select.html sitemap.html \ + sntp.html stats.html tickadj.html warp.html xleave.html .endif MAN= ntp.conf.5 ntp.keys.5 -MAN+= ntp-keygen.8 ntpd.8 ntpdate.8 ntpdc.8 ntpq.8 ntptime.8 +MAN+= ntp-keygen.8 ntpd.8 ntpdate.8 ntpdc.8 ntpq.8 ntptime.8 sntp.8 .PATH: ${.CURDIR}/../../../contrib/ntp/html \ - ${.CURDIR}/../../../contrib/ntp/html/build \ - ${.CURDIR}/../../../contrib/ntp/html/drivers + ${.CURDIR}/../../../contrib/ntp/util \ + ${.CURDIR}/../../../contrib/ntp/util \ + ${.CURDIR}/../../../contrib/ntp/ntpd \ + ${.CURDIR}/../../../contrib/ntp/ntpsnmpd .include <bsd.prog.mk> diff --git a/usr.sbin/ntp/doc/drivers/Makefile b/usr.sbin/ntp/doc/drivers/Makefile new file mode 100644 index 0000000..7ae3cd2 --- /dev/null +++ b/usr.sbin/ntp/doc/drivers/Makefile @@ -0,0 +1,21 @@ +# $FreeBSD$ + +.include <src.opts.mk> + +SUBDIR= icons scripts +FILESDIR= ${SHAREDIR}/doc/ntp/drivers + +.if ${MK_HTML} != "no" +FILES= driver1.html driver10.html driver11.html driver12.html driver16.html \ + driver18.html driver19.html driver20.html driver22.html driver26.html \ + driver27.html driver28.html driver29.html driver3.html driver30.html \ + driver31.html driver32.html driver33.html driver34.html driver35.html \ + driver36.html driver37.html driver38.html driver39.html driver4.html \ + driver40.html driver42.html driver43.html driver44.html driver45.html \ + driver46.html driver5.html driver6.html driver7.html driver8.html \ + driver9.html mx4200data.html oncore-shmem.html tf582_4.html +.endif + +.PATH: ${.CURDIR}/../../../../contrib/ntp/html/drivers + +.include <bsd.prog.mk> diff --git a/usr.sbin/ntp/doc/drivers/icons/Makefile b/usr.sbin/ntp/doc/drivers/icons/Makefile new file mode 100644 index 0000000..e76e1fa --- /dev/null +++ b/usr.sbin/ntp/doc/drivers/icons/Makefile @@ -0,0 +1,13 @@ +# $FreeBSD$ + +.include <src.opts.mk> + +FILESDIR= ${SHAREDIR}/doc/ntp/drivers/icons + +.if ${MK_HTML} != "no" +FILES= home.gif mail2.gif +.endif + +.PATH: ${.CURDIR}/../../../../../contrib/ntp/html/drivers/icons + +.include <bsd.prog.mk> diff --git a/usr.sbin/ntp/doc/drivers/scripts/Makefile b/usr.sbin/ntp/doc/drivers/scripts/Makefile new file mode 100644 index 0000000..44ff1a6 --- /dev/null +++ b/usr.sbin/ntp/doc/drivers/scripts/Makefile @@ -0,0 +1,13 @@ +# $FreeBSD$ + +.include <src.opts.mk> + +FILESDIR= ${SHAREDIR}/doc/ntp/drivers/scripts + +.if ${MK_HTML} != "no" +FILES= footer.txt style.css +.endif + +.PATH: ${.CURDIR}/../../../../../contrib/ntp/html/drivers/scripts + +.include <bsd.prog.mk> diff --git a/usr.sbin/ntp/doc/hints/Makefile b/usr.sbin/ntp/doc/hints/Makefile new file mode 100644 index 0000000..fdbcea0 --- /dev/null +++ b/usr.sbin/ntp/doc/hints/Makefile @@ -0,0 +1,17 @@ +# $FreeBSD$ + +.include <src.opts.mk> + +FILESDIR= ${SHAREDIR}/doc/ntp/hints + +.if ${MK_HTML} != "no" +FILES= a-ux aix bsdi changes decosf1 decosf2 freebsd hpux linux mpeix \ + notes-xntp-v3 parse refclocks rs6000 sco.html sgi \ + solaris-dosynctodr.html solaris.html solaris.xtra.4023118 \ + solaris.xtra.4095849 solaris.xtra.S99ntpd solaris.xtra.patchfreq \ + sun4 svr4-dell svr4_package todo vxworks.html winnt.html +.endif + +.PATH: ${.CURDIR}/../../../../contrib/ntp/html/hints + +.include <bsd.prog.mk> diff --git a/usr.sbin/ntp/doc/icons/Makefile b/usr.sbin/ntp/doc/icons/Makefile new file mode 100644 index 0000000..410a380 --- /dev/null +++ b/usr.sbin/ntp/doc/icons/Makefile @@ -0,0 +1,13 @@ +# $FreeBSD$ + +.include <src.opts.mk> + +FILESDIR= ${SHAREDIR}/doc/ntp/icons + +.if ${MK_HTML} != "no" +FILES= home.gif mail2.gif sitemap.png +.endif + +.PATH: ${.CURDIR}/../../../../contrib/ntp/html/icons + +.include <bsd.prog.mk> diff --git a/usr.sbin/ntp/doc/ntp-keygen.8 b/usr.sbin/ntp/doc/ntp-keygen.8 index 2d48301..89c4e09 100644 --- a/usr.sbin/ntp/doc/ntp-keygen.8 +++ b/usr.sbin/ntp/doc/ntp-keygen.8 @@ -1,21 +1,25 @@ +.Dd February 4 2015 +.Dt NTP_KEYGEN 8 User Commands +.Os +.\" EDIT THIS FILE WITH CAUTION (ntp-keygen-opts.mdoc) .\" .\" $FreeBSD$ .\" -.Dd May 17, 2006 -.Dt NTP-KEYGEN 8 -.Os +.\" It has been AutoGen-ed February 4, 2015 at 02:44:02 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntp-keygen-opts.def +.\" and the template file agmdoc-cmd.tpl .Sh NAME .Nm ntp-keygen -.Nd key generation program for ntpd +.Nd Create a NTP host key .Sh SYNOPSIS .Nm -.Op Fl deGgHIMnPT -.Op Fl c Ar scheme -.Op Fl i Ar name -.Op Fl p Ar password -.Op Fl S Op Cm RSA | DSA -.Op Fl s Ar name -.Op Fl v Ar nkeys +.\" 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. @@ -27,22 +31,142 @@ These files are used for cookie encryption, digital signature and challenge/response identification algorithms compatible with the Internet standard security infrastructure. .Pp -All files are in PEM-encoded printable ASCII format, +All files are in PEM\-encoded printable ASCII format, so they can be embedded as MIME attachments in mail to other sites and certificate authorities. By default, files are not encrypted. +.Pp +When used to generate message digest 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 the SHA1 and other message +digest algorithms. +The message digest 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 Ar password -option specifies the write password and -.Fl q Ar password -option the read password for previously encrypted files. +.Fl p +option specifies the password for local encrypted files and the +.Fl q +option the password for encrypted files sent to remote sites. +If no password is specified, the host name returned by the Unix +.Fn gethostname +function, normally the DNS name of the host is used. +.Pp The +.Ar pw +option of the +.Ar crypto +configuration command specifies the read +password for previously encrypted local files. +This must match the local password used by this program. +If not specified, the host name is used. +Thus, if files are generated by this program without password, +they can be read back by +.Ar ntpd +without password but only on the same host. +.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 +.Ar 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. +The location of the keys directory can be changed by the +.Ar keysdir +configuration command in such cases. +Normally, this is in +.Pa /etc . +.Pp +This program directs commentary and error messages to the standard +error stream +.Ar stderr +and remote files to the standard output stream +.Ar 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 +.Ar ntpkey +and include the file type, generating host and filestamp, +as described in the +.Dq Cryptographic Data Files +section below. +.Ss Running the Program +To test and gain experience with Autokey concepts, log in as root and +change to the keys directory, usually +.Pa /usr/local/etc +When run for the first time, or if all files with names beginning with +.Ar ntpkey +have been removed, use 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. +command without arguments to generate a +default RSA host key and matching RSA\-MD5 certificate with expiration +date one year hence. +If run again without options, the program uses the +existing keys and parameters and generates only a new certificate with +new expiration date one year hence. +.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 RSA or DSA type. +By default, the signature +message digest type is 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. +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 The .Xr ntpd 8 @@ -83,7 +207,125 @@ and generation date and time as comments. 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. +in NFS\-mounted networks. +The actual location of the keys directory +and each file can be overridden by configuration commands, +but this is not recommended. +Normally, the files for each host are generated by that host +and used only by that host, although exceptions exist +as noted later on this page. +.Pp +Normally, files containing private values, +including the host key, sign key and identification parameters, +are permitted root read/write\-only; +while others containing public values are permitted world readable. +Alternatively, files containing private values can be encrypted +and these files permitted world readable, +which simplifies maintenance in shared file systems. +Since uniqueness is insured by the hostname and +file name extensions, the files for a NFS server and +dependent clients can all be installed in the same shared directory. +.Pp +The recommended practice is to keep the file name extensions +when installing a file and to install a soft link +from the generic names specified elsewhere on this page +to the generated files. +This allows new file generations to be activated simply +by changing the link. +If a link is present, ntpd follows it to the file name +to extract the filestamp. +If a link is not present, +.Xr ntpd 8 +extracts the filestamp from the file itself. +This allows clients to verify that the file and generation times +are always current. +The +.Nm +program uses the same timestamp extension for all files generated +at one time, so each generation is distinct and can be readily +recognized in monitoring data. +.Ss Running the program +The safest way to run the +.Nm +program is logged in directly as root. +The recommended procedure is change to the keys directory, +usually +.Pa /usr/local/etc , +then run the program. +When run for the first time, +or if all +.Cm ntpkey +files have been removed, +the program generates a RSA host key file and matching RSA\-MD5 certificate file, +which is all that is necessary in many cases. +The program also generates soft links from the generic names +to the respective files. +If run again, the program uses the same host key file, +but generates a new certificate file and link. +.Pp +The host key is used to encrypt the cookie when required and so must be RSA type. +By default, the host key is also the sign key used to encrypt signatures. +When necessary, a different sign key can be specified and this can be +either RSA or DSA type. +By default, the message digest type is MD5, but any combination +of sign key type and message digest type supported by the OpenSSL library +can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 +and RIPE160 message digest algorithms. +However, the scheme specified in the certificate must be compatible +with the sign key. +Certificates using any digest algorithm are compatible with RSA sign keys; +however, only SHA and SHA1 certificates are compatible with DSA sign keys. +.Pp +Private/public key files and certificates are compatible with +other OpenSSL applications and very likely other libraries as well. +Certificates or certificate requests derived from them should be compatible +with extant industry practice, although some users might find +the interpretation of X509v3 extension fields somewhat liberal. +However, the identification parameter files, although encoded +as the other files, are probably not compatible with anything other than Autokey. +.Pp +Running the program as other than root and using the Unix +.Ic su +command +to assume root may not work properly, since by default the OpenSSL library +looks for the random seed file +.Cm .rnd +in the user home directory. +However, there should be only one +.Cm .rnd , +most conveniently +in the root directory, so it is convenient to define the +.Cm $RANDFILE +environment variable used by the OpenSSL library as the path to +.Cm /.rnd . +.Pp +Installing the keys as root might not work in NFS\-mounted +shared file systems, as NFS clients may not be able to write +to the shared keys directory, even as root. +In this case, NFS clients can specify the files in another +directory such as +.Pa /etc +using the +.Ic keysdir +command. +There is no need for one client to read the keys and certificates +of other clients or servers, as these data are obtained automatically +by the Autokey protocol. +.Pp +Ordinarily, cryptographic files are generated by the host that uses them, +but it is possible for a trusted agent (TA) to generate these files +for other hosts; however, in such cases files should always be encrypted. +The subject name and trusted name default to the hostname +of the host generating the files, but can be changed by command line options. +It is convenient to designate the owner name and trusted name +as the subject and issuer fields, respectively, of the certificate. +The owner name is also used for the host and sign key files, +while the trusted name is used for the identity files. +.Pp +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. @@ -93,7 +335,7 @@ 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; +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, @@ -132,7 +374,7 @@ When run for the first time, or if all .Cm ntpkey files have been removed, -the program generates a RSA host key file and matching RSA-MD5 certificate file, +the program generates a RSA host key file and matching RSA\-MD5 certificate file, which is all that is necessary in many cases. The program also generates soft links from the generic names to the respective files. @@ -175,7 +417,7 @@ in the root directory, so it is convenient to define the environment variable used by the OpenSSL library as the path to .Cm /.rnd . .Pp -Installing the keys as root might not work in NFS-mounted +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 @@ -197,7 +439,9 @@ 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. -.Ss Trusted Hosts and Groups +seconds. +seconds. +s Trusted Hosts and Groups Each cryptographic configuration involves selection of a signature scheme and identification scheme, called a cryptotype, as explained in the @@ -206,7 +450,7 @@ section of .Xr ntp.conf 5 . The default cryptotype uses RSA encryption, MD5 message digest and TC identification. -First, configure a NTP subnet including one or more low-stratum +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; @@ -248,7 +492,7 @@ is either .Cm RSA or .Cm DSA . -The most often need to do this is when a DSA-signed certificate is used. +The most often need to do this is when a DSA\-signed certificate is used. If it is necessary to use a different certificate scheme than the default, run .Nm @@ -257,7 +501,7 @@ with the option and selected .Ar scheme as needed. -If +f .Nm is run again without these options, it generates a new certificate using the same scheme and sign key. @@ -311,7 +555,7 @@ On trusted host alice run to generate the host key file .Pa ntpkey_RSAkey_ Ns Ar alice.filestamp and trusted private certificate file -.Pa ntpkey_RSA-MD5_cert_ Ns Ar alice.filestamp . +.Pa ntpkey_RSA\-MD5_cert_ Ns Ar alice.filestamp . Copy both files to all group hosts; they replace the files which would be generated in other schemes. On each host bob install a soft link from the generic name @@ -424,16 +668,16 @@ Select certificate message digest/signature encryption scheme. The .Ar scheme can be one of the following: -. Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , +. Cm RSA\-MD2 , RSA\-MD5 , RSA\-SHA , RSA\-SHA1 , RSA\-MDC2 , RSA\-RIPEMD160 , DSA\-SHA , or -.Cm DSA-SHA1 . +.Cm DSA\-SHA1 . Note that RSA schemes must be used with a RSA sign key and DSA schemes must be used with a DSA sign key. The default without this option is -.Cm RSA-MD5 . +.Cm RSA\-MD5 . .It Fl d Enable debugging. -This option displays the cryptographic data produced in eye-friendly billboards. +This option displays the cryptographic data produced in eye\-friendly billboards. .It Fl e Write the IFF client keys to the standard output. This is intended for automatic key distribution by mail. @@ -462,7 +706,7 @@ By default, the program generates public certificates. .It Fl p Ar password Encrypt generated files containing private data with .Ar password -and the DES-CBC algorithm. +and the DES\-CBC algorithm. .It Fl q Set the password for reading files to password. .It Fl S Oo Cm RSA | DSA Oc @@ -476,14 +720,14 @@ This is used for the issuer field in certificates and in the file name for identity files. .It Fl T Generate a trusted certificate. -By default, the program generates a non-trusted certificate. +By default, the program generates a non\-trusted certificate. .It Fl V Ar nkeys -Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. +Generate parameters and keys for the Mu\-Varadharajan (MV) identification scheme. .El .Ss Random Seed File All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize -the internal pseudo-random number generator used +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 @@ -496,7 +740,7 @@ 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. +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 @@ -541,19 +785,19 @@ program and .Xr ntpd 8 daemon. Cryptographic values are encoded first using ASN.1 rules, -then encrypted if necessary, and finally written PEM-encoded +then encrypted if necessary, and finally written PEM\-encoded printable ASCII format preceded and followed by MIME content identifier lines. .Pp The format of the symmetric keys file is somewhat different than the other files in the interest of backward compatibility. -Since DES-CBC is deprecated in NTPv4, the only key format of interest +Since DES\-CBC is deprecated in NTPv4, the only key format of interest is MD5 alphanumeric strings. Following hte heard the keys are entered one per line in the format .D1 Ar keyno type key where .Ar keyno -is a positive integer in the range 1-65,535, +is a positive integer in the range 1\-65,535, .Ar type is the string MD5 defining the key format and .Ar key @@ -594,8 +838,236 @@ used by the and .Xr ntpdc 8 utilities. -.Sh Bugs +.Sh "OPTIONS" +.Bl -tag +.It Fl b Ar imbits , Fl \-imbits Ns = Ns Ar imbits +identity modulus bits. +This option takes an integer number as its argument. +The value of +.Ar imbits +is constrained to being: +.in +4 +.nf +.na +in the range 256 through 2048 +.fi +.in -4 +.sp +The number of bits in the identity modulus. The default is 256. +.It Fl c Ar scheme , Fl \-certificate Ns = Ns Ar scheme +certificate scheme. +.sp +scheme is one of +RSA\-MD2, RSA\-MD5, RSA\-SHA, RSA\-SHA1, RSA\-MDC2, RSA\-RIPEMD160, +DSA\-SHA, or DSA\-SHA1. +.sp +Select the certificate message digest/signature encryption scheme. +Note that RSA schemes must be used with a RSA sign key and DSA +schemes must be used with a DSA sign key. The default without +this option is RSA\-MD5. +.It Fl C Ar cipher , Fl \-cipher Ns = Ns Ar cipher +privatekey cipher. +.sp +Select the cipher which is used to encrypt the files containing +private keys. The default is three\-key triple DES in CBC mode, +equivalent to "@code{\-C des\-ede3\-cbc". The openssl tool lists ciphers +available in "\fBopenssl \-h\fP" output. +.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 e , Fl \-id\-key +Write IFF or GQ identity keys. +.sp +Write the IFF or GQ client keys to the standard output. This is +intended for automatic key distribution by mail. +.It Fl G , Fl \-gq\-params +Generate GQ parameters and keys. +.sp +Generate parameters and keys for the GQ identification scheme, +obsoleting any that may exist. +.It Fl H , Fl \-host\-key +generate RSA host key. +.sp +Generate new host keys, obsoleting any that may exist. +.It Fl I , Fl \-iffkey +generate IFF parameters. +.sp +Generate parameters for the IFF identification scheme, obsoleting +any that may exist. +.It Fl i Ar group , Fl \-ident Ns = Ns Ar group +set Autokey group name. +.sp +Set the optional Autokey group name to name. This is used in +the file name of IFF, GQ, and MV client parameters files. In +that role, the default is the host name if this option is not +provided. The group name, if specified using \fB\-i/\-\-ident\fP or +using \fB\-s/\-\-subject\-name\fP following an '\fB@\fP' character, +is also a part of the self\-signed host certificate's subject and +issuer names in the form \fBhost@group\fP and should match the +\'\fBcrypto ident\fP' or '\fBserver ident\fP' configuration in +\fBntpd\fP's configuration file. +.It Fl l Ar lifetime , Fl \-lifetime Ns = Ns Ar lifetime +set certificate lifetime. +This option takes an integer number as its argument. +.sp +Set the certificate expiration to lifetime days from now. +.It Fl M , Fl \-md5key +generate MD5 keys. +.sp +Generate MD5 keys, obsoleting any that may exist. +.It Fl m Ar modulus , Fl \-modulus Ns = Ns Ar modulus +modulus. +This option takes an integer number as its argument. +The value of +.Ar modulus +is constrained to being: +.in +4 +.nf +.na +in the range 256 through 2048 +.fi +.in -4 +.sp +The number of bits in the prime modulus. The default is 512. +.It Fl P , Fl \-pvt\-cert +generate PC private certificate. +.sp +Generate a private certificate. By default, the program generates +public certificates. +.It Fl p Ar passwd , Fl \-password Ns = Ns Ar passwd +local private password. +.sp +Local files containing private data are encrypted with the +DES\-CBC algorithm and the specified password. The same password +must be specified to the local ntpd via the "crypto pw password" +configuration command. The default password is the local +hostname. +.It Fl q Ar passwd , Fl \-export\-passwd Ns = Ns Ar passwd +export IFF or GQ group keys with password. +.sp +Export IFF or GQ identity group keys to the standard output, +encrypted with the DES\-CBC algorithm and the specified password. +The same password must be specified to the remote ntpd via the +"crypto pw password" configuration command. See also the option +-\-id\-key (\-e) for unencrypted exports. +.It Fl S Ar sign , Fl \-sign\-key Ns = Ns Ar sign +generate sign key (RSA or DSA). +.sp +Generate a new sign key of the designated type, obsoleting any +that may exist. By default, the program uses the host key as the +sign key. +.It Fl s Ar host@group , Fl \-subject\-name Ns = Ns Ar host@group +set host and optionally group name. +.sp +Set the Autokey host name, and optionally, group name specified +following an '\fB@\fP' character. The host name is used in the file +name of generated host and signing certificates, without the +group name. The host name, and if provided, group name are used +in \fBhost@group\fP form for the host certificate's subject and issuer +fields. Specifying '\fB\-s @group\fP' is allowed, and results in +leaving the host name unchanged while appending \fB@group\fP to the +subject and issuer fields, as with \fB\-i group\fP. The group name, or +if not provided, the host name are also used in the file names +of IFF, GQ, and MV client parameter files. +.It Fl T , Fl \-trusted\-cert +trusted certificate (TC scheme). +.sp +Generate a trusted certificate. By default, the program generates +a non\-trusted certificate. +.It Fl V Ar num , Fl \-mv\-params Ns = Ns Ar num +generate <num> 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 <num> 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_<option\-name>\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 +The +.Fl p Ar password +option specifies the write password and +.Fl q Ar password +option the read password for previously encrypted files. +The +.Nm +program prompts for the password if it reads an encrypted file +and the password is missing or incorrect. +If an encrypted file is read successfully and +no write password is specified, the read password is used +as the write password by default. +.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\-2015 The University of Delaware and Network Time Foundation all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. +.Sh BUGS It can take quite a while to generate some cryptographic values, from one to several minutes with modern architectures such as UltraSPARC and up to tens of minutes to an hour with older architectures such as SPARC IPC. +.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 index 1aeed33..4ed9440 100644 --- a/usr.sbin/ntp/doc/ntp.conf.5 +++ b/usr.sbin/ntp/doc/ntp.conf.5 @@ -1,14 +1,23 @@ +.Dd February 4 2015 +.Dt NTP_CONF 5 File Formats +.Os +.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc) .\" .\" $FreeBSD$ .\" -.Dd December 21, 2006 -.Dt NTP.CONF 5 -.Os +.\" It has been AutoGen-ed February 4, 2015 at 02:42:07 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntp.conf.def +.\" and the template file agmdoc-cmd.tpl .Sh NAME .Nm ntp.conf -.Nd Network Time Protocol (NTP) daemon configuration file +.Nd Network Time Protocol (NTP) daemon configuration file format .Sh SYNOPSIS -.Nm /etc/ntp.conf +.Nm +.Op Fl \-option\-name +.Op Fl \-option\-name Ar value +.Pp +All arguments must be options. +.Pp .Sh DESCRIPTION The .Nm @@ -24,16 +33,6 @@ but could be installed elsewhere .Fl c command line option). .Pp -The -.Pa /etc/rc.d/ntpdate -script reads this file to get a list of NTP servers to use if the -variable -.Dq Li ntpdate_hosts -was not declared. -Refer to the -.Xr rc.conf 5 -man page for further info about this. -.Pp The file format is similar to other .Ux configuration files. @@ -46,13 +45,13 @@ 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, +host addresses written in numeric, dotted\-quad form, integers, floating point numbers (when specifying times in seconds) and text strings. .Pp The rest of this page describes the configuration and control options. The -.Qq Notes on Configuring NTP and Setting up a NTP Subnet +.Qq Notes on Configuring NTP and Setting up an NTP Subnet page (available as part of the HTML documentation provided in @@ -81,6 +80,7 @@ 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 @@ -110,7 +110,7 @@ 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) +If the Basic Socket Interface Extensions for IPv6 (RFC\-2553) is detected, support for the IPv6 address family is generated in addition to the default support of the IPv4 address family. In a few cases, including the reslist billboard generated @@ -133,6 +133,14 @@ 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 @@ -166,12 +174,12 @@ equivalent classes for that address family. .Xc .El .Pp -These four commands specify the time server name or address to +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. +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 @@ -179,6 +187,12 @@ page 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 @@ -192,7 +206,7 @@ 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 +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 @@ -268,7 +282,7 @@ Options: 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 Commands . +.Sx Authentication Options . .It Cm burst when the server is reachable, send a burst of eight packets instead of the usual one. @@ -305,7 +319,7 @@ 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. +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 @@ -317,7 +331,7 @@ the option to a lower limit of 4 (16 s). .It Cm noselect Marks the server as unused, except for display purposes. -The server is discarded by the selection algorithm. +The server is discarded by the selection algroithm. .It Cm prefer Marks the server as preferred. All other things being equal, @@ -333,7 +347,7 @@ for further information. .It Cm ttl Ar ttl This option is used only with broadcast server and manycast client modes. -It specifies the time-to-live +It specifies the time\-to\-live .Ar ttl to use on broadcast server and multicast server and the maximum @@ -346,7 +360,7 @@ 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 +Versions 1\-4 are the choices, with version 4 the default. .El .Ss Auxiliary Commands @@ -361,9 +375,9 @@ 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 +server and client should operate using symmetric\-key or public\-key authentication as described in -.Sx Authentication Commands . +.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. @@ -374,9 +388,9 @@ 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 +and client should operate using symmetric\-key or public\-key authentication as described in -.Sx Authentication Commands . +.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. @@ -387,24 +401,38 @@ 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 Commands . +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 +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. +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 +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 @@ -466,7 +494,7 @@ 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. +credentials and initialize the protocol .Pp The .Cm auth @@ -525,9 +553,9 @@ cryptography are summarized below; further details are in the briefings, papers and reports at the NTP project page linked from .Li http://www.ntp.org/ . -.Ss Symmetric-Key Cryptography -The original RFC-1305 specification allows any one of possibly -65,534 keys, each distinguished by a 32-bit key identifier, to +.Ss Symmetric\-Key Cryptography +The original RFC\-1305 specification allows any one of possibly +65,534 keys, each distinguished by a 32\-bit key identifier, to authenticate an association. The servers and clients involved must agree on the key and key identifier to @@ -575,7 +603,7 @@ command selects the key used as the password for the utility. .Ss Public Key Cryptography NTPv4 supports the original NTPv3 symmetric key scheme -described in RFC-1305 and in addition the Autokey protocol, +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 @@ -603,8 +631,8 @@ 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 +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 @@ -614,7 +642,7 @@ page. The specific cryptographic environment used by Autokey servers and clients is determined by a set of files and soft links generated by the -.Xr ntp-keygen 8 +.Xr ntp\-keygen 1ntpkeygenmdoc program. This includes a required host key file, required certificate file and optional sign key file, @@ -669,7 +697,7 @@ 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 +includes the source and destinatino IP addresses in message digest computations and so the same addresses must be available at both the server and client. For this reason operation @@ -744,9 +772,11 @@ 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 +Bob sends Cathy a thing called a crypto\-NAK, which tells her something broke. -She can see the evidence using the ntpq program. +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. @@ -766,7 +796,7 @@ with one server and no authentication with another might not be wise. .Ss Key Management The cryptographic values used by the Autokey protocol are incorporated as a set of files generated by the -.Xr ntp-keygen 8 +.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. @@ -783,7 +813,7 @@ The remaining files are necessary only for the Autokey protocol. .Pp Certificates imported from OpenSSL or public certificate -authorities have certain limitations. +authorities have certian limitations. The certificate should be in ASN.1 syntax, X.509 Version 3 format and encoded in PEM, which is the same format used by OpenSSL. @@ -796,7 +826,7 @@ 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 . +.Cm trustRoot ; . Other extension fields are ignored. .Ss Authentication Commands .Bl -tag -width indent @@ -814,7 +844,7 @@ sent. Specifies the key identifier to use with the .Xr ntpq 8 utility, which uses the standard -protocol defined in RFC-1305. +protocol defined in RFC\-1305. The .Ar key argument is @@ -904,7 +934,7 @@ containing the keys and key identifiers used by .Xr ntpd 8 , .Xr ntpq 8 and -.Xr ntpdc +.Xr ntpdc 8 when operating with symmetric key cryptography. This is the same operation as the .Fl k @@ -926,11 +956,11 @@ argument is a key identifier for the trusted key, where the value can be in the range 1 to 65,534, inclusive. .It Ic revoke Ar logsec -Specifies the interval between re-randomization of certain +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; +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 @@ -950,7 +980,7 @@ purpose, although different keys can be used with different servers. The .Ar key -arguments are 32-bit unsigned +arguments are 32\-bit unsigned integers with values from 1 to 65,534. .El .Ss Error Codes @@ -1029,7 +1059,7 @@ automatically summarized and archived for retrospective analysis. .Bl -tag -width indent .It Ic statistics Ar name ... Enables writing of statistics records. -Currently, four kinds of +Currently, eight kinds of .Ar name statistics are supported. .Bl -tag -width indent @@ -1046,7 +1076,7 @@ the file generation set named 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. +clock address in dotted\-quad notation. The final field shows the last timecode received from the clock in decoded ASCII format, where meaningful. @@ -1068,11 +1098,10 @@ following form to the file generation set named 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 +address in dotted\-quad notation, The final message field includes the message type and certain ancillary information. See the -.Sx Authentication Commands +.Sx Authentication Options section for further information. .It Cm loopstats Enables recording of loop filter statistics information. @@ -1087,7 +1116,7 @@ the file generation set named 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 - +show time offset (seconds), frequency offset (parts per million \- PPM), RMS jitter (seconds), Allan deviation (PPM) and clock discipline time constant. .It Cm peerstats @@ -1100,20 +1129,20 @@ 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 +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, +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. +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. @@ -1129,7 +1158,7 @@ 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. +in dotted\-quad notation. The final four fields show the originate, receive, transmit and final NTP timestamps in order. The timestamp @@ -1156,7 +1185,7 @@ 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. +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 @@ -1227,7 +1256,7 @@ modifications via the .Ar filegen option. It is defined by the -server, usually specified as a compile-time constant. +server, usually specified as a compile\-time constant. It may, however, be configurable for individual file generation sets via other commands. @@ -1293,7 +1322,7 @@ and a day specification in the form .Cm YYYYMMdd . .Cm YYYY -is a 4-digit year number (e.g., 1992). +is a 4\-digit year number (e.g., 1992). .Cm MM is a two digit month number. .Cm dd @@ -1305,21 +1334,21 @@ in a file named .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 +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 +filename base: A dot, a 4\-digit year number, the letter .Cm W , -and a 2-digit week number. +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. +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 @@ -1330,9 +1359,9 @@ 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. +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. +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 @@ -1369,7 +1398,7 @@ The daemon implements a general purpose address/mask based restriction list. The list contains address/match entries sorted first -by increasing address values and then by increasing mask values. +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. @@ -1406,11 +1435,11 @@ 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. +an indefinate period. When a client or network is denied access -for an indefinite period, the only way at present to remove +for an indefinate period, the only way at present to remove the restrictions is by restarting the server. -.Ss The Kiss-of-Death Packet +.Ss The Kiss\-of\-Death Packet Ordinarily, packets denied service are simply dropped with no further action except incrementing statistics counters. Sometimes a @@ -1418,9 +1447,9 @@ 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. +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 +to zero and the reference identifier field set to a four\-byte ASCII code. If the .Cm noserve @@ -1462,12 +1491,12 @@ subcommand specifies the minimum average packet spacing, while the .Cm minimum subcommand specifies the minimum packet spacing. -Packets that violate these minimum are discarded -and a kiss-o'-death packet returned if enabled. +Packets that violate these minima are discarded +and a kiss\-o'\-death packet returned if enabled. The default minimum average and minimum are 5 and 2, respectively. The monitor subcommand specifies the probability of discard -for packets that overflow the rate-control window. +for packets that overflow the rate\-control window. .It Xo Ic restrict address .Op Cm mask Ar mask .Op Ar flag ... @@ -1475,13 +1504,13 @@ for packets that overflow the rate-control window. The .Ar address argument expressed in -dotted-quad form is the address of a host or network. +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 +argument expressed in dotted\-quad form defaults to .Cm 255.255.255.255 , meaning that the .Ar address @@ -1505,7 +1534,7 @@ 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 +restrict informational queries and attempts to do run\-time reconfiguration of the server. One or more of the following flags may be specified: @@ -1517,7 +1546,7 @@ and .Xr ntpdc 8 queries. .It Cm kod -If this flag is set when an access violation occurs, a kiss-o'-death +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. @@ -1564,6 +1593,18 @@ Deny packets which would result in mobilizing a new association. This includes broadcast and symmetric active packets when a configured association does not exist. +It 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 +.It not +include the +.Cm nopeer +directive. .It Cm noserve Deny all packets except .Xr ntpq 8 @@ -1586,7 +1627,7 @@ UDP port (123). Both .Cm ntpport and -.Cm non-ntpport +.Cm non\-ntpport may be specified. The @@ -1621,7 +1662,7 @@ 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, +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 @@ -1650,7 +1691,7 @@ 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 +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 @@ -1680,7 +1721,7 @@ 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 +in a volley of eight client/server at 2\-s intervals during which both the synchronization and cryptographic protocols run concurrently. Following the volley, @@ -1693,7 +1734,7 @@ 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 +and the effects of implosion due to near\-simultaneous arrival of manycast server messages. The strategy is determined by the .Ic manycastclient , @@ -1776,7 +1817,7 @@ 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 will find only primary servers +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 @@ -1859,7 +1900,7 @@ 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. +re\-associate accordingly. .Pp Some administrators prefer to avoid running .Xr ntpd 8 @@ -1956,7 +1997,7 @@ 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 outerlayer +The clustering algorithm repeatedly casts out outlyer associations until no more than .Cm minclock associations remain. @@ -1966,7 +2007,7 @@ 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 true chimers for the clustering algorithm. +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 @@ -1981,13 +2022,13 @@ a single falseticker. 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. +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 +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 @@ -2007,7 +2048,7 @@ 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 +.Qq Pulse\-per\-second (PPS) Signal Interfacing page (available as part of the HTML documentation provided in @@ -2057,7 +2098,7 @@ is an integer denoting the clock type and .Ar u indicates the unit -number in the range 0-3. +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. @@ -2117,7 +2158,7 @@ and 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 +device\-dependent time offsets and four flags that can be included in the .Ic fudge command as well. @@ -2134,7 +2175,7 @@ The .Cm stratum option is used for this purpose. Also, in cases -involving both a reference clock and a pulse-per-second (PPS) +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 @@ -2171,7 +2212,7 @@ provided in for further information. .It Cm mode Ar int Specifies a mode number which is interpreted in a -device-specific fashion. +device\-specific fashion. For instance, it selects a dialing protocol in the ACTS driver and a device subtype in the parse @@ -2221,7 +2262,7 @@ 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. +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 @@ -2249,8 +2290,8 @@ page 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. +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 @@ -2271,7 +2312,7 @@ 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. +device\-specific fashion. For instance, it selects a dialing protocol in the ACTS driver and a device subtype in the parse @@ -2338,7 +2379,7 @@ 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). +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. @@ -2351,16 +2392,16 @@ otherwise, should be avoided. .Oo .Cm auth | Cm bclient | .Cm calibrate | Cm kernel | -.Cm monitor | Cm ntp | -.Cm pps | Cm stats +.Cm mode7 | monitor | +.Cm ntp | 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 +.Cm mode7 | monitor | +.Cm ntp | Cm stats .Oc .Xc Provides a way to enable or disable various server options. @@ -2396,6 +2437,19 @@ 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 @@ -2414,17 +2468,6 @@ closes the feedback loop, which is useful for testing. The default for this flag is .Ic enable . -.It Cm pps -Enables the pulse-per-second (PPS) signal when frequency and time is -disciplined by the precision time kernel modifications. -See the -.Qq A Kernel Model for Precision Timekeeping -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) -page for further information. -The default for this flag is -.Ic disable . .It Cm stats Enables the statistics facility. See the @@ -2458,7 +2501,7 @@ keywords can be prefixed with .Ql = , .Ql + and -.Ql - , +.Ql \- , where .Ql = sets the @@ -2466,7 +2509,7 @@ sets the priority mask, .Ql + adds and -.Ql - +.Ql \- removes messages. .Xr syslog 3 @@ -2531,7 +2574,7 @@ This command specifies the location of an alternate log file to be used instead of the default system .Xr syslog 3 facility. -This is the same operation as the -l command line option. +This is the same operation as the \-l command line option. .It Ic setvar Ar variable Op Cm default This command adds an additional system variable. These @@ -2611,12 +2654,12 @@ 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. +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 +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). @@ -2644,6 +2687,29 @@ be set to any positive number in seconds. If set to zero, the stepout pulses will not be suppressed. .El +.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 can be allocated. +Probably only available under Linux, this option is useful +when dropping root (the +.Fl i +option). +The default is 32 megabytes. Setting this to zero will prevent any attemp to lock memory. +.It Cm stacksize Ar N4kPages +Specifies the maximum size of the process stack on systems with the +.It Cm filenum Ar Nfiledescriptors +Specifies the maximum number of file descriptors ntpd may have open at once. Defaults to the system default. +.Fn mlockall +function. +Defaults to 50 4k pages (200 4k pages in OpenBSD). +.El .It Xo Ic trap Ar host_address .Op Cm port Ar port_number .Op Cm interface Ar interface_address @@ -2669,10 +2735,30 @@ is started. 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. +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_<option\-name>\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 @@ -2684,10 +2770,20 @@ RSA private key .It Pa ntpkey_ Ns Ar host RSA public key .It Pa ntp_dh -Diffie-Hellman agreement parameters +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 rc.conf 5 , +.Sh "SEE ALSO" .Xr ntpd 8 , .Xr ntpdc 8 , .Xr ntpq 8 @@ -2700,9 +2796,14 @@ A snapshot of this documentation is available in HTML format in .Pa /usr/share/doc/ntp . .Rs .%A David L. Mills -.%T Network Time Protocol (Version 3) -.%O RFC1305 +.%T Network Time Protocol (Version 4) +.%O RFC5905 .Re +.Sh "AUTHORS" +The University of Delaware and Network Time Foundation +.Sh "COPYRIGHT" +Copyright (C) 1992\-2015 The University of Delaware and Network Time Foundation all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. .Sh BUGS The syntax checking is not picky; some combinations of ridiculous and even hilarious options and modes may not be @@ -2714,3 +2815,10 @@ 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 index dc9531c..4ec3bb3 100644 --- a/usr.sbin/ntp/doc/ntp.keys.5 +++ b/usr.sbin/ntp/doc/ntp.keys.5 @@ -1,25 +1,37 @@ +.Dd February 4 2015 +.Dt NTP_KEYS 5 File Formats +.Os SunOS 5.10 +.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc) .\" .\" $FreeBSD$ .\" -.Dd January 13, 2000 -.Dt NTP.KEYS 5 -.Os +.\" $FreeBSD$ +.\" +.\" It has been AutoGen-ed February 4, 2015 at 02:42:10 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntp.keys.def +.\" and the template file agmdoc-file.tpl .Sh NAME .Nm ntp.keys -.Nd NTP daemon key file format +.Nd NTP symmetric key file format + +.Sh NAME +.Nm ntp.keys +.Nd NTP symmetric key file format .Sh SYNOPSIS -.Nm /etc/ntp.keys +.Nm +.Op Fl \-option\-name +.Op Fl \-option\-name Ar value +.Pp +All arguments must be options. +.Pp .Sh DESCRIPTION -Following is a description of the format of NTP key files. -For a description of the use of these files, see the +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 -In the case of DES, the keys are 56 bits long with, -depending on type, a parity check on each byte. -In the case of MD5, the keys are 64 bits (8 bytes). .Xr ntpd 8 reads its keys from a file specified using the .Fl k @@ -29,7 +41,7 @@ statement in the configuration file. While key number 0 is fixed by the NTP standard (as 56 zero bits) and may not be changed, -one or more of the keys numbered 1 through 15 +one or more keys numbered between 1 and 65534 may be arbitrarily set in the keys file. .Pp The key file uses the same comment conventions @@ -40,57 +52,51 @@ Key entries use a fixed format of the form .Pp where .Ar keyno -is a positive integer, +is a positive integer (between 1 and 65534), .Ar type -is a single character which defines the key format, +is the message digest algorithm, and .Ar key is the key itself. .Pp The .Ar key -may be given in one of four different formats, +may be given in a format controlled by the .Ar type -character. -The four key types, and corresponding formats, -are listed following. -.Bl -tag -width X -.It Li S -The key is a 64-bit hexadecimal number in the format -specified in the DES specification; -that is, the high order seven bits of each octet are used -to form the 56-bit key -while the low order bit of each octet is given a value -such that odd parity is maintained for the octet. -Leading zeroes must be specified -(i.e., the key must be exactly 16 hex digits long) -and odd parity must be maintained. -Hence a zero key, in standard format, would be given as -.Ql 0101010101010101 . -.It Li N -The key is a 64-bit hexadecimal number in the format -specified in the NTP standard. -This is the same as the DES format, -except the bits in each octet have been rotated one bit right -so that the parity bit is now the high order bit of the octet. -Leading zeroes must be specified and odd parity must be maintained. -A zero key in NTP format would be specified as -.Ql 8080808080808080 . -.It Li A -The key is a 1-to-8 character ASCII string. -A key is formed from this by using the low order 7 bits -of each ASCII character in the string, -with zeroes added on the right -when necessary to form a full width 56-bit key, -in the same way that encryption keys are formed from -.Ux -passwords. -.It Li M -The key is a 1-to-8 character ASCII string, -using the MD5 authentication scheme. -Note that both the keys and the authentication schemes (DES or MD5) -must be identical between a set of peers sharing the same key number. +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 @@ -100,21 +106,57 @@ and 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_<option\-name>\fP or \fBNTP_KEYS\fP +.fi +.ad +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. .Sh FILES -.Bl -tag -width /etc/ntp.drift -compact +.Bl -tag -width /etc/ntp.keys -compact .It Pa /etc/ntp.keys the default name of the configuration file .El -.Sh SEE ALSO +.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 -.Sh BUGS -.Xr ntpd 8 -has gotten rather fat. -While not huge, it has gotten larger than might -be desirable for an elevated-priority daemon running on a workstation, -particularly since many of the fancy features which consume the space -were designed more with a busy primary server, rather than a high -stratum workstation, in mind. +.Xr ntpdc 8 , +.Xr sntp 8 +.Sh "AUTHORS" +The University of Delaware and Network Time Foundation +.Sh "COPYRIGHT" +Copyright (C) 1992\-2015 The University of Delaware and Network Time Foundation all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. +.Sh "BUGS" +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 index 069ef42..665aa0b 100644 --- a/usr.sbin/ntp/doc/ntpd.8 +++ b/usr.sbin/ntp/doc/ntpd.8 @@ -1,25 +1,24 @@ +.Dd February 4 2015 +.Dt NTPD 8 User Commands +.Os +.\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc) .\" .\" $FreeBSD$ .\" -.Dd May 18, 2010 -.Dt NTPD 8 -.Os +.\" It has been AutoGen-ed February 4, 2015 at 02:42:12 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntpd-opts.def +.\" and the template file agmdoc-cmd.tpl .Sh NAME .Nm ntpd -.Nd Network Time Protocol (NTP) daemon +.Nd NTP daemon program .Sh SYNOPSIS .Nm -.Op Fl aAbDdgLmnPqx -.Op Fl c Ar conffile -.Op Fl f Ar driftfile -.Op Fl k Ar keyfile -.Op Fl l Ar logfile -.Op Fl p Ar pidfile -.Op Fl r Ar broadcastdelay -.Op Fl s Ar statsdir -.Op Fl t Ar key -.Op Fl v Ar variable -.Op Fl V Ar variable +.\" 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 +[ <server1> ... <serverN> ] +.Pp .Sh DESCRIPTION The .Nm @@ -27,14 +26,15 @@ utility is an operating system daemon which sets and maintains the system time of day in synchronism with Internet standard time servers. It is a complete implementation of the -Network Time Protocol (NTP) version 4, but also retains -compatibility with version 3, as defined by RFC-1305, and version 1 -and 2, as defined by RFC-1059 and RFC-1119, respectively. +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 +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 @@ -82,154 +82,307 @@ utility programs. When .Nm starts it looks at the value of -.Cm umask 2 , +.Xr umask 2 , and if zero .Nm will set the -.Cm umask 2 +.Xr umask 2 to 022. -.Pp -The following options are available: -.Bl -tag -width indent -.It Fl a +.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 +.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 -Enable the client to synchronize to broadcast servers. -.It Fl c Ar conffile -Specify the name and path of the configuration file, default -.Pa /etc/ntp.conf . -.It Fl d -Specify debugging mode. -This option may occur more than once, -with each occurrence indicating greater detail of display. -You need to compile -.Nm -with DEBUG in order to use this. -.It Fl D Ar level -Specify debugging level directly. -.It Fl f Ar driftfile -Specify the name and path of the frequency file, default -.Pa /etc/ntp.drift . +.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 -.Ic driftfile Ar driftfile -configuration command. -.It Fl g +\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, -.Nm -exits with a message to the system log if the offset exceeds -the panic threshold, which is 1000 s by default. -This option allows the time to be set to any value without restriction; -however, this can happen only once. -If the threshold is exceeded after that, -.Nm -will exit with a message to the system log. -This option can be used with the -.Fl q +\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 -.Fl x +\fB\-x\fP options. See the -.Ic tinker -command for other options. -.It Fl k Ar keyfile -Specify the name and path of the symmetric key file, default -.Pa /etc/ntp.keys . +\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 -.Ic keys Ar keyfile -configuration command. -.It Fl l Ar logfile +\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 -.Ic logfile Ar logfile -configuration command. -.It Fl L -Do not listen to virtual IPs. -The default is to listen. -.It Fl m -Enable the client to synchronize to multicast servers at the IPv4 multicast -group address 224.0.1.1. -.It Fl n +\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. -.It Fl N -To the extent permitted by the operating system, run the -.Nm +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 pidfile -Specify the name and path of the file used to record the -.Nm +.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 -.Ic pidfile Ar pidfile -configuration command. -.It Fl P Ar priority -To the extent permitted by the operating system, run the -.Nm -at the specified priority. -.It Fl q -Exit the -.Nm -just after the first time the clock is -set. -This behavior mimics that of the -.Xr ntpdate 8 -program, -which is to be retired. +\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 -.Fl g +\fB\-g\fP and -.Fl x -options can -be used with this option. +\fB\-x\fP +options can be used with this option. Note: The kernel time discipline is disabled with this option. -.It Fl r Ar broadcastdelay -Specify the default propagation delay from the -broadcast/multicast server to this client. -This is necessary -only if the delay cannot be computed automatically by the -protocol. -.It Fl s Ar statsdir -Specify the directory path for files created by the statistics -facility. +.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 -.Ic statsdir Ar statsdir -configuration command. -.It Fl t Ar key -Add a key number to the trusted key list. -This option can occur more than once. -.It Fl v Ar variable -.It Fl V Ar variable -Add a system variable listed by default. -.It Fl x -Normally, the time is slewed if the offset is less than the -step threshold, which is 128 ms by default, and stepped if above -the threshold. -This option sets the threshold to 600 s, -which is well within the accuracy window to set the clock manually. -Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, -each second of adjustment requires an amortization interval of 2000 s. +\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 -.Fl g +\fB\-g\fP and -.Fl q +\fB\-q\fP options. See the -.Ic tinker -command for other options. +\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_<option\-name>\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 at designated poll intervals. +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 @@ -241,7 +394,8 @@ an interval randomized over a few seconds. At the default initial poll interval of 64s, several minutes can elapse before the clock is set. -The initial delay to set the clock can be reduced using the +This initial delay to set the clock +can be safely and dramatically reduced using the .Cm iburst keyword with the .Ic server @@ -250,19 +404,23 @@ 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 +time\-of\-year (TOY) chip to maintain the time during periods when the power is off. When the machine is booted, the chip is used to initialize the operating system time. After the machine has synchronized to a NTP server, the operating system corrects the chip from time to time. -In case there is no TOY chip or for some -reason its time is more than 1000s from the server time, +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 @@ -270,10 +428,12 @@ 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. +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 +clock has been set an error greater than 1000s will cause .Nm to exit anyway. .Pp @@ -284,7 +444,7 @@ 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 +the synchronization distance, which is equal to one\-half the roundtrip delay plus error budget terms, can become very large. The .Nm @@ -297,27 +457,30 @@ 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 +As the result of this behavior, once the clock has been set it +very rarely strays more than 128 ms even under extreme cases of network path congestion and jitter. Sometimes, in particular when .Nm -is first started, the error might exceed 128 ms. -This -may on occasion cause the clock to be set backwards if the local -clock time is more than 128 s in the future relative to the server. +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. -.Pp -The issues should be carefully explored before deciding to use +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 +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 @@ -330,7 +493,7 @@ 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 +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 @@ -343,7 +506,7 @@ 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. @@ -351,7 +514,71 @@ It helps in these cases to use the .Cm burst keyword when -configuring the server. +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 +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 . +.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 @@ -397,12 +624,12 @@ provided in 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 +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 +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 @@ -427,16 +654,17 @@ to 1024s in order to reduce network overhead. .Pp In some cases it may not be practical for .Nm -to run -continuously. +to run continuously. A common workaround has been to run the .Xr ntpdate 8 -program from a +or +.Xr sntp 8 +programs from a .Xr cron 8 job at designated times. -However, this program does not have the crafted signal -processing, error checking and mitigation algorithms of +However, these programs do not have the crafted signal +processing, error checking or mitigation algorithms of .Nm . The .Fl q @@ -460,7 +688,7 @@ couple of minutes, the daemon times out and exits. After a suitable period of mourning, the .Xr ntpdate 8 -program may be +program will be retired. .Pp When kernel support is available to discipline the clock @@ -478,7 +706,7 @@ the frequency and offset to settle down. Then the .Nm is -stopped and run in one-time mode as required. +stopped and run in one\-time mode as required. At each startup, the frequency is read from the file and initializes the kernel frequency. @@ -529,7 +757,7 @@ 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" +.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. @@ -540,7 +768,7 @@ 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 +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. @@ -563,6 +791,8 @@ 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 @@ -572,11 +802,23 @@ the default name of the drift file .It Pa /etc/ntp.keys the default name of the key file .El -.Sh SEE ALSO +.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 ntpq 8 , +.Xr sntp 8 .Pp In addition to the manual pages provided, comprehensive documentation is available on the world wide web @@ -599,14 +841,53 @@ A snapshot of this documentation is available in HTML format in .%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\-2015 The University of Delaware and Network Time Foundation all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. .Sh BUGS The .Nm utility has gotten rather fat. While not huge, it has gotten -larger than might be desirable for an elevated-priority +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 index 35ea7aa..3373614 100644 --- a/usr.sbin/ntp/doc/ntpdc.8 +++ b/usr.sbin/ntp/doc/ntpdc.8 @@ -1,25 +1,38 @@ +.Dd February 4 2015 +.Dt NTPDC 8 User Commands +.Os +.\" EDIT THIS FILE WITH CAUTION (ntpdc-opts.mdoc) .\" .\" $FreeBSD$ .\" -.Dd May 17, 2006 -.Dt NTPDC 8 -.Os +.\" It has been AutoGen-ed February 4, 2015 at 02:42:44 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntpdc-opts.def +.\" and the template file agmdoc-cmd.tpl .Sh NAME .Nm ntpdc -.Nd special NTP query program +.Nd vendor-specific NTPD control program .Sh SYNOPSIS .Nm -.Op Fl 46ilnps -.Op Fl c Ar command -.Op Ar host -.Op Ar ... +.\" 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 -The .Nm -utility is used to query the +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 -daemon about its +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. @@ -31,51 +44,103 @@ In addition, nearly all the configuration options which can be specified at startup using ntpd's configuration file may also be specified at run time using .Nm . -.Pp -The following options are available: -.Bl -tag -width indent -.It Fl 4 -Force DNS resolution of following host names on the command line to the -IPv4 namespace. -.It Fl 6 -Force DNS resolution of following host names on the command line to the -IPv6 namespace. -.It Fl c Ar command -The following argument is interpreted as an interactive format -command and is added to the list of commands to be executed on the -specified host(s). -Multiple -.Fl c -options may be given. -.It Fl i -Force -.Nm -to operate in interactive mode. -Prompts -will be written to the standard output and commands read from the -standard input. -.It Fl l -Obtain a list of peers which are known to the server(s). -This -switch is equivalent to -.Ql Fl c Ar listpeers . -.It Fl n -Output all host addresses in dotted-quad numeric format rather -than converting to the canonical host names. -.It Fl p -Print a list of the peers known to the server as well as a -summary of their state. -This is equivalent to -.Ql Fn c Ar peers . -.It Fl s -Print a list of the peers known to the server as well as a -summary of their state, but in a slightly different format than the -.Fl p -switch. -This is equivalent to -.Ql Fl c Ar dmpeers . +.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 -.Pp +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from configuration ("RC" or ".INI") file(s) and values from +environment variables named: +.nf + \fBNTPDC_<option\-name>\fP or \fBNTPDC\fP +.fi +.ad +The environmental presets take precedence (are processed later than) +the configuration files. +The \fIhomerc\fP files are "\fI$HOME\fP", and "\fI.\fP". +If any of these are directories, then the file \fI.ntprc\fP +is searched for within those directories. +.Sh USAGE If one or more request options are included on the command line when .Nm @@ -231,7 +296,7 @@ a timeout will be twice the timeout value set. .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 +These are read\-only commands in that they make no modification of the server configuration state. .Bl -tag -width indent @@ -258,7 +323,7 @@ entry is operating in. A .Ql \&+ denotes symmetric active, a -.Ql \&- +.Ql \&\- indicates symmetric passive, a .Ql \&= means the @@ -267,6 +332,8 @@ remote server is being polled in client mode, a 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. @@ -279,7 +346,7 @@ name with its parameter or On .Ic hostnames .Cm no -only IP-addresses +only IP\-addresses will be displayed. .It Ic dmpeers A slightly different peer summary list. @@ -307,15 +374,15 @@ 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 +Show per\-peer statistic counters associated with the specified peer(s). -.It Ic clockinfo Ar clock_peer_address Oo Ar ... Oc +.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. +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 @@ -329,12 +396,12 @@ 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 +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 +phase\-lock loop and thus the speed at which it can adapt to oscillator drift. The .Sq watchdog timer @@ -354,7 +421,7 @@ default. 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. +in the NTP Version 3 specification, RFC\-1305. .Pp The .Sq system flags @@ -428,7 +495,7 @@ module. Print statistics counters related to memory allocation code. .It Ic iostats -Print statistics counters maintained in the input-output +Print statistics counters maintained in the input\-output module. .It Ic timerstats Print statistics counters maintained in the timer/event queue @@ -487,7 +554,7 @@ 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 +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 @@ -523,7 +590,7 @@ The 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 +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 @@ -547,7 +614,7 @@ The 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 +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 @@ -607,9 +674,9 @@ Enables the kernel time discipline, if available. The default for this flag is enable if support is available, otherwise disable. .It Cm monitor Enables the monitoring facility. -See the -.Xr ntpdc 8 . -program and the monlist command or further information. +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. @@ -617,7 +684,7 @@ 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 +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 @@ -694,7 +761,24 @@ for further information. Clear the statistics counters in various modules of the server. See the source listing for further information. .El -.Sh SEE ALSO +.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 @@ -702,6 +786,11 @@ See the source listing for further information. .%T Network Time Protocol (Version 3) .%O RFC1305 .Re +.Sh AUTHORS +The formatting directives in this document came from FreeBSD. +.Sh "COPYRIGHT" +Copyright (C) 1992\-2015 The University of Delaware and Network Time Foundation all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. .Sh BUGS The .Nm @@ -713,3 +802,10 @@ 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 index 0a47c76..1eba486 100644 --- a/usr.sbin/ntp/doc/ntpq.8 +++ b/usr.sbin/ntp/doc/ntpq.8 @@ -1,39 +1,44 @@ +.Dd February 4 2015 +.Dt NTPQ 8 User Commands +.Os +.\" EDIT THIS FILE WITH CAUTION (ntpq-opts.mdoc) .\" .\" $FreeBSD$ .\" -.Dd May 17, 2006 -.Dt NTPQ 8 -.Os +.\" It has been AutoGen-ed February 4, 2015 at 02:43:19 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntpq-opts.def +.\" and the template file agmdoc-cmd.tpl .Sh NAME .Nm ntpq .Nd standard NTP query program .Sh SYNOPSIS .Nm -.Op Fl inp -.Op Fl c Ar command -.Op Ar host -.Op Ar ... +.\" 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 The .Nm -utility is used to monitor NTP daemon -.Xr ntpd 8 -operations and determine performance. -It uses the standard NTP mode 6 control message formats -defined in Appendix B of the NTPv3 specification RFC1305. -The same formats are used in NTPv4, although some of the variables -have changed and new ones added. -The description on this page is for the NTPv4 variables. -.Pp -The program can be run either in interactive mode or controlled -using command line arguments. -Requests to read and write arbitrary variables can be assembled, -with raw and pretty-printed output options being available. +utility program is used to query NTP servers which +implement the standard NTP mode 6 control message formats defined +in Appendix B of the NTPv3 specification RFC1305, requesting +information about current state and/or changes in that state. +The same formats are used in NTPv4, although some of the +variables have changed and new ones added. The description on this +page is for the NTPv4 variables. +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 -can also obtain and print a list of peers in a common format -by sendingmultiple queries to the server. -.Pp +utility can also obtain and print a +list of peers in a common format by sending multiple queries to the +server. If one or more request options is included on the command line when .Nm @@ -51,10 +56,8 @@ The .Nm utility will prompt for commands if the standard input is a terminal device. -.Pp -The .Nm -utility uses NTP mode 6 packets to communicate with the +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 @@ -66,55 +69,6 @@ utility makes one attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable timeout time. -.Pp -For examples and usage, see the -.Qq NTP Debugging Techniques -page -(available as part of the HTML documentation -provided in -.Pa /usr/share/doc/ntp ) . -.Pp -The following options are available: -.Bl -tag -width indent -.It Fl 4 -Force DNS resolution of following host names on the command line to the -IPv4 namespace. -.It Fl 6 -Force DNS resolution of following host names on the command line to the -IPv6 namespace. -.It Fl c -The following argument is interpreted as an interactive format -command and is added to the list of commands to be executed on the -specified host(s). -Multiple -.Fl c -options may be given. -.It Fl d -Turn on debugging mode. -.It Fl i -Force -.Nm -to operate in interactive mode. -Prompts -will be written to the standard output and commands read from the -standard input. -.It Fl n -Output all host addresses in dotted-quad numeric format rather -than converting to the canonical host names. -.It Fl p -Print a list of the peers known to the server as well as a -summary of their state. -This is equivalent to the -.Ic peers -interactive command. -.El -.Pp -Note that in contexts where a host name is expected, a -.Fl 4 -qualifier preceding the host name forces DNS resolution to the -IPv4 namespace, while a -.Fl 6 -qualifier forces DNS resolution to the IPv6 namespace. Specifying a command line option other than .Fl i @@ -132,11 +86,6 @@ Interactive format commands consist of a keyword followed by zero to four arguments. Only enough characters of the full keyword to uniquely identify the command need be typed. -The output of a -command is normally sent to the standard output, but optionally the -output of individual commands may be sent to a file by appending a -.Ql \&> , -followed by a file name, to the command line. A number of interactive format commands are executed entirely within the @@ -144,16 +93,16 @@ the utility itself and do not result in NTP mode 6 requests being sent to a server. These are described following. -.Bl -tag -width indent -.It Ic \&? Op Ar command_keyword +.Bl -tag -width "? [command_keyword]" -compact -offset indent +.It Ic ? Op Ar command_keyword .It Ic help Op Ar command_keyword A -.Sq Ic \&? +.Ql \&? by itself will print a list of all the command keywords known to this incarnation of .Nm . A -.Sq Ic \&? +.Ql \&? followed by a command keyword will print function and usage information about the command. This command is probably a better @@ -161,11 +110,12 @@ source of information about .Nm than this manual page. -.It Xo Ic addvars -.Ar variable_name Ns Op = Ns Ar value ... +.It Ic addvars Ar variable_name Ns Xo Op Ic =value +.Ic ... .Xc -.It Ic rmvars Ar variable_name ... +.It Ic rmvars Ar variable_name Ic ... .It Ic clearvars +.It Ic showvars The data carried by NTP mode 6 messages consists of a list of items of the form .Ql variable_name=value , @@ -186,7 +136,7 @@ The 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. +be comma\-separated and not contain white space. The .Ic rmvars command can be used to remove individual variables from the list, @@ -194,6 +144,32 @@ while the .Ic clearlist command removes all variables from the list. +The +.Ic showvars +command displays the current list of optional variables. +.It Ic authenticate Op yes | no +Normally +.Nm +does not authenticate requests unless +they are write requests. +The command +.Ql authenticate yes +causes +.Nm +to send authentication with all requests it +makes. +Authenticated requests causes some servers to handle +requests slightly differently, and can occasionally melt the CPU in +fuzzballs if you turn authentication on before doing a +.Ic peer +display. +The command +.Ql authenticate +causes +.Nm +to display whether or not +.Nm +is currently autheinticating requests. .It Ic cooked Causes output from query commands to be "cooked", so that variables which are recognized by @@ -202,15 +178,19 @@ will have their values reformatted for human consumption. Variables which .Nm -thinks should have a decodable value but did not are +thinks should have a decodable value but didn't are marked with a trailing .Ql \&? . -.It Xo Ic debug +.It Xo +.Ic debug +.Oo .Cm more | .Cm less | .Cm off +.Oc .Xc -Turns internal query program debugging on and off. +With no argument, displays the current debug level. +Otherwise, the debug level is changed to the indicated level. .It Ic delay Ar milliseconds Specify a time interval to be added to timestamps included in requests which require authentication. @@ -220,11 +200,14 @@ 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 exit +Exit +.Nm . .It Ic host Ar hostname Set the host to which future queries will be sent. -Hostname may -be either a host name or a numeric address. -.It Ic hostnames Cm yes | Cm no +.Ar 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 @@ -240,36 +223,64 @@ modified using the command line .Fl n switch. .It Ic keyid Ar keyid -This command specifies the key number to be used to authenticate -configuration requests. -This must correspond to a key number the server has -been configured to use for this purpose. -.It Xo Ic ntpversion +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 keytype Xo Oo +.Cm md5 | +.Cm OpenSSLDigestType +.Oc +.Xc +Specify the type of key to use for authenticating requests. +.Cm md5 +is alway supported. +If +.Nm +was built with OpenSSL support, +any digest type supported by OpenSSL can also be provided. +If no argument is given, the current +.Ic keytype +is displayed. +.It Ic ntpversion Xo Oo .Cm 1 | .Cm 2 | .Cm 3 | .Cm 4 +.Oc .Xc Sets the NTP version number which .Nm claims in packets. -Defaults to 3, Note that mode 6 control messages (and -modes, for that matter) did not exist in NTP version 1. +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 for a password (which will not be echoed) which will -be used to authenticate configuration requests. -The password must -correspond to the key configured for NTP server for this purpose. +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. +.\" Not yet implemented. +.\" .It Ic poll +.\" .Op Ar n +.\" .Op Ic verbose +.\" Poll an NTP server in client mode +.\" .Ar n +.\" times. .It Ic quit Exit .Nm . .It Ic raw Causes all output from query commands is printed as received from the remote server. -The only formatting/interpretation done on +The only formating/interpretation done on the data is to transform nonascii data into a printable (but barely understandable) form. .It Ic timeout Ar milliseconds @@ -280,572 +291,666 @@ 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 +Print the version of the +.Nm +program. .El -.Ss Control Message Commands -Each association known to an NTP server has a 16 bit integer association -identifier. -NTP control messages which carry peer variables must identify the -peer the values correspond to by including its association ID. -An association -ID of 0 is special, and indicates the variables are system variables, whose -names are drawn from a separate name space. -.Pp -Control message commands result in one or more NTP mode 6 -messages being sent to the server, and cause the data returned to -be printed in some format. -Most commands currently implemented send -a single message and expect a single response. -The current -exceptions are the peers command, which will send a preprogrammed -series of messages to obtain the data it needs, and the mreadlist -and mreadvar commands, which will iterate over a range of -associations. -.Bl -tag -width indent -.It Ic associations -Obtains and prints a list of association identifiers and peer -statuses for in-spec peers of the server being queried. -The list is -printed in columns. -The first of these is an index numbering the -associations from 1 for internal use, the second the actual -association identifier returned by the server and the third the -status word for the peer. -This is followed by a number of columns -containing data decoded from the status word. -See the peers command -for a decode of the -.Sq condition -field. -Note that the data -returned by the -.Ic associations -command is cached internally -in -.Nm . -The index is then of use when dealing with stupid -servers which use association identifiers which are hard for humans -to type, in that for any subsequent commands which require an -association identifier as an argument, the form and index may be -used as an alternative. -.It Xo Ic clockvar Op Ar assocID -.Oo -.Ar variable_name Ns Op = Ns Ar value ... -.Oc -.Ar ... -.Xc -.It Xo Ic cv Op Ar assocID -.Oo -.Ar variable_name Ns Op = Ns Ar value ... -.Oc -.Ar ... -.Xc -Requests that a list of the server's clock variables be sent. -Servers which have a radio clock or other external synchronization -will respond positively to this. -If the association identifier is -omitted or zero the request is for the variables of the -.Sq system clock -and will generally get a positive response from all -servers with a clock. -If the server treats clocks as pseudo-peers, -and hence can possibly have more than one clock connected at once, -referencing the appropriate peer association ID will show the -variables of a particular clock. -Omitting the variable list will -cause the server to return a default variable display. +.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 mode\-6 message to the server and expect a single response message. +The exceptions are the +.Li peers +command, which sends a series of messages, +and the +.Li mreadlist +and +.Li mreadvar +commands, which iterate over a range of associations. +.Bl -tag -width "something" -compact -offset indent +.It Cm 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" ".Sy Description" +.It Sy String Ta Sy Description +.It Li ind Ta index on this list +.It Li assid Ta association ID +.It Li status Ta peer status word +.It Li conf Ta Li yes : persistent, Li no : ephemeral +.It Li reach Ta Li yes : reachable, Li no : unreachable +.It Li auth Ta Li ok , Li yes , Li bad and Li none +.It Li condition Ta selection status (see the Li select field of the peer status word) +.It Li last_event Ta event report (see the Li event field of the peer status word) +.It Li cnt Ta event count (see the Li count field of the peer status word) +.El +.It Cm authinfo +Display the authentication statistics. +.It Cm clockvar Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ... +.It Cm cv Ar assocID Oo Ar name Ns Oo Cm = Ns Ar value Oc Oc Op ... +Display a list of clock variables for those associations supporting a reference clock. +.It Cm :config Op ... +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 Cm config\-from\-file Ar filename +Send the each line of +.Ar filename +to the server as run\-time configuration commands in the same format as a line in the configuration file. This command is experimental until further notice and clarification. Authentication is required. +.It Ic ifstats +Display statistics for each local network address. Authentication is required. +.It Ic iostats +Display network and reference clock I/O statistics. +.It Ic kerninfo +Display kernel loop and PPS statistics. As with other ntpq output, times are in milliseconds. The precision value displayed is in milliseconds as well, unlike the precision system variable. .It Ic lassociations -Obtains and prints a list of association identifiers and peer -statuses for all associations for which the server is maintaining -state. -This command differs from the -.Ic associations -command -only for servers which retain state for out-of-spec client -associations (i.e., fuzzballs). -Such associations are normally -omitted from the display when the -.Ic associations -command is -used, but are included in the output of -.Ic lassociations . -.It Ic lpassociations -Print data for all associations, including out-of-spec client -associations, from the internally cached list of associations. -This -command differs from -.Ic passociations -only when dealing with -fuzzballs. -.It Ic lpeers -Like R peers, except a summary of all associations for which -the server is maintaining state is printed. -This can produce a much -longer list of peers from fuzzball servers. -.It Ic mreadlist Ar assocID Ar assocID -.It Ic mrl Ar assocID Ar assocID -Like the -.Ic readlist -command, except the query is done -for each of a range of (nonzero) association IDs. -This range is -determined from the association list cached by the most recent -.Ic associations -command. -.It Xo Ic mreadvar Ar assocID Ar assocID -.Oo -.Ar variable_name Ns Op = Ns Ar value ... +Perform the same function as the associations command, except display mobilized and unmobilized associations. +.It Ic lopeers Xo +.Oo Ic \-4 | +.Ic \-6 .Oc .Xc -.It Xo Ic mrv Ar assocID Ar assocID -.Oo -.Ar variable_name Ns Op = Ns Ar value ... +Obtain and print a list of all peers and clients showing +.Ar dstadr +(associated with any given IP version). +.It Ic lpeers Xo +.Oo Ic \-4 | +.Ic \-6 .Oc .Xc -Like the +Print a peer spreadsheet for the appropriate IP version(s). +.Ar dstadr +(associated with any given IP version). +.It Ic monstats +Display monitor facility statistics. +.It Ic mrulist Oo Ic limited | Ic kod | Ic mincount Ns = Ns Ar count | Ic laddr Ns = Ns Ar localaddr | Ic sort Ns = Ns Ar sortorder | Ic resany Ns = Ns Ar hexmask | Ic resall Ns = Ns Ar hexmask Oc +Obtain and print traffic counts collected and maintained by the monitor facility. +With the exception of +.Cm sort Ns = Ns Ar sortorder , +the options filter the list returned by +.Cm ntpd. +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 any of +.Cm addr , +.Cm count , +.Cm avgint , +.Cm lstint , +or any of those preceded by a minus sign (hyphen) to reverse the sort order. +The output columns are: +.Bl -tag -width "something" -compact -offset indent +.It Column +Description +.It Ic lstint +Interval in s 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 +DNS name, numeric address, or address followed by +claimed DNS name which could not be verified in parentheses. +.El +.It Ic mreadvar assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ... +.It Ic mrv assocID assocID Oo Ar variable_name Ns Oo = Ns Ar value Oc Oc ... +Perform the same function as the .Ic readvar -command, except the query is done for -each of a range of (nonzero) association IDs. -This range is -determined from the association list cached by the most recent +command, except for a range of association IDs. +This range is determined from the association list cached by the most recent .Ic associations command. -.It Ic opeers -An old form of the -.Ic peers -command with the reference ID -replaced by the local interface address. +.It Ic opeers Xo +.Oo Ic \-4 | +.Ic \-6 +.Oc +.Xc +Obtain and print the old\-style list of all peers and clients showing +.Ar dstadr +(associated with any given IP version), +rather than the +.Ar refid . .It Ic passociations -Displays association data concerning in-spec peers from the -internally cached list of associations. -This command performs -identically to the +Perform the same function as the .Ic associations -except that it displays -the internally stored data rather than making a new query. +command, +except that it uses previously stored data rather than making a new query. .It Ic peers -Obtains a current list peers of the server, along with a -summary of each peer's state. -Summary information includes the -address of the remote peer, the reference ID (0.0.0.0 if this is -unknown), the stratum of the remote peer, the type of the peer -(local, unicast, multicast or broadcast), when the last packet was -received, the polling interval, in seconds, the reachability -register, in octal, and the current estimated delay, -offset and dispersion of the peer, all in milliseconds. -The character at the left margin of each line shows the -synchronization status of the association and is a valuable -diagnostic tool. -The encoding and meaning of this character, -called the tally code, is given later in this page. -.It Ic pstatus Ar assocID -Sends a read status request to the server for the given -association. -The names and values of the peer variables returned -will be printed. -Note that the status word from the header is -displayed preceding the variables, both in hexadecimal and in -pidgeon English. +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 Ic [tally] +single\-character code indicating current value of the +.Ic select +field of the +.Lk decode.html#peer "peer status word" +.It Ic remote +host name (or IP number) of peer. +The value displayed will be truncated to 15 characters unless the +.Fl w +flag is given, in which case the full value will be displayed +on the first line, +and the remaining data is displayed on the next line. +.It Ic refid +association ID or +.Lk decode.html#kiss "'kiss code" +.It Ic st +stratum +.It Ic t +.Ic u : +unicast or manycast client, +.Ic b : +broadcast or multicast client, +.Ic l : +local (reference clock), +.Ic s : +symmetric (peer), +.Ic A : +manycast server, +.Ic B : +broadcast server, +.Ic M : +multicast server +.It Ic when +sec/min/hr since last received packet +.It Ic poll +poll interval (log2 s) +.It Ic reach +reach shift register (octal) +.It Ic delay +roundtrip delay +.It Ic offset +offset of server relative to this host +.It Ic jitter +jitter +.El +.It Ic pstats Ar assocID +Show the statistics for the peer with the given +.Ar assocID . .It Ic readlist Ar assocID .It Ic rl Ar assocID -Requests that the values of the variables in the internal -variable list be returned by the server. -If the association ID is -omitted or is 0 the variables are assumed to be system variables. -Otherwise they are treated as peer variables. -If the internal -variable list is empty a request is sent without data, which should -induce the remote server to return a default display. -.It Xo Ic readvar Ar assocID -.Ar variable_name Ns Op = Ns Ar value -.Ar ... -.Xc -.It Xo Ic rv Ar assocID -.Ar variable_name Ns Op = Ns Ar value -.Ar ... -.Xc -Requests that the values of the specified variables be returned -by the server by sending a read variables request. +Read the system or peer variables included in the variable list. +.It Ic readvar Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc +.It Ic rv Ar assocID Ar name Ns Oo Ns = Ns Ar value Oc Oo , ... Oc +Display the specified 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 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 +YYYYMMDDTTTT , +where YYYY is the year, +MM the month of year, +DD the day of month and +TTTT the time of day. +.It Ic reslist +Show the access control (restrict) list for +.Nm . +.It Ic saveconfig Ar filename +Write the current configuration, +including any runtime modifications given with +.Ic :config +or +.Ic config\-from\-file , +to the ntpd host's file +.Ar filename . +This command will be rejected by the server unless +.Lk miscopt.html#saveconfigdir "saveconfigdir" +appears in the +.Ic ntpd +configuration file. +.Ar filename +can use +.Xr strftime +format specifies to substitute the current date and time, for example, +.Ic q]saveconfig ntp\-%Y%m%d\-%H%M%S.confq] . +The filename used is stored in system variable +.Ic savedconfig . +Authentication is required. +.It Ic timerstats +Display interval timer counters. +.It Ic writelist Ar assocID +Write the system or peer variables included in the variable list. +.It Ic writevar Ar assocID Ar name Ns = Ns Ar value Op , ... +Write the specified variables. If the -association ID is omitted or is given as zero the variables are -system variables, otherwise they are peer variables and the values -returned will be those of the corresponding peer. -Omitting the -variable list will send a request with no data which should induce -the server to return a default display. +.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 -encoding and meaning of the variables derived from NTPv3 is given in -RFC-1305; the encoding and meaning of the additional NTPv4 variables are -given later in this page. -.It Xo Ic writevar Ar assocID -.Ar variable_name Ns Op = Ns Ar value -.Ar ... -.Xc -Like the readvar request, except the specified variables are -written instead of read. -.It Ic writelist Op Ar assocID -Like the readlist request, except the internal list variables -are written instead of read. +.Ar assocID +is required, as the same name can occur in both spaces. +.It Ic sysinfo +Display operational summary. +.It Ic sysstats +Print statistics counters maintained in the protocol module. .El -.Ss Tally Codes -The character in the left margin in the -.Sq peers -billboard, -called the tally code, shows the fate of each association -in the clock selection process. -Following is a list of these characters, the pigeon used -in the +.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 in the .Ic rv -command, and a short explanation of the condition revealed. -.Bl -tag -width indent -.It space -.Pq reject -The peer is discarded as unreachable, synchronized to this server (synch -loop) or outrageous synchronization distance. -.It x -.Pq falsetick -The peer is discarded by the intersection algorithm as a falseticker. -.It \&. -.Pq excess -The peer is discarded as not among the first ten peers sorted by -synchronization distance and so is probably a poor candidate for further -consideration. -.It \&- -.Pq outlyer -The peer is discarded by the clustering algorithm as an outlyer. -.It \&+ -.Pq candidat -The peer is a survivor and a candidate for the combining algorithm. -.It \&# -.Pq selected -The peer is a survivor, but not among the first six peers sorted by -synchronization distance. -If the association is ephemeral, it may be -demobilized to conserve resources. -.It \&* -.Pq sys.peer -The peer has been declared the system peer and lends its variables to the -system variables. -.It o -.Pq pps.peer -The peer has been declared the system peer and lends its variables to -the system variables. -However, the actual system synchronization is derived -from a pulse-per-second (PPS) signal, either indirectly via the PPS -reference clock driver or directly via kernel interface. -.El -.Ss System Variables -The -.Cm status , -.Cm leap , -.Cm stratum , -.Cm precision , -.Cm rootdelay , -.Cm rootdispersion , -.Cm refid , -.Cm reftime , -.Cm poll , -.Cm offset , and -.Cm frequency -variables are described in RFC-1305 -specification. -Additional NTPv4 system variables include the following. -.Bl -tag -width indent -.It version -Everything you might need to know about the software version and generation -time. -.It processor -The processor and kernel identification string. -.It system -The operating system version and release identifier. -.It state -The state of the clock discipline state machine. -The values are described -in the architecture briefing on the NTP Project page linked from -www.ntp.org. -.It peer -The internal integer used to identify the association currently designated -the system peer. -.It jitter -The estimated time error of the system clock measured as an exponential -average of RMS time differences. -.It stability -The estimated frequency stability of the system clock measured as an -exponential average of RMS frequency differences. -.El +.Ic as +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 -When the NTPv4 daemon is compiled with the OpenSSL software library, additional -system variables are displayed, including some or all of the following, -depending on the particular dance: -.Bl -tag -width indent -.It flags -The current flags word bits and message digest algorithm identifier (NID) -in hex format. -The high order 16 bits of the four-byte word contain the NID -from the OpenSSL ligrary, while the low-order bits are interpreted as -follows: -.Bl -tag -width indent -.It 0x01 -autokey enabled -.It 0x02 -NIST leapseconds file loaded -.It 0x10 -PC identity scheme -.It 0x20 -IFF identity scheme -.It 0x40 -GQ identity scheme -.El -.It hostname -The name of the host as returned by the Unix -.Fn gethostname -library -function. -.It hostkey -The NTP filestamp of the host key file. -.It cert -A list of certificates held by the host. -Each entry includes the subject, -issuer, flags and NTP filestamp in order. -The bits are interpreted as -follows: -.Bl -tag -width indent -.It 0x01 -certificate has been signed by the server -.It 0x02 -certificate is trusted -.It 0x04 -certificate is private -.It 0x08 -certificate contains errors and should not be trusted +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 rv +billboard. +Not all variables are displayed in some configurations. +.Bl -tag -width "something" -compact -offset indent +.It Variable +Description +.It Ic status +.Lk decode.html#sys "system status word" +.It Ic version +NTP software version and build time +.It Ic processor +hardware platform and version +.It Ic system +operating system and version +.It Ic leap +leap warning indicator (0\-3) +.It Ic stratum +stratum (1\-15) +.It Ic precision +precision (log2 s) +.It Ic rootdelay +total roundtrip delay to the primary reference clock +.It Ic rootdisp +total dispersion to the primary reference clock +.It Ic peer +system peer association ID +.It Ic tc +time constant and poll exponent (log2 s) (3\-17) +.It Ic mintc +minimum time constant (log2 s) (3\-10) +.It Ic clock +date and time of day +.It Ic refid +reference ID or +.Lk decode.html#kiss "kiss code" +.It Ic reftime +reference time +.It Ic offset +combined offset of server relative to this host +.It Ic sys_jitter +combined system jitter +.It Ic frequency +frequency offset (PPM) relative to hardware clock +.It Ic clk_wander +clock frequency wander (PPM) +.It Ic clk_jitter +clock jitter +.It Ic tai +TAI\-UTC offset (s) +.It Ic leapsec +NTP seconds when the next leap second is/was inserted +.It Ic expire +NTP seconds when the NIST leapseconds file expires .El -.It leapseconds -The NTP filestamp of the NIST leapseconds file. -.It refresh -The NTP timestamp when the host public cryptographic values were refreshed -and signed. -.It signature -The host digest/signature scheme name from the OpenSSL library. -.It tai -The TAI-UTC offset in seconds obtained from the NIST leapseconds table. +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 Ic host +Autokey host name for this host +.It Ic ident +Autokey group name for this host +.It Ic flags +host flags (see Autokey specification) +.It Ic digest +OpenSSL message digest algorithm +.It Ic signature +OpenSSL digest/signature scheme +.It Ic update +NTP seconds at last signature update +.It Ic cert +certificate subject, issuer and certificate flags +.It Ic until +NTP seconds when the certificate expires .El .Ss Peer Variables -The -.Cm status , -.Cm srcadr , -.Cm srcport , -.Cm dstadr , -.Cm dstport , -.Cm leap , -.Cm stratum , -.Cm precision , -.Cm rootdelay , -.Cm rootdispersion , -.Cm readh , -.Cm hmode , -.Cm pmode , -.Cm hpoll , -.Cm ppoll , -.Cm offset , -.Cm delay , -.Cm dspersion , -.Cm reftime -variables are described in the RFC-1305 specification, as -are the timestamps -.Cm org , -.Cm rec -and -.Cm xmt . -Additional NTPv4 system variables include -the following. -.Bl -tag -width indent -.It flash -The flash code for the most recent packet received. -The encoding and -meaning of these codes is given later in this page. -.It jitter -The estimated time error of the peer clock measured as an exponential -average of RMS time differences. -.It unreach -The value of the counter which records the number of poll intervals since -the last valid packet was received. -.El -.Pp -When the NTPv4 daemon is compiled with the OpenSSL software library, additional -peer variables are displayed, including the following: -.Bl -tag -width indent -.It flags -The current flag bits. -This word is the server host status word with -additional bits used by the Autokey state machine. -See the source code for -the bit encoding. -.It hostname -The server host name. -.It initkey Ar key -The initial key used by the key list generator in the Autokey protocol. -.It initsequence Ar index -The initial index used by the key list generator in the Autokey protocol. -.It signature -The server message digest/signature scheme name from the OpenSSL software -library. -.It timestamp Ar time -The NTP timestamp when the last Autokey key list was generated and signed. +The following peer variables appear in the +.Ic rv +billboard for each association. +Not all variables are displayed in some configurations. +.Bl -tag -width "something" -compact -offset indent +.It Variable +Description +.It Ic associd +association ID +.It Ic status +.Lk decode.html#peer "peer status word" +.It Ic srcadr +source (remote) IP address +.It Ic srcport +source (remote) port +.It Ic dstadr +destination (local) IP address +.It Ic dstport +destination (local) port +.It Ic leap +leap indicator (0\-3) +.It Ic stratum +stratum (0\-15) +.It Ic precision +precision (log2 s) +.It Ic rootdelay +total roundtrip delay to the primary reference clock +.It Ic rootdisp +total root dispersion to the primary reference clock +.It Ic refid +reference ID or +.Lk decode.html#kiss "kiss code" +.It Ic reftime +reference time +.It Ic reach +reach register (octal) +.It Ic unreach +unreach counter +.It Ic hmode +host mode (1\-6) +.It Ic pmode +peer mode (1\-5) +.It Ic hpoll +host poll exponent (log2 s) (3\-17) +.It Ic ppoll +peer poll exponent (log2 s) (3\-17) +.It Ic headway +headway (see +.Lk rate.html "Rate Management and the Kiss\-o'\-Death Packet" ) +.It Ic flash +.Lk decode.html#flash "flash status word" +.It Ic offset +filter offset +.It Ic delay +filter delay +.It Ic dispersion +filter dispersion +.It Ic jitter +filter jitter +.It Ic ident +Autokey group name for this association +.It Ic bias +unicast/broadcast bias +.It Ic xleave +interleave delay (see +.Lk xleave.html "NTP Interleaved Modes" ) .El -.Ss Flash Codes The -.Cm flash -code is a valuable debugging aid displayed in the peer variables -list. -It shows the results of the original sanity checks defined in the NTP -specification RFC-1305 and additional ones added in NTPv4. -There are 12 tests -designated -.Sy TEST1 -through -.Sy TEST12 . -The tests are performed in a certain order -designed to gain maximum diagnostic information while protecting against -accidental or malicious errors. +.Ic 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 -.Sy flash -variable is initialized to zero as -each packet is received. -If after each set of tests one or more bits are set, -the packet is discarded. +.Ic 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 -Tests -.Sy TEST1 -through -.Sy TEST3 -check the packet timestamps from which the offset and -delay are calculated. -If any bits are set, the packet is discarded; otherwise, -the packet header variables are saved. -.Sy TEST4 -and -.Sy TEST5 -are associated with -access control and cryptographic authentication. -If any bits are set, the -packet is discarded immediately with nothing changed. -.Pp -Tests -.Sy TEST6 -through -.Sy TEST8 -check the health of the server. -If any bits are set, -the packet is discarded; otherwise, the offset and delay relative to the server -are calculated and saved. -TEST9 checks the health of the association itself. -If -any bits are set, the packet is discarded; otherwise, the saved variables are -passed to the clock filter and mitigation algorithms. -.Pp -Tests -.Sy TEST10 -through -.Sy TEST12 -check the authentication state using Autokey -public-key cryptography, as described in the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -If -any bits are set and the association has previously been marked reachable, the -packet is discarded; otherwise, the originate and receive timestamps are saved, -as required by the NTP protocol, and processing continues. -.Pp -The -.Cm flash -bits for each test are defined as follows. -.Bl -tag -width indent -.It 0x001 -.Pq TEST1 -Duplicate packet. -The packet is at best a casual retransmission and at -worst a malicious replay. -.It 0x002 -.Pq TEST2 -Bogus packet. -The packet is not a reply to a message previously sent. -This -can happen when the NTP daemon is restarted and before somebody else -notices. -.It 0x004 -.Pq TEST3 -Unsynchronized. -One or more timestamp fields are invalid. -This normally -happens when the first packet from a peer is received. -.It 0x008 -.Pq TEST4 -Access is denied. -See the -.Sx Access Control Support -section of -.Xr ntp.conf 5 . -.It 0x010 -.Pq TEST5 -Cryptographic authentication fails. -See the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -.It 0x020 -.Pq TEST6 -The server is unsynchronized. -Wind up its clock first. -.It 0x040 -.Pq TEST7 -The server stratum is at the maximum than 15. -It is probably unsynchronized -and its clock needs to be wound up. -.It 0x080 -.Pq TEST8 -Either the root delay or dispersion is greater than one second, which is -highly unlikely unless the peer is unsynchronized to Mars. -.It 0x100 -.Pq TEST9 -Either the peer delay or dispersion is greater than one second, which is -higly unlikely unless the peer is on Mars. -.It 0x200 -.Pq TEST10 -The autokey protocol has detected an authentication failure. -See the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -.It 0x400 -.Pq TEST11 -The autokey protocol has not verified the server or peer is proventic and -has valid public key credentials. -See the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . -.It 0x800 -.Pq TEST12 -A protocol or configuration error has occurred in the public key algorithms -or a possible intrusion event has been detected. -See the -.Sx Authentication Options -section of -.Xr ntp.conf 5 . +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 Ic flags +peer flags (see Autokey specification) +.It Ic host +Autokey server name +.It Ic flags +peer flags (see Autokey specification) +.It Ic signature +OpenSSL digest/signature scheme +.It Ic initsequence +initial key ID +.It Ic initkey +initial key index +.It Ic timestamp +Autokey signature timestamp .El -.Sh SEE ALSO -.Xr ntp.conf 5 , -.Xr ntpd 8 , -.Xr ntpdc 8 -.Sh BUGS -The -.Ic peers -command is non-atomic and may occasionally result in -spurious error messages about invalid associations occurring and -terminating the command. -The timeout time is a fixed constant, -which means you wait a long time for timeouts since it assumes sort -of a worst case. -The program should improve the timeout estimate as -it sends queries to a particular host, but does not. +.Ss Clock Variables +The following clock variables appear in the +.Ic cv +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 Ic associd +association ID +.It Ic status +.Lk decode.html#clock "clock status word" +.It Ic device +device description +.It Ic timecode +ASCII time code string (specific to device) +.It Ic poll +poll messages sent +.It Ic noreply +no reply +.It Ic badformat +bad format +.It Ic baddata +bad date or time +.It Ic fudgetime1 +fudge time 1 +.It Ic fudgetime2 +fudge time 2 +.It Ic stratum +driver stratum +.It Ic refid +driver reference ID +.It Ic flags +driver flags +.El +.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, 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 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_<option\-name>\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\-2015 The University of Delaware and Network Time Foundation all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. +.Sh "BUGS" +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/ntptime.8 b/usr.sbin/ntp/doc/ntptime.8 index f130307..bb3b41a 100644 --- a/usr.sbin/ntp/doc/ntptime.8 +++ b/usr.sbin/ntp/doc/ntptime.8 @@ -1,7 +1,7 @@ .\" .\" $FreeBSD$ .\" -.Dd January 7, 2000 +.Dd April 27, 2015 .Dt NTPTIME 8 .Os .Sh NAME @@ -52,8 +52,6 @@ Specify estimated error, in microseconds. Specify frequency offset, in parts per million. .It Fl h Display help information. -.It Fl l -Specify the leap bits as a code from 0 to 3. .It Fl m Ar max_error Specify max possible errors, in microseconds. .It Fl o Ar offset diff --git a/usr.sbin/ntp/doc/ntptrace.8 b/usr.sbin/ntp/doc/ntptrace.8 index 554a3c0..40cb719 100644 --- a/usr.sbin/ntp/doc/ntptrace.8 +++ b/usr.sbin/ntp/doc/ntptrace.8 @@ -1,76 +1,93 @@ +.Dd February 4 2015 +.Dt NTPTRACE 8 User Commands +.Os +.\" EDIT THIS FILE WITH CAUTION (ntptrace-opts.mdoc) .\" .\" $FreeBSD$ .\" -.Dd January 6, 2000 -.Dt NTPTRACE 8 -.Os +.\" It has been AutoGen-ed February 4, 2015 at 02:37:48 AM by AutoGen 5.18.5pre4 +.\" From the definitions ntptrace-opts.def +.\" and the template file agmdoc-cmd.tpl .Sh NAME .Nm ntptrace -.Nd "trace a chain of NTP servers back to the primary source" +.Nd Trace peers of an NTP server .Sh SYNOPSIS .Nm -.Op Fl vdn -.Op Fl r Ar retries -.Op Fl t Ar timeout -.Op Ar server -.Sh DESCRIPTION -The -.Nm -utility determines where a given Network Time Protocol (NTP) server gets -its time from, and follows the chain of NTP servers back to their -master time source. -If given no arguments, it starts with -.Dq localhost . +.\" 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 -Here is an example of the output from -.Nm : -.Bd -literal -% ntptrace -localhost: stratum 4, offset 0.0019529, synch distance 0.144135 -server2ozo.com: stratum 2, offset 0.0124263, synch distance 0.115784 -usndh.edu: stratum 1, offset 0.0019298, synch distance 0.011993, refid 'WWVB' +.Sh DESCRIPTION +\fBntptrace\fP is a perl script that uses the ntpq utility program to follow +the chain of NTP servers from a given host back to the primary time source. For +ntptrace to work properly, each of these servers must implement the NTP Control +and Monitoring Protocol specified in RFC 1305 and enable NTP Mode 6 packets. +.sp +If given no arguments, ntptrace starts with localhost. Here is an example of +the output from ntptrace: +.sp +.Bd -literal -offset indent +% ntptrace localhost: stratum 4, offset 0.0019529, synch distance 0.144135 +server2ozo.com: stratum 2, offset 0.0124263, synch distance 0.115784 usndh.edu: +stratum 1, offset 0.0019298, synch distance 0.011993, refid 'WWVB' .Ed -.Pp -On each line, the fields are (left to right): the host name, the -host stratum, -the time offset between that host and the local host -(as measured by -.Nm ; -this is why it is not always zero for -.Dq localhost ) , -the host -synchronization distance, -and (only for stratum-1 servers) the reference clock ID. -All times -are given in seconds. -Note that the stratum is the server hop count to the primary source, -while the synchronization distance is the estimated error -relative to the primary source. -These terms are precisely defined in RFC 1305. -.Pp -The following options are available: -.Bl -tag -width indent -.It Fl d -Turn on some debugging output. -.It Fl n -Turn off the printing of host names; instead, host IP addresses -are given. -This may be necessary if a nameserver is down. -.It Fl r Ar retries -Set the number of retransmission attempts for each host; the default is 5. -.It Fl t Ar timeout -Set the retransmission timeout (in seconds); the default is 2. -.It Fl v -Print verbose information about the NTP servers. +.sp +On each line, the fields are (left to right): the host name, the host stratum, +the time offset between that host and the local host (as measured by +\fBntptrace\fP; this is why it is not always zero for "localhost"), the host +synchronization distance, and (only for stratum\-1 servers) the reference clock +ID. All times are given in seconds. Note that the stratum is the server hop +count to the primary source, while the synchronization distance is the +estimated error relative to the primary source. These terms are precisely +defined in RFC\-1305. +.Sh "OPTIONS" +.Bl -tag +.It Fl n , Fl \-numeric +Print IP addresses instead of hostnames. +.sp +Output hosts as dotted\-quad numeric format rather than converting to +the canonical host names. +.It Fl m Ar number , Fl \-max\-hosts Ns = Ns Ar number +Maximum number of peers to trace. +This option takes an integer number as its argument. +The default +.Ar number +for this option is: +.ti +4 + 99 +.sp +This option has not been fully documented. +.It Fl r Ar string , Fl \-host Ns = Ns Ar string +Single remote host. +The default +.Ar string +for this option is: +.ti +4 + 127.0.0.1 +.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 v Op Brq Ar v|c|n 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 "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 -.Rs -.%A D L Mills -.%T Network Time Protocol (Version 3) -.%O RFC1305 -.Re -.Sh BUGS -This program makes no attempt to improve accuracy by doing multiple -samples. +.Sh "NOTES" +This manual page was \fIAutoGen\fP\-erated from the \fBntptrace\fP +option definitions. diff --git a/usr.sbin/ntp/doc/pic/Makefile b/usr.sbin/ntp/doc/pic/Makefile new file mode 100644 index 0000000..11bcab6 --- /dev/null +++ b/usr.sbin/ntp/doc/pic/Makefile @@ -0,0 +1,27 @@ +# $FreeBSD$ + +.include <src.opts.mk> + +FILESDIR= ${SHAREDIR}/doc/ntp/pic + +.if ${MK_HTML} != "no" +FILES= 9400n.jpg alice11.gif alice13.gif alice15.gif alice23.gif \ + alice31.gif alice32.gif alice35.gif alice38.gif alice44.gif \ + alice47.gif alice51.gif alice61.gif barnstable.gif beaver.gif \ + boom3.gif boom3a.gif boom4.gif broad.gif bustardfly.gif c51.jpg \ + description.jpg discipline.gif dogsnake.gif driver29.gif \ + driver43_1.gif driver43_2.jpg fg6021.gif fg6039.jpg fig_3_1.gif \ + flatheads.gif flt1.gif flt2.gif flt3.gif flt4.gif flt5.gif flt6.gif \ + flt7.gif flt8.gif flt9.gif freq1211.gif gadget.jpg gps167.jpg \ + group.gif hornraba.gif igclock.gif neoclock4x.gif offset1211.gif \ + oncore_evalbig.gif oncore_remoteant.jpg oncore_utplusbig.gif oz2.gif \ + panda.gif pd_om006.gif pd_om011.gif peer.gif pogo.gif pogo1a.gif \ + pogo3a.gif pogo4.gif pogo5.gif pogo6.gif pogo7.gif pogo8.gif \ + pzf509.jpg pzf511.jpg rabbit.gif radio2.jpg sheepb.jpg stack1a.jpg \ + stats.gif sx5.gif thunderbolt.jpg time1.gif tonea.gif tribeb.gif \ + wingdorothy.gif +.endif + +.PATH: ${.CURDIR}/../../../../contrib/ntp/html/pic + +.include <bsd.prog.mk> diff --git a/usr.sbin/ntp/doc/scripts/Makefile b/usr.sbin/ntp/doc/scripts/Makefile new file mode 100644 index 0000000..13adda7 --- /dev/null +++ b/usr.sbin/ntp/doc/scripts/Makefile @@ -0,0 +1,15 @@ +# $FreeBSD$ + +.include <src.opts.mk> + +FILESDIR= ${SHAREDIR}/doc/ntp/scripts + +.if ${MK_HTML} != "no" +FILES= accopt.txt audio.txt authopt.txt clockopt.txt command.txt config.txt \ + confopt.txt external.txt footer.txt hand.txt install.txt manual.txt \ + misc.txt miscopt.txt monopt.txt refclock.txt special.txt style.css +.endif + +.PATH: ${.CURDIR}/../../../../contrib/ntp/html/scripts + +.include <bsd.prog.mk> diff --git a/usr.sbin/ntp/doc/sntp.8 b/usr.sbin/ntp/doc/sntp.8 new file mode 100644 index 0000000..4d09cb0 --- /dev/null +++ b/usr.sbin/ntp/doc/sntp.8 @@ -0,0 +1,313 @@ +.Dd February 4 2015 +.Dt SNTP 8 User Commands +.Os +.\" EDIT THIS FILE WITH CAUTION (sntp-opts.mdoc) +.\" +.\" $FreeBSD$ +.\" +.\" It has been AutoGen-ed February 4, 2015 at 02:34:20 AM by AutoGen 5.18.5pre4 +.\" From the definitions sntp-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm sntp +.Nd standard Simple Network Time Protocol client 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 +[ 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. +.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. +.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_<option\-name>\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\-2015 The University of Delaware and Network Time Foundation all rights reserved. +This program is released under the terms of the NTP license, <http://ntp.org/license>. +.Sh "BUGS" +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. |