configure / set / delete / show / compare — the operational vocabulary

Every change to a VyOS router is composed inside one shell: configure mode. It is the environment where the candidate configuration lives, where the diff is generated, where validators run, and where the change is either committed to the running configuration or discarded. The five commands the engineer types hundreds of times per day — configure, set, delete, show, compare — are the operational vocabulary. Master them and the rest of the course reads easier.

Entering configure mode

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

The prompt changes from $ to # and the bracketed [edit] appears. [edit] shows the current position in the candidate tree, in the Junos-style convention VyOS inherited from Vyatta.

The five commands

flowchart LR
  A[configure] --> B[edit prompt<br/>candidate loaded]
  B --> C[set / delete<br/>edit candidate]
  B --> D[show / compare<br/>inspect candidate]
  C --> E[commit]
  D --> E
  E --> F{validators pass?}
  F -->|yes| G[running config<br/>updated]
  F -->|no| H[error printed<br/>candidate kept]
  B --> I[discard / exit discard]
  G --> J[save]

set — add a configuration directive

[edit]
vyos@vyos# set system host-name 'router-core-01'
[edit]
vyos@vyos# set interfaces ethernet eth0 address '192.0.2.1/24'
[edit]
vyos@vyos# set protocols bgp system-as '64512'
[edit]
vyos@vyos# set protocols bgp neighbor 192.0.2.2 remote-as '64512'

set writes into the candidate tree. Repeating the same set is harmless — the node already holds that value.

Repeating it with a different value is where the two shapes of node matter. A single-value node such as host-name is replaced. A multi-value node such as address gains a second value, and the router ends up with both. The tree does not warn you, because for address that is a completely legitimate thing to want.

delete — remove a configuration directive

[edit]
vyos@vyos# delete system host-name
[edit]
vyos@vyos# delete interfaces ethernet eth0 address '192.0.2.1/24'
[edit]
vyos@vyos# delete protocols bgp neighbor 192.0.2.2

delete prunes the node and everything beneath it. Deleting protocols bgp neighbor 192.0.2.2 removes that neighbour’s entire subtree, including its address families, timers and passwords — which is what you want when you are removing a peer, and a much larger blast radius than intended when you are trying to remove one of its settings. Name the leaf you actually want gone.

show — inspect the candidate

[edit]
vyos@vyos# show system host-name
 host-name router-core-01
[edit]
vyos@vyos# show interfaces ethernet eth0
 address 192.0.2.1/24

In configure mode, show reads the candidate, not the running configuration. This is the most common early confusion: after a set, show reflects the change and the router does not, and the two only converge at commit.

show | commands prints the same candidate as set lines, which is the form to paste into a change record or a peer review.

compare — the diff between candidate and running

[edit]
vyos@vyos# compare
+ system {
+     host-name router-core-01
+ }
+ protocols {
+     bgp {
+         system-as 64512
+         neighbor 192.0.2.2 {
+             remote-as 64512
+         }
+     }
+ }

Every + is being added and every - is being removed. compare takes arguments: compare saved diffs the candidate against the configuration on disk rather than the running one, and compare N or compare N M diffs against stored revisions.

Tab completion and inline help

Pressing Tab at any point lists what the node accepts:

[edit]
vyos@vyos# set interfaces ethernet eth<TAB>
eth0    eth1    eth2
[edit]
vyos@vyos# set protocols bgp <TAB>
Possible completions:
   address-family   BGP address-family parameters
   neighbor         BGP neighbor
   parameters       BGP parameters
   peer-group       BGP peer-group
   system-as        Autonomous System Number (ASN)

The ? key prints the same help without completing:

[edit]
vyos@vyos# set system login user ?
Possible completions:
   <name>   User name

That set protocols bgp completion is worth a second look, because it is the fastest way to tell which release you are on. On VyOS 1.3 the local ASN was a node name, so the tree was set protocols bgp 64512 neighbor ... and completion offered a number here. From 1.4 onward the ASN is a leaf — set protocols bgp system-as 64512 — and peers hang off set protocols bgp neighbor ... directly. A runbook written against 1.3 fails at the first BGP line on a 1.5 box, and completion tells you why in one keystroke.

