Skip to content

Products

Licensing

SurrealDB Enterprise, including every SurrealDS node, needs a valid licence to start. This page explains how to get a licence, where to find its key, where to put it, and how a node behaves while it runs.

A node gets its licence in one of two ways:

  • Licence key: The default. The node checks the key online against the licence service when it starts and while it runs.

  • Licence file: For nodes that cannot reach the internet. The node checks a signed file locally and never contacts the licence service. See Run offline with a licence file.

A licence key and a licence file are secrets. Anyone who has one can start nodes against your licence, so store them as you store a database password.

SurrealDB issues each licence to a SurrealDB Cloud organisation. If you do not have an organisation yet, sign in to SurrealDB Studio and create one first. Then contact SurrealDB or email sales@surrealdb.com, and give the name of your organisation.

LicenceUse it for
TrialEvaluating SurrealDB Enterprise. A trial is time-limited, and each organisation can have one trial.
PaidRunning SurrealDB Enterprise under a contract.

To issue a paid licence, SurrealDB needs this information:

InformationWhy it is needed
The number of nodes in the clusterThe licence limits how many nodes run at the same time.
The number of CPU cores on each nodeThe licence can limit the cores on one node and the cores across the cluster.
The term you needEach licence has an expiry date.

One licence covers one cluster. If you run a second cluster, such as a staging cluster beside production, request a second licence for it.

Offline use is a separate option on a licence. If your nodes cannot reach the internet, tell SurrealDB when you request the licence.

When the licence is issued, it appears in your organisation in Studio.

Each licence that SurrealDB issues to your organisation is listed on the organisation's Licences page in SurrealDB Studio. Organisation administrators and owners can see this page. Members cannot see it, and the page is only in the sidebar when the organisation has at least one licence.

  1. In Studio, open your organisation.

  2. In the sidebar, select Licences. The list shows each licence with its type (Trial or Paid), its expiry, its state when it is not active, and an Offline label when offline use is included.

  3. Select a licence. A panel opens with its status, type, expiry, node limit and whether offline use is included.

  4. To get the licence key, select Reveal key under Run with the licence key. Studio shows the line SURREAL_LICENSE_KEY=<your-licence-key>, which you can copy. Select Hide when you are done.

  5. To get a licence file, select Download licence file under Run offline. This section is only shown when offline use is included. Studio saves the file as <licence-id>.lic and shows the date until which the file is valid.

Keep the key and the file in your secret store, and supply them to each node as the rest of this page describes.

If Studio shows "This licence does not include offline use", the licence can only run with its key. To add offline use, contact SurrealDB.

Each node reads the key once when it starts, from SURREAL_LICENSE_KEY or from SURREAL_LICENSE_KEY_FILE. Set exactly one of these two variables. To run from a licence file instead, see Run offline with a licence file.

VariableValue
SURREAL_LICENSE_KEYThe licence key.
SURREAL_LICENSE_KEY_FILEThe absolute path to a file that contains the key, such as a mounted secret.
SURREAL_LICENSE_STATE_PATHOptional. The absolute path of the attestation cache file. See Starting while the licence service is unreachable.

The node refuses to start if both SURREAL_LICENSE_KEY and SURREAL_LICENSE_KEY_FILE are set, if the key file path is relative, or if the key file is unreadable or empty. Spaces and line breaks around the key are ignored. There is no command-line flag for the licence key.

To change the key, update the variable or the file and restart the node. In a cluster, restart the nodes one at a time.

The Enterprise image is surrealdb/surrealdb-enterprise. Pass the key from your shell, so that it does not appear in the command line:

export SURREAL_LICENSE_KEY='<your-licence-key>'
docker run --rm -p 8000:8000 -e SURREAL_LICENSE_KEY surrealdb/surrealdb-enterprise:latest start --user root --pass secret

-e SURREAL_LICENSE_KEY without a value copies the variable from the shell that runs docker. See Run with Docker.

Write the key to a file that only the service account can read, and point SURREAL_LICENSE_KEY_FILE at it:

