This document is mastered in asciidoc format. If you are reading it in HTML,you can find the original at the GPSD project website.

GPSD, NTP and a GPS receiver supplying 1PPS (one pulse-per-second)output can be used to set up a high-quality NTP time server. ThisHOWTO explains the method and various options you have in setting itup.

Here is the quick-start sequence. The rest of this document goesinto more detail about the steps.

1. Ensure that gpsd and either ntpd or chronyd are installed on yoursystem. (Both gpsd and ntpd are pre-installed in many stock Linuxdistributions; chronyd is normally not.) You don’t have to choosewhich to use yet if you have easy access to both, but knowing whichalternatives are readily available to you is a good place to start.

2. Verify that your gpsd version is at least 3.22. Many problems arecaused by the use of old versions. When in doubt, reinstallgpsd from the upstream source. Many distributions ship oldand/or broken versions of gpsd.

3. Connect a PPS-capable GPS receiver to one of your serial or USBports. A random cheap consumer-grade GPS receiver won’t do; youmay have to do some hunting to find a usable one.

4. Check that it actually emits PPS by pointing GPSD’s gpsmon utilityat the port. If it has a good (3D-mode) fix, lines marked "PPS"should scroll by in the packet-logging window. A new device out ofthe box may take up to 30 minutes for the first 3D fix. If gpsmonshows a 3D fix, but does not show PPS lines, try running ppscheck.

5. If you persistently fail to get live PPS, (a) you may have askyview problem, (b) you may have a cabling problem, (c) your GPSmay not support PPS, (d) you may have a gpsd or kernel configurationproblem, (e) you may have a device problem, (f) there may be a bugin the core GPSD code used by gpsmon. These are listed in roughlydecreasing probability. Troubleshoot appropriately.

6. Edit your ntpd or chronyd configuration to tell your NTP daemon tolisten for time hints. (This step is somewhat tricky.)

7. Start up gpsd. If you are using ntpd, you can use ipcrm(1) to check thatverify that the shared-memory segment that gpsd and ntpd want touse to communicate has been attached; or you can impatiently skipto the next step and look for the segment only if that fails.

8. Use cgps or xgps to verify that your GNSS receiver has a good 3D fix.

9. Use ntpshmmon to verify that gpsd is sending time corrections to SHMmemory.

10. Use ntpq or the chronyc sources command to verify that your deviceis feeding time corrections to your NTP daemon.

11. (Optional and challenging.) Hand-tune your installation for thebest possible performance.

This document does not attempt to explain all the intricacies of timeservice; it is focused on practical advice for one specific deploymentcase. There is an introduction[TIME-INTRO] to basic concepts andterminology for those new to time service. An overview of the NTPprotocols can be found at[WIKI-NTP], and the official NTP FAQ[NTP-FAQ] is probably as gentle an introduction to the NTP referenceimplementation as presently exists.

We encourage others to contribute additions and corrections.

There are a few important terms we need to define up front.Latencyis delay from a time measurement until a report on it arrives where itis needed.Jitter is short-term variation in latency.Wobble is ajitter-like variation that is long compared to typical measurementperiods.Accuracy is the traceable offset from 'true' time asdefined by a national standard institute.

A good analogy to jitter vs wobble is changes in sea level on a beach.Jitter is caused by wave action, wobble is the daily effect of tides.For a time server, the most common causes of wobble are varying GPSsatellite geometries and the effect of daily temperature variations onthe oscillators in your equipment.

See[TIME-INTRO] for a technical description of how NTP correctsyour computer’s clock against wobble. For purposes of this how-to, theimportant concepts to take way are those of time strata, servers, andreference clocks.

Ordinary NTP client computers are normally configured to get time fromone or more Stratum 2 (or less commonly Stratum 3) NTPservers. However, with GPSD and a suitable GPS receiver, you can easilycondition your clock to higher accuracy than what you get from typicalStratum 2; with a little effort, you can do better than you can getfrom most public Stratum 1 servers.

You can then make your high-quality time available to other systems onyour network, or even run a public NTP server. Anyone can do this;there is no official authority, and any NTP client may choose to useyour host as a server by requesting time from it. The time-servicenetwork is self-regulating, with NTP daemons constantly pruningstatistical outliers so the timebase cannot be accidentally ordeliberately compromised.

In fact many public and widely-trusted Stratum 1 servers use GPSreceivers as their reference clocks, and a significant fraction ofthose use GPSD in the way we will describe here.

The way time is shipped from GPS satellites causes problems tobeware of in certain edge cases.

Date and time in GPS is represented as number of weeks from the startof zero second of 6 January 1980, plus number of seconds into theweek. GPS time isnot leap-second corrected, though satellites alsobroadcast a current leap-second correction which is updated onsix-month boundaries according to rotational bulletins issued by theInternational Earth Rotation and Reference Systems Service (IERS).

The leap-second correction is only included in the multiplexed satellitesubframe broadcast, once every 12.5 minutes. While the satellites donotify GPSes of upcoming leap-seconds, this notification is notnecessarily processed correctly on consumer-grade devices, and may notbe available at all when a GPS receiver has just cold-booted. Thus,reported UTC time may be slightly inaccurate between a cold boot or leapsecond and the following subframe broadcast.

GPS date and time are subject to a rollover problem in the 10-bit weeknumber counter, which will re-zero every 1024 weeks (roughly every 19.6years). The first rollover since GPS went live in 1980 was in Aug-1999,followed by Apr-2019, the next will be in Nov-2038 (the 32-bit and POSIXissues will probably be more important by then). The new "CNAV" dataformat extends the week number to 13 bits, with the first rolloveroccurring in Jan-2137, but this is only used with some newly added GPSsignals, and is unlikely to be usable in most consumer-grade receiverscurrently.

