awesome-o-image updates the Defend-O-Tron’s firmware from the terminal. It does the same jobs as the web interface’s Device → Firmware page: check for updates, download and stage a version, apply it, roll back, list what is installed, and remove an old version. The Firmware page runs this same tool, so the two always agree.
For most updates, the Firmware page is the simpler way. Use the command for scripts, or when you work at a console without a browser.
Where to run it: open Device → Terminal in the web interface, or connect over SSH.
awesome-o-image <command> [options]
status and list only read, and work without sudo.sudo: it changes the firmware files, or reads the device’s identity to sign in to the firmware server.--config <path> to read a different settings file. You need it only for testing.Exit codes: 0 means it worked. 1 means it failed, and the message says why. 2 means wrong usage, for example an unknown command or option.
Each firmware version has an ID like trixie-amd64-6.18.63-b299de8434f2:
trixie: the Debian release the firmware is built on.amd64 on a V200, or current on a V100: the kernel build.6.18.63: the Linux kernel version.b299de8434f2: the start of the firmware’s SHA-256 checksum. Two builds with the same kernel have different IDs.The device also keeps its factory image, the firmware it shipped with, as a last-resort fallback. This tool never removes it. A V200 reinstall from a USB installer replaces it, and removes the downloaded versions.
Asks the firmware server whether a newer firmware is offered, and records the answer. It downloads only a few kilobytes of information and never changes the firmware.
sudo awesome-o-image check
The device runs check by itself every Sunday at 3 AM, at a random moment within the hour, in the device’s time zone. If the device was off then, it checks soon after it starts. The Check for updates button on the Firmware page runs the same check.
It prints one line, after the date and time, with the result, the version the server offers, its Debian release and its kernel:
check: <result> (version=<id> codename=<release> kernel=<kernel>)
| Result | Meaning |
|---|---|
up-to-date |
The offered version is already running, installed or staged. Nothing to do |
kernel-update-available |
The offered version has a newer kernel |
content-update-available |
Same kernel, but other parts of the firmware changed |
downgrade-available |
The offered version has an older kernel, or a kernel from a different kernel build |
codename-mismatch |
The offered version is for a different Debian release. It cannot be installed |
error |
The server could not be reached, or its answer was not valid. The message says why |
check exits with code 1 for error, and 0 for every other result.
Shows what is running, what boots next, what is staged, and what the last check found.
awesome-o-image status [--json]
Example from a V200:
$ awesome-o-image status
CURRENT
Running: trixie-amd64-6.18.63-b299de8434f2
Default: trixie-amd64-6.18.63-b299de8434f2
Staged: —
AVAILABLE
None
HISTORY
Last check: 2026-11-17T19:24:52Z (up-to-date)
Last activity: —
DETAILS
Factory image:
Normal LABEL: -
Maint LABEL: -
Version: trixie-amd64-6.18.63-69cb26a15d30
Kernel: 6.18.63-amd64-x86
Content: 69cb26a15d304a65ad51298359d03480a114dfe1ef72192a1e7f2973c5d668e5
Renamed: (pre-rename; default factory names still in extlinux.conf)
Installed images: 2
- trixie-amd64-6.18.63-45fe5628f8ab (kernel 6.18.63-amd64-x86, 2026-11-17T18:47:58Z)
- trixie-amd64-6.18.63-b299de8434f2 (kernel 6.18.63-amd64-x86, 2026-11-17T19:34:29Z)
factory.kernel, content or downgrade).- and the default text there.With --json, it prints the same information as one JSON object, for scripts.
Downloads a firmware version and gets it ready, but does not switch to it. Your current firmware keeps running and keeps booting until you apply.
sudo awesome-o-image stage [--version <id>] [--quiet]
| Option | Effect |
|---|---|
--version <id> |
Stage this version instead of the one the last check found. versions lists the IDs |
--quiet |
Do not show the download and unpacking progress |
What it does:
/boot/images/<id>/ and adds it to the boot menu.When it is done, it prints:
Staged trixie-amd64-6.18.63-b299de8434f2. Run 'awesome-o-image apply' to activate.
stage does not ask before staging an older kernel. The web interface does.
Makes the staged firmware the one that boots next. It downloads nothing, so it is quick. The device keeps running its current firmware until it restarts.
sudo awesome-o-image apply [--reboot] [--cleanup auto|on|off]
| Option | Effect |
|---|---|
--reboot |
Restart the device straight away. Internet traffic through the device stops while it restarts |
--cleanup on |
Clean up old firmware files during the next restart |
--cleanup off |
Do not clean up during the next restart |
--cleanup auto |
The default. Use the choice Awesome-O publishes with the version. Versions published without one use the firmware_cleanup setting (see Configuration) |
What the cleanup does. Your changes to the device are kept apart from the firmware itself. The cleanup removes the old firmware’s program files from that store, so the new firmware starts clean, and does not remove your settings (/etc), your data, your container settings in /opt/deploy/local, or the web certificates. With the cleanup, this happens in the same restart. Without it, the device notices the change when the new firmware starts, and restarts once more by itself to clean up. The Clean up old firmware files on the next boot box on the Firmware page is the same choice.
Example:
$ sudo awesome-o-image apply
Default flipped to "trixie-amd64-6.18.63-b299de8434f2".
Reboot to activate.
The firmware you had before stays on the device, so you can roll back to it.
Makes an earlier firmware, or the factory image, the one that boots next. It downloads and deletes nothing.
sudo awesome-o-image rollback [--version <id>] [--factory] [--reboot]
| Option | Effect |
|---|---|
--factory |
Roll back to the factory image |
--version <id> |
Roll back to this installed version |
--reboot |
Restart the device straight away |
With no option, it picks the firmware installed just before the current default. If there is none, it picks the factory image.
$ sudo awesome-o-image rollback
Default rolled back to "trixie-amd64-6.18.63-45fe5628f8ab".
Reboot to activate.
Already the default boot image; nothing to roll back. and changes nothing.apply scheduled. The device still cleans up if it finds that the firmware changed.--factory needs the factory image’s version. If status shows Version: - under Factory image, --factory refuses and says why. Roll back to an installed version instead, or see Recovery.Lists the downloaded firmware on the device. The factory image is not listed, because it is always there.
awesome-o-image list [--json]
Example from a V200:
$ awesome-o-image list
ID KERNEL INSTALLED FLAGS
trixie-amd64-6.18.63-45fe5628f8ab 6.18.63-amd64-x86 2026-11-17T18:47:58Z -
trixie-amd64-6.18.63-b299de8434f2 6.18.63-amd64-x86 2026-11-17T19:34:29Z default,running
FLAGS shows default (boots next), running (running now) and staged (waiting for apply). A device that has only its factory image prints No images installed (factory only).
With --json, it prints the list as a JSON array.
Deletes a downloaded firmware: its files under /boot/images/<id>/ and its boot menu entries.
sudo awesome-o-image remove <id>
It refuses to remove:
$ sudo awesome-o-image remove trixie-amd64-6.18.63-45fe5628f8ab
Removed trixie-amd64-6.18.63-45fe5628f8ab.
The device does not remove old firmware by itself, so use remove when the boot partition gets full.
Lists the firmware versions the server offers this device, newest first.
sudo awesome-o-image versions [--json]
It first prints one line that says it read the device’s identity. Then, for example:
ID KERNEL DATE FLAGS
trixie-amd64-6.18.63-b299de8434f2 6.18.63 2026-11-17 latest,available,running,installed
FLAGS shows latest (the server’s newest), available (what the last check found), running and installed.
The device runs this at every start. It compares the firmware running now with the firmware that ran before. If they differ, for example after the firmware was changed without this tool or the Firmware page, it prepares the cleanup and restarts the device straight away (see apply). You do not need to run it yourself.
sudo awesome-o-image reconcile
awesome-o-image version (or --version, -v) prints the installed version of the awesome-o-services package, which includes this tool. awesome-o-image help (or --help, -h) prints the usage text.
Update from the terminal:
sudo awesome-o-image check
sudo awesome-o-image stage
sudo awesome-o-image apply --reboot
Install a particular version:
sudo awesome-o-image versions
sudo awesome-o-image stage --version <id>
sudo awesome-o-image apply
Roll back after an update went wrong:
sudo awesome-o-image rollback --reboot
Free space on the boot partition:
awesome-o-image list
sudo awesome-o-image remove <id>
Most devices never need a change here.
| Path | Who edits it | What it is |
|---|---|---|
/etc/awesome-o/image-updater.conf |
The package. Do not edit it | The shipped settings, with a comment for each. Because you do not edit it, package updates can replace it with new settings without asking |
/etc/awesome-o/image-updater.conf.d/*.conf |
You | Your changes. These files are read after the main file, in name order. Set only the settings you want to change |
To make a change, copy the sample and edit the copy:
sudo cp /usr/share/doc/awesome-o-services/examples/local.conf.sample \
/etc/awesome-o/image-updater.conf.d/local.conf
sudo nano /etc/awesome-o/image-updater.conf.d/local.conf
| Section | What it controls |
|---|---|
[server] |
The firmware server: base_url, the list file (index_pointer) and each version’s description file (manifest_file). trusted_ca_path adds a CA bundle for a server with a private certificate. require_signature decides whether a missing or bad signature on these files is refused (true, the shipped value) or only logged (false). auth_scheme is bearer: the device signs in with its own identity, so there is no password to set |
[boot] |
Where the boot partition, boot menu, firmware folders and state file are. Do not change these |
[network] |
timeout_seconds (60) and user_agent for the connection to the server |
[retention] |
keep_installed (3) and auto_apply (always false). The current version reads keep_installed but does not act on it: old firmware stays until you remove it |
[apply] |
firmware_cleanup (true): the cleanup choice for apply --cleanup auto when a version was published without one |
[identity] |
Where the device’s signed identity is stored, and how it is checked. The device uses it to sign in to the firmware server. Do not change these |
An unknown section or a setting with a bad value is an error, and the command stops and says why. An unknown setting in a known section is only a warning.
After editing: run sudo awesome-o-image check. A result other than error means the settings work and the server can be reached.
| Path | What it is |
|---|---|
/var/lib/awesome-o-image/state.json |
What is running, the default, what is staged, the installed firmware and the last check |
/var/lib/awesome-o-image/update.lock |
Makes sure only one stage, apply, rollback or remove runs at a time. A second one stops with another update operation is in progress |
/run/awesome-o-image/notify.json |
The last firmware event, for the web interface’s banner. It is gone after a restart |
/boot/images/<id>/ |
Each downloaded firmware |
awesome-o-image-check.timer |
The weekly check |
awesome-o-image.