Working from the console#

You will end up able to do everything from a keyboard attached to the router that you would otherwise do from a browser — and several things you cannot do any other way. The console is the recovery path for a lockout, the only shell on a freshly installed router, and where a router with no internet access gets upgraded.

Before you start#

• A monitor and keyboard, a serial connection, or a VM console.
• The console password chosen during the install. It is the same for both console accounts.

What the banner tells you#

Every start writes /etc/issue, printed above the login prompt:

  Wheelhouse 0.9.1 -- edge
  ==========================================================================
  Web UI:    https://192.0.2.1:8443  (eth1)
  Sign in:   with your Wheelhouse admin account
  Console:   wheelhouse, with the password chosen at install
             vyos is kept for recovery
  --------------------------------------------------------------------------
  Built on VyOS 1.5-rolling-202608220006
  Licences and corresponding source: /usr/share/doc/wheelhouse
  ==========================================================================

One Web UI: line per addressed interface, IPv4 first, up to five before it says how many more there are. When a management address is set under Admin → Agent settings, the banner shows that one address instead, and says not on any interface when the router no longer has it. Read the banner for three things:

• "waiting for an address on any interface" — the machine has no address. Plug something in, or set one from the console.
• An Agent: line — the agent is not running, and the line names the command that shows its log.
• Sign in: admin / <some string> — the agent created a fresh account and that string is a one-time password, written to /config/wheelhouse/initial-password. Sign in with it and change it immediately; the file is deleted the moment that account's password changes.

The banner is redrawn from a timer, so it follows the machine: an address that arrives after start-up appears without a restart.

The two kinds of account, and which one you want#

Router accounts are listed, and their passwords and SSH keys changed, under System → Settings → Router accounts; Wheelhouse accounts under Admin → Users. Neither can be used in the other's place, and changing a web interface password does not change a console password, or the other way round.

On the live image, before an install, the console account is vyos with the password vyos, and the banner says so. A router installed by an older Wheelhouse has only vyos; the banner names whichever it finds.

Step 1 — Get a configuration session#

configure

The prompt changes. From here set and delete make the same changes the web interface's editors make: the editors add these lines to the pending changes, and the web interface shows them in Advanced mode.

set interfaces ethernet eth0 address 192.0.2.1/24
compare
commit
save

Four commands, before anything else:

commit without save is a change that disappears at the next restart. The web interface works the same way: Apply changes changes the running configuration, and Save configuration in the System page header writes it for the next start.

Step 2 — Commit something risky safely#

commit-confirm 2

Two minutes to run confirm. If you do not, the router restarts and starts with its saved configuration: the changes are gone, and so is any change committed earlier and not saved. Use it for anything that touches uplink addressing, the firewall, NAT, SSH or the API — which is to say, anything that can end the session you are typing in, even at a physical console, because a firewall rule can cut the agent off as readily as it can cut you off.

It is the same mechanism as Apply with auto-revert and Keep changes in the web interface.

What the console can do that the network cannot#

• Recover a lockout, with a tool built for it. wheelhouse-rescue resets a web interface password, removes an account's second factor, runs first boot again, restores a configuration from a file, forgets a management address that shut you out, explains why the agent will not start, and resets the router's Wheelhouse data to how it left the factory. It refuses to run anywhere but a real console — including inside SSH, whatever the terminal claims — because physical presence is what stands in for the password it is resetting. Every action goes into the audit log as rescue. Locked out of the UI.
• Install an image from a local file, which the web interface cannot: Add an image from a URL on the System page takes an http or https address only, so a router with no internet access is upgraded here or not at all.
  bash

  add system image /path/to/wheelhouse-0.9.2-amd64.iso

  Upgrade the whole system.

• Remove a nat static rule. Wheelhouse does not write or remove that node, because committing it through this platform build's HTTP API has been seen to stop the API process; its own 1:1 NAT is a rule pair the Commit Bar applies. A nat static rule made here is listed on the NAT page as read-only, and removed here too. 1:1 NAT.
• Run a packet capture when the agent is not on the router. Diagnostics → Capture runs one on a normal install. An agent running elsewhere cannot, and the page says so; in Advanced mode it also shows the monitor traffic command to run here.
• Collect a support bundle when the web interface will not answer. wheelhouse-support produces the same bundle as Download support bundle on the Support page, adds the journal from before the agent restarted, and writes one redacted file into the current directory, or into a directory you name. In Advanced mode the Support page shows these commands in its From the router’s console panel. Support.
• Read and edit the agent's store, with the agent stopped — though wheelhouse-rescue password and wheelhouse-rescue totp do the two things people actually edit it for, without the risk of a hand-edit.

Step 3 — Run an operational command over SSH#

show configuration commands and its relatives are shell functions of the operational CLI, not programs, so a non-interactive SSH session needs the wrapper:

ssh wheelhouse@<router> '/opt/vyatta/bin/vyatta-op-cmd-wrapper show configuration commands'

At an interactive console you just type show configuration commands.

Serial consoles#

The installer takes over the first video console (tty1) on a live start. A serial console keeps a normal login prompt, and its banner says so. Log in as vyos and run the installer by hand:

sudo wheelhouse-install

dialog draws in 80 columns; every installer screen and banner is sized for that.

Check it worked#

show version
show interfaces
show configuration commands | wc -l

If show version answers, the router is alive whatever the network thinks.

See also#

• Locked out of the UI
• Turn SSH on, and restrict it
• Upgrade the whole system
• Advanced mode and the router's commands — what the web interface shows in words, and the commands behind a change
• Serial consoles