Validação, troubleshooting e rotina de mudanças seguras no Apache

Rotina de mudanças seguras: editar, validar e aplicar

Uma rotina de mudanças seguras no Apache reduz indisponibilidade e evita “quebrar” múltiplos sites por um erro pequeno. A ideia é sempre: (1) preparar a alteração, (2) validar sintaxe e coerência, (3) aplicar com o menor impacto possível, (4) verificar rapidamente o resultado, (5) se necessário, reverter com rapidez.

Checklist rápido antes de mexer

• Identifique o arquivo exato que será alterado (ex.: arquivo do vhost, include, arquivo de TLS).
• Garanta um ponto de retorno: copie o arquivo atual para um backup com data.
• Tenha um comando de validação pronto (configtest) e um plano de aplicação (reload vs restart).
• Tenha um método de verificação pós-mudança: checar vhosts ativos, portas em escuta, firewall local e logs.

Backup e edição com segurança

Antes de editar, faça uma cópia do arquivo. Isso permite rollback imediato caso o reload falhe ou o site apresente comportamento inesperado.

# Exemplo (ajuste o caminho do arquivo do vhost conforme sua distro) sudo cp /etc/apache2/sites-available/meusite.conf /etc/apache2/sites-available/meusite.conf.bak-$(date +%F-%H%M) sudo nano /etc/apache2/sites-available/meusite.conf

Se você usa controle de versão (Git) para /etc, o princípio é o mesmo: commit pequeno e descritivo antes e depois da mudança.

Validar sintaxe: apachectl configtest

O teste de sintaxe detecta erros como diretivas inválidas, chaves faltando, includes quebrados e problemas básicos de parsing. Ele não garante que a lógica do vhost está correta, mas evita o erro mais comum: “Apache não sobe por erro de config”.

# Debian/Ubuntu (geralmente) sudo apache2ctl configtest # RHEL/CentOS/Alma/Rocky (geralmente) sudo apachectl configtest

Saída esperada quando está OK:

Continue em nosso aplicativo e ...

• Ouça o áudio com a tela desligada
• Ganhe Certificado após a conclusão
• + de 5000 cursos para você explorar!

ou continue lendo abaixo...

Baixar o aplicativo

Syntax OK

Se houver erro, a mensagem costuma apontar arquivo e linha. Corrija e rode novamente até ficar OK.

Aplicar mudança: reload vs restart

Escolher entre reload e restart é parte da rotina segura:

• reload: recarrega a configuração sem derrubar o processo principal de forma abrupta. Em geral, é a opção preferida para aplicar mudanças de config com menor impacto.
• restart: reinicia o serviço. Pode interromper conexões ativas e é mais disruptivo. Use quando necessário (por exemplo, após certas mudanças de módulos/MPM, ou quando o reload não aplica como esperado).

# systemd sudo systemctl reload apache2   # Debian/Ubuntu sudo systemctl reload httpd     # RHEL-like # se precisar reiniciar sudo systemctl restart apache2 sudo systemctl restart httpd

Depois de aplicar, confirme o estado do serviço:

sudo systemctl status apache2  # ou httpd

Verificar quais vhosts estão ativos

Quando um site “não responde”, frequentemente o vhost esperado não está carregado, está sendo sombreado por outro, ou o ServerName/ServerAlias não está casando com o Host do request.

# Lista vhosts carregados e a ordem de matching sudo apachectl -S

O que observar na saída:

• Qual vhost está como default em cada IP:porta.
• Se o ServerName e ServerAlias do site aparecem como esperado.
• Se há warnings de ServerName global não definido (não é fatal, mas atrapalha diagnóstico).

Checar portas em escuta e conflitos

Se o Apache não está atendendo em uma porta, verifique se o processo está escutando e se não há conflito com outro serviço.

# Ver portas em escuta e processo dono sudo ss -ltnp | grep -E ':(80|443)\b' # alternativa sudo lsof -iTCP:80 -sTCP:LISTEN sudo lsof -iTCP:443 -sTCP:LISTEN

Se outra aplicação estiver usando 80/443, o Apache pode falhar ao iniciar ou ficar apenas em uma das portas.

Checar firewall local (host) rapidamente

Mesmo com Apache OK, o acesso pode falhar por bloqueio local. Verifique o firewall em uso.

