diff --git a/board/common/rootfs/etc/profile.d/convenience.sh b/board/common/rootfs/etc/profile.d/convenience.sh index a160330e..799318ea 100644 --- a/board/common/rootfs/etc/profile.d/convenience.sh +++ b/board/common/rootfs/etc/profile.d/convenience.sh @@ -4,6 +4,7 @@ alias ll='ls -alF' alias ls='ls --color=auto' export EDITOR=/usr/bin/edit +export LESS="-P %f (press h for help or q to quit)" alias vim='vi' alias view='vi -R' alias emacs='mg' diff --git a/configs/aarch64_defconfig b/configs/aarch64_defconfig index b7deddfc..60789091 100644 --- a/configs/aarch64_defconfig +++ b/configs/aarch64_defconfig @@ -92,6 +92,7 @@ BR2_PACKAGE_RAUC_NETWORK=y BR2_PACKAGE_SYSKLOGD=y BR2_PACKAGE_SYSKLOGD_LOGGER=y BR2_PACKAGE_WATCHDOGD=y +BR2_PACKAGE_LESS=y BR2_PACKAGE_MG=y BR2_PACKAGE_NANO=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_URANDOM=y BR2_PACKAGE_KLINFIX=y +BR2_PACKAGE_LOWDOWN=y BR2_PACKAGE_NET=y BR2_PACKAGE_TETRIS=y BR2_PACKAGE_QUERIERD=y diff --git a/configs/x86_64_defconfig b/configs/x86_64_defconfig index 492ae02c..6af091af 100644 --- a/configs/x86_64_defconfig +++ b/configs/x86_64_defconfig @@ -89,6 +89,7 @@ BR2_PACKAGE_RAUC_NETWORK=y BR2_PACKAGE_SYSKLOGD=y BR2_PACKAGE_SYSKLOGD_LOGGER=y BR2_PACKAGE_WATCHDOGD=y +BR2_PACKAGE_LESS=y BR2_PACKAGE_MG=y BR2_PACKAGE_NANO=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_URANDOM=y BR2_PACKAGE_KLINFIX=y +BR2_PACKAGE_LOWDOWN=y BR2_PACKAGE_NET=y BR2_PACKAGE_TETRIS=y BR2_PACKAGE_QUERIERD=y diff --git a/doc/cli/README.md b/doc/cli/README.md new file mode 120000 index 00000000..3caa8838 --- /dev/null +++ b/doc/cli/README.md @@ -0,0 +1 @@ +introduction.md \ No newline at end of file diff --git a/doc/cli/introduction.md b/doc/cli/introduction.md new file mode 100644 index 00000000..8ed9220e --- /dev/null +++ b/doc/cli/introduction.md @@ -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 + 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 +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 +``` + +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. + diff --git a/doc/cli/keybindings.md b/doc/cli/keybindings.md new file mode 100644 index 00000000..8f66f639 --- /dev/null +++ b/doc/cli/keybindings.md @@ -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 --> configure + +See possible arguments, with brief help text, to a command: + + show ? + +Type the command, then tap the `?` key. + diff --git a/doc/cli.md b/doc/cli/tutorial.md similarity index 67% rename from doc/cli.md rename to doc/cli/tutorial.md index fb170553..0e9a64e3 100644 --- a/doc/cli.md +++ b/doc/cli/tutorial.md @@ -1,34 +1,22 @@ -CLI User Guide -============== +User Guide +========== -* [Introduction](#introduction) -* [Admin Exec](#admin-exec) -* [Configure Context](#configure-context) - * [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) +The command line interface (CLI, see-el-i) is built on the open source +component [klish][1], which implements a CISCO like, or Juniper Networks +JunOS-like CLI on a UNIX system. - -Introduction ------------- - -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: +New users always get the CLI as the default "shell" when logging in, but +the default `admin` user logs in to the Bash. To access the CLI, type: cli Key commands available in any context are: help - show + show -For each command it is also possible to press the `?` key and `TAB` to -get more help and suggestions for completion. +For each command it also possible to press the `?` key and `TAB` to get +more help and suggestions for completion. Admin Exec @@ -41,7 +29,7 @@ managing configuration files/profiles and doing advanced debugging. 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 copy Copy 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: ``` -root@infix-12-34-56:configure> +admin@infix-12-34-56:configure> abort Abandon candidate check Validate candidate 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.: ``` -root@infix-12-34-56:configure> edit interfaces interface eth0 +admin@infix-12-34-56:configure> 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. ``` -root@infix-12-34-56:configure> up +admin@infix-12-34-56:configure> up [edit] ``` ### Set IP Address on an Interface ``` -root@infix-12-34-56:configure> +admin@infix-12-34-56:configure> [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] -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] ``` @@ -106,7 +94,7 @@ From anywhere in configure context you can see the changes you have made by typing `diff`: ``` -root@infix-12-34-56:configure> diff +admin@infix-12-34-56:configure> diff interfaces { interface eth0 { + 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. ``` -root@infix-12-34-56:configure> +admin@infix-12-34-56:configure> [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] -root@infix-12-34-56:configure> set veth peer veth0b +admin@infix-12-34-56:configure> set veth peer veth0b [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] -root@infix-12-34-56:configure> up +admin@infix-12-34-56:configure> up [edit interfaces] -root@infix-12-34-56:configure> diff +admin@infix-12-34-56:configure> diff interfaces { + interface veth0a { + type veth; @@ -156,7 +144,7 @@ interfaces { + } } [edit interfaces] -root@infix-12-34-56:configure> leave +admin@infix-12-34-56:configure> leave ``` 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. ``` -root@infix-12-34-56:exec> configure +admin@infix-12-34-56:exec> configure [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] -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] -root@infix-12-34-56:configure> up +admin@infix-12-34-56:configure> up [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] -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] -root@infix-12-34-56:configure> diff +admin@infix-12-34-56:configure> diff interfaces { + interface br0 { + type bridge; @@ -219,7 +207,7 @@ 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 @@ -233,17 +221,19 @@ is filtered, except LLDP frames as shown above. Apply the changes (from candidate to running): ``` -root@infix-12-34-56:configure> leave -root@infix-12-34-56:exec> show running-config +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; - } - } + 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) @@ -251,9 +241,12 @@ configuration to startup, so the changes are made persistent across 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 > are allowed at the moment. Use the `TAB` key to make this easier. diff --git a/package/klinfix/klinfix.mk b/package/klinfix/klinfix.mk index 7f445be6..7805182e 100644 --- a/package/klinfix/klinfix.mk +++ b/package/klinfix/klinfix.mk @@ -12,4 +12,10 @@ KLINFIX_SITE = $(BR2_EXTERNAL_INFIX_PATH)/src/klinfix KLINFIX_DEPENDENCIES = klish-plugin-sysrepo 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)) diff --git a/package/klish/klish.mk b/package/klish/klish.mk index 7d4289ec..b266023b 100644 --- a/package/klish/klish.mk +++ b/package/klish/klish.mk @@ -21,11 +21,6 @@ define KLISH_INSTALL_CONFIG $(@D)/plugins/klish/xml/ptypes.xml $(INSTALL) -t $(TARGET_DIR)/etc/klish -D -m 0644 \ $(@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 KLISH_POST_INSTALL_TARGET_HOOKS += KLISH_INSTALL_CONFIG diff --git a/src/klinfix/xml/infix.xml b/src/klinfix/xml/infix.xml index 2ea385d5..708fd3c1 100644 --- a/src/klinfix/xml/infix.xml +++ b/src/klinfix/xml/infix.xml @@ -101,6 +101,20 @@ %u@%h:exec> + + + + keybindings + tutorial + introduction + + + + topic=${KLISH_PARAM_topic:-quick} + lowdown -t term /usr/share/infix/cli/${topic}.md + + + /ietf-system:system-shutdown