Tutorial do Debian 13 / Configurar sites Nginx e diagnosticar respostas 403, 404 e permissões

No Debian 13, os sites do Nginx podem armazenar configurações em sites-available e ser ativados por meio de links simbólicos em sites-enabled. Após verificar a configuração, aplique-a com reload e, separadamente, verifique a porta, o valor do cabeçalho Host, as permissões de arquivos e as respostas HTTP reais. Este tutorial adiciona um site estático em 127.0.0.1:8080 enquanto preserva o site padrão e compara as causas das respostas 200, 403 e 404.

Verifique o escopo do laboratório e os serviços em escuta

Nginx é um servidor web que recebe requisições HTTP (Hypertext Transfer Protocol, protocolo de transferência de hipertexto) e serve arquivos ou encaminha as requisições para outras aplicações. Aqui, configuraremos apenas um site estático servindo arquivos HTML diretamente. Você precisa de um usuário comum do Debian 13 com privilégios sudo e curl, e todas as verificações HTTP devem ser executadas dentro da VM Debian. O exemplo escuta apenas no loopback da VM. O acesso a partir de um PC hospedeiro exigiria um plano separado para o endereço de escuta e encaminhamento; este laboratório mantém todas as requisições dentro da VM.

Durante a instalação do pacote, o site padrão pode ser iniciado. Em um servidor de produção real, primeiro verifique se há conflitos com servidores web existentes nas portas 80 e 443 e estabeleça procedimentos de manutenção. Verifique também se 127.0.0.1:8080 não está em uso. Se outro serviço ocupar um endereço e porta necessários, interrompa esta instalação e identifique o conflito em vez de interromper esse serviço.

ss -ltn
dpkg-query -W nginx nginx-common 2>/dev/null
apt-cache policy nginx

dpkg-query em pacotes não instalados pode retornar um status diferente de zero. Isso sozinho não é um erro do sistema. Na VM do teste original, o Nginx não estava instalado e apenas o SSH na porta 22 estava aberto. Ele foi instalado a partir do repositório Debian da seguinte forma.

sudo apt update
sudo apt install nginx curl
nginx -v
systemctl is-active nginx
systemctl is-enabled nginx
sudo nginx -t

O nginx e o nginx-common instalados na VM do teste original estavam na versão 1.26.3-3+deb13u10, e o serviço estava ativo e habilitado. Os números de revisão do pacote podem variar dependendo do momento da implantação e das atualizações de segurança. Se o serviço não iniciar, verifique a causa real, como falha ao associar o serviço ao endereço e à porta, com systemctl status nginx --no-pager e sudo journalctl -u nginx -n 50 --no-pager.

Inspecione os caminhos de inclusão do Debian e faça backup dos originais

