General Configuration
The NTP daemon reads its configuration from a file named ntp.conf. On UNIX-like systems, this file is located in the /etc directory by default.
On Windows platforms, if a recent NTP version has been installed using the GUI installer from the Meinberg NTP download page, the ntp.conf file is located in an etc\ directory below the NTP program directory, e.g. in c:\Program Files\NTP\etc. Earlier versions of NTP for Windows assumed the ntp.conf file to be located in either %systemroot% or %systemroot%\system32\drivers\etc, where %systemroot% corresponds to c:\winnt or c:\windows in standard installations.
In most installations the ntp.conf file contains at least one or more lines starting with the keyword server. Each of those lines specifies one reference time source which can be either another computer on the network, or a radio clock connected to the local computer.
Reference time sources are specified using IP addresses, or host names which can be resolved by a name server. If an IP address represents a real node on the network then the NTP daemon assumes another NTP daemon running on a computer with that address. Additionally, NTP uses some pseudo IP addresses to specifiy special reference time sources.
For example, NTP uses a pseudo IP address 127.127.8.n to access a Meinberg radio clock installed at the local computer. To access its own system clock, also called the local clock, NTP uses the pseudo IP address 127.127.1.0. This IP address must not be mixed up with 127.0.0.1, which is the IP of the localhost, i.e. the computer's loopback interface.
Attention:
Some older versions of NTP have problems with DNS name resolution under Windows, if the programm package
has been compiled with MD5 authentication. In this case all TCP/IP addresses in the ntp.conf file
must be entered in dotted decimal notation (e.g. 172.16.1.1) rather than DNS name like
host.domain.com.
Configuration With Meinberg Radio Clock or GPS (Unix)
There's also a Linux driver for Meinberg PC plug-in cards available on the Meinberg software download page. Besides ways to configure and monitor the plug-in cards this driver provides a software interface which lets NTP's parse driver read the reference time from a plug-in card rather than via a serial port under Linux. This driver is not required for devices which are directly connected via a serial port.
The configuration steps described below must be done by a user with sufficient rights on the system, e.g. root. The parse driver accesses radio clocks via symbolic links /dev/refclock-n, where n is an index number in the range 0 through 3 since the parse driver can handle up to four reference clocks at the same time.
Each symbolic link must point to a physical device which represents an existing radio clock. In most cases the physical device is a serial port at which a radio clock has been connected externally. However, under Linux this link can also point to a device node which represents a plugin card.
Each of the reference clocks must also be specified in the ntp.conf file using a server line with the pseudo IP address 127.127.8.n, where n must correspond to the index numbers used with the symbolic device names /dev/refclock-n mentioned above.
The pseudo IP address must be followed by a mode m parameter which specifies the type of radio clock represented by the device. The table below lists the mode values which can be used with Meinberg radio clocks:
| mode number | radio clock | trust time |
|---|---|---|
| mode 0 | Meinberg PZF clock with TCXO | 12 hours |
| mode 1 | Meinberg PZF clock with OCXO | 4 days |
| mode 2 | Meinberg Standard Time String with 9600, 7E2 | 30 minutes |
| mode 7 | Meinberg GPS with OCXO, 19200, 8N1 | 4 days |
For example, if a single radio clock is connected to the serial port /dev/ttyS0 then a symbolic link for the clock must be set up using the command
ln -s /dev/ttyS0 /dev/refclock-0
If a PC plug-in board with the Meinberg Linux driver shall be used as reference time source for NTP, thesymbolic link must point to the device implemented by that driver:
ln -s /dev/mbgclock0 /dev/refclock-0
Please note: Recent versions of the Meinberg driver package for Linux create the /dev/refclock-* links automatically using the Linux udev system. In older versions of the driver package (before 3.0.0) the link had to be created manually, and the device node to be used for the refclock link was named /dev/mbgntp. If in doubt please see the README file which comes with the driver package.
In the next step the file ntp.conf must be edited to configure the NTP daemon and tell it which reference clocks to use. The file should include a server line for the refclock-0 device created above. If the radio clock sends the Meinberg standard time string at 9600 baud and framing 7E2 then, as can be seen from the table above, the mode for refclock-0 must be set to 2. Also, if plug-in card is used under Linux then mode 2 must always be used:
server 127.127.8.0 mode 2 # standard time string with 9600, 7E2
Additionally, there should be an entry for the local clock which can be used as a fallback resource if no other time source is available. Since the local clock is not very accurate, it should be fudged to a low stratum:
server 127.127.1.0# local clock fudge 127.127.1.0 stratum 12
Now the NTP daemon must be started (or restarted) to let the changes take effect. If the daemon has been shipped with the operating system then it may have support for Meinberg clocks compiled in, or not.
If the output of the command ntpq -p lists a clock labeled generic then everything is fine and the NTP daemon supports the reference clock.
If the generic clock is not listed in the ntpq output then the NTP package may have been compiled without support for the parse clocks, or the NTP daemon may not have permission to access the device. The syslog messages from the NTP daemon after startup should indicate the real reason for the problem.
The permission denied problem can occur with plug-in cards under recent Linux distributions which come with AppArmor or SELinux security tools enabled. See the README file from the Linux driver package for details and how to fix this problem.
If the existing NTP daemon has been built without support for the parse clocks then the NTP package must be reconfigured and recompliled on the target platform. This requires a compiler package installed on the target platform, and the source code of the NTP distribution.
In the example below name is the base name of the NTP source package which is normally distributed as a file name.tar.gz which must be uncompressed on the target computer:
tar xvzf name.tar.gz
To compile the package, change into the NTP base directory, and run configure and make to build the programs. You may use the following commands:
cd name ./configure --enable-MEINBERG make
After the build procedure has finished successfully each of the new programs is available in its own subdirectory which has the same name as the program itself. Make sure there's no old version of ntpd or xntpd running, then start the new NTP daemon by entering
ntpd/ntpdif a ntp-4.* package has been compiled, or
xntpd/xntpdif a xntp3 package has been compiled.
The command ntpq -p can be used to verify that the new daemon works correctly. Finally the newly compiled programs should be copied to the destination directories. The standard procedure to do that is by simply running the command
make install
However, care must be taken if a version of NTP had been installed previously. The old versions of the NTP executables should be deleted or overwritten by the new programs to prevent the NTP daemon from being loaded instead of the new one when the system starts up the next time. Also, the new executables must be in the directory where they are expected by the system startup scripts.
Care must be taken especially if the NTP version changes between v3.x and v4.x because the naming conventions have changed between those version (e.g xntpd/ntpd).
Configuration With Meinberg Radio Clock (Windows)
On Windows platforms, NTP does not currently support most external reference clocks directly. Instead, the Meinberg driver can be used together with most internal and external Meinberg radio clocks to discipline the Windows system time. The NTP service can then be used to make the disciplined Windows system time available on the network.
If NTP is installed using the GUI installer from the Meinberg NTP download page and the setup program detects the Meinberg driver package which has already been installed before then the NTP installer suggests to create an appropriate NTP configuration labelled "Follow Meinberg Time Service".
This configuration should include the following lines:
server 127.127.1.0# local clock fudge 127.127.1.0 stratum 0 # disciplined by radio clock
Since in this case the Windows system time is disciplined by a radio clock, Local Clock's stratum should be forced to 0. The NTP server is then visible as stratum 1 server on the network.
Unlike stated before on this page, the config file should not contain the line disable ntp since this may be the reason that the time server is not accepted by its clients.
Also, there should be no driftfile specified, and if a file ntp.drift already exists on the machine, it should be deleted. Otherwise the NTP service might try to correct the system clock drift, thus working against the radio clock driver, resulting in a poor quality of time synchronization.
Configuration Without Radio Clock
Configuration of computers without external reference clock is quite simple. For each computer which is to be used as reference time source, a line must be added to the file ntp.conf. Additionally, the computer's local clock can configured to be used by the NTP service if none of the other time servers on the network can be reached. Since the time servers on the network shall be preferred, the local clock's stratum should be forced to a high number:
server 127.127.1.0# local clock fudge 127.127.1.0 stratum 12# not disciplined server ntp_server_1 iburst server ntp_server_2 iburst server ...where ntp_server_1, ntp_server_2, etc. must be the real host names or IP addresses of existing NTP servers. The keyword iburst causes quick synchronization at program start. Older NTP versions do not support iburst.
Additional Configuration Options
During operation, the NTP daemon computes the drift of the system clock compared to the reference time. The daemon can save the drift rate to a file to have it available at the next restart. If the daemon shall maintain the drift file to increase synchronization speed, the location of that file must be specified by adding a line like
driftfile /etc/ntp.driftto the ntp.conf file.
Attention: If the NTP service under windows works together with the Meinberg driver package then a driftfile should not be configured. See also: Configuration With Meinberg Radio Clock (Windows).
There are many more options which can be set up using the configuration file. Please refer to the NTP documentation for details.
Checking the NTP Status
The command line utility ntpq can be used to check the status of a NTP daemon on either the local machine or on a remote host.
ntpq can be run in an interactive mode or in batch mode. In batch mode, ntpq executes a command and returns to the command prompt. The parameter -p ('peers') lets ntpq print the status of a NTP daemon. Enter
ntpq -pto display the status of the daemon on the local machine, or
ntpq -p ntp_serverto display the status of the daemon on the remote host ntp_server. The command should print a table with one status line for each reference time source which has been configured for the NTP daemon on the specified host:
remote refid st t when poll reach delay offset jitter ==================================================================================== LOCAL(0) .LCL0. 12 l 30 64 377 0.000 0.000 0.000 *GENERIC(0) .DCFa. 0 - 24 64 377 0.000 0.050 0.003 +172.16.3.103 .PPS. 1 u 36 64 377 1.306 -0.019 0.043
The table above shows the output for a NTP daemon which has 3 reference time sources: its own local clock, a DCF77 radio clock as refclock-0, plus an NTP daemon on the network, with IP address 172.16.3.103.
If the first character of a line is not blank then it contains a qualifier for the corresponding reference time source. Immediately after the daemon has been started all qualifiers are blank. The NTP daemon needs several polling cycles to check the available time sources and declare one of them as the reference it synchronizes to.
An asterisk * in the first column marks the reference time source which is currently preferred by the NTP daemon, the + character marks high quality candidates for the reference time which could be used if the currently selected reference time source should become unavailable.
The column remote displays the IP address or the host name of the reference time source, where LOCAL refers to the local clock. The refid shows the type of the reference clock, where e.g. LOCAL or LCL refers to the local clockagain, .DCFa. refers to a standard DCF77 time source, and .PPS. indicates that the reference clock is disciplined by a hardware pulse-per-second signal. Other identifiers are possible, depending on the type of the reference clock.
The column st reflects the stratum number of the reference time source. In the example above, the local clock has stratum 12, the remote time server at 172.16.3.103 has stratum 1 which is the best you can see across the network, and the local radio clock has stratum 0, so the radio clock is currently being preferred.
Every time a when count reaches the poll number in the same line, the NTP daemon queries the time from the corresponding time source and resets the when count to 0. The query results of each polling cycle are filtered and used as a measure for the clock's quality and reachability.
The column reach shows if a reference time source could be reached at the last polling intervals, i.e. data could be read from the reference time source, and the reference time source was synchronized. The value must be interpreted as an 8 bit shift register whose contents is for historical reasons displayed as octal values. If the NTP daemon has just been started, the value is 0. Each time a query was successful a '1' is shifted in from the right, so after the daemon has been started the sequence of reach numbers is 0, 1, 3, 7, 17, 37, 77, 177, 377. The maximum value 377 means that the eight last queries were completed successfully.
Queries are considered successful if data can be received from the time source, and the time source in turn claims to be synchronized to some other timesource. In case of a hardware reference clock this means, the query is considered as unsuccessful if the hardware reference clock is not synchronized to its incoming time signal, e.g. because the clock's antenna has been disconnected, or if no data can be received e.g. because the serial cable to an external device has been disconnected.
The NTP daemon must have reached a reference time source several times (reach not 0) before it selects a preferred time source and puts an asterisk in the first column.
The columns delay, offset and jitter show some timing values which are derived from the query results. In some versions of ntpq the last column is labeled disp (for dispersion) instead of jitter. All values are in in milliseconds. The delay value is derived from the roundtrip time of the queries. The offset value shows the difference between the reference time and the system clock. The jitter value indicates the magnitude of jitter between several time queries.
