Skip site navigation (1)Skip section navigation (2)
Date:      Fri, 31 Jan 2014 21:35:12 +0000 (UTC)
From:      Dru Lavigne <dru@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r43710 - head/en_US.ISO8859-1/books/handbook/network-servers
Message-ID:  <201401312135.s0VLZCfJ014161@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: dru
Date: Fri Jan 31 21:35:11 2014
New Revision: 43710
URL: http://svnweb.freebsd.org/changeset/doc/43710

Log:
  Editorial pass through the NTP chapter.
  Headings and content shuffled about to improve flow.
  Text clarified and logic should be much clearer now.
  
  Sponsored by: iXsystems

Modified:
  head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml	Fri Jan 31 20:55:48 2014	(r43709)
+++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml	Fri Jan 31 21:35:11 2014	(r43710)
@@ -5227,208 +5227,158 @@ Starting smbd.</screen>
     -->
     <title>Clock Synchronization with NTP</title>
 
-    <indexterm><primary>NTP</primary></indexterm>
-
-    <para>Over time, a computer's clock is prone to drift.  The
-      Network Time Protocol (NTP) is one way to ensure the clock
-      stays accurate.</para>
-
-    <para>Many Internet services rely on, or greatly benefit from,
-      computers' clocks being accurate.  For example, a web server
-      may receive requests to send a file if it has been modified
-      since a certain time.  In a local area network environment, it
-      is essential that computers sharing files from the same file
-      server have synchronized clocks so that file timestamps stay
-      consistent.  Services such as &man.cron.8; also rely on an
-      accurate system clock to run commands at the specified
-      times.</para>
-
     <indexterm><primary>NTP</primary>
-      <secondary>ntpd</secondary>
+    <secondary>ntpd</secondary>
     </indexterm>
 
-    <para>&os; ships with the &man.ntpd.8;
-      <acronym role="Network Time Protocol">NTP</acronym> server
-      which can be used to query other
-      <acronym role="Network Time Protocol">NTP</acronym> servers to
-      set the clock on the machine or provide time services to
-      others.</para>
-
-    <sect2>
-      <title>Choosing Appropriate NTP Servers</title>
-
-      <indexterm>
-	<primary>NTP</primary>
-	<secondary>choosing servers</secondary>
-      </indexterm>
-
-      <para>In order to synchronize the clock, one or more
-	<acronym role="Network Time Protocol">NTP</acronym> servers
-	must be defined.  The network administrator or ISP may have
-	set up an NTP server for this purpose&mdash;check their
-	documentation to see if this is the case.  There is an <link
+    <para>Over time, a computer's clock is prone to drift.   This is 
+      problematic as many network services require the computers on a network
+      to share the same accurate time.  Accurate time is also needed to ensure
+      that file timestamps stay
+      consistent.  The
+      Network Time Protocol (<acronym>NTP</acronym>) is one way to provide clock
+      accuracy in a network.</para>
+
+    <para>&os; includes &man.ntpd.8;
+      which can be configured to query other
+      <acronym>NTP</acronym> servers in order to
+      synchronize the clock on that machine or to provide time services to
+      other computers in the network.  The servers which are queried
+	can be local to the network or provided by an <acronym>ISP</acronym>.
+	In addition, an <link
 	  xlink:href="http://support.ntp.org/bin/view/Servers/WebHome">online
-	  list of publicly accessible NTP servers</link> which may be
-	referenced to find an NTP server nearest to the system.  Take
-	care to review the policy for any chosen servers, and ask for
-	permission if required.</para>
-
-      <para>Choosing several unconnected NTP servers is a good idea in
-	case one of the servers being used becomes unreachable or
-	its clock is unreliable.  &man.ntpd.8; uses the responses it
-	receives from other servers intelligently&mdash;it will favor
-	unreliable servers less than reliable ones.</para>
-    </sect2>
+	  list of publicly accessible <acronym>NTP</acronym> servers</link>
+	is available.  When choosing a public <acronym>NTP</acronym> server, select
+	one that is geographically close and
+	review its usage policy.</para>
+
+      <para>Choosing several <acronym>NTP</acronym> servers is recommended in
+	case one of the servers becomes unreachable or
+	its clock proves unreliable.  As <application>ntpd</application> receives responses,
+	it favors
+	reliable servers over the less reliable ones.</para>
+
+	<para>This section describes how to configure <application>ntpd</application> on &os;.  Further documentation can be found in
+	<filename>/usr/share/doc/ntp/</filename> in HTML
+	format.</para>
 
     <sect2>
-      <title>Configuring The Machine</title>
+      <title><acronym>NTP</acronym> Configuration</title>
 
-      <indexterm>
-	<primary>NTP</primary>
-	<secondary>configuration</secondary>
+      <indexterm><primary>NTP</primary>
+	<secondary>ntp.conf</secondary>
+	<tertiary>ntpdate</tertiary>
       </indexterm>
 
