Get started
Connect Proxmox
Each Nebla location is one Proxmox VE cluster or standalone node, reached through an API token. Nebla never uses SSH and leaves nothing running on the host. Setup runs once per cluster, in a root shell on any node. Proxmox VE 8 and 9 are supported.
One-line setup
In the admin area, open Locations and choose Connect a location. Enter a name and choose Get setup command. The page shows one command:
curl -fsSL 'https://panel.example.com/v1/enroll.sh' | NEBLA_TOKEN=nbe_... bash
Run it as root on any node of the cluster. The command works once and is valid for 30 minutes. Choose New command for another. You can read the script first at /v1/enroll.sh on your panel. It is plain text.
The script refuses to run without root or on anything other than Proxmox VE 8 or 9. It checks with the panel before it changes anything, then:
- creates or resets the roles
NeblaandNeblaISOwith the exact privileges Nebla needs for your Proxmox version, - creates the user
nebla@pveif it is missing, - grants
Neblaon/, andNeblaISOon every storage that holds ISOs, imports or disk images, - creates a new API token named
nebla@pve!nebla-<location>-<6 chars>, with privilege separation off, - reports the token, the certificate fingerprint of every node, and the cluster's storages back to the panel.
It writes no files. A re-run resets both roles to the exact privilege list, so privileges you added to them by hand are removed.
Finish in the panel
The enrollment page picks up the report. You then have 24 hours to finish. Choose:
- the Proxmox URL, prefilled from the node's IP on port 8006,
- the disk storage for server disks (one with
imagescontent), - the ISO storage for Nebla's cloud-init seed ISOs,
- optionally an import storage, which turns on built-in OS images (Proxmox VE 8.4 or later),
- optionally a volume storage. Left empty, volumes go to each node's disk storage.
Nebla connects to the URL, checks that the certificate it sees is one the node reported, and pins it.
The script granted NeblaISO on every candidate storage because it didn't know which ones you would pick. After you finish, the page lists optional commands that remove it from the storages the location doesn't use.
If the node can't reach the panel
Open The node can't reach this panel? on the enrollment page. It gives a script that makes no network calls. Run it on the node. It prints one line that starts with nebla-enroll:v1:. Paste that line into the page. The line contains the token secret, so clear your terminal scrollback afterwards. The online script prints the same line when it can't send its report.
Run setup again
Use Re-run setup on the location page after a certificate renewal, or to rotate the token. The old token keeps working until you finish. The location then switches to the new token and fingerprints, and the page shows the command that removes the old token:
pveum user token remove nebla@pve <old token>
Turn on the datacenter firewall
Nebla turns on the VM firewall for every server, with IP and MAC filtering so a server can't use addresses it wasn't given. User firewalls also live in each VM's firewall rules. Proxmox only applies any of this when the firewall is on at the datacenter level:
Datacenter > Firewall > Options > Firewall: Yes
Datacenter rules govern traffic to the Proxmox hosts, not to the VMs. Before you turn it on, check that those rules still allow your own SSH and web UI access on port 8006. The location page warns while the datacenter firewall is off.
Storages
| Storage | Content type | Used for |
|---|---|---|
| Disk storage | images | Server disks, for example local-lvm, a ZFS pool or Ceph RBD. |
| ISO storage | iso | The small cloud-init seed ISO Nebla uploads for each server, for example local. |
| Import storage | import | Downloads for built-in OS images. Optional, needs Proxmox VE 8.4 or later. |
| Volume storage | images | Volumes. Optional, defaults to each node's disk storage. |
To add a content type to an existing directory storage, list the types it already has plus the new one:
pvesm set local --content iso,vztmpl,backup,import
Built-in OS images also need outbound HTTPS from each node to the image's download site, and from the panel to look up the newest image and its checksum.
Manual setup
Use this if you can't run the setup script. In a root shell on any node:
# Proxmox VE 9. On VE 8, replace VM.GuestAgent.Audit with VM.Monitor.
pveum role add Nebla --privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Disk VM.Config.Memory VM.Config.Network VM.Config.Options VM.Config.Cloudinit VM.PowerMgmt VM.Console VM.Audit VM.GuestAgent.Audit Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit Sys.Audit SDN.Use"
# Only for built-in OS images:
pveum role modify Nebla --append 1 --privs "Sys.AccessNetwork VM.Config.HWType"
pveum role add NeblaISO --privs "Datastore.Allocate Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit"
pveum user add nebla@pve --comment "Nebla panel"
pveum aclmod / --users nebla@pve --roles Nebla
pveum aclmod /storage/<iso_storage> --users nebla@pve --roles NeblaISO
pveum aclmod /storage/<import_storage> --users nebla@pve --roles NeblaISO
pveum aclmod /storage/<volume_storage> --users nebla@pve --roles NeblaISO
pveum user token add nebla@pve panel --privsep 0
Skip the image, import or volume lines for features you don't use. Proxmox versions without Sys.AccessNetwork need Sys.Modify on / for built-in OS images instead. The last command prints the token secret once. The token ID is nebla@pve!panel.
NeblaISO carries Datastore.Allocate, which Proxmox requires before it deletes an ISO or a volume. It also lets the token delete any other volume on that storage, so grant it only on the storages listed above, never on /.
Then read the TLS fingerprint of the node your location URL points at:
pvenode cert info
Use the fingerprint of the certificate pveproxy serves: pveproxy-ssl.pem if you uploaded one or use ACME, otherwise pve-ssl.pem. In the panel, choose Connect a location, then Connect manually, and enter the URL, token ID nebla@pve!panel, secret, fingerprint and storages.
The Proxmox setup reference explains every privilege and covers hand-built cloud-init templates.
What Nebla touches
Nebla tags the VMs it creates nebla and nb-srv-<id>, and the templates it builds from built-in OS images nebla-tpl. It only ever changes VMs with one of those tags, so your existing VMs are left alone.
- Run one Nebla install per Proxmox cluster.
- Before reinstalling Nebla with a fresh database, remove the VMs tagged
nebla, because the new install reuses server IDs. - Never create a VM with ID 999999999. Nebla uses that ID as the owner of volume disks.
Remove Nebla from Proxmox
pveum user delete nebla@pve
pveum role delete Nebla
pveum role delete NeblaISO
Deleting the user removes its tokens and ACLs.