29.11. Clock Synchronization with NTP

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 (NTP) is one way to provide clock accuracy in a network.

FreeBSD includes ntpd(8) which can be configured to query other NTP servers to synchronize the clock on that machine or to provide time services to other computers in the network.

This section describes how to configure ntpd on FreeBSD. Further documentation can be found in /usr/share/doc/ntp/ in HTML format.

29.11.1. NTP Configuration

On FreeBSD, the built-in ntpd can be used to synchronize a system's clock. Ntpd is configured using rc.conf(5) variables and /etc/ntp.conf, as detailed in the following sections.

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.

29.11.1.1. The /etc/ntp.conf file

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, FreeBSD provides a project-sponsored pool, 0.freebsd.pool.ntp.org.

Example 29.4. Sample /etc/ntp.conf

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

# Allow unrestricted access from localhost for queries and control.
restrict 127.0.0.1
restrict ::1

# Add a specific server.
server ntplocal.example.com iburst

# Add FreeBSD pool servers until 3-6 good servers are available.
tos minclock 3 maxclock 6
pool 0.freebsd.pool.ntp.org iburst

# Use a local leap-seconds file.
leapfile "/var/db/ntpd.leap-seconds.list"

The format of this file is described in ntp.conf(5). The descriptions below provide a quick overview of just the keywords used in the sample file above.

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 ntp.conf(5).

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.

The leapfile keyword specifies the location of a file containing information about leap seconds. The file is updated automatically by periodic(8). The file location specified by this keyword must match the location set in the ntp_db_leapfile variable in /etc/rc.conf.

29.11.1.2. NTP entries in /etc/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:

# 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)

29.11.1.3. Ntpd and the unpriveleged ntpd user

Ntpd on FreeBSD can start and run as an unpriveleged user. Doing so requires the 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 mac_ntpd(4) for details.

  • Set ntpd_user="ntpd" in /etc/rc.conf

29.11.2. Using NTP with a PPP Connection

ntpd does not need a permanent connection to the Internet to function properly. However, if a PPP connection is configured to dial out on demand, NTP traffic should be prevented from triggering a dial out or keeping the connection alive. This can be configured with filter directives in /etc/ppp/ppp.conf. For example:

set filter dial 0 deny udp src eq 123
# Prevent NTP traffic from initiating dial out
set filter dial 1 permit 0 0
set filter alive 0 deny udp src eq 123
# Prevent incoming NTP traffic from keeping the connection open
set filter alive 1 deny udp dst eq 123
# Prevent outgoing NTP traffic from keeping the connection open
set filter alive 2 permit 0/0 0/0

For more details, refer to the PACKET FILTERING section in ppp(8) and the examples in /usr/share/examples/ppp/.

Note:

Some Internet access providers block low-numbered ports, preventing NTP from functioning since replies never reach the machine.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.