kb:time_sync:ntp:configuration:ntp_leap_second_file

The NTP Leap Second File

Purpose

The NTP daemon ntpd can be configured to evaluate a leap second file (a simple text file in a specific format) to

  • determine if a leap second has been scheduled for the near future
  • determine the UTC to TAI offset and pass it to the OS kernel clock (if the kernel supports this)
  • pass the TAI offset to the NTP clients via the autokey protocol


Sites Providing a Leap Second File

Download links for the Meinberg web site


Leap Second Announcements from IERS

The Earth Orientation Center of the International Earth Rotation and reference systems Service (IERS), located at the Observatoire de Paris, France, determines when a leap second is to be inserted into the UTC time scale.

Here is a graphic showing how the UTC time has evolved over the years, where every step indicates a leap second:

Source: https://hpiers.obspm.fr/iers/bul/bulc/graphe_UT1-TAI_history.png


A bulletin C is published once every six months to tell if a leap second is scheduled for the end of next June or December, or not. The last published bulletin C is available under this link:

Since 2015, the IERS also provides an own leap second file.


Information Provided by the Leap Second File

Beside the table of leap second dates and TAI offset, the original leap second file contained only a time stamp indicating the last modification date of the file, in a line starting with a special comment #$.

Later, the format was extended to also include a file expiration date, tagged by the special comment #@, and a SHA1 hash, tagged by the special comment #h. Time stamps in the leap second file are specified using the NTP format, i.e. represent the number of seconds since 1900-01-01 00:00:00.

Last Modification Date

A line starting with a special comment #$ contains the last modification date, in NTP format. There is only one such line in a leap second file.

If several instances versions of a leap second file are available, the last modification date can be used to determine which file is newer and possibly more current.

TAI Offset Table

The main data part of the leap second file contains a table of dates indicating when the difference between TAI and UTC time scales change due to a leap second, e.g.: 

...
3550089600      35      # 1 Jul 2012
3644697600      36      # 1 Jul 2015
3692217600      37      # 1 Jan 2017

The first column is a time stamp in NTP format (seconds since 1900-01-01 00:00:00 UTC) indicating the epoch at which a new TAI/UTC offset takes effect, and the second column indicates the new offset value valid after the epoch. The data fields can be separated by spaces or tabs, depending on the origin of the file.

Whenever the offset changes, this is due to insertion (or deletion, in theory) of a leap second immediately before the beginning of the new epoch associated with the time stamp. The 3rd column starts with a comment character # and indicates the calendar date associated with the start of the epoch.

Expiration Date

A line starting with a special comment #@ contains the expiration date of the file, in NTP format. There is only one such line in a leap second file.

Applications should use the expiration date to determine if the leap second file is still valid, or not.

After the file has expired, it is not possible to tell if there has been another leap second scheduled after the expiration date, which also caused a change in the TAI/UTC offset, so it is good practice to update the leap second file even if no other leap second has been scheduled, but only the expiration date has been updated.

The expiration date of the leap second file should be about 11 months after the file is published to ensure consistent use and sufficient time for distribution of updates, for example:

  • Last bulletin C published at the beginning of January telling whether a leap second is scheduled for the end of June
  • Next bulletin C published at the beginning of July telling if a leap second is scheduled for the end of December

So after the bulletin C published in January, we know whether a leap second will occur in June, or not. But we also know there will be no more change from July until end of December. So a leap second file published in January can be valid until a few days before December 31, i.e. for about 11 months. Because the next file is published after the bulletin C in July, but the previous version of the file is still valid until December, users have more than 5 months time to provide their NTP servers with an updated leap second file.

The longer the overlapping interval of and old and new leap second file, the longer is the interval during which scripts could check for an updated file.

SHA1 Hash

A line starting with a special comment #h contains a SHA1 hash. There is only one such line in a leap second file.

The hash only guarantees the integrity of a file. It does not prove that the file comes from an authentic source, so the hash can optionally be ignored to simplify maintenance of the leap second information by other applications that create such a file.

