<body>
<h3>Autokey Public-Key Authentication</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->01-Jan-2011 2:41<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->15-Jan-2011 21:26<!-- #EndDate -->
UTC</p>
<hr>
<h4>Table of Contents</h4>
<p> Optional identity schemes described on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page are based on cryptographic challenge/response exchanges. Optional identity schemes provide strong security against masquerade and most forms of clogging attacks. These schemes are exceptionally difficult to cryptanalyze, as the challenge/response exchange data are used only once. They are described along with an executive summary, current status, briefing slides and reading list on the <a href="http://www.eecis.udel.edu/~mills/autokey.html">Autonomous Authentication</a> page.</p>
<p>Autokey authenticates individual packets using cookies bound to the IP source and destination addresses. The cookies must have the same IP addresses at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers and clients are operated outside firewall perimeters.</p>
<p>Autokey is designed to authenticate servers to clients, not the other way around as in SSH. An Autokey server can support an authentication scheme such as the Trusted Certificate (TC) scheme described in RFC 5905, while a client is free to choose between the various options. It is important to understand that these provisions are optional and that selection of which option is at the discretion of the client. If the client does not require authentication, it is free to ignore it, even if some other client of the same server elects to participate in either symmetric key or public key cryptography.</p>
-<p> Autokey uses industry standard X.509 public certificates, which can be produced by commercial services, utility programs in the OpenSSL software library, and the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program in the NTP software distribution. A certificate includes the subject name of the client, the issuer name of the server, the public key of the server and the time period over which the the server public and private keys are valid. All Autokey hosts have a self-signed certificate with the Autokey name as both the subject and issuer. During the protocol, additional certificates are produced with the Autokey host name as subject and the host that signs the certificate as issuer.</p>
-<p>There are two timeouts associated with the Autokey scheme. The <em>key list timeout</em> is set by the <tt>automax</tt> command, which specifies the interval between generating new key lists by the client. The default timeout of about 1.1 hr is appropriate for the majority of configurations and ordinarily should not be changed. The <em>revoke timeout</em> is set by the <tt>revoke</tt> command, which specifies the interval between generating new server private values. It is intended to reduce the vulnerability to cryptanalysis; however, new values require the server to encrypt each client cookie separately. The default timeout of about 36 hr is appropriate for most servers, but might be too short for national time servers.</p>
+<p> Autokey uses industry standard X.509 public certificates, which can be produced by commercial services, utility programs in the OpenSSL software library, and the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program in the NTP software distribution. A certificate includes the subject name of the client, the issuer name of the server, the public key of the client and the time period over which the the public and private keys are valid. All Autokey hosts have a self-signed certificate with the Autokey name as both the subject and issuer. During the protocol, additional certificates are produced with the Autokey host name as subject and the host that signs the certificate as issuer.</p>
+<p>There are two timeouts associated with the Autokey scheme. The <em>key list timeout</em> is set by the <tt>automax</tt> command, which specifies the interval between generating new key lists by the client or server. The default timeout of about 1.1 hr is appropriate for the majority of configurations and ordinarily should not be changed. The <em>revoke timeout</em> is set by the <tt>revoke</tt> command, which specifies the interval between generating new server private values. It is intended to reduce the vulnerability to cryptanalysis; however, new values require the server to encrypt each client cookie separately. The default timeout of about 36 hr is appropriate for most servers, but might be too short for national time servers.</p>
<h4 id="cert">Autokey Subnets</h4>
-<p> An Autokey subnet consists of a collection of hosts configured as an acyclic, directed tree with roots one or more trusted hosts (THs) operating at the lowest stratum of the subnet. Note that the requirement that the NTP subnet be acyclic means that, if hosts are configured with each other in symmetric modes, each must be a TH. The THs are synchronized directly or indirectly to national time services via trusted means, such as radio, satellite or telephone modem, or one or more trusted agents (TAs) of a parent subnet. NTP subnets can be nested, with the THs of a child subnet configured for one or more TAs of the parent subnet. The TAs can serve one or more child subnets, each with its own security policy and set of THs.</p>
+<p> An Autokey subnet consists of a collection of hosts configured as an acyclic, directed tree with roots one or more trusted hosts (THs) operating at the lowest stratum of the subnet. Note that the requirement that the NTP subnet be acyclic means that, if two hosts are configured with each other in symmetric modes, each must be a TH. The THs are synchronized directly or indirectly to national time services via trusted means, such as radio, satellite or telephone modem, or one or more trusted agents (TAs) of a parent subnet. NTP subnets can be nested, with the THs of a child subnet configured for one or more TAs of a parent subnet. The TAs can serve one or more child subnets, each with its own security policy and set of THs.</p>
<p>A certificate trail is a sequence of certificates, each signed by a host one step closer to the THs and terminating at the self-signed certificate of a TH. The requirement that the subnet be acyclic means certificate trails can never loop. NTP servers operate as certificate authorities (CAs) to sign certificates provided by their clients. The CAs include the TAs of the parent subnet and those subnet servers with dependent clients.</p>
<p> In order for the signature to succeed, the client certificate valid period must begin within the valid period of the server certificate. If the server period begins later than the client period, the client certificate has expired; if the client period begins later than the server period, the server certificate has expired.</p>
-<p>The Autokey protocol runs for each association separately; but, while the certificate trail authenticates each host on the trail to the THs, it does not validate the time values themselves. Ultimately, this is determined by the NTP on-wire protocol. During the protocol, the client recursively obtains the certificates on the trail to a TH, saving each in a cache ordered from most recent to oldest. If an expired certificate is found, it is invalidated and marked for later replacement. As the client certificate itself is not involved in the certificate trail, it can only be declared valid or expired when the server signs it. </p>
+<p>The Autokey protocol runs for each association separately, During the protocol, the client recursively obtains the certificates on the trail to a TH, saving each in a cache ordered from most recent to oldest. If an expired certificate is found, it is invalidated and marked for later replacement. As the client certificate itself is not involved in the certificate trail, it can only be declared valid or expired when the server signs it. </p>
<p>The certificates derived from each association are combined in the cache with duplicates suppressed. If it happens that two different associations contribute certificates to the cache, a certificate on the trail from one association could expire before any on another trail. In this case the remaining trails will survive until the expired certificate is replaced. Once saved in the cache, a certificate remains valid until it expires or is replaced by a new one.</p>
<p> It is important to note that the certificate trail is validated only at startup when an association is mobilized. Once validated in this way, the server remains valid until it is demobilized, even if certificates on the trail to the THs expire. While the certificate trail authenticates each host on the trail to the THs, it does not validate the time values themselves. Ultimately, this is determined by the NTP on-wire protocol.</p>
<p>Example</p>
</div>
<p>Figure 1 shows an example configuration with three NTP subnets, Alice, Helen and Carol. Alice and Helen are parent groups for Carol with TA C belonging to Alice and TA S belonging to Helen. Hosts A and B are THs of Alice, host R is the TH of Helen and host X is the TH of Carol. Assume that all associations are client/server, child subnet TH X has two mobilized associations, one to Alice TA host C and the other to Carol TA host S. While not shown in the figure, Alice hosts A and B could configure symmetric mode associations between them for redundancy and backup.</p>
<p>Note that host D certificate trail is D→C→A or D→C→B, depending on the particular order the trails are built. Host Y certificate trail is only Y→X, since X is a TH. Host X has two certificate trails X→C→A or X→C→B, and X→S→R.</p>
+<h4 ident="names">Subnet Group Names</h4>
+<p>In some configurations where more than one subnet shares an Ethernet or when multiple subnets exist in a manycast or pool configuration, it is useful to isolate one subnet from another. In Autokey this can be done using subnet group names. An Autokey host name is specified by the <tt>-s</tt> option of the <tt>ntp-keygen</tt> program using the syntax <tt><em>host</em>@<em>group</em></tt>, where <em><tt>host</tt></em> is the host name and <em><tt>group</tt></em> is the optional subnet group name. If <em><tt>host</tt></em> is omitted, the host name defaults to the string returned by the Unix <tt>gethostname()</tt> routine. Thus, for host <tt>beauregard.udel.edu</tt> the option <tt>-s @red</tt> specifies the Autokey host name <tt>beauegard.udel.edu@red</tt>.</p>
+<p>A subnet host with a given group name will discard ASSOC packets from all subnets with a different group name. This effectively disables the Autokey protocol without additional packet overhead. For instance, one or more manycast or pool servers will not respond to ASSOC packets from subnets with difference group names. Groups sharing an Ethernet will be filtered in the same way.</p>
+<p>However, as shown in Figure 1, there are configurations where a TH of one group needs to listen to a TA of a different group. This is accomplished using the <tt>ident</tt> option of the <tt>crypto</tt> command and/or the <tt>ident</tt> option of the <tt>server</tt> command. The former case applies to all hosts sharing a common broadcast, manycast or symmetric passive modes, while the latter case applies to each individual client/server or symmetric active mode association. In either case the host listens to the specified group name in addition to the group name specified in the <tt>-s</tt> option of the <tt>ntp-keygen</tt> program.</p>
<h4 id="group">NTP Secure Groups</h4>
<p>NTP security groups are an extension of the NTP subnets described in the previous section. They include in addition to certificate trails one or another identity schemes described on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page. NTP secure groups are used to define cryptographic compartments and security
hierarchies. The identity scheme insures that the server is authentic and not victim of masquerade by an intruder acting as a middleman.</p>
key message digest algorithm. If compliance with FIPS 140-2 is required,
the algorithm must be ether <tt>SHA</tt> or <tt>SHA1</tt>. The Autokey message digest algorithm must be the same for all participants in the NTP subnet.</p>
<p>Example</p>
-<p>Returning to the example of Figure 1, Alice, Helen and Carol run TC, internally, as the environment is secure and without threat from external attack, in particular a middleman masquerade. However, TH X of Carol is vulnerable to masquerade on the links between X and C and between X and S. Therefore, both parent subnet TAs C and S are run an identity exchange with child group TH X. Both have the same encrlypted keys file and X the common plarameters file.</p>
+<p>Returning to the example of Figure 1, Alice, Helen and Carol run TC, internally, as the environment is secure and without threat from external attack, in particular a middleman masquerade. However, TH X of Carol is vulnerable to masquerade on the links between X and C and between X and S. Therefore, both parent subnet TAs C and S run an identity exchange with child group TH X. Both have the same encrypted keys file and X the common parameters file.</p>
<h4 id="config2">Configuration - Authentication Schemes</h4>
<p>Autokey has an intimidating number of options, most of which are not necessary in typical scenarios. However, the Trusted Certificate (TC) scheme is recommended for national NTP time services, such as those operated by NIST and USNO. Configuration for TC is very simple. For each server, e.g. <tt>time.nist.gov,</tt> as root:</p>
<p><tt># cd /usr/local/etc<br>
<p>It is possible to configure clients of server <tt>grundoon.udel.edu</tt> in the same way with the server line pointing to <tt>grundoon.udel.edu</tt>. Dependent clients authenticate to <tt>time.nistg.gov</tt> through <tt>grundoon.udel.edu</tt>.</p>
<p>In the above configuration examples, the default Autokey host name is the string returned by the Unix <tt>gethostname()</tt> library routine. However, this name has nothing to do with the DNS name of the host. The Autokey host name is used as the subject and issuer names on the certificate, as well as the default password for the encrypted keys files. The Autokey host name can be changed using the <tt>-s</tt> option of the <tt>ntp-keygen</tt> program. The default password can be changed using the <tt>-p</tt> option of the <tt>ntp-keygen</tt> program and the <tt>pw</tt> option of the <tt>crypto</tt> command.</p>
<h4 id="ident">Configuration - Identity Schemes</h4>
-<p> The example in this section uses the IFF identity scheme, but others, including GQ and MV, can be used as well. A parent subnet TA generates IFF tidentity files using an <tt>ntp-keygen </tt> program command with options specified in this section, while the child secure group TH uses the same program command with no options. Both the TA and TH use the <tt>crypto</tt> command with no options. In addition, the TH specifies options for the <tt>server</tt> and <tt>ident</tt> commands as described in this section. </p>
+<p> The example in this section uses the IFF identity scheme, but others, including GQ and MV, can be used as well. A parent subnet TA generates IFF identity files using an <tt>ntp-keygen </tt> program command with options specified in this section, while the child secure group TH uses the same program command with no options. Both the TA and TH use the <tt>crypto</tt> command with no options. In addition, the TH specifies options for the <tt>server</tt> and <tt>ident</tt> commands as described in this section. </p>
<p> It's best to start with a functioning TC configuration and add commands as necessary. For example, the TA generates an encrypted server keys file and nonencrypted client parameters file for the IFF identity scheme using the command</p>
<p><tt>ntp-keygen -I</tt>.</p>
<p> Note the TA is not necessarily a trusted host, so may not need the <tt>-T</tt> option. The nonencrypted client parameters can be exported using the command</p>
<p><tt>ntp-keygen -e ><i>file</i></tt>,</p>
<p>where the <tt>-e</tt> option redirects the client parameters to <em><tt>file</tt></em> via the standard output stream for a mail application or stored locally for later distribution to one or more THs. In a similar fashion the encrypted keys file can be exported using the command </p>
<p><tt>ntp-keygen -q <em>passw2</em> ><i>file</i></tt>,</p>
-<p>where <em><tt>passwd2</tt></em> is the read password for another TH. While the file name used for the client parameters file is arbitrary, it is common practice to use a mnemonic group name like <tt>red</tt>. On the other hand, the file name used for the keys file must follow the conventions desdribed on the <tt>ntp-keygen</tt> page. The encrypted server keys file is exported to other TAs that may serve the secure group, while the nonencrypted client parameters file can be distributed to all THs by nonsecure means.</p>
-<p>To complete the configuration, the TH includes the client parameters file name as the <tt>ident</tt> option of the the <tt>server</tt> command for the TA assocition</p>
+<p>where <em><tt>passwd2</tt></em> is the read password for another TH. While the file name used for the client parameters file is arbitrary, it is common practice to use the subnet group name as described above, such as <tt>red</tt>. On the other hand, the file name used for the keys file must follow the conventions described on the <tt>ntp-keygen</tt> page. The encrypted server keys file is exported to other TAs that may serve the secure group, while the nonencrypted client parameters file can be distributed to all THs by nonsecure means.</p>
+<p>To complete the configuration, the TH includes the client parameters file name as the <tt>ident</tt> option of the the <tt>server</tt> command for the TA association</p>
<p><tt>server 1.2.3.4 ident <em>group</em>,</tt></p>
-<p> where <em><tt>group</tt></em> is the chosen group name, in this case <tt>red</tt>. In addtion, if operating as a broadcast/multicast client or a symmmetric passive peer, the TH includes an <tt>ident</tt> command</p>
+<p> where <em><tt>group</tt></em> is the chosen group name, in this case <tt>red</tt>. In addition, if operating as a broadcast/multicast client or a symmetric passive peer, the TH includes an <tt>ident</tt> command</p>
<p><tt>ident <em>group</em>,</tt></p>
<p>where <em><tt>group</tt></em> is the chosen group name, in this case <tt>red</tt>.</p>
<h4 id="ident2">Identity Schemes and Cryptotypes</h4>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"><title>Generic NMEA GPS Receiver</title>
+
+ <link href="driver20_files/a" type="text/css" rel="stylesheet">
+
+ <style type="text/css">
+ table.dlstable { font-size:85%; }
+ td.ttf{ font-family:Courier; font-weight:bold; }
+ </style></head>
-<html>
-
- <head>
- <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
- <title>Generic NMEA GPS Receiver</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Generic NMEA GPS Receiver</h3>
- <hr>
- <h4>Synopsis</h4>
- <p>Address: 127.127.20.<i>u</i><br>
- Reference ID: <tt>GPS</tt><br>
- Driver ID: <tt>GPS_NMEA</tt><br>
- Serial Port: <tt>/dev/gps<i>u</i></tt>; 4800 - 115200 bps, 8-bits, no parity<br>
- Serial Port: <tt>/dev/gpspps<i>u</i></tt>; for just the PPS signal (this is tried first for PPS, before <tt>/dev/gps<i>u</i></tt>)<br>
- Serial Port: <tt>/dev/gps<i>u</i></tt>; symlink to server:port (for nmead) Features: <tt>tty_clk</tt></p>
- <h4>Description</h4>
- <p>This driver supports GPS receivers with the <tt>$GPRMC, $GPGLL, $GPGGA, $GPZDA, and $GPZDG</tt> NMEA sentences by default. Note that Accord's custom NMEA sentence <tt>$GPZDG</tt> reports using the GPS timescale, while the rest of the sentences report UTC. The difference between the two is a whole number of seconds which increases with each leap second insertion in UTC. To avoid problems mixing UTC and GPS timescales, the driver disables processing of UTC sentences once <tt>$GPZDG</tt> is received.</p>
- <p>The driver expects the receiver to be set up to transmit at least one supported sentence every second.</p>
- <p>The accuracy depends on the receiver used. Inexpensive GPS models are available with a claimed PPS signal accuracy of 1 <font face="Symbol">m</font>s or better relative to the broadcast signal. However, in most cases the actual accuracy is limited by the precision of the timecode and the latencies of the serial interface and operating system.</p>
- <p>If the Operating System supports PPSAPI (<a href="http://www.ietf.org/rfc/rfc2783.txt">RFC 2783</a>), fudge flag1 1 enables its use.<br> </p>
- <p>The various GPS sentences that this driver recognises look like this:<br>
- (others quietly ignored)</p>
- <pre><tt>$GPRMC,UTC,POS_STAT,LAT,LAT_REF,LON,LON_REF,SPD,HDG,DATE,MAG_VAR,MAG_REF*CS<cr><lf>
-$GPGLL,LAT,LAT_REF,LONG,LONG_REF,UTC,POS_STAT*CS<cr><lf>
-$GPGGA,UTC,LAT,LAT_REF,LONG,LONG_REF,FIX_MODE,SAT_USED,HDOP,ALT,ALT_UNIT,GEO,G_UNIT,D_AGE,D_REF*CS<cr><lf>
-$GPZDA,UTC,DD,MM,YYYY,TH,TM,*CS<cr><lf>
-$GPZDG,GPSTIME,DD,MM,YYYY,AA.BB,V*CS<cr><lf>
-
- UTC - Time of day on UTC timescale. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.fff])
- POS_STAT - Position status. (A = Data valid, V = Data invalid)
- LAT - Latitude (llll.ll)
- LAT_REF - Latitude direction. (N = North, S = South)
- LON - Longitude (yyyyy.yy)
- LON_REF - Longitude direction (E = East, W = West)
- SPD - Speed over ground. (knots) (x.x)
- HDG - Heading/track made good (degrees True) (x.x)
- DATE - Date (ddmmyy)
- MAG_VAR - Magnetic variation (degrees) (x.x)
- MAG_REF - Magnetic variation (E = East, W = West)
- FIX_MODE - Position Fix Mode (0 = Invalid, >0 = Valid)
- SAT_USED - Number Satellites used in solution
- HDOP - Horizontal Dilution of Precision
- ALT - Antenna Altitude
- ALT_UNIT - Altitude Units (Metres/Feet)
- GEO - Geoid/Elipsoid separation
- G_UNIT - Geoid units (M/F)
- D_AGE - Age of last DGPS Fix
- D_REF - Reference ID of DGPS station
- GPSTIME - Time of day on GPS timescale. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.f])
- DD - Day of the month (1-31)
- MM - Month of the year (1-12)
- YYYY - Year
- AA.BB - Denotes the signal strength (should be < 05.00)
- V - GPS sync status
- '0' => INVALID time,
- '1' => accuracy of +/- 20ms,
- '2' => accuracy of +/- 100ns
- CS - Checksum
- <cr><lf> - Sentence terminator.</tt></pre>
-
-<p>Specific GPS sentences and bitrates may be selected by setting bits of the 'mode' in the server configuration line:<br>
- <tt>server 127.127.20.x mode X</tt><br> bit 0 - process <tt>$GPMRC</tt> (value = 1)<br> bit 1 - process <tt>$GPGGA</tt> (value = 2)<br> bit 2 - process <tt>$GPGLL</tt> (value = 4)<br> bit 4 - process <tt>$GPZDA</tt> or <tt>$GPZDG</tt> (value = 8)<br>
-<p>The default (mode 0) is to process all supported sentences, which results in the last received each cycle being used. Multiple sentences may be selected by adding their mode bit values. The driver uses 4800 bits per second by default. Faster bitrates can be selected using bits 4, 5, and 6 of the mode field:<br><br>
- bits 4/5/6 - select serial bitrate (0 for 4800 - the default, 16 for 9600, 32 for 19200, 48 for 38400, 64 for 57600, 80 for 115200)<br></p>
- <p>The driver will send a <tt>$PMOTG,RMC,0000*1D<cr><lf></tt> command each poll interval. This is not needed on most GPS receivers because they automatically send <tt>$GPRMC</tt> every second, but helps a Motorola GPS receiver that is otherwise silent. NMEA devices ignore commands they do not understand.</p>
- <h4>Setting up the Garmin GPS-25XL</h4>
- Switch off all output with by sending it the following string.
- <pre>"$PGRMO,,2<cr><lf>"</pre>
- <p>Now switch only $GPRMC on by sending it the following string.</p>
- <pre>"$PGRMO,GPRMC,1<cr><lf>"</pre>
- <p>On some systems the PPS signal isn't switched on by default. It can be switched on by sending the following string.</p>
- <pre>"$PGRMC,,,,,,,,,,,,2<cr><lf>"</pre>
- <h4>Monitor Data</h4>
- <p>The GPS sentence that is used is written to the clockstats file and available with ntpq -c clockvar.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the PPS time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Specifies the serial end of line time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>GPS</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Disable PPS signal processing if 0 (default); enable PPS signal processing if 1.
- <dt><tt>flag2 0 | 1</tt>
- <dd>If PPS signal processing is enabled, capture the pulse on the rising edge if 0 (default); capture on the falling edge if 1.
- <dt><tt>flag3 0 | 1</tt>
- <dd>If PPS signal processing is enabled, use the <tt>ntpd</tt> clock discipline if 0 (default); use the kernel discipline if 1.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Obscures location in timecode: 0 for disable (default), 1 for enable.
- </dl>
- <p>Additional Information</p>
- <p><a href="../refclock.html">Reference Clock Drivers</a></p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
+
+
+ <body>
+ <h3>Generic NMEA GPS Receiver</h3>
+ <hr>
+ <h4>Synopsis</h4>
+
+ <p>
+ Address: 127.127.20.<i>u</i><br>
+ Reference ID: <tt>GPS</tt><br>
+ Driver ID: <tt>GPS_NMEA</tt><br>
+ Serial Port: <tt>/dev/gps<i>u</i></tt>; 4800 - 115200 bps, 8-bits, no parity<br>
+ Serial Port: <tt>/dev/gpspps<i>u</i></tt>; for just the PPS signal (this
+ is tried first for PPS, before <tt>/dev/gps<i>u</i></tt>)<br>
+ Serial Port: <tt>/dev/gps<i>u</i></tt>; symlink to server:port (for nmead)<br>
+ Features: <tt>tty_clk</tt>
+ </p>
+
+ <h4>Description</h4>
+
+ <p>
+ This driver supports GPS receivers with
+ the <tt>$GPRMC</tt>, <tt>$GPGLL</tt>, <tt>$GPGGA</tt>, <tt>$GPZDA</tt>
+ and <tt>$GPZDG</tt> NMEA sentences by default. Note that Accord's
+ custom NMEA sentence <tt>$GPZDG</tt> reports using the GPS timescale,
+ while the rest of the sentences report UTC. The difference between
+ the two is a whole number of seconds which increases with each leap
+ second insertion in UTC. To avoid problems mixing UTC and GPS
+ timescales, the driver disables processing of UTC sentences
+ once <tt>$GPZDG</tt> is received.
+ </p>
+ <p>
+ The driver expects the receiver to be set up to transmit at least one
+ supported sentence every second.
+ </p>
+ <p>
+ The accuracy depends on the receiver used. Inexpensive GPS models are
+ available with a claimed PPS signal accuracy of
+ 1 <font face="Symbol">m</font>s or better relative to the broadcast
+ signal. However, in most cases the actual accuracy is limited by the
+ precision of the timecode and the latencies of the serial interface and
+ operating system.
+ </p>
+ <p>
+ If the Operating System supports PPSAPI
+ (<a href="http://www.ietf.org/rfc/rfc2783.txt">RFC 2783</a>), fudge flag1
+ 1 enables its use.
+ </p>
+ <p>
+ The various GPS sentences that this driver recognises look like this:<br>
+ (others quietly ignored)
+ </p>
+
+ <p><table class="dlstable" border="1">
+ <caption>Accepted NMEA sentences</caption>
+ <tbody><tr>
+ <th>Sentence</th>
+ <th>Vendor</th>
+ </tr><tr>
+ <td class="ttf">$GPRMC,UTC,POS_STAT,LAT,LAT_REF,LON,LON_REF,SPD,HDG,DATE,MAG_VAR,MAG_REF*CS<cr><lf></td>
+ </tr><tr>
+ <td class="ttf">$GPGLL,LAT,LAT_REF,LON,LON_REF,UTC,POS_STAT*CS<cr><lf></td>
+ </tr><tr>
+ <td class="ttf">$GPGGA,UTC,LAT,LAT_REF,LON,LON_REF,FIX_MODE,SAT_USED,HDOP,ALT,ALT_UNIT,GEO,G_UNIT,D_AGE,D_REF*CS<cr><lf></td>
+ </tr><tr>
+ <td class="ttf">$GPZDA,UTC,DD,MM,YYYY,TH,TM,*CS<cr><lf></td>
+ </tr><tr>
+ <td class="ttf">$GPZDG,GPSTIME,DD,MM,YYYY,AA.BB,V*CS<cr><lf></td>
+ <td>Accord</td>
+ </tr>
+ </tbody></table></p>
+
+ <p><table class="dlstable" border="1">
+ <caption>NMEA data items</caption>
+ <tbody><tr>
+ <th>Symbol</th>
+ <th>Meaning and Format</th>
+ </tr>
+
+ <tr>
+ <td class="ttf">UTC</td>
+ <td>Time of day on UTC timescale. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.fff])</td>
+ </tr><tr>
+ <td class="ttf">POS_STAT</td>
+ <td>Position status. (A = Data valid, V = Data invalid)</td>
+ </tr><tr>
+ <td class="ttf">LAT</td>
+ <td>Latitude (llll.ll)</td>
+ </tr><tr>
+ <td class="ttf">LAT_REF</td>
+ <td>Latitude direction. (N = North, S = South)</td>
+ </tr><tr>
+ <td class="ttf">LON</td>
+ <td>Longitude (yyyyy.yy)</td>
+ </tr><tr>
+ <td class="ttf">LON_REF</td>
+ <td>Longitude direction (E = East, W = West)</td>
+ </tr><tr>
+ <td class="ttf">SPD</td>
+ <td>Speed over ground. (knots) (x.x)</td>
+ </tr><tr>
+ <td class="ttf">HDG</td>
+ <td>Heading/track made good (degrees True) (x.x)</td>
+ </tr><tr>
+ <td class="ttf">DATE</td>
+ <td>Date (ddmmyy)</td>
+ </tr><tr>
+ <td class="ttf">MAG_VAR</td>
+ <td>Magnetic variation (degrees) (x.x)</td>
+ </tr><tr>
+ <td class="ttf">MAG_REF</td>
+ <td>Magnetic variation (E = East, W = West)</td>
+ </tr><tr>
+ <td class="ttf">FIX_MODE</td>
+ <td>Position Fix Mode (0 = Invalid, >0 = Valid)</td>
+ </tr><tr>
+ <td class="ttf">SAT_USED</td>
+ <td>Number of Satellites used in solution</td>
+ </tr><tr>
+ <td class="ttf">HDOP</td>
+ <td>Horizontal Dilution of Precision</td>
+ </tr><tr>
+ <td class="ttf">ALT</td>
+ <td>Antenna Altitude</td>
+ </tr><tr>
+ <td class="ttf">ALT_UNIT</td>
+ <td>Altitude Units (Metres/Feet)</td>
+ </tr><tr>
+ <td class="ttf">GEO</td>
+ <td>Geoid/Elipsoid separation</td>
+ </tr><tr>
+ <td class="ttf">G_UNIT</td>
+ <td>Geoid units (M/F)</td>
+ </tr><tr>
+ <td class="ttf">D_AGE</td>
+ <td>Age of last DGPS Fix</td>
+ </tr><tr>
+ <td class="ttf">D_REF</td>
+ <td>Reference ID of DGPS station</td>
+ </tr><tr>
+ <td class="ttf">GPSTIME</td>
+ <td>Time of day on GPS timescale. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.f])</td>
+ </tr><tr>
+ <td class="ttf">DD</td>
+ <td>Day of the month (1-31)</td>
+ </tr><tr>
+ <td class="ttf">MM</td>
+ <td>Month of the year (1-12)</td>
+ </tr><tr>
+ <td class="ttf">YYYY</td>
+ <td>Year</td>
+ </tr><tr>
+ <td class="ttf">AA.BB</td>
+ <td>Denotes the signal strength (should be < 05.00)</td>
+ </tr><tr>
+ <td class="ttf">V</td>
+ <td>GPS sync status<br>
+ '0' => INVALID time,<br>
+ '1' => accuracy of +/- 20ms,<br>
+ '2' => accuracy of +/- 100ns</td>
+ </tr><tr>
+ <td class="ttf">CS</td>
+ <td> Checksum</td>
+ </tr><tr>
+ <td class="ttf"><cr><lf></td>
+ <td>Sentence terminator.</td>
+ </tr>
+ </tbody></table></p>
+
+
+ <h4>The 'mode' byte</h4>
+
+ <p>
+ Specific GPS sentences and bitrates may be selected by setting bits of
+ the 'mode' in the server configuration line:<br> <tt>server
+ 127.127.20.x mode X</tt>
+ </p>
+
+ <table border="1">
+ <caption>mode byte bits and bit groups</caption>
+ <tbody><tr>
+ <th align="center">Bit</th>
+ <th align="center">Dec.</th>
+ <th align="left">Meaning</th>
+ </tr>
+
+ <tr>
+ <td align="center">0</td>
+ <td align="center">1</td>
+ <td>process <tt>$GPMRC</tt></td>
+ </tr><tr>
+ <td align="center">1</td>
+ <td align="center">2</td>
+ <td>process <tt>$GPGGA</tt></td>
+ </tr><tr>
+ <td align="center">2</td>
+ <td align="center">4</td>
+ <td>process <tt>$GPGLL</tt></td>
+ </tr><tr>
+ <td align="center">3</td>
+ <td align="center">8</td>
+ <td>process <tt>$GPZDA</tt> or <tt>$GPZDG</tt></td>
+ </tr><tr>
+ <td rowspan="6" align="center">4-6</td>
+ <td align="center">0</td>
+ <td>linespeed 4800bps</td>
+ </tr><tr>
+ <td align="center">16</td>
+ <td>linespeed 9600bps</td>
+ </tr><tr>
+ <td align="center">32</td>
+ <td>linespeed 19200bps</td>
+ </tr><tr>
+ <td align="center">48</td>
+ <td>linespeed 38400bps</td>
+ </tr><tr>
+ <td align="center">64</td>
+ <td>linespeed 57600bps</td>
+ </tr><tr>
+ <td align="center">80</td>
+ <td>linespeed 115200bps</td>
+ </tr><tr>
+ <td align="center">7</td>
+ <td align="center">128</td>
+ <td>Write the sub-second fraction of the receive time stamp to the
+ clockstat file for all recognised NMEA sentences. This can be used to
+ get a useful value for fudge time2.<br><strong>Caveat:</strong> This
+ will fill your clockstat file rather fast. Use it only temporarily to
+ get the numbers for the NMEA sentence of your choice.</td>
+ </tr>
+ </tbody></table>
+
+
+ <p>
+ The default (mode 0) is to process all supported sentences at a linespeed
+ of 4800bps, which results in the first one received and recognised in
+ each cycle being used. If only specific sentences should be
+ recognised, then the mode byte must be chosen to enable only the selected
+ ones. Multiple sentences may be selected by adding their mode bit
+ values, but of those enabled still only the first received sentence in a
+ cycle will be used. Using more than one sentence per cycle is
+ impossible, because
+ </p><ul>
+ <li>there is only <a href="#fudgetime2">fudge time2</a> available to
+ compensate for transmission delays but every sentence would need a
+ different one and
+ </li><li>using more than one sentence per cycle overstuffs the internal data
+ filters.
+ </li></ul>
+ The driver uses 4800 bits per second by default, but faster bitrates can
+ be selected using bits 4 to 6 of the mode field.
+ <p></p>
+
+ <p>
+ <strong>Caveat:</strong> Using higher line speeds does not necessarily
+ increase the precision of the timing device. Higher line speeds are
+ not necessarily helpful for the NMEA driver, either. They can be
+ used to accomodate for an amount of data that does not fit into a
+ 1-second cycle at 4800bps, but high-speed high-volume NMEA data is likely
+ to cause trouble with the serial line driver since NMEA supports no
+ protocol handshake. Any device that is exclusively used for time
+ synchronisation purposes should be configured to transmit the relevant
+ data only, e.g. one <tt>$GPRMC</tt> or <tt>$GPZDA</tt> per second, at a
+ linespeed of 4800bps or eventually 9600bps.
+ </p>
+
+ <p>
+ <a href="https://support.ntp.org/bin/view/Support/ConfiguringNMEARefclocks">Configuring
+ NMEA Refclocks</a> might give further useful hints for specific hardware
+ devices that exhibit strange or curious behaviour.
+ </p>
+
+ <p>
+ To make a specific setting, select the corresponding decimal values from
+ the mode byte table, add them all together and enter the resulting
+ decimal value into the clock configuration line.
+ </p>
+
+ <p>
+ The driver will send a <tt>$PMOTG,RMC,0000*1D<cr><lf></tt>
+ command each poll interval. This is not needed on most GPS
+ receivers because they automatically send <tt>$GPRMC</tt> every second,
+ but helps a Motorola GPS receiver that is otherwise silent. NMEA
+ devices ignore commands they do not understand.
+ </p>
+
+ <h4>Setting up the Garmin GPS-25XL</h4>
+
+ Switch off all output with by sending it the following string.
+ <pre>"$PGRMO,,2<cr><lf>"</pre>
+ <p>Now switch only $GPRMC on by sending it the following string.</p>
+ <pre>"$PGRMO,GPRMC,1<cr><lf>"</pre>
+
+ <p>On some systems the PPS signal isn't switched on by default. It can be
+ switched on by sending the following string.</p>
+ <pre>"$PGRMC,,,,,,,,,,,,2<cr><lf>"</pre>
+
+ <h4>Monitor Data</h4>
+
+ <p>The GPS sentence that is used is written to the clockstats file and
+ available with ntpq -c clockvar.</p>
+
+ <h4>Fudge Factors</h4>
+
+ <dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the PPS time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><a name="fudgetime2"><tt>time2 <i>time</i></tt></a></dt>
+ <dd>Specifies the serial end of line time offset calibration factor, in seconds and fraction, with default
+ 0.0.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with
+ default <tt>GPS</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Disable PPS signal processing if 0 (default); enable PPS signal processing if 1.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>If PPS signal processing is enabled, capture the pulse on the rising edge if 0 (default); capture on the
+ falling edge if 1.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>If PPS signal processing is enabled, use the <tt>ntpd</tt> clock discipline if 0 (default); use the kernel
+ discipline if 1.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Obscures location in timecode: 0 for disable (default), 1 for enable.</dd>
+ </dl>
+
+ <p>Additional Information</p>
+ <p><a href="">Reference Clock Drivers</a></p>
+ <hr>
+ <script type="text/javascript" language="javascript" src="driver20_files/a"></script>
+ </body></html>
projects / thirdparty / ntp.git / commitdiff
