> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxmox VE

> Monitore e controle nós, máquinas virtuais, containers LXC e storages de um servidor ou cluster Proxmox VE

# Proxmox VE

A integração **Proxmox VE** conecta o Portal à API de um servidor (ou cluster)
[Proxmox Virtual Environment](https://www.proxmox.com/en/proxmox-virtual-environment).
Ela expõe sensores de uso de CPU, memória, disco e storage, o estado de cada
VM e container, e botões para ligar, desligar, reiniciar e criar snapshots.
O funcionamento segue o componente `proxmoxve` do Home Assistant.

> [!NOTE]
>
> Roda apenas em um **edge local (home)**: o edge precisa alcançar o Proxmox
> na porta da API (padrão `8006`).

## Pré-requisitos: usuário e permissões

Recomendamos criar um usuário dedicado (ou um **API token**) com apenas as
permissões necessárias. No Proxmox, em **Datacenter → Permissions → Roles**,
crie uma role com os privilégios abaixo e atribua-a ao usuário/token no
caminho `/`:

| Privilégio | Necessário para |
| - | - |
| `Sys.Audit` | Ler o estado dos nós, storages e tarefas de backup |
| `VM.Audit` | Ler o estado das VMs e containers |
| `VM.PowerMgmt` | Botões de iniciar/parar/reiniciar/suspender VMs e containers |
| `VM.Snapshot` | Botão **Criar snapshot** |
| `Sys.PowerMgmt` | Botões de reiniciar/desligar o nó e iniciar/parar todos os convidados |
| `Sys.Modify` | Entidade de atualizações pendentes do nó |

Os botões cujas permissões o usuário não tiver não são criados.

### Criar um API token

1. Em **Datacenter → Permissions → API Tokens**, clique em **Add**.
2. Escolha o usuário (ex: `portal@pve`) e informe um **Token ID** (ex: `portal`).
3. Desmarque **Privilege Separation** para o token herdar as permissões do
   usuário — ou atribua a role diretamente ao token.
4. Copie o **Secret** exibido; ele só aparece uma vez.

## Configurar

**1. Adicione a integração**

Vá em **Configurações → Integrações → Adicionar → Proxmox VE** e selecione
um edge local.

**2. Informe o servidor**

Preencha **Host**, **Porta** (padrão `8006`), **Usuário** e o **Método de
autenticação** (`PAM`, `Proxmox VE` ou outro realm). Marque **Usar API
token** para autenticar por token em vez de senha.

**3. Credenciais**

Informe a **Senha** ou o **Token ID** e o **Segredo** do token. Se escolheu
outro realm, informe também o **Realm**.

**4. Pronto**

O Portal descobre automaticamente os nós, VMs, containers e storages e
atualiza os dados a cada minuto. Recursos novos aparecem sozinhos e os
removidos do Proxmox são removidos do Portal.

> [!WARNING]
>
> Se o Proxmox usa o certificado autoassinado padrão, desmarque **Verificar
> certificado SSL**.

Para mudar host, porta ou credenciais depois, use **Reconfigurar** na
integração. Se a senha ou o token expirar, o Portal pede uma nova
autenticação.

## Entidades

Cada nó, VM, container e storage vira um dispositivo próprio.

### Nó

| Entidade | Plataforma | Descrição |
| - | - | - |
| CPU | `sensor` | Uso de CPU (%) |
| Memória máxima | `sensor` | Memória total (GiB) |
| Uso de memória | `sensor` | Uso de memória (%) |
| Uso do disco | `sensor` | Uso do disco raiz (%) |
| Ligado desde | `sensor` | Horário do último boot |
| Estado | `sensor` | `online` / `offline` |
| Em execução | `binary_sensor` | `on` quando o nó está online |
| Falha no backup | `binary_sensor` | `on` quando a última tarefa de backup falhou |
| Atualizações | `update` | Pacotes pendentes (exige `Sys.Modify`) |
| Reiniciar, Desligar | `button` | Reinicia ou desliga o nó |
| Iniciar todos, Parar todos, Suspender todos | `button` | Ações em massa sobre os convidados do nó |

### VM (QEMU) e container (LXC)

| Entidade | Plataforma | Descrição |
| - | - | - |
| CPU, Memória máxima, Uso de memória, Ligado desde, Estado | `sensor` | Métricas e estado do convidado |
| Em execução | `binary_sensor` | `on` quando o convidado está rodando |
| Iniciar, Parar, Reiniciar, Desligar | `button` | Controle de energia |
| Pausar, Suspender, Retomar, Reset | `button` | Apenas VMs |
| Criar snapshot | `button` | Cria o snapshot `portal_snapshot_AAAAMMDDhhmmss` |

### Storage

| Entidade | Plataforma | Descrição |
| - | - | - |
| Usado, Total, Disponível | `sensor` | Espaço em GiB |
| Uso | `sensor` | Ocupação (%) |
| Ativo, Habilitado, Compartilhado | `binary_sensor` | Estado do storage |

Valores adicionais (como disco e rede dos convidados) ficam disponíveis nos
atributos das entidades.

## Automações

Os botões podem ser usados como ações em automações — por exemplo, criar um
snapshot antes de uma janela de manutenção ou desligar VMs não essenciais
quando o nobreak entrar em bateria. O binary\_sensor **Falha no backup** é um
bom gatilho para notificações.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.