Configurar um endereço IP estático no Debian e no Ubuntu

Quatro dados sem os quais não deve começar

Um endereço estático escreve-se em poucos segundos. A razão pela qual, mesmo assim, tantos servidores ficam mudos depois do reinício quase nunca está na sintaxe: está em ter adivinhado um dos quatro dados de base em vez de o ter lido. São eles o nome da interface, o endereço com o respetivo comprimento de prefixo, o gateway e os nameservers. Leia estes valores com o sistema a funcionar, enquanto a máquina ainda está acessível.

ip -brief address show
ip -4 route show
ip -6 route show
cat /etc/resolv.conf

A primeira linha dá-lhe o nome da interface. Em servidores virtuais, chama-se ens3, enp1s0 ou eth0, consoante a plataforma; em bare metal é muitas vezes eno1. Copie o nome tal e qual, não o adivinhe. Um erro de escrita neste ponto produz uma configuração sintaticamente impecável que simplesmente não corresponde a nenhuma placa existente.

O comprimento do prefixo merece atenção especial. Muitos fornecedores encaminham um único endereço IPv4 com /32 para o servidor e, nesse caso, o gateway fica fora da própria sub-rede. Outros atribuem redes /24 clássicas. Qual dos casos se aplica descobre-se pelo caminho realmente utilizado:

ip route get 1.1.1.1

A seguir, crie uma cópia de segurança. Custa dez segundos e é a diferença entre um rollback e um ticket.

cp -a /etc/netplan /root/netplan.bak
cp -a /etc/network/interfaces /root/interfaces.bak

Que sistema controla a sua rede neste momento?

O Debian e o Ubuntu usam ferramentas diferentes, e a falha total mais frequente nasce de duas delas configurarem a mesma placa ao mesmo tempo. Comece por esclarecer o que está em uso:

ls -l /etc/netplan/
ls -l /etc/network/interfaces /etc/network/interfaces.d/
ls -l /etc/systemd/network/

A regra prática para as quatro versões atuais: o Ubuntu 24.04 e o Ubuntu 22.04 são configurados através do netplan, que por sua vez comanda o systemd-networkd em segundo plano. O Debian 13 e o Debian 12 chegam, depois de uma instalação padrão, com o ifupdown e o ficheiro /etc/network/interfaces. O systemd-networkd está presente no Debian, mas não ativo, e o netplan pode ser instalado a posteriori, embora não seja o caminho previsto.

Nas imagens de cloud junta-se ainda outra camada: no primeiro arranque, o cloud-init escreve um ficheiro próprio, tipicamente /etc/netplan/50-cloud-init.yaml ou, no Debian, um bloco em /etc/network/interfaces.d/. Quem edita esse ficheiro sem travar o cloud-init volta a encontrar a configuração antiga no reinício seguinte.

Ubuntu 24.04 e 22.04: endereço estático com netplan

O netplan lê todos os ficheiros em /etc/netplan/ por ordem alfabética e traduz o conteúdo em configuração para o systemd-networkd. Não crie um segundo ficheiro com a mesma interface: edite o que já existe ou desative o antigo de forma limpa. Uma configuração completa com IPv4 e IPv6 tem este aspeto:

network:
  version: 2
  renderer: networkd
  ethernets:
    ens3:
      dhcp4: false
      dhcp6: false
      accept-ra: false
      addresses:
        - 203.0.113.10/24
        - "2001:db8:1234::2/64"
      routes:
        - to: default
          via: 203.0.113.1
        - to: default
          via: "2001:db8:1234::1"
      nameservers:
        addresses: [9.9.9.9, 149.112.112.112, 2620:fe::fe]

Há três pontos que vale a pena explicar um a um.

Em primeiro lugar, as rotas predefinidas ficam em routes e já não em gateway4 ou gateway6. Estas duas chaves estão descontinuadas desde o netplan 0.103. Ainda funcionam no Ubuntu 22.04 e no Ubuntu 24.04, mas respondem a cada invocação com `gateway4` has been deprecated, use default routes instead. Quem escreve de raiz, escreve rotas.

