TimeKeeper handles leap seconds by “slewing” in the default mode and will not introduce discontinuities, “jumps” or pauses in time to correct them. It will smoothly adjust any offset introduced by a leap second to ensure monotonically increasing time. Some time keeping methods and time reference sources do pause the clock and TimeKeeper will deal with them gracefully. This will initially show up as about a 1.0 second offset of the time which will be smoothly corrected out over the next three to eight minutes.
TimeKeeper does offer a mode to “jump” the clock or perform a “step” when the leap second occurs in order to reduce the amount of time needed to correct out the time offset introduced by the leap second. This can be enabled by setting STEP_ON_LEAPSECOND=1. When TimeKeeper detects a 1 second offset within a 15 second window of when leap seconds are introduced (either midnight UTC of June 30 or December 31 of a year) it will immediately correct the clock by 1 second. Depending on how leap seconds are propagated within your time environment this may not occur exactly when the leap second occurs.
We recommend testing how a leap second is handled in your specific environment by simulating one if very fast correction of a leap second is important to you. Feel free to contact firstname.lastname@example.org if you would like assistance.
TimeKeeper using external reference devices
Please refer to the documentation for your time reference device for specifics on how it handles leap seconds since this will determine how TimeKeeper responds.
If a direct GPS or other absolute time source is being used that provides time via a UTC broken down format then normally an additional second will be sent to TimeKeeper as the 23rd hour, 59th minute and 60th second of the day when the leap second happens. This will show up on the server as 1 second after the 23rd hour, 59th minute and 59th second of the day. When the new day starts in the next second - 0th hour, 0th minute and 0th second TimeKeeper will calculate this as the same second as was previously reported by the time source. This will mean TimeKeeper will calculate an error of 1 second at that time.
Over the next few seconds TimeKeeper will work to remove that error through slewing. Normally this takes 5 to 10 seconds to do. It should be noted that an offset will be expected when leap seconds are introduced and will take 5 to 10 seconds to eliminate. During the time that this offset is being reduced TimeKeeper will not slow down the clock by more than 25% of its original value.
TimeKeeper as an NTP client/server
Most NTP protocol implementations will handle leap seconds by pausing the clock at some point in the last second of the day. TimeKeeper does not do this. Below is an example of querying a typical non-TimeKeeper NTP server at 0.25 second intervals during a leap second.
23:59:58.50 23:59:58.75 23:59:59.00 23:59:59.25 23:59:59.50 23:59:59.75 23:59:59.75 23:59:59.75 23:59:59.75 23:59:59.75 00:00:00.00 00:00:00.25
When TimeKeeper is acting as a client to one of these non-TimeKeeper NTP servers TimeKeeper will slow it’s own clock down slightly so that it can match the remote clock that is paused until the 1 second offset that was introduced by the leap second is corrected. This offset removal should take a few seconds.
TimeKeeper acting as a NTP server will set the ``leap second indicator'' flag in responses that it sends. It will track the time of any source that it is configured to use and will send that time out to any requesting NTP clients.
TimeKeeper as a PTP client/server
TimeKeeper as a PTP client will see a leap second occurs when a PTP Announce message sent by the server shows a change in the UTC offset field. At that point TimeKeeper will begin to correct the offset introduced by the change in TAI to UTC offset values. This occurs whenever the server sends the new UTC offset in an announce message and that can vary depending on the server. This could be quite some time after the actual leap second.
TimeKeeper acting as a PTP server will set the “leap second indicator” bit in announce messages to clients. When the leap second occurs according to the source feeding the server TimeKeeper will slew to match the source and will provide that time to the client, unless configured to step as described above.