d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

- Update to ntp-4.2.0

Browse Source 
PR:		docs/79857
Submitted by:	Tsurutani Naoki <turutani@scphys.kyoto-u.ac.jp>
This commit is contained in:
Pav Lucistnik 2006-05-17 10:50:35 +00:00
parent f6ce2a64f7
commit a0ff005ba5
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=158688
7 changed files with 2457 additions and 1340 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
usr.sbin/ntp/doc/Makefile
View File

@ -24,7 +24,7 @@ FILES= accopt.html assoc.html audio.html authopt.html build.html \
.endif
MAN= ntp.conf.5 ntp.keys.5
MAN+= ntpd.8 ntpdate.8 ntpdc.8 ntpq.8 ntptime.8 ntptrace.8
MAN+= ntp-keygen.8 ntpd.8 ntpdate.8 ntpdc.8 ntpq.8 ntptime.8 ntptrace.8
.PATH: ${.CURDIR}/../../../contrib/ntp/html \
${.CURDIR}/../../../contrib/ntp/html/drivers

583
usr.sbin/ntp/doc/ntp-keygen.8 Normal file
View File

@ -0,0 +1,583 @@
.\"
.\" $FreeBSD$
.\"
.Dd May 17, 2006
.Dt NTP-KEYGEN. 8
.Os
.Sh NAME
.Nm ntp-keygen
.Nd key generation program for ntpd
.Sh SYNOPSIS
.Nm
.Op Fl deGgHIMnPT
.Op Fl c Oo Cm RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 Oc
.Op Fl i Ar name
.Op Fl p Ar password
.Op Fl S Oo Cm RSA | DSA Oc
.Op Fl s Ar name
.Op Fl v Ar nkeys
.Sh DESCRIPTION
This program generates cryptographic data files used by the NTPv4
authentication and identification schemes.
It generates MD5 key files used in symmetric key cryptography.
In addition, if the OpenSSL software library has been installed,
it generates keys, certificate and identity files used in public key
cryptography. These files are used for cookie encryption,
digital signature and challenge/response identification algorithms
compatible with the Internet standard security infrastructure.
.Pp
All files are in PEM-encoded printable ASCII format,
so they can be embedded as MIME attachments in mail to other sites
and certificate authorities.
By default, files are not encrypted. The
.Fl p Ar password
option specifies the write password and
.Fl q Ar password
option the read password for previously encrypted files.
The
.Nm
program prompts for the password if it reads an encrypted file
and the password is missing or incorrect.
If an encrypted file is read successfully and
no write password is specified, the read password is used
as the write password by default.
.Pp
The
.Xr ntpd 8
configuration command
.Ic crypto pw Ar password
specifies the read password for previously encrypted files.
The daemon expires on the spot if the password is missing
or incorrect.
For convenience, if a file has been previously encrypted,
the default read password is the name of the host running
the program.
If the previous write password is specified as the host name,
these files can be read by that host with no explicit password.
.Pp
File names begin with the prefix
.Cm ntpkey_
and end with the postfix
.Ar _hostname.filestamp ,
where
.Ar hostname
is the owner name, usually the string returned
by the Unix gethostname() routine, and
.Ar filestamp
is the NTP seconds when the file was generated, in decimal digits.
This both guarantees uniqueness and simplifies maintenance
procedures, since all files can be quickly removed
by a
.Ic rm ntpkey\&*
command or all files generated
at a specific time can be removed by a
.Ic rm
.Ar \&*filestamp
command.
To further reduce the risk of misconfiguration,
the first two lines of a file contain the file name
and generation date and time as comments.
.Pp
All files are installed by default in the keys directory
.Pa /usr/local/etc ,
which is normally in a shared filesystem
in NFS-mounted networks. The actual location of the keys directory
and each file can be overridden by configuration commands,
but this is not recommended.
Normally, the files for each host are generated by that host
and used only by that host, although exceptions exist
as noted later on this page.
.Pp
Normally, files containing private values,
including the host key, sign key and identification parameters,
are permitted root read/write-only;
while others containing public values are permitted world readable.
Alternatively, files containing private values can be encrypted
and these files permitted world readable,
which simplifies maintenance in shared file systems.
Since uniqueness is insured by the hostname and
file name extensions, the files for a NFS server and
dependent clients can all be installed in the same shared directory.
.Pp
The recommended practice is to keep the file name extensions
when installing a file and to install a soft link
from the generic names specified elsewhere on this page
to the generated files.
This allows new file generations to be activated simply
by changing the link.
If a link is present, ntpd follows it to the file name
to extract the filestamp.
If a link is not present,
.Xr ntpd 8
extracts the filestamp from the file itself.
This allows clients to verify that the file and generation times
are always current. The
.Nm
program uses the same timestamp extension for all files generated
at one time, so each generation is distinct and can be readily
recognized in monitoring data.
.Ss Running the program
The safest way to run the
.Nm
program is logged in directly as root.
The recommended procedure is change to the keys directory,
usually
.Pa /ust/local/etc ,
then run the program. When run for the first time,
or if all
.Cm ntpkey
files have been removed,
the program generates a RSA host key file and matching RSA-MD5 certificate file,
which is all that is necessary in many cases.
The program also generates soft links from the generic names
to the respective files.
If run again, the program uses the same host key file,
but generates a new certificate file and link.
.Pp
The host key is used to encrypt the cookie when required and so must be RSA type.
By default, the host key is also the sign key used to encrypt signatures.
When necessary, a different sign key can be specified and this can be
either RSA or DSA type.
By default, the message digest type is MD5, but any combination
of sign key type and message digest type supported by the OpenSSL library
can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2
and RIPE160 message digest algorithms.
However, the scheme specified in the certificate must be compatible
with the sign key.
Certificates using any digest algorithm are compatible with RSA sign keys;
however, only SHA and SHA1 certificates are compatible with DSA sign keys.
.Pp
Private/public key files and certificates are compatible with
other OpenSSL applications and very likely other libraries as well.
Certificates or certificate requests derived from them should be compatible
with extant industry practice, although some users might find
the interpretation of X509v3 extension fields somewhat liberal.
However, the identification parameter files, although encoded
as the other files, are probably not compatible with anything other than Autokey.
.Pp
Running the program as other than root and using the Unix
.Ic su
command
to assume root may not work properly, since by default the OpenSSL library
looks for the random seed file
.Cm .rnd
in the user home directory.
However, there should be only one
.Cm .rnd ,
most conveniently
in the root directory, so it is convenient to define the
.Cm $RANDFILE
environment variable used by the OpenSSL library as the path to
.Cm /.rnd .
.Pp
Installing the keys as root might not work in NFS-mounted
shared file systems, as NFS clients may not be able to write
to the shared keys directory, even as root.
In this case, NFS clients can specify the files in another
directory such as
.Pa /etc
using the
.Ic keysdir
command.
There is no need for one client to read the keys and certificates
of other clients or servers, as these data are obtained automatically
by the Autokey protocol.
.Pp
Ordinarily, cryptographic files are generated by the host that uses them,
but it is possible for a trusted agent (TA) to generate these files
for other hosts; however, in such cases files should always be encrypted.
The subject name and trusted name default to the hostname
of the host generating the files, but can be changed by command line options.
It is convenient to designate the owner name and trusted name
as the subject and issuer fields, respectively, of the certificate.
The owner name is also used for the host and sign key files,
while the trusted name is used for the identity files.
.Pp
.Ss Trusted Hosts and Groups
Each cryptographic configuration involves selection of a signature scheme
and identification scheme, called a cryptotype,
as explained in the
.Sx Authentication Options
section of
.Xr ntp.conf 5 .
The default cryptotype uses RSA encryption, MD5 message digest
and TC identification.
First, configure a NTP subnet including one or more low-stratum
trusted hosts from which all other hosts derive synchronization
directly or indirectly. Trusted hosts have trusted certificates;
all other hosts have nontrusted certificates.
These hosts will automatically and dynamically build authoritative
certificate trails to one or more trusted hosts.
A trusted group is the set of all hosts that have, directly or indirectly,
a certificate trail ending at a trusted host.
The trail is defined by static configuration file entries
or dynamic means described on the
.Sx Automatic NTP Configuration Options
section of
.Xr ntp.conf 5 .
.Pp
On each trusted host as root, change to the keys directory.
To insure a fresh fileset, remove all
.Cm ntpkey
files.
Then run
.Nm
.Fl T
to generate keys and a trusted certificate.
On all other hosts do the same, but leave off the
.Fl T
flag to generate keys and nontrusted certificates.
When complete, start the NTP daemons beginning at the lowest stratum
and working up the tree.
It may take some time for Autokey to instantiate the certificate trails
throughout the subnet, but setting up the environment is completely automatic.
.Pp
If it is necessary to use a different sign key or different digest/signature
scheme than the default, run
.Nm
with the
.Fl S Ar type
option, where
.Ar type
is either
.Cm RSA
or
.Cm DSA .
The most often need to do this is when a DSA-signed certificate is used.
If it is necessary to use a different certificate scheme than the default,
run
.Nm
with the
.Fl c Ar scheme
option and selected
.Ar scheme
as needed.
If
.Nm
is run again without these options, it generates a new certificate
using the same scheme and sign key.
.Pp
After setting up the environment it is advisable to update certificates
from time to time, if only to extend the validity interval.
Simply run
.Nm
with the same flags as before to generate new certificates
using existing keys.
However, if the host or sign key is changed,
.Xr ntpd 8
should be restarted.
When
.Xr ntpd 8
is restarted, it loads any new files and restarts the protocol.
Other dependent hosts will continue as usual until signatures are refreshed,
at which time the protocol is restarted.
.Ss Identity Schemes
As mentioned on the Autonomous Authentication page,
the default TC identity scheme is vulnerable to a middleman attack.
However, there are more secure identity schemes available,
including PC, IFF, GQ and MV described on the
.Qq Identification Schemes
page
(maybe available at
.Li http://www.eecis.udel.edu/%7emills/keygen.html ) .
These schemes are based on a TA, one or more trusted hosts
and some number of nontrusted hosts.
Trusted hosts prove identity using values provided by the TA,
while the remaining hosts prove identity using values provided
by a trusted host and certificate trails that end on that host.
The name of a trusted host is also the name of its sugroup
and also the subject and issuer name on its trusted certificate.
The TA is not necessarily a trusted host in this sense, but often is.
.Pp
In some schemes there are separate keys for servers and clients.
A server can also be a client of another server,
but a client can never be a server for another client.
In general, trusted hosts and nontrusted hosts that operate
as both server and client have parameter files that contain
both server and client keys. Hosts that operate
only as clients have key files that contain only client keys.
.Pp
The PC scheme supports only one trusted host in the group.
On trusted host alice run
.Nm
.Fl P
.Fl p Ar password
to generate the host key file
.Pa ntpkey_RSAkey_ Ns Ar alice.filestamp
and trusted private certificate file
.Pa ntpkey_RSA-MD5_cert_ Ns Ar alice.filestamp .
Copy both files to all group hosts;
they replace the files which would be generated in other schemes.
On each host bob install a soft link from the generic name
.Pa ntpkey_host_ Ns Ar bob
to the host key file and soft link
.Pa ntpkey_cert_ Ns Ar bob
to the private certificate file.
Note the generic links are on bob, but point to files generated
by trusted host alice. In this scheme it is not possible to refresh
either the keys or certificates without copying them
to all other hosts in the group.
.Pp
For the IFF scheme proceed as in the TC scheme to generate keys
and certificates for all group hosts, then for every trusted host in the group,
generate the IFF parameter file.
On trusted host alice run
.Nm
.Fl T
.Fl I
.Fl p Ar password
to produce her parameter file
.Pa ntpkey_IFFpar_ Ns Ar alice.filestamp ,
which includes both server and client keys.
Copy this file to all group hosts that operate as both servers
and clients and install a soft link from the generic
.Pa ntpkey_iff_ Ns Ar alice
to this file.
If there are no hosts restricted to operate only as clients,
there is nothing further to do. As the IFF scheme is independent
of keys and certificates, these files can be refreshed as needed.
.Pp
If a rogue client has the parameter file, it could masquerade
as a legitimate server and present a middleman threat.
To eliminate this threat, the client keys can be extracted
from the parameter file and distributed to all restricted clients.
After generating the parameter file, on alice run
.Nm
.Fl e
and pipe the output to a file or mail program.
Copy or mail this file to all restricted clients.
On these clients install a soft link from the generic
.Pa ntpkey_iff_ Ns Ar alice
to this file. To further protect the integrity of the keys,
each file can be encrypted with a secret password.
.Pp
For the GQ scheme proceed as in the TC scheme to generate keys
and certificates for all group hosts, then for every trusted host
in the group, generate the IFF parameter file.
On trusted host alice run
.Nm
.Fl T
.Fl G
.Fl p Ar password
to produce her parameter file
.Pa ntpkey_GQpar_ Ns Ar alice.filestamp ,
which includes both server and client keys.
Copy this file to all group hosts and install a soft link
from the generic
.Pa ntpkey_gq_ Ns Ar alice
to this file.
In addition, on each host bob install a soft link
from generic
.Pa ntpkey_gq_ Ns Ar bob
to this file.
As the GQ scheme updates the GQ parameters file and certificate
at the same time, keys and certificates can be regenerated as needed.
.Pp
For the MV scheme, proceed as in the TC scheme to generate keys
and certificates for all group hosts.
For illustration assume trish is the TA, alice one of several trusted hosts
and bob one of her clients. On TA trish run
.Nm
.Fl V Ar n
.Fl p Ar password ,
where
.Ar n
is the number of revokable keys (typically 5) to produce
the parameter file
.Pa ntpkeys_MVpar_ Ns Ar trish.filestamp
and client key files
.Pa ntpkeys_MVkeyd_ Ns Ar trish.filestamp
where
.Ar d
is the key number (0 \&<
.Ar d
\&<
.Ar n ) .
Copy the parameter file to alice and install a soft link
from the generic
.Pa ntpkey_mv_ Ns Ar alice
to this file.
Copy one of the client key files to alice for later distribution
to her clients.
It doesn't matter which client key file goes to alice,
since they all work the same way.
Alice copies the client key file to all of her cliens.
On client bob install a soft link from generic
.Pa ntpkey_mvkey_ Ns Ar bob
to the client key file.
As the MV scheme is independent of keys and certificates,
these files can be refreshed as needed.
.Ss Command Line Options
.Bl -tag -width indent
.It Fl c Oo Cm RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 Oc
Select 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
.Cm RSA-MD5 .
.It Fl d
Enable debugging.
This option displays the cryptographic data produced in eye-friendly billboards.
.It Fl e
Write the IFF client keys to the standard output.
This is intended for automatic key distribution by mail.
.It Fl G
Generate parameters and keys for the GQ identification scheme,
obsoleting any that may exist.
.It Fl g
Generate keys for the GQ identification scheme
using the existing GQ parameters.
If the GQ parameters do not yet exist, create them first.
.It Fl H
Generate new host keys, obsoleting any that may exist.
.It Fl I
Generate parameters for the IFF identification scheme,
obsoleting any that may exist.
.It Fl i Ar name
Set the suject name to
.Ar name .
This is used as the subject field in certificates
and in the file name for host and sign keys.
.It Fl M
Generate MD5 keys, obsoleting any that may exist.
.It Fl P
Generate a private certificate.
By default, the program generates public certificates.
.It Fl p Ar password
Encrypt generated files containing private data with
.Ar password
and the DES-CBC algorithm.
.It Fl q
Set the password for reading files to password.
.It Fl S Oo Cm RSA | DSA Oc
Generate a new sign key of the designated type,
obsoleting any that may exist.
By default, the program uses the host key as the sign key.
.It Fl s Ar name
Set the issuer name to
.Ar name .
This is used for the issuer field in certificates
and in the file name for identity files.
.It Fl T
Generate a trusted certificate.
By default, the program generates a non-trusted certificate.
.It Fl V Ar nkeys
Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme.
.El
.Ss Random Seed File
All cryptographically sound key generation schemes must have means
to randomize the entropy seed used to initialize
the internal pseudo-random number generator used
by the library routines.
The OpenSSL library uses a designated random seed file for this purpose.
The file must be available when starting the NTP daemon and
.Nm
program. If a site supports OpenSSL or its companion OpenSSH,
it is very likely that means to do this are already available.
.Pp
It is important to understand that entropy must be evolved
for each generation, for otherwise the random number sequence
would be predictable.
Various means dependent on external events, such as keystroke intervals,
can be used to do this and some systems have built-in entropy sources.
Suitable means are described in the OpenSSL software documentation,
but are outside the scope of this page.
.Pp
The entropy seed used by the OpenSSL library is contained in a file,
usually called
.Cm .rnd ,
which must be available when starting the NTP daemon
or the
.Nm
program. The NTP daemon will first look for the file
using the path specified by the
.Ic randfile
subcommand of the
.Ic crypto
configuration command.
If not specified in this way, or when starting the
.Nm
program,
the OpenSSL library will look for the file using the path specified
by the
.Ev RANDFILE
environment variable in the user home directory,
whether root or some other user.
If the
.Ev RANDFILE
environment variable is not present,
the library will look for the
.Cm .rnd
file in the user home directory.
If the file is not available or cannot be written,
the daemon exits with a message to the system log and the program
exits with a suitable error message.
.Ss Cryptographic Data Files
All other file formats begin with two lines.
The first contains the file name, including the generated host name
and filestamp.
The second contains the datestamp in conventional Unix date format.
Lines beginning with # are considered comments and ignored by the
.Nm
program and
.Xr ntpd 8
daemon.
Cryptographic values are encoded first using ASN.1 rules,
then encrypted if necessary, and finally written PEM-encoded
printable ASCII format preceded and followed by MIME content identifier lines.
.Pp
The format of the symmetric keys file is somewhat different
than the other files in the interest of backward compatibility.
Since DES-CBC is deprecated in NTPv4, the only key format of interest
is MD5 alphanumeric strings. Following hte heard the keys are
entered one per line in the format
.D1 Ar keyno type key
where
.Ar keyno
is a positive integer in the range 1-65,535,
.Ar type
is the string MD5 defining the key format and
.Ar key
is the key itself,
which is a printable ASCII string 16 characters or less in length.
Each character is chosen from the 93 printable characters
in the range 0x21 through 0x7f excluding space and the
.Ql #
character.
.Pp
Note that the keys used by the
.Xr ntpq 8
and
.Xr ntpdc 8
programs
are checked against passwords requested by the programs
and entered by hand, so it is generally appropriate to specify these keys
in human readable ASCII format.
.Pp
The
.Nm
program generates a MD5 symmetric keys file
.Pa ntpkey_MD5key_ Ns Ar hostname.filestamp .
Since the file contains private shared keys,
it should be visible only to root and distributed by secure means
to other subnet hosts.
The NTP daemon loads the file
.Pa ntp.keys ,
so
.Nm
installs a soft link from this name to the generated file.
Subsequently, similar soft links must be installed by manual
or automated means on the other subnet hosts.
While this file is not used with the Autokey Version 2 protocol,
it is needed to authenticate some remote configuration commands
used by the
.Xr ntpq 8
and
.Xr ntpdc 8
utilities.
.Sh Bugs
It can take quite a while to generate some cryptographic values,
from one to several minutes with modern architectures
such as UltraSPARC and up to tens of minutes to an hour
with older architectures such as SPARC IPC.

2201
usr.sbin/ntp/doc/ntp.conf.5
View File

File diff suppressed because it is too large Load Diff

148
usr.sbin/ntp/doc/ntpd.8
View File

@ -1,7 +1,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd August 2, 2001
.Dd May 17, 2006
.Dt NTPD 8
.Os
.Sh NAME
@ -9,13 +9,11 @@
.Nd Network Time Protocol (NTP) daemon
.Sh SYNOPSIS
.Nm
.Op Fl aAbdgLmnPqx
.Op Fl 46aAbDdgLmnPqx
.Op Fl c Ar conffile
.Op Fl D Ar level
.Op Fl f Ar driftfile
.Op Fl k Ar keyfile
.Op Fl l Ar logfile
.Op Fl N Cm high
.Op Fl p Ar pidfile
.Op Fl r Ar broadcastdelay
.Op Fl s Ar statsdir
@ -84,76 +82,94 @@ utility programs.
When
.Nm
starts it looks at the value of
.Xr umask 2 ,
.Cm umask 2 ,
and if zero
.Nm
will set the
.Xr umask 2
.Cm umask 2
to 022.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl 4
Force DNS resolution of following host names to the IPv4 namespace.
.It Fl 6
Force DNS resolution of following host names to the IPv6 namespace.
.It Fl a
Enable authentication mode (default).
Require cryptographic authentication for broadcast client,
multicast client and symmetric passive associations.
This is the default.
.It Fl A
Disable authentication mode.
Do not require cryptographic authentication for broadcast client,
multicast client and symmetric passive associations.
This is almost never a good idea.
.It Fl b
Synchronize using NTP broadcast messages.
Enable the client to synchronize to broadcast servers.
.It Fl c Ar conffile
Specify the name and path of the configuration file.
(Disable
netinfo?)
Specify the name and path of the configuration file, default
.Pa /etc/ntp.conf .
.It Fl d
Specify debugging mode.
This flag may occur multiple times,
Specify debugging mode. This option may occur more than once,
with each occurrence indicating greater detail of display.
.It Fl D Ar level
Specify debugging level directly.
.It Fl f Ar driftfile
Specify the name and path of the drift file.
Specify the name and path of the frequency file, default
.Pa /etc/ntp.drift .
This is the same operation as the
.Ic driftfile Ar driftfile
configuration command.
.It Fl g
Normally,
.Nm
exits if the offset exceeds the sanity
limit, which is 1000 s by default.
If the sanity limit is set to
zero, no sanity checking is performed and any offset is acceptable.
This option overrides the limit and allows the time to be set to
any value without restriction; however, this can happen only once.
After that,
exits with a message to the system log if the offset exceeds
the panic threshold, which is 1000 s by default.
This option allows thetime to be set to any value without restriction;
however, this can happen only once.
If the threshold is exceeded after that,
.Nm
will exit if the limit is exceeded.
This
option can be used with the
will exit with a message to the system log.
This option can be used with the
.Fl q
option.
and
.Fl x
options. See the
.Ic tinker
command for other options.
.It Fl k Ar keyfile
Specify the name and path of the file containing the NTP
authentication keys.
Specify the name and path of the symmetric key file, default
.Pa /etc/ntp.keys .
This is the same operation as the
.Ic keys Ar keyfile
configuration command.
.It Fl l Ar logfile
Specify the name and path of the log file.
The default is the
system log facility.
The default is the system log file.
This is the same operation as the
.Ic logfile Ar logfile
configuration command.
.It Fl L
Listen to virtual IPs.
Do not listen to virtual IPs. The default is to listen.
.It Fl m
Synchronize using NTP multicast messages on the IP multicast
group address 224.0.1.1 (requires multicast kernel).
Enable the client to synchronize to multicast servers at the IPv4 multicast
group address 224.0.1.1.
.It Fl n
Do not fork.
.It Fl N Ar priority
.It Fl N
To the extent permitted by the operating system, run the
.Nm
at a high priority.
at the highest priority.
.It Fl p Ar pidfile
Specify the name and path to record the
.Nm Ns 's
process
ID.
.It Fl P
Override the priority limit set by the operating system.
Not
recommended for sissies.
Specify the name and path of the file used to record the
.Nm
process ID.
This is the same operation as the
.Ic pidfile Ar pidfile
configuration command.
.It Fl P Ar priority
To the extent permitted by the operating system, run the
.Nm
at the specified priority.
.It Fl q
Exit the
.Nm
@ -169,17 +185,22 @@ and
.Fl x
options can
be used with this option.
Note: The kernel time discipline is disabled with this option.
.It Fl r Ar broadcastdelay
Specify the default propagation delay from the
broadcast/multicast server and this computer.
broadcast/multicast server to this client.
This is necessary
only if the delay cannot be computed automatically by the
protocol.
.It Fl s Ar statsdir
Specify the directory path for files created by the statistics
facility.
This is the same operation as the
.Ic statsdir Ar statsdir
configuration command.
.It Fl t Ar key
Add a key number to the trusted key list.
This option can occur more than once.
.It Fl v Ar variable
.It Fl V Ar variable
Add a system variable listed by default.
@ -187,22 +208,20 @@ Add a system variable listed by default.
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 forces the time to be slewed in all
cases.
If the step threshold is set to zero, all offsets are
stepped, regardless of value and regardless of the
.Fl x
option.
In general, this is not a good idea, as it bypasses the
clock state machine which is designed to cope with large time and
frequency errors Note: Since the slew rate is limited to 0.5 ms/s,
each second of adjustment requires an amortization interval of 2000
s.
Thus, an adjustment of many seconds can take hours or days to
amortize.
This option sets the threshold to 600 s,
which is well within the accuracy window to set the clock manually.
Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s,
each second of adjustment requires an amortization interval of 2000 s.
Thus, an adjustment as much as 600 s will take almost 14 days to complete.
This option can be used with the
.Fl g
and
.Fl q
option.
options.
See the
.Ic tinker
command for other options.
Note: The kernel time discipline is disabled with this option.
.El
.Ss "How NTP Operates"
The
@ -216,7 +235,7 @@ the signal processing and mitigation algorithms can accumulate and
groom the data and set the clock.
In order to protect the network
from bursts, the initial poll interval for each server is delayed
an interval randomized over 0-16s.
an interval randomized over a few seconds.
At the default initial poll
interval of 64s, several minutes can elapse before the clock is
set.
@ -322,7 +341,9 @@ The intent of this behavior
is to quickly correct the frequency and restore operation to the
normal tracking mode.
In the most extreme cases
(time.ien.it comes to mind), there may be occasional
(
.Cm time.ien.it
comes to mind), there may be occasional
step/slew corrections and subsequent frequency corrections.
It
helps in these cases to use the
@ -431,7 +452,7 @@ keyword with the
configuration command.
With this
keyword a volley of messages are exchanged to groom the data and
the clock is set in about a minute.
the clock is set in about 10 s.
If nothing is heard after a
couple of minutes, the daemon times out and exits.
After a suitable
@ -506,7 +527,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.
@ -535,7 +556,8 @@ and positive (puff) correction, which depends on the sign of the
offset.
.Pp
The filter is activated by the
.Ic tinker command and
.Ic tinker
command and
.Cm huffpuff
keyword, as described in
.Xr ntp.conf 5 .

19
usr.sbin/ntp/doc/ntpdate.8
View File

@ -1,7 +1,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd January 6, 2000
.Dd May 17, 2006
.Dt NTPDATE 8
.Os
.Sh NAME
@ -9,7 +9,7 @@
.Nd set the date and time via NTP
.Sh SYNOPSIS
.Nm
.Op Fl bBdoqsuv
.Op Fl 46bBdoqsuv
.Op Fl a Ar key
.Op Fl e Ar authdelay
.Op Fl k Ar keyfile
@ -56,6 +56,12 @@ the interval between runs.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl 4
Force DNS resolution of following host names on the command line to the
IPv4 namespace.
.It Fl 6
Force DNS resolution of following host names on the command line to the
IPv6 namespace.
.It Fl a Ar key
Enable the authentication function and specify the key
identifier to be used for authentication as the argument
@ -239,10 +245,17 @@ an alternative to running a daemon, doing so once every hour or two
will result in precise enough timekeeping to avoid stepping the
clock.
.Pp
Note that in contexts where a host name is expected, a
.Fl 4
qualifier preceding the host name forces DNS resolution to the
IPv4 namespace, while a
.Fl 6
qualifier forces DNS resolution to the IPv6 namespace.
.Pp
If NetInfo support is compiled into
.Nm ,
then the
.Ic server
.Cm server
argument is optional if
.Nm
can find a

159
usr.sbin/ntp/doc/ntpdc.8
View File

@ -1,7 +1,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd January 7, 2000
.Dd May 17, 2006
.Dt NTPDC 8
.Os
.Sh NAME
@ -9,9 +9,10 @@
.Nd special NTP query program
.Sh SYNOPSIS
.Nm
.Op Fl ilnps
.Op Fl 46ilnps
.Op Fl c Ar command
.Op Ar host ...
.Op Ar host
.Op Ar ...
.Sh DESCRIPTION
The
.Nm
@ -33,6 +34,12 @@ ntpd's configuration file may also be specified at run time using
.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
@ -51,7 +58,7 @@ standard input.
Obtain a list of peers which are known to the server(s).
This
switch is equivalent to
.Ql -c listpeers .
.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.
@ -59,14 +66,14 @@ than converting to the canonical host names.
Print a list of the peers known to the server as well as a
summary of their state.
This is equivalent to
.Ql -c peers .
.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 -c dmpeers .
.Ql Fl c Ar dmpeers .
.El
.Pp
If one or more request options are included on the command line
@ -115,6 +122,13 @@ utility which affect the
state of the local server must be authenticated, which requires
both the remote program and local server share a common key and key
identifier.
.Pp
Note that in contexts where a host name is expected, a
.Fl 4
qualifier preceding the host name forces DNS resolution to the IPv4 namespace,
while a
.Fl 6
qualifier forces DNS resolution to the IPv6 namespace.
Specifying a command line option other than
.Fl i
or
@ -148,12 +162,12 @@ following.
.It Ic \&? Ar command_keyword
.It Ic help Ar command_keyword
A
.Ic \&?
.Ic Ql \&?
will print a list of all the command
keywords known to this incarnation of
.Nm .
A
.Ic \&?
.Ic Ql \&?
followed by a command keyword will print function and usage
information about the command.
This command is probably a better
@ -287,15 +301,15 @@ A
.Ql \&*
denotes the peer the server is currently
synchronizing with.
.It Ic showpeer Ar peer_address ...
.It Ic showpeer Ar peer_address Oo Ar ... Oc
Shows a detailed display of the current peer variables for one
or more peers.
Most of these values are described in the NTP
Version 2 specification.
.It Ic pstats Ar peer_address ...
.It Ic pstats Ar peer_address Oo Ar ... Oc
Show per-peer statistic counters associated with the specified
peer(s).
.It Ic clockinfo Ar clock_peer_address ...
.It Ic clockinfo Ar clock_peer_address Oo Ar ... Oc
Obtain and print information concerning a peer clock.
The
values obtained provide information on the setting of fudge factors
@ -429,7 +443,7 @@ Obtain and print traffic counts collected and maintained by the
monitor facility.
The version number should not normally need to be
specified.
.It Ic clkbug Ar clock_peer_address ...
.It Ic clkbug Ar clock_peer_address Oo Ar ... Oc
Obtain debugging information for a reference clock driver.
This
information is provided only by some clock drivers and is mostly
@ -535,7 +549,7 @@ address of the local network or a multicast group address assigned
to NTP.
If a multicast address, a multicast-capable kernel is
required.
.It Ic unconfig Ar peer_address ...
.It Ic unconfig Ar peer_address Oo Ar ... Oc
This command causes the configured bit to be removed from the
specified peer(s).
In many cases this will cause the peer
@ -552,108 +566,79 @@ is willing to continue on in this fashion.
This command provides a way to set certain data for a reference
clock.
See the source listing for further information.
.It Ic enable Ar flag ...
.It Ic disable Ar flag ...
.It Xo Ic enable
.Oo
.Cm auth | Cm bclient |
.Cm calibrate | Cm kernel |
.Cm monitor | Cm ntp |
.Cm pps | Cm stats
.Oc
.Xc
.It Xo Ic disable
.Oo
.Cm auth | Cm bclient |
.Cm calibrate | Cm kernel |
.Cm monitor | Cm ntp |
.Cm pps | Cm stats
.Oc
.Xc
These commands operate in the same way as the
.Ic enable
and
.Ic disable
configuration file commands of
.Xr ntpd 8 .
Following is a description of the flags.
Note that only the
.Cm auth ,
.Cm bclient ,
.Cm monitor ,
.Cm pll ,
.Cm pps
and
.Cm stats
flags can be set by
.Nm ;
the
.Cm pll_kernel
and
.Cm pps_kernel
flags are
read-only.
.Bl -tag -width indent
.It Cm auth
Enables the server to synchronize with unconfigured peers only
if the peer has been correctly authenticated using a trusted key
and key identifier.
The default for this flag is enable.
if the peer has been correctly authenticated using either public key
or private key cryptography. The default for this flag is enable.
.It Cm bclient
Enables the server to listen for a message from a broadcast or
multicast server, as in the
.Ic multicastclient
command with
default address.
multicast server, as in the multicastclient command with
default address. The default for this flag is disable.
.It Cm calibrate
Enables the calibrate feature for reference clocks.
The default for this flag is disable.
.It Cm kernel
Enables the kernel time discipline, if available.
The default for this flag is enable if support is available, otherwise disable.
.It Cm monitor
Enables the monitoring facility.
Enables the monitoring facility. See the
.Xr ntpdc 8 .
program and the monlist command or further information.
The default for this flag is enable.
.It Cm ntp
Enables time and frequency discipline.
In effect, this switch opens and closes the feedback loop,
which is useful for testing. The default for this flag is enable.
.It Cm pps
Enables the pulse-per-second (PPS) signal when frequency
and time is disciplined by the precision time kernel modifications.
See the
.Ic monlist
command for further information.
The
default for this flag is enable.
.It Cm pll
Enables the server to adjust its local clock by means of NTP.
If disabled, the local clock free-runs at its intrinsic time and
frequency offset.
This flag is useful in case the local clock is
controlled by some other device or protocol and NTP is used only to
provide synchronization to other clients.
In this case, the local
clock driver is used.
See the
.Qq "Reference Clock Drivers"
page
.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 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"
page for further information.
The default for this flag is
disable.
page for further information. The default for this flag is disable.
.It Cm stats
Enables the statistics facility.
See the
.Sx Monitoring Options
section
of the
section of
.Xr ntp.conf 5
page for further information.
The default for this flag is enable.
.It Cm pll_kernel
When the precision time kernel modifications are installed,
this indicates the kernel controls the clock discipline; otherwise,
the daemon controls the clock discipline.
.It Cm pps_kernel
When the precision time kernel modifications are installed and
a pulse-per-second (PPS) signal is available, this indicates the
PPS signal controls the clock discipline; otherwise, the daemon or
kernel controls the clock discipline, as indicated by the
.Cm pll_kernel
flag.
for further information.
The default for this flag is disable.
.El
.It Xo Ic restrict Ar address Ar mask
.Ar flag ...
.Ar flag Oo Ar ... Oc
.Xc
This command operates in the same way as the
.Ic restrict
configuration file commands of
.Xr ntpd 8 .
.It Xo Ic unrestrict Ar address Ar mask
.Ar flag ...
.Ar flag Oo Ar ... Oc
.Xc
Unrestrict the matching entry from the restrict list.
.It Xo Ic delrestrict Ar address Ar mask
@ -669,8 +654,8 @@ configuration file).
This
allows encryption keys to be changed without restarting the
server.
.It Ic trustedkey Ar keyid ...
.It Ic untrustedkey Ar keyid ...
.It Ic trustedkey Ar keyid Oo Ar ... Oc
.It Ic untrustedkey Ar keyid Oo Ar ... Oc
These commands operate in the same way as the
.Ic trustedkey
and