Navigating the tree

[edit]
vyos@vyos# edit protocols bgp
[edit protocols bgp]
vyos@vyos# set neighbor 192.0.2.2 remote-as '64512'
[edit protocols bgp]
vyos@vyos# up
[edit protocols]
vyos@vyos# top
[edit]

edit moves down into a node, up moves one level back, top returns to the root. Inside a node, set and show are relative to it — which is convenient for a long editing session and is exactly how an operator ends up creating a node one level deeper than they meant. The bracketed prompt is the guard: read it before every set.

Committing, confirming, persisting

[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

commit applies the candidate to the running configuration. save writes the running configuration to /config/config.boot so it survives a reboot. They are separate steps, and a committed but unsaved change is a change that disappears at the next power event — which is the correct behaviour for a risky change and a disaster for a routine one.

For anything that can cut your own access — an address, a firewall ruleset, an SSH listener — use the timed form:

[edit]
vyos@vyos# commit-confirm 5
[edit]
vyos@vyos# confirm

commit-confirm 5 applies the change and starts a five-minute timer. Type confirm within that window and it stays. Lose the session because the change was wrong, and the router reverts on its own. This is the single most valuable habit in the mode, and it costs one extra word.

The exit that refuses

[edit]
vyos@vyos# exit
Cannot exit: configuration modified.
Use 'exit discard' to discard the changes and exit.
[edit]
vyos@vyos# exit discard
vyos@vyos:~$

Configure mode will not let you leave with uncommitted changes. This is a guard, and it is easy to defeat by reflex: the operator who reads the message, types exit discard to get out of the way of something more urgent, and comes back an hour later finds the work gone. There is no undo for a discard.

If the candidate holds work you want to keep but not commit yet, leave the session open, or write it out with show | commands first.

Configuration traps in configure mode

• Forgetting commit. The candidate is not the router. show will happily confirm a change that no packet has ever seen.
• Forgetting save. commit applies, save persists. A change that survived testing and not a reboot is the classic Monday-morning incident.
• commit without compare. Commit applies everything in the candidate, including whatever was left there before you arrived.
• exit discard as a reflex. It is the only way out of a modified candidate and it is irreversible.
• Editing deeper than you think. A relative set from inside edit protocols bgp writes under BGP. Read the bracketed prompt.

How it fails

• A candidate you did not create. compare shows changes nobody in the room remembers making — a colleague’s abandoned session, or your own from before lunch. discard clears the candidate back to the running configuration; investigate before committing, never after.
• Validator failure on commit. A change that violates a constraint is rejected with a specific message, and the candidate is kept so you can fix it. Read the message: it names the node. Re-running commit unchanged produces the same failure.
• A silently doubled multi-value node. No error, a clean commit, and two addresses or two next-hops where you meant one. Only compare and a post-commit show catch this.
• A command from the wrong release. The completion tree does not offer the node the runbook uses. That is not a broken box — it is a runbook written for 1.3 being pasted into 1.5. Check show version and the release the runbook targets before editing the command until it is accepted.

Rollback

To recover a candidate you do not understand:

[edit]
vyos@vyos# compare
[edit]
vyos@vyos# discard
[edit]
vyos@vyos# show | commands

compare first, so you know what you are about to throw away — copy it somewhere if it looks like real work. discard resets the candidate to the running configuration. show | commands then confirms you are looking at the configuration you expected.

If the running configuration itself is wrong, load /config/config.boot replaces the candidate with the last saved configuration, and compare shows exactly what has drifted since the last save.

Production discipline

Cross-course references

The Linux course’s V-Linux-NetConfig covers the underlying configuration management. The OPNsense course’s II-OPNsense-Configure covers the equivalent shell on the firewall side. The Ansible course’s XLII-Ansible-BeyondLinux covers how to drive configure mode from an Ansible playbook.

Quiz