VyOS Configuration Overview - Hierarchical Management

VyOS uses a hierarchical configuration system that provides flexible and structured management of system settings.

Configuration structure

The VyOS configuration is organized as a tree of nodes, each of which can hold values and child nodes.

Hierarchy example

interfaces {
    ethernet eth0 {
        address 192.168.1.1/24
        description "LAN Interface"
    }
    ethernet eth1 {
        address dhcp
        description "WAN Interface"
    }
}

Representation as set commands

The same configuration expressed as set commands:

set interfaces ethernet eth0 address 192.168.1.1/24
set interfaces ethernet eth0 description 'LAN Interface'
set interfaces ethernet eth1 address dhcp
set interfaces ethernet eth1 description 'WAN Interface'

Operating modes

Operational mode

Used for:

Viewing system information
Monitoring status
Running diagnostic commands
Managing system processes

Command-line prompt: vyos@vyos:~$

Configuration mode

Used for:

Changing system settings
Managing the configuration
Applying and saving changes

Command-line prompt: vyos@vyos#

Entering configuration mode:

vyos@vyos:~$ configure
[edit]
vyos@vyos#

Core concepts

1. Working and active configuration

VyOS distinguishes between two types of configuration:

Working configuration - changes that have been made but not yet applied
Active configuration - the current running configuration of the system

Changes from the working configuration are transferred to the active configuration after running the commit command.

2. Transactional model

Configuration changes are applied atomically:

All changes are applied at once when commit runs
If any change causes an error, the entire transaction is rolled back
This prevents partially applied configurations

3. Automatic rollback

VyOS supports automatic rollback for critical changes:

vyos@vyos# commit-confirm 5

If the confirm command is not run within 5 minutes, all changes are automatically rolled back. This protects against losing access to a remote router.

4. Configuration history

VyOS automatically records the history of all commit operations:

vyos@vyos# show system commit
0   2024-10-13 15:30:45 by vyos via cli
1   2024-10-13 14:15:22 by vyos via cli
2   2024-10-13 12:05:10 by vyos via cli

You can roll back to any previous version:

vyos@vyos# rollback 1
vyos@vyos# commit

Configuration node types

Leaf nodes

Nodes that hold final values:

set system host-name 'vyos-router'
set interfaces ethernet eth0 address '192.168.1.1/24'

Container nodes

Nodes that contain other nodes:

set interfaces ethernet eth0
set service dhcp-server

Multi-value nodes

Nodes that can hold several values:

set interfaces ethernet eth0 address '192.168.1.1/24'
set interfaces ethernet eth0 address '192.168.2.1/24'
set interfaces ethernet eth0 address '2001:db8::1/64'

Tag nodes

Nodes with named instances:

set firewall ipv4 name WAN_LOCAL rule 10
set firewall ipv4 name WAN_LOCAL rule 20
set firewall ipv4 name WAN_LOCAL rule 30

Configuration file

Location

The active configuration is stored in:

/config/config.boot

Format

The configuration is saved in a text format (similar to JSON):

interfaces {
    ethernet eth0 {
        address 192.168.1.1/24
        description "LAN Interface"
        hw-id 00:0c:29:44:3b:0f
    }
}
system {
    host-name vyos-router
    time-zone UTC
}

Manual editing

Editing /config/config.boot directly while the system is running is not recommended. Instead, use:

The set and delete commands in configuration mode
The load command to load a configuration from a file

To edit the configuration offline (when the system is powered off), you can mount the /config partition and edit config.boot.

Configuration management

Saving the configuration

vyos@vyos# save
Saving configuration to '/config/config.boot'...
Done

Saving to a different file:

vyos@vyos# save /tmp/backup-config.boot

Saving to a remote server:

vyos@vyos# save scp://user@192.0.2.100/backup/config.boot

Loading the configuration

Loading a configuration from a file:

vyos@vyos# load /tmp/backup-config.boot

Loading from a remote server:

vyos@vyos# load scp://user@192.0.2.100/backup/config.boot

Merging configurations

Merging a configuration from a file with the current one:

vyos@vyos# merge /tmp/additional-config.boot

Viewing the configuration

The entire configuration

vyos@vyos# show

Part of the configuration

vyos@vyos# show interfaces
vyos@vyos# show interfaces ethernet eth0

Configuration as set commands

vyos@vyos# show interfaces ethernet eth0 | commands
set interfaces ethernet eth0 address '192.168.1.1/24'
set interfaces ethernet eth0 description 'LAN Interface'