For accurate time reporting, therefore, a GPS requires a supplementaltime references sufficient to identify the current rollover period,e.g. accurate to within 512 weeks. Many GPSes have a wired-in (andundocumented) assumption about the UTC time of the last rollover andwill thus report incorrect times outside the rollover period they weredesigned in.

For accurate time service via GPSD, you require three things:

• A GPS made since the last rollover, so its hidden assumption aboutthe epoch will be correct.

• Enough time elapsed since a cold boot or IERS leap-second adjustmentfor the current leap-second to get update.

• A GPS that properly handles leap-second adjustments. Anythingbased on a u-blox from v6 onward should be good; the status ofSiRFs is unknown and doubtful.

GPSD is useful for precision time service because it can use the 1PPSpulse delivered by some GPS receivers to discipline (correct) a localNTP instance.

It’s tempting to think one could use a GPS receiver for time servicejust by timestamping the arrival of the first character in the reporton each fix and correcting for a relatively small fixed latencycomposed of fix-processing and RS232 transmission time.

At one character per ten bits (counting framing and stopbits) a9600-bps serial link introduces about a mSec of latencypercharacter; furthermore, your kernel will normally delay deliveryof characters to your application until the next timer tick, aboutevery 4 mSec in modern kernels. Both USB and RS232 will incur thatapproximately 5mSec-per-char latency overhead. You’ll have to dealwith this latency even on chips like the Venus 6 that claim thebeginning of their reporting burst is synced to PPS. (Such claims arenot always reliable, in any case.)

Unfortunately, fix reports are also delayed in the receiver and onthe link by as much as several hundred mSec, and this delay is notconstant. This latency varies (wobbles) throughout the day. It may bestable to 10 mSec for hours and then jump by 200mSec. Under thesecircumstances you can’t expect accuracy to UTC much better than 1second from this method.

For example: SiRF receivers, the make currently most popular inconsumer-grade GPS receivers, exhibit a wobble of about 170mSec in theoffset between actual top-of-second and the transmission of the firstsentence in each reporting cycle.

To get accurate time, then, the in-band fix report from the GPSreceiver needs to be supplemented with an out-of-band signal that hasa low and constant or near-constant latency with respect to the timeof the fix. GPS satellites deliver a top-of-GPS-secondnotification that is nominally accurate to 50nSec; in capable GPSreceivers that becomes the 1PPS signal.

1PPS-capable GPS receivers use an RS-232 control line to ship the 1PPSedge of second to the host system (usually Carrier Detect or RingIndicator; GPSD will quietly accept either). Satellite top-of-secondloses some accuracy on the way down due mainly to variable delays inthe ionosphere; processing overhead in the GPS receiver itself adds abit more latency, and your local host detecting that pulse adds stillmore latency and jitter. But it’s still often accurate to on theorder of 1 uSec.

Under most Unixes there are two ways to watch 1PPS; Kernel PPS (KPPS)and plain PPS latching. KPPS is an implementation of RFC 2783[RFC-2783].Plain PPS just references the pulse to the system clock asmeasured in user space. These have different error budgets.

Kernel PPS uses a kernel function to accurately timestamp the statuschange on the PPS line. Plain PPS has the kernel wake up the GPSD PPSthread and then the PPS thread reads the current system clock. Asnoted in the GPSD code, having the kernel do the time stamp yieldslower latency and less jitter. Both methods have accuracy degraded byinterrupt-processing latency in the kernel serial layer, but plainPPS incurs additional context-switching overhead that KPPS does not.

With KPPS it is very doable to get the system clock stable to ±1uSec. Otherwise, you are lucky to get ±5 uSec, and there will beabout 20uSec of jitter. All these figures were observed onplain-vanilla x86 PCs with clock speeds in the 2GHz range.

All the previous figures assume you’re using PPS delivered over RS232.USB GPS receivers that deliver 1PPS are rare, but do exist. Notably,there’s the Navisys GR-601W/GR-701W/GR-801W[MACX-1]. In case these devices goout of production it’s worth noting that they are a trivialmodification of the stock two-chip-on-a-miniboardcommodity-GPS-receiver design of engine plus USB-to-serial adapter;the GR-[678]01W wires a u-blox 6/7/8 to a Prolific Logic PL23203. Toget 1PPS out, this design just wires the 1PPS pin from the GPS engineto the Carrier Detect pin on the USB adapter. (This is known as the"Macx-1 mod".)

With this design, 1PPS from the engine will turn into a USB event thatbecomes visible to the host system (and GPSD) the next time the USBdevice is polled. USB 1.1 polls 1024 slots every second. Each slot ispolled in the same order every second. When a device is added it isassigned to one of those 1024 polling slots. It should then be clearthat the accuracy of a USB 1.1 connected GPS receiver would be about 1mSec.

As of mid-2016 no USB GPS receiver we know of implements the higherpolling-rate options in USB 2 and 3 or the interrupt capability in USB3. When one does, and if it has the Macx-1 mod, higher USB accuracywill ensue.

Observed variations from the typical figure increase towards the bottomof the table. Notably, a heavily loaded host system can reduce PPSaccuracy further, though not KPPS accuracy except in the most extremecases. The USB poll interval tends to be very stable (relative to its1mSec or 100μSec base).

Network NTP time accuracy can be degraded below RFC5905’s "a few tensof milliseconds" by a number of factors. Almost all have more to dowith the quality of your Internet connection to your servers than withthe time accuracy of the servers themselves. Some negatives:

• Having a cable modem. That is, as opposed to DSL or optical fiber, whichtend to have less variable latencies.

• Path delay asymmetries due to peering policy. These can confuseNTP’s reconciliation algorithms.

With these factors in play, worst-case error can reach up to±100mSec. Fortunately, errors of over ±100mSec areunusual and should occur only if all your network routes to servershave serious problems.

