Everything you can do in the web console can also be done with commands: the same settings, the same pending changes, the same commit. The command line is useful when a page does not open, over a slow connection, for repeating a change on a second firewall, and for scripts.
At a glance:
| Where | How |
|---|---|
| In the web console | The terminal button in the top bar (on every page), or System › Command line for a full page |
| Over SSH | ssh admin@<firewall address> from the management network |
| At the firewall itself | The console menu, item 1, Command line |
You sign in with your Korthveil account, as in the web console. There is no operating-system shell: only the commands in this guide.
| Mode | Prompt | What for | Who |
|---|---|---|---|
| Operational | admin@korthmain> |
Look at the firewall's state, run tests | Every account |
| Configure | admin@korthmain# |
Change settings, then commit them | Superuser and administrator accounts |
The prompt shows which firewall you are on (its name, here korthmain). In a failover pair, check it before you change anything.
configure enters configure mode; exit goes back. Changes you made stay pending until you commit or discard them.
| Key or word | What it does |
|---|---|
? |
Lists what can come next at this point, with a short description |
Tab |
Completes the word; pressed again, lists the choices |
Up / Down |
The previous and next commands |
Ctrl-C |
Clears the line |
Ctrl-D |
Leaves (on an empty line) |
help |
The built-in guides and the commands of this mode |
help start, help configure, help commit, help lists, help examples |
Short built-in guides |
help <command> |
One command's words, for example help show |
On a phone or tablet, the buttons under the terminal do the same: Tab, ?, the arrows, Copy all, Copy commands, Paste, Clear, Font, Larger and Full screen.
sh int is show interfaces."Rack 4".;.
These change nothing. Every account can use them.
| Command | What it shows or does |
|---|---|
show system |
Product, version, hostname, operating system, kernel, uptime, CPU, load, memory, time |
show version |
The Korthveil version only |
show interfaces |
Every port: link, addresses, traffic |
show interfaces <port> |
One port in detail, for example show interfaces enp1s0 |
show routes |
The routing table; show routes ipv4 or show routes ipv6 for one family |
show sessions |
Connections through and to the firewall (50 by default; limit 1–1000) |
show sessions address 192.168.2.50 |
Only connections to or from that address; also port 443, protocol udp, limit 200 |
show services |
The core services and whether they run |
show modules |
The add-ins: on or off, and their health |
show log |
The system log, newest last (50 lines); lines 200 (1–1000), unit rampartd, match dhcp narrow it. match searches the last 5,000 entries |
show revisions |
The commit history: number, time, who, from where, comment; count 50 for more (1–500) |
show configuration |
The running (committed) settings; add a path for part of them, for example show configuration system |
show user |
The account you are signed in with, and its role |
ping <address or name> |
Sends 4 echo requests; count 10 (1–10), ipv4 or ipv6, interface enp2s0 |
traceroute <address or name> |
The path to a host, hop by hop; ipv4, ipv6, interface |
lookup <name> |
Resolves a name with the firewall's own DNS; ipv4 (A only) or ipv6 (AAAA only) |
test-port <address> <port> |
Tries a TCP connection, for example test-port 192.168.2.10 443 |
show isolated |
Devices without internet now (Isolate), with the time left, who and why |
show backup-internet |
The backup internet connection (a phone plugged in by USB): standby or in use for IPv4 and IPv6, since when, why, and the phones plugged in now (with what to do on a phone that does not share its connection yet) |
show dns-forwarder |
The DNS forwarder (dnsmasq): off (and whether the DNS resolver answers instead), or running with its upstream servers, the addresses it listens on, how many DHCP client names it answers, and its cache and upstream counters |
ask <question> |
Asks the AI assistant about this firewall (add-in); ask new … starts a new conversation |
configure |
Enters configure mode |
exit or quit |
Leaves the command line |
These two act at once, without a commit, and are written to the audit log. Superuser, administrator and operator accounts can use them:
| Command | What it does |
|---|---|
isolate <MAC or address> |
Takes the device off the internet for 10 minutes. The LAN, the other local networks and the firewall stay reachable. minutes 30 (1–1440) and reason "bedtime" are optional. Isolating it again sets a new end time |
release <MAC> |
Ends an isolation now |
The settings form a tree, the same one the web console edits. Each word goes one level down; the last word is the value.
| Command | What it does |
|---|---|
set <path> <value> |
Sets a value; creates a list entry when the name is new |
set <path> [ v1 v2 ] |
Adds values to a list of values |
set <path to a secret> |
Leave the value out: you are asked for it twice, without it showing on screen |
delete <path> |
Removes a setting, a list entry, or a whole section |
delete <path> <values> |
Removes only those values from a list of values |
show |
The pending settings at this point; show <path> for one part |
show | set |
The same, as set commands you can copy and paste |
edit <path> |
Works below a path; the [edit …] line shows where you are |
up / top |
One level up / back to the top |
compare |
What a commit would change: - removed, + added |
commit check |
Checks the pending changes and changes nothing |
commit |
Applies the pending changes, all or nothing |
commit comment "text" |
The same, with a note in the revision history |
commit confirmed 5 |
Applies them and rolls back after 5 minutes unless you type confirm |
confirm |
Keeps a commit confirmed |
discard |
Throws away all pending changes |
rollback <revision> |
Loads an earlier revision as pending changes; then commit |
run <command> |
Runs an operational command without leaving, for example run show interfaces |
exit |
Back to operational mode; pending changes stay pending |
Named entries (ports, zones, rules, objects) take their name as the next word:
set interfaces enp1s0 ipv4 gateway 192.168.2.1set zones LAN ping truedelete zones guestEntries without a name use their number: set routing static 1 gateway 192.168.10.254. This also works for lists inside add-in settings, for example the DNS resolver's upstream servers: set modules dns-filter settings forward servers 3 address 1.1.1.2. The next free number adds an entry; show … | set prints the numbers to use.
The pending changes are shared with the web console. A change made with set appears in the console's pending changes, and the other way round. Either side can commit it.
Use commit confirmed 5 for anything that could cut off your own access: addresses, gateways, zones, management access, the web console's port. If you lose the connection, the firewall undoes the change by itself after five minutes. When everything still works, type confirm.
A commit that has problems is refused, and nothing changes. Each problem is listed with the setting, what is wrong, and usually a fix or a "did you mean". Errors must be fixed; warnings and info lines are advice and do not stop the commit.
Add | and a filter to any command:
| Filter | What it keeps |
|---|---|
| match TEXT |
Lines containing TEXT (upper and lower case alike) |
| except TEXT |
Lines not containing TEXT |
| count |
Only the number of lines |
| last N |
The last N lines |
| set |
Settings as set commands (after show) |
| json |
Settings as JSON (after show) |
Filters can be chained: show log lines 300 | match dhcp | last 5.
show configuration | set prints commands that rebuild the configuration, without passwords or keys. Paste them into configure mode on another firewall.
| Task | Commands |
|---|---|
| Rename this firewall | configure · set system hostname korthmain · commit |
| A static address on a port | set interfaces enp2s0 ipv4 mode static · set interfaces enp2s0 ipv4 addresses 192.168.2.4/24 · commit confirmed 5 · confirm |
| A gateway on a port | set interfaces enp1s0 ipv4 gateway 192.168.2.1 · commit confirmed 5 · confirm (static ports only; a DHCP port gets its gateway from DHCP) |
| http:// forwards to https:// | set system webUI httpRedirect true · commit |
| DNS servers | set system dns servers [ 9.9.9.9 2620:fe::fe ] · commit |
| A backup upstream DNS provider | set modules dns-filter settings forward servers 3 address 1.1.1.2 · set modules dns-filter settings forward servers 3 tlsName security.cloudflare-dns.com · commit (or Network › DNS resolver › Add upstream) |
| Time zone | set system time timezone America/Chicago · commit |
| Turn an add-in on or off | set modules dhcp enabled true (or false) · commit |
| Remove an empty zone | delete zones MGMT · commit |
| Undo the last change | run show revisions · rollback <the revision before> · commit |
| Throw away what you typed | discard |
| Is the internet reachable? | ping 9.9.9.9 · lookup repo.klokur.com |
| Who is connected to a device? | show sessions address 192.168.2.50 |
| No internet for a device for 30 minutes | isolate 192.168.2.62 minutes 30 reason "homework" · show isolated · release <its MAC> to end early |
| Why did a service stop? | show services · show log unit rampartd lines 100 |
ssh admin@192.168.2.4 'show interfaces'.ssh admin@192.168.2.4 'configure; set system hostname korthmain; commit'.ssh admin@192.168.2.4 < changes.txt, one command per line, # for comments. It stops at the first error.The exit status is 0 when everything worked and 1 when a command failed.
show prints only <secret set> or <secret unset>, and | set leaves them out.| You see | Meaning | What to do |
|---|---|---|
error … addresses and gateway apply only to static mode |
That port gets its address by DHCP | Check show interfaces <port>: you may be on the other firewall of a pair, or on the wrong port |
the configuration has errors |
The commit was refused; nothing changed | Fix the lines marked error, or discard |
Run 'confirm' by 16:35 or the change rolls back |
A commit confirmed is waiting |
Type confirm when everything still works |
Note: there are uncommitted changes |
You left configure mode with pending changes | They stay pending; commit or discard them later |
incomplete command or ambiguous |
A word is missing or too short | Press ? to see what can come next |
limit is a number from 1 to 1000, not "x" (or lines, count, port) |
A number is out of range or not a number | Use a number in the range shown |
"…" is not understood here; usage: … |
A word the command does not know | Follow the usage shown |
no answer from …, no address found for …, port … is not reachable |
The test ran and failed; the lines above say why (for example Network is unreachable for IPv6 without an IPv6 internet connection) |
Check the route, DNS, or the remote device |
| SSH refuses the connection | SSH is off, or you are not on the management network | Turn it on under System › Command line › Access, or use the terminal in the web console |