O diretório sites-available é onde os arquivos de configuração são armazenados, e nem todos os arquivos nele contidos são aplicados automaticamente. No pacote prático, /etc/nginx/nginx.conf incluía /etc/nginx/conf.d/*.conf e /etc/nginx/sites-enabled/* dentro do contexto http. Prossiga após verificar essa regra diretamente.

grep -nE 'user |include .*(conf.d|sites-enabled)' /etc/nginx/nginx.conf
ls -l /etc/nginx/sites-enabled
sudo nginx -T | less

nginx -T imprime todas as configurações incluídas juntamente com uma verificação. Como informações de autenticação ou endereços internos podem estar incluídos, não publique essa saída sem examiná-la. No less, saia com q. Na VM original, os processos que atendem às requisições, chamados workers, usavam a conta www-data, e o link do site padrão foi mantido.

O seguinte é um bloco de preparação para verificar se o caminho de prática não existe e para preservar o original. Execute no mesmo terminal Bash. Se o caminho já existir, pare sem deletar ou sobrescrever. Os backups das configurações operacionais preparados pelo leitor também devem incluir todos os arquivos de inclusão e certificados relacionados.

set -euo pipefail
for p in /srv/lf-web25 /etc/nginx/sites-available/lf-web25 /etc/nginx/sites-enabled/lf-web25 /var/backups/lf-debian13-25; do
    if test -e "$p" || test -L "$p"; then
        echo "Path already exists: $p" >&2
        exit 1
    fi
done
sudo install -d -m 700 /var/backups/lf-debian13-25
sudo cp -a /etc/nginx/nginx.conf /etc/nginx/sites-available/default /var/backups/lf-debian13-25/
sudo sha256sum /etc/nginx/nginx.conf /etc/nginx/sites-available/default | sudo tee /var/backups/lf-debian13-25/original.sha256

Crie os arquivos estáticos e a configuração completa do host virtual

Os arquivos do site de prática são colocados em /srv/lf-web25/public. O administrador possui os arquivos, e o worker do Nginx só pode lê-los. Os diretórios precisam de permissão de execução para percorrer o caminho, e os arquivos precisam de permissão de leitura. Este exemplo se aplica apenas a arquivos estáticos públicos, e senhas ou materiais privados não são colocados neste caminho.

sudo install -d -m 755 /srv/lf-web25/public /srv/lf-web25/public/empty
printf '%s
' '<!doctype html><html lang="en"><meta charset="utf-8"><title>Lab 25</title><h1>LF WEB 25</h1></html>' | sudo tee /srv/lf-web25/public/index.html
sudo chmod 644 /srv/lf-web25/public/index.html

Escreva todo o próximo bloco no arquivo de configuração. O terminador de heredoc entre aspas CONF preserva $uri como uma variável do Nginx, não como uma variável de shell. O invólucro de shell é um bloco Bash; o conteúdo entre os marcadores CONF é a configuração completa do Nginx.

sudo tee /etc/nginx/sites-available/lf-web25 > /dev/null <<'CONF'
server {
    listen 127.0.0.1:8080 default_server;
    server_name _;
    return 404;
}
server {
    listen 127.0.0.1:8080;
    server_name lab25.test;
    root /srv/lf-web25/public;
    index index.html;
    access_log /var/log/nginx/lf-web25-access.log;
    error_log /var/log/nginx/lf-web25-error.log;
    location / {
        try_files $uri $uri/ =404;
    }
}
CONF
Configurações Papel desta prática
listen 127.0.0.1:8080 Ele aceita apenas conexões do próprio loopback da VM. Não pode ser acessado diretamente da internet.
default_server Especifica o servidor padrão para solicitações com nomes incompatíveis naquele endereço e porta.
server_name lab25.test Direciona a esse site as requisições cujo cabeçalho Host corresponde a lab25.test. Não cria registros DNS.
root e index Define o caminho do arquivo para encontrar a URI (Uniform Resource Identifier, identificador de recurso) da requisição e o arquivo padrão do diretório.
try_files $uri $uri/ =404 Verifica o arquivo ou diretório e retorna 404 se não encontrado.

O próprio server_name _ não é um curinga especial que captura todos os nomes. Aqui, default_server determina a escolha padrão. Se você duplicar isso no mesmo endereço e porta, um erro pode ocorrer, então verifique as configurações existentes. A documentação de manipulação de requisições do Nginx explica a ordem de primeiro selecionar o endereço e a porta, e depois determinar o nome do Host e o servidor padrão.

Crie o link simbólico de ativação, verifique a configuração e aplique-a. Continue na sessão Bash dedicada. A seguinte cadeia && executa reload apenas quando nginx -t for bem-sucedido; uma verificação falha deve ser corrigida antes de prosseguir.

sudo ln -s /etc/nginx/sites-available/lf-web25 /etc/nginx/sites-enabled/lf-web25
sudo nginx -t && sudo systemctl reload nginx
systemctl is-active nginx
ss -ltn | grep '127.0.0.1:8080'

O reload faz com que a configuração seja lida novamente, mas o ato de salvar o próprio arquivo de configuração não é aplicado ao processo em execução. Mesmo que passe na verificação, isso não garante as permissões reais de leitura de arquivos do worker ou a resposta desejada do Host, portanto a verificação HTTP continua. O escopo das opções nginx -t e -T pode ser verificado na documentação do comando nginx no Debian.

Compare a seleção por Host, as respostas HTTP e o DNS

O seguinte comando usa --noproxy para excluir os efeitos das variáveis de ambiente do proxy. A primeira requisição é para o site real, a segunda é para o servidor padrão com um nome incompatível, a terceira é para um arquivo inexistente e a quarta é para um diretório sem um index.

curl --noproxy '*' -i -H 'Host: lab25.test' http://127.0.0.1:8080/
curl --noproxy '*' -i -H 'Host: other.test' http://127.0.0.1:8080/
curl --noproxy '*' -i -H 'Host: lab25.test' http://127.0.0.1:8080/missing
curl --noproxy '*' -i -H 'Host: lab25.test' http://127.0.0.1:8080/empty/
Requisição Resultado Verificado Interpretação
lab25.test / 200, LF WEB 25 Selecionou o site desejado e os arquivos estáticos.
other.test / 404 Este é o valor de retorno explícito do servidor padrão.
lab25.test /missing 404 Não foi possível encontrar o arquivo alvo no site correspondente.
lab25.test /empty/ 403 Existe um diretório, mas sem índice, e a listagem de diretórios não é permitida.

Por padrão, o curl não considera o recebimento de HTTP 404 como uma falha no processo. Para verificações automáticas, use -f para retornar falha em respostas de erro HTTP, ou imprima o status com -w e compare-o explicitamente. Imprimir um status apenas com -w não faz com que um erro HTTP produza um status de saída de falha no curl. Para escrever o nome do site na URL, mas solicitá-lo sem alterar o DNS público, use o seguinte comando. --resolve fornece o mapeamento de nome, porta e endereço apenas para esta requisição curl.

curl --noproxy '*' -fsS --resolve lab25.test:8080:127.0.0.1 http://lab25.test:8080/

Mesmo que o comando tenha sucesso, lab25.test não está registrado no DNS da internet. Para tornar um serviço externo público, você precisa de um domínio real, o caminho para o servidor, um endereço de escuta apropriado, firewall e HTTPS separadamente. Seguir este exercício não requer a abertura da porta 8080 externamente.

Relacione falhas de permissão aos registros de erro

Mesmo que você receba o mesmo 403, a causa pode ser diferente. Abaixo está uma comparação onde alteramos apenas um arquivo de propriedade do root criado neste exercício para 600, removendo a permissão de leitura do worker, e então fizemos uma requisição. Não aplique isso a arquivos operacionais. Verifique o status HTTP e imediatamente restaure para 644.

sudo chmod 600 /srv/lf-web25/public/index.html
curl --noproxy '*' -sS -o /dev/null -w '%{http_code}
' -H 'Host: lab25.test' http://127.0.0.1:8080/
namei -l /srv/lf-web25/public/index.html
sudo tail -n 10 /var/log/nginx/lf-web25-error.log
sudo chmod 644 /srv/lf-web25/public/index.html
curl --noproxy '*' -fsS -H 'Host: lab25.test' http://127.0.0.1:8080/

O resultado do teste original foi 403 com a mensagem Permission denied quando definido para 600, e 200 após a restauração. A requisição anterior a /empty/ produziu o erro directory index is forbidden. Os registros permitem distinguir essas duas causas de HTTP 403. namei mostra permissões até os diretórios intermediários. Se você não tiver permissão de travessia de diretório em um diretório pai, o arquivo final não pode ser lido mesmo que esteja em 644.

Não resolva isso com chmod -R 777. Verifique o caminho, o proprietário, a conta do worker, listas de controle de acesso (ACLs, Access Control Lists) e logs de negação do AppArmor, se necessário, e conceda apenas as permissões necessárias. Mesmo que a verificação da configuração do Nginx seja bem-sucedida como root, isso não é o mesmo que o worker www-data conseguir ler. O log de acesso é usado para ver solicitações e status, e o log de erros é usado para restringir a razão da negação.

Recupere a configuração do site e limpe o laboratório

Antes de alterar as configurações, faça uma cópia separada da versão já verificada como funcional deste site. No teste original, enquanto uma configuração com diretivas desconhecidas é rejeitada pelo nginx -t, os workers existentes que não foram recarregados continuam a retornar 200. Restaure o arquivo que falhou para a versão já verificada como funcional e verifique novamente. Os leitores devem criar o hábito de copiar, verificar e aplicar a versão já verificada como funcional sem criar erros nas configurações de produção.

sudo cp -a /etc/nginx/sites-available/lf-web25 /var/backups/lf-debian13-25/good-site
sudo nginx -t && sudo systemctl reload nginx
curl --noproxy '*' -fsS -H 'Host: lab25.test' http://127.0.0.1:8080/

Para restaurar este arquivo de laboratório, compare-o com sudo diff -u /var/backups/lf-debian13-25/good-site /etc/nginx/sites-available/lf-web25. Se o arquivo salvo for a versão pretendida, restaure-o com sudo cp -a /var/backups/lf-debian13-25/good-site /etc/nginx/sites-available/lf-web25. Execute o comando acima que só faz reload se nginx -t passar e repita a solicitação HTTP específica do Host. Preserve quaisquer edições novas pretendidas antes de copiar.

Se houver um problema com o site alterado, compare a versão funcional recém-salva com o arquivo atual e restaure apenas o arquivo desse site. Não sobrescreva imprudentemente as configurações comuns. O comportamento de substituição do worker ao recarregar e o manuseio em caso de falha podem ser confirmados no Guia de recarga de configuração do Nginx.

Para encerrar a prática, primeiro remova o link e desligue o servidor dedicado na porta 8080 com verificação e recarga. Não pare o site padrão nem todo o serviço do Nginx. Se você quiser manter os logs antes de executar os passos abaixo, copie os dois logs dedicados para a pasta de backup.

sudo cp -a /var/log/nginx/lf-web25-access.log /var/log/nginx/lf-web25-error.log /var/backups/lf-debian13-25/
sudo rm -- /etc/nginx/sites-enabled/lf-web25
sudo nginx -t && sudo systemctl reload nginx
ss -ltn
sudo sha256sum -c /var/backups/lf-debian13-25/original.sha256

Logo após o recarregamento, permita algum tempo para que os processos workers existentes terminem as requisições, e então verifique novamente. Após confirmar que o listener 127.0.0.1:8080 desapareceu e o hash original está OK, limpe apenas os arquivos dedicados. No ambiente de produção, também verifique se os processos workers ainda presentes não estão mais acessando os logs dedicados.

sudo rm -- /etc/nginx/sites-available/lf-web25 /srv/lf-web25/public/index.html
sudo rmdir /srv/lf-web25/public/empty /srv/lf-web25/public /srv/lf-web25
sudo rm -- /var/log/nginx/lf-web25-access.log /var/log/nginx/lf-web25-error.log
systemctl is-active nginx

Na verificação final do curso original, o listener e os arquivos dedicados foram removidos, os hashes do nginx.conf e do site padrão foram mantidos, e o próprio Nginx estava ativo. Os pacotes instalados foram mantidos. A remoção dos pacotes será decidida separadamente após verificar o uso deles com outros sites e uso futuro.