sudo mkdir -p /etc/surrealdb
printf '%s\n' '<your-licence-key>' | sudo tee /etc/surrealdb/license.key > /dev/null
sudo chmod 600 /etc/surrealdb/license.key

Then set the variable in the service definition that starts the node:

systemd unit (Linux)
[Service]
Environment=SURREAL_LICENSE_KEY_FILE=/etc/surrealdb/license.key
Environment=SURREAL_LICENSE_STATE_PATH=/var/lib/surrealdb/license-state.json
launchd property list (macOS)
<key>EnvironmentVariables</key>
<dict>
    <key>SURREAL_LICENSE_KEY_FILE</key>
    <string>/etc/surrealdb/license.key</string>
    <key>SURREAL_LICENSE_STATE_PATH</key>
    <string>/var/lib/surrealdb/license-state.json</string>
</dict>

The file must be readable by the user that the node runs as. Run SurrealDS on your own machines shows a complete service definition.

Store the key in a Kubernetes Secret in the namespace of the SurrealDS resource:

kubectl -n <namespace> create secret generic surrealdb-license --from-literal=key='<your-licence-key>'

Then pass it to the nodes through spec.env. The operator has no licence field of its own:

spec:
  env:
    - name: SURREAL_LICENSE_KEY
      valueFrom:
        secretKeyRef:
          name: surrealdb-license
          key: key
    - name: SURREAL_LICENSE_STATE_PATH
      value: /var/lib/shale/license-state.json

The operator does not mount extra volumes into the node pods, so use SURREAL_LICENSE_KEY with a secretKeyRef rather than SURREAL_LICENSE_KEY_FILE. /var/lib/shale is the node's persistent volume, so the attestation cache survives a pod restart there. A change to the Secret does not restart the nodes, so restart them after you rotate the key. See Deploy SurrealDS with the Kubernetes operator.

Each node checks its own licence, without asking the other nodes.

  • At startup, the node validates the key online against the licence service at api.keygen.sh, and checks the signature on the answer against a key built into the binary.

  • While it runs, the node validates again every 30 minutes, with up to 10% random variation, and sends a heartbeat every 15 minutes.

  • Each node counts as one machine against the licence's node limit. A SurrealDS node is identified by its scope and node number, so it keeps the same identity across restarts and machine moves. Any other node is identified by its host name.

Each node needs outbound HTTPS (TCP port 443) to api.keygen.sh. The node connects to it directly, not through a SurrealDB service, and verifies its certificate against the operating system's trusted certificate authorities.

A node that runs with a licence key and has never reached api.keygen.sh cannot start. To run where outbound internet access is not permitted, use a licence file.

With SURREAL_LICENSE_STATE_PATH set, the node stores the last signed answer from the licence service at that path. If the licence service is unreachable at a later start, the node verifies the stored answer again and starts from it, as long as the answer is less than 24 hours old.

  • Put the file on persistent storage. A file in a container's writable layer is lost when the container is recreated.

  • Protect the file. It contains the licence key in plain text. The node creates it with mode 0600.

  • Use an absolute, writable path. A relative path, or a path that the node cannot write, stops the node from starting.

Without the variable there is no cache, and every start needs api.keygen.sh to be reachable. A cache stops being used when the licence key changes, so the first start after a key rotation also needs api.keygen.sh. A machine clock more than one hour behind the time on the stored answer also prevents its use.

Available since: v4.0.1

A licence file is a signed copy of your licence that a node checks locally. A node that runs from a licence file never contacts api.keygen.sh or any other SurrealDB service, so it can run in an air-gapped network.

A licence file is available only for a licence that includes offline use. In Studio, these licences have the Offline label. To add offline use to a licence, contact SurrealDB.

Download the file from Studio, as described in Find your licence in Studio. Then point SURREAL_LICENSE_FILE at it:

VariableValue
SURREAL_LICENSE_FILEThe absolute path to the licence file.

