Como configurar contentores Incus numa VPS

O que é um contentor de sistema Incus

Os contentores de sistema Incus numa VPS fornecem uma máquina completa, com o seu próprio sistema init e as suas próprias contas de utilizador. Não são um único processo com um sistema de ficheiros associado. O contentor arranca, executa um init como PID 1 e responde a systemctl. Partilha o kernel do host, por isso não é uma máquina virtual. Tudo o que está acima do kernel comporta-se como um sistema independente.

O Incus é o fork comunitário do LXD, mantido no âmbito do projeto Linux Containers. O comando cliente é incus. Também executa máquinas virtuais reais através do QEMU quando se utiliza --vm, mas o contentor de sistema é o motivo pelo qual a maioria das pessoas instala o Incus. É esse o modelo abrangido pelo resto deste guia.

Por que as comparações com Docker induzem em erro

O Docker empacota um processo. O Incus empacota um sistema operativo. A documentação do Incus estabelece diretamente esta distinção: "Os contentores de aplicações (fornecidos, por exemplo, pelo Docker) empacotam um único processo ou aplicação. Os contentores de sistema, por outro lado, simulam um sistema operativo completo, semelhante ao que seria executado num host ou numa máquina virtual."

Esta diferença altera a forma como utiliza o sistema no dia a dia.

• Uma imagem Docker não tem init, por isso systemctl falha dentro dela. Um contentor Incus executa um sistema init, pelo que os serviços e os temporizadores funcionam como num servidor.
• Um contentor Docker deve ser destruído e recriado a partir de um Dockerfile. Um contentor Incus deve ser mantido, atualizado e guardado em snapshots.
• Uma imagem Docker é um artefacto de compilação que publica num registry. Uma instância Incus é estado armazenado num pool de armazenamento, e pode movê-la com incus export.
• O Docker isola uma carga de trabalho. O Incus isola uma máquina, pelo que um contentor pode conter várias cargas de trabalho e várias contas de utilizador.

Pode executar Docker dentro de um contentor de sistema Incus. Não deve executar Incus dentro de um contentor de aplicação Docker. Se pretende realmente um processo por contentor, com uma etapa de compilação da imagem, leia primeiro a comparação Podman e Docker numa VPS. Se pretende um kernel separado por carga de trabalho, em vez de um kernel partilhado, consulte Firecracker microVMs numa VPS, que segue na direção oposta.

O Incus funciona dentro de um VPS?

Isso depende do tipo de virtualização e do kernel do seu VPS. Verifique ambos antes de instalar qualquer coisa. Não confie apenas na página de marketing do provedor. Execute estes quatro comandos no servidor.

systemd-detect-virt
uname -r
stat -fc %T /sys/fs/cgroup
cat /sys/fs/cgroup/cgroup.controllers

systemd-detect-virt imprimir kvm ou qemu significa que o seu VPS é uma máquina virtual com kernel próprio. Esse é o caso mais simples, porque o Incus funciona como funcionaria em hardware físico. Imprimir lxc, lxc-libvirt ou openvz significa que o seu VPS é um contentor que partilha o kernel do provedor. Os contentores Incus executados dentro dele são contentores aninhados, e o aninhamento só funciona se o provedor o tiver ativado no seu contentor. Não é possível ativá-lo a partir do interior, porque essa configuração fica no host, que não está sob o seu controlo.

stat -fc %T /sys/fs/cgroup deve imprimir cgroup2fs. Qualquer outro resultado significa que o servidor usa uma organização cgroup (control group) v1 ou híbrida, que as versões atuais do Incus não suportam como destino.

cat /sys/fs/cgroup/cgroup.controllers lista os controladores de grupos de controlo delegados ao seu VPS. A documentação do Incus indica blkio, cpuset, devices, freezer, memory e pids como necessários. Num VPS aninhado, essa lista costuma ser mais curta do que num VPS KVM, porque o provedor escolhe o que disponibiliza. Um controlador ausente desse ficheiro é um controlador que o Incus não pode utilizar. Por isso, o limite de instâncias que depende dele não está disponível.

A versão do kernel é mais importante do que era. Em agosto de 2026, a documentação do Incus indica dois requisitos mínimos diferentes para os dois ramos mantidos pelo projeto upstream. O ramo 6.0 LTS (long term support) indica: "The minimum supported kernel version is 5.4." O ramo estável atual indica: "The minimum supported kernel version is 6.12." O Ubuntu 24.04 disponibiliza a série 6.0 LTS no seu próprio repositório e associa-a a um kernel 6.8, uma combinação suportada. Instalar a versão estável atual a partir do repositório upstream nesse mesmo kernel 6.8 coloca o sistema abaixo do mínimo documentado. Leia uname -r antes de escolher um repositório.

