the state of clock synchronization and setting in debian

 In the PC "architecture", there are two main clocks in the sense of what's the time.  The hardware clock lives on the motherboard, and can be spotted by its button-shaped CR2032 battery, which maintains the time even when no power supply is connected.  The OS clock exists in volatile state, somehow between the memory and the CPU, meaning it is lost when the OS is shut down.  From the perspective of a POSIX user, the OS time is accessed thru functions like time(2), or the date(1) utility.

On boot, the OS clock gets its time initialised from the hardware clock.  Shortly after, depending on the system's ntp configuration, and the right network access, this may get replaced straight away with an ntp server's notion of the time.  Therefore, the sysadmin may not notice if the hardware clock is wrong, if the system gets its time from ntp shortly after each boot.  This creates a situation where, if the system has to be brought up without network (or internet, depending on where this ntp server is) access, its clock is wrong.  This introduces more errors and inconsistencies at a time when it is probably least convenient.

On shutdown, the hardware clock may get set based on the OS clock.  This helps preserve the correct time across reboots or while powered-down.  When I looked at this on Debian around a decade ago, it did this.  There was a hwclock --systohc in some init script called at shutdown. 

During normal operation, the hardware clock is probably not getting synced.  Note that for systems that only ever shutdown by losing power, their hardware clock never gets set.  But if they get their time from ntp on boot, no one may notice (until they do).  When I looked on Debian a decade ago, there was no ongoing or regular sync from the OS clock to the hardware clock.  We added configuration on our servers to set the hardware clock once a day or so.  We also added monitoring of the difference between the OS and the hardware clock, and also of the differences of these with NTP.  

If there is a notion of sync-ing the OS clock to the hardware clock, there is no reason for this to be a shutdown-time-only action.  This should be part of the standard Debian configuration.  This is one doable improvement.  I'd be interested to know if any of the Linux-based distributions do this.

I've just set the time on a computer with LAN-only network access and no NTP config.  As a quick check, I rebooted it.  It came back up with the wrong time.  This is Debian 11.  So perhaps Debian has lost even the sync-on-shutdown thing that it used to have.  Perhaps this is a side-effect of them migrating to systemd.  I set it again, ran hwclock --systohc by hand, and rebooted.  It came back with the correct time.  But note that the hardware clock is now drifting, at whatever rate it drifts at, and there is nothing to bring it back.  One day, after a reboot, the difference will be big enough to cause a problem.  Unless all the monitoring and syncing configuration is put in place again.

This is a sad example of the lack of good technical interface design in Linux.  To someone capable of taking an overview of the system, and lacking attachment to particular happenstance, it is obvious that whatever is presented to the user (sysadmin) as the normal way of setting the time, should set both the OS time and the hardware clock, presenting just a general view of system time that incorporates both, without the user (sysadmin) having to worry about the distinction.  In cases where the user (sysadmin) does care about the distinction, more specific tooling should be available so they can do so.

It's almost 20 years since I worked with Solaris, but its design was pretty good on this front.  I remember that to have a serial console, you set something.  You did not have to do 4 things: one for a BIOS, one for a bootloader, one for a kernel, and one for a "gettty" / login stage.  You set one thing, because someone with decent technical design, designed it that way.  I don't remember how you set the date and time on Solaris, and whether this presented a unified view of setting both volatile and persistent hardware clock times.

How might a unified interface design look, taking account of the context of POSIX?

The date utility is only for reading the time in POSIX.  This means that the common -s option, for setting the time on GNU coreutils's date (and possibly others) is what POSIX tends to call an "implementation matter", but what would more properly be called an "extension" of the interface defined in POSIX.  If date -s is still going to be the normal way presented to the user (sysadmin) to set the system time, then it should set both the OS and the hardware time.  This should be specified clearly in the system's documentation for the date utility, which should categorise date as an interface element extended from POSIX, and should state that the -s option itself is an extension not in the POSIX version of date.

The clock_settime function, with clock_id value of CLOCK_REALTIME, is the POSIX way to set the time (I can't locate a utility to set the time, just a function).  I have not used this interface in a program, and I don't know its exact behaviour on Linux currently.  From the POSIX definition, which talks about a notion of "system" time without distinguishing between volatile vs hardware clocks, clock_settime(CLOCK_REALTIME, ?) should indeed set both, in a nice implementation.  I suspect it currently just sets the volatile OS clock, but haven't checked.  Note the potential for confusion here, because Linux-heads (who have no sense of technical design, btw) talk about RTC, meaning realtime clock, as the hardware clock, whereas CLOCK_REALTIME in POSIX means the general notion of system time, and in the Linux implementation may (to check!) have ended up being the OS-only time.  Not just the term "real time", but also the term "system", is overloaded in this context, and so both should be clarified on use.

Next time someone Ubuntifies (forks Debian publicly), I'd love to see them take care of technical design details with some kind of care, taking care of cross-cutting concerns throughout the whole system holistically, simplifying rather than always complifying interface design, and specifying the provided interfaces and their relationships to standard interfaces like POSIX explicitly and diligently in the user manual.