An image on demand server for OpenWrt based distributions
Attendedsysupgrade Server for OpenWrt (GSoC 2017)
This project simplifies the sysupgrade process for upgrading the firmware of
devices running OpenWrt or distributions based on it. These tools offer an easy
way to reflash the router with a new firmware version
(including all packages) without the need to use
It's called Attended SysUpgrade (ASU) because the upgrade process is not started automatically, but is initiated by a user who waits until it's done.
ASU is based on an API (described below) to request custom firmware images with any selection of packages pre-installed. This avoids the need to set up a build environment, and makes it possible to create a custom firmware image even using a mobile device.
Clients of the Sysupgrade Server
OpenWrt Firmware Selector
offers a simple tool under
System > Attended Sysupgrade. It requests a new
firmware image that includes the current set of packages, waits until it's built
and flashes it. If "Keep Configuration" is checked in the GUI, the device
upgrades to the new firmware without any need to re-enter any configuration or
re-install any packages.
performs the same process as the
from SSH/the command line.
The server listens for image requests and, if valid, automatically generates them. It coordinates several OpenWrt ImageBuilders and caches the resulting images in a Redis database. If an image is cached, the server can provide it immediately without rebuilding.
Run your own server
Redis is required to store image requests:
sudo apt install redis-server tar
pip install asu
You can use
misc/config.py as an example.
Start the server via the following commands:
export FLASK_APP=asu.asu # set Flask app to asu flask janitor update # download upstream profiles/packages - this runs forever flask run # run development server - this runs forever
Start the worker via the following comand:
rq worker # this runs forever
Run the service inside multiple Docker containers. The services include the _
ASU_ server itself, a janitor service which fills the Redis database with
known packages and profiles as well as a
rqworker which actually builds
Currently all services share the same folder and therefore a very "open" access is required. Suggestions on how to improve this setup are welcome.
mkdir ./asu-service/ chmod 777 ./asu-service/ cp ./misc/config.py ./asu-service/ docker-compose up
A webserver should proxy API calls to port 8000 of the
server service while
asu/ folder should be file hosted as-is.
It is recommended to run ASU via
gunicorn proxied by
caddyserver. Find a possible server configurations in the
The ASU server will try
/etc/asu/config.py to find a
configuration. Find an example configuration in the
pip install gunicorn gunicorn "asu.asu:create_app()"
Ideally use the tool
squid to cache package indexes, which are reloaded every
time an image is built. Find a basic configuration in at
which should be copied to
If you want to use
systemd find the service files
worker@.service in the
misc folder as well.
After cloning this repository, create a Python virtual environment and install the dependencies:
python3 -m venv .direnv source .direnv/bin/activate pip install -r requirements.txt export FLASK_APP=asu.asu # set Flask app to asu export FLASK_APP=tests.conftest:mock_app FLASK_DEBUG=1 # run Flask in debug mode with mock data flask run
The API is documented via OpenAPI and can be viewed interactively on the server:
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.