Keep oss-fuzz happy

[ntpsec.git] / docs / quick.adoc

= Client Quick Start Guide
include::include-html.ad[]

[cols="10%,90%",frame="none",grid="none",style="verse"]
|==============================
|image:pic/orchestra.gif[]|
{millshome}pictures.html[from 'Pogo', by Walt Kelly]

Take it away, boys!

|==============================


== Related Links

include::includes/hand.adoc[]

== Table of Contents

* link:#introduction[Introduction]
* link:#basics[Configuration Basics]
* link:#pool[Using the NTP Pool]
* link:#howmany[How Many Servers?]
* link:#gps[Configuring A Local GPS]
* link:#dhcp[Special considerations when using DHCP]
* link:#sanity[Sanity-Checking Your Time Service]
* link:#security[Network Time Security]

'''''

[[introduction]]
== Introduction

This page is a quick start for the 99% of NTP configurations that are
not intended to serve time to others, but just run in client mode and
optionally have a local GPS reference clock. It describes how to
write a basic +{ntpconf}+ configuration file for this common case,
and introduces some concepts that will be useful later on in the
Handbook.

If you installed NTPsec using a distro package, the package's stock
configuration may not need any changes.  You can use this guide to
understand the default configuration.  If you installed NTPsec from
source, this guide will help you build your configuration.

It is very likely that your NTP configuration file, +{ntpconf}+ ,
resides in +/etc+ .  On Debian (and derivatives), it is
in +/etc/ntpsec+ if you installed from the package.

If you are using a typical residential setup, in which your machine
performs DHCP to your ISP's servers and receives a dynamic address,
your +{ntpconf}+ may be altered or generated by DHCP at
address-allocation time to use the NTP servers provided by DHCP.

NTPsec, unlike legacy versions, can also be configured using an
Apache-style directory +/etc/ntp.d/+ of configuration-file segments.
This is intended to make life easier for software configurators, which
can write independent segments rather than having to do the kind of
edit-in-place on a flat +{ntpconf}+ that comes naturally to a human.

[[basics]]
== Configuration basics

An NTP configuration file normally consists of three sections: logging
controls, security/access controls, and +server+/+refclock+ declarations.  In
most configurations, the first two sections will be a boilerplate set
of defaults.

Under +/etc/ntp.d/+, the text in these segments can be split up into file
parts (with names ending in .conf) in any way that is convenient.
Parts are evaluated in the text sort order of their names.

The simplest, minimal logging configuration consists of a line like this:

------------------------------------------------------------------
driftfile /var/lib/ntp/ntp.drift
------------------------------------------------------------------

This sets up a drift file, which is used to store a measurement of
the drift frequency of your computer's clock crystal between runs
of +ntpd+. The drift is used to converge on correct time more quickly
after startup.

You might see something more like this:

------------------------------------------------------------------
driftfile /var/lib/ntp/ntp.drift

statsdir /var/log/ntpstats/

statistics loopstats peerstats clockstats
filegen loopstats file loopstats type day enable
filegen peerstats file peerstats type day enable
filegen clockstats file clockstats type day enable

logfile /var/log/ntpd.log
logconfig =syncall +clockall +peerall +sysall
------------------------------------------------------------------

This is a logging section intended to enable extensive statistics and
diagnostics useful for tuning your time service.

Note that the directories in which the log files are being created
need to exist, and be writable by the user under which +ntpd+ runs.

Your security/access section will almost always look a lot like this:

------------------------------------------------------------------
restrict default kod limited nomodify noquery
restrict 127.0.0.1
restrict ::1
------------------------------------------------------------------

This disallows configuration or +ntpq+ queries from anywhere off the
local system.  Older configurations may duplicate the +restrict default+
line into a +restrict -6 default+ and/or use +-6+ on the IPv6 localhost
exception. These are no longer necessary, but not harmful.

The server/refclock declarations are the most variable part of the
configuration.  They tell +ntpd+ what its sources for time are.

[[pool]]
== Using the NTP Pool

The NTP Pool is a dynamic collection of publicly available servers
that freely provide highly accurate time via the Network Time Protocol to
clients worldwide. The machines that are "in the pool" are part of the
pool.ntp.org domain as well as many subdomains divided by geographical region
or software vendor, and are distributed to NTP clients via round robin DNS.

Your +{ntpconf}+ can use one or several of these DNS names.  The
https://www.ntppool.org/en/use.html[NTP Pool documentation] gives this
example (but see below for a better version):

------------------------------------------------------------------
server 0.pool.ntp.org
server 1.pool.ntp.org
server 2.pool.ntp.org
server 3.pool.ntp.org
------------------------------------------------------------------

In a pre-configured NTP installation set up by an OS vendor or distribution
packager, you are likely to see a set of time-server declarations pointing
at a vendor subdomain of the NTP Pool (+0.vendor.pool.ntp.org+, etc.).

Multiple declarations of individual pool servers is not the best
method; they're a workaround for a historical bug in NTP Classic.  It's
better to use the +pool+ directive:

------------------------------------------------------------------
pool 0.pool.ntp.org
pool 1.pool.ntp.org
pool 2.pool.ntp.org
pool 3.pool.ntp.org
------------------------------------------------------------------

Use of the +server+ command does a one-time DNS lookup, and uses the IP
address returned thereafter.  If the server becomes unavailable, the DNS name
will not be re-resolved.  The +pool+ command will use multiple servers that
the DNS name resolves to, refreshing as required.  For details on the
refreshing algorithm, see link:discover.html#assoc[Association Management].
The number of associations is controlled by the +maxclock+ option of the
link:miscopt.html#tos[+tos+] command, which should typically be changed from
the default.

Using only a single pool entry has some limitations:

------------------------------------------------------------------
# This works, but is IPv4 only and spins up associations slower:
pool pool.ntp.org

# Likewise for 0, 1, or 3:
pool 0.pool.ntp.org

# Only the "2" hostname has IPv6 currently, so this works with both IPv4
# IPv6, but still spins up associations slower than using all four names:
pool 2.pool.ntp.org

# Vendor domains do not work with only the top-level name:
pool vendor.pool.ntp.org

# The numbers work with vendor subdomains, with the same caveats:
pool 0.vendor.pool.ntp.org
------------------------------------------------------------------

Note: while you could in theory request time service from any specific
time server in the world, it is considered bad form to use a non-pool
server unless you know you have permission.  This applies, in
particular, to various public timeservers maintained by corporations
or academic institutions and intended to be used by their members.

For high-quality time service, it is advantageous if your upstream
servers are located where packet-transit times to you are short and
there is little random variation in them.  Unfortunately, "near you on the
network" is often difficult to map and changes unpredictably over time.
However, there is a very rough correlation with national boundaries--more
so when the country in question is geographically small and relatively
advanced.

The NTP Pool DNS servers try to give you servers in the same country
or continent, but this is not guaranteed.  Accordingly, the NTP
Pool has subdomains for many countries, named by ISO country code.
If you are in the United Kingdom, for example, you might want to use the UK
subdomain:

------------------------------------------------------------------
pool 0.uk.pool.ntp.org
pool 1.uk.pool.ntp.org
pool 2.uk.pool.ntp.org
pool 3.uk.pool.ntp.org
------------------------------------------------------------------

If you know your ISO country code, it is often possible to find an
analogous group of servers by pinging them.

Ideally, one would like one's servers to use multiple different kinds
of timesources (as opposed to, say, all being GPS-based) and be split
across different autonomous networks as a hedge against outages and
routing problems.  Unfortunately, the random nature of pool allocation
makes this impossible to guarantee. It is, however, worth keeping in mind if
you can set up a custom configuration with non-pool servers that you
have permission to use.

[[howmany]]
== How Many Servers?

If you have only one server, things are simple.  Your system will
follow that server even if it doesn't have the correct time.  (Your
server might bail if the local clock is too far off - see
link:clock.html#panic[panic threshold].)

Two servers might seem like a simple redundant setup, but what happens
if they don't agree?  NTP has no way to determine which one is
correct.

If you have three servers, two can outvote a
link:ntpspeak.html[falseticker].  But that reduces to two if one of
them is not responding.

If you are using 4 servers, you still have 3 if one of them stops
responding.  Unless you are serving time to other systems,
this is a reasonable setup. It is normal for client-only systems.

You can add more servers.  With 5 servers, you still have 3 if 2 are
down and 3 can outvote 2 falsetickers.  That may be appropriate if you
need high reliability, say because you are serving hundreds of
clients.

One +pool+ declaration will normally get you four or more servers.

[[gps]]
== Configuring A Local GPS

Connecting a local GPS to your machine will provide extremely
accurate time, provided it has link:ntpspeak.html[PPS] capability.
However, unless your GPS has a perfect continuous skyview, you will still
want to use servers from the link:#pool[the NTP Pool] or elsewhere.

The easiest way to arrange this is by installing
https://gpsd.io[GPSD] to watch the GPS, and configuring your
+ntpd+ to accept time from it.  It is also possible to do this with
native +ntpd+ drivers (nmea, trimble, oncore), though these are less
flexible and a bit more difficult to configure.

The following configuration lines tell your +ntpd+ to accept time
from GPSD:

------------------------------------------------------------------
refclock shm unit 1 prefer refid PPS
refclock shm unit 0 refid GPS
------------------------------------------------------------------

Note the order above; +ntpd+ prefers earlier defined refclocks
to later.  PPS is significantly more accurate than the in-band stream.

For details on setting up the GPSD end, see the
https://gpsd.io/gpsd-time-service-howto.html[GPSD Time Service
HOWTO].

If you are looking to set up a Stratum 1 timeserver, you may find
https://www.ntpsec.org/white-papers/stratum-1-microserver-howto/[Stratum-1-Microserver HOWTO]
helpful.

[[dhcp]]
== Special considerations when using DHCP

If your machine uses DHCP to get a dynamic IP address from your ISP,
that handshake may provide you with a list of NTP servers.
Suspect this if, when you look at your +{ntpconf}+, you
see server domain names obviously belonging to your ISP or
your ntpq -p printout doesn't match what you expect.

The way this works is that your DHCP client requests the list,
then it restarts your +ntpd+ with a custom configuration file
generated from that list.

A good thing about this is that your ISP is likely to hand you servers
that are close to you on its network and will thus have fairly steady
ping times.  A bad thing is that you may have difficulty making
configuration of a local reference clock stick.

If you look in your +/etc/init.d/ntp+ file, systemd unit, or other scripts
involved in starting +ntpd+, you may see something like this:

------------------------------------------------------------------
if [ -e /var/lib/ntp/ntp.conf.dhcp ]; then
        NTPD_OPTS="$NTPD_OPTS -c /var/lib/ntp/ntp.conf.dhcp"
fi
------------------------------------------------------------------

The -c option tells +ntpd+ that the path to a generated configuration
file follows.  The generation process might pick up your local changes
to +{ntpconf}+ or it might not; this depends on your OS supplier. (Debian
derivatives normally 'do' base on your local +{ntpconf}+.)  If it does,
all is well.  If it does not, you may have to modify the hook scripts
that generate that file, or disable the generation process.

You may also wish to ignore the DHCP-provided servers for other reasons.
For example, you may wish to use specific servers which support
link:#security[Network Time Security].  On Debian derivatives, if you
installed from the package, you can set +IGNORE_DHCP="yes"+ in
+/etc/default/ntpsec+ to ignore DHCP-provided NTP servers.

[[sanity]]
== Sanity-Checking Your Time Service

Here's how to tell if and/or how well your time service is working.
Wait a few minutes for it to sync with upstream servers, then fire
up ntpq with the -p (peers) option.  You should see a display looking
something like this:

------------------------------------------------------------------
     remote           refid      st t when poll reach   delay   offset  jitter
==============================================================================
*b1-66er.matrix. 18.26.4.105      2 u  871 1024  377    6.655    1.042   0.659
+tools.ninjaneer 216.218.254.202  2 u  268 1024  377   69.917    0.275   0.858
-96.226.123.230  129.7.1.66       2 u  689 1024  377   43.322   -2.322   0.982
-a1.pcloud.com   18.26.4.105      2 u  861 1024  377   41.805   -2.283   0.453
+juniperberry.ca 17.253.34.253    2 u  682 1024  377   82.361    0.927   1.370
------------------------------------------------------------------

If you have a local GPS you should see something like this:

------------------------------------------------------------------
     remote           refid      st t when poll reach   delay   offset  jitter
==============================================================================
xSHM(0)          .GPS.            0 l   39   64  377    0.000  -591.41  70.967
*SHM(1)          .PPS.            0 l   43   64  377    0.000    0.003   0.004
+time-a.timefreq .ACTS.           1 u    5   64  377   48.438    0.487   3.163
-time-a.nist.gov .ACTS.           1 u   23   64  377   73.233   32.901   0.587
-fwwds-1-pt.tunn 173.162.192.156  2 u   11   64  377   48.311   -2.082   2.649
+clocka.ntpjs.or 192.5.41.40      2 u   22   64  377   13.146    0.743   0.644
------------------------------------------------------------------

In the latter table, the first two lines represent the refclock.

In both cases, the column to look at first is the "reach". A value of
377 indicates that your client has been getting samples continuously
for eight poll intervals.  A value of 0 is bad - it means you're not
communicating with the upstream server or clock at all.  To interpret other
values, you need to interpret the reach column in octal, expand
it to binary, and read each bit as a yes/no for its poll interval
Thus, for example, 017 means samples from the last four polls but
none before that.

Next, you want to look at the line for "preferred" server (marked with
*).  This is the one that is closest to the approximation of UTC that
NTP's algorithms have computed from its inputs. What you want to see here
is low jitter. The PPS feed in the second example is pretty good. The
figures from +b1-66er.matrix.+ in the first display are not great, but
they're not out of line for operation over a WAN.

Large offsets are most likely due to asymmetric packet delays; large
jitter is more likely due to bufferbloat and other sources of variable
latency under load.  Note that the units for delay, offset, and jitter
are milliseconds.

[[security]]
== Network Time Security

The NTP protocol will work with unauthenticated servers, this is what
makes the NTP Pool Project feasible.  However, to close off some lines of
attack on NTP, especially spoofing and Man-In-The-Middle, NTPsec supports
Network Time Security (NTS).  Further information on how to enable NTS is
available in the link:NTS-QuickStart.html[NTS Quick Start Guide].

'''''

include::includes/footer.adoc[]