// This is the body of the manual page for ntpd.conf.
// It's included in two places: once for the docs/ HTML
// tree, and once to make an individual man page.

== SYNOPSIS
/etc/ntpsec/ntp.conf

== DESCRIPTION

The `ntp.conf` configuration file is read at initial startup by the
{ntpdman} daemon in order to specify the synchronization
sources, modes, and other related information. Usually, it is installed
in the `/etc` directory, but could be installed elsewhere (see the
daemon's `-c` command line option).

The file format is similar to other UNIX configuration files. Comments
begin with a ‘#’ character and extend to the end of the line; blank
lines are ignored. Configuration commands consist of an initial keyword
followed by a list of arguments, some of which may be optional,
separated by whitespace. Commands may not be continued over multiple
lines. Arguments may be host names, host addresses written in numeric,
dotted-quad form, integers, floating point numbers (when specifying
times in seconds) and text strings.

Configuration files may have inclusion lines.  The syntax is +includefile+
followed by whitespace followed by a file or directory name.  The
configuration is evaluated as though the text of the file - or all
files of the directory with the extension ".conf" - were textually
spliced in at the point of the include. Relative paths will work, even
when the -c option changes the config directory root.

The rest of this page describes the configuration and control options.
The "Notes on Configuring NTP and Setting up an NTP Subnet" page
(available as part of the HTML documentation provided under
`/usr/share/doc/ntp`) contains an extended discussion of these options.
In addition to the discussion of general 'Configuration Options',
there are sections describing the following supported functionality and
the options used to control it:

* Authentication Support
* NTS Support
* Monitoring Support
* Access Control Support
* Automatic NTP Configuration Options
* Reference Clock Support
* Miscellaneous Options

Following these is a section describing 'Miscellaneous Options'.
While there is a rich set of options available, the only required
option is one or more `pool`, `server`, `peer`, or `broadcast`
commands.

== Configuration Support

Following is a description of the configuration commands in
NTPv4. There are two classes of commands, association commands that
configure a persistent association with a remote server or peer or
reference clock, and auxiliary commands that specify environment
variables that control various related operations.

=== Association Commands

Only those options applicable to each command are listed below. Use of
options not listed may not be caught as an error, but may result in
some weird and even destructive behavior.

In contexts where a host name is expected, a `-4` or `--ipv4`
qualifier preceding the host name forces DNS resolution to the IPv4
namespace, while a `-6` or `--ipv6` qualifier forces DNS resolution to
the IPv6 namespace.

include::../includes/assoc-commands.adoc[]

=== Association Options

include::../includes/assoc-options.adoc[]

=== Association Auxiliary Commands

include::../includes/assoc-auxcommands.adoc[]

=== Authentication Commands

include::../includes/auth-commands.adoc[]

=== NTS Commands

include::../includes/nts-commands.adoc[]

[[monit]]
== Monitoring Support

{ntpdman} includes a comprehensive monitoring facility suitable
for continuous, long term recording of server and client timekeeping
performance. See the +statistics+ command below for a listing and example of
each type of statistics currently supported. Statistic files are managed
using file generation sets and scripts in the ./scripts directory of this
distribution. Using these facilities and UNIX cron(8) jobs, the data
can be automatically summarized and archived for retrospective
analysis.

=== Monitoring Commands

include::../includes/mon-commands.adoc[]

== Access Control Support

The {ntpdman} 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. A match occurs when the bitwise AND of the mask and the packet
source address is equal to the bitwise AND of the mask and address in
the list. The list is searched in order with the last match found
defining the restriction flags associated with the entry. Additional
information and examples can be found in the "Notes on Configuring NTP
and Setting up a NTP Subnet" page (available as part of the HTML
documentation).

The restriction facility was implemented in conformance with the access
policies for the original NSFnet backbone time servers. Later the
facility was expanded to deflect cryptographic and clogging attacks.
While this facility may be useful for keeping unwanted or broken or
malicious clients from congesting innocent servers, it should not be
considered an alternative to the NTP authentication facilities. Source
address based restrictions are easily circumvented by a determined
cracker.

