License Management
Every QuantaStor appliance needs its own license key before it will accept any configuration change, and every key must be activated within seven days of being applied. This page covers what a key entitles a system to, how keys are distributed across a storage grid, the License Manager and its Add / Activate / Remove flows, and how to read the current license state from the web interface and from the CLI.
| Section | Purpose |
|---|---|
| Why a license is required | What stops working without a valid license, and what keeps working. |
| What a license key covers | Editions, categories, capacity limits and feature flags carried in a key. |
| License keys in a storage grid | One key per appliance, unique keys, and how support keys attach to system keys. |
| The License Manager | The dialog that owns every licensing action. |
| The Licenses tab | The per-system license grid and what each column means. |
| Adding a license key | The EULA, the key block, and the Add License dialog. |
| Bulk add | Applying a multi-key file across a grid, and the distribution plan. |
| Activating a license key | Online activation, offline activation by email, and the grace period. |
| Expiry, leases and renewal | What happens as a key approaches and passes its end date. |
| Support keys | Support subscription keys and the reseller contact details attached to them. |
| Removing a license key | When to remove a key, and what removal costs you. |
| Checking license state from the CLI | license-list and license-get.
|
Why a license is required
A license key is what enables management operations on a Storage System. The service checks the local system's license before it runs any operation that creates, modifies or deletes an object -- pools, volumes, shares, users, schedules, snapshots, replication, Ceph resources -- and refuses with a message naming the system:
No licenses are registered for Storage System 'qs-node-110', please add a license to enable management functions.
Once the activation grace period has run out the refusal changes to:
The grace period for activating license on Storage System 'qs-node-110' has expired.
What keeps working matters as much as what stops. The check sits in the management service, not in the data path, so pools stay imported and existing volumes and network shares keep serving their clients. Listing, monitoring, alerting and the Tasks view are unaffected, and so are the licensing operations themselves -- you can always add and activate a key on a system that is otherwise refusing changes.
Adding, activating and updating a license key are also exempt from the password-expiry check, so you can license a system whose admin password has already lapsed without resetting it first.
What a license key covers
A key is issued to one appliance and carries the entitlement as a set of fields, all of which are visible with qs license-get --key=<key>.
| Field | What it controls |
|---|---|
| Edition | Free/Community, Trial, Standard, Enterprise, or Express Edition. Free/Community Edition additionally caps the grid at four appliances, and on a support key the edition sets the support level. |
| Category | What kind of key it is: Storage System (the system key, one per appliance), Support Subscription, Multi-Feature License, or a single-feature add-on -- + Terabyte Limit, + Node Limit, + Volume Limit, + Snapshot Limit, + Cloud Limit, + User Limit, + SSD Optimized, + Remote Replication. |
| Duration | Subscription -- time-limited, with an expiration date -- or Multi-year Subscription, which has no expiration date of its own. |
| Terabyte Limit | Raw capacity, in TB, that the system may place under management. See Capacity accounting below. |
| Node, Volume, Snapshot, Cloud and User limits | Object count ceilings. The cloud limit caps the number of cloud resource groups, with a floor of 16 regardless of the key. |
| SSD Enabled / Remote Replication Enabled | Gate SSD caching and optimization, and remote replication links, schedules and replicas. Trial and Cloud Edition keys bypass both checks. |
| Encryption Disabled / Object Storage Disabled | Set on keys that exclude pool encryption or object storage; the matching operation is refused with "key feature validation check failed". |
| Is High Availability | Marks the key as an HA key. Where an HA key names a parent key, that parent key must also be registered somewhere in the grid or the secondary node's key is not honoured. |
| Lease Enforcement Enabled | The key must re-check in with the license server periodically. See Expiry, leases and renewal. |
| License Server | The license server the key was issued from and the one it activates against. Keys issued by OSNEXUS carry licensing.osnexus.com; a key issued from a dedicated cloud license server names that server instead.
|
| Parent License Key / Replaces License Key | Which system key a support or feature key belongs to, and which key a reissued key supersedes. |
Capacity accounting
The Terabyte Limit is measured against raw disk capacity actually in use, not against provisioned or used space. A physical disk counts towards the total once it belongs to a storage pool, a pool device, a Ceph OSD or a Ceph journal group. Excluded are system and pool-level hot-spares, multipath child devices, mounted disks, and the mirrored boot pool. Disks that belong to a hardware unit are counted as the smallest disk in the unit multiplied by the number of disks in it, so an array of mixed drives is not over-counted.
The system's licensed capacity is the sum of the Terabyte Limits of every Storage System, Multi-Feature and + Terabyte Limit key registered to it; expired time-limited keys are dropped from the sum. Storage pool create and grow are the operations that check it, with roughly a terabyte of slack before they refuse:
License space limit exceed by 3.98TB, cannot create/grow storage pool due to insufficent licenses (32TB limit). Please contact your OSNEXUS representative regarding an add-on license.
The TB Utilized column shows how much of each key's capacity is accounted for. When utilization passes the limit, the key moves to a Warning state whose detail reads Licensed limit exceeded by 'n' TB.
License keys in a storage grid
Licensing is per appliance, not per grid: a three-node grid needs three system keys. Keys are unique to one system, and a system cannot be added to a grid using a key that is already registered on an existing member:
Specified system 'qs-node-112' is using license key 'XXXX-XXXX-XXXXXX-XXXX' which is already in use by node 'qs-node-111'. Each appliance in a grid must have a unique license key.
License records replicate across the grid, so the License Manager and qs license-list on any member show every member's keys, grouped by Storage System. A key is bound to the system's identifier rather than to its host name, so renaming a system leaves its license untouched.
Support and feature keys are not free-standing. Each one names its system key in a parent field, and that system key has to be registered on the appliance before the support or feature key will be accepted:
Feature license add failed. The system license must be registered before feature licenses may be added.
Two further rules follow from that pairing, and both matter when you are applying a bundle of keys:
- A feature key must be the same edition as the system key it attaches to. Support keys are the exception -- a support subscription may be at a higher or lower level than the system key.
- Applying a system key clears every other license on that appliance. Add the system key first and its support and feature keys afterwards; if you re-apply a system key later you have to re-apply the feature keys with it. The Bulk Add plan warns you when a key file re-supplies a system key without re-supplying the support and feature keys it will clear.
The License Manager
The License Manager is where every licensing action lives.
It is also on the context menu of a Storage System in the tree, and on the About dialog. The Registered License Keys grid at the top of the dialog is the same grid as the Licenses tab, and the five buttons below it are:
| Button | What it does |
|---|---|
| Activate Online... | Activates the selected key by contacting the license server directly. |
| Activate via Email... | Generates the activation request email for a system with no route to the license server, and takes the activation code that comes back. |
| Add License... | Adds one key block to one Storage System. |
| Bulk Add... | Distributes a key file containing several keys across the whole grid. |
| Remove License | Removes the selected key. |
Select a row before pressing a button: Activate Online, Activate via Email and Remove License open with the selected key already chosen, and Add License opens with that key's Storage System selected.
Right-clicking a license row -- in the License Manager or on the Licenses tab -- offers the same set of actions plus Modify Support Contact Info..., which has no button of its own.
You can also license a new appliance from the Getting Started / Configuration Guide, whose System Setup workflow puts Add License at Step 1 and Activate License at Step 2. Both buttons open the same dialogs described here.
The Licenses tab
The tab lists every license key in the grid, grouped by the Storage System that holds it, so you can see at a glance which appliances are licensed and which are not.
| Column | Meaning |
|---|---|
| Edition | The key's edition, e.g. Trial Edition, Enterprise Edition. |
| Status | Activated, or Requires Activation in red until an activation code has been applied. |
| License Server | The license server this key activates against. |
| Expires | Days remaining, in red under 14 days and Expired once past. Never for a key with no end date, or Lease Enforced with the days left in the current lease. |
| TB Limit | Raw capacity the key licenses, in TB. |
| TB Utilized | Raw capacity currently attributed to this key. |
| License Key | The key itself. Keys are four dash-separated groups, XXXX-XXXX-XXXXXX-XXXX.
|
| Full Name, Company | Licensee details carried in the key block. |
| Duration | Subscription or Multi-year Subscription. |
| High Availability | Always renders Supported. |
| Category | Storage System, Support Subscription, Multi-Feature License or one of the single-feature add-ons. |
Storage System, Type and Version columns exist but are hidden by default; add them from the column header menu. Sorting is by Category.
Select a row and open the Properties panel on the right edge for the same key in a vertical list -- Status, Edition, Type, Category, Duration, Company, Full Name, Email and, for a time-limited key, its expiration date. The panel is also the quickest place to read the Activation Request Code you need for offline activation: it shows that field while a key still needs activating, and the applied Activation Key once it has been activated. A not-for-resale key is called out there as NOT FOR RESALE.
Adding a license key
OSNEXUS sends license keys by email. Each key arrives as a human-readable summary -- edition, duration, category, capacity, expiration date -- followed by the key block that the appliance actually reads:
Generated License Key: XXXX-XXXX-XXXXXX-XXXX
License Edition: Enterprise
License Duration: Time-limited
License Category: System
Terabyte Limit: 256
Expiration Date:Tue Jun 22 00:00:00 2027
--------START KEY BLOCK--------
66756c6c2d6e616d653d4f534e65787573205375
70706f72740a656d61696c2d616464726573733d
0a7365727665722d6671646e3d6c6963656e7369
6e672e6f736e657875732e636f6d0a747970653d
... twenty or more further lines ...
653d547565204a756e2032322030303a30303a30
---------END KEY BLOCK---------
Add License presents the end user license agreement first. Accept opens the Add License dialog; Decline ends the operation. The dialog itself has two fields:
- Storage System -- which appliance in the grid the key is applied to. It is pre-selected from whatever you had selected when you opened the dialog, and must be set before OK will proceed.
- A text area for the key block.
Paste the key block including the START KEY BLOCK and END KEY BLOCK lines. The block is signature-checked on the appliance, so a partial copy is rejected rather than half-applied -- the most common reason an add fails is a paste that stopped short of the end of the block. Use the clipboard rather than retyping.
From the CLI, point qs license-add at a file containing the key block:
qs license-add --key-file=/tmp/mykey.txt qs license-add --key-file=/tmp/mykey.txt --storage-system=qs-node-111
Omit --storage-system to license the appliance you are connected to. Adding a key registers it; it does not activate it.
Bulk add: distributing a key file across a grid
A grid order arrives as a single key file holding one system key per appliance, and often a support key for each. Bulk Add takes that file, works out which key belongs on which appliance, shows you the plan, and then applies it.
Select the key file with Browse..., or paste its contents into Key Blocks directly. Then press Preview Distribution Plan. Preview changes nothing at all -- it neither takes a lock nor starts a task -- so it is safe to run as often as you like while you check the plan.
The equivalent CLI command is qs license-add-bulk, with --preview for the same plan as a table:
qs license-add-bulk --key-file=/tmp/gridkeys.txt --preview
STORAGE SYSTEM SYSTEM KEY REPLACES KEY SUPPORT KEY KEY TB NEED TB FIT ACTION MESSAGE
qs-node-120 aAbB-cCdD-eEfF01-2345 0123-4567-89aAbB-cCdD 256 0 OK PREVIEW System key assigned, replacing the node's current license (expires 2026-11-25). New expiration: 2027-06-22.
qs-node-121 6789-aAbB-cCdDeE-fF01 eEfF-0123-456789-aAbB 256 0 OK PREVIEW System key assigned, replacing the node's current license (expires 2026-11-25). New expiration: 2027-06-22.
qs-node-122 2345-6789-aAbBcC-dDeE cCdD-eEfF-012345-6789 256 0 OK PREVIEW System key assigned, replacing the node's current license (expires 2026-11-25). New expiration: 2027-06-22.
fF01-2345-6789aA-bBcC 256 0 UNASSIGNED Every grid node already has a system key from this run; no node left for this key.
How keys are matched to appliances
The plan is computed on the grid master from grid-replicated inventory and license records -- it does not query the other nodes -- and it is recomputed when you apply, so the plan reflects the state of the grid at the moment the work actually runs.
- Keys already registered anywhere in the grid are never re-applied. They are reported as already applied, and the appliance holding them is remembered so their support and feature keys can still be routed to it. This is also what makes a partly-applied run safe to repeat: a second run picks up only the keys that did not land the first time.
- A key that names the key it replaces is pinned to the appliance holding that key, even if that appliance is currently licensed. This is the renewal and upgrade case.
- The remaining system keys are best-fitted, in two passes. Appliances with no license or an expired one are served first, largest capacity requirement first, so the biggest appliance gets the key that fits it. Any keys still left over then go to appliances that are already validly licensed, soonest-to-expire first, as replacements -- reissued keys with a later end date are routine, so a licensed appliance is never skipped outright, only ranked behind every appliance with no usable license.
- For each appliance the smallest key that meets its requirement wins, with the earliest key in the file breaking a tie. If no remaining key is large enough, the largest one left is assigned and Fit reads UNDER.
- Support and feature keys follow their parent system key to whichever appliance ends up holding it.
Capacity is the only thing the match considers; it does not take HA pairing into account.
Reading the plan
Each row is one appliance, or one key that could not be placed on one. Key TB is the capacity the key licenses and Need TB is the appliance's raw capacity requirement; Fit is OK when the key covers it and UNDER when it does not. The Message column carries the detail, including the two ways a reissue can quietly cost an appliance something -- a new key with less coverage than the one it replaces, and a new key with a lower TB limit than the current one.
| Action | Meaning |
|---|---|
| PREVIEW | The plan will apply keys to this appliance. These rows start ticked. |
| APPLIED | The keys were applied to this appliance. |
| FAILED | The apply was attempted and failed; the message says why. |
| NODE_OFFLINE | The appliance has no reachable management port, so it was skipped. |
| SKIPPED_NOT_SELECTED | You unticked the row, so the appliance was left alone. |
| SKIPPED_ALREADY_APPLIED | The key in the file is already registered on this appliance. |
| SKIPPED_ALREADY_LICENSED | The appliance keeps its current license because no key was left over to replace it. |
| SKIPPED_NO_KEY | The appliance is unlicensed and the file had no key left for it. |
| SKIPPED_DUPLICATE_KEY | The same key appears more than once in the file. A key may only ever be applied once. |
| UNASSIGNED | The key could not be placed -- every appliance already has one from this run, or a support or feature key's parent system key is neither in the file nor registered in the grid. |
A key block the appliance cannot decode is reported on its own row as FAILED and the rest of the file is still processed, so one bad key does not sink the run.
Applying the plan
Every actionable row starts ticked. Untick any appliance you want to hold back, then press OK. The work runs as a task on the grid master, which sends each appliance its own key blocks -- system key first, then the support and feature keys that hang off it. A failure on one appliance does not stop the others, and each row's outcome is recorded, so the Tasks view tells you which appliances were licensed without reopening the dialog.
On the CLI, limit an apply to particular appliances with --system-list:
qs license-add-bulk --key-file=/tmp/gridkeys.txt qs license-add-bulk --key-file=/tmp/gridkeys.txt --system-list=qs-node-120,qs-node-121
Bulk Add adds keys; it does not activate them. Activate each appliance afterwards.
Activating a license key
A key that has been added but not activated shows Requires Activation in red, and starts a seven-day grace period during which the appliance behaves normally. Warning alerts are raised as the grace period opens and again with 48 and 24 hours left. When it runs out, configuration changes stop until an activation code is applied; nothing else about the appliance changes, and applying the code restores it immediately.
Online activation
Select the key, check that Activation Status reads Activation Required, and press OK. The appliance contacts the license server named in the key -- the License Server column -- and writes the activation code it gets back into the license record. From the CLI:
qs license-activate-online qs license-activate-online --key=aAbB-cCdD-eEfF01-2345
With no --key the command picks the first key that still needs activating, preferring the local system's, and reports There are no keys available to activate. when every key is already activated.
Online activation needs a working default gateway and DNS. When it fails, the appliance works out whether the network is the reason and says so rather than just reporting a failure: for a key issued by OSNEXUS it pings a public DNS address and then resolves a public host name, and reports a gateway problem or a DNS problem accordingly; for a key issued from another license server it pings that server instead. Two results are worth knowing in advance:
- More than one default gateway will break activation. The gateway check specifically advises verifying that only one network gateway is configured, on one port.
- An HTTP proxy suppresses the diagnosis, not the activation. Activation requests go out through the proxy configured on the Storage System. But if
HTTP_PROXYis set in/etc/environment
Offline activation by email
Use this when the appliance has no route to the license server. Select the key and the dialog fills in a Subject and a Message containing the licensee name, the email address on the key, the activation request code and the license key. Send that text to support@osnexus.com, then paste the activation code you receive into Activation Code and press OK.
The two fields are only populated while a key needs activating. For a key that is already activated the Subject and Message fields are empty and disabled, and Activation Code shows the code that was applied.
The same code can be applied from the CLI, and does not need the key to be named -- the appliance matches the code against the request codes of the keys it holds:
qs license-activate --activation-key=aAbB-cCdD-eEfF-0123
Expiry, leases and renewal
The license manager re-checks the local system's license every five minutes, so a key that lapses or is renewed takes effect without a service restart.
| Key | Expires column | What happens at the end |
|---|---|---|
| Subscription (time-limited) | Days remaining, red under 14 days, then Expired | Configuration changes stop and a License Subscription Expired alert is raised. Existing storage keeps serving clients. |
| Multi-year Subscription without lease enforcement | Never | Nothing; the key does not lapse. |
| Multi-year Subscription with lease enforcement | Lease Enforced, with the days left in the current lease | The appliance renews the lease against the license server once a day. The key lapses 30 days after the last successful renewal, or 30 days after its license date if it was never activated, and raises a License Subscription Lease Expired alert. |
Lease renewal is automatic and needs no operator action, but it does need the license server to stay reachable -- a lease-enforced appliance that loses its route to the license server for a month stops accepting configuration changes. Force a renewal with qs license-activate-online --renew-lease.
A key can also be retired at the license server, which takes effect at the next check regardless of the expiration date and raises a License Subscription Retired alert. If a key you expect to be current is reported as retired, contact OSNEXUS support.
To renew, add the replacement key and activate it. A renewal system key replaces the appliance's existing one, so re-apply any support and feature keys with it; across a grid, Bulk Add handles both in one pass.
License alerts
Licensing raises these alert types, which are routed like any others by the Alert Manager:
| Alert | Severity | Raised when |
|---|---|---|
| License Activation Required | Warning | A key is added and the grace period begins. |
| License Grace Period Ending | Warning | 48 hours and again 24 hours before the grace period ends. |
| License Grace Period Expired | Error | The grace period ran out with no activation code applied. |
| License Activation Key Invalid | Error | A stored activation code fails verification. |
| License Check Failed | Warning | No system license is present on the appliance. |
| License Subscription Expired | Warning | A time-limited key passed its expiration date. |
| License Subscription Lease Expired | Warning | A lease-enforced key has not renewed for 30 days. |
| License Subscription Retired | Warning | The license server retired the key. |
| License Subscription Activated | Info | A key became active. |
Support keys and support contact information
A Support Subscription key is a second key that attaches to an appliance's system key and carries the support entitlement. It is separate from the system key on purpose: support renews on its own cycle, and a support subscription may be at a higher or lower level than the system key it covers. Support keys are added exactly like any other key -- individually with Add License, or as part of a grid bundle with Bulk Add, which pairs each support key with its system key automatically.
The support key's edition determines the support level, which the Properties panel shows as Support Level on a support key -- and only on a support key:
| Support key edition | Support Level |
|---|---|
| Express | OEM Support |
| Standard | Silver Support |
| Enterprise | Gold Support |
| Platinum | Platinum Support |
| Cloud, Migration | OEM Support |
| Object | OEM Support |
| Trial | Proof-of-Concept |
| Free/Community | Community Support |
Where support is delivered by a reseller rather than by OSNEXUS directly, record the reseller's details against the key:
The dialog shows the selected key, its activation status and the Storage System that holds it, then takes Support Contact Name, Support Email, Support Phone and Support Contract #. Tick Apply info to all licenses in Storage Grid to push the same details onto every key in the grid rather than just the selected one.
The details are stored on the license record and also written to /var/opt/osnexus/quantastor/support.info
The same fields are available on the CLI:
qs license-modify-support --key=aAbB-cCdD-eEfF01-2345 --reseller-name="Example Reseller" \
--reseller-email=support@example.com --reseller-contact-number=+1-555-0100 \
--support-contract-number=EX-12345
Removing a license key
Removing a key is rarely necessary -- adding a replacement system key already supersedes the old one -- and the option is mainly there for clearing out an expired key. Select the key, check the Edition, Type, Category and Duration shown in License Properties, and press OK; a confirmation prompt names the key before anything is removed.
Removing an appliance's system key removes every license on that appliance and immediately disables configuration changes on it, exactly as if it had never been licensed. Data access is unaffected: pools stay imported and clients keep reaching their volumes and shares.
qs license-remove --key=aAbB-cCdD-eEfF01-2345
Checking license state from the CLI
qs license-list lists every key in the grid. Add --flags=min for one line per key:
qs license-list --flags=min Storage System License Key Full Name Company License Edition TB Limit Expires qs-node-110 aAbB-cCdD-eEfF01-2345 ... OSNEXUS 1 32 Wed Nov 25 19:06:55 2026 qs-node-111 6789-aAbB-cCdDeE-fF01 ... OSNEXUS 1 32 Wed Nov 25 19:06:55 2026 qs-node-112 2345-6789-aAbBcC-dDeE ... OSNEXUS 1 32 Wed Nov 25 19:06:55 2026
The minimal form prints License Edition as its numeric value; the web interface and the full output resolve it to a name.
qs license-get --key=<key> prints one key in full -- every entitlement field listed in What a license key covers, plus the activation request code, the activation key, the last lease renewal date, the reseller contact fields and the capacity currently attributed to the key. The --key argument is mandatory, so take the key or its UUID from qs license-list first.
Related pages
- Storage System -- the appliance a license key is issued to.
- Grid Configuration -- combining licensed appliances into a storage grid.
- Upgrade Manager -- keeping a licensed appliance current.
- Send System Log Report -- support log reports, which carry the support contact details recorded against a license key.
- Alert Manager -- where license alerts are routed.
- QuantaStor CLI Command Reference -- full argument lists for the
license-*commands.
Verified against QuantaStor 6.9.0.