From b031f5216a534e2706576604ff1e0c525a63c874 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Sun, 25 Jan 2026 02:08:53 +0100 Subject: [PATCH] doc: update remaining guides to new example format Signed-off-by: Joachim Wiberg --- doc/container.md | 529 +++++++++++++++++++++++-------------------- doc/dhcp.md | 100 ++++---- doc/hardware.md | 44 ++-- doc/management.md | 88 ++++--- doc/nacm.md | 48 ++-- doc/ntp.md | 132 ++++++----- doc/qos.md | 17 +- doc/syslog.md | 171 +++++++------- doc/system.md | 226 +++++++++--------- doc/tunnels.md | 127 +++++------ doc/upgrade.md | 182 +++++++-------- doc/vpn-wireguard.md | 281 +++++++++++------------ doc/wifi.md | 8 +- 13 files changed, 962 insertions(+), 991 deletions(-) diff --git a/doc/container.md b/doc/container.md index 02a0b795..59aca114 100644 --- a/doc/container.md +++ b/doc/container.md @@ -92,17 +92,18 @@ your container image and application to run. Classic Hello World: - admin@example:/> container run docker://hello-world - Starting docker://hello-world :: use Ctrl-p Ctrl-q to detach - Trying to pull docker.io/library/hello-world:latest... - Getting image source signatures - Copying blob c1ec31eb5944 done - Copying config d2c94e258d done - Writing manifest to image destination - Storing signatures +
admin@example:/> container run docker://hello-world
+Starting docker://hello-world :: use Ctrl-p Ctrl-q to detach
+Trying to pull docker.io/library/hello-world:latest...
+Getting image source signatures
+Copying blob c1ec31eb5944 done
+Copying config d2c94e258d done
+Writing manifest to image destination
+Storing signatures
 
-    Hello from Docker!
-    This message shows that your installation appears to be working correctly.
+Hello from Docker!
+This message shows that your installation appears to be working correctly.
+
### Example: Web Server @@ -110,22 +111,24 @@ A web server with [nginx][], using standard docker bridge. Podman will automatically create a VETH pair for us, connecting the container to the `docker0` bridge: - admin@example:/> configure - admin@example:/config/> edit interface docker0 - admin@example:/config/interface/docker0/> set container-network - admin@example:/config/interface/docker0/> end - admin@example:/config/> edit container web - admin@example:/config/container/web/> set image docker://nginx:alpine - admin@example:/config/container/web/> set network publish 8080:80 - admin@example:/config/container/web/> set network interface docker0 - admin@example:/config/container/web/> set volume cache target /var/cache - admin@example:/config/container/web/> leave - admin@example:/> show container +
admin@example:/> configure
+admin@example:/config/> edit interface docker0
+admin@example:/config/interface/docker0/> set container-network
+admin@example:/config/interface/docker0/> end
+admin@example:/config/> edit container web
+admin@example:/config/container/web/> set image docker://nginx:alpine
+admin@example:/config/container/web/> set network publish 8080:80
+admin@example:/config/container/web/> set network interface docker0
+admin@example:/config/container/web/> set volume cache target /var/cache
+admin@example:/config/container/web/> leave
+admin@example:/> show container
+
Exit to the shell and verify the service with curl, or try to attach to your device's IP address using your browser: - admin@example:~$ curl http://localhost:8080 +
admin@example:~$ curl http://localhost:8080
+
or connect to port 8080 of your running Infix system with a browser. See the following sections for how to add more interfaces and manage @@ -142,31 +145,32 @@ how to upgrade to a newer base image. The CLI help shows: - admin@example:/config/container/system/> help image - NAME - image +
admin@example:/config/container/system/> help image
+NAME
+    image <string>
 
-    DESCRIPTION
-        Docker image for the container: [transport]name[:tag|@digest]
+DESCRIPTION
+    Docker image for the container: [transport]name[:tag|@digest]
 
-        quay.io/username/myimage     -- Pull myimage:latest
-        docker://busybox             -- Pull busybox:latest from Docker Hub
-        docker://ghcr.io/usr/img     -- Pull img:latest from GitHub packages
-        dir:/media/usb/myimage:1.1   -- Use myimage v1.1 from USB media
-        docker-archive:/tmp/archive  -- Use archive:latest from tarball
-        oci-archive:/lib/oci/archive -- Use archive:latest from OCI archive
-                                        May be in .tar or .tar.gz format
+    quay.io/username/myimage     -- Pull myimage:latest
+    docker://busybox             -- Pull busybox:latest from Docker Hub
+    docker://ghcr.io/usr/img     -- Pull img:latest from GitHub packages
+    dir:/media/usb/myimage:1.1   -- Use myimage v1.1 from USB media
+    docker-archive:/tmp/archive  -- Use archive:latest from tarball
+    oci-archive:/lib/oci/archive -- Use archive:latest from OCI archive
+                                    May be in .tar or .tar.gz format
 
-        Additionally, the following URIs are also supported for setups
-        that do not use a HUB or similar.  Recommend using 'checksum'!
+    Additionally, the following URIs are also supported for setups
+    that do not use a HUB or similar.  Recommend using 'checksum'!
 
-        ftp://addr/path/to/archive   -- Downloaded using wget
-        http://addr/path/to/archive  -- Downloaded using curl
-        https://addr/path/to/archive -- Downloaded using curl
+    ftp://addr/path/to/archive   -- Downloaded using wget
+    http://addr/path/to/archive  -- Downloaded using curl
+    https://addr/path/to/archive -- Downloaded using curl
 
-        Note: if a remote repository cannot be reached, the creation of the
-              container will be put on a queue that retries pull every time
-              there is a route change in the host's system.
+    Note: if a remote repository cannot be reached, the creation of the
+          container will be put on a queue that retries pull every time
+          there is a route change in the host's system.
+
> [!TIP] > The built-in help system in the CLI is generated from the YANG model, @@ -198,26 +202,28 @@ mind. **Shell OCI Example:** - admin@example:~$ cd /var/tmp/ - admin@example:/var/tmp$ sudo wget https://github.com/kernelkit/curiOS/releases/download/edge/curios-oci-amd64.tar.gz - Connecting to github.com (140.82.121.3:443) - wget: note: TLS certificate validation not implemented - Connecting to objects.githubusercontent.com (185.199.109.133:443) - saving to 'curios-oci-amd64.tar.gz' - curios-oci-amd64.tar 100% |*********************************| 7091k 0:00:00 ETA - 'curios-oci-amd64.tar.gz' saved - admin@example:/var/tmp$ ll - total 7104 - drwxr-xr-x 3 root root 4096 Mar 27 14:22 ./ - drwxr-xr-x 14 root root 4096 Mar 27 11:57 ../ - -rw-r--r-- 1 root root 7261785 Mar 27 14:22 curios-oci-amd64.tar.gz - drwx------ 6 frr frr 4096 Mar 27 11:57 frr/ +
admin@example:~$ cd /var/tmp/
+admin@example:/var/tmp$ sudo wget https://github.com/kernelkit/curiOS/releases/download/edge/curios-oci-amd64.tar.gz
+Connecting to github.com (140.82.121.3:443)
+wget: note: TLS certificate validation not implemented
+Connecting to objects.githubusercontent.com (185.199.109.133:443)
+saving to 'curios-oci-amd64.tar.gz'
+curios-oci-amd64.tar 100% |*********************************| 7091k  0:00:00 ETA
+'curios-oci-amd64.tar.gz' saved
+admin@example:/var/tmp$ ll
+total 7104
+drwxr-xr-x    3 root     root          4096 Mar 27 14:22 ./
+drwxr-xr-x   14 root     root          4096 Mar 27 11:57 ../
+-rw-r--r--    1 root     root       7261785 Mar 27 14:22 curios-oci-amd64.tar.gz
+drwx------    6 frr      frr           4096 Mar 27 11:57 frr/
+
Importing the image into Podman can be done either from the CLI admin-exec context ... - admin@example:/var/tmp$ cli - admin@example:/> container load /var/tmp/curios-oci-amd64.tar.gz name curios:edge +
admin@example:/var/tmp$ cli
+admin@example:/> container load /var/tmp/curios-oci-amd64.tar.gz name curios:edge
+
> [!TIP] > The `name curios:edge` is the tag you give the imported (raw) archive @@ -227,31 +233,33 @@ admin-exec context ... ... or by giving the container configuration the full path to the OCI archive, which helps greatly with container upgrades (see below): - admin@example:/config/container/system/> set image oci-archive:/var/tmp/curios-oci-amd64.tar.gz +
admin@example:/config/container/system/> set image oci-archive:/var/tmp/curios-oci-amd64.tar.gz
+
**Checksum Example:** - admin@example:/> configure - admin@example:/config/> edit container sys - admin@example:/config/container/sys/> set hostname sys - admin@example:/config/container/sys/> set image ftp://192.168.122.1/curios-oci-amd64-v24.05.0.tar.gz - admin@example:/config/container/sys/> set checksum - md5 sha256 sha512 - admin@example:/config/container/sys/> set checksum sha256 4f01077036527498ed910f1a3e80645ae3eff629d10043cf80ebc6850c99c629 - admin@example:/config/container/sys/> leave - admin@example:/> copy running-config startup-config - admin@example:/> show container - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - b02e945c43c9 localhost/curios-oci-amd64-v24.05.0:latest 5 seconds ago Up 5 seconds sys +
admin@example:/> configure
+admin@example:/config/> edit container sys
+admin@example:/config/container/sys/> set hostname sys
+admin@example:/config/container/sys/> set image ftp://192.168.122.1/curios-oci-amd64-v24.05.0.tar.gz
+admin@example:/config/container/sys/> set checksum
+    md5 sha256 sha512
+admin@example:/config/container/sys/> set checksum sha256 4f01077036527498ed910f1a3e80645ae3eff629d10043cf80ebc6850c99c629
+admin@example:/config/container/sys/> leave
+admin@example:/> copy running-config startup-config
+admin@example:/> show container
+NAME  STATUS         NETWORK  MEMORY (KiB)  CPU%
+sys   Up 5 seconds                  72/512  0.02
 