Se o objetivo for executar máquinas virtuais completas, a limitação é diferente e mais difícil. Consulte virtualização aninhada num VPS para saber se o seu VPS consegue disponibilizar /dev/kvm, e Proxmox num VPS alugado para o caso em que o hardware é seu.

Instalar o Incus no Ubuntu ou Debian

Debian 13 e Ubuntu 24.04 e versões posteriores incluem o Incus nos seus próprios repositórios.

sudo apt update
sudo apt install -y incus

No Debian, incus-base instala o suporte para contentores sem os componentes de máquinas virtuais. No Ubuntu, adicione qemu-system se também quiser instâncias --vm.

Para obter uma versão mais recente do que a disponibilizada pela sua distribuição, os pacotes upstream estão em pkgs.zabbly.com. Estes comandos vêm do README do próprio repositório do projeto.

sudo apt update && sudo apt install -y curl
sudo mkdir -p /etc/apt/keyrings/
sudo curl -fsSL https://pkgs.zabbly.com/key.asc -o /etc/apt/keyrings/zabbly.asc
sudo sh -c 'cat <<EOF > /etc/apt/sources.list.d/zabbly-incus-stable.sources
Enabled: yes
Types: deb
URIs: https://pkgs.zabbly.com/incus/stable
Suites: $(. /etc/os-release && echo ${VERSION_CODENAME})
Components: main
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/zabbly.asc
EOF'
sudo apt-get update
sudo apt-get install -y incus

Depois, dê ao seu utilizador acesso ao socket do daemon.

sudo usermod -aG incus-admin "$USER"
newgrp incus-admin
incus info

incus info imprimir a configuração do servidor significa que o socket funciona. Um erro de permissões significa que a alteração do grupo ainda não chegou à sua shell. newgrp incus-admin aplica a alteração à shell atual, enquanto um novo login a aplica corretamente. Trate a pertença a incus-admin como equivalente a root no host, porque o acesso a esse socket dá controlo total sobre um daemon executado como root. Algumas distribuições também criam um grupo incus simples para acesso restrito dos utilizadores.

Agora inicialize o daemon.

sudo incus admin init

Responda às perguntas em vez de usar incus admin init --minimal. O caminho mínimo seleciona o driver de armazenamento dir, e a próxima secção explica por que essa escolha continua a afetar a configuração.

Inicie algo e confirme que funciona.

incus launch images:debian/13 web
incus list
incus exec web -- bash

incus list deve mostrar web como RUNNING com um endereço IPv4 na sub-rede incusbr0. A ausência de endereço significa que o DHCP (protocolo de configuração dinâmica de hosts) não foi concluído, o que é explicado na secção de rede. Um contentor que não consiga iniciar apresenta o motivo em incus info web --show-log, e as falhas ao nível do daemon aparecem em sudo journalctl -u incus -n 50. Numa VPS em que systemd-detect-virt devolveu lxc ou openvz, este arranque é o teste efetivo para saber se o nesting está disponível.

Por que o backend de armazenamento predefinido é importante

O backend de armazenamento determina se um snapshot é instantâneo ou uma cópia completa do disco do contentor. É a única escolha feita durante a instalação que não pode ser alterada mais tarde sem custos significativos.

O Incus suporta dir, btrfs, lvm, zfs, Ceph e vários drivers remotos. Numa VPS com um único disco, a escolha real é entre dir e btrfs.

O driver dir mantém cada contentor como ficheiros e diretórios normais em /var/lib/incus. O Incus documenta-o como "muito mais lento do que todos os outros drivers", porque tem de descompactar cada imagem e criar cópias reais, em vez de referenciar blocos partilhados. Um snapshot de um contentor de 4 GiB grava 4 GiB e demora tanto tempo como cp -a. As quotas de disco só funcionam em ext4 ou XFS com quotas de projeto ativadas ao nível do sistema de ficheiros. Na maioria das imagens de VPS, essa opção não está ativada por predefinição. Por isso, um limite de disco num pool dir muitas vezes não tem efeito.

btrfs e zfs usam copy-on-write, pelo que um snapshot regista apenas os blocos alterados depois da sua criação. O Incus identifica estes dois como os backends recomendados. Os snapshots tornam-se quase instantâneos. As quotas de disco funcionam através do suporte de quotas do próprio sistema de ficheiros.

A maioria dos planos de VPS fornece um único disco sem uma partição livre. Por isso, coloque o pool num ficheiro loop. O Incus faz isso automaticamente quando não fornece source=.