# UFW (Ubuntu) sudo ufw status verbose # firewalld (RHEL-like) sudo firewall-cmd --state sudo firewall-cmd --list-ports sudo firewall-cmd --list-services # iptables (legado) sudo iptables -S

Se a porta 80/443 não estiver liberada, ajuste a regra conforme a política do servidor (evite “liberar tudo”; libere apenas o necessário).

Logs como ferramenta de fechamento de diagnóstico

Para troubleshooting, o fluxo típico é: reproduzir o problema (com curl/navegador) e observar logs em tempo real. Isso permite correlacionar horário, vhost, URI, status code e mensagem de erro.

# Acompanhar logs em tempo real (ajuste caminhos conforme sua distro) sudo tail -f /var/log/apache2/access.log /var/log/apache2/error.log # Em RHEL-like costuma ser /var/log/httpd/access_log e error_log

Para isolar por vhost, é comum ter logs separados por site. Se você já usa logs por vhost, acompanhe o arquivo específico do site afetado.

Ferramentas de verificação rápida (comandos práticos)

Testar resposta HTTP/HTTPS com Host correto

Quando há múltiplos vhosts, testar por IP sem enviar o Host pode cair no vhost default. Use curl com header Host (e, em HTTPS, SNI é relevante).

# HTTP com Host header curl -i -H 'Host: www.exemplo.com' http://127.0.0.1/ # HTTPS com SNI (use o nome no URL) curl -vk https://www.exemplo.com/ --resolve www.exemplo.com:443:127.0.0.1

Confirmar qual certificado o servidor está entregando

Para problemas de certificado, valide o certificado apresentado e o nome (CN/SAN) diretamente na conexão.

openssl s_client -connect 127.0.0.1:443 -servername www.exemplo.com -showcerts

Procure por:

• O certificado exibido (Subject/SAN) corresponde ao domínio?
• A cadeia (intermediários) está completa?
• Você conectou com -servername correto (SNI)?

Problemas guiados e fluxos de investigação

Caso 1: “O vhost não responde” (timeout, conexão recusada, site errado)

Sintomas comuns: navegador dá timeout; curl retorna “Connection refused”; ou abre outro site (vhost default) em vez do esperado.

Fluxo passo a passo

1. Reproduza localmente para separar rede externa de problema no Apache:

   curl -i http://127.0.0.1/ curl -i -H 'Host: www.exemplo.com' http://127.0.0.1/

2. Verifique se o Apache está ativo e sem falhas:

   sudo systemctl status apache2  # ou httpd

3. Verifique se está escutando na porta correta:

   sudo ss -ltnp | grep -E ':(80|443)\b'

   Se não estiver escutando, procure erro de bind/porta ocupada no status e no error log.