-      <sect3>
-	<title>Basic Configuration</title>
-
-	<indexterm><primary>ntpdate</primary></indexterm>
-
-	<para>To synchronize the clock only when the machine boots up,
-	  use &man.ntpdate.8;.  This may be appropriate for some
-	  desktop machines which are frequently rebooted and only
-	  require infrequent synchronization, but most machines should
-	  run &man.ntpd.8;.</para>
-
-	<para>Using &man.ntpdate.8; at boot time is also a good idea
-	  for machines that run &man.ntpd.8;.  The &man.ntpd.8;
-	  program changes the clock gradually, whereas &man.ntpdate.8;
+	<para>To only synchronize the clock when a system boots,
+	  use &man.ntpdate.8;.  This alone can be appropriate for
+	  desktops which are frequently rebooted.  However,
+	  most systems should
+	  run <application>ntpdate</application> at boot time as well as configure <application>ntpd</application>.
+	  This is because <application>ntpd</application>
+	  changes the clock gradually, whereas <application>ntpdate</application>
 	  sets the clock, no matter how great the difference between a
 	  machine's current clock setting and the correct time.</para>
 
-	<para>To enable &man.ntpdate.8; at boot time, add
+	<para>To enable <application>ntpdate</application> at boot time, add
 	  <literal>ntpdate_enable="YES"</literal> to
-	  <filename>/etc/rc.conf</filename>.  Also specify all
-	  synchronization servers and any flags to be passed to
-	  &man.ntpdate.8; in <varname>ntpdate_flags</varname>.</para>
-      </sect3>
-
-      <sect3>
-	<title>General Configuration</title>
+	  <filename>/etc/rc.conf</filename>.  To also enable
+	  <application>ntpd</application>, add the <literal>ntpd_enable="YES"</literal>
+	  entry to <filename>/etc/rc.conf</filename>.  Additional variables can be specified
+	  in <filename>/etc/rc.conf</filename>.  Refer to &man.rc.conf.5;,
+	  &man.ntpdate.8;, and &man.ntpd.8; for details.</para>
+
+	<para>Both applications
+	  read <filename>/etc/ntp.conf</filename> to determine
+	  which servers to query.  Here is a simple example of an
+	  <filename>/etc/ntp.conf</filename>:</para>
 
-	<indexterm>
-	  <primary>NTP</primary>
-	  <secondary>ntp.conf</secondary>
-	</indexterm>
-
-	<para>NTP is configured by the
-	  <filename>/etc/ntp.conf</filename> file in the format
-	  described in &man.ntp.conf.5;.  Here is a simple
-	  example:</para>
+	<example>
+	  <title> Sample <filename>/etc/ntp.conf</filename></title>
 
 	<programlisting>server ntplocal.example.com prefer
 server timeserver.example.org
 server ntp2a.example.net
 
 driftfile /var/db/ntp.drift</programlisting>
+	</example>
 
-	<para>The <literal>server</literal> option specifies which
-	  servers are to be used, with one server listed on each line.
-	  If a server is specified with the <literal>prefer</literal>
-	  argument, as with
-	  <systemitem
-	    class="fqdomainname">ntplocal.example.com</systemitem>,
+	<para>The format of this file is
+	  described in &man.ntp.conf.5;.  The <literal>server</literal> option specifies which
+	  servers to query, with one server listed on each line.
+	  If a server entry includes <literal>prefer</literal>,
 	  that server is preferred over other servers.  A response
 	  from a preferred server will be discarded if it differs
-	  significantly from other servers' responses, otherwise it
-	  will be used without any consideration to other responses.
-	  The <literal>prefer</literal> argument is normally used for
-	  NTP servers that are known to be highly accurate, such as
+	  significantly from responses; otherwise it
+	  will be used.
+	  The <literal>prefer</literal> argument should only be used for
+	  <acronym>NTP</acronym> servers that are known to be highly accurate, such as
 	  those with special time monitoring hardware.</para>
 
-	<para>The <literal>driftfile</literal> option specifies which
+	<para>The <literal>driftfile</literal> entry specifies which
 	  file is used to store the system clock's frequency offset.
-	  The &man.ntpd.8; program uses this to automatically
+	  <application>ntpd</application> uses this to automatically
 	  compensate for the clock's natural drift, allowing it to
 	  maintain a reasonably correct setting even if it is cut off
-	  from all external time sources for a period of time.</para>
-
-	<para>The <literal>driftfile</literal> option specifies which
-	  file is used to store information about previous responses
-	  from the NTP servers being used.  This file contains
-	  internal information for NTP.  It should not be modified by
-	  any other process.</para>
-      </sect3>
-
-      <sect3>
-	<title>Controlling Access to Your Server</title>
-
-	<para>By default, the NTP server will be accessible to all
-	  hosts on the Internet.  The <literal>restrict</literal>
-	  option in <filename>/etc/ntp.conf</filename>
-	  controls which machines can access the server.</para>
-
-	<para>To deny all machines from accessing the NTP
+	  from all external time sources for a period of time.  This
+	  file also stores information about previous responses
+	  from <acronym>NTP</acronym> servers.  Since this file contains
+	  internal information for <acronym>NTP</acronym>, it should not be modified.</para>
+
+	<para>By default, an <acronym>NTP</acronym> server is accessible to any
+	  network host.  The <literal>restrict</literal>
+	  option in <filename>/etc/ntp.conf</filename> can be used to
+	  control which systems can access the server.  For example,
+	  to deny all machines from accessing the <acronym>NTP</acronym>
 	  server, add the following line to
 	  <filename>/etc/ntp.conf</filename>:</para>
 
 	<programlisting>restrict default ignore</programlisting>
 
 	<note>
