---
title: Proxmox VE
description: Aggiungi cluster Proxmox VE come origine VM: token API a privilegi minimi, storage, template di immagini cloud, pool IP, blocco TLS e origine per piano.
url: https://nexcmp.com/it/docs/infrastructure/proxmox/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Proxmox VE

> **Dove nel pannello di amministrazione:** Infrastructure › Cloud provider › Providers (`/infra/providers`), quindi la pagina del provider (`/infra/providers/<id>`) con le schede Overview, Clusters, VMs, Servers e Credentials. I piani si impostano in Services › Virtual Machines › Plans & pricing (`/vm/catalog`).

## Descrizione {#what-it-does}

NexCMP può vendere macchine virtuali eseguite su uno o più cluster Proxmox VE, in affiancamento o in sostituzione di CloudStack. Una VM viene creata clonando un template OS con clone completo, quindi configurata tramite cloud-init: dimensioni, indirizzo IP da un pool definito dall'utente, password di root e chiave SSH. I clienti ottengono il controllo dell'alimentazione, la console, gli snapshot, la reinstallazione, il reset della password e le metriche nel portale. Non vedono mai il cluster, il nodo o il nome dell'origine.

Usalo quando utilizzi già Proxmox VE o per offrire un secondo pool di VM con prezzi differenti.

## Requisiti {#requirements}

| Elemento | Requisito |
|---|---|
| Proxmox VE | PVE 9.x. L'integrazione è stata verificata sulla 9.2. Richiede il contenuto storage `import` e l'opzione disco `import-from` (PVE 8.2 o versioni successive). |
| Rete dal pannello | HTTPS verso l'API del cluster, `https://<host or IP>:8006`. Nessun percorso, nome utente o query. Sia il pannello che il worker si connettono; la console del browser viene inoltrata tramite proxy attraverso il pannello. |
| Account | Un utente PVE dedicato con un **API token** e un ruolo personalizzato con i privilegi elencati di seguito. Non usare mai `root@pam`. |
| Storage | Uno storage per i dischi delle VM che supporta i clone (ad esempio `local-lvm`). Per il generatore di template integrato, lo storage denominato `local` con i tipi di contenuto `import` e `snippets`. |
| Rete | Un bridge Linux (ad esempio `vmbr0`) che raggiunge la rete in cui risiedono gli IP dei clienti. Usa un bridge compatibile con le VLAN se inserisci un tag VLAN. |
| IP | Un blocco IPv4 (da /16 a /30) instradato verso quel bridge, con un gateway. NexCMP assegna gli indirizzi in autonomia; Proxmox non dispone di una gestione degli IP. |
| Template | Una VM template cloud-init per ciascun OS, su ogni nodo su cui effettui il deployment, con il guest agent QEMU. |
| Zona | Una zona esistente a cui collegare il cluster. Vedi [Zones](https://nexcmp.com/it/docs/infrastructure/zones/). |
| Dipende da | Nessuno. |

## Prepara l'infrastruttura {#prepare-the-infrastructure}

Esegui i comandi come root su qualsiasi nodo del cluster.

### 1. Crea un ruolo, un utente e un API token con privilegi minimi {#_1-create-a-least-privilege-role-user-and-api-token}

1. Crea il ruolo. L'elenco dei privilegi corrisponde esattamente a ciò che utilizza NexCMP; non contiene nulla che modifichi utenti, definizioni di storage o il datacenter.

   ```bash
   pveum role add NexCMP -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.PowerMgmt VM.Audit VM.Console VM.Snapshot VM.Snapshot.Rollback VM.Backup VM.GuestAgent.Audit VM.GuestAgent.Unrestricted Datastore.Audit Datastore.AllocateSpace Datastore.AllocateTemplate Sys.Audit Sys.AccessNetwork SDN.Use SDN.Audit Pool.Audit Mapping.Audit Mapping.Use"
   ```

   `Sys.AccessNetwork` è richiesto per il download dell'immagine cloud. PVE 9 non dispone del privilegio `VM.Monitor`; non aggiungerlo.

2. Crea l'utente e un token. `--privsep 1` significa che i diritti del token corrispondono all'**intersezione** tra i permessi dell'utente e quelli propri del token.

   ```bash
   pveum user add nexcmp@pve --comment "NexCMP"
   pveum user token add nexcmp@pve api --privsep 1
   ```

   Il comando stampa il token **secret una sola volta** (un UUID). Copialo adesso. L'ID del token è `nexcmp@pve!api`.

3. Assegna il ruolo **sia** all'utente che al token. Questo è il passaggio che spesso si dimentica: con la separazione dei privilegi, solo il token riceve errori 403 come `Datastore.Audit` se l'utente non ha i permessi.

   ```bash
   pveum acl modify / --roles NexCMP --users nexcmp@pve
   pveum acl modify / --roles NexCMP --tokens 'nexcmp@pve!api'
   ```

4. Verificalo dal server del pannello:

   ```bash
   curl -sk -H 'Authorization: PVEAPIToken=nexcmp@pve!api=<secret>' https://192.0.2.10:8006/api2/json/version
   ```

   Un documento JSON con un `version` indica che il token funziona. (`-k` serve solo per questa verifica rapida; NexCMP memorizza il certificato autonomamente, vedi sotto.)

### 2. Controlla il bridge e lo storage {#_2-check-the-bridge-and-the-storage}

```bash
pvesm status          # storages, type, content and free space
ip -br link show type bridge
```

- Le VM dei clienti ricevono `virtio` interfacce di rete sul bridge inserito in NexCMP. Se configuri una VLAN, il bridge deve supportare le VLAN.
- Posiziona le VM dei clienti su un bridge o una VLAN **separati dall'indirizzo di gestione del nodo**. Se condividono una rete, il set di IP di gestione automatico del firewall di Proxmox apre le porte 22, 8006, 3128, 5900-5999 e 60000-60050 del nodo a ogni VM in quella rete. Se non puoi separarli, aggiungi una regola DROP esplicita per la subnet delle VM verso tali porte prima della regola ACCEPT di gestione.

### 3. Note sullo storage (LVM-thin) {#_3-storage-notes-lvm-thin}

- Lascia il **zeroing del thin-pool sui valori predefiniti**. Disattivarlo (`lvchange -Zn`) può lasciare vecchi dati nei blocchi appena allocati e corrompere le tabelle delle partizioni o i file system delle VM clonate.
- I dischi che segnalano "write cache: disabled" possono clonare a pochi MB/s. Controlla con `hdparm -W /dev/sdX` e abilita la cache di scrittura se il disco dispone di protezione contro la perdita di alimentazione.

### 4. Abilita il contenuto `import` (solo per il generatore di template integrato) {#_4-enable-the-import-content-only-for-the-built-in-template-builder}

Il generatore integrato scarica l'immagine cloud nello storage denominato `local` e crea il template da essa. Aggiungi `import` (e `snippets`) all'elenco dei contenuti di quello storage. Mantieni i tipi che usi già; `--content` sostituisce l'intero elenco:

```bash
pvesm status --storage local     # note the current content
pvesm set local --content iso,vztmpl,backup,import,snippets
```

### 5. Crea un template OS da un'immagine cloud {#_5-build-an-os-template-from-a-cloud-image}

Un template è una VM cloud-init clonata da NexCMP. Ciascuno è registrato sotto una breve **OS key** come `ubuntu-24.04` con il relativo ID della VM. Crea un template per OS **su ogni nodo che riceverà le VM**, poiché il clone viene eseguito sul nodo scelto.

**Opzione A, consigliata: crealo tu stesso.** Le immagini cloud standard di Ubuntu e Debian non contengono il guest agent e non consentono il login come root, mentre NexCMP imposta la password di root tramite cloud-init. Prepara prima l'immagine:

```bash
apt install -y libguestfs-tools
wget -O noble.qcow2 https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
virt-customize -a noble.qcow2 --install qemu-guest-agent \
  --write /etc/cloud/cloud.cfg.d/99-nexcmp.cfg:$'ssh_pwauth: true\ndisable_root: false\n' \
  --write /etc/ssh/sshd_config.d/00-nexcmp.conf:$'PermitRootLogin yes\nPasswordAuthentication yes\n'
```

Quindi crea la VM del template (l'ID 9000 è un esempio; mantieni gli ID dei template sotto il valore `vmid from`, predefinito 1000):

```bash
qm create 9000 --name tpl-ubuntu-24-04 --memory 2048 --cores 2 --cpu host --ostype l26 \
  --scsihw virtio-scsi-single --net0 virtio,bridge=vmbr0 --agent 1 --serial0 socket --vga serial0
qm set 9000 --scsi0 local-lvm:0,import-from=$PWD/noble.qcow2,discard=on,iothread=1
qm set 9000 --ide2 local-lvm:cloudinit --boot order=scsi0
qm template 9000
```

**Opzione B: il generatore integrato.** La scheda **Create OS template from cloud image** nella scheda Clusters (vedi sotto) scarica un'immagine qcow2, crea il template e lo registra. Crea la VM con cloud-init e il flag del guest agent, ma non modifica il contenuto dell'immagine. Usala solo con un'immagine che consente già il login come root e avvia il guest agent, oppure quando fornisci anche uno snippet vendor-data di cloud-init.


Il guest agent è necessario per **Reset password** e per mostrare l'indirizzo IP della VM.

### 6. Conosci l'impronta digitale del certificato (facoltativo) {#_6-know-the-certificate-fingerprint-optional}

NexCMP considera affidabile il cluster memorizzando l'impronta digitale SHA-256 del suo certificato TLS, quindi un certificato autofirmato va benissimo. Per visualizzare il valore che NexCMP memorizzerà:

```bash
openssl x509 -in /etc/pve/local/pve-ssl.pem -noout -fingerprint -sha256
```

## Collega in NexCMP {#connect-in-nexcmp}

1. Apri **Infrastructure › Cloud provider › Providers** e fai clic su **Add cloud provider**. Scegli **Proxmox VE** e compila i campi:

   | Campo | Valore di esempio |
   |---|---|
   | Name | `Proxmox cluster 1` |
   | Endpoint | `https://192.0.2.10:8006` |
   | Token id | `nexcmp@pve!api` |
   | Token secret | `XXXX` (l'UUID stampato al passaggio 1) |
   | Slug | `pve-1` (a-z, 0-9, trattino, 2-32 caratteri) |
   | Default node | `pve1` (vuoto: il nodo online con più RAM libera) |
   | Storage | `local-lvm` |
   | Bridge | `vmbr0` |

      ![Finestra di dialogo Aggiungi provider cloud con Proxmox VE selezionato ed esempi di endpoint, token e valori di storage](https://nexcmp.com/it/docs/images/infrastructure/proxmox-01-add-provider.webp)

2. Fai clic su **Save & open provider** e inserisci un motivo quando richiesto. Il token viene crittografato prima di essere memorizzato.
3. Nella scheda **Overview** fai clic su **Test connection**. Il primo test riuscito **memorizza l'impronta digitale TLS del cluster**; da quel momento in poi verrà rifiutato qualsiasi certificato differente.


4. Apri la scheda **Clusters**. La scheda **Node · storage · bridge** elenca ciò che l'API rileva; la scheda **Cluster configuration** contiene le impostazioni:

   | Campo | Significato |
   |---|---|
   | Default node | Nodo utilizzato per le nuove VM. Se vuoto, indica il nodo online con più RAM libera. |
   | Storage, Bridge, VLAN | Storage del disco, bridge NIC e tag VLAN facoltativo (0 indica nessun tag). |
   | CPU type | `host` per impostazione predefinita. Utilizza `x86-64-v2-AES` quando i nodi dispongono di generazioni di CPU differenti. |
   | vmid from | Primo ID di VM assegnato alle VM dei clienti (predefinito 1000). |
   | Storage ISO, Storage backup | Lascia vuoto a meno che tu non li utilizzi; se vuoto, le funzioni ISO e di backup non vengono offerte. |
   | Template OS | Uno per riga, `os-key=vmid`, ad esempio `ubuntu-24.04=9000`. |
   | Pinned TLS fingerprint (SHA-256) | Compilato dal primo test. Cancellalo ed esegui nuovamente il test dopo aver sostituito il certificato del cluster. |

      ![Scheda Clusters, scheda Cluster configuration con esempio di nodo, storage, bridge ed elenco di template OS](https://nexcmp.com/it/docs/images/infrastructure/proxmox-03-cluster-config.webp)

5. Facoltativo: se hai utilizzato l'Opzione B precedente, compila **Create OS template from cloud image** (chiave OS `ubuntu-24.04`, vmid `9000`, nodo `pve1`, URL dell'immagine qcow2) e fai clic su **Create template**. L'operazione viene eseguita in background per alcuni minuti; il risultato si trova nel registro di audit.

      ![Scheda Create OS template from cloud image con un esempio di URL di immagine Ubuntu](https://nexcmp.com/it/docs/images/infrastructure/proxmox-04-template-from-image.webp)

6. Fai clic su **Add pool** in **Cluster IP pool** e crea il pool da cui le VM attingono gli indirizzi:

   | Campo | Valore di esempio |
   |---|---|
   | Name | `customers-1` |
   | CIDR | `198.51.100.0/24` |
   | Gateway | `198.51.100.1` (mai assegnato a una VM) |
   | DNS | `1.1.1.1,8.8.8.8` (da 1 a 4 indirizzi IPv4) |
   | Bridge, VLAN | `vmbr0`, `0` |
   | Already used IPs | uno per riga, `ip note`, ad esempio `198.51.100.10 monitoring` |

   NexCMP non assegna mai l'indirizzo di rete, l'indirizzo di broadcast, il gateway o un indirizzo riservato. I pool dello stesso cluster non possono sovrapporsi. Un pool può essere eliminato solo quando nessuno dei suoi indirizzi è in uso.

      ![Finestra di dialogo Aggiungi pool IP con un esempio di /24 e gateway](https://nexcmp.com/it/docs/images/infrastructure/proxmox-05-ip-pool.webp)

7. In **Attach cluster to zone**, scegli la zona e, facoltativamente, il nome di un nodo, quindi fai clic su **Attach to zone**. Il cluster si unisce alla zona che già vende VM, consentendo a una zona di includere contemporaneamente CloudStack e Proxmox. La nuova risorsa **non viene venduta per impostazione predefinita** e non modifica il comportamento dei piani esistenti.

      ![Scheda Attach cluster to zone con una zona esistente selezionata](https://nexcmp.com/it/docs/images/infrastructure/proxmox-06-attach-zone.webp)

8. Apri **Services › Virtual Machines › Plans & pricing** e fai clic su **Add plan**. In **Infrastructure source** scegli il cluster Proxmox, quindi imposta CPU, RAM, disco e prezzo. Un piano Proxmox non richiede alcuna offerta CloudStack. Per vendere la stessa configurazione da entrambe le fonti, utilizza **Clone** su un piano e seleziona l'altra fonte. Il disco del piano deve essere almeno grande quanto il disco del template; Proxmox non è in grado di ridurre le dimensioni di un disco.


### Importa una VM già esistente {#import-a-vm-that-already-exists}

Apri la scheda **Servers** per elencare le macchine virtuali sul cluster. **Import** assegna una VM esistente a un account cliente senza alcun costo: non viene fatturato nulla per ore, tempo di spegnimento o traffico. Il cliente può avviare, arrestare, riavviare e aprire la console ma non può eliminarla; solo un amministratore può farlo. Durante l'importazione NexCMP legge solamente dal cluster.

- Il cluster deve essere associato a una zona **con il nome del nodo** di quella VM (lascia vuoto il nodo e le importazioni segnalano che la regione non è configurata).
- Per rendere una VM **protetta** (arresto, riavvio, reinstallazione, ripristino di snapshot, eliminazione e cambio piano vengono rifiutati), importala dalla riga di comando con `--protect`:

  ```bash
  sudo -u nexcmp /opt/nexcmp/bin/nexcmp px-import --provider pve-1 --server-ref pve1/101 --account-id 12 --hostname web-1 --protect
  ```



### Cosa è supportato e cosa non lo è su Proxmox {#what-is-and-is-not-supported-on-proxmox}

| Funzionalità | Proxmox VE |
|---|---|
| Crea, accendi/spegni/riavvia, elimina | Sì |
| Ridimensiona CPU e RAM, ingrandisci il disco | Sì, ma la VM viene arrestata, modificata e riavviata (nessun ridimensionamento a caldo) |
| Snapshots | Sì, fino a 5 per VM: crea, elenca, ripristina, elimina |
| Reinstallazione | Sì: la VM viene ricostruita dal template e mantiene il suo ID, IP e impostazioni, con una nuova password |
| Reimposta password | Sì, tramite il guest agent |
| Console | Sì, una console via browser inoltrata dal pannello |
| Metriche | Sì: CPU, memoria, rete e disco |
| Montaggio ISO, backup, firewall, IPv6, port forwarding, cambio IP, volumi extra, Auto Scaling, DDoS Shield, VPC, misurazione della banda | Non disponibile. La pagina della VM del cliente nasconde ciò che un source non può fare. |

## Verifica {#verify}

1. **Test connection** mostra OK e lo stato del provider è attivo.
2. **Clusters** elenca i tuoi nodi come online, con lo storage e il bridge.
3. **Cluster IP pool** mostra i conteggi degli indirizzi liberi, usati e trattenuti.
4. La chiave del sistema operativo compare tra i template della zona in **Services › Virtual Machines › Template** dopo che il cluster è stato collegato.
5. Ordina una VM di test da un piano che utilizza il cluster. Dovrebbe ottenere un indirizzo dal pool, una password di root e una console funzionante; il pool mostra un indirizzo utilizzato.

## Limiti e note {#limits-and-notes}

::: tip Zone a sorgente mista
A partire da NexCMP 1.4.0, il listino prezzi pubblico di Cloud Server funziona anche quando CloudStack e Proxmox VE condividono una zona. Ciascun piano utilizza la propria **Infrastructure source**. Dopo aver collegato un cluster, controlla il listino prezzi pubblico ed effettua un ordine di prova per ciascuna sorgente.
:::

- È possibile aggiungere più cluster Proxmox. Ciascuno corrisponde a un provider.
- Una zona offre un source predefinito; un piano con il proprio **Infrastructure source** viene distribuito esattamente su quel cluster, a condizione che il cluster sia attivo e si trovi nella zona del piano.
- Un cluster dietro la stessa zona di CloudStack mantiene i suoi piani legacy su CloudStack. Esegui un test d'ordine completo prima del lancio.
- Il token API può essere solo sostituito, mai visualizzato. Sostituiscilo nella scheda **Credentials**: crea prima il nuovo token in Proxmox, inseriscilo, esegui **Test connection**, quindi revoca il vecchio token.
- Le azioni Test, Sync e cluster-info sono limitate a sei chiamate al minuto per amministratore.
- NexCMP fattura ai tuoi clienti; i costi dell'hardware e delle licenze del cluster sono a tuo carico.


## Troubleshooting {#troubleshooting}

| Sintomo | Causa | Soluzione |
|---|---|---|
| Test: "Key rejected (wrong access key / secret, or revoked)" o HTTP 401/403 | ID token o secret errati, oppure l'ACL è stata assegnata solo al token | Esegui nuovamente i due comandi `pveum acl modify` (utente **e** token) e verifica che l'ID del token sia `user@realm!tokenid`. |
| Test: "Could not connect to the provider" o "Timed out" | Firewall, host o porta errati | Controlla `https://host:8006` dal server del pannello. |
| Test: "Endpoint non valido o non presente nella allowlist" | L'endpoint contiene un percorso, un utente, una query oppure non è HTTPS | Usa esattamente `https://host:8006`. |
| "il certificato TLS del cluster NON corrisponde al fingerprint associato" | Il certificato del cluster è stato sostituito | Cancella **Pinned TLS fingerprint** nella scheda Clusters, salva e riesegui **Test connection**. |
| Slug rifiutato | Non rispetta a-z, 0-9, trattino o non ha una lunghezza di 2-32 caratteri | Usa qualcosa di simile a `pve-1`. |
| "Formato ID token: user@realm!tokenid e secret obbligatorio" | ID token o segreto mancante | Inseriscili entrambi; il segreto è l'UUID stampato al momento della creazione del token. |
| "Riga del template non valida: …" | Una riga in **Template OS** non è `key=vmid` | Usa lettere, cifre, `.`, `_`, `-` nella chiave e un vmid di almeno 100. |
| "Chiave OS: a-z 0-9 . _ - e vmid ≥ 100" | Chiave o ID non validi in **Create template** | Correggi la chiave del sistema operativo e usa un vmid disponibile. |
| "vmid … already exists" durante la creazione di un template | Il vmid è già in uso | Scegli un altro ID. |
| "l'URL punta a un indirizzo interno" | L'URL dell'immagine è un IP interno | Usa un URL pubblico; i nomi vengono risolti da Proxmox. |
| L'attività del template fallisce durante il download | Lo storage `local` non dispone del contenuto `import` | `pvesm set local --content …,import,snippets`, quindi riprova. Un nome file deve terminare con `.qcow2`, `.raw`, `.vmdk`, `.ova` o `.ovf`. |
| "cluster has no online nodes" o "node … is not online" | Il nodo predefinito è spento o scritto in modo errato | Correggi **Default node** o lascialo vuoto. |
| "l'immagine non appartiene al cluster" | Il sistema operativo del piano non è presente in **Template OS** | Aggiungi la chiave all'elenco e salva. |
| La distribuzione rimane in attesa e poi fallisce durante la clonazione | La VM del template non si trova sul nodo scelto | Crea il template su quel nodo oppure imposta **Default node** sul nodo che lo contiene. |
| Il cliente non riesce ad accedere come root | L'immagine blocca il login come root | Ricrea il template come descritto nell'Opzione A. |
| Il ripristino della password non ha alcun effetto | Agent guest non installato nel guest | Installa e abilita `qemu-guest-agent` nel template. |
| "Nome, CIDR e gateway sono obbligatori" | Campo del pool mancante | Compilali tutti e tre. |
| Pool create: "overlaps with pool …", "gateway must be within range (not network/broadcast address)" oppure "cidr: network address must be …" | Pool sovrapposto, gateway errato o CIDR non su un confine di rete | Usa un intervallo libero, un gateway al suo interno e un CIDR scritto come indirizzo di rete (ad esempio `198.51.100.0/24`). |
| Import: "la region non è impostata" | Il cluster è collegato senza il nome del nodo della VM | Collega il cluster alla zona specificando il nome del nodo. |