Config Sync

Config Sync is a service for automatic configuration synchronization between two VyOS routers.

Overview

Config Sync provides automatic replication of configuration changes from the primary router to the secondary one.

Key capabilities:

One-way synchronization (primary → secondary)
Selective synchronization of configuration sections
Automatic push of changes after commit
Two synchronization modes: load and set
Support for all major configuration sections

Requirements:

VyOS REST API configured on the secondary router
Both routers must be online
Identical VyOS version on both devices
Network connectivity between the routers

Protocol: HTTPS/HTTP (VyOS REST API)

Port: 443 (HTTPS) or a custom value

How it works

Architecture

┌──────────────────┐                    ┌──────────────────┐
│   Primary VyOS   │                    │  Secondary VyOS  │
│                  │                    │                  │
│  Config Sync     │──── HTTPS API ────>│   REST API       │
│  Client          │                    │   Server         │
│                  │                    │                  │
└──────────────────┘                    └──────────────────┘
     (master)                               (replica)

Synchronization process

The administrator makes changes on the primary router
A commit is executed on the primary
Config Sync intercepts the changes
The changes are pushed to the secondary via the REST API
The secondary applies the configuration
The result is logged on the primary

Synchronization direction

Important: Synchronization is one-way:

Primary → Secondary: Yes
Secondary → Primary: No

Changes made on the secondary are NOT synchronized back and will be overwritten during the next synchronization from the primary.

Basic configuration

Preparing the Secondary router

The first step is to configure the REST API on the secondary router:

VyOS 1.4 (Sagitta)

configure
set service https api keys id config-sync key 'your-secure-api-key-here'
commit
save

VyOS 1.5 (Circinus)

configure
set service https api keys id config-sync key 'your-secure-api-key-here'
set service https api rest
commit
save

Note: In VyOS 1.5, the REST API endpoint must be explicitly enabled.

Configuring the Primary router

Configure Config Sync on the primary router:

configure

# Specify the secondary router address
set service config-sync secondary address '192.168.100.2'

# API key (must match the key on the secondary)
set service config-sync secondary key 'your-secure-api-key-here'

# Sections to synchronize
set service config-sync section firewall
set service config-sync section nat
set service config-sync section vpn

commit
save

Configuration parameters

Secondary router

address

IP address or hostname of the secondary router:

set service config-sync secondary address '192.168.100.2'
set service config-sync secondary address 'vyos-backup.example.com'
set service config-sync secondary address '2001:db8::2'

key

API key for authentication:

set service config-sync secondary key 'your-secure-api-key-here'

Generating a secure key:

openssl rand -base64 32

port

REST API TCP port (default 443):

set service config-sync secondary port 443
set service config-sync secondary port 8443

timeout

Connection timeout in seconds (default 60):

set service config-sync secondary timeout 60
set service config-sync secondary timeout 120

Increase this value for slow links or large configurations.

Section - sections to synchronize

Select the configuration sections to replicate:

set service config-sync section <section-name>

Available sections:

Section	Description
`firewall`	Firewall rules, zones, groups
`interfaces`	Interface configuration
`nat`	NAT rules (source, destination)
`nat66`	NAT66 (IPv6-to-IPv6)
`pki`	PKI certificates and keys
`protocols`	Dynamic routing (BGP, OSPF, RIP)
`qos`	Quality of Service policies
`service`	Services (DHCP, DNS, SSH, etc.)
`system`	System settings (hostname, users, etc.)
`vpn`	VPN configuration (IPsec, OpenVPN, L2TP)
`vrf`	Virtual Routing and Forwarding

Examples:

Synchronize all network services:

set service config-sync section firewall
set service config-sync section nat
set service config-sync section interfaces
set service config-sync section vpn

Routing and services only:

set service config-sync section protocols
set service config-sync section service

Mode - synchronization mode

load (default)

Replaces the section configuration on the secondary:

set service config-sync mode load

Behavior:

Removes the existing section configuration on the secondary
Loads the new configuration from the primary
Recommended for full synchronization

Example:

# Primary has:
firewall rule 10, 20, 30

# Secondary will have exactly the same:
firewall rule 10, 20, 30

# Any other rules on the secondary will be removed

set

Adds/updates the configuration on the secondary:

set service config-sync mode set

Behavior:

Does not remove the existing configuration
Adds new parameters
Updates existing parameters
May lead to configuration mismatch

Example:

# Primary has:
firewall rule 10, 20