The node refuses to start if SURREAL_LICENSE_FILE is set together with SURREAL_LICENSE_KEY, SURREAL_LICENSE_KEY_FILE or SURREAL_LICENSE_STATE_PATH. The attestation cache is not used with a licence file, because the node has no online answer to store.

To run the Docker image from a licence file, mount the file read-only into the container:

docker run --rm -p 8000:8000 \
  -v /etc/surrealdb/license.lic:/license.lic:ro \
  -e SURREAL_LICENSE_FILE=/license.lic \
  surrealdb/surrealdb-enterprise:latest start --user root --pass secret

For a binary on your own machines, store the file as you store a key file, readable only by the service account, and set Environment=SURREAL_LICENSE_FILE=/etc/surrealdb/license.lic in the service definition.

The Kubernetes operator does not mount extra volumes into the node pods, so it cannot supply a licence file. To run SurrealDS offline on Kubernetes, contact SurrealDB.

Each file has its own validity period, which starts when you download it. The default period is 180 days, and the longest period is 366 days. A file stops being valid at whichever is earlier: the end of its own period, or the expiry date of the licence.

A licence file cannot be withdrawn after it is issued. If SurrealDB suspends a licence, the files that were already downloaded for it stay valid until they expire. This is why a file has a limited period.

The node checks the file against its own system clock. Keep the clock on each node correct.

The node reads the file once when it starts. To renew it:

  1. Download a new file from Studio.

  2. Replace the old file on each node.

  3. Restart the nodes one at a time.

Renew the file before it expires. A running node does not read a new file until it restarts.

Licence file stateAt startupOn a running node
ValidStarts.Keeps serving.
ExpiredRefuses to start.About 30 minutes or less after the expiry, /ready returns 503. The process exits with status 3 three hours after the expiry.
Not valid yetRefuses to start, unless the node's clock is behind the file's issue time by one hour or less.-
Signature, product or environment does not matchRefuses to start.-
Licence suspended when the file was downloadedRefuses to start.-
Offline use not includedRefuses to start.-
Over the per-node core limitRefuses to start.-

Unlike a licence key, an expired licence file also stops a running node, because the node has no other way to learn that the licence ended. To prevent a stop, put a renewed file in place and restart the node before the expiry, or within the three hours after it.

A node that runs from a licence file does not count the nodes in the cluster. The node limit of the licence still applies under your agreement with SurrealDB.

This section describes a node that runs with a licence key. For a licence file, see What happens when a licence file expires.

Licence stateAt startupOn a running node
ValidStarts.Keeps serving.
No key configuredRefuses to start.-
ExpiredRefuses to start. There is no grace period after the expiry date.Keeps serving and logs a warning. The next start is refused.
Suspended, banned or not foundRefuses to start.After two checks two minutes apart confirm it, /ready returns 503. The process exits with status 3 no sooner than 24 hours later.
Over the node or core limitRefuses to start.Keeps serving and logs a warning, or stops as for a suspended licence if the limit applies to this node.
api.keygen.sh unreachableStarts if the cache holds a valid answer less than 24 hours old. Refuses otherwise.Keeps serving for 24 hours after the last verified answer. Then /ready returns 503, and the process exits with status 3 no sooner than three hours later.

A refused start exits with status 1. A key issued for a different environment is reported as not found.

The 24-hour offline allowance is measured from the time on the licence service's last signed answer, so a restart during an outage continues it and does not start a new one. If the licence is reinstated, or api.keygen.sh becomes reachable again, before the node exits, the node returns to service without a restart.

A 503 from /ready removes the node from a load balancer that checks readiness. Clients that connect to the node directly continue to be served until the process exits.

Note

An attestation cached by v3.3.0-beta.4 is not accepted by v3.3.0 or later, so the first start after that upgrade needs api.keygen.sh to be reachable.

Each node reports its licence state through the surrealdb_license_* gauges on /metrics. An anonymous scrape does not return them. See Licence metrics.

Before the node is ready, its HTTP listener is not open, so a refused start shows only in the exit status and the log. The log message names the cause, for example a missing key or an expired licence.

Was this page helpful?

Last updated