Skip site navigation (1)Skip section navigation (2)
Date:      Mon, 16 Sep 2019 02:12:39 +0000 (UTC)
From:      Ian Lepore <ian@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r53407 - head/en_US.ISO8859-1/books/handbook/network-servers
Message-ID:  <201909160212.x8G2CdLh053297@repo.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: ian (src committer)
Date: Mon Sep 16 02:12:39 2019
New Revision: 53407
URL: https://svnweb.freebsd.org/changeset/doc/53407

Log:
  Update the NTP section of the handbook.
  
  Ntpd has evolved considerably in recent years and the handbook has fallen
  out of date. Notable updates include...
  
   - The sample ntp.conf file in the handbook was a bad example that, if used,
     would expose the user to potential network attacks or exploits by
     allowing full query and control access to ntpd. The sample config now
     contains the restrict options that are considered current best practices
     for a public-facing ntpd daemon. The config would actually work (and be
     safe) even if a user just blindly cut and pastes it.
  
   - The new(-ish) ntp.conf 'pool' keyword is featured prominently in the
     sample, and the existence of the FreeBSD project-sponsored pool is
     documented.
  
   - Separate subsections now exist for ntp.conf and the rc.conf variables
     that affect how ntpd runs. The existence and effect of the un-obvious
     ntpd_oomprotect rc variable is mentioned.
  
   - A new subsection describes running ntpd as the unpriveleged ntpd user. It
     details how certain configurations can prevent the rc.d script from
     automatically running ntpd unpriveleged, and describes how to manually
     configure unpriveleged operation in those cases.
  
   - It now mentions the fact that firewalls need to be configured to pass udp
     packets on port 123 for ntpd to operate.
  
  Approved by:	allanjude
  Differential Revision:	https://reviews.freebsd.org/D21659

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	Mon Sep 16 01:55:47 2019	(r53406)
+++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml	Mon Sep 16 02:12:39 2019	(r53407)
@@ -4237,23 +4237,10 @@ Starting smbd.</screen>
       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 <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>
+      other <acronym>NTP</acronym> servers to synchronize the clock on
+      that machine or to provide time services to other computers in
+      the network.</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
@@ -4262,99 +4249,210 @@ Starting smbd.</screen>
     <sect2>
       <title><acronym>NTP</acronym> Configuration</title>
 
-      <indexterm><primary>NTP</primary>
-	<secondary>ntp.conf</secondary>
-      </indexterm>
+      <indexterm><primary>NTP</primary></indexterm>
 
       <para>On &os;, the built-in <application>ntpd</application> can
-	be used to synchronize a system's clock.  To enable
-	<application>ntpd</application> at boot time, add
-	<literal>ntpd_enable="YES"</literal> to
-	<filename>/etc/rc.conf</filename>.  Additional variables can
-	be specified in <filename>/etc/rc.conf</filename>.  Refer to
-	&man.rc.conf.5; and &man.ntpd.8; for
-	details.</para>
+	be used to synchronize a system's clock.
+	<application>Ntpd</application> is configured using &man.rc.conf.5;
+	variables and <filename>/etc/ntp.conf</filename>, as detailed
+	in the following sections.</para>
 
-      <para>This application reads <filename>/etc/ntp.conf</filename>
-	to determine which <acronym>NTP</acronym> servers to query.
-	Here is a simple example of an
-	<filename>/etc/ntp.conf</filename>:</para>
+      <para><application>Ntpd</application> communicates with its network
+        peers using UDP packets.  Any firewalls between your machine and
+	its NTP peers must be configured to allow UDP packets in and out
+	on port 123.</para>
 
-      <example>
-	<title>Sample <filename>/etc/ntp.conf</filename></title>
+      <sect3>
+	<title>The <filename>/etc/ntp.conf</filename> file</title>
 
-	<programlisting>server ntplocal.example.com prefer
-server timeserver.example.org
-server ntp2a.example.net
+	<indexterm><primary>NTP</primary>
+	  <secondary>ntp.conf</secondary>
+	</indexterm>
 
