# VyOS Configuration Overview - Hierarchical Management

> VyOS configuration system - hierarchical structure, transactional model, commit/save workflow, version history, and configuration rollback.

Source: https://opennix.org/en/docs/vyos/first-steps/vyos-config-overview/


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:

```bash
#!/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:

```bash
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:

```bash
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:

```yaml
- 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/`:

```bash
#!/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](/docs/vyos/) - detailed guides for configuring components
- [Administrator Guide](/docs/vyos/admin-guide/) - operational commands and automation
- [Troubleshooting](/docs/vyos/admin-guide/vyos-troubleshooting/) - diagnosing problems