Skip to main content

offspot-config

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

CodeFactor License: GPL v3 codecov PyPI version shields.io PyPI - Python Version

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

Member Kind Function
firmware string Set WiFi firmware to use
timezone string Set Host timezone
hostname string Set machine's hostname (not domain, see ap).
ethernet object Set network configuration for ethernet interface
ap object Set WiFi AP configuration for wireless interface
containers object Builds the docker-compose file

firmware

firmware is itself a single object.

Member Kind Required Function
brcm43455 string no Firmware to use for brcm43455 chipset (Pi 3B+/4/5)
brcm43430 string no Firmware to use for brcm43430 chipset (Pi 0W/3

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

Firmware Comment
raspios Supports 4/5 clients. Came with RaspiOS
supports-19_2021-11-30 Supports 19 clients. Can be used in AP+STA mode (not supported in Hotspot yet)
supports-24_2021-10-05_noap+sta Supports 24 clients. Can not be used in AP+STA mode
supports-32_2015-03-01_unreliable Supports 32 clients. Unreliable. Available for tests only

brcm43430 chipset firmwares

Firmware Comment
raspios Supports 4/5 clients. Came with RaspiOS
supports-30_2018-09-28 Supports 30 clients.

⚠️ 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.

Member Kind Required Function
type string yes Either dhcp or static
address string static Static IPv4 adress to set
routers string static Space-separated IPv4 addresses to use as gateways. Use any different address inside subnet if not using it.
dns string static Space-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: 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.

Member Kind Required Function
ssid string yes SSID (Network Name)
passphrase string no Passphrase/password to connect to the network. Defaults to Open Network
profile string no AP Configuration: perf (802.11ac@5Ghz – requires brcm43455), coverage (802.11n@2.4Ghz). Defaults to perf.
address string no IP address to set on the wireless interface. Defaults to 192.168.144.1
channel_24 integer no WiFi channel to use for 2.4Ghz network (1-14). Defaults to 11.
channel_5 integer no WiFi channel to use for 5Ghz network (32, 36, 40, 44). Defaults to 36.
country string no Country-code to apply frequencies limitations for. Defaults to FR
hide boolean no Hide SSID (Clients must know and enter its name to connect)
interface string no Interface to configure AP for. Defaults to wlan0
dhcp-range string no IP range for AP clients. start,end,subnet,ttl format. Default: .100-.240 from address
network [string] no Network to advertise DHCP on. Defaults to .0/24 from address
nodhcp-interfaces [string] no Interfaces where the DHCP server will not run
dns [string] no DNS to set via DHCP when working as Internet gateway. Defaults to 8.8.8.8, 1.1.1.1
captured-address string no IP address to set DNS fallback to when offline (all domains but locals are sent to it). Default: 198.51.100.1
as-gateway boolean no Make this device act as a gateway to Internet (wired) for AP (wireless) clients (when/if eth0 has connectivity)
tld string no Search (top-level) domain to set via DHCP. Defaults to offspot
domain string no Domain name to direct to the offspot. Defaults to generic (resolved as generic.{tld}
welcome string no Additional domain to direct to offspot. Defaults to goto.kiwix (resolved as goto.generic.{tld}
spoof boolean* no Whether to direct all DNS requests to the offspot. Useful for captive-portal without Internet bridge^1.
  • ^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

Metadata

Release files for offspot-config 2.10.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for offspot-config 2.10.4
File Size Uploaded Provenance Actions
offspot_config-2.10.4.tar.gz 173.9 kB With provenance Details for offspot_config-2.10.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for offspot-config 2.10.4
File Interpreter ABI Platform Actions
offspot_config-2.10.4-py3-none-any.whl Python 3 none any Details for offspot_config-2.10.4-py3-none-any.whl

Total release size: 351.3 kB

Release files / offspot_config-2.10.4.tar.gz

Download URL offspot_config-2.10.4.tar.gz
Size 173.9 kB
Tags Source
SHA-256 checksum
How to use checksums
cd687f215d23955e66654ba3a05180926f2d902a71f28090fa30f55f4aaab929
BLAKE2b-256 checksum
How to use checksums
23346fe928a7ad772b3bdf164c432e405dc240b79ff60ba46d66a364b7e7a724
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Release files / offspot_config-2.10.4-py3-none-any.whl

Download URL offspot_config-2.10.4-py3-none-any.whl
Size 177.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
29c546305cc2aa4dcec4c353b71df0f0769f4a4ba7bd7d142ddedfbc9037b5d1
BLAKE2b-256 checksum
How to use checksums
cea9e6436870804ef423a6bf949c7ae182581dec0944be7079f80d38f0105a4c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Security for offspot-config 2.10.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for offspot_config-2.10.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.10.4 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page