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: split CLI tutorial into multile files

Browse Source 
Fixes #455

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2024-06-28 12:54:27 +02:00
parent f1585476da
commit 1fac47a728
8 changed files with 315 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/README.md
+2 -1
View File
@@ -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)
doc/cli/tutorial.md → doc/cli/configure.md
-110
View File
@@ -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
doc/cli/introduction.md
+93 -19
View File
@@ -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:
doc/cli/netcalc.md
+62
View File
@@ -0,0 +1,62 @@
## Usage
```
netcalc <ADDRESS/LEN | NETWORK NETMASK> [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
```
doc/cli/quick.md
+2 -2
View File
@@ -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
doc/cli/tcpdump.md
+91
View File
@@ -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
doc/cli/upgrade.md
+45
View File
@@ -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.
src/klish-plugin-infix/xml/infix.xml
+20 -4
View File
@@ -123,10 +123,14 @@
<COMMAND name="help" help="Help system (try also the '?' key)">
<PARAM name="topic" ptype="/STRING" min="0" help="Help topic">
<COMPL>
<ACTION sym="printl">configure</ACTION>
<ACTION sym="printl">introduction</ACTION>
<ACTION sym="printl">keybindings</ACTION>
<ACTION sym="printl">netcalc</ACTION>
<ACTION sym="printl">quick</ACTION>
<ACTION sym="printl">tcpdump</ACTION>
<ACTION sym="printl">text-editor</ACTION>
<ACTION sym="printl">tutorial</ACTION>
<ACTION sym="printl">upgrade</ACTION>
</COMPL>
</PARAM>
<ACTION sym="script">
@@ -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
</ACTION>
</COMMAND>
@@ -431,10 +435,22 @@
</ACTION>
</COMMAND>
<COMMAND name="netcalc" help="IP subnet calculator">
<COMMAND name="netcalc" help="IP subnet calculator, with subnetting">
<PARAM name="addrlen" ptype="/STRING" help="ADDRESS[/LEN]"/>
<PARAM name="netmask" ptype="/STRING" min="0" help="Optional NETMASK"/>
<ACTION sym="script">netcalc $KLISH_PARAM_addrlen $KLISH_PARAM_netmask</ACTION>
<PARAM name="split" ptype="/UINT" min="0" help="Split network: 1-32 (IPv4), 1-128 (IPv6)"/>
<ACTION sym="script">
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
</ACTION>
</COMMAND>
<COMMAND name="ping" help="Ping a network host or multicast group">