Tutorial de Debian 13 / Configurar sitios Nginx y diagnosticar respuestas 403 y 404

En Debian 13, los sitios de Nginx pueden almacenar configuraciones en sites-available y activarse mediante enlaces simbólicos en sites-enabled. Después de verificar la configuración, aplíquela con reload y, por separado, verifique el puerto, el valor del encabezado Host, los permisos de archivos y las respuestas HTTP reales. Este tutorial agrega un sitio estático en 127.0.0.1:8080 mientras conserva el sitio predeterminado y compara las causas de las respuestas 200, 403 y 404.

Verifique el alcance del laboratorio y los servicios en escucha

Nginx es un servidor web que recibe solicitudes HTTP (Hypertext Transfer Protocol, protocolo de transferencia de hipertexto) y entrega archivos o pasa las solicitudes a otras aplicaciones. Aquí, solo configuraremos un sitio estático sirviendo archivos HTML directamente. Necesita un usuario regular de Debian 13 con privilegios sudo y curl, y todas las comprobaciones HTTP deben ejecutarse dentro de la máquina virtual Debian. El ejemplo escucha solo en la interfaz local (loopback) de la VM. El acceso desde una PC anfitriona requeriría un plan separado para la dirección de escucha y el reenvío; este laboratorio mantiene todas las solicitudes dentro de la VM.

Durante la instalación del paquete, el sitio predeterminado puede iniciar. En un servidor de producción real, primero verifique conflictos con los servidores web existentes en los puertos 80 y 443 y establezca procedimientos de mantenimiento. Verifique también que 127.0.0.1:8080 no esté en uso. Si otro servicio ocupa una dirección y puerto necesarios, detenga esta instalación e identifique el conflicto en lugar de detener ese servicio.

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

dpkg-query en paquetes no instalados puede devolver un estado distinto de cero. Eso por sí solo no es un error del sistema. En la VM de la prueba original, Nginx no estaba instalado y solo SSH en el puerto 22 estaba abierto. Se instaló desde el repositorio de Debian de la siguiente manera.

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

El nginx y nginx-common instalados en la VM de la prueba original eran de la versión 1.26.3-3+deb13u10, y el servicio estaba activo y habilitado. Los números de revisión del paquete pueden variar dependiendo del momento de la implementación y de las actualizaciones de seguridad. Si el servicio no se inicia, verifique la causa real, como un fallo al asociar el servicio a la dirección y el puerto, con systemctl status nginx --no-pager y sudo journalctl -u nginx -n 50 --no-pager.

Inspeccione las rutas de inclusión de Debian y haga una copia de seguridad de los originales

