Configuration
-------------

The default ntp.conf file is set up for an NTP "client" that
synchronizes to high-stratum NTP servers on the Internet.  This should
be sufficient for most installations on well-connected hosts that
simply want to keep their clocks accurate.

The default time servers are servers from a pool.ntp.org vendor zone
assigned to Debian.  Consider replacing this if you have local time
servers in your organization or network.  A list of public NTP time
servers is available on the web at:

    http://ntp.isc.org/bin/view/Servers/WebHome

Extra configuration work will be necessary to offer time service to
other hosts, to use hardware time receivers, or to synchronize the
clocks on networks that are not connected to the Internet.  The
documentation in the package ntpsec-doc will assist with these tasks.


Refclock Changes
----------------

There is a new syntax for configuring refclocks that uses names
instead of numbers encoded in loopback IP addresses.  The old syntax
is accepted for backwards compatibility.

Many refclock drivers have been removed upstream.  Several have been
disabled in this package.

If you were using the Type 45 GPSD client protocol (JSON) driver, you
will need to switch to the SHM driver.

Two drivers have new device path prefixes:
    Type  4 - Generic Spectracom Receivers
      /dev/wwvb0 -> /dev/spectracom0
    Type 29 - Trimble Palisade/Thunderbolt/Acutime GPSes
      /dev/palisade0 -> /dev/trimble0
Both of these drivers, plus these two have been deprecated:
    Type 11 - Arbiter 1088A/B GPS Receiver
    Type 44 - NeoClock4X DCF77 / TDF Receiver
If you use any of these, please alert the package maintainer or the
upstream NTPsec project right away.

While not deprecated, if you use the Type 20 Generic NMEA GPS Receiver
driver, you should strongly consider switching to the gpsd and the SHM
driver.

If you use the SHM driver and apparmor, see the note in:
/etc/apparmor.d/usr.sbin.ntpd


ntpviz
------

A visualization utility, ntpviz, is available in the ntpsec-ntpviz
package.  When installed, it will configure (by way of an /etc/ntp.d
file) ntpd to log stats.  It adds systemd units and cron jobs that
generate daily and weekly graphs from those stats.  If Apache is
installed, these will be served at /ntpviz/ by default.


DHCP
----

If DHCP is used to configure the host, and the DHCP server sends
information about NTP servers, then this information will be used
automatically.  This is done by making a copy of /etc/ntp.conf at
/run/ntp.conf.dhcp, replacing the server entries with the
information provided by the DHCP server, and restarting the NTP
server.

In order for this to work, the "ntp-servers" option must be mentioned
in the "request" statement in /etc/dhcp/dhclient.conf.  This is not
the case in a default installation.  A complete configuration might
look like this, for example:

    request subnet-mask, broadcast-address, time-offset, routers,
            domain-name, domain-name-servers, host-name,
            netbios-name-servers, netbios-scope, interface-mtu,
            ntp-servers;

If you don't like using the NTP servers sent by the DHCP server, this
is also the right place to turn off this behavior.

To make the DHCP server in the Debian package isc-dhcp-server send NTP
server information, add a line like the following at an appropriate
place:

    option ntp-servers ntp1.foo.bar, ntp2.foo.bar;


SMP Systems
-----------

Several people have reported that ntpd fails on SMP boxes unless the
"Enhanced Real-Time Clock" support is enabled in the kernel.  This is
known to be essential on SMP Alpha systems, and is believed to also be
necessary on SMP Intel systems.


Logging
-------

By default, ntpd will log via syslog.  The daemon will use the
LOG_DAEMON facility, leading to ntpd log entries going to
/var/log/daemon.log.  If you define a logfile location in
/etc/ntp.conf, the daemon will do direct file system writes to the
specified file, avoiding syslog.  Previous Debian packages did this,
with the side effect that they had to ship a weekly cron job that
stopped the daemon, rotated the log, then restarted the daemon.  This
is moderately evil for high-stratum NTP servers, where ntpd should be
allowed to run more or less forever.  This mode of logging is not
recommended and no longer supported by the Debian packages.


NTP and hwclock Issues
----------------------

hwclock (from the util-linux package) is normally called on startup
and shutdown.  You should ensure that hwclock --adjust is never called
(make sure it is disabled in /etc/init.d/hwclock.sh; this is the
default in new Debian installations).

You should allow hwclock --systohc to be called on shutdown unless you
are running the NANO kernel patch, because the kernel does not fully
update the RTC time, and it could be off by a multiple of 30 minutes
in the next boot if hwclock --systohc is never called by the shutdown
sequence.  See the hwclock README files in the util-linux
documentation for more information.


Firewalls
---------

If your system is behind a firewall, the port you need to open up to
allow the NTP protocol to work (for either ntpdate or ntpd) is UDP
port 123.  Server-to-server NTP packets usually use this for both
source and destination: for extra security, a stateful firewall should
block "new" packets with source, but not destination, port 123 from
entering your network.


Keys
----

ntpkeygen can be used to generate an MD5 ntp.keys file in /etc.  Use
of these keys has not yet been tested; please report success or
failure in using them to the maintainer.


PPS
---

This build of ntpd has been PPS enabled. You can use a PPS reference clock.
To achieve better accuracy, you may need to rebuild your kernel with
CONFIG_NTP_PPS, which need CONFIG_NO_HZ=n to be set.  You may also add
CONFIG_RCU_FAST_NO_HZ.

You can find more information there:
- https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=691672#41
- https://docs.ntpsec.org/latest/pps.html
- https://docs.ntpsec.org/latest/kernpps.html


Apparmor Profile
----------------

If your system uses AppArmor, please note that the shipped enforcing profile
works with the default installation, and changes in your configuration may
require changes to the installed apparmor profile. Please see
https://wiki.ubuntu.com/DebuggingApparmor before filing a bug against this
software.

If your ntpd configuration needs access to a device (e.g. a local DCF clock),
you may need to add this device to: /etc/apparmor.d/tunables/ntpd

For use with clocks that report via shared memory (e.g. gpsd), you may need
to give ntpd access to all of shared memory, though this can be considered
dangerous. See https://launchpad.net/bugs/722815 for details. To enable, add
this to /etc/apparmor.d/local/usr.sbin.ntpd:
    capability ipc_owner,

For either change, you need to reload the AppArmor profile for the changes to
take effect:
    # apparmor_parser -r /etc/apparmor.d/usr.sbin.ntpd