Configuration differences

Viewing changes before commit:

vyos@vyos# compare
[edit interfaces ethernet eth0]
+address 192.168.1.1/24
+description "LAN Interface"

Comparing with a previous version:

vyos@vyos# compare 1

Configuration validation

VyOS automatically validates the configuration when commit runs:

vyos@vyos# commit
[interfaces ethernet eth0]
Invalid address '192.168.1.256/24'
Commit failed

Types of checks:

Syntactic correctness
Value validity (IP addresses, ports, etc.)
Dependencies between parameters
Configuration conflicts

Comments

Adding comments to configuration elements:

vyos@vyos# comment interfaces ethernet eth0 "Primary LAN interface for internal network"

Comments are shown when viewing the configuration:

vyos@vyos# show interfaces ethernet eth0
/* Primary LAN interface for internal network */
ethernet eth0 {
    address 192.168.1.1/24
    description "LAN Interface"
}

Configuration templates

Using variables

When working with repetitive configurations, you can use external scripts to generate set commands.

Example bash script:

#!/bin/bash
for i in {1..10}; do
  echo "set interfaces ethernet eth0.$i vif $i"
  echo "set interfaces ethernet eth0.$i address 192.168.$i.1/24"
done

Save the output to a file and load it:

vyos@vyos# load /tmp/vlan-config.txt
vyos@vyos# commit

Configuration archiving

Automatic archiving

Configuring automatic archiving of every committed version:

set system config-management commit-archive location '/config/archive'
set system config-management commit-revisions 100

Remote archiving

Automatically sending the configuration to a remote server after every commit:

set system config-management commit-archive location 'scp://backup@192.0.2.100/vyos-configs'

On every commit, the configuration will be automatically copied to the remote server.

Best practices

1. Always use commit-confirm for remote changes

vyos@vyos# commit-confirm 10

This protects you from losing access due to a faulty configuration.

2. Make backups before significant changes

vyos@vyos# save /tmp/backup-$(date +%Y%m%d-%H%M%S).boot

3. Use compare before commit

vyos@vyos# compare

Always review your changes before applying them.

4. Document the configuration with comments

vyos@vyos# comment interfaces ethernet eth0 "Connected to core switch port 1/0/24"

5. Use meaningful names for rules and groups

Instead of:

set firewall ipv4 name RULE1 rule 10

Use:

set firewall ipv4 name WAN_LOCAL rule 10

6. Group related changes

Make related changes together and commit them as a single logical unit.

7. Save the configuration regularly

After every successful commit:

vyos@vyos# save

8. Maintain versioning

Use a version control system (Git) to store your configuration files:

cd /config
git init
git add config.boot
git commit -m "Initial configuration"

Configuration automation

Via the API

VyOS 1.5.x provides a REST API for automation:

curl -X POST https://vyos-router/configure \
  -H "Content-Type: application/json" \
  -d '{
    "op": "set",
    "path": ["interfaces", "ethernet", "eth0", "address"],
    "value": "192.168.1.1/24"
  }'

Via Ansible

Using the Ansible module:

- name: Configure VyOS interface
  vyos_config:
    lines:
      - set interfaces ethernet eth0 address 192.168.1.1/24
      - set interfaces ethernet eth0 description 'LAN Interface'

Via scripts

Creating startup scripts in /config/scripts/:

#!/bin/vbash
source /opt/vyatta/etc/functions/script-template
configure
set interfaces ethernet eth0 description 'Auto-configured by script'
commit
save

Troubleshooting

Configuration is not applied

Check for errors during commit:

vyos@vyos# commit

Review the detailed logs:

vyos@vyos:~$ show log | grep commit

Loss of access after changes

If you use a remote connection, always use commit-confirm:

vyos@vyos# commit-confirm 5

Rolling back to a working configuration

If the system does not boot after changes, boot from the previous image via GRUB or use:

vyos@vyos:~$ configure
vyos@vyos# rollback
vyos@vyos# commit
vyos@vyos# save

Next steps

Now that you understand the structure of the VyOS configuration, continue with:

Configuration - detailed guides for configuring components
Administrator Guide - operational commands and automation
Troubleshooting - diagnosing problems

Reviewed by OpenNix LLC · Last updated on 29 July 2026

VyOS CLI - Operational Mode and Configuration VyOS Administrator Guide