# Reference Clock Support

Master Time Facility at the UDel Internet Research Laboratory

## 1. Related Links

### 1.1. Handbook Pages

- Command Index

- Access Control Support

- Association Management

- Authentication Support

- Automatic Server Discovery Schemes

- Rate Management

- Reference Clock Support

### 1.2. Reference Clock Support

- External Clock Discipline and the Local Clock Driver

- How to Write a Reference Clock Driver

- How to build new generic clocks

- Reference Clock Drivers

- local

- spectracom

- truetime

- generic

- arbiter

- modem

- nmea

- pps

- hpgps

- shm

- trimble

- oncore

- jjy

- zyfer

- gpsd

## 2. Table of Contents

- Introduction

- Special Considerations

- List of Reference Clock Drivers

## 3. Introduction

NTP supports a large number of satellite, radio and telephone modem reference clocks, plus a special pseudo-clock used for backup or when no other clock source is available.

A general description of the reference clock support is on this page. Additional information about each reference clock driver can be found via links from here. Additional information is on the Debugging Hints for Reference Clock Drivers and How To Write a Reference Clock Driver pages. Information on how to support pulse-per-second (PPS) signals produced by some devices is on the Pulse-per-second (PPS) Signal Interfacing page. All reference clock drivers require that the reference clock use only Coordinated Universal Time (UTC). Timezone and standard/daylight adjustments are performed by the operating system kernel.

Nowadays a reference clock will generally (though not always) be a GPS or GPSDO (GPS-disciplined oscillator). In former times it was often a radio timecode receiver synchronized to standard time as provided by NIST and USNO in the US, NRC in Canada and their counterparts elsewhere in the world. Precision time radios have been extinct in the U.S. since NIST changed their signal modulation at 2012-10-29T15:00:00Z; elsewhere they still exist but usage is declining under pressure from GPS technology.

A device driver specific to each reference clock must be compiled in the distribution; however, most common GPS, radio, satellite and telephone modem clocks are included by default and are activated by configuration commands. Note that an attempt to configure a reference clock when the driver has not been compiled or the hardware port has not been appropriately configured results in a scalding remark to the system log file, but is otherwise non hazardous.

Reference clocks are supported in the same way as ordinary NTP servers and use the same filter, select, cluster and combine algorithms. The connection to the computer is device dependent - usually a serial port. The particular device is specified by adding a soft link from the name used by the driver to the particular device name.

The `refclock` command is used to configure a reference clock. The options resemble those of the `server` directives, but `mode`, `minpoll`, `maxpoll`, and `prefer` options are supported for reference clocks, as described on the Reference Clock Commands page. The `prefer` option can be useful to persuade the server to cherish a reference clock with somewhat more enthusiasm than other reference clocks or peers. It is further discussed on the Mitigation Rules and the `prefer` Keyword page. The `minpoll` and `maxpoll` options have meaning only for selected clock drivers.

Additionally, the `refid` and `stratum` options can be used to override the defaults for the device. There are two optional device-dependent time offsets and four flags that can be included in the `refclock` command as well.

The stratum number of a reference clock is by default zero. Since the ntpd(8) daemon adds one to the stratum of each peer, a primary server ordinarily displays an external stratum of one. In order to provide engineered backups, it is often useful to specify the reference clock stratum as greater than zero. The stratum option is used for this purpose. Also, in cases involving both a reference clock and a pulse-per-second (PPS) discipline signal, it may be useful to specify the reference clock identifier as other than the default, depending on the driver. The refid option is used for this purpose. Except where noted, these options apply to all clock drivers.

## 4. Special Considerations

The Undisciplined Local Clock driver can simulate a reference clock when no external synchronization sources are available. If a server with this driver is connected directly or indirectly to the public Internet, there is some danger that it can destabilize other clients. It is not recommended that the local clock driver be used in this way, as the orphan mode described on the Association Management page provides a generic backup capability.

The local clock driver can also be used when an external synchronization source such as the IEEE 1588 Precision Time Protocol or NIST Lockclock directly synchronizes the computer time. Further information is on the External Clock Discipline and the Local Clock Driver page.

Several drivers make use of the pulse-per-second (PPS) signal discipline, which is part of the generic driver interface, so require no specific configuration. For those drivers that do not use this interface, the PPS Clock Discipline driver can provide this function. It normally works in conjunction with the reference clock that produces the timecode signal, but can work with another driver or remote server. When PPS kernel features are present, the driver can redirect the PPS signal to the kernel.

Some drivers depending on longwave or shortwave radio services need to know the radio propagation time from the transmitter to the receiver. This must be calculated for each specific receiver location and requires the geographic coordinates of both the transmitter and receiver. The transmitter coordinates for various radio services are given in the Time and Frequency Standard Station Information page. Receiver coordinates can be obtained locally or from Google Earth. The actual calculations are beyond the scope of this document.

Depending on interface type, port speed, etc., a reference clock can have a small residual offset relative to another. To reduce the effects of jitter when switching from one driver to the another, it is useful to calibrate the drivers to a common ensemble offset. The `enable calibrate` configuration command described on the Miscellaneous Options page activates a special feature which automatically calculates a correction factor for each driver relative to an association designated the prefer peer.

## 5. List of Reference Clock Drivers

Following is a list showing the type name and title of each driver currently implemented. Click on a selected type for specific description and configuration documentation.

If you have seen older versions of NTP, this list may have fewer entries than you expected. Support for some very ancient drivers (notably, those rendered obsolete by the WWVB modulation change at 2012-10-29T15:00:00Z) has been dropped in order to reduce our maintenance load. So have some other drivers (notably the Austron 2200A/2201A and Magnavox MX4200) after having been end-of-lifed with no sign of aftermarket activity for more than ten years. Several others have been removed for relying on obsolete buses or hardware classes that no longer exist.

For security reasons, we will no longer support any refclock that requires a closed-source driver to run. This filtered out the Datum/Bancomm/Symmetricom bc600-series GPS/IRIG Receiver, the Hopf GPS/DCF77 6039 for PCI-Bus, and the Spectracom TSYNC PCI. The Hopf 6021 driver has also been removed because it duplicates support for the 6021 in the generic parse driver.

Name | Flags | Driver
--- | --- | ---
local | - | Undisciplined Local Clock
spectracom | D2 | Generic Spectracom Receivers
truetime | d2 | TrueTime GPS/GOES Receivers
generic | T | Generic Reference Driver (Parse)
arbiter | d2 | Arbiter 1088A/B GPS Receiver
modem | - | NIST/USNO/PTB Modem Time Services
nmea | T | Generic NMEA GPS Receiver
pps | T | PPS Clock Discipline
hpgps | T | Hewlett Packard GPS Receivers
shm | T | Shared Memory Driver
trimble | D | Trimble Palisade/Thunderbolt/Acutime GPSes
oncore | d2 | Motorola Oncore GPS
jjy | T | JJY Receivers
zyfer | - | Zyfer GPStarplus Receiver
gpsd | d | GPSD client protocol

The name in the left column is the driver type to be used in the refclock declaration. Matching to these names is case-insensitive.

The flags field should be interpreted as follows:

Flag | Meaning
--- | ---
D | Deprecated. May be removed in a future release
d | Disabled in the Debian package.
T | Regularly tested by an active maintainer (some devices/modes)
2 | Returns only 2-digit years. Relies on system clock for century.

Home Page | Site Map | Contacts