Licence#

Admin → Licence shows the licence this router holds and what the licence server last said about it, and takes a new key. The page's subtitle states the rule:

Changing the configuration needs a licence. Reading it does not.

The page is for admins only. Every role can see the licence's state — the line under the header of every page uses it — but only an admin can enter or remove a key.

What the licence gates#

Changes to the router. Without a usable licence the agent refuses them, with a message naming the fix, and keeps answering everything that reads.

Works without a licence	Needs a licence
Signing in, including single sign-on	Adding to or removing from the pending changes, and Discard
Every page and every reading: interfaces, firewall, NAT, DHCP, DNS, routing, apps, logs	Apply changes, Apply with auto-revert and Keep changes
The audit log and the configuration history	Restoring an earlier revision
Download configuration, on the System page	Save configuration
Users, API tokens, your own account, and Agent settings, Restart agent included	Every app action: install, update, restart, remove
Restart router, Shut down and the system images	Downloading or restoring a backup, and taking or restoring a snapshot
Checking for updates, a traceroute, a packet capture	Installing an agent update
`/metrics`	Reconcile, the UPnP settings and removing a UPnP mapping, and the fleet

A lapsed licence therefore leaves you able to watch the router, restart it, move it to a new system image, and take its configuration off it.

The seven states#

The badge in the page header shows the state.

State	Changes	Meaning
Valid	allowed	The key verifies, and today is before its expiry.
Grace period	allowed	Expired, but inside the grace period. The banner names the date changes stop.
Clock not verified	allowed	The router's clock reads before the licence was issued.
Expired	refused	Past the expiry and past the grace period.
Revoked	refused	The licence server said so.
Invalid	refused	The stored key does not verify, and the banner says why.
No licence	refused	No key is stored.

A banner sits under the page header whenever the state carries a message: amber while the licence still allows changes (a grace period, a clock not verified), red when it does not.

This licence#

Row	What it shows
Licence ID	The licence's ID, from the key.
Plan	The plan the key carries.
Licensed to	The name and email address the key carries, when it carries them.
Routers	How many routers the key allows.
Features	The features the key carries. `fleet` is the one the product checks.
Expires	The date, and the days left.
Grace period ends	The date changes stop, after the expiry.
This router's fingerprint	See below.

The fingerprint#

A short hexadecimal string that identifies this installation to the licence server, so that the key's router limit can be counted. It stays the same when the agent or the router restarts. It changes when the router is moved to a new system image or reinstalled, and the licence server then sees an installation it has not counted before. The key keeps working. Releasing a retired activation is done by whoever issued the key: nothing on the router releases it, and this page has no action for it — Backup and restore.

Licence server#

Row	What it shows
Server	The licence server the agent refreshes against, or Not used when none is set.
Last refresh	How long ago, or Not yet.
Answer	The status the server last returned, and its message.
Last refresh error	The last failure to reach the server, or None.

The panel's note:

The key is verified on the router and refreshed from the licence server once a day. Without the server it stays valid until it expires, and then for the grace period.

How verification works#

A key is a signed statement: WHL1.<key ID>.<payload>.<signature>. The payload names the licence ID, the customer, the plan, the features, the router limit, when it was issued, the expiry and the grace period. The signature is Ed25519, checked against public keys built into the agent.

The check happens on the router, offline: a router with no route to the internet still knows what it holds. A build can carry more than one public key, so the signing key can be rotated: a new key ships beside the old one, and the old one is then retired on the server.

A key that does not verify is refused with the reason: "that is not a Wheelhouse licence key" for the wrong shape, "the licence signature does not verify", or "the licence was signed by a key this build does not know (…); upgrade the agent".

How refresh works#

The agent sends the key, the fingerprint, the host name and its own version to the licence server: 20 seconds after it starts, then once a day, and every hour after a failed attempt.

The server answers	What the agent does
With a new token	Keeps it, and the expiry follows the subscription.
That the licence is revoked (`403`)	Marks the licence revoked. Changes stop at once, even though the key still verifies.
With a refusal (`400`, `402`, `404`, `409`)	Records the answer and its message. The key keeps working until its expiry plus the grace period.
Not at all, or with anything else	Records the error. Nothing changes.

A network failure never costs you the ability to change the router. Only a definite answer from the licence server, or the passage of time, does.

Entering a key#

Paste the key into Licence key and press Activate. The panel is titled Enter a licence key when the router has none and Replace the licence key when it has one. The field's hint: "Starts with WHL1. It is in your purchase email."

Activate is enabled only when the text starts with WHL1., and the agent verifies the signature before storing anything. A key that does not verify is refused with the reason, and nothing is saved.

A key that verifies is stored with the agent's settings, recorded in the audit log as license-set, and sent to the licence server at once, so the page shows the server's answer. The message says Licence activated, or Licence stored: followed by the state when the key does not allow changes — an expired key, for example.

A key can also reach the agent as a file when it starts: the installed service reads /config/wheelhouse/license-key when that file exists. The file must not be readable by anyone but its owner, or the agent refuses to start. A key given that way is stored as well, so it is kept after the file is gone.

Removing a key#

Remove licence key opens a red panel:

Without a licence key the configuration cannot be changed until a key is entered. This page cannot show the key again.

It asks for the licence ID to be typed — Enter the licence ID, …, to confirm — or the word remove when the stored key is too broken to have a readable ID. Remove licence key in the panel then removes it; Cancel leaves it. Keep a copy of the key first: nothing in the web interface ever shows it. Removal is recorded as license-remove.

Licensed features#

A key can carry a list of features, and one is checked today: fleet. Without it the Fleet page is not in the navigation, and the agent refuses the fleet requests with "the fleet feature is not part of this licence's plan". A router with no usable licence at all refuses them first, with the general licence message.

When there is something to say, a line appears under the header of every page: red when changes are refused, amber during a grace period or when seven days or fewer are left. An admin's line links to this page; other roles see "Ask an admin to enter a licence key."

For automation#

GET /api/license returns the state and is open to every role. PUT /api/admin/license enters a key and DELETE /api/admin/license removes one; both are admin-only. The states are valid, grace, clock-unverified, expired, revoked, invalid and unlicensed.

A request the licence refuses answers 402 Payment Required, with the reason and the state in the body. The two fleet reads, GET /api/fleet/{id}/config and GET /api/fleet/{id}/version, need the fleet feature as well — the only reads behind the licence, because they read a different router. GET /api/fleet, the list, does not.