= How To Test NTPsec =

This assumes you have downloaded the source and built a system
and now you want to test your new ntpd.

For help on getting that far, see ../INSTALL

== Path problems with the test tools ==

The very first thing to do, even before you start up ntpd, is to change
directory to ntpclients/ and run ./ntpq there. If you get a message that says

---------------------------------------------------------------------
ntpq: can't find Python NTP library -- check PYTHONPATH.
---------------------------------------------------------------------

you have a problem.  A lot of what was C code in legacy versions
(pretty much everything except ntpd itself, in fact) has been moved to
Python in order to improve maintainability and decrease attack
surface.  Most of these tools share a Python library of critical
functions.  If you can't load that library, you can't test effectively.

The waf build is supposed to create a symbolic link from ntpclients/ntp to
pylib in the build directory. This should enable ntpq to "import ntp"
before you install to rootspace. If that link is not created or
doesn't point to pylib/ under your build directory, report
this as a bug. If it is, but ./ntpq startup fails anyway, you may
have a mis-configured Python and need to investigate that.

Load paths are more likely to be an issue after rootspace
installation.  On most systems, waf will by default install the Python
library under /usr/local/lib/python${VERSION}/dist-packages (or
possibly the peer directory site-packages) where ${VERSION} is what
the command "python --version" gives back. This directory should be on
your Python's sys.path, in which case all will proceed normally.

If it's not, you will get the same ntpq failure to launch ./ntpq from
anywhere *outside* the source tree.  You may be able to patch around
this by setting the environment variable PYTHONPATH to include the
rootspace directory where waf installed the library; use "waf -v
install" to nail down this location.

Be aware that if this sort of problem occurs in an NTPsec instance
installed from a binary package, it is almost certainly not an NTPsec
bug but a packaging error that the NTPsec maintainers themselves can't
fix. In that case you need to report it to your distribution
maintainers.

== Preliminary one-off test ==

For a one-off test:

1. Do "ps ax | grep ntpd" or equivalent to find out what the command line is.

2. Use whatever you do on your system to stop the normal ntpd.  This
 is likely to be either something resembling "/etc/init.d/ntp stop" or
 "systemctl stop timeservice".

3. Run ./build/ntpd/ntpd plus the command line parameters from above. 

4. It will daemonize itself and give you back your terminal.

Your current /etc/ntp.conf should work correctly.

Check your log files to see if there is anything strange.
Run "ntpq -p" to see if things look normal.

== Full qualification test ==

For a longer test, including over reboots...

Install your new code using "./waf install" (as root).
That will install your new ntpd into /usr/local/sbin/ntpd

Now you have to patch your (re)start scripts to look there
and restart ntpd.  The details vary by OS/distro.

=== Distributions using systemd ===

1. Edit /usr/lib/systemd/system/ntpd.service

2. Change ExecStart=/usr/sbin/ntpd -u ntp:ntp $OPTIONS
   to   ExecStart=/usr/local/sbin/ntpd -u ntp:ntp $OPTIONS
   then do "service ntpd restart"

3. systemctl may barf about an out of date file and tell you
   how to fix it.  If so, follow its directions and try again.

Note that under Fedora and CentOS, "dnf update" may undo that edit
and revert to running the system version.

Older versions used /etc/rc.d/init.d/ntpd. The file /etc/sysconfig/ntpd
gets sourced into the init script so you can put real code in there
(systemd doesn't do that)  You can insert this:

--------------------------------------------------
    PATH="/usr/local/sbin:$PATH"
--------------------------------------------------

=== Debian, Ubuntu, Raspbian ===

Many newer versions use systemd; follow those directions. The
rest of this section describes the older set of conventions used
with a traditional System V init sequence.

Edit /etc/init.d/ntp. Change

--------------------------------------------------
DAEMON=/usr/sbin/ntpd
--------------------------------------------------

to

--------------------------------------------------
DAEMON=/usr/local/sbin/ntpd
--------------------------------------------------

A good safety measure in case you want to revert later is to duplicate
the line, comment out the first one and edit the second one. That
looks like this:

--------------------------------------------------
# DAEMON=/usr/sbin/ntpd
DAEMON=/usr/local/sbin/ntpd
--------------------------------------------------

If you are using DHCP and your DHCP servers provide NTP servers,
Debian makes a dummy ntp.conf using those servers and not the
ones you put into the normal /etc/ntp.conf.  To use your ntp.conf
rather than the one it wants you to:

1. Edit /etc/init.d/ntp

2. Comment out the clump of 3 lines that references dhcp:

--------------------------------------------------
# if [ -e /var/lib/ntp/ntp.conf.dhcp ]; then
#       NTPD_OPTS="$NTPD_OPTS -c /var/lib/ntp/ntp.conf.dhcp"
# fi
--------------------------------------------------

apt-get upgrade may undo those edits and revert to running the system version.

=== FreeBSD ===

Edit /etc/rc.conf It needs to contain this:

--------------------------------------------------
ntpd_enable="YES"
ntpd_program="/usr/local/sbin/ntpd"
--------------------------------------------------

If you are running ntpd, the first line will be there
already.  The default is NO.

=== NetBSD ===

Edit /etc/rc.d/ntpd. Change

--------------------------------------------------
command="/usr/sbin/${name}"
--------------------------------------------------

to

--------------------------------------------------
command="/usr/local/sbin/${name}"
--------------------------------------------------

A good safety measure in case you want to revert later is to duplicate
the line, comment out the first one and edit the second one. That
looks like this:

--------------------------------------------------
# command="/usr/sbin/${name}"
command="/usr/local/sbin/${name}"
--------------------------------------------------

// end
