Documentation
Installing Jointbox on Ubuntu, activating a licence, and what to do when something does not look right.
Installing
Jointbox installs on a clean Ubuntu 22.04 or 24.04 server. The installer sets up PostgreSQL, FreeRADIUS, the backend, the web panel and the licence agent, and tunes PostgreSQL to the RAM it finds.
sudo bash install.sh
Run it on a server you are prepared to dedicate to Jointbox. It configures system services and a database cluster; it is not designed to share a box with an existing PostgreSQL or web stack.
Activating
The installer offers to activate at the end. If you skipped that, or you are adding a licence to an existing install:
sudo jointbox-licensed -activate JBX-XXXXX-XXXXX-XXXXX-XXXXX \ -company "Your ISP" -email "you@example.com" sudo systemctl restart jointbox-licensed jointbox-licensed -status
Pass trial in place of a key for a 24-hour trial. The company and
email are optional, but they are what support sees against your activation.
The agent stores a signed licence on disk and renews it in the background about every six hours. Renewal continues for as long as your account is paid up, so an active customer never has to think about this again.
Licence states
Your panel shows the current state under Licence.
| State | What it means | What still works |
|---|---|---|
| ACTIVE | Normal. | Everything. |
| GRACE | Expired, inside the grace period. Renewal is being retried. | Everything. |
| EXPIRED | Past the grace period. | Reading, reports, payment collection, and all RADIUS. Creating and changing records is blocked. |
| HARDWARE_MISMATCH | This licence was activated on a different machine. | Same as EXPIRED. See Moving server. |
| UNLICENSED | No licence has been installed on this server yet. | Same as EXPIRED. |
| UNAVAILABLE | The licence agent is not running. | Everything. Nothing is blocked. |
Licensing never takes subscribers offline.
FreeRADIUS reads the database directly and never asks the panel for permission. Authentication, accounting, CoA, disconnects and bandwidth control run in every state on this page, including EXPIRED. Payment gateway callbacks stay open too — otherwise an expired customer could not pay to renew.
UNAVAILABLE is our problem, not yours.
If the agent is missing or stopped, the panel treats the installation as licensed and blocks nothing. A licensing system that takes an ISP offline because our service crashed would be worse than one that occasionally lets an unlicensed panel keep working. Your licence will still lapse on its own if the agent stays down, because it cannot renew — so it is worth fixing, but it is not an emergency.
Subscriber caps
Each plan covers a number of subscribers, counted across the whole installation including every reseller. What happens at the limit is set on your licence, not in the software:
- Warn — the panel shows a banner; nothing is refused.
- Block — creating a new subscriber past the cap is refused.
- Overage — refused a set percentage above the cap, so you are never stopped dead mid-onboarding.
In every case, existing subscribers are untouched. Nobody is disconnected, nothing is suspended, and RADIUS carries on exactly as before. The only thing affected is creating new records.
Moving to another server
A licence is tied to the hardware it was activated on. Migrating, changing a
motherboard, or cloning a VM will produce HARDWARE_MISMATCH on the
new machine.
Contact support to release the old activation, then activate normally on the new server. There is a limit on how many times a licence can be moved in a year, so releases are handled by a person rather than automatically.
Cloning a VM does not clone its activation.
If you clone a running Jointbox server, the clone has a different hardware fingerprint and will not be licensed. Running two panels from one licence is not something to plan around — each server needs its own.
Troubleshooting
jointbox-licensed: command not found
The agent is not installed. Install it, then activate:
cd /opt/jointbox sudo bash scripts/install-licence-agent.sh
"Licence agent: could not download"
The server could not fetch the agent binary. Check the machine can reach this site at all:
curl -sI https://panel.jointbox.net/api/v1/version.php
If that works but the install still fails, the download itself is the problem — tell support, because it is on our side, not yours.
The panel says the agent is not running
sudo systemctl status jointbox-licensed sudo systemctl restart jointbox-licensed journalctl -u jointbox-licensed -n 50 --no-pager
Nothing is blocked while this is true, but your licence cannot renew.
Which server am I looking at?
Support will ask for this. It contains no subscriber data.
jointbox-licensed -fingerprint
Force a renewal check now
Useful right after a payment, instead of waiting for the next cycle.
sudo jointbox-licensed -once jointbox-licensed -status
Updating
Updates are pulled and rebuilt in place. Your data and configuration are left alone.
cd /opt/jointbox sudo bash update-jointbox.sh
If an update stops on a database migration error, do not re-run it repeatedly — send support the message. A failed migration leaves a marker that has to be cleared deliberately, and guessing at it can lose data.