Time Sync Operations

This page is the operator runbook for Librux time sync on Linux. It keeps the command path focused on configuration, verification, and recovery.

Use it when you need these behaviors.

• configure a leader or follower host
• start the managed time-sync service or manual helper
• verify whether one-way cross-host timing can be accepted
• diagnose the common unsynchronized states

For deployment readiness checks, see Deployment Checks.

Operating Model

Librux does not make the control backend a global clock server. Time sync is a host-level responsibility observed by the runtime.

Normal Linux product deployments use the following.

• librux-control.service as the non-root host control backend
• librux-timesyncd.service for managed time-sync ownership
• ptp4l and phc2sys for PTP paths
• librux timesync doctor and /api/v1/control/status for readiness evidence

Do not run the control backend with sudo. Keep privileged clock work inside the time-sync service or explicit sudo librux-timesync ... helper commands.

Modes

Mode	Time-sync service behavior	Runtime clock behavior
auto	selects hardware PTP, software PTP, or Librux logical time from host evidence	reports the selected backend and acceptance evidence
ptp	starts linuxptp using the configured software_timestamping policy	observes PTP discipline
hardware_ptp	starts linuxptp and requires hardware timestamping	observes PTP discipline
software_ptp	starts linuxptp with software timestamping	observes PTP discipline; intended for diagnostics rather than strict production timing
librux_logical	leaves linuxptp stopped because the control backend owns logical synchronization	applies UDP-probe logical correction through the SDK clock layer
librux_logical_hw	leaves linuxptp stopped because the control backend owns logical synchronization	applies logical correction and requires hardware timestamp evidence

librux_logical and librux_logical_hw do not adjust the host system clock. They expose a Librux clock correction through the SDK clock layer.

1. Configure

Edit the installed runtime config.

<prefix>/bin/librux-config --config <prefix>/runtime/config.yaml

Typical keys.

control:
  advertise_host: <host-address>
  api_host: 0.0.0.0

federation:
  peers:
    - <peer-host>

time_sync:
  enabled: true
  management_mode: managed
  mode: auto
  role: auto
  leader_host: auto
  transport: auto
  nic: auto

For a fixed follower.

time_sync:
  enabled: true
  management_mode: managed
  mode: auto
  role: follower
  leader_host: <leader-host>
  transport: l2
  nic: <nic-name>

Transport rule.

• prefer l2 for same-switch physical hardware PTP validation
• use udp4 for VM, sandbox, or IP-oriented smoke tests
• keep auto when local linuxptp defaults are acceptable

If the runtime API is reachable from the network, enable security and restrict allowed client CIDRs before treating the host as a managed deployment.

2. Start Runtime

For product installs.

sudo systemctl status librux-control.service --no-pager
sudo systemctl status librux-timesyncd.service --no-pager

For a development shell.

. <prefix>/env.sh
librux control --config "$LIBRUX_PREFIX/config.yaml"

Readiness check.

curl -sf http://127.0.0.1:8001/api/v1/ready

3. Start Time Sync

Managed mode is the recommended path.

sudo systemctl enable --now librux-timesyncd.service

If services were not installed yet.

sudo <prefix>/bin/librux system install \
  --prefix <prefix> \
  --config <prefix>/runtime/config.yaml

Manual helper mode remains useful for bring-up and debugging.

sudo <prefix>/bin/librux-timesync \
  --config <prefix>/runtime/config.yaml \
  --run \
  --component ptp4l

Follower example.

sudo <prefix>/bin/librux-timesync \
  --config <prefix>/runtime/config.yaml \
  --run \
  --component ptp4l \
  --role follower \
  --leader-host <leader-host> \
  --transport l2 \
  --nic <nic-name>

Use the managed service for normal operation. Use manual helper commands only when you want foreground logs or a controlled validation window.

4. Verify

Run doctor.

. <prefix>/env.sh
librux timesync doctor --json

For convergence waits.

librux timesync doctor --wait --stable-polls 3

Runtime status.

curl -sf http://127.0.0.1:8001/api/v1/control/status

Minimum acceptance checks for cross-host one-way timing.

• time_sync_status.enabled = true
• selected role and leader match the intended topology
• selected backend is accepted for the workload
• clock_status.accepted_for_one_way = true
• clock_status.domain_compatible = true
• hardware PTP paths have a valid active NIC and no recent ptp4l faults

For PTP followers, a low ptp4l master offset alone is not enough. The application-visible clock must also be accepted. Librux reports that through clock_status, not by assuming the PTP servo is sufficient.

For Event one-way latency, time-sync readiness is necessary but not sufficient. the Event path gate for the exact publisher/subscriber pair must also report ready.

5. Recovery And Failure Cases

synced=false, ptp4l_running=false

Likely cause.

• time-sync service is not running
• manual helper was started without direct sudo

Fix.

sudo systemctl start librux-timesyncd.service
librux timesync doctor --json

synced=false, ptp4l_running=true, offset_ns=null

Likely cause.

• telemetry has not converged
• pmc cannot read linuxptp status
• the configured log directory does not match the active helper/service

Fix.

• wait and rerun doctor
• inspect the active time-sync log path
• confirm pmc -u -b 0 "GET TIME_STATUS_NP" works on the host

Follower reaches SLAVE, but one-way timing is rejected

Likely cause.

• PHC is tracking the master, but CLOCK_REALTIME is not accepted
• phc2sys is not running or is blocked by sanity checks
• another host time service is moving the system clock

Fix.

• stop competing time services for the validation window
• confirm the leader PHC bridge is running when required
• run the guided PHC/system recovery only when an explicit clock step is allowed

sudo <prefix>/bin/librux-timesync \
  --config <prefix>/runtime/config.yaml \
  --component phc-system-recovery \
  --run \
  --allow-clock-step \
  --max-clock-step-ns <bound>

After recovery, start normal time sync again and require clock_status.accepted_for_one_way=true before accepting one-way latency.

Doctor cannot read /dev/ptpN

Treat this as an observability or permission issue first. Use managed librux-timesyncd telemetry, run doctor with suitable privileges, or grant read access to the PHC device for the validation user.

Time sync is disabled in config

The runtime may be using a different config file than the one you edited. Re-apply the config and restart the relevant runtime service.

6. Stop

Stop only the time-sync companion when you are validating or changing time-sync policy.

sudo systemctl stop librux-timesyncd.service

If you started the helper directly in a foreground terminal, stop that helper process from the same terminal. Stop librux-control.service only when you are intentionally shutting down the host control backend.

Related Pages

• Federation Time Model
• Deployment Checks
• Troubleshooting
• CLI Tools
• Timing Benchmarks