-	  <para>This will also prevent access from the server to any
-	    servers listed in the local configuration.  If there is a
-	    need to synchronise the NTP server with an external NTP
+	  <para>This will also prevent access from other <acronym>NTP</acronym> servers. 
+	    If there is a
+	    need to synchronize with an external <acronym>NTP</acronym>
 	    server, allow only that specific server.  Refer to
 	    &man.ntp.conf.5; for more information.</para>
 	</note>
 
 	<para>To allow machines within the network to synchronize
 	  their clocks with the server, but ensure they are not
-	  allowed to configure the server or used as peers to
-	  synchronize against, add</para>
+	  allowed to configure the server or be used as peers to
+	  synchronize against, instead use:</para>
 
 	<programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting>
 
-	<para>instead, where
-	  <systemitem class="ipaddress">192.168.1.0</systemitem> is an
-	  <acronym>IP</acronym> address on the network and
+	<para>where
+	  <systemitem class="ipaddress">192.168.1.0</systemitem> is the
+	  local network address and
 	  <systemitem class="netmask">255.255.255.0</systemitem> is
-	  the network's netmask.</para>
+	  the network's subnet mask.</para>
 
-	<para>The <filename>/etc/ntp.conf</filename> file can contain
-	  multiple <literal>restrict</literal> options.  For more
-	  details, see the <literal>Access Control Support</literal>
+	<para>Multiple <literal>restrict</literal> entries are supported.
+	  For more
+	  details, refer to the <literal>Access Control Support</literal>
 	  subsection of &man.ntp.conf.5;.</para>
-      </sect3>
-    </sect2>
 
-    <sect2>
-      <title>Running the NTP Server</title>
-
-      <para>To ensure the NTP server is started at boot time, add the
-	line <literal>ntpd_enable="YES"</literal> to
-	<filename>/etc/rc.conf</filename>.  To pass
-	additional flags to &man.ntpd.8;, edit the
-	<varname>ntpd_flags</varname> parameter in
-	<filename>/etc/rc.conf</filename>.</para>
-
-      <para>To start the server without rebooting the machine, run
-	<command>ntpd</command> being sure to specify any additional
-	parameters from <varname>ntpd_flags</varname> in
-	<filename>/etc/rc.conf</filename>.  For example:</para>
+	<para>Once
+	<literal>ntpd_enable="YES"</literal> has been added to
+	  <filename>/etc/rc.conf</filename>, <application>ntpd</application>
+	  can be started now without rebooting the system by typing:</para>
 
-      <screen>&prompt.root; <userinput>ntpd -p /var/run/ntpd.pid</userinput></screen>
+      <screen>&prompt.root; <userinput>service ntpd start</userinput></screen>
     </sect2>
 
     <sect2>
-      <title>Using <application>ntpd</application> with a Temporary
-	Internet Connection</title>
+      <title>Using <acronym>NTP</acronym> with a <acronym>PPP</acronym>
+	Connection</title>
 
-      <para>The &man.ntpd.8; program does not need a permanent
+      <para><application>ntpd</application> does not need a permanent
 	connection to the Internet to function properly.  However, if
-	there is a temporary connection that is configured to dial out
-	on demand, it is a good idea to prevent NTP traffic from
-	triggering a dial out or keeping the connection alive.  PPP
-	users can use the <literal>filter</literal>
+	a <acronym>PPP</acronym> connection is configured to dial out
+	on demand, <acronym>NTP</acronym> traffic should be prevented from
+	triggering a dial out or keeping the connection alive.  This can be configured
+	with <literal>filter</literal>
 	directives in <filename>/etc/ppp/ppp.conf</filename>.  For
 	example:</para>
 
@@ -5441,7 +5391,7 @@ driftfile /var/db/ntp.drift</programlist
  # Prevent outgoing NTP traffic from keeping the connection open
  set filter alive 2 permit 0/0 0/0</programlisting>
 
-      <para>For more details see the
+      <para>For more details, refer to the
 	<literal>PACKET FILTERING</literal> section in &man.ppp.8; and
 	the examples in
 	<filename>/usr/share/examples/ppp/</filename>.</para>
@@ -5452,14 +5402,6 @@ driftfile /var/db/ntp.drift</programlist
 	  reach the machine.</para>
       </note>
     </sect2>
-
-    <sect2>
-      <title>Further Information</title>
-
-      <para>Documentation for the NTP server can be found in
-	<filename>/usr/share/doc/ntp/</filename> in HTML
-	format.</para>
-    </sect2>
   </sect1>
 
   <sect1 xml:id="network-syslogd">



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201401312135.s0VLZCfJ014161>