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: relocate and extend CLI docs with intro and keybindings

Browse Source 
This is not just for online viewing, these markdown documents are also
made available in the CLI itself from admin-exec as:

    help [introduction | keybindings | tutorial]

With this commit we also add lowdown and the real less application to
be the Infix help system.

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 52301db8bd
commit d913ce00e6
10 changed files with 217 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
board/common/rootfs/etc/profile.d/convenience.sh
+1
View File
@@ -4,6 +4,7 @@ alias ll='ls -alF'
alias ls='ls --color=auto' alias ls='ls --color=auto'
export EDITOR=/usr/bin/edit export EDITOR=/usr/bin/edit
export LESS="-P %f (press h for help or q to quit)"
alias vim='vi' alias vim='vi'
alias view='vi -R' alias view='vi -R'
alias emacs='mg' alias emacs='mg'
configs/aarch64_defconfig
+2
View File
@@ -92,6 +92,7 @@ BR2_PACKAGE_RAUC_NETWORK=y
BR2_PACKAGE_SYSKLOGD=y BR2_PACKAGE_SYSKLOGD=y
BR2_PACKAGE_SYSKLOGD_LOGGER=y BR2_PACKAGE_SYSKLOGD_LOGGER=y
BR2_PACKAGE_WATCHDOGD=y BR2_PACKAGE_WATCHDOGD=y
BR2_PACKAGE_LESS=y
BR2_PACKAGE_MG=y BR2_PACKAGE_MG=y
BR2_PACKAGE_NANO=y BR2_PACKAGE_NANO=y
BR2_TARGET_ROOTFS_SQUASHFS=y BR2_TARGET_ROOTFS_SQUASHFS=y
@@ -116,6 +117,7 @@ BR2_PACKAGE_FINIT_PLUGIN_RTC=y
BR2_PACKAGE_FINIT_PLUGIN_TTY=y BR2_PACKAGE_FINIT_PLUGIN_TTY=y
BR2_PACKAGE_FINIT_PLUGIN_URANDOM=y BR2_PACKAGE_FINIT_PLUGIN_URANDOM=y
BR2_PACKAGE_KLINFIX=y BR2_PACKAGE_KLINFIX=y
BR2_PACKAGE_LOWDOWN=y
BR2_PACKAGE_NET=y BR2_PACKAGE_NET=y
BR2_PACKAGE_TETRIS=y BR2_PACKAGE_TETRIS=y
BR2_PACKAGE_QUERIERD=y BR2_PACKAGE_QUERIERD=y
configs/x86_64_defconfig
+2
View File
@@ -89,6 +89,7 @@ BR2_PACKAGE_RAUC_NETWORK=y
BR2_PACKAGE_SYSKLOGD=y BR2_PACKAGE_SYSKLOGD=y
BR2_PACKAGE_SYSKLOGD_LOGGER=y BR2_PACKAGE_SYSKLOGD_LOGGER=y
BR2_PACKAGE_WATCHDOGD=y BR2_PACKAGE_WATCHDOGD=y
BR2_PACKAGE_LESS=y
BR2_PACKAGE_MG=y BR2_PACKAGE_MG=y
BR2_PACKAGE_NANO=y BR2_PACKAGE_NANO=y
BR2_TARGET_ROOTFS_SQUASHFS=y BR2_TARGET_ROOTFS_SQUASHFS=y
@@ -121,6 +122,7 @@ BR2_PACKAGE_FINIT_PLUGIN_RTC=y
BR2_PACKAGE_FINIT_PLUGIN_TTY=y BR2_PACKAGE_FINIT_PLUGIN_TTY=y
BR2_PACKAGE_FINIT_PLUGIN_URANDOM=y BR2_PACKAGE_FINIT_PLUGIN_URANDOM=y
BR2_PACKAGE_KLINFIX=y BR2_PACKAGE_KLINFIX=y
BR2_PACKAGE_LOWDOWN=y
BR2_PACKAGE_NET=y BR2_PACKAGE_NET=y
BR2_PACKAGE_TETRIS=y BR2_PACKAGE_TETRIS=y
BR2_PACKAGE_QUERIERD=y BR2_PACKAGE_QUERIERD=y
doc/cli/README.md
Symlink
+1
View File
@@ -0,0 +1 @@
introduction.md
doc/cli/introduction.md
+101
View File
@@ -0,0 +1,101 @@
# Introduction
The command line interface (CLI, see-ell-i) is the traditional way of
interacting with single network equipment like switches and routers.
Today more advanced graphical NETCONF-based tools are available that
allows for managing entire fleets of installed equipment.
Nevertheless, when it comes to initial deployment and debugging, it
is very useful to know how to navigate and use the CLI. This very
short guide intends to help you with that.
## Key Concepts
The two modes in the CLI are the admin-exec and the configure context.
When logging in to the system, be it from console or SSH, you land in
admin-exec. Here you can inspect the system status and do operations
to debug networking issues, e.g. ping. You can also enter configure
context by typing: `configure`
The system has several datastores (or files):
- `factory-config` consists of a set of default configurations, some
static and others generated per-device, e.g., a unique hostname and
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.
- `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`.
- `candidate-config` is created from `running-config` when entering the
configure context. Any changes made here can be discarded (`abort`,
`rollback`) or committed (`commit`, `leave`) to `running-config`.
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
In configure context the following commands are available:
| **Command** | **Description** |
|-------------------|--------------------------------------------------------|
| `set foo bar val` | Set `bar` leaf node in `foo` subcontext to `val` |
| `no foo bar` | Clear/delete configuration made to `bar` in `foo` |
| `edit foo baz` | Enter `baz` sub-sub-context in `foo` subcontext |
| `abort` | Abort changes in configuration, return to admin-exec |
| `exit` | Exit one level sub-context, or abort from top-level |
| `leave` | Save changes to `running-config`, return to admin-exec |
| `show [foo]` | Show configured values (optionally in subcontext) |
| `diff [foo]` | Show uncommitted changes in candidate |
| `do command` | Call admin-exec command: `do show log` |
| `commit` | |
### Example Session
> Remember to use the `TAB` and `?` keys to speed up your navigation.
> See `help keybindings` for more tips!
In this example we enter configure context to add an IPv4 address to
interface `eth0`, then we apply the changes using the `leave` command.
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
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
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
```
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
Or restarting the device.
doc/cli/keybindings.md
+43
View File
@@ -0,0 +1,43 @@
# 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 |
| | | |
> **Note:** the Alt key on your keyboard may also be called Meta. If you
> have neither, first tap the Esc key instead of holding down Alt/Meta.
## Examples
Complete a word. Start by typing a few characters, then tap the TAB key
on your keyboard:
conf<TAB> --> configure
See possible arguments, with brief help text, to a command:
show ?
Type the command, then tap the `?` key.
doc/cli.md → doc/cli/tutorial.md
+47 -54
View File
@@ -1,34 +1,22 @@
CLI User Guide User Guide
============== ==========
* [Introduction](#introduction) The command line interface (CLI, see-el-i) is built on the open source
* [Admin Exec](#admin-exec) component [klish][1], which implements a CISCO like, or Juniper Networks
* [Configure Context](#configure-context) JunOS-like CLI on a UNIX system.
* [Set IP Address on an Interface](#set-ip-address-on-an-interface)
* [Creating a VETH pair](#creating-a-veth-pair)
* [Creating a Bridge](#creating-a-bridge)
* [Saving Changes](#saving-changes)
New users always get the CLI as the default "shell" when logging in, but
Introduction the default `admin` user logs in to the Bash. To access the CLI, type:
------------
The Infix CLI is built on the [klish project][1], which is a framework
for implementing a CISCO, or Juniper Networks JunOS-like CLI on a UNIX
system.
Currently, when the `admin` user logs in the default shell is Bash. To
access the CLI, type:
cli cli
Key commands available in any context are: Key commands available in any context are:
help help
show show
For each command it is also possible to press the `?` key and `TAB` to For each command it also possible to press the `?` key and `TAB` to get
get more help and suggestions for completion. more help and suggestions for completion.
Admin Exec Admin Exec
@@ -41,7 +29,7 @@ managing configuration files/profiles and doing advanced debugging.
Available commands can be seen by pressing `?` at the prompt: Available commands can be seen by pressing `?` at the prompt:
``` ```
root@infix-12-34-56:exec> admin@infix-12-34-56:exec>
configure Create new candidate-config based on running-config configure Create new candidate-config based on running-config
copy Copy copy Copy
exit Exit exit Exit
@@ -57,7 +45,7 @@ Enter the configure context from admin-exec by typing `configure`
followed by Enter. Available commands, press `?` at the prompt: followed by Enter. Available commands, press `?` at the prompt:
``` ```
root@infix-12-34-56:configure> admin@infix-12-34-56:configure>
abort Abandon candidate abort Abandon candidate
check Validate candidate check Validate candidate
commit Commit current candidate to running-config commit Commit current candidate to running-config
@@ -79,7 +67,7 @@ root@infix-12-34-56:configure>
The `edit` command lets you change to a sub-configure context, e.g.: The `edit` command lets you change to a sub-configure context, e.g.:
``` ```
root@infix-12-34-56:configure> edit interfaces interface eth0 admin@infix-12-34-56:configure> edit interfaces interface eth0
[edit interfaces interface eth0] [edit interfaces interface eth0]
``` ```
@@ -87,18 +75,18 @@ Notice the `[edit ...]` displayed, it shows your current location.
Use `up` to go back to the previous context. Use `up` to go back to the previous context.
``` ```
root@infix-12-34-56:configure> up admin@infix-12-34-56:configure> up
[edit] [edit]
``` ```
### Set IP Address on an Interface ### Set IP Address on an Interface
``` ```
root@infix-12-34-56:configure> admin@infix-12-34-56:configure>
[edit] [edit]
root@infix-12-34-56:configure> edit interfaces interface eth0 admin@infix-12-34-56:configure> edit interfaces interface eth0
[edit interfaces interface eth0] [edit interfaces interface eth0]
root@infix-12-34-56:configure> set ipv4 address 192.168.2.200 prefix-length 24 admin@infix-12-34-56:configure> set ipv4 address 192.168.2.200 prefix-length 24
[edit interfaces interface eth0] [edit interfaces interface eth0]
``` ```
@@ -106,7 +94,7 @@ From anywhere in configure context you can see the changes you have
made by typing `diff`: made by typing `diff`:
``` ```
root@infix-12-34-56:configure> diff admin@infix-12-34-56:configure> diff
interfaces { interfaces {
interface eth0 { interface eth0 {
+ ipv4 { + ipv4 {
@@ -125,17 +113,17 @@ 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. world. Here we also add an IPv4 address to one end of the pair.
``` ```
root@infix-12-34-56:configure> admin@infix-12-34-56:configure>
[edit] [edit]
root@infix-12-34-56:configure> edit interfaces interface veth0a admin@infix-12-34-56:configure> edit interfaces interface veth0a
[edit interfaces interface veth0a] [edit interfaces interface veth0a]
root@infix-12-34-56:configure> set veth peer veth0b admin@infix-12-34-56:configure> set veth peer veth0b
[edit interfaces interface veth0a] [edit interfaces interface veth0a]
root@infix-12-34-56:configure> set ipv4 address 192.168.0.1 prefix-length 24 admin@infix-12-34-56:configure> set ipv4 address 192.168.0.1 prefix-length 24
[edit interfaces interface veth0a] [edit interfaces interface veth0a]
root@infix-12-34-56:configure> up admin@infix-12-34-56:configure> up
[edit interfaces] [edit interfaces]
root@infix-12-34-56:configure> diff admin@infix-12-34-56:configure> diff
interfaces { interfaces {
+ interface veth0a { + interface veth0a {
+ type veth; + type veth;
@@ -156,7 +144,7 @@ interfaces {
+ } + }
} }
[edit interfaces] [edit interfaces]
root@infix-12-34-56:configure> leave admin@infix-12-34-56:configure> leave
``` ```
See the bridging example below for more. See the bridging example below for more.
@@ -172,19 +160,19 @@ Here we create a non-VLAN filtering bridge that forwards any, normally
link-local, LLDP traffic. link-local, LLDP traffic.
``` ```
root@infix-12-34-56:exec> configure admin@infix-12-34-56:exec> configure
[edit] [edit]
root@infix-12-34-56:configure> edit interfaces interface br0 admin@infix-12-34-56:configure> edit interfaces interface br0
[edit interfaces interface br0] [edit interfaces interface br0]
root@infix-12-34-56:configure> set bridge ieee-group-forward lldp admin@infix-12-34-56:configure> set bridge ieee-group-forward lldp
[edit interfaces interface br0] [edit interfaces interface br0]
root@infix-12-34-56:configure> up admin@infix-12-34-56:configure> up
[edit interfaces] [edit interfaces]
root@infix-12-34-56:configure> set interface eth0 bridge-port bridge br0 admin@infix-12-34-56:configure> set interface eth0 bridge-port bridge br0
[edit interfaces] [edit interfaces]
root@infix-12-34-56:configure> set interface veth0b bridge-port bridge br0 admin@infix-12-34-56:configure> set interface veth0b bridge-port bridge br0
[edit interfaces] [edit interfaces]
root@infix-12-34-56:configure> diff admin@infix-12-34-56:configure> diff
interfaces { interfaces {
+ interface br0 { + interface br0 {
+ type bridge; + type bridge;
@@ -219,7 +207,7 @@ interfaces {
+ } + }
} }
[edit interfaces] [edit interfaces]
root@infix-12-34-56:configure> leave admin@infix-12-34-56:configure> leave
``` ```
Both a physical port `eth0` and a virtual port `veth0b` (bridge side of Both a physical port `eth0` and a virtual port `veth0b` (bridge side of
@@ -233,17 +221,19 @@ is filtered, except LLDP frames as shown above.
Apply the changes (from candidate to running): Apply the changes (from candidate to running):
``` ```
root@infix-12-34-56:configure> leave admin@infix-12-34-56:configure> leave
root@infix-12-34-56:exec> show running-config admin@infix-12-34-56:exec> show running-config
...
interfaces { interfaces {
interface eth0 { interface eth0 {
type ethernetCsmacd; type ethernetCsmacd;
ipv4 { ipv4 {
address 192.168.2.200 { address 192.168.2.200 {
prefix-length 24; prefix-length 24;
} }
} }
} }
...
``` ```
Since we did not get any warnings we can save the running (RAM only) Since we did not get any warnings we can save the running (RAM only)
@@ -251,9 +241,12 @@ configuration to startup, so the changes are made persistent across
reboots: reboots:
``` ```
root@infix-12-34-56:exec> copy running-config startup-config 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 > **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. > are allowed at the moment. Use the `TAB` key to make this easier.
package/klinfix/klinfix.mk
+6
View File
@@ -12,4 +12,10 @@ KLINFIX_SITE = $(BR2_EXTERNAL_INFIX_PATH)/src/klinfix
KLINFIX_DEPENDENCIES = klish-plugin-sysrepo KLINFIX_DEPENDENCIES = klish-plugin-sysrepo
KLINFIX_AUTORECONF = YES KLINFIX_AUTORECONF = YES
define KLINFIX_INSTALL_DOC
$(INSTALL) -t $(TARGET_DIR)/usr/share/infix/cli -D -m 0644 \
$(wildcard $(BR2_EXTERNAL_INFIX_PATH)/doc/cli/*.md)
endef
KLINFIX_POST_INSTALL_TARGET_HOOKS += KLINFIX_INSTALL_DOC
$(eval $(autotools-package)) $(eval $(autotools-package))
package/klish/klish.mk
-5
View File
@@ -21,11 +21,6 @@ define KLISH_INSTALL_CONFIG
$(@D)/plugins/klish/xml/ptypes.xml $(@D)/plugins/klish/xml/ptypes.xml
$(INSTALL) -t $(TARGET_DIR)/etc/klish -D -m 0644 \ $(INSTALL) -t $(TARGET_DIR)/etc/klish -D -m 0644 \
$(@D)/klish.conf $(@D)/klishd.conf $(@D)/klish.conf $(@D)/klishd.conf
# klish's default pager settings assumes that less understands
# all GNU options, so we disable it.
sed -i -e 's/#UsePager=y/UsePager=n/' \
$(TARGET_DIR)/etc/klish/klish.conf
endef endef
KLISH_POST_INSTALL_TARGET_HOOKS += KLISH_INSTALL_CONFIG KLISH_POST_INSTALL_TARGET_HOOKS += KLISH_INSTALL_CONFIG
src/klinfix/xml/infix.xml
+14
View File
@@ -101,6 +101,20 @@
<ACTION sym="prompt" exec_on="always">%u@%h:exec> </ACTION> <ACTION sym="prompt" exec_on="always">%u@%h:exec> </ACTION>
</PROMPT> </PROMPT>
<COMMAND name="help" help="Help system (also try '?' key)">
<PARAM name="topic" ptype="/STRING" min="0" help="Help topic">
<COMPL>
<ACTION sym="printl">keybindings</ACTION>
<ACTION sym="printl">tutorial</ACTION>
<ACTION sym="printl">introduction</ACTION>
</COMPL>
</PARAM>
<ACTION sym="script">
topic=${KLISH_PARAM_topic:-quick}
lowdown -t term /usr/share/infix/cli/${topic}.md
</ACTION>
</COMMAND>
<COMMAND name="poweroff" help="Poweroff system (system policy may yield reboot)"> <COMMAND name="poweroff" help="Poweroff system (system policy may yield reboot)">
<ACTION sym="klix_rpc@klinfix" ptype="STRING">/ietf-system:system-shutdown</ACTION> <ACTION sym="klix_rpc@klinfix" ptype="STRING">/ietf-system:system-shutdown</ACTION>
</COMMAND> </COMMAND>