medium riskservice affecting~120 min

Runbook: Deploy a New VyOS Router

1 · Prerequisites

Confirm every item is in place before any state change.

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

· Console access exists and has been tested before the install starts: serial at 115200 8N1 with no flow control, an IPMI virtual console, or the hypervisor console. Everything below can remove network access to this box; the console is the only thing that cannot be removed by a commit.
· The ISO is verified against the signature published by the project. Since 1.4.3 VyOS signs releases with minisign rather than GPG, so an older GPG-based procedure will not verify a current image — follow the current installation documentation.
· The target disk is identified positively, not assumed: lsblk from the live session, matched against the serial number or the slot. install image destroys what is on the disk it is given, and on a multi-disk chassis the default is not necessarily the disk you mean.
· The firmware mode is known — ls /sys/firmware/efi from the live session distinguishes UEFI from legacy BIOS. A mismatch between firmware mode and partition scheme installs cleanly and then fails to boot.
· The management plan is decided before the first commit: which interface, which address, whether it sits in a management VRF, and whether the router is reachable from the operator network without traversing the routed interfaces it is about to serve.
· The addressing, hostname, NTP sources and syslog destination are written down in advance. A router configured from memory is a router nobody else can rebuild.
· At least one operator SSH public key is available to paste at the console. Removing password authentication without a working key in place is the commonest self-inflicted lockout in this procedure.
· It is agreed and recorded whether this router is being cabled into a live estate at the end of this runbook or staged offline. That decision changes the risk of every step after the hardening block.
· A second person is named for the handover and is available. A router only one person can reach is a single point of failure that no amount of hardware redundancy fixes.
· The router is not connected to any routed or Internet-facing interface yet. The default image ships with a documented default credential; the window between first boot and hardening is the entire exposure of this procedure and it belongs off the network.

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1Connect the console and confirm a login prompt appears. Do not proceed on an assumption about the console — the whole procedure depends on it and this is the cheapest moment to find out it is wrong.
2Boot the verified ISO. Log in to the live session with the documented default credential and confirm the target disk with lsblk and the firmware mode with ls /sys/firmware/efi.
3Run install image. Answer the prompts, and use --no-default-configuration for any production box so the new image does not inherit the live session state — most importantly a DHCP client on an interface that will have no DHCP server where this router is going.
4Reboot, remove the boot media, and confirm the box comes up on its own with show version and show system image. A router that boots only with the USB stick in it is not installed.
5Change the default credential before anything else: configure, set system login user vyos authentication plaintext-password, commit, save. This is the first commit on the box and it is the one that stops mattering the moment the box is cabled.
6Install the operator key and give the box an identity: set system login user vyos authentication public-keys operator key ... and its matching type, then set system host-name, set system time-zone, set system name-server. Commit and save.
7Prove key authentication works over the console-configured management address before removing password authentication. Log in with the key from another window, in a session you have not yet used.
8Only then harden SSH: set service ssh disable-password-authentication, set service ssh listen-address bound to the management address, and set service ssh vrf if a management VRF is in use. Apply with commit-confirm 5, prove a fresh key-based login still works, then confirm and save.
9Give the box a working sense of time and a place to send its logs, before it has anything interesting to say: set service ntp server, set system syslog remote 198.51.100.50 facility all level info, plus the local time-zone already set. Commit and save.
10Verify the clock has actually converged and syslog is arriving at the collector. Both are claims about a remote system; check the remote system.
11Configure the interfaces and addressing for the role this router will play, with every interface carrying a description that says what is on the other end of the cable.
12Build the input-chain firewall as an explicit accept list — management access from the operator prefix, ICMP, established and related — and set default-action drop in the same commit. A default-deny committed before its accept rules is a lockout with a timer on it.
13Apply the firewall with commit-confirm 5 and immediately open a new session from the operator network. Do not confirm from the session that was already open; an existing connection may survive on state while every new connection is refused.
14Add source NAT and forward-chain rules only if this router provides them, and only after the input chain is confirmed working. set nat source rule 100 outbound-interface name eth0, ... source address, ... translation address masquerade.
15save. Then reboot the router deliberately, from the console, and confirm it comes back with the configuration intact and reachable. An unsaved commit survives until exactly this moment.
16Capture the post-deployment baseline: show configuration commands | strip-private into the configuration repository, plus show version, show system image, show interfaces, show ip route, show firewall, show ssh fingerprints.
17Cable the router into the estate only after the reboot test has passed. Bring up one link at a time and confirm each before the next.
18Hand over: the second named operator logs in with their own key, from their own machine, and confirms they can reach the console path as well. The deployment is not finished until somebody who did not build it can recover it.

