Instalando a imagem em um equipamento que já executa OpenWrt

Objetivo

Nesta etapa vamos instalar no TP-Link EAP225-Outdoor v3 a imagem personalizada construída nos tutoriais anteriores.

O equipamento utilizado nesta reprodução já executava OpenWrt antes do teste. Por isso, o procedimento descrito aqui utiliza o mecanismo de atualização sysupgrade.

A instalação inicial de OpenWrt em um equipamento que ainda executa a firmware original do fabricante é outro procedimento. Ela depende do modelo, da revisão de hardware e dos mecanismos de instalação disponíveis em cada equipamento e será tratada em um tutorial específico.

Este tutorial é, portanto, voltado principalmente para atualizar pelo terminal um equipamento que já executa:

• OpenWrt;
• LibreMesh;
• ou outra firmware derivada de OpenWrt que mantenha compatibilidade com sysupgrade.

Importante: isso não significa que qualquer firmware possa ser substituída diretamente por qualquer imagem sysupgrade. O modelo, a revisão de hardware e o target da imagem precisam ser compatíveis.

Embora LuCI e outras interfaces possam oferecer mecanismos gráficos de atualização, aqui utilizamos o terminal porque ele torna explícitos os passos de identificação do hardware, conferência do arquivo, teste de compatibilidade e escolha sobre a preservação das configurações.

1. Confirme o equipamento antes de atualizar

Acesse o roteador por SSH e registre as informações do sistema atual:

ubus call system board
cat /etc/openwrt_release
cat /etc/os-release

Confirme principalmente:

• fabricante e modelo;
• revisão de hardware;
• versão atual do OpenWrt ou da firmware derivada;
• target e subtarget, quando disponíveis.

No caso desta reprodução, o destino da imagem é:

TP-Link EAP225-Outdoor v3
ath79 / generic
OpenWrt 24.10.7

A atualização só deve prosseguir depois de confirmar que o arquivo sysupgrade.bin foi produzido para esse equipamento.

2. Localize a imagem sysupgrade

No computador onde a firmware foi compilada:

cd ~/openwrt/bin/targets/ath79/generic
ls -lh *eap225-outdoor-v3*sysupgrade.bin

Para a atualização de um OpenWrt já existente, utilizamos a imagem cujo nome termina em:

squashfs-sysupgrade.bin

A imagem factory.bin é destinada a outro tipo de instalação e não deve ser intercambiada automaticamente com a imagem sysupgrade.bin.

3. Confira o hash antes da transferência

No diretório dos artefatos:

sha256sum *eap225-outdoor-v3*sysupgrade.bin

Se o arquivo sha256sums estiver disponível, também é possível localizar somente a linha correspondente:

grep 'eap225-outdoor-v3.*sysupgrade.bin' sha256sums

Registre o valor obtido.

4. Transfira a imagem para o roteador

Envie o arquivo para /tmp/ no equipamento:

scp openwrt-ath79-generic-tplink_eap225-outdoor-v3-squashfs-sysupgrade.bin \
  root@IP_DO_ROTEADOR:/tmp/

Depois entre novamente no roteador:

ssh root@IP_DO_ROTEADOR

Confira se o arquivo chegou:

ls -lh /tmp/*sysupgrade.bin
sha256sum /tmp/*sysupgrade.bin

O hash deve ser igual ao registrado no computador de compilação.

Se apenas os binários tiverem sido copiados para outro diretório, sha256sum -c sha256sums pode acusar como ausentes outros arquivos listados no conjunto original. Para esta etapa, compare especificamente o hash da imagem que será instalada.

5. Teste a compatibilidade antes de gravar

Antes de iniciar a atualização:

sysupgrade -T /tmp/openwrt-ath79-generic-tplink_eap225-outdoor-v3-squashfs-sysupgrade.bin

O parâmetro -T pede ao sysupgrade que teste a imagem sem iniciar a gravação.

Se a verificação falhar, não force a instalação até compreender a causa.

6. Decida se a configuração antiga deve ser preservada

Uma atualização normal pode preservar arquivos de configuração. Em uma bancada de homologação, entretanto, isso pode mascarar problemas ao carregar ajustes de uma firmware anterior.

Nesta reprodução escolhemos uma instalação limpa, sem preservar a configuração existente:

sysupgrade -n /tmp/openwrt-ath79-generic-tplink_eap225-outdoor-v3-squashfs-sysupgrade.bin

A opção -n impede que as configurações antigas sejam mantidas.

Isso é especialmente útil quando o equipamento vinha de outra versão de OpenWrt ou de LibreMesh e queremos verificar o comportamento da imagem recém-construída sem heranças do sistema anterior.

Em um roteador em produção, -n pode apagar endereços, credenciais, VLANs, parâmetros de rádio e outras configurações necessárias. Faça backup antes de usar essa opção fora de uma bancada de testes.

7. Aguarde a reinicialização

Após executar sysupgrade, a sessão SSH será encerrada.

Durante a gravação:

• não desligue o equipamento;
• não remova a alimentação PoE;
• não reinicie manualmente;
• aguarde o equipamento completar o boot.

O endereço IP usado anteriormente pode deixar de responder depois de uma instalação limpa.

Isso não significa necessariamente que a atualização falhou. A nova firmware pode gerar outra configuração de rede ou outro endereço para o nó.

8. Confirme o novo sistema depois do boot

Depois de recuperar o acesso:

ubus call system board
cat /etc/openwrt_release
cat /etc/os-release
ip addr

Na reprodução documentada, o EAP225-Outdoor v3 iniciou corretamente com OpenWrt 24.10.7 e a configuração do LibreMesh foi criada.

A inspeção detalhada do equipamento, das interfaces, dos rádios e da malha é feita no tutorial seguinte, Teste de bancada da imagem no EAP225-Outdoor v3.

Resultado desta etapa

O fluxo validado foi:

EAP225-Outdoor v3 já executando OpenWrt
        ↓
imagem sysupgrade compatível
        ↓
transferência para /tmp
        ↓
conferência do hash
        ↓
sysupgrade -T
        ↓
sysupgrade -n
        ↓
reinicialização
        ↓
nova imagem inicia no equipamento

Esta etapa valida a atualização a partir de um sistema OpenWrt já instalado.

A primeira instalação a partir da firmware original do fabricante não foi realizada aqui e será documentada separadamente.