For higher security, the file should be signed using a public key certificate which can also be checked after the file has already been downloaded. However, this is currently not implemented. For now there's only a limited proof of authenticity if the file is downloaded via a https link, and there's no security at all if it is downloaded from a plain FTP site.

At least the copy of the leap second file distributed via the TZDB at IANA has some modern cryptographic signatures.


Naming Conventions

The original name of the leap second file is leap-seconds.nnnnnnn, where nnnnnnn is the NTP time of the last modification. Usually there is a symbolic link leap-seconds.list which points to the current version of the file. The link makes it easier to download the file automatically whenever a new version has been published.


Usage with 'ntpd'

The details of using the leap second file have changed slightly across different versions of ntpd.


Versions of 'ntpd' Behaving Differently

Current versions of ntpd (4.2.8 and newer) really check the expiration date of the leap second file, and stop using it after the file has expired. Also, ntpd checks the file at least once per day, and automatically reloads the file if it has been updated.

Earlier versions of ntpd including 4.2.6 did not reload an updated leap second file automatically, so the NTP daemon had to be restarted after the file had been updated. Also, these ntpd versions didn't check the expiration date and accepted the file even though it had expired. As a result, even valid leap second announcements from other sources could be discarded if the leap second file was configured but outdated. See also:
http://bugs.ntp.org/show_bug.cgi?id=861#c46


Configuring 'ntpd' to Use the Leap Second File

For ntpd 4.2.6 and newer it is sufficient to specify the path to the file in ntp.conf: 

leapfile “/path/to your/leap-file”


Ignoring the SHA1 hash

With ntpd 4.2.8p14 and newer it is also possible to configure ntpd to not check the SHA1 hash: 

leapfile “/path/to your/leap-file” ignorehash

This is useful if the leap second file is generated on the fly by another application.


'ntpd' versions prior to 4.2.6

Versions of ntpd prior to 4.2.6 evaluate the leap second file only if the autokey feature has been enabled and properly configured. First the crypto directory has to be specified in ntp.conf via the keysdir directive: 

keysdir "/etc/ntp"

Then the leap second file has to be placed in the specified directory, and inside that directory a symbolic link has to be created which points to that file:

ntpkey_leap → leap-seconds.list

ntpkey_leap is the standard name for the link, but this can be overridden by a configuration parameter.

In both cases the autokey feature can be used to forward the information from the leap second file to clients which have also been configured properly to use autokey. NTP nodes display a valid tai= number in the output of the ntpq -c rv command, if they have either a local leap second file available, or receive the leap second table from an upstream server via the autokey protocol.


Sites Providing a Leap Second File

The Leap Second File from IERS

While leap second files were initially provided by US institutions such as NIST and USNO, in early 2014 it was proposed that the IERS should also provide a leap second file. Reasons were:

  1. The IERS is the institution that decides whether a leap second is to be scheduled
  2. Unlike NIST which is a pure U.S. organization, the International Earth Rotation Service is an international institution

Specifically the 2nd point is pretty important for an international acceptance of the leap second file, especially for countries which are not particularly friends of the United States. This was pointed out in a presentation at the Future Of UTC Conference 2013 in Charlottesville: http://futureofutc.org

Fortunately, the IERS has actually provided their own version of a leap second file, even via https:


The Leap Second File from NIST

General information on the NIST's internet time services is available at
https://www.nist.gov/pml/time-and-frequency-division/services/internet-time-service-its

Originally, the NIST version of the leap second file was made publicly available via FTP access to each of the NIST time servers. However, According to a note on their web page FTP access to the time servers has been phased out, and all of the public files including the leap second file have been moved to these public FTP sites:

These FTP servers also provide the source code of a tiny C program which can be used to compute or verify the SHA1 hash of a leap second file.

:!: Please note that some current web browers have stopped supporting FTP access for security reasons, so the links above may not work via web browser.


The Leap Second File at USNO

Also the U.S. Naval Observatory (USNO) used to provide an own version of a leap second file via FTP:

