Installing and activating a license

Upload the .lic file with Install license on the console's License page, or hand it to the installer with ohm install --license /root/customer.lic. The install runs as a background job.

Everything this chapter describes is reported here: the edition, the activation state, the challenge, and why a license is not granting its tier.

Subscriptions count installations, perpetual licenses bind to a machine

How a license is held to one server depends on its kind:

• A subscription or a trial is not bound to a machine. The license server counts it by its installation: every server keeps a random install id in its license directory, and a license admits as many installations as its installation cap allows, one unless the license says otherwise. A second server checking in with a license whose cap is full is refused as already in use. Activating one gives you its license file with no machine in it, and changing the hardware underneath does not change the installation.
• A perpetual license is bound to one machine. It is issued offline for a machine with an attested TPM (class S below), never checks in, and will not grant its edition anywhere else.

The 14-day activation window

A perpetual license that has never been activated carries no hardware id yet. Rather than refusing it, the server grants its edition for 14 days so you can get running while activation is arranged. A subscription or a trial needs no activation window: it is never bound.

Length	14 days
Anchored	On first sight of the file, written once
Renewable	No. Nothing but activation moves the anchor
After it runs out	The license stops granting its tier and the server runs unregistered, which switches off what the license carried. The License page says why

The activation window is separate from the check-in grace window below: a check-in does not extend it.

A license bound to a different machine is refused immediately

The window is for a license that has never been activated anywhere. One that was activated before, on another server, is refused on the spot: it has had its window.

If the license directory is read-only the anchor is held in memory instead. The window still ends, but a restart moves it, and both the log and the License page say so.

The hardware challenge

Your server derives a challenge from the strongest machine identity it can find, tried in order:

Class	Source
S	The TPM endorsement key
A	The SMBIOS system UUID
B	Firmware serial numbers
C	The host's /etc/machine-id

The class is part of the challenge string, so a challenge looks like A2-....

The ordering is by where the identity lives, not by how it looks. A virtual machine cloned from a template carries the template's disk, and therefore its /etc/machine-id, while the platform-held identities differ per clone. Because the class is part of the challenge, a machine that stops producing its class A identity produces a class C challenge, which no longer matches the license.

Changing the hardware can unregister a server with a perpetual license

Moving the installation to different hardware, or a virtualisation change that alters the SMBIOS UUID or TPM, produces a different challenge. A perpetual license stops matching. The last valid license does not bridge that as a fault either, because its record was written on the old hardware: the server runs unregistered until it is reactivated, switching off everything an unregistered server does not carry. See When the license changes.

Plan a migration as a reactivation, not as a file copy: on the new server, move the license there. A subscription is not bound to the hardware, so new hardware under the same installation keeps it.

Activating

Online, in one step

The console's License page can activate directly: it trades your license key and email plus this server's own challenge for the signed file and the first check-in receipt in one round trip.

That has a useful side effect on day one: it proves the machine can actually reach the license server it will be checking in with.

The same activation from the command line, for a server nobody has a browser on:

Remote or localagainst pelmo

$ ohm license activate --key A067-8266-AC09-F75B-0211 --email owner@example.com

Moving a license to this server

A license runs on one server, or on as many as its installation cap allows. When you activate it on a new one while it is still active on the old one, the Activate this server panel says This license is active on another machine. Move it here?

1. Press Move it here. The license server e-mails the address the license was issued to a link to confirm the move. The panel says the e-mail was sent, and until when the link works: 24 hours.
2. Open the link in the e-mail and confirm.
3. Press Check again in the panel. The license moves to this server and is activated here.

The old server stops using the license at its next check-in and runs unregistered: what the license carried is switched off there, its GeoIP and Fail2Ban sponsorships included. An old server that is off the network stops when its offline days run out.

From the command line, --move does the first step and the same command run again once the link is confirmed finishes it; until then it ends with exit code 2:

Remote or localagainst pelmo

$ ohm license activate --key A067-8266-AC09-F75B-0211 --email owner@example.com --move

The panel says	What it means
This license is active on another machine. It cannot be moved here before a date	A license can be moved once in 30 days and three times a year; that is the day the next move is allowed
This license was moved too recently	The same limit, met by the move just asked for
The license server cannot send the confirmation e-mail a move needs right now	Nothing was moved and nothing was sent. Try Move it here again later

