[Git][NTPsec/ntpsec][master] Filled out "Quick Start for Client Configurations"

Tue Aug 23 12:06:42 UTC 2016

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


Commits:
1ad7eb70 by Eric S. Raymond at 2016-08-23T08:06:27-04:00
Filled out "Quick Start for Client Configurations"

- - - - -


1 changed file:

- + docs/clientstart.txt


Changes:

=====================================
docs/clientstart.txt
=====================================

--- /dev/null
+++ b/docs/clientstart.txt
@@ -0,0 +1,217 @@
+= Quick Start for Client Configurations =
+
+[cols="10%,90%",frame="none",grid="none",style="verse"]
+|==============================
+|image:pic/orchestra.gif[]|
+{millshome}pictures.html[from 'Pogo', by Walt Kelly]
+
+Take it away, boys!
+
+|==============================
+
+
+== Related Links ==
+
+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]
+
+'''''
+
+[[introduction]]
+== Introduction ==
+
+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,
+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
+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.
+
+[[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
+of defaults.
+
+The simplest, minimal logging configuration consists of a line like this:
+
+------------------------------------------------------------------
+driftfile /var/lib/ntp/ntp.drift
+------------------------------------------------------------------
+
+This sets up a drift file, which is used to store a measurement of
+the drift frequency of your computer's clock crystal between runs
+of +{ntpd}. The drift is used to converge on correct time more quickly
+after startup.
+
+You might see something more like this:
+
+------------------------------------------------------------------
+driftfile /var/lib/ntp/ntp.drift
+
+statsdir /var/log/ntpstats/
+
+statistics loopstats peerstats clockstats
+filegen loopstats file loopstats type day enable
+filegen peerstats file peerstats type day enable
+filegen clockstats file clockstats type day enable
+
+logfile /var/log/ntpd.log  
+logconfig =syncall +clockall +peerall +sysall
+------------------------------------------------------------------
+
+This is a logging section intended to enable maximum statistics and
+diagnostics useful for tuning your time service.
+
+Your security/access section will almost always look a lot like this:
+
+------------------------------------------------------------------
+restrict default kod limited nomodify notrap nopeer noquery  
+restrict -6 default kod limited nomodify notrap nopeer noquery
+restrict 127.0.0.1  
+restrict -6 ::1
+------------------------------------------------------------------
+
+This disallows configuration or +{ntpq}+ queries from anywhere off the
+local system.
+
+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:
+
+------------------------------------------------------------------
+server 0.ubuntu.pool.ntp.org
+server 1.ubuntu.pool.ntp.org
+server 2.ubuntu.pool.ntp.org
+server 3.ubuntu.pool.ntp.org
+------------------------------------------------------------------
+
+The next section will explain what pool servers are and why you might
+want to change them.
+
+[[pool]]
+== Configuring Pool Servers ==
+
+The NTP pool is a worldwide federation of public-facing NTP servers,
+almost always 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}+.
+
+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
+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
+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
+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.
+
+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:
+
+------------------------------------------------------------------
+server 0.uk.pool.ntp.org
+server 1.uk.pool.ntp.org
+server 2.uk.pool.ntp.org
+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.
+
+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
+routing probems.  Unfortunately, the random nature of pool allocation
+makes this imposssible to guarantee. It is, however, worth keeping in mind if
+you can set up a custom configuration with non-pool servers that you
+have permission to use.
+
+[[howmany]]
+== How Many Servers?
+
+If you have only one server, things are simple.  Your system will
+follow that server even if it doesn't have the correct time.  (Your
+server might bail if the local clock is too far off - see
+link:clock.html#panic[panic threshold].)
+
+Two servers might seem like a simple redundant setup, but what happens
+if they don't agree?  NTP has no way to determine which one is
+correct.
+
+If you have three servers, two can outvote a
+link:ntpspeak.html[falseticker].  But that reduces to two if one of
+them is not responding.
+
+If you are using 4 servers, you still have 3 if one of them stops
+responding (your +{ntpd}+ will ask the pool dispatcher for another server
+when it notices this).  Unless you are serving time to other 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
+need high reliability, say because you are serving hundreds of
+clients.
+
+[[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.)
+
+The easiest way to arrange this is by installing
+http://catb.org/gpsd/[GPSD] to watch the and configuring your +{ntpd}+
+to accept time from it.  It is also possible to do this with native
++{ntpd}+ drivers (nmea, jupiter, trimble, oncore), though these are
+less flexible and a bit more difficult to configure.
+
+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
+------------------------------------------------------------------
+
+For details on setting up the GPSD end, see the
+http://catb.org/gpsd/gpsd-time-service-howto.html[GPSD Time Service
+HOWTO].
+
+'''''
+
+include::includes/footer.txt[]



View it on GitLab: https://gitlab.com/NTPsec/ntpsec/commit/1ad7eb70f6c89a2cd8a00c173dc7143b7f888cf0
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ntpsec.org/pipermail/vc/attachments/20160823/b787ef11/attachment.html>
