Sharing one licence between installations
If you run several separate DartRelay installations, for example one per site or per school, they can all draw their Relay Seats from a single licence. This page explains when to use licence sharing, how to set it up, and what happens when an installation cannot reach the licence holder.
When to use licence sharing
There are three ways to run more than one DartRelay server, and only one of them needs this page:
| Shape | Database | How it is licensed |
|---|---|---|
| One server | Its own | Activated with a product key. See Licensing and Relay Seats. |
| A pool of servers behind a load balancer | One database shared by every server | Activated once; the other servers read the licence from the shared database. See Running several servers (pools). |
| Separate installations | Each has its own | One installation holds the product key and shares it; the others enrol with it. This page. |
Choose licence sharing when the installations are genuinely separate: different databases, often different domains or network segments, perhaps administered by different people, but bought under one licence. There is no separate licence-server product to install. Any installation can share its licence.
The words used on this page
- Licence holder: the installation activated with the product key, which switches sharing on.
- Enrolled installation: an installation that takes its seats from the licence holder.
- Enrolment token: a one-time code the licence holder issues so one installation can enrol.
How it works
Every Relay Seat in the shared pool is counted in one place, on the licence holder. When a device on an enrolled installation starts its first session, the enrolled installation asks the licence holder for a seat; when the device's last session ends, it gives the seat back. Every 30 seconds each enrolled installation also reports the full list of devices holding seats on it, so a lost message corrects itself quickly.
All of this travels over the licence holder's ordinary web address and port, the same one its portal uses. You do not need to open any other port between sites.
The seat rule is the same everywhere: a Relay Seat is one device with a live session. A licence for 100 seats means 100 devices at once across all the installations together.
Before you begin
- The licence holder must be activated with a valid licence. See Activating your licence.
- Each enrolled installation must be able to reach the licence holder's web address.
- Use HTTPS with a certificate the enrolled installation trusts whenever the network between them is not fully trusted. The enrolment token is a secret; over an untrusted connection, whatever answers could capture it. See Endpoints and certificates.
- If you would rather expose a separate port only for licensing, add an endpoint for it on the licence holder's Endpoints page and give the enrolled installations that address.
Step 1: switch sharing on at the licence holder
- Open the Activation page on the licence holder. In its console, go to System → Activation.
- Find the Share this licence card. Sharing is off by default. While it is off, the licence holder refuses every enrolment and nothing else changes.
- Switch sharing on. The card now shows Add an installation, the list of installations and the pool totals.
- Click Add an installation. An enrolment token appears: six groups of eight characters.
- Copy all six groups. The token is shown once only, can be used once, and expires after 24 hours. The last two groups identify the licence holder, and the enrolling installation checks them, so copy the whole token; a shortened one is refused.
Issue a separate token for each installation you want to enrol.
Step 2: enrol the other installation
There are three places to enrol, and they do the same thing. Pick whichever fits the moment.
While installing
- Run the installer on the new server. When it asks how the server is licensed, choose A separate installation that uses another installation's licence ("This server has its own database, but its seats come from another installation").
- Enter the licence holder's address and the enrolment token. The installer checks the token with the licence holder before installing anything, and tells you if it would be refused. Checking does not use the token up.
- Finish the installation. Enrolment completes by itself when DartRelay first starts.
On an installation that is already running
- Open the Activation page on that installation. Go to System → Activation.
- Use Use the licence of another installation. Enter the licence holder's address and the token, then click Enrol.
This means an installation that was first set up with its own key can be converted later without reinstalling.
In the setup wizard
The setup wizard's licence step offers the same choice.
If you changed the database in the wizard's previous step, enrol again from System → Activation once the wizard has finished. The wizard enrols into whichever database is live at that moment.
What you should see
Within about a minute, the enrolled installation's Activation page says Licensed by another installation, and the licence holder lists it with the status Reporting.
Watching and managing the shared pool
On the licence holder, the Share this licence card shows every enrolled installation and the whole pool.
| Column | What it shows |
|---|---|
| Name / Machine | Which installation and which server it is on. |
| Version | The DartRelay version it runs. |
| Last contact | When it last reported. An installation silent for more than five minutes stops counting towards the pool and runs on its own offline allowance (see below). |
| Devices now | Devices holding a seat on it at the moment. |
| 7-day peak | The highest number of its devices at once over the last seven days. |
| Offline allowance | How many devices it may admit while it cannot reach the licence holder. |
| Revoke | Stops the installation taking seats from this licence. |
The pool line adds it up: seats in use on the licence holder, plus seats on the others, against the number licensed and any Extra. When the pool is full, a launch on any installation is refused with the pool numbers.
Each installation's own System → Seats page lists the devices on that installation. See Seeing who holds a seat.
When an installation cannot reach the licence holder
Network links between sites fail. Licence sharing is designed so that a short outage does not stop people working, while a long one cannot be used to run without a licence.
Each report the licence holder answers comes back with a signed permit that the enrolled installation keeps. While the licence holder cannot be reached:
- Devices that already hold a seat keep working and can open more applications.
- New devices are admitted up to the offline allowance. The allowance is the installation's 7-day peak plus 10%, rounded up, with a minimum of 5, and never more than the licence allows.
- This lasts for the licence's Grace period, 3 days unless your licence sets another number, counted from the last successful report.
- After Grace ends, new launches are refused with a message saying why and since when. Open sessions are never cut.
About ten minutes into an outage, the enrolled installation's console shows the licence strip, naming the licence holder, when it was last reached, the device allowance and the date new launches will stop. When the link returns, the first report tells the licence holder about every device admitted in the meantime, and the strip clears within 30 seconds.
The permit is signed by the licence holder, so editing the enrolled installation's database does not extend it, and nor does setting the server clock back.
A district runs a licence holder at head office and an enrolled installation at each of five schools. One school's link to head office fails on a Thursday afternoon. That school's highest use over the past week was 40 devices, so its allowance is 44. Lessons carry on: the 40 pupils already working continue, and up to four more devices can start. If the link were still down after three days, new devices at that school would be refused until it returned, but nobody already working would be disconnected.
Revoking an installation, or stopping sharing
Click Revoke beside an installation to stop it using the licence. Revoking takes effect the next time that installation contacts the licence holder, normally within 30 seconds:
- no new session can start there, not even on a device that already has one;
- sessions already open continue until they end;
- the installation's console shows that it was refused, and why.
The same happens to every enrolled installation if you switch sharing off on the licence holder, or if the licence holder's own licence lapses. These are decisions rather than outages, so the offline allowance does not apply.
To bring a revoked installation back, issue a new token and enrol it again.
Renewals and expiry
The licence holder includes its licence's expiry date in every permit, so enrolled installations show the same expiry warning as the licence holder. Renew on the licence holder; the enrolled installations follow within a report or two. See The licence strip.
A licence holder that is itself a pool
The licence holder can be a pool of DartRelay servers on a shared database. Any server in that pool can answer the enrolled installations, so the licence holder is as available as the pool is. Give the enrolled installations the pool's load-balanced address. See Running several servers (pools).
If something goes wrong
The installer or Activation page refuses the token
Tokens are single-use and last 24 hours. Check that all six groups were copied, that sharing is still on at the licence holder, and that the address is right. Issue a fresh token if in doubt.
The enrolled installation never shows "Licensed by another installation"
Check that the server can reach the licence holder's address and port, and that any firewall between sites allows it. If it enrolled during the setup wizard straight after a database change, enrol again from System → Activation.
The strip says the installation is running on grace
The enrolled installation has not reached the licence holder for at least ten minutes. Check the network path and that the licence holder is running. Users already working are unaffected; new devices are limited to the offline allowance until the link returns.
Launches are refused everywhere with the pool numbers
The shared pool is full. Look at the Share this licence card to see which installation is using the seats, then at that installation's System → Seats page.
An installation says it was refused
It has been revoked, sharing has been switched off, or the licence holder's own licence has lapsed. Check the licence holder's Activation page.
Related pages
Licensing and Relay Seats
What a seat is and how to activate.
Running several servers
Pools on a shared database.
Endpoints and certificates
Add a port and a trusted certificate.
Installing DartRelay
The installer and its licensing question.