Asking again before the link is confirmed sends no second e-mail for a quarter of an hour. An offline license cannot be moved.

Through the portal

The manual flow still exists. Copy the server's hardware challenge from the License page, paste it into the activation portal with your license key, and download the resulting .lic.

Then install it by uploading it on the License page, or by dropping it into the license directory:

/root/.local/share/ohm/license/

Files there are loaded at startup, and re-scanned hourly, so a renewal takes effect without a restart. Invalid or expired files are reported as warnings rather than silently ignored.

Local only

$ ohm license agreement show

Remote or localagainst pelmo

$ ohm license agreement status

show prints the agreement this build carries; status says which version is in force and who accepted it, on this host or on a remote one.

The License page shows the agreement too, and under it the Third-party notices: every open-source component built into the product, with the license it is distributed under. They read as a document, with the components in tables and each license text in a block of its own that opens when you click it or the component's license in a table. The command line prints the same notices:

Local only

$ ohm license notices

Your e-mail address is proof, not a lookup key

The address used at activation proves ownership of the license. It is not how a license is found or identified, and changing it is not how you move a license to another server.

The recurring check-in

A node-locked license on a build that knows its license server is kept honest by a recurring check-in. A scheduled job reports to the license server and receives a signed receipt.

Cadence	Daily by default. The license server may ask for anything from 1 to 168 hours
After a failed check-in	Tried again at the retry interval the license server sets, every hour by default, until a check-in succeeds; then the cadence again. The License check-in card says when the next attempt is due
Grace window	The license's own: 7 days on the current offers. Before the first check-in has got through, 14 days
On failure	The server keeps working on the last receipt until the window ends. A subscription then runs on as License server unreachable: nothing is switched off, and only changes that need a feature beyond Community wait, until the license's offline days run out (14 days after the last check-in unless the license says otherwise); then it runs unregistered, as No check-in for too long. A trial whose window ends becomes a fault: it runs on for 14 days on the last license the server verified, then unregistered
On recovery	Full edition returns the moment one check-in succeeds

The window is carried by the receipt, not by a local timestamp. A server whose receipt runs out without a check-in getting through keeps everything running if its license is a subscription whose term has not ended, for at most the offline days the receipt states. A trial keeps everything running for 14 days as a fault. After either, the server runs unregistered until a check-in gets through. A license server that answers and refuses the license is not an outage: the server runs unregistered at once. See When the license changes.

Disabling the check-in schedule disables the asked cadence and the retry with it, so the daily schedule is both the floor and the operator's off switch. A license that was given back, by removing it or because the license server says it was deactivated, is not retried sooner.

What the check-in reports

This is customer business data and you should know what leaves your server. Each check-in carries:

• The license key and this installation's randomly generated install id
• The hardware challenge and the product version
• The number of running instances, not the number configured, and the number of console accounts, each with what the license allows
• The host names your instances answer on
• This server's clock and the sequence number of the last receipt it holds
• The version of the license agreement accepted here, its digest and when it was first accepted

Activating from the License page or with ohm license activate sends the same, except the two counts, and adds the e-mail address the license was issued to and the comment you give, if any. The license server records the network address each call arrives from, and its time and outcome. No database, filestore, log or credential is sent, and neither the name nor the address of whoever accepted the agreement. The license agreement describes it in Article 4.2.

A server with no license

A server with no license file installed has nothing to check in with. The same scheduled job then sends a daily report to the license server instead, so Antelao can see how the product is used without a license. It carries:

• The product, this installation's install id and the hardware challenge
• The product version and this server's clock
• The number of running instances and of console accounts
• The host names your instances answer on
• The version of the license agreement accepted here, its digest and when it was first accepted

No license key is sent and nothing is granted in return. The license server records the network address the report arrives from and the country it is in. The license agreement describes it in Article 4.2.

Cadence	Once a day, as the license server asks
Off switch	Disabling the License check-in schedule on the Maintenance page stops it too
On failure	Nothing happens to the server. A report that cannot be delivered does not fail the job; the job's result and the License page say so
Where it shows	The License page's Report to the license server card, with when the last report was delivered and when the next is due, and ohm license presence

Report now on that card sends one immediately. When you install a license later, the installation keeps its install id, so the license server recognises it; from then on the check-in reports instead.

