diff --git a/doc/README.md b/doc/README.md index 2d88f69b..8888f3cf 100644 --- a/doc/README.md +++ b/doc/README.md @@ -11,8 +11,9 @@ the `help` command. - **CLI Topics** - [Introduction to the CLI](cli/introduction.md) - - [CLI User's Guide](cli/tutorial.md) + - [Configuring using the CLI](cli/configure.md) - [Quick Overview](cli/quick.md) + - [Upgrading the Software](cli/upgrade.md) - **Infix User Guide** - [Introduction](introduction.md) - [System Configuration](system.md) diff --git a/doc/cli/tutorial.md b/doc/cli/configure.md similarity index 70% rename from doc/cli/tutorial.md rename to doc/cli/configure.md index bb43b772..23cad3bb 100644 --- a/doc/cli/tutorial.md +++ b/doc/cli/configure.md @@ -1,109 +1,3 @@ -User Guide -========== - -The command line interface (CLI, see-ell-aye) implements a CISCO-like, -or Juniper Networks JunOS-like, CLI for UNIX systems. - -New users always get the CLI as the default "shell" when logging in, but -the default `admin` user logs in to `bash`. To access the CLI, type: - - cli - -Key commands available in any context are: - - help - show - -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., `switch-12-34-56`. An example of how to change the hostname -> is included below. - - -Admin Exec ----------- - -The top-level context after logging in and starting the CLI is the -admin-exec or "main" context. It is used for querying system status, -managing configuration files/profiles and doing advanced debugging. - -Available commands can be seen by pressing `?` at the prompt: - -``` -admin@host:/> - configure Create new candidate-config based on running-config - copy Copy configuration, e.g., copy running-config startup-config - exit Exit from CLI (log out) - factory-reset Restore the system to factory default state - follow Monitor a log file, use Ctrl-C to abort - help Help system (also try '?' key) - logout Alias to exit - netcalc IP subnet calculator - password Password tools - ping Ping a network host or multicast group - poweroff Poweroff system (system policy may yield reboot) - reboot Reboot system - set Set operations, e.g., current date/time - shell Enter system shell - show Show system status and configuration files - tcpdump Capture network traffic - upgrade Install a software update bundle -``` - -To get more help for a given command, type the command, a space, and -then tap `?` again. You can also tap the `Tab` key to see available -argument completions. - -### Upgrading the Software - -The admin-exec command `upgrade` can be used to install software images, or -bundles. A bundle is a signed and self-contained package that carries all the -information necessary to determine if it holds a bootloader, a Linux image, or -even both. - -To install a new software image to the currently *inactive* partition[^1], we -use the `upgrade` command and a URI to a ftp/tftp/sftp or http/https server -that hosts the file: - -``` -admin@host:/> upgrade tftp://192.168.122.1/firmware-x86_64-v23.11.pkg -installing - 0% Installing - 0% Determining slot states - 20% Determining slot states done. - 20% Checking bundle - 20% Verifying signature - 40% Verifying signature done. - 40% Checking bundle done. - 40% Checking manifest contents - 60% Checking manifest contents done. - 60% Determining target install group - 80% Determining target install group done. - 80% Updating slots - 80% Checking slot rootfs.1 - 90% Checking slot rootfs.1 done. - 90% Copying image to rootfs.1 - 99% Copying image to rootfs.1 done. - 99% Updating slots done. -100% Installing done. -Installing `tftp://192.168.122.1/firmware-x86_64-v23.11.pkg` succeeded -admin@host:/> -``` - -The secondary partition (`rootfs.1`) has now been upgraded and will be used as -the *active* partition on the next boot. Leaving the primary partition, with -the version we are currently running, intact in case of trouble. - -[^1]: It is not possible to upgrade the partition we booted from. Thankfully - the underlying "rauc" subsystem keeps track of this. Hence, to upgrade - both partitions you must reboot to the new version (to verify it works) - and then repeat the same command. - - Configure Context ----------------- @@ -382,7 +276,3 @@ 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`. - - - -[1]: https://src.libcode.org/pkun/klish diff --git a/doc/cli/introduction.md b/doc/cli/introduction.md index ef7be3a5..09165c71 100644 --- a/doc/cli/introduction.md +++ b/doc/cli/introduction.md @@ -1,6 +1,7 @@ # Introduction -The command line interface (CLI, see-ell-i) is the traditional way of +The command line interface (CLI, see-ell-aye) implements a CISCO-like, +or Juniper Networks JunOS-like, CLI. It 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. @@ -9,34 +10,107 @@ 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. + +## About + +New users usually get the CLI as the default "shell" when logging in, +but the default `admin` user logs in to `bash`. To access the CLI, +type: + +``` +admin@host-12-34-56:~$ cli + +See the 'help' command for an introduction to the system + +admin@host-12-34-56:/> +``` + +The prompt (beginning of the line) changes slightly. Key commands +available in any context are: + +``` +admin@host-12-34-56:/> help # Try: Tab or ? +... +admin@host-12-34-56:/> show # Try: Tab or ? +admin@host-12-34-56:/> # Try: Tab or ? +``` + +> **Tip:** Even on an empty command line you can tap the Tab or ? keys. +> See `help keybindings` for more tips! + + ## 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 first have -a stopover in a UNIX shell, usually Bash. Type `cli` to enter the CLI -and finally land in admin-exec. Here you can inspect system status and -do operations to debug networking issues, e.g. ping. You can also enter -configure context by typing: `configure` +The top-level context after logging in and starting the CLI is the +admin-exec or "main" context. It is used for querying system status, +managing configuration files/profiles and doing advanced debugging. -The system has several datastores (or files): +Available commands can be seen by pressing `?` at the prompt: - - `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. - - `startup-config` is created from `factory-config` at boot if it does - 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`. +``` +admin@host:/> + configure Create new candidate-config based on running-config + copy Copy file or configuration, e.g., copy running-config startup-config + dir List available configuration files + exit Exit from CLI (log out) + factory-reset Restore the system to factory default state + follow Monitor a log file, use Ctrl-C to abort + help Help system (try also the '?' key) + logout Alias to exit + netcalc IP subnet calculator, with subnetting + password Password tools + ping Ping a network host or multicast group + poweroff Poweroff system (system policy may yield reboot) + reboot Reboot system + remove Remove a configuration file + set Set operations, e.g., current date/time + show Show system status and configuration files + tcpdump Capture network traffic + upgrade Install a software update bundle from remote or local file +``` + +The system has three *main datastores* (or files): *factory*, *startup*, +and *running* that can be managed and inspected using the `copy`, +`show`, and `configure` commands. The traditional names used in the CLI +for these are listed below: + + - `factory-config` the default configuration from factory for the + device, i.e., what the system returns to after a `factory-reset` + - `startup-config` created from `factory-config` at first boot after + factory reset. Loaded as the system configuration on each boot + - `running-config` what is actively running on the system. If no + changes have been made since boot, 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`. + `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: +Edit the *running* configuration using the `configure` command. This +copies *running* to *candidate*, a temporary datastore, where changes +are made: - admin@host-12-34-56:/> copy running-config startup-config +``` +admin@host-12-34-56:/> configure +admin@host-12-34-56:/config/> ... # Try: Tab or ? +admin@host-12-34-56:/config/> leave +``` + +The `leave` command activates the changes by issuing a transaction to, +essentially, copy the *candidate* back to *running*. Depending on the +changes made, this can take a few seconds. If the changes are invalid, +i.e., not correct according to the underlying YANG models, a warning is +shown and the session remains in configure context. Use the `abort` +command to cancel your changes, or investigate further with the `diff` +command (see more below). + +To save configuration changes made to the `running-config` to persistent +store, so the system will use them for consecutive reboots, use the +`copy` command: + +``` +admin@host-12-34-56:/> copy running-config startup-config +``` In *configure context* the following commands are available: diff --git a/doc/cli/netcalc.md b/doc/cli/netcalc.md new file mode 100644 index 00000000..ec6e65d4 --- /dev/null +++ b/doc/cli/netcalc.md @@ -0,0 +1,62 @@ +## Usage + +``` +netcalc
[split <1-32 | 64-128>] +``` + +## Description + +`netcalc` is a network calculator that takes an IP address and a subnet +mask, or an IP address and prefix mask in CIDR notation, and then returns +information about the subnet. Both IPv4 and IPv6 is supported. + +A subnet can be entered in two ways: + + - `192.168.2.0 255.255.255.0`: traditional IPv4 'address netmask' style + - `192.168.2.0/24`: modern prefix length, same also for IPv6 + +An optional `split LEN` can be given as argument, the new length value +must be bigger than the current prefix length. See example below. + + +## Examples + +Its most commonly used features are to understand how many addresses an +IP subnet has, what the broadcast address is, first and last *usable* +address. + +``` +admin@example:/> netcalc 192.168.2.0/24 +Address : 192.168.2.0 11000000.10101000.00000010. 00000000 +Netmask : 255.255.255.0 = 24 11111111.11111111.11111111. 00000000 +Wildcard : 0.0.0.255 00000000.00000000.00000000. 11111111 +=> +Network : 192.168.2.0/24 11000000.10101000.00000010. 00000000 +HostMin : 192.168.2.1 11000000.10101000.00000010. 00000001 +HostMax : 192.168.2.254 11000000.10101000.00000010. 11111110 +Broadcast: 192.168.2.255 11000000.10101000.00000010. 11111111 +Hosts/Net: 254 Class C, Private network (RFC1918) +``` + +Another common use-case is for IP subnetting, i.e., using only as many +addresses for an IP subnet as needed. Example, to split the above /24 +in four: + +``` +admin@example:/> netcalc 192.168.2.0/24 split 26 +Address : 192.168.2.0 11000000.10101000.00000010. 00000000 +Netmask : 255.255.255.0 = 24 11111111.11111111.11111111. 00000000 +Wildcard : 0.0.0.255 00000000.00000000.00000000. 11111111 +=> +Network : 192.168.2.0/24 11000000.10101000.00000010. 00000000 +HostMin : 192.168.2.1 11000000.10101000.00000010. 00000001 +HostMax : 192.168.2.254 11000000.10101000.00000010. 11111110 +Broadcast: 192.168.2.255 11000000.10101000.00000010. 11111111 +Hosts/Net: 254 Class C, Private network (RFC1918) + +[Split network/26] +Network : 192.168.2.0 - 192.168.2.63 Netmask : 255.255.255.192 +Network : 192.168.2.64 - 192.168.2.127 Netmask : 255.255.255.192 +Network : 192.168.2.128 - 192.168.2.191 Netmask : 255.255.255.192 +Network : 192.168.2.192 - 192.168.2.255 Netmask : 255.255.255.192 +``` diff --git a/doc/cli/quick.md b/doc/cli/quick.md index 8f5838ba..c1bdaad8 100644 --- a/doc/cli/quick.md +++ b/doc/cli/quick.md @@ -19,9 +19,9 @@ 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 | +| `help configure` | How to use configure context | | `help text-editor` | Help with the built-in text-editor command | +| `help keybindings` | Lists keybindings and other helpful tricks | > In `configure` context the `help setting` command shows the YANG > description text for each node and container. To reach the admin diff --git a/doc/cli/tcpdump.md b/doc/cli/tcpdump.md new file mode 100644 index 00000000..c668c5ff --- /dev/null +++ b/doc/cli/tcpdump.md @@ -0,0 +1,91 @@ +## Network Traffic Inspection + +`tcpdump` is useful tool for analyzing and diagnosing network problems. +This document presents the limited feature set that exposed is in the +CLI. Administrator level users with shell access can use the full +feature set, and is not described here. + +The following section is useful for understanding how to use the tool. +A section called [Examples](#examples) follows that, which may be what +you want to scroll down to. + + +### Hardware Overview + +Using `tcpdump` effectively requires an understanding of how the +underlying hardware works. For a standard PC, or common single-board +computers (SBC), the network cards (NICs) are usually connected directly +to the CPU. + + .---------. + | +-- eth0 + | CPU | + | +-- eth1 + '---------' + +In this setup it is evident that traffic coming in on either eth0 or +eth1 reach the CPU, i.e., running `tcpdump eth0` captures all traffic. + +However, on other types of networking hardware, e.g., dedicated switch +core setups depicted below, the flow of network traffic will likely +*not* pass through the CPU. This depends of course on how the switch is +set up, for instance if routing between all ports is enabled, each flow +will reach the CPU, but in a plain switching setup it will not. + + .---------. + | | + | CPU | + | | + '----+----' + | + | + .----------+---------. + | | + ---+ +--- + E1 | SC | E3 + ---+ +--- + E2 | | E4 + '--+--+--+--+--+--+--' + | | | | | | + E5 E6 E7 E8 E9 E10 + +So, running `tcpdump e1` in a switching setup, inside the CPU, the only +traffic that will be captured is traffic ingressing port E1 destined for +the CPU itself. To analyze traffic going through the switch, you need +something called *port mirroring*, or *port monitoring*, i.e., setting +up the switch core to mirror traffic ingressing and/or egressing a set +of ports to another port. On this *monitor port* you can then run your +tcpdump, which means you need an external device (laptop). + +> A planned feature is to support mirroring traffic to the CPU port, +> which would be an effective way to log and monitor traffic over a +> longer period of time. Highly effective for diagnosing intermittent +> and other rare network issues. + +If only "proof of life" is required, then sometimes port counters, also +called *RMON counters*, can be very useful too. Seeing counters of a +particular type increment means traffic is ingressing or egressing. + + +### Examples + +Listen to all traffic on an interface: + + admin@example:/> tcpdump e1 + +Listen to only ping traffic: + + admin@example:/> tcpdump e1 expression icmp + +Listen to traffic on a given port: + + admin@example:/> tcpdump e1 expression "port 80" + +Wait for one ping only: + + admin@example:/> tcpdump e1 count 1 expression icmp + +Very verbose output: + + admin@example:/> tcpdump e1 verbose + diff --git a/doc/cli/upgrade.md b/doc/cli/upgrade.md new file mode 100644 index 00000000..9586da85 --- /dev/null +++ b/doc/cli/upgrade.md @@ -0,0 +1,45 @@ +Upgrading the Software +---------------------- + +The admin-exec command `upgrade` can be used to install software images, or +bundles. A bundle is a signed and self-contained package that carries all the +information necessary to determine if it holds a bootloader, a Linux image, or +even both. + +To install a new software image to the currently *inactive* partition[^1], we +use the `upgrade` command and a URI to a ftp/tftp/sftp or http/https server +that hosts the file: + +``` +admin@host:/> upgrade tftp://192.168.122.1/firmware-x86_64-v23.11.pkg +installing + 0% Installing + 0% Determining slot states + 20% Determining slot states done. + 20% Checking bundle + 20% Verifying signature + 40% Verifying signature done. + 40% Checking bundle done. + 40% Checking manifest contents + 60% Checking manifest contents done. + 60% Determining target install group + 80% Determining target install group done. + 80% Updating slots + 80% Checking slot rootfs.1 + 90% Checking slot rootfs.1 done. + 90% Copying image to rootfs.1 + 99% Copying image to rootfs.1 done. + 99% Updating slots done. +100% Installing done. +Installing `tftp://192.168.122.1/firmware-x86_64-v23.11.pkg` succeeded +admin@host:/> +``` + +The secondary partition (`rootfs.1`) has now been upgraded and will be used as +the *active* partition on the next boot. Leaving the primary partition, with +the version we are currently running, intact in case of trouble. + +[^1]: It is not possible to upgrade the partition we booted from. Thankfully + the underlying "rauc" subsystem keeps track of this. Hence, to upgrade + both partitions you must reboot to the new version (to verify it works) + and then repeat the same command. diff --git a/src/klish-plugin-infix/xml/infix.xml b/src/klish-plugin-infix/xml/infix.xml index 3c1b6058..3cf3409f 100644 --- a/src/klish-plugin-infix/xml/infix.xml +++ b/src/klish-plugin-infix/xml/infix.xml @@ -123,10 +123,14 @@ + configure introduction keybindings + netcalc + quick + tcpdump text-editor - tutorial + upgrade @@ -135,7 +139,7 @@ if [ -f "$fn" ]; then lowdown -t term --term-vmargin=1 "$fn" else - echo "Topic not available." + echo "Help topic not available, try help without an argument, or tap '?' for a list." fi @@ -431,10 +435,22 @@ - + - netcalc $KLISH_PARAM_addrlen $KLISH_PARAM_netmask + + + if [ -n "$KLISH_PARAM_split" ]; then + if echo $KLISH_PARAM_addrlen |grep -q ':'; then + split="-S $KLISH_PARAM_split" + else + split="-s $KLISH_PARAM_split" + fi + else + split="" + fi + netcalc $split $KLISH_PARAM_addrlen $KLISH_PARAM_netmask +