---
title: Templates de OS e ISOs
description: Prepare as imagens de SO que os clientes implantam: crie e registre templates do CloudStack e monte templates de cloud-image do Proxmox VE.
url: https://nexcmp.com/pt/docs/infrastructure/templates/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Templates de OS e ISOs {#os-templates-and-isos}

> **Onde no admin:** Services › Virtual Machines › Template (`/vm/templates`). Os templates do Proxmox são listados por cluster em Infrastructure › Cloud provider › Providers › (cluster) › Clusters.

## O que faz {#what-it-does}

Um template é a imagem de sistema operacional da qual uma nova VM é iniciada. O NexCMP não armazena imagens por conta própria: ele lê o que o CloudStack reporta (templates prontos e em destaque) ou o que você lista para um cluster Proxmox, e permite escolher quais são vendidos, com um nome voltado ao cliente, ícone e usuário de login. Esta página mostra como preparar imagens que funcionam bem com o NexCMP: login por senha, redimensionamento dinâmico de CPU e RAM, arquivo swap e um disco raiz que cresce até o tamanho do plano.

## Requisitos {#requirements}

| Item | Requisito |
|---|---|
| Construtor de templates do CloudStack | Uma máquina Linux com `libguestfs-tools` (`virt-customize`, `virt-sparsify`, `guestfish`), `qemu-utils`, `curl` e cerca de 5 GB de disco livre. Não são necessários KVM nem root. Acesso à internet para instalações de pacotes (ou compile com `--offline`). |
| Onde fica o construtor | Ele vem incluído em todas as versões em `/opt/nexcmp/releases/<version>/share/templates/` no servidor do painel. Você não precisa executá-lo lá: copie a pasta para qualquer máquina Linux. |
| Servidor web | Qualquer servidor HTTP(S) que a VM de armazenamento secundário do CloudStack possa alcançar para publicar o arquivo `.qcow2` finalizado. Ele não precisa estar acessível a partir da Internet. |
| CloudStack | Uma conta que possa registrar templates, e o ID da sua zona e de um tipo de OS correspondente. Consulte [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/). |
| Proxmox VE | VMs de template com cloud-init e o agente convidado QEMU, uma por OS e por nó. Consulte [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). |
| Depende de | [CloudStack](https://nexcmp.com/pt/docs/infrastructure/cloudstack/) ou [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/) conectado primeiro. |

## Preparar a infraestrutura {#prepare-the-infrastructure}

### CloudStack: criar um template {#cloudstack-build-a-template}

Imagens base suportadas (a imagem do fornecedor é baixada e seu checksum é verificado antes de qualquer alteração):

| Imagem | `--distro` | Usuário de login |
|---|---|---|
| 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` |

Mais distribuições: adicione uma linha a `distros.conf` (URL da imagem, arquivo de checksum, família `deb` ou `rpm`).

1. Copie o construtor para uma máquina de compilação e execute-o:

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

   Adicione `--panel-url https://cloud.example.com` para incluir um agente opcional de monitoramento no primeiro boot que se registra com o seu painel (somente HTTPS). Sem ele, nenhum agente é adicionado. Outras opções: `--base <file>` para usar uma imagem que você baixou, `--offline` para ignorar instalações de pacotes.

2. O resultado é `out/ubuntu-24.04-v7.qcow2` e seu `.sha256`. A compilação termina executando `verify-image.sh`, que inspeciona a imagem finalizada como somente leitura e rejeita imagens defeituosas (ela é mantida como `.unverified`). Você pode executá-lo novamente a qualquer momento: `./verify-image.sh out/ubuntu-24.04-v7.qcow2 --no-agent`.

O que o construtor insere na imagem:

| Item | Motivo |
|---|---|
| `qemu-guest-agent` | O CloudStack pode consultar a VM sobre CPUs e IPs, e colocá-la em espera (quiesce) para snapshots. |
| cloud-init com a fonte de dados do CloudStack, `set_passwords` em cada inicialização, login de senha por SSH | A senha gerada é obtida a partir do roteador virtual e **Reset password** funciona. |
| Uma regra udev para CPU e RAM adicionadas a quente (hot-added) | vCPUs e RAM adicionadas a quente entram em atividade sozinhas, fazendo com que o dimensionamento em tempo real (live scaling) e o Auto Scaling funcionem. |
| Um serviço de arquivo de troca (swap file) | Cria `/swapfile` do menor valor entre 50% da RAM e 4 GiB após o disco crescer. `touch /etc/cmp-swap.disabled` o desativa. |
| cloud-init `growpart` e `resizefs` | O pequeno disco raiz cresce para o tamanho de disco do plano na primeira inicialização. |
| machine-id vazio, sem chaves de host SSH | Cada VM obtém sua própria identidade. |

::: warning Nomeie o template como `<OS> <version> <vN>`
O NexCMP ativa o **Auto Scaling** para templates cujo nome termina em `vN` ou `vN.M` com **N de 6 ou mais** (`Ubuntu 24.04 v7`, `Rocky Linux 9 v7.1`). O construtor impõe isso para `--version`. Registre o template exatamente com o nome impresso.
:::

3. Publique o arquivo e registre-o no CloudStack. Use o SHA-256 impresso pelo build e registre somente após o arquivo ser totalmente gravado:

   ```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` permite que o CloudStack gere a senha da VM.
   - `isdynamicallyscalable=true` permite o dimensionamento em tempo real (live scaling).
   - `host-passthrough` é necessário para as imagens atuais do Rocky e Alma inicializarem; `osdefault` mantém o controlador de disco portátil.

4. Aguarde o template atingir **Download Complete / Ready**.

A imagem do fornecedor mantém seu tamanho virtual pequeno (cerca de 3.5 GiB para Ubuntu e Debian, 10 GiB para Rocky). Lembre-se de que o disco de um plano não pode ser menor do que o disco do template.

### Proxmox VE: criar um template {#proxmox-ve-make-a-template}

Crie um template de VM cloud-init por SO em cada nó em que você fizer o deploy, com o agente de convidado instalado e o login de root ativado, e registre-o como `os-key=vmid`. Os comandos completos estão em [Proxmox VE](https://nexcmp.com/pt/docs/infrastructure/proxmox/). O construtor do CloudStack acima **não** é para o Proxmox: ele configura o cloud-init para a fonte de dados do CloudStack.

### ISOs {#isos}

Os clientes montam suas próprias ISOs através do módulo **Images** (CloudStack) ou do módulo de Servidores Dedicados. Eles são separados dos templates de SO nesta página. Consulte [Modules](https://nexcmp.com/pt/docs/infrastructure/modules/) e [Dedicated servers](https://nexcmp.com/pt/docs/infrastructure/dedicated/).

## Conectar no NexCMP {#connect-in-nexcmp}

1. Abra **Services › Virtual Machines › Template**. Clique em **Sync now** ou aguarde até 15 minutos. A sincronização adiciona templates prontos e em destaque no CloudStack.

      ![A página Template listando templates sincronizados com seu estado pronto e coluna de hot-plug de CPU](https://nexcmp.com/pt/docs/images/infrastructure/templates-01-list.webp)

2. Clique em **Edit** em um novo template e defina o que os clientes veem:

   | Campo | Valor de exemplo |
   |---|---|
   | Nome de exibição para clientes | `Ubuntu 24.04 LTS` |
   | Família do SO | `ubuntu` (ícone e usuário padrão) |
   | Versão | `24.04` |
   | Nome de usuário para login | `ubuntu` (Windows: `Administrator`; outros: `root`) |
   | Ícone | URL da imagem, um caminho ou um nome |
   | Order | `10` |
   | Active | On |
   | Hot-plug de vCPU/RAM (escala em tempo real) | **Auto by name (v6 or later)**, **Yes** ou **No (needs a restart)** |

      ![Diálogo Edit template com um nome visível ao cliente, família do SO, usuário de login e a opção de hot-plug](https://nexcmp.com/pt/docs/images/infrastructure/templates-02-edit.webp)

3. Ative o template. Um template que o CloudStack não lista mais é ocultado automaticamente (e você é alertado no Telegram se configurado); ele nunca é excluído do NexCMP.

### Substituir um modelo por uma versão mais recente {#replace-a-template-with-a-newer-build}

Use **More › Replace with new version** no modelo comercializado. Escolha o novo modelo pronto e atualmente desativado. A entrada comercializada passa a apontar para a nova compilação, mantendo o nome, a ordem e o ícone; a antiga é desativada como opção de retorno (para voltar, use **Replace** na nova entrada). As VMs em execução não são afetadas. Se a nova compilação pertencer a uma família de SO diferente, marque a confirmação primeiro.

## Verificar {#verify}

1. A linha mostra **ready** e, para compilações chamadas `vN` com N igual a 6 ou mais, **CPU hot-plug: supported**.
2. Implante uma VM de teste a partir do modelo e verifique dentro dela:
   - você pode fazer login com a senha exibida no portal;
   - `df -h /` exibe o tamanho do disco do plano;
   - após um redimensionamento dinâmico (**Change plan** sem reinicialização), `nproc` e `free -m` aumentam;
   - `swapon --show` lista `/swapfile` (discos com menos de swap mais 2 GiB livres são ignorados);
   - `systemctl is-active qemu-guest-agent` exibe `active`.
3. Se você integrou o agente, a VM aparecerá nos hosts monitorados do painel um minuto após a primeira inicialização. A VM precisa de um IP público próprio: o painel a reconhece pelo IP de origem público.

## Limites e observações {#limits-and-notes}

- O construtor é exclusivo para Linux e compila imagens Linux. Outras imagens (por exemplo, Windows) podem ser registradas no CloudStack por outros meios; o NexCMP lista o que o CloudStack reporta.
- Apenas o agente amd64 é distribuído; outras arquiteturas ignoram a instalação do agente.
- A imagem é verificada com `guestfish`, mas nunca inicializada pelo construtor. Sempre implante uma VM de teste antes de disponibilizar uma nova imagem.
- Ignore o agente em uma VM com `touch /etc/cmp-agent.disabled` antes da primeira inicialização. Remova-o mais tarde com `systemctl disable --now cmp-agent cmp-agent-install; rm -rf /etc/cmp-agent /usr/local/bin/cmp-agent` e, em seguida, exclua o agente no console de administração.

## Resolução de problemas {#troubleshooting}

| Sintoma | Causa | Correção |
|---|---|---|
| `virt-customize` falha ao baixar pacotes | A máquina de compilação não tem rede de saída | Corrija o DNS ou o proxy nessa máquina ou compile com `--offline` em uma imagem base que já possua os pacotes. |
| `libguestfs: error: /usr/bin/supermin exited with error status 1` | O kernel do host não pode ser lido pelo usuário atual (Ubuntu) | `sudo chmod +r /boot/vmlinuz*` ou execute a compilação como root. |
| A soma de verificação difere ou a imagem do fornecedor não existe mais | Os fornecedores movem seus arquivos "latest" | Baixe a imagem você mesmo, verifique-a com o arquivo de soma de verificação do fornecedor e forneça-a com `--base`. |
| Rocky: um XFS mais recente não pode ser montado | O kernel do host é muito antigo | Compile em uma máquina com um kernel recente. |
| `--version must be v6 or higher` | O nome deve ser `vN` com N igual a 6 ou mais | Use `--version v7`. |
| `--panel-url must be a plain https:// URL` | O agente é baixado e executado como root, portanto, HTTP simples é recusado | Use uma URL `https://` sem espaços, aspas ou string de consulta. |
| O modelo permanece **not ready** | O CloudStack ainda não concluiu o download | Aguarde **Download Complete**, verifique se a VM de armazenamento secundário consegue alcançar a URL. |
| A linha exibe **no-pass** | O modelo foi registrado sem `passwordenabled=true` | Registre-o novamente com essa flag. |
| O hot-plug de CPU exibe **unsupported** | O nome não termina em `vN` (N igual a 6 ou mais) | Renomeie o modelo ou defina **vCPU/RAM hot-plug** como **Yes** em Edit se a imagem possuir a regra udev. |
| "Empty template list" após a primeira conexão | A sincronização não foi executada | Clique em **Sync now** (requer o worker em execução) ou aguarde o ciclo de 15 minutos. |