Clock changes

The receipt carries the license server's own clock, and the highest value ever seen is kept.

A local clock reading earlier than that is surfaced as a clock-rollback warning. A regression beyond five minutes that stays uncorrected for an hour of running time is enforced: the license is not honoured until the clock is corrected. On a server that held a valid license that is a fault, and after 14 days the server runs unregistered. Keep the server's clock synchronised.

A small regression never enforces, because a snapshot restore looks identical to one.

Files in the license directory

File	Contents
*.lic	The license files themselves
install-id	This installation's random id, generated once
checkin.receipt	The latest signed receipt
checkin-state.json	Last attempt, last success, last error, grace anchor, server-time mark
presence-state.json	When the daily report of a server with no license was last sent
last-valid-license.json	What the last license this server could verify granted, which a fault runs on

The license directory must be writable

Before the first receipt arrives, the grace window counts from an anchor written into checkin-state.json. If that file cannot be written, typically because the license directory is mounted read-only, the anchor is held in memory instead: the window still ends, and both the log and the License page say so. A restart moves the in-memory anchor.

The limits a license carries

Every limit on Editions is read from the license: the instances, the console accounts, the databases, custom modules and host names per instance, and the concurrent jobs. A license that states no value for databases, custom modules or host names per instance, or for concurrent jobs, gets the unregistered one. Each is enforced on what already exists, as soon as the license changes: see The limits.

The instance limit

A license may carry its own maximum instance count, separate from the edition quota. A start that would exceed it is refused, while restarting an instance that already runs never is. When a license allows fewer instances than run, the ones above the limit are stopped - Production kept running first, then Staging, then Development, the oldest first within each - and started again by themselves when a license allows them. See When the license changes.

If check-ins are failing but the receipt is still valid, the receipt's limit applies, since that is the license server's latest signed word. With no usable receipt, the license's own limit applies.

A license's console user accounts limit counts the console accounts that exist, enabled or not, rather than concurrent sessions. It is enforced when an account is created: the account that would exceed it is refused. When a license allows fewer accounts than are enabled, the newest are disabled until it allows them again; the account created at setup and one Administrator are always kept.

The version ceiling

A license may cover product versions up to a given major.minor and nothing newer. It is a ceiling, not a pin: a license covering 3.4 keeps running 3.0, 3.1 and 3.4, and refuses 3.5 and 4.0.

A license that does not cover the build is not applied at all, and the License page names both numbers rather than showing a generic refusal. A server that held a valid license runs on it for 14 days as a fault, and then unregistered.

Offline licenses

Every perpetual license is an offline license: issued for one machine, it never checks in, and never degrades for lack of a receipt. Subscriptions and trials always check in.

In exchange it is only valid on attested hardware. At every load the machine must present a class S identity and satisfy every one of these, in order:

1. The TPM carries an endorsement key certificate in its reserved NV storage. Most virtual TPMs carry none, which is where they usually fail.
2. That certificate parses as X.509.
3. Its public key is the endorsement key this chip derives. The modulus match is the one check that ties the certificate to the silicon.
4. It is not self-signed.
5. It is inside its validity period.
6. It declares the TCG endorsement-key-certificate usage.
7. Its TCG vendor id is one of the hardware manufacturers the build recognises. Vendor ids that virtual TPMs present are deliberately absent, and a refusal names them as virtual.
8. Its signature chains to the certificate authority of a TPM manufacturer the build carries, so a certificate that merely names a genuine manufacturer is refused.

Update the host agent and the management API together

From 0.24.0 an offline license runs only once the host agent and the management API are both on 0.24.0 or later, because the agent hands the API the manufacturer check above. On a server with an offline license, update both together.

Removing a license

Removing a license from the License page deletes the files. Nothing in the API or the console can select a removed license back, so keeping the files would only have looked like a safety net. Keep your own copy.

A subscription or a trial is given back to the license server as it is removed: its place under the installation cap is free at once for another server, and this server stops honouring it, even with the file put back, until the license is activated here again.

A perpetual license removed or replaced stays activated on this server at the license server. To install it on another server, ask support to reset its activations.

The server then runs unregistered, and everything an unregistered server does not carry is switched off until a license is installed again. See When the license changes.

Related

• Editions
• When the license changes
• Mail, for the expiry warning
• Troubleshooting