= Installation instructions =

== Prerequisites ==

This software should build on any operating system conformant to
POSIX.1-2001 and ISO/IEC 9899:1999 (C99).  In addition, the operating
system must have an ntp_adjtime(2) call or the older BSD adjtime(2)
call. Also, it must support the IPv6 API defined in RFC 2493 and
RFC 2553. Finally, it must support iterating over active UDP interfaces
via getifaddrs(3) or some equivalent facility.

You can browse a summary of differences from legacy NTP here:

https://docs.ntpsec.org/latest/ntpsec.html

There are some prerequisites.  Libraries need the binary installed
to run and in addition, the development headers installed to build.

Python 2.x, x >= 6, or Python 3.x, x >= 3::
   Required to build, and for various scripts such as ntpviz (but see
   the guidance for packagers in devel/packaging.txt).  Our Python code
   has been written polyglot to also run with production versions of
   Python 3.  Note that you will need both the ordinary Python
   installation and Python dev tools, if your OS makes such a
   distinction.

   Required to build.
   Debian: python-dev
   Fedora: python-devel
   SLES: python-devel

bison::
   Required to build.
   Debian: bison
   Fedora: bison
   Gentoo package: sys-devel/bison
   SLES: bison . Included in pattern `basis-devel`, which includes gcc, etc.

libcap::
   Required on Linux, to support dropping root.
   Fedora: libcap and libcap-devel
   Debian: libcap2 and libcap-dev
   Gentoo package: sys-libs/libcap
   SLES: libcap2 and libcap-devel

gnuplot::
   Required for ntpviz.
   Debian: gnuplot
   Fedora: gnuplot
   Gentoo package: sci-visualization/gnuplot
   Ubuntu package: gnuplot5
   SLES: gnuplot

psutils::
   Optional for ntpviz.  Allows running with ionice()
   Debian package: python-psutil or python3-psutil
   Gentoo package: dev-python/psutil
   Ubuntu package: python-psutil or python3-psutil
   SLES: python-psutil

seccomp::
   Optional on Linux to support restricting syscalls
   Debian: libseccomp-dev (gets libseccomp2)
   Fedora: libseccomp-devel
   Gentoo package: sys-libs/libseccomp
   SLES: libseccomp-devel

OpenSSL::
   Optional, required for --enable-crypto.
   Enables encryption and authentication.
   Debian: libssl1.0.0 and libssl-dev
   Fedora: openssl-libs and openssl-devel
   Gentoo package: dev-libs/openssl
   SLES: openssl-libs and openssl-devel

sys/timepps.h::
   If you are building to supply Stratum 1 time service (that is, with
   refclocks linked in) you may find that you need the sys/timepps.h
   file to be installed, depending on which refclocks you enable.
   This won't be necessary for pure client (Stratum 2 or higher)
   installations.
   Debian: pps-tools
   Fedora: pps-tools-devel (pps-tools may be useful for debugging)
   Gentoo package: net-misc/pps-tools
   SLES: SLES 12 and earlier do not seem to have this available.

asciidoc, a2x::
   You will need asciidoc to make HTML and a2x to make manual pages from the
   documentation masters.  Only required if you configured with --enable-doc.
   Note, you need asciidoc 8.6.0 at minimum.
   Debian: asciidoc
   Fedora: asciidoc  (Stock CentOS/RHEL has only 8.4.5, you must upgrade)
   Gentoo package: app-text/asciidoc
   SLES: asciidoc

Local copy of DocBook stylesheets:
   Optional: Prevents documentation build failures when your Internet is down
   Debian: docbook-xsl
   Fedora: docbook-xsl-stylesheets
   Gentoo package: app-text/docbook-xsl-stylesheets
   SLES: docbook-xsl-stylesheets .  Pulled in by `asciidoc`

liberation::
   Optional, improves font quality in ntpviz renderings.
   Debian: liberation
   Fedora: liberation
   Gentoo package: media-fonts/liberation-fonts
   SLES: liberation-fonts

The OS X build has been tested in this environment:

 OS X Version             : 10.11.x (El Capitan)
 Xcode Version            : 7.1
 Xcode Command Line Tools : 7.2-beta

All you will require is the Xcode command line tools with no additions.
There is currently no support for using Xcode's builder. NTPsec's standard
waf based build system is used.

