Software Update

The Software Update tab lets an administrator replace the running console container without accessing the host directly. Upgrades are Docker image tar files, which you upload here in the browser or stage from the appliance shell with aisec-upgrade. Download the console upgrade tar for a release from the Superna support site. You can also install a signed upgrade package.

Kubernetes and Helm Deployments

This tab does not apply when the console runs from the Helm chart, and it appears greyed out on that type of deployment. Upgrade a Helm-deployed console by updating the console image tag in your Helm values and running helm upgrade. See Install on Kubernetes. Uploading a tar to the console has no effect and only uses disk space.

How Upgrades Work

On the OVA appliance, the console runs as a Docker container owned by a systemd service, aisec-console-app.service. A running application cannot replace its own container, so the swap is split between three parts on the host.

1. The console stores the uploaded image tar in /opt/superna/upgradeimages/ and writes bundle-meta.json (image tag, size, and SHA-256). When you click Apply Upgrade, it also writes a .trigger file, and then exits.
2. The upgrade watcher (aisec-console-upgrade-watcher.service) sees the trigger. It runs as an unprivileged account with no Docker access. It records the current image as the rollback target, writes the new image tag, and asks systemd to restart aisec-console-app.service. Restarting the console and its database services is the only privilege it has.
3. systemd restarts the console. Before the container starts, a root-owned loader verifies the SHA-256 of the staged tar and loads it into Docker. The container then starts on the new image. Older console images are pruned. The newest three, the running image, and the rollback target are kept.

The watcher then checks the console's health endpoint and rolls back if the console does not become healthy. See Automatic Rollback.

Before You Begin

• Create a backup. See Backup.
• Plan a maintenance window. The console is unavailable for about 1 to 2 minutes during the swap.

Choose one of two upgrade methods:

• Quantum Trust signed package (.qtspkg). Follow the steps in that section, which end with a service restart.
• Manual upload of the console upgrade tar file, or staging it from the appliance shell. After the image reaches the Ready state, continue with Apply an Upgrade.

Quantum Trust Signed Delivery

The Quantum Trust Software Delivery card installs a Superna-signed upgrade package (.qtspkg) instead of a raw Docker image tar. Superna signs packages with ML-DSA-87 (NIST FIPS 204), a post-quantum digital signature algorithm. The console verifies the signature before it allows installation, which protects against tampered or counterfeit software.

Install a signed package

1. Drag a .qtspkg file onto the card, or click the card to browse for it.
2. The console uploads the package and validates it. Validation checks the package structure and manifest, the target component, the signing key, the digital signature, the payload hash and size, and rollback protection (downgrades below the manifest minimum are blocked).
3. Review the result badge.
4. If validation passes, click Install Build N to confirm.
5. Restart the service to apply the update.

Result badges

Badge	Meaning
Quantum Trust Signed	The signature is valid. The package is safe to install.
Quantum Trust Signed + Customer Encrypted	The package is signed and encrypted for this installation. All validation steps passed.
Signature Invalid	Superna did not sign the file, or it was modified.
Unknown Signing Key	This console does not trust the signing key. Update the console first.
Wrong Component	The package is for a different component. Use the correct upload location.
Rollback Blocked	The version is below the minimum the signing manifest allows.
Invalid Package	The file is not a valid .qtspkg, or required entries are missing.
Wrong Installation	The customer-encrypted package was produced for a different console. The System Public Key fingerprint of this console does not match the fingerprint in the package.
Decapsulation Failed	The delivery-key.bin entry in the package could not be processed. The package may be corrupt. Download it from Superna again.
Decryption Failed	Payload authentication failed after the delivery key was recovered. The payload may be corrupt, or the delivery key does not match this installation. Download the package from Superna again.

Customer-encrypted packages

Superna can produce a package that is encrypted for your installation. The payload is encrypted with AES-256-GCM, and the key is encapsulated with your installation's ML-KEM-1024 public key (NIST FIPS 203). Only the console the package was built for can decrypt it.

