Add sfptpd example

.gitignore

@@ -51,3 +51,7 @@ TODO.md
 
 .task
 dist
+
+terraform.tfstate
+terraform.tfstate.backup
+.terraform

CHANGELOG.md

@@ -4,7 +4,8 @@ Changelog
 ## v0.4.0 (2024-01-25)
 
  * Added `ptp` and `pps` device types. I'm more of a bottom, but I do like disciplining clocks.
-
+ * Added `sfptpd` example at `examples/terraform/sfptpd`](./examples/terraform/sfptpd/main.tf)
+
 ## v0.3.0 (2024-01-24)
 
  * Add `num_pseudo` to control the number of `onload` psuedo-devices are created.

README.md

@@ -136,6 +136,10 @@ If `mount_onload` is enables mounting of all the files and paths configured belo
 
 ## Tips
 
+See the examples directory:
+
+ * [`sfptpd` Nomad System Job with Terraform](./examples/terraform/sfptpd/README.md)
+
 The binary distribution includes `nomad-onload-probe`, which scans a system using the same code as `nomad-onload-device`:
 
 ```

examples/terraform/sfptpd/README.md

@@ -0,0 +1,11 @@
+# `sfptpd` Nomad System Job Example
+
+Stands up sfptpd as a Nomad System Job using Terraform.  It requires `nomad-onload` plugin installed to discover the `ptp` devices.
+
+```
+cd examples/terraform/sfptpd
+terraform init
+terraform apply
+```
+
+This is my first stab at this, so don't take it as anything more than demonstrative.  But I do get clock sync.

examples/terraform/sfptpd/files/ptp_slave.yml.tpl

@@ -0,0 +1,153 @@
+# Modified From:
+#   https://raw.githubusercontent.com/Xilinx-CNS/sfptpd/master/config/ptp_slave.cfg
+#
+# Example configuration for sfptpd operating as a PTP slave
+#
+# SPDX-License-Identifier: BSD-3-Clause
+# (c) Copyright 2012-2022 Xilinx, Inc.
+#
+
+#
+# Generic Configuration
+#
+[general]
+
+# Create a PTP Synchronization Module instance.
+sync_module ptp ptp1
+
+# Specify whether messages are sent to the syslog, stderr or to a file. By default
+# messages are sent to stderr.
+# message_log /local/sfptpd_msgs.txt
+message_log stderr
+
+# Specify whether stats logging is enabled and whether stats are sent to stdout
+# or to a file
+# stats_log /local/sfptpd_stats.txt
+stats_log stdout
+
+# Specifies whether to attempt using hardware timestamps on non-Solarflare
+# hardware. Its driver must support raw hardware timestamps and expose a PHC
+# device adjustable via clock_adjtime (adjtimex). If enabling, watch out for
+# NICs advertising separate clocks that are actually shared resulting in
+# inconsistent correction or not accepting clock adjustments.
+non_solarflare_nics off
+
+# In the event of a NIC reset or otherwise causing the NIC clock to read
+# the Unix epoch time, immediately correct the NIC clock in addition to the
+# default behaviour of preventing the wrong time from propagating.
+epoch_guard correct-clock
+
+#
+# PTP Instance Configuration
+#
+[ptp1]
+
+# Specify PTP Slave mode
+ptp_mode slave
+
+# Enable dump of each received PTP packet in detail - produces lots of output!
+# ptp_pkt_dump
+
+# Enable logging of PPS measurements
+# ptp_pps_log
+
+# TX and RX transmission latencies in nanoseconds - use to correct for network
+# asymmetry.
+ptp_tx_latency 0
+ptp_rx_latency 0
+
+# Specify the PTP delay mechanism - end-to-end or peer-to-peer
+ptp_delay_mechanism end-to-end
+
+# Specify the PTP network mode - conventional multicast or hybrid
+# ptp_network_mode hybrid
+
+# Use to modify the PTP domain in the range 0..255. Default is 0.
+# ptp_domain 0
+
+# Sets the convergence threshold in ns, the maximum offset from the clock
+# source over a 60s period to be considered in sync. The default is 1000 or
+# 100000 if software timestamping is in use.
+# sync_threshold 1000.0
+
+#
+# PTP Generic Configuration
+#
+
+[ptp]
+
+# Specify the interface to use.
+# interface eth1
+
+# Multicast TTL value. Default is 64.
+# ptp_ttl 64
+
+# Configures how PTP handles the UTC offset valid flag. The specification is
+# ambigious in its description of the meaning of the UTC offset valid flag
+# and this has resulted in varying different implementations. In most
+# implementations, if the UTC offset valid flag is not set then the UTC offset
+# is not used but in others, the UTC offset valid is an indication that the
+# master is completely confident that the UTC offset is correct. Various
+# options are supported:
+#    default  If UTCV is set use the UTC offset, otherwise do not use it
+#    ignore   Do not used the UTCV flag - always apply the indicated UTC offset
+#    prefer   Prefer GMs that have UTCV flag set above those that don't
+#    require  Do not accept GMs that do not set UTCV
+# ptp_utc_valid_handling default
+
+# Configure PTP management message support. Disabled by default. Possible
+# values are:
+#    disabled   Management messages disabled
+#    read-only  Only requests to read information (GET) will be accepted
+# ptp_mgmt_msgs disabled
+
+# Access Control Lists
+# This feature restricts the set of network addresses from which PTP will listen
+# to timing and management messages. The control uses an allow and deny list
+# and the option to specify the order in which the lists are evaluated. There are
+# separate controls for timing and management messages.
+# Each list should be a series of network address in the format a.b.c.d/x where
+# a.b.c.d specifies the subnet and x the mask - to specify a single IP address
+# a mask of 32 should be specified.
+# When enabled, each time that a PTP message is received, the source IP address
+# of the incoming message is matched against the allow and deny lists. The second
+# list in the ordering creates exceptions for the first list and the default
+# action is the opposite of the first list type.
+# The network addresses in each list should be separated with spaces or commas e.g.
+#       192.168.1.0/24 192.168.4.0/24 172.10.11.1/32 or
+#       192.168.1.0/24,192.168.4.0/24,172.10.11.1/32
+#
+# ptp_timing_acl_allow 172.16.128.48/32 172.16.128.47/32
+# ptp_timing_acl_deny 172.16.128.0/21
+# ptp_timing_acl_order deny-allow
+#
+# ptp_mgmt_acl_allow 10.10.1.1/32 10.12.1.0/24
+# ptp_mgmt_acl_deny 172.0.0.0/8
+# ptp_mgmt_acl_order allow-deny
+
+# The Announce receipt timeout in multiples of the announce interval.
+# ptp_announce_timeout 6
+
+# The Sync Packet receipt timeout in multiples of the sync packet interval.
+# ptp_sync_pkt_timeout 6
+
+# The Delay Request in interval in 2^number seconds. If specified for a
+# PTP slave, this overrides the value communicated to the slave from the
+# master.
+# ptp_delayreq_interval 0
+
+# The Delay Response receipt timeout 2^number seconds. Default is -2 (250ms).
+# ptp_delayresp_timeout -2
+
+# The maximum number of foreign master records a node is enable to store
+# simultaneously.
+# ptp_max_foreign_records 16
+
+# Set PTPD debug message level. Defaults to 0 (off).
+# ptp_trace 0
+
+# Set the PPS propagation delay
+# [pps]
+# pps_delay 0.0
+
+# fin

examples/terraform/sfptpd/files/sfptpd.nomad.tpl

@@ -0,0 +1,65 @@
+# nomad-onload sfptpd Nomad Job Template
+# Copyright (c) 2024 Neomantra BV
+
+job "sfptpd" {
+  region = "global"
+  datacenters = ["${NOMAD_DATACENTERS}"]
+  type = "system"
+
+  constraint {
+    attribute = "$${node.unique.name}"
+    value     = "${NOMAD_NODE_CONSTRAINT}"
+  }
+
+  update {
+    max_parallel = 1
+    stagger      = "1m"
+    auto_revert  = true
+  }
+
+  group "sfptpd" {
+    count = 1
+
+    ephemeral_disk {
+      sticky = true
+      migrate = true
+      size = 1024
+    }
+
+    task "sfptpd" {
+      driver = "docker"
+      config {
+        image = "${SFPTPD_IMAGE}"
+        args = [
+          "-v", 
+          "-i", "${NIC_INTERFACE}",
+          "-f", "$${NOMAD_ALLOC_DIR}/conf/sfptpd.cfg",
+        ]
+
+        # Sorry, the nomad-onload plugin can't do *everything* for you!
+        network_mode = "host"
+        privileged = true
+        cap_add = [
+          "net_bind_service",
+          "net_admin",
+          "net_raw",
+          "sys_time"
+        ]
+      }
+      resources {
+        device "ptp" {}
+        %{~ if lower("${ONLOAD_ENABLED}") == "true" ~}
+        device "onload" {}
+        %{~ endif ~} 
+      }
+
+      template {
+        destination = "$${NOMAD_ALLOC_DIR}/conf/sfptpd.cfg"
+        change_mode = "restart"
+        data        = <<EOT
+{{ with nomadVar "conf" }}{{ .sfptpd }}{{ end }}"
+EOT
+      }
+    }
+  }
+}

examples/terraform/sfptpd/main.tf

@@ -0,0 +1,53 @@
+# nomad-onload
+# sfptpd Terraform Example
+# Copyright (c) 2024 Neomantra BV
+#
+# Point the Provider address to your Nomad infrastracture
+#
+# The nomad-onload-plugin is only needed if you need Onload-enabled sfptpd;
+# you can use it with muggle devices.
+#
+# Install the nomad-onload Plugin on the Nomad Client and set "nomad_nodename".
+#
+
+# Yes, it should be variables, but this is a demo.
+locals {
+    # target this to your own infrastructure
+    nomad_address    = "http://localhost:4646"
+    nomad_datacenter = "*"
+    nomad_node       = "node1"
+    nic_interface    = "eth0"
+    sfptpd_image     = "onload/sfptpd:3.7.1.1007"
+}
+
+terraform {
+  required_providers {
+    nomad = {
+      source  = "hashicorp/nomad"
+      version = ">= 2.0.0"
+    }
+  }
+  required_version = ">= 1.6.2"
+}
+
+provider "nomad" {
+    address = local.nomad_address
+}
+
+resource "nomad_variable" "sfptpd" {
+  namespace = "default"
+  path      = "conf"
+  items = {
+    sfptpd = file("files/ptp_slave.yml.tpl")
+  }
+}
+
+resource "nomad_job" "sfptpd" {
+  jobspec = templatefile("files/sfptpd.nomad.tpl", {
+    NOMAD_DATACENTERS     = local.nomad_datacenter,
+    NOMAD_NODE_CONSTRAINT = local.nomad_node,
+    NIC_INTERFACE         = local.nic_interface,
+    SFPTPD_IMAGE          = local.sfptpd_image
+    ONLOAD_ENABLED        = "false"
+  })
+}