[Git][NTPsec/ntpsec][master] 5 commits: Correct formatting, to make anchors within text work

Eric S. Raymond gitlab at mg.gitlab.com
Tue Nov 29 11:58:13 UTC 2016

Eric S. Raymond pushed to branch master at NTPsec / ntpsec

df1b84a6 by Sanjeev Gupta at 2016-11-29T16:01:07+08:00
Correct formatting, to make anchors within text work

asciidoc internal links must be:
 [[Hello]] Hello::
 This is how to say hello

 This is how to say hello

- - - - -
57e8b0ee by Sanjeev Gupta at 2016-11-29T16:41:28+08:00
HOPF reorganised its website, correct to new location

- - - - -
40ddb8ea by Sanjeev Gupta at 2016-11-29T16:45:44+08:00
Change filename for consistency, this was causing a broken link

driver-howto.txt => driver_howto.txt
in line with the other docs.

- - - - -
21063ef8 by Sanjeev Gupta at 2016-11-29T17:31:22+08:00
Remove broken internal link

Is there any info available on the crypto status codes,
similar to the KISS or FLASH codes?

- - - - -
466fe02d by Sanjeev Gupta at 2016-11-29T17:44:06+08:00
Remove and replace incorrect TOC

The TOC in this document had been copied from quick.txt
commit 1690b354

- - - - -

6 changed files:

- docs/decode.txt
- − docs/driver-howto.txt
- docs/driver_generic.txt
- docs/includes/refclock.txt
- docs/ntpspeak.txt
- docs/outside-tools.txt


--- a/docs/decode.txt
+++ b/docs/decode.txt
@@ -23,7 +23,9 @@ include::includes/install.txt[]
 * link:#clock[Clock Status Word]
 * link:#flash[Flash Status Word]
 * link:#kiss[Kiss Codes]
-* link:#crypto[Crypto Messages]
+// The crypto link goes nowhere.  TODO: locate this info and add here
+// -- Sanjeev 20161129
+// * link:#crypto[Crypto Messages]