For these packages the console also confirms that the delivery key is present, matches the package fingerprint to this installation's System Public Key, recovers the delivery key, and decrypts and verifies the payload. Any corruption is detected.

If you see Wrong Installation:

1. Go to Settings > Security and find the System Public Key (ML-KEM-1024) section.
2. Copy the key fingerprint.
3. Send the fingerprint to Superna and request a re-encrypted package.

The standard Docker image upload below the Quantum Trust card is available on every OVA installation. It is independent of the signed-package path, and you can use either.

Manual Upload

To upload the console upgrade tar (aisec-console-upgrade-<version>.tar) from your computer:

1. Drag the .tar file onto the upload area, or click the area to browse for it.
2. Click Upload. A progress bar shows the progress. Files are typically 1–2 GB, so the upload can take several minutes.
3. After the upload, the console validates the file by checking the tar header and minimum size, and computes its checksums. The image then moves to the Ready state.

The Ready card shows the image tag, the MD5 checksum with a copy button, and the file size. If the staged build is the one already running, the card says so instead of offering an upgrade.

Upgrade from the Appliance Shell

You can run the same upgrade on the appliance itself, without the browser.

sudo aisec-upgrade /path/to/aisec-console-upgrade-<version>.tar   # upgrade and wait for the result
sudo aisec-upgrade --dry-run /path/to/<tar>                        # validate only
sudo aisec-upgrade --status                                        # running image, rollback target, watcher
sudo aisec-upgrade --rollback                                      # return to the previous image

Both methods use the same staging directory and watcher, so an upload staged in the web interface and one staged from the shell replace each other.

Verify the checksum

The Ready card shows an MD5 checksum. To confirm that the image was not corrupted in transit:

1. On the machine that holds the original file, run md5sum /path/to/aisec-console-upgrade-<version>.tar on Linux or md5 /path/to/aisec-console-upgrade-<version>.tar on macOS.
2. Compare the output with the MD5 value shown in the console.

If the values differ, dismiss the staged image and upload it again. Do not apply an image with a mismatched checksum.

Apply an Upgrade

Use these steps after a manually uploaded image reaches the Ready state.

1. In the Ready card, click Apply Upgrade.
2. A confirmation dialog shows the build number and image tag. Review them, and click Apply Upgrade to proceed.
3. An amber Replacing container banner appears while the container is replaced.
4. After about 5–6 seconds the connection is lost. The page switches to Waiting for restart and checks the login endpoint every 3 seconds.
5. When the new container responds, the page reloads automatically.

Total downtime is approximately 1 to 2 minutes, which covers the console restart and its startup.

On the OVA, uploading or applying fails with an error while an appliance maintenance operation is running, such as an installation update, a sizing change, a credential reset, or an OS-patch window. Nothing is changed. Apply the upgrade again when the operation has finished. The appliance's maintenance tools likewise refuse to start while an upgrade is in progress.

Automatic Rollback

After the restart, the watcher checks the console's health endpoint (/api/health) every 10 seconds for up to 3 minutes. If the console does not become healthy:

1. The watcher writes the previous image tag back and restarts aisec-console-app.service on it.
2. The watcher writes an upgrade-failed.txt file with the reason for the failure, including a likely root cause read from the console log, for example out of memory, a database connection failure, or a port already in use.

The next time the console starts, a red Upgrade failed banner appears. Click Dismiss to clear the failure and return to the Idle state.

For details, check the watcher log on the appliance with sudo tail -50 /opt/superna/upgradeimages/upgrade-watcher.log (timestamps are UTC), or run sudo journalctl -u aisec-console-app.service.

If the previous version does not become healthy either, the console is usually unreachable. Connect to the appliance over SSH and check sudo aisec-upgrade --status, the watcher log, and the journal.

State Reference

State	Meaning
Idle	No staged image. Only the upload section is shown.
Uploading	The image tar is being uploaded. A progress bar is visible.
Validating	The upload is complete. Tar header and minimum-size checks are running.
Ready	A validated image is staged. Apply Upgrade is available.
Upgrading	The container replacement is in progress.
Failed	The upgrade failed. Automatic rollback restored the previous container.