# Secondary has:
firewall rule 30, 40

# After synchronization the secondary will have:
firewall rule 10, 20, 30, 40

Recommendation: Use load to guarantee identical configurations.

Configuration examples

Basic HA router

Primary router:

configure

# Secondary router
set service config-sync secondary address '192.168.100.2'
set service config-sync secondary key 'MySecureKey123!@#'

# Synchronize critical sections
set service config-sync section firewall
set service config-sync section nat
set service config-sync section system

# Full-replacement mode
set service config-sync mode load

commit
save

Secondary router:

configure

# Enable REST API
set service https api keys id config-sync key 'MySecureKey123!@#'
set service https api rest

commit
save

HA VPN gateway

Primary:

configure

# Secondary router
set service config-sync secondary address '10.0.0.2'
set service config-sync secondary key 'VpnGatewaySync2024'
set service config-sync secondary timeout 120

# VPN and related sections
set service config-sync section vpn
set service config-sync section firewall
set service config-sync section nat
set service config-sync section pki

# Replacement mode
set service config-sync mode load

commit
save

Synchronizing OSPF configuration

Primary:

configure

# Secondary router
set service config-sync secondary address '192.168.1.2'
set service config-sync secondary key 'OspfSyncKey'

# Routing protocols and system only
set service config-sync section protocols
set service config-sync section system

commit
save

Multi-site with VRF

Primary:

configure

# Secondary router
set service config-sync secondary address '10.10.10.2'
set service config-sync secondary key 'VrfMultiSite2024'

# VRF, routing, and services
set service config-sync section vrf
set service config-sync section protocols
set service config-sync section interfaces
set service config-sync section service

commit
save

Full synchronization of all sections

Primary:

configure

set service config-sync secondary address '192.168.100.2'
set service config-sync secondary key 'FullSyncKey2024'

# All supported sections
set service config-sync section firewall
set service config-sync section interfaces
set service config-sync section nat
set service config-sync section nat66
set service config-sync section pki
set service config-sync section protocols
set service config-sync section qos
set service config-sync section service
set service config-sync section system
set service config-sync section vpn
set service config-sync section vrf

set service config-sync mode load

commit
save

Examples for cloud providers

Yandex Cloud HA configuration

Topology:

Primary VyOS: 192.168.10.10 (internal IP)
Secondary VyOS: 192.168.10.20 (internal IP)
Both VMs in the same Yandex Cloud subnet
Security Group allows HTTPS between the VMs

Secondary router (192.168.10.20):

configure

# REST API setup
set service https api keys id yc-config-sync key 'YC-Secure-Key-2024-Random-String'
set service https api rest

# Allow HTTPS from the internal network
set service https listen-address 192.168.10.20

# HTTPS certificate (self-signed for internal use)
set service https certificates system-generated-certificate

commit
save

Primary router (192.168.10.10):

configure

# Connection to the secondary
set service config-sync secondary address '192.168.10.20'
set service config-sync secondary key 'YC-Secure-Key-2024-Random-String'
set service config-sync secondary port 443
set service config-sync secondary timeout 90

# Sections to synchronize
set service config-sync section firewall
set service config-sync section nat
set service config-sync section interfaces
set service config-sync section system

# Full-replacement mode
set service config-sync mode load

commit
save

Note for Yandex Cloud:

Use internal IP addresses for synchronization
Configure Security Groups to allow HTTPS (TCP 443)
Consider using a Network Load Balancer for failover

VK Cloud (Mail.ru Cloud) HA configuration

Topology:

Primary VyOS: 10.0.10.10 (private IP)
Secondary VyOS: 10.0.10.20 (private IP)
Floating IP for failover
Security Group with an HTTPS rule

Secondary router (10.0.10.20):

configure

# REST API configuration
set service https api keys id vkcloud-sync key 'VKCloud-HA-Key-SecureRandom123'
set service https api rest

# Listen on the private interface
set service https listen-address 10.0.10.20

# Self-signed certificate
set service https certificates system-generated-certificate

commit
save

Primary router (10.0.10.10):

configure

# Secondary endpoint
set service config-sync secondary address '10.0.10.20'
set service config-sync secondary key 'VKCloud-HA-Key-SecureRandom123'
set service config-sync secondary port 443
set service config-sync secondary timeout 120

# Critical sections
set service config-sync section firewall
set service config-sync section nat
set service config-sync section vpn
set service config-sync section service

set service config-sync mode load

commit
save

