DEV Community

Cover image for A Practical Guide to Time for Developers: Part 4 -The Linux Time Sync Cheat Sheet
Dmytro Huz
Dmytro Huz

Posted on • Originally published at dmytrohuz.com

A Practical Guide to Time for Developers: Part 4 -The Linux Time Sync Cheat Sheet

If you got here and made it through the previous articles, you have already done the hard part. You are basically a time guru now.

You know what time means in computing, how a machine keeps it, why clocks drift, how synchronization works, and why timestamp location matters. That is already more than most people ever learn about this topic.

Now let’s compress all of that into the Linux view of the world.

This is the top of the iceberg: a small set of clocks, commands, and tools that represent most of the concepts we have been building up across the series.

Think of this as the practical cheat sheet — the 90% version. The one you can use to inspect clocks, understand what is synchronized to what, and handle most everyday Linux time-sync tasks without drowning in documentation.

This is probably the part you will want to bookmark.


The three main clock entities in Linux

When people say “Linux time,” they often mean one thing. In reality, Linux commonly deals with at least three different clock entities:

  • system time
  • RTC
  • PHC

They serve different purposes.


1. System time

This is the normal wall-clock time used by most applications.

It is what you usually see when you run:

date
Enter fullscreen mode Exit fullscreen mode

or:

timedatectl
Enter fullscreen mode Exit fullscreen mode

Conceptually, this is the kernel’s main wall clock, commonly associated with CLOCK_REALTIME.

This is the clock used by:

  • most user-space applications
  • logs
  • system services
  • everyday time queries

Quick check

date
timedatectl
Enter fullscreen mode Exit fullscreen mode

Mental model

System clock = the main OS wall clock
Enter fullscreen mode Exit fullscreen mode

2. RTC (Real-Time Clock)

The RTC is the battery-backed hardware clock on the motherboard.

Its main job is simple: keep time while the machine is powered off.

Linux often uses it during boot to initialize system time, and may update it again later from system time. But the RTC is usually not the main precision synchronization clock during normal operation.

Quick check

sudo hwclock --show
timedatectl
Enter fullscreen mode Exit fullscreen mode

Common operations

Copy system time to RTC:

sudo hwclock --systohc
Enter fullscreen mode Exit fullscreen mode

Copy RTC to system time:

sudo hwclock --hctosys
Enter fullscreen mode Exit fullscreen mode

Mental model

RTC = persistent clock for boot/shutdown
Enter fullscreen mode Exit fullscreen mode

3. PHC (PTP Hardware Clock)

A PHC is a hardware clock exposed by a PTP-capable network interface.

This is where Linux gets especially interesting.

A PHC lives on the NIC, much closer to the real transmit/receive event than the normal system clock. That is why it matters for precise synchronization.

PHCs usually appear as device files like:

/dev/ptp0
/dev/ptp1
Enter fullscreen mode Exit fullscreen mode

Quick check

List PHC devices:

ls -l /dev/ptp*
Enter fullscreen mode Exit fullscreen mode

Check which PHC belongs to a NIC and whether hardware timestamping is supported:

ethtool -T eth0
Enter fullscreen mode Exit fullscreen mode

Mental model

PHC = hardware clock on the NIC, used for precise packet timing
Enter fullscreen mode Exit fullscreen mode

One picture: how they relate

RTC
  |
  | used mainly at boot / shutdown
  v
System clock (CLOCK_REALTIME)
  ^
  |
  | phc2sys can sync between them
  |
PHC (/dev/ptpX on NIC)
  ^
  |
  | ptp4l syncs PHC to PTP network
  |
PTP network / Grandmaster
Enter fullscreen mode Exit fullscreen mode

A rough summary:

  • RTC keeps time while power is off
  • system clock is what most software reads
  • PHC is the precision clock on the NIC

How Linux syncs time with NTP

In the NTP world, Linux usually synchronizes the system clock.

Common tools:

  • chronyd
  • systemd-timesyncd
  • older setups may use ntpd

Check whether NTP is active

timedatectl
Enter fullscreen mode Exit fullscreen mode

If you use chrony

Show synchronization state:

chronyc tracking
Enter fullscreen mode Exit fullscreen mode

Show time sources:

chronyc sources -v
Enter fullscreen mode Exit fullscreen mode

Mental model

NTP servers
   |
   v
chronyd / timesyncd / ntpd
   |
   v
System clock
Enter fullscreen mode Exit fullscreen mode

In other words, NTP usually targets the system clock, not the PHC.


How Linux syncs time with PTP

In the PTP world, Linux often follows a two-step path:

  1. synchronize the PHC to the PTP network
  2. synchronize the system clock to that PHC

The two main tools are:

  • ptp4l
  • phc2sys

ptp4l: syncing the NIC-side clock

ptp4l speaks PTP on the network and usually synchronizes the PHC associated with the interface.

Typical example:

sudo ptp4l -i eth0 -m
Enter fullscreen mode Exit fullscreen mode

Meaning:

  • i eth0 → use interface eth0
  • m → print log messages to stdout

Mental model

PTP Grandmaster / network
        |
        v
      ptp4l
        |
        v
