INSTALL

PTP Daemon Version 2 Build and Installation Instructions

15 June 2015

George V. Neville-Neil, Wojciech Owczarek

The PTP Daemon is known to work on FreeBSD, NetBSD, OpenBSD,
OpenSolaris and its derivatives, Mac OS X and Linux systems.

*) Requirements

You will need the following tools and libraries to build ptpd2:

1. GNU autotools (automake, autoconf, libtool etc.) - essential

2. PCAP libraries (libpcap/bpf) and development headers
   (optional but recommended) - required for Ethernet transport
   and generally recommended for message performance

3. SNMP libraries (optional) - will allow building with SNMP
   support

*) Building

1. cd into the root of the tree (which is where the file you're
   reading resides)

2. If building from a repository such as Subversion, CVS or GIT, run:

   autoreconf -vi

3. If building from a distribution .tar.gz package, you may run autoreconf -vi,
   but in most cases running ./configure should be enough - you must run
   autoreconf if configure or result in errors.

4. ./configure

   ========= configure script options for ptpd ========================

   * To disable the statistics code in order to lower computational
   expense and RAM usage, configure the build with the following options:

   ./configure --disable-statistics

   * To build a slave-only version (with GM logic disabled), build with:

    ./configure --enable-slave-only

    This will build a version incapable of running as master.

    * As of 2.3.1, the default timer implamentation used for periodic
    actions uses POSIX timers if only the OS supports it. To disable
    POSIX timer support and use the old interval timer implementation,
    the following switch can be used:

    ./configure --disable-posix-timers

    * As of 2.3.1, support was added for multiple unicast destinations
    (both GMs and slaves) - with negotiation (signaling) and without.
    The default maximum number of unicast destinations (also the
    maximum number of slaves for a signaling GM) is set to 128. This
    can be changed to a maximum of 2048 using:

   ./configure --with-max-unicast-destinations=[16...2048]

    It is possible to change this limit to more than 2048, but realistically
    due to message scheduling, timer signal usage and single-threaded
    architecture, anywhere above 1000 ptpd will show high CPU utilisation.
    Ptpd has been successfully tested as unicast Telecom (negotiation) master
    at 1000 slaves and high message rates (32/sec) and provided adequate
    performance. When running high numbers of slaves, it is recommended
    to use libpcap (ptpengine:use_libpcap=y) to allow easier matching
    of Sync and FollowUp, unless the NIC supports software transmit
    timestamps. Without those and without libpcap, ptpd loops packets 
    back into its own socket, so the followUp destination cannot be
    matched with the Sync destination, and a lookup table is used.
    Hash collissions are low, but they may happen, in which case
    ptpd will iterate over a table of last timestamps.  This is only and issue
    in extreme scenarios.

    * With certain NIC drivers on Linux providing the SO_TIMESTAMPING
    functionality with software transmit timestamps (SOF_TIMESTAMPING_
    TX_SOFTWARE), unpredictable transmit timestamp failures can occur, 
    which may cause unstable operation and in some cases high CPU usage
    (see https://sourceforge.net/p/ptpd/discussion/469208/thread/4aea6e47).
    While fixes have been implemented and have shown success, 
    there is still some risk. To disable SO_TIMESTAMPING support on Linux
    completely, regardless of OS support, use:

    ./configure --disable-so-timestamping

5. make

6. Read the manual pages ptpd2(8) and ptpd2.conf(5). The man pages
   are the most complete source of configuration information.
   ptpd2 itself also provides an extensive help:
   run ptpd2 --help to see the short help
   run ptpd2 --long-help to see the long help for all settings
   run ptpd2 -e [key:setting] to display help for a single setting

7. Update test/client-e2e-socket.conf so that its
   "ptpengine:interface = " setting points to a network interface on
   your test machine that can see PTP packets from a grandmaster.

8. Test it in place: ./src/ptpd2 -c test/client-e2e-socket.conf

9. Check the log output of the daemon in /var/run/ptpd2.event.log
   Check statistics output of the daemon in /var/run/ptpd2.stats.log
   Check the status file /var/run/ptpd2.status.log

10. If the results look good, make install

The daemon may work on other POSIX based systems but this is not
guaranteed.  Patches and fixes are welcome on the SourceForge page:

http://ptpd.sf.net