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: minor syntax changes/cleanup, rephrase + use admonitions

Browse Source 
Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2025-07-30 14:58:01 +02:00
parent 9d912446a7
commit a491f2a88b
12 changed files with 57 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/boot.md
+18 -26
View File
@@ -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 <slot>`
rauc status mark-active <slot>
Where `<slot>` is one of:
Where `<slot>` is one of:
| `<slot>` | Source |
|----------|---------------------------|
| rootfs.0 | Primary partition |
| rootfs.1 | Secondary partition |
| net.0 | Netboot (where supported) |
| `<slot>` | 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 |
|-----------|-----------------|
doc/cli/configure.md
+8 -9
View File
@@ -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
doc/cli/introduction.md
+2 -1
View File
@@ -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!
doc/cli/netcalc.md
+3 -3
View File
@@ -1,4 +1,4 @@
## Usage
# Network Calculator
```
netcalc <ADDRESS/LEN | NETWORK NETMASK> [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.
doc/cli/tcpdump.md
+3 -3
View File
@@ -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:
doc/cli/upgrade.md
+1 -2
View File
@@ -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
doc/container.md
+3 -27
View File
@@ -1,31 +1,7 @@
Containers in Infix
===================
<img align="right" src="img/docker.webp" alt="Docker whale" width=360>
* [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.
<img align="right" src="img/docker-hello-world.svg" alt="Hello World" width=360>
![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
---------------------------
<img align="right" src="img/shield-checkmark.svg" alt="Hello World" width=100>
![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!
doc/license.md
+1 -1
View File
@@ -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
doc/management.md
+1 -1
View File
@@ -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
doc/override-package.md
+9 -6
View File
@@ -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 `<pkg>_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
doc/syslog.md
+6 -6
View File
@@ -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.
doc/virtual.md
+2 -2
View File
@@ -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