diff --git a/doc/cli/introduction.md b/doc/cli/introduction.md index 8ed9220e..c87c5a29 100644 --- a/doc/cli/introduction.md +++ b/doc/cli/introduction.md @@ -24,7 +24,7 @@ The system has several datastores (or files): number of ports/interfaces. This file is generated at boot, if it does not exist, i.e., only on first boot or after factory reset. - `startup-config` is created from `factory-config` at boot if it does - not exist. It is loaded as the system configuration on each reboot. + not exist. It is loaded as the system configuration on each boot. - `running-config` is what is actively running on the system. If no changes have been made since the system booted, it is the same as `startup-config`. @@ -35,9 +35,9 @@ The system has several datastores (or files): To save configuration changes made to the `running-config` so the system will use them consecutive reboots, use the `copy` command: - admin@infix-12-34-56:exec> copy running-config startup-config + admin@infix-12-34-56:/> copy running-config startup-config -In configure context the following commands are available: +In *configure context* the following commands are available: | **Command** | **Description** | |-------------------|--------------------------------------------------------| @@ -64,38 +64,43 @@ We inspect the system status to ensure the change took effect. Then we save the changes for the next reboot. ``` -admin@infix-12-34-56:exec> configure -[edit] -admin@infix-12-34-56:configure> edit interfaces interface eth0 -[edit interfaces interface eth0] -admin@infix-12-34-56:configure> set ipv4 - address autoconf bind-ni-name enabled forwarding mtu neighbor -[edit interfaces interface eth0] -admin@infix-12-34-56:configure> set ipv4 address 192.168.2.200 prefix-length 24 -[edit interfaces interface eth0] -admin@infix-12-34-56:configure> show +admin@infix-12-34-56:/> configure +admin@infix-12-34-56:/config/> edit interfaces interface eth0 +admin@infix-12-34-56:/config/interfaces/interface/eth0/> set ipv4 + address autoconf bind-ni-name enabled + forwarding mtu neighbor +admin@infix-12-34-56:/config/interfaces/interface/eth0/> set ipv4 address 192.168.2.200 prefix-length 24 +admin@infix-12-34-56:/config/interfaces/interface/eth0/> show type ethernetCsmacd; ipv4 address 192.168.2.200 prefix-length 24; ipv6 enabled true; -[edit interfaces interface eth0] -admin@infix-12-34-56:configure> diff -interfaces interface eth0+ ipv4+ address 192.168.2.200+ prefix-length 24; -[edit interfaces interface eth0] -admin@infix-12-34-56:configure> leave -admin@infix-12-34-56:exec> show interfaces brief +admin@infix-12-34-56:/config/interfaces/interface/eth0/> diff +interfaces { + interface eth0 { ++ ipv4 { ++ address 192.168.2.200 { ++ prefix-length 24; ++ } ++ } + } +} +admin@infix-12-34-56:/config/interfaces/interface/eth0/> leave +admin@infix-12-34-56:/> show interfaces brief lo UNKNOWN 00:00:00:00:00:00 eth0 UP 52:54:00:12:34:56 admin@infix-12-34-56:exec> show ip brief lo UNKNOWN 127.0.0.1/8 ::1/128 eth0 UP 192.168.2.200/24 fe80::5054:ff:fe12:3456/64 -admin@infix-12-34-56:exec> copy running-config startup-config +admin@infix-12-34-56:/> copy running-config startup-config ``` One of the ideas behind a separate running and startup configuration is to be able to verify a configuration change. In case of an inadvertent change that, e.g., breaks networking, it is trivial to revert back by: - admin@infix-12-34-56:exec> copy startup-config running-config +``` +admin@infix-12-34-56:/> copy startup-config running-config +``` Or restarting the device. diff --git a/doc/cli/keybindings.md b/doc/cli/keybindings.md index 8f66f639..6d68e28a 100644 --- a/doc/cli/keybindings.md +++ b/doc/cli/keybindings.md @@ -1,31 +1,33 @@ # Keybindings -> Tap `q` or `Ctrl-c` to quit the help viewer. - Writing CLI commands by hand is very tedious. To make things easier the CLI has several keybindings, most significant first: -| **Key** | **Cmd/Key** | **Description** | -|---------|---------------|--------------------------------------------------| -| TAB | | Complete current command, see below for example | -| ? | | Show available commands, or arguments, with help | -| Ctrl-c | | Cancel everything on current line | -| Ctrl-d | `abort` | Abort context, `exit` in admin-exec | -| Ctrl-z | `leave` | Leave and activate changes in configure context | -| Ctrl-f | Right arrow | Move cursor forward one character | -| Ctrl-b | Left arrow | Move cursor back one character | -| Alt-f | Ctrl-Right | Move cursor forward one word | -| Alt-b | Ctrl-Left | Move cursor back one word | -| Ctrl-e | End | Move cursor to end of line | -| Ctrl-a | Home | Move cursor to beginning of line | -| Ctrl-k | | Kill (cut) text from cursor to end of line | -| Ctrl-u | | Delete (cut) entire line | -| Ctrl-y | | Yank (paste) from kill buffer to cursor | -| Ctrl-w | Alt-Backspace | Delete (cut) word to the left | -| | Alt-Delete | Delete (cut) word to the right | -| | | | +| **Key** | **Cmd/Key** | **Description** | +|---------|----------------|--------------------------------------------------| +| TAB | | Complete current command, see below for example | +| ? | | Show available commands, or arguments, with help | +| Ctrl-c | | Cancel everything on current line | +| Ctrl-d | `abort`/`exit` | Delete character, or abort/exit on empty line | +| Ctrl-z | `leave` | Leave and activate changes in configure context | +| Ctrl-f | Right arrow | Move cursor forward one character | +| Ctrl-b | Left arrow | Move cursor back one character | +| Meta-f | Ctrl-Right | Move cursor forward one word | +| Meta-b | Ctrl-Left | Move cursor back one word | +| Ctrl-e | End | Move cursor to end of line | +| Ctrl-a | Home | Move cursor to beginning of line | +| Ctrl-k | | Kill (cut) text from cursor to end of line | +| Ctrl-u | | Delete (cut) entire line | +| Ctrl-y | | Yank (paste) from kill buffer to cursor | +| Meta-. | | Yank (paste) last argument from previous line | +| Ctrl-w | Meta-Backspace | Delete (cut) word to the left | +| | Meta-Delete | Delete (cut) word to the right | +| Ctrl-l | | Clear screen and refresh current line | +| Ctrl-p | Up arrow | History, previous command | +| Ctrl-n | Down arrow | History, next command | +| Ctrl-r | | History, reversed interactive search (i-search) | -> **Note:** the Alt key on your keyboard may also be called Meta. If you +> **Note:** the Meta key is called Alt on most modern keyboards. If you > have neither, first tap the Esc key instead of holding down Alt/Meta. ## Examples @@ -38,6 +40,9 @@ on your keyboard: See possible arguments, with brief help text, to a command: show ? + bridge Show bridge (ports/fdb/mdb/vlans) + datetime Show current date and time, default RFC2822 format + ... Type the command, then tap the `?` key. diff --git a/doc/cli/quick.md b/doc/cli/quick.md new file mode 100644 index 00000000..5b5c1eaa --- /dev/null +++ b/doc/cli/quick.md @@ -0,0 +1,25 @@ +# Quick Overview + +The question mark `?` key along with the `Tab` key are your best friends +in the command line interface. They provide context help and completion +of commands you input. See the table below for a handful of examples. + +| **Command** | **Description** | +|---------------------|----------------------------------------------------| +| `help` | Overview of topics/settings in the current context | +| `?` | Lists commands + brief help in the current context | +| `` | Lists commands available in the current context | +| `partial` | Completes a partial command name | +| `command ` | Lists keywords/arguments associated with a command | +| `command keyword ?` | Lists arguments associated with a keyword + help | + +Explore the following topics for more information. Note, the +keybindings are really useful to learn! + +| **Command** | **Description** | +|---------------------|--------------------------------------------| +| `help introduction` | An introduction to the CLI | +| `help keybindings` | Lists keybindings and other helpful tricks | +| `help tutorial` | The CLI User Guide | + + diff --git a/doc/cli/tutorial.md b/doc/cli/tutorial.md index 0e9a64e3..13fb8c63 100644 --- a/doc/cli/tutorial.md +++ b/doc/cli/tutorial.md @@ -18,6 +18,12 @@ Key commands available in any context are: For each command it also possible to press the `?` key and `TAB` to get more help and suggestions for completion. +> **Note:** for the sake of brevity, the hostname in the following +> examples has been shortened to `host`. The default name is composed +> from a product specific string followed by the last three octets of +> the system base MAC address, e.g., `infix-12-34-56`. An example of +> how to change the hostname is included below. + Admin Exec ---------- @@ -29,7 +35,7 @@ managing configuration files/profiles and doing advanced debugging. Available commands can be seen by pressing `?` at the prompt: ``` -admin@infix-12-34-56:exec> +admin@host:/> configure Create new candidate-config based on running-config copy Copy exit Exit @@ -45,7 +51,8 @@ Enter the configure context from admin-exec by typing `configure` followed by Enter. Available commands, press `?` at the prompt: ``` -admin@infix-12-34-56:configure> +admin@host:/> +admin@host:/config/> abort Abandon candidate check Validate candidate commit Commit current candidate to running-config @@ -61,40 +68,42 @@ admin@infix-12-34-56:configure> show Show configuration top Ascend to the configuration root up Ascend to the parent configuration node -[edit] ``` The `edit` command lets you change to a sub-configure context, e.g.: ``` -admin@infix-12-34-56:configure> edit interfaces interface eth0 -[edit interfaces interface eth0] +admin@host:/config/> edit interfaces interface eth0 +admin@host:/config/interfaces/interface/eth0/> ``` -Notice the `[edit ...]` displayed, it shows your current location. -Use `up` to go back to the previous context. +Use `up` to go up one level. ``` -admin@infix-12-34-56:configure> up -[edit] +admin@host:/config/interfaces/interface/eth0/> up +admin@host:/config/interfaces/> ``` +> **Note:** the tree structure in the configure context is automatically +> generated from the system's supported NETCONF YANG models, which may +> vary between products. However, the `ietf-interfaces.yang` and +> `ietf-ip.yang` models, for instance, that provide basic networking +> support are common to all systems. + + ### Set IP Address on an Interface ``` -admin@infix-12-34-56:configure> -[edit] -admin@infix-12-34-56:configure> edit interfaces interface eth0 -[edit interfaces interface eth0] -admin@infix-12-34-56:configure> set ipv4 address 192.168.2.200 prefix-length 24 -[edit interfaces interface eth0] +admin@host:/config/> edit interfaces interface eth0 +admin@host:/config/interfaces/interface/eth0/> +admin@host:/config/interfaces/interface/eth0/> set ipv4 address 192.168.2.200 prefix-length 24 ``` From anywhere in configure context you can see the changes you have made by typing `diff`: ``` -admin@infix-12-34-56:configure> diff +admin@host:/config/interfaces/interface/eth0/> diff interfaces { interface eth0 { + ipv4 { @@ -106,6 +115,83 @@ interfaces { } ``` + +### Saving Changes + +Apply the changes (from candidate to `running-config`): + +``` +admin@host:/config/interfaces/> leave +admin@host:/> show running-config +... +interfaces { + interface eth0 { + type ethernetCsmacd; + ipv4 { + address 192.168.2.200 { + prefix-length 24; + } + } + } +... +``` + +Since we did not get any warnings we can save the running (RAM only) +configuration to startup, so the changes are made persistent across +reboots: + +``` +admin@host:/> copy running-config startup-config +``` + +The `startup-config` can also be inspected with the `show` command to +verify the changes are saved. + +> **Note:** most (all) commands need to be spelled out, no short forms +> are allowed at the moment. Use the `TAB` key to make this easier. + + +### Changing Hostname + +Settings like hostname are located in the `ietf-system.yang` model. +Here is how it can be set. + +``` +admin@host:/config/> edit system +admin@host:/config/system/> set hostname example +admin@host:/config/system/> leave +admin@example:/> +``` + +Notice how the hostname in the prompt does not change until the change +is committed. + +> **Note:** critical services like syslog, mDNS, LLDP, and similar that +> advertise the hostname, are restarted when the hostname is changed. + + +### Changing Password + +User management, including passwords, is also a part of `ietf-system`. + +``` +admin@host:/config/> edit system authentication +admin@host:/config/system/authentication/> do password encrypt +Password: ****** +$1$oVHGR0AP$6Pad1Pm8jPwPsan5WHULS1 +admin@host:/config/system/authentication/> set user admin password $1$oVHGR0AP$6Pad1Pm8jPwPsan5WHULS1 +admin@host:/config/system/> leave +``` + +The call to `do password encrypt` brings up the helpful admin-exec +command to hash, and optionally salt, your password. This encrypted +string is what goes into the system configuration. + +> **Tip:** if you are having trouble thinking of a password, there is +> also `do password generate`, which generates random but readable +> strings using the UNIX command `pwgen`. + + ### Creating a VETH Pair The following example creates a `veth0a <--> veth0b` virtual Ethernet @@ -113,17 +199,11 @@ pair which is useful for connecting, e.g., a container to the physical world. Here we also add an IPv4 address to one end of the pair. ``` -admin@infix-12-34-56:configure> -[edit] -admin@infix-12-34-56:configure> edit interfaces interface veth0a -[edit interfaces interface veth0a] -admin@infix-12-34-56:configure> set veth peer veth0b -[edit interfaces interface veth0a] -admin@infix-12-34-56:configure> set ipv4 address 192.168.0.1 prefix-length 24 -[edit interfaces interface veth0a] -admin@infix-12-34-56:configure> up -[edit interfaces] -admin@infix-12-34-56:configure> diff +admin@host:/config/> edit interfaces interface veth0a +admin@host:/config/interfaces/interface/veth0a/> set veth peer veth0b +admin@host:/config/interfaces/interface/veth0a/> set ipv4 address 192.168.0.1 prefix-length 24 +admin@host:/config/interfaces/interface/veth0a/> up +admin@host:/config/interfaces/> diff interfaces { + interface veth0a { + type veth; @@ -143,8 +223,7 @@ interfaces { + } + } } -[edit interfaces] -admin@infix-12-34-56:configure> leave +admin@host:/config/interfaces/> leave ``` See the bridging example below for more. @@ -156,23 +235,18 @@ See the bridging example below for more. ### Creating a Bridge -Here we create a non-VLAN filtering bridge that forwards any, normally -link-local, LLDP traffic. +Building on the previous example, we now create a non-VLAN filtering +bridge (`br0`) that forwards any, normally link-local, LLDP traffic +between both its bridge ports: `eth0` and `vet0b`. ``` -admin@infix-12-34-56:exec> configure -[edit] -admin@infix-12-34-56:configure> edit interfaces interface br0 -[edit interfaces interface br0] -admin@infix-12-34-56:configure> set bridge ieee-group-forward lldp -[edit interfaces interface br0] -admin@infix-12-34-56:configure> up -[edit interfaces] -admin@infix-12-34-56:configure> set interface eth0 bridge-port bridge br0 -[edit interfaces] -admin@infix-12-34-56:configure> set interface veth0b bridge-port bridge br0 -[edit interfaces] -admin@infix-12-34-56:configure> diff +admin@host:/> configure +admin@host:/config/> edit interfaces interface br0 +admin@host:/config/interfaces/interface/br0/> set bridge ieee-group-forward lldp +admin@host:/config/interfaces/interface/br0/> up +admin@host:/config/interfaces/> set interface eth0 bridge-port bridge br0 +admin@host:/config/interfaces/> set interface veth0b bridge-port bridge br0 +admin@host:/config/interfaces/> diff interfaces { + interface br0 { + type bridge; @@ -206,8 +280,6 @@ interfaces { + } + } } -[edit interfaces] -admin@infix-12-34-56:configure> leave ``` Both a physical port `eth0` and a virtual port `veth0b` (bridge side of @@ -215,40 +287,10 @@ the VETH pair from the previous example) are now bridged. Any traffic ingressing one port will egress the other. Only reserved IEEE multicast is filtered, except LLDP frames as shown above. +> **Note:** the bridge can be named anything, provided the interface +> name is not already taken. However, for any name outside the pattern +> `br[0-9]+`, you have to set the interface type manually to `bridge`. -### Saving Changes - -Apply the changes (from candidate to running): - -``` -admin@infix-12-34-56:configure> leave -admin@infix-12-34-56:exec> show running-config -... -interfaces { - interface eth0 { - type ethernetCsmacd; - ipv4 { - address 192.168.2.200 { - prefix-length 24; - } - } - } -... -``` - -Since we did not get any warnings we can save the running (RAM only) -configuration to startup, so the changes are made persistent across -reboots: - -``` -admin@infix-12-34-56:exec> copy running-config startup-config -``` - -The `startup-config` can also be inspected with the `show` command to -verify the changes are saved. - -> **Note:** most (all) commands need to be spelled out, no short forms -> are allowed at the moment. Use the `TAB` key to make this easier. [1]: https://src.libcode.org/pkun/klish