docs/driver-howto.txt deleted
--- a/docs/driver-howto.txt
+++ /dev/null
@@ -1,255 +0,0 @@
-= How to Write a Reference Clock Driver =
-http://www.eecis.udel.edu/%7emills/pictures.html[from 'Pogo', Walt Kelly]
-You need a little magic.
-== Related Links ==
-== Table of Contents ==
-* link:#desc[Description]
-* link:#file[Files Which Need to be Changed]
-* link:#intf[Interface Routine Overview]
-* link:#pps[Pulse-per-Second Interface]
-== When Not to Write a Driver ==
-If the device you are trying to support is an exotic GPS, you should
-probably not write an +ntpd+ driver for it.  Instead, check to see if
-it is already supported by {GPSD}, a project with which NTPsec
-cooperates closely.  The GPSD people are specialists in managing GPSes
-and better at it than we are, supporting a much broader range of
-devices, and GPSD is designed to feed clock samples to +ntpd+ from any
-of them.  If you need to write a driver for a GPS, they'll take it and
-should have it.
-If you have a non-GPS time source (like a time radio or GPSDO) that
-you want to support, consider link:generic_howto.html[writing a mode
-for it in the generic driver] rather than a full driver of its own;
-this will be easier.  The generic driver is so called because it
-factors out a lot of I/O and housekeeping code common to all drivers,
-allowing you support a new device type by writing only a parser for
-its sentences.
-== Structure of a Driver ==
-NTP reference clock support maintains the fiction that the clock is
-actually an ordinary server in the NTP tradition, but operating at a
-synthetic stratum of zero. The entire suite of algorithms filter the
-received data and select the best sources to correct the system clock.
-No packets are exchanged with a reference clock; however, the transmit,
-receive and packet procedures are replaced with code to simulate them.
-The driver assumes three timescales: standard time maintained by a
-distant laboratory such as USNO or NIST, reference time maintained by
-the external radio and the system time maintained by NTP. The radio
-synchronizes reference time via radio, satellite or modem. As the
-transmission means may not always be reliable, most radios continue to
-provide clock updates for some time after signal loss using an internal
-reference oscillator. In such cases the radio may or may not reveal the
-time since last synchronized or the estimated time error.
-All three timescales run only in Coordinated Universal Time (UTC) and
-are not adjusted for local timezone or standard/daylight time. The local
-timezone, standard/daylight indicator and year, if provided, are
-ignored. However, it is important to determine whether a leap second is
-to be inserted in the UTC timescale in the near future so NTP can insert
-it in the system timescale at the appropriate epoch.
-The interface routines in the +ntp_refclock.c+ source file call the
-following driver routines via a transfer vector:
-  The association has just been mobilized. The driver may allocate a
-  private structure and open the device(s) required.
-  The association is about to be demobilized. The driver should close
-  all device(s) and free private structures.
-  A timecode string is ready for retrieval using the +refclock_gtlin()+
-  or +refclock_gtraw()+ routines and provide clock updates.
-  Called at poll timeout, by default 64 s. Ordinarily, the driver will
-  send a poll sequence to the radio as required.
-  Called once per second. This can be used for housekeeping functions.
-  In the case with pulse-per-second (PPS) signals, this can be used to
-  process the signals and provide clock updates.
-The receive routine retrieves a timecode string via serial or parallel
-port, PPS signal or other means. It decodes the timecode in days, hours,
-minutes, seconds and nanoseconds and checks for errors. It provides
-these data along with the on-time timestamp to the +refclock_process+
-routine, which saves the computed offset in a 60-sample circular buffer.
-On occasion, either by timeout, sample count or call to the poll
-routine, the driver calls +refclock_receive+ to process the circular
-buffer samples and update the system clock.
-The best way to understand how the clock drivers work is to study one of
-the drivers already implemented, such as +refclock_spectracom.c+. The
-main interface is the +refclockproc+ structure, which contains for most
-drivers the decoded timecode, on-time timestamp, reference timestamp,
-exception reports and statistics tallies, etc. The support routines are
-passed a pointer to the +peer+ structure, which contains a pointer to
-the +refclockproc+ structure, which in turn contains a pointer to the
-unit structure, if used. For legacy purposes, a table
-+typeunit[type][unit]+ contains the peer structure pointer for each
-configured clock type and unit. This structure should not be used for
-new implementations.
-Radio and modem reference clocks by convention have addresses of the
-form +127.127.t.u+, where _t_ is the clock type and _u_ in the range 0-3
-is used to distinguish multiple instances of clocks of the same type.
-These addresses used to be exposed as part of the refclock
-configuration syntax, but are no longer.  Nothing in ntpd now actually
-requires this form of address for clocks, but it is still generated
-so as not to hand surprises to legacy +ntpq+ instances that still make
-the assumption.
-Most clocks require a serial or parallel port or special bus peripheral.
-The particular device is normally specified by adding a soft link
-+/dev/deviceu+ to the particular hardware device.
-By convention, reference clock drivers are named in the form
-+refclock_xxxx.c+, where +xxxx+ is a unique string. Each driver is
-assigned a unique long-form driver name, short-form driver name and
-device name. The existing assignments are in the
-link:refclock.html[Reference Clock Drivers] page and its dependencies.
-== Conventions, Fudge Factors and Flags ==
-Most drivers support manual or automatic calibration for systematic
-offset bias using values encoded in the +refclock+ configuration command.
-By convention, the +time1+ value defines the calibration offset in
-seconds. For those drivers that support statistics collection using the
-+filegen+ utility and the +clockstats+ file, the +flag4+ switch enables
-the utility.
-If the calibration feature has been enabled, the +flag1+ switch is set
-and the PPS signal is actively disciplining the system time, the +time1+
-value is automatically adjusted to maintain a residual offset of zero.
-Once the its value has stabilized, the value can be inserted in the
-configuration file and the calibration feature disabled.
-== Files Which Need to be Changed ==
-When a new reference clock driver is installed, the following files need
-to be edited. Note that changes are also necessary to properly integrate
-the driver in the configuration and makefile scripts, but these are
-decidedly beyond the scope of this page.
-  The reference clock type defines are used in many places. Each driver
-  is assigned a unique type number. Unused numbers are clearly marked in
-  the list. A unique +REFCLK_xxxx+ identification code should be
-  recorded in the list opposite its assigned type number.
-  The +./libntp/clktype+ array is used by certain display functions. A
-  unique short-form name of the driver should be entered together with
-  its assigned identification code.
-  The +clocktypes+ array is used for certain control message displays
-  functions. It should be initialized with the reference clock class
-  assigned to the driver, as per the NTP specification RFC-1305. See the
-  +./include/ntp_control.h+ header file for the assigned classes.
-  This file contains a list of external structure definitions which are
-  conditionally defined. A new set of entries should be installed
-  similar to those already in the table. The +refclock_conf+ array is a
-  set of pointers to transfer vectors in the individual drivers. The
-  external name of the transfer vector should be initialized in
-  correspondence with the type number.
-== Interface Routine Overview ==
-+refclock_newpeer+ - initialize and start a reference clock.::
-  This routine allocates and initializes the interface structure which
-  supports a reference clock in the form of an ordinary NTP peer. A
-  driver-specific support routine completes the initialization, if used.
-  Default peer variables which identify the clock and establish its
-  reference ID and stratum are set here. It returns one if success and
-  zero if the clock address is invalid or already running, insufficient
-  resources are available or the driver declares a bum rap.
-+refclock_unpeer+ - shut down a clock::
-  This routine is used to shut down a clock and return its resources to
-  the system.
-+refclock_transmit+ - simulate the transmit procedure::
-  This routine implements the NTP transmit procedure for a reference
-  clock. This provides a mechanism to call the driver at the NTP poll
-  interval, as well as provides a reachability mechanism to detect a
-  broken radio or other madness.
-+refclock_process+ - insert a sample in the circular buffer::
-  This routine saves the offset computed from the on-time timestamp and
-  the days, hours, minutes, seconds and nanoseconds in the circular
-  buffer. Note that no provision is included for the year, as provided
-  by some (but not all) radio clocks. Ordinarily, the year is implicit
-  in the Unix file system and hardware/software clock support, so this
-  is ordinarily not a problem.
-+refclock_receive+ - simulate the receive and packet procedures::
-  This routine simulates the NTP receive and packet procedures for a
-  reference clock. This provides a mechanism in which the ordinary NTP
-  filter, selection and combining algorithms can be used to suppress
-  misbehaving radios and to mitigate between them when more than one is
-  available for backup.
-+refclock_gtraw+, +refclock_gtlin+ - read the buffer and on-time timestamp::
-  These routines return the data received from the clock and the on-time
-  timestamp. The +refclock_gtraw+ routine returns a batch of one or more
-  characters returned by the Unix terminal routines in raw mode. The
-  +refclock_gtlin+ routine removes the parity bit and control characters
-  and returns all the characters up to and including the line
-  terminator. Either routine returns the number of characters delivered.
-+refclock_open+ - open a serial port for reference clock::
-  This routine opens a serial port for I/O and sets default options. It
-  returns the file descriptor if success and zero if failure.
-+refclock_ioctl+ - set serial port control functions::
-  This routine attempts to hide the internal, system-specific details of
-  serial ports. It can handle POSIX (+termios+), SYSV (+termio+) and BSD
-  (+sgtty+) interfaces with varying degrees of success. The routine
-  returns one if success and zero if failure.
-  This routine initializes the Pulse-per-Second interface (see below).
-  This routine is called once per second to read the latest PPS offset
-  and save it in the circular buffer (see below).
-== Pulse-per-Second Interface ==
-When the Pulse-per-Second Application Interface (RFC 2783) is present, a
-compact PPS interface is available to all drivers. See the
-link:prefer.html[Mitigation Rules and the Prefer Peer] page for further
-information. To use this interface, include the +timeppps.h+ and
-+refclock_pps.h+ header files and define the +refclock_ppsctl+ structure
-in the driver private storage. The +timepps.h+ file is specific to each
-operating system and may not be available for some systems.
-To use the interface, call +refclock_ppsapi+ from the startup routine
-passing the device file descriptor and +refclock_ppsctl+ structure
-pointer. Then, call +refclock_pps+ from the timer routine passing the
-association pointer and +refclock_ppsctl+ structure pointer. See the
-+refclock_pps.c+ file for examples and calling sequences. If the PPS
-signal is valid, the offset sample will be save in the circular buffer
-and a bit set in the association flags word indicating the sample is
-valid and the driver an be selected as a PPS peer. If this bit is set
-when the poll routine is called, the driver calls the
-+refclock_receive+ routine to process the samples in the circular
-buffer and update the system clock.