Security Group setup in VK Cloud:

# Allow HTTPS between the HA pair
Direction: Ingress
Protocol: TCP
Port: 443
Source: 10.0.10.10/32

AWS HA across different AZs

Topology:

Primary: us-east-1a (10.0.1.10)
Secondary: us-east-1b (10.0.2.20)
Different Availability Zones for fault tolerance

Secondary (10.0.2.20):

configure

set service https api keys id aws-ha key 'AWS-HA-Sync-Key-Random'
set service https api rest
set service https listen-address 10.0.2.20
set service https certificates system-generated-certificate

commit
save

Primary (10.0.1.10):

configure

set service config-sync secondary address '10.0.2.20'
set service config-sync secondary key 'AWS-HA-Sync-Key-Random'
set service config-sync secondary timeout 150

# Full synchronization for DR
set service config-sync section firewall
set service config-sync section nat
set service config-sync section interfaces
set service config-sync section protocols
set service config-sync section service
set service config-sync section system
set service config-sync section vpn

set service config-sync mode load

commit
save

Azure HA with an Availability Set

Topology:

Primary: 172.16.1.10 (zone 1)
Secondary: 172.16.1.20 (zone 2)
Azure Load Balancer for failover

Secondary (172.16.1.20):

configure

set service https api keys id azure-ha key 'Azure-ConfigSync-2024-SecureKey'
set service https api rest
set service https listen-address 172.16.1.20

commit
save

Primary (172.16.1.10):

configure

set service config-sync secondary address '172.16.1.20'
set service config-sync secondary key 'Azure-ConfigSync-2024-SecureKey'
set service config-sync secondary port 443

set service config-sync section firewall
set service config-sync section nat
set service config-sync section vpn
set service config-sync section protocols

set service config-sync mode load

commit
save

Operational commands

Viewing the configuration

Show the current Config Sync configuration:

show service config-sync

Output:

 config-sync {
     mode load
     secondary {
         address 192.168.100.2
         key ****************
         port 443
         timeout 60
     }
     section firewall
     section nat
     section vpn
 }

Manual synchronization

Config Sync triggers automatically after a commit. To run it manually:

reset config-sync

This re-synchronizes all configured sections.

Checking the status

Check the last synchronization:

show log | match config-sync

Successful synchronization:

Oct 15 10:30:15 vyos-primary config-sync[1234]: Successfully synced section 'firewall' to 192.168.100.2
Oct 15 10:30:16 vyos-primary config-sync[1234]: Successfully synced section 'nat' to 192.168.100.2

Synchronization error:

Oct 15 10:30:15 vyos-primary config-sync[1234]: Failed to sync to 192.168.100.2: Connection timeout

Monitoring the logs

Real-time monitoring:

monitor log | match config-sync

Or via the system journal:

show log tail 50 | match config-sync

Troubleshooting

Synchronization is not working

Symptoms: Changes on the primary do not appear on the secondary.

Check 1 - REST API on the secondary:

show service https

It must be running and have an API key.

Check 2 - Network connectivity:

ping 192.168.100.2

Check 3 - HTTPS availability:

curl -k https://192.168.100.2/

It should return a response from the VyOS API.

Check 4 - Inspect the logs:

show log | match config-sync

Solution:

# On the secondary, verify the API
show service https api

# Restart the HTTPS service if needed
restart https

# On the primary, check the configuration
show service config-sync

# Try a manual synchronization
reset config-sync

Authentication error

Symptoms: Authentication failed in the logs.

Cause: The API keys do not match.

Solution:

On the secondary:

show service https api keys

On the primary:

show service config-sync secondary key

Update the key on the primary if they differ:

set service config-sync secondary key 'correct-key-from-secondary'
commit

Timeout errors

Symptoms: Connection timeout in the logs.

Causes:

Slow network
Large configuration
Overloaded secondary

Solution:

Increase the timeout:

set service config-sync secondary timeout 180
commit

Check the load on the secondary:

# On the secondary
show system cpu
show system memory

Partial synchronization

Symptoms: Some sections synchronize, others do not.

Check:

show log | match "config-sync.*Failed"

Possible causes:

VyOS version incompatibility
Syntax errors in the configuration
Insufficient API key permissions

Solution:

Check the versions:

# On both routers
show version

Validate the configuration:

show configuration commands | grep <section>

Secondary router offline

Symptoms: Connection refused or No route to host.

Check:

ping 192.168.100.2
show log | match config-sync

