offspot-config

A library to read/write an Offspot runtime config and a collection of scripts to use it within offspot/base-image.

Scripts Usage

Launched via offspot-runtime-config-fromfile, it:

• reads a YAML config file and changes the offspot configuration accordingly.
• starts associated services

Its primary goal is to allow one to change some key offspot configuration upon next boot by changing one file (stored in FAT32 /boot/firmware –so writable anywhere), following a descriptive format.

Notes:

• It is not a configuration reference. It only lists the changes requested (whatever the status of those settings) at next boot. In an already configured system the file should be an empty YAML document (---).
• While -fromfile reads a YAML file, it mostly runs individual, feature-specific scripts that takes parameters on the command-line.
• it's a configuration tool that must be ran as root.

offspot-runtime-config-fromfile --debug /boot/firmware/offspot.yaml

• --debug will show you what exact parameters were passed to individual scripts so you can manually launch them should there be an issue.
• this script is meant to be run automaticaly on boot (via systemd) before docker-compose.service.
• It returns 0 on success, 1 on general failures and 2 on misconfiguration (invalid parameter). Same goes for individual scripts.
• it starts hostapd, dnsmasq and iptables-restore automatically. If you start it on boot, disable them (systemctl disable hostapd dnsmasq)

Installation

⚠️ Warning: only tested on offspot base-image (raspiOS bookworm)

apt install hostapd dnsmasq dhcpcd5 python3-yaml python3-pip
systemctl unmask hostapd
systemctl disable hostapd dnsmasq
pip3 install offspot-config

Library usage

pip3 install offspot-config

from offspot_runtime.checks import is_valid_ipv4

# CheckResponse can be treated as a boolean
if is_valid_ipv4("10.0.0.1"):
   …

# CheckResponse exposes `.passed` (`bool`) and `.help_text` (`str`)
check = is_valid_ipv4("10.0.0.a")
if not check.passed:
    raise SystemExit(check.help_text)

# Directly raise a `ValueError` exception
is_valid_ipv4("10.0.0.a").raise_for_status()

offspot.yaml format

offspot.yaml is composed of a single object with predefined candidate members.

• No member is required.
• Unknown members are simply ignored.
• No relation between first-level members.

Valid first-level members

firmware

firmware is itself a single object.

Chipsets included in RaspiOS have limitations on the number of WiFi clients that can connect to it. Using this, you can change the version of the firmware to use for your chipset.

Each chipset supports a different set of firmwares.

brcm43455 chipset firmwares

brcm43430 chipset firmwares

⚠️ Warning: WiFi firmware update requires a reboot to be effective.

Example:

---
firmware:
  brcm43455: raspios
  brcm43430: supports-30_2018-09-28

timezone

Must be a valid timezone. Get a complete list with:

timedatectl list-timezones

⚠️ Warning: timezones are case-sentitive. Africa/Bamako works but Africa/bamako or utc doesn't.

Example:

---
timezone: Europe/Berlin

hostname

Must be alphanumeric string up to 63 characters. Can be composed of multiple (max 64) of those, separated by a single dot. Total length must be under 256 characters.

Example:

---
hostname: library-lab-pi23

Note: this is not the domain name on the network. See ap for this. hostname is mostly useless.

ethernet

network is itself a single object.

Examples:

---
ethernet:
  type: dhcp

---
ethernet:
  type: static
  address: 192.168.5.1
  routers: 192.168.5.200
  dns: 192.168.5.200

Notes

If you need to mix this simple configuration tool with a more complex dhcpcd.conf file, use the following armor in your file:

### config-network: start ###
### config-network: end ###

The script will set its properties in-between those lines, keeping the rest of your configuration.

Without an armor, configuration is appended at end of file, specifying eth0 interface if missing (untouched dhcpcd.conf)

ap

ap is itself an object.

• ^1: Special value auto triggers it when the hotspot is offline and disables it when it is connected to Internet

notes

• iptables is not persistent. ap will write rules to /etc/iptables/*.rules. If you don't use offspot-runtime-config-fromfile on start, manually reload them via a script or service:

/usr/bin/find /etc/iptables/ -name '*.rules' -exec /sbin/iptables-restore {} \;

containers

containers is the full docker-compose.yaml you want to use. It will be written to /etc/docker/compose.yml.

---
containers:
  services:
    kiwix:
      container_name: kiwix
      image: ghcr.io/offspot/kiwix-serve:dev
      command: /bin/sh -c "kiwix-serve /data/*.zim"
      volumes:
        - "/data/zims:/data:ro"
      expose:
        - "80"
      restart: always