Executar e verificar um nó AeroNyx

Este runbook reúne os comandos do dia a dia para um nó AeroNyx registrado: status, saúde, logs, provas de relay e de caixa postal, atualizações seguras, rollback e o que verificar depois de uma reinicialização. Todos os comandos estão no repositório do nó (deploy/node/aeronyx-node.sh e o binário aeronyx-server) e são mostrados com as opções que o código aceita.

Se você ainda não instalou um nó, comece por Instalar e registrar um nó AeroNyx.

Antes de começar

Execute tudo a partir de um shell de root (sudo -i). O diretório de configuração /etc/aeronyx e o diretório de estado /var/lib/aeronyx têm modo 700, então os comandos de status, saúde, validação e relay não conseguem lê-los como outro usuário.

Entre no repositório a partir do qual o serviço realmente roda e passe-o com --repo-dir em todos os comandos do script. Sem --repo-dir, o script assume /opt/aeronyx/AeroNyx.

cd "$(systemctl show aeronyx-server -p WorkingDirectory --value)"
pwd

Em nós instalados com o comando do Nodeboard, isso imprime /root/open/AeroNyx.

Comandos em resumo

Status

./deploy/node/aeronyx-node.sh status --repo-dir "$PWD"

status imprime, nesta ordem:

1. systemctl status aeronyx-server (últimas 20 linhas)
2. um resumo da API local de saúde (http://127.0.0.1:8421/api/vpn/health) e da API de status do operador (http://127.0.0.1:8421/api/operator/status)
3. a prontidão local da descoberta a partir de http://127.0.0.1:8422/api/discovery/status: anúncio do ChatRelay e quórum de pares
4. o estado do último fluxo de atualização a partir de /var/lib/aeronyx/upgrade-status.json
5. uma recomendação ao operador: operator_status, operator_title, operator_detail e operator_next_step

A recomendação vem da verificação de saúde. O seu status é um dos seguintes:

Saúde

./deploy/node/aeronyx-node.sh health --repo-dir "$PWD" --json

A verificação de saúde lê arquivos, o systemd e os endpoints locais; ela nunca altera o host. Cada verificação imprime [PASS], [WARN] ou [FAIL], depois uma linha [SUMMARY] pass=… warn=… fail=… e, em seguida, uma linha de JSON. Use --json-only para imprimir somente o JSON. O comando sai com status diferente de zero se alguma verificação falhar.

O que ela verifica: o repositório, o Cargo.lock rastreado e o binário de release; a validação da configuração com aeronyx-server validate; os arquivos de registro e de chave; a unidade systemd, a política de reinicialização e o hardening; memória, disco e as portas 51820 e 8421; encaminhamento de IP e NAT; o endpoint local de saúde; a descoberta; e os backups de versões.

Principais campos do JSON:

Você pode ler os endpoints locais brutos diretamente:

curl -s http://127.0.0.1:8421/api/vpn/health
curl -s http://127.0.0.1:8422/api/discovery/status

Logs

./deploy/node/aeronyx-node.sh logs --repo-dir "$PWD" --lines 200
./deploy/node/aeronyx-node.sh logs --repo-dir "$PWD" --follow

Eles encapsulam journalctl -u aeronyx-server -n <lines> --no-pager (padrão de 160 linhas) e journalctl -u aeronyx-server -f. Use journalctl diretamente para intervalos de tempo, por exemplo journalctl -u aeronyx-server --since "1 hour ago".

Provas de relay e de caixa postal

Estes comandos respondem a perguntas diferentes. Não trate uma sonda sintética aprovada como prova de entrega real.

relay-probe (sintético)

./deploy/node/aeronyx-node.sh relay-probe --repo-dir "$PWD" --json
./deploy/node/aeronyx-node.sh relay-probe --repo-dir "$PWD" --two-hop --json

Envia um envelope BlindRelay sintético, aleatório e opaco deste nó para um par ChatRelay descoberto e reporta apenas variações de contadores. --two-hop o envia por um salto intermediário até um nó terminal. O status do resultado é ok, attention, blocked ou error, e two_hop_readiness explica o que está faltando quando um caminho de dois saltos não é possível. Ele lê o cache de pares e a chave do nó, por isso precisa de root. Não é tráfego de usuário e não prova a entrega na caixa postal. fleet-smoke executa uma verificação sintética semelhante em vários nós públicos que você lista com --endpoints.

relay-smoke (autenticado, de ponta a ponta)

./target/release/aeronyx-server relay-smoke --confirm-live-relay-smoke --json

relay-smoke age como um cliente real contra o nó deste host. Ele abre duas sessões de curta duração com identidades descartáveis e conclui o handshake de produção, fixado à chave deste nó. Ele envia uma mensagem aleatória de 48 bytes, com criptografia de ponta a ponta, pelo caminho de relay autenticado de múltiplos saltos. Em seguida, verifica o recibo terminal assinado para essa solicitação exata, puxa a mensagem da caixa postal deste nó, a descriptografa, a confirma e verifica se a caixa postal está vazia e se as sessões foram encerradas.

Ele se recusa a iniciar a menos que todos os critérios sejam atendidos:

Observações:

• Ele precisa rodar como root no próprio nó. Ele lê /etc/aeronyx/server.toml e a chave do nó, e aceita somente endereços de loopback (--server, padrão 127.0.0.1:51820; --health-url, padrão http://127.0.0.1:8421/api/vpn/health).
• --timeout-seconds define a janela da prova: de 5 a 120 segundos, padrão 30.
• Zero sessões ativas significa que um nó que atende usuários de VPN precisa ser drenado antes. Ative o Maintenance Mode no Nodeboard e espere as sessões chegarem a zero.
• As duas sessões de teste são sessões reais do protocolo, então podem aparecer brevemente em Sessions no Nodeboard.
• Uma aprovação tem "status": "passed", com terminal_receipt_observed, entry_mailbox_round_trip_verified, entry_mailbox_ack_verified e e2e_ciphertext_verified todos true, e session_cleanup é explicit_authenticated_close. terminal_replica_cleanup é node_ttl_managed: confirmar no nó de entrada não exclui a cópia mantida pelo nó terminal, que expira por conta própria.
• Qualquer critério não atendido, erro ou campo ausente é uma prova que falhou, não um sucesso parcial.

mailbox-probe (originado no cliente)

./target/release/aeronyx-server mailbox-probe \
  --seed http://SEED_PUBLIC_IP:8422 \
  --target <64-hex node ID of the mailbox node> \
  --entry <64-hex node ID of a different entry node> \
  --confirm-live-mailbox-probe --json

mailbox-probe se comporta como um aplicativo: usa chaves descartáveis, monta a sua própria rota onion a partir de descritores assinados coletados dos nós --seed e envia HTTP simples para a API entre pares pública do nó de entrada, sem sessão de VPN. Ele executa o ciclo de vida completo da caixa postal anônima no nó de destino: ticket_issue, lease_create, put, pull_one, ack e um pull_one final. Ele verifica se os bytes puxados coincidem e se a caixa postal fica vazia depois. Uma aprovação reporta "status": "verified" e o número de saltos.

• --seed pode ser repetido. Sem --entry, a rota tem um salto.
• Um ID de nó é a chave pública do nó em hexadecimal, com 64 caracteres. Em um nó que você opera, ./target/release/aeronyx-server pubkey -c /etc/aeronyx/server.toml o imprime.
• O destino precisa ter a caixa postal anônima ativada ([memchain.chat_relay.anonymous_mailbox] enabled = true); ela vem desativada por padrão.
• --work-bits (padrão 12) precisa ser pelo menos igual à configuração de trabalho de ticket do destino. --timeout-seconds vale por solicitação (padrão 20).
• Ele não lê arquivos locais do nó, então pode rodar a partir de qualquer máquina que tenha o binário. Ele prova a custódia de um item opaco, não que um destinatário consiga descriptografá-lo.

Atualizar com segurança

Use o fluxo de atualização, não git pull seguido de systemctl restart:

./deploy/node/aeronyx-node.sh upgrade --repo-dir "$PWD" --build-priority live --build-jobs auto

O que ele faz:

1. Obtém uma trava de implantação e se recusa a rodar se arquivos rastreados no checkout tiverem sido modificados (--allow-dirty ignora essa trava).
2. Puxa main (ou compila um commit exato em um checkout isolado com --commit <40-hex SHA>).
3. Compila com o toolchain Rust fixado pelo repositório. A prioridade live (o padrão) e --build-jobs auto usam cerca de metade das CPUs para que o nó em execução continue atendendo.
4. Valida /etc/aeronyx/server.toml com o novo binário. O arquivo de configuração nunca é sobrescrito.
5. Faz backup do binário que está realmente em execução em /var/lib/aeronyx/releases/.
6. Verifica as sessões ativas depois da compilação e novamente logo antes da reinicialização. Se houver alguma, ou se a contagem não puder ser lida enquanto o serviço roda, ele para sem trocar de versão.
7. Atualiza as unidades systemd, coloca o novo binário no lugar e reinicia o serviço.
8. Espera até 180 segundos (90 verificações, com 2 segundos de intervalo) até que a saúde local reporte ok a partir do commit que acabou de compilar. Se a reinicialização, o estado do serviço ou a verificação de saúde falhar, ele restaura automaticamente o binário e as unidades anteriores.
9. Mantém os 10 backups mais recentes de cada tipo e registra o resultado em /var/lib/aeronyx/upgrade-status.json.

Se o nó tiver sessões ativas, a compilação ainda é executada e, em seguida, a atualização para com Active sessions appeared during compilation. Enter maintenance mode, drain sessions, and run the upgrade again. Ative o Maintenance Mode em Settings no Nodeboard, espere as sessões ativas chegarem a zero e execute o mesmo comando novamente. A recompilação reutiliza o cache.

Preparar agora, reiniciar depois

./deploy/node/aeronyx-node.sh upgrade --repo-dir "$PWD" --no-restart

--no-restart compila, valida e faz backup e, em seguida, instala o novo binário em disco sem reiniciar. Depois disso, status reporta upgrade_staged. O processo em execução mantém a versão antiga. Qualquer reinicialização posterior, incluindo um reboot ou uma reinicialização automática após uma falha, inicia o novo binário.

Para fazer a troca em uma janela de manutenção, drene o nó e execute a atualização novamente sem puxar, para que ela troque exatamente para o que você preparou, com a verificação de sessões, a espera pela saúde e o rollback:

./deploy/node/aeronyx-node.sh upgrade --repo-dir "$PWD" --skip-pull

Não use --force. Ele reinicia mesmo quando há sessões ativas ou a contagem de sessões é desconhecida, e desconecta os usuários.

Rollback manual

A atualização faz rollback automaticamente quando a nova versão não consegue iniciar ou reportar que está saudável. Para voltar a uma versão anterior mais tarde, promova um dos binários salvos:

ls -lt /var/lib/aeronyx/releases/
./deploy/node/aeronyx-node.sh promote-binary --repo-dir "$PWD" \
  --binary /var/lib/aeronyx/releases/<aeronyx-server.binary.YYYYMMDD_HHMMSS.xxxxxx>

promote-binary valida a configuração com o binário escolhido e se recusa a rodar a menos que as sessões ativas sejam exatamente zero. Ele pede que você digite PROMOTE BINARY, faz backup do binário atual ao lado dele, troca o binário e reinicia. Se o serviço não ficar saudável em 180 segundos, ele restaura o binário anterior. Ele substitui somente o binário, não as unidades systemd.

Depois de qualquer reinicialização

Verifique estes itens, nesta ordem:

1. systemctl is-active aeronyx-server retorna active. A unidade é Type=notify, então active significa que o processo reportou estar pronto; a inicialização pode levar até 300 segundos antes que o systemd desista.
2. ./deploy/node/aeronyx-node.sh status --repo-dir "$PWD" mostra operator_status=ok ou um aviso que você entende.
3. ./deploy/node/aeronyx-node.sh health --repo-dir "$PWD" --json termina com "success":true e local_vpn_health.status é ok.
4. O commit em execução é o que você pretendia: curl -s http://127.0.0.1:8421/api/vpn/health o reporta como runtime.git_commit. (O runtime.git_commit em health --json é o commit do checkout.)
5. discovery_readiness.peer_quorum.quorum_ready é true após as primeiras rodadas de gossip.
6. Para nós de relay: relay-probe --two-hop --json reporta ok.
7. No Nodeboard, o heartbeat está recente, Rust Runtime mostra a nova versão e a reinicialização aparece em Alerts / Events. Desative o Maintenance Mode quando terminar.
8. journalctl -u aeronyx-server --since "15 min ago" não tem erros repetidos.

Como isso aparece no Nodeboard

O Nodeboard recebe o heartbeat assinado e os relatórios de sessão do nó. Ele não executa comandos no host por conta própria; as ações que você escolhe ali entram em uma fila e o nó as executa no próximo heartbeat.

Os detalhes do nó também têm um cartão Operator Runbook com comandos copiáveis de health, status, logs e atualização preparada para o caminho de repositório detectado.

O que as saídas contêm

status, health, relay-probe, relay-smoke e mailbox-probe imprimem apenas valores agregados: contagens, estados, tempos e códigos de motivo. Eles não imprimem chaves privadas, códigos de registro, IPs públicos de clientes, destinos, conteúdo de DNS, payloads nem texto puro de mensagens. Os registros de sessão com chaves de clientes ficam visíveis no Nodeboard, não nessas saídas; consulte o Guia do console do operador Nodeboard. Ao compartilhar saídas com o suporte, compartilhe o JSON e o seu carimbo de data e hora, não endereços de host nem credenciais.

Perguntas frequentes

Qual comando devo executar primeiro quando algo parece errado?

Execute ./deploy/node/aeronyx-node.sh status --repo-dir "$PWD" como root. Ele mostra o estado do serviço, a saúde local, a descoberta e a próxima etapa recomendada, e não altera o host.

Por que a verificação de saúde falha com "config missing" ou avisos do Git?

Provavelmente você não é root ou está apontando para o repositório errado. /etc/aeronyx e /var/lib/aeronyx são acessíveis somente ao root e, sem --repo-dir, o script verifica /opt/aeronyx/AeroNyx em vez do checkout a partir do qual o serviço roda.

Qual é a diferença entre relay-probe e relay-smoke?

relay-probe envia um envelope opaco sintético e só mostra que um caminho de relay aceita tráfego. relay-smoke age como um cliente real: verifica um recibo terminal assinado e um ciclo completo de pull e confirmação na caixa postal para uma mensagem de teste criptografada.

Por que o relay-smoke diz que precisa de zero sessões ativas?

Ele atribui as variações de contadores às suas próprias sessões de teste, por isso só roda em um nó ocioso. Ative o Maintenance Mode no Nodeboard, espere as sessões ativas chegarem a zero e, então, execute-o.

Posso atualizar sem desconectar os usuários?

Você pode compilar e preparar uma atualização com --no-restart enquanto os usuários estão conectados. A troca para a nova versão exige uma reinicialização, então drene o nó com o Maintenance Mode e depois execute upgrade --skip-pull.

Como volto para a versão anterior?

Uma atualização que falha faz rollback automaticamente. Para fazer rollback mais tarde, use promote-binary com um dos backups em /var/lib/aeronyx/releases/; ele exige zero sessões ativas e restaura o binário anterior se o binário promovido não estiver saudável.