[Git][NTPsec/ntpsec][master] 36 commits: Lexical cleanups
Richard Laager
gitlab at mg.gitlab.com
Sat Dec 14 04:16:01 UTC 2019
Richard Laager pushed to branch master at NTPsec / ntpsec
Commits:
50e15694 by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Lexical cleanups
- - - - -
dd01d6af by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Expand and clarify pool usage
- - - - -
f8c617ac by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Add section on NTS in quick start, pointing to NTS Quick Start
- - - - -
577932f0 by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Update and proofread NTS Quick Start
Add netnod servers
Add our boilerplate
Other syntax fixes
- - - - -
74326a08 by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Fix some links
- - - - -
5d92bd84 by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Add links both ways, between quick and quick-NTS
Fixes #623
- - - - -
b2bb3196 by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Expand References and Citations
Welcome to wikipedia :-)
- - - - -
8e7b0654 by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Reword the link to pool information
Signed-off-by: Richard Laager <rlaager at wiktel.com>
- - - - -
12a3d911 by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Correct Let's Encrypt spelling
Caught by Richard Laager, thank you.
- - - - -
44c5c3e1 by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Signal ntpd to pick up new or renewed certificate
Thanks, Richard
- - - - -
574ae81d by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Correctly de-capitalise 'Certificate'
- - - - -
4e2ab511 by Sanjeev Gupta at 2019-12-14T04:05:11+00:00
Lots of typo and spelling fixes
Thanks, Richard
- - - - -
d29db228 by Richard Laager at 2019-12-14T04:05:11+00:00
Cleanup NTS client/server docs headers
- - - - -
d57c3c6c by Richard Laager at 2019-12-14T04:05:11+00:00
Expand "Dec" to "December" in the NTS docs
Suggested-by: James Browning <jamesb.fe80 at gmail.com>
- - - - -
7a44a5fe by Richard Laager at 2019-12-14T04:05:11+00:00
Add back a note about TLS 1.3 to NTS docs
- - - - -
c24e98fc by Richard Laager at 2019-12-14T04:05:11+00:00
Revert remote server back to server in NTS docs
- - - - -
d7e88837 by Richard Laager at 2019-12-14T04:05:11+00:00
Fix a typo in the NTS docs
- - - - -
eb6bd1b8 by Richard Laager at 2019-12-14T04:05:11+00:00
Cleanup the NTS key/certificate mentions
A certificate is not quite the same as a public key. Also, I've
expanded the details on what it means to be "fully chained up".
Rather than using the name of an actual server (which is mentioned above
as such, and thus could be confusing), use "ntp.example.com".
- - - - -
5cb824f2 by Richard Laager at 2019-12-14T04:05:11+00:00
Standardize NTP Pool name and terminology
Sanjeev Gupta wanted to capitalize Pool because we are referring to the
specific pool. I standardized "the NTP Pool", which is something the
NTP Pool website uses to refer to itself.
I also cleaned up some terminology around "subdomains".
- - - - -
e65c88da by Richard Laager at 2019-12-14T04:05:11+00:00
Cleanup more of the pool documentation
- - - - -
5609f580 by Richard Laager at 2019-12-14T04:05:11+00:00
Cleanup various things in the quickstart docs
- - - - -
88621e92 by Richard Laager at 2019-12-14T04:05:11+00:00
Expand the DHCP notes in the quickstart docs
- - - - -
616ad778 by Richard Laager at 2019-12-14T04:05:11+00:00
Rework the pool quickstart guide
This merges the two sections with pool examples together. It also
addresses the following issues:
1. The claim about the Ubuntu config is simply wrong. It does not look
like the documentation said it does.
2. The existing example "pool ubuntu.pool.ntp.org" is wrong, as vendor
subdomains do not resolve without a number. In other words, that
example did not even work.
3. Only the "2.(vendor.)pool.ntp.org" names currently support IPv6 (i.e.
return AAAA records).
- - - - -
977102f1 by Richard Laager at 2019-12-14T04:05:11+00:00
Bring more consistency to the docs
- - - - -
d9aa1c0d by Richard Laager at 2019-12-14T04:05:11+00:00
Merge more duplicated pool documentation
- - - - -
39138c27 by Richard Laager at 2019-12-14T04:05:11+00:00
Improve the maxclock documentation
This documents everything I've learned about maxclock:
- Pool entries count towards maxclock, but not minclock. This is
arguably a bug, but it is the current behavior and changing it
breaks backwards compatibility to some degree.
I posted my experiences here:
https://lists.ntpsec.org/pipermail/devel/2019-November/008858.html
saying:
I have a number of systems with "tos maxclock 11" set explicitly
and their steady state is 4 pool entries and 7 actual
associations.
Hal confirmed here:
https://lists.ntpsec.org/pipermail/devel/2019-November/008859.html
saying:
It uses working slots on the min test but counts pool on
the max test.
- maxclock should be an odd number.
I posted here:
https://lists.ntpsec.org/pipermail/devel/2019-November/008856.html
saying:
http://support.ntp.org/bin/view/Support/SelectingOffsiteNTPServers
says "the general rule is for 2n+1 to protect against 'n'
falsetickers". (It goes on to discuss the exception for n=1, which
is not relevant here.)
If that's true, then it seems like odd numbers of servers are
better, all things being equal.
- I kept the existing bit about maxclock typically being two greater
than minclock, but expanded that to "two or three" to be consistent
with the goal of maxclock being an odd number.
I also added a note about a typical minclock value being 3. This allows
for protecting against one falseticker.
- - - - -
c743fa9a by Richard Laager at 2019-12-14T04:05:11+00:00
Cleanup the NTS Quick Start Guide some more
Among other things, this removes the mention of one hour cookie
rotation. As noted, that was for testing, but it was removed in 1.1.7.
- - - - -
dc0b9e8e by Richard Laager at 2019-12-14T04:05:11+00:00
Replace more ntp.conf with {ntpconf}
- - - - -
f89616a6 by Richard Laager at 2019-12-14T04:05:11+00:00
Make some minor fixes to the docs
- - - - -
ee4c05cf by Richard Laager at 2019-12-14T04:05:11+00:00
Rip out the details on manycast
This is a partial fix for #622.
- - - - -
123971b2 by Richard Laager at 2019-12-14T04:05:11+00:00
Cleanup more pool docs
- - - - -
5977a4b9 by Richard Laager at 2019-12-14T04:05:11+00:00
Eliminate docs/pic/panda.adoc
Everything in docs/pic is installed directly. That is appropriate for
image files, but not for panda.adoc.
I moved the historical note into ntplogtemp.adoc, which uses panda.gif.
This addresses my comment in #622.
- - - - -
e6346ed4 by Richard Laager at 2019-12-14T04:05:11+00:00
Fix the docs some more
These changes were from the review of my previous changes.
Suggested-by: James Browning <jamesb.fe80 at gmail.com>
- - - - -
c076bda9 by Richard Laager at 2019-12-14T04:05:11+00:00
Remove the "restrict -6" examples
These are no longer necessary. I remember this being changed a while
back, but I also personally tested just now that "restrict default"
applies equally to IPv4 and IPv6.
- - - - -
4a4f6069 by Richard Laager at 2019-12-14T04:05:11+00:00
Reword the NTP Pool NTS limitation
This makes it more clear that this is not an NTPsec limitation.
- - - - -
d941e8d0 by Richard Laager at 2019-12-14T04:05:11+00:00
More improvements to docs consistency
- - - - -
19 changed files:
- docs/NTS-QuickStart.adoc
- docs/assoc.adoc
- docs/authentic.adoc
- docs/build.adoc
- docs/confopt.adoc
- docs/debug.adoc
- docs/discover.adoc
- docs/includes/assoc-commands.adoc
- docs/includes/install.adoc
- docs/includes/ntpd-body.adoc
- docs/includes/ntpkeygen-body.adoc
- docs/includes/ntpq-body.adoc
- docs/index.adoc
- docs/miscopt.adoc
- docs/ntplogtemp.adoc
- docs/ntpsec.adoc
- docs/ntpspeak.adoc
- − docs/pic/panda.adoc
- docs/quick.adoc
Changes:
=====================================
docs/NTS-QuickStart.adoc
=====================================
@@ -1,4 +1,4 @@
-= Quick way to get NTS working
+= NTS Quick Start Guide
include::include-html.ad[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
@@ -11,83 +11,113 @@ For putting out compiler fires.
|==============================
+== Related Links
+
+include::includes/hand.adoc[]
+
+== Table of Contents
+
+* link:#introduction[Introduction]
+* link:#client[NTS Client Configuration]
+* link:#server[NTS Server Configuration]
+* link:#verify[Verification]
+* link:#refer[References]
+
+'''''
+
+[[introduction]]
+== Introduction
+
NTS is a method for using TLS/SSL to authenticate NTP traffic on the net.
That means that bad guys can't forge packets that will give your
system bogus time.
-The RFC hasn't been published yet (June 2019). Nothing has changed
+The RFC hasn't been published yet (December 2019). Nothing has changed
recently, but there may be minor adjustments when it is finalized.
-== ntp.conf (you are a client)
+Note: The NTP Pool does not currently support NTS.
+
+It is strongly suggested that you get a "normal", unauthenticated,
+NTP server working before enabling NTS. This may reduce the time
+spent debugging. See the link:quick.adoc[Client Quick Start Guide].
+
+[[client]]
+== NTS Client Configuration
-Append the keyword `nts` to the end of your `server`
-lines. Do these only for servers that speak NTS. As of
-June 2019, the following should work:
+Append the keyword `nts` to the end of your `server` lines. Do this only for
+servers that speak NTS. If the server uses a port other than 123 for NTS key
+exchange, you also need to specify the port number. As of December 2019, the
+following should work:
Public NTP servers supporting NTS:
------------------------------------------------------------
-server time.cloudflare.com:1234 nts # TLS1.3 only
+server time.cloudflare.com:1234 nts # Global, anycast
+server nts.ntp.se:4443 nts # Sweden
------------------------------------------------------------
+CloudFlare supports only TLS 1.3. To use TLS 1.3, you must have OpenSSL 1.1.1
+or higher.
+
Development machines, so there may be gaps in availability:
------------------------------------------------------------
-server ntpmon.dcs1.biz nts
-server pi4.rellim.com nts
-server ntp1.glypnod.com nts
-server ntp2.glypnod.com nts
+server ntpmon.dcs1.biz nts # Singapore
+server ntp1.glypnod.com nts # San Francisco
+server ntp2.glypnod.com nts # London
------------------------------------------------------------
Note that you must use the same host name that was used to create
-the server's certificate. IP Addresses will not work.
+the server's certificate. IP addresses will not work.
This assumes that the server is using a certificate covered by
-your OS/distro's root server collection.
-
-Restart `ntpd`, and skip to <<Verification>>, below.
+your OS/distro's root certificate collection.
+Restart `ntpd`, and skip to link:#verify[Verification], below.
-== ntp.conf (you are a server)
+[[server]]
+== NTS Server Configuration
Being an NTS server requires a well-formed SSL certificate. The
-easiest way to do this is to use LetsEncrypt. It needs a FQDN.
-Please see the Certbot client site
-[[https://certbot.eff.org/]] for instructions.
+easiest way to do this is to use Let's Encrypt. It needs a FQDN.
+Please see the
+https://certbot.eff.org/[certbot client site] for instructions.
The following worked on Fedora:
------------------------------------------------------------
-]$ sudo dnf install certbot
+$ sudo dnf install certbot
# Install
-]$ sudo certbot certonly --standalone
+$ sudo certbot certonly --standalone
# Renew
-]$ sudo certbot renew
+$ sudo certbot renew
+$ sudo killall -HUP ntpd
------------------------------------------------------------
-If you already have an SSL Cert for your server, and you are
-serving time using the same FQDN, you can reuse that Cert.
+If you already have an SSL certificate for your server, and you are
+serving time using the same FQDN, you can reuse that certificate.
-Add the line:
+Next, add the line:
`nts enable`
-to your conf file.
+to your +{ntpconf}+ file.
Locate the following two files:
-* Your Cert Private Key
-* Your Cert Public Key, fully chained up
+* Your certificate private key
+* Your certificate chain (i.e. your certificate followed by any intermediate
+ CA certificates)
-Then add the lines below to your ntp.conf, replacing
+Then add the lines below to your +{ntpconf}+, replacing
with your pathnames.
-Example, using LetsEncrypt:
+Example, using Let's Encrypt:
------------------------------------------------------------
-nts key /etc/letsencrypt/live/ntpmon.dcs1.biz/privkey.pem
-nts cert /etc/letsencrypt/live/ntpmon.dcs1.biz/fullchain.pem
+nts key /etc/letsencrypt/live/ntp.example.com/privkey.pem
+nts cert /etc/letsencrypt/live/ntp.example.com/fullchain.pem
------------------------------------------------------------
Note that `ntpd` must be able to read both files and you want to
@@ -103,14 +133,17 @@ Some distros use `/var/db/` rather than `/var/lib/`.
nts cookie /var/lib/ntp/nts-keys
------------------------------------------------------------
-Restart your server, and skip to <<Verification>>, below.
+Restart your server, and skip to link:#verify[Verification], below.
+[[verify]]
== Verification
-Check your log file.
+Check your log file. The current NTS implementation is quite chatty, and the
+log lines may change, so what you see will be similar, but not the same,
+as below.
-For each client, you should see lines like this:
+As a client, you should see lines like this:
------------------------------------------------------------
2019-03-22T08:06:33 ntpd[12915]: DNS: dns_probe: pi3.rellim.com, cast_flags:1, flags:21801
@@ -157,9 +190,8 @@ Each one will produce log lines like this:
10 Jun 04:55:11 ntpd[823]: NTS: error:1408F10B:SSL routines:ssl3_get_record:wrong version number
------------------------------------------------------------
-The logging prefix *NTSs* is for the NTS Server component, eg
-initializing your keys. The *NTSc* component is for the NTS Client
-part, where you are talking to *other* NTS servers.
+The logging prefix *NTSs* is for the NTS server component. The *NTSc*
+component is for the NTS client part, where you are talking to NTS servers.
=== Check with ntpq
@@ -187,14 +219,11 @@ The RFC calls for the server to rotate the private key used to
encrypt cookies every 24 hours. The server also saves the previous
key so old cookies will work for at least 24 hours. 24 hours and 8 cookies
will work for a polling interval of up to 3 hours. That's much longer
-than the default max of 1024 seconds. For testing, the server currently
-rotates keys every hour so cookies won't work if the polling interval
-gets over 450 seconds. The largest power of 2 that will work is 256, or
-8 in the `ntpq -p` `poll` column.
+than the default +maxpoll+ of 10 (1024 seconds).
=== Check ntp variables
-Try `ntpq -c nts` . This will show various counters related
+Try `ntpq -c nts`. This will show various counters related
to NTS. This feature is under active development, so the
format might change. An example:
@@ -217,5 +246,17 @@ NTS KE serves: 75
NTS KE serves_bad: 56
------------------------------------------------------------
+
+[[refer]]
+== References
+
+
+* https://datatracker.ietf.org/doc/draft-ietf-ntp-using-nts-for-ntp/[Current Status of NTS Draft]
+* https://developers.cloudflare.com/time-services/nts/usage/[Cloudflare Public NTS Servers]
+* https://www.netnod.se/blog/what-network-time-security-and-why-it-important[Netnod NTS Service]
+* https://datatracker.ietf.org/meeting/106/materials/slides-106-ntp-nts-deployment-03.pdf[Deployment Review]
+
+'''''
+
include::includes/footer.adoc[]
=====================================
docs/assoc.adoc
=====================================
@@ -63,8 +63,8 @@ client (mode 3) request to the specified server and expects a server
described as a "pull" operation, in that the host pulls the time and
related values from the server.
-A host is configured in client mode using the +server+ (sic)
-or +pool+ command and specifying the server DNS name or IPv4 or
+A host is configured in client mode using the +server+ or +pool+
+command and specifying the server DNS name or IPv4 or
IPv6 address; the server requires no prior configuration (but
see link:access.html[Access Control]). The +iburst+ option described
later on this page is recommended for clients, as this speeds up initial
@@ -122,7 +122,7 @@ NTP broadcast modes are intended for configurations
involving one or a few servers and a possibly very large client
population. Broadcast mode can be used with Ethernet, FDDI and WiFi
spans interconnected by hubs or switches. Ordinarily, broadcast packets
-do not extend beyond a level-3 router.
+do not extend beyond a router.
A server is configured to send broadcast messages using the
+broadcast+ command and specifying the subnet address for broadcast.
@@ -130,15 +130,9 @@ A server is configured to send broadcast messages using the
[[many]]
== Manycast and Pool Modes
-Manycast and pool modes are automatic discovery and configuration
-paradigms. They are intended as a means for a client to troll the
-nearby network neighborhood to find cooperating willing servers,
-validate them using cryptographic means and evaluate their time values
-with respect to other servers that might be lurking in the
-vicinity. The intended result is that each client mobilizes ephemeral
-client associations with some number of the "best" of the nearby
-servers, yet automatically reconfigures to sustain this number of
-servers should one or another fail. Additional information is on the
+Manycast is no longer supported by NTPsec.
+
+For more information on pool mode, see the
link:discover.html[Automatic Server Discovery Schemes] page.
[[poll]]
=====================================
docs/authentic.adoc
=====================================
@@ -204,14 +204,13 @@ for the +ntpq+ utility.
[[nts]]
== Network Time Security
-NTS (Network Time security) uses the TLS public-key encryption
+Network Time security (NTS) uses the TLS public-key encryption
infrastructure to secure and authenticate associations.
This section is a placeholder for complete documentation on NTS. The
NTS implementation is work in progress conforming to a draft RFC not
-yet (Aug 2019) accepted. A Quick Start Guide on the current implementation
-of NTS is available at
-link:NTS-QuickStart.html[Quick way to get NTS working] .
+yet (December 2019) accepted. For configuration examples, see the
+link:NTS-QuickStart.html[NTS Quick Start Guide].
NTPsec's future direction is to fully support NTS and eventually
remove older, insecure authentication methods.
@@ -231,10 +230,10 @@ users. Therefore, this flag should be used only for a dedicated server
with no clients other than MS-SNTP.*
[[autokey]]
-== Autokey
+== Autokey
Old versions of NTP supported Autokey, which used an early form of
-public-key cryptography for authentication. It was described in RFC 5906.
+public-key cryptography for authentication. It is described in RFC 5906.
Unfortunately, autokey was buggy and a source of vulnerabilities; it
has been removed. NTS is intended to replace it. It is mentioned here
=====================================
docs/build.adoc
=====================================
@@ -73,10 +73,10 @@ the executables by default in +/usr/local/bin+.
You are now ready to configure the daemon. You will need to create an NTP
configuration file by default in +{ntpconfpath}+. Newbies should see the
-link:quick.html[Quick Start] page for orientation. Seasoned veterans can
-start with the link:ntpd.html[+ntpd+ - Network Time Protocol (NTP)
-daemon] page and move on to the specific configuration option pages from
-there.
+link:quick.html[Client Quick Start Guide]. Seasoned
+veterans can start with the link:ntpd.html[+ntpd+ - Network Time Protocol
+(NTP) Daemon] and link:ntp_conf.html[+ntpd+ Configuration File] pages and
+move on to the specific configuration option pages.
[[prob]]
== If You Have Problems
=====================================
docs/confopt.adoc
=====================================
@@ -53,10 +53,12 @@ the host name forces DNS resolution to the IPv4 namespace, while a
Unless noted otherwise, further information about these commands is at
link:discover.html#pool[Automatic Server Discovery].
-The https://www.ntppool.org/[www.ntppool.org] page describes a
+
+The https://www.ntppool.org/[NTP Pool Project] coordinates a
compatible pool of public NTP servers, which are probably what you
want to define associations with unless you specifically know
-otherwise.
+otherwise. See link:quick.html#pool[Using the NTP Pool] for configuration
+examples.
include::includes/assoc-commands.adoc[]
=====================================
docs/debug.adoc
=====================================
@@ -40,7 +40,7 @@ running. The most common of these are the lack of a UDP port for NTP
(123) in the Unix +/etc/services+ file (or equivalent in some systems).
*Note that NTP requires port 123 for both source and destination ports.*
These facts should be pointed out to firewall administrators.
-If you are using link:NTS-QuickStart.html[NTS], you also need to
+If you are using link:authentic.html#nts[NTS], you also need to
add an entry for TCP port 123.
Other problems are apparent in the system log, which ordinarily shows
=====================================
docs/discover.adoc
=====================================
@@ -31,7 +31,7 @@ please see https://tools.ietf.org/html/rfc5905[RFC 5905].
The pool scheme expands a single DNS name into multiple peer entries.
This is intended for, but not limited to, the
-https://www.ntppool.org[NTP Pool Project], a worldwide set of servers
+https://www.ntppool.org[NTP Pool], a worldwide set of servers
volunteered for public use.
The mechanism might be described as _grab-n'-prune._ Through one means or
@@ -44,10 +44,8 @@ to the NTP mitigation algorithms, and surplus associations are pruned.
Pool discovery uses an iterated process to discover new preemptable client
associations as long as the total number of client associations is less
-than the +maxclock+ option of the +tos+ command. The +maxclock+ default
-is 10, but it should be changed in typical configuration to some lower
-number, usually two greater than the +minclock+ option of the same
-command.
+than the +maxclock+ option of the link:miscopt.html#tos[+tos+] command,
+which should typically be changed from the default.
Pool discovery uses a stratum filter to select just those servers with
strata considered useful. This can avoid large numbers of clients
@@ -85,7 +83,7 @@ for applicability and defaults.
The idea of targeting servers on a random basis to distribute and
balance the load is not a new one; however, the
-https://www.pool.ntp.org/en/use.html[NTP Pool Project] puts
+https://www.ntppool.org/[NTP Pool Project] puts
this on steroids. At present, several thousand operators around the
globe have volunteered their servers for public access. In general,
NTP is a lightweight service and servers used for other purposes don't
@@ -96,21 +94,13 @@ advantages of multiple servers using the NTP mitigation algorithms.
To support this service, custom DNS software is used by pool.ntp.org
and its subdomains to discover a random selection of participating
(in-country) servers in response to a DNS query. The client receiving
-this list mobilizes some or all of them, similar to the manycast
-discovery scheme, and prunes the excess. Cryptographic authentication
-is not required.
+this list mobilizes some or all of them, as described above. Cryptographic
+authentication is not supported.
The pool scheme is configured using one or more +pool+ commands with DNS
names indicating the pool from which to draw. The +pool+ command can be
-used more than once; duplicate servers are detected and discarded. In
-principle, it is possible to use a configuration file containing a
-single line +pool pool.ntp.org+. The NTP Pool Project offers
-instructions on using the pool with the +server+ command, which is
-suboptimal but works with older versions of +ntpd+ predating the +pool+
-command. Use of the +server+ command does a one-time DNS lookup, and
-uses the IP address returned thereafter. If the server becomes unavailable,
-the DNS will not be re-resolved. The +pool+ command will
-use multiple servers that the DNS resolves to, refreshing as required.
+used more than once; duplicate servers are detected and discarded. For
+configuration examples, see link:quick.html#pool[Using the NTP Pool].
'''''
=====================================
docs/includes/assoc-commands.adoc
=====================================
@@ -13,7 +13,7 @@ link-local IPV6 address with an interface specified in
+peer+ _address_ [+key+ _key_] [+version+ _version_] [+prefer+] [+minpoll+ _minpoll_] [+maxpoll+ _maxpoll_]
-+unpeer+ ['address' | 'associd' | +clock+ 'clocktype' [ +unit+ 'unitnum']]::
++unpeer+ ['address' | 'associd' | +clock+ 'clocktype' [+unit+ 'unitnum']]::
These four commands specify the time server name or address to be
used and the mode in which to operate. The _address_ can be either a
DNS name or an IP address in dotted-quad notation. If it is a
=====================================
docs/includes/install.adoc
=====================================
@@ -1,7 +1,8 @@
=== Build and Install
* link:build.html[Building and Installing the Distribution]
* link:rdebug.html[Debugging Reference Clock Drivers]
-* link:quick.html[Quick Start for Client Configurations]
+* link:quick.html[Client Quick Start Guide]
+* link:NTS-QuickStart.html[NTS Quick Start Guide]
* link:debug.html[NTP Debugging Techniques]
* link:bugs.html[NTP Bug Reporting Procedures]
=====================================
docs/includes/ntpd-body.adoc
=====================================
@@ -47,7 +47,7 @@ times out and exits without setting the clock.
Various internal +ntpd+ variables can be displayed and configuration
options altered while the +ntpd+ is running using the
-{ntpqman} utility program. The state of ntpd can be continuously
+{ntpqman} utility program. The state of +ntpd+ can be continuously
monitored using {ntpmonman}.
When +ntpd+ starts it looks at the value of umask(2), and if
@@ -346,7 +346,7 @@ are present the resulting time offsets stray outside the 128-ms range
and an eventual step or slew time correction is required. If following
such a correction the frequency error is so large that the first sample
is outside the acceptable range, +ntpd+ enters the same state as when
-the _ntp.drift_ file is not present. The intent of this behavior is to
+the +ntp.drift+ file is not present. The intent of this behavior is to
quickly correct the frequency and restore operation to the normal
tracking mode. In the most extreme cases, there may be occasional
step/slew corrections and subsequent frequency corrections. It helps in
@@ -356,9 +356,9 @@ ONLY when you have permission to do so from the owner of the target host.
Finally, in the past, many startup scripts would run
a separate utility to get the system clock close to correct before
starting {ntpdman}, but this was never more than a mediocre hack
-and is no longer needed. If you are following the instructions
-in <<starting>> and you still need to set the
-system time before starting ntpd, please open a bug report and
+and is no longer needed. If you are following the
+link:#starting[best current practice] and you still need to set the
+system time before starting +ntpd+, please open a bug report and
document what is going on, and then look at using {ntpdigman}.
There is a way to start {ntpdman} that often addresses all of
@@ -369,7 +369,7 @@ the problems mentioned above.
First, use the _iburst_ option on your _server_ and _pool_ entries.
-If you can also keep a good _ntp.drift_ file then {ntpdman} will
+If you can also keep a good +ntp.drift+ file then {ntpdman} will
effectively "warm-start" and your system's clock will be stable in under
11 seconds' time.
@@ -388,7 +388,7 @@ will ever be to start any processes that require stable time.
=== Frequency Discipline
The +ntpd+ behavior at startup depends on whether the frequency file,
-usually _ntp.drift_, exists. This file contains the latest estimate of
+usually +ntp.drift+, exists. This file contains the latest estimate of
clock frequency error. When the +ntpd+ is started and the file does not
exist, the +ntpd+ enters a special mode designed to quickly adapt to the
particular system clock oscillator time and frequency error. This takes
@@ -468,7 +468,7 @@ intrinsic clock frequency error is small enough for the discipline loop
correct it. The capture range of the loop is 500 PPM at an interval of
64s decreasing by a factor of two for each doubling of the interval. At a
minimum of 1,024 s, for example, the capture range is only 31 PPM. If
-the intrinsic error is greater than this, the drift file _ntp.drift_
+the intrinsic error is greater than this, the drift file +ntp.drift+
will have to be specially tailored to reduce the residual error below
this limit. Once this is done, the drift file is automatically updated
once per hour and is available to initialize the frequency on subsequent
@@ -540,7 +540,7 @@ It will also retry any pending DNS or NTS lookups.
On most systems, you can send SIGHUP to +ntpd+ with
-----
- # sigkill -HUP ntpd
+ # killall -HUP ntpd
-----
If built with debugging enabled (waf configured with +--enable-debug+)
=====================================
docs/includes/ntpkeygen-body.adoc
=====================================
@@ -52,7 +52,7 @@ string returned by the Unix gethostname() routine, and _filestamp_ is
the NTP seconds when the file was generated, in decimal digits.
+ntpkeygen+ also makes a soft link from +ntp.keys+ to the generated
-file. +ntp.keys+ is the normal file used in +ntp.conf+.
+file. +ntp.keys+ is the normal file used in +{ntpconf}+.
[[random]]
== Random Seed File
=====================================
docs/includes/ntpq-body.adoc
=====================================
@@ -171,7 +171,7 @@ as following.
+keyid+ 'keyid'::
This command specifies the key number to be used to authenticate
configuration requests; this must correspond to a key ID configured
- with the +controlkey+ command in the server's +ntp.conf+
+ with the +controlkey+ command in the server's +{ntpconf}+
+keytype+::
Specify the digest algorithm to use for authenticated requests, with
=====================================
docs/index.adoc
=====================================
@@ -93,10 +93,10 @@ handbook pages. These should be read in conjunction with the command and
option information available on the pages listed on the
link:sitemap.html[Site Map] page.
-link:quick.html[Quick start for client configurations]::
+link:quick.html[Client Quick Start Guide]::
Basic configuration for 99% of client installations. Introduces
concepts used later in the Handbook.
-link:NTS-QuickStart.html[Quick start for NTS]::
+link:NTS-QuickStart.html[NTS Quick Start Guide]::
A short guide for setting up for NTS.
link:assoc.html[Association Management]::
Describes how to configure servers and peers and manage the various
=====================================
docs/miscopt.adoc
=====================================
@@ -43,9 +43,14 @@ include::includes/misc-options.adoc[]
Server Discovery] page for further details.
+maxclock+ 'maxclock';;
Specify the maximum number of servers retained by the server
- discovery schemes. The default is 10. See the
- link:discover.html[Automatic Server Discovery] page for further
- details.
+ discovery schemes. The default is 10, which should typically be changed.
+ This should be an odd number (to most effectively outvote
+ link:ntpspeak.html[falsetickers]) typically two or three more than
+ +minclock+, plus the number of +pool+ entries. The pool entries
+ must be added as +maxclock+, but not +minclock+, also counts the +pool+
+ entries themselves. For example, +tos maxclock 11+ with four +pool+ lines
+ would keep 7 associations. See the link:discover.html[Automatic Server
+ Discovery] page for further details.
+maxdist+ 'maxdistance';;
Specify the synchronization distance threshold used by the clock
selection algorithm. The default is 1.5 s. This determines both the
@@ -72,7 +77,7 @@ include::includes/misc-options.adoc[]
Specify the number of servers used by the selection algorithm as the
minimum to set the system clock. The default is 1 for legacy
purposes; however, for critical applications the value should be
- somewhat higher but less than +minclock+.
+ somewhat higher (e.g. 3) but less than +minclock+.
+orphan+ 'stratum';;
Specify the orphan stratum with default 16. If less than 16 this is
the stratum assumed by the root servers. See the
=====================================
docs/ntplogtemp.adoc
=====================================
@@ -1,6 +1,5 @@
= ntplogtemp - log system temperature data for use by ntpviz
include::include-html.ad[]
-//FIXME: Image duplicates the one used for panda.adoc
[cols="10%,90%",frame="none",grid="none",style="verse"]
|==============================
@@ -9,6 +8,17 @@ include::include-html.ad[]
P is for patching.
+// This is preserved in case we ever want the historical flavor again.
+// The baby panda was scanned at University College London and used as a
+// FAX test image for a demonstration of the DARPA Atlantic SATNET Program
+// and the first transatlantic Internet connection in 1978. The computing
+// system used for that demonstration was called the
+// {millshome}database/papers/fuzz.ps[Fuzzball]. As
+// it happened, this was also the first Internet multimedia presentation
+// and the first to use a predecessor of NTP in regular operation. The
+// image was widely copied and used for testing purpose throughout much of
+// the 1980s.
+
|==============================
== Manual Pages
=====================================
docs/ntpsec.adoc
=====================================
@@ -142,7 +142,7 @@ to the security-critical core.
* Various features related to runtime dumping of the configuration
state have been removed for security reasons. These include the
+saveconfig+ command in +ntpq+, the +--saveconfigquit+ option of ntpd, and
- the implementation of related config declarations in +ntp.conf+.
+ the implementation of related config declarations in +{ntpconf}+.
* Likewise, the poorly-documented ntpdsim code has also been removed
to gain a significant reduction in code complexity.
=====================================
docs/ntpspeak.adoc
=====================================
@@ -228,17 +228,16 @@ include::include-html.ad[]
sustained accuracy than NTP, into the sub-microsecond range.
[[pool]] pool::
- In an NTP context, "the pool" is usually the
- https://www.ntppool.org/en[NTP Pool Project], a collection of
- thousands of NTP servers around the world that you can use to keep
- time. The DNS names are designed to keep the timeservers you select
+ In an NTP context, "the pool" usually refers to the
+ https://www.ntppool.org/[NTP Pool Project], which coordinates a volunteer
+ collection of thousands of NTP servers around the world that anyone can
+ use. The DNS names are designed to keep the timeservers you select
relatively "close" to you on the internet, with varying degrees of
specificity, e.g. using north-america.pool.ntp.org may connect you
to timeservers from Canada to Panama, while us.pool.ntp.org is more
- likely to connect you to timeservers within the continental U.S..
- These pool timeservers are usually run by volunteers. See
- the link:quick.html#pool[Quick Start for Client Configurations] for a more
- in-depth discussion of pools.
+ likely to connect you to timeservers within the continental U.S.
+ See the link:quick.html#pool[Client Quick Start Guide]
+ for configuration examples.
[[proventic]] proventic:: <<Mills-speak>> for "the transitive
completion of the authentication relationship", defined in RFC 5906.
=====================================
docs/pic/panda.adoc deleted
=====================================
@@ -1,14 +0,0 @@
-// This is preserved from the old quickstart page in case we ever want
-// the historical flavor again.
-.FAX test image for SATNET (1979).
-image:pic/panda.gif[]
-
-The baby panda was scanned at University College London and used as a
-FAX test image for a demonstration of the DARPA Atlantic SATNET Program
-and the first transatlantic Internet connection in 1978. The computing
-system used for that demonstration was called the
-{millshome}database/papers/fuzz.ps[Fuzzball]. As
-it happened, this was also the first Internet multimedia presentation
-and the first to use a predecessor of NTP in regular operation. The
-image was widely copied and used for testing purpose throughout much of
-the 1980s.
=====================================
docs/quick.adoc
=====================================
@@ -1,4 +1,4 @@
-= Quick Start for Client Configurations
+= Client Quick Start Guide
include::include-html.ad[]
[cols="10%,90%",frame="none",grid="none",style="verse"]
@@ -19,11 +19,12 @@ include::includes/hand.adoc[]
* link:#introduction[Introduction]
* link:#basics[Configuration Basics]
-* link:#pool[Configuring Pool Servers]
+* link:#pool[Using the NTP Pool]
* 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:#security[Network Time Security]
'''''
@@ -33,38 +34,39 @@ include::includes/hand.adoc[]
This page is a quick start for the 99% of NTP configurations that are
not intended to serve time to others, but just run in client mode and
optionally have a local GPS reference clock. It describes how to
-write a basic +ntp.conf+ configuration file for this common case,
+write a basic +{ntpconf}+ configuration file for this common case,
and introduces some concepts that will be useful later on in the
Handbook.
-If your NTP program was installed from a binary package (such as
-a deb or RPM file under Linux) you can use this introduction as a
-guide to reading the configuration, but may not have to modify it
-at all.
+If you installed NTPsec using a distro package, the package's stock
+configuration may not need any changes. You can use this guide to
+understand the default configuration. If you installed NTPsec from
+source, this guide will help you build your configuration.
-It is most likely that your NTP configuration file, +ntp.conf+ ,
-resides in +/etc+ .
+It is very likely that your NTP configuration file, +{ntpconf}+ ,
+resides in +/etc+ . On Debian (and derivatives), it is
+in +/etc/ntpsec+ if you installed from the package.
If you are using a typical residential setup, in which your machine
performs DHCP to your ISP's servers and receives a dynamic address,
-your +ntp.conf+ may be altered or generated by DHCP at
+your +{ntpconf}+ may be altered or generated by DHCP at
address-allocation time to use the NTP servers provided by DHCP.
NTPsec, unlike legacy versions, can also be configured using an
-Apache-style directory /etc/ntp.d of configuration-file segments.
+Apache-style directory +/etc/ntp.d/+ of configuration-file segments.
This is intended to make life easier for software configurators, which
can write independent segments rather than having to do the kind of
-edit-in-place on a flat ntp.conf that comes naturally to a human.
+edit-in-place on a flat +{ntpconf}+ that comes naturally to a human.
[[basics]]
== Configuration basics
An NTP configuration file normally consists of three sections: logging
-controls, security/access controls, and server/refclock declarations. In
-most configurations the first two sections will be a boilerplate set
+controls, security/access controls, and +server+/+refclock+ declarations. In
+most configurations, the first two sections will be a boilerplate set
of defaults.
-Under /etc/ntp.d, the text in these segments can be split up into file
+Under +/etc/ntp.d/+, the text in these segments can be split up into file
parts (with names ending in .conf) in any way that is convenient.
Parts are evaluated in the text sort order of their names.
@@ -105,53 +107,81 @@ Your security/access section will almost always look a lot like this:
------------------------------------------------------------------
restrict default kod limited nomodify nopeer noquery
-restrict -6 default kod limited nomodify nopeer noquery
restrict 127.0.0.1
-restrict -6 ::1
+restrict ::1
------------------------------------------------------------------
This disallows configuration or +ntpq+ queries from anywhere off the
-local system.
+local system. Older configurations may duplicate the +restrict default+
+line into a +restrict -6 default+ and/or use +-6+ on the IPv6 localhost
+exception. These are no longer necessary, but not harmful.
The server/refclock declarations are the most variable part of the
configuration. They tell +ntpd+ what its sources for time are.
-In a pre-configured NTP installation set up by an OS vendor or
-distribution packager, you are likely to see a set of time-server
-declarations pointing at a vendor-specific set of NTP pool servers.
-Under Ubuntu Linux, for example, it probably looks like this:
+[[pool]]
+== Using the NTP Pool
+
+The NTP Pool is a dynamic collection of publicly available servers
+that freely provide highly accurate time via the Network Time Protocol to
+clients worldwide. The machines that are "in the pool" are part of the
+pool.ntp.org domain as well as many subdomains divided by geographical region
+or software vendor, and are distributed to NTP clients via round robin DNS.
+
+Your +{ntpconf}+ can use one or several of these DNS names. The
+https://www.ntppool.org/en/use.html[NTP Pool documentation] gives this
+example (but see below for a better version):
------------------------------------------------------------------
-server 0.ubuntu.pool.ntp.org
-server 1.ubuntu.pool.ntp.org
-server 2.ubuntu.pool.ntp.org
-server 3.ubuntu.pool.ntp.org
+server 0.pool.ntp.org
+server 1.pool.ntp.org
+server 2.pool.ntp.org
+server 3.pool.ntp.org
------------------------------------------------------------------
+In a pre-configured NTP installation set up by an OS vendor or distribution
+packager, you are likely to see a set of time-server declarations pointing
+at a vendor subdomain of the NTP Pool (+0.vendor.pool.ntp.org+, etc.).
+
Multiple declarations of individual pool servers is not the best
method; they're a workaround for a historical bug in NTP Classic. It's
-better to say
+better to use the +pool+ directive:
------------------------------------------------------------------
-pool ubuntu.pool.ntp.org
+pool 0.pool.ntp.org
+pool 1.pool.ntp.org
+pool 2.pool.ntp.org
+pool 3.pool.ntp.org
------------------------------------------------------------------
-The next section will explain what pool servers are and why you might
-want to change them.
+Use of the +server+ command does a one-time DNS lookup, and uses the IP
+address returned thereafter. If the server becomes unavailable, the DNS name
+will not be re-resolved. The +pool+ command will use multiple servers that
+the DNS name resolves to, refreshing as required. For details on the
+refreshing algorithm, see link:discover.html#assoc[Association Management].
+The number of associations is controlled by the +maxclock+ option of the
+link:miscopt.html#tos[+tos+] command, which should typically be changed from
+the default.
-[[pool]]
-== Configuring Pool Servers
+Using only a single pool entry has some limitations:
+
+------------------------------------------------------------------
+# This works, but is IPv4 only and spins up associations slower:
+pool pool.ntp.org
-The NTP pool is a dynamic collection of networked computers that
-provide highly accurate time via the Network Time Protocol to clients
-worldwide. The machines that are "in the pool" are part of the
-pool.ntp.org domain as well as of many subdomains divided by
-geographical or organizational zone, and are distributed to NTP
-clients via round robin DNS.
+# Likewise for 0, 1, or 3:
+pool 0.pool.ntp.org
-The +server+ declarations in your +ntp.conf+ normally point at one or
-several of these DNS names. These are resolved via DNS to Pool
-servers.
+# Only the "2" hostname has IPv6 currently, so this works with both IPv4
+# IPv6, but still spins up associations slower than using all four names:
+pool 2.pool.ntp.org
+
+# Vendor domains do not work with only the top-level name:
+pool vendor.pool.ntp.org
+
+# The numbers work with vendor subdomains, with the same caveats:
+pool 0.vendor.pool.ntp.org
+------------------------------------------------------------------
Note: while you could in theory request time service from any specific
time server in the world, it is considered bad form to use a non-pool
@@ -159,26 +189,25 @@ server unless you know you have permission. This applies, in
particular, to various public timeservers maintained by corporations
or academic institutions and intended to be used by their members.
-For high-quality time service it is advantageous if your upstream
+For high-quality time service, it is advantageous if your upstream
servers are located where packet-transit times to you are short and
-there is little random variation in them. Because the NTP pool is
-worldwide, asking for a random assignment from it may give you a
-timeserver on the other side of the world. Thus, the pool is divided
-into subsections. To improve your service, pick a pool section near
-you on the network.
-
-Unfortunately, "near you on the network" is often difficult to map
-and changes unpredictably over time. However, there is a very
-rough correlation with national boundaries - more so when the
-country in question is geographically small and relatively advanced.
-Accordingly, the NTP pool has national sections for many countries,
-named by ISO country code.
-
-If you are in Great Britain, for example, you might want to use the UK
-section of the pool:
+there is little random variation in them. Unfortunately, "near you on the
+network" is often difficult to map and changes unpredictably over time.
+However, there is a very rough correlation with national boundaries--more
+so when the country in question is geographically small and relatively
+advanced.
+
+The NTP Pool DNS servers try to give you servers in the same country
+or continent, but this is not guaranteed. Accordingly, the NTP
+Pool has subdomains for many countries, named by ISO country code.
+If you are in the United Kingdom, for example, you might want to use the UK
+subdomain:
------------------------------------------------------------------
-pool uk.pool.ntp.org
+pool 0.uk.pool.ntp.org
+pool 1.uk.pool.ntp.org
+pool 2.uk.pool.ntp.org
+pool 3.uk.pool.ntp.org
------------------------------------------------------------------
If you know your ISO country code, it is often possible to find an
@@ -217,15 +246,15 @@ down and 3 can outvote 2 falsetickers. That may be appropriate if you
need high reliability, say because you are serving hundreds of
clients.
-One pool declaration will normally get you four or more servers.
+One +pool+ declaration will normally get you four or more servers.
[[gps]]
== Configuring A Local GPS
Connecting a local GPS to your machine will provide extremely
accurate time, provided it has link:ntpspeak.html[PPS] capability.
-(However, unless your GPS has a perfect continuous skyview, you will still
-want check servers from the pool.)
+However, unless your GPS has a perfect continuous skyview, you will still
+want to use servers from the link:#pool[the NTP Pool] or elsewhere.
The easiest way to arrange this is by installing
https://gpsd.io[GPSD] to watch the GPS, and configuring your
@@ -242,23 +271,22 @@ refclock shm unit 0 refid GPS
------------------------------------------------------------------
Note the order above; +ntpd+ prefers earlier defined refclocks
-to later. Your PPS is likely to be more accurate than the
-in-band stream.
+to later. PPS is significantly more accurate than the in-band stream.
For details on setting up the GPSD end, see the
https://gpsd.io/gpsd-time-service-howto.html[GPSD Time Service
HOWTO].
If you are looking to set up a Stratum 1 timeserver, you may find
-https://www.ntpsec.org/white-papers/stratum-1-microserver-howto/
-very helpful.
+https://www.ntpsec.org/white-papers/stratum-1-microserver-howto/[Stratum-1-Microserver HOWTO]
+helpful.
[[dhcp]]
== Special considerations when using DHCP
If your machine uses DHCP to get a dynamic IP address from your ISP,
that handshake may provide you with a list of NTP servers.
-Suspect this if, when you look at your +ntp.conf+, you
+Suspect this if, when you look at your +{ntpconf}+, you
see server domain names obviously belonging to your ISP or
your ntpq -p printout doesn't match what you expect.
@@ -271,9 +299,8 @@ that are close to you on its network and will thus have fairly steady
ping times. A bad thing is that you may have difficulty making
configuration of a local reference clock stick.
-One family of systems with this behavior is Debian Linux, including
-Ubuntu. On these systems the DHCP client is NetworkManager. If you
-look in your +/etc/init.d/ntp+ file, you may see something like this:
+If you look in your +/etc/init.d/ntp+ file, systemd unit, or other scripts
+involved in starting +ntpd+, you may see something like this:
------------------------------------------------------------------
if [ -e /var/lib/ntp/ntp.conf.dhcp ]; then
@@ -283,11 +310,17 @@ fi
The -c option tells +ntpd+ that the path to a generated configuration
file follows. The generation process might pick up your local changes
-to +ntp.conf+ or it might not; this depends on your OS supplier (Debian
-derivatives normally 'do' base on your local +ntp.conf+). If it does,
+to +{ntpconf}+ or it might not; this depends on your OS supplier. (Debian
+derivatives normally 'do' base on your local +{ntpconf}+.) If it does,
all is well. If it does not, you may have to modify the hook scripts
that generate that file, or disable the generation process.
+You may also wish to ignore the DHCP-provided servers for other reasons.
+For example, you may wish to use specific servers which support
+link:#security[Network Time Security]. On Debian derivatives, if you
+installed from the package, you can set +IGNORE_DHCP="yes"+ in
++/etc/default/ntpsec+ to ignore DHCP-provided NTP servers.
+
[[sanity]]
== Sanity-Checking Your Time Service
@@ -342,6 +375,15 @@ jitter is more likely due to bufferbloat and other sources of variable
latency under load. Note that the units for delay, offset, and jitter
are milliseconds.
+[[security]]
+== Network Time Security
+
+The NTP protocol will work with unauthenticated servers, this is what
+makes the NTP Pool Project feasible. However, to close off some lines of
+attack on NTP, especially spoofing and Man-In-The-Middle, NTPsec supports
+Network Time Security (NTS). Further information on how to enable NTS is
+available in the link:NTS-QuickStart.html[NTS Quick Start Guide].
+
'''''
include::includes/footer.adoc[]
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/2b1f0f538c954c8667311e425c45c91775bd4ef0...d941e8d02e9022d73c5bcaa4973d8d0f5f448826
--
View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/2b1f0f538c954c8667311e425c45c91775bd4ef0...d941e8d02e9022d73c5bcaa4973d8d0f5f448826
You're receiving this email because of your account on gitlab.com.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ntpsec.org/pipermail/vc/attachments/20191214/23eb60df/attachment-0001.htm>
More information about the vc
mailing list