diff options
Diffstat (limited to 'contrib/ntp/html/clockopt.htm')
-rw-r--r-- | contrib/ntp/html/clockopt.htm | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/contrib/ntp/html/clockopt.htm b/contrib/ntp/html/clockopt.htm new file mode 100644 index 0000000..b128b42 --- /dev/null +++ b/contrib/ntp/html/clockopt.htm @@ -0,0 +1,193 @@ +<HTML><HEAD><TITLE> +Reference Clock Options +</TITLE></HEAD><BODY><H3> +Reference Clock Options +</H3><HR> + +<H4>Reference Clock Support</H4> + +The NTP Version 4 daemon supports many different radio, satellite and +modem reference clocks plus a special pseudo-clock used for backup or +when no other clock source is available. Detailed descriptions of +individual device drivers and options can be found in the <A +HREF="refclock.htm">Reference Clock Drivers </A>page. Additional +information can be found in the pages referenced there, including the <A +HREF="rdebug.htm">Debugging Hints for Reference Clock Drivers</A> and <A +HREF="howto.html">How To Write a Reference Clock Driver</A> pages. In +many drivers, support for a PPS signal is available as described in <A +HREF="pps.htm">Pulse-per-second (PPS) Signal Interfacing</A> page. Many +drivers support special line discipline/streams modules which can +significantly improve the accuracy using the driver. These are described +in the <A HREF="ldisc.htm">Line Disciplines and Streams Drivers</A> +page. + +<P>A reference clock will generally (though not always) be a radio +timecode receiver which is synchronized to a source of standard time +such as the services offered by the NRC in Canada and NIST and USNO in +the U.S. The interface between the computer and the timecode receiver is +device dependent, but is usually a serial port. A device driver specific +to each reference clock must be selected and compiled in the +distribution; however, most common radio, satellite and modem clocks are +included by default. Note that an attempt to configure a reference clock +when the driver has not been included or the hardware port has not been +appropriately configured results in a scalding remark to the system log +file, but is otherwise non hazardous. + +<P>For the purposes of configuration, <TT>ntpd</TT> treats reference +clocks in a manner analogous to normal NTP peers as much as possible. +Reference clocks are identified by a syntactically correct but invalid +IP address, in order to distinguish them from normal NTP peers. +Reference clock addresses are of the form <TT>127.127.<I>t.u</I></TT>, +where <I><TT>t</TT></I> is an integer denoting the clock type and +<I><TT>u</TT></I> indicates the unit number. While it may seem overkill, +it is in fact sometimes useful to configure multiple reference clocks of +the same type, in which case the unit numbers must be unique. + +<P>The <TT>server</TT> command is used to configure a reference clock, +where the <I><TT>address</TT></I> argument in that command is the clock +address. The <TT>key</TT>, <TT>version</TT> and <TT>ttl</TT> options are +not used for reference clock support. The <TT>mode</TT> option is added +for reference clock support, as described below. The <TT>prefer</TT> +option can be useful to persuade the server to cherish a reference clock +with somewhat more enthusiasm than other reference clocks or peers. +Further information on this option can be found in the <A +HREF="prefer.htm">Mitigation Rules and the <TT>prefer</TT> Keyword +</A>page. The <TT>minpoll</TT> and <TT>maxpoll</TT> options have meaning +only for selected clock drivers. See the individual clock driver +document pages for additional information. + +<P>The stratum number of a reference clock is by default zero. Since the +<TT>ntpd</TT> daemon adds one to the stratum of each peer, a primary +server ordinarily displays stratum one. In order to provide engineered +backups, it is often useful to specify the reference clock stratum as +greater than zero. The <TT>stratum</TT> option is used for this purpose. +Also, in cases involving both a reference clock and a pulse-per-second +(PPS) discipline signal, it is useful to specify the reference clock +identifier as other than the default, depending on the driver. The +<TT>refid</TT> option is used for this purpose. Except where noted, +these options apply to all clock drivers. + +<H4>Reference Clock Commands</H4> + +<DL><DT><TT>server 127.127.<I>t.u</I> [prefer] [mode <I>int</I>] +[minpoll <I>int</I>] [maxpoll <I>int</I>]</TT></DT> +<DD>This command can be used to configure reference clocks in special +ways. The options are interpreted as follows:</DD> + +<DL><DT><TT>prefer</TT></DT> +<DD>Marks the reference clock as preferred. All other things being +equal, this host will be chosen for synchronization among a set of +correctly operating hosts. See the <A HREF="prefer.htm">Mitigation Rules +and the <TT>prefer</TT> Keyword </A>page for further information.</DD> + +<DT><TT>mode <I>int</I></TT></DT> +<DD>Specifies a mode number which is interpreted in a device-specific +fashion. For instance, it selects a dialing protocol in the ACTS driver +and a device subtype in the <TT>parse</TT> drivers.</DD> + +<DT><TT>minpoll <I>int</I></TT></DT> +<DT><TT>maxpoll<I> int</I></TT></DT> +<DD>These options specify the minimum and maximum polling interval for +reference clock messages, in seconds to the power of two. For most +directly connected reference clocks, both <TT>minpoll</TT> and +<TT>maxpoll</TT> default to 6 (64 s). For modem reference clocks, +<TT>minpoll</TT> defaults to 10 (17.1 m) and <TT>maxpoll</TT> defaults +to 14 (4.5 h). The allowable range is 4 (16 s) to 17 (36.4 h) +inclusive.</DD> + +</DL> + +<DT><TT>fudge 127.127.<I>t.u</I> [time1 <I>sec</I>] [time2 <I>sec</I>] +[stratum <I>int</I>] [refid <I>string</I>] [mode <I>int</I>] [flag1 0|1] +[flag2 0|1] [flag3 0|1] [flag4 0|1]</TT></DT> +<DD>This command can be used to configure reference clocks in special +ways. It must immediately follow the <TT>server</TT> command which +configures the driver. Note that the same capability is possible at run +time using the <TT><A HREF="ntpdc.htm">ntpdc</A></TT> program. The +options are interpreted as follows:</DD> + +<DL> + +<DT><TT>time1 <I>sec</I></TT></DT> +<DD>Specifies a constant to be added to the time offset produced by the +driver, a fixed-point decimal number in seconds. This is used as a +calibration constant to adjust the nominal time offset of a particular +clock to agree with an external standard, such as a precision PPS +signal. It also provides a way to correct a systematic error or bias due +to serial port latencies, different cable lengths or receiver internal +delay. The specified offset is in addition to the propagation delay +provided by other means, such as internal DIPswitches. Where a +calibration for an individual system and driver is available, an +approximate correction is noted in the driver documentation pages.</DD> + +<DT><TT>time2 <I>secs</I></TT></DT> +<DD>Specifies a fixed-point decimal number in seconds, which is +interpreted in a driver-dependent way. See the descriptions of specific +drivers in the <A HREF="refclock.htm">reference clock drivers</A> +page.</DD> + +<DT><TT>stratum <I>int</I></TT></DT> +<DD>Specifies the stratum number assigned to the driver, an integer +between 0 and 15. This number overrides the default stratum number +ordinarily assigned by the driver itself, usually zero.</DD> + +<DT><TT>refid <I>string</I></TT></DT> +<DD>Specifies an ASCII string of from one to four characters which +defines the reference identifier used by the driver. This string +overrides the default identifier ordinarily assigned by the driver +itself.</DD> + +<DT><TT>mode <I>int</I></TT></DT> +<DD>Specifies a mode number which is interpreted in a device-specific +fashion. For instance, it selects a dialing protocol in the ACTS driver +and a device subtype in the <TT>parse</TT> drivers.</DD> + +<DT><TT>flag1</TT> <TT>flag2</TT> <TT>flag3</TT> <TT>flag4</TT></DT> +<DD>These four flags are used for customizing the clock driver. The +interpretation of these values, and whether they are used at all, is a +function of the particular clock driver. However, by convention +<TT>flag4</TT> is used to enable recording monitoring data to the +<TT>clockstats</TT> file configured with the <TT>filegen</TT> command. +When a PPS signal is available, a special automatic calibration facility +is provided. If the <tt>flag1</tt> switch is set and the PPS signal is +actively disciplining the system time, the calibration value is +automatically adjusted to maintain a residual offset of zero. Further +information on the <TT>filegen</TT> command can be found in the <A +HREF="monopt.htm">Monitoring Options </A>page.</DD> + +</DL> + +<DT><TT>pps <I>device</I> [assert|clear] [hardpps]</TT></DT> +<DD>Specifies the name and options for the serial port device to which +the PPS signal is connected. Note, this command replaces use of +<TT>fudge flag3</TT>, which was used for the same purpose in NTPv3. Note +that this command should preceed the <TT>server</TT> and <TT>fudge</TT> +command for the same device. Note also that the <TT>assert</TT>, +<TT>clear</TT> and <TT>hardpps</TT> options are only available if the +<tt>ppsapi</tt> standard PPS interface is available.</DD> + +<DL> + +<DT><TT>device</TT></DT> +<DD>Specify the device name associated with the PPS signal. The name +must match exactly the link name specified in the driver documentation +page.</DD> + +<DT><TT>assert</TT></DT> +<DT><TT>clear</TT></DT> +<DD>Using <TT>assert</TT> or <TT>clear</TT> specifies if the high going +or low going edge of the signal must be used. The default is +<TT>assert</TT>.</DD> + +<DT><TT>hardpps</TT></DT> +<DD>This flag is used to tell the kernel that the signal from this +device must be used to drive hardpps().</DD> + +<DD>The <TT>assert</TT>, <TT>clear</TT> and <TT>hardpps</TT> options +are only available if the PPSAPI is used.</DD> + +</DL> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> |