If your kernel provides the RFC 2783 KPPS (kernel PPS) API, gpsd willuse that for extra accuracy. Many Linux distributions have a packagecalled "pps-tools" that will install KPPS support and the timepps.hheader file. We recommend you do that. If your kernel is built inthe normal modular way, this package installation will suffice.

Building gpsd

$ scons -c$ scons timeservice=yes

Kernel support

CONFIG_PPS=yCONFIG_PPS_CLIENT_LDISC=y

CONFIG_PPS_CLIENT_GPIO=yCONFIG_GPIO_SYSFS=y

Time service daemon

NTPSec

To get 1PPS to your NTP daemon, you first need to get it from aPPS-capable GPS receiver. As of early 2015 this means either thepreviously mentioned GR devices or a serial GPS receiver with 1PPS.

You can find 1PPS-capable devices supported by GPSD at[HARDWARE].Note that the most popular consumer-grade GPS receivers do not usuallydeliver 1PPS through USB or even RS232. The usual run of cheap GPSmice won’t do. In general, you can’t use a USB device for timeservice unless you know it has the Macx-1 mod.

In the past, the RS232 variant of the Garmin GPS-18 has been verycommonly used for time service (see[LVC] for a typical setup verywell described). While it is still a respectable choice, newerdevices have better sensitivity and signal discrimination. This makesthem superior for indoor use as time sources.

In general, use a GPS receiver with an RS232 interface for timeservice if you can. The GR-601W was designed (by one of the authors,as it happens) for deployment with commodity TCP/IP routers that onlyhave USB ports. RS232 is more fiddly to set up (with older deviceslike the GPS-18 you may even have to make your own cables) but it candeliver three orders of magnitude better accuracy and repeatability — enough to meet prevailing standards for a public Stratum 1 server.

Among newer receiver designs the authors found the u-blox line ofreceivers used in the GR-[678]01W to be particularly good. Verydetailed information on its timing performance can be found at[UBLOX-TIMING]. One of us (Raymond) has recent experience with aneval kit, the EVK 6H-0-001, that would make an excellent Stratum 0device.

Both the EVK 6H and GR-601W are built around the LEA-6H module, whichis a relatively inexpensive but high-quality navigation GPSreceiver. We make a note of this because u-blox also has a specializedtiming variant, the LEA 6T, which would probably be overkill for anNTP server. (The 6T does have the virtue that you could probably get agood fix from one satellite in view once it knows its location, butthe part is expensive and difficult to find.)

Unfortunately as of early 2015 the LEA-6H is still hard to find in apackaged RS232 version, as opposed to a bare OEM module exporting TTLlevels or an eval kit like the EVK 6H-0-001 costing upwards ofUS$300. Search the web; you may find a here-today-gone-tomorrow offeron alibaba.com or somewhere similar.

The LEA-6T, and some other higher-end GPS receivers (but not theLEA-6H) have a stationary mode which, after you initialize it with thedevice’s location, can deliver time service with only one goodsatellite lock (as opposed to the three required for a fix in itsnormal mode). For most reliable service we recommend using stationarymode if your device has it. GPSD tools don’t yet directly supportthis, but that capability may be added in a future release.

The design of your host system can also affect time quality. The±5uSec error bound quoted above is for a dual-core or bettersystem with clock in the 2GHz range on which the OS can schedule thelong-running PPS thread in GPSD on an otherwise mostly unusedprocessor (the Linux scheduler, in particular, will do this). On asingle-core system, contention with other processes can pileon several additional microseconds of error.

If you are super-serious about your time-nuttery, you may want to lookinto the newest generation of dedicated Stratum 1 microservers beingbuilt out of open-source SBCs like the Raspberry Pi and Beaglebone, orsometimes with fully custom designs. A representative build is welldescribed at[RPI].

These microserver designs avoid load-induced jitter by being fullydedicated to NTP service. They are small, low-powered devices andoften surprisingly inexpensive, as in costing less than US$100. Theytend to favor the LEA-6H, and many of them use preinstalled GPSD onboard.

You can determine whether your GPS receiver emits 1PPS, and gpsd isdetecting it, by running the gpsmon utility (giving it the GPSreceiver’s serial-device path as argument). Watch for lines of dashesmarked 'PPS' in the packet-logging window; for most GPS receiver typesthere will also be a "PPS offset:" field in the data panels aboveshowing the delta between PPS and your local clock.

If you don’t have gpsmon available, or you don’t see PPS lines in it,you can run ppscheck. As a last resort you can gpsd at -D 5 and watchfor PPS state change messages in the logfile.

If you don’t see evidence of incoming PPS, here are some troublesources to check:

1. The skyview of your GPS receiver may be poor. Suspect this if,when you watch it with cgps, it wanders in and out of having agood 3D fix. Unfortunately, the only fix for this is to re-siteyour GPS where it can see more sky; fortunately, this is not ascommon a problem as it used to be, because modern receivers areoften capable of getting a solid fix indoors.

2. If you are using an RS232 cable, examine it suspiciously, ideallywith an RS232 breakout box. Cheap DB9 to DB9 cables such as thoseissued with UPSs often carry TXD/RXD/SG only, omitting handshakelines such as DCD, RI, and DSR that are used to carry 1PPS.Suspect this especially if the cable jacket looks too skinny tohold more than three leads!

3. Verify that your gpsd and kernel were both built with PPS support,as previously described in the section on software prerequisites.

4. Verify that the USB or RS232 device driver is accepting the ioctlthat tells it to wait on a PPS state change from the device. Themessages you hopenot to see look like "KPPS cannot set PPS linediscipline" and "PPS ioctl(TIOCMIWAIT) failed". The formercan probably be corrected by running as root; the latter (whichshould never happen with an RS232 device) probably means your USBdevice driver lacks this wait capability entirely and cannot beused for time service.

