Commit 705feaff authored by James Browning's avatar James Browning Committed by Eric S. Raymond

strip header trailers 8

parent 5d077927
Pipeline #46081136 passed with stages
in 4 minutes and 47 seconds
= Kernel Model for Precision Timekeeping =
= Kernel Model for Precision Timekeeping
include::html.include[]
image:pic/alice61.gif[]
......@@ -6,7 +6,7 @@ image:pic/alice61.gif[]
Alice finds the kernel a house of cards.
== Related Links ==
== Related Links
include::includes/misc.adoc[]
......@@ -42,7 +42,7 @@ provide synchronization limited in principle only by the accuracy and
stability of the external timing source. Typical results with the PPS
signal from a GPS receiver and a modern computer are in the 3 μs range.
== References ==
== References
1. Mills, D.L., and P.-H. Kamp. The nanokernel. _Proc. Precision Time
and Time Interval (PTTI) Applications and Planning Meeting_ (Reston VA,
......
= PPSAPI Interface for Precision Time Signals =
= PPSAPI Interface for Precision Time Signals
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......@@ -8,13 +8,13 @@ include::html.include[]
|==============================
== Related Links ==
== Related Links
include::includes/misc.adoc[]
'''''
== Introduction ==
== Introduction
RFC 2783 describes the PPSAPI application programming interface for
external precision time signals, such as the pulse-per-second (PPS)
......@@ -44,7 +44,7 @@ NTP server as a reference clock. The driver can also use the PPSAPI as
an interface directly to the kernel PPS facility as described on the
link:kern.html[Kernel Model for Precision Timekeeping] page.
== PPSAPI Application Program Interface ==
== PPSAPI Application Program Interface
The PPSAPI interface provides the following functions:
......
= Leap Second Processing =
= Leap Second Processing
include::html.include[]
Every six months the International Earth Rotation Service
......
= Leap Second Smearing with NTP =
= Leap Second Smearing with NTP
include::html.include[]
By Martin Burnicki
......@@ -28,7 +28,7 @@ the normal NTP packet exchange, so clients also become aware of an
approaching leap second, and can handle the leap second appropriately.
== The Problem on Unix-like Systems ==
== The Problem on Unix-like Systems
If a leap second is to be inserted, then in most Unix-like systems the OS
kernel just steps the time back by 1 second at the beginning of the leap
......@@ -51,7 +51,7 @@ though this mechanism has been available for decades, almost
nobody uses it.
== The Leap Smear Approach ==
== The Leap Smear Approach
Due to the reasons mentioned above, some support for leap smearing has
recently been implemented in ntpd. This means that to insert a leap second
......@@ -79,7 +79,7 @@ transparent to the clients, and the clients don't even notice there's a
leap second.
== Pros and Cons of the Smearing Approach ==
== Pros and Cons of the Smearing Approach
The disadvantages of this approach are:
......@@ -98,7 +98,7 @@ better approach may be to slew the time in a well defined way, over a
certain interval, thus "smearing" the leap second.
== The Motivation to Implement Leap Smearing ==
== The Motivation to Implement Leap Smearing
Here is some historical background for ntpd, related to smearing/slewing
time.
......@@ -174,7 +174,7 @@ The leap smear implementation is optionally available in ntp-4.2.8p3 and
later, and the changes can be tracked via http://bugs.ntp.org/2855.
== Using NTP's Leap Second Smearing ==
== Using NTP's Leap Second Smearing
* Leap Second Smearing MUST NOT be used for public servers, e.g. servers
provided by metrology institutes, or servers participating in the NTP pool
......@@ -217,7 +217,7 @@ servers at the same time. During the smear interval they would get
different times from different servers and wouldn't know which server(s) to
accept.
== Setting Up A Smearing NTP Server ==
== Setting Up A Smearing NTP Server
If an NTP server should perform leap smearing then the leap smear interval
(in seconds) needs to be specified in the NTP configuration file ntp.conf,
......
= Miscellaneous Commands and Options =
= Miscellaneous Commands and Options
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......@@ -10,13 +10,13 @@ We have three, now looking for more.
|==============================
== Related Links ==
== Related Links
include::includes/miscopt.adoc[]
'''''
== Commands and Options ==
== Commands and Options
include::includes/misc-options.adoc[]
......
= Mode 6 Protocol =
= Mode 6 Protocol
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......@@ -10,11 +10,11 @@ Keeping control of the situation.
|==============================
== Related Links ==
== Related Links
include::includes/hand.adoc[]
== Table of Contents ==
== Table of Contents
* link:#intro[Introduction]
* link:#packet[Mode 6 packet structure]
......@@ -25,7 +25,7 @@ include::includes/hand.adoc[]
'''''
[[intro]]
== Introduction ==
== Introduction
This page describes the Mode 6 protocol used to get status information
from a running ntpd and configure some of its behaviors on the fly.
......@@ -38,7 +38,7 @@ the Python Mode 6 libraries included in the distribution. Both 'ntpq'
and 'ntpmon' use these.)
[[packet]]
== Mode 6 packet structure ==
== Mode 6 packet structure
The protocol uses UDP packets transmitted and received over port 123.
They use the same structure (header, plus extension, plus optional
......@@ -103,7 +103,7 @@ it's 500 octets, which is far in excess of any plausible request or
response size in the actual protocol.
[[varlists]]
== Variable-Value Lists ==
== Variable-Value Lists
Several requests and responses (in fact, all but one) use a common
textual payload format consisting of a comma-separated list of items.
......@@ -148,7 +148,7 @@ quoted-string = %x22 *(%21 | %x23-7E) %x22
-----------------------------------------------------------
[[requests]]
== Mode 6 Requests ==
== Mode 6 Requests
Request-response types are distinguished by operation codes. The
table below lists them all. The "Auth?" column tells whether a
......@@ -177,7 +177,7 @@ software. CTL_OP_WRITECLOCK is unimplemented and will throw a
permission error. CTL_OP_ASYNCMSG is reserved for expansion. The
remaining opcodes are as follows:
=== CTL_OP_READSTAT ===
=== CTL_OP_READSTAT
This requests ntpd to ship up a list of association IDs and status
words for all peers currently associated with the ntpd instance. It
......@@ -197,7 +197,7 @@ divided by 4.
Interpretation of the peer status word is described
link:decode.html#peer[here].
=== CTL_OP_READVAR ===
=== CTL_OP_READVAR
This requests ntpd to ship up a list of peer variable settings for an
association specified by ID, or system variables if the ID is zero. It
......@@ -209,7 +209,7 @@ calls for a report on all known variables.
The response payload is a textual varlist.
=== CTL_OP_WRITEVAR ===
=== CTL_OP_WRITEVAR
Some system variable are defined as being settable from a mode 6
client. This request provides a general way to do that. It requires
......@@ -223,7 +223,7 @@ association ID of 0. There is no response payload.
No system variables are currently settable. This may change in a
future release.
=== CTL_OP_READCLOCK ===
=== CTL_OP_READCLOCK
This requests ntpd to ship up a list of peer variable settings for a
reference clock association specified by ID. It does not require
......@@ -235,7 +235,7 @@ calls for a report on all known variables.
The response payload is a textual varlist.
=== CTL_OP_CONFIGURE ===
=== CTL_OP_CONFIGURE
This request is used to change the configuration of ntpd without
restarting the daemon. It requires authentication.
......@@ -248,7 +248,7 @@ Note: Due to an implementation error, the response packet may and
typically will contain trailing garbage. Implementations should
expect this and truncate it at the first NUL.
=== CTL_OP_READ_MRU ===
=== CTL_OP_READ_MRU
This request is used to retrieve information about recent traffic
between ntpd and its clients and peers; in NTP-speak this traffic summary is
......@@ -398,7 +398,7 @@ displaying or passing on the report (that is, as opposed to
incremental display with an attempt to suppress stale records on the
fly).
=== CTL_OP_READ_ORDLIST_A ===
=== CTL_OP_READ_ORDLIST_A
This request is used for two purposes: to retrieve restriction lists
and to retrieve interface statistics. For the former use, the request
......@@ -480,7 +480,7 @@ up.#:: Uptime in seconds.
|INT_BCASTXMIT | 0x400 | socket setup to allow broadcasts
|==========================================================================
=== CTL_OP_REQ_NONCE ===
=== CTL_OP_REQ_NONCE
This request is used to initialize an MRU-list conversation. It
informs ntpd that the Mode 6 client is ready to receive. It does
......@@ -504,7 +504,7 @@ the last nonce transmission time in your client and re-request based
on that.
[[auth]]
== Authentication ==
== Authentication
Authenticated requests require a MAC (message authentication code)
trailer following the payload data, if any. Such requests must be
......@@ -528,7 +528,7 @@ octets for SHA-1. Longer digests are truncated.
The key length for AES is 16 bytes. Longer keys are truncated. Shorter
keys are padded with 0s. MD5 and SHA-1 can use any key length.
== Compatibility Notes ==
== Compatibility Notes
The "recent" parameter of CTL_OP_READ_MRU is not supported in versions
prior to NTPsec 0.9.6.
......
= Monitoring Commands and Options =
= Monitoring Commands and Options
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......@@ -10,11 +10,11 @@ Pig was hired to watch the logs.
|==============================
== Related Links ==
== Related Links
include::includes/monopt.adoc[]
== Table of Contents ==
== Table of Contents
* link:#intro[Naming Conventions]
* link:#cmd[Monitoring Commands and Options]
......@@ -23,7 +23,7 @@ include::includes/monopt.adoc[]
'''''
[[intro]]
== Naming Conventions ==
== Naming Conventions
The +ntpd+ daemon includes a comprehensive monitoring facility which
collects statistical data of various types and writes the data to
......@@ -48,7 +48,7 @@ There is a visualization tool, link:ntpviz.html[ntpviz], which assists
in making sense of statistics files.
[[cmd]]
== Monitoring Commands and Options ==
== Monitoring Commands and Options
Unless noted otherwise, further information about these commands is on
the link:decode.html[Event Messages and Status Codes] page.
......
= ntpd System Log Messages =
= ntpd System Log Messages
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......@@ -11,7 +11,7 @@ The log can be shrill at times.
|==============================
== Related Links ==
== Related Links
include::includes/install.adoc[]
......@@ -32,20 +32,20 @@ something about the system operations, but do not affect the time.
In the following a \'?' character stands for text in the message. The
meaning should be clear from context.
== Protocol Module ==
== Protocol Module
=== LOG_ERR ===
=== LOG_ERR
+buffer overflow ?+::
Fatal error. An input packet is too long for processing.
=== LOG_NOTICE ===
=== LOG_NOTICE
+no reply; clock not set+::
No servers have been found. The server(s) and/or
network may be down. Standard debugging procedures apply.
=== LOG_INFO ===
=== LOG_INFO
+proto_config: illegal item ?, value ?+::
Program error. Bugs can be reported link:bugs.html[here].
......@@ -64,9 +64,9 @@ meaning should be clear from context.
The system clock is running on internal batteries. The server(s)
and/or network may be down.
== Clock Discipline Module ==
== Clock Discipline Module
=== LOG_ERR ===
=== LOG_ERR
--
+time correction of ? seconds exceeds sanity limit (?); set clock manually to the correct UTC time+. ::
Fatal error. Better do what it says, then restart the daemon. Be advised
......@@ -79,7 +79,7 @@ meaning should be clear from context.
Program error. Bugs can be reported link:bugs.html[here].::
--
=== LOG_NOTICE ===
=== LOG_NOTICE
+frequency error ? exceeds tolerance 500 PPM+::
The hardware clock frequency error exceeds the rate the kernel can
......@@ -97,7 +97,7 @@ meaning should be clear from context.
The PPS signal has died, probably due to a dead radio, broken wire or
loose connector.
=== LOG_INFO ===
=== LOG_INFO
+kernel time sync status ?+::
For information only. See the codes in the +timex.h+ file.
......
= Differences from NTP Classic =
= Differences from NTP Classic
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......@@ -8,13 +8,13 @@ include::html.include[]
Accept no imitations.
|==============================
== Related Links ==
== Related Links
* A list of all links is on the link:sitemap.html[Site Map] page.
'''''
== Table of Contents ==
== Table of Contents
* link:#intro[Introduction]
* link:#incompatible[Incompatible Changes]
......@@ -24,7 +24,7 @@ Accept no imitations.
* link:#other[Other user-visible changes]
[[intro]]
== Introduction ==
== Introduction
The design objectives of this distribution, NTPsec, are in
many ways a break with NTP's past. We have deliberately jettisoned
......@@ -47,7 +47,7 @@ Most of the changes are under the hood, internal to the codebase. A
few will be user-visible.
[[incompatible]]
== Incompatible Changes ==
== Incompatible Changes
Normally NTPsec is a drop-in replacement for legacy versions. We have
tried to hold incompatible changes to a minimum, but there are a
......@@ -95,7 +95,7 @@ a build-time switch, not a run-time one).
of at least two CVEs.
[[security]]
== Security Improvements ==
== Security Improvements
We have spent more effort than anything else on reducing attack
surface and hardening code. In toto, more than 74% of the NTP Classic
......@@ -154,7 +154,7 @@ to the security-critical core.
copy and formatting functions replaced by safe (bounded) ones.
[[timesync]]
== Time-synchronization improvements ==
== Time-synchronization improvements
* Internally, there is more consistent use of nanosecond precision.
A visible effect of this is that time stepping with sufficiently
......@@ -180,7 +180,7 @@ to the security-critical core.
code was lost without trace by the time NTPsec forked.
[[clients]]
== Client Tool Improvements ==
== Client Tool Improvements
* A new tool, +ntpmon+, performs real-time monitoring of your
peer and MRU status with efficient (least-cost) querying.
......@@ -226,7 +226,7 @@ to the security-critical core.
* ntpq displays the root distance (aka. synchronization distance) in the
sysinfo command.
== Configuration Improvements ==
== Configuration Improvements
* The notorious collision between pool and nopeer in older
implementations has been fixed; the pool keyword is now fully
......@@ -294,7 +294,7 @@ to the security-critical core.
option.
[[other]]
== Other user-visible changes ==
== Other user-visible changes
* The documentation has been extensively updated and revised. One
important change is that manual pages are now generated from the
......@@ -302,7 +302,7 @@ to the security-critical core.
drift out of synchronization.
[[future]]
== Future directions ==
== Future directions
* We intend to fully support Network Time Security and to be first or
second interop on that standard once it is finalized. At that
......
= A Glossary of NTP-speak =
= A Glossary of NTP-speak
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......
= Motorola ONCORE - The Shared Memory Interface =
= Motorola ONCORE - The Shared Memory Interface
include::html.include[]
== Introduction ==
== Introduction
In NMEA mode, the Oncore GPS receiver provides the user with the same
information as other GPS receivers. In BINARY mode, it can provide a lot
......@@ -30,7 +30,7 @@ This interface was written by Poul-Henning Kamp (phk@FreeBSD.org), and
modified by Reg Clemens (reg@dwf.com). The interface is known to work in
FreeBSD, Linux, and Solaris.
== Activating the Interface ==
== Activating the Interface
Although the Shared Memory Interface will be compiled into the Oncore
driver on those systems where Shared Memory is supported, to activate
......@@ -66,7 +66,7 @@ like
would be required.
== Storage of Messages in Shared Memory ==
== Storage of Messages in Shared Memory
With the shared memory interface, the oncore driver (refclock_oncore)
allocates space for all of the messages that it is configured to
......@@ -139,7 +139,7 @@ appropriate slot. The additional slots are for messages containing 0D,
2D and 3D positions. These messages can be distinguished by different
bit patterns in the last data byte of the record.
== Opening the Shared Memory File ==
== Opening the Shared Memory File
The shared memory segment is accessed through a file name given on a
*SHMEM* card in the +/etc/ntp.oncore+ input file. The following code
......@@ -168,7 +168,7 @@ could be used to open the Shared Memory Segment:
}
---------------------------------------------------------------------------------
== Accessing the data ==
== Accessing the data
The following code shows how to get to the individual records.
......@@ -241,7 +241,7 @@ messages that we want to examine, and the name of a program to call when
a new message of that type is arrives. The loop can be run every few
seconds to check for new data.
== Examples ==
== Examples
There are two complete examples available. The first plots satellite
positions and the station position as affected by SA, and keeps track of
......
= Orphan Mode =
= Orphan Mode
include::html.include[]
Sometimes an NTP subnet becomes isolated from all UTC sources such as
......
= Outside Tools =
= Outside Tools
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......@@ -9,11 +9,11 @@ include::html.include[]
|==============================
== Related Links ==
== Related Links
include::includes/hand.adoc[]
== Table of Contents ==
== Table of Contents
* link:#introduction[Introduction]
* link:#wireshark[Wireshark]
......@@ -23,7 +23,7 @@ include::includes/hand.adoc[]
'''''
[[introduction]]
== Introduction ==
== Introduction
Because NTP is a widely-used an well-established service, people
who write tools for system administrators frequently have
......@@ -31,21 +31,21 @@ features and plugins designed to help you work with it. This
page collects some references that may be useful.
[[wireshark]]
== Wireshark ==
== Wireshark
The https://www.wireshark.org/[Wireshark] protocol analyzer has
support for displaying NTP packets with the fields broken out
and interpreted.
[[nagios]]
== Nagios ==
== Nagios
The https://www.nagios.org/[Nagios] monitoring suite has native
support for querying NTP servers. The 'check_ntp_peer' and
'check_ntp_time' programs may be of particular interest.
[[netdata]]
== Netdata ==
== Netdata
The https://github.com/firehol/netdata/wiki[Netdata] monitoring
solution has native support for realtime monitoring of ntpd,
......
= NTP PARSE clock data formats =
= NTP PARSE clock data formats
include::html.include[]
The parse driver currently supports several clocks with different query
......@@ -9,7 +9,7 @@ parse/clk_*.c and ntpd/refclock_parse.c files).
'''''
== Meinberg clocks ==
== Meinberg clocks
------------------------------------------------------------------------------
Meinberg: start=<STX>, end=<ETX>, sync on start
......@@ -155,7 +155,7 @@ there may be a special firmware version available.
'''''
== Raw DCF77 Data via serial line ==
== Raw DCF77 Data via serial line
RAWDCF: end=TIMEOUT>1.5s, sync each char (any char),generate pseudo time
codes, fixed format
......@@ -177,7 +177,7 @@ one minute. A bit of the time code is sent once a second.
LFLAG 0
----------------------------------------------
== DCF77 raw time code ==
== DCF77 raw time code
From "Zur Zeit", Physikalisch-Technische Bundesanstalt (PTB),
......@@ -232,7 +232,7 @@ encoding:
'''''
== Schmid clock ==
== Schmid clock
Schmid clock: needs poll, binary input, end='\xFC', sync start
......@@ -273,7 +273,7 @@ for the lsb is sent first).
'''''
== Trimble SV6 ASCII time code (TAIP) ==
== Trimble SV6 ASCII time code (TAIP)
Trimble SV6: needs poll, ascii timecode, start='>', end='<',
query='>QTM<', eol='<'
......@@ -307,7 +307,7 @@ Special flags are:
'''''
== ELV DCF7000 ==
== ELV DCF7000
ELV DCF7000: end='\r', pattern=" - - - - - - - \r"
......@@ -325,7 +325,7 @@ code (though not very precise!) delimited by '\r'
'''''
== HOPF 6021 und Kompatible ==
== HOPF 6021 und Kompatible
HOPF Funkuhr 6021 mit serieller Schnittstelle Created by F.Schnekenbuehl
<frank@comsys.dofn.de> from clk_rcc8000.c Nortel DASA Network Systems
......@@ -384,7 +384,7 @@ Type 6021 Serial Output format
'''''
== Diem Computime Clock ==
== Diem Computime Clock
The Computime receiver sends a datagram in the following format every
minute
......@@ -409,7 +409,7 @@ minute
'''''
== WHARTON 400A Series Clock with a 404.2 Serial interface ==
== WHARTON 400A Series Clock with a 404.2 Serial interface
The WHARTON 400A Series clock is able to send date/time serial messages
in 7 output formats. We use format 1 here because it is the shortest. We
......
= Poll Process =
= Poll Process
include::html.include[]
The poll process sends NTP packets at intervals determined by the clock
......
= Pulse-Per-Second (PPS) Signal Interfacing =
= Pulse-Per-Second (PPS) Signal Interfacing
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......@@ -10,11 +10,11 @@ Alice is trying to find the PPS signal connector.
|==============================
== Related Links ==
== Related Links
include::includes/misc.adoc[]
== Table of Contents ==
== Table of Contents
* link:#intro[Introduction]
* link:#opsys[Operating System Support]
......@@ -23,7 +23,7 @@ include::includes/misc.adoc[]
'''''
[[intro]]
== Introduction ==
== Introduction
Most conventional time sources (radio clocks and GPSes) are connected
using a serial or USB port operating at speeds of 9600 bps. The
......@@ -49,7 +49,7 @@ serial port interface signals. Note that NTPsec no
longer supports connection via the RD pin of a serial port.
[[opsys]]
== Operating System Support ==
== Operating System Support
Both the serial and parallel port connection require operating system
support, which is available in a few operating systems, including
......@@ -61,7 +61,7 @@ The interface consists of the +timepps.h+ header file, which should be
in the /usr/include/ or /usr/include/sys directory of your file
system.
== PPS Driver ==
== PPS Driver
PPS support is built into some drivers, in particular the NMEA
driver, and may be added to other drivers in future. Alternatively,
......@@ -76,7 +76,7 @@ Internet server could be designated preferred. Note that the +pps+
configuration command has been obsoleted by this driver.
[[use]]
== Using the Pulse-per-Second (PPS) Signal ==
== Using the Pulse-per-Second (PPS) Signal
The PPS signal can be used in three ways: using the NTP
grooming and mitigation algorithms, or using the kernel PPS
......
= Mitigation Rules and the prefer Keyword =
= Mitigation Rules and the prefer Keyword
include::html.include[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
......@@ -10,11 +10,11 @@ Listen carefully to what I say; it is very complicated.
|==============================
== Related Links ==
== Related Links
include::includes/misc.adoc[]
== Table of Contents ==
== Table of Contents
* link:#intro[Introduction and Overview]
* link:#combine[Combine Algorithm]
......@@ -27,7 +27,7 @@ include::includes/misc.adoc[]
'''''
[[intro]]
== Introduction and Overview ==
== Introduction and Overview
This page summarizes the criteria for choosing from among the survivors
of the clock cluster algorithm a set of contributors to the clock
......@@ -70,7 +70,7 @@ directly, as described on the link:kern.html[A Kernel Model for
Precision Timekeeping] page.
[[combine]]
== Combine Algorithm ==
== Combine Algorithm
The clock combine algorithm uses the survivor list to produce a weighted
average of both offset and jitter. Absent other considerations discussed
......@@ -86,7 +86,7 @@ survivors at the smallest root distance and thus the smallest maximum
error.
[[clockhop]]
== Anti-Clockhop Algorithm ==
== Anti-Clockhop Algorithm
The anti-clockhop algorithm is intended for cases where multiple servers
are available on a fast LAN with modern computers. Typical offset
......@@ -117,7 +117,7 @@ operation continue in this way, the candidate peer will eventually
become the system peer.
[[peer]]
== Peer Classification ==
== Peer Classification
The behavior of the various algorithms and mitigation rules involved
depends on how the various synchronization sources are classified. This
......@@ -160,7 +160,7 @@ backup source, should all other sources fail, or as the primary source
if the +prefer+ option is present.
[[prefer]]
== The +prefer+ Peer ==
== The +prefer+ Peer
The mitigation rules are designed to provide an intelligent selection of
the system peer from among the selectable sources of different types.
......@@ -194,7 +194,7 @@ becomes a falseticker, the combined backup sources continue to
discipline the system clock.
[[miti]]
== Mitigation Rules ==
== Mitigation Rules
As the select algorithm scans the associations for selectable
candidates, the modem driver and local driver are segregated for later,
......@@ -250,7 +250,7 @@ If none of the above is the case, the data are disregarded and the