---
title: Template di OS e ISO
description: Prepara le immagini OS distribuite dai clienti: compila e registra i template di CloudStack e crea i template di immagini cloud per Proxmox VE.
url: https://nexcmp.com/it/docs/infrastructure/templates/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Template di OS e ISO {#os-templates-and-isos}

> **Dove nell'admin:** Services › Virtual Machines › Template (`/vm/templates`). I template Proxmox sono elencati per cluster in Infrastructure › Cloud provider › Providers › (cluster) › Clusters.

## Descrizione {#what-it-does}

Un template è l'immagine del sistema operativo da cui si avvia una nuova VM. NexCMP non memorizza direttamente le immagini: legge quelle segnalate da CloudStack (pronte, in evidenza) o quelle elencate per un cluster Proxmox, permettendoti di scegliere quali vendere assegnando un nome orientato al cliente, un’icona e un utente di accesso. Questa pagina mostra come preparare immagini perfettamente compatibili con NexCMP: accesso tramite password, ridimensionamento live di CPU e RAM, file di swap e disco di root che si espande fino alle dimensioni del piano.

## Requisiti {#requirements}

| Elemento | Requisito |
|---|---|
| Generatore di template CloudStack | Una macchina Linux con `libguestfs-tools` (`virt-customize`, `virt-sparsify`, `guestfish`), `qemu-utils`, `curl` e circa 5 GB di spazio libero su disco. Non sono richiesti KVM né i permessi di root. Accesso a Internet per l'installazione dei pacchetti (o compilazione con `--offline`). |
| Dove si trova il generatore | È incluso in ogni release in `/opt/nexcmp/releases/<version>/share/templates/` sul server del pannello. Non è necessario eseguirlo lì: basta copiare la cartella su qualsiasi macchina Linux. |
| Server Web | Qualsiasi server HTTP(S) raggiungibile dalla VM di storage secondario di CloudStack per pubblicare il file `.qcow2` completato. Non deve necessariamente essere raggiungibile da Internet. |
| CloudStack | Un account autorizzato a registrare i template, l'ID della zona e di un tipo di OS corrispondente. Vedi [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/). |
| Proxmox VE | VM template Cloud-init con QEMU guest agent, una per OS e per nodo. Vedi [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). |
| Dipende da | [CloudStack](https://nexcmp.com/it/docs/infrastructure/cloudstack/) o [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/) collegati preventivamente. |

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

### CloudStack: compila un template {#cloudstack-build-a-template}

Immagini di base supportate (l'immagine del produttore viene scaricata e il relativo checksum verificato prima di qualsiasi modifica):

| Immagine | `--distro` | Utente di accesso |
|---|---|---|
| Ubuntu 22.04 | `ubuntu-22.04` | `ubuntu` |
| Ubuntu 24.04 | `ubuntu-24.04` | `ubuntu` |
| Debian 12 | `debian-12` | `debian` |
| Rocky Linux 9 | `rocky-9` | `rocky` |

Altre distribuzioni: aggiungi una riga a `distros.conf` (URL dell'immagine, file di checksum, famiglia `deb` o `rpm`).

1. Copia il generatore su una macchina di compilazione ed eseguilo:

   ```bash
   cp -r /opt/nexcmp/releases/<version>/share/templates ~/templates && cd ~/templates
   ./build-template.sh --distro ubuntu-24.04 --version v7 --work ./out
   ```

   Aggiungi `--panel-url https://cloud.example.com` per integrare un agente di monitoraggio opzionale al primo avvio che si registra con il tuo pannello (solo HTTPS). Senza di esso, non viene aggiunto alcun agente. Altre opzioni: `--base <file>` per usare un'immagine scaricata, `--offline` per saltare l'installazione dei pacchetti.

2. Il risultato è `out/ubuntu-24.04-v7.qcow2` e il suo `.sha256`. La compilazione termina eseguendo `verify-image.sh`, che ispeziona l'immagine completata in sola lettura rifiutandone una difettosa (viene mantenuta come `.unverified`). Puoi rieseguirlo in qualsiasi momento: `./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent`.

Cosa inserisce il generatore nell'immagine:

| Elemento | Motivo |
|---|---|
| `qemu-guest-agent` | CloudStack può interrogare la VM su CPU e IP e metterla in pausa per gli snapshot. |
| cloud-init con l'origine dati CloudStack, `set_passwords` a ogni avvio, login SSH con password | La password generata viene recuperata dal router virtuale e **Reset password** funziona. |
| Una regola udev per CPU e RAM aggiunte a caldo | I vCPU e la RAM aggiunti a caldo si attivano autonomamente, quindi il ridimensionamento live e l'Auto Scaling funzionano. |
| Un servizio di file di swap | Crea `/swapfile` del minore tra il 50% della RAM e 4 GiB dopo che il disco è cresciuto. `touch /etc/cmp-swap.disabled` lo disattiva. |
| cloud-init `growpart` e `resizefs` | Il piccolo disco di root si estende alla dimensione del disco del piano al primo avvio. |
| machine-id vuoto, nessuna chiave host SSH | Ogni VM ottiene la propria identità. |

::: warning Nomina il template `<OS> <version> <vN>`
NexCMP attiva **Auto Scaling** per i template il cui nome termina in `vN` o `vN.M` con **N di 6 o superiore** (`Ubuntu 24.04 v7`, `Rocky Linux 9 v7.1`). Il builder applica questo per `--version`. Registra il template con il nome esatto stampato.
:::

3. Pubblica il file e registralo in CloudStack. Usa lo SHA-256 stampato dalla compilazione e registralo solo dopo che il file è stato scritto completamente:

   ```bash
   cmk list ostypes keyword="Ubuntu 24.04" filter=id,description
   cmk register template name="Ubuntu 24.04 v7" displaytext="Ubuntu 24.04 v7" \
     url=https://files.example.com/ubuntu-24.04-v7.qcow2 zoneid=<zone-id> format=QCOW2 hypervisor=KVM \
     ostypeid=<os-type-id> passwordenabled=true sshkeyenabled=true isdynamicallyscalable=true \
     requireshvm=true isextractable=false ispublic=true isfeatured=true \
     checksum="{SHA-256}<sha256 of the file>" \
     details[0].guest.cpu.mode=host-passthrough details[0].rootDiskController=osdefault
   ```

   - `passwordenabled=true` consente a CloudStack di generare la password della VM.
   - `isdynamicallyscalable=true` consente il ridimensionamento live.
   - `host-passthrough` è necessario per l'avvio delle immagini correnti di Rocky e Alma; `osdefault` mantiene portabile il controller del disco.

4. Attendi che il template raggiunga **Download Complete / Ready**.

L'immagine del vendor mantiene la sua piccola dimensione virtuale (circa 3.5 GiB per Ubuntu e Debian, 10 GiB per Rocky). Ricorda che il disco di un piano non può essere più piccolo del disco del template.

### Proxmox VE: crea un template {#proxmox-ve-make-a-template}

Crea un template VM cloud-init per OS su ogni nodo su cui effettui il deployment, con il guest agent installato e il login root abilitato, quindi registralo come `os-key=vmid`. I comandi completi si trovano in [Proxmox VE](https://nexcmp.com/it/docs/infrastructure/proxmox/). Il builder CloudStack sopra **non** è per Proxmox: configura cloud-init per l'origine dati CloudStack.

### ISO {#isos}

I clienti montano le proprie ISO tramite il modulo **Images** (CloudStack) o il modulo Server Dedicati. Questi sono separati dai template OS di questa pagina. Vedi [Modules](https://nexcmp.com/it/docs/infrastructure/modules/) e [Dedicated servers](https://nexcmp.com/it/docs/infrastructure/dedicated/).

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

1. Apri **Services › Virtual Machines › Template**. Fai clic su **Sync now** o attendi fino a 15 minuti. La sincronizzazione aggiunge i template pronti e in evidenza in CloudStack.

      ![La pagina dei template che elenca i template sincronizzati con il loro stato di pronto e la colonna di hot-plug della CPU](https://nexcmp.com/it/docs/images/infrastructure/templates-01-list.webp)

2. Fai clic su **Edit** su un nuovo template e imposta ciò che vedono i clienti:

   | Campo | Valore di esempio |
   |---|---|
   | Nome visualizzato per i clienti | `Ubuntu 24.04 LTS` |
   | Famiglia OS | `ubuntu` (icona e utente predefinito) |
   | Versione | `24.04` |
   | Nome utente di login | `ubuntu` (Windows: `Administrator`; altro: `root`) |
   | Icona | URL dell'immagine, un percorso o un nome |
   | Order | `10` |
   | Active | On |
   | Hot-plug vCPU/RAM (scale live) | **Auto by name (v6 or later)**, **Yes** o **No (needs a restart)** |

      ![Finestra di modifica del template con nome visibile al cliente, famiglia OS, utente di login e opzione di hot-plug](https://nexcmp.com/it/docs/images/infrastructure/templates-02-edit.webp)

3. Attiva il template. Un template che CloudStack non elenca più viene nascosto automaticamente (e ricevi un avviso su Telegram se configurato); non viene mai eliminato da NexCMP.

### Sostituisci un template con una build più recente {#replace-a-template-with-a-newer-build}

Usa **More › Replace with new version** sul template venduto. Scegli il nuovo template pronto e attualmente disabilitato. La voce venduta punterà quindi alla nuova build mantenendo nome, ordine e icona; quella vecchia viene disabilitata come via di ritorno (per tornare indietro, usa **Replace** sulla nuova voce). Le macchine virtuali in esecuzione non vengono toccate. Se la nuova build appartiene a un'altra famiglia di OS, spunta prima la conferma.

## Verifica {#verify}

1. La riga mostra **ready** e, per le build denominate `vN` con N pari o superiore a 6, **CPU hot-plug: supported**.
2. Distribuisci una VM di test dal template e controlla all'interno della VM:
   - puoi effettuare l'accesso con la password mostrata nel portale;
   - `df -h /` mostra la dimensione del disco del piano;
   - dopo un ridimensionamento a caldo (**Change plan** senza riavvio), `nproc` e `free -m` aumentano;
   - `swapon --show` elenca `/swapfile` (i dischi con spazio libero inferiore alla swap più 2 GiB vengono saltati);
   - `systemctl is-active qemu-guest-agent` stampa `active`.
3. Se hai integrato l'agent, la VM appare tra gli host monitorati del pannello un minuto dopo il primo avvio. La VM necessita di un IP pubblico proprio: il pannello la riconosce tramite il suo IP sorgente pubblico.

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

- Il builder è solo per Linux e compila immagini Linux. Altre immagini (ad esempio Windows) possono essere registrate in CloudStack con altri mezzi; NexCMP elenca ciò che CloudStack segnala.
- Viene fornito solo l'agent amd64; le altre architetture saltano l'installazione dell'agent.
- L'immagine viene controllata con `guestfish` ma non viene mai avviata dal builder. Distribuisci sempre una VM di test prima di vendere una nuova immagine.
- Salta l'agent su una VM con `touch /etc/cmp-agent.disabled` prima del primo avvio. Rimuovilo in seguito con `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent`, quindi elimina l'agent nella console di amministrazione.

## Troubleshooting {#troubleshooting}

| Sintomo | Causa | Soluzione |
|---|---|---|
| `virt-customize` non riesce a scaricare i pacchetti | La macchina di build non ha connettività di rete in uscita | Correggi il DNS o il proxy su quella macchina, oppure compila con `--offline` su un'immagine di base che possiede già i pacchetti. |
| `libguestfs: error: /usr/bin/supermin exited with error status 1` | Il kernel dell'host non è leggibile dall'utente corrente (Ubuntu) | `sudo chmod +r /boot/vmlinuz*`, oppure esegui la build come root. |
| Il checksum differisce o l'immagine del vendor non esiste più | I vendor spostano i loro file "latest" | Scarica tu stesso l'immagine, controllala rispetto al file di checksum del vendor e passala con `--base`. |
| Rocky: un XFS più recente non può essere montato | Il kernel dell'host è troppo vecchio | Compila su una macchina con un kernel recente. |
| `--version must be v6 or higher` | Il nome deve essere `vN` con N pari o superiore a 6 | Usa `--version v7`. |
| `--panel-url must be a plain https:// URL` | L'agent viene scaricato ed eseguito come root, quindi l'HTTP in chiaro viene rifiutato | Usa un URL `https://` senza spazi, virgolette o stringa di query. |
| Il template rimane **not ready** | CloudStack non ha completato il download | Attendi **Download Complete**, verifica che la VM di storage secondario possa raggiungere l'URL. |
| La riga mostra **no-pass** | Il template è stato registrato senza `passwordenabled=true` | Registralo di nuovo con quel flag. |
| L'hot-plug della CPU mostra **unsupported** | Il nome non termina con `vN` (N pari o superiore a 6) | Rinomina il template o imposta **vCPU/RAM hot-plug** su **Yes** in Edit se l'immagine dispone della regola udev. |
| "Empty template list" dopo la prima connessione | La sincronizzazione non è stata eseguita | Fai clic su **Sync now** (richiede il worker in esecuzione) o attendi il ciclo di 15 minuti. |