NTP

The Network Time Protocol (NTP) is used to synchronize your system's time to another system's time.

Since high precision online servers feed the Internet with a high quality shared time, NTP allows the synchronization of every computer in the world in a very accurate fashion.

is a very useful application, and should be installed on every machine, to grant time synchronization, proper file and directory times, expected cron behavior, appropriate logs and so on.

can also be used to serve time for a network. For example a LAN consisting of Windows and Linux machines can all synchronize to a single NTP server, saving bandwidth.

There are alternative programs to perform time synchronization via NTP, such as OpenNTPD and Chrony.

About the NTP logic
The NTP protocol is a client/server protocol but also a peer-to-peer protocol.

The servers, in fact, can synchronize each other in a symmetric way.

Referring to a limited number of stratum 1 servers -- directly connected to the high precision clocks (atomic clocks, GPS receivers, Loran receivers...) -- all other servers take the time from the lower stratum and synchronize each other within the same stratum.

In general, computers away from a clock by the same number of hops are said to be in the same stratum. Computers never synchronized are known to be in the stratum 16.

Computers in stratum 1 are not always public. Computers using a local reference clock are stratum 1 by default if it is functioning correctly. In addition a computer using a reference clock does not need to be connected to the network to be a high precision time keeper.

You can find stratum 2 (or higher) servers available on the net and many people try to find stratum 2 servers in their own country to get the best time synchronization.

If you can connect your computers directly to the Internet, normally you'll refer to such stratum 2 servers, but if your computers are connected to each other (for example in a LAN), they can also act as stratum 3 (or higher) and synchronize themselves in the peer-to-peer way.

See the links at the very bottom part of this page to learn more.

Installation
Normally, you'll run NTP as a service, called ntpd. ntpd can (and should) easily be set up to run as a non-root user, defaulting to user ntp.

If you want to drop root privileges running the NTP daemon, make sure that your kernel has been compiled with the following options (>=2.6.26):

Then you must activate the USE flag:

If you want to use a local hardware reference clock such as a GPS receiver you will need to enable PPS functionality in the kernel (>=2.6.32, >=2.6.38 for the kernel consumer). PPS support can be either built into the kernel or it can be a module. If you build it as a module the module name is pps_core. For most setups the reference clock and the PPS signal will be connected to a serial port and Parallel port PPS is not needed. If you have a new enough kernel using the PPS kernel consumer is recommended.:

Then you must activate the USE flag to have PPS support and the clock drivers in ntp:

Also for full PPS support you will need net-misc/ntp-4.2.6_p3-r1 or later. Unmask as needed.

Finally, to install, emerge it as usual:

Configuration
The behavior of NTP is driven by.

Via this file you can control especially three features of the ntpd service:
 * the servers to connect to, as client;
 * the clients allowed to connect to your service;
 * the hosts to connect to as peers.

The servers and local reference clocks are indicated via the directive, that you must repeat once per server or clock. The option is highly recommended to improve the initial behavior.

The clients and peers are allowed by default to connect to your server. You can manage the restrictions via the directive. Note that a rule with no options "indicates that free access to the server is to be given" (see the man page).

The directive indicates the peers to search for.

To learn more, read the (large) man page:

For more information on using a hardware reference clock on Linux see: LinuxPPS hardware clock configuration page

If you have a low-speed/high-latency connection, and if you have iburst option set, consider the calldelay directive.

Configuration examples
See the section below to find the best time servers.

Motorola Oncore reference clocks also require a separate configuration file. The naming conventions is /etc/ntp.oncore.u where u corresponds to the unit number used in the server line for the Oncore in the /etc/ntp.conf file. For the above example this is unit 0.

Local reference clock drivers expect certain device names and you will need to setup symlinks to the hardware devices so that the drivers can find the devices. This can be done using udev. Here is an example file for an Oncore GPS and a Garmin GPS 18 LVC NMEA GPS but this is basically how this can be done for any of the other reference clock types but the SYMLINK's will need to be changed to what the driver expects. Note for Oncore devices the the device name ends with the unit number and this needs to match what is used in the ntp.conf file for the server line for this device:

Lastly you will need to setup an init script to create the line discipline for the PPS device before starting ntp. Here is an example:

To set the serial port for the line discipline use a configuration file like this one:

Find a Time Server
There are many public time servers around the world.

The default Gentoo configuration includes a list of "Pools for Gentoo users" (see the example above), but you can choose a server in your own country or right inside your network (if any).

Perhaps the best choice is to start looking for a good set of stratum 2 official public servers.

Generally, you can start reading the official server list, to find geographic servers and low stratum servers.

If you want to learn more about official server you can check the NTP Project site. The NTP Pool Project is a very interesting reading, too.

Finally, you can test the chosen servers via:

or

The last command is available after:

If you are in a corporate or similar local context, perhaps they have one or more local NTP servers, well connected to public servers. In a Windows world you could use a Domain Controller (DC). Ask to your network administrator for that.

If your network rules don't allow you to connect to a public server, an internal server should exist.