5. If you have a solid 3D fix, a known-good cable, your software isproperly configured, the wait ioctl succeeded, but you still get noPPS, then you might have a GPS receiver that fails to deliver PPSoff the chip to the RS232 or USB interface. You get to becomeintimate with datasheets and pinouts, and might need to acquire adifferent GPS receiver.

If you’re going to use gpsd for time service, you must run in -n modeso the clock will be updated even when no clients are active. This optionis forced if you built GPSD with timeservice=yes as an option.

Note that gpsd assumes that after each fix the GPS receiver willassert 1PPS first and ship sentences reporting time of fixsecond (and the sentence burst will end before the next 1PPS). EveryGPS we know of does things in this order. (However, on some very oldGPSes that defaulted to 4800 baud, long sentence bursts — notablythose containing a skyview — could slop over into the next second.)

If you ever encounter an exception, it should manifest as reportedtimes that look like they’re from the future and require a negativefudge. If this ever happens, please report the device make and modelto the GPSD maintainers, so we can flag it in our GPS hardwaredatabase.

There is another possible cause of small negative offsets whichshows up on the GR-601W: implementation bugs in your USB driver,combining with quantization by the USB poll interval. Thisdoesn’t mean the u-blox 6 inside it is actually emitting PPSafter the GPS timestamp is shipped.

In order to present the smallest possible attack surface toprivilege-escalation attempts, gpsd, if run as root, drops its rootprivileges very soon after startup - just after it has opened anyserial device paths passed on the command line.

Thus, KPPS can only be used with devices passed that way, not withGPSes that are later presented to gpsd by the hotplug system. Thosehotplug devices may, however, be able to use plain, non-kernelPPS. gpsd tries to automatically fall back to this when absence ofroot permissions makes KPPS unavailable.

In general, if you start gpsd as other than root, the following thingswill happen that degrade the accuracy of reported time:

1. Devices passed on the command line will be unable to use KPPS andwill fall back to the same plain PPS that all hotplug devices mustuse, increasing the associated error from ~1 uSec to about ~5 uSec.

2. gpsd will be unable to renice itself to a higher priority. Thisaction helps protect it against jitter induced by variable systemload. It’s particularly important if your NTP server is a general-usecomputer that’s also handling mail or web service or development.

3. The way you have to configure ntpd and chrony will change awayfrom what we show you here; ntpd will need to be told differentshared-memory segment numbers, and chronyd will need a differentsocket location.

4. gpsd will be unable to change to user nobody. This means gpsd willparadoxically run with higher privileges than if it was started as root.This increases the attack surface and decreases your security.

You may also find gpsd can’t open serial devices at all if yourOS distribution has done "secure" things with the permissions.

Most Unix systems get their time service through ntpd, a very old andstable open-source software suite which is the referenceimplementation of NTP. The project home page is[NTP.ORG]. Werecommend using NTPsec, a recent fork that is improved andsecurity-hardened[NTPSEC.ORG].

When gpsd receives a sentence with a timestamp, it packages thereceived timestamp with current local time and sends it to ashared-memory segment with an ID known to ntpd, the network timesynchronization daemon. If ntpd has been properly configured toreceive this message, it will be used to correct the system clock.

When in doubt, the preferred method to start your timekeeping is:

where /dev/ttyXX is whatever 1PPS-capable device you have. In abinary-package-based Linux distribution it is probable that ntpdwill already have been launched at boot time.

It’s best to have gpsd start first. That way when ntpd restarts it hasa good local time handy. If ntpd starts first, it will set the localclock using a remote, probably pool, server. Then ntpd has to spend awhole day slowly resyncing the clock.

If you’re using dhcp3-client to configure your system, make sureyou disable /etc/dhcp3/dhclient-exit-hooks.d/ntp, as dhclient wouldrestart ntpd with an automatically created ntp.conf otherwise — andgpsd would not be able to talk with ntpd anymore.

While gpsd may be runnable as non-root, you will get significantlybetter accuracy of time reporting in root mode; the difference, whilealmost certainly insignificant for feeding Stratum 1 time to clientsover the Internet, may matter for PTP service over a LAN. Typicallyonly root can access kernel PPS, whereas in non-root mode you’re limited toplain PPS (if that feature is available). As noted in the previoussection on 1PPS quality issues, this difference has performanceimplications.

The rest of these setup instructions will assume that you are startinggpsd as root, with occasional glances at the non-root case.

Now check to see if gpsd has correctly attached the shared-memorysegments in needs to communicate with ntpd. ntpd’s rules for thecreation of these segments are:

Segments 0 and 1

Permissions are 0600 — other programs can only read andwrite this segment when running as root.

Segments 2, 3 and above

Permissions are 0666 — other programs can read and write as any user. If ntpd has been configured to use these segments, any unprivileged user is allowed to provide data for synchronization.

Because gpsd can be started either as root or non-root, it checks andattaches the more privileged segment pair it can — either 0 and 1 or 2and 3.

For each GPS receiver that gpsd controls, it will use the attached ntpshmsegments in pairs (for coarse clock and pps source, respectively)starting from the first found segments.

To debug, try looking at the live segments this way:

If gpsd was started as root, the results should look like this:

For a bit more data try this:

If gpsd cannot open the segments, check that you are not running SELinuxor apparmor. Either may require you to configure a security exception.

If you see the shared segments (keys 1314148400 — 1314148403), andno gpsd or ntpd is running then try removing them like this:

Here is a minimal sample ntp.conf configuration to work with GPSD runas root, telling ntpd how to read the GPS notifications

