From owner-svn-doc-all@freebsd.org Mon Sep 16 02:12:39 2019 Return-Path: Delivered-To: svn-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id A463AEFA79; Mon, 16 Sep 2019 02:12:39 +0000 (UTC) (envelope-from ian@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 46WqWq4c8Bz40lX; Mon, 16 Sep 2019 02:12:39 +0000 (UTC) (envelope-from ian@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 68F4D1973F; Mon, 16 Sep 2019 02:12:39 +0000 (UTC) (envelope-from ian@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id x8G2Cdod053298; Mon, 16 Sep 2019 02:12:39 GMT (envelope-from ian@FreeBSD.org) Received: (from ian@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id x8G2CdLh053297; Mon, 16 Sep 2019 02:12:39 GMT (envelope-from ian@FreeBSD.org) Message-Id: <201909160212.x8G2CdLh053297@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: ian set sender to ian@FreeBSD.org using -f From: Ian Lepore Date: Mon, 16 Sep 2019 02:12:39 +0000 (UTC) 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 X-SVN-Group: doc-head X-SVN-Commit-Author: ian X-SVN-Commit-Paths: head/en_US.ISO8859-1/books/handbook/network-servers X-SVN-Commit-Revision: 53407 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 16 Sep 2019 02:12:39 -0000 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. provide clock accuracy in a network. &os; includes &man.ntpd.8; which can be configured to query - other NTP 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 ISP. - In addition, an online - list of publicly accessible NTP - servers is available. When choosing a public - NTP server, select one that is geographically - close and review its usage policy. + other NTP servers to synchronize the clock on + that machine or to provide time services to other computers in + the network. - Choosing several NTP servers is - recommended in case one of the servers becomes unreachable or - its clock proves unreliable. As ntpd - receives responses, it favors reliable servers over the less - reliable ones. - This section describes how to configure ntpd on &os;. Further documentation can be found in /usr/share/doc/ntp/ in HTML @@ -4262,99 +4249,210 @@ Starting smbd. <acronym>NTP</acronym> Configuration - NTP - ntp.conf - + NTP On &os;, the built-in ntpd can - be used to synchronize a system's clock. To enable - ntpd at boot time, add - ntpd_enable="YES" to - /etc/rc.conf. Additional variables can - be specified in /etc/rc.conf. Refer to - &man.rc.conf.5; and &man.ntpd.8; for - details. + be used to synchronize a system's clock. + Ntpd is configured using &man.rc.conf.5; + variables and /etc/ntp.conf, as detailed + in the following sections. - This application reads /etc/ntp.conf - to determine which NTP servers to query. - Here is a simple example of an - /etc/ntp.conf: + Ntpd 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. - - Sample <filename>/etc/ntp.conf</filename> + + The <filename>/etc/ntp.conf</filename> file - server ntplocal.example.com prefer -server timeserver.example.org -server ntp2a.example.net + NTP + ntp.conf + -driftfile /var/db/ntp.drift - + Ntpd reads + /etc/ntp.conf + to determine which NTP servers to query. + Choosing several NTP servers is recommended + in case one of the servers becomes unreachable or its clock proves + unreliable. As ntpd 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 + ISP, or selected from an + online list of publicly accessible NTP + servers. + When choosing a public NTP server, select one + that is geographically close and review its usage policy. The + pool configuration keyword selects one or more + servers from a pool of servers. An + online list of publicly accessible NTP + pools + is available, organized by geographic area. In addition, &os; + provides a project-sponsored pool, + 0.freebsd.pool.ntp.org. - The format of this file is described in &man.ntp.conf.5;. - The server option specifies which servers - to query, with one server listed on each line. If a server - entry includes prefer, 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 - prefer argument should only be used for - NTP servers that are known to be highly - accurate, such as those with special time monitoring - hardware. + + Sample <filename>/etc/ntp.conf</filename> + This is a simple example of an ntp.conf + file. It can safely be used as-is; it contains the recommended + restrict options for operation on a + publicly-accessible network connection. + +# 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 - The driftfile entry specifies which - file is used to store the system clock's frequency offset. - ntpd 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 NTP servers. Since this file contains - internal information for NTP, it should not - be modified. +# Allow unrestricted access from localhost for queries and control. +restrict 127.0.0.1 +restrict ::1 - By default, an NTP server is accessible - to any network host. The restrict option - in /etc/ntp.conf can be used to control - which systems can access the server. For example, to deny all - machines from accessing the NTP server, add - the following line to - /etc/ntp.conf: +# Add a specific server. +server ntplocal.example.com iburst - restrict default ignore +# Add FreeBSD pool servers until 3-6 good servers are available. +tos minclock 3 maxclock 6 +pool 0.freebsd.pool.ntp.org iburst - - This will also prevent access from other - NTP servers. If there is a need to - synchronize with an external NTP server, - allow only that specific server. Refer to &man.ntp.conf.5; - for more information. - +# Use a local leap-seconds file. +leapfile "/var/db/ntpd.leap-seconds.list" - 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: + 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. - restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap + By default, an NTP server is accessible + to any network host. The restrict keyword + controls which systems can access the server. Multiple + restrict 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 + Access Control Support subsection of + &man.ntp.conf.5;. - where 192.168.1.0 is the local - network address and 255.255.255.0 is the network's - subnet mask. + The server keyword specifies a single + server to query. The file can contain multiple server keywords, + with one server listed on each line. The pool + keyword specifies a pool of servers. + Ntpd will add one or more + servers from this pool as needed to reach the number of peers + specified using the tos minclock value. The + iburst keyword directs + ntpd to perform a burst of eight quick + packet exchanges with a server when contact is first established, + to help quickly synchronize system time. - Multiple restrict entries are - supported. For more details, refer to the Access - Control Support subsection of - &man.ntp.conf.5;. + The leapfile 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 + ntp_db_leapfile variable in + /etc/rc.conf. + - Once ntpd_enable="YES" has been added - to /etc/rc.conf, - ntpd can be started now without - rebooting the system by typing: + + NTP entries in <filename>/etc/rc.conf</filename> - &prompt.root; service ntpd start + NTP + rc.conf + + + Set ntpd_enable=YES to start + ntpd at boot time. Once + ntpd_enable=YES has been added + to /etc/rc.conf, + ntpd can be started immediately without + rebooting the system by typing: + + &prompt.root; service ntpd start + + Only ntpd_enable must be set to use ntpd. + The rc.conf variables listed below may also be + set as needed. + + Set ntpd_sync_on_start=YES to allow + ntpd to step the clock any amount, one + time at startup. Normally ntpd 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. + + Set ntpd_oomprotect=YES to protect the + ntpd daemon from being killed by + the system attempting to recover from an Out Of Memory + (OOM) condition. + + Set ntpd_config= to the location of + an alternate ntp.conf file. + + Set ntpd_flags= to contain any other + ntpd flags as needed, but avoid using + these flags which are managed internally by + /etc/rc.d/ntpd: + + + -p (pid file location) + + -c (set ntpd_config= + instead) + + + + + <application>Ntpd</application> and the unpriveleged + <literal>ntpd</literal> user + + Ntpd on &os; can start and + run as an unpriveleged user. Doing so requires the + &man.mac.ntpd.4; policy module. The + /etc/rc.d/ntpd startup script first + examines the NTP configuration. If possible, it loads the + mac_ntpd module, then starts + ntpd as unpriveleged user + ntpd (user id 123). + To avoid problems with file and directory access, the startup + script will not automatically start + ntpd as ntpd + when the configuration contains any file-related options. + + The presence of any of the following in + ntpd_flags requires manual configuration + as described below to run as the ntpd user: + + -f or --driftfile + -i or --jaildir + -k or --keyfile + -l or --logfile + -s or --statsdir + + + The presence of any of the following keywords in + ntp.conf requires manual configuration + as described below to run as the ntpd user: + + crypto + driftfile + key + logdir + statsdir + + + To manually configure ntpd + to run as user ntpd you must: + + Ensure that the ntpd + user has access to all the files and directories specified + in the configuration. + Arrange for the mac_ntpd + module to be loaded or compiled into the kernel. See + &man.mac.ntpd.4; for details. + Set ntpd_user="ntpd" in + /etc/rc.conf + +