The Timebeat config file is quite an extensive kit with many options and customizable features.
Most of these items can be safely ignored unless you are looking for advanced features for your setup. By default, the Timecard is configured to synchronise to GNSS, so primarily, you will need to look at logging options, which can be found in a separate guide or the distribution settings.
Below is an extensive, in-depth look at the config file to help you on your way.
As always the timebeat config file can be found in: /etc/timebeat/timebeat.yml
license.keyfile: place the location of your timebeat.lic file - this is required
config.peerids: place the pathname of peerids.json - a file used for adding enrichment data to your PTP feeds, typically used with UTC Verification - this is not required
adjust_clock: true or false - this is required, setting to false will put all sources into monitor only mode
step_limit: this is the threshold for the maximum offset to source timebeat will step the clock, if an offset is greater than this value timebeat will not step the clock into line.
primary_clocks: This section is for your primary sources, these are used before all others with a hierarchy of PPS, PTP, NTP, PHC, NMEA
- protocol: This is where you select the source protocol, the next few lines detail the PTP protocol options.
domain: This is the PTP domain number
serve_unicast: True or False, when set to true this config will distribute Unicast PTP
max_unicast_subscribers: This limits the number of Unicast subscribers the source will allow
serve_multicast: True or False - when set to true this source will distribute multicast PTP
## server_only: True or False - when set to true this source will only distribute PTP, if set to false then this source will be used in the synchronisation of the device and distribute similar to a boundary clock. (default is false)
announce_interval: This is the announce interval rate - see interval rates for more info.
sync_interval: This is the sync interval rate - see interval rates for more info.
delayrequest_interval: This is the delay request interval rate - see interval rates for more info.
disable: True or False - when set to true this source config will be disabled
unicast_master_table: This is identifies the Unicast master, this should match the IP address of the Unicast master, If this device is the unicast master then it should be it's own IP address.
delay_strategy: This is the PTP delay strategy to be used, options are e2e (default) or P2P
hybrid_e2e: True or False - when set to true this enables Hybrid mode for PTP
priority1: This is the PTP priority
priority2: This is the PTP priority
monitor_only: True or False, when set to true this source will only be monitored and not used to synchronise the device
use_layer2: True or False, when set to True PTP will use Layer2.
interface: This is the interface that will receive or send PTP
group: This is used in conjunction with the Open Timecard PTP sync settings or the Oscillator config section. This creates a group of PTP sources
profile: This details which PTP profile will be in use
logsource: This adds a named record against the source for enhancing monitoring capabilities
asymmetry_compensation: This adds a static compensation of error to the source
max_packets_per_second: 0 # If inbound packet rate exceeds this a WRED algorithm is used
peer_id: This provides a link to the peerids.json file
sptp_enable: True or False - setting to true will enable simple PTP
- protocol: ntp
ip: This is the IP address or name server of your NTP source, if serving NTP it will also act as the outgoing IP
pollinterval: This is how often timebeat will poll the NTP server for the time
monitor_only: True or False, when set to true this source will only be monitored and not used to synchronise the device
serve_unicast: True or False, when set to true this source will distribute NTP
interface: This is the interface on which you will distribute NTP
server_only: True or False, when set to true this will serve NTP only, when set to False it can synchronise to a source of NTP and serve NTP
- protocol: pps
interface: This is the interface or PHC which is receiving the PPS input
pin: Typically this is the SDP number
index: This is the Index / channel
cable_delay: A static delay to account for cable length
edge_mode: rising, falling or both, this is the edge timebeat will look for of the incoming PPS
monitor_only: True or False, when set to true this source will only be monitored and not used to synchronise the device
atomic: True or False, If true it indicates the use of an atomic oscillator
linked_device: This is a link to the secondary source typically a NMEA or Open timecard source, this is how to link the PTP clock class
secondary_clocks:
NOTE: All primary clock source protocols can be used in secondary clocks and vice versa however typically the below are always secondary.
- protocol: nmea
device: Pathname to the NMEA data, typically over serial
baud: Baud rate of the serial connection
offset: A static offset which can be applied to the source
monitor_only: True or False, when set to true this source will only be monitored and not used to synchronise the device
- protocol: timebeat_opentimecard
card_config:
- 'gnss:signal:' This is the combination of GNSS satellites or signals to track.
- 'gnss:nmea_tcp_server:' This enables NMEA over an IP server.
- 'osc:type:' This specifies the oscillator in use on the card
- 'osc:tau_steps:' This creates a custom TAU programme for use with the Rubidium SA5x oscillator
- 'eth:sfp_accuracy:' This enables high precision sync to be distributed on the SFP connection
- 'clkgen:dco_group:' This links a PTP source to the Timecard system when synchronising to a PTP source
offset: This adds a static offset to the source
atomic: True or False, indicates if it is an atomic oscillator or not
monitor_only: True or False, when set to true this source will only be monitored and not used to synchronise the device
# Where we discipline an oscillator with PPS from a pin (if we don't have GNSS but get time from PTP for instance
- protocol: fallback
active_on_group: This is the group name which is detailed in the PTP sources
active_on_min_sources: This refers to the minimum number of sources required not to trigger. i.e if sources fall below this number the oscillator fallback will kick in.
active_on_threshold: This is the threshold variance between sources, at which if sources deviate above this value oscillator fall back will kick in
monitor_only: True or False, when set to true this source will only be monitored and not used to synchronise the device
disable: True or False - when set to true this source config will be disabled
advanced:
# Steering Algorithm Options
steering:
algo: This is the steering algorithm that will be in use. sigma is quick and reactive, whereas rho is slow and less reactive to jitter
algo_logging: True or False, setting this to true will enable algo logging to the database. This is typically clock frequencies
outlier_filter_enabled: True or False, setting to false will disable the lucky packet filter, advised not to disable
outlier_filter_type: This changes the setting of how aggressive the outlier filter will be.
servo_offset_arrival_driven: true
interference_monitor: This is triggered when Timebeat detects another service modifying the clock (typically think ntpd, sfptpd, chrony etc.)
backoff_timer: This is the amount of time timebeat will wait if interference has been detected before attempting to modify the particular clock
extended_step_limits: This goes beyond the top level step limit but is governed by it. This allows you to customise the behavior
forward: This is the forward step and slew limits
boundary: The amount of offset before a step can take place
limit: The limit at which timebeat will not step beyond
backward: This is the backward step and slew limit
boundary: The amount of offset before a step can take place
limit: The limit at which timebeat will not step beyond
linux_specific:
hardware_timestamping: Default to true, setting to false will stop PHC synchronisation and only synchronise the system clock
external_software_timestamping: True or false, this is default to true, if external timestamping is not present timebeat will automatically set to false - advised not to change
sync_nic_slaves: True or False, when set to true timebeat will synchronise all PHC's identified on the device
disable_adjustment: This is used to disable synchronising a clock but you still want to synchronise the slaves, useful when PHC's are exposed as different HW clocks but share a common PHC (think mellanox).
phc_offset_strategy: This manually changes the sync strategy of the linux driver used, advised not to change.
phc_local_pref: If you have multiple sources coming into multiple PHC's this allows for the manual selection of a master.
phc_smoothing_strategy: This modifies the smoothing strategy per PHC, advised not to change
phc_lp_filter_enabled: This enables a lucky packet filter to be applied between PHC and system clock, advised not to change
phc_ng_filter_enabled: This enables a non-gaussian filter to be applied between PHC and system clock, advised not to change
phc_samples: Number of samples used to determine offset of system clock, advised not to change
phc_one_step: Enables one step PTP on particular PHC
tai_offset: Determines the TAI offset, advised to maintain setting to Auto.
phc_offsets: Allows manually changing TAI offset between PHC's and system clock, advised not to change
pps_config: Enables PPS out to be configured from an interface at startup
ptp_tuning:
enable_ptp_global_sockets: True or false, setting to true will allow Timebeat to utilise global sockets for PTP detection, advised not to use unless using auto-detect
relax_delay_requests: True or False, setting to true will randomly delay 'delay request' messages, this option is forced to true with Multicast
auto_discover_enabled: When auto discover is enabled, ptp multicast sources will automatically be configured as secondary sources based on received announce messages if no explicit configuration in the domain exist.
multicast_ttl: This manually sets the multicast ttl
dscp.general: This setting modifies the DSCP value, typically used in Broadcast
dscp.event:
# Clock Quality
clock_quality: This section is for the PTP packet data
auto: True or False, This is recomended to remain as Auto but can be configured manually. This sets up the PTP packet data.
class: This is the clock class provided in the PTP packets
accuracy: This is the level of accuracy detailed in the PTP packet data (not the offset data)
variance:
timesource: This is the timesource, typically this will be atomic or GNSS of oscillator as it relates to the Open Timecard
synchronise_rtc: This is where you can disable synchronisation of the RTC
enable: True or False, setting to false will disable synchronisation of the RTC
clock_interval: This is the interval of how often timebeat will synchronise the RTC
cli:
enable: True or false, setting to true will enable CLI access
bind_port: The bind port for the CLI
bind_host: The bind host/ip address of the CLI
server_key: "/etc/timebeat/cli_id_rsa"
authorised_keys: "/etc/timebeat/authorised_keys"
username: This is the username used to ssh to the CLI
password: This is the password to the CLI when requested
# ================================== General ===================================
name: This changes the name of the logged device to something other than the hostname
# ================================== Outputs ===================================
# Configure what output to use when sending the data collected by the beat.
NOTE: only one output configuration can be used at a time.
# -------------------------------- File Output ---------------------------------
output.file: This enables Timebeat to log offset data to a local file.
enabled: True or False, when set to true, timebeat will log to file
path: The pathname for where timebeat will log to
filename: The file name timebeat will create for the file
rotate_every_kb: When this size is reached, and on every Timebeat restart, the files are rotated
number_of_files: Maximum number of files before they are rotated
permissions: Permissions to use for file creation. The default is 0600.
rotate_on_startup: Configure automatic file rotation on every startup. The default is true.
# ================================== Logging ===================================
logging.level: Sets the log level
logging.metrics.enabled: True or False, this logs various metrics every 30seconds internal to timebeat, not offset data.
logging.metrics.period: This is the frequency timebeat logs internal metrics
logging.to_files: True or False, setting to true enables timebeat to create logs to files (not offset data)
logging.files:
path: Configure the path where the logs are written. The default is the logs directory
name: The file name
rotateeverybytes: Configure log file size limit. If limit is reached, log file will be automatically rotated
keepfiles: Number of rotated log files to keep. Oldest files will be deleted first.
permissions: The permissions mask to apply when rotating log files. The default value is 0600
rotateonstartup: True or False, Rotate existing logs on startup rather than appending to the existing Default is true
# ============================== Process Security ==============================
seccomp.enabled: True or False, Default is false, this disable the filtering of syscalls as we require system clock access. Timebeat will not operate if you set to true.