-    admin@example:/> show log
-    ...
-    Nov 20 07:24:56 example container[5040]: Fetching ftp://192.168.122.1/curios-oci-amd64-v24.05.0.tar.gz
-    Nov 20 07:24:56 example container[5040]: curios-oci-amd64-v24.05.0.tar.gz downloaded successfully.
-    Nov 20 07:24:56 example container[5040]: curios-oci-amd64-v24.05.0.tar.gz checksum verified OK.
-    Nov 20 07:24:57 example container[5040]: Cleaning up extracted curios-oci-amd64-v24.05.0
-    Nov 20 07:24:57 example container[5040]: podman create --name sys --conmon-pidfile=/run/container:sys.pid --read-only --replace --quiet --cgroup-parent=containers  --restart=always --systemd=false --tz=local --hostname sys --log-driver k8s-file --log-opt path=/run/containers/sys.fifo --network=none curios-oci-amd64-v24.05.0
-    Nov 20 07:24:57 example container[3556]: b02e945c43c9bce2c4be88e31d6f63cfdb1a3c8bdd02179376eb059a49ae05e4
+admin@example:/> show log
+...
+Nov 20 07:24:56 example container[5040]: Fetching ftp://192.168.122.1/curios-oci-amd64-v24.05.0.tar.gz
+Nov 20 07:24:56 example container[5040]: curios-oci-amd64-v24.05.0.tar.gz downloaded successfully.
+Nov 20 07:24:56 example container[5040]: curios-oci-amd64-v24.05.0.tar.gz checksum verified OK.
+Nov 20 07:24:57 example container[5040]: Cleaning up extracted curios-oci-amd64-v24.05.0
+Nov 20 07:24:57 example container[5040]: podman create --name sys --conmon-pidfile=/run/container:sys.pid --read-only --replace --quiet --cgroup-parent=containers  --restart=always --systemd=false --tz=local --hostname sys --log-driver k8s-file --log-opt path=/run/containers/sys.fifo --network=none curios-oci-amd64-v24.05.0
+Nov 20 07:24:57 example container[3556]: b02e945c43c9bce2c4be88e31d6f63cfdb1a3c8bdd02179376eb059a49ae05e4
+
Understanding Image Tags @@ -359,12 +367,11 @@ writable paths provided by Podman (`/dev`, `/dev/shm`, `/run`, `/tmp`, When using version-specific tags, you upgrade by explicitly changing the image reference in your configuration: -``` -admin@example:/> configure -admin@example:/config/> edit container web -admin@example:/config/container/web/> set image docker://nginx:1.25.3 -admin@example:/config/container/web/> leave -``` +
admin@example:/> configure
+admin@example:/config/> edit container web
+admin@example:/config/container/web/> set image docker://nginx:1.25.3
+admin@example:/config/container/web/> leave
+
**What happens:** @@ -375,29 +382,27 @@ admin@example:/config/container/web/> leave **Example:** Upgrading from one version to another: -``` -admin@example:/> configure -admin@example:/config/> edit container system -admin@example:/config/container/system/> show image +
admin@example:/> configure
+admin@example:/config/> edit container system
+admin@example:/config/container/system/> show image
 image ghcr.io/kernelkit/curios:v24.11.0;
-admin@example:/config/container/system/> set image ghcr.io/kernelkit/curios:v24.12.0
-admin@example:/config/container/system/> leave
-admin@example:/> show log
+admin@example:/config/container/system/> set image ghcr.io/kernelkit/curios:v24.12.0
+admin@example:/config/container/system/> leave
+admin@example:/> show log
 ...
 Dec 13 14:32:15 example container[1523]: Pulling ghcr.io/kernelkit/curios:v24.12.0...
 Dec 13 14:32:18 example container[1523]: Stopping old container instance...
 Dec 13 14:32:19 example container[1523]: Creating new container with updated image...
 Dec 13 14:32:20 example container[1523]: Container system started successfully
-```
+
### Method 2: Upgrading Mutable Tags For images using mutable tags like `:latest` or `:edge`, use the `container upgrade` command: -``` -admin@example:/> container upgrade NAME -``` +
admin@example:/> container upgrade NAME
+
This command: @@ -408,8 +413,7 @@ This command: **Example using registry:** -``` -admin@example:/> container upgrade system +
admin@example:/> container upgrade system
 system
 Trying to pull ghcr.io/kernelkit/curios:edge...
 Getting image source signatures
@@ -420,7 +424,7 @@ Storing signatures
 0cb6059c0f4111650ddbc7dbc4880c64ab8180d4bdbb7269c08034defc348f17
 system: not running.
 59618cc3c84bef341c1f5251a62be1592e459cc990f0b8864bc0f5be70e60719
-```
+
**Example using local OCI archive:** @@ -429,11 +433,10 @@ new archive onto the system (see Container Images section above), then, provided the `oci-archive:/path/to/archive` format is used in your configuration, call the upgrade command: -``` -admin@example:/> container upgrade system +
admin@example:/> container upgrade system
 Upgrading container system with local archive: oci-archive:/var/tmp/curios-oci-amd64.tar.gz ...
 7ab4a07ee0c6039837419b7afda4da1527a70f0c60c0f0ac21cafee05ba24b52
-```
+
OCI archives can also be fetched from ftp/http/https URLs. In that case, the upgrade works the same way as a registry image — Infix downloads the @@ -472,15 +475,16 @@ occasions where they are too restricted and users start looking for the For example, a system container from which `ping` does not work: - admin@example:/config/container/system/> edit capabilities - admin@example:/config/container/system/capabilities/> set add net_raw - admin@example:/config/container/system/capabilities/> end - admin@infix-00-00-00:/config/container/system/> show - ... - capabilities { - add net_raw; - } - ... +
admin@example:/config/container/system/> edit capabilities
+admin@example:/config/container/system/capabilities/> set add net_raw
+admin@example:/config/container/system/capabilities/> end
+admin@infix-00-00-00:/config/container/system/> show
+...
+capabilities {
+  add net_raw;
+}
+...
+
Infix supports a subset of all [capabilities][6] that are relevant for containers. Please note, that this is an advanced topic that require @@ -504,12 +508,13 @@ Resource limits are set per container and include: Example configuration limiting a container to 512 MiB of memory and 1.5 CPU cores: - admin@example:/> configure - admin@example:/config/> edit container web - admin@example:/config/container/web/> edit resource-limit - admin@example:/config/container/web/resource-limit/> set memory 524288 - admin@example:/config/container/web/resource-limit/> set cpu 1500 - admin@example:/config/container/web/resource-limit/> leave +
admin@example:/> configure
+admin@example:/config/> edit container web
+admin@example:/config/container/web/> edit resource-limit
+admin@example:/config/container/web/resource-limit/> set memory 524288
+admin@example:/config/container/web/resource-limit/> set cpu 1500
+admin@example:/config/container/web/resource-limit/> leave
+
Common CPU limit examples: @@ -521,8 +526,9 @@ Common CPU limit examples: Runtime resource usage statistics are available in the operational datastore: - admin@example:/> show container web - ... +
admin@example:/> show container web
+...
+
Use `show container usage` to see resource consumption across all containers, including memory, CPU, block I/O, network I/O, and process counts. @@ -563,10 +569,11 @@ container use seem to be so simple. All interface configuration is done in configure context. - admin@example:/> configure - admin@example:/config> edit interface docker0 - admin@example:/config/interface/docker0/> set container-network - admin@example:/config/interface/docker0/> leave +
admin@example:/> configure
+admin@example:/config> edit interface docker0
+admin@example:/config/interface/docker0/> set container-network
+admin@example:/config/interface/docker0/> leave
+
There is more to this story. When using the CLI, and sticking to common interface nomenclature, Infix helps you with some of the boring stuff. @@ -574,8 +581,9 @@ E.g., creating a new interface with a name like `brN` or `dockerN` automatically *infers* the interface types, which you would otherwise have to set manually: - admin@example:/config/interface/docker0/> set type bridge - admin@example:/config/interface/docker0/> set container-network type bridge +
admin@example:/config/interface/docker0/> set type bridge
+admin@example:/config/interface/docker0/> set container-network type bridge
+
> [!IMPORTANT] > When configuring the system via an API such as NETCONF or RESTCONF, no @@ -601,16 +609,17 @@ other networking parameters (DNS, default route) are set up. Some of the defaults of a container `bridge` can be changed, e.g., instead of `set container-network type bridge`, above, do: - admin@example:/config/interface/docker0/> edit container-network - admin@example:/config/interface/docker0/container-network/> set type bridge - admin@example:/config/interface/docker0/container-network/> edit subnet 192.168.0.0/16 - admin@example:/config/interface/docker0/container-network/subnet/192.168.0.0/16/> set gateway 192.168.255.254 - admin@example:/config/interface/docker0/container-network/subnet/192.168.0.0/16/> end - admin@example:/config/interface/docker0/container-network/> edit route 10.0.10.0/24 - admin@example:/config/interface/docker0/container-network/route/10.0.10.0/24/> set gateway 192.168.10.254 - admin@example:/config/interface/docker0/container-network/route/10.0.10.0/24/> end - admin@example:/config/interface/docker0/container-network/> end - admin@example:/config/interface/docker0/> leave +
admin@example:/config/interface/docker0/> edit container-network
+admin@example:/config/…/container-network/> set type bridge
+admin@example:/config/…/container-network/> edit subnet 192.168.0.0/16
+admin@example:/config/…/subnet/192.168.0.0/16/> set gateway 192.168.255.254
+admin@example:/config/…/subnet/192.168.0.0/16/> end
+admin@example:/config/…/container-network/> edit route 10.0.10.0/24
+admin@example:/config/…/route/10.0.10.0/24/> set gateway 192.168.10.254
+admin@example:/config/…/route/10.0.10.0/24/> end
+admin@example:/config/…/container-network/> end
+admin@example:/config/interface/docker0/> leave
+
Other network settings, like DNS and domain, use built-in defaults, but can be overridden from each container. Other common settings per @@ -622,24 +631,25 @@ in a `bridge`. Below an example of a system container calls `set network interface docker0`, here we show how to set options for that network: - admin@example:/config/container/ntpd/> edit network interface docker0 - admin@example:/config/container/ntpd/network/interface/docker0/> - admin@example:/config/container/ntpd/network/interface/docker0/> set option - Options for masquerading container bridges. - admin@example:/config/container/ntpd/network/interface/docker0/> help option - NAME - option - - DESCRIPTION - Options for masquerading container bridges. +
admin@example:/config/container/ntpd/> edit network interface docker0
+admin@example:/config/…/network/interface/docker0/>
+admin@example:/config/…/network/interface/docker0/> set option
+<string>  Options for masquerading container bridges.
+admin@example:/config/…/network/interface/docker0/> help option
+NAME
+        option <string>
 
-            Example: ip=1.2.3.4            -- request a specific IP (IPv4 or IPv6)
-                     mac=00:01:02:c0:ff:ee -- set fixed MAC address in container
-                     interface_name=foo0   -- set interface name inside container
-    
-    admin@example:/config/container/ntpd/network/interface/docker0/> set option ip=172.17.0.2
-    admin@example:/config/container/ntpd/network/interface/docker0/> set option interface_name=wan
-    admin@example:/config/container/ntpd/network/interface/docker0/> leave
+DESCRIPTION
+        Options for masquerading container bridges.
+
+        Example: ip=1.2.3.4            -- request a specific IP (IPv4 or IPv6)
+                 mac=00:01:02:c0:ff:ee -- set fixed MAC address in container
+                 interface_name=foo0   -- set interface name inside container
+
+admin@example:/config/…/network/interface/docker0/> set option ip=172.17.0.2
+admin@example:/config/…/network/interface/docker0/> set option interface_name=wan
+admin@example:/config/…/network/interface/docker0/> leave
+
### Container Host Interface @@ -674,14 +684,15 @@ container-end of pair `ntpd`. This is just a convenience for us when reading the configuration later. The *real action* happens on the last line where we declare the `ntpd` end as a container network interface: - admin@example:/config/> edit interface veth0 - admin@example:/config/interface/veth0/> set veth peer ntpd - admin@example:/config/interface/veth0/> set ipv4 address 192.168.0.1 prefix-length 24 - admin@example:/config/interface/veth0/> end - admin@example:/config/> edit interface ntpd - admin@example:/config/interface/ntpd/> set ipv4 address 192.168.0.2 prefix-length 24 - admin@example:/config/interface/ntpd/> set custom-phys-address static 00:c0:ff:ee:00:01 - admin@example:/config/interface/ntpd/> set container-network +
admin@example:/config/> edit interface veth0
+admin@example:/config/interface/veth0/> set veth peer ntpd
+admin@example:/config/interface/veth0/> set ipv4 address 192.168.0.1 prefix-length 24
+admin@example:/config/interface/veth0/> end
+admin@example:/config/> edit interface ntpd
+admin@example:/config/interface/ntpd/> set ipv4 address 192.168.0.2 prefix-length 24
+admin@example:/config/interface/ntpd/> set custom-phys-address static 00:c0:ff:ee:00:01
+admin@example:/config/interface/ntpd/> set container-network
+
> [!TIP] > Notice how you can also set a custom MAC address at the same time. @@ -690,8 +701,9 @@ Adding the interface to the container is the same as before, but since everything for host interfaces is set up in the interfaces context, we can take a bit of a shortcut. - admin@example:/config/container/ntpd/> set network interface ntpd - admin@example:/config/container/ntpd/> leave +
admin@example:/config/container/ntpd/> set network interface ntpd
+admin@example:/config/container/ntpd/> leave
+
> [!TIP] > Use the `set network interface ntpd option interface_name=foo0` to set @@ -712,9 +724,10 @@ pair to give our container two interfaces: We start by adding the second VETH pair: - admin@example:/config/> edit interface veth1a - admin@example:/config/interface/veth1a/> set veth peer veth1 - admin@example:/config/interface/veth1a/> set ipv4 address 192.168.1.2 prefix-length 24 +
admin@example:/config/> edit interface veth1a
+admin@example:/config/interface/veth1a/> set veth peer veth1
+admin@example:/config/interface/veth1a/> set ipv4 address 192.168.1.2 prefix-length 24
+
> [!NOTE] > The LAN bridge (br1) in this example has IP address 192.168.1.1. @@ -723,20 +736,21 @@ When a container has multiple host interfaces it can often be useful to have a default route installed. This can be added from the host with a `0.0.0.0/0` route on one of the interfaces: - admin@example:/config/interface/veth1a/> set container-network route 0.0.0.0/0 gateway 192.168.1.1 - admin@example:/config/interface/veth1a/> show - type veth; - container-network { - type host; - route 0.0.0.0/0 { - gateway 192.168.1.1; - } - } - veth { - peer veth1; - } - admin@example:/config/interface/veth1a/> end - admin@example:/config/> set interface veth1 bridge-port bridge br1 +
admin@example:/config/interface/veth1a/> set container-network route 0.0.0.0/0 gateway 192.168.1.1
+admin@example:/config/interface/veth1a/> show
+type veth;
+container-network {
+  type host;
+  route 0.0.0.0/0 {
+    gateway 192.168.1.1;
+  }
+}
+veth {
+  peer veth1;
+}
+admin@example:/config/interface/veth1a/> end
+admin@example:/config/> set interface veth1 bridge-port bridge br1
+
Please note, container network routes require the base interface also have a static IP address set. Setting only the route, but no address, @@ -762,11 +776,12 @@ It is possible to mount files, directories, and even files matching a glob, into a container. This gives precise control over the container's file system: - admin@example:/config/container/system/> edit mount leds - admin@example:/config/container/system/mount/leds> set source /sys/class/leds - admin@example:/config/container/system/mount/leds> set target /sys/class/leds - admin@example:/config/container/system/mount/leds> end - admin@example:/config/container/system/> +
admin@example:/config/container/system/> edit mount leds
+admin@example:/config/container/system/mount/leds> set source /sys/class/leds
+admin@example:/config/container/system/mount/leds> set target /sys/class/leds
+admin@example:/config/container/system/mount/leds> end
+admin@example:/config/container/system/>
+
Any type of file can be *bind mounted* into the container, just watch out for permissions though. In the example above, `/sys/class/leds` is @@ -782,7 +797,8 @@ trigger a container restart. Other times *volumes* are a better fit. A volume is an automatically created read-writable entity that follows the life of your container. - admin@example:/config/container/ntpd/> set volume varlib target /var/lib +
admin@example:/config/container/ntpd/> set volume varlib target /var/lib
+
Volumes are persistent across both reboots and upgrades of the base image. They are created by Podman when the container first starts up, @@ -812,14 +828,15 @@ where: To clean up unused volumes and reclaim disk space, use the admin-exec command: - admin@example:/> container prune - Deleted Images - ... - Deleted Volumes - ntpd-varlib - system-data +
admin@example:/> container prune
+Deleted Images
+...
+Deleted Volumes
+ntpd-varlib
+system-data
 
-    Total reclaimed space: 45.2MB
+Total reclaimed space: 45.2MB
+
The `container prune` command safely removes: @@ -830,14 +847,16 @@ The `container prune` command safely removes: > [!TIP] > You can monitor container resource usage with the command: > -> admin@example:/> show container usage +> 
admin@example:/> show container usage
+>
> > This displays disk space used by images, containers, and volumes, > helping you decide when to run the prune command. > > To see which volumes exist and which containers use them: > -> admin@example:/> show container volumes +> 
admin@example:/> show container volumes
+>
### Content Mounts @@ -847,12 +866,13 @@ when deploying similar systems at multiple sites. When the host loads its `startup-config` (or even `factory-config`) a temporary file is created using the decoded base64 data from the `content` node. - admin@example:/config/container/ntpd/> edit mount ntpd.conf - admin@example:/config/container/ntpd/mount/ntpd.conf> text-editor content - ... interactive editor starts up ... - admin@example:/config/container/ntpd/mount/ntpd.conf> set target /etc/ntpd.conf - admin@example:/config/container/ntpd/mount/ntpd.conf> end - admin@example:/config/container/ntpd/> +
admin@example:/config/container/ntpd/> edit mount ntpd.conf
+admin@example:/config/container/ntpd/mount/ntpd.conf> text-editor content
+... interactive editor starts up ...
+admin@example:/config/container/ntpd/mount/ntpd.conf> set target /etc/ntpd.conf
+admin@example:/config/container/ntpd/mount/ntpd.conf> end
+admin@example:/config/container/ntpd/>
+
The editor is a small [Emacs clone called Mg][2], see the built-in help text, or press Ctrl-x Ctrl-c to exit and save. When the editor exits @@ -876,12 +896,13 @@ Let's try out what we've learned by setting up a system container, a container providing multiple services, using the `docker0` interface we created previously: - admin@example:/> configure - admin@example:/config> edit container system - admin@example:/config/container/system/> set image ghcr.io/kernelkit/curios:edge - admin@example:/config/container/system/> set network interface docker0 - admin@example:/config/container/system/> set publish 222:22 - admin@example:/config/container/system/> leave +
admin@example:/> configure
+admin@example:/config> edit container system
+admin@example:/config/container/system/> set image ghcr.io/kernelkit/curios:edge
+admin@example:/config/container/system/> set network interface docker0
+admin@example:/config/container/system/> set publish 222:22
+admin@example:/config/container/system/> leave
+
> [!NOTE] > Ensure you have a network connection to the registry. If the image @@ -896,26 +917,29 @@ container configuration context for the full syntax.) Available containers can be accessed from admin-exec: - admin@example:/> show container - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - 439af2917b44 ghcr.io/kernelkit/curios:edge 41 hours ago Up 16 hours 0.0.0.0:222->222/tcp system +
admin@example:/> show container
+NAME     STATUS        NETWORK  MEMORY (KiB)  CPU%
+system   Up 16 hours   docker0       136/512  0.02
+
This is a system container, so you can "attach" to it by starting a shell (or logging in with SSH): - admin@example:/> container shell system - root@439af2917b44:/# +
admin@example:/> container shell system
+root@439af2917b44:/#
+
Notice how the hostname inside the container changes. By default the container ID (hash) is used, but this can be easily changed: - root@439af2917b44:/# exit - admin@example:/> configure - admin@example:/config/> edit container system - admin@example:/config/container/system/> set hostname sys101 - admin@example:/config/container/system/> leave - admin@example:/> container shell system - root@sys101:/# +
root@439af2917b44:/# exit
+admin@example:/> configure
+admin@example:/config/> edit container system
+admin@example:/config/container/system/> set hostname sys101
+admin@example:/config/container/system/> leave
+admin@example:/> container shell system
+root@sys101:/#
+
In fact, the container `hostname` setting supports the same format specifiers as the host's `hostname` setting: @@ -940,16 +964,17 @@ Infix currently does not have a native firewall configuration, and even when it does it will never expose the full capabilities of `nftables`. For advanced setups, the following is an interesting alternative. - admin@example:/> configure - admin@example:/config> edit container nftables - admin@example:/config/container/nftables/> set image ghcr.io/kernelkit/curios-nftables:edge - admin@example:/config/container/nftables/> set network host - admin@example:/config/container/nftables/> set privileged - admin@example:/config/container/nftables/> edit mount nftables.conf - admin@example:/config/container/nftables/mount/nftables.conf/> set target /etc/nftables.conf - admin@example:/config/container/nftables/mount/nftables.conf/> text-editor content - ... interactive editor starts up where you can paste your rules ... - admin@example:/config/container/nftables/mount/nftables.conf/> leave +
admin@example:/> configure
+admin@example:/config> edit container nftables
+admin@example:/config/container/nftables/> set image ghcr.io/kernelkit/curios-nftables:edge
+admin@example:/config/container/nftables/> set network host
+admin@example:/config/container/nftables/> set privileged
+admin@example:/config/container/nftables/> edit mount nftables.conf
+admin@example:/config/…/mount/nftables.conf/> set target /etc/nftables.conf
+admin@example:/config/…/mount/nftables.conf/> text-editor content
+... interactive editor starts up where you can paste your rules ...
+admin@example:/config/…/mount/nftables.conf/> leave
+
Notice how we `set network host`, so the container can see and act on all the host's interfaces, and that we also have to run the container @@ -968,19 +993,20 @@ file system and store in the host's `startup-config`. However, `ntpd` also saves clock drift information in `/var/lib/ntpd`, so we will also use volumes in this example. - admin@example:/> configure - admin@example:/config> edit container ntpd - admin@example:/config/container/ntpd/> set image ghcr.io/kernelkit/curios-ntpd:edge - admin@example:/config/container/ntpd/> set network interface ntpd # From veth0 above - admin@example:/config/container/ntpd/> edit mount ntp.conf - admin@example:/config/container/ntpd/mount/ntp.conf/> set target /etc/ntp.conf - admin@example:/config/container/ntpd/mount/ntp.conf/> text-editor content - ... interactive editor starts up where you can paste your rules ... - admin@example:/config/container/ntpd/mount/ntp.conf/> end - admin@example:/config/container/ntpd/> edit volume varlib - admin@example:/config/container/ntpd/volume/varlib/> set target /var/lib - admin@example:/config/container/ntpd/volume/varlib/> leave - admin@example:/> copy running-config startup-config +
admin@example:/> configure
+admin@example:/config> edit container ntpd
+admin@example:/config/container/ntpd/> set image ghcr.io/kernelkit/curios-ntpd:edge
+admin@example:/config/container/ntpd/> set network interface ntpd    # From veth0 above
+admin@example:/config/container/ntpd/> edit mount ntp.conf
+admin@example:/config/container/ntpd/mount/ntp.conf/> set target /etc/ntp.conf
+admin@example:/config/container/ntpd/mount/ntp.conf/> text-editor content
+... interactive editor starts up where you can paste your rules ...
+admin@example:/config/container/ntpd/mount/ntp.conf/> end
+admin@example:/config/container/ntpd/> edit volume varlib
+admin@example:/config/container/ntpd/volume/varlib/> set target /var/lib
+admin@example:/config/container/ntpd/volume/varlib/> leave
+admin@example:/> copy running-config startup-config
+
The `ntp.conf` file is stored in the host's `startup-config` and any state data in the container's `/var/lib` is retained between reboots @@ -1015,25 +1041,28 @@ First, enable *Privileged* mode, this unlocks the door and allows the container to manage resources on the host system. An example is the `nftables` container mentioned previously. - admin@example:/config/container/system/> set privileged +
admin@example:/config/container/system/> set privileged
+
Second, mount the host's `/proc/1` directory to somewhere inside your container. Here we pick `/1`: - admin@example:/config/container/system/> edit mount host - admin@example:/config/container/system/mount/host/> set source /proc/1 - admin@example:/config/container/system/mount/host/> set target /1 - admin@example:/config/container/system/mount/host/> leave +
admin@example:/config/container/system/> edit mount host
+admin@example:/config/container/system/mount/host/> set source /proc/1
+admin@example:/config/container/system/mount/host/> set target /1
+admin@example:/config/container/system/mount/host/> leave
+
Third, from inside the container, use the host's PID 1 namespaces with the `nsenter`[^2] command to slide through the container's walls. Here we show two example calls to `hostname`, first the container's own name and then asking what the hostname is on the host: - root@sys101:/# hostname - sys101 - root@sys101:/# nsenter -m/1/ns/mnt -u/1/ns/uts -i/1/ns/ipc -n/1/ns/net hostname - example +
root@sys101:/# hostname
+sys101
+root@sys101:/# nsenter -m/1/ns/mnt -u/1/ns/uts -i/1/ns/ipc -n/1/ns/net hostname
+example
+
One use-case for this method is when extending Infix with a management container that connects to other systems. For some tips on how to diff --git a/doc/dhcp.md b/doc/dhcp.md index f0444215..c2792930 100644 --- a/doc/dhcp.md +++ b/doc/dhcp.md @@ -19,20 +19,18 @@ servers[^1]. The following example configures a DHCP server for subnet 192.168.2.0/24 with an address pool: -``` -admin@example:/> configure -admin@example:/config/> edit dhcp-server subnet 192.168.2.0/24 -admin@example:/config/dhcp-server/…/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200 -admin@example:/config/dhcp-server/…/192.168.2.0/24/> leave -``` +
admin@example:/> configure
+admin@example:/config/> edit dhcp-server subnet 192.168.2.0/24
+admin@example:/config/dhcp-server/…/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200
+admin@example:/config/dhcp-server/…/192.168.2.0/24/> leave
+
When setting up the server from the CLI, the system automatically adds a few default DHCP options that will be sent to clients: both DNS server and default gateway will use the system address on the matching interface. -``` -admin@example:/> show running-config +
admin@example:/> show running-config
   "infix-dhcp-server:dhcp-server": {
     "subnet": [
       {
@@ -54,7 +52,7 @@ admin@example:/> show running-config
       }
     ]
   }
-```
+
> [!IMPORTANT] > Remember to set up an interface in this subnet, avoid using addresses @@ -68,23 +66,21 @@ admin@example:/> show running-config To reserve specific IP addresses for clients based on their MAC address, hostname, or client ID: -``` -admin@example:/config/dhcp-server/…/192.168.2.0/24/> edit host 192.168.2.10 -admin@example:/config/dhcp-server/…/192.168.2.10/> set match mac-address 00:11:22:33:44:55 -admin@example:/config/dhcp-server/…/192.168.2.10/> set hostname printer -admin@example:/config/dhcp-server/…/192.168.2.10/> leave -``` +
admin@example:/config/dhcp-server/…/192.168.2.0/24/> edit host 192.168.2.10
+admin@example:/config/dhcp-server/…/192.168.2.10/> set match mac-address 00:11:22:33:44:55
+admin@example:/config/dhcp-server/…/192.168.2.10/> set hostname printer
+admin@example:/config/dhcp-server/…/192.168.2.10/> leave
+
Match hosts using a client identifier instead of MAC address: -``` -admin@example:/config/dhcp-server/…/192.168.1.0/24/> edit host 192.168.1.50 -admin@example:/config/dhcp-server/…/192.168.1.50/> edit match -admin@example:/config/dhcp-server/…/match/> set client-id hex c0:ff:ee -admin@example:/config/dhcp-server/…/match/> leave -admin@example:/config/dhcp-server/…/192.168.1.50/> set lease-time infinite -admin@example:/config/dhcp-server/…/192.168.1.50/> leave -``` +
admin@example:/config/dhcp-server/…/192.168.1.0/24/> edit host 192.168.1.50
+admin@example:/config/dhcp-server/…/192.168.1.50/> edit match
+admin@example:/config/dhcp-server/…/match/> set client-id hex c0:ff:ee
+admin@example:/config/dhcp-server/…/match/> leave
+admin@example:/config/dhcp-server/…/192.168.1.50/> set lease-time infinite
+admin@example:/config/dhcp-server/…/192.168.1.50/> leave
+
The `hex` prefix here ensures matching of client ID is done using the hexadecimal octets `c0:ff:ee`, three bytes. Without the prefix the @@ -100,32 +96,30 @@ ASCII string "c0:ff:ee", eight bytes, is used. Configure additional DHCP options globally, per subnet, or per host: -``` -admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24 -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit option dns-server -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/dns-server/> set address 8.8.8.8 -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/dns-server/> leave -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit option ntp-server -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/ntp-server/> set address 192.168.2.1 -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/ntp-server/> leave -``` +
admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24
+admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit option dns-server
+admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/dns-server/> set address 8.8.8.8
+admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/dns-server/> leave
+admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> edit option ntp-server
+admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/ntp-server/> set address 192.168.2.1
+admin@example:/config/dhcp-server/subnet/192.168.2.0/24/option/ntp-server/> leave
+
When configuring, e.g., `dns-server`, or `router` options with the value `auto`, the system uses the IP address from the interface matching the subnet. For example: -``` -admin@example:/> show interfaces -INTERFACE PROTOCOL STATE DATA +
admin@example:/> show interfaces
+INTERFACE       PROTOCOL   STATE       DATA                                    
 eth0            ethernet   UP          02:00:00:00:00:00
                 ipv4                   192.168.1.1/24 (static)
 eth1            ethernet   UP          02:00:00:00:00:01
                 ipv4                   192.168.2.1/24 (static)
 
-admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> edit option dns-server
-admin@example:/config/dhcp-server/subnet/192.168.1.0/24/option/dns-server/> set address auto
-admin@example:/config/dhcp-server/subnet/192.168.1.0/24/option/dns-server/> leave
-```
+admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> edit option dns-server
+admin@example:/config/dhcp-server/subnet/192.168.1.0/24/option/dns-server/> set address auto
+admin@example:/config/dhcp-server/subnet/192.168.1.0/24/option/dns-server/> leave
+
In this case, clients in subnet 192.168.1.0/24 will receive 192.168.1.1 as their DNS server address. @@ -135,29 +129,27 @@ as their DNS server address. Configure DHCP for multiple networks: -``` -admin@example:/> configure -admin@example:/config/> edit dhcp-server -admin@example:/config/dhcp-server/> edit subnet 192.168.1.0/24 -admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> set pool start-address 192.168.1.100 end-address 192.168.1.200 -admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> leave -admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24 -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200 -admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> leave -``` +
admin@example:/> configure
+admin@example:/config/> edit dhcp-server
+admin@example:/config/dhcp-server/> edit subnet 192.168.1.0/24
+admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> set pool start-address 192.168.1.100 end-address 192.168.1.200
+admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> leave
+admin@example:/config/dhcp-server/> edit subnet 192.168.2.0/24
+admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> set pool start-address 192.168.2.100 end-address 192.168.2.200
+admin@example:/config/dhcp-server/subnet/192.168.2.0/24/> leave
+
## Monitoring View active leases and server statistics: -``` -admin@example:/> show dhcp-server -IP ADDRESS MAC HOSTNAME CLIENT ID EXPIRES +
admin@example:/> show dhcp-server
+IP ADDRESS       MAC                HOSTNAME            CLIENT ID             EXPIRES
 192.168.2.22     00:a0:85:00:02:05                      00:c0:ff:ee           3591s
 192.168.1.11     00:a0:85:00:04:06  foo                 01:00:a0:85:00:04:06  3591s
 