--- a/docs/driver_generic.txt
+++ b/docs/driver_generic.txt
@@ -232,7 +232,7 @@ image:pic/pd_om006.gif[http://www.trimble.com/cgi/omprod.cgi/pd_om006.html]
 * *refclock generic subtype 12*
-*http://www.hopf-time.com[HOPF] http://hopf.com/manuals/english/pdf_6---/e6021gps_0601.pdf[Funkuhr 6021]*
+*http://www.hopf-time.com[HOPF] http://www.hopf.com/downloads/manuals/6021gps_v0601_en.pdf[Funkuhr 6021]*

--- a/docs/includes/refclock.txt
+++ b/docs/includes/refclock.txt
@@ -1,6 +1,6 @@
 === Reference Clock Support ===
 * link:extern.html[External Clock Discipline and the Local Clock Driver]
-* link:driver-howto.html[How to Write a Reference Clock Driver]
+* link:driver_howto.html[How to Write a Reference Clock Driver]
 * link:generic_howto.html[How to build new generic clocks]
 * link:refclock.html[Reference Clock Drivers]
 * link:sitemap.html[Site Map]

--- a/docs/ntpspeak.txt
+++ b/docs/ntpspeak.txt
@@ -7,8 +7,7 @@
+[[ACTS]] ACTS::
   http://www.nist.gov/pml/div688/grp40/acts.cfm[NIST Automated
   Computer Time Service]. NIST provides a civil time reference for
   computers equipped with analog modems that can dial to its phone
