From 55ed500de0baba3beeea8779f2aed4866abfe8f5 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Tue, 23 Jun 2026 11:25:32 +0100 Subject: docs: Update Config sync page to VyOS 1.5 standards (#2113) (#2114) * docs: Update Config sync page to VyOS 1.5 standards * Minor corrections * Update config-sync.md * Apply suggestion from @github-actions[bot] * Apply suggestion from @github-actions[bot] --------- (cherry picked from commit 228149f1a1d824b968b565f82c3ee73eb7ba489c) Co-authored-by: LiudmylaNad Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/configuration/service/config-sync.md | 317 +++++++++++++++++++++--------- 1 file changed, 223 insertions(+), 94 deletions(-) (limited to 'docs') diff --git a/docs/configuration/service/config-sync.md b/docs/configuration/service/config-sync.md index a575f947..262b7cd7 100644 --- a/docs/configuration/service/config-sync.md +++ b/docs/configuration/service/config-sync.md @@ -1,164 +1,293 @@ +--- +myst: + html_meta: + description: | + Config sync is a VyOS service that replicates selected sections of + one router's configuration to another by pushing changes from a + primary to a secondary over the HTTPS API. + keywords: config-sync, configuration synchronization, primary, secondary, https api +--- + (config-sync)= -# Config Sync +# 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. -Configuration synchronization (config sync) is a feature of VyOS that -permits synchronization of the configuration of one VyOS router to -another in a network. +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: -The main benefit to configuration synchronization is that it eliminates having -to manually replicate configuration changes made on the primary router to the -secondary (replica) router. +- `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. -The writing of the configuration to the secondary router is performed through -the VyOS HTTP API. The user can specify which portion(s) of the configuration will -be synchronized and the mode to use - whether to replace or add. +Synchronization is strictly unidirectional from primary to secondary; +changes made on the secondary are not sent back. -To prevent issues with divergent configurations between the pair of routers, -synchronization is strictly unidirectional from primary to replica. Both -routers should be online and run the same version of VyOS. +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 -```{cfgcmd} set service config-sync secondary \ +### Secondary router parameters + +```{cfgcmd} set service config-sync secondary address \ + +**Configure the address of the secondary router.** -Specify the address, API key, timeout and port of the secondary router. -You need to enable and configure the HTTP API service on the secondary -router for config sync to operate. +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 {abbr}`FQDN (Fully Qualified Domain Name)`. This +value is mandatory. ``` -```{cfgcmd} set service config-sync section \ +```{note} +The address must be set whenever `service config-sync` is configured. +Otherwise, the commit is rejected. +``` -Specify the section of the configuration to synchronize. If more than one -section is to be synchronized, repeat the command to add additional -sections as required. +Example: + +```none +set service config-sync secondary address 192.0.2.112 ``` -```{cfgcmd} set service config-sync mode \ +```{cfgcmd} set service config-sync secondary port \<1-65535\> -Two options are available for *mode*: either *load* and replace or *set* -the configuration section. +**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: + ```none -Supported options for
include: - firewall - interfaces - nat - nat66 - pki - policy - protocols - qos - service - system - vpn - vrf +set service config-sync secondary port 8443 +``` + +```{cfgcmd} set service config-sync secondary key \ + +**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 + 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. +``` -## Operational Commands +Example: -````{opcmd} show configuration secondary sync [commands] [running | candidate | saved] [\] +```none +set service config-sync secondary key 'foo' +``` -Display configuration differences between the local node and -a config-sync secondary node. +```{cfgcmd} set service config-sync secondary timeout \<1-3600\> -This command allows operators to compare configurations across nodes -participating in configuration synchronization (e.g., primary and -secondary routers). It helps detect configuration drift and validate -intended changes before synchronization. +**Configure how long, in seconds, the primary router waits for an HTTPS +response from the secondary after pushing configuration.** -**Parameters:** +The default is 60 seconds. +``` -```{eval-rst} -.. list-table:: - :widths: 30 70 - :header-rows: 0 +Example: - * - ``commands`` (optional) - - Show output as a list of configuration commands instead of raw diff. - * - ``running|candidate|saved`` (optional, mutually exclusive) - - Select which configuration to compare: - ``running`` (current active configuration, default), - ``candidate`` (uncommitted changes), or - ``saved`` (last saved configuration). Only one of these may be - specified at a time; if omitted, ``running`` is used. +```none +set service config-sync secondary timeout 120 ``` -**Examples:** +### Synchronization mode -:::{code-block} none -# compare full running configuration with a secondary node -show configuration secondary sync +```{cfgcmd} set service config-sync mode \ -# compare only interface configuration -show configuration secondary sync running interfaces dummy +**Configure how the secondary router applies the configuration pushed +by the primary:** -# compare candidate configuration and display as a list of commands -show configuration secondary sync commands candidate -::: -```` +- `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: + +```none +set service config-sync mode load +``` -Without a built-in cross-node diff, operators may unintentionally push -changes that conflict with the remote configuration (e.g., mismatched -interfaces, firewall policies, or protocol settings). +### Sections to synchronize +```{cfgcmd} set service config-sync section \ + +**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: + +- `firewall` +- `interfaces ` +- `nat` +- `nat66` +- `pki` +- `policy` +- `protocols ` +- `qos ` +- `service ` +- `system ` +- `vpn` +- `vrf` +``` + +```{note} +At least one section must be set whenever `service config-sync` is +configured. Otherwise, the commit is rejected. +``` + +Example: + +```none +set service config-sync section protocols ospf +set service config-sync section system time-zone +``` + +## Operation + +```{opcmd} show configuration secondary sync [commands] [running | candidate | saved [\]] + +**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 `` 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: + +```none +# 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 -- Synchronize the time-zone and OSPF configuration from Router A to Router B -- The address of Router B is 10.0.20.112 and the port used is 8443 +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. -Configure the HTTP API service on Router B +Enable and configure the HTTPS API service on Router B: ```none -set service https listen-address '10.0.20.112' +set service https listen-address '192.0.2.112' set service https port '8443' -set service https api keys id KID key 'foo' +set service https api keys id primary key 'foo' set service https api rest ``` -Configure the config-sync service on Router A +Configure the config-sync service on Router A: ```none set service config-sync mode 'load' -set service config-sync secondary address '10.0.20.112' +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 config-sync relevant changes to Router A's configuration +Make changes on Router A that fall under one of the synchronized +sections. The post-commit hook fires automatically on commit: ```none vyos@vyos-A# set system time-zone 'America/Los_Angeles' vyos@vyos-A# commit -INFO:vyos_config_sync:Config synchronization: Mode=load, -Secondary=10.0.20.112 +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 '10.0.48.0/30' +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=10.0.20.112 -yos@vyos-A# save +INFO:vyos_config_sync:Config synchronization: Mode=load, Secondary=192.0.2.112 +vyos@vyos-A# save ``` -Verify configuration changes have been replicated to Router B +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: ```none 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 '10.0.48.0/30' +set protocols ospf area 0 network '198.51.100.0/30' ``` - - -## Known issues - -Configuration resynchronization. With the current implementation of *service -config-sync*, the secondary node must be online. -- cgit v1.2.3