Gerenciando guests KVM com virsh: listar, iniciar, shutdown versus destroy e autostart

Objetivo

Inspecionar, iniciar, parar e configurar o autostart de guests KVM gerenciados pelo libvirt, usando o virsh, sem corromper a definição persistente do domínio.

Pré-requisitos

Acesso como root ou pertencer ao grupo libvirt no host do hypervisor, com o serviço libvirtd (ou virtqemud, ativado por socket) em execução. Quando executado como root, o virsh conecta-se a qemu:///system; quando executado por um usuário comum, usa por padrão o qemu:///session privado desse usuário (a menos que LIBVIRT_DEFAULT_URI ou a configuração do cliente indiquem outra coisa), e esse URI não mostra os guests do sistema. Informe -c qemu:///system explicitamente e confirme com virsh uri.

Passos

1. Liste os guests: virsh list --all mostra todos os domínios definidos e o respectivo estado (running, shut off, paused). O comando virsh list sozinho mostra apenas os que estão em execução.
2. Inspecione um guest: virsh dominfo <name> exibe estado, número de CPUs, memória, flag de autostart e persistência. virsh domstate <name> exibe apenas o estado.
3. Inicie um guest que está definido, mas parado: virsh start <name>.
4. Parada graciosa: virsh shutdown <name> pede ao sistema operacional do guest que se desligue e retorna imediatamente; o sucesso não é garantido e o tempo necessário pode variar. Com o QEMU, o hypervisor escolhe o método (normalmente um evento de botão de energia ACPI, que o SO do guest precisa tratar); --mode agent usa o QEMU guest agent, se houver um em execução no guest. Consulte virsh domstate <name> repetidamente até que o estado seja shut off.
5. Parada forçada: virsh destroy <name> encerra o domínio imediatamente, sem dar ao SO do guest nenhuma chance de reagir, o que equivale a puxar o cabo de energia; escritas do guest ainda não gravadas em disco podem ser perdidas. Use-o somente quando o shutdown não for concluído após uma espera razoável. Ele não apaga nenhum disco, e um domínio persistente pode ser iniciado novamente; já um domínio transiente desaparece depois de parado, junto com os metadados de seus snapshots.
6. Ative ou desative a inicialização de um domínio persistente junto com o boot do host: virsh autostart <name> (o libvirt inicia o guest quando o host dá boot) e virsh autostart --disable <name> para remover essa configuração.
7. Acesso ao console: virsh console <name> conecta-se a um console serial definido no XML do guest (exige um dispositivo <console type='pty'> e um getty configurado dentro do guest); saia com Ctrl+].
8. As definições de domínio ficam em XML em /etc/libvirt/qemu/<name>.xml; não edite esses arquivos manualmente, pois o libvirt não reconhece tais edições. Use virsh edit <name>, que abre a definição persistente (inativa) em $VISUAL/$EDITOR, verifica erros e redefine o domínio ao salvar; em um guest em execução, a mudança só tem efeito no próximo boot. Faça antes um backup com virsh dumpxml --inactive <name> > <name>.xml; virsh dumpxml <name> mostra a definição em execução.

Resultado esperado

virsh dominfo <name> reflete imediatamente o novo estado ou a nova configuração de autostart; virsh list --all mostra shut off após um destroy ou depois que um shutdown foi concluído (não necessariamente quando o virsh shutdown retorna).

Limites e base de verificação

O comportamento depende de o SO do guest reagir ao pedido de desligamento; um guest que não trata o evento de botão de energia ACPI (por exemplo, uma imagem mínima sem nenhum processo escutando esse evento, ou um guest Windows cuja política do botão de energia está definida para não fazer nada) não responderá e exigirá um desligamento de dentro do guest, --mode agent ou destroy. Este módulo não cobre a instalação do libvirt nem a configuração de redes ou storage pools, além do que foi citado.