@@ -17,8 +16,7 @@ ACTS::
   around a microsecond for <<PPS>>. But the service is still
   occasionally used as a backup to more precise sources.
+[[association]] association::
   An association is the relationship that an NTP client and server have
   when the server is computing and shipping time updates to the client
   and the client is expecting them.  There are several different kinds
@@ -28,18 +26,15 @@ association::
   for discovering association partners, creating and maintaining
   associations, and preventing attackers from forming associations.
-[[association ID]]
-association ID::
+[[association ID]] association ID::
   A numeric identifier designating an association, normally internal
   to ntpd but exposed in <<mode 6>> packets.
+[[atom]] atom::
   Old name for the PPS driver.  Origin lost in the mists of history,
   but probably related in some way to cesium atomic clocks.
+[[drift]] drift::
   In an NTP context, drift refers to the frequency offset of a clock crystal
   in an NTP host that causes the system time to slowly drift.  It is
   usually  expressed in a parts-per-million (PPM) offset from its
@@ -51,16 +46,14 @@ drift::
   it doesn't have to go through the entire resampling and resynchronization
   process before providing reliable time.
+[[falseticker]] falseticker::
   <<Mills-speak>> for a timeserver identified as not
   reliable by statistical filtering.  Usually this does not imply any
   problem with the timeserver itself but rather with highly variable
   and asymmetric network delays between server and client, but firmware
   bugs in GPS receivers have produced falsetickers.
+[[fudge]] fudge::
   Can have one of two senses.  Either (1) an offset configured for a
   <<refclock>> or server to correct its time, reversing a fixed or
   nearly-fixed propagation delay, or (2) in the old config syntax, a "fudge
@@ -68,8 +61,7 @@ fudge::
   declaration to change the refclock's behavior in some
   driver-dependent way.
+[[fuzzball]] fuzzball::
    Historical. An
    system] running on PDP-11s used for early time-service and Internet
@@ -77,8 +69,7 @@ fuzzball::
    While some of these remained in service as late as 1988 they are
    now long gone, but have left a few traces in the NTP codebase.
+[[GPS]] GPS::
    Global Positioning System; also, "a GPS" is a radio receiver
    designed to get position and time fixes from the system. GPS fixes
    are derived from spherical trigonometry using the precisely known
