Offspot Runtime Configuration Scripts & Library
Project description
offspot-runtime-config
A collection of scripts for use within offspot/base-image.
Launched via offspot-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
–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.
Usage
offspot-config-fromfile --debug /boot/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 and2
on misconfiguration (invalid parameter). Same goes for individual scripts. - it starts
hostapd
,dnsmasq
andiptables-restore
automatically. If you start it on boot, disable them (systemctl disable hostapd dnsmasq
)
Installation
⚠️ Warning: only tested on offspot base-image (raspiOS bullseye)
apt install hostapd dnsmasq dhcpcd5 python3-yaml python3-pip
systemctl unmask hostapd
systemctl disable hostapd dnsmasq
pip3 install offspot_runtime_config
Alternatively, if you don't want to rely on python packages, you can use scripts (almost) directly
curl -L https://github.com/offspot/runtime-config/archive/refs/heads/main.tar.gz| tar xf -
mv runtime-config-main/src/offspot_runtine_condig /some/place/
for name in containers fromfile ap ethernet hostname timezone
do
ln -s /some/place/$name.py /usr/local/bin/offspot-config-$name
done
Library usage
pip3 install offspot-runtime-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 |
---|---|---|
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 |
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 |
address |
string |
no | IP address to set on the wireless interface. Defaults to 192.168.2.1 |
channel |
integer |
no | WiFi channel to use for the network (1-14). Defaults to 11 . |
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 |
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. 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 useoffspot-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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for offspot-runtime-config-1.2.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7e0266e79c79a1fc463b16376bc5bdb5d7d49ffbd977af6901852e23465da698 |
|
MD5 | eeae4206cf9a419faf975ff5453d1c35 |
|
BLAKE2b-256 | 934a9c6c0f44911bd17fe2aa81de7c10bce52a833464e9259eccd49317b28a0a |
Hashes for offspot_runtime_config-1.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b346c907b98d1a577ad86229a17c6b9ee7b2408577a1a1808fece6a0ac1627a5 |
|
MD5 | e46d061b2290c3e23d171c7c2d319d94 |
|
BLAKE2b-256 | a19c425830aacba5070a98752ab7f8e7621ccb88e7506c0a721e12c4d1f95e4d |