4 · Verification

Confirm the procedure actually fixed the problem.

✓show version reports the intended release, and show system image shows the installed image as the default boot entry. A router that boots something other than what you installed will surprise you at the next power cut, not now.
✓The default credential no longer works. Test it — do not assume the commit that changed it did what you meant.
✓Key-based SSH from the operator network succeeds in a new session, opened after the hardening commit was confirmed.
✓Password authentication is refused: show configuration commands | match ssh includes disable-password-authentication, and an attempt with a password fails.
✓show ssh fingerprints output is recorded in the build document, so the next person to connect can tell this router from an impostor.
✓The clock is correct and synchronised, verified against the NTP source rather than by looking at it once.
✓Log lines from this hostname are visible at the syslog collector. Checked at the collector, not at the router.
✓show firewall ipv4 input filter shows the accept rules with non-zero packet counts and a default-action drop. Counters at zero on the management rule mean the traffic is arriving somewhere else.
✓Every interface has a description naming what is on the other end, and show interfaces matches the cabling record.
✓The router has been rebooted since the final save and came back complete and reachable. This is the only test that distinguishes a committed configuration from a persisted one.
✓The configuration is committed to the configuration repository off-box, and the second named operator has independently logged in.

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶Inside a commit-confirm window with the router gone silent: wait for the timer. It reverts on its own, and waiting is faster and safer than reaching for the console.
↶With a session still open: rollback 1, compare to read what will be undone, then commit. Nothing reverts until the commit.
↶Locked out over the network with the console alive: log in at the console, configure, rollback 1, compare, commit, save. The console is unaffected by the firewall and by the SSH service — which is why it is the first pre-check and not an afterthought.
↶Locked out with no console: there is no remote recovery path on a router that refuses connections. The remaining options are a site visit or out-of-band power control with a boot into the alternate image. Plan for this before the firewall commit, not after it.
↶A configuration mistake made before the first save is reverted by rebooting: the router boots /config/config.boot, which is the last saved state. This is a genuinely useful property early in a deployment and a trap later on, when it silently discards work you thought was applied.
↶POINT OF NO RETURN: install image writes to the target disk and whatever was on it is gone. There is no rollback for a wrong disk, only a restore from whatever backup existed before you started. Confirm the disk twice; it is thirty seconds against an unbounded loss.
↶POINT OF NO RETURN: a key that has been on this box is on this box. If the router is being rebuilt because it may have been exposed, rotate the operator keys and any shared secrets rather than reinstating them from the old configuration.

6 · Escalation

When the runbook isn't enough, contact:

· Escalate to the data-centre or remote-hands team the moment the console does not respond as expected. Stop the deployment there; every step after this point assumes a recovery path that you have just discovered you do not have.
· Escalate to whoever owns the hardware before running install image on a disk whose contents you cannot positively account for. "It was probably blank" is not an account.
· Escalate to security before this router is cabled into a live estate if the hardening block could not be completed — default credential still active, password authentication still enabled, or no firewall. A partially hardened router on a production network is an incident waiting for a scanner to find it.
· Escalate to network engineering before cabling if this router will carry a prefix, an AS, or a VRRP identity that already exists elsewhere in the estate. Duplicates are found by the routing protocol, at the worst possible moment.
· Escalate to the monitoring team when the router is deployed but not yet visible to monitoring. A router nobody is watching is worse than one that does not exist, because it will be relied on.
· Escalate if the handover cannot be completed because no second operator can reach the box. That is a deployment defect, not a scheduling inconvenience, and it should block sign-off.

Deploying a router is not a hard procedure. It is a procedure with an ordering constraint that most of its failures come from ignoring.