@@ -86,8 +77,7 @@ GPS::
    also provides time service; those that emit <<PPS>> are suitable
    as clock sources for Stratum 1 timeservers.
    GPS Disciplined Oscillator. A good crystal is synchronized to
    time from a GPS receiver.  The combination gets the short term
    stability of the crystal and the long term stability of GPS.
@@ -95,23 +85,20 @@ GPSDO::
    GPS receiver stops working.  Most cell towers have GPSDOs.
    You can usually spot the conical GPS antenna.
+[[GPSD]] GPSD::
    The http://www.catb.org/gpsd/[GPS Daemon], an open-source device
    manager for GPSes and other geodetic sensors. Frequently used as
    a clock source by Stratum 1 sites via the link:driver_shm.html[SHM]
+[[holdover]] holdover::
    In connection with a <<GPSD0>> or <<time radio>> that may lose
    signal from its time source, holdover is its ability to continue
    delivering accurate time from an internal oscillator. Due to
    <<drift>> in the oscillator, accuracy drops as holdover time (time
    since last signal lock) increases.
-[[in-band time]]
-in-band time::
+[[in-band time]] in-band time::
    GPS-based time sources often deliver two channels of time
    information. The timestamp delivered as ASCII data over the
    serial link is called "in-band time" to contrast it with the
@@ -119,8 +106,7 @@ in-band time::
    by itself as it tends to have a large random wander from top
    of second.
-[[leap second]]
-leap second::
+[[leap second]] leap second::
    Because the earth's rotation varies in irregular ways (gradually
    slowing due to tidal drag) and the second is now defined in
    absolute terms rather than as a fraction of day length, keeping
@@ -132,16 +118,14 @@ leap second::
    authorities.  The current leap-second offset is automatically
    propagated through the <<GPS>> system.
+[[leapfile]] leapfile::
    A local file containing the current <<leap second>> offset, typically
    fetched from <<USNO>> or <<NIST>> and potentially needing updates
    near the very beginning of each half year. Normally retrieved
    by a cron(1) job, but some varieties of <<refclock>> (notably
    GPSes) update the same information during normal operation.
+[[Mills-speak]] Mills-speak::
    Dr. David Mills, the original architect of NTP and its standards,
    wrote in a vivid and idiosyncratic style which is still preserved in
    much of NTP's documentation.  He coined many neologisms which
@@ -151,36 +135,31 @@ Mills-speak::
    NTP dictionary], though not all those terms are still in use.
-[[mode 6]]
-mode 6::
+[[mode 6]] mode 6::
    Mode 6 is a control protocol used to get various kinds of
    status information from a running ntpd and configure it on
    the fly.  So called from the value 6 (0110) in the packet mode
    field.  It is described in detail mode6.html[here].
+[[NIST]] NIST::
    http://www.nist.gov/[National Institute of Standards and
    Technology].  The civilian national time authority of the USA;
    runs <<WWVB>>.  Responsible for keeping U.S. civil time
    coordinated with international UTC time.  NIST time tracks <<USNO>>
    time to within a few nanoseconds.
-NTP Classic::
+[[NTP-classic]] NTP Classic::
    The original reference implementation of NTP by Dave Mills, later
    maintained by the Network Time Foundation.  NTPsec forked from it
    on June 6th, 2015.
+[[nonce]] nonce::
   An arbitrary number that may only be used once. a random or
   pseudo-random number issued in an authentication protocol (such as
   NTP's) to ensure that old communications cannot be reused in replay
-parse driver::
+[[parse-driver]] parse driver::
   A refclock, now known as link:driver_generic.html[generic], which
   handles multiple <<time radio>> protocols - two dozen mostly
   European precision time radios mostly using DCF, the broadcast time
@@ -189,14 +168,12 @@ parse driver::
   table-driven parser. Older documentation used the term "parse
   driver" interchangeably with "generic driver".
-[[popcorn spike]]
-popcorn spike::
+[[popcorn spike]] popcorn spike::
   A packet from a particular peer that has a computed theta more than
   three standard deviations from the prevous sample.  These are
   normally treated as random outliers and suppressed.
+[[PPS]] PPS::
   (Also as "1PPS") Pulse Per Second. A top-of-second pulse emitted
   by time sources, typically a GPS receiver or atomic clocks.  It
   is often connected to a RS-232 modem control signal pin.
@@ -207,35 +184,29 @@ PPS::
   provisions to grab a timestamp at interrupt time.  The API is described
   in RFC-2783.
+[[PTP]] PTP::
   https://en.wikipedia.org/wiki/Precision_Time_Protocol[Precision Time
   Protocol], which does for hosts on a local area network what NTP
   does on the general Internet. By taking advantage of the (usually)
   more controlled conditions of a LAN, it is capable of much higher
   sustained accuracy than NTP, into the sub-microsecond range.