Be a Time Server
Simply uncomment the last line of the configuration example:

Naturally, the address/mask pair must match your network configuration and preferences.

If you want to share your time as peer, you have to omit the option and add this kind of line:

If you have a public IP address and if you want to take part in a pool, read joining the pool.

Zeroconf
If you want to publish the NTP server service on your local network using Zeroconf, add to ,

Restart the ntpd for the changes to take effect,

See the Avahi article for more information.

Running the ntpd service
should always be run as service, to grant permanent and accurate clock synchronization.

As usual, start the service:

And, register the service in your default runlevel, to make it start automatically at the boot:

If you are using a PPS device with an init script like the example /etc/init.d/ntp-pps above substitute it for the ntpd scripts in the above commands like this:

Setting the hardware clock during shutdown
Hardware clocks are not very accurate. (See the NTP.org article on clock quality.)

Systems keep the clock accuracy up via software techniques, but when you power off a computer, the hardware time could significantly drift.

To avoid this, you can set your hardware clock during shutdown. For baselayout < 2.0.0:

For baselayout >= 2.0.0:

Checking ntp
It may take up to 4 hours of semi-continuous reachability to calibrate the clock before you achieve right stratum status. If the stratum status hasn't changed in a few hours, your synchronization is definitely failing. If you are using a local reference clock and the kernel consumer the clock should sync in less than 10 minutes. Without the kernel consumer it can take several hours for the clock to sync.

From synchronization with stratum 2 servers, your stratum should settle at stratum 3. If you are using a local reference clock your server will be stratum 1 once the clock syncs.

You can check your stratum status (and other info):

assID=0 status=06c4 leap_none, sync_ntp, 12 events, event_peer/strat_chg, version="ntpd 4.2.4p5@1.1541-o dom nov 23 01:53:44 UTC 2008 (1)", processor="x86_64", system="Linux/2.6.26-gentoo-r3-s2", leap=00, stratum=3, precision=-20, rootdelay=1058.355, rootdispersion=197.731, peer=52626, refid=146.48.81.102, reftime=ccd71166.f658267e Wed, Nov 26 2008  1:05:58.962, poll=6, clock=ccd711f3.a404822a Wed, Nov 26 2008  1:08:19.640, state=4, offset=102.200, frequency=-2.919, jitter=47.034, noise=54.332, stability=0.349, tai=0

You can check what peers you are connected to (and in turn what they are connected to):

remote          refid      st t when poll reach   delay   offset  jitter ============================================================================== xntp2.inrim.it  .UTCI. 1 u   8  128  377  1374.95  301.984  42.437 *saguaro.bilink. 193.204.114.232 2 u    5  128  373  522.163  -172.36 103.515 +ns1.nexellent.n 193.67.79.202   2 u    4  128  337  693.205  -95.659 257.506 +jane.telecom.mi 129.69.1.153    2 u    6   64  337  646.135  -101.23 223.258 -tucano.isti.cnr 193.204.114.232 2 u    1  128  317  141.040  -314.45 243.724 -kraken2.bilink. 193.204.114.232 2 u    2  128  377  122.122  -349.67 303.197 +host219-54-stat 193.204.114.232 2 u    4   64  157  413.224  -180.87  89.052 -h180.argonavis. 62.173.184.58   3 u   62   64  377  112.123  -352.11 295.195 lap            192.108.114.23   3 u   19   64  377    0.001  229.477   6.025

For a local reference clock you can check server status and other information with: ntp_gettime returns code 0 (OK) time d1c87d4b.fa2b05e0 Wed, Jul 13 2011 13:23:39.977, (.977219348), maximum error 2233 us, estimated error 1 us, TAI offset 0 ntp_adjtime returns code 0 (OK) modes 0x0 , offset 0.000 us, frequency -37.929 ppm, interval 256 s,  maximum error 2233 us, estimated error 1 us, status 0x2107 (PLL,PPSFREQ,PPSTIME,PPSSIGNAL,NANO), time constant 4, precision 0.001 us, tolerance 500 ppm, pps frequency -37.931 ppm, stability 0.022 ppm, jitter 2.112 us, intervals 96, jitter exceeded 31, stability exceeded 2, errors 0.

The example above is for a Motorola Oncore UT+ with kernel 2.6.38-r6 using the kernel consumer.

After some hour of connection, if your computer hangs in the stratum 16 something is going wrong. See the section to resolve.

Setting time now
The comes with a set of options and tools useful to perform a quick and dirty clock synchronization.

These tools, however, should not be confused with the deprecated tools (and with the deprecated startup logic).

If you want to synchronize your system manually, without starting a service, you can run:

This will start the service and keep it on until it performs a good synchronization, then it leaves.

The previous command is not yet a quick and dirty command. It performs many requests and drift back the system clock slowly, to avoid time jumps.

