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.  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:
    https://support.ntp.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, this information will be used automatically.  This is done
by making a copy of ntp.conf at /run/ntpsec/ntp.conf.dhcp, replacing the
server entries with the information provided by the DHCP server, and
restarting the NTP server.

If you use dhclient, the "ntp-servers" option must be mentioned in the
"request" statement in /etc/dhcp/dhclient.conf.  This is the default.

To ignore the NTP servers sent by the DHCP server, set IGNORE_DHCP to "yes" in
/etc/default/ntpsec.

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 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 at:
    - 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 changes in your configuration
may require changes to the installed apparmor profile.  Before filing a bug,
please see:
    https://wiki.ubuntu.com/DebuggingApparmor

If your ntpd configuration needs access to a device (e.g. a local DCF clock),
you 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, reload the AppArmor profile for the changes to take effect:
    apparmor_parser -r /etc/apparmor.d/usr.sbin.ntpd