The number "0.9999" is a placeholder, to be explained shortly. Itisnot a number to be used in production - it’s too large. If youcan’t replace it with a real value, it would be best to leave out theclause entirely so the entry looks like:

This is equivalent to declaring a time1 of 0.

The pool statement adds a variable number of servers (often 10) asadditional time references needed by ntpd for redundancy and to give youa reference to see how well your local GPS receiver is performing. Ifyou are outside of the USA replace the pool servers with one in yourlocal area. See[USE-POOL] for further information.

The pool statement, and the driftfile and logfile declarations after it,will not be strictly necessary if the default ntp.conf that yourdistribution supplies gives you a working setup. The two pairs ofserver and fudge declarations are the key.

ntpd can be used in Denial of Service (DoS) attacks. To prevent that,but still allow clients to request the local time, be sure the 'restrict'statements are in your ntpd config file. For more information see[CVE-2009-3563].

Users of ntpd versions older than revision ntp-4.2.5p138 should instead usethis ntp.conf, when gpsd is started as root:

Users of ntpd versions prior to ntp-4.2.5 do not have the "pool" option.Alternative configurations exist, but it is recommended that you upgradentpd, if feasible.

The magic pseudo-IP address 127.127.28.0 identifies unit 0 of the ntpdshared-memory driver (NTP0); 127.127.28.1 identifies unit 1 (NTP1).Unit 0 is used for in-band message timestamps and unit 1 for the (moreaccurate, when available) time derived from combining in-band messagetimestamps with the out-of-band PPS synchronization pulse. Splittingthese notifications allows ntpd to use its normal heuristics to weightthem.

Different units — 2 (NTP2) and 3 (NTP3), respectively — must be usedwhen gpsd is not started as root. Some GPS HATs put PPS time on a GPIOpin and will also use unit 2 (NTP2) for the PPS time correction.

With this configuration, ntpd will read the timestamp posted by gpsdevery 64 seconds (16 if non-root) and send it to unit 0.

The number after the parameter time1 (0.9999 in the example above) is a"fudge", offset in seconds. It’s an estimate of the latency betweenthe time source and the 'real' time. You can use it to compensate outsome of the fixed delays in the system. An 0.9999 fudge would beridiculously large.

You may be able to find a value for the fudge by looking at the entryfor your GPS receiver type on[HARDWARE]. Later in this documentwe’ll explain methods for estimating a fudge factor on unknownhardware.

There is nothing magic about the refid fields; they are just labelsused for generating reports. You can name them anything you like.

When you start gpsd, it will wait for a few good fixes before attemptingto process PPS. You should run cgps to verify your GPS receiver has a3D lock before worrying about timekeeping.

After starting (as root) ntpd, then gpsd, a listing similar to the onebelow should appear as the output of the command "ntpq -p" (afterallowing the GPS receiver to acquire a 3D fix). This may take up to30 minutes if your GPS receiver has to cold-start or has a poorskyview.

The line with refid ".GPS." represents the in-band time reports fromyour GPS receiver. When you are getting PPS then it may look likethis:

Note the additional ".PPS." line.

If the value under "reach" for the SHM lines remains zero, check thatgpsd is running; cgps reports a 3D fix; and the '-n' option was used.Some GNSS receivers specialized for time service can report time with signallock on only one satellite, but with most devices a 3D fix isrequired.

When the SHM(0) line does not appear at all, check your ntp.conf andthe system logs for error messages from ntpd.

Notice the 1st and 3rd servers, stratum 1 servers, disagree by more than8 mSec. The 1st and 2nd servers disagree by over 12 mSec. Our localPPS reference agrees to the clock.sjc.he.net server within the expectedjitter of the GR-601W in use.

When no other servers or local reference clocks appear in the NTPconfiguration, the system clock will lock onto the GPS clock, but thisis a fragile setup — you can lose your only time reference if the GPSreceiver is temporarily unable to get satellite lock.

You should always have at least two (preferably four) fallback serversin your ntpd.conf for proper ntpd operation, in case your GPS receiverfails to report time. The 'pool' command makes this happen. Andyou’ll need to adjust the offsets (fudges) in your ntp.conf so theSHM(0) time is consistent with your other servers (and other localreference clocks, if you have any). We’ll describe how to diagnose andtune your server configuration in a later section.

NTP is a cluster protocol. It sorts time sources into clusters, picksthe best cluster, then the best source in that cluster, for its timesource. By default, NTPsec requires 3 "sane" time sources beforeserving time. This is set with theminsane option. Not at allrecommended, but you can forcentpd to rely sole on your PPS source byadjustingminsane like this in your ntp.conf:

Also note that after cold-starting ntpd it may calibrate for up to 15minutes before it starts adjusting the clock. Because the frequencyerror estimate ("drift") that NTP uses isn’t right when you firststart NTP, there will be a phase error that persists while thefrequency is estimated. So if your clock is a little slow, then itwill keep getting behind, and the positive offset will cause NTP toadjust the phase forward and also increase the frequency offset error.After a day or so or maybe less the frequency estimate will be veryclose and there won’t be a persistent offset.

The GPSD developers would like to receive information about theoffsets (fudges) observed by users for each type of receiver. If yourGPS receiver is not present in[HARDWARE], or doesn’t have arecommended fudge, or you see a fudge value very different from what’sthere, send us the output of the "ntpq -p" command and the make andtype of receiver.

chrony is an alternative open-source implementation of NTP service,originally designed for systems with low-bandwidth or intermittentTCP/IP service. It interoperates with ntpd using the same NTPprotocols. Unlike ntpd which is designed to always be connected tomultiple internet time sources, chrony is designed for long periodsof offline use. Like ntpd, it can either operate purely as a clientor provide time service. The chrony project has a home page at[CHRONY]. Its documentation includes an instructive feature comparisonwith ntpd at[CHRONY-COMPARE].