-admin@example:/> show dhcp-server statistics
+admin@example:/> show dhcp-server statistics
 DHCP offers sent                : 6
 DHCP ACK messages sent          : 5
 DHCP NAK messages sent          : 0
@@ -166,7 +158,7 @@ DHCP discover messages received : 6
 DHCP request messages received  : 5
 DHCP release messages received  : 6
 DHCP inform messages received   : 6
-```
+
[^1]: This requires the system DNS resolver to be configured. diff --git a/doc/hardware.md b/doc/hardware.md index 3370f9aa..814fec29 100644 --- a/doc/hardware.md +++ b/doc/hardware.md @@ -8,7 +8,7 @@ hardware][1], with deviations and augmentations in _infix-hardware_. For Infix to be able to control USB port(s), a device tree modification is needed (see _alder.dtsi_ for full example). -``` +```json chosen { infix { usb-ports = <&cp0_usb3_1>; @@ -24,26 +24,38 @@ All USB ports in the system will be disabled during boot due to the file Infix to control USB port(s), remove the file or manually enable the USB bus, here is an example: -``` +```bash # Enable the bus echo 1 > /sys/bus/usb/devices/usb1/authorized ``` And then enable sub-devices (e.g. USB memory) -``` +```bash # Enable a device plugged into usb1 echo 1 > /sys/bus/usb/devices/usb1/1-1/authorized ``` ### Current status -``` -admin@example:/> show hardware - USB PORTS - NAME STATE - USB unlocked -``` +
admin@example:/> show hardware
+HARDWARE COMPONENTS                                           
+──────────────────────────────────────────────────────────────
+Board Information                                            
+Model               : FriendlyElec NanoPi R2S
+Manufacturer        : FriendlyElec
+Serial Number       : 9d1fbfdab6d171ce
+Base MAC Address    : 4a:dc:d8:20:0d:85
+──────────────────────────────────────────────────────────────
+USB Ports                                                    
+NAME                                         STATE     OPER   
+USB                                          unlocked  enabled
+──────────────────────────────────────────────────────────────
+Sensors                                                      
+NAME                          VALUE                 STATUS    
+soc                           44.1 °C               ok        
+soc                           44.5 °C               ok        
+
An USB port can be in two states _unlocked_ and _locked_. When a port is locked, all connected devices will get power, but never authorized by @@ -56,12 +68,11 @@ Linux to use. > command `show hardware` in admin-exec context. (Use `do` prefix in > configure context.) -``` -admin@example:/> configure -admin@example:/config/> set hardware component USB state admin-state unlocked -admin@example:/config/> leave +
admin@example:/> configure
+admin@example:/config/> set hardware component USB state admin-state unlocked
+admin@example:/config/> leave
 admin@example:/>
-```
+
### Using a USB Stick @@ -81,8 +92,7 @@ The only way currently to safely "eject" a USB memory stick is to use `umount` command from a UNIX shell, which explicitly synchronizes any cached data to disk before returning the prompt: -``` -admin@example:~$ sudo umount /media/log -``` +
admin@example:~$ sudo umount /media/log
+
[1]: https://www.rfc-editor.org/rfc/rfc8348.html diff --git a/doc/management.md b/doc/management.md index fafb3a32..ece5abca 100644 --- a/doc/management.md +++ b/doc/management.md @@ -9,22 +9,20 @@ as NETCONF, RESTCONF, and CLI via SSH or Console. An SSH server (SSHv2) is provided for remote management. It can be enabled/disabled as shown below. -``` -admin@example:/> configure -admin@example:/config/> edit ssh -admin@example:/config/ssh/> set enabled +
admin@example:/> configure
+admin@example:/config/> edit ssh
+admin@example:/config/ssh/> set enabled
 admin@example:/config/ssh/>
