The panel and its nodes trust each other through the panel's own certificate authority. Enrolment gives a node its certificate; from then on every call between them is mutual TLS, pinned to that certificate. The node's private key is made on the node and never leaves it.
The enrolment token#
When you add a node, the panel gives it a one-time token: 32 random bytes, shown as 64 hex characters in the install command (VMSTACK_TOKEN=…). The token is valid for 60 minutes. After that, the node page shows Generate new command.
The installer stores the token in /etc/vmstack/enroll-token and the panel's CA in /etc/vmstack/panel-ca.pem. The agent then waits for the panel.
What happens during enrolment#
The panel tries to enrol every pending node in the background, so you do not need to click anything after running the command.
- The panel connects to the agent and sends a random challenge.
- The agent answers with a certificate request for its key and a proof made with the token. The token itself is never sent.
- The panel checks that the request is for the very key the agent used in the TLS handshake and that the proof matches the token.
- The panel signs a certificate and the agent installs it. The token is discarded; the node turns Online and is polled.
Every step that fails is recorded in System › Audit log as node.enrollment_failed with the reason (for example key_mismatch, bad_proof, already_enrolled_elsewhere). A node whose agent is not answering yet simply stays pending.
If the agent refuses to enrol because of the licence (it was installed with --licensing enforce, or was licensed before, and has no valid licence from this panel), the Install the agent panel says so. The panel keeps trying and sends its licence each time. See Licensing.
The node's certificate#
The node's Overview has a Certificate panel:
| Row | Meaning |
|---|---|
| Fingerprint | SHA-256 of the certificate, shortened; the copy button copies all of it |
| Issued, Expires | Dates. Within 14 days of expiry it is shown as a fault with the days left |
| Identity | node-<id>.nodes.vmstack.invalid, the name the panel checks. address only for a certificate issued before identity names, which is renewed at the next chance |
| Renewal | when it is renewed automatically, whether a renewal is under way, or the last error |
Certificates are valid for one year. Each carries the node's identity name and its address. The panel connects to the address but checks the certificate against the identity name, and accepts only certificates its own CA signed.
Automatic renewal#
The panel renews a node's certificate before it expires, over the existing mutual-TLS channel:
- A certificate is due when a third of its lifetime or less is left (about four months for a one-year certificate).
- The scheduler runs
php artisan vmstack:renew-node-certificatesevery 5 minutes. A renewal under way is continued at once; other due nodes are tried at most once every 6 hours. - Each renewal makes a new key on the node. The node switches to the new certificate for new connections; open connections, such as a console, keep theirs.
- The node keeps the previous key and certificate until the panel confirms it reached the node with the new one. Without a confirmation within 30 minutes the node goes back to the previous pair by itself.
Running servers and open consoles are not affected by a renewal.
Renew now#
To renew one node at once: on its Overview, in the Certificate panel, click Renew now and confirm. The panel shows Renewal queued. and the new fingerprint when it is done. From the command line:
php artisan vmstack:renew-node-certificates --node=<node-id> --force
<node-id> is the number in the node page's URL.
Alerts#
php artisan vmstack:check-certificates runs daily. It raises a certificate alert for a node certificate that expires within 14 days, for the panel's own client certificate within 14 days, and for the CA within 365 days. The mail event is in the group "Certificates expiring or failing to renew". See Alerts.
The panel's client certificate (the one it presents to nodes) renews itself daily when 30 days or less are left.
When a certificate has expired#
The panel cannot renew a certificate it cannot connect with. An expired node certificate shows expired in the Certificate panel and the node cannot be reached until it is enrolled again. Follow Enrol a node again. The automatic renewal months ahead and the alerts are there so this never happens.
Enrol a node again#
Use this when a node's certificate expired, the node was reinstalled, or its key was lost.
-
On the node's page, click Enroll again and confirm. The node goes back to pending and its certificate is revoked. The panel cannot poll it or give it tasks until it is enrolled again.
-
Copy the new install command the node page shows.
-
Run it on the node with
--forceadded at the end:curl -fsSL '…/install.sh' | VMSTACK_TOKEN=<token> bash -s -- --ca <…> --agent-url '…' --port 8443 --force--forcemakes the installer discard the old enrolment and key. Without it the installer stops with "this node is already enrolled". -
Wait for the node to turn Online.
The node's servers keep running throughout; only their controls are unavailable until the node is enrolled again. A node enrolled before does not need a new licence slot when it is enrolled again.