However, the sites above as well as other USNO sites were taken offline in October 2019 due to some planned modernization efforts. As of February 14, 2022 the site https://maia.usno.navy.mil is online again, but does not yet provide a leap second file.


The Leap Second File Provided by the Olson/IANA TZDB

The so-called Olson TZ database (TZDB) is hosted at IANA https://www.iana.org/time-zones and provides a set of time zone description files, including daylight saving information for the current year as well as for past years.

Beside the time zone description files it also contains a leapseconds file which is in a different format than the original file from NIST. The TZDB version of the file is used to implement the so-called right time zones properly.

Current versions of the TZDB distribution archive also contain a copy of the leap-seconds.list file in NTP format, as well as the leapseconds.awk script which is used to generate the TZDB version of the file from a source file from IERS or NIST.

The leap seconds file at the IANA site is available here:


The advantage of using the IANA version of the leap second file is that whenever the time zone information (TZDB) is updated on a computer, the leap second file is also automatically updated.

Though admittedly it would be preferable that either the IERS or any other original sources would directly sign their leap second file, TZDB distributions 2012e and newer are signed via a PGP/GPG signature as per Internet RFC 6557 (2012) section 3. The signatures are currently not available on the download page but are included in the announcement emails sent via the tz or tz-announce mailing lists.

For information about how to verify the authenticity of a file using an associated signature file, see the knowledge base article File Hashes and Cryptographic Signatures.

Also, TZDB releases have signed tags in the Github development repository; this is another way to verify leap-seconds.list.


The disadvantage on the other hand is that a new version of a leap second file is only rolled out when a new version of the TZDB is published, which usually happens when some time zone rules are going to change, but not necessarily after only a new version of the leap second file has been published.


The development version of the TZ database is maintained on GitHub:

and a few details are available on Paul Eggert's homepage at:


The Leap Second File at IETF

The IETF website https://www.ietf.org/timezones/data/ used to provide the files extracted from the latest TZDB distribution archive, but this no longer appears to be the case .


The Leap Second File at Meinberg

For convenience, Meinberg provides a copy of the IERS leap second file at their web site:

Since the original site at IERS does not provide a cryptographic signature for their leap second file, Meinberg has created such a signature, which can be downloaded as a file here:

For information about how to verify the authenticity of a file using an associated signature file, see the knowledge base article File Hashes and Cryptographic Signatures.


Summary

The best option is to download the file from IERS or a copy of the IERS file from the Meinberg site.

The files from NIST or IANA/TZDB are often only published with a significant delay.

Some other former sources like USNO or IETF don't work anymore.


History and References

The NTP protocol was originally designed to distribute UTC time, including leap second warnings. Later there was an idea to provide a table of leap second events allowing to derive TAI from UTC.

At the Precise Time And Time Interval (PTTI) Meeting in 2000, a paper entitled USING THE NETWORK TIME PROTOCOL (NTP) TO TRANSMIT INTERNATIONAL ATOMIC TIME (TAI) was presented by Judah Levine, National Institute of Standards and Technology, and David Mills, University of Delaware with a suggestion on how to provide and use such a table of leap seconds as a file.

In NTP v4, a packet extension field was specified that can be appended to the standard NTP network packets to support autokey etc. The paper presented proposes installing a leap second file on all top-level NTP servers and using these extension fields to provide all clients with the contents of the leap second table, if autokey has been enabled and configured properly on the client and server.

An overview of the meeting as well as the cited paper were usually available via a web page at USNO:

  • https://tycho.usno.navy.mil/ptti/ptti2000.html
  • https://tycho.usno.navy.mil/ptti/2000papers/paper34.pdf


Unfortunately, the USNO website appears to no longer provide this information, but copies of the papers are still available here:

— Martin Burnicki martin.burnicki@meinberg.de, last updated 2024-02-15

  • kb/time_sync/ntp/configuration/ntp_leap_second_file.txt
  • Last modified: 2024-02-15 16:44
  • by 127.0.0.1