685
usr.sbin/ntp/doc/ntpq.8
View File

@ -1,7 +1,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd January 7, 2000
.Dd May 17, 2006
.Dt NTPQ 8
.Os
.Sh NAME
@ -11,24 +11,28 @@
.Nm
.Op Fl inp
.Op Fl c Ar command
.Op Ar host ...
.Op Ar host
.Op Ar ...
.Sh DESCRIPTION
The
.Nm
utility is used to query NTP servers
which implement the recommended NTP mode 6 control message format
about current state and to request changes in that state.
The
program may be run either in interactive mode or controlled using
command line arguments.
Requests to read and write arbitrary
variables can be assembled, with raw and pretty-printed output
options being available.
utility is used to monitor NTP daemon
.Xr ntpd 8
operations and determine performance.
It uses the standard NTP mode 6 control message formats
defined in Appendix B of the NTPv3 specification RFC1305.
The same formats are used in NTPv4, although some of the variables
have changed and new ones added.
The description on this page is for the NTPv4 variables.
.Pp
The program can be run either in interactive mode or controlled
using command line arguments.
Requests to read and write arbitrary variables can be assembled,
with raw and pretty-printed output options being available.
The
.Nm
utility can also obtain and print a
list of peers in a common format by sending multiple queries to the
server.
can also obtain and print a list of peers in a common format
by sendingmultiple queries to the server.
.Pp
If one or more request options is included on the command line
when
@ -64,7 +68,7 @@ the remote host is not heard from within a suitable timeout
time.
.Pp
For examples and usage, see the
.Qq "NTP Debugging Techniques"
.Qq NTP Debugging Techniques
page
(available as part of the HTML documentation
provided in
@ -72,6 +76,12 @@ provided in
.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
@ -79,6 +89,8 @@ specified host(s).
Multiple
.Fl c
options may be given.
.It Fl d
Turn on debugging mode.
.It Fl i
Force
.Nm
@ -97,6 +109,12 @@ This is equivalent to the
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
@ -130,12 +148,12 @@ These are described following.
.It Ic \&? Op Ar command_keyword
.It Ic help Op Ar command_keyword
A
.Ql \&?
.Ic Ql \&?
by itself will print a list of all the command
keywords known to this incarnation of
.Nm .
A
.Ql \&?
.Ic Ql \&?
followed by a command keyword will print function and usage
information about the command.
This command is probably a better
@ -176,22 +194,6 @@ while the
.Ic clearlist
command removes all variables from the
list.
.It Ic authenticate Cm yes | Cm 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.
.It Ic cooked
Causes output from query commands to be "cooked", so that
variables which are recognized by
@ -238,11 +240,9 @@ modified using the command line
.Fl n
switch.
.It Ic keyid Ar keyid
This command allows the specification of a key number to be
used to authenticate configuration requests.
This must correspond
to a key number the server has been configured to use for this
purpose.
This command specifies the key number to be used to authenticate
configuration requests. This must correspond to a key number the server has
been configured to use for this purpose.
.It Xo Ic ntpversion
.Cm 1 |
.Cm 2 |
@ -257,16 +257,13 @@ Defaults to 3, Note that mode 6 control messages (and
modes, for that matter) did not exist in NTP version 1.
There appear
to be no servers left which demand version 1.
.It Ic passwd
This command prompts for a password (which will not be echoed) which will
be used to authenticate configuration requests. The password must
correspond to the key configured for NTP server for this purpose.
.It Ic quit
Exit
.Nm .
.It Ic passwd
This command prompts you to type in a password (which will not
be echoed) which will be used to authenticate configuration
requests.
The password must correspond to the key configured for
use by the NTP server for this purpose if such requests are to be
successful.
.It Ic raw
Causes all output from query commands is printed as received
from the remote server.
@ -283,14 +280,11 @@ retries each query once after a timeout, the total waiting time for
a timeout will be twice the timeout value set.
.El
.Ss Control Message Commands
Each peer known to an NTP server has a 16 bit integer association
identifier assigned to it.
NTP control messages which carry peer
variables must identify the peer the values correspond to by
including its association ID.
An association ID of 0 is special,
and indicates the variables are system variables, whose names are
drawn from a separate name space.
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
@ -327,7 +321,7 @@ in
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 of index may be
association identifier as an argument, the form and index may be
used as an alternative.
.It Xo Ic clockvar Op Ar assocID
.Oo
@ -432,261 +426,12 @@ 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 in the left margin indicates the fate of this
peer in the clock selection process.
Following is a list of these
characters, the pigeon used in the
.Ic rv
command, and a short
explanation of the condition revealed.
.Bl -tag -width indent
.It space
.Pq reject
The peer is discarded as unreachable, synchronized to this
server (synch loop) or outrageous synchronization distance.
.It x
.Pq falsetick
The peer is discarded by the intersection algorithm as a
falseticker.
.It \&.
.Pq excess
The peer is discarded as not among the first ten peers sorted
by synchronization distance and so is probably a poor candidate for
further consideration.
.It \&-
.Pq outlyer
The peer is discarded by the clustering algorithm as an
outlyer.
.It \&+
.Pq candidate
The peer is a survivor and a candidate for the combining
algorithm.
.It \&#
.Pq selected
The peer is a survivor, but not among the first six peers
sorted by synchronization distance.
If the association is ephemeral,
it may be demobilized to conserve resources.
.It \&*
.Pq 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
.El
.Pp
The
.Va flash
variable is a valuable debugging aid.
It
displays the results of the original sanity checks defined in the
NTP specification RFC-1305 and additional ones added in NTP Version
4.
There are eleven tests called
.Sy TEST1
through
.Sy TEST11 .
The tests are performed in a certain order
designed to gain maximum diagnostic information while protecting
against accidental or malicious errors.
The
.Va flash
variable
is first initialized to zero.
If after each set of tests one or
more bits are set, the packet is discarded.
.Pp
Tests
.Sy TEST4
and
.Sy TEST5
check the access
permissions and cryptographic message digest.
If any bits are set
after that, the packet is discarded.
Tests
.Sy TEST10
and
.Sy TEST11
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
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.
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.
Test
.Sy 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
The
.Va flash
bits for each test read in increasing order
from the least significant bit are defined as follows.
.Bl -tag -width indent
.It Sy TEST1
Duplicate packet.
The packet is at best a casual retransmission
and at worst a malicious replay.
.It Sy 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 Sy TEST3
Unsynchronized.
One or more timestamp fields are invalid.
This
normally happens when the first packet from a peer is
received.
.It Sy TEST4
Access is denied.
See the
.Qq "Access Control"
page.
.It Sy TEST5
Cryptographic authentication fails.
See the
.Sx Authentication Options
section of
.Xr ntp.conf 5 .
.It Sy TEST6
The server is unsynchronized.
Wind up its clock first.
.It Sy TEST7
The server stratum is at the maximum than 15.
It is probably
unsynchronized and its clock needs to be wound up.
.It Sy TEST8
Either the root delay or dispersion is greater than one second,
which is highly unlikely unless the peer is synchronized to
Mars.
.It Sy TEST9
Either the peer delay or dispersion is greater than one second,
which is highly unlikely unless the peer is on Mars.
.It Sy TEST10
The autokey protocol has detected an authentication failure.
See the
.Sx Authentication Options
section of
.Xr ntp.conf 5 .
.It Sy TEST11
The autokey protocol has not verified the server or peer is
authentic and has valid public key credentials.
See the
.Sx Authentication Options
section of
.Xr ntp.conf 5 .
.El
.Pp
Additional system variables used by the NTP Version 4 Autokey
support include the following:
.Bl -tag -width indent
.It Ic certificate Ar filestamp
Shows the NTP seconds when the certificate file was
created.
.It Ic hostname Ar host
Shows the name of the host as returned by the Unix
.Xr gethostname 3
library function.
.It Ic flags Ar hex
Shows the current flag bits, where the
.Ar hex
bits
are interpreted as follows:
.Bl -tag -width indent
.It 0x01
autokey enabled
.It 0x02
RSA public/private key files present
.It 0x04
PKI certificate file present
.It 0x08
Diffie-Hellman parameters file present
.It 0x10
NIST leapseconds table file present
.El
.It Ic leapseconds Ar filestamp
Shows the NTP seconds when the NIST leapseconds table file was
created.
.It Ic params Ar filestamp
Shows the NTP seconds when the Diffie-Hellman agreement
parameter file was created.
.It Ic publickey Ar filestamp
Shows the NTP seconds when the RSA public/private key files
were created.
.It Ic refresh Ar filestamp
Shows the NTP seconds when the public cryptographic values were
refreshed and signed.
.It Ic tai Ar offset
Shows the TAI-UTC offset in seconds obtained from the NIST
leapseconds table.
.El
.Pp
Additional peer variables used by the NTP Version 4 Autokey
support include the following:
.Bl -tag -width indent
.It Ic certificate Ar filestamp
Shows the NTP seconds when the certificate file was
created.
.It Ic flags Ar hex
Shows the current flag bits, where the
.Ar hex
bits are
interpreted as in the system variable of the same name.
The bits
are set in the first autokey message received from the server and
then reset as the associated data are obtained from the server and
stored.
.It Ic hcookie Ar hex
Shows the host cookie used in the key agreement algorithm.
.It Ic initkey Ar key
Shows the initial key used by the key list generator in the
autokey protocol.
.It Ic initsequence Ar index
Shows the initial index used by the key list generator in the
autokey protocol.
.It Ic pcookie Ar hex
Specifies the peer cookie used in the key agreement
algorithm.
.It Ic timestamp Ar time
Shows the NTP seconds when the last autokey key list was
generated and signed.
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.
@ -721,7 +466,10 @@ system variables, otherwise they are peer variables and the values
returned will be those of the corresponding peer.
Omitting the
variable list will send a request with no data which should induce
the server to return a default display.
the server to return a default display. The
encoding and meaning of the variables derived from NTPv3 is given in
RFC-1305; the encoding and meaning of the additional NTPv4 variables are
given later in this page.
.It Xo Ic writevar Ar assocID
.Ar variable_name Ns Op = Ns Ar value
.Ar ...
@ -732,6 +480,323 @@ written instead of read.
Like the readlist request, except the internal list variables
are written instead of read.
.El
.Ss Tally Codes
The character in the left margin in the
.Sq peers
billboard,
called the tally code, shows the fate of each association
in the clock selection process.
Following is a list of these characters, the pigeon used
in the
.Ic rv
command, and a short explanation of the condition revealed.
.Bl -tag -width indent
.It space
.Pq reject
The peer is discarded as unreachable, synchronized to this server (synch
loop) or outrageous synchronization distance.
.It x
.Pq falsetick
The peer is discarded by the intersection algorithm as a falseticker.
.It \&.
.Pq excess
The peer is discarded as not among the first ten peers sorted by
synchronization distance and so is probably a poor candidate for further
consideration.
.It \&-
.Pq outlyer
The peer is discarded by the clustering algorithm as an outlyer.
.It \&+
.Pq candidat
The peer is a survivor and a candidate for the combining algorithm.
.It \&#
.Pq selected
The peer is a survivor, but not among the first six peers sorted by
synchronization distance. If the association is ephemeral, it may be
demobilized to conserve resources.
.It \&*
.Pq sys.peer
The peer has been declared the system peer and lends its variables to the
system variables.
.It o
.Pq pps.peer
The peer has been declared the system peer and lends its variables to
the system variables. However, the actual system synchronization is derived
from a pulse-per-second (PPS) signal, either indirectly via the PPS
reference clock driver or directly via kernel interface.
.El
.Ss System Variables
The
.Cm status ,
.Cm leap ,
.Cm stratum ,
.Cm precision ,
.Cm rootdelay ,
.Cm rootdispersion ,
.Cm refid ,
.Cm reftime ,
.Cm poll ,
.Cm offset ,
and
.Cm frequency
variables are described in RFC-1305
specification. Additional NTPv4 system variables include the following.
.Bl -tag -width indent
.It version
Everything you might need to know about the software version and generation
time.
.It processor
The processor and kernel identification string.
.It system
The operating system version and release identifier.
.It state
The state of the clock discipline state machine. The values are described
in the architecture briefing on the NTP Project page linked from
www.ntp.org.
.It peer
The internal integer used to identify the association currently designated
the system peer.
.It jitter
The estimated time error of the system clock measured as an exponential
average of RMS time differences.
.It stability
The estimated frequency stability of the system clock measured as an
exponential average of RMS frequency differences.
.El
.Pp
When the NTPv4 daemon is compiled with the OpenSSL software library, additional
system variables are displayed, including some or all of the following,
depending on the particular dance:
.Bl -tag -width indent
.It flags
The current flags word bits and message digest algorithm identifier (NID)
in hex format. The high order 16 bits of the four-byte word contain the NID
from the OpenSSL ligrary, while the low-order bits are interpreted as
follows:
.Bl -tag -width indent
.It 0x01
autokey enabled
.It 0x02
NIST leapseconds file loaded
.It 0x10
PC identity scheme
.It 0x20
IFF identity scheme
.It 0x40
GQ identity scheme
.El
.It hostname
The name of the host as returned by the Unix
.Fn gethostname
library
function.
.It hostkey
The NTP filestamp of the host key file.
.It cert
A list of certificates held by the host. Each entry includes the subject,
issuer, flags and NTP filestamp in order. The bits are interpreted as
follows:
.Bl -tag -width indent
.It 0x01
certificate has been signed by the server
.It 0x02
certificate is trusted
.It 0x04
certificate is private
.It 0x08
certificate contains errors and should not be trusted
.El
.It leapseconds
The NTP filestamp of the NIST leapseconds file.
.It refresh
The NTP timestamp when the host public cryptographic values were refreshed
and signed.
.It signature
The host digest/signature scheme name from the OpenSSL library.
.It tai
The TAI-UTC offset in seconds obtained from the NIST leapseconds table.
.El
.Ss Peer Variables
The
.Cm status ,
.Cm srcadr ,
.Cm srcport ,
.Cm dstadr ,
.Cm dstport ,
.Cm leap ,
.Cm stratum ,
.Cm precision ,
.Cm rootdelay ,
.Cm rootdispersion ,
.Cm readh ,
.Cm hmode ,
.Cm pmode ,
.Cm hpoll ,
.Cm ppoll ,
.Cm offset ,
.Cm delay ,
.Cm dspersion ,
.Cm reftime
variables are described in the RFC-1305 specification, as
are the timestamps
.Cm org ,
.Cm rec
and
.Cm xmt .
Additional NTPv4 system variables include
the following.
.Bl -tag -width indent
.It flash
The flash code for the most recent packet received. The encoding and
meaning of these codes is given later in this page.
.It jitter
The estimated time error of the peer clock measured as an exponential
average of RMS time differences.
.It unreach
The value of the counter which records the number of poll intervals since
the last valid packet was received.
.El
.Pp
When the NTPv4 daemon is compiled with the OpenSSL software library, additional
peer variables are displayed, including the following:
.Bl -tag -width indent
.It flags
The current flag bits. This word is the server host status word with
additional bits used by the Autokey state machine. See the source code for
the bit encoding.
.It hostname
The server host name.
.It initkey Ar key
The initial key used by the key list generator in the Autokey protocol.
.It initsequence Ar index
The initial index used by the key list generator in the Autokey protocol.
.It signature
The server message digest/signature scheme name from the OpenSSL software
library.
.It timestamp Ar time
The NTP timestamp when the last Autokey key list was generated and signed.
.El
.Ss Flash Codes
The
.Cm flash
code is a valuable debugging aid displayed in the peer variables
list. It shows the results of the original sanity checks defined in the NTP
specification RFC-1305 and additional ones added in NTPv4. There are 12 tests
designated
.Sy TEST1
through
.Sy TEST12 .
The tests are performed in a certain order
designed to gain maximum diagnostic information while protecting against
accidental or malicious errors. The
.Sy flash
variable is initialized to zero as
each packet is received. If after each set of tests one or more bits are set,
the packet is discarded.
.Pp
Tests
.Sy TEST1
through
.Sy TEST3
check the packet timestamps from which the offset and
delay are calculated. If any bits are set, the packet is discarded; otherwise,
the packet header variables are saved.
.Sy TEST4
and
.Sy TEST5
are associated with
access control and cryptographic authentication. If any bits are set, the
packet is discarded immediately with nothing changed.
.Pp
Tests
.Sy TEST6
through
.Sy TEST8
check the health of the server. If any bits are set,
the packet is discarded; otherwise, the offset and delay relative to the server
are calculated and saved. TEST9 checks the health of the association itself. If
any bits are set, the packet is discarded; otherwise, the saved variables are
passed to the clock filter and mitigation algorithms.
.Pp
Tests
.Sy TEST10
through
.Sy TEST12
check the authentication state using Autokey
public-key cryptography, as described in the
.Sx Authentication Options
section of
.Xr ntp.conf 5 .
If
any bits are set and the association has previously been marked reachable, the
packet is discarded; otherwise, the originate and receive timestamps are saved,
as required by the NTP protocol, and processing continues.
.Pp
The
.Cm flash
bits for each test are defined as follows.
.Bl -tag -width indent
.It 0x001
.Pq TEST1
Duplicate packet. The packet is at best a casual retransmission and at
worst a malicious replay.
.It 0x002
.Pq TEST2
Bogus packet. The packet is not a reply to a message previously sent. This
can happen when the NTP daemon is restarted and before somebody else
notices.
.It 0x004
.Pq TEST3
Unsynchronized. One or more timestamp fields are invalid. This normally
happens when the first packet from a peer is received.
.It 0x008
.Pq TEST4
Access is denied. See the
.Sx Access Control Support
section of
.Xr ntp.conf 5 .
.It 0x010
.Pq TEST5
Cryptographic authentication fails. See the
.Sx Authentication Options
section of
.Xr ntp.conf 5 .
.It 0x020
.Pq TEST6
The server is unsynchronized. Wind up its clock first.
.It 0x040
.Pq TEST7
The server stratum is at the maximum than 15. It is probably unsynchronized
and its clock needs to be wound up.
.It 0x080
.Pq TEST8
Either the root delay or dispersion is greater than one second, which is
highly unlikely unless the peer is unsynchronized to Mars.
.It 0x100
.Pq TEST9
Either the peer delay or dispersion is greater than one second, which is
higly unlikely unless the peer is on Mars.
.It 0x200
.Pq TEST10
The autokey protocol has detected an authentication failure. See the
.Sx Authentication Options
section of
.Xr ntp.conf 5 .
.It 0x400
.Pq TEST11
The autokey protocol has not verified the server or peer is proventic and
has valid public key credentials. See the
.Sx Authentication Options
section of
.Xr ntp.conf 5 .
.It 0x800
.Pq TEST12
A protocol or configuration error has occurred in the public key algorithms
or a possible intrusion event has been detected. See the
.Sx Authentication Options
section of
.Xr ntp.conf 5 .
.El
.Sh SEE ALSO
.Xr ntp.conf 5 ,
.Xr ntpd 8 ,