Config sync
Configuration synchronization (config-sync) is a VyOS service that replicates selected sections of one router’s configuration to another router. It eliminates the need to manually mirror configuration changes from a primary router to a secondary.
Synchronization is performed by a post-commit hook on the primary router. The hook watches the sections selected for synchronization. When any of them is modified by a commit, the hook calls the HTTPS API on the secondary router and sends the current state of all selected sections in one of the following modes:
load: Replaces the selected sections on the secondary with the primary’s version. Anything that exists only on the secondary inside those sections is removed.set: Merges the primary’s version of the selected sections into the secondary. Conflicting values are overwritten by the primary. Entries that exist only on the secondary are kept.
Synchronization is strictly unidirectional from primary to secondary; changes made on the secondary are not sent back.
Both routers must be online during a commit on the primary that modifies a configured section. If the secondary is unreachable, the primary’s commit still succeeds, but the configuration is not synchronized, and the failure is recorded in the system log.
Configuration
Secondary router parameters
Configure the address of the secondary router.
The primary router pushes the synchronized configuration to this address over the secondary’s HTTPS API. The value can be an IPv4 address, an IPv6 address, or an FQDN. This value is mandatory.
Note
The address must be set whenever service config-sync is configured.
Otherwise, the commit is rejected.
Example:
set service config-sync secondary address 192.0.2.112
Configure the TCP port on which the secondary router’s HTTPS API listens.
The value must match the port configured under service https port on
the secondary router. If they diverge, the primary’s commit succeeds,
but the post-commit sync fails. The secondary is not updated, and the
primary logs the error to the system log.
The default is 443, matching the default of service https port.
Example:
set service config-sync secondary port 8443
Configure the HTTPS API key the primary router uses to authenticate to the secondary router’s HTTPS API.
The value must match a key configured under service https api keys id <ID> key on the secondary. If no matching key exists on the secondary,
the primary’s commit still succeeds, but the post-commit sync fails.
The secondary is not updated, and the primary logs the error to the
system log.
Note
This value must be set whenever service config-sync is configured.
Otherwise, the commit is rejected.
Example:
set service config-sync secondary key 'foo'
Configure how long, in seconds, the primary router waits for an HTTPS response from the secondary after pushing configuration.
The default is 60 seconds.
Example:
set service config-sync secondary timeout 120
Synchronization mode
Configure how the secondary router applies the configuration pushed by the primary:
load: Replaces the selected sections on the secondary with the primary’s version. Anything that exists only on the secondary inside those sections is removed.set: Merges the primary’s version of the selected sections into the secondary. Conflicting values are overwritten by the primary. Entries that exist only on the secondary are kept.
Note
This value must be set whenever service config-sync is configured.
Otherwise, the commit is rejected.
Example:
set service config-sync mode load
Sections to synchronize
Configure one or more configuration sections to be synchronized from the primary to the secondary router.
Repeat the command to add additional sections. If any configured section was modified by a commit on the primary, the hook pushes the current state of all configured sections to the secondary. If none of the configured sections were modified, the hook does nothing.
Supported sections:
firewallinterfaces <bonding | bridge | dummy | ethernet | geneve | input | l2tpv3 | loopback | macsec | openvpn | pppoe | pseudo-ethernet | sstpc | tunnel | virtual-ethernet | vti | vxlan | wireguard | wireless | wwan>natnat66pkipolicyprotocols <babel | bfd | bgp | failover | igmp-proxy | isis | mpls | nhrp | ospf | ospfv3 | pim | pim6 | rip | ripng | rpki | segment-routing | static>qos <interface | policy>service <console-server | dhcp-relay | dhcp-server | dhcpv6-relay | dhcpv6-server | dns | lldp | mdns | monitoring | ndp-proxy | ntp | snmp | tftp-server | webproxy>system <conntrack | flow-accounting | login | option | sflow | static-host-mapping | sysctl | time-zone>vpnvrf
Note
At least one section must be set whenever service config-sync is
configured. Otherwise, the commit is rejected.
Example:
set service config-sync section protocols ospf
set service config-sync section system time-zone
Operation
Show the difference between the local configuration on the primary and the running configuration on the secondary.
The command fetches the secondary’s running configuration live over the HTTPS API, so the secondary must be reachable.
The local configuration defaults to running and can be set to
candidate (uncommitted changes) or saved (last saved configuration).
The remote side is always the secondary’s running configuration.
By default, the difference is shown in the curly-brace configuration
format with - prefixing lines that exist only on the secondary and
+ prefixing lines that exist only on the primary. The optional
commands keyword renders the same difference as a sequence of set
and delete configuration commands, where set lists paths present
only on the primary, and delete lists paths present only on the
secondary.
The optional <config-node-path> argument limits the difference to a
single section and must be one of the sections already configured under
set service config-sync section. If omitted, the difference covers
all configured sections.
Examples:
# Compare the full running configuration against the secondary
show configuration secondary sync
# Compare only the OSPF protocol configuration against the secondary
show configuration secondary sync running protocols ospf
# Compare the candidate configuration against the secondary,
# rendered as commands
show configuration secondary sync commands candidate
Example
The following example synchronizes the system time-zone and
protocols ospf sections from Router A (primary, 192.0.2.1) to
Router B (secondary, 192.0.2.112). Router B’s HTTPS API listens on
TCP port 8443.
Enable and configure the HTTPS API service on Router B:
set service https listen-address '192.0.2.112'
set service https port '8443'
set service https api keys id primary key 'foo'
set service https api rest
Configure the config-sync service on Router A:
set service config-sync mode 'load'
set service config-sync secondary address '192.0.2.112'
set service config-sync secondary port '8443'
set service config-sync secondary key 'foo'
set service config-sync section protocols 'ospf'
set service config-sync section system 'time-zone'
Make changes on Router A that fall under one of the synchronized sections. The post-commit hook fires automatically on commit:
vyos@vyos-A# set system time-zone 'America/Los_Angeles'
vyos@vyos-A# commit
INFO:vyos_config_sync:Config synchronization: Mode=load, Secondary=192.0.2.112
vyos@vyos-A# save
vyos@vyos-A# set protocols ospf area 0 network '198.51.100.0/30'
vyos@vyos-A# commit
INFO:vyos_config_sync:Config synchronization: Mode=load, Secondary=192.0.2.112
vyos@vyos-A# save
Each commit on Router A modifies one section, but because the hook
pushes all configured sections whenever any of them is modified, both
commits replace the full state of system and protocols ospf on
Router B.
Verify that the changes have been applied on Router B:
vyos@vyos-B:~$ show configuration commands | match time-zone
set system time-zone 'America/Los_Angeles'
vyos@vyos-B:~$ show configuration commands | match ospf
set protocols ospf area 0 network '198.51.100.0/30'