If you need set up your time really quickly (for example if your system time is totally wrong and you're not afraid of time jumps), you can run:

Setting time at boot
If you really need a quick time synchronization during boot, you can activate the service, provided by.

As of, the Gentoo service uses the deprecated  command (see the man page).

You can easily switch to the command in the manner shown below. works much faster (in a fraction of a second) than (which takes a few seconds).

where you'll choose your best servers.

Then you can start the service and load it at default runlevel, in the usual manner.

The actual indication, however, doesn't require this.

See this pitched discussion (with some dust up) to learn more.

If there is no connection at boot, ntp-client will issue the error message name server cannot be used, reason: Temporary failure in name resolution. This may be addressed by setting in, or by increasing the timeout for ntp-client. If you are using as a network manager, your network interfaces will stay inactive even if they reach the "started" stage. In this case, you can take out of the default runlevel and activate  with a script in  and  (see this thread in the Gentoo forums).

Firewall configuration
NTP uses UDP port 123. TCP is not used.

To synchronize with external time servers, the following standard iptables rule is sufficient:

If you want to serve time, you need that your 123 UDP port be reachable. Add this before the corresponding lines

More information on IPTABLES firewall and its settings can be found in the Gentoo Handbook.

DHCP
If you are using DHCP to get an IP address, dhcpcd will overwrite by default.

If your DHCP server hands out a valid NTP server, this is not a problem. If it does not, you will want to make sure dhcpcd will not overwrite this file.

You can do this by editing as such:

where eth0 is the interface that uses dhcpcd. This section used to suggest using the -N option; however, it seems -N, -R, and -Y have all been removed and replaced by -C -- where is the config file you intend to prevent dhcpcd from overwriting. See the dhcpcd man page for more information.

If you are using instead of dhcpcd to retrieve an IP address, it will also overwrite. By editing you can avoid this.

Edit the file to read something like this:

More information on DHCP and its settings can be found in the Gentoo Handbook.

PPP and discontinuous connections
If your Internet connection is a ppp discontinuous connection (e.g. a dial-up connection or a GPRS/UMTS/HSDPA connection) and if you start/stop the ntpd service in the typical runlevel related mode, the ntpd daemon will fill your logs with a garbage of annoying error messages when the Internet connection is down.

To avoid this, you can keep the start/stop scripts off from your runlevels and add two simple scripts in the and  directories:

(Don't forget to perform some test to establish the best sleeping time.)

Obviously, in this way you cannot act as a good ntpd server for a LAN.

In addition, you should consider the low-speed/high-latency of most PPP connection. If you set the option (see above), use a different  could be a good idea:

Time is wrong by several hours
If shows the wrong hour, then check  and  in the localization guide and handbook.

Run:

(rather than ntpd) to instantly set the time - quick and dirty.

Clock drifts
If the clock moves faster or slower than normal, then try adding to the kernel line in.

No server suitable for synchronization found
Client machines will refuse to synchronize from a stratum 16 time server, with the error message no server suitable for synchronization found.

If you use the Gentoo Home Router Guide it blocks incoming requests to privileged ports. To avoid this, comment out the two lines

Or add the following above the drop lines:

Bad file descriptor
If you are seeing Bad file descriptor errors in, then make sure that only one instance of is running:

Error : Servname not supported for ai_socktype
If you are seeing the error message Error : Servname not supported for ai_socktype, then run:

Gnome's time & date settings
If you have previously tried to set up NTP through Gnome's time & date settings, and are seeing Failed to set clock or NTP socket is in use errors, then uncheck Gnome's "Synchronize clock with Internet servers" box.

Access Restrictions
If ntpd won't connect with the servers, the access restrictions could be too strict. For example

Here the does ignore all packets, even those answers from the time servers. Output from the command looks like this: {{Code|ntpq -c peers| remote          refid      st t when poll reach   delay   offset  jitter

=
================================================================= tack.Informatik .INIT. 16 u   - 1024    0    0.000    0.000 4000.00 }} Solution: If you have a firewall which filters access to port 123, you can leave the restrictions a bit lesser like this:

Without a firewall you can write a strong default restriction and add lesser restrictions for each time server:

But you have to manage the restrictions for each time server, which could be too much work to do. It is better to use a firewall. Note that this example is also inaccurate, as you can't specify hostnames in restrict lines, only IP addresses, which further complicates things.

Also don't forget that if you use the nopeer keyword, then ntpd won't synchronise against any servers covered by that restrict line! (So in the above example, ntpd will never sync against anything, because the two timeservers are listed as nopeer and everything else is covered by the ignore line.)

Failed to Drop root Privileges
If ntpd does not start and contains the error message, cap_set_proc failed to drop root privileges: Operation not permitted, then check that the kernel "capability" module is loaded, as referred to above.

If the server simply runs as root, then check that you emerged with the  enabled.

Then check that your appears like this:

When in doubt.
If you double checked everything and made sure all your configurations, firewalls, permissions and what not were correct, you may want to double check and make sure the current time is correct. If the time or date is off by a significant amount ntpd will fail to synchronize. So when in doubt try setting the time manually and restarting ntpd.

Other Problems
Read the NTP troubleshooting guide, which includes some online tools for remotely querying your server, to make sure your firewall or your ISP's firewall isn't blocking TCP/UDP port 123.