-driftfile /var/db/ntp.drift</programlisting>
-      </example>
+	<para><application>Ntpd</application> reads
+	  <filename>/etc/ntp.conf</filename>
+	  to determine which <acronym>NTP</acronym> servers to query.
+	  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.  The servers
+	    which are queried can be local to the network, provided by an
+	    <acronym>ISP</acronym>, or selected from an <link
+	      xlink:href="http://support.ntp.org/bin/view/Servers/WebHome">;
+	      online list of publicly accessible <acronym>NTP</acronym>
+	      servers</link>.
+	    When choosing a public <acronym>NTP</acronym> server, select one
+	    that is geographically close and review its usage policy.  The
+	    <literal>pool</literal> configuration keyword selects one or more
+	    servers from a pool of servers.  An <link
+	      xlink:href="http://support.ntp.org/bin/view/Servers/NTPPoolServers">;
+	      online list of publicly accessible <acronym>NTP</acronym>
+	      pools</link>
+	    is available, organized by geographic area.  In addition, &os;
+	    provides a project-sponsored pool,
+	    <literal>0.freebsd.pool.ntp.org</literal>.</para>
 
-      <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.  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>
+	<example>
+	  <title>Sample <filename>/etc/ntp.conf</filename></title>
+	  <para>This is a simple example of an <filename>ntp.conf</filename>
+	    file.  It can safely be used as-is; it contains the recommended
+	    <literal>restrict</literal> options for operation on a
+	    publicly-accessible network connection.</para>
+	  <programlisting>
+# Disallow ntpq control/query access.  Allow peers to be added only
+# based on pool and server statements in this file.
+restrict default limited kod nomodify notrap noquery nopeer
+restrict source  limited kod nomodify notrap noquery
 
-      <para>The <literal>driftfile</literal> entry specifies which
-	file is used to store the system clock's frequency offset.
-	<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.  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>
+# Allow unrestricted access from localhost for queries and control.
+restrict 127.0.0.1
+restrict ::1
 
-      <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>
+# Add a specific server.
+server ntplocal.example.com iburst
 
-      <programlisting>restrict default ignore</programlisting>
+# Add FreeBSD pool servers until 3-6 good servers are available.
+tos minclock 3 maxclock 6
+pool 0.freebsd.pool.ntp.org iburst
 
-      <note>
-	<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>
+# Use a local leap-seconds file.
+leapfile "/var/db/ntpd.leap-seconds.list"</programlisting></example>
 
-      <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 be used as peers to synchronize
-	against, instead use:</para>
+	<para>The format of this file is described in &man.ntp.conf.5;.
+	  The descriptions below provide a quick overview of just the
+	  keywords used in the sample file above.</para>
 
-      <programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting>
+	<para>By default, an <acronym>NTP</acronym> server is accessible
+	  to any network host.  The <literal>restrict</literal> keyword
+	  controls which systems can access the server.  Multiple
+	  <literal>restrict</literal> entries are supported, each one
+	  refining the restrictions given in previous statements.  The
+	  values shown in the example grant the local system full query
+	  and control access, while allowing remote systems only the
+	  ability to query the time.  For more details, refer to the
+	  <literal>Access Control Support</literal> subsection of
+	  &man.ntp.conf.5;.</para>
 
-      <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
-	subnet mask.</para>
+	<para>The <literal>server</literal> keyword specifies a single
+	  server to query.  The file can contain multiple server keywords,
+	  with one server listed on each line.  The <literal>pool</literal>
+	  keyword specifies a pool of servers.
+	  <application>Ntpd</application> will add one or more
+	  servers from this pool as needed to reach the number of peers
+	  specified using the <literal>tos minclock</literal> value.  The
+	  <literal>iburst</literal> keyword directs
+	  <application>ntpd</application> to perform a burst of eight quick
+	  packet exchanges with a server when contact is first established,
+	  to help quickly synchronize system time.</para>
 
-      <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>
+	<para>The <literal>leapfile</literal> keyword specifies the location
+	  of a file containing information about leap seconds.  The file is
+	  updated automatically by &man.periodic.8;.  The file location
+	  specified by this keyword must match the location set in the
+	  <literal>ntp_db_leapfile</literal> variable in
+	  <filename>/etc/rc.conf</filename>.</para>
+      </sect3>
 
-      <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>
+      <sect3>
+	<title>NTP entries in <filename>/etc/rc.conf</filename></title>
 