-```
+
By default the SSH server accepts connections to port 22 on all its IP addresses, but this can be adjusted using the `listen` command. To make the server (only) listen for incoming connections to IP address _192.168.1.1_ and port _12345_ the following commands can be used. -``` -admin@example:/> configure -admin@example:/config/> edit ssh -admin@example:/config/ssh/> show +
admin@example:/> configure
+admin@example:/config/> edit ssh
+admin@example:/config/ssh/> show
 enabled true;
 hostkey genkey;
 listen ipv4 {
@@ -35,12 +33,12 @@ listen ipv6 {
   address ::;
   port 22;
 }
-admin@example:/config/ssh/> no listen ipv6
-admin@example:/config/ssh/> edit listen ipv4
-admin@example:/config/ssh/listen/ipv4/> set address 192.168.1.1
-admin@example:/config/ssh/listen/ipv4/> set port 12345
+admin@example:/config/ssh/> no listen ipv6
+admin@example:/config/ssh/> edit listen ipv4
+admin@example:/config/ssh/listen/ipv4/> set address 192.168.1.1
+admin@example:/config/ssh/listen/ipv4/> set port 12345
 admin@example:/config/ssh/listen/ipv4/>
-```
+
The default SSH hostkey is generated on first boot and is used in both SSH and NETCONF (SSH transport). Custom keys can be added to the @@ -62,9 +60,10 @@ created by OpenSSL. After the key has been stored in the keystore and given the name _mykey_ it can be added to SSH configuration: - admin@example:/> configure - admin@example:/config/> edit ssh - admin@example:/config/ssh/> set hostkey mykey +
admin@example:/> configure
+admin@example:/config/> edit ssh
+admin@example:/config/ssh/> set hostkey mykey
+
## Console Port @@ -78,9 +77,8 @@ connected to the console port of the device. The serial port is typically setup to run at 115200 baud, 8N1. -``` -Infix OS — Immutable.Friendly.Secure v24.11.1 (ttyS0) -example login: admin +
Infix OS — Immutable.Friendly.Secure v24.11.1 (ttyS0)
+example login: admin
 Password:
 .-------.
 |  . .  | Infix OS — Immutable.Friendly.Secure
@@ -90,26 +88,24 @@ Password:
 Run the command 'cli' for interactive OAM
 
 admin@example:~$
-```
+
The `resize` command can be used to update terminal settings to the size of your terminal window. -``` -admin@example:~$ resize +
admin@example:~$ resize
 COLUMNS=115;LINES=59;export COLUMNS LINES;
 admin@example:~$
-```
+
CLI can be entered from shell in the same way as for SSH. -``` -admin@example:~$ cli +
admin@example:~$ cli
 
 See the 'help' command for an introduction to the system
 
-admin@example:/> show interfaces
-INTERFACE       PROTOCOL   STATE       DATA
+admin@example:/> show interfaces
+INTERFACE       PROTOCOL   STATE       DATA                                    
 lo              ethernet   UP          00:00:00:00:00:00
                 ipv4                   127.0.0.1/8 (static)
                 ipv6                   ::1/128 (static)
@@ -117,7 +113,7 @@ e1              ethernet   LOWER-DOWN  00:53:00:06:03:01
 e2              ethernet   LOWER-DOWN  00:53:00:06:03:02
 ...
 admin@example:/>
-```
+
## Web, Web-console and RESTCONF @@ -132,27 +128,25 @@ There is also a *Netbrowse* Web service presenting information about the unit's neighbors, collected via mDNS (see [Discovery](discovery.md) for more details). -``` -admin@example:/> configure -admin@example:/config/> edit web -admin@example:/config/web/> help +
admin@example:/> configure
+admin@example:/config/> edit web
+admin@example:/config/web/> help
   enabled                           Enable or disable on all web services.
   console                           Web console interface.
   netbrowse                         mDNS Network Browser.
   restconf                          IETF RESTCONF Server.
 admin@example:/config/web/>
-```
+
### Enable/disable Web Service and Server The Web service can be enabled as shown below. -``` -admin@example:/> configure -admin@example:/config/> edit web -admin@example:/config/web/> set enabled -admin@example:/config/web/> -``` +
admin@example:/> configure
+admin@example:/config/> edit web
+admin@example:/config/web/> set enabled
+admin@example:/config/web/>
+
Enabling the Web service implies that a Web server is enabled. Currently this Web server provides generic Infix information, @@ -172,11 +166,10 @@ The Web console has its own enable/disable setting, but will only be activated if the Web service is enabled. The example below shows how to disable the Web console. -``` -admin@example:/config/web/> edit console -admin@example:/config/web/console/> no enabled +
admin@example:/config/web/> edit console
+admin@example:/config/web/console/> no enabled
 admin@example:/config/web/console/>
-```
+
### Enable/disable RESTCONF Service @@ -188,11 +181,10 @@ The RESTCONF service has its own enable/disable setting, but will only be activated if the Web service is enabled. The example below shows how to disable the RESTCONF service. -``` -admin@example:/config/web/> edit restconf -admin@example:/config/web/restconf/> no enabled +
admin@example:/config/web/> edit restconf
+admin@example:/config/web/restconf/> no enabled
 admin@example:/config/web/restconf/>
-```
+
## System Upgrade diff --git a/doc/nacm.md b/doc/nacm.md index 4e641bca..4635f020 100644 --- a/doc/nacm.md +++ b/doc/nacm.md @@ -399,11 +399,11 @@ operators can immediately configure them without updating NACM rules. **Effective permissions by group:** -| Group | Read | Write | Exec | Exceptions | -|-------|------|-------|------|------------| -| admin | All | All | All | None | -| operator | All | All | All | Cannot access passwords, keystore, truststore | -| guest | All | None | None | Read-only access | +| Group | Read | Write | Exec | Exceptions | +|----------|------|-------|------|-----------------------------------------------| +| admin | All | All | All | None | +| operator | All | All | All | Cannot access passwords, keystore, truststore | +| guest | All | None | None | Read-only access | ## Common Patterns @@ -505,8 +505,7 @@ Deny access to sensitive data for all users (except admins with permit-all): Check what NACM groups a user belongs to: -``` -admin@example:/> show nacm +
admin@example:/> show nacm
 enabled              : yes
 default read access  : permit
 default write access : permit
@@ -524,77 +523,74 @@ denied notifications : 0
           └──────────┴─────────┴─────────┴─────────┘
               ✓ Full    ⚠ Restricted    ✗ Denied
 
-USER                   SHELL   LOGIN
+USER                   SHELL   LOGIN                            
 admin                  bash    password+key
 jacky                  bash    password
 monitor                false   key
 
-GROUP                  USERS
+GROUP                  USERS                                    
 admin                  admin
 operator               jacky
 guest                  monitor
-```
+
For details about a group's restrictions, use `show nacm group `: -``` -admin@example:/> show nacm group operator +
admin@example:/> show nacm group operator
 members          : jacky
 read permission  : restricted
 write permission : restricted
 exec permission  : restricted
 applicable rules : 4
 ──────────────────────────────────────────────────────────────────────
-permit-system-rpcs
+permit-system-rpcs
   action     : permit
   operations : exec
   target     : ietf-system (rpc: *)
 
 ──────────────────────────────────────────────────────────────────────
-deny-password-access (via '*')
+deny-password-access (via '*')
   action     : deny
   operations : *
   target     : /ietf-system:system/authentication/user/password
 
 ──────────────────────────────────────────────────────────────────────
-deny-keystore-access (via '*')
+deny-keystore-access (via '*')
   action     : deny
   operations : *
   target     : ietf-keystore
 
 ──────────────────────────────────────────────────────────────────────
-deny-truststore-access (via '*')
+deny-truststore-access (via '*')
   action     : deny
   operations : *
   target     : ietf-truststore
-```
+
### Testing Access The easiest way to test NACM permissions is to log in as the user and try the operation: -```bash -$ ssh jacky@host -jacky@example:/> configure -jacky@example:/config/> edit system authentication user admin -jacky@example:/config/system/authentication/user/admin/> set authorized-key foo +
$ ssh jacky@host
+jacky@example:/> configure
+jacky@example:/config/> edit system authentication user admin
+jacky@example:/config/system/authentication/user/admin/> set authorized-key foo
 Error: Access to the data model "ietf-system" is denied because "jacky" NACM authorization failed.
 Error: Failed applying changes (2).
-```
+
### NACM Statistics NACM tracks denied operations. If you suspect permission issues, check the statistics: -``` -admin@example:/> show nacm +
admin@example:/> show nacm
 ...
   denied operations      : 5
   denied data writes     : 12
 ...
-```
+
Increasing counters indicate permission denials are occurring. diff --git a/doc/ntp.md b/doc/ntp.md index 9fa07ab3..67ea2bbc 100644 --- a/doc/ntp.md +++ b/doc/ntp.md @@ -13,37 +13,34 @@ while serving time to downstream clients. Configure a standalone NTP server using only a local reference clock: -``` -admin@example:/> configure -admin@example:/config/> edit ntp -admin@example:/config/ntp/> leave -``` +
admin@example:/> configure
+admin@example:/config/> edit ntp
+admin@example:/config/ntp/> leave
+
When setting up NTP via the CLI the system automatically configures a local reference clock. The default [stratum](#ntp-stratum-levels) is 16 (unsynchronized), which is suitable for isolated networks. For production use, configure a specific stratum level: -``` -admin@example:/config/> edit ntp -admin@example:/config/ntp/> set refclock-master master-stratum 10 -admin@example:/config/ntp/> leave -``` +
admin@example:/config/> edit ntp
+admin@example:/config/ntp/> set refclock-master master-stratum 10
+admin@example:/config/ntp/> leave
+
## Server Mode Synchronize from upstream NTP servers while serving time to clients: -``` -admin@example:/config/> edit ntp -admin@example:/config/ntp/> edit unicast-configuration 0.pool.ntp.org type uc-server -admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set iburst true -admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> end -admin@example:/config/ntp/> edit unicast-configuration 1.pool.ntp.org type uc-server -admin@example:/config/ntp/…/1.pool.ntp.org/type/uc-server/> set iburst true -admin@example:/config/ntp/…/1.pool.ntp.org/type/uc-server/> end -admin@example:/config/ntp/> leave -``` +
admin@example:/config/> edit ntp
+admin@example:/config/ntp/> edit unicast-configuration 0.pool.ntp.org type uc-server
+admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set iburst true
+admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> end
+admin@example:/config/ntp/> edit unicast-configuration 1.pool.ntp.org type uc-server
+admin@example:/config/ntp/…/1.pool.ntp.org/type/uc-server/> set iburst true
+admin@example:/config/ntp/…/1.pool.ntp.org/type/uc-server/> end
+admin@example:/config/ntp/> leave
+
The `unicast-configuration` uses a composite key with both address and type. Both hostnames and IP addresses are supported. The `iburst` option enables @@ -56,23 +53,21 @@ Each server acts as both client and server to the other: **First peer:** -``` -admin@peer1:/config/> edit ntp -admin@peer1:/config/ntp/> edit unicast-configuration 192.168.1.2 type uc-peer -admin@peer1:/config/ntp/…/192.168.1.2/type/uc-peer/> end -admin@peer1:/config/ntp/> set refclock-master master-stratum 8 -admin@peer1:/config/ntp/> leave -``` +
admin@peer1:/config/> edit ntp
+admin@peer1:/config/ntp/> edit unicast-configuration 192.168.1.2 type uc-peer
+admin@peer1:/config/ntp/…/192.168.1.2/type/uc-peer/> end
+admin@peer1:/config/ntp/> set refclock-master master-stratum 8
+admin@peer1:/config/ntp/> leave
+
**Second peer:** -``` -admin@peer2:/config/> edit ntp -admin@peer2:/config/ntp/> edit unicast-configuration 192.168.1.1 type uc-peer -admin@peer2:/config/ntp/…/192.168.1.1/type/uc-peer/> end -admin@peer2:/config/ntp/> set refclock-master master-stratum 8 -admin@peer2:/config/ntp/> leave -``` +
admin@peer2:/config/> edit ntp
+admin@peer2:/config/ntp/> edit unicast-configuration 192.168.1.1 type uc-peer
+admin@peer2:/config/ntp/…/192.168.1.1/type/uc-peer/> end
+admin@peer2:/config/ntp/> set refclock-master master-stratum 8
+admin@peer2:/config/ntp/> leave
+
This configuration provides mutual synchronization between peers. If one peer fails, the other continues to serve time to clients. @@ -103,12 +98,11 @@ the other peer. Control how often the NTP server polls upstream sources: -``` -admin@example:/config/ntp/> edit unicast-configuration 0.pool.ntp.org type uc-server -admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set minpoll 4 -admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set maxpoll 10 -admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> end -``` +
admin@example:/config/ntp/> edit unicast-configuration 0.pool.ntp.org type uc-server
+admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set minpoll 4
+admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> set maxpoll 10
+admin@example:/config/ntp/…/0.pool.ntp.org/type/uc-server/> end
+
Poll intervals are specified as powers of 2: - `minpoll 4` = poll every 2^4 = 16 seconds (minimum polling rate) @@ -126,12 +120,11 @@ critical for embedded systems without RTC that boot with epoch time. To customize the values: -``` -admin@example:/config/ntp/> edit makestep -admin@example:/config/ntp/makestep/> set threshold 2.0 -admin@example:/config/ntp/makestep/> set limit 1 -admin@example:/config/ntp/makestep/> end -``` +
admin@example:/config/ntp/> edit makestep
+admin@example:/config/ntp/makestep/> set threshold 2.0
+admin@example:/config/ntp/makestep/> set limit 1
+admin@example:/config/ntp/makestep/> end
+
- **threshold** - If clock offset exceeds this (in seconds), step immediately instead of slewing slowly @@ -143,19 +136,44 @@ correct time within seconds instead of hours. ## Monitoring -Check NTP server statistics: +For a quick overview: -``` -admin@example:/> show ntp server -NTP SERVER CONFIGURATION -Local Stratum : 10 +To view the sources being used by the NTP client, run: -SERVER STATISTICS -Packets Received : 142 -Packets Sent : 142 -Packets Dropped : 0 -Send Failures : 0 -``` +
admin@example:/> show ntp
+Mode                : Client
+Stratum             : 3
+Ref time (UTC)      : Sat Jan 24 23:41:42 2026
+
+ADDRESS         MODE    STATE     STRATUM  POLL
+147.78.228.41   server  outlier         2   64s
+192.168.0.1     server  unusable        0  128s
+176.126.86.247  server  selected        2   64s
+
+ +Check NTP source status: + +
admin@example:/> show ntp source
+MS  Name/IP address  Stratum  Poll  Reach  LastRx          Last sample
+^+  147.78.228.41          2     6    007      15  -431us +/- 33.573ms
+^*  176.126.86.247         2     6    007      14   -389us +/- 4.307ms
+
+ +For detailed information about a specific source: + +
admin@example:/> show ntp source 176.126.86.247
+Address             : 176.126.86.247
+Mode                : Server (client mode) [^]
+State               : Selected sync source [*]
+Configured          : Yes
+Stratum             : 2
+Poll interval       : 7 (2^7 seconds = 128s)
+Reachability        : 377 (octal) = 11111111b
+Last RX             : 75s ago
+Offset              : +2.0us (+0.002000ms)
+Delay               : 4.270ms (0.004270s)
+Dispersion          : 205.0us (0.205000ms)
+
## NTP Stratum Levels diff --git a/doc/qos.md b/doc/qos.md index 25e3b047..d937104f 100644 --- a/doc/qos.md +++ b/doc/qos.md @@ -91,15 +91,14 @@ These `ingress-qos` and `egress-qos` settings are done per VLAN, both defaulting to '0'. The example below shows how to keep the PCP priority for packets being routed between two VLAN interfaces. -``` -admin@example:/config/> edit interface e1.10 -admin@example:/config/interface/e1.10/> set vlan ingress-qos priority from-pcp -admin@example:/config/interface/e1.10/> up -admin@example:/config/> edit interface e1.20 -admin@example:/config/interface/e1.20/> set vlan egress-qos pcp from-priority -admin@example:/config/interface/e1.20/> leave -admin@example:/> -``` +
admin@example:/config/> edit interface e1.10
+admin@example:/config/interface/e1.10/> set vlan ingress-qos priority from-pcp
+admin@example:/config/interface/e1.10/> up
+admin@example:/config/> edit interface e1.20
+admin@example:/config/interface/e1.20/> set vlan egress-qos pcp from-priority
+admin@example:/config/interface/e1.20/> leave
+admin@example:/>
+
## A complex example diff --git a/doc/syslog.md b/doc/syslog.md index 002e98ec..ead621bd 100644 --- a/doc/syslog.md +++ b/doc/syslog.md @@ -21,20 +21,19 @@ an example. For a list of available log facilities, see the table in a later section. -``` -admin@example:/> configure -admin@example:/config/> edit syslog actions log-file file:/media/log/mylog -admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list +
admin@example:/> configure
+admin@example:/config/> edit syslog actions log-file file:/media/log/mylog
+admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list
       all    audit     auth authpriv  console     cron    cron2   daemon      ftp     kern
    local0   local1   local2   local3   local4   local5   local6   local7      lpr     mail
      news      ntp   syslog     user     uucp
-admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list all severity
+admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list all severity
      alert       all  critical     debug emergency     error      info      none    notice   warning
-admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list all severity critical
-admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list mail severity warning
-admin@example:/config/syslog/…/file:/media/log/mylog/> leave
+admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list all severity critical
+admin@example:/config/syslog/…/file:/media/log/mylog/> set facility-list mail severity warning
+admin@example:/config/syslog/…/file:/media/log/mylog/> leave
 admin@example:/>
-```
+
> [!IMPORTANT] > The `log-file` syntax requires the leading prefix `file:`. If the @@ -50,11 +49,10 @@ disk with outdated logs. A rotated file is saved in stages and older ones are also compressed (using `gzip`). Use the `show log` command in admin-exec context to start the log file viewer: -``` -admin@example:/config/syslog/> do show log +
admin@example:/config/syslog/> do show log
 log  log.0  log.1.gz  log.2.gz  log.3.gz  log.4.gz  log.5.gz
-admin@example:/config/syslog/> do show log log.1.gz
-```
+admin@example:/config/syslog/> do show log log.1.gz
+
> [!TIP] > Use the Tab key on your keyboard list available log files. The `do` @@ -68,51 +66,48 @@ Log file rotation can be configured both globally and per log file. Here we show the global settings, the set up is the same for per log file, which if unset inherit the global settings: -``` -admin@example:/> configure -admin@example:/config/> edit syslog file-rotation -admin@example:/config/syslog/file-rotation/> show +
admin@example:/> configure
+admin@example:/config/> edit syslog file-rotation
+admin@example:/config/syslog/file-rotation/> show
 admin@example:/config/syslog/file-rotation/>
-```
+
The defaults are not shown. We can inspect them by asking the YANG model for the help texts: -``` -admin@example:/config/syslog/file-rotation/> help +
admin@example:/config/syslog/file-rotation/> help
    max-file-size    number-of-files
-admin@example:/config/syslog/file-rotation/> help max-file-size 
-NAME
+admin@example:/config/syslog/file-rotation/> help max-file-size
+NAME
         max-file-size kilobytes
 
-DESCRIPTION
+DESCRIPTION
         Maximum log file size (kiB), before rotation.
 
-DEFAULT
+DEFAULT
         1024
-admin@example:/config/syslog/file-rotation/> help number-of-files 
-NAME
+admin@example:/config/syslog/file-rotation/> help number-of-files
+NAME
         number-of-files [0..4294967295]
 
-DESCRIPTION
+DESCRIPTION
         Maximum number of log files retained.
 
-DEFAULT
+DEFAULT
         10
-```
+
To change the defaults to something smaller, 512 kiB and 20 (remember everything after .0 is compressed, and text compresses well): -``` -admin@example:/config/syslog/file-rotation/> set max-file-size 512 -admin@example:/config/syslog/file-rotation/> set number-of-files 20 -admin@example:/config/syslog/file-rotation/> show +
admin@example:/config/syslog/file-rotation/> set max-file-size 512
+admin@example:/config/syslog/file-rotation/> set number-of-files 20
+admin@example:/config/syslog/file-rotation/> show
 number-of-files 20;
 max-file-size 512;
-admin@example:/config/syslog/file-rotation/> leave
+admin@example:/config/syslog/file-rotation/> leave
 admin@example:/>
-```
+
## Log Format @@ -135,14 +130,13 @@ perform time stamping at the time of arrival. Configuring the log format is the same for log files and remotes: -``` -admin@example:/config/> edit syslog actions log-file file:foobar -admin@example:/config/syslog/…/file:foobar/> set log-format +
admin@example:/config/> edit syslog actions log-file file:foobar
+admin@example:/config/syslog/…/file:foobar/> set log-format
                   bsd               rfc3164              rfc5424
-admin@example:/config/syslog/…/file:foobar/> set log-format rfc5424
-admin@example:/config/syslog/…/file:foobar/> leave
+admin@example:/config/syslog/…/file:foobar/> set log-format rfc5424
+admin@example:/config/syslog/…/file:foobar/> leave
 admin@example:/>
-```
+
## Log to Remote Server @@ -158,19 +152,18 @@ remote syslog servers do not support receiving time stamped log messages -- this is of course entirely dependent on how the remote server is set up, as well as local policy. -``` -admin@example:/config/> edit syslog +
admin@example:/config/> edit syslog
        actions file-rotation        server
-admin@example:/config/> edit syslog actions destination moon
-admin@example:/config/syslog/…/moon/> set
+admin@example:/config/> edit syslog actions destination moon
+admin@example:/config/syslog/…/moon/> set
  facility-list    log-format           udp
-admin@example:/config/syslog/…/moon/> set udp
+admin@example:/config/syslog/…/moon/> set udp
  address    port
-admin@example:/config/syslog/…/moon/> set udp address 192.168.0.12
-admin@example:/config/syslog/…/moon/> set facility-list container severity all
-admin@example:/config/syslog/…/moon/> leave
+admin@example:/config/syslog/…/moon/> set udp address 192.168.0.12
+admin@example:/config/syslog/…/moon/> set facility-list container severity all
+admin@example:/config/syslog/…/moon/> leave
 admin@example:/>
-```
+
> [!TIP] > The alternatives shown below each prompt in the example above can be @@ -181,14 +174,13 @@ admin@example:/> 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. -``` -admin@example:/> configure -admin@example:/config/> edit syslog server -admin@example:/config/syslog/server/> set enabled true -admin@example:/config/syslog/server/> set listen udp 514 address 10.0.0.1 -admin@example:/config/syslog/server/> leave +
admin@example:/> configure
+admin@example:/config/> edit syslog server
+admin@example:/config/syslog/server/> set enabled true
+admin@example:/config/syslog/server/> set listen udp 514 address 10.0.0.1
+admin@example:/config/syslog/server/> leave
 admin@example:/>
-```
+
See the above [Log to File](#log-to-file) section on how to set up filtering of received logs to local files. Advanced filtering based @@ -208,13 +200,12 @@ Messages can be filtered using regular expressions (POSIX extended regex) on the message content. This is useful when you want to log only messages containing specific keywords or patterns: -``` -admin@example:/config/> edit syslog actions log-file file:errors -admin@example:/config/syslog/…/file:errors/> set pattern-match "ERROR|CRITICAL|FATAL" -admin@example:/config/syslog/…/file:errors/> set facility-list all severity info -admin@example:/config/syslog/…/file:errors/> leave +
admin@example:/config/> edit syslog actions log-file file:errors
+admin@example:/config/syslog/…/file:errors/> set pattern-match "ERROR|CRITICAL|FATAL"
+admin@example:/config/syslog/…/file:errors/> set facility-list all severity info
+admin@example:/config/syslog/…/file:errors/> leave
 admin@example:/>
-```
+
This will log all messages containing ERROR, CRITICAL, or FATAL. @@ -224,22 +215,20 @@ By default, severity filtering uses "equals-or-higher" comparison, meaning a severity of `error` will match error, critical, alert, and emergency messages. You can change this behavior: -``` -admin@example:/config/> edit syslog actions log-file file:daemon-errors -admin@example:/config/syslog/…/file:daemon-errors/> set facility-list daemon -admin@example:/config/syslog/…/daemon/> set severity error -admin@example:/config/syslog/…/daemon/> set advanced-compare compare equals -admin@example:/config/syslog/…/daemon/> leave +
admin@example:/config/> edit syslog actions log-file file:daemon-errors
+admin@example:/config/syslog/…/file:daemon-errors/> set facility-list daemon
+admin@example:/config/syslog/…/daemon/> set severity error
+admin@example:/config/syslog/…/daemon/> set advanced-compare compare equals
+admin@example:/config/syslog/…/daemon/> leave
 admin@example:/>
-```
+
This will log only `error` severity messages, not higher severities. You can also block specific severities: -``` -admin@example:/config/syslog/…/daemon/> set advanced-compare action block -``` +
admin@example:/config/syslog/…/daemon/> set advanced-compare action block
+
This will exclude `error` messages from the log. @@ -248,13 +237,12 @@ This will exclude `error` messages from the log. When acting as a log server, you can filter messages by hostname. This is useful for directing logs from different devices to separate files: -``` -admin@example:/config/> edit syslog actions log-file file:router1 -admin@example:/config/syslog/…/file:router1/> set hostname-filter router1 -admin@example:/config/syslog/…/file:router1/> set facility-list all severity info -admin@example:/config/syslog/…/file:router1/> leave +
admin@example:/config/> edit syslog actions log-file file:router1
+admin@example:/config/syslog/…/file:router1/> set hostname-filter router1
+admin@example:/config/syslog/…/file:router1/> set facility-list all severity info
+admin@example:/config/syslog/…/file:router1/> leave
 admin@example:/>
-```
+
Multiple hostnames can be added to the filter list. @@ -263,15 +251,14 @@ Multiple hostnames can be added to the filter list. For more advanced filtering, you can match on specific message properties using various comparison operators: -``` -admin@example:/config/> edit syslog actions log-file file:myapp -admin@example:/config/syslog/…/file:myapp/> edit property-filter -admin@example:/config/syslog/…/property-filter/> set property programname -admin@example:/config/syslog/…/property-filter/> set operator isequal -admin@example:/config/syslog/…/property-filter/> set value myapp -admin@example:/config/syslog/…/property-filter/> leave +
admin@example:/config/> edit syslog actions log-file file:myapp
+admin@example:/config/syslog/…/file:myapp/> edit property-filter
+admin@example:/config/syslog/…/property-filter/> set property programname
+admin@example:/config/syslog/…/property-filter/> set operator isequal
+admin@example:/config/syslog/…/property-filter/> set value myapp
+admin@example:/config/syslog/…/property-filter/> leave
 admin@example:/>
-```
+
Available properties: - `msg`: Message body @@ -290,15 +277,13 @@ Available operators: The comparison can be made case-insensitive: -``` -admin@example:/config/syslog/…/property-filter/> set case-insensitive true -``` +
admin@example:/config/syslog/…/property-filter/> set case-insensitive true
+
Or negated to exclude matching messages: -``` -admin@example:/config/syslog/…/property-filter/> set negate true -``` +
admin@example:/config/syslog/…/property-filter/> set negate true
+
### Facilities diff --git a/doc/system.md b/doc/system.md index d4c8cbb9..f2394086 100644 --- a/doc/system.md +++ b/doc/system.md @@ -22,13 +22,12 @@ hostname is included below. User management, including passwords, SSH keys, remote authentication is available in the system authentication configuration context. -``` -admin@example:/config/> edit system authentication user admin -admin@example:/config/system/authentication/user/admin/> change password +
admin@example:/config/> edit system authentication user admin
+admin@example:/config/system/…/user/admin/> change password
 New password:
 Retype password:
-admin@example:/config/system/authentication/user/admin/> leave
-```
+admin@example:/config/system/…/user/admin/> leave
+
The `change password` command starts an interactive dialogue that asks for the new password, with a confirmation, and then salts and encrypts @@ -56,16 +55,15 @@ are supported. With SSH keys in place it is possible to disable password login, just remember to verify SSH login and network connectivity before doing so. -``` -admin@example:/config/> edit system authentication user admin -admin@example:/config/system/authentication/user/admin/> edit authorized-key admin@example -admin@example:/config/system/authentication/user/admin/authorized-key/example@host/> set algorithm ssh-rsa -admin@example:/config/system/authentication/user/admin/authorized-key/example@host/> set key-data AAAAB3NzaC1yc2EAAAADAQABAAABgQC8iBL42yeMBioFay7lty1C4ZDTHcHyo739gc91rTTH8SKvAE4g8Rr97KOz/8PFtOObBrE9G21K7d6UBuPqmd0RUF2CkXXN/eN2PBSHJ50YprRFt/z/304bsBYkDdflKlPDjuSmZ/+OMp4pTsq0R0eNFlX9wcwxEzooIb7VPEdvWE7AYoBRUdf41u3KBHuvjGd1M6QYJtbFLQMMTiVe5IUfyVSZ1RCxEyAB9fR9CBhtVheTVsY3iG0fZc9eCEo89ErDgtGUTJK4Hxt5yCNwI88YaVmkE85cNtw8YwubWQL3/tGZHfbbQ0fynfB4kWNloyRHFr7E1kDxuX5+pbv26EqRdcOVGucNn7hnGU6C1+ejLWdBD7vgsoilFrEaBWF41elJEPKDzpszEijQ9gTrrWeYOQ+x++lvmOdssDu4KvGmj2K/MQTL2jJYrMJ7GDzsUu3XikChRL7zNfS2jYYQLzovboUCgqfPUsVba9hqeX3U67GsJo+hy5MG9RSry4+ucHs= -admin@example:/config/system/authentication/user/admin/authorized-key/example@host/> show +
admin@example:/config/> edit system authentication user admin
+admin@example:/config/system/…/user/admin/> edit authorized-key admin@example
+admin@example:/config/system/…/example@host/> set algorithm ssh-rsa
+admin@example:/config/system/…/example@host/> set key-data AAAAB3NzaC1yc2EAAAADAQABAAABgQC8iBL42yeMBioFay7lty1C4ZDTHcHyo739gc91rTTH8SKvAE4g8Rr97KOz/8PFtOObBrE9G21K7d6UBuPqmd0RUF2CkXXN/eN2PBSHJ50YprRFt/z/304bsBYkDdflKlPDjuSmZ/+OMp4pTsq0R0eNFlX9wcwxEzooIb7VPEdvWE7AYoBRUdf41u3KBHuvjGd1M6QYJtbFLQMMTiVe5IUfyVSZ1RCxEyAB9fR9CBhtVheTVsY3iG0fZc9eCEo89ErDgtGUTJK4Hxt5yCNwI88YaVmkE85cNtw8YwubWQL3/tGZHfbbQ0fynfB4kWNloyRHFr7E1kDxuX5+pbv26EqRdcOVGucNn7hnGU6C1+ejLWdBD7vgsoilFrEaBWF41elJEPKDzpszEijQ9gTrrWeYOQ+x++lvmOdssDu4KvGmj2K/MQTL2jJYrMJ7GDzsUu3XikChRL7zNfS2jYYQLzovboUCgqfPUsVba9hqeX3U67GsJo+hy5MG9RSry4+ucHs=
+admin@example:/config/system/…/example@host/> show
 algorithm ssh-rsa;
 key-data AAAAB3NzaC1yc2EAAAADAQABAAABgQC8iBL42yeMBioFay7lty1C4ZDTHcHyo739gc91rTTH8SKvAE4g8Rr97KOz/8PFtOObBrE9G21K7d6UBuPqmd0RUF2CkXXN/eN2PBSHJ50YprRFt/z/304bsBYkDdflKlPDjuSmZ/+OMp4pTsq0R0eNFlX9wcwxEzooIb7VPEdvWE7AYoBRUdf41u3KBHuvjGd1M6QYJtbFLQMMTiVe5IUfyVSZ1RCxEyAB9fR9CBhtVheTVsY3iG0fZc9eCEo89ErDgtGUTJK4Hxt5yCNwI88YaVmkE85cNtw8YwubWQL3/tGZHfbbQ0fynfB4kWNloyRHFr7E1kDxuX5+pbv26EqRdcOVGucNn7hnGU6C1+ejLWdBD7vgsoilFrEaBWF41elJEPKDzpszEijQ9gTrrWeYOQ+x++lvmOdssDu4KvGmj2K/MQTL2jJYrMJ7GDzsUu3XikChRL7zNfS2jYYQLzovboUCgqfPUsVba9hqeX3U67GsJo+hy5MG9RSry4+ucHs=;
-admin@example:/config/system/authentication/user/admin/authorized-key/example@host/> leave
-```
+admin@example:/config/system/…/example@host/> leave
+
> [!NOTE] > The `ssh-keygen` program already base64 encodes the public key data, @@ -112,8 +110,7 @@ way to regain full access is to perform a *factory reset*. For an overview of users and groups on the system, there is an admin-exec command: -``` -admin@example:/> show nacm +
admin@example:/> show nacm
 enabled              : yes
 default read access  : permit
 default write access : permit
@@ -131,16 +128,16 @@ denied notifications : 0
           └──────────┴─────────┴─────────┴─────────┘
               ✓ Full    ⚠ Restricted    ✗ Denied
 
-USER                   SHELL   LOGIN
+USER                   SHELL   LOGIN                            
 admin                  bash    password+key
 jacky                  clish   password
 monitor                false   key
 
-GROUP                  USERS
+GROUP                  USERS                                    
 admin                  admin
 operator               jacky
 guest                  monitor
-```
+
The permissions matrix shows effective access for each NACM group: @@ -151,46 +148,44 @@ The permissions matrix shows effective access for each NACM group: For detailed information about a specific group's rules: -``` -admin@example:/> show nacm group operator +
admin@example:/> show nacm group operator
 members          : jacky
 read permission  : restricted
 write permission : restricted
 exec permission  : restricted
 applicable rules : 4
 ──────────────────────────────────────────────────────────────────────
-permit-system-rpcs
+permit-system-rpcs
   action     : permit
   operations : exec
   target     : ietf-system (rpc: *)
   comment    : Operators can reboot, shutdown, and set system time.
 
 ──────────────────────────────────────────────────────────────────────
-deny-password-access (via '*')
+deny-password-access (via '*')
   action     : deny
   operations : *
   target     : /ietf-system:system/authentication/user/password
   comment    : No user except admins can access password hashes.
 
 ──────────────────────────────────────────────────────────────────────
-deny-keystore-access (via '*')
+deny-keystore-access (via '*')
   action     : deny
   operations : *
   target     : ietf-keystore
   comment    : No user except admins can access cryptographic keys.
 
 ──────────────────────────────────────────────────────────────────────
-deny-truststore-access (via '*')
+deny-truststore-access (via '*')
   action     : deny
   operations : *
   target     : ietf-truststore
   comment    : No user except admins can access trust store.
-```
+
For user details: -``` -admin@example:/> show nacm user jacky +
admin@example:/> show nacm user jacky
 shell            : clish
 login            : password
 nacm group       : operator
@@ -198,20 +193,26 @@ read permission  : restricted
 write permission : restricted
 exec permission  : restricted
 
-For detailed rules, use: show nacm group 
-```
+For detailed rules, use: show nacm group <name>
+
### Adding a User Creating a new user starts with defining the user account in the system: -``` -admin@example:/config/> edit system authentication user jacky -admin@example:/config/system/authentication/user/jacky/> change password +
admin@example:/config/> edit system authentication user jacky
+admin@example:/config/system/…/user/jacky/> change password
 New password:
 Retype password:
-admin@example:/config/system/authentication/user/jacky/> leave
-```
+admin@example:/config/system/…/user/jacky/> leave
+
+ +> [!TIP] +> It is also possible to use set password ... if you have the +> fully crypted and salted string ready. This can be created offline +> with the [`mkpasswd(1)`][5] tool, or the built-in CLI version do +> password encrypt [OPTS]. The `do` prefix is handy for reaching +> all top-level commands when in configure context. An authorized SSH key can be added the same way as described in the previous sections. @@ -219,11 +220,10 @@ previous sections. By default, shell access is disabled (`shell false`). To allow CLI/SSH access, set the shell: -``` -admin@example:/config/> edit system authentication user jacky -admin@example:/config/system/authentication/user/jacky/> set shell clish -admin@example:/config/system/authentication/user/jacky/> leave -``` +
admin@example:/config/> edit system authentication user jacky
+admin@example:/config/system/…/user/jacky/> set shell clish
+admin@example:/config/system/…/user/jacky/> leave
+
Available shells: @@ -250,27 +250,24 @@ corresponding NACM group: **Operator user:** -``` -admin@example:/config/> edit nacm group operator -admin@example:/config/nacm/group/operator/> set user-name jacky -admin@example:/config/nacm/group/operator/> leave -``` +
admin@example:/config/> edit nacm group operator
+admin@example:/config/nacm/group/operator/> set user-name jacky
+admin@example:/config/nacm/group/operator/> leave
+
**Adding another admin:** -``` -admin@example:/config/> edit nacm group admin -admin@example:/config/nacm/group/admin/> set user-name alice -admin@example:/config/nacm/group/admin/> leave -``` +
admin@example:/config/> edit nacm group admin
+admin@example:/config/nacm/group/admin/> set user-name alice
+admin@example:/config/nacm/group/admin/> leave
+
**Guest user:** -``` -admin@example:/config/> edit nacm group guest -admin@example:/config/nacm/group/guest/> set user-name monitor -admin@example:/config/nacm/group/guest/> leave -``` +
admin@example:/config/> edit nacm group guest
+admin@example:/config/nacm/group/guest/> set user-name monitor
+admin@example:/config/nacm/group/guest/> leave
+
> [!TIP] > For technical details about NACM rule evaluation, module-name vs path @@ -363,12 +360,11 @@ cryptographic key material through global NACM rules. Notice how the hostname in the prompt does not change until the change is committed by issuing the `leave` command. -``` -admin@example:/config/> edit system -admin@example:/config/system/> set hostname myrouter -admin@example:/config/system/> leave +
admin@example:/config/> edit system
+admin@example:/config/system/> set hostname myrouter
+admin@example:/config/system/> leave
 admin@myrouter:/>
-```
+
The hostname is advertised over mDNS-SD in the `.local` domain. If another device already has claimed the `myrouter.local` CNAME, in our @@ -379,12 +375,11 @@ available devices on your LAN. In some cases you may want to set the device's *domain name* as well. This is handled the same way: -``` -admin@example:/config/> edit system -admin@example:/config/system/> set hostname foo.example.com -admin@example:/config/system/> leave +
admin@example:/config/> edit system
+admin@example:/config/system/> set hostname foo.example.com
+admin@example:/config/system/> leave
 admin@foo:/>
-```
+
Both host and domain name are stored in the system files `/etc/hosts` and `/etc/hostname`. The latter is exclusively for the host name. The @@ -406,12 +401,11 @@ built-in [`text-editor` command](cli/text-editor.md). > See the next section for how to change the editor used to something > you may be more familiar with. -``` -admin@example:/config/> edit system -admin@example:/config/system/> text-editor motd-banner -admin@example:/config/system/> leave +
admin@example:/config/> edit system
+admin@example:/config/system/> text-editor motd-banner
+admin@example:/config/system/> leave
 admin@example:/>
-```
+
Log out and log back in again to inspect the changes. @@ -427,13 +421,12 @@ as the `text-editor` command: To change the editor to GNU Nano: -``` -admin@example:/> configure -admin@example:/config/> edit system -admin@example:/config/system/> set text-editor nano -admin@example:/config/system/> leave +
admin@example:/> configure
+admin@example:/config/> edit system
+admin@example:/config/system/> set text-editor nano
+admin@example:/config/system/> leave
 admin@example:/>
-```
+
> [!IMPORTANT] > Configuration changes only take effect after issuing the `leave` @@ -447,18 +440,17 @@ The system supports both static and dynamic (DHCP) DNS setup. The locally configured (static) server is preferred over any acquired from a DHCP client. -``` -admin@example:/> configure -admin@example:/config/> edit system dns-resolver -admin@example:/config/system/dns-resolver/> set server google udp-and-tcp address 8.8.8.8 -admin@example:/config/system/dns-resolver/> show +
admin@example:/> configure
+admin@example:/config/> edit system dns-resolver
+admin@example:/config/system/dns-resolver/> set server google udp-and-tcp address 8.8.8.8
+admin@example:/config/system/dns-resolver/> show
 server google {
   udp-and-tcp {
     address 8.8.8.8;
   }
 }
-admin@example:/config/system/dns-resolver/> leave
-```
+admin@example:/config/system/dns-resolver/> leave
+
It is also possible to configure resolver options like timeout and retry attempts. See the YANG model for details, or use the built-in @@ -475,16 +467,15 @@ help system in the CLI. Below is an example configuration for enabling NTP with a specific server and the `iburst` option for faster initial synchronization. -``` -admin@example:/> configure -admin@example:/config/> edit system ntp -admin@example:/config/system/ntp/> set enabled -admin@example:/config/system/ntp/> set server ntp-pool -admin@example:/config/system/ntp/> set server ntp-pool udp address pool.ntp.org -admin@example:/config/system/ntp/> set server ntp-pool iburst -admin@example:/config/system/ntp/> set server ntp-pool prefer -admin@example:/config/system/ntp/> leave -``` +
admin@example:/> configure
+admin@example:/config/> edit system ntp
+admin@example:/config/system/ntp/> set enabled
+admin@example:/config/system/ntp/> set server ntp-pool
+admin@example:/config/system/ntp/> set server ntp-pool udp address pool.ntp.org
+admin@example:/config/system/ntp/> set server ntp-pool iburst
+admin@example:/config/system/ntp/> set server ntp-pool prefer
+admin@example:/config/system/ntp/> leave
+
This configuration enables the NTP client and sets the NTP server to `pool.ntp.org` with the `iburst` and `prefer` options. The `iburst` @@ -504,36 +495,38 @@ The status for NTP sources is availble in YANG and accessable with CLI/NETCONF/RESTCONF. To view the sources being used by the NTP client, run: -``` -admin@target:/> show ntp -ADDRESS MODE STATE STRATUM POLL-INTERVAL -192.168.1.1 server candidate 1 6 -192.168.2.1 server candidate 1 6 -192.168.3.1 server selected 1 6 -``` + +
admin@example:/> show ntp
+Mode                : Client
+Stratum             : 3
+Ref time (UTC)      : Sat Jan 24 23:41:42 2026
+
+ADDRESS         MODE    STATE     STRATUM  POLL
+147.78.228.41   server  outlier         2   64s
+192.168.0.1     server  unusable        0  128s
+176.126.86.247  server  selected        2   64s
+
### Show NTP Status To check the status of NTP synchronization (only availble in CLI), use the following command: -``` -admin@example:/> show ntp tracking -Reference ID : C0248F86 (192.36.143.134) -Stratum : 2 -Ref time (UTC) : Mon Oct 21 10:06:45 2024 -System time : 0.000000001 seconds slow of NTP time -Last offset : -3845.151367188 seconds -RMS offset : 3845.151367188 seconds -Frequency : 4.599 ppm slow -Residual freq : +1293.526 ppm -Skew : 12.403 ppm -Root delay : 1.024467230 seconds -Root dispersion : 0.273462683 seconds -Update interval : 0.0 seconds -Leap status : Normal -admin@example:/> -``` +
admin@example:/> show ntp tracking
+Reference ID        : 176.126.86.247
+Stratum             : 3
+Ref time (UTC)      : Sat Jan 24 23:41:42 2026
+System time         : 0.000000 seconds slow of NTP time
+Last offset         : -454779.375000000 seconds
+RMS offset          : 454779.375000000 seconds
+Frequency           : 0.000 ppm slow
+Residual freq       : -26.383 ppm
+Skew                : 1000000.000 ppm
+Root delay          : 0.007395 seconds
+Root dispersion     : 39.181149 seconds
+Update interval     : 0.0 seconds
+Leap status         : Normal
+
This output provides detailed information about the NTP status, including reference ID, stratum, time offsets, frequency, and root delay. @@ -546,3 +539,4 @@ reference ID, stratum, time offsets, frequency, and root delay. [2]: https://github.com/kernelkit/infix/blob/main/src/confd/yang/infix-system%402024-02-29.yang [3]: https://www.rfc-editor.org/rfc/rfc8341 [4]: https://chrony-project.org/doc/4.6.1/chronyc.html +[5]: https://linux.die.net/man/1/mkpasswd diff --git a/doc/tunnels.md b/doc/tunnels.md index 8d9d211f..a79f1413 100644 --- a/doc/tunnels.md +++ b/doc/tunnels.md @@ -28,14 +28,13 @@ IPv6 tunnels in two modes: A basic GRE tunnel for routing between two sites: -``` -admin@example:/> configure -admin@example:/config/> edit interface gre0 -admin@example:/config/interface/gre0/> set gre local 192.168.3.1 remote 192.168.3.2 -admin@example:/config/interface/gre0/> set ipv4 address 10.255.0.1 prefix-length 30 -admin@example:/config/interface/gre0/> leave +
admin@example:/> configure
+admin@example:/config/> edit interface gre0
+admin@example:/config/interface/gre0/> set gre local 192.168.3.1 remote 192.168.3.2
+admin@example:/config/interface/gre0/> set ipv4 address 10.255.0.1 prefix-length 30
+admin@example:/config/interface/gre0/> leave
 admin@example:/>
-```
+
This creates a Layer 3 tunnel between 192.168.3.1 and 192.168.3.2 using the outer IP addresses, with the tunnel itself using 10.255.0.0/30 for @@ -45,14 +44,13 @@ the inner IP addressing. GRETAP tunnels operate at Layer 2, allowing bridging across the tunnel: -``` -admin@example:/> configure -admin@example:/config/> edit interface gretap0 -admin@example:/config/interface/gretap0/> set type gretap -admin@example:/config/interface/gretap0/> set gre local 192.168.3.1 remote 192.168.3.2 -admin@example:/config/interface/gretap0/> leave +
admin@example:/> configure
+admin@example:/config/> edit interface gretap0
+admin@example:/config/interface/gretap0/> set type gretap
+admin@example:/config/interface/gretap0/> set gre local 192.168.3.1 remote 192.168.3.2
+admin@example:/config/interface/gretap0/> leave
 admin@example:/>
-```
+
GRETAP interfaces can be added to a bridge, bridging local and remote Ethernet segments. See the [Bridge Configuration](bridging.md) @@ -69,33 +67,31 @@ exchange routes. **Site A configuration:** -``` -admin@siteA:/> configure -admin@siteA:/config/> edit interface gre0 -admin@siteA:/config/interface/gre0/> set gre local 203.0.113.1 remote 203.0.113.2 -admin@siteA:/config/interface/gre0/> set ipv4 address 10.255.0.1 prefix-length 30 -admin@siteA:/config/interface/gre0/> set ipv4 forwarding -admin@siteA:/config/interface/gre0/> end -admin@siteA:/config/> edit routing control-plane-protocol ospfv2 name default ospf -admin@siteA:/config/routing/…/ospf/> set area 0.0.0.0 interface gre0 -admin@siteA:/config/routing/…/ospf/> leave +
admin@siteA:/> configure
+admin@siteA:/config/> edit interface gre0
+admin@siteA:/config/interface/gre0/> set gre local 203.0.113.1 remote 203.0.113.2
+admin@siteA:/config/interface/gre0/> set ipv4 address 10.255.0.1 prefix-length 30
+admin@siteA:/config/interface/gre0/> set ipv4 forwarding
+admin@siteA:/config/interface/gre0/> end
+admin@siteA:/config/> edit routing control-plane-protocol ospfv2 name default ospf
+admin@siteA:/config/routing/…/ospf/> set area 0.0.0.0 interface gre0
+admin@siteA:/config/routing/…/ospf/> leave
 admin@siteA:/>
-```
+
**Site B configuration:** -``` -admin@siteB:/> configure -admin@siteB:/config/> edit interface gre0 -admin@siteB:/config/interface/gre0/> set gre local 203.0.113.2 remote 203.0.113.1 -admin@siteB:/config/interface/gre0/> set ipv4 address 10.255.0.2 prefix-length 30 -admin@siteB:/config/interface/gre0/> set ipv4 forwarding -admin@siteB:/config/interface/gre0/> end -admin@siteB:/config/> edit routing control-plane-protocol ospfv2 name default ospf -admin@siteB:/config/routing/…/ospf/> set area 0.0.0.0 interface gre0 -admin@siteB:/config/routing/…/ospf/> leave +
admin@siteB:/> configure
+admin@siteB:/config/> edit interface gre0
+admin@siteB:/config/interface/gre0/> set gre local 203.0.113.2 remote 203.0.113.1
+admin@siteB:/config/interface/gre0/> set ipv4 address 10.255.0.2 prefix-length 30
+admin@siteB:/config/interface/gre0/> set ipv4 forwarding
+admin@siteB:/config/interface/gre0/> end
+admin@siteB:/config/> edit routing control-plane-protocol ospfv2 name default ospf
+admin@siteB:/config/routing/…/ospf/> set area 0.0.0.0 interface gre0
+admin@siteB:/config/routing/…/ospf/> leave
 admin@siteB:/>
-```
+
Once configured, OSPF will establish a neighbor relationship through the tunnel and exchange routes between the sites. For more info on OSPF @@ -118,11 +114,10 @@ The TTL setting controls the Time To Live value for the outer tunnel packets. By default, tunnels use a fixed TTL of 64, which allows packets to traverse multiple hops between tunnel endpoints. -``` -admin@example:/config/> edit interface gre0 -admin@example:/config/interface/gre0/> set gre ttl 255 -admin@example:/config/interface/gre0/> leave -``` +
admin@example:/config/> edit interface gre0
+admin@example:/config/interface/gre0/> set gre ttl 255
+admin@example:/config/interface/gre0/> leave
+
Valid values are 1-255, or the special value `inherit` which copies the TTL from the encapsulated packet. @@ -136,11 +131,10 @@ from the encapsulated packet. The ToS setting controls QoS marking for tunnel traffic: -``` -admin@example:/config/> edit interface gre0 -admin@example:/config/interface/gre0/> set gre tos 0x10 -admin@example:/config/interface/gre0/> leave -``` +
admin@example:/config/> edit interface gre0
+admin@example:/config/interface/gre0/> set gre tos 0x10
+admin@example:/config/interface/gre0/> leave
+
Valid values are 0-255 for fixed ToS/DSCP marking, or `inherit` (default) to copy the ToS value from the encapsulated packet. @@ -151,11 +145,10 @@ The `pmtu-discovery` setting can be used to control the Path MTU Discovery on GRE tunnels. When enabled (default), the tunnel respects the Don't Fragment (DF) bit and performs PMTU discovery: -``` -admin@example:/config/> edit interface gre0 -admin@example:/config/interface/gre0/> set gre pmtudisc false -admin@example:/config/interface/gre0/> leave -``` +
admin@example:/config/> edit interface gre0
+admin@example:/config/interface/gre0/> set gre pmtudisc false
+admin@example:/config/interface/gre0/> leave
+
Disabling PMTU discovery may be necessary in networks with broken ICMP filtering but can lead to suboptimal performance and fragmentation. @@ -175,15 +168,14 @@ Infix supports both IPv4 and IPv6 for VXLAN tunnel endpoints. > If you name your VXLAN interface `vxlanN`, where `N` is a number, the > CLI infers the interface type automatically. -``` -admin@example:/> configure -admin@example:/config/> edit interface vxlan100 -admin@example:/config/interface/vxlan100/> set vxlan local 192.168.3.1 -admin@example:/config/interface/vxlan100/> set vxlan remote 192.168.3.2 -admin@example:/config/interface/vxlan100/> set vxlan vni 100 -admin@example:/config/interface/vxlan100/> leave +
admin@example:/> configure
+admin@example:/config/> edit interface vxlan100
+admin@example:/config/interface/vxlan100/> set vxlan local 192.168.3.1
+admin@example:/config/interface/vxlan100/> set vxlan remote 192.168.3.2
+admin@example:/config/interface/vxlan100/> set vxlan vni 100
+admin@example:/config/interface/vxlan100/> leave
 admin@example:/>
-```
+
The VNI uniquely identifies the VXLAN segment and must match on both tunnel endpoints. @@ -193,16 +185,15 @@ tunnel endpoints. The default VXLAN UDP destination port is 4789 (IANA assigned). In some cases you may need to use a different port: -``` -admin@example:/> configure -admin@example:/config/> edit interface vxlan100 -admin@example:/config/interface/vxlan100/> set vxlan local 192.168.3.1 -admin@example:/config/interface/vxlan100/> set vxlan remote 192.168.3.2 -admin@example:/config/interface/vxlan100/> set vxlan vni 100 -admin@example:/config/interface/vxlan100/> set vxlan remote-port 8472 -admin@example:/config/interface/vxlan100/> leave +
admin@example:/> configure
+admin@example:/config/> edit interface vxlan100
+admin@example:/config/interface/vxlan100/> set vxlan local 192.168.3.1
+admin@example:/config/interface/vxlan100/> set vxlan remote 192.168.3.2
+admin@example:/config/interface/vxlan100/> set vxlan vni 100
+admin@example:/config/interface/vxlan100/> set vxlan remote-port 8472
+admin@example:/config/interface/vxlan100/> leave
 admin@example:/>
-```
+
The remote-port setting allows interoperability with systems using non-standard VXLAN ports. diff --git a/doc/upgrade.md b/doc/upgrade.md index 97ce32b9..88dd91b8 100644 --- a/doc/upgrade.md +++ b/doc/upgrade.md @@ -8,16 +8,14 @@ The _boot order_ defines which image is tried first, and is listed with the CLI `show software` command. It also shows Infix version installed per partition, and which image was used when booting (`STATE booted`). -``` -admin@example:/> show software -BOOT ORDER -primary secondary net +
admin@example:/> show software
+Boot order : primary secondary net
 
-NAME      STATE     VERSION                DATE
-primary   booted    v25.01.0               2025-04-25T10:15:00+00:00
-secondary inactive  v25.01.0               2025-04-25T10:07:20+00:00
+NAME       STATE     VERSION                DATE                     
+primary    booted    v25.01.0               2025-04-25T10:15:00+00:00
+secondary  inactive  v25.01.0               2025-04-25T10:07:20+00:00
 admin@example:/>
-```
+
YANG support for upgrading Infix, inspecting and _modifying_ the boot-order, is defined in [infix-system-software][2]. @@ -41,52 +39,47 @@ valid values. Example: View current boot order and change it: -``` -admin@example:/> show boot-order +
admin@example:/> show boot-order
 primary secondary net
-admin@example:/> set boot-order secondary primary net
-admin@example:/> show boot-order
+admin@example:/> set boot-order secondary primary net
+admin@example:/> show boot-order
 secondary primary net
 admin@example:/>
-```
+
Example: Set boot order to only try primary partition: -``` -admin@example:/> show boot-order +
admin@example:/> show boot-order
 secondary primary net
-admin@example:/> set boot-order primary
-admin@example:/> show boot-order
+admin@example:/> set boot-order primary
+admin@example:/> show boot-order
 primary
 admin@example:/>
-```
+
Example: Using tab-completion (press TAB to see available options): -``` -admin@example:/> set boot-order +
admin@example:/> set boot-order TAB
 net        primary    secondary
-admin@example:/> set boot-order secondary 
+admin@example:/> set boot-order secondary TAB
 net        primary    secondary
-admin@example:/> set boot-order secondary primary
-admin@example:/> show boot-order
+admin@example:/> set boot-order secondary primary
+admin@example:/> show boot-order
 secondary primary
 admin@example:/>
-```
+
The new boot order takes effect on the next reboot and can be verified with `show boot-order` or `show software`: -``` -admin@example:/> show software -BOOT ORDER -secondary primary +
admin@example:/> show software
+Boot order : secondary primary
 
-NAME      STATE     VERSION                DATE
-primary   booted    v25.01.0               2025-04-25T10:15:00+00:00
-secondary inactive  v25.01.0               2025-04-25T10:07:20+00:00
+NAME       STATE     VERSION                DATE                     
+primary    booted    v25.01.0               2025-04-25T10:15:00+00:00
+secondary  inactive  v25.01.0               2025-04-25T10:07:20+00:00
 admin@example:/>
-```
+
> [!NOTE] > The boot order is automatically updated when performing an upgrade. @@ -127,27 +120,28 @@ configuration before performing an upgrade. The backup is useful if the upgrade fails, and makes a later [downgrade](#downgrading) a smoother process. -``` -admin@example:/> dir /cfg +
admin@example:/> dir /cfg
 /cfg directory
 backup/             ssl/                startup-config.cfg
 
-admin@example:/> copy /cfg/startup-config.cfg /cfg/v25.01.0-startup-config.cfg
-admin@example:/> dir /cfg
+admin@example:/> copy /cfg/startup-config.cfg /cfg/v25.01.0-startup-config.cfg
+admin@example:/> dir /cfg
 /cfg directory
 backup/             ssl/                startup-config.cfg           v25.01.0-startup-config.cfg
 
-admin@example:/> 
-```
+admin@example:/>
+
*Upgrade:* Here the image *pkg bundle* was made available via TFTP. -``` -admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.03.1.pkg +
admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.03.1.pkg
 installing
   0% Installing
   0% Determining slot states
  10% Determining slot states done.
+...
+ 40% Checking slot rootfs.1 (secondary)
+ 46% Checking slot rootfs.1 (secondary) done.
 ...
  98% Copying image to rootfs.1
  99% Copying image to rootfs.1
@@ -156,14 +150,13 @@ installing
 100% Installing done.
 Installing `tftp://198.18.117.1/infix-aarch64-25.03.1.pkg` succeeded
 admin@example:/>
-```
+
*Reboot:* The unit will boot on the other partition, with the newly installed image. The `Loading startup-config` step conducts migration of startup configuration if applicable. -``` -admin@example:/> reboot +
admin@example:/> reboot
 [ OK ] Stopping Static routing daemon
 [ OK ] Stopping Zebra routing daemon
 ...
@@ -173,7 +166,7 @@ admin@example:/> reboot
 [ OK ] Starting Status daemon
 
 Infix OS — Immutable.Friendly.Secure v25.03.1 (ttyS0)
-example login: admin
+example login: admin
 Password:
 .-------.
 |  . .  | Infix OS — Immutable.Friendly.Secure
@@ -182,19 +175,18 @@ Password:
 
 Run the command 'cli' for interactive OAM
 
-admin@example:~$ cli
+admin@example:~$ cli
 
 See the 'help' command for an introduction to the system
 
-admin@example:/> show software
-BOOT ORDER
-secondary primary net
+admin@example:/> show software
+Boot order : secondary primary net
 
-NAME      STATE     VERSION                DATE
-primary   inactive  v25.01.0               2025-04-25T10:15:00+00:00
-secondary booted    v25.03.1               2025-04-25T10:24:31+00:00
+NAME       STATE     VERSION                DATE                     
+primary    inactive  v25.01.0               2025-04-25T10:15:00+00:00
+secondary  booted    v25.03.1               2025-04-25T10:24:31+00:00
 admin@example:/>
-```
+
As shown, the *boot order* has been updated, so that *secondary* is now the preferred boot source. @@ -217,20 +209,18 @@ numbering). The startup configuration is migrated to `1.5` definitions and stored, while a backup previous startup configuration is stored in directory `/cfg/backup/`. -``` -admin@example:/> dir /cfg/backup/ +
admin@example:/> dir /cfg/backup/
 /cfg/backup/ directory
 startup-config-1.4.cfg
 
 admin@example:/>
-```
+
The modifications made to the startup configuration can be viewed by comparing the files from the *shell*. An example is shown below. -``` -admin@example:/> exit -admin@example:~$ diff /cfg/backup/startup-config-1.4.cfg /cfg/startup-config.cfg +
admin@example:/> exit
+admin@example:~$ diff /cfg/backup/startup-config-1.4.cfg /cfg/startup-config.cfg
 --- /cfg/backup/startup-config-1.4.cfg
 +++ /cfg/startup-config.cfg
 ...
@@ -244,7 +234,7 @@ admin@example:~$ diff /cfg/backup/startup-config-1.4.cfg /cfg/startup-config.cfg
 +    "version": "1.5"
 ...
 admin@example:~$
-```
+
## Downgrading @@ -259,16 +249,14 @@ startup configuration before rebooting. In both cases we start out with a unit running Infix v25.03.1, and wish to downgrade to v25.01.0. -``` -admin@example:/> show software -BOOT ORDER -primary secondary net +
admin@example:/> show software
+Boot order : primary secondary net
 
-NAME      STATE     VERSION                DATE
-primary   booted    v25.03.1               2025-04-25T11:36:26+00:00
-secondary inactive  v25.03.1               2025-04-25T10:24:31+00:00
+NAME       STATE     VERSION                DATE                     
+primary    booted    v25.03.1               2025-04-25T11:36:26+00:00
+secondary  inactive  v25.03.1               2025-04-25T10:24:31+00:00
 admin@example:/>
-```
+
### With Backup `startup-config` @@ -292,24 +280,22 @@ running Infix v25.01.0 on the unit. See section [Upgrading](#upgrading) above for more information. In the following example, there is a backup file available named `v25.01.0-startup-config.cfg`: -``` -admin@example:/> dir /cfg +
admin@example:/> dir /cfg
 /cfg directory
 backup/       ssl/       startup-config.cfg    v25.01.0-startup-config.cfg
 
-admin@example:/> 
-```
+admin@example:/>
+
The alternative is to use a startup config implicitly backed up by the system as part of [Configuration Migration](#configuration-migration). -``` -admin@example:/> dir /cfg/backup/ +
admin@example:/> dir /cfg/backup/
 /cfg/backup/ directory
 startup-config-1.4.cfg
 
 admin@example:/>
-```
+
> [!CAUTION] > Using a backup configuration file stored when the unit was running the @@ -330,8 +316,7 @@ config*. *Use `upgrade` command to downgrade:* -``` -admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.01.0.pkg +
admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.01.0.pkg
 installing
   0% Installing
   0% Determining slot states
@@ -342,35 +327,32 @@ installing
 100% Installing done.
 Installing `tftp://198.18.117.1/infix-aarch64-25.01.0.pkg` succeeded
 admin@example:/>
-```
+
*Apply the backup configuration file:* It is recommended to use a backup configuration file for the Infix version to downgrade to, if there is one available. -``` -admin@example:/> copy /cfg/v25.01.0-startup-config.cfg /cfg/startup-config.cfg -Overwrite existing file /cfg/startup-config.cfg (y/N)? y +
admin@example:/> copy /cfg/v25.01.0-startup-config.cfg /cfg/startup-config.cfg
+Overwrite existing file /cfg/startup-config.cfg (y/N)? y
 admin@example:/>
-```
+
An alternative is to use a backup file stored when the system conducted a [configuration migration](#configuration-migration). See the *caution* note above. -``` -admin@example:/> copy /cfg/backup/startup-config-1.4.cfg /cfg/startup-config.cfg -Overwrite existing file /cfg/startup-config.cfg (y/N)? y +
admin@example:/> copy /cfg/backup/startup-config-1.4.cfg /cfg/startup-config.cfg
+Overwrite existing file /cfg/startup-config.cfg (y/N)? y
 admin@example:/>
-```
+
*Reboot:* The unit will come up with the applied backup configuration. -``` -admin@example:/> reboot +
admin@example:/> reboot
 [ OK ] Saving system clock to file
 [ OK ] Stopping Software update service
 [ OK ] Stopping Status daemon
@@ -384,7 +366,7 @@ admin@example:/> reboot
 
 Infix OS — Immutable.Friendly.Secure v25.01.0 (ttyS0)
 example login:
-```
+
> [!NOTE] > If the unit despite these measures ends up in *failure config*, see @@ -403,8 +385,7 @@ its default login credentials[^1]. *Use `upgrade` command to downgrade:* -``` -admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.01.0.pkg +
admin@example:/> upgrade tftp://198.18.117.1/infix-aarch64-25.01.0.pkg
 installing
   0% Installing
   0% Determining slot states
@@ -415,7 +396,7 @@ installing
 100% Installing done.
 Installing `tftp://198.18.117.1/infix-aarch64-25.01.0.pkg` succeeded
 admin@example:/>
-```
+
*Reboot:* @@ -426,8 +407,7 @@ config][3]. This is what is seen on the console when this situation occurs. Note that the login prompt displays `failed` as part of the *hostname*. -``` -admin@example:/> reboot +
admin@example:/> reboot
 [ OK ] Saving system clock to file
 [ OK ] Stopping Software update service
 [ OK ] Stopping Status daemon
@@ -444,32 +424,30 @@ Infix OS — Immutable.Friendly.Secure v25.01.0 (ttyS0)
 
 ERROR: Corrupt startup-config, system has reverted to default login credentials
 failed-00-00-00 login:
-```
+
To remedy a situation like this, you can login with the unit's *default login credentials*, preferrably via a [console port][4]. The unit's default credentials are typically printed on a sticker on the unit. -``` -failed-00-00-00 login: admin +
failed-00-00-00 login: admin
 Password:
 
 Run the command 'cli' for interactive OAM
 
 admin@failed-00-00-00:~$
-```
+
When it is *safe* from a network operations perspective, you can conduct a factory reset and reboot. It is recommended to remove the unit from any production network before doing this, as a factory reset may enable undesired connectivity between the unit's ports. -``` -admin@failed-00-00-00:~$ factory -Factory reset device (y/N)? y +
admin@failed-00-00-00:~$ factory
+Factory reset device (y/N)? y
 factory: scheduled factory reset on next boot.
-Reboot now to perform reset, (y/N)? y
+Reboot now to perform reset, (y/N)? y
 [ OK ] Saving system time (UTC) to RTC
 [ OK ] Stopping mDNS alias advertiser
 ...
@@ -485,7 +463,7 @@ Please press Enter to activate this console.
 
 Infix OS — Immutable.Friendly.Secure v25.01.0 (ttyS0)
 example login:
-```
+
Continued configuration is done as with any unit after factory reset. diff --git a/doc/vpn-wireguard.md b/doc/vpn-wireguard.md index 1daa1360..a5ceff8d 100644 --- a/doc/vpn-wireguard.md +++ b/doc/vpn-wireguard.md @@ -41,27 +41,25 @@ and saves it to `publickey`. **Import the private key into the keystore:** -``` -admin@example:/> configure -admin@example:/config/> edit keystore asymmetric-key wg-site-a -admin@example:/config/keystore/asymmetric-key/wg-site-a/> set public-key-format x25519-public-key-format -admin@example:/config/keystore/asymmetric-key/wg-site-a/> set private-key-format x25519-private-key-format -admin@example:/config/keystore/asymmetric-key/wg-site-a/> set public-key bN1CwZ1lTP6KsrCwZ1lTP6KsrCwZ1lTP6KsrCwZ1lTP= -admin@example:/config/keystore/asymmetric-key/wg-site-a/> set private-key aMqBvZqkSP5JrqBvZqkSP5JrqBvZqkSP5JrqBvZqkSP= -admin@example:/config/keystore/asymmetric-key/wg-site-a/> leave +
admin@example:/> configure
+admin@example:/config/> edit keystore asymmetric-key wg-site-a
+admin@example:/config/keystore/asymmetric-key/wg-site-a/> set public-key-format x25519-public-key-format
+admin@example:/config/keystore/asymmetric-key/wg-site-a/> set private-key-format x25519-private-key-format
+admin@example:/config/keystore/asymmetric-key/wg-site-a/> set public-key bN1CwZ1lTP6KsrCwZ1lTP6KsrCwZ1lTP6KsrCwZ1lTP=
+admin@example:/config/keystore/asymmetric-key/wg-site-a/> set private-key aMqBvZqkSP5JrqBvZqkSP5JrqBvZqkSP5JrqBvZqkSP=
+admin@example:/config/keystore/asymmetric-key/wg-site-a/> leave
 admin@example:/>
-```
+
**Import peer public keys into the truststore:** -``` -admin@example:/> configure -admin@example:/config/> edit truststore public-key-bag wg-peers public-key peer-b -admin@example:/config/truststore/…/peer-b/> set public-key-format x25519-public-key-format -admin@example:/config/truststore/…/peer-b/> set public-key PEER_PUBLIC_KEY_HERE -admin@example:/config/truststore/…/peer-b/> leave +
admin@example:/> configure
+admin@example:/config/> edit truststore public-key-bag wg-peers public-key peer-b
+admin@example:/config/truststore/…/peer-b/> set public-key-format x25519-public-key-format
+admin@example:/config/truststore/…/peer-b/> set public-key PEER_PUBLIC_KEY_HERE
+admin@example:/config/truststore/…/peer-b/> leave
 admin@example:/>
-```
+
> [!IMPORTANT] > Keep private keys secure! Never share your private key. Only exchange @@ -78,37 +76,35 @@ A basic WireGuard tunnel between two sites: **Site A configuration:** -``` -admin@siteA:/> configure -admin@siteA:/config/> edit interface wg0 -admin@siteA:/config/interface/wg0/> set wireguard listen-port 51820 -admin@siteA:/config/interface/wg0/> set wireguard private-key wg-site-a -admin@siteA:/config/interface/wg0/> set ipv4 address 10.0.0.1 prefix-length 24 -admin@siteA:/config/interface/wg0/> edit wireguard peer wg-peers peer-b -admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> set endpoint 203.0.113.2 -admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> set endpoint-port 51820 -admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> set allowed-ips 10.0.0.2/32 -admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> set persistent-keepalive 25 -admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> leave +
admin@siteA:/> configure
+admin@siteA:/config/> edit interface wg0
+admin@siteA:/config/interface/wg0/> set wireguard listen-port 51820
+admin@siteA:/config/interface/wg0/> set wireguard private-key wg-site-a
+admin@siteA:/config/interface/wg0/> set ipv4 address 10.0.0.1 prefix-length 24
+admin@siteA:/config/interface/wg0/> edit wireguard peer wg-peers peer-b
+admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> set endpoint 203.0.113.2
+admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> set endpoint-port 51820
+admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> set allowed-ips 10.0.0.2/32
+admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> set persistent-keepalive 25
+admin@siteA:/config/interface/…/wg-peers/peer/peer-b/> leave
 admin@siteA:/>
-```
+
**Site B configuration:** -``` -admin@siteB:/> configure -admin@siteB:/config/> edit interface wg0 -admin@siteB:/config/interface/wg0/> set wireguard listen-port 51820 -admin@siteB:/config/interface/wg0/> set wireguard private-key wg-site-b -admin@siteB:/config/interface/wg0/> set ipv4 address 10.0.0.2 prefix-length 24 -admin@siteB:/config/interface/wg0/> edit wireguard peer wg-peers peer-a -admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> set endpoint 203.0.113.1 -admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> set endpoint-port 51820 -admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> set allowed-ips 10.0.0.1/32 -admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> set persistent-keepalive 25 -admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> leave +
admin@siteB:/> configure
+admin@siteB:/config/> edit interface wg0
+admin@siteB:/config/interface/wg0/> set wireguard listen-port 51820
+admin@siteB:/config/interface/wg0/> set wireguard private-key wg-site-b
+admin@siteB:/config/interface/wg0/> set ipv4 address 10.0.0.2 prefix-length 24
+admin@siteB:/config/interface/wg0/> edit wireguard peer wg-peers peer-a
+admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> set endpoint 203.0.113.1
+admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> set endpoint-port 51820
+admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> set allowed-ips 10.0.0.1/32
+admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> set persistent-keepalive 25
+admin@siteB:/config/interface/…/wg-peers/peer/peer-a/> leave
 admin@siteB:/>
-```
+
This creates an encrypted tunnel with Site A at 10.0.0.1 and Site B at 10.0.0.2. @@ -130,10 +126,9 @@ For a simple point-to-point tunnel, you typically allow only the peer's tunnel IP address (e.g., `10.0.0.2/32`). For site-to-site VPNs connecting entire networks, include the remote network prefixes: -``` -admin@example:/config/interface/…/wg-peers/peer/peer-a/> set allowed-ips 10.0.0.2/32 -admin@example:/config/interface/…/wg-peers/peer/peer-a/> set allowed-ips 192.168.2.0/24 -``` +
admin@example:/config/interface/…/wg-peers/peer/peer-a/> set allowed-ips 10.0.0.2/32
+admin@example:/config/interface/…/wg-peers/peer/peer-a/> set allowed-ips 192.168.2.0/24
+
This allows traffic to/from the peer at 10.0.0.2 and routes traffic destined for 192.168.2.0/24 through this peer. @@ -174,35 +169,34 @@ Settings that support bag-level defaults and per-peer overrides: **Example with bag-level defaults:** -``` -admin@example:/> configure -admin@example:/config/> edit interface wg0 -admin@example:/config/interface/wg0/> set wireguard listen-port 51820 -admin@example:/config/interface/wg0/> set wireguard private-key wg-key -admin@example:/config/interface/wg0/> set ipv4 address 10.0.0.1 prefix-length 24 +
admin@example:/> configure
+admin@example:/config/> edit interface wg0
+admin@example:/config/interface/wg0/> set wireguard listen-port 51820
+admin@example:/config/interface/wg0/> set wireguard private-key wg-key
+admin@example:/config/interface/wg0/> set ipv4 address 10.0.0.1 prefix-length 24
 
 # Configure defaults for all peers in the 'branch-offices' bag
-admin@example:/config/interface/wg0/> edit wireguard peers branch-offices
-admin@example:/config/interface/…/wireguard/peers/branch-offices/> set endpoint-port 51820
-admin@example:/config/interface/…/wireguard/peers/branch-offices/> set persistent-keepalive 25
-admin@example:/config/interface/…/wireguard/peers/branch-offices/> end
+admin@example:/config/interface/wg0/> edit wireguard peers branch-offices
+admin@example:/config/interface/…/wireguard/peers/branch-offices/> set endpoint-port 51820
+admin@example:/config/interface/…/wireguard/peers/branch-offices/> set persistent-keepalive 25
+admin@example:/config/interface/…/wireguard/peers/branch-offices/> end
 
 # Configure peer-specific settings (inherits endpoint-port and keepalive from bag)
-admin@example:/config/interface/…/wireguard/peers/branch-offices/> edit peer office-east
-admin@example:/config/interface/…/branch-offices/peer/office-east/> set endpoint 203.0.113.10
-admin@example:/config/interface/…/branch-offices/peer/office-east/> set allowed-ips 10.0.0.10/32
-admin@example:/config/interface/…/branch-offices/peer/office-east/> set allowed-ips 192.168.10.0/24
-admin@example:/config/interface/…/branch-offices/peer/office-east/> end
+admin@example:/config/interface/…/wireguard/peers/branch-offices/> edit peer office-east
+admin@example:/config/interface/…/branch-offices/peer/office-east/> set endpoint 203.0.113.10
+admin@example:/config/interface/…/branch-offices/peer/office-east/> set allowed-ips 10.0.0.10/32
+admin@example:/config/interface/…/branch-offices/peer/office-east/> set allowed-ips 192.168.10.0/24
+admin@example:/config/interface/…/branch-offices/peer/office-east/> end
 
 # Another peer with an override for persistent-keepalive
-admin@example:/config/interface/…/wireguard/peers/branch-offices/> edit peer office-west
-admin@example:/config/interface/…/branch-offices/peer/office-west/> set endpoint 203.0.113.20
-admin@example:/config/interface/…/branch-offices/peer/office-west/> set allowed-ips 10.0.0.20/32
-admin@example:/config/interface/…/branch-offices/peer/office-west/> set allowed-ips 192.168.20.0/24
-admin@example:/config/interface/…/branch-offices/peer/office-west/> set persistent-keepalive 10
-admin@example:/config/interface/…/branch-offices/peer/office-west/> leave
+admin@example:/config/interface/…/wireguard/peers/branch-offices/> edit peer office-west
+admin@example:/config/interface/…/branch-offices/peer/office-west/> set endpoint 203.0.113.20
+admin@example:/config/interface/…/branch-offices/peer/office-west/> set allowed-ips 10.0.0.20/32
+admin@example:/config/interface/…/branch-offices/peer/office-west/> set allowed-ips 192.168.20.0/24
+admin@example:/config/interface/…/branch-offices/peer/office-west/> set persistent-keepalive 10
+admin@example:/config/interface/…/branch-offices/peer/office-west/> leave
 admin@example:/>
-```
+
In this example: - Both peers inherit `endpoint-port 51820` and `persistent-keepalive 25` from the bag @@ -235,13 +229,12 @@ then add the remote network to `allowed-ips` and configure static routes. For mobile clients or peers without fixed IPs, omit the `endpoint` setting. WireGuard learns the peer's endpoint from authenticated incoming packets: -``` -admin@hub:/> configure -admin@hub:/config/> edit interface wg0 wireguard peers wg-peers peer mobile-client -admin@hub:/config/interface/…/wg-peers/peer/mobile-client/> set allowed-ips 10.0.0.10/32 -admin@hub:/config/interface/…/wg-peers/peer/mobile-client/> leave +
admin@hub:/> configure
+admin@hub:/config/> edit interface wg0 wireguard peers wg-peers peer mobile-client
+admin@hub:/config/interface/…/wg-peers/peer/mobile-client/> set allowed-ips 10.0.0.10/32
+admin@hub:/config/interface/…/wg-peers/peer/mobile-client/> leave
 admin@hub:/>
-```
+
The mobile client configures the hub's endpoint normally. The hub learns and tracks the mobile client's changing IP address automatically. @@ -256,59 +249,57 @@ sites connect to a central hub. **Hub configuration:** -``` -admin@hub:/> configure -admin@hub:/config/> edit interface wg0 -admin@hub:/config/interface/wg0/> set ipv4 address 10.0.0.1 prefix-length 24 -admin@hub:/config/interface/wg0/> set wireguard listen-port 51820 -admin@hub:/config/interface/wg0/> set wireguard private-key wg-hub -admin@hub:/config/interface/wg0/> edit wireguard peers wg-peers +
admin@hub:/> configure
+admin@hub:/config/> edit interface wg0
+admin@hub:/config/interface/wg0/> set ipv4 address 10.0.0.1 prefix-length 24
+admin@hub:/config/interface/wg0/> set wireguard listen-port 51820
+admin@hub:/config/interface/wg0/> set wireguard private-key wg-hub
+admin@hub:/config/interface/wg0/> edit wireguard peers wg-peers
 
 # Spoke 1
-admin@hub:/config/interface/…/wireguard/peers/wg-peers/> edit peer spoke1
-admin@hub:/config/interface/…/wg-peers/peer/spoke1/> set allowed-ips 10.0.0.2/32
-admin@hub:/config/interface/…/wg-peers/peer/spoke1/> set allowed-ips 192.168.1.0/24
-admin@hub:/config/interface/…/wg-peers/peer/spoke1/> end
+admin@hub:/config/interface/…/wireguard/peers/wg-peers/> edit peer spoke1
+admin@hub:/config/interface/…/wg-peers/peer/spoke1/> set allowed-ips 10.0.0.2/32
+admin@hub:/config/interface/…/wg-peers/peer/spoke1/> set allowed-ips 192.168.1.0/24
+admin@hub:/config/interface/…/wg-peers/peer/spoke1/> end
 
 # Spoke 2
-admin@hub:/config/interface/…/wireguard/peers/wg-peers/> edit peer spoke2
-admin@hub:/config/interface/…/wg-peers/peer/spoke2/> set allowed-ips 10.0.0.3/32
-admin@hub:/config/interface/…/wg-peers/peer/spoke2/> set allowed-ips 192.168.2.0/24
-admin@hub:/config/interface/…/wg-peers/peer/spoke2/> leave
+admin@hub:/config/interface/…/wireguard/peers/wg-peers/> edit peer spoke2
+admin@hub:/config/interface/…/wg-peers/peer/spoke2/> set allowed-ips 10.0.0.3/32
+admin@hub:/config/interface/…/wg-peers/peer/spoke2/> set allowed-ips 192.168.2.0/24
+admin@hub:/config/interface/…/wg-peers/peer/spoke2/> leave
 
 # Add routes for spoke networks
-admin@hub:/> configure
-admin@hub:/config/> edit routing control-plane-protocol static name default
-admin@hub:/config/routing/…/static/name/default/> set ipv4 route 192.168.1.0/24 wg0
-admin@hub:/config/routing/…/static/name/default/> set ipv4 route 192.168.2.0/24 wg0
-admin@hub:/config/routing/…/static/name/default/> leave
+admin@hub:/> configure
+admin@hub:/config/> edit routing control-plane-protocol static name default
+admin@hub:/config/routing/…/static/name/default/> set ipv4 route 192.168.1.0/24 wg0
+admin@hub:/config/routing/…/static/name/default/> set ipv4 route 192.168.2.0/24 wg0
+admin@hub:/config/routing/…/static/name/default/> leave
 admin@hub:/>
-```
+
**Spoke 1 configuration:** -``` -admin@spoke1:/> configure -admin@spoke1:/config/> edit interface wg0 -admin@spoke1:/config/interface/wg0/> set wireguard listen-port 51820 -admin@spoke1:/config/interface/wg0/> set wireguard private-key wg-spoke1 -admin@spoke1:/config/interface/wg0/> set ipv4 address 10.0.0.2 prefix-length 24 -admin@spoke1:/config/interface/wg0/> edit wireguard peers wg-peers peer hub -admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set endpoint 203.0.113.1 -admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set endpoint-port 51820 -admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set allowed-ips 10.0.0.1/32 -admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set allowed-ips 10.0.0.3/32 -admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set allowed-ips 192.168.0.0/24 -admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set allowed-ips 192.168.2.0/24 -admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set persistent-keepalive 25 -admin@spoke1:/config/interface/…/wg-peers/peer/hub/> leave -admin@spoke1:/> configure -admin@spoke1:/config/> edit routing control-plane-protocol static name default -admin@spoke1:/config/routing/…/static/name/default/> set ipv4 route 192.168.0.0/24 wg0 -admin@spoke1:/config/routing/…/static/name/default/> set ipv4 route 192.168.2.0/24 wg0 -admin@spoke1:/config/routing/…/static/name/default/> leave +
admin@spoke1:/> configure
+admin@spoke1:/config/> edit interface wg0
+admin@spoke1:/config/interface/wg0/> set wireguard listen-port 51820
+admin@spoke1:/config/interface/wg0/> set wireguard private-key wg-spoke1
+admin@spoke1:/config/interface/wg0/> set ipv4 address 10.0.0.2 prefix-length 24
+admin@spoke1:/config/interface/wg0/> edit wireguard peers wg-peers peer hub
+admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set endpoint 203.0.113.1
+admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set endpoint-port 51820
+admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set allowed-ips 10.0.0.1/32
+admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set allowed-ips 10.0.0.3/32
+admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set allowed-ips 192.168.0.0/24
+admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set allowed-ips 192.168.2.0/24
+admin@spoke1:/config/interface/…/wg-peers/peer/hub/> set persistent-keepalive 25
+admin@spoke1:/config/interface/…/wg-peers/peer/hub/> leave
+admin@spoke1:/> configure
+admin@spoke1:/config/> edit routing control-plane-protocol static name default
+admin@spoke1:/config/routing/…/static/name/default/> set ipv4 route 192.168.0.0/24 wg0
+admin@spoke1:/config/routing/…/static/name/default/> set ipv4 route 192.168.2.0/24 wg0
+admin@spoke1:/config/routing/…/static/name/default/> leave
 admin@spoke1:/>
-```
+
This configuration allows Spoke 1 to reach both the hub network (192.168.0.0/24) and Spoke 2's network (192.168.2.0/24) via the hub, enabling spoke-to-spoke @@ -319,9 +310,8 @@ communication through the central hub. The `persistent-keepalive` setting sends periodic packets to keep the tunnel active through NAT devices and firewalls: -``` -admin@example:/config/interface/…/wg-peers/peer/hub/> set persistent-keepalive 25 -``` +
admin@example:/config/interface/…/wg-peers/peer/hub/> set persistent-keepalive 25
+
This is particularly important when: @@ -340,21 +330,20 @@ for peers with public static IPs that initiate connections. WireGuard fully supports IPv6 for tunnel endpoints: -``` -admin@example:/> configure -admin@example:/config/> edit interface wg0 -admin@example:/config/interface/wg0/> set wireguard listen-port 51820 -admin@example:/config/interface/wg0/> set wireguard private-key wg-key -admin@example:/config/interface/wg0/> set ipv4 address 10.0.0.1 prefix-length 24 -admin@example:/config/interface/wg0/> set ipv6 address fd00::1 prefix-length 64 -admin@example:/config/interface/wg0/> edit wireguard peers wg-peers peer remote -admin@example:/config/interface/…/wg-peers/peer/remote/> set endpoint 2001:db8::2 -admin@example:/config/interface/…/wg-peers/peer/remote/> set endpoint-port 51820 -admin@example:/config/interface/…/wg-peers/peer/remote/> set allowed-ips 10.0.0.2/32 -admin@example:/config/interface/…/wg-peers/peer/remote/> set allowed-ips fd00::2/128 -admin@example:/config/interface/…/wg-peers/peer/remote/> leave +
admin@example:/> configure
+admin@example:/config/> edit interface wg0
+admin@example:/config/interface/wg0/> set wireguard listen-port 51820
+admin@example:/config/interface/wg0/> set wireguard private-key wg-key
+admin@example:/config/interface/wg0/> set ipv4 address 10.0.0.1 prefix-length 24
+admin@example:/config/interface/wg0/> set ipv6 address fd00::1 prefix-length 64
+admin@example:/config/interface/wg0/> edit wireguard peers wg-peers peer remote
+admin@example:/config/interface/…/wg-peers/peer/remote/> set endpoint 2001:db8::2
+admin@example:/config/interface/…/wg-peers/peer/remote/> set endpoint-port 51820
+admin@example:/config/interface/…/wg-peers/peer/remote/> set allowed-ips 10.0.0.2/32
+admin@example:/config/interface/…/wg-peers/peer/remote/> set allowed-ips fd00::2/128
+admin@example:/config/interface/…/wg-peers/peer/remote/> leave
 admin@example:/>
-```
+
WireGuard can carry both IPv4 and IPv6 traffic regardless of whether the tunnel endpoints use IPv4 or IPv6. @@ -363,13 +352,12 @@ tunnel endpoints use IPv4 or IPv6. Check WireGuard interface status and peer connections: -``` -admin@example:/> show interfaces +
admin@example:/> show interfaces
 wg0             wireguard  UP          2 peers (1 up)
                 ipv4                   10.0.0.1/24 (static)
                 ipv6                   fd00::1/64 (static)
 
-admin@example:/> show interfaces wg0
+admin@example:/> show interfaces wg0
 name                : wg0
 type                : wireguard
 index               : 12
@@ -389,7 +377,7 @@ peers               : 2
     latest handshake  : 2025-12-09T09:15:22+0000
     transfer tx       : 45120 bytes
     transfer rx       : 32768 bytes
-```
+
The connection status shows `UP` if a handshake occurred within the last 3 minutes, indicating an active tunnel. The `latest handshake` timestamp shows @@ -416,17 +404,16 @@ cO2DxZ2mUQ7LtsrDxZ2mUQ7LtsrDxZ2mUQ7LtsrDxZ2m= **Import the preshared key into the keystore:** -``` -admin@example:/> configure -admin@example:/config/> edit keystore symmetric-key wg-psk -admin@example:/config/keystore/symmetric-key/wg-psk/> set key-format wireguard-symmetric-key-format -admin@example:/config/keystore/symmetric-key/wg-psk/> set key cO2DxZ2mUQ7LtsrDxZ2mUQ7LtsrDxZ2mUQ7LtsrDxZ2m= -admin@example:/config/keystore/symmetric-key/wg-psk/> end -admin@example:/config/interface/wg0/> edit wireguard peers wg-peers peer remote -admin@example:/config/interface/…/wg-peers/peer/remote/> set preshared-key wg-psk -admin@example:/config/interface/…/wg-peers/peer/remote/> leave +
admin@example:/> configure
+admin@example:/config/> edit keystore symmetric-key wg-psk
+admin@example:/config/keystore/symmetric-key/wg-psk/> set key-format wireguard-symmetric-key-format
+admin@example:/config/keystore/symmetric-key/wg-psk/> set key cO2DxZ2mUQ7LtsrDxZ2mUQ7LtsrDxZ2mUQ7LtsrDxZ2m=
+admin@example:/config/keystore/symmetric-key/wg-psk/> end
+admin@example:/config/interface/wg0/> edit wireguard peers wg-peers peer remote
+admin@example:/config/interface/…/wg-peers/peer/remote/> set preshared-key wg-psk
+admin@example:/config/interface/…/wg-peers/peer/remote/> leave
 admin@example:/>
-```
+
The preshared key must be securely shared between both peers and configured on both sides. diff --git a/doc/wifi.md b/doc/wifi.md index 3aa7d3f3..da47f85f 100644 --- a/doc/wifi.md +++ b/doc/wifi.md @@ -90,7 +90,7 @@ Reboot when the radio becomes available. Before configuring WiFi interfaces, you must first configure the WiFi radio. Radios are automatically discovered and named `radio0`, `radio1`, etc. -### Country Code and Regulatory Compliance +### Country Code ⚠ The radio defaults to "00" for World domain, but some systems may ship with a factory default country code (typically "DE" for the BPi-R3). @@ -160,7 +160,7 @@ admin@example:/config/hardware/component/radio0/wifi-radio/> leave > TX power and channel width are automatically determined by the driver > based on regulatory constraints, PHY mode, and hardware capabilities. -### WiFi 6 (802.11ax) Support +### WiFi 6 Support WiFi 6 (802.11ax) is always enabled in AP mode on all bands, providing improved performance through features like OFDMA, BSS Coloring, and beamforming. @@ -247,7 +247,7 @@ Station mode connects to an existing Wi-Fi network. Before configuring station mode, follow the "Discovering Available Networks (Scanning)" section above to scan for available networks and identify the SSID you want to connect to. -### Step 1: Configure WiFi Password +### Step 1: Configure Password Create a keystore entry for your WiFi password (8-63 characters): @@ -344,7 +344,7 @@ admin@example:/config/interface/wifi0/> leave - `wpa3-personal`: WPA3-SAE (more secure, requires WPA3-capable clients) - `wpa2-wpa3-personal`: Mixed mode (maximum compatibility) -### Hidden Network (SSID Hiding) +### SSID Hiding To create a hidden network that doesn't broadcast its SSID: