Servers API

Whether the team has a MaxMind GeoLite2 account on file

The licence key is write-only. serversUsing counts the team's servers that currently use the MaxMind source.

Store the team's MaxMind account ID and licence key

The key is sealed with the instance secret key. Servers on the MaxMind source receive it with their next reconcile (sent immediately to online agents, never persisted in a command).

Remove the team's MaxMind account

Refused with 409 maxmind_in_use while a server still uses the MaxMind source.

Control-plane version, agent version skew per server and the pre-upgrade backup

The version the control plane runs, whether agents behind it upgrade themselves when they connect, the outcome of the backup the control plane took before its last upgrade, and for every server how its agent's version compares (behind, current, ahead, unknown), whether it can be upgraded now (and if not, why) and the state of its latest upgrade.

Switch the automatic agent upgrade

Needs the servers:write scope and the instance admin (the first account). Audited.

List servers

Get a server

Update a server's name, host settings, retention or alert settings

Upgrade one server's agent to the control plane's version

The agent downloads the binary from this control plane, checks its SHA-256 against the one in the command, replaces itself, restarts when its running work is done and rolls back if the new binary does not start. Needs the Owner or Admin role; audited. 409 server_offline, agent_current, agent_newer or upgrade_in_progress; 422 agent_predates_upgrade (re-run the agent installer once) or no_agent_binary.

Docker cleanup settings and history of a server

Whether the scheduled cleanup is on, when it runs next and the most recent runs with what each prune step removed. A cleanup removes dangling images, unused images older than unusedImageMinAgeHours (default 72), build cache older than buildCacheMinAgeDays (default 7) and unused NebulaCtrl networks, and optionally stopped containers NebulaCtrl does not manage. It never removes the current or a rollback-eligible release's image, a pinned infrastructure image, or any volume.

Change the Docker cleanup settings of a server

