pic/orchestra.gif
from Pogo, by Walt Kelly Take it away, boys!

Table of Contents

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 /etc/ntp.conf configuration file for this common case, and introduces some concepts that will be useful later on in the Handbook.

If your NTP configuration was installed from a binary package (such as a deb or RPM file under Linux) you can use this introduction as a guide to reading it, but may not have to modify it at all.

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 ntp.conf may be altered or generated by DHCP at address-allocation time to use the NTP servers provided by DHCP.

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.

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 maximum statistics and diagnostics useful for tuning your time service.

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

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

This disallows configuration or ntpq queries from anywhere off the local system.

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

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-specific set of NTP pool servers. Under Ubuntu Linux, for example, it probably looks like this:

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

The next section will explain what pool servers are and why you might want to change them.

Configuring Pool Servers

The NTP pool is a worldwide federation of public-facing NTP servers, many equipped with their own local reference clocks, that have volunteered to provide time service to anyone who requests it through a pool dispatcher machine. The server declarations in your /etc/ntp.conf normally point at several of these pool dispatchers. When your ntpd send a request to one, it picks a random server from its part of the pool and hands that address back to your ntpd.

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. Because the NTP pool is worldwide, accepting a random assignment from it may give you a timeserver on the other side of the world. Thus, the pool is divided into subsections, each with its own dispatchers. To improve your service, pick a pool section near you on the network.

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. Accordingly, the NTP pool has national sections for many countries, named by ISO country code.

If you are in Great Britain, for example, you might want to use the UK section of the pool:

server 0.uk.pool.ntp.org
server 1.uk.pool.ntp.org
server 2.uk.pool.ntp.org
server 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.

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 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 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.

Configuring A Local GPS

Connecting a local GPS to your machine will provide extremely accurate time, provided it has PPS capability. (However, unless your GPS has a perfect continuous skyview, you will still want check servers from the pool.)

The easiest way to arrange this is by installing 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, jupiter, 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 0 refid GPS
refclock shm unit 1 prefer refid PPS

For details on setting up the GPSD end, see the GPSD Time Service HOWTO.

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 ntp.conf, 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.

One family of systems with this behavior is Debian Linux, including Ubuntu. On these systems the DHCP client is NetworkManager. If you look in your /etc/init.d/ntp file, 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 ntp.conf or it might not; this depends on your OS supplier (Debian derivatives normally do base on your local ntp.conf). 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.

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

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 18.26.4.105 in the first display are not great, but they’re not out of line for operation over a WAN. Offset over a second is most likely due to asymmetric packet delays; large jitter is more likely due to bufferbloat and other sources of variable latency under load.


icons/home.gif Home Page

icons/sitemap.png Site Map

icons/mail2.gif Contacts