gpsd, when run as root, may feed time information to chronyd usingsockets. The sockets are named /run/chrony.XXXX.sock. Where XXXX isreplaced by the basenames of the device names gpsd is using. If yourreceiver outputs serial data on /dev/ttyS0, then the correspondingsocket is /run/chrony.ttyS0.sock. If your PPS is on /dev/pps0, then thecorresponding socket is /run/chrony.pps0.sock.

Older systems may use the /var/run directory instead of /run. If gpsdcan not open the sockets there, it falls back to try /tmp.

No gpsd configuration is required to talk to chronyd. chronyd isconfigured using the file /etc/chrony.conf or /etc/chrony/chrony.conf.Check your distributions documentation for the correct location.

To get chronyd to connect to gpsd using the socket method add thefollowing lines your chrony.conf file. Except, replace XXXX withthe basename of your device’s serial port, often ttyS0, ttyACM0, orttyAMA0. Replace YYYY with the basename of your PPS device, usuallypps0.

When running as root:

Older systems may use the /var/run directory for the socket file insteadof /run. /run is compliant with FHS 3.0. If that file can not be openedthen gpsd falls back to trying in /tmp:

You can also get gpsd to connect to chronyd using the basic ntpdcompatible SHM method. To use that instead of sockets, add these linesto the basic chrony.conf file:

You need to add the "precision 1e-7" on the SHM 1 line as chronyd failsto read the precision from the SHM structure. Without knowing the highprecision of the PPS on SHM 1 it may not place enough importance on itsdata.

The number "0.9999" is a placeholder as explained in the previoussection about configuringntpd. It isnot a number to be used inproduction - it’s too large. If you can’t replace it with a real value,it would be best to not use the SHM 0 source at all, keeping only theSHM 1 source.

If you are outside of the USA replace the pool servers with one in yourlocal area. See[USE-POOL] for further information.

The offset option is functionally like ntpd’s time1 option, used tocorrect known and constant latency.

The 'allow' option allows anyone on the internet to query your server’stime.

See the chrony.conf man page for more detail on the configuration options[CHRONY-MAN].

Finally note that chronyd needs to be started before gpsd so thesockets are ready before gpsd starts up.

If running as root, the preferred starting procedure is:

After you have verified with cgps that your GPS receiver has a good 3Dlock you can check that gpsd is outputting good time by running ntpshmmon.

If you see only "NTP2", instead, you forgot to go root before starting gpsd.

Once ntpshmmon shows good time data you can see how chrony is doing byrunning 'chronyc sources'. Your output will look like this:

The stratum is as in ntpq. The Poll is how many seconds elapse between samples.The Reach is as in ntpq. LastRx is the time since the last successfulsample. Last sample is the offset and jitter of the source.

To keep chronyd from preferring NMEA time over PPS time, you can add anoverlarge fudge to the NMEA time. Or add the suffix 'noselect' so itis never used, just monitored.

This section is general and can be used with either ntpd or chronyd.We’ll have more to say about tuning techniques for the specificimplementations in later sections.

The clock crystals used in consumer electronics have two properties weare interested in: accuracy and stability.Accuracy is how well themeasured frequency matches the number printed on the can.Stabilityis how well the frequency stays the same even if it isn’t accurate.(Long term aging is a third property that is interesting, but ntpd andchrony both a use a drift history that is relatively short; thus,this is not a significant cause of error.)

Typical specs for oscillator packages are 20, 50, 100 ppm. That includeseverything; initial accuracy, temperature, supply voltage, aging, etc.

With a bit of software, you can correct for the inaccuracy. ntpd andchrony both call itdrift. It just takes some extra low order bitson the arithmetic doing the time calculations. In the simplest case,if you thought you had a 100 MHz crystal, you need to change that tosomething like 100.000324. The use of a PPS signal from gpsdcontributes directly to this measurement.

Note that a low drift contributes to stability, not necessarily accuracy.

The major source of instability is temperature. Ballpark is the driftchanges by 1 PPM per degree C. This means that the drift does not stayconstant, it may vary with a daily and yearly pattern. This is why thevalue of drift the ntpd uses is calculated over a (relatively) short time.

So how do we calculate the drift? The general idea is simple.Measure the time offset every N seconds over a longer window of timeT, plot the graph, and fit a straight line. The slope of that line isthe drift. The units cancel out. Parts-per-million is a handy scale.

How do you turn that hand waving description into code? One easy wayis to set N=2 and pick the right T, then run the answer through alow pass filter. In that context, there are two competing sources oferror. If T is too small, the errors on each individual measurementof the offset time will dominate. If T is too big, the actual driftwill change while you are measuring it. In the middle is a sweetspot. (For an example, see[ADEV-PLOT].)

Both ntpd and chrony use this technique; ntpd also uses a moreesoteric form of estimation called a "PLL/FLL hybrid loop". How T and N arechosen is beyond the scope of this HOWTO and varies by implementationand tuning parameters.

If you turn on the right logging level ("statistics loopstats peerstats"for ntpd, "log measurements tracking" for chronyd), that will recordboth offset, drift, and the polling interval. The ntpd stats are easy tofeed to gnuplot, see the example script in the GPSD contrib directory.The most important value is the offset reported in the 3rd field inloopstats and the last field in tracking.log. With gnuplot you cancompare them (after concatenating the rotated logs):

While your NTP daemon (ntpd or chrony) is adjusting the pollinginterval, it is assuming that the drift is not changing. It getsconfused if your drift changes abruptly, say because you started somebig chunk of work on a machine that’s usually idle and that raises thetemperature.

Your NTP daemon writes out the drift every hour or so. (Less often ifit hasn’t changed much to reduce the workload on flash file systems.)On startup, it reloads the old value.

