INSTALL.adoc

   1 = Installation instructions =
   2
   3 == Prerequisites ==
   4
   5 This software should build on any operating system conformant to
   6 POSIX.1-2001 and ISO/IEC 9899:1999 (C99).  In addition, the operating
   7 system must have an ntp_adjtime(2) call. Also, it must support the
   8 IPv6 API defined in RFC 2493 and RFC 2553. Finally, it must support
   9 iterating over active UDP interfaces via getifaddrs(3) or some
  10 equivalent facility.
  11
  12 You can browse a summary of differences from legacy NTP here:
  13
  14 https://docs.ntpsec.org/latest/ntpsec.html
  15
  16 There are some prerequisites.  Libraries need the binary installed
  17 to run and in addition, the development headers installed to build.
  18
  19 We need pthreads (It's optional in POSIX)
  20 We need OpenSSL != 1.1.1a (1.1.1a has a fatal bug)
  21 NTS needs TLS1.3 or newer.
  22
  23 === The short version ===
  24
  25 If you are on a Debian or Ubuntu distribution that uses apt-get, or on
  26 a Fedora or RedHat distribution that uses yum or dnf, or a Suse
  27 distribution that uses yast or zypper, or Gentoo, you can use the
  28 ./buildprep script.
  29
  30 In that case, run ./buildprep -n to see what needs to be installed as
  31 prerequisites on your system.  In order that we have a single point of
  32 truth about package requirements, much information about
  33 installable-package names that used to live in this file has moved to
  34 that script.
  35
  36 If you are using other distributions or OSes, such as macOS, Solaris,
  37 or *BSD, you will have to install the build prerequisites by hand on
  38 your system.  Read the buildprep script to get an idea what packages
  39 are required.
  40
  41 buildprep does not attempt to install dependencies for optional
  42 components like ntpviz or building documentation unless asked. See
  43 buildprep --help for details on available options.  psutil may require
  44 different packages depending on whether your base Python version is
  45 2 or 3.
  46
  47 === Details ===
  48
  49 Python 2.x, x >= 6, or Python 3.x, x >= 3::
  50    Required to build, and for various scripts such as ntpviz (but see
  51    the guidance for packagers in devel/packaging.adoc).  Our Python code
  52    has been written polyglot to run with either Python 2 or Python 3.
  53    Note that you will need both the ordinary Python installation and
  54    Python dev tools, if your OS makes such a distinction.
  55
  56    If you are running on a distro with no `python` executable, you will
  57    need to run waf as `python3 waf` rather than `./waf`.  You will also
  58    need `python3 waf configure --pyshebang=/usr/bin/env python3` or similar.
  59
  60    Some OS distros won't find our installed python libraries.
  61    More info in README-PYTHON.
  62
  63 argparse::
  64    Required for ntpviz when using Python version 2.6
  65    Install with pip: pip install argparse
  66
  67 psutil::
  68    Optional for ntpviz.  Allows running with ionice()
  69    Debian: python-psutil or python3-psutil
  70    Ubuntu: python-psutil or python3-psutil
  71    Fedora/CentOS: python-psutil or python3-psutil
  72    Gentoo: dev-python/psutil
  73    SLES: python-psutil or python3-psutil
  74
  75 sys/timepps.h::
  76    If you are building to supply Stratum 1 time service (that is, with
  77    refclocks linked in) you may find that you need the sys/timepps.h
  78    file to be installed, depending on which refclocks you enable.
  79    This won't be necessary for pure client (Stratum 2 or higher)
  80    installations.
  81
  82 AsciiDoc:
  83    You will need an AsciiDoc processor to make HTML and/or manual pages from
  84    the documentation masters.  The supported processors, in order of
  85    preference, are asciidoctor, asciidoc(-py3)/a2x, and asciidoc3/a2x3.
  86
  87 asciidoctor::
  88    Note: you need asciidoctor 1.5.8 or newer.  Otherwise, use asciidoc or
  89    asciidoc3.
  90    Debian/Ubuntu: asciidoctor (Debian 10+, Ubuntu 19.04+)
  91    Fedora: rubygem-asciidoctor (Fedora 32+)
  92    Gentoo: app-text/asciidoctor
  93    SLES: asciidoctor
  94
  95 asciidoc, a2x::
  96    Note: you need asciidoc 8.6.8 or newer.  Alternatively, use asciidoctor
  97    or asciidoc3.
  98    Debian/Ubuntu: asciidoc
  99    Fedora/CentOS: asciidoc
 100    Gentoo: app-text/asciidoc
 101    SLES: asciidoc
 102
 103 asciidoc3, a2x3::
 104    Note: you need asciidoc 3.0.2 or newer.  Alternatively, use asciidoctor
 105    or asciidoc.  There are currently no distro packages of asciidoc3.
 106    However, upstream provides deb, pip and rpm packages.
 107
 108 Local copy of DocBook stylesheets:
 109    Optional: Prevents documentation build failures when your Internet is down
 110    Debian/Ubuntu: docbook-xsl
 111    Fedora/CentOS: docbook-xsl-stylesheets
 112    Gentoo: app-text/docbook-xsl-stylesheets
 113    SLES: docbook-xsl-stylesheets - pulled in by `asciidoc`
 114
 115 wget:
 116    Optional, used by ntpleapfetch
 117
 118 == Basic Installation ==
 119
 120 These are generic Unix installation instructions.  Some notes on
 121 specific platforms follow this section.
 122
 123 Under Unix, the simplest way to compile this package is:
 124
 125   1. `cd` to the directory containing the package's source code.
 126
 127   2. Run `./buildprep` as root to get your prerequisites installed.
 128
 129   3. Run `./waf configure` to configure the package for your system.
 130   You may want to add configuration options after the verb 'configure';
 131   see below. NOTE: if you will be using any local reference clocks (GPS,
 132   PTP, SHM, etc.) then you need to configure for them by running the
 133   command: `./waf configure --refclock=all`.
 134
 135   4. Run `./waf build` to compile the package.
 136
 137   5. Run `./waf install` to install the programs and any data files and
 138      documentation.
 139
 140   6. You can uninstall cleanly by running `./waf uninstall` as root.
 141
 142   7. Look under "Boot script setup" in wscript for how to set up
 143      boot time startup of ntpd; this will vary according to your
 144      init system.
 145
 146   8. You can remove the program binaries and object files from the
 147      source code directory by running `./waf clean`.
 148
 149   9. To also remove the files that `./waf configure` created (so you can
 150      configure and compile the package for a different kind of
 151      computer), run `./waf distclean`.
 152
 153 === ldconfig ===
 154
 155 It may be necessary after installing on some systems (incl. Linux) to
 156 rebuild the ld.so cache or equivalent if using the FFI library (default).
 157
 158 === Solaris ===
 159
 160 When building the NTPsec suite using gcc under Solaris, you may see
 161 prototype-mismatch warnings involving adjtime(2).  These warnings are
 162 functionally harmless and can be ignored.  They reflect an unfortunate
 163 choice by Solaris not to const the function's first argument as do
 164 other implementations.
 165
 166 == Build Bugs ==
 167
 168 The configuration system occasionally acts up during builds on new
 169 platforms.  If you see the message "Compilation check failed but
 170 include exists!" this means that an attempt to compile a small test
 171 program using the include header mentioned on the previous line
 172 failed, but waf configure then found that despite this the header file
 173 exists on your system.
 174
 175 When this happens, it is likely that the header has prerequisites
 176 on your system that waf configure doesn't know about - that is,
 177 other headers always need to be included before it in C programs.
 178 Please report this as a bug, along with your platform details.
 179
 180 == Source build limitations ==
 181
 182 When you do an install from source, no attempt is made to generate an
 183 /etc/ntp.conf for you.  The reason is that we, the maintainers, can't
 184 know what pool host you are authorized to use.  If you have an existing
 185 ntp.conf from a legacy version, you can expect it to work.
 186
 187 Due to a limitation of the Python distutils library, if you install
 188 from the source distribution with prefix set to a value other than
 189 /usr (in particular, if it's the default value /usr/local), that
 190 prefix will be honored *only if the corresponding Python library
 191 directory already exists*. Otherwise, under Linux, the install will
 192 drop the ntp Python library in /usr/lib. This layout may violate the
 193 Linux File Hierarchy Standard.
 194
 195 You should have neither issue if you install from an OS distribution's
 196 binary package.
 197
 198 == Installation Names ==
 199
 200 By default, `waf install` will install the package's files in
 201 `/usr/local/bin`, `/usr/local/man`, etc.  You can specify an
 202 installation prefix other than `/usr/local` by giving waf the
 203 option `--prefix=PATH`.
 204
 205 You should read the section "Path problems with the test tools" in
 206 devel/testing.adoc before setting a non-default prefix.
 207
 208 There is a separate `--destdir` option that changes the root of the
 209 entire installation hierarchy, prepending all paths.  It defaults to `/`.
 210 You might, say, use --destdir=/tmp/ntp for a test install to see what
 211 the installation paths look like without running as root or touching
 212 system directories.
 213
 214 NB: --destdir is specified at install time, --prefix is specified
 215 at configure time and saved until install time.
 216
 217
 218 == Qualification testing ==
 219
 220 Details on how to qualify NTPsec if you've never used it before
 221 are at devel/testing.adoc.
 222
 223 == Strict compatibility mode ==
 224
 225 There have been a handful of forward-incompatible changes from NTP Classic.
 226 These are unlikely to affect normal operation.  However, there is a configure
 227 operation, --enable-classic-mode, that restores certain legacy behaviors. This
 228 is not recommended, as it makes the code a little bulkier and slower.
 229
 230 Here's what it currently does:
 231
 232 * Reverts logging to the old format that designates clocks with magic
 233   addresses rather than the driver shortname and unit number.
 234
 235 * Enables declaring generic-driver refclocks with the old magic-address
 236   syntax (but the new syntax won't work for these, though it will for
 237   other driver types).
 238
 239 * Reverts the default baudrate of the NMEA driver to 4800 (from 9600).
 240
 241 * Restores the old (non-RFC 3339) format of logfile timestamps.
 242
 243 Other behaviors may be added in future releases.
 244
 245 == Optional Features ==
 246
 247 The waf builder accepts `--enable-FEATURE` options to where FEATURE
 248 indicates an optional part of the package.  Do `waf --help` for a list
 249 of options.
 250
 251 refclocks are enabled with `--refclock=<n1,n2,n3..>` or `--refclock=all`
 252 `waf configure --list` will print a list of available refclocks.
 253
 254 === --enable-early-droproot ===
 255
 256 Drop root privileges as early as possible.  This requires the refclock
 257 devices to be owned by the same owner or group that ntpd will be
 258 running under (most likely that group will be named "ntp") so that it
 259 can still open the devices.  This can be accomplished by adding
 260 `GROUP="ntp"` or `OWNER="ntp"` to the udev rules that create the
 261 device symlinks for the refclocks.
 262
 263 == Developer options ==
 264
 265 --disable-debug-gdb::
 266      Disable GDB debugging symbols.
 267
 268 == Operation Controls ==
 269
 270 The waf builder recognizes the following options to control how it
 271 operates.
 272
 273 --help::
 274      Print a summary of the options to `waf configure`, and exit.
 275
 276 --version::
 277      Print the version of waf used to generate the `configure`
 278      script, and exit.
 279
 280 == Cross-compiling ==
 281
 282 Set up a cross-compile environment for the target architecture.  At minimum
 283 it will need OpenSSL headers/libraries and Python headers/libraries.
 284
 285 Configure NTPSec with:
 286
 287   PYTHON_VERSION=2.7 PYTAG=cpython27 pyext_PATTERN="%s.so" PYTHON_LDFLAGS='-lpthread -ldl' \
 288   ./waf configure --cross-compiler=/path/to/your/cross/cc \
 289   --pythondir=/usr/local/lib/python2.7/dist-packages --pythonarchdir=/usr/local/lib/python2.7/dist-packages
 290
 291 There are also --cross-cflags and --cross-ldflags to supply the cross compiler
 292 with appropriate values.
 293
 294 == Statistics ==
 295
 296 If you want to generate the ntpviz graphs regularly, add these lines to
 297 your root crontab:
 298
 299 [source,cron]
 300 ----
 301 53 * * * * cd /usr/local/src/NTP/ntpsec/ntpstats; ./ntpviz -p 1 -o day
 302 45 11,23 * * * cd /usr/local/src/NTP/ntpsec/ntpstats; ./ntpviz -p 7 -o week
 303 ----
 304
 305 // end
 306