diff --git a/README.md b/README.md index 50949801..d19ce1ed 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,16 @@ [![License Badge][]][License] [![Coverity Status][]][Coverity Scan] [![Discord][discord-badge]][discord-url] Infix - Linux <3 NETCONF -
Documentation - - - **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](doc/license.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 is a free, Linux based, immutable Network Operating System (NOS) built on [Buildroot][1], and [sysrepo][2]. A powerful mix that ease porting to different platforms, simplify long-term maintenance, and -provide made-easy management using NETCONF[^1] or the built-in [command -line interface (CLI)][3] from a console or SSH login. *Click the -foldout (▶ Example CLI Session) below for an example.* +provide made-easy management using NETCONF[^1] or the built-in command +line interface (CLI) from a console or SSH login. + +> Click the **▶ Example CLI Session** foldout below for an example, or +> head on over to the [Infix Documentation](doc/README.md) for more +> information on how to set up the system. Although primarily focused on switches and routers, the core values may be appealing for other use-cases as well: diff --git a/doc/README.md b/doc/README.md deleted file mode 120000 index 3c9aa0d2..00000000 --- a/doc/README.md +++ /dev/null @@ -1 +0,0 @@ -variant.md \ No newline at end of file diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000..6ee3cf45 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,33 @@ + +Welcome to Infix, your friendly Network Operating System! On these +pages you can find both user and developer documentation. + +> Topics on configuring the system include CLI examples, every setting +> is also possible to perform using NETCONF. In fact, the Infix test +> system solely relies on NETCONF for configuring network topologies. + +The CLI documentation is also available from inside the CLI itself using +the `help` command. + +- **CLI Topics** + - [Introduction to the CLI](cli/introduction.md) + - [CLI User's Guide](cli/tutorial.md) + - [Quick Overview](cli/quick.md) + - **Infix User Guide** + - [Network Configuration](networking.md) + - **Infix In-Depth** + - [Boot Procedure](boot.md) + - [Branding & Releases](branding.md) + - [Containers in Infix](container.md) + - [Find Your Device on the Network](discovery.md) + - [Hardware Info & Status](hardware.md) + - [Infix Variants](variant.md) + - [Virtual Environments](virtual.md) + - [Vital Product Data (VPD)](vpd.md) + - [YANG to Ethtool Mapping](eth-counters.md) + - [Origin & Licensing](license.md) + - **Developer Topics** + - [Developer's Guide](developers-guide.md) + - [Developing with Infix](override-package.md) + - [Regression Testing with Infamy](testing.md) + diff --git a/doc/eth-counters.md b/doc/eth-counters.md index f0a55e29..2e9e3fad 100644 --- a/doc/eth-counters.md +++ b/doc/eth-counters.md @@ -1,4 +1,5 @@ # YANG to Ethtool Mapping + This column contains the mapping between YANG and Linux / Ethtool counters. ``` diff --git a/doc/networking.md b/doc/networking.md index 74df1c1b..28da1f2f 100644 --- a/doc/networking.md +++ b/doc/networking.md @@ -1,4 +1,4 @@ -# Linux Networking +# Network Configuration Infix aims to support all Linux Networking constructs. The YANG models used to describe the system are chosen to fit well and leverage the diff --git a/doc/testing.md b/doc/testing.md index a6e71a97..d5c5183d 100644 --- a/doc/testing.md +++ b/doc/testing.md @@ -1,5 +1,5 @@ -Testing -======= +Regression Testing with Infamy +============================== Infix comes with a test suite that is intended to provide end-to-end verification of supported features. Generally speaking, this means diff --git a/doc/variant.md b/doc/variant.md index 2f2fc7e0..2f0415c3 100644 --- a/doc/variant.md +++ b/doc/variant.md @@ -1,13 +1,11 @@ Infix Variants ============== -Infix has two main *flavors*. Both have a default `admin` account, -which is allowed to log in from remote, default password `admin` -- +Infix comes in two *flavors*. Both have a default `admin` account, +allowed to log in from remote, with the 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 ------- @@ -27,22 +25,23 @@ using the built-in [CLI](cli/introduction.md)[^1]. > 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. +For more information, see [Containers in Infix](container.md). + +[^1]: A [RESTCONF][7] 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. +Infix Classic is very much like a traditional embedded Linux system. +Stripped down, single read-only image, reusing the same Linux kernel and +Buildroot base as the NETCONF variant. Unlike the NETCONF variant, it +is up to the administrator to manually modify system configuration files +in `/etc`[^2] and control 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. @@ -50,103 +49,13 @@ tool. See the online help command for an introduction to the system and help on available tools, like text editors, network debugging, etc. +> **Note:** the Classic builds are legacy at this point. They were +> initially used for educational purposes, and sometimes as slightly +> more useful end-devices in GNS3. Little to no testing is done on +> them and they may eventually be migrated to a separate repository. -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). - -> **Note:** a vanilla Infix build does not support Hybrid Mode out of -> the box. You can enable it, and build your own images by adding the -> following line to `board/common/rootfs/etc/finit.conf`: -> -> runparts /cfg/start.d -> -> See the [Developer's Guide](developers-guide.md) for a build HowTo. - - -### 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. - -### Customizing Services - -When running containers a common question is: "what if we want an outside -SSH connection on port 22 to be forwarded to the container instead of the -Infix system?" There are two possible answers that currently require a -Hybrid Mode fix since it is not yet possible to configure the SSH daemon: - - 1. Disable SSH daemon - 2. Run SSH daemon on another port - -The first one is simple, use what you have learned above about start.d -scripts and add one that does `initctl disable sshd`. - -The second is a little bit more involved: - -``` -root@infix:/cfg/start.d$ cat <10-custom-sshd-port.sh -#!/bin/sh -echo SSHD_OPTS=\"-p222\" > /etc/default/sshd -EOF -root@infix:/cfg/start.d$ chmod +x 10-custom-sshd-port.sh -``` - - +[^2]: In Classic builds the `/etc` directory is saved across reboots on + a separate read-write partition. [1]: https://www.sysrepo.org/ [2]: https://github.com/CESNET/netopeer @@ -154,6 +63,5 @@ root@infix:/cfg/start.d$ chmod +x 10-custom-sshd-port.sh [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 +[7]: https://datatracker.ietf.org/doc/html/rfc8040