El directorio sites-available es donde se almacenan los archivos de configuración, y no todos los archivos dentro de él se aplican automáticamente. En el paquete de práctica, /etc/nginx/nginx.conf incluía /etc/nginx/conf.d/*.conf y /etc/nginx/sites-enabled/* dentro del contexto http. Proceda después de verificar esta regla directamente.

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 las configuraciones incluidas junto con una verificación. Dado que la información de autenticación o las direcciones internas pueden estar incluidas, no publique esa salida sin examinarla. En less, salga con q. En la VM original, los procesos que atienden las solicitudes, llamados workers, utilizaban la cuenta www-data, y se mantenía el enlace del sitio predeterminado.

El siguiente es un bloque de preparación para verificar que la ruta de práctica no exista y para preservar la original. Ejecute en la misma terminal Bash. Si la ruta ya existe, deténgase sin borrar ni sobrescribir. Las copias de seguridad de las configuraciones operativas preparadas por el lector también deben incluir todos los archivos incluibles y 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

Cree los archivos estáticos y la configuración completa del host virtual

Los archivos del sitio de práctica se colocan en /srv/lf-web25/public. El administrador posee los archivos, y el worker de Nginx solo puede leerlos. Los directorios necesitan permiso de ejecución para recorrer la ruta, y los archivos necesitan permiso de lectura. Este ejemplo se aplica solo a archivos estáticos públicos, y las contraseñas o materiales privados no se colocan en esta ruta.

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

Escriba todo el siguiente bloque en el archivo de configuración. El terminador heredoc entre comillas CONF conserva $uri como una variable de Nginx, no como una variable de shell. El envoltorio de shell es un bloque Bash; el contenido entre los marcadores CONF es la configuración completa de 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
Configuraciones Rol de esta práctica
listen 127.0.0.1:8080 Solo acepta conexiones desde el loopback de la propia máquina virtual. No se puede acceder directamente desde Internet.
default_server Especifica el servidor predeterminado para solicitudes con nombres que no coinciden en esa dirección y puerto.
server_name lab25.test Dirige a este sitio las solicitudes cuyo encabezado Host coincide con lab25.test. No crea registros DNS.
root e index Establece la ruta de archivos para encontrar la URI (Uniform Resource Identifier, identificador de recurso) de la solicitud y el archivo predeterminado para el directorio.
try_files $uri $uri/ =404 Verifica el archivo o directorio y devuelve 404 si no se encuentra.

El server_name _ en sí mismo no es un comodín especial que capture todos los nombres. Aquí, default_server determina la elección predeterminada. Si duplica esa declaración en la misma dirección y puerto, puede producirse un error: revise la configuración existente. La documentación sobre el manejo de solicitudes de Nginx explica el orden de primero seleccionar la dirección y el puerto, y luego determinar el nombre del Host y el servidor predeterminado.

Cree el enlace simbólico de activación, compruebe la configuración y aplíquela. Continúe en la sesión dedicada de Bash. La siguiente cadena && ejecuta reload solo cuando nginx -t tiene éxito; una verificación fallida debe corregirse antes de continuar.

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'

Reload hace que vuelva a leer la configuración, pero el acto de guardar el archivo de configuración en sí mismo no se aplica al proceso en ejecución. Incluso si pasa la verificación, no garantiza los permisos reales de lectura de archivos del worker ni la respuesta deseada del Host, por lo que la verificación HTTP continúa. El alcance de las opciones nginx -t y -T se puede consultar en la documentación del comando nginx en Debian.

Compare la selección por Host, las respuestas HTTP y el DNS

El siguiente comando usa --noproxy para excluir los efectos de las variables de entorno del proxy. La primera solicitud es al sitio real, la segunda es al servidor por defecto con un nombre no coincidente, la tercera es a un archivo inexistente, y la cuarta es a un directorio sin índice.

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/
Solicitud Resultado Verificado Interpretación
lab25.test / 200, LF WEB 25 Se seleccionó el sitio deseado y los archivos estáticos.
other.test / 404 Este es el valor de retorno explícito del servidor predeterminado.
lab25.test /missing 404 No se pudo encontrar el archivo objetivo en el sitio correspondiente.
lab25.test /empty/ 403 Hay un directorio, pero no hay índice, y no se permite la lista de directorios.

Por defecto, curl no trata la recepción de HTTP 404 como un fallo del proceso. Para verificaciones automáticas, use -f para devolver error en respuestas HTTP con error, o imprima el estado con -w y compárelo explícitamente. Imprimir un estado solo con -w no hace que un error HTTP produzca un estado de salida fallido en curl. Para escribir el nombre del sitio en la URL pero solicitarlo sin cambiar el DNS público, use el siguiente comando. --resolve proporciona la asignación de nombre, puerto y dirección solo para esta solicitud de curl.

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

Incluso si el comando tiene éxito, lab25.test no está registrado en el DNS de internet. Para hacer que un servicio externo sea público, necesita un dominio real, la ruta al servidor, una dirección de escucha apropiada, firewall y HTTPS por separado. Seguir este ejercicio no requiere abrir el puerto 8080 externamente.

Relacione los fallos de permisos con los registros de errores

Incluso si obtiene el mismo 403, la causa puede ser diferente. A continuación se muestra una comparación donde solo cambiamos un archivo propiedad de root creado en este ejercicio a 600, eliminando el permiso de lectura del worker, y luego realizamos una solicitud. No aplique esto a archivos de servicios en producción. Compruebe el estado HTTP y restablezca inmediatamente el modo 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/

El resultado de la prueba original fue 403 con el mensaje Permission denied cuando se estableció en 600, y 200 después de la restauración. La solicitud anterior a /empty/ produjo el error directory index is forbidden. Los registros permiten distinguir estas dos causas de HTTP 403. namei muestra los permisos hasta los directorios intermedios. Si no tiene permiso de recorrido de directorio en un directorio padre, el archivo final no se puede leer incluso si es 644.

No lo resuelva con chmod -R 777. Verifique la ruta, el propietario, la cuenta del worker, las listas de control de acceso (ACL, Access Control Lists) y los registros de denegación de AppArmor si es necesario, y solo otorgue los permisos necesarios. Incluso si la verificación de la configuración de Nginx tiene éxito como root, no es lo mismo que el worker www-data pueda leer. El registro de acceso se utiliza para ver solicitudes y estados, y el registro de errores se utiliza para reducir la causa de la denegación.

Recupere la configuración del sitio y retire los recursos del laboratorio

Antes de cambiar la configuración, haga una copia separada de la versión ya comprobada como funcional de este sitio. En la prueba original, mientras una configuración con directivas desconocidas es rechazada por nginx -t, los workers existentes que no se han recargado continuaron devolviendo 200. Restaure el archivo fallido a la versión ya comprobada como funcional y verifique nuevamente. Los lectores deberían adquirir el hábito de copiar, verificar y aplicar la versión ya comprobada como funcional sin crear errores en la configuración de producción.

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 archivo de laboratorio, compárelo con sudo diff -u /var/backups/lf-debian13-25/good-site /etc/nginx/sites-available/lf-web25. Si el archivo guardado es la versión deseada, restáurelo con sudo cp -a /var/backups/lf-debian13-25/good-site /etc/nginx/sites-available/lf-web25. Ejecute el comando anterior que solo realiza reload si nginx -t tiene éxito y repita la solicitud HTTP específica del host. Conserve cualquier edición más reciente intencional antes de copiar.

Si hay un problema con el sitio modificado, compare la versión funcional recién guardada con el archivo actual y restaure solo el archivo de ese sitio. No sobrescriba imprudentemente la configuración común. El comportamiento de reemplazo de los workers al recargar y el manejo en caso de falla se pueden confirmar en Guía de recarga de configuración de Nginx.

Para finalizar la práctica, primero elimine el enlace y apague el servidor dedicado en el puerto 8080 con check y recarga. No detenga el sitio predeterminado ni todo el servicio de Nginx. Si desea conservar los registros antes de realizar los pasos a continuación, copie los dos registros dedicados a la carpeta de respaldo.

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

Justo después de la recarga, permita algo de tiempo para que los procesos workers existentes terminen las solicitudes, luego verifique nuevamente. Después de confirmar que la escucha en 127.0.0.1:8080 ha desaparecido y que el hash original está bien, limpie solo los archivos dedicados. En el entorno de producción, también verifique que los procesos workers todavía presentes ya no estén accediendo a los registros 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

En la verificación final del curso original, la escucha y los archivos dedicados se eliminaron, los hashes de nginx.conf y del sitio predeterminado se mantuvieron, y Nginx en sí estaba activo. Los paquetes instalados se conservaron. La eliminación de paquetes se decidirá por separado después de verificar su uso con otros sitios y su uso futuro.