Add /dev/ptp0 passthrough

Some virtual cloud services provide a very good system time on their
host, which can be accessed by the guest VMs through the `/dev/ptp0`
device. This interface is found on Hyper-V and KVM (the latter
requires the `ptp_kvm` module to be loaded).

In my experience the time is very stable and often quite accurate,
often helping chrony to converge faster to a good time. As a result,
this commit adds an optional functionality to pass the host's
`/dev/ptp0` device to the container.

README.md

@@ -209,6 +209,28 @@ Enabling the control requires granting SYS_TIME capability and a container run-t
     ...
 ```
 
+## Enable the use of a PTP clock
+
+If you have a `/dev/ptp0`, either a real hardware clock or virtual one provided by a VM host
+you can enable the use of it by passing the device to the container. As an example,
+using `docker-compose.yaml`, that would look like this:
+
+```yaml
+  ...
+  devices:
+    - /dev/ptp0:/dev/ptp0
+```
+
+This will allow chronyd to use the PTP clock as a reference clock. A virtual clock simply provides
+the host's system time with great precision and stability; whether that time is accurate depends
+on the host provider. In our experience, some VPS vendors give pretty good time (off by
+milliseconds), while others are off by seconds.
+
+For information on configuring the host to have a virtual PTP clock, see the following:
+
+ * https://opensource.com/article/17/6/timekeeping-linux-vms
+
+
 ## Testing your NTP Container
 
 From any machine that has `ntpdate` you can query your new NTP container with the follow

assets/startup.sh

@@ -65,6 +65,11 @@ for N in $NTP_SERVERS; do
   fi
 done
 
+# PTP0 configuration: if it has been passed through, it means we want to use it
+if [ -e /dev/ptp0 ]; then
+  echo "refclock PHC /dev/ptp0 poll 3 dpoll -2 stratum 2" >> ${CHRONY_CONF_FILE}
+fi
+
 # final bits for the config file
 {
   echo

docker-compose.yml

@@ -7,9 +7,11 @@ services:
     container_name: ntp
     restart: always
     ports:
-      - 123:123/udp
+      - 1123:1123/udp
+#     devices:
+#       - /dev/ptp0:/dev/ptp0
     environment:
-      - NTP_SERVERS=time.cloudflare.com
+#      - NTP_SERVERS=time.cloudflare.com
       - LOG_LEVEL=0
 #      - TZ=America/Vancouver
 #      - NOCLIENTLOG=true

run.sh

@@ -12,20 +12,31 @@ function check_container() {
 
 # function to start new docker container
 function start_container() {
+  if [ "${ENABLE_PTP:-false}" = true ]; then
+    echo "PTP requested..."
+    if [ -e /dev/ptp0 ]; then
+      echo "PTP device found: /dev/ptp0, passing through..."
+      PTPARG="--device=/dev/ptp0"
+    else
+      echo "PTP device not found: /dev/ptp0"
+    fi
+  fi
   $DOCKER run --name=${CONTAINER_NAME}             \
               --detach=true                        \
               --restart=always                     \
-              --publish=123:123/udp                \
+              --publish=1123:1123/udp                \
               --env=NTP_SERVERS=${NTP_SERVERS}     \
               --env=ENABLE_NTS=${ENABLE_NTS}       \
               --env=ENABLE_SYSCLK=${ENABLE_SYSCLK} \
               --env=NOCLIENTLOG=${NOCLIENTLOG}     \
               --env=LOG_LEVEL=${LOG_LEVEL}         \
+              --env=ENABLE_PTP=${ENABLE_PTP}       \
               --cap-add=SYS_TIME                   \
               --read-only=true                     \
               --tmpfs=/etc/chrony:rw,mode=1750     \
               --tmpfs=/run/chrony:rw,mode=1750     \
               --tmpfs=/var/lib/chrony:rw,mode=1750 \
+              $PTPARG \
               ${DOCKER_OPTS}                       \
               ${IMAGE_NAME}:latest > /dev/null
 }

vars

@@ -28,3 +28,6 @@ LOG_LEVEL=0
 
 # (optional) additional docker run options you may want
 DOCKER_OPTS=""
+
+# (optional) ask run.sh to pass /dev/ptp0 
+RENABLE_PTP=false