diff --git a/README.md b/README.md index 8148d77c..86de6bb8 100644 --- a/README.md +++ b/README.md @@ -1,178 +1,48 @@ -Infix Linux Networking Made Easy - -* [Introduction](#introduction) - * [NETCONF Mode](#netconf-mode) - * [Classic Mode](#classic-mode) - * [Hybrid Mode](#hybrid-mode) -* [Hardware](#hardware) -* [Qemu](#qemu) -* [GNS3](#gns3) -* [Building](#building) -* [Testing](doc/testing.md) -* [Docker Image](test/docker/README.md) -* [Origin & Licensing](origin--licensing) - +Linux Networking Made Easy Introduction ------------ -Infix is an embedded Linux Network Operating System (NOS) based on -[Buildroot][1], [Finit][2], [ifupdown-ng][3], and [sysrepo][6]. -Providing an easy-to-maintain and easy-to-port Open Source base for -networked equipment. +Infix is a Linux Network Operating System (NOS) based on [Buildroot][1], +and [sysrepo][2]. A powerful mix that ease porting to different target +platforms, simplify long-term maintenance, and also provide made-easy +management using NETCONF[^1]. + +Infix can run on many different types of architectures and boards, much +thanks to Linux and Buildroot. Currently the focus is on 64-bit ARM +devices, optionally with switching fabric supported by Linux switchdev. +The [following boards](board/aarch64/README.md) are fully supported: + + - Marvell CN9130 CRB + - Marvell EspressoBIN + - Microchip SparX-5i PCB135 (eMMC) + +An x86_64 build is also available, primarily intended for development +and testing, but can also be used for evaluation and demo purposes. For +more information, see: [Infix in Virtual Environments](doc/virtual.md). > 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. +> page for our 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, managed using, e.g., the `cli` tool - - **Classic:** built from `$ARCH_classic_defconfig`, more below - -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.) +> For *customer specific builds* of Infix, see your product repository. -### NETCONF Mode +Topics +------ -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). + - **CLI Topics** + - [Introduction to the CLI](doc/cli/introduction.md) + - [CLI User's Guide](doc/cli/tutorial.md) + - [Quick Overview](doc/cli/quick.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 start user scripts from a [run-parts(8)][] like -directory: `/cfg/start.d`. For example, the following starts OSPF: - -```sh -root@infix:~$ cp -a /etc/frr /cfg/ -root@infix:~$ mkdir /cfg/start.d -root@infix:~$ cd /cfg/start.d -root@infix:/cfg/start.d$ cat <10-enable-ospf.sh -#!/bin/sh -# Use vtysh to modify the OSPF configuration -mount --bind /cfg/frr /etc/frr -initctl enable zebra -initctl enable ospfd -initctl enable bfdd -(sleep 1; vtysh -b)& -exit 0 -EOF -root@infix:/cfg/start.d$ chmod +x 10-enable-ospf.sh -``` - -This is also the way to start containers (provided the images have been -downloaded with `podman pull` first): - -``` -root@infix:/cfg/start.d$ cat <20-enable-container.sh -#!/bin/sh -podman-service -e -d "Nginx container" -p "-p 80:80 -v /cfg/www:/usr/share/nginx/html:ro" nginx:alpine -exit 0 -EOF -root@infix:/cfg/start.d$ chmod +x 20-enable-container.sh -``` - -Reboot to activate the changes. To activate the changes without -rebooting, run the script and call `initctl reload`. - -> **Note:** Neither [Frr](https://frrouting.org) (Zebra/OSPF/BFD) or -> [podman](https://podman.io) are enabled in default Infix builds. Some -> customers have them enabled in their specific builds, and you can also -> enable it yourself in Infix by using `make menuconfig` followed by -> rebuilding the image. - -For more information, see [Containers in Infix](doc/container.md). - - -Hardware --------- - -### aarch64 - -By default, Infix builds with support for the following boards (you -may enable additional boards in the config, of course): - -- Marvell CN9130 CRB -- Marvell EspressoBIN -- Microchip SparX-5i PCB135 (eMMC) - -See the aarch64 specific [documentation](board/aarch64/README.md) for more -information. - -### x86_64 - -Primarily intended to be run under [QEMU][] for development & test as -well as evaluation, demo and [training][] purposes, e.g. using [GNS3][] -or [Qeneth][7]. - - -QEMU ----- - -A virtualized instance can easily be launched from a Linux system, with -Qemu installed, by issuing `make run`. - -Some settings, e.g. networking, can be configured via `make menuconfig` -under `External options -> QEMU virtualization`. - - -GNS3 ----- - -Download the [latest build][0] of the `x86_64`, or `x86_64_classic` -flavor. Unpack in a dedicated directory and use ["Import Appliance"][9] -to install the `.gns3a` file into GNS3. Infix (`x86_64`) is in the -"Router" category, it has 10 interfaces available by default for use as -switch ports or routing. The *classic* build only has one interface by -default, geared more towards acting as an end device. - - -Building --------- - -Buildroot is almost stand-alone, but need a few locally installed tools -to bootstrap itself. For details, see the [excellent manual][manual]. - -Briefly, to build an Infix image; select the target and then make: - - make x86_64_defconfig - make - -Online help is available: - - make help - -To see available defconfigs for supported targets, use: - - make list-defconfigs - -> **Note:** build dependencies (Debian/Ubuntu): sudo apt install make libssl-dev + - **Infix In-Depth** + - [Infix Variants](doc/variant.md) + - [Boot Procedure](doc/boot.md) + - [Containers in Infix](doc/container.md) + - [Developer's Guide](doc/developers-guide.md) + - [Discover Your Device](doc/discovery.md) + - [Virtual Environments](doc/virtual.md) Origin & Licensing @@ -197,26 +67,15 @@ Infix releases include the license information covering all Open Source packages. This is extracted automatically at build time using the tool `make legal-info`. Any proprietary software built on top of Infix, or Buildroot, would need separate auditing to ensure it does not link with -any GPL[^1] licensed library. +any GPL[^2] licensed library. -[^1]: Infix image builds use GNU libc (GLIBC) which is covered by the - [LGPL][4]. The LGPL *does allow* proprietary software, as long as +[^1]: or RESTCONF, , for + mode information, see [Infix Variants](doc/variant.md). +[^2]: Infix image builds use GNU libc (GLIBC) which is covered by the + [LGPL][8]. The LGPL *does allow* proprietary software, as long as said software is linking dynamically, [not statically][5], to GLIBC. -[0]: https://github.com/kernelkit/infix/releases/tag/latest [1]: https://buildroot.org/ -[2]: https://github.com/troglobit/finit -[3]: https://github.com/ifupdown-ng/ifupdown-ng -[4]: https://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License +[2]: https://www.sysrepo.org/ [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 +[8]: https://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License diff --git a/doc/developers-guide.md b/doc/developers-guide.md new file mode 100644 index 00000000..a5a57cb7 --- /dev/null +++ b/doc/developers-guide.md @@ -0,0 +1,29 @@ +Developer's Guide +================= + +Building +-------- + +Buildroot is almost stand-alone, it needs a few locally installed tools +to bootstrap itself. For details, see the [excellent manual][manual]. + +Briefly, to build an Infix image; select the target and then make: + + make x86_64_defconfig + make + +Online help is available: + + make help + +To see available defconfigs for supported targets, use: + + make list-defconfigs + +> **Note:** build dependencies (Debian/Ubuntu): sudo apt install make libssl-dev + + +[manual]: https://buildroot.org/downloads/manual/manual.html + + +[7]: https://github.com/wkz/qeneth diff --git a/doc/image921-scaled.png b/doc/image921-scaled.png new file mode 100644 index 00000000..d0781142 Binary files /dev/null and b/doc/image921-scaled.png differ diff --git a/doc/image930-scaled.png b/doc/image930-scaled.png new file mode 100644 index 00000000..8a82d4f7 Binary files /dev/null and b/doc/image930-scaled.png differ diff --git a/doc/variant.md b/doc/variant.md new file mode 100644 index 00000000..ddcecffa --- /dev/null +++ b/doc/variant.md @@ -0,0 +1,126 @@ +Infix Variants +============== + +Infix has two main *flavors*. Both have a default `admin` account, +which is allowed to log in from remote, default password `admin` -- +*customer specific builds* may have something else, e.g., per-device +generated factory password. + +> See [Infix Discovery](discovery.md) to locate your device. + + +NETCONF +------- + +Infix use by [sysrepo][1] and [Netopeer][2] to provide NETCONF support. +A set of sysrepo plugins configure the network, using the Linux iproute2 +tool suite, generate configuration files in `/etc`, and control the all +system daemons, e.g., enable DHCP client on an interface. + +Configuration of an Infix device can be done remotely, using command +line tools like [netconf-client][3] and [netopeer2-cli][2], or desktop +GUI tools like [NETCONFc][4] and [MG-SOFT NetConf Browser][5]. It is +also possible to log in to the device using SSH and set it up locally +using the built-in [CLI](cli/introduction.md)[^1]. + +> **Note:** unlike Infix Classic, the `/etc` directory is a volatile RAM +> disk populated on each boot from the `startup-config`, ensuring a +> coherent centralized view of the system. + +[^1]: A [RESTCONF][] based WebUI is also in progress. + + +Classic +------- + +Infix Classic is very much like a traditional embedded Linux system. It +use the same kernel as NETCONF builds, but unlike them it is up to the +administrator to manually modify system configuration files in `/etc` +and control the system services using the `initctl` tool. + +For example, networking is configured by editing the [ifupdown-ng][6] +files in `/etc/network/interfaces`. + +> In Classic builds the `/etc` directory is saved across reboots. + +To perform a factory reset, wiping all changes in `/etc`, and all other +areas of the file system that are persistent, use the factory +tool. + +See the online help command for an introduction to the system +and help on available tools, like text editors, network debugging, etc. + + +Hybrid Mode +----------- + +Since Infix is under heavy development, it does not yet have all bells +and whistles in place in the NETCONF builds. To that end it is possible +to manually manage certain properties and services. It's a little bit +tricky since any changes to the `/etc` directory is lost at reboot. + +To work around that we use the [run-parts(8)][] feature of the system, +available in some customer specific images. The system runs any user +scripts in `/cfg/start.d` before leaving runlevel S (bootstrap). + +### Starting OSPF + +For example, the following starts OSPF: + +```sh +root@infix:~$ cp -a /etc/frr /cfg/ +root@infix:~$ mkdir /cfg/start.d +root@infix:~$ cd /cfg/start.d +root@infix:/cfg/start.d$ cat <10-enable-ospf.sh +#!/bin/sh +# Use vtysh to modify the OSPF configuration +mount --bind /cfg/frr /etc/frr +initctl enable zebra +initctl enable ospfd +initctl enable bfdd +(sleep 1; vtysh -b) & +exit 0 +EOF +root@infix:/cfg/start.d$ chmod +x 10-enable-ospf.sh +``` + +The `/cfg` area is persistent across reboots. Here we assume the user +has already created the `/cfg/frr` directory, populated it with the +original files from `/etc/frr`, and then modified the appropriate files +to enable OSPF and BFD. + +### Starting Containers + +Using `/cfg/start.d` is also the way to start containers (provided the +images have been downloaded with `podman pull` first): + +``` +root@infix:/cfg/start.d$ cat <20-enable-container.sh +#!/bin/sh +podman-service -e -d "Nginx container" -p "-p 80:80 -v /cfg/www:/usr/share/nginx/html:ro" nginx:alpine +exit 0 +EOF +root@infix:/cfg/start.d$ chmod +x 20-enable-container.sh +``` + +Reboot to activate the changes. To activate the changes without +rebooting, run the script and call `initctl reload`. + +For more information, see [Containers in Infix](container.md). + +> **Note:** Neither [Frr](https://frrouting.org) (Zebra/OSPF/BFD) or +> [podman](https://podman.io) are enabled in the official Infix builds. +> Some customers have them enabled in their specific builds, and you can +> of course also enable it yourself in Infix by using `make menuconfig` +> followed by rebuilding the image. + + +[1]: https://www.sysrepo.org/ +[2]: https://github.com/CESNET/netopeer +[3]: https://pypi.org/project/netconf-client/ +[4]: http://www.seguesoft.com/index.php/netconfc/ +[5]: https://www.mg-soft.si/mgNetConfBrowser.html +[6]: https://github.com/ifupdown-ng/ifupdown-ng +[run-parts(8)]: https://manpages.ubuntu.com/manpages/trusty/man8/run-parts.8.html +[RESTCONF]: https://datatracker.ietf.org/doc/html/rfc8040 + diff --git a/doc/virtual.md b/doc/virtual.md new file mode 100644 index 00000000..16b56aeb --- /dev/null +++ b/doc/virtual.md @@ -0,0 +1,57 @@ +Infix in Virtual Environments +============================= + +Infix primarily targets real hardware, deployment to the cloud is not a +priority at the moment. However, for development and testing purposes +there is an `x86_64` build that runs in [Qemu][]. + +These images also work with the Graphical Network Simulator ([GNS3][]), +which is a very user-friendly tool for playing around with simple to +complex network setups, verifying interoperability between vendors, etc. + + +QEMU +---- + +> **Note:** installation for Debian/Ubuntu based systems: sudo apt +> install virt-manager -- dependencies ensure the relevant Qemu +> packages are pulled in as well. Installing [virt-manager][virt] helps +> set up Qemu networking on your system. + +A virtualized Infix x86_64 instance can easily be launched from a Linux +system, with [Qemu][] installed, by issuing: + + ./qemu.sh + +from an unpacked [release tarball][rels]. From a built source tree of +Infix the same functionality is bundled as: + + make run + +To change settings, e.g. networking, make run-menuconfig, or +from a pre-built Infix release tarball, using ./qemu.sh -c + +The Infix test suite is built around Qemu and [Qeneth][qeth], see: + + * [Testing](doc/testing.md) + * [Docker Image](test/docker/README.md) + + +GNS3 +---- + +Download the [latest build][rels] of the `x86_64`, or `x86_64_classic` +flavor. Unpack the tarball in a dedicated directory and use ["Import +Appliance"][APPL] to install the `.gns3a` file into [GNS3][]. + +Infix (`x86_64`) is in the "Router" category, it has with 10 interfaces +available by default for use as switch ports or routing. The *classic* +build only has one interface by default, geared more towards acting as +an end device. + +[Qemu]: https://www.qemu.org/ +[GNS3]: https://gns3.com/ +[virt]: https://virt-manager.org/ +[rels]; https://github.com/kernelkit/infix/releases +[qeth]: https://github.com/wkz/qeneth +[APPL]: https://docs.gns3.com/docs/using-gns3/beginners/import-gns3-appliance/