Package: offspot-config
offspot-configA library to read/write an Offspot runtime config and a collection of scripts to use it withinoffspot/base-image.Scripts UsageLaunched viaoffspot-runtime-config-fromfile, it:reads a YAML config file and changes the offspot configuration accordingly.starts associated servicesIts 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 isnot 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-fromfilereads 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--debugwill 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)beforedocker-compose.service.It returns0on success,1on general failures and2on misconfiguration (invalid parameter). Same goes for individual scripts.it startshostapd,dnsmasqandiptables-restoreautomatically. If you start it on boot, disable them (systemctl disable hostapd dnsmasq)Installation⚠️ Warning: only tested on offspot base-image (raspiOS bookworm)aptinstallhostapddnsmasqdhcpcd5python3-yamlpython3-pip
systemctlunmaskhostapd
systemctldisablehostapddnsmasq
pip3installoffspot-configLibrary usagepip3installoffspot-configfromoffspot_runtime.checksimportis_valid_ipv4# CheckResponse can be treated as a booleanifis_valid_ipv4("10.0.0.1"):…# CheckResponse exposes `.passed` (`bool`) and `.help_text` (`str`)check=is_valid_ipv4("10.0.0.a")ifnotcheck.passed:raiseSystemExit(check.help_text)# Directly raise a `ValueError` exceptionis_valid_ipv4("10.0.0.a").raise_for_status()offspot.yamlformatoffspot.yamlis composed of a singleobjectwith predefined candidate members.No member is required.Unknown members are simply ignored.No relation between first-level members.Valid first-level membersMemberKindFunctionfirmwarestringSet WiFi firmware to usetimezonestringSet Host timezonehostnamestringSet machine's hostname (not domain, seeap).ethernetobjectSet network configuration for ethernet interfaceapobjectSet WiFi AP configuration for wireless interfacecontainersobjectBuilds the docker-compose filefirmwarefirmwareis itself a singleobject.MemberKindRequiredFunctionbrcm43455stringnoFirmware to use forbrcm43455chipset (Pi 3B+/4/5)brcm43430stringnoFirmware to use forbrcm43430chipset (Pi 0W/3Chipsets 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.brcm43455chipset firmwaresFirmwareCommentraspiosSupports 4/5 clients. Came with RaspiOSsupports-19_2021-11-30Supports 19 clients. Can be used in AP+STA mode (not supported in Hotspot yet)supports-24_2021-10-05_noap+staSupports 24 clients. Cannotbe used inAP+STAmodesupports-32_2015-03-01_unreliableSupports 32 clients.Unreliable. Available for tests onlybrcm43430chipset firmwaresFirmwareCommentraspiosSupports 4/5 clients. Came with RaspiOSsupports-30_2018-09-28Supports 30 clients.⚠️ Warning: WiFi firmware updaterequires a rebootto be effective.Example:---firmware:brcm43455:raspiosbrcm43430:supports-30_2018-09-28timezoneMust be a valid timezone. Get a complete list with:timedatectllist-timezones⚠️ Warning: timezones arecase-sentitive.Africa/Bamakoworks butAfrica/bamakoorutcdoesn't.Example:---timezone:Europe/BerlinhostnameMust 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-pi23Note: this is not the domain name on the network. Seeapfor this.hostnameis mostly useless.ethernetnetworkis itself a singleobject.MemberKindRequiredFunctiontypestringyesEitherdhcporstaticaddressstringstaticStatic IPv4 adress to setroutersstringstaticSpace-separated IPv4 addresses to use as gateways. Use any different address inside subnet if not using it.dnsstringstaticSpace-separated IPv4 addresses to use as domain name servers. Use any different address inside subnet if not using it.Examples:---ethernet:type:dhcp---ethernet:type:staticaddress:192.168.5.1routers:192.168.5.200dns:192.168.5.200NotesIf you need to mix this simple configuration tool with a more complexdhcpcd.conffile, use the followingarmorin 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 anarmor, configuration is appended at end of file, specifyingeth0interface if missing (untoucheddhcpcd.conf)apapis itself anobject.MemberKindRequiredFunctionssidstringyesSSID (Network Name)passphrasestringnoPassphrase/password to connect to the network. Defaults to Open NetworkaddressstringnoIP address to set on the wireless interface. Defaults to 192.168.2.1channelintegernoWiFi channel to use for the network (1-14). Defaults to11.countrystringnoCountry-code to apply frequencies limitations for. Defaults toFRhidebooleannoHide SSID (Clients must know and enter its name to connect)interfacestringnoInterface to configure AP for. Defaults towlan0dhcp-rangestringnoIP range for AP clients.start,end,subnet,ttlformat. Default:.100-.240from addressnetwork[string]noNetwork to advertise DHCP on. Defaults to.0/24from addressnodhcp-interfaces[string]noInterfaces where the DHCP server will not rundns[string]noDNS to set via DHCP when working as Internet gateway. Defaults to8.8.8.8,1.1.1.1captured-addressstringnoIP address to set DNS fallback to when offline (all domains but locals are sent to it). Default:198.51.100.1as-gatewaybooleannoMake this device act as a gateway to Internet (wired) for AP (wireless) clients (when/ifeth0has connectivity)tldstringnoSearch (top-level)domainto set via DHCP. Defaults tooffspotdomainstringnoDomain name to direct to the offspot. Defaults togeneric(resolved asgeneric.{tld}welcomestringnoAdditional domain to direct to offspot. Defaults togoto.kiwix(resolved asgoto.generic.{tld}spoofboolean*noWhether to direct all DNS requests to the offspot. Useful for captive-portal without Internet bridge^1.^1: Special valueautotriggers it when the hotspot is offline and disables it when it is connected to Internetnotesiptablesis not persistent.apwill write rules to/etc/iptables/*.rules. If you don't useoffspot-runtime-config-fromfileon start, manually reload them via a script or service:/usr/bin/find/etc/iptables/-name'*.rules'-exec/sbin/iptables-restore{}\;containerscontainersis the full docker-compose.yaml you want to use. It will be written to/etc/docker/compose.yml.---containers:services:kiwix:container_name:kiwiximage:ghcr.io/offspot/kiwix-serve:devcommand:/bin/sh -c "kiwix-serve /data/*.zim"volumes:-"/data/zims:/data:ro"expose:-"80"restart:always