sudo apt install -y btrfs-progs
incus storage create fast btrfs size=30GiB
incus profile device set default root pool=fast
incus launch images:debian/13 web2 -s fast

Sem size=, um pool baseado em loop usa 20% do espaço livre em disco, com um mínimo de 5 GiB e um máximo de 30 GiB. Defina este valor de forma explícita. O ficheiro loop é um ficheiro no sistema de ficheiros raiz. Por isso, o pool e o host partilham o mesmo espaço livre. Se o pool ficar cheio, o disco do host também fica cheio.

O ZFS no Debian e no Ubuntu é um módulo DKMS, e não um módulo integrado no kernel. Por isso, é recompilado a cada atualização do kernel e pode falhar durante uma dessas atualizações. Num servidor que não monitoriza diariamente, o btrfs exige menos manutenção dos dois.

Os três modos de rede e o que cada um expõe

incus admin init cria uma bridge gerida chamada incusbr0 e coloca nela cada nova instância. Essa é uma das três formas de ligar um contentor, e as outras duas existem porque a primeira oculta os contentores atrás de NAT (network address translation).

Bridge gerida. incusbr0 recebe uma sub-rede privada. O host mantém o primeiro endereço dessa sub-rede e atua como gateway, enquanto o Incus fornece DHCP e DNS (domain name system) nela. O tráfego de saída passa pelo endereço público do host com NAT de origem aplicado. Nada do exterior consegue chegar ao contentor até que isso seja explicitamente configurado. Encaminhe uma porta com um dispositivo proxy.

incus config device add web http proxy listen=tcp:0.0.0.0:8080 connect=tcp:127.0.0.1:80 nat=true

nat=true encaminha com regras do netfilter em vez de fazer proxy através de uma ligação separada em userspace. Assim, o endereço real do cliente permanece nos logs do contentor. O Incus suporta esse modo apenas quando o host é o gateway da instância, que é exatamente o caso de incusbr0.

macvlan. O contentor recebe o seu próprio endereço MAC (media access control) na rede física do host. Na maioria das plataformas VPS, isto falha porque a porta do switch virtual está associada ao endereço MAC da VM e descarta frames de qualquer outro endereço. Existe uma segunda limitação que afeta os casos em que isto funciona. A documentação do Incus indica que "macvlan devices, while able to communicate between themselves and to the outside, cannot talk to their parent device. This means that you can't use macvlan if you ever need your instances to talk to the host itself." Os dispositivos macvlan conseguem comunicar entre si e com o exterior, mas não conseguem comunicar com o dispositivo pai. Portanto, não pode usar macvlan se precisar que as instâncias comuniquem com o próprio host.

Routed. Este é o modo que normalmente funciona numa VPS com endereços adicionais. A documentação do Incus descreve o dispositivo como aquele que "creates a virtual device pair to connect the host to the instance and sets up static routes and proxy ARP/NDP entries to allow the instance to join the network of a designated parent interface". ARP é o address resolution protocol. O contentor mantém um endereço público. O host responde a ARP por esse endereço, pelo que o fornecedor continua a ver apenas o endereço MAC do host.

incus config device add web eth0 nic nictype=routed parent=enp1s0 ipv4.address=203.0.113.20

Obtenha o nome da interface pai a partir de ip route show default. As imagens atuais usam nomes como enp1s0 ou ens3, e raramente eth0. Dar ao dispositivo o nome eth0 substitui o dispositivo fornecido pelo perfil default, pelo que o contentor fica na interface routed em vez da bridge. Verifique o resultado a partir do interior com ip a e ip route.

Por que um container conseguiu aceder a um serviço no host

Um container em incusbr0 tem o seu próprio namespace de rede. Não tem uma barreira de firewall contra o host. O host está nessa bridge no endereço do gateway. Por isso, a partir do container, o host é um vizinho diretamente acessível, e todos os serviços do host ligados a 0.0.0.0 respondem nesse endereço.

Verifique por si próprio. No host, liste o que está a escutar.

sudo ss -tlnp

Depois, a partir de um container, tente aceder ao gateway que ip route apresenta.

ip route show default
nc -zv 10.0.0.1 6379

Se uma base de dados, um endpoint de métricas ou um painel de administração no host estiver ligado a 0.0.0.0, essa verificação será bem-sucedida. O firewall de rede do seu provedor nunca viu o pacote, porque o pacote nunca saiu da máquina. Esta é a explicação para a maioria das perguntas do tipo "como conseguiu aceder àquilo": o container está isolado da Internet por NAT, mas não está isolado do host por nenhuma barreira.