Needs the servers:write scope. cron sets the schedule (UTC), unusedImageMinAgeHours and buildCacheMinAgeDays the age limits and diskTriggerPercent the disk usage that starts an emergency run (omitted or 0: the server's disk alert threshold); omitted or 0 keeps each default. Turning the schedule off also turns off the emergency run; "Run cleanup now" still works. 422 validation_failed for a bad cron expression (or one that fires more often than every 15 minutes) or an out-of-range value.

Run the Docker cleanup of a server now

Queues the same cleanup the schedule runs. The result (reclaimed bytes, items per step) appears in the server's cleanup history. 409 server_offline when the server is offline, 409 cleanup_running while one is in flight.

Remove unused Docker volumes of a server

Removes volumes that no container (running or stopped) mounts and that NebulaCtrl does not manage: anonymous volumes and volumes made outside NebulaCtrl. Volumes of NebulaCtrl services (nc-vol-*, or labeled as managed) are never removed. This deletes data and cannot be undone: confirm must be the server's name. The schedule never does this.

Host hardening of a server: the Lynis index, the safe fixes and what is left

The Security tab: Lynis's hardening index from the latest audit, every curated safe fix with its state on the host (applied, already compliant, pending, unavailable), the findings that remain with an explanation and the commands to deal with them, and the history of runs. NebulaCtrl never offers a fix for SSH, the firewall or accounts.

Switch the weekly Lynis audit of a server

Needs the servers:write scope and the Owner or Admin role. Audited.

Apply safe hardening fixes

Applies the selected fixes (the default set when none is selected), checks each one and undoes it by itself if it did not take effect, then audits again so the new index is known. Each fix is reversible with the rollback endpoint. Never changes SSH, the firewall or accounts. Needs the Owner or Admin role; audited.

Audit the host with Lynis now

Queues a Lynis audit on the server. It only reads the host. With installLynis, the agent first installs Lynis (from CISOfy's repository, else the distribution's). Needs the Owner or Admin role. 409 server_offline when the server is offline, 409 hardening_running while a run is in flight.

Undo safe hardening fixes

Restores what NebulaCtrl changed for the selected fixes: the previous sysctl values, file modes, login.defs lines and banners. A fix NebulaCtrl did not apply is left alone. Needs the Owner or Admin role; audited.

Mesh node of a server

Whether the server joined the mesh, its node (state, tailnet addresses, peers, exposed services) and the link nodes that run on it.

Turn the mesh on or off for a server

Enabling adds one tagged device to the team's tailnet (it may be billed by Tailscale) and needs acceptMeshChanges; with ?dryRun=true it returns the plan instead (devices added, whether the host has /dev/net/tun, warnings and blockers). Disabling is refused (409 mesh_server_in_use) while replicas or cross-server links use the server's node. The node key is minted when the command is sent and never stored.

Test the mesh connectivity of a server

The agent checks whether the server's node reaches the other servers' nodes (connected, refused, timeout, no_path). This is the ground truth for advisory ACL modes.

Re-provision the mesh node of a server

Deletes the node's device from the tailnet and re-creates it with a fresh single-use key and a fresh state volume. The node gets a new tailnet IP and the access rules regenerate. Use it when the node needs attention.

Pending OS updates and reboot-required of a server

The Updates panel: how many packages are waiting (and how many are security updates), whether the host asks for a reboot, the pending packages with a warning where an upgrade is risky, the production services that run on the server, and the recent runs. The agent checks every server about every 6 hours; known is false until the first check completes.

Upgrade the server's packages

Runs apt-get upgrade or dnf upgrade (security updates only with securityOnly) on the host as root, keeping the configuration files you changed, then checks again. The upgrade runs detached on the host, so it finishes even when Docker restarts. Never reboots. Instance admin only; confirm must be the server's name; a server that runs production services or the control plane also needs acknowledgeProduction (422 production_ack_required), and a token that asks for production approvals gets 409 approval_required. Needs a completed check first (409 no_check_yet). Audited.

Check the server for updates now

Refreshes the package lists on the host and records the pending updates and reboot-required. Changes no package. Needs the Owner or Admin role. 409 server_offline when the server is offline, 409 patching_running while a run is in flight.

What an upgrade of the server would do

The plan shown before the confirmation: the packages that would be upgraded, the risky ones among them and why, whether a reboot will probably be needed, whether Docker restarts, the production services on the server and what the apply request must carry (the server's name, and acknowledgeProduction when requiresAcknowledgement). Changes nothing.

Reboot the server

Schedules a reboot of the host a few seconds ahead. Every service on the server goes down until it boots and Docker starts them again. The run stays rebooting until the agent reconnects on a new boot (it fails after 20 minutes). Instance admin only; confirm must be the server's name; a server that runs production services or the control plane also needs acknowledgeProduction. Audited.

One check, upgrade or reboot of a server, with the upgrade's log

The log is the tail of what the package manager printed. A run in rebooting waits for the agent to reconnect on a new boot.

Revoke a server's agent

Revokes the agent identity and pending enrollment tokens, cancels commands that were never delivered (their deployments fail with "Server revoked. No changes were made.") and disconnects the agent. Containers already running on the host are left untouched.

Cloudflare Tunnel state of a server

Whether the server has a Cloudflare Tunnel, the connector's observed state and the ingress sync. A server without a tunnel answers state: off and says whether one can be enabled.

Enable a Cloudflare Tunnel on a server

Creates a remotely-managed tunnel with the team's Cloudflare connection, pushes its ingress rules (every hostname of the server's services to the proxy, then a 404 catch-all) and tells the agent to run the cloudflared connector. The connector token is fetched when the command is sent and is never stored. Once the connector connects, the server's domains in connected zones point at the tunnel and ports 80 and 443 may stay closed. Needs the servers:write and proxy:write scopes. The Cloudflare token needs the permission Account, Cloudflare Tunnel, Edit (422 cloudflare_tunnel_forbidden).

Disable the Cloudflare Tunnel of a server

Points the server's domains back at its public IP, removes the connector and deletes the tunnel at Cloudflare shortly afterwards. Disabling a tunnel that is already being removed retries the delete. Ports 80 and 443 must be reachable again before the DNS change propagates.

Re-sync the Cloudflare Tunnel of a server

Re-pushes the ingress rules and re-sends the connector command (creating the container again when it is gone). Use it when the connector needs attention.

The Unrestricted switch and Compose availability of a server

Make a server unrestricted, or restricted again

By default Compose stacks and services run under safe allow-lists: no privileged mode, host network, host PID namespace, devices, GPUs, custom runtime, unconfined seccomp or AppArmor, NET_ADMIN or SYS_ADMIN, Docker socket or host bind mounts. An unrestricted server lifts them for everything on it, so anyone who can deploy there can take over the server. Instance admin only; enabling needs confirm to equal the server's name. Audited as server.unrestricted.enable or .disable. Disabling does not touch running containers: the next deploy, rollback or reconcile of a stack or service that needs the lifted rules fails until it is edited or moved.

Upgrade agents one server at a time (staged)

Upgrades the given servers (every server whose agent can be upgraded now when none are given) in name order. Each upgrade must be confirmed by the agent reconnecting with the new version before the next one starts; the first failure stops the rollout and leaves the remaining servers untouched. Needs the Owner or Admin role; audited. 409 nothing_to_upgrade when no agent qualifies.

Create a pending server and a one-time enrollment token

The token is valid for one hour and can enroll exactly one agent. It is returned only in this response (and in an idempotent replay of it).