4. Confirme vhosts carregados e matching:

   sudo apachectl -S

   Procure o vhost do domínio e veja em qual IP:port ele está definido. Se o request cai no vhost default, revise ServerName/ServerAlias e a porta do <VirtualHost *:80>/*:443.

5. Verifique firewall local (se o acesso externo falha, mas local funciona):

   sudo ufw status verbose # ou firewalld/iptables conforme o caso

6. Cheque logs durante o teste:

   sudo tail -f /var/log/apache2/error.log

   Se não aparece nada no log ao fazer o curl, o tráfego pode nem estar chegando ao Apache (firewall, NAT, balanceador, DNS apontando errado).

Correções típicas

• Vhost não habilitado/carregado (em distros que exigem enable): habilitar e recarregar.
• Porta errada no bloco <VirtualHost> (ex.: vhost HTTPS definido em *:80).
• Conflito de porta com outro serviço.
• Firewall local bloqueando 80/443.

Caso 2: “403 Forbidden” por permissão/escopo de diretório

Sintomas comuns: o site responde, mas retorna 403 para a raiz ou para um diretório específico. O access log mostra 403, e o error log costuma indicar o motivo (negado por configuração, falta de permissão de leitura, ou execução de diretório).

Fluxo passo a passo

1. Reproduza e capture o status:

   curl -i -H 'Host: www.exemplo.com' http://127.0.0.1/

2. Leia o error log no momento do request:

   sudo tail -n 50 /var/log/apache2/error.log

   Mensagens úteis incluem variações de “client denied by server configuration”, “AH01630 client denied by server configuration”, “permission denied”, “Options FollowSymLinks or SymLinksIfOwnerMatch is off”.

3. Confirme o caminho real do DocumentRoot e do recurso (erros de path levam a 403/404 confusos):

   sudo apachectl -S

4. Verifique permissões no filesystem (leitura e travessia):

   # Ajuste o caminho do DocumentRoot sudo namei -l /var/www/meusite/public

   Procure se algum diretório no caminho não tem permissão de “x” (travessia) para o usuário/grupo do Apache, ou se os arquivos não têm leitura.

5. Verifique se o bloco de diretório aplicável está cobrindo o path correto

   Um erro comum é ter regras de acesso para um diretório diferente do DocumentRoot real, ou ter um bloco mais específico negando acesso.

Correções típicas

• Permissões/ownership incorretos no caminho do DocumentRoot (algum diretório sem travessia).
• Regra de acesso negando (ex.: Require all denied) aplicada ao diretório errado.
• Symlink apontando para local sem permissões adequadas (e/ou política de symlink do Apache impedindo).

Caso 3: “Rewrite em loop” (redirecionamento infinito)

Sintomas comuns: navegador acusa “too many redirects”; curl -I mostra múltiplos 301/302 repetidos; o access log registra várias requisições para a mesma URL em sequência.

Fluxo passo a passo

1. Detecte o loop com curl seguindo redirects:

   curl -IL http://www.exemplo.com/

   Se a mesma Location aparece repetidamente (ou alterna entre duas URLs), há loop.

2. Identifique se o loop é HTTP<->HTTPS ou www<->non-www

   Exemplos comuns:

   • HTTP redireciona para HTTPS, mas o vhost HTTPS redireciona de volta para HTTP.
   • www redireciona para sem www, mas outra regra faz o inverso.

3. Verifique a regra que está gerando o redirect

   Procure por regras de redirect/rewrite no vhost e em arquivos incluídos. Se houver múltiplos pontos de rewrite (vhost + diretório), o comportamento pode duplicar.

4. Use logs para confirmar o padrão:

   sudo tail -f /var/log/apache2/access.log

   Observe a sequência de status 301/302 e o caminho requisitado.

5. Valide a condição de parada

   Loops acontecem quando a regra não tem uma condição que impeça reescrever/redirecionar uma URL já “corrigida”. Garanta que a regra só aplique quando necessário (por exemplo, apenas quando não estiver em HTTPS, ou apenas quando o Host não for o desejado).

Correções típicas

• Adicionar/ajustar condições para não reescrever quando já está no destino correto.
• Evitar duplicidade de regras (mesma intenção aplicada em mais de um lugar).
• Conferir se o balanceador/proxy termina TLS e repassa para Apache em HTTP; nesse caso, a regra de “forçar HTTPS” pode precisar considerar headers como X-Forwarded-Proto (se e somente se você confia no proxy).

Caso 4: “SSL com certificado errado” (certificado de outro site, mismatch de domínio)

Sintomas comuns: o navegador mostra certificado de outro domínio; erro de nome (CN/SAN não bate); ou o certificado correto existe no servidor, mas não é o que está sendo entregue.

Fluxo passo a passo

1. Confirme qual certificado é apresentado via SNI:

   openssl s_client -connect 127.0.0.1:443 -servername www.exemplo.com -showcerts

   Se sem -servername aparece um certificado diferente, isso indica que o default TLS pode estar sendo usado quando o SNI não casa (ou quando o cliente não envia SNI).

2. Verifique o vhost :443 carregado e a ordem:

   sudo apachectl -S

   Veja qual vhost é o default em *:443 e se o seu domínio está associado ao vhost correto.

3. Confirme se o vhost correto tem os caminhos de certificado corretos

   Erros comuns:

   • Apontar SSLCertificateFile para o arquivo de outro site.
   • Trocar certificado e chave entre vhosts.
   • Esquecer intermediários (cadeia incompleta) e o cliente “reclamar” de validação.

4. Recarregue e reteste:

   sudo apachectl configtest sudo systemctl reload apache2  # ou httpd openssl s_client -connect 127.0.0.1:443 -servername www.exemplo.com

Correções típicas

• Garantir que cada vhost TLS tenha ServerName correto e esteja em <VirtualHost *:443>.
• Garantir que o vhost default em 443 não “capture” o domínio por falta de match.
• Conferir paths de certificado/chave e cadeia completa.

Modelo de rotina operacional (para repetir em toda mudança)