Ligue os serviços do host a 127.0.0.1 sempre que possível. Depois, filtre a bridge no host. Num sistema com ufw, a política deny predefinida já bloqueia o tráfego de containers para o host. Isso interrompe o DNS e o DHCP do Incus. A correção indicada na documentação do Incus é sudo ufw allow in on incusbr0. Esse comando reabre todas as portas do host para todos os containers. Em vez disso, permita apenas o que os containers realmente precisam.

sudo ufw allow in on incusbr0 to any port 53 proto udp
sudo ufw allow in on incusbr0 to any port 53 proto tcp
sudo ufw allow in on incusbr0 to any port 67 proto udp
sudo ufw route allow in on incusbr0
sudo ufw route allow out on incusbr0

As duas regras ufw route permitem que o tráfego das instâncias atravesse o host até à Internet. Sem elas, a política de encaminhamento do ufw descarta os pacotes encaminhados. Assim, os containers obtêm um endereço, mas não conseguem aceder a nada.

Snapshots e perfis

Um snapshot é uma cópia da instância num ponto específico no tempo, dentro do respetivo pool de armazenamento.

incus snapshot create web pre-upgrade
incus info web
incus snapshot restore web pre-upgrade
incus snapshot delete web pre-upgrade

incus info web lista os snapshots que a instância contém. Agende-os por instância.

incus config set web snapshots.schedule=@daily
incus config set web snapshots.expiry=4w

Um snapshot permanece no mesmo pool, no mesmo disco e no mesmo servidor. Protege contra uma atualização mal sucedida. Não protege contra a falha de um disco nem contra a eliminação da instância. A cópia de segurança é incus export, e o ficheiro tem de sair do servidor.

incus export web /root/web-backup.tar.gz
incus import /root/web-backup.tar.gz

Um perfil é um conjunto nomeado de chaves de configuração e dispositivos aplicado às instâncias. Todas as instâncias recebem o perfil default, salvo indicação em contrário. Esse perfil fornece o disco raiz e a interface de rede. Editar default altera todas as instâncias que o utilizam. Isto é útil, mas também permite desligar a rede de vinte contentores de uma só vez.

incus profile create small
incus profile set small limits.memory=512MiB
incus profile set small limits.cpu=1
incus launch images:debian/13 api -p default -p small

Os perfis são aplicados por ordem. Por isso, uma chave definida no último perfil listado prevalece. Consulte a configuração efetiva de uma instância com incus config show api --expanded.

Executar Docker dentro de um contentor Incus

O Docker dentro de um contentor de sistema Incus precisa que o nesting esteja ativado, porque o Docker cria os seus próprios namespaces e mounts, que um contentor não pode criar por predefinição.

incus config set web security.nesting=true
incus restart web

A documentação do Incus descreve security.nesting como "Whether to allow nesting inside of the instance" e define-o como false para contentores. Dois pontos adicionais estão descritos diretamente nas FAQ do Incus. Um contentor não pode carregar módulos do kernel. Por isso, qualquer módulo necessário ao Docker tem de ser carregado no host e indicado com incus config set web linux.kernel_modules overlay,br_netfilter. Além disso, criar um ficheiro /.dockerenv dentro do contentor faz com que o Docker ignore algumas verificações que falham num ambiente nested.

Em hosts Ubuntu 24.04, as restrições do AppArmor aos user namespaces não privilegiados podem bloquear o pivot_root que runc executa. O Docker dentro do contentor apresenta:

failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error jailing process inside rootfs: pivot_root .: permission denied

e o dmesg do host mostra uma linha que contém apparmor="DENIED" operation="pivotroot" class="mount". A definição que costuma ser alterada é kernel.apparmor_restrict_unprivileged_userns. Desativá-la não é uma correção fiável: o relatório de bug do Incus para esta recusa específica regista que defini-la como 0 não resolveu o problema. Consulte primeiro dmesg para ver a recusa. Assim, confirma se o AppArmor é realmente a causa antes de alterar uma predefinição de segurança.

Se preferir executar os contentores diretamente no VPS e eliminar uma camada, executar Docker num VPS explica essa configuração separadamente.

Modos de falha e as mensagens apresentadas

As instâncias perdem toda a rede depois de instalar o Docker no host. A documentação do Incus identifica a causa: "O Docker define a política global de FORWARD como drop, o que impede o Incus de encaminhar tráfego e faz com que as instâncias percam a conectividade de rede." As instâncias mantêm os seus endereços, mas não conseguem chegar a nenhum destino. Defina ip-forward-no-drop como true em /etc/docker/daemon.json. Depois, torne o encaminhamento persistente e permita a passagem da bridge pela própria chain do Docker.