PHC on eth0 (/dev/ptpX)
Enter fullscreen mode Exit fullscreen mode

This is usually where the NIC-side precision timing gets aligned to the network timing domain.


phc2sys: syncing one local clock to another

Once the PHC is synchronized, the rest of the machine may still be reading the system clock.

That is why phc2sys exists.

Its job is to synchronize one local clock to another.

The most common use is:

PHC → system clock

Example:

sudo phc2sys -s eth0 -c CLOCK_REALTIME -m
Enter fullscreen mode Exit fullscreen mode

Meaning:

  • s eth0 → source is the PHC associated with eth0
  • c CLOCK_REALTIME → target is the system clock
  • m → print status

Mental model

PHC on NIC
   |
   v
phc2sys
   |
   v
System clock
Enter fullscreen mode Exit fullscreen mode

This is the classic Linux PTP flow.


The classic Linux PTP pipeline

PTP Grandmaster
      |
      v
  [ network ]
      |
      v
NIC hardware timestamping
      |
      v
    ptp4l
      |
      v
PHC (/dev/ptp0) synchronized to PTP domain
      |
    phc2sys
      |
      v
System clock (CLOCK_REALTIME)
      |
      v
Applications / logs / services
Enter fullscreen mode Exit fullscreen mode

This is one of the most useful diagrams to keep in your head.


PHC to system clock, or system clock to PHC?

In precision setups, the common direction is:

PHC → system clock
Enter fullscreen mode Exit fullscreen mode

because the PHC is closer to the wire and usually the better timing source in a PTP environment.

That is why this is a common command:

sudo phc2sys -s eth0 -c CLOCK_REALTIME -m
Enter fullscreen mode Exit fullscreen mode

But phc2sys is more general than that. It can synchronize clocks in other directions too.


Syncing one PHC to another

Linux can also synchronize different hardware clocks to each other.

Conceptually:

PHC A → PHC B
Enter fullscreen mode Exit fullscreen mode

For example:

sudo phc2sys -s /dev/ptp0 -c /dev/ptp1 -m
Enter fullscreen mode Exit fullscreen mode

This is less common than PHC-to-system-clock sync, but it is useful when one interface or subsystem should follow another local hardware clock.


Where software timestamping fits

Not every NIC has hardware timestamping. Not every system needs that level of precision.

Linux can still synchronize clocks using software timestamps, and for many use cases that is completely fine.

But the practical tradeoff remains the same:

  • hardware timestamping gives measurements closer to the real wire event
  • software timestamping includes more delay and variation from the OS path

That is why software timestamping usually belongs to a looser precision budget, while hardware timestamping is what unlocks much tighter synchronization.


The most useful commands at a glance

Check system time

date
timedatectl
Enter fullscreen mode Exit fullscreen mode

Check RTC

sudo hwclock --show
Enter fullscreen mode Exit fullscreen mode

List PHC devices

ls -l /dev/ptp*
Enter fullscreen mode Exit fullscreen mode

Check NIC timestamping support

ethtool -T eth0
Enter fullscreen mode Exit fullscreen mode

Run PTP on an interface

sudo ptp4l -i eth0 -m
Enter fullscreen mode Exit fullscreen mode

Sync system clock from PHC

sudo phc2sys -s eth0 -c CLOCK_REALTIME -m
Enter fullscreen mode Exit fullscreen mode

Check chrony state

chronyc tracking
chronyc sources -v
Enter fullscreen mode Exit fullscreen mode

The one table worth remembering

RTC ------------------> system time at boot / shutdown
NTP daemon -----------> system clock
ptp4l ----------------> PHC
phc2sys --------------> PHC <-> system clock
hwclock --systohc ----> system clock -> RTC
hwclock --hctosys ----> RTC -> system clock
Enter fullscreen mode Exit fullscreen mode

The biggest practical lesson

When somebody says:

“The machine is synchronized.”

That is usually too vague.

The useful follow-up question is:

Which clock is synchronized?

  • the RTC?
  • the system clock?
  • the PHC?
  • and which one is the application actually using?

That one question prevents a lot of confusion.


One-screen summary

RTC
- battery-backed motherboard clock
- keeps time while machine is off
- checked with: hwclock --show

System clock
- main OS wall clock
- used by most applications
- checked with: date, timedatectl
- synchronized by: NTP or by phc2sys from PHC

PHC
- hardware clock on a PTP-capable NIC
- represented as: /dev/ptpX
- checked with: ls /dev/ptp*, ethtool -T eth0
- synchronized by: ptp4l

Typical Linux PTP flow
PTP network -> ptp4l -> PHC -> phc2sys -> system clock
Enter fullscreen mode Exit fullscreen mode

Final note

If you made it all the way here, you did not just read a few articles about clocks.

You built a real mental model of time in computing — from first principles, to clocks inside a machine, to synchronization across networks, to the actual Linux entities and tools that make it work in practice.

That already puts you far ahead of most engineers who touch these systems.

You now know enough to stop treating time as a mysterious background feature and start seeing it for what it really is: infrastructure, measurement, coordination, and engineering.

And it was the final piece: a practical cheat sheet you can actually use. Bookmark it. Return to it. Break things with it. Fix things with it.


Top comments (0)