-      <screen>&prompt.root; <userinput>service ntpd start</userinput></screen>
+	<indexterm><primary>NTP</primary>
+	  <secondary>rc.conf</secondary>
+	</indexterm>
+
+	<para>Set <literal>ntpd_enable=YES</literal> to start
+	  <application>ntpd</application> at boot time.  Once
+	  <literal>ntpd_enable=YES</literal> has been added
+	  to <filename>/etc/rc.conf</filename>,
+	  <application>ntpd</application> can be started immediately without
+	  rebooting the system by typing:</para>
+
+	<screen>&prompt.root; <userinput>service ntpd start</userinput></screen>
+
+	<para>Only <literal>ntpd_enable</literal> must be set to use ntpd.
+	The <filename>rc.conf</filename> variables listed below may also be
+	set as needed.</para>
+
+	<para>Set <literal>ntpd_sync_on_start=YES</literal> to allow
+	  <application>ntpd</application> to step the clock any amount, one
+	  time at startup.  Normally <application>ntpd</application> will
+	  log an error message and exit if the clock is off by more than
+	  1000 seconds.  This option is especially useful on systems without
+	  a battery-backed realtime clock.</para>
+
+	<para>Set <literal>ntpd_oomprotect=YES</literal> to protect the
+	  <application>ntpd</application> daemon from being killed by
+	  the system attempting to recover from an Out Of Memory
+	  (<acronym>OOM</acronym>) condition.</para>
+
+        <para>Set <literal>ntpd_config=</literal> to the location of
+	  an alternate <filename>ntp.conf</filename> file.</para>
+
+	<para>Set <literal>ntpd_flags=</literal> to contain any other
+	  <application>ntpd</application> flags as needed, but avoid using
+	  these flags which are managed internally by
+	  <filename>/etc/rc.d/ntpd</filename>:
+	  <itemizedlist spacing='compact'>
+	    <listitem><para>
+	      <literal>-p</literal> (pid file location)</para></listitem>
+	    <listitem><para>
+	      <literal>-c</literal> (set <literal>ntpd_config=</literal>
+	      instead)</para></listitem>
+	  </itemizedlist></para>
+      </sect3>
+
+      <sect3>
+	<title><application>Ntpd</application> and the unpriveleged
+	  <literal>ntpd</literal> user</title>
+
+	<para><application>Ntpd</application> on &os; can start and
+	  run as an unpriveleged user.  Doing so requires the
+	  &man.mac.ntpd.4; policy module.  The
+	  <filename>/etc/rc.d/ntpd</filename> startup script first
+	  examines the NTP configuration.  If possible, it loads the
+	  <literal>mac_ntpd</literal> module, then starts
+	  <application>ntpd</application> as unpriveleged user
+	  <literal>ntpd</literal> (user id 123).
+	  To avoid problems with file and directory access, the startup
+	  script will not automatically start
+	  <application>ntpd</application> as <literal>ntpd</literal>
+	  when the configuration contains any file-related options.</para>
+
+	<para>The presence of any of the following in
+	  <literal>ntpd_flags</literal> requires manual configuration
+	  as described below to run as the <literal>ntpd</literal> user:
+	  <itemizedlist spacing='compact'>
+	    <listitem><para>-f or --driftfile</para></listitem>
+	    <listitem><para>-i or --jaildir</para></listitem>
+	    <listitem><para>-k or --keyfile</para></listitem>
+	    <listitem><para>-l or --logfile</para></listitem>
+	    <listitem><para>-s or --statsdir</para></listitem>
+	  </itemizedlist></para>
+
+	<para>The presence of any of the following keywords in
+	  <filename>ntp.conf</filename> requires manual configuration
+	  as described below to run as the <literal>ntpd</literal> user:
+	  <itemizedlist spacing='compact'>
+	    <listitem><para>crypto</para></listitem>
+	    <listitem><para>driftfile</para></listitem>
+	    <listitem><para>key</para></listitem>
+	    <listitem><para>logdir</para></listitem>
+	    <listitem><para>statsdir</para></listitem>
+	    </itemizedlist></para>
+
+	<para>To manually configure <application>ntpd</application>
+	  to run as user <literal>ntpd</literal> you must:
+	  <itemizedlist mark='none' spacing='compact'>
+	    <listitem><para>Ensure that the <literal>ntpd</literal>
+	      user has access to all the files and directories specified
+	      in the configuration.</para></listitem>
+	    <listitem><para>Arrange for the <literal>mac_ntpd</literal>
+	      module to be loaded or compiled into the kernel.  See
+	      &man.mac.ntpd.4; for details.</para></listitem>
+	    <listitem><para>Set <literal>ntpd_user="ntpd"</literal> in
+	      <filename>/etc/rc.conf</filename></para></listitem>
+	  </itemizedlist></para>
+      </sect3>
     </sect2>
 
     <sect2>



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