Em segundo lugar, accept-ra: false desliga a configuração automática de IPv6. Se a deixar ligada enquanto atribui um endereço fixo, a placa acaba com dois endereços e duas rotas predefinidas, e quem ganha decide-se pela métrica, não pela sua intenção.

Em terceiro lugar, as permissões do ficheiro. Desde o netplan 0.106, cada invocação avisa quando o ficheiro YAML é legível por outros utilizadores: Permissions for /etc/netplan/01-static.yaml are too open. Netplan configuration should NOT be accessible by others. Isto não é cosmética, porque em ficheiros destes também constam chaves de WLAN e dados de túneis.

chmod 600 /etc/netplan/*.yaml

Quando o gateway fica fora da própria sub-rede

Num endereço encaminhado individualmente com /32, o kernel não conhece nenhum caminho direto até ao gateway e recusa a rota. No journal fica então Could not set route: Network is unreachable e, na tentativa manual com ip route add, a resposta é RTNETLINK answers: Network is unreachable. A solução chama-se on-link:

      addresses:
        - 203.0.113.10/32
      routes:
        - to: default
          via: 192.0.2.1
          on-link: true

No IPv6, o caso especial é a regra: muitas redes indicam como gateway o endereço link-local fe80::1. Como o netplan associa sempre as rotas a uma interface, basta via: "fe80::1" no bloco da placa em causa.

Silenciar o cloud-init

Se existir um ficheiro 50-cloud-init.yaml no diretório, coloque adicionalmente um bloqueio, caso contrário o seu trabalho é sobrescrito no arranque seguinte:

echo 'network: {config: disabled}' > /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg

netplan try: o comando que não o deixa fechado de fora

A ordem correta é verificar, testar, fixar. O netplan generate traduz os ficheiros YAML sem ativar nada e assinala erros de sintaxe de imediato. Só depois vem o teste propriamente dito.

netplan generate
netplan try --timeout 120
netplan apply

O netplan try aplica a nova configuração e repõe automaticamente a antiga se não premir a tecla Enter dentro do prazo. O valor predefinido é de 120 segundos. É exatamente por isso que num servidor remoto nunca se começa pelo netplan apply: um erro de escrita no endereço do gateway termina a sessão SSH e, sem uma rede de segurança, a coisa acaba na consola ou numa reinstalação.

Não confie cegamente na reversão. Estão documentados casos em que o netplan try não restabeleceu a ligação depois de esgotado o tempo, sobretudo ao editar o ficheiro gerado pelo cloud-init. Depois de uma reversão, verifique sempre se o ficheiro em disco está mesmo outra vez no estado anterior.

Para tudo aquilo que o netplan try não cobre (e para o Debian com ifupdown, onde este comando nem sequer existe), há um segundo cinto de segurança que se tem revelado útil: uma tarefa de limpeza que repõe a cópia de segurança caso não dê sinal de vida a tempo.

nohup sh -c 'sleep 300; cp -a /root/netplan.bak/. /etc/netplan/; netplan apply' >/dev/null 2>&1 &

Guarde o número de processo que aparece na saída. Se tudo funcionar, termine a tarefa com kill. Se já não conseguir entrar, ela repara o sistema sozinha ao fim de cinco minutos. Trabalhe além disso dentro do tmux ou do screen, para que uma sessão SSH interrompida não leve consigo o seu editor a meio da mudança.

Nos servidores root KVM resta como última instância a consola na área de cliente, através da qual chega ao sistema mesmo sem rede a funcionar. Em máquinas dedicadas, o caminho de volta é bastante mais trabalhoso, pelo que aí a rotina de precaução conta a dobrar.

Debian 13 e 12 com /etc/network/interfaces

Depois de uma instalação padrão, é o ifupdown que comanda a rede. A configuração é orientada a linhas e prevê blocos separados por família de endereços:

auto lo
iface lo inet loopback

auto ens3
iface ens3 inet static
    address 203.0.113.10/24
    gateway 203.0.113.1

iface ens3 inet6 static
    address 2001:db8:1234::2/64
    gateway 2001:db8:1234::1
    accept_ra 0

O auto ens3 vale para ambos os blocos, não precisa de uma segunda linha auto. Se o gateway ficar fora da sub-rede, aplica-se a mesma ideia do netplan, apenas formulada à mão:

iface ens3 inet static
    address 203.0.113.10/32
    post-up ip route add 192.0.2.1 dev ens3
    post-up ip route add default via 192.0.2.1
    pre-down ip route del default via 192.0.2.1

A maior armadilha no Debian não é a sintaxe, é a ativação. O systemctl restart networking baixa a placa por instantes e, se a nova configuração não aguentar, a sessão desaparece. O ifdown ens3 && ifup ens3 é ainda mais delicado, porque o ifup nunca chega a ser executado assim que a ligação cai logo no ifdown. Crie portanto primeiro a tarefa de limpeza descrita acima e só depois execute:

systemctl restart networking
systemctl status networking

Há duas mensagens com que se cruza regularmente. ifup: interface ens3 already configured significa que o ifupdown ainda contabiliza a placa como ativa, mesmo que talvez já não esteja; o estado consta em /run/network/ifstate. E Job for networking.service failed because the control process exited with error code é apenas a casca, porque o motivo verdadeiro está em journalctl -xeu networking e costuma ser uma rota predefinida atribuída duas vezes, com RTNETLINK answers: File exists.

DNS com o ifupdown

A linha óbvia dns-nameservers 9.9.9.9 no ficheiro só faz efeito se estiver instalado um intermediário que a transfira para /etc/resolv.conf, classicamente o pacote resolvconf. Sem esse intermediário, a entrada fica sem qualquer consequência, e isso só dá nas vistas quando os nomes deixam de resolver: Temporary failure in name resolution. Quem não quiser instalar mais nada mantém o /etc/resolv.conf diretamente e verifica com ls -l /etc/resolv.conf se o ficheiro é um symlink, ou seja, se é gerido por outro serviço.

Utilizar o Debian com systemd-networkd

Quem num servidor Debian já usa de qualquer forma as ferramentas do systemd, ou gere muitas interfaces e túneis, fica mais consistente com o systemd-networkd. A mudança tem três passos: criar a configuração, ativar o novo serviço, desativar o antigo.

[Match]
Name=ens3

[Network]
Address=203.0.113.10/24
Address=2001:db8:1234::2/64
Gateway=203.0.113.1
Gateway=2001:db8:1234::1
DNS=9.9.9.9
DNS=2620:fe::fe
IPv6AcceptRA=no

Este ficheiro pertence a /etc/systemd/network/10-ens3.network. Para um gateway fora da sub-rede, acrescente um bloco de rota próprio:

[Route]
Gateway=192.0.2.1
GatewayOnLink=yes

Depois vem a comutação, de preferência outra vez com a tarefa de limpeza a cobrir-lhe as costas:

systemctl enable --now systemd-networkd
systemctl disable networking
networkctl status ens3

A saída do networkctl status é o retorno mais honesto que este tema tem para oferecer. Se aí aparecer State: routable (configured), o serviço aceitou o ficheiro e pô-lo em prática. Se aparecer configuring ou degraded, tentou e falhou, independentemente de o comando de arranque ter regressado sem erros.

A parte do DNS é autónoma no Debian: o systemd-networkd só inscreve nameservers na resolução se o systemd-resolved estiver a correr e o /etc/resolv.conf apontar para o ficheiro dele.

apt-cache policy systemd-resolved

Esta consulta depende da versão e engana de uma forma pouco vistosa. Um pacote autónomo systemd-resolved só existe a partir do Debian 12 e do Ubuntu 24.04, e aí o comando indica uma versão. No Ubuntu 22.04, pelo contrário, o serviço ainda está dentro do próprio pacote systemd e, nesse caso, o comando corre sem erros mas não devolve absolutamente nada. Uma instalação falha então com Unable to locate package systemd-resolved. A saída vazia não quer portanto dizer que falta o resolver, mas sim que o pacote não existe nessa versão. Em sistemas mais antigos, como o Debian 11, passa-se exatamente o mesmo. Nessas versões, verifique antes:

apt-cache policy systemd
systemctl status systemd-resolved

O serviço ativa-se com systemctl enable --now systemd-resolved e, a seguir, o symlink habitual aponta para /run/systemd/resolve/stub-resolv.conf. Quem não quiser isso dispensa o systemd-resolved e escreve os nameservers de forma estática em /etc/resolv.conf. O que não deve fazer: as duas coisas pela metade.

Integrar endereços IP adicionais

Os endereços adicionais não são um caso especial, são simplesmente mais uma entrada. No netplan, a lista cresce:

      addresses:
        - 203.0.113.10/24
        - 203.0.113.11/24
        - 203.0.113.12/24
        - "2001:db8:1234::2/64"
        - "2001:db8:1234::3/64"

No systemd-networkd escreve várias linhas Address= umas por baixo das outras. No ifupdown, complete a definição existente em vez de criar uma segunda:

iface ens3 inet static
    address 203.0.113.10/24
    gateway 203.0.113.1
    post-up ip addr add 203.0.113.11/24 dev ens3
    post-up ip addr add 203.0.113.12/24 dev ens3
    pre-down ip addr del 203.0.113.11/24 dev ens3
    pre-down ip addr del 203.0.113.12/24 dev ens3

A grafia antiga com ens3:0 continua a funcionar, mas é uma relíquia do tempo anterior à ferramenta ip. Não cria dispositivos adicionais reais, apenas designações, e nas regras de firewall gera mais confusão do que utilidade.

Há três coisas que costumam correr mal com os endereços adicionais. A primeira: o endereço não está atribuído do lado do servidor. Nenhuma configuração de sistema operativo do mundo põe a funcionar um IP que não esteja encaminhado para o seu servidor, pelo que a consulta à área de cliente é o primeiro passo e não o último. A segunda: um segundo endereço da mesma rede não leva uma segunda rota predefinida. Uma segunda entrada de gateway padrão traz-lhe RTNETLINK answers: File exists ou, pior ainda, caminhos de resposta que mudam. A terceira: no IPv6 é quase sempre o /64 completo que está encaminhado para o servidor, ou seja, pode escolher livremente dentro dessa gama, mas apenas o endereço indicado pelo fornecedor é realmente necessário como endereço de interface configurado.

Para saber se um endereço adicional funciona mesmo para o exterior, teste de forma dirigida a partir do ponto de origem:

ping -c 3 -I 203.0.113.11 1.1.1.1

Como reconhecer que ficou mesmo bem

O facto de um comando ter corrido sem mensagem de erro diz pouco sobre o estado da rede. Estas cinco verificações dizem alguma coisa:

1. O endereço está na placa certa: ip -brief address show mostra exatamente os endereços pretendidos e nenhum resto da configuração antiga.
2. O caminho para o exterior está correto, incluindo o endereço de origem: ip route get 1.1.1.1 indica o gateway esperado e o src esperado.
3. O IPv6 tem uma rota predefinida própria: ip -6 route show default não pode estar vazio, caso contrário tudo passa silenciosamente por IPv4.
4. A resolução de nomes funciona independentemente da acessibilidade: getent hosts deb.debian.org devolve um endereço, não apenas silêncio.
5. O único teste verdadeiro é um reinício. Só depois dele sabe se a configuração vem do ficheiro ou ainda da memória.

No Ubuntu, o netplan status --all dá ainda um resumo compacto e, no systemd-networkd, o networkctl status faz o mesmo. Em caso de dúvida, ambos mostram que um endereço consta do ficheiro mas nunca chegou a ser assumido.

Mensagens de erro na íntegra

As quatro distribuições em comparação direta

Se puser a firewall em funcionamento logo a seguir à configuração de rede, tenha em atenção que as regras para o novo endereço e para o IPv6 valem em separado. Como montar isso de forma limpa está no nosso guia sobre o UFW em Debian e Ubuntu e, para proteger o acesso depois disso, em proteger o servidor SSH.

Resumo para o próximo servidor

Ler os valores em vez de os adivinhar, criar uma cópia de segurança, escrever a configuração, testar com o netplan try ou com uma tarefa de limpeza própria, fixar, reiniciar e só então dar por concluído. Quem cumpre esta ordem perde, no pior dos casos, cinco minutos. Quem a encurta perde, no pior dos casos, o servidor até alguém se sentar à consola.