Below are the default values for the UTC source configuration within Timebeat's config file.
It is always recommended that you understand what these parameters do as they will have direct effects on the functioning of the Timebeat app.
Timebeat is configured out of the box to synchronise to UTC using multicast PTP. This means that if your source of UTC is configured to distribute time using PTP multicast Timebeat will automatically sync to this. For this to work however your time server must be configured to distribute over Domain zero (most are by default).
For a breakdown of each section continue reading:
# ______ _ __ __
# /_ __/(_)____ ___ ___ / /_ ___ ____ _ / /_
# / / / // __ `__ \ / _ \ / __ \ / _ \ / __ `// __/
# / / / // / / / / // __// /_/ // __// /_/ // /_
# /_/ /_//_/ /_/ /_/ \___//_.___/ \___/ \__,_/ \__/
################### Timebeat Configuration AREA #########################
timebeat:
# Location of license key file for premium features
license.keyfile: "/etc/timebeat/timebeat.lic"
# Configuration for clock synchronisation
clock_sync:
# Clocksync
# Default is true enabling clock synchronisation, setting to false for monitoring purposes only (false will not adjust the clock)
adjust_clock: true
# To remove step limit restrictions comment out the below, this will allow the clock to be stepped indefinitely
step_limit: 15m # "s", "h" "d" can be used to denominate seconds, hours or days for step limit.
primary_clocks:
# PTP Config example
- protocol: ptp
domain: 0
#serve_unicast: true # (Enterprise Feature)
#serve_multicast: true # (Enterprise Feature)
#server_only: true # (Enterprise Feature)
announce_interval: 1
sync_interval: 0
delayrequest_interval: 0
#unicast_master_table: ["1.2.3.4","2.3.4.5", "3.4.5.6"]
#delay_strategy: e2e # (Enterprise Feature) - other options which can be used are: 'p2p'
#priority1: 128 # (Enterprise Feature)
#priority2: 128 # (Enterprise Feature)
#monitor_only: false
#interface: enp2s0
# PTP Config example
#- protocol: ptp
#domain: 10
#serve_unicast: true
#serve_multicast: true
#server_only: true
#announce_interval: 1
#sync_interval: 0
#delayrequest_interval: 0
#unicast_master_table: ["1.2.3.4","2.3.4.5", "3.4.5.6"]
#delay_strategy: e2e
#priority1: 128
#priority2: 128
#monitor_only: false
#interface: enp2s0
# NTP Config example
#- protocol: ntp
#ip: "1.2.3.4" # You can also use name formate e.g: time.server.com
#pollinterval: 4s # Values tested: 500ms, 1s, 2s, 4s and 8s # 4s is recommended for public NTP servers
#monitor_only: false
# Pulse-per-second input config example (ENTERPRISE FEATURE) PPS can be configured using Timebeat CLI
#- protocol: pps
#interface: ens3
#pin: 0
#index: 0
#monitor_only: false
# Secondary clocks. When all primary sources are unavailable the below will activate (ENTERPRISE FEATURE)
secondary_clocks:
# PTP Config example
#- protocol: ptp
#domain: 0
#serve_unicast: true # (Enterprise Feature)
#serve_multicast: true # (Enterprise Feature)
#server_only: true # (Enterprise Feature)
#announce_interval: 1
#sync_interval: 0
#delayrequest_interval: 0
#unicast_master_table: ["1.2.3.4","2.3.4.5", "3.4.5.6"]
#delay_strategy: e2e # (Enterprise Feature) - other options which can be used are: 'p2p'
#priority1: 128 # (Enterprise Feature)
#priority2: 128 # (Enterprise Feature)
#monitor_only: false
#interface: enp2s0
# PTP Config example
#- protocol: ptp
#domain: 10
#serve_unicast: true
#serve_multicast: true
#server_only: true
#announce_interval: 1
#sync_interval: 0
#delayrequest_interval: 0
#unicast_master_table: ["1.2.3.4","2.3.4.5", "3.4.5.6"]
#delay_strategy: e2e
#priority1: 128
#priority2: 128
#monitor_only: false
#interface: enp2s0
# NTP Config example
#- protocol: ntp
#ip: "1.2.3.4" # You can also use name formate e.g: ntp.time.server.com
#pollinterval: 4s # Values tested: 500ms, 1s, 2s, 4s and 8s # 4s is recommended for public NTP servers
#monitor_only: false
# NMEA-GNSS input config example (can provide majortime for PPS sources)
# Eight data bits, no parity bit, and one stop bit (8N1) is assumed
# (It is not recommended to configure a NMEA source if you have an alternative secondary source) (ENTERPRISE FEATURE)
#- protocol: nmea
#device: "/dev/ttyS0"
#baud: 9600
#monitor_only: false
Adjust clock and Step Limit:
# Default is true enabling clock synchronisation, setting to false for monitoring purposes only (false will not adjust the clock)
adjust_clock: "true"
# To remove step limit restrictions comment out the below, this will allow the clock to be stepped indefinately
step_limit: "15m" # "s", "h" "d" can be used to denominate seconds, hours or days for step limit.
To make sure Timebeat alters and synchronises the clocks on the device adjust_clock must be set to "true". However if this parameter is set to "false" then Timebeat will enter into what we describe as monitor only mode. This provides all the detailed output as you would expect from Timebeat but it does not synchronise the clocks on your system, instead, it observes the clocks without adjusting. This means that Timebeat can be used to understand how your current timing systems are performing or if you want to understand how your system responds when synchronisation is not possible.
One important item to note on monitor mode is that Timebeat will not be able to bind to PTP on ports 319 and 320 if another application is using this. That means monitor mode will need to have an NTP source configured in the Timebeat config file to populate the visualisations.
The step_limit can be modified to provide stricter or more lenient step limits or similarly less strict. If the step limit is increased this will allow Timebeat to step by larger increments, for a lower step limit this would restrict Timebeats ability to step. When you amend this parameter you will not be amending the slew boundary which remains at the default setting of 500ms. It should also be noted that if you comment out the Step Limit then there will be no restriction in place and Timebeat could modify you clock by years (or more, essentially to no limit), this is of course based on the source of time being provided. We do however recommend leaving at a minimum the default limit in place.
For Timebeat Cloud and Timebeat Enterprise users check out our detailed guide on step and slew limits available in the Advanced configuration. Enhanced step and slew limit configuration is not available in Timebeat FREE
Primary and Secondary Clocks:
Timebeat has two configuration modes for sources, these are categorised as primary_clocks and secondary_clocks.
Primary clocks are the sources of UTC that Timebeat will always aim to use solely to synchronise against.
Secondary clocks are monitored all of the time and will be displayed in your dashboards so that you can maintain observation on their performance.
However Secondary sources are only used to synchronise your system when all Primary sources are no longer being received. In the event all Primary sources stop being received any secondary source that is configured will become active and an annotation will be added to your platform front end. When at least one primary source comes back online and is being received again Timebeat will automatically switch back to the Primary source.
All source input types can be configured as Primary or Secondary sources.
primary_clocks:
# PTP Config example
- protocol: ptp
domain: 0
#serve_unicast: true # (Enterprise Feature)
#serve_multicast: true # (Enterprise Feature)
#server_only: true # (Enterprise Feature)
announce_interval: 1
sync_interval: 0
delayrequest_interval: 0
#unicast_master_table: ["1.2.3.4","2.3.4.5", "3.4.5.6"]
#delay_strategy: e2e # (Enterprise Feature) - other options which can be used are: 'p2p'
#priority1: 128 # (Enterprise Feature)
#priority2: 128 # (Enterprise Feature)
#monitor_only: false
#interface: enp2s0
# PTP Config example
#- protocol: ptp
#domain: 10
#serve_unicast: true
#serve_multicast: true
#server_only: true
#announce_interval: 1
#sync_interval: 0
#delayrequest_interval: 0
#unicast_master_table: ["1.2.3.4","2.3.4.5", "3.4.5.6"]
#delay_strategy: e2e
#priority1: 128
#priority2: 128
#monitor_only: false
#interface: enp2s0
# NTP Config example
#- protocol: ntp
#ip: "1.2.3.4" # You can also use name formate e.g: time.server.com
#pollinterval: 4s # Values tested: 500ms, 1s, 2s, 4s and 8s # 4s is recommended for public NTP servers
#monitor_only: false
# Pulse-per-second input config example (ENTERPRISE FEATURE) PPS can be configured using Timebeat CLI
#- protocol: pps
#interface: ens3
#pin: 0
#index: 0
#monitor_only: false
# Secondary clocks. When all primary sources are unavailable the below will activate (ENTERPRISE FEATURE)
secondary_clocks:
# PTP Config example
#- protocol: ptp
#domain: 0
#serve_unicast: true # (Enterprise Feature)
#serve_multicast: true # (Enterprise Feature)
#server_only: true # (Enterprise Feature)
#announce_interval: 1
#sync_interval: 0
#delayrequest_interval: 0
#unicast_master_table: ["1.2.3.4","2.3.4.5", "3.4.5.6"]
#delay_strategy: e2e # (Enterprise Feature) - other options which can be used are: 'p2p'
#priority1: 128 # (Enterprise Feature)
#priority2: 128 # (Enterprise Feature)
#monitor_only: false
#interface: enp2s0
# PTP Config example
#- protocol: ptp
#domain: 10
#serve_unicast: true
#serve_multicast: true
#server_only: true
#announce_interval: 1
#sync_interval: 0
#delayrequest_interval: 0
#unicast_master_table: ["1.2.3.4","2.3.4.5", "3.4.5.6"]
#delay_strategy: e2e
#priority1: 128
#priority2: 128
#monitor_only: false
#interface: enp2s0
# NTP Config example
#- protocol: ntp
#ip: "1.2.3.4" # You can also use name formate e.g: ntp.time.server.com
#pollinterval: 4s # Values tested: 500ms, 1s, 2s, 4s and 8s # 4s is recommended for public NTP servers
#monitor_only: false
# NMEA-GNSS input config example (can provide majortime for PPS sources)
# Eight data bits, no parity bit, and one stop bit (8N1) is assumed
# (It is not recommended to configure a NMEA source if you have an alternative secondary source) (ENTERPRISE FEATURE)
#- protocol: nmea
#device: "/dev/ttyS0"
#baud: 9600
#monitor_only: false
PTP Source Configuration
Timebeat operates differently from what you may have experienced with alternative synchronisation systems.
There are two main ways to configure PTP with Timebeat and they are:
- Best Master Clock Algorithm (BMCA)
- Multi Source Synchronisation Algorithm (MSSA)
For most installations we would recommend using the MSSA configuration as this will provide you with the most resilient method for synchronisation and removes the inherent flaws of not only BMCA but also of understanding source reliability.
For a detailed explanation of the two algorithms and how MSSA works check out the Algorithms guide in our Features and Functionality section.
Best Master Clock Algorithm Configuration (Multi-cast)
(Operating multiple grand masters in the same domain)
To configure Timebeat to synchronise using the BMCA with PTP it is quite simple. For Multicast you just need to make sure the Domain is accurate to what your sources are configured to and uncomment the necessary lines. By default Timebeat is configured with Domain 0 and as such if your sources are within domain 0 you do not need to configure any further.
Multi Source Synchronisation Algorithm (Multi-cast)
(Operating multiple grand masters in different domains)
Configuring Timebeat to synchronise using MSSA with PTP is equally simple. All you have to do Is enable the same configuration again (a duplicate below) but modify the domain to match your alternate source domain. The key to this configuration will be modifying your source (most likely a local grandmaster) to have a separate domain for each source.
Timebeat default configuration depicts this by having the first PTP source configured to domain 0 and the second PTP source example configured to Domain 10.
It should be noted that you could run BMCA from within the MSSA configuration by having multiple sources within each domain.
Best Master Clock Algorithm Configuration (Uni-cast)
To configure Timebeat to operate with a Unicast source it is also very simple. All you have to do is update the Unicast Master table with all of the IP's for your sources of PTP. For clarification each IP address should only be relevant to the domain number configured, I.e. the Unicast Master Table for a source configured to domain 0 should only have IP addresses of sources distributing over domain 0.
Multi Source Synchronisation Algorithm (Uni-cast)
To configure Unicast for the MSSA system it Is identical to how you would for BMCA in that you populate the Unicast Master Table with the IP addresses of your sources of PTP. The only key difference is that you would have multiple Unicast Master Tables to complete, one for each domain configured.
In summation the key lines within the config file to enable Timebeat to receive PTP are highlighted below in Green and the optional lines are highlighted in yellow:
# PTP Config example - protocol: ptp domain: 0 #serve_unicast: true # (Enterprise Feature) #serve_multicast: true # (Enterprise Feature) #server_only: true # (Enterprise Feature) announce_interval: 1 sync_interval: 0 delayrequest_interval: 0 #unicast_master_table: ["1.2.3.4","2.3.4.5", "3.4.5.6"] #delay_strategy: e2e # (Enterprise Feature) - other options which can be used are: 'p2p' #priority1: 128 # (Enterprise Feature) #priority2: 128 # (Enterprise Feature) #monitor_only: false #interface: enp2s0
(a separate guide will go into greater detail on interval rates and setting Timebeat up as a Boundary Clock or Grand Master, this can be found here)
PPS Source Configuration
Timebeat is able to consume multiple PPS (Pulse Per Second) Inputs at any given time and if in place will operate using the Multi Source Synchronisation Algorithm, however it is unusual to have more than one configured due to hardware input limitations (not enough PPS in inputs available).
The below configuration snippet shows how to configure PPS.
# Pulse-per-second input config example (ENTERPRISE FEATURE) PPS can be configured using Timebeat CLI
#- protocol: pps
#interface: ens3
#pin: 0
#index: 0
#monitor_only: false
What is important to understand is the interface name that you are receiving PPS into. Then all you need to understand is the pin and the index, these vary depending on the hardware you are using so always consult your hardware device information to find this out. It may be possible to understand this information using the Timebeat CLI tool which is covered in a separate guide available here.
PPS will always obtain major time from any other configured source whether they are Primary or Secondary.
NTP Source Configuration
NTP is very simple to configure and requires minimal input. Put simply you need to have an NTP address, which can be the domain name server such as time.timebeat.app (not a real ntp server) or the IP address associated with it 1.2.3.4 (not a real ntp server). Then all that is required is the poll interval.
For public NTP servers we recommend a minimum poll interval of 4s as if you poll more often the NTP server is likely to start rejecting your requests which can effect the accuracy and stability of your sync. For private NTP servers you can poll more often for increased performance.
The below snippet from the config file shows the NTP configuration
# NTP Config example
#- protocol: ntp
#ip: "1.2.3.4" # You can also use name formate e.g: ntp.time.server.com
#pollinterval: 4s # Values tested: 500ms, 1s, 2s, 4s and 8s # 4s is recommended for public NTP servers
#monitor_only: false
NMEA Source Configuration
NMEA is a useful source if you are using PPS and operating Timebeat as a Grandmaster. The reason for this is it can be a very useful input for not only providing major time to PPS but also to understand your satellite constellations and how well you are locked onto GNSS.
The below config snippet demonstrates how to configure NMEA
# NMEA-GNSS input config example (can provide majortime for PPS sources)
# Eight data bits, no parity bit, and one stop bit (8N1) is assumed
# (It is not recommended to configure a NMEA source if you have an alternative secondary source) (ENTERPRISE FEATURE)
#- protocol: nmea
#device: "/dev/ttyS0"
#baud: 9600
#monitor_only: false
Secondary Sources and monitor_only
Secondary sources are configured in exactly the same methods as above with the distinct difference that they appear under the secondary_source: configuration line within timebeat.yml.
# Secondary clocks. When all primary sources are unavailable the below will activate (ENTERPRISE FEATURE)
secondary_clocks:
Secondary clock configuration can be NTP, PTP, PPS NMEA or a mix of all. It is important to understand that although Secondary sources are tracked and you visualisations are available for the offset of your device and the secondary sources at no point is a secondary source used for synchronisation when a primary source is still active. Once all primary sources fail or are not received by the timebeat application, only then will the secondary sources be used to actively synchronise the device. When a secondary source is in use an annotation is logged to the database and alerts can be configured to notify.
It should be noted that currently if NTP is enable as a primary or secondary source of UTC Hardware timestamping will not be available
monitor_only is available for all sources and is quite simple to understand. Unlike what we have previously detailed as Monitor mode, monitor_only when associated against a source will ensure that under no circumstances will that source be used to synchronise with. It will monitor as if it were in monitor mode with the key difference that Timebeat can skill synchronise your device using an alternative configured source of UTC.