Terminal reference (NCL)
The grammar
The language of the terminal written out in full: the grammar, the tolerances, the principles.
This page is for whoever wants the whole language on one page: the rules it is built on, the grammar, and the words it accepts besides the ones the grammar names. The other pages of this section explain each command; this one explains how a line is read. The specification of the language, which the app follows, is the file docs/terminal-commands.md of the repository: it carries the version of the language, and its sessions are run by the same tests as the examples of this reference.
Principles
- Verb first. A line starts with what to do:
ping,trace,show,set,add,connect,use. - Prepositions are optional noise where nothing is ambiguous:
show config of Switch-1andshow config Switch-1are the same line. - Role keywords split names.
from,to,of,onandviasay what each part of the line is, so that a device name of several words needs no quotes:ping PC Sales 1 from Core Switch HQ. - Context.
use <device>makes a device the one every command is about: the prompt takes its name, andfromandonare implied.exitleaves (Help and the session). - Vendor-neutral words.
show neighbors, not the name of a protocol;interface 3 down, notno shutdown;add route, notip route. An interface is one word for a port and a network card, andinterfacesis the standard table of both. - Tolerances are part of the language. Optional prepositions, dropped articles, the words
deviceandhost, double-quoted names, an address in place of a device, and a suggestion when a verb or a device is not found (below). - Every refusal says what was expected. A command that cannot be run answers with the form it should have had, or with the reason in the terms of the network (
PC-1 is a PC: routes belong on routers and firewalls), and changes nothing.
The grammar
The grammar is written in a notation close to EBNF. A word in quotes is typed as it is, [ … ] is optional, { … } is repeated, | is a choice, and ( … ) groups. What stands between (* … *) is a comment.
command ::= diagnostic | inspection | configuration | session
diagnostic ::= "ping" target ["from" device]
| "trace" target ["from" device] ["as" service]
| ("browse" | "mail" | "download") target ["from" device]
| "resolve" name ["from" device]
service ::= "ping" | "web" | "email" | "dns"
inspection ::= "show" show-target [["of"] device]
show-target ::= "devices" | "interfaces" | "ports" | "vlans"
| "connections" | "config" | "neighbors" | "ip"
| "routes" | "rules" | "nat" | "dhcp" | "dns"
configuration ::= set-cmd | vlan-cmd | link-cmd | iface-cmd | route-cmd | rule-cmd
| forward-cmd | record-cmd
set-cmd ::= "set" ("ip" | "gateway" | "subnet" | "name")
["of"] device ["to"] value
vlan-cmd ::= "add" "vlan" number ["to"] device
| "remove" "vlan" number "from" device
link-cmd ::= "connect" device ["to"] device
| "disconnect" device ["from"] device
iface-cmd ::= "interface" iface-id iface-setting [["on"] device]
iface-id ::= number | nic-name (* port 3, eth0 *)
iface-setting ::= "up" | "down"
| "ip" (ipv4 ["/" prefix] | "none")
| "gateway" (ipv4 | "none") (* network cards *)
| "access" vlan (* switch ports *)
| "trunk" (vlan {"," vlan} | "all") (* switch ports *)
| "default" (* switch ports: no VLAN of its own *)
| "zone" ("trust" | "untrust" | "dmz" | "none") (* firewall ports *)
| "nat" ["on" | "off" | "none"] (* router/firewall ports *)
| "dhcp" ["on" | "off" | "none"] (* network cards *)
| ["dhcp"] "pool" (ipv4 ["to"] ipv4 ["gateway" ipv4] ["dns" ipv4] | "none")
(* router/firewall ports, server cards *)
| "dns" (ipv4 | "none") (* network cards *)
route-cmd ::= "add" ["backup"] "route" network "via" next-hop [["on"] device]
| "remove" "route" network ["via" next-hop] [("from" | "on") device]
network ::= ipv4 "/" prefix | "default"
next-hop ::= ipv4 | device
rule-cmd ::= "add" "rule" [position] ("allow" | "deny") [service | "any"]
"from" endpoint "to" endpoint ["on" device]
| "remove" "rule" position [("from" | "on") device]
endpoint ::= "any" | "trust" | "untrust" | "dmz" | ipv4 | network | device
forward-cmd ::= "add" "forward" [service | "any"] "from" ["interface"] number
"to" (ipv4 | device) ["on" device]
| "remove" "forward" position [("from" | "on") device]
record-cmd ::= "add" "record" name ["to"] (ipv4 | device) ["on" device]
| "remove" "record" (position | name) [("from" | "on") device]
session ::= "use" device | "exit" | "clear" | "help" [topic]
target ::= device | ipv4 | name
device ::= word { word } | '"' text '"' (* multi-word, quotable *)
name ::= label "." label { "." label } (* www.company.example *)In a device context (use …) the ["from" device], [["of"] device] and [["on"] device] parts default to the context device. show dhcp and show dns with no device, outside a context, are about the whole drawing. Where a command ends with something that may be a device of several words (the destination of a rule, the address of a forward or of a record), on is what parts it from the device the command is for, and cannot be left out: ["on" device].
The grammar names the form of each command. It leaves out, to stay short, the words that mean the same as one it names: they are in the table of aliases.
Tokens, names and quotes
- A line is cut into words at spaces. Case does not matter for the words of the language (
PING,Show), nor for the name of a device:web-erpfinds Web-ERP. - A device is a run of words. Everything between two role keywords is one device name, joined with single spaces:
ping Core Switch HQ from PC Sales 1has two devices of three and three words. The keywords arefrom,to,of,onandvia, and, last in atrace,as. - Double quotes keep a name whole. A word in quotes is never a keyword and is never dropped:
ping "Gateway to HQ" from "PC-1". Quote a name that has a keyword inside it. A quote that is not closed runs to the end of the line, and a pair of quotes with nothing between is ignored. - A name matches a device exactly (spaces counted once, case ignored), or an address does: the address of the device, or of any of its ports or cards that is enabled. An address stands for the device, and where a question has a target it is the address aimed at (Targets). A name that does not match is never guessed: it is refused, with a suggestion.
- Two devices with one name (a drawing made before the windows and the terminal refused it) are never told apart by guessing: a command that names them is refused with
2 devices are called "PC-1": rename one of them …, andusedoes not enter either. An address of one of them still names that one. - A host name is a name with at least one dot,
www.company.example: where a question has a target, and a device or an address does not match, it is looked up in a DNS server first (Asking). It is also the name of a record (DHCP and DNS). A word with no dot is not a host name. - A number is one or more digits: a port, a VLAN from 1 to 4094, a position in a list. A network is an address and a prefix,
192.168.30.0/24, ordefault. - Values are checked before they are written: an address that is not an address, a network that is not a network, a VLAN out of 1–4094 are refused with the form that was expected. A mask is a dotted mask,
255.255.255.0, or a prefix,/24.
Tolerances
What the terminal accepts besides the form of the grammar. It is part of the language, and every item is one line to read in the parser:
- Optional prepositions.
of,on,toandfrommay be left out where the grammar puts them in brackets, and are skipped when they stand at the head of a name:show ip of PC-1,show ip on PC-1,show ip PC-1. - Articles.
theandaat the head of a name are dropped:ping the Web-01 from the PC-1. - The words
deviceandhost, at the head of a name, are dropped too:use device SW-Office,ping Web-01 from host PC-1. A name that has them inside (Meeting Room Host), or in quotes, is kept as it is. - An address where a device is expected, in every command. A typed address is the address aimed at.
- A suggestion when something is not found. An unknown verb is answered with the closest verb (
pinng→ping); an unknown word aftershow, with the closest one (did you mean "show devices"?); a device that is not found, with the closest name, when it is close enough to be a slip (did you mean "Web-01"?). - A line that is empty is skipped: the terminal prints a new prompt.
A line that is refused is answered in three parts: unknown command: "<the line>", then what was expected or the closest word, then type "help" for the command list. A device that is not found is answered device not found: "<name>". Anything else is a reason, in the words of the network.
The aliases
| Command | Also written |
|---|---|
show devices |
ls, list |
show <what> |
sh <what>. ls <what> and list <what> too |
show ip |
ipconfig, ifconfig |
trace |
traceroute, tracert |
browse |
web, curl |
mail |
email |
download |
wget |
resolve |
lookup, nslookup |
remove |
delete |
exit |
quit |
clear |
cls |
help |
? |
interface <n> up, interface <n> down |
enable port <n>, disable port <n> |
ip in interface <id> ip |
address |
interface <id> pool … |
interface <id> dhcp pool …, and interface <id> dhcp server … |
none in ip, gateway, zone, dns, pool |
clear. For pool also off |
off in nat and dhcp |
none, no, disable |
gateway in a pool |
gw |
allow, deny |
permit, block |
a service any |
all |
a service ping |
icmp |
a service web |
http, https |
a service email |
mail, smtp |
interface in add forward … from interface <n> |
port, or nothing |
<first> to <last> in a pool |
<first>-<last>, or <first> <last> |
The versions of the language
The language has a version, shown by help in its first line, and described in the overview. Until version 1.0 the forms in the grammar are stable, but aliases and the wording of the answers may still change between two minor versions: the examples of this reference are run against the app at every change, and fail when an answer is not the one printed here.
See also
- Overview and conventions: how the pages of this reference write a command.
- Help and the session:
help,use,exit,clear. - The specification on GitHub.