Behavior: Config Sync will keep retrying on the next commit.

Solution:

Restore network connectivity
Check the firewall between the routers
After recovery, run reset config-sync

Configuration conflicts

Symptoms: After synchronization, the secondary has errors or unexpected behavior.

Cause: The set mode can create conflicts.

Solution:

Switch to load mode:

set service config-sync mode load
commit

Manually clear the section configuration on the secondary if needed:

# On the secondary
delete firewall
commit

# Config Sync will load a fresh configuration on the next commit on the primary

VyOS version mismatch

Symptoms: Synchronization works, but the secondary shows errors.

Check:

# On both routers
show version | grep Version

Solution: Upgrade both routers to the same VyOS version.

Security

Protecting the API key

Generating a strong key:

openssl rand -base64 32

Example output:

3Km8WxT7qN9vB2hL5pY6sF1dC4eR8tU3jH7gN2mK9xP=

Do not use weak keys:

Dictionary words
Simple patterns (123456, password)
Short keys (< 20 characters)

Firewall rules

Restrict REST API access to the primary router only:

On the secondary router:

# Allow HTTPS only from the primary
set firewall ipv4 input filter rule 100 action accept
set firewall ipv4 input filter rule 100 destination port 443
set firewall ipv4 input filter rule 100 protocol tcp
set firewall ipv4 input filter rule 100 source address 192.168.100.1

# Deny all other HTTPS connections
set firewall ipv4 input filter rule 110 action drop
set firewall ipv4 input filter rule 110 destination port 443
set firewall ipv4 input filter rule 110 protocol tcp

commit

HTTPS certificates

Self-signed certificates (internal networks):

set service https certificates system-generated-certificate
commit

Custom certificates:

# First, import the certificate via PKI
set pki certificate vyos-cert certificate 'MII...'
set pki certificate vyos-cert private key 'MII...'

# Use it in HTTPS
set service https certificates certificate vyos-cert
commit

Restricting the listen-address

Listen only on the internal interface:

set service https listen-address 192.168.100.2
set service https listen-address 10.0.0.2
commit

Do not use:

# Dangerous - listens on all interfaces
set service https listen-address 0.0.0.0

Audit logging

Enable logging of all API operations:

set system syslog global facility all level info
set system syslog host 192.168.1.100 facility all level info
commit

Best practices

Planning

Choose the right sections: Synchronize only what must be identical
Test on staging: Verify Config Sync in a test environment before production
Document the architecture: Clearly indicate which router is primary and which is secondary

Configuration

Use load mode: Guarantees identical configurations
Do not synchronize interfaces blindly: Interfaces may have different IP addresses
Generate strong API keys: At least 32 characters of random data
Set an adequate timeout: Account for configuration size and network speed

Operations

Monitor the logs: Regularly check synchronization success
Test failover: Periodically verify that the secondary is operational
Make backups: Config Sync does not replace a backup
Version control: Keep configuration history in git

Security

Restrict the firewall: Only the primary should have access to the secondary’s API
Use internal networks: Do not synchronize over the public internet without a VPN
Rotate keys regularly: Rotate API keys every 90 days
Log all operations: Centralized logging for an audit trail

Fault tolerance

Test failover scenarios: Primary goes down, switch over to the secondary
Document recovery procedures: How to bring the primary back into service
Synchronization after recovery: How to restore sync after downtime
Monitor both routers: Alerting on synchronization problems

Limitations

One-way synchronization: Primary → secondary only
Requires an online secondary: Both routers must be reachable
Identical VyOS version: Version incompatibility can cause errors
No conflict resolution: Changes on the secondary are overwritten
Single secondary: Cannot synchronize with multiple secondaries simultaneously
Synchronous operations: The commit is blocked until synchronization completes

Alternative approaches

For multiple replication

If you need to synchronize more than 2 routers:

Configuration Management: Ansible, SaltStack, Puppet
Git-based: Store configurations in git, apply via CI/CD
Scripted sync: Custom scripts using the VyOS API

For bidirectional sync

Config Sync does not support two-way synchronization. Options:

Two Config Sync instances: Configure mutual synchronization (beware of loops!)
External orchestration: Ansible with centralized state
Manual coordination: Choose one router as the source of truth

Integration with HA

Config Sync works great with VyOS HA (VRRP):

Primary (VRRP Master):

configure

# VRRP
set high-availability vrrp group LAN vrid 10
set high-availability vrrp group LAN interface eth1
set high-availability vrrp group LAN address 192.168.1.1/24

