Below are the default values for the Advanced 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. It is advised that you consult with a Timebeat technical support with questions on this area if you are unsure before making changes within a live environment.
For a breakdown of each section continue reading:
#
# _______________________________________
# / Below are the advanced configurations \
# | change at own risk, please refer to |
# \ documentation guides for detail /
# ---------------------------------------
# \ ^ /^
# \ / \ // \
# \ |\___/| / \// .\
# \ /O O \__ / // | \ \ *----*
# / / \/_/ // | \ \ \ |
# @___@` \/_ // | \ \ \/\ \
# 0/0/| \/_ // | \ \ \ \
# 0/0/0/0/| \/// | \ \ | |
# 0/0/0/0/0/_|_ / ( // | \ _\ | /
# 0/0/0/0/0/0/`/,_ _ _/ ) ; -. | _ _\.-~ / /
# ,-} _ *-.|.-~-. .~ ~
# \ \__/ `/\ / ~-. _ .-~ /
# \____(oo) *. } { /
# ( (--) .----~-.\ \-` .~
# //__\\ \__ Ack! ///.----..< \ _ -~
# // \\ ///-._ _ _ _ _ _ _{^ - - - - ~
#
#(THE BELOW ADVANCED OPTIONS ARE ENTERPRISE FEATURES)
advanced:
# Steering Algorithm Options
steering:
# Several algorithms are available :
#
# alpha, beta, gamma, rho & sigma
# Most likely you will want the sigma algo in a reasonably noise
# free (low jitter / low network congestion) environment. In a less than
# ideal environment with hardware timestamping rho may be better depending
# on the circumstances. If your servers don't support hardware timestamping,
# then go for the sigma algo as well.
#
# algo: "sigma"
# Log steering algo constituents
# algo_logging: false
# Log steering algo constituents
# outlier_filter_enabled: true
# Several outlier filter types are available
# "strict", "moderate" and "relaxed"
# outlier_filter_type: "strict"
# In the event an alternative system adjusts the clock, timebeat will cease active operation and transition into monitoring mode.
# period of time defined in the value below
interference_monitor:
backoff_timer: "5m"
# Slewing is active only when the offset is less than the step boundary,
# If the offset is less than the step limit but greater than the step boundary time will be stepped and not slewed,
# The step boundary cannot exceed the step limit, it is able to be equal to,
# If the offset is greater than both step limit and step boundary the clock will not be synchronised, neither stepping or slewing will take place,
# Any change to the below configuration will override the default/configured limits above.
extended_step_limits:
#forward:
#boundary: "500ms"
#limit: "15m"
#backward:
#boundary: "500ms"
#limit: "15m"
windows_specific:
# Default is true, setting configuration to false will alter the Windows Timer Resolution, Default of true sets the Timer Resolution to a fine value.
# disable_os_relax: true
linux_specific:
# Enable hardware timestamping on Linux SOF_TIMESTAMPING_(R|T)X_HARDWARE
# hardware_timestamping: true
# Enable external software timestamping on Linux SOF_TIMESTAMPING_(R|T)X_SOFTWARE
# external_software_timestamping: true
# Synchronise non-master PHC (nic) clocks on Linux
# sync_nic_slaves: false
ptp_tuning:
# Randomly delay DELAY_REQ packets by 200-800ms from receipt of SYNC packets
# (this option will be forced true for multicast sources irrespective of the value below)
# relax_delay_requests: true
cli:
# Enable the CLI interface on telnet://127.0.0.1:65129
# enable: false
# CLI username and password
# username: "admin"
# password: "password"
The Steering Algorithm and Outlier Filter
Timebeat offers flexible options for its sync settings as we understand all too well that no two environments are the same and different variables means different settings work better in different environments. This is why we offer the ability to customise the steering algorithm in use and the outlier filter rules.
The Steering Algorithm
advanced:
# Steering Algorithm Options
steering:
# Several algorithms are available :
#
# alpha, beta, gamma, rho & sigma
# Most likely you will want the sigma algo in a reasonably noise
# free (low jitter / low network congestion) environment. In a less than
# ideal environment with hardware timestamping rho may be better depending
# on the circumstances. If your servers don't support hardware timestamping,
# then go for the sigma algo as well.
#
# algo: "sigma"
# Log steering algo constituents
# algo_logging: false
By default Timebeat uses the sigma algorithm. This in practice has shown to be the most versatile and reliable when it comes to environment scenarios, this being said however, it may not be best for you.
# algo: "sigma"
The five algorithms available at the moment are as follows:
- alpha
- beta
- gamma
- rho
- sigma
If you are not happy with the performance of sigma we recommend testing out the alternative options until you are comfortable. If performance still is not obtained get in touch with our technical support as they may have some hints for you.
# algo_logging: false
The above configuration line can be set to true. In doing so you will start to log some metrics associated with the steering algorithm performance and activity. This is useful if you are investigating other algorithms or in need to troubleshoot your synchronisation. Timebeat defaults to this information being off as most users do not require this level of detail, however there is no issue or performance overhead incurred if left on all the time.
The Outlier Filter
The Outlier filter is another method to fine tune your system to integrate with your environment better than just the default options.
In traditional deployments it probably isn't necessary to modify the Outlier Filter. The below snippet shows the config line which can be changed.
# Several outlier filter types are available
# "strict", "moderate" and "relaxed"
# outlier_filter_type: "strict"
Currently there are 3 outlier filter modes which are:
- strict
- moderate
- relaxed
If you are looking at modifying the outlier filter it is worth experimenting with all settings before settling on your preference as they can have varied results depending on what you are looking to resolve. It could be worth speaking to Timebeat technical support on this subject for any hints or tips on how best to fine tune your system.
Interference Mode:
# In the event an alternative system adjusts the clock, timebeat will cease active operation and transition into monitoring mode.
# period of time defined in the value below
interference_monitor:
backoff_timer: "5m"
The backoff_timer is adjustable in minutes. By default this is set to 5 minutes. The backoff_timer directly relates to what we define as Interference Mode. Interference mode is triggered when an application other than Timebeat modifies the system clock, typically this would be a system such as ntpd or W32Time on windows. When another application modifies the system clock Timebeat enters interference mode; when interference mode is active Timebeat will not attempt to alter the system clock.
This is where the backoff_timer comes into play, Timebeat will attempt to modify the system clock every interval to which it is set. If Timebeat believes that another application is still modifying the system clock it will again "backoff" for the interval set and so the process continues until the alternative application is stopped.
Step and Slew Limits:
# Slewing is active only when the offset is less than the step boundary,
# If the offset is less than the step limit but greater than the step boundary time will be stepped and not slewed,
# The step boundary cannot exceed the step limit, it is able to be equal to,
# If the offset is greater than both step limit and step boundary the clock will not be synchronised, neither stepping or slewing will take place,
# Any change to the below configuration will override the default/configured limits above.
extended_step_limits:
#forward:
#boundary: "500ms"
#limit: "15m"
#backward:
#boundary: "500ms"
#limit: "15m"
Stepping and Slewing is probably the most customised feature within Timebeat Enterprise. Simply put slewing is a slow steady modification of your clock being synched, this allows Timebeat to maintain a stable offset. Stepping is a rapid shot to zero (or close to) this means that your clock could change by seconds, minutes, hours or even years depending on the configuration.
By default Timebeat has a step limit of 15 minutes, any step required greater than this value will need manual intervention as a complete check and balance. Within the advanced configuration section you can modify forward and backward step and slew limits. Forward limits are for when your time is behind UTC and requires movement ahead of your current time. Backwards limits are for when your clock is fast and requires movement behind your current time.
You may never want to step in a direction as you require consistency and not jumps in time, in order to achieve this just set the limit and the boundary to the same value. It is highly recommended that the boundary is not set too low as this will mean the clock will be stepped all the time which will lead to instability in your synchronisation.
Windows Specific:
windows_specific:
# Default is true, setting configuration to false will alter the Windows Timer Resolution, Default of true sets the Timer Resolution to a fine value.
# disable_os_relax: true
The windows timer is typically 15.625 microseconds (primarily on older Operating System releases) which does not lend itself to enabling the most accurate synchronisation possible. This is why as standard we disable the "relax" function within the Windows timer so that it maintains a constant 1 microsecond granularity enabling much more stable and accurate synchronisation.
Although you can modify the parameter to false which will leave the Windows Timer at the default setting of your Operating Systems configuration we do not see why you would want to as the stability and accuracy of your synchronisation will decrease - it is however your choice :)
Linux Specific:
linux_specific:
# Enable hardware timestamping on Linux SOF_TIMESTAMPING_(R|T)X_HARDWARE
# hardware_timestamping: true
# Enable external software timestamping on Linux SOF_TIMESTAMPING_(R|T)X_SOFTWARE
# external_software_timestamping: true
# Synchronise non-master PHC (nic) clocks on Linux
# sync_nic_slaves: false
Hardware timestamping enables the synchronisation of clocks located on a Network Card. This relies entirely on your NiC being IEEE1588 capable. When set to true your synchronisation will be stabilised and the hardware clock will become the master clock. When there is a master clock which is not the system clock the system clock will be synchronised by the master and not directly from the source of the UTC - If the system clock is the master clock and there are no network cards being synchronised then the system clock will receive UTC directly from the source.
Timebeat has many methods for synchronising your system and by default the most effective are active. They can be switched off, but why would you want to?
external_software_timestamping is the perfect example. If hardware timestamping is not available Timebeat will attempt to use external software timestamping, this provides much more accurate synchronisation when switched on as it bypasses the kernel.
By default sync_nic_slaves is set to false, this is because depending on your environment it can become more CPU intensive when set to true. What this means is that if you have multiple network cards capable of being synchronised (and they may have multiple interfaces which would have multiple clocks all being synchronised). This being said when set to true all physical clocks (NiC) will be synchronised.
PTP Tuning:
ptp_tuning:
# Randomly delay DELAY_REQ packets by 200-800ms from receipt of SYNC packets
# (this option will be forced true for multicast sources irrespective of the value below)
# relax_delay_requests: true
relax_delay_requests is defaulted to true, this means that Timebeat will delay messages at a random rate and not at fixed intervals. This is set to allow for greater stability for synchronisation with any Grand Master Clock manufacturer as each operates slightly differently. When set to true you will experience the most stable synchronisation across the board.
Timebeat CLI
The Timebeat CLI can be a useful tool for on-the-fly modification of elements within the config file or to understand what devices are using what (specifically useful for PPS configuration).
By default this is configured to off as most users will not have need for this functionality, however by modifying the configuration below to set enable to true and uncomment out the username and password you will be able to access the CLI at the stated telnet address.
cli:
# Enable the CLI interface on telnet://127.0.0.1:65129
# enable: false
# CLI username and password
# username: "admin"
# password: "password"
For a detailed guide on how to use the Timebeat CLI check out the CLI guide in our Features and Functionality category