diff --git a/README.md b/README.md index 2e6eb4b9..1816e2ff 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ Infix Linux Networking Made Easy * [Introduction](#introduction) +* [NETCONF Mode](#netconf-mode) + * [NETCONF Mode](#netconf-mode) + * [Classic Mode](#classic-mode) + * [Hybrid Mode](#hybrid-mode) * [Hardware](#hardware) * [Qemu](#qemu) * [GNS3](#gns3) @@ -19,40 +23,50 @@ networked equipment. > See the [GitHub Releases](https://github.com/kernelkit/infix/releases) > page for out pre-built images. The *Latest Build* has the bleeding edge > images, if possible we recommend using a versioned release. +> +> For customer specific builds of Infix, see your respective repository. Infix has two main *flavors*, or defconfigs: - - **NETCONF:** the default, is configured using the `cli` tool, or any - external NETCONF client, after boot. It uses sysrepo as the data - store to generate configuration files in `/etc` and control the - system daemons, e.g., enable DHCP client on an interface. + - **NETCONF:** the default, managed using, e.g., the `cli` tool + - **Classic:** built from `$ARCH_classic_defconfig`, more below - - **Classic:** built from `$ARCH_classic_defconfig`. Here it is up to - the administrator to modify configuration files in `/etc` and control - the system daemons using the `initctl` tool. After login, see the - online `help` command for an introduction to the system. - -Both flavors have a `root` user, which is only allowed to log in from -the console port, no password by default on standard builds. There is -also a `factory` user, password `reset`, to perform factory reset on -systems that do not have a reset button. - -Additionally, the standard builds also have an `admin` user, which is -allowed to log in from remote, password `admin` on standard builds. It -is the recommended account to use for managing Infix. +Both flavors have an `admin` user, which is allowed to log in from +remote, password `admin` on standard builds. It is the recommended +account to use for managing Infix. (The `root` account is currently +also available, but will soon become a non-login account used only for +running system services.) -Hybrid Mode ------------ +### NETCONF Mode -Since Infix is under heavy development, it does not yet have all its -bells and whistles in place, in particular the default build. To that -end it is possible to manually manage certain services that are not yet +NETCONF is the primary reason Infix exists. Configuration of an Infix +device can be done either remotely, using tools like [netconf-client][] +or [netopeer2-cli][], or locally using the [`cli` tool](doc/cli.md). + +Infix use [sysrepo][6] as the data store for NETCONF. A set of plugins +configure the network, using iproute2, generate configuration files in +`/etc`, and control the system daemons, e.g., enable DHCP client on an +interface. + + +### Classic Mode + +Here it is up to the administrator to modify configuration files in +`/etc` and control the system daemons using the `initctl` tool. + +See the online `help` command for an introduction to the system. + + +### Hybrid Mode + +Since Infix is under heavy development, it does not yet have all bells +and whistles in place, in particular in the default build. To that end +it is possible to manually manage certain services that are not yet possible to configure using NETCONF. -At bootstrap Finit can optionally start scripts from a [run-parts(8)][] -like directory: `/cfg/start.d`. To enable this mode, see the following -examples: +At bootstrap Finit can start user scripts from a [run-parts(8)][] like +directory: `/cfg/start.d`. For example, the following starts OSPF: ```sh root@infix:~$ mkdir /cfg/start.d @@ -192,9 +206,12 @@ any GPL[^1] licensed library. [5]: https://lwn.net/Articles/117972/ [6]: https://www.sysrepo.org/ [7]: https://github.com/wkz/qeneth +[8]: https://addiva-elektronik.github.io/2023/05/12/using-netconf-client-and-server-to-update-switch-configuration/ [9]: https://docs.gns3.com/docs/using-gns3/beginners/import-gns3-appliance/ [QEMU]: https://www.qemu.org/ [GNS3]: https://gns3.com/ [training]: https://addiva-elektronik.github.io/ [manual]: https://buildroot.org/downloads/manual/manual.html [run-parts(8)]: https://manpages.ubuntu.com/manpages/trusty/man8/run-parts.8.html +[netconf-client]: https://pypi.org/project/netconf-client/ +[netopeer2-cli]: https://github.com/CESNET/netopeer2 diff --git a/doc/cli.md b/doc/cli.md new file mode 100644 index 00000000..c0d0b6aa --- /dev/null +++ b/doc/cli.md @@ -0,0 +1,139 @@ +CLI User Guide +============== + +The Infix CLI is built on the [klish project][1], which is a framework +for implementing a CISCO, or Juniper Networs JunOS-like CLI on a UNIX +systems. + +Currently, when the `admin` user logs in the default shell is Bash. To +access the CLI, type: + + cli + +Key commands available in any context are: + + help + show + +For each command it is also possible to press the `?` key and `TAB` to +get more help and suggestions for completion. + + +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: + +``` +root@infix-12-34-56:exec> + configure Create new candidate-config based on running-config + copy Copy + exit Exit + logout Alias for exit + shell Enter system shell + show Show +``` + +Configure Context +----------------- + +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> + abort Abandon candidate + check Validate candidate + commit Commit current candidate to running-config + delete Delete configuration setting(s) + diff Summarize uncommitted changes + do Execute operational mode command + edit Descend to the specified configuration node + exit Ascend to the parent configuration node, or abort (from top) + leave Finalize candidate and apply to running-config + no Alias for delete + rollback Restore candidate to running-config + set Set configuration setting + 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.: + +``` +root@infix-12-34-56:configure> edit interfaces interface eth0 +[edit interfaces interface eth0] +``` + +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 +[edit] +``` + +### Set IP Address on an Interface + +``` +root@infix-12-34-56:configure> +[edit] +root@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 +[edit interfaces interface eth0] +``` + +From anywhere in configure context you can see the changes you have +made by typing `diff`: + +``` +root@infix-12-34-56:configure> diff +interfaces { + interface eth0 { ++ ipv4 { ++ address 192.168.2.200 { ++ prefix-length 24; ++ } ++ } + } +} +``` + +### Saving Changes + +Apply the changes (from candidate to running): + +``` +root@infix-12-34-56:configure> leave +root@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: + +``` +root@infix-12-34-56:exec> copy running-config startup-config +``` + +> **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