29.11. Clock Synchronization with NTP
Prev | Chapter 29. Network Servers | Next

## 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.3. 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.

Prev | Up | Next
29.10. File and Print Services for Microsoft® Windows® Clients (Samba) | Home | 29.12. iSCSI Initiator and Target Configuration

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>.