The Clock Mini-HOWTO

• Index
• Introduction
• How Linux Keeps Track of Time
• Software
• Radio Clocks

3. Software

3.1 Clock(8) and Hwclock(8)

All linux distributions install either the old clock(8) or the newer hwclock(8), but without a correction factor. Some may also install adjtimex(8), or they may include it on the CD as optional (or you can download it from the usual Linux archive sites). Some distributions also include a graphical clock setting program that runs in an X-window, but those are designed for interactive use, and the system will still install clock(8) or hwclock(8) for use in the startup scripts.

Clock(8) requires you to calculate the correction factor by hand, but hwclock(8) calculates it automatically whenever you use it to reset the RTC (using another program to set the RTC will interfere with the drift correction, so always use the same program if you're using a correction factor). If you have an older system that still uses clock(8) and you want to upgrade, you can find hwclock(8) in the "util-linux" package, version 2.7 or later. See the man page for more information.

Note

The man page for hwclock(8) may be called "clock" for backward compatibility, so try both names. Hwclock(8) will respond to commands written for clock(8), but the result may not be the same-- in particular, "hwclock -a" is not quite the same as "clock -a", so if you're upgrading to hwclock I'd suggest replacing all references to "clock" in your startup scripts to use hwclock's native commands instead.

The startup scripts vary from one distribution to another, so you may have to search a bit to find where it sets the clock. Typical locations are /etc/rc.local, /etc/rc.d/rc.sysinit, /etc/rc.d/boot, or some similar place.

The correction factor for the RTC is stored in /etc/adjtime. Red Hat has a script in /etc/sysconfig/clock that controls the options to hwclock.

When you're setting the clock to determine the drift rate, keep in mind that your local telephone time announcement may or may not be accurate. If you don't have a shortwave radio or GPS receiver, you can hear the audio feed from WWV by calling (303)499-7111 (this is a toll call to Boulder, Colorado). It will cut you off after three minutes, but that should be long enough to set the clock. USNO and Canada's CHU also have telephone time services, but I prefer WWV's because there is more time between the announcement and the "beep". You can also get the time from a network time server using the ntpdate program that comes with ntpd, and there's a javaclock at www.time.gov.

In any case, what you're setting is the system clock, not the RTC (see the man page for the date command for the formats to use). Then use hwclock to set the RTC and calculate the drift rate. If you're doing this by hand, you should be able to set it within a second or two, and get a reasonable approximation of the drift rate after a few weeks. Then you can run adjtimex(8) to fine-tune the system clock.

3.2 Adjtimex(8)

Adjtimex(8) allows the user to adjust the kernel's time variables, and therefore change the speed of the system clock (you must be logged in as "root" to do this). It is cleverly designed to compare the system clock to the RTC using the same correction factor used by clock(8) or hwclock(8), as stored in /etc/adjtime. So, once you've established the drift rate of the RTC, it's fairly simple to correct the system clock as well. Once you've got it running at the right speed, you can add a line to your startup scripts to set the correct kernel variables at boot time. Since adjtimex(8) was designed to work with clock(8) or hwclock(8), it includes a work-around for the "every 11 minutes" bug.

After you've installed adjtimex(8) you can get more information on setting it up by typing "man 8 adjtimex" (there is also an adjtimex(2) man page, which is not what you want) and by reading the README file in /usr/doc/adjtimex-1.3/README (where the version number in the path will be the current version of adjtimex(8)).

3.3 Xntpd and ntpd: the Network Time Protocol

Xntpd (NTPv3) has been replaced by ntpd (NTPv4); the earlier version is no longer being maintained.

Ntpd is the standard program for synchronizing clocks across a network, and it comes with a list of public time servers you can connect to. It can be a little more complicated to set up than the other programs described here, but if you're interested in this kind of thing I highly recommend that you take a look at it anyway.

The "home base" for information on ntpd is the NTP website at http://www.eecis.udel.edu/~ntp/ which also includes links to all kinds of interesting time-related stuff (including software for other OS's). Some linux distributions include ntpd on the CD. There is a list of public time servers at http://www.eecis.udel.edu/~mills/ntp/clock2.html.

A relatively new feature in ntpd is a "burst mode" which is designed for machines that have only intermittent dial-up access to the internet.

Ntpd includes drivers for quite a few radio clocks (although some appear to be better supported than others). Most radio clocks are designed for commercial use and cost thousands of dollars, but there are some cheaper alternatives (discussed in later sections). In the past most were WWV or WWVB receivers, but now most of them seem to be GPS receivers. NIST has a PDF file that lists manufacturers of radio clocks on their website at http://www.boulder.nist.gov/timefreq/links.htm (near the bottom of the page). The NTP website also includes many links to manufacturers of radio clocks at http://www.eecis.udel.edu/~ntp/hardware.htm and http://www.eecis.udel.edu/~mills/ntp/refclock.htm. Either list may or may not be up to date at any given time :-). The list of drivers for ntpd is at http://www.eecis.udel.edu/~ntp/ntp_spool/html/refclock.htm.

Ntpd also includes drivers for several dial-up time services. These are all long-distance (toll) calls, so be sure to calculate the effect on your phone bill before using them.

3.4 Chrony

Xntpd was originally written for machines that have a full-time connection to a network time server or radio clock. In theory it can also be used with machines that are only connected intermittently, but Richard Curnow couldn't get it to work the way he wanted it to, so he wrote "chrony" as an alternative for those of us who only have network access when we're dialed in to an ISP (this is the same problem that ntpd's new "burst mode" was designed to solve). The current version of chrony includes drift correction for the RTC, for machines that are turned off for long periods of time.

You can get more information from Richard Curnow's website at http://www.rrbcurnow.freeuk.com/chrony or http://go.to/chrony. There are also two chrony mailing lists, one for announcements and one for discussion by users. For information send email to chrony-users-subscribe@egroups.com or chrony-announce-subscribe@egroups.com

Chrony is normally distributed as source code only, but Debian has been including a binary in their "unstable" collection. The source file is also available at the usual Linux archive sites.

3.5 Clockspeed

Another option is the clockspeed program by DJ Bernstein. It gets the time from a network time server and simply resets the system clock every three seconds. It can also be used to synchronize several machines on a LAN.

I've sometimes had trouble reaching his website at http://Cr.yp.to/clockspeed.html, so if you get a DNS error try again on another day. I'll try to update this section if I get some better information.