Create sysupgrade images for OpenWrt on demand
Attendedsysupgrade Server for OpenWrt (GSoC 2017)
This project intends to simplify the sysupgrade process of devices running OpenWrt or
distributions based on the former like LibreMesh. The provided tools here offer an easy
way to reflash the router with a new version or package upgrades, without the need of
Additionally it offers an API (covered below) to request custom images with any selection of packages pre-installed, allowing to create firmware images without the need of setting up a build environment, even from mobile devices.
Add a view to the Luci system tab called "Attended Sysupgrade". Offers a button to search for updates and if found, to flash the image created by the update server.
Add CLI to perform sysupgrades. Makes use of
ucert to verify images are from a trusted source.
The server listens to update and image requests and images are automatically generated if the requests was valid. This is done by automatically setting up OpenWrt ImageBuilders and cache images in a database. This allows to quickly respond to requests without rebuilding exiting images again.
You can set this server in
/etc/config/attendedsysupgrade after installation of a
Run your own server
It's fairly easy to run your own asu server! You can test it locally via Docker, Vagrant or Ansible. The following steps except you are familiar with either Docker, Vagrant or Ansible.
Make sure to have
docker-compose installed. Simply execute the server via
the following command:
This will start a postgres container preseeded with the required database schema.
Afterwards a server is started which performs an initial download of available versions
and target/subtarget combinations. Once this is done the server itself is started via
A worker container waits for the server to come up (on port 8000) and will start builders, garbage collectors and an updater.
updater are created, caching downloaded ImageBuilders. You
can change this behaviour in the
Copy the configuration file from
./ansible/host_vars/<hostname>.yml. Add the Ansible variables
ansible_user to the top of the config file.
Change all settings as you like, the config file is automatically copied to the host
Make sure your vagrant environment is setup and supports the used Debian 9 image (virtualbox/libvirt). Also Ansible is requred to setup the service. To start vagrant simply run the following command:
Ansible automatically starts to setup the postgres database, server and worker. Once
installed two systemd services are running, called
their well beeing via
journalct -fu asu-*.
Ansible takes the configuration file from
./asu/utils/config.yml.default or a specific
one, if exists, from
To hack on the server, please install it manually. The following steps give an (may incomplete) overview on the required steps. It's focused on Debian based system, feel free to add documentation for other systems.
The server requires the following packages
apt install python3-pip odbc-postgresql unixodbc-dev gunicorn3 git \ bash wget postgresql
To run the worker addiditonal packages are required, based on the official wiki
apt install subversion g++ zlib1g-dev build-essential git python rsync \ man-db libncurses5-dev gawk gettext unzip file libssl-dev wget zip
Install the server package
pip3 to install the package
pip3 install -e .
flask to find the package.
Setting up PostgreSQL
asu uses ODBC you have
to add the servers database to your
/etc/odbc.ini. See an example
configuration here. Once added setup the PostgreSQL user account. From a
root shell login as postgres, create the
asu database and change the password!
su postgres createdb asu psql create role asu with password 'changeme' nosuperuser nocreatedb nocreaterole noinherit login noreplication nobypassrls; grant all privileges on database asu to asu;
Now let flask initiate the database and load available targets.
export FLASK_APP=asu flask initdb flask loaddb
The server and worker(s) are now ready to run!
Starting the server
Either start the server in single thread mode via
flask or via
# runs on localhost:5000 FLASK_APP=asu flask run # runs on localhost:8000 gunicorn3 asu:app
Starting the worker
Simply run the following command to run the worker, it will start multiple threads for updating, cleaning and building firmware images:
FLASK_APP=asu flask run-worker
Sends information about the device to the server to see if a new distribution version or package upgrades are available. An upgrade check could look like this:
||all user installed packages|
Most information can be retrieved via
ubus call system board. Missing information can
be gathered via the
packages contains all user installed
packages plus version. Packages installed as an dependence are excluded as they've been
automatically and dependencies may change between versions.
It's also possible to check for a new version without sending packages by removing
installed from the request.
The server validates the request. Below is a possible response for a new version:
||All packages for the new image|
An version upgrade does not ignore package upgrades for the following reason. Between versions it possible that package names may change, packages are dropped or merged. The response contains all packages included changed ones.
The upgrade check response should be shown to the user in a readable way.
Once the user decides to perform the sysupgrade a new request is send to the server called upgrade request.
||All packages for the new image|
The upgrade request is nearly the same as the upgrade check before, except only
containing package names without version and adding
board and possibly
the server builds the requested image the clients keeps polling the server sending a
GET to the server.
request_hash was retrieved the client should switch to
GET requests with the
hash to save the server from validating the request again.
||path where files are stored|
||name of sysupgrade file|
||path to build log|
||hash of the image|
||hash of the request|
It's also possible to request to build an image. The request is nearly the same as for
upgrade-request. The response only contains a link to the created
upgrade-request parameters if available.
An additional parameter is the
defaults parameter which allows to set the content of
/etc/uci-defaults/99-server-defaults within the image. This allows to set custom
options for the resulting image. To distinguish between custom images the name will
contain a hash of the requested
defaults value and is stored in a different place,
only visible if the full hash (32bit) is known.
This is a special case for clients that do not necessary require a sysupgrade compatible image. An example is the LibreMesh Chef firmware builder.
Response status codes
The client should check the status code:
|200||build finish / upgrade available||see parameters of
|202||building, queued, imagebuilder setup||building right now, in build queue, imagebuilder not ready. Details are in header
|204||no updates||device is up to date. Contains
|409||manifest fail||selection of requested packages caused a conflict|
|413||imagesize fail||produced image too big for device|
|420||defaults size fail||requested defaults exceeds maximum size (10kB)|
|422||unknown package||unknown package in request|
|501||no sysupgrade||image build successful but no sysupgrade image created|
|502||proxy backend down||nginx runs but python part is down, likely maintenance|
|503||server overload||please wait ~5 minutes|
It's also possible to receive information about build images or package versions,
available devices and more. All responses are in
/api/image/<image_hash>Get information about an image. This contains various information stored about the image.
/api/manifest/<manifest_hash>Get packages and versions of a manifest. The manifest contains all installed packages of an image. The
manifest_hashcan be received by the api call
/api/distrosGet all supported distros with latest version and a short description if available.
/api/versions[?distro=<distribution>]Get all supported versions with short description (of a singele distribution if given).
/api/models?distro=&version=&model_search=<search string>Get all supported devices of distro/version that contain the
/api/packages_image?distro=&version=&target=&subtarget=&profile=Get all default packages installed on an image
||Get list of most installed packages|
||Get list of most created targets|
||Return image build information|
||Return number of known packages|
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size asu-0.2.4-py3-none-any.whl (37.6 kB)||File type Wheel||Python version py3||Upload date||Hashes View hashes|
|Filename, size asu-0.2.4.tar.gz (36.3 kB)||File type Source||Python version None||Upload date||Hashes View hashes|