From a491f2a88be4427e71ef189aba75189ccd7f5b44 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Sat, 12 Jul 2025 15:14:15 +0200 Subject: [PATCH] doc: minor syntax changes/cleanup, rephrase + use admonitions Signed-off-by: Joachim Wiberg --- doc/boot.md | 44 +++++++++++++++++------------------------ doc/cli/configure.md | 17 ++++++++-------- doc/cli/introduction.md | 3 ++- doc/cli/netcalc.md | 6 +++--- doc/cli/tcpdump.md | 6 +++--- doc/cli/upgrade.md | 3 +-- doc/container.md | 30 +++------------------------- doc/license.md | 2 +- doc/management.md | 2 +- doc/override-package.md | 15 ++++++++------ doc/syslog.md | 12 +++++------ doc/virtual.md | 4 ++-- 12 files changed, 57 insertions(+), 87 deletions(-) diff --git a/doc/boot.md b/doc/boot.md index 650353fe..ecd2cd73 100644 --- a/doc/boot.md +++ b/doc/boot.md @@ -67,15 +67,15 @@ minimum. Two settings are available: sources are considered can be configured. To select the active source, use [RAUC][]: - `rauc status mark-active ` + rauc status mark-active - Where `` is one of: + Where `` is one of: - | `` | Source | - |----------|---------------------------| - | rootfs.0 | Primary partition | - | rootfs.1 | Secondary partition | - | net.0 | Netboot (where supported) | + | `` | Source | + |------------|---------------------------| + | `rootfs.0` | Primary partition | + | `rootfs.1` | Secondary partition | + | `net.0` | Netboot (where supported) | - **Debug**: By default, the kernel will only output errors to the console during boot. Optionally, this can be altered such that all @@ -126,7 +126,7 @@ Interface](#bootloader-interface). System Upgrade -============== +-------------- Much of the minutiae of software upgrades is delegated to [RAUC][], which offers lots of benefits out-of-the-box: @@ -160,10 +160,9 @@ same upgrade command again will bring both partitions into sync. Image Formats -============= +------------- -SquashFS Image --------------- +### SquashFS Image **Canonical Name**: `rootfs.squashfs` @@ -176,8 +175,7 @@ virtual instance of Infix. [initrd]: https://docs.kernel.org/admin-guide/initrd.html -FIT Framed Squash Image ------------------------ +### FIT Framed Squash Image **Canonical Name**: `rootfs.itb` @@ -219,8 +217,7 @@ the information needed by U-Boot in a single file. [FIT]: https://u-boot.readthedocs.io/en/latest/usage/fit.html -RAUC Upgrade Bundle -------------------- +### RAUC Upgrade Bundle **Canonical Name**: `infix-${ARCH}.pkg` @@ -233,8 +230,7 @@ When performing a [System Upgrade](#system-upgrade), this is the format to use. -Disk Image ----------- +### Disk Image **Canonical Name**: `disk.img` @@ -264,7 +260,7 @@ scheme. Partitions marked with an asterisk are optional. | | '-----------' -### `boot` - Bootloader +**`boot` - Bootloader** | Parameter | Value | |-----------|-----------------------------------------| @@ -278,8 +274,7 @@ in a separate storage device, e.g. a serial FLASH. On x86_64, this partition holds the EFI system partition, containing the GRUB bootloader. - -### `aux` - Auxiliary Data +**`aux` - Auxiliary Data** | Parameter | Value | |-----------|-----------------| @@ -307,8 +302,7 @@ Note that the bootloader's primary environment is bundled in the binary - `uboot.env` is only used to import a few settings that is required to configure the boot order. - -### `primary`/`secondary` - Root Filesystems +**`primary`/`secondary` - Root Filesystems** | Parameter | Value | |-----------|-------------------| @@ -320,8 +314,7 @@ Holds the [SquashFS Image](#squashfs-image). Two copies exist so that an incomplete upgrade does not brick the system, and to allow fast rollbacks when upgrading to a new version. - -### `cfg` - Configuration Data +**`cfg` - Configuration Data** | Parameter | Value | |-----------|-----------------| @@ -332,8 +325,7 @@ rollbacks when upgrading to a new version. Non-volatile storage of the system configuration and user data. Concretely, user data is everything stored under `/root` and `/home`. - -### `var` - Variable Data +**`var` - Variable Data** | Parameter | Value | |-----------|-----------------| diff --git a/doc/cli/configure.md b/doc/cli/configure.md index 23cad3bb..caf5acb0 100644 --- a/doc/cli/configure.md +++ b/doc/cli/configure.md @@ -1,5 +1,4 @@ -Configure Context ------------------ +# CLI Configure Context Enter the configure context from admin-exec by typing `configure` followed by Enter. Available commands, press `?` at the prompt: @@ -48,7 +47,7 @@ admin@host:/config/> > support are common to all systems. -### Set IP Address on an Interface +## Set IP Address on an Interface ``` admin@host:/config/> edit interface eth0 @@ -73,7 +72,7 @@ interfaces { ``` -### Saving Changes +## Saving Changes Apply the changes (from candidate to `running-config`): @@ -108,7 +107,7 @@ verify the changes are saved. > are allowed at the moment. Use the `TAB` key to make this easier. -### Changing Hostname +## Changing Hostname Settings like hostname are located in the `ietf-system.yang` model. Here is how it can be set. @@ -127,7 +126,7 @@ is committed. > advertise the hostname, are restarted when the hostname is changed. -### Changing Password +## Changing Password User management, including passwords, is also a part of `ietf-system`. @@ -154,7 +153,7 @@ then be used with `set password ...`. > strings using the UNIX command `pwgen`. -### SSH Authorized Key +## SSH Authorized Key Logging in remotely with SSH is possible by adding a *public key* to a user. Here we add the authorized key to the admin user, multiple keys @@ -178,7 +177,7 @@ admin@host:/config/system/authentication/user/admin/authorized-key/example@host/ > key data, so there is no need to use the `text-editor` command, `set` > does the job. -### Creating a VETH Pair +## Creating a VETH Pair The following example creates a `veth0a <--> veth0b` virtual Ethernet pair which is useful for connecting, e.g., a container to the physical @@ -219,7 +218,7 @@ See the bridging example below for more. > NETCONF, however, you must include the `veth0b` interface. -### Creating a Bridge +## Creating a Bridge Building on the previous example, we now create a non-VLAN filtering bridge (`br0`) that forwards any, normally link-local, LLDP traffic diff --git a/doc/cli/introduction.md b/doc/cli/introduction.md index 09165c71..968a16e6 100644 --- a/doc/cli/introduction.md +++ b/doc/cli/introduction.md @@ -129,7 +129,8 @@ In *configure context* the following commands are available: | `do command` | Call admin-exec command: `do show log` | | `commit` | | -### Example Session + +## Example Session > Remember to use the `TAB` and `?` keys to speed up your navigation. > See `help keybindings` for more tips! diff --git a/doc/cli/netcalc.md b/doc/cli/netcalc.md index ec6e65d4..8514bb1f 100644 --- a/doc/cli/netcalc.md +++ b/doc/cli/netcalc.md @@ -1,4 +1,4 @@ -## Usage +# Network Calculator ``` netcalc
[split <1-32 | 64-128>] @@ -12,8 +12,8 @@ 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 +- `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. diff --git a/doc/cli/tcpdump.md b/doc/cli/tcpdump.md index c668c5ff..e7f9233a 100644 --- a/doc/cli/tcpdump.md +++ b/doc/cli/tcpdump.md @@ -1,4 +1,4 @@ -## Network Traffic Inspection +# Network Monitoring `tcpdump` is useful tool for analyzing and diagnosing network problems. This document presents the limited feature set that exposed is in the @@ -10,7 +10,7 @@ A section called [Examples](#examples) follows that, which may be what you want to scroll down to. -### Hardware Overview +## Hardware Overview Using `tcpdump` effectively requires an understanding of how the underlying hardware works. For a standard PC, or common single-board @@ -67,7 +67,7 @@ called *RMON counters*, can be very useful too. Seeing counters of a particular type increment means traffic is ingressing or egressing. -### Examples +## Examples Listen to all traffic on an interface: diff --git a/doc/cli/upgrade.md b/doc/cli/upgrade.md index 854c3706..21ecce6a 100644 --- a/doc/cli/upgrade.md +++ b/doc/cli/upgrade.md @@ -1,5 +1,4 @@ -Upgrading the Software ----------------------- +# Upgrading the System 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 diff --git a/doc/container.md b/doc/container.md index 69b00108..9d32ae40 100644 --- a/doc/container.md +++ b/doc/container.md @@ -1,31 +1,7 @@ Containers in Infix =================== -Docker whale -* [Introduction](#introduction) -* [Caution](#caution) -* [Getting Started](#getting-started) - * [Examples](#examples) -* [Container Images](#container-images) -* [Upgrading a Container Image](#upgrading-a-container-image) -* [Networking and Containers](#networking-and-containers) - * [Container Bridge](#container-bridge) - * [Container Host Interface](#container-host-interface) - * [Host Networking](#host-networking) -* [Mounts and Volumes](#mounts-and-volumes) - * [Content Mounts](#content-mounts) -* [Example Containers](#example-containers) - * [System Container](#system-container) - * [Application Container: nftables](#application-container-nftables) - * [Application Container: ntpd](#application-container-ntpd) -* [Advanced](#advanced) - * [Running Host Commands From Container](#running-host-commands-from-container) -* [Container Requirements](#container-requirements) - * [Advanced Users](#advanced-users) - - -Introduction ------------- +![Docker whale](img/docker.webp){ width=360 align="right" } Infix comes with native support for Docker containers using [podman][]. The [YANG model][1] describes the current level of support, complete @@ -111,7 +87,7 @@ your container image and application to run. > virtualization, containers reuse the host's CPU and kernel. -Hello World +![Hello World](img/docker-hello-world.svg){align="right" width="360"} ### Examples @@ -279,7 +255,7 @@ archive, which helps greatly with container upgrades (see below): Upgrading a Container Image --------------------------- -Hello World +![Up-to-date Shield](img/shield-checkmark.svg){align="right" width="100"} The applications in your container are an active part of the system as a whole, so make it a routine to keep your container images up-to-date! diff --git a/doc/license.md b/doc/license.md index 5517dadf..860a78cd 100644 --- a/doc/license.md +++ b/doc/license.md @@ -1,5 +1,5 @@ Origin & Licensing ------------------- +================== Infix is entirely built on Open Source components (packages). Most of them, as well as the build system with its helper scripts and tools, is diff --git a/doc/management.md b/doc/management.md index df8e7a65..47faff6a 100644 --- a/doc/management.md +++ b/doc/management.md @@ -1,4 +1,4 @@ -# Management +# System Management The system utilizes YANG models for keeping configuration and operational data. These databases can be managed through different interfaces such diff --git a/doc/override-package.md b/doc/override-package.md index 262625b7..ca56338a 100644 --- a/doc/override-package.md +++ b/doc/override-package.md @@ -2,9 +2,11 @@ Package Override ================ This guide demonstrates how the `local.mk` file is utilized to override -a Linux Buildroot package. As an example we use `tcpdump` to illustrate -this process. +a Buildroot package, which can be very useful when fixing bugs, adding +features, or evaluating new releases of packages. As an example we use +`tcpdump` to illustrate this process. +> [!TIP] > For a comprehensive guide to utilizing Buildroot during development, > including the `_OVERRIDE_SRCDIR` mechanism, shown below, please > see [Using Buildroot during development][1] in the official docs. @@ -67,9 +69,10 @@ drwxr-xr-x 7 group user 12288 Nov 10 18:28 tcpdump-custom/ As long as your local override is in place, Buildroot will use your custom version. -> **Remember:** the build directory is ephemeral, so be careful to -> change any of the files therein. It can be useful though during -> debugging, but just make sure to learn the difference between the -> various Buildroot commands to build, clean, reconfigure, etc. +> [!NOTE] +> Remember, the build directory is ephemeral, so be careful to change +> any of the files therein. It can be useful though during debugging, +> but just make sure to learn the difference between the various +> Buildroot commands to build, clean, reconfigure, etc. [1]: https://buildroot.org/downloads/manual/manual.html#_using_buildroot_during_development diff --git a/doc/syslog.md b/doc/syslog.md index dbad4e54..dec67019 100644 --- a/doc/syslog.md +++ b/doc/syslog.md @@ -1,4 +1,4 @@ -## Syslog Support +# Syslog Support The system comes with native logging to internal storage, `/var/log/`, or `/log` for a shortcut. Depending on the device, this may be a RAM @@ -13,7 +13,7 @@ sink), this is covered briefly at the very end of this document. > a listing of existing native log files. -### Log to File +## Log to File Logging to a local file is useful when combined with an external media. E.g., a USB stick with a log partition (named/labeled: "log"). Below is @@ -43,7 +43,7 @@ admin@example:/> > that the filename is not already in use. -### Log Rotation +## Log Rotation By default log files are allowed to grow to a size of 1 MiB after which they are "rotated". The whole reason for this is to not fill up the @@ -113,7 +113,7 @@ admin@example:/> ``` -### Log Format +## Log Format There are three major syslog log formats, the default is [RFC3164][] for log files and BSD for remote logging. Depending on time synchronization @@ -144,7 +144,7 @@ admin@example:/> [RFC3164]: https://datatracker.ietf.org/doc/html/rfc3164 [RFC5424]: https://datatracker.ietf.org/doc/html/rfc5424 -### Log to Remote Server +## Log to Remote Server Logging to a remote syslog server is the recommended way of supervising the system. This way all login attempts (console, SSH, or web) and any @@ -176,7 +176,7 @@ admin@example:/> > above can be found by tapping the Tab key. -### Acting as a Log Server +## Acting as a Log Server The syslog server can act as a log sink for other devices on a LAN. For this to work you need a static IP address, here we use 10.0.0.1/24. diff --git a/doc/virtual.md b/doc/virtual.md index 4cdcaeef..49c8b28c 100644 --- a/doc/virtual.md +++ b/doc/virtual.md @@ -1,5 +1,5 @@ -Infix in Virtual Environments -============================= +Virtual Environments +===================== Infix primarily targets real hardware, deployment to the cloud is not a priority at the moment. However, for development and testing purposes