== Basic Installation ==

These are generic Unix installation instructions.

Under Unix, the simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and

  2. Run `./waf configure' to configure the package for your system.
  You may want to add configuration options after the verb 'configure';
  see below.

  3. Invoke `./waf build' to compile the package.

  4. Invoke `./waf install' to install the programs and any data files and
     documentation.

  5. You can uninstall cleanly by invoking `./waf uninstall' as root.

  6. You can remove the program binaries and object files from the
     source code directory by typing `./waf clean'.

  7. To also remove the files that `./waf configure' created (so you can
     configure and compile the package for a different kind of
     computer), type `./waf distclean'.

Under OS X you can build NTPsec using Xcode command line tools with no
additions. There is currently no support for using Xcode's builder.

== Qualification testing ==

Details on how to qualify NTPsec if you've never used it before
are at devel/testing.txt.

== Build Bugs ==

You may find that after a fresh clone and first ./waf build you get a
Python import error when trying to run ntpq or other Python tools.
If this happens, just do ./waf build again.  This is a known bug
which will be fixed in a future release.

The configuration system occasionally acts up during builds on new
platforms.  If you see the message "Compilation check failed but
include exists!" this means that an attempt to compile a small test
program using the include header mentioned on the previous line
failed, but waf configure then found that despite this the header file
exists on your system.

When this happens, it is likely that the header has prerequisites
on your system that waf configure doesn't know about - that is,
other headers always need to be included before it in C programs.

Please report this as a bug, along with your platform details.

== Installation Names ==

By default, `waf install' will install the package's files in
`/usr/local/bin', `/usr/local/man', etc.  You can specify an
installation prefix other than `/usr/local' by giving waf the
option `--prefix=PATH'.

You should read the section "Path problems with the test tools" in
devel/testing.txt before setting a non-default prefix.

== Strict compatibility mode ==

There have been a handful of forward-incompatible changes from NTP Classic.
These are unlikely to affect normal operation.  However, there is a configure
operation, --enable-classic-mode, that restores certain legacy behaviors. This
is not recommended, as it makes the code a little bulkier and slower.

Here's what it presently does:

* Reverts logging to the old format that designates clocks with magic
  addresses rather than the driver shortname and unit number.

* Enables declaring generic-driver refclocks with the old magic-address
  syntax (but the new syntax won't work for these, though it will for
  other driver types).

* Reverts the default baudrate of the NMEA driver to 4800 (from 9600).

* Restores the old (non-RFC 3339) format of logfile timestamps.

Other behaviors may be added in future releases.

== Optional Features ==

The waf builder accepts `--enable-FEATURE' options to where FEATURE
indicates an optional part of the package.  Do `waf --help' for a list
of options.

refclocks are enabled with `--refclock=<n1,n2,n3..> or --refclock=all'
`waf configure --list' will print a list of available refclocks.

=== --enable-early-droproot ===

Drop root privileges as early as possible.  This requires the refclock
devices to be owned by the same owner or group that ntpd will be
running under (most likely that group will be named "ntp") so that it
can still open the devices.  This can be accomplished by adding
`GROUP="ntp"` or `OWNER="ntp"` to the udev rules that create the
device symlinks for the refclocks.

== Developer options ==

--enable-debug-gdb::
     Enable GDB debugging symbols.

== Operation Controls ==

The waf builder recognizes the following options to control how it
operates.

--help::
     Print a summary of the options to `waf configure', and exit.

--version::
     Print the version of waf used to generate the `configure'
     script, and exit.

== Cross-compiling ==

Set up a cross-compile environment for the target architecture.  At minimum
it will need its own binaries for the OpenSSL library.

Configure NTPSec with:

  waf configure --enable-cross=/path/to/your/cross/cc

There are also --cross-cflags and --cross-ldflags to supply the cross compiler 
with appropriate values.

== Statistics ==

If you want to generate the ntpviz graphs regularly, add these lines to
your root crontab:

53 * * * * cd /usr/local/src/NTP/ntpsec/ntpstats; ./ntpviz -p 1 -o day
45 11,23 * * * cd /usr/local/src/NTP/ntpsec/ntpstats; ./ntpviz -p 7 -o week

// end