A fresh VyOS image ships with a documented default credential, SSH listening, and no firewall. That is the correct default for something you have just installed at a console, and it is an unacceptable state for something reachable from a network. The entire risk of this runbook lives in the interval between those two facts, and the way to manage it is to do all the work off the network and cable the box afterwards.

The second ordering constraint is subtler and produces the more common outage: every control you are about to add — key-only authentication, a bound listen address, a default-deny firewall — removes a way of reaching the router. Add them in an order where each one is proved before the next one closes the door behind it.

When this runbook applies

A new bare-metal router, or a new VM built from the ISO, going into a production estate.
A rebuild of an existing router where the disk is being reinstalled rather than the configuration restored.

When it does not

Restoring a router from backup. That is a different procedure with a different verification: the configuration is known-good and the question is whether it landed intact. Use the restore runbook.
Cloud images. The bootstrap is cloud-init and the credential and key handling happen before first boot, which removes the console step that shapes this whole runbook.
In-place upgrades. The dual-image model handles those and there is no install to do.

Blast radius

Narrow at the start, wide at the end — and the transition is a moment you choose, so choose it deliberately.

While the box is off the network, the only thing at risk is the target disk, and install image is unambiguously destructive to it. Once the box is cabled, it is a participant in the routing estate: a duplicate router ID, an unexpected route advertisement, or an unintended DHCP server reaches well beyond this router.

Step 0: the console is the whole safety net

Serial is 115200 8N1 with no flow control. A terminal set to a different baud rate produces garbage, and garbage on a console at 02:00 reads exactly like a dead box — which is how a working console gets written off as a failed one during an incident.

Test it now, before the install: log in over the console, run a command, log out. Where the console is an IPMI or hypervisor virtual console, test that too, from the network path you would actually use in an outage rather than from the one that happens to be open.

Every later step in this runbook can remove network access to the router. None of them can remove the console. That asymmetry is the reason the console test is step zero rather than a line in a checklist somewhere, and it is why “we will sort the console out afterwards” is the decision that turns a lockout into a site visit.

If the console does not work, stop. Do not proceed on the theory that you will not need it.

Step 1: install, onto a disk you have positively identified

Destructiveconfirm the target before you commit to it

lsblk
ls /sys/firmware/efi

install image --no-default-configuration

Two things about that command are worth the sentence they cost.

lsblk is not a formality on a chassis with more than one disk. The installer’s default target is not necessarily the disk you mean, and install image gives you exactly one chance to notice.

--no-default-configuration stops the new image inheriting the live session’s state — most consequentially a DHCP client on an interface that will have no DHCP server wherever this router is going. A box that boots looking for an address it will never receive is a box you reach only by console, and the reason will not be obvious.

After the reboot, confirm the box stands on its own:

Read-only / Safeit is installed when it boots without the media

show version
show system image

show system image also tells you which entry boots next — worth reading now rather than discovering after an unplanned power cut. The alternate slot is the rollback path for future upgrades, and set system image default-boot is how you steer it.

Step 2: identity and credentials, before anything is reachable

Configuration changefirst commit on the box

configure
set system login user vyos authentication plaintext-password
set system login user vyos authentication public-keys operator key 'ssh-ed25519 AAAA...'
set system login user vyos authentication public-keys operator type ssh-ed25519

set system host-name edge-01
set system time-zone Europe/London
set system name-server 198.51.100.53

commit
save

Hostname, time-zone and resolver look like cosmetics and are not. The hostname is how this router identifies itself in every syslog line and every monitoring record, and a fleet of boxes called vyos is a fleet whose logs cannot be correlated. The time-zone is the difference between a log you can line up against an incident timeline and one you cannot.

Change the password before anything else, because that is the credential that is published on the project’s own website.

Step 3: prove the key before you remove the password

This is the step people reverse, and reversing it is the classic self-inflicted lockout: password authentication is disabled in the same commit that installs a key nobody has tested.

Service impact possiblekey first, then close the other door

# From another window, using the key, in a session you have not used:
#   ssh -i ~/.ssh/id_ed25519 vyos@198.51.100.10
# Only when that works:

set service ssh disable-password-authentication
set service ssh listen-address 198.51.100.10

commit-confirm 5

# Prove a NEW key-based login still works, then:
confirm
save