If you restart the daemon, it should start with a close old driftvalue and quickly converge to the newer slightly different value. Ifyou reboot, expect it to converge to a new/different drift value andthat may take a while depending on how different the basic calibrationfactors are.

ARP is the sound of your server choking

Watch your temperatures

Power saving is not your friend

nohz=off intel_idle.max_cstate=0

nohz=off

This section deals specifically with ntpd. It discusses algorithmsused by the ntpd suite to measure and correct the system time. It is notdirectly applicable to chronyd, although some design considerationsmay be similar.

You can’t optimize what you can’t visualize. The easiest way tovisualize ntpd performance is with ntpviz from[NTPSEC.ORG]. Once youare regularly graphing your server performance it is much easier to seethe results of changes.

NTP performance tuning

pool us.pool.ntp.org iburst

$ ntpq -p remote          refid         st t when poll reach delay offset jitter========================================================================-arthur.testserv 162.23.41.56   2 u 62     64 377  5.835 -1.129   8.921-ntppublic.uzh.c 130.60.159.7   3 u 62     64 377  6.121 -4.102   6.336-smtp.irtech.ch  162.23.41.56   2 u 35     64 377 15.521 -1.677   8.678+time2.ethz.ch   .PPS.          1 u 27     64 377  5.938 -1.713  16.404-callisto.mysnip 192.53.103.104 2 u 53     64 377 49.357 -0.274   5.125-shore.naturalne 122.135.113.81 3 u 22     64 377 14.676 -0.528   2.601-ntp.univ-angers 195.220.94.163 2 u 41     64 377 40.678 -1.847  13.391+SHM(0)          .GPS.          0 l  4     64 377  0.000 34.682   7.952*SHM(1)          .PPS.          0 l  3     64 377  0.000 -2.664   0.457

statsdir /var/log/ntpstats/statistics peerstatsfilegen peerstats file peerstats type day enable

   # mkdir -p /var/log/ntpstats   # chown ntp:ntp /var/log/ntpstats

awk '     /127\.127\.28\.0/ { sum += $5 * 1000; cnt++; }     END { print sum / cnt; }' </var/log/ntpstats/peerstats

server 127.127.28.0 minpoll 4 maxpoll 4 noselectfudge 127.127.28.0 time1 0.420 refid GPS

grep 127.127.28.0 peerstats > peerstats.shm

set term gifset output "fudge.gif"

set term x11

        gnuplot> plot "peerstats.shm" using ($2):($5):($8) with yerrorbars        gnuplot> replot "peerstats.shm" using ($2):($5) with lines

Polling Interval

server 127.127.28.1 minpoll 0 maxpoll 0 prefer

The easiest way to determine the offset with chronyd is probably toconfigure the source whose offset should be measured with the noselectoption and a long poll, let chronyd run for at least 4 hours andobserve the offset reported in the chronyc sourcestats output. If theoffset is unstable, wait longer. For example:

SHM 0 configured as:refclock SHM 0 poll 8 filter 1000 noselect

In this case (Garmin 18x) the offset specified in the config for theSHM 0 source should be around 0.495.

By now if you have a good serial PPS signal your local clock shouldhave jitter on the order of 1 uSec. You do not want the hassle ofplacing a GPS receiver on each of your local computers. So youinstall chrony or ntp on your other hosts and configure them to useyour NTP PPS server as their local server.

With your best setup on a lightly loaded GigE network you find that yourNTP clients have jitter on the order of 150 uSec, or 150 times worsethan your master. Bummer, you want to do much better, so you look tothe Precision Time Protocol[PTP] for help. PTP is also known as IEEE1588.

With PTP you can easily synchronize NTP hosts to 5 uSec with somegeneric NIC hardware and newer Linux kernels. Some of the Ethernetdrivers have been modified to time stamp network packets when sending andreceiving. This is done with the new SO_TIMESTAMPING socket option. Nohardware support is required.

A more recent addition is PTP Hardware Clock (PHC) support. This requireshardware support in the NIC.

Software timestamping is more mature, available on more NICs, and almostas accurate as hardware timestamping. Try it first. This HOWTO willbuild on those results.

One final wrinkle before proceeding with PTP. Ethernet ports havesomething called[EEE] (IEEE 802.3az). Percentage wise EEE can save50% of the Ethernet energy needs. Sadly this is 50% of an already smallenergy usage. Only important in large data centers. EEE can be verydisruptive to timekeeping. Up to almost 1 Sec of errors in offset,wander and jitter. To see if you have EEE enabled, and then turn itoff:

PTP with software timestamping

CONFIG_NETWORK_PHY_TIMESTAMPING=yPTP_1588_CLOCK=y

# ethtool -T eth0 | fgrep SOFTWAREsoftware-transmit     (SOF_TIMESTAMPING_TX_SOFTWARE)software-receive      (SOF_TIMESTAMPING_RX_SOFTWARE)software-system-clock (SOF_TIMESTAMPING_SOFTWARE)

# GPS Serial data reference (NTP0)server 127.127.28.0fudge 127.127.28.0 time1 0.9999 refid GPS# GPS PPS reference (NTP1)server 127.127.28.1 preferfudge 127.127.28.1 refid PPS# local PTP reference (NTP2)server 127.127.28.2fudge 127.127.28.2 refid PTP

refclock SHM 0 refid GPS precision 1e-1 offset 0.9999 delay 0.2refclock SHM 1 refid PPS precision 1e-7refclock SHM 2 refid PTP precision 1e-7

[global]# only syslog every 1024 secondssummary_interval 10# send to chronyd/ntpd using SHM 2clock_servo ntpshmntpshm_segment 2# set our priority high since we have PPSpriority1 10priority2 10[eth0]

# ethtool --set-eee eth0 eee off# ptp4l -S -f /usr/local/etc/ptp4l.conf &

