README.md

   1 # NQPTP – Not Quite PTP
   2 `nqptp` is a daemon that monitors timing data from [PTP](https://en.wikipedia.org/wiki/Precision_Time_Protocol) clocks it sees on ports 319 and 320. It maintains records for one clock, identified by its Clock ID.
   3
   4 It is a companion application to [Shairport Sync](https://github.com/mikebrady/shairport-sync) and provides timing information for AirPlay 2 operation.
   5
   6 ## Installation
   7
   8 This guide is for recent Linux and FreeBSD systems.
   9
  10 As usual, you should first ensure everything is up to date.
  11
  12 #### Please use `git`!
  13 As you probably know, you can download the repository in two ways: (1) using `git` to clone it  -- recommended -- or (2) downloading the repository as a ZIP archive. Please use the `git` method. The reason it that when you use `git`,
  14 the build process can incorporate the `git` build information in the version string you get when you execute the command `$ nqptp -V`.
  15 This will be very useful for identifying the exact build if you are making comments or bug reports. Here is an example:
  16 ```
  17 Version with git build information:
  18 Version: 1.1-dev-24-g0c00a79. Shared Memory Interface Version: 5.
  19
  20 Version without git build information:
  21 Version: 1.1-dev. Shared Memory Interface Version: 5.
  22 ```
  23 ### Remove Old Service Files
  24 #### Linux
  25 If you are updating from version `1.2.4` or earlier in Linux, remove the service file `nqptp.service` from the directories `/lib/systemd/system` and `/usr/local/lib/systemd/system` (you'll need superuser privileges):
  26 ```
  27 # rm /lib/systemd/system/nqptp.service
  28 # rm /usr/local/lib/systemd/system/nqptp.service
  29 # systemctl daemon-reload
  30 ```
  31 Don't worry if you get a message stating that the files doesn't exist -- no harm done.
  32
  33 #### FreeBSD
  34 At present, there is no need to remove the old startup script as (in FreeBSD only) it is always replaced during the `# make install` step.
  35
  36 The startup script is at `/usr/local/etc/rc.d/nqptp`.
  37
  38 ### Build and Install
  39
  40 Note that you will need superuser privileges to install, enable and start the daemon.
  41
  42 #### Linux
  43 ```
  44 $ git clone https://github.com/mikebrady/nqptp.git
  45 $ cd nqptp
  46 $ autoreconf -fi
  47 $ ./configure --with-systemd-startup
  48 $ make
  49 # make install
  50 ```
  51 #### FreeBSD
  52 ```
  53 $ git clone https://github.com/mikebrady/nqptp.git
  54 $ cd nqptp
  55 $ autoreconf -fi
  56 $ ./configure --with-freebsd-startup
  57 $ make
  58 # make install
  59 ```
  60 The `make install` installs a startup script as requested. You should enable it and start it in the normal way:
  61
  62 ### First Install or Update?
  63 #### Linux
  64 ##### First Install
  65 If you are installing `nqptp` for the first time, enable it and start it:
  66 ```
  67 # systemctl enable nqptp
  68 # systemctl start nqptp
  69 ```
  70 If Shairport Sync is already running, you should restart it after starting `nqptp`:
  71 ```
  72 # systemctl restart shairport-sync
  73 ```
  74 ##### Update
  75 If you are updating an existing installation of `nqptp`, after installing it you should restart it. You should then also restart Shairport Sync:
  76 ```
  77 # systemctl restart nqptp
  78 # systemctl restart shairport-sync
  79 ```
  80 #### FreeBSD
  81 ##### First Install
  82 If you are installing `nqptp` for the first time, add an automatic startup entry for it in `/etc/rc.local` and start it:
  83 1. Edit `/etc/rc.conf` and add the following line:
  84    ```
  85    nqptp_enable="YES"
  86    ```
  87 2. When you have finished editing `/etc/rc.conf`, you can start `nqptp` from the command line:
  88    ```
  89    # service nqptp start
  90    ```
  91 If Shairport Sync is already running, you should you restart it after starting `nqptp`:
  92 ```
  93 # service shairport_sync restart
  94 ```
  95
  96 ##### Update
  97 If you are updating an existing installation of `nqptp`, after installing it you should restart it. You should then also restart Shairport Sync:
  98 ```
  99 # service nqptp restart
 100 # service shairport_sync restart
 101 ```
 102
 103 ## Firewall
 104 If your system runs a firewall, ensure that ports 319 and 320 are open for UDP traffic in both directions. These ports are associated with PTP service and may be referred to as "PTP" in firewall rules. For example, the following would open ports 319 and 320 for Fedora, which uses `firewalld`:
 105 ```
 106 # firewall-cmd --add-service=ptp
 107 # firewall-cmd --permanent --add-service=ptp # make it permanent across reboots
 108 ```
 109
 110 ## Notes
 111 The `nqptp` application requires exclusive access to ports 319 and 320.
 112 This means that it can not coexist with any other user of those ports, such as full PTP service daemons.
 113 In Linux, `nqptp` runs as a low-priviliged user but is given special access to ports 319 and 320 using systemd `AmbientCapabilities`.
 114 In FreeBSD, `nqptp` runs as `root` user.
 115
 116 ## Programming Notes
 117 Commands and status information are sent to `nqptp` over port 9000.
 118
 119 Information about the PTP clock is provided via a [POSIX shared memory](https://pubs.opengroup.org/onlinepubs/007908799/xsh/shm_open.html) interface.
 120
 121
 122 Here are details of the interface:
 123 ```c
 124 typedef struct {
 125   uint64_t master_clock_id;             // the current master clock
 126   uint64_t local_time;                  // the time when the offset was calculated
 127   uint64_t local_to_master_time_offset; // add this to the local time to get master clock time
 128   uint64_t master_clock_start_time;     // this is when the master clock became master
 129 } shm_structure_set;
 130
 131 // The actual interface comprises a shared memory region of type struct shm_structure.
 132 // This comprises two records of type shm_structure_set.
 133 // The secondary record is written strictly after all writes to the main record are
 134 // complete. This is ensured using the __sync_synchronize() construct.
 135 // The reader should ensure that both copies match for a read to be valid.
 136 // For safety, the secondary record should be read strictly after the first.
 137
 138 struct shm_structure {
 139   uint16_t version; // check this is equal to NQPTP_SHM_STRUCTURES_VERSION
 140   shm_structure_set main;
 141   shm_structure_set secondary;
 142 };
 143 ```
 144
 145 Clock records that are not updated for a period are deleted.
 146 ## Known Issues
 147 * `nqptp` has not been thoroughly checked or audited for security issues. Note that it runs in `root` mode on FreeBSD.
 148 * It's probably buggy!
 149 * `nqptp` does not take advantage of hardware timestamping.
 150
 151 ## Things Can Change
 152 The `nqptp` daemon is under active development and, consequently, everything here can change, possibly very radically.
 153
 154 ## NQPTP is not PTP!
 155 `nqptp` uses just a part of the [IEEE 1588-2008](https://standards.ieee.org/standard/1588-2008.html) protocol. It is not a PTP clock.