# Config Sync
set service config-sync secondary address '192.168.100.2'
set service config-sync secondary key 'HA-Sync-Key'
set service config-sync section firewall
set service config-sync section nat
set service config-sync section service

commit
save

Secondary (VRRP Backup):

configure

# VRRP (same settings)
set high-availability vrrp group LAN vrid 10
set high-availability vrrp group LAN interface eth1
set high-availability vrrp group LAN address 192.168.1.1/24

# REST API for Config Sync
set service https api keys id config-sync key 'HA-Sync-Key'
set service https api rest

commit
save

Result:

VRRP provides IP failover
Config Sync guarantees an identical configuration
If the primary goes down, the secondary is ready to take over

Monitoring

Prometheus metrics

If you use the VyOS Prometheus exporter:

# Metrics to monitor
- vyos_config_sync_last_success_timestamp
- vyos_config_sync_failures_total
- vyos_config_sync_duration_seconds

Zabbix monitoring

A script to check synchronization:

#!/bin/bash
# check_config_sync.sh

LAST_SYNC=$(grep "Successfully synced" /var/log/messages | tail -1)
SYNC_TIME=$(echo "$LAST_SYNC" | awk '{print $1, $2, $3}')

# Check that synchronization happened within the last hour
if [ -z "$SYNC_TIME" ]; then
    echo "CRITICAL: No config sync found"
    exit 2
fi

# Return OK
echo "OK: Last sync at $SYNC_TIME"
exit 0

Syslog

Send Config Sync logs to a centralized syslog:

set system syslog host 192.168.1.100 facility all level info
set system syslog host 192.168.1.100 port 514
commit

Scenario examples

Initial setup of a new HA pair

Step 1 - Configure the secondary:

configure
set service https api keys id ha-sync key 'GeneratedSecureKey123'
set service https api rest
set service https listen-address 192.168.100.2
commit
save

Step 2 - Configure the primary:

configure
set service config-sync secondary address '192.168.100.2'
set service config-sync secondary key 'GeneratedSecureKey123'
set service config-sync section firewall
set service config-sync section nat
set service config-sync section vpn
commit
save

Step 3 - Verify:

show log | match config-sync

Step 4 - Test a change:

configure
set firewall ipv4 input filter rule 999 action accept
set firewall ipv4 input filter rule 999 description "Test sync"
commit

Step 5 - Check on the secondary:

show firewall ipv4 input filter rule 999

Recovery after a failure

Scenario: The primary was offline and changes were made on the secondary.

Step 1 - Determine the source of truth:

If the secondary configuration is correct, make it the new primary
If the primary configuration is correct, re-synchronize

Step 2 - Switching roles (secondary → primary):

On the old secondary (now the primary):

configure
set service config-sync secondary address '192.168.100.1'
set service config-sync secondary key 'HA-Sync-Key'
set service config-sync section firewall
# ... remaining sections
commit

On the old primary (now the secondary):

configure
delete service config-sync
set service https api keys id ha-sync key 'HA-Sync-Key'
set service https api rest
commit

Step 3 - Force synchronization:

reset config-sync

Planned maintenance

Before maintenance:

# Back up both routers
show configuration commands | cat > /config/backup-$(date +%Y%m%d).conf

# Verify that the secondary is synchronized
show log | match config-sync | tail -20

During maintenance:

# Temporarily disable Config Sync if you are changing the primary
set service config-sync secondary disable
commit

# Perform the maintenance
# ...

# Re-enable it
delete service config-sync secondary disable
commit

# Re-synchronize
reset config-sync

Troubleshooting Checklist

When you run into problems, go through this list:

REST API is running on the secondary (show service https)
API keys match on the primary and secondary
Network connectivity (ping, traceroute)
HTTPS port is reachable (curl, telnet)
Firewall is not blocking HTTPS between the routers
VyOS versions match on both devices
Sections to synchronize are specified correctly
Timeout is sufficient for the configuration size
Logs show no synchronization errors
The secondary router is not overloaded (CPU, memory)
The configuration on the primary is valid (commit check)

Next steps

High Availability (VRRP) - configuring VRRP for IP failover
HTTPS API - detailed REST API setup
System Login - managing users and API keys
Monitoring - monitoring Config Sync operations

Reviewed by OpenNix LLC · Last updated on 29 July 2026

Web Proxy (Squid) in VyOS Monitoring Service in VyOS