# local PTP reference (NTP0)server 127.127.28.0fudge 127.127.28.0 refid PTP

refclock SHM 0 refid PTP precision 1e-7

[global]# only syslog every 1024 secondssummary_interval 10# send to chronyd/ntpd using SHM 0clock_servo ntpshmntpshm_segment 0[eth0]

# ethtool --set-eee eth0 eee off# ptp4l -S -f /usr/local/etc/ptp4l.conf &

PTP with hardware timestamping

CONFIG_DP83640_PHY=yCONFIG_PTP_1588_CLOCK_PCH=y

# ethtool -T eth0hardware-transmit     (SOF_TIMESTAMPING_TX_HARDWARE)hardware-receive      (SOF_TIMESTAMPING_RX_HARDWARE)all                   (HWTSTAMP_FILTER_ALL)

[global]# only syslog every 1024 secondssummary_interval 10clock_servo linreg[eth0]

# ethtool --set-eee eth0 eee off# ptp4l -H -f /usr/local/etc/ptp4l.conf &# sleep 3# phc2sys -a -r -E ntpshm -m -M 0 &

[NTP-FAQ] has good advice on things to be sure you have done — andare ready to do — before becoming a public server. One detail itdoesn’t mention is that you’ll need to un-firewall UDP port 123. TheNTP protocol does not use TCP, so no need to unblock TCP port 123.

If and when you are ready to go public, see[JOIN-POOL].

Beat Bolli <bbolli@ewanet.ch> wrote much of the section on NTPperformance tuning. Hal Murray <hmurray@megapathdsl.net> wrotemuch of the section on NTP working and performance details.Sanjeev Gupta <ghane0@gmail.com> assisted with editing.Shawn Kohlsmith <skohlsmith@gmail.com> tweaked the Bibliography.Jaap Winius <jwinius@rjsystems.nl> cleaned up some terminology.

The loopstats-based tuning procedure for ntpd was drafted by SanjeevGupta <ghane0@gmail.com>, based on discussions on the GPSD list[GPSD-LIST] in Oct and Nov 2013. Code examples are based on work byAndy Walls <andy@silverblocksystems.net>. A copy of the originalemail can be found at[ANDY-POST]. A thorough review was contributedby Jaap Winius <jwinius@rjsystems.nl>.

• [TIME-INTRO]Introduction to Time Service

• [WIKI-NTP]Network Time Protocol

• [NTP-FAQ]NTP FAQ

• [RFC-2783]RFC 2783

• [RFC-5905]RFC 5905

• [MACX-1]Navisys GR-601W u-blox-6 "Macx-1" USB GPS receiver

• [CHRONY-COMPARE]ntpd (comparison with chrony)

• [CHRONYDEFAULT]https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/thread/JXFOZ2BQW2IBRWZVYCIQ45OR4MXZ2B7H/

• [HARDWARE]Compatible Hardware

• [UBLOX-TIMING]GPS-based timing considerations with u-blox 6 receivers

• [RPI]The Raspberry Pi as a Stratum-1 NTP Server

• [NTP.ORG]Home of the Network Time Protocol project

• [NTPSEC.ORG]Wecome to NTPsec

• [USE-POOL]How do I use pool.ntp.org?

• [CVE-2009-3563]https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2009-3563

• [CHRONY]Chrony Home

• [CHRONY-MAN]https://chrony-project.org/documentation.html

• [ADEV-PLOT]Allan deviation and Averaging

• [ZONES]https://www.pool.ntp.org/zone

• [NTPQ-OUTPUT]ntpq output description

• [JOIN-POOL]How do I join pool.ntp.org?

• [ANDY-POST]Clarifications needed for the time-service HOWTO

• [NTP-MONOPT]NTP Monitoring

• [GPSD-LIST]gpsd-dev Archives

• [PTP]PTP

• [LINUX-PTP]Linux PTP

• [EEE]Energy-Efficient Ethernet

• [LVC]https://www.rjsystems.nl/en/2100-ntpd-garmin-gps-18-lvc-gpsd.php

• [GITLAB-SOURCE]NTPSec source on Gitlab

1.1, Nov 2013

Initial release.

1.2, Aug 2014

Note that NetBSD now has PPS support.

1.3, Aug 2014

Add a note about the GR-601W.

1.4, Dec 2014

Cleaned up Bibliography

2.0, Feb 2015

More about troubleshooting PPS delivery. Folded in SanjeevGupta’s Calibration Howto describing the loopstats-basedprocedure. Added preliminary information on PTP.

2.1 Mar 2015

More on PTP. Added link to Jaap Winius’s page on GPS-18 setup.

2.2 Mar 2015

Detailed explanation of NTP has moved to a new page,Introduction to Time Service.

2.3 Mar 2015

Use the NTP accuracy estimate from RFC 5905.

2.4 Mar 2015

Removed some typos, corrected formatting, and minor changes.A bit more specificity about root vs. non-root.

2.5 Apr 2016

Note the existence of the GR-701W.

2.6 May 2016

New section on GPS time. Note the existence of the GR-801W.Describe the special timeserver build of GPSD. Recommend NTPsec.Add Macx-1 link.Add sections on ARP and temperature problems

2.7 June 2016

Add section on avoiding power saving.

2.8 July 2016

Mention required version of gpsdFix Typos.

2.9 August 2016

Fix typos.

2.10 September 2016

Mention ntpvizRecommend minpoll=maxpoll=0 for PPS refclocksRecommend NTPsec.

2.11 June 2019

Check all links, and update to https where possible

2.12 January 2021

Add Table of Contents. Markup cleanup.

November 2021

Minor cleanup around timeservice=yes.

This file is Copyright 2013 by the GPSD project
SPDX-License-Identifier: BSD-2-clause