Clients can be denied service because they are explicitly included in
the restrict list created by the restrict command or implicitly as the
result of cryptographic or rate limit violations. Cryptographic
violations include certificate or identity verification failures; rate
limit violations generally result from defective NTP implementations
that send packets at abusive rates. Some violations cause denied service
only for the offending packet, others cause denied service for a timed
period and others cause the denied service for an indefinite period.
When a client or network is denied access for an indefinite period, the
only way at present to remove the restrictions is by restarting the
server.

=== The Kiss-of-Death Packet

Ordinarily, packets denied service are simply dropped with no further
action except incrementing statistics counters. Sometimes a more
proactive response is needed, such as a server message that explicitly
requests the client to stop sending and leave a message for the system
operator. A special packet format has been created for this purpose
called the "kiss-of-death" (KoD) packet. KoD packets have the leap bits
set unsynchronized and stratum set to zero and the reference identifier
field set to a four-byte ASCII code. If the `noserve` or `notrust` flag
of the matching restrict list entry is set, the code is "DENY"; if the
`limited` flag is set and the rate limit is exceeded, the code is
"RATE". Finally, if a cryptographic violation occurs, the code is
"CRYP".

A client receiving a KoD performs a set of sanity checks to minimize
security exposure, then updates the stratum and reference identifier
peer variables, sets the access denied (BOGON4) bit in the peer flash
variable and sends a message to the log. As long as the BOGON4 bit is
set, the client will send no further packets to the server. The only way
at present to recover from this condition is to restart the protocol at
both the client and server. This happens automatically at the client
when the association times out. It will happen at the server only if the
server operator cooperates.

== Access Control Commands

include::../includes/access-commands.adoc[]

== Automatic NTP Configuration Options

=== Manycasting

For a detailed description of manycast operation, see the "Server
Discovery" page (available as part of the HTML documentation).

=== Manycast Options

// This is a subset of the tos options applicable to manycast.
// It omits the more general tinkering options.  If you change this,
// be very sure to keep docs/miscopt.adoc synchronized.

`tos` [`ceiling` _ceiling_ | `floor` _floor_ | `minclock` _minclock_ | `minsane` _minsane_]::
  This command affects the clock selection and clustering algorithms. It
  can be used to select the quality and quantity of peers used to
  synchronize the system clock and is most useful in manycast mode. The
  variables operate as follows:

  `ceiling` _ceiling_;;
    Peers with strata above _ceiling_ will be discarded if there are at
    least _minclock_ peers remaining. This value defaults to 15, but can
    be changed to any number from 1 to 15.
  `floor` _floor_;;
    Peers with strata below _floor_ will be discarded if there are at
    least _minclock_ peers remaining. This value defaults to 1, but can
    be changed to any number from 1 to 15.
  `minclock` _minclock_;;
    The clustering algorithm repeatedly casts out outlier associations
    until no more than _minclock_ associations remain. This value
    defaults to 3, but can be changed to any number from 1 to the number
    of configured sources.
  `minsane` _minsane_;;
    This is the minimum number of candidates available to the clock
    selection algorithm in order to produce one or more truechimers for
    the clustering algorithm. If fewer than this number are available,
    the clock is undisciplined and allowed to run free. The default is 1
    for legacy purposes. However, according to principles of Byzantine
    agreement, _minsane_ should be at least 4 in order to detect and
    discard a single falseticker.

== Reference Clock Support

For a detailed description of reference-clock configuration, see the
"Reference Clock Drivers" page (available as part of the HTML
documentation provided in `/usr/share/doc/ntp`).

== Reference Clock Commands

include::../includes/clock-options.adoc[]

== Miscellaneous Options

include::../includes/misc-options.adoc[]

== FILES

`/etc/ntpsec/ntp.conf`::
  the default name of the configuration file
`/etc/ntpsec/ntp.keys`::
  private keys

One of the following exit values will be returned:

0 (EXIT_SUCCESS)::
  Successful program execution.
1 (EXIT_FAILURE)::
  The operation failed or the command syntax was not valid.

== SEE ALSO

{ntpdman}, {ntpqman}.

In addition to the manual pages provided, comprehensive documentation is
available on the world wide web at {project-website}. A snapshot of
this documentation is available in HTML format in `/usr/share/doc/ntp`.

David L. Mills, _Network Time Protocol (Version 4)_, RFC 5905

== BUGS

The syntax checking is not picky; some combinations of ridiculous and
even hilarious options and modes may not be detected.