Task guides#
A guide is one job. It says what you will end up with, what you need before you start, the steps with the screen and the fields each one fills in, how to check that it worked, and how to undo it. Where a guide shows commands, they are the ones Advanced mode shows for the same change, so it can be followed from the console instead.
The manual describes screens; these pages describe work. To understand what a page does, read the manual — Network, Security, VPN and accounts and Services, monitoring and system.
How to read a guide#
Every page follows the same shape.
| Section | What it is for |
|---|---|
| The opening paragraph | What you will have when you finish. |
| Before you start | Role, licence, interfaces, anything that must already exist. |
| The steps | Each one names the screen, then the fields to fill in and what the change adds. |
| Check it worked | A command or a page that confirms the result. |
| Undoing it | The reverse operations, or the revision to roll back to. |
| See also | The manual page for the screen, the concept behind it, and the reference. |
Two things hold throughout.
Nothing applies itself. Every editor adds its change to the pending changes; the Commit Bar is the only thing in the product that applies them. A step that ends with Save or Add leaves the change waiting in the bar, listed as a sentence, until you press Apply changes.
A dangerous change is armed, not hoped for. Anything that touches uplink addressing, firewall rules, NAT, SSH or the API can cut you off from the router you are editing. Apply those with auto-revert: the router restarts with its saved configuration if you do not keep the changes inside the window, which turns a lockout into a two-minute wait.
The sections#
Network#
Interfaces, addressing and the paths packets take: VLANs, bridges, bonds, PPPoE, tunnels, static routes, a second uplink with failover, load balancing, policy routing, per-uplink NAT, shaping, BGP, OSPF, VRRP, and what IPv6 does and does not do here.
Security#
Publishing a service without opening more than you meant to, a default-drop ruleset, groups instead of literals, the Suricata IDS, inline IPS, certificates, and the hardening pass to do before a box faces the internet.
VPN#
WireGuard for a laptop and between two sites, IPsec to a third-party device, an OpenVPN server for remote devices, and Tailscale as a subnet router.
Services and apps#
DHCP reservations and relay, router advertisements, DNS forwarding and records, dynamic DNS, mDNS across VLANs, and the whole app lifecycle: install, update, restart, uninstall.
Monitoring#
Prometheus, remote syslog, SNMP, NetFlow export, LLDP, and finding what is using the link right now.
Operations#
Backups that are actually complete, restores, rebuilding onto new hardware, rolling back, upgrading the image and the agent alone, recovering from a lockout, SSH, the console, scheduled tasks, sysctl and time.
Accounts and access#
Operator accounts, two-factor, API tokens, single sign-on, and the router's own console accounts.
Automation#
Your first API call, staging and committing from a script, config as code with a desired-state file, the reconcile loop, drift alerts, and pointing one agent at several routers.
Migration#
Coming from OPNsense: turning a config.xml into VyOS commands, reading the report
before you boot anything, building a seed that installs the replacement, and checking a
running router against the configuration it should have.
Troubleshooting#
A symptom-to-cause table and the order to work through it when something is wrong.
The guides most people need first#
- Take a backup that is actually complete — before anything else, because the config file on its own is not a backup.
- Harden a router that faces the internet — ten things in rough order of value.
- Publish a service: forward, accept, and hairpin — the job that goes wrong most often, and why.
- Coming from OPNsense — the whole migration, including what does not come across.