+[[pool]] pool::
    In an NTP context, "the pool" is usually the
    http://www.pool.ntp.org/en/[NTP Pool Project], a collection of
    thousands of NTP servers accessible through DNS servers that hand
    out service addresses at random from the pool.
-  <<Mills-speak>> for "the transitive completion of the
+[[proventic]] proventic:: <<Mills-speak>> for "the transitive completion of the
   authentication relationship", defined in RFC5906. Time is proventic
   if it is provided by a chain of time servers between which packets
   are authenticated and the chain reaches back to Stratum 1.
+[[refclock]] refclock::
   Shorthand for a "reference clock", a primary time source. A computer
   with a refclock is implicitly Stratum 1.
+[[stratum]] stratum::
   A "stratum" is a layer in the hieratchy of time servers.  a
   <<refclock>> is considered stratum 0; a computer directly attached to
   a refclock is stratum 1; and a client served by a stratum N is
@@ -244,8 +215,7 @@ stratum::
   unusual to see a public timeserver with stratum > 3, and thus
   almost all NTP clients are at Stratum 4 or lower.
-time radio::
+[[time-radio]] time radio::
   A radio receiver specialized for picking up accurate time reference
   signals broadcast over the air by a national time authority; notable
   ones include <<WWVB>> (U.S.), CHU (Canada), DCF (Germany), MSF
@@ -257,22 +227,19 @@ time radio::
   used to be important time sources, but (especially in the U.S.) have
   been largely obsolesced by <<GPS>> and <<GPSDO>>-based clocks.
+[[truechimer]] truechimer::
   <<Mills-speak>> for a timeserver that provides time believed good,
   that is with low jitter with respect to UTC.  As with a
   link#falseticker[falseticker], this is usually less a property of
   the server itself than it is of favorable network topology.
+[[USNO]] USNO::
   http://www.usno.navy.mil/USNO[The United States Naval Observatory],
   one of the two U.S. national time authorities and the source of the
   U.S. military time reference, now delivered primarily by GPS
   signals. U.S. civil and military time agree to within nanoseconds.
+[[WWVB]] WWVB::
   http://www.nist.gov/pml/div688/grp40/wwvb.cfm[The U.S. national time
   radio station], run by <<NIST>> and broadcasting a highly accurate
   U.S. civil-time reference.  Formerly an important primary time

--- a/docs/outside-tools.txt
+++ b/docs/outside-tools.txt
@@ -15,12 +15,8 @@ include::includes/hand.txt[]
 == Table of Contents ==
 * link:#introduction[Introduction]
-* link:#basics[Configuration Basics]
-* link:#pool[Configuring Pool Servers]
-* link:#howmany[How Many Servers?]
-* link:#gps[Configuring A Local GPS]
-* link:#dhcp[Special considerations when using DHCP]
-* link:#sanity[Sanity-Checking Your Time Service]
+* link:#wireshark[Wireshark]
+* link:#nagios[Nagios]
@@ -32,12 +28,14 @@ who write tools for system administrators frequently have
 features and plugins designed to help you work with it. This
 page collects some references that may be useful.
 == Wireshark ==
 The https://www.wireshark.org/[Wireshark] protocol analyzer has
 support for displaying NTP packets with the fields broken out
 and interpreted.
 == Nagios ==
 The https://www.nagios.org/[Nagios] monitoring suite has native

View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/297b519ba6f6dbd9d2882952569f7e469aec6915...466fe02d00f7f58877b41275ac919b085783b676
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ntpsec.org/pipermail/vc/attachments/20161129/97b3c7a1/attachment.html>

More information about the vc mailing list