Guia de administração de máquinas virtuais KVM/Libvirt pela linha de comando, organizado por categorias funcionais — as mesmas do virsh --help (libvirt 11.x, a versão do nosso homelab). Destinado a quem já conhece Linux básico e quer dominar o ciclo de vida completo das VMs sem depender de interface gráfica.
Convenção: os exemplos rodam localmente no hypervisor (
qemu:///system) ou remotamente da estação de trabalho comvirsh -c qemu+ssh://gean@kvm-01/system ..., conforme configurado no tutorial do homelab. DefinaLIBVIRT_DEFAULT_URIpara omitir o-c.
┌──────────────────────────────────────────────┐
│ Ferramentas: virsh, virt-install, │
│ virt-manager, Terraform (provider libvirt) │
├──────────────────────────────────────────────┤
│ libvirt (daemon: libvirtd) │
│ API única: domínios, redes, pools, volumes │
├──────────────────────────────────────────────┤
│ QEMU (emulador + dispositivos virtio) │
├──────────────────────────────────────────────┤
│ KVM (módulo do kernel: /dev/kvm) │
│ virtualização assistida por hardware │
└──────────────────────────────────────────────┘
/dev/kvm;virsh é o shell dessa API — quase tudo no libvirt é feito por ele.| URI | Escopo | Uso |
|---|---|---|
qemu:///system |
Daemon do sistema (root), VMs compartilhadas | Produção/homelab — padrão desta wiki |
qemu:///session |
Por usuário, VMs privadas, sem acesso a recursos privilegiados | Testes em desktop |
qemu+ssh://user@host/system |
Daemon remoto via SSH | Gerenciar kvm-01/02/03 da estação |
# Flags de virtualização no CPU (>0 = suportado)
egrep -c '(vmx|svm)' /proc/cpuinfo
# Módulo carregado
lsmod | grep kvm
# Detalhes do nodo via libvirt
virsh nodeinfo
virsh uri # URI de conexão atual
virsh list --all # todos os domínios, ligados ou não
Exemplo completo e comentado (o mesmo validado no tutorial do homelab):
sudo virt-install \
--virt-type kvm \ # usa /dev/kvm (nunca emulação pura)
--machine q35 \ # chipset moderno (PCIe)
--name debian13 \
--boot uefi \ # requer o pacote ovmf
--cdrom /datastore/isos/debian-13.4.0-amd64-netinst.iso \
--os-variant debian13 \ # otimizações por SO (osinfo-query os)
--disk pool=default,size=32,format=qcow2,bus=virtio,cache=none \
--memory 4096 --vcpus 2 \
--cpu host-passthrough \ # expõe todas as features do CPU físico
--network network=default,model=virtio \
--graphics vnc,listen=0.0.0.0 \ # console VNC acessível da estação
--noautoconsole # não prende o terminal ao instalador
Com as golden images do pool templates criadas pelo Packer:
# Caminho rápido: clonar uma VM existente parada
sudo virt-clone --original debian13 --name web-01 \
--file /datastore/images/web-01.qcow2
# Caminho do laboratório: backing store manual + cloud-init
sudo qemu-img create -f qcow2 -F qcow2 \
-b /datastore/templates/debian-trixie-base.qcow2 \
/datastore/images/web-01.qcow2 32G
Para mais de uma VM, o clone manual vira toil — é exatamente o problema que a série Terraform resolve declarativamente.
virsh start web-01 # ligar
virsh shutdown web-01 # desligar gracioso (ACPI — guest precisa cooperar)
virsh reboot web-01 # reiniciar gracioso
virsh suspend web-01 # pausar (RAM congelada, VM continua alocada)
virsh resume web-01 # retomar
virsh save web-01 web-01.save # hibernar: RAM em disco, VM desalocada
virsh restore web-01.save # voltar do arquivo de hibernação
virsh autostart web-01 # ligar com o host
virsh autostart --disable web-01
destroynão apaga a VM — é o "botão de força": corta a energia instantaneamente (risco de corrupção de filesystem no guest). Apagar a definição éundefine. Ambos estão na tabela de risco da seção 9.
virsh list --all # estado resumido
virsh dominfo web-01 # CPU, memória, autostart, estado
virsh domstate web-01 # só o estado
virsh console web-01 # console serial (saia com Ctrl+])
virsh edit web-01 # edita o XML (valida ao salvar)
virsh dumpxml web-01 # XML atual (ótimo para backup/auditoria)
virsh domifaddr web-01 # IPs da VM (via agent ou DHCP leases)
virsh domstats web-01 # estatísticas agregadas (CPU, blk, net)
virsh domblklist web-01 # discos anexados (vda, vdb, sda...)
virsh domiflist web-01 # interfaces de rede
virsh domblkstat web-01 vda # I/O de um disco
virsh domifstat web-01 vnet0 # tráfego de uma interface
virsh dommemstat web-01 # memória (requer balloon ativo)
virsh cpu-stats web-01 # tempos de CPU
virsh snapshot-create-as web-01 pre-upgrade "Antes do upgrade para trixie"
virsh snapshot-list web-01
virsh snapshot-revert web-01 pre-upgrade
virsh snapshot-delete web-01 pre-upgrade
Checkpoints (categoria Domain Checkpoint) são a base do backup incremental (virsh checkpoint-create-as + backup-begin) — diferente de snapshot, um checkpoint só registra a trilha de blocos alterados, sem congelar estado.
Snapshots de disco qcow2 não substituem backup: vivem na mesma mídia da VM. E lembre que snapshots em cadeia degradam I/O — consolide com
blockcommitapós janelas de mudança.
virsh net-list --all # redes definidas (default, NAT, isoladas...)
virsh net-dumpxml default # definição XML
virsh net-define rede.xml # criar a partir de XML
virsh net-start docker # ativar
virsh net-autostart docker # ativar com o host
virsh net-destroy docker # desativar (definição permanece)
virsh net-undefine docker # apagar a definição
virsh net-dhcp-leases default # leases DHCP da rede
Os três perfis de rede (NAT, isolada, bridge) e seus XMLs estão detalhados no tutorial Redes customizadas — lá elas são declaradas via Terraform, mas o objeto libvirt resultante é o mesmo.
Duas categorias do help com ressalvas:
iface-* (interfaces do host): depende do backend netcf, indisponível na maioria das distribuições modernas — gerencie a br0 pelo /etc/network/interfaces (como no homelab) ou netplan;nwfilter-* (nwfilter-list, nwfilter-define, nwfilter-edit): filtros de tráfego por interface de VM (anti-spoofing de IP/MAC, limites de protocolo) — a camada de microssegmentação do libvirt.virsh pool-list --all
virsh pool-define-as --name imagens --type dir --target /datastore/images
virsh pool-build imagens # cria o diretório-alvo, se necessário
virsh pool-start imagens
virsh pool-autostart imagens
virsh pool-refresh default # re-escanear volumes criados por fora
virsh vol-list default
virsh vol-create-as default web-01-data.qcow2 32G --format qcow2
virsh vol-info web-01-data.qcow2 default
virsh vol-resize web-01-data.qcow2 64G --pool default
virsh vol-download web-01-data.qcow2 backup.qcow2 --pool default
virsh vol-delete web-01-data.qcow2 --pool default
Pools de diretório cobrem o homelab; o libvirt também suporta LVM (logical), NFS (netfs), iSCSI e Ceph RBD para storage compartilhado — pré-requisito de migração ao vivo sem cópia de discos (seção 7).
qemu-img info debian-trixie-base.qcow2 # formato, backing chain, tamanho
qemu-img create -f qcow2 disco.qcow2 32G # criar
qemu-img convert -O qcow2 disco.raw disco.qcow2 # converter (ex.: raw → qcow2)
qemu-img resize disco.qcow2 +16G # ampliar (guest ainda precisa de growpart)
qemu-img check disco.qcow2 # integridade
virsh vol-create-as default web-01-logs.qcow2 16G --format qcow2
virsh attach-disk web-01 \
--source /datastore/images/web-01-logs.qcow2 \
--target vdb --driver qemu --subdriver qcow2 \
--persistent --live
No guest, o disco aparece como /dev/vdb — formatação e montagem conforme o tutorial Docker, seção 3. (Na série Terraform, essa mesma operação é o recurso extra_disks.)
As flags --live (VM em execução), --config (persiste no XML) e --current (ambas) se aplicam a quase todos os comandos desta seção — usar só --live perde a mudança no próximo boot.
virsh attach-disk web-01 --source /datastore/images/extra.qcow2 --target vdb --persistent --live
virsh detach-disk web-01 vdb --persistent --live
virsh attach-interface web-01 network docker --model virtio --persistent --live
virsh detach-interface web-01 network --mac 52:54:00:aa:bb:cc --persistent --live
virsh attach-device web-01 usb.xml --persistent # USB via XML de dispositivo
virsh setvcpus web-01 4 --maximum --config # teto de vCPUs (requer VM desligada)
virsh setvcpus web-01 2 --live # hot-plug até o teto
virsh setmaxmem web-01 8G --config
virsh setmem web-01 6G --live # balloon de memória
virsh numatune web-01 --nodeset 0 --config # afinidade NUMA
virsh blockresize web-01 vda 64G # após vol-resize, expõe o novo tamanho ao guest
Com três hosts no laboratório, a migração ao vivo move uma VM ligada de kvm-01 para kvm-02:
# Storage local: copia os discos durante a migração
virsh migrate --live --persistent --copy-storage-all web-01 \
qemu+ssh://gean@kvm-02/system
# Ajustes finos
virsh migrate-setmaxdowntime web-01 300 # downtime máximo (ms) na troca final
virsh migrate-setspeed web-01 500 # banda máxima (MiB/s)
virsh domjobinfo web-01 # progresso da migração
Boas práticas:
--cpu host-passthrough exige processadores semelhantes; entre o x3550 M2 e o M4 (gerações Intel diferentes), prefira um modelo nomeado comum (ex.: host-model ou Westmere) nas VMs que migrarão;--persistent grava a definição no destino; sem ela a VM vira transitória (some ao desligar);--copy-storage-all — a migração passa a levar segundos.Antes de promover uma VM a template, remova identidade única (chaves SSH, machine-id, logs) — o build do Packer já faz isso no customizing-image.sh; manualmente seria:
sudo virt-sysprep -d debian13 \
--operations ssh-hostkeys,machine-id,logfiles,udev-persistent-net
forward mode='none'), como a rede docker do laboratório;nwfilter para anti-spoofing nas interfaces das VMs;virsh secret-define/secret-set-value guardam credenciais de storage (Ceph, iSCSI CHAP) fora do XML dos domínios.
undefineapaga a definição (com--nvramremove também as variáveis UEFI; sem--remove-all-storage, os discos permanecem).vol-delete,pool-destroyesnapshot-deletesão irreversíveis. Regra do laboratório:virsh dumpxmlpara arquivo antes de qualquerundefine, e snapshot/checkpoint antes de mudanças destrutivas no guest.
| Categoria | Comando | Descrição | Exemplo | Risco |
|---|---|---|---|---|
| Host/Hypervisor | nodeinfo |
CPU/memória do host | virsh nodeinfo |
Baixo |
| Host/Hypervisor | uri |
URI de conexão atual | virsh uri |
Baixo |
| Host/Hypervisor | capabilities |
Capacidades do hypervisor | virsh capabilities |
Baixo |
| Domain Management | list --all |
Listar domínios | virsh list --all |
Baixo |
| Domain Management | start |
Ligar VM | virsh start web-01 |
Baixo |
| Domain Management | shutdown |
Desligar gracioso (ACPI) | virsh shutdown web-01 |
Baixo |
| Domain Management | reboot |
Reiniciar gracioso | virsh reboot web-01 |
Baixo |
| Domain Management | destroy |
Corte de energia forçado | virsh destroy web-01 |
Alto |
| Domain Management | suspend / resume |
Pausar/retomar | virsh suspend web-01 |
Médio |
| Domain Management | save / restore |
Hibernar/restaurar RAM | virsh save web-01 f.save |
Médio |
| Domain Management | autostart |
Ligar com o host | virsh autostart web-01 |
Baixo |
| Domain Management | define |
Criar VM a partir de XML | virsh define vm.xml |
Médio |
| Domain Management | undefine |
Apagar definição da VM | virsh undefine web-01 --nvram |
Alto |
| Domain Management | console |
Console serial | virsh console web-01 |
Baixo |
| Domain Management | edit |
Editar XML com validação | virsh edit web-01 |
Médio |
| Domain Management | domrename |
Renomear VM | virsh domrename old new |
Médio |
| Domain Monitoring | dominfo |
Resumo do domínio | virsh dominfo web-01 |
Baixo |
| Domain Monitoring | domstate |
Estado atual | virsh domstate web-01 |
Baixo |
| Domain Monitoring | dumpxml |
XML completo | virsh dumpxml web-01 > web-01.xml |
Baixo |
| Domain Monitoring | domstats |
Estatísticas agregadas | virsh domstats web-01 |
Baixo |
| Domain Monitoring | domblklist / domiflist |
Discos / interfaces | virsh domblklist web-01 |
Baixo |
| Domain Monitoring | domblkstat / domifstat |
I/O de disco / rede | virsh domblkstat web-01 vda |
Baixo |
| Domain Monitoring | dommemstat |
Memória via balloon | virsh dommemstat web-01 |
Baixo |
| Domain Monitoring | domifaddr |
IPs da VM | virsh domifaddr web-01 |
Baixo |
| Domain Monitoring | cpu-stats |
Tempos de CPU | virsh cpu-stats web-01 |
Baixo |
| Domain Monitoring | domjobinfo |
Progresso de jobs (migração) | virsh domjobinfo web-01 |
Baixo |
| Snapshot | snapshot-create-as |
Criar snapshot | virsh snapshot-create-as web-01 s1 |
Médio |
| Snapshot | snapshot-list |
Listar snapshots | virsh snapshot-list web-01 |
Baixo |
| Snapshot | snapshot-revert |
Reverter a snapshot | virsh snapshot-revert web-01 s1 |
Alto |
| Snapshot | snapshot-delete |
Apagar snapshot | virsh snapshot-delete web-01 s1 |
Médio |
| Domain Checkpoint | checkpoint-create-as |
Checkpoint p/ backup incremental | virsh checkpoint-create-as web-01 c1 |
Médio |
| Networking | net-list --all |
Listar redes | virsh net-list --all |
Baixo |
| Networking | net-define / net-undefine |
Criar / apagar rede | virsh net-define rede.xml |
Médio |
| Networking | net-start / net-destroy |
Ativar / desativar rede | virsh net-start docker |
Médio |
| Networking | net-autostart |
Rede ativa com o host | virsh net-autostart docker |
Baixo |
| Networking | net-dumpxml / net-edit |
Ver / editar XML da rede | virsh net-edit default |
Médio |
| Networking | net-dhcp-leases |
Leases DHCP | virsh net-dhcp-leases default |
Baixo |
| Network Filter | nwfilter-list / nwfilter-define |
Filtros de tráfego | virsh nwfilter-list |
Médio |
| Storage Pool | pool-define-as |
Criar pool | virsh pool-define-as ... |
Médio |
| Storage Pool | pool-list --all |
Listar pools | virsh pool-list --all |
Baixo |
| Storage Pool | pool-start / pool-autostart |
Ativar pool | virsh pool-start default |
Baixo |
| Storage Pool | pool-refresh |
Re-escanear volumes | virsh pool-refresh default |
Baixo |
| Storage Pool | pool-destroy / pool-delete |
Desativar / apagar conteúdo | virsh pool-delete imagens |
Alto |
| Storage Volume | vol-create-as |
Criar volume | virsh vol-create-as default d.qcow2 32G |
Baixo |
| Storage Volume | vol-list / vol-info |
Listar / detalhar | virsh vol-info d.qcow2 default |
Baixo |
| Storage Volume | vol-resize |
Ampliar volume | virsh vol-resize d.qcow2 64G --pool default |
Médio |
| Storage Volume | vol-upload / vol-download |
Subir / baixar imagem | virsh vol-download d.qcow2 bkp.qcow2 |
Baixo |
| Storage Volume | vol-delete |
Apagar volume | virsh vol-delete d.qcow2 --pool default |
Alto |
| Dispositivos | attach-disk / detach-disk |
Hot-plug de disco | virsh attach-disk web-01 ... --live |
Médio |
| Dispositivos | attach-interface / detach-interface |
Hot-plug de NIC | virsh attach-interface web-01 network docker |
Médio |
| Dispositivos | attach-device / detach-device |
Dispositivo via XML (USB etc.) | virsh attach-device web-01 usb.xml |
Médio |
| Recursos | setvcpus |
Hot-plug de vCPUs | virsh setvcpus web-01 4 --live |
Médio |
| Recursos | setmem / setmaxmem |
Balloon / teto de RAM | virsh setmem web-01 6G --live |
Médio |
| Recursos | numatune |
Afinidade NUMA | virsh numatune web-01 --nodeset 0 |
Médio |
| Recursos | blockresize |
Expor novo tamanho ao guest | virsh blockresize web-01 vda 64G |
Médio |
| Migração | migrate |
Migrar VM (ao vivo) | virsh migrate --live web-01 qemu+ssh://... |
Alto |
| Migração | migrate-setmaxdowntime |
Downtime máximo | virsh migrate-setmaxdowntime web-01 300 |
Baixo |
| Migração | migrate-setspeed |
Limitar banda | virsh migrate-setspeed web-01 500 |
Baixo |
| Segredos | secret-define / secret-set-value |
Credenciais de storage | virsh secret-define s.xml |
Médio |
| Events | event |
Observar eventos de domínio | virsh event web-01 --all |
Baixo |
| Tarefa | Comando |
|---|---|
| VMs ativas em cada host | virsh list (e virsh list --all para as paradas) |
| Saúde de I/O de uma VM | virsh domblkstat web-01 vda && virsh domifstat web-01 vnet0 |
| IP de uma VM recém-criada | virsh domifaddr web-01 ou virsh net-dhcp-leases default |
| Snapshot antes de mudança | virsh snapshot-create-as web-01 pre-$(date +%F) |
| Ampliar disco | vol-resize → blockresize → growpart+resize2fs/xfs_growfs no guest |
| Backup da definição | virsh dumpxml web-01 > web-01.$(date +%F).xml |
| Logs de uma VM problemática | sudo journalctl -u libvirtd + /var/log/libvirt/qemu/web-01.log |
| Liberar host para manutenção | virsh migrate --live das VMs ativas para outro nó |