= GPSD Time Service HOWTO = Gary E. Miller , Eric S. Raymond v1.0, October 2013 This document is mastered in asciidoc format. If you are reading it in HTML, you can find the original at the GPSD project website. == Introduction == GPSD, NTP and a GPS supplying 1PPS (one pulse-per-second) output can be used to set up a high-quality NTP time server. This HOWTO explains the method and various options you have in setting it up. This document is intended to be a comprehensive guide suitable for people who know little about time service. We encourage others to contribute additions and corrections. This document does not attempt to explain all the intricacies of time service; it is focused on practical advice for one specific deployment case. An overview of the protocols can be found at <>, and the official NTP FAQ <> is probably as gentle an introduction as presently exists. .Units table |==================================================== | nSec | nanoSecond | 1/1,000,000,000 of a second | uSec | microSecond | 1/1,000,000 of a second | mSec | milliSecond | 1/1,000 of a second |==================================================== There are a few important terms we need to define up front. *Latency* is delay from a time measurement until a report on it arrives where it is needed. *Jitter* is short-term variation in latency. *Wobble* is a jitter-like variation that is long compared to typical measurement periods. *Accuracy* is the traceable offset from 'true' time as defined 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 cause of wobble is the effect of daily temperature variations on the oscillators in your equipment. == How NTP Works == NTP (Network Time Protocol) is a set of protocols that attempts to synchronize computer clocks across the Internet - ultimately, Universal Coordinated Time (UTC) as defined by several scale-related atomic clocks run by national standards institutes. NTP Version 4 is defined in <>. NTP service daemons running on each host do clock synchronization in the presence of variable network latency by monitoring those delays in real time and passing around messages that say, essentially, "I received your request at time X, I'm sending the reply at time Y and the propagation delay to my source of time is Z". Each daemon then uses rather complex algorithms that we won't attempt to describe here to digest incoming messages into a composite "NTP time". NTP conditions your system clock by noticing how your system clock time differs from deduced NTP time, then speeding up or slowing down your clock's tick rate until it is synchronized. These tick-rate changes are usually extremely small, much too small for a human or even most software timing loops to ever notice. But large changes are possible. Most computers are just NTP clients. They send NTP requests to a set of servers and use it to adjust the local clock. It is generally expected that NTP clients will have an accuracy (that is, maximum divergence from the master atomic clock) of at most ±100 mSec, possibly less depending upon the quality of your network connection. Some NTP hosts are time *servers*. These are known as "chimers". They respond to NTP clients with time read from high-precision reference clocks (often abbreviated "refclocks") synchronized to national time standards. GPSes, because they distribute a single atomic-clock time basis in a way that is generally accessible, are widely used as refclocks. You will hear time service people speak of "Stratum 0" (the reference clocks) "Stratum 1" (NTP servers directly connected to reference clocks) and "Stratum 2" (servers that get time from Stratum 1). Stratum 3 chimers redistribute time from Stratum 2, and so forth. There are defined higher strata up to 15, but you will probably never see a public chimer higher than Stratum 3 or 4. Ordinary client computers are normally configured to get time from one or more Stratum 2 (or less commonly Stratum 3) servers. However, with GPSD and a suitable GPS device, you can easily condition your clock to higher accuracy than what you get from typical Stratum 2; with a little effort you can do better than you can get from most public Stratum 1 servers. You can then make your high-quality time available to other systems on your network, or even run a public NTP server. Anyone can do this; there is no official authority, and any NTP client may choose to use your host as a chimer by requesting time from it. The time-service network is self-regulating, with NTP daemons constantly pruning statistical outliers so the timebase cannot be accidentally or deliberately compromised. In fact many public and widely-trusted Stratum 1 chimers use GPSes as their Stratum 0, and a significant fraction of those use GPSD in the way we will describe here. == 1PPS quality issues == GPSD is useful for precision time service because it can use the 1PPS pulse delivered by some GPSes to discipline (correct) a local NTP instance. It's tempting to think one could use a GPS for time service just by timestamping the arrival of the first character in the report on each fix and correcting for a relatively small fixed latency composed of fix-processing and RS232 transmission time. Unfortunately, fix reports are often delayed in the receiver and on the link by as much as several hundred mSec, and this delay is not constant. This latency varies (jitters) throughout the day. It may be stable to 10 mSec for hours and then jump by 200mSec. Under these circumstances you can't expect accuracy to UTC much better than 1 second from this method. For example: SiRF receivers, the make currently most popular in consumer-grade GPSes, exhibit a wobble of about 170mSec in the offset between actual top-of-second and the transmission of the first sentence in each reporting cycle. You can see this graphed at <>. To get accurate time, then, the in-band fix report from the GPS needs to be supplemented with an out-of-band signal that has a low and constant latency with respect to the time of of the fix. GPS satellites deliver a top-of-GPS-second notification that is nominally accurate to 50nSec; in capable GPses that becomes the 1PPS signal. 1PPS-capable GPSes use an RS-232 control line to ship the 1PPS edge of second to the host system (usually Carrier Detect or Ring Indicator; GPSD will quietly accept either). Satellite top-of-second loses some accuracy on the way down due mainly to variable delays in the ionosphere; processing overhead in the GPS itself adds a bit more latency, and your local host detecting that pulse adds still more latency and jitter. But it's still often accurate to on the order 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 <>. Plain PPS just references the pulse to the system clock as measured in user space. These have different error budgets. Kernel PPS uses a kernel function to accurately timestamp the status change on the PPS line. Plain PPS has the kernel wake up the PPS thread and then the PPS thread reads the current system clock. As noted in the GPSD code, having the kernel do the time stamp yields lower latency and less jitter. Both methods have accuracy degraded by interrupt-processing latency in the kernel serial layer, but plain PPS incurs additional context-switching overhead that KPPS does not. With KPPS it is very doable to get the system clock stable to ±1 uSec. Otherwise you are lucky to get ±5 uSec, and there will be about 20uSec of jitter. All these figures were observed on plain-vanilla x86 PCS with clock speeds in the 2GHz range. All the previous figures assume you're using PPS delivered over RS232. USB GPSes that deliver 1PPS are rare, but do exist. Notably, there's the Navsys GR601-W. In case this device goes out of production it's worth noting that it's a trivial modification of the stock two-chip-on-a-miniboard commodity-GPS design of engine plus USB-to-serial adapter; the GR601-W wires a uBlox 6 to a Prolific Logic PL23203. To get 1PPS out, just wire the 1PPS pin from the GPS engine to 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 that becomes visible to the host system (and GPSD) the next time the USB device is polled. USB 1.1 polls 1024 slots ever second. Each slot is polled in the same order every second. When a device is added it is assigned to one of those 1024 polling slots. It should then be clear that the accuracy of a USB 1.1 connected GPS would be about 1 mSec. As of late 2013 no USB GPS we know of implements the higher polling-rate options in USB 2 and 3. When one does, and if it has the Macx-1 mod, higher USB accuracy will ensue. .Summary of typical accuracy |======================================= | GPS atomic clock | ±50nSec | KPPS | ±1uSec | PPS | ±5uSec | USB poll interval | ±1mSec | Network NTP time | ±10mSec |======================================= Observed variations from the typical figure increase towards the bottom of the table. Notably, a heavily loaded host system can reduce PPS accuracy, though not KPPS accuracy except in the most extreme cases. The USB poll interval tends to be very stable. Network NTP time accuracy can be degraded below 10mSec by a number of factors. Almost all have more to do with the quality of your Internet connection to your chimers than with the acuracy of the chimers themselves. Some negatives: * Having a cable modem. That is, as opposed to DSL or optical fiber, which tend to have less variable latencies. * Path delay asymmetries due to peering policy. These can confuse NTP's reconciliation algorithms. With these factors in play, worst-case error can reach up to ±100mSec. Fortunately, errors of over ±100mSec are very unusual and should occur only if all your network routes to chimers have serious problems. == Choice of Hardware == To get 1PPS to your NTP daemon, you first need to get it from a PPS-capable GPS. As of late 2013 this means either the previously mentioned GR601-W or a serial GPS with 1PPS. You can find 1PPS-capable devices supported by GPSD at <>. Note that the most popular consumer-grade GPS engine - SiRF - does not deliver 1PPS through USB or even RS232. Thus the usual run of cheap GPS mice won't do. In general, you can't use a USB device for time service unless you know it has the Macx-1 mod. In the past, the RS232 variant of the Garmin GPS-18 has been very commonly used for time service. While it is still a respectable choice, newer devices have better sensitivity and signal discrimination. This makes them superior for indoor use as time sources. In general, use a GPS with an RS232 interface for time service if you can. The GR601-W was designed (by one of the authors, as it happens) for deployment with commodity TCP/IP routers that only have USB ports. RS232 is more fiddly to set up (with older devices like the GPS-18 you may even have to make your own cables) but it can deliver three orders of magnitude better accuracy and repeatability - enough to meet prevailing standards for a public Stratum 1 chimer. Among newer receiver designs we've found the the uBlox 6 receiver used in the GR601-W to be particularly good. Very detailed information on its timing performance can be found at <>. One of us (Raymond) has recent experience with an eval kit, the EVK 6H-0-001, that would make an excellent Stratum 0 device. Both the EVK 6H and GR601-W are built around the LEA-6H module, which is a relatively inexpensive but high-quality navigation GPS. We make a note of this because u-blox also has a specialized timing variant, the LEA 6T, which would be expensive overkill for an NTP server. Unfortunately as of late 2013 the LEA-6H is still hard to find in a packaged RS232 version, as opposed to a bare OEM module exporting TTL levels or an eval kit like the EVK 6H-0-001 costing upwards of US$300. Search the web; you may find a here-today-gone-tomorrow offer on alibaba.com or somewhere similar. The LEA-6T, and some other higher-end GPS receivers (but not the LEA-6H) have a stationary mode which, after you initialize it with the device's location, can deliver time service with only one good satellite lock (as opposed to the three required for a fix in its normal mode). For most reliable service we recommend using stationary mode if your device has it. GPSD tools don't yet directly support this, 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 better system with clock in the 2GHz range on which the OS can schedule the long-running PPS thread in GPSD on an otherwise mostly unused processor (the Linux scheduler, in particular, will do this). On a single-core system, contention with other processes can pile on several additional microseconds of error. If you are super-serious about your time-nuttery, you may want to look into the newest generation of dedicated Stratum 1 microservers being built out of open-source SBCs like the Raspberry Pi and Beaglebone, or sometimes with fully custom designs. A representative build is well described at <>. These microserver designs avoid load-induced jitter by being fully dedicated to NTP service. They are small, low-powered devices and often surprisingly inexpensive, as in costing less than US$100. They tend to favor the LEA-6H, and many of them use preinstalled GPSD on board. == Enabling PPS == gpsd includes support for interpreting the 1PPS pulses; this can be used to update your time at much higher accuracy than message time provides. You can determine whether your GPS emits this pulse, and gpsd is detecting it, by running at -D 5 and watching for carrier-detect state change messages in the logfile. In addition, if your kernel provides the RFC 2783 KPPS (kernel PPS) API gpsd will use that for extra accuracy. Note that gpsd assumes that after each fix the GPS will assert 1PPS first and ship sentences reporting time of fix second. Every GPS we know of does things in this order. If you ever encounter an exception, it should manifest as reported times that look like they're from the future and require a negative fudge. If this ever happens, please report the device make and model to the GPSD maintainers so we can flag it in our GPS hardware database. Many Linux distributions have a package called "pps-tools" that will install KPPS support and the time_pps.h header file. We recommend you do that. If your kernel is built in the normal modular way, this package installation will suffice. If you are scratch-building your Linux kernel, the configuration must include either these two lines, or the same with "y" replaced by "m" to enable the drivers as modules: ----------------------------------------------------------------------------- CONFIG_PPS=y CONFIG_PPS_CLIENT_LDISC=y ----------------------------------------------------------------------------- Your Linux distribution may ship a file "config-xxxx" in the /boot directory, which will have a list of the configuration options that were used to build the kernel. You can check if the above options are set. Usually they will be set to "m", which is sufficient. Other OSes have different ways to enable KPPS in their kernels. When we learn what those are, we'll document them or point at references. If you're going to use gpsd for time service, you must run in -n mode so the clock will be updated even when no JSON clients are active. In order to present the smallest possible attack surface to privilege-escalation attempts, gpsd, if run as root, drops its root privileges very soon after startup - just after it has opened any serial device paths passed on the command line. Thus, KPPS can only be used with devices passed that way, not with GPSes that are later presented to gpsd by the hotplug system. Those hotplug devices may, however, be able to use plain, non-kernel PPS. gpsd tries to automatically fall back to this when absence of root permissions makes KPPS unavailable. In general, if you start gpsd as other than root, the following things will happen that degrade the accuracy of reported time: 1. Devices passed on the command line will be unable to use KPPS and will fall back to the same plain PPS that all hotplug devices must use, increasing the associated error from ~1 uSec to about ~5 uSec. 2. gpsd will be unable to renice itself to a higher priority. This action helps protect it against jitter induced by variable system load. It's particularly important if your NTP server is a general-use computer that's also handling mail or web service or development. 3. The way you have to configure ntpd and chrony will change away from what we show you here; ntpd will need to be told different shared-memory segment numbers, and chronyd will need a different socket location. You may also find gpsd can't open serial devices at all if your OS distribution has done "secure" things with the permissions. == Feeding NTPD from GPSD == Most Unix systems get their time service through ntpd, a very old and stable open-source software suite which is the reference implementation of NTP. The project home page is <>. When gpsd receives a sentence with a timestamp, it packages the received timestamp with current local time and sends it to a shared-memory segment with an ID known to ntpd, the network time synchronization daemon. If ntpd has been properly configured to receive this message, it will be used to correct the system clock. When in doubt, the preferred method to start your timekeeping is: ----------------------------------------------------------------------------- $ su - (or sudo -s ) # killall -9 gpsd ntpd # ntpd -gN # sleep 2 # gpsd -n /dev/ttyXX # sleep 2 # cgps ----------------------------------------------------------------------------- where /dev/ttyXX is whatever 1PPS-capable device you have. In a binary-package-based Linux distribution it is probable that ntpd will already have brrn launched at boot time. The rest of these setup instructions will assume that you are starting gpsd as root, with occasional glances at the non-root case. Now check to see if gpsd has correctly attached the shared-memory segments in needs to communicate with ntpd. ntpd's rules for the creation of these segments are: Segments 0 and 1:: Permissions are 0600 - other programs can only read and write this segment when running as root. Segments 2 and 3:: 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 synchronisation. Because gpsd can be started either as root or non-root, it checks and attaches the more privileged segment pair it can - either 0 and 1 or 2 and 3. For each GPS receiver that gpsd controls, it will use the attached ntpshm segments 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 ----------------------------------------------------------------------------- ipcs -m ----------------------------------------------------------------------------- If gpsd was started as root, the results should look like this: ----------------------------------------------------------------------------- ------ Shared Memory Segments -------- key shmid owner perms bytes nattch status 0x4e545030 0 root 700 96 2 0x4e545031 32769 root 700 96 2 0x4e545032 163842 root 666 96 1 0x4e545033 196611 root 666 96 1 ----------------------------------------------------------------------------- For a bit more data try this: ----------------------------------------------------------------------------- cat /proc/sysvipc/shm ----------------------------------------------------------------------------- If gpsd cannot open the segments, check that you are not running SELinux or apparmor. Either may require you to configure a security exception. If you see the shared segments (keys 1314148400 -- 1314148403), and no gpsd or ntpd is running then try removing them like this: ----------------------------------------------------------------------------- ipcrm -M 0x4e545030 ipcrm -M 0x4e545031 ipcrm -M 0x4e545032 ipcrm -M 0x4e545033 ----------------------------------------------------------------------------- Here is a minimal sample ntp.conf configuration telling ntpd how to read the GPS notifications, when gpsd is started as root: ----------------------------------------------------------------------------- pool us.pool.ntp.org iburst driftfile /var/lib/ntp/ntp.drift logfile /var/log/ntp.log # GPS Serial data reference server 127.127.28.0 fudge 127.127.28.0 time1 0.420 refid GPS # GPS PPS reference server 127.127.28.1 prefer fudge 127.127.28.1 refid PPS ----------------------------------------------------------------------------- The pool statement adds 4 chimers as additional time references needed by ntpd for redundancy and to give you a reference to see how well your local GPS is performing. If you are outside of the USA replace the pool servers with one in your local area. See <> for further information. Users of ntpd versions older than revision ntp-4.2.5p138 should instead use this ntp.conf, when gpsd is started as root: ----------------------------------------------------------------------------- pool us.pool.ntp.org iburst driftfile /var/lib/ntp/ntp.drift logfile /var/log/ntp.log # GPS Serial data reference server 127.127.28.0 minpoll 4 maxpoll 4 fudge 127.127.28.0 time1 0.420 refid GPS # GPS PPS reference server 127.127.28.1 minpoll 4 maxpoll 4 prefer fudge 127.127.28.1 refid PPS ----------------------------------------------------------------------------- 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 upgrade ntpd, if feasible. The magic pseudo-IP address 127.127.28.0 identifies unit 0 of the ntpd shared-memory driver; 127.127.28.1 identifies unit 1. Unit 0 is used for message-decoded time and unit 1 for the (more accurate, when available) time derived from combining message-decoded time with the PPS synchronization pulse. Splitting these notifications allows ntpd to use its normal heuristics to weight them. (Different units - 2 and 3, respectively - must be used when gpsd is not started as root.) With this configuration, ntpd will read the timestamp posted by gpsd every 64 seconds (16 if non-root) and send it to unit 0. The number after the parameter time1 (0.420 in the example above) is a "fudge", offset in seconds. It's an estimate of the latency between the time source and the 'real' time. You can use it to adjust out some of the fixed delays in the system. To keep ntpd from preferring NMEA time over PPS time, you can add an overlarge fudge to the NMEA time. Or add the suffix 'noselect' so it is never used, just monitored. When you start gpsd, it will wait for a few good fixes before attempting to process PPS. You may run 'cgps' to verify your GPS has a 3D lock before worrying about timekeeping. After starting (as root) ntpd, then gpsd, a listing similar to the one below should appear as the output of the command "ntpq -p" (after allowing the GPS to acquire a 3D fix). This may take up to 30 minutes if your GPS has to cold start or has a poor skyview. ----------------------------------------------------------------------------- remote refid st t when poll reach delay offset jitter ============================================================================== xtime-a.timefreq .ACTS. 1 u 40 64 377 59.228 -8.503 0.516 -bonehed.lcs.mit 18.26.4.106 2 u 44 64 377 84.259 4.194 0.503 +clock.sjc.he.ne .CDMA. 1 u 41 64 377 23.634 -0.518 0.465 +SHM(0) .GPS. 0 l 50 64 377 0.000 6.631 5.331 ----------------------------------------------------------------------------- If you are running PPS then it may look like this: ----------------------------------------------------------------------------- remote refid st t when poll reach delay offset jitter ============================================================================== xtime-a.timefreq .ACTS. 1 u 40 64 377 59.228 -8.503 0.516 -bonehed.lcs.mit 18.26.4.106 2 u 44 64 377 84.259 4.194 0.503 +clock.sjc.he.ne .CDMA. 1 u 41 64 377 23.634 -0.518 0.465 +SHM(0) .GPS. 0 l 50 64 377 0.000 6.631 5.331 *SHM(1) .PPS. 0 l 49 64 377 0.000 0.222 0.310 ----------------------------------------------------------------------------- If the value under "reach" for the SHM lines remains zero, check that gpsd is running; cgps reports a 3D fix; and the '-n' option was used. Some GPSes specialized for time service can report time with signal lock on only one satellite, but with most devices a 3D fix is required. When the SHM(0) line does not appear at all, check your ntp.conf and the system logs for error messages from ntpd. Notice the 1st and 3rd servers, stratum 1 servers, disagree by more than 8 mSec. The 1st and 2nd servers disagree by over 12 mSec. Our local PPS reference agrees to the clock.sjc.he.net server within the expected jitter of the GR-601W in use. When no other chimers or local reference clocks appear in the NTP configuration, the system clock will lock onto the GPS clock, but this is a fragile setup - you can lose your only time reference if the GPS is temporarily unable to get satellite lock. You should always have at least two (preferably four) fallback chimers in your ntpd.conf for proper ntpd operation, in case your GPS fails to report time. The 'pool' command makes this happen. And you'll need to adjust the offsets (fudges) in your ntp.conf so the SHM(0) time is consistent with your other chimers (and other local reference clocks, if you have any). We'll describe how to diagnose and tune your chimer configuration in a later section. The gpsd developers would like to receive information about the offsets (fudges) observed by users for each type of receiver. Please check the GPS hardware table at <>; if your GPS is not present or doesn't have a recommended fudge, send us the output of the "ntpq -p" command and the make and type of receiver. == Feeding chrony from GPSD == chrony is an alternative open-source implementation of NTP service, originally designed for systems with low-bandwidth or intermittent TCP/IP service. It interoperates with ntpd using the same NTP protocols. Unlike ntpd which is designed to always be connected to multiple internet time sources, chrony is designed for long periods of offline use. Like ntpd, it can either operate purely as a client or provide time service. The chrony project has a home page at <>. Its documentation includes an instructive feature comparison with ntpd at <>. gpsd can provide reference clock information to chronyd similarly to the way it talks to ntpd. The advantage to using chrony is that the PPS time resolution is in nanoseconds. This is 1,000 times more precision than the microsecond time resolution provided to ntpd. This only matters if you has an RS-232 connected 1PPS refclock. When gpsd supports the new ntpd protocol this difference will disappear. gpsd, when run as root, talks to chronyd using a socket named /var/run/chrony.ttyXX.sock (where ttyXX is replaced by the GPS device name. This allows multiple GPS to feed one chronyd. No gpsd configuration is required to talk to chronyd. chronyd is configured 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 basic ntpd compatible SHM method add this to use this basic chrony.conf file: ----------------------------------------------------------------------------- server 0.us.pool.ntp.org server 1.us.pool.ntp.org server 2.us.pool.ntp.org server 3.us.pool.ntp.org driftfile /etc/chrony/chrony.drift # delay 0.0 is right, but use 0.2 to avoid NMEA # time fighting with PPS time # or use noprefer and a good offset refclock SHM 0 offset 0.0 delay 0.2 refclock SHM 1 offset 0.0 delay 0.0 prefer ----------------------------------------------------------------------------- If you are outside of the USA replace the pool servers with one in your local area. See <> for further information. The offset option is functionally like ntpd's time1 option, used to correct known and constant latency. To get chronyd to connect to gpsd using the more precise socket method add this to your chrony.conf file (replacing ttyXX with your device name). If running as root: ----------------------------------------------------------------------------- server 0.us.pool.ntp.org server 1.us.pool.ntp.org server 2.us.pool.ntp.org server 3.us.pool.ntp.org driftfile /etc/chrony/chrony.drift # delay 0.0 is right, but use 0.2 to avoid NMEA # time fighting with PPS time # or use noprefer and a good offset refclock SHM 0 offset 0.0 delay 0.2 refclock SHM 1 offset 0.0 delay 0.0 noprefer #refclock PPS refclock SOCK /var/run/chrony.ttyXX.sock prefer ----------------------------------------------------------------------------- If not running as root change the "refclock SOCK" line to: ----------------------------------------------------------------------------- refclock SOCK /tmp/chrony.ttyXX.sock prefer ----------------------------------------------------------------------------- Finally note that chronyd needs to be started before gpsd so the socket is ready when gpsd starts up. If running as root, the preferred starting procedure is: ----------------------------------------------------------------------------- $ su - (or sudo -s ) # killall -9 gpsd chronyd # chrony -f /etc/chrony/chrony.conf -s -r # sleep 2 # gpsd -n /dev/ttyXX # sleep 2 # cgps ----------------------------------------------------------------------------- After you have verified with cgps that your GPS has a good 3D lock you can check how chrony is doing by running 'chronyc sources'. Your output will look like this: ----------------------------------------------------------------------------- # chronyc sources 210 Number of sources = 7 MS Name/IP address Stratum Poll Reach LastRx Last sample =============================================================================== #* SHM0 0 4 377 22 -1646us[-3345us] +/- 100ms #? SHM1 0 4 377 19 -126ms[ -126ms] +/- 67us #? SOC2 0 4 0 10y +0ns[ +0ns] +/- 0ns ^? vimo.dorui.net 3 6 377 23 -123ms[ -125ms] +/- 71ms ^? time.gac.edu 2 6 377 24 -127ms[ -128ms] +/- 55ms ^? 2001:470:1:24f::2:3 2 6 377 24 -122ms[ -124ms] +/- 44ms ^? 142.54.181.202 2 6 377 22 -126ms[ -128ms] +/- 73ms ----------------------------------------------------------------------------- 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 successful sample. Last sample is the offset and jitter of the source. To keep chronyd from preferring NMEA time over PPS time, you can add an overlarge fudge to the NMEA time. Or add the suffix 'noselect' so it is never used, just monitored. == NTP performance tuning == For good time stability, you should always have at least four other chimers in your ntpd or chrony configuration besides your GPS - in case, for example, your GPS is temporarily unable to achieve satellite lock, or has an attack of temporarity insanity. You can find public NTP chimers to add to your configuration at <>. To minimize latency variations, use the national and regional pool domains for your country and/or nearby ones. Your ntp.conf configuration line should probably look like this ----------------------------------------------------------------------------- pool us.pool.ntp.org iburst ----------------------------------------------------------------------------- where "us" may be replaced by one of the zone/country codes the Pool project supports (list behind the "Global" link at <>). The "pool" tag expands to four randomly chosen servers by default. "iburst" implements a fast start algorithm that also weeds out bad servers. Note that a chimer can be a poor performer for either of three reasons. It may be shipping bad time, or the best routes between you and it have large latency variations (jitter), or it may have an asymetric route, confusing NTP. The standard tool for tuning ntpd is "ntpq" ("NTP query program"). To show a list of all servers declared in ntp.conf and their statistics, invoke it with the "-p" option. On a sample system configured with 7 servers from the NTP pool project and one PPS GPS attached via RS232, this is the output: ------------------------------------------------------------------------ $ 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 ------------------------------------------------------------------------ The interesting columns are "remote", "st", "reach" and "offset". "remote" is the name of the remote NTP server. The character in its first column shows its current state: "-" or "x" for out-of-tolerance servers, "+" for good servers ("truechimers"), and "*" for the one good server currently used as the primary reference. The calculations used to determine a server's state are outside the scope of this document; details are available in NTPv4 RFC 5905. "st" shows the remote server's stratum. "reach" is the octal representation of the remote server's reachability. A bit is set if the corresponding poll of the server was successful, i.e. the server returned a reply. New poll results are shifted in from the least significant bit; results older than 8 polls are discarded. In the absence of network problems, this should show "377". "offset" shows the mean offset in the times reported between this local host and the remote server in milliseconds. This is the value that can be fudged with the "time1" parameter of the GPS server line in ntp.conf. If the offset is positive, reduce the time1 value and vice versa. A more detailed description of the output is available at <>. In order to determine the correct GPS offset, do the following: [start=1] 1. Add these lines to ntp.conf: ----------------------------------------------------------------------------- statsdir /var/log/ntpstats/ statistics peerstats filegen peerstats file peerstats type day enable ----------------------------------------------------------------------------- Or, if you are running chronyd add these to chrony.conf: ----------------------------------------------------------------------------- logdir /var/log/chrony log statistics measurements tracking ----------------------------------------------------------------------------- This enables logging of the peer server statistics. [start=2] 2. Make sure the directory exists properly. For ntpd as root do: ----------------------------------------------------------------------------- # mkdir -p /var/log/ntpstats # chown ntp:ntp /var/log/ntpstats ----------------------------------------------------------------------------- For chronyd as root do: ----------------------------------------------------------------------------- # mkdir -p /var/log/chrony # chown root:root /var/log/chrony ----------------------------------------------------------------------------- [start=3] 3. Start ntpd (or chronyd) and let it run for at least four hours. Periodically check progress with "ntpq -p" or "chronyc sources" and wait until change has settled out. [start=4] 4. Calculate the average GPS offset using this script (a copy is included as contrib/ntpoffset in the GPSD distribution): ----------------------------------------------------------------------------- awk ' /127\.127\.28\.0/ { sum += $5 * 1000; cnt++; } END { print sum / cnt; } ' > has good advice on things to be sure you have done - and are ready to do - before becoming a public chimer. One detail it doesn't mention is that you'll need to un-firewall UDP port 123. If and when you are ready to go public, see <>. == Acknowledgments == Beat Bolli wrote much of the section on NTP performance tuning. == References == [bibliography] - [[[WIKI-NTP]]] http://en.wikipedia.org/wiki/Network_Time_Protocol[Network Time Protocol] - [[[NTP-FAQ]]] http://www.ntp.org/ntpfaq/[NTP FAQ] - [[[RFC-5905] http://www.ietf.org/rfc/rfc5905.txt[Network Time Protocol Version 4: Protocol and Algorithms Specification] - [[[HARDWARE]]] http://catb.org/gpsd/hardware.html[Compatible Hardware] - [[UBLOX-TIMING]] http://www.u-blox.com/images/downloads/Product_Docs/Timing_AppNote_%28GPS.G6-X-11007%29.pdf[GPS-based timing considerations with u-blox 6 receivers] - [[[RPI]]] http://www.satsignal.eu/ntp/Raspberry-Pi-NTP.html[The Raspberry Pi as a Stratum-1 NTP Server] - [[[NTP.ORG]]] http://www.ntp.org/[Home of the Network Time Protocol project] - [[[USE-POOL]]] http://www.pool.ntp.org/en/use.html[How do I use pool.ntp.org?] - [[[JOIN-POOL]]] http://www.pool.ntp.org/en/join.html[How do I join pool.ntp.org?] - [[[CHRONY]]] http://chrony.tuxfamily.org/[Chrony Home] - [[[CHRONY-COMPARE]]] http://chrony.tuxfamily.org/manual.html#Comparison-with-ntpd[ntpd (comparison with chrony)] - [[[NTPQ-OUTPUT]]] http://nlug.ml1.co.uk/2012/01/ntpq-p-output/831[ntpq output description] - [[[SIRF-WOBBLE]]] http://www.megapathdsl.net/~hmurray/ntp/GPSSiRF-off.gif[Peer Offset of SiRF units] - [[[ZONES]]] http://www.pool.ntp.org/zone