1. Synopsis

Name: sock
Reference ID: SOCK

2. Description

This driver receives its reference clock info from a datagram Unix socket. The driver creates the socket NTPsec readable with write access as defined by mode (below).

3. Structures of datagram packets

typedef struct
{
	struct timeval tv; // system time at measurement
	double offset; // source time - system time?
	int32_t pulse; // !0 is sample is from PPS source,
		       // i.e., other source required for  seconds
	int32_t
	    leap; // 0, 1, 2 -> normal, insert leap, delete leap second
	int32_t _pad;  // Padding, ignored
	int32_t magic; // Protocol Identifier 0x534f434b is 'SOCK'
} sockTime;

The driver uses two structures to decode the 32 and 64-bit time_t variants separately.

4. Operation mode

Processing each packet begins when it is received. Copying of variables occurs if a packet has a valid (32 or 40-byte) length. Shifting the other packets to empty and missized piles occurs then.

Moving some packets to the unsupported sender pile happens next. Shifting a packet to another pile occurs if it leaps wrong. Discarding also occurs for too old, off, or broken packets.

Adding the data of good packets to the queue then occurs.

Every poll interval, the data shifts, and writing to clock stats occurs.

5. Clockstats

NTPsec writes a clock stats record. The first three fields are the usual date, time, and source designator common to all clock stats records.

The 4th field is the number of received requests since the last poll. The 5th field is the number of empty packets received.

ntpd uses the last 64 responses. The 6th field is the number of samples that didn’t have a supported length. The 7th field is the number of samples from unsupported senders. The 8th field is the number of samples without an unsupported leap mode. The 9th field is the number of samples with non-finite offset, too large of a time offset, or pre-epoch time code. The 10th field is the count of usable samples.

Here is a sample showing driver starting up:
2025-02-07T14:18:03 ntpd[2127527]: REFCLOCK: sock(1) fd: 5
2025-02-07T14:18:03 ntpd[2127527]: REFCLOCK: sock(0) fd: 6

The clock identification is usually the driver type and unit, but if you have ntpd built in strict Classic compatibility mode; it will be a magic clock address expressing the same information in a more opaque way.

6. Driver Options

unit number

The driver unit number defaults to 0. Used as a distinguishing suffix in the unit name.

time1 time

Specifies the time offset calibration factor in decimal seconds, with default 0.0.

time2 time

Changes the maximum allowed difference between the remote and local clocks in seconds. Ignores values <1.0 or >86400.0, with a default value of 4 h (14400 s). See also flag 1.

stratum number

Stratum specifies the driver stratum, in decimal from 0 to 15, with default 0.

refid string

Refid specifies the driver reference identifier, an ASCII string from one to four characters, with default SOCK.

flag1 {0 | 1}

Checks the difference limit if set. Skips the difference limit if not set (default). There is no need for this flag; just let the upper-level logic prune out falsetickers. NOTE: This flag is the opposite of flag1 in NTP Classic.

flag2 {0 | 1}

Not used by this driver.

flag3 {0 | 1}

Not used by this driver.

flag4 {0 | 1}

Writes clock stats records when the driver is polled unless set 0.

subtype

Unsupported by this driver.

mode

Default 0. laxness of the security restriction.
0 only allows the creating uid to write to the socket.
1 allows anyone in group.
2 allows anyone.
3+ causes the instantiation to fail.
Only mode 0 is blessed. modes 1 and 2 are as abominations unto Gary.

path filename

This option specifies the path of the Unix socket. A typical path is /var/run/chrony.clk.gps0.sock or /var/run/chrony.ttyS0.sock, many Linux systems now use /run, but it may also work if placed in /tmp instead.

ppspath filename

Unsupported by this driver.

baud number

Unsupported by this driver.

7. GPSD Configuration Example

The most common use of this driver is to get samples from a gpsd instance. GPSD knows how to talk to many GPS devices. GPSD will provide one or more socket clocks depending on its configuration.

For a GPS receiver with a pulse-per-second (PPS) connected to the host, there will be one SHM clock for the serial data stream only and another SHM clock with the PPS timing (when available):

ntp.conf excerpt
refclock sock unit 0 path /var/run/chrony.clk.gps0.sock refid GPS
refclock sock unit 1 path /var/run/chrony.gps0.sock prefer refid PPS

You can set the minpoll as low as 0 with a default of 6.

Any change will require several hours for ntpd to converge with the new settings. Use ntpviz to find the best poll interval for your system.

The value that yields the lowest jitter may not be the one that yields the best offset.

8. Additional Information

Reference Clock Drivers

homeHome Page

sitemapSite Map

mail2Contacts