Where a management VRF is in use, set service ssh vrf binds the daemon into it, which keeps SSH unreachable from the routed interfaces altogether. That is a stronger control than any firewall rule, because it is not a rule that can be evaluated in the wrong order.

Step 4: time and logs, before there is anything to investigate

Configuration changethe box needs to be able to explain itself

set service ntp server 198.51.100.51
set service ntp server 198.51.100.52

set system syslog remote 198.51.100.50 facility all level info
set system syslog remote 198.51.100.50 protocol udp

commit
save

Both of these are claims about a remote system, so verify them at the remote system. An NTP server configured and not reachable is a router with a drifting clock and a configuration that says otherwise; a syslog destination that is not receiving is a router whose evidence exists only locally and disappears with the disk.

Do this before the routing configuration, not after. The first incident on a new router is disproportionately likely to happen during its first week, and a router with no usable timestamps and no exported logs is one you will be debugging from memory.

Step 5: the firewall, in one commit, with a timer

Service impact possibleaccept rules and default-deny together

set firewall ipv4 input filter rule 10 action accept
set firewall ipv4 input filter rule 10 state established
set firewall ipv4 input filter rule 11 action accept
set firewall ipv4 input filter rule 11 state related
set firewall ipv4 input filter rule 15 action drop
set firewall ipv4 input filter rule 15 state invalid

set firewall ipv4 input filter rule 20 action accept
set firewall ipv4 input filter rule 20 protocol tcp
set firewall ipv4 input filter rule 20 destination port 22
set firewall ipv4 input filter rule 20 source address 198.51.100.0/24

set firewall ipv4 input filter rule 30 action accept
set firewall ipv4 input filter rule 30 protocol icmp

set firewall ipv4 input filter default-action drop

compare
commit-confirm 5

The accept rules and the default-action drop belong in the same commit. Committing default-deny first and the accept rules second is a lockout with a gap in the middle, and the gap is long enough to matter because you will be reading the diff during it.

Then verify from a new connection, and read the counters rather than the configuration:

Read-only / Safecounters, not intentions

run show firewall ipv4 input filter
run show firewall statistics

A management rule sitting at zero packets while the default-action counter climbs means your traffic is being matched by something else, and the rule you believe is protecting the box is not the rule in effect.

Step 6: the reboot test, which is the actual sign-off

Cable the router into the estate only after that test passes, one link at a time, confirming each before the next. Then complete the handover: a second operator, their own key, their own machine, and the console path as well. A router only one person can reach has no redundancy that matters.

Common patterns

Symptom	Likely cause	Where to look
Box boots only with the install media present	Installed to the wrong disk, or firmware mode mismatch	`show system image`, boot order
Unreachable after the SSH hardening commit	Key never tested, or listen-address wrong	Console; let `commit-confirm` expire
Unreachable after the firewall commit	Default-deny with no accept rule for management	Console; `show firewall ipv4 input filter`
Old session works, new connections refused	Established state carrying the old session	Always test with a new connection
Configuration gone after a power cut	Committed but never saved	`/config/config.boot`
Interface has no address on first boot	Live-session DHCP client inherited by the image	Reinstall with `--no-default-configuration`
Logs at the collector show `vyos` for several routers	Hostname never set	`set system host-name`
Certificate and log timestamps disagree with reality	NTP configured but not reaching a source	The NTP source, not the router
Router deployed but invisible to monitoring	Handover incomplete	The monitoring system

Why this matters

The reason deployment deserves a runbook at all is that it is the one procedure where every mistake is cheap at the time and expensive later. Nothing is depending on this router yet. The wrong disk, the untested console, the unsaved configuration, the hostname left at the default — none of them produce a symptom on the day. They produce a symptom during the first real incident, when the router is load-bearing and the person holding it is not the person who built it.

That is also why the ordering in this runbook is worth more than any individual command in it. Console before network. Identity before service. Key before password removal. Accept rules in the same commit as the deny. Reboot before cable. Each of those is a place where doing the two halves in the wrong order still ends in a working router most of the time, and ends in a site visit the rest of the time.

The last step is the one most likely to be skipped and the one worth defending hardest. A deployment is not finished when the router routes. It is finished when somebody who did not build it can log in, find the configuration in the repository, reach the console, and recover the box without you.