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 exact commands each one runs, how to check that it worked, and how to undo it. Every command a guide shows is a command the product itself shows: the web UI renders set and delete lines before it stages them, so a guide written from the code is also a guide you can follow from the console with no browser at all.

The manual describes screens. These pages describe work. If you are trying to understand what a page does, read the manual — Network, Security, VPN and accounts and Services, monitoring and system — and if you are trying to get something done, start here.

How to read a guide#

Every page follows the same shape.

Two habits are assumed throughout, because they are what the product is built around.

Nothing applies itself. Every editor stages operations into a working set; the Commit Bar is the only thing in the product that commits. A guide that says "stage this" means the change is sitting in the bar until you press Commit.

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. Commit those with commit-confirm: the router reboots back into the previous configuration if you do not confirm 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, 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#

1. Take a backup that is actually complete — before anything else, because the config file on its own is not a backup.
2. Harden a router that faces the internet — ten things in rough order of value.
3. Publish a service: forward, accept, and hairpin — the job that goes wrong most often, and why.
4. Coming from OPNsense — the whole migration, including what does not come across.

Checked against ui/src/components/CommitBar.tsx · agent/staging.go · agent/main.go · docs/ui.md