peter/infix
1
0
Fork 0
mirror of https://github.com/kernelkit/infix.git synced 2026-07-22 01:13:00 +02:00
Code Issues Packages Projects Releases Wiki Activity

doc/cli: update all the topics to match the refreshed CLI functions

Browse Source 
Also, add a new `quick.md` that pops up when the user types `help`.
Very quick intro to get started.  Useful when we add a factory-default
motd: "Welcome to the CLI, type 'help' for a quick overview."

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2023-08-08 16:35:18 +02:00
committed by Tobias Waldekranz
parent bfce877525
commit 9766bbbed5
4 changed files with 199 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/cli/introduction.md
+26 -21
View File
@@ -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 <TAB>
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 <TAB>
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 <LOOPBACK,UP,LOWER_UP>
eth0 UP 52:54:00:12:34:56 <BROADCAST,MULTICAST,UP,LOWER_UP>
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.
doc/cli/keybindings.md
+27 -22
View File
@@ -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.
doc/cli/quick.md
+25
View File
@@ -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 |
| `<Tab>` | Lists commands available in the current context |
| `partial<Tab>` | Completes a partial command name |
| `command <Tab>` | 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 |
doc/cli/tutorial.md
+121 -79
View File
@@ -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