[Git][NTPsec/ntpsec][master] 4 commits: Proofreading and asciidoc markup

Eric S. Raymond gitlab at mg.gitlab.com
Mon Jan 30 14:02:46 UTC 2017


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


Commits:
1e7dfd19 by Sanjeev Gupta at 2017-01-30T09:02:38-05:00
Proofreading and asciidoc markup

- - - - -
2e6c5db3 by Sanjeev Gupta at 2017-01-30T09:02:38-05:00
Clean up pool language ...

... and add the Stratum 1 Howto

- - - - -
688da8b1 by Sanjeev Gupta at 2017-01-30T09:02:38-05:00
Mention pool command as an alternative to multiple server lines

- - - - -
6f438374 by Sanjeev Gupta at 2017-01-30T09:02:38-05:00
Reverse order of refclock lines (Gary's comment)

- - - - -


1 changed file:

- docs/quick.txt


Changes:

=====================================
docs/quick.txt
=====================================
--- a/docs/quick.txt
+++ b/docs/quick.txt
@@ -32,17 +32,21 @@ include::includes/hand.txt[]
 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 /etc/ntp.conf configuration file for this common case,
+write a basic +ntp.conf+ configuration file for this common case,
 and introduces some concepts that will be useful later on in the
 Handbook.
 
-If your NTP configuration was installed from a binary package (such as
+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 it, but may not have to modify it at all.
+guide to reading the configuration, but may not have to modify it
+at all.
+
+It is most likely that your NTP configuration file, +ntp.conf+ ,
+resides in +/etc+ .
 
 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 +ntp.conf+ may be altered or generated by DHCP at
 address-allocation time to use the NTP servers provided by DHCP.
 
 [[basics]]
@@ -80,9 +84,12 @@ logfile /var/log/ntpd.log
 logconfig =syncall +clockall +peerall +sysall
 ------------------------------------------------------------------
 
-This is a logging section intended to enable maximum statistics and
+This is a logging section intended to enable extensive statistics and
 diagnostics useful for tuning your time service.
 
+Note that the directories in which the log files are being created
+need to exist, and be writable by the user under which +ntpd+ runs.
+
 Your security/access section will almost always look a lot like this:
 
 ------------------------------------------------------------------
@@ -116,14 +123,15 @@ want to change them.
 [[pool]]
 == Configuring Pool Servers ==
 
-The NTP pool is a worldwide federation of public-facing NTP servers,
-many equipped with their own local reference clocks, that
-have volunteered to provide time service to anyone who requests it
-through a pool dispatcher machine. The +server+ declarations in your
-/etc/ntp.conf normally point at several of these pool dispatchers.
-When your +ntpd+ send a request to one, it picks a random server
-from its part of the pool and hands that address back to your
-+ntpd+.
+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 several
+subdomains divided by geographical zone and are distributed
+to NTP clients via round robin DNS.
+
+The +server+ declarations in your +ntp.conf+ normally point at
+several of these DNS names.  These are resolved via DNS to Pool servers.
 
 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
@@ -134,10 +142,10 @@ or academic institutions and intended to be used by their members.
 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, accepting a random assignment from it may give you a
+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, each with its own dispatchers.  To improve your
-service, pick a pool section near you on the network.
+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
@@ -159,6 +167,13 @@ server 3.uk.pool.ntp.org
 If you know your ISO country code, it is often possible to find an
 analogous group of servers by pinging them.
 
+Recent versions of NTP, (and NTPsec is recent enough), know of the
+pool concept, so you can replace the above with:
+
+------------------------------------------------------------------
+pool uk.pool.ntp.org
+------------------------------------------------------------------
+
 Ideally, one would like one's servers to use multiple different kinds
 of timesources (as opposed to, say, all being GPS-based) and be split
 across different autonomous networks as a hedge against outages and
@@ -185,7 +200,7 @@ them is not responding.
 
 If you are using 4 servers, you still have 3 if one of them stops
 responding.  Unless you are serving time to other systems,
-this is a reasonable setup. It is normal for client-only systems
+this is a reasonable setup. It is normal for client-only systems.
 
 You can add more servers.  With 5 servers, you still have 3 if 2 are
 down and 3 can outvote 2 falsetickers.  That may be appropriate if you
@@ -210,20 +225,28 @@ The following configuration lines tell your +ntpd+ to accept time
 from GPSD:
 
 ------------------------------------------------------------------
-refclock shm unit 0 refid GPS
 refclock shm unit 1 prefer refid PPS
+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.
+
 For details on setting up the GPSD end, see the
 http://catb.org/gpsd/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.
+
 [[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 +ntp.conf+, you
 see server domain names obviously belonging to your ISP or
 your ntpq -p printout doesn't match what you expect.
 
@@ -238,7 +261,7 @@ 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:
+look in your +/etc/init.d/ntp+ file, you may see something like this:
 
 ------------------------------------------------------------------
 if [ -e /var/lib/ntp/ntp.conf.dhcp ]; then
@@ -246,10 +269,10 @@ if [ -e /var/lib/ntp/ntp.conf.dhcp ]; then
 fi
 ------------------------------------------------------------------
 
-The -c option tells +ntpd that the path to a generated configuration
+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 +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,
 all is well.  If it does not, you may have to modify the hook scripts
 that generate that file, or disable the generation process.
 
@@ -284,7 +307,7 @@ xSHM(0)          .GPS.            0 l   39   64  377    0.000  -591.41  70.967
 +clocka.ntpjs.or 192.5.41.40      2 u   22   64  377   13.146    0.743   0.644
 ------------------------------------------------------------------
 
-The first two lines represent the refclock.
+In the latter table, the first two lines represent the refclock.
 
 In both cases, the column to look at first is the "reach". A value of
 377 indicates that your client has been getting samples continuously
@@ -299,11 +322,12 @@ Next, you want to look at the line for "preferred" server (marked with
 *).  This is the one that is closest to the approximation of UTC that
 NTP's algorithms have computed from its inputs. What you want to see here
 is low jitter. The PPS feed in the second example is pretty good. The
-figures from 18.26.4.105 in the first display are not great, but
-they're not out of line for operation over a WAN.  Offset over a
-second is most likely due to asymmetric packet delays; large jitter
+figures from +b1-66er.matrix.+ in the first display are not great, but
+they're not out of line for operation over a WAN.  Large offsets
+are most likely due to asymmetric packet delays; large jitter
 is more likely due to bufferbloat and other sources of variable
-latency under load.
+latency under load.  Note that the units for delay, offset, and jitter
+are milli-seconds.
 
 '''''
 



View it on GitLab: https://gitlab.com/NTPsec/ntpsec/compare/920115ee0a5924bb72bdaa70113feaae35a50f10...6f4383744c27403df81ad3d59c9b26029c249598
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ntpsec.org/pipermail/vc/attachments/20170130/88d0b396/attachment.html>


More information about the vc mailing list