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: refactor, let first page be table of contents

Browse Source 
- Drop doc/README.md symlink to variant.md
 - Make doc/README.md the table of contents
 - Clean up variant.md, OSPF and containers now fully supported

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2024-03-22 05:34:36 +01:00
parent b2fef1585f
commit 2eb487ebcd
6 changed files with 60 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+6 -19
View File
@@ -1,29 +1,16 @@
[![License Badge][]][License] [![Coverity Status][]][Coverity Scan] [![Discord][discord-badge]][discord-url]
<img align="right" src="doc/logo.png" alt="Infix - Linux <3 NETCONF" width=480 border=10>
<details><summary><b>Documentation</b></summary>
- **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)
</details>
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:
doc/README.md
-1
View File
@@ -1 +0,0 @@
variant.md
doc/README.md
+33
View File
@@ -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)
doc/eth-counters.md
+1
View File
@@ -1,4 +1,5 @@
# YANG to Ethtool Mapping
This column contains the mapping between YANG and Linux / Ethtool counters.
```
doc/networking.md
+1 -1
View File
@@ -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
doc/testing.md
+2 -2
View File
@@ -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
doc/variant.md
+17 -109
View File
@@ -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 <kbd>factory</kbd>
tool.
@@ -50,103 +49,13 @@ tool.
See the online <kbd>help</kbd> 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 <<EOF >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 <<EOF >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 <<EOF >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