echo "net.ipv4.conf.all.forwarding=1" | sudo tee /etc/sysctl.d/99-forwarding.conf
sudo systemctl restart systemd-sysctl
sudo iptables -I DOCKER-USER -i incusbr0 -j ACCEPT
sudo iptables -I DOCKER-USER -o incusbr0 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT

Essas regras iptables não sobrevivem sozinhas a um reboot. Torne-as persistentes.

Os contentores deixam de arrancar com um erro de cgroup. A FAQ do Incus documenta este caso. Uma mensagem sobre Failed to mount "/sys/fs/cgroup" normalmente significa que um cliente VPN no host montou o controlador de cgroup v1 net_cls sobre o cgroup v2, que o Incus utiliza. sudo umount /sys/fs/cgroup/net_cls remove o problema.

A instância não recebe um endereço IPv4. incus list mostra que está em execução, mas com a coluna de endereço vazia. As respostas DHCP do host estão a ser descartadas, normalmente por uma firewall do host que não conhece a bridge. No ufw, sudo ufw allow in on incusbr0 to any port 67 proto udp resolve o problema. Monitorize a chegada dos pedidos com sudo tcpdump -ni incusbr0 port 67.

A instância recusa arrancar numa VPS aninhada. Consulte primeiro incus info <name> --show-log e depois sudo journalctl -u incus -n 50. Se systemd-detect-virt indicar lxc ou openvz, o problema está do lado do fornecedor, e nenhuma definição dentro da sua VPS o altera.

Os snapshots são lentos e o disco continua a encher. Está a utilizar um pool dir. incus storage list apresenta o driver de cada pool. Para mudar para um pool copy-on-write, crie o novo pool, copie as instâncias para ele com incus copy web web-new -s fast e elimine os originais depois de confirmar que as cópias arrancam.

FAQ

Um contentor Incus é a mesma coisa que um contentor Docker?

Não. O Docker empacota um único processo ou aplicação. Um contentor de sistema Incus simula um sistema operativo completo, com o seu próprio init, utilizadores, serviços e gestor de pacotes. Mantém e aplica correções a um contentor Incus como faria com um servidor. Remove um contentor Docker e recria-o a partir de uma imagem. Pode executar Docker dentro de um contentor Incus definindo security.nesting=true no contentor. O inverso não funciona.

Posso executar o Incus num VPS?

Num VPS KVM, sim. Se systemd-detect-virt imprimir kvm ou qemu, tem o seu próprio kernel e o Incus comporta-se como num sistema físico. Se imprimir lxc, lxc-libvirt ou openvz, o próprio VPS é um contentor. Nesse caso, os contentores Incus ficam aninhados e só funcionam se o fornecedor tiver ativado o nesting no seu contentor. Verifique também uname -r, porque, em agosto de 2026, o ramo estável atual do Incus documenta um kernel mínimo de 6.12, enquanto o ramo 6.0 LTS documenta 5.4.

Que backend de armazenamento devo escolher para o Incus num VPS?

btrfs num ficheiro loop, exceto se tiver um dispositivo de bloco disponível para esse fim. O controlador dir está documentado como sendo muito mais lento do que os restantes, porque copia ficheiros em vez de usar copy-on-write. Por isso, cada snapshot grava novamente o contentor inteiro. incus admin init --minimal seleciona dir. Por isso, vale a pena responder às perguntas interativas durante os dois minutos necessários. Crie o pool com incus storage create fast btrfs size=30GiB.

Porque é que o meu contentor Incus consegue aceder a um serviço executado no host?

Porque a bridge incusbr0 predefinida coloca o host na mesma sub-rede que o contentor, no endereço do gateway, e não existe filtragem entre ambos. Qualquer serviço do host associado a 0.0.0.0 responde nesse endereço. A firewall do fornecedor nunca vê esses pacotes, porque eles não saem da máquina. Associe os serviços do host a 127.0.0.1. Num host com ufw, permita apenas DNS e DHCP de entrada em incusbr0, em vez de usar a regra abrangente sudo ufw allow in on incusbr0.

Como faço uma cópia de segurança de um contentor Incus?

incus export web /root/web-backup.tar.gz grava a instância e os seus snapshots num único ficheiro, e incus import restaura-o no mesmo servidor ou noutro. Os snapshots criados com incus snapshot create não são cópias de segurança. Permanecem no mesmo pool de armazenamento e no mesmo disco. Por isso, sobrevivem a uma atualização mal sucedida, mas não à falha do servidor. Agende-os com incus config set web snapshots.schedule=@daily e copie as exportações para fora da máquina.