Activate a licence

Activate a VMStack licence key on a panel, read the licence page, refresh it, move a licence to another panel and remove it.

A licence key looks like VMS-STD-XXXX-XXXX-XXXX-XXXX. The second group is the type: STD for a standard licence (Unlimited and Small nodes), HOM for Homelab, EVL for a trial. Your keys are in your vmstack.eu account, under Licences.

A key is bound to one panel install at a time, and an install has one licence.

Activate a key#

In the panel:

  1. Go to System › Settings › Licence (or the Welcome to VMStack screen of a new panel).
  2. Under I have a licence key, paste the key into Licence key. Case, spaces and dashes do not matter.
  3. Click Activate. Activating means you accept the VMStack licence terms.

The page says "Licence activated:" with the plan's name. The key has a check character, so a mistyped key is caught before anything is sent: "This is not a valid licence key. Check it for typos".

Activating a second key on a panel that already has one replaces the first, which is freed.

While installing#

Pass the key to the panel installer and it is activated at the end of the install:

curl -fsSL https://vmstack.eu/install.sh | bash -s -- --licence-key VMS-STD-XXXX-XXXX-XXXX-XXXX

See Installer options.

From a shell#

On the panel server:

sudo -u vmstack php /opt/vmstack/current/artisan vmstack:licence-activate VMS-STD-XXXX-XXXX-XXXX-XXXX

It prints "Licence … activated:" with the plan and the licensee, or why not. It prints the key masked.

The licence page#

Once a licence is held, System › Settings › Licence shows:

Field Meaning
Plan The plan's name, with Active, Evaluation, Attention (over the node allowance, or not refreshed for 24 hours), New servers blocked or Expired
Key The key, masked
Licensee The company the licence is for
Nodes The panel's nodes against the allowance ("3 of 4", or "no limit")
Nodes by plan For a licence with both Unlimited and Small nodes: how many of each
Servers per node The most servers on one node (Small), or "No limit"
Licence term ends The end of the paid period, or "No end"
Token valid until When the current licence token expires (48 hours after it was issued)
Last refresh When the panel last renewed the token

Refresh now renews the token at once, for example after you bought more nodes. Manage at vmstack.eu opens the licence in your account.

The same information is in the API at GET /api/v1/licence; see the API reference.

How the licence stays current#

The panel renews its token from vmstack.eu every 6 hours (plus a random delay of up to 30 minutes), sending its install ID, version and node and server counts. A token lasts 48 hours, so an outage of vmstack.eu or of the panel's internet access for a day changes nothing. When renewals fail, the panel retries after 15 minutes, 1 hour and then every 2 hours, and every 15 minutes once the token has less than 12 hours left. Administrators see a banner when the token is more than 24 hours old.

Changes to the licence (more nodes, a renewal, a trial converted to a paid licence) reach the panel at its next renewal, or at once with Refresh now. A new key replacing a trial's arrives the same way; you do not type it.

The panel checks the token's signature against a key built into the panel, refuses a token older than the newest it has accepted, and does not trust a clock that has been turned back. Setting the server's clock back does not extend a licence.

Move a licence to another panel#

A licence can be moved, for example to a reinstalled panel or a new server. Choose one:

  • On the old panel: System › Settings › Licence › Remove licence, confirm, then activate the key on the new panel.
  • In your vmstack.eu account, when the old panel is gone: open the licence, click Move to a new install and confirm, then activate the key on the new panel. The old panel stops creating servers and adding nodes within 48 hours.

A licence can be moved 3 times in 30 days; after that, contact support.

A panel restored from its own panel backup keeps its install, so its licence keeps working without a move.

Remove the licence#

Remove licence frees the key so it can be activated on another panel. The panel then cannot create servers or add nodes until a licence is activated again; running servers are not affected. If vmstack.eu cannot be reached at that moment, the licence is removed from the panel anyway, and the page tells you to move the key in your vmstack.eu account before using it elsewhere.