Nginx-spiekbrief: commando's, configuratiefragmenten en foutoplossing

10 min leestijd·Matthieu
web-servernginxreverse-proxycheatsheetlinux

Snelreferentie voor dagelijkse Nginx-bewerkingen op Debian 12 en Ubuntu 24.04. Georganiseerd per taak, zodat je snel vindt wat je nodig hebt. Voor een volledige handleiding, zie Nginx-beheer op een VPS.

Hoe beheer ik de Nginx-service?

Gebruik systemctl om Nginx via systemd aan te sturen, of stuur signalen rechtstreeks met nginx -s. Systemctl is de standaard op moderne Debian- en Ubuntu-systemen. De native nginx -s-commando's communiceren rechtstreeks met het masterproces via het PID-bestand. Beide werken. Systemctl is beter voor automatisering en persistentie bij het opstarten.

Signaal- en commandotoewijzing

Actie systemctl-commando nginx -s equivalent Unix-signaal Effect op workers
Starten sudo systemctl start nginx (niet van toepassing) - Masterproces start, maakt workers aan
Stoppen (graceful) sudo systemctl stop nginx sudo nginx -s quit SIGQUIT Workers maken lopende verzoeken af en stoppen dan
Stoppen (direct) sudo systemctl kill nginx sudo nginx -s stop SIGTERM Workers verbreken verbindingen en stoppen
Config herladen sudo systemctl reload nginx sudo nginx -s reload SIGHUP Nieuwe workers starten met nieuwe config. Oude workers maken hun verzoeken af en stoppen dan. Geen verloren verbindingen.
Logs heropenen (niet ingebouwd) sudo nginx -s reopen SIGUSR1 Workers heropenen logbestandsdescriptors. Gebruik na logrotatie.
Inschakelen bij boot + nu starten sudo systemctl enable --now nginx (niet van toepassing) - Maakt symlink voor opstarten, start direct
Uitschakelen + stoppen sudo systemctl disable --now nginx (niet van toepassing) - Verwijdert boot-symlink, stopt direct

enable --now zorgt dat Nginx herstart na een reboot en start het direct. Gebruik altijd dit commando in plaats van een simpele start.

Reload vs restart

reload stuurt SIGHUP. Het masterproces leest de nieuwe config, start nieuwe workers en laat oude workers hun actieve verbindingen afhandelen. Geen downtime.

restart stuurt SIGTERM (stop), start dan opnieuw. Alle actieve verbindingen worden verbroken. Gebruik restart alleen bij het wijzigen van listen-poorten, laden van nieuwe modules of upgraden van het Nginx-binary.

Test altijd voor het herladen:

sudo nginx -t && sudo systemctl reload nginx

Als nginx -t faalt, wordt het herladen niet uitgevoerd. Je draaiende config blijft onaangetast.

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Na het herladen:

sudo systemctl status nginx

● nginx.service - A high performance web server and a reverse proxy server
     Loaded: loaded (/usr/lib/systemd/system/nginx.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-03-20 10:15:32 UTC; 2s ago

Het enabled in de Loaded-regel betekent dat het bij het opstarten wordt gestart. Nginx installeren op Debian 12 en Ubuntu 24.04 vanuit de officiële repository

Hoe test en inspecteer ik de Nginx-configuratie?

Voer nginx -t uit om de syntax te valideren zonder de draaiende server te beïnvloeden. Voer nginx -T uit om te valideren en de volledige geparseerde config naar stdout te dumpen. Voer nginx -V uit om compilatiemodules en flags te zien.

Commando Doel
sudo nginx -t Config-syntax testen, controleren of gerefereerde bestanden bestaan
sudo nginx -t -q Dezelfde test, onderdrukt niet-foutuitvoer (handig in scripts)
sudo nginx -T Test + volledige geparseerde config naar stdout dumpen
sudo nginx -V Versie, compiler, configure-argumenten, ingebouwde modules tonen
sudo nginx -v Alleen versienummer tonen

Draaiende config dumpen en doorzoeken

sudo nginx -T 2>/dev/null | grep -A5 "server_name example.com"

Dit commando toont de volledige config (alle geïncludeerde bestanden samengevoegd) en filtert op een specifiek serverblok. Sneller dan handmatig bestanden openen wanneer je tientallen includes hebt.

Gecompileerde modules controleren

sudo nginx -V 2>&1 | tr ' ' '\n' | grep module

--with-http_ssl_module
--with-http_v2_module
--with-http_realip_module
--with-http_gzip_static_module
--with-http_stub_status_module

Je kunt een directive niet gebruiken als de bijbehorende module niet is gecompileerd. Dit is het eerste wat je moet controleren wanneer een directive "unknown directive"-fouten veroorzaakt.

Waar staan de Nginx-config- en logbestanden?

Op Debian 12 en Ubuntu 24.04 installeert de pakketbeheerder alles onder /etc/nginx/. Logs gaan naar /var/log/nginx/. Hier is de volledige structuur.

Pad Doel
/etc/nginx/nginx.conf Hoofdconfig. Stelt worker-aantal, events, http-blok, includes in
/etc/nginx/sites-available/ Serverblokbestanden (beschikbaar maar niet per se actief)
/etc/nginx/sites-enabled/ Symlinks naar sites-available. Nginx laadt deze.
/etc/nginx/conf.d/ Extra configfragmenten. Geladen door de standaard include in nginx.conf
/etc/nginx/snippets/ Herbruikbare config-snippets (SSL-parameters, beveiligingsheaders)
/etc/nginx/mime.types MIME-typetoewijzingen
/var/log/nginx/access.log Verzoeklog
/var/log/nginx/error.log Foutenlog
/run/nginx.pid PID-bestand van het masterproces

Een site inschakelen:

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Een site uitschakelen:

sudo rm /etc/nginx/sites-enabled/example.com
sudo nginx -t && sudo systemctl reload nginx

Voor een diepgaande uitleg van de directorystructuur, zie Nginx configuratiebestandsstructuur uitgelegd.

Wat zijn de meestgebruikte Nginx-config-snippets?

Elk snippet hieronder is een minimaal werkend voorbeeld. Kopieer, pas de waarden aan, test met nginx -t, herlaad. Voor volledige handleidingen over elk onderwerp, volg de interne links.

Hoe stel ik een basis-serverblok in?

Een serverblok (virtuele host) koppelt een domein aan een documentroot. Plaats dit in /etc/nginx/sites-available/example.com.

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

    root /var/www/example.com/html;
    index index.html;

    server_tokens off;

    location / {
        try_files $uri $uri/ =404;
    }
}

server_tokens off verbergt de Nginx-versie in de responsheaders. Versie-openbaarmaking helpt aanvallers bekende kwetsbaarheden te targeten.

Maak een symlink in sites-enabled en herlaad. Nginx server blocks: meerdere domeinen op één VPS

Hoe redirect ik HTTP naar HTTPS?

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

    return 301 https://$host$request_uri;
}

return 301 is sneller dan rewrite voor volledige URL-redirects. Nginx verwerkt return voordat het bestandssysteem wordt aangeraakt.

Hoe configureer ik Nginx als reverse proxy?

Stuur verzoeken door naar een backend op poort 3000. Plaats dit in het HTTPS-serverblok.

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

De afsluitende slash doet ertoe. proxy_pass http://127.0.0.1:3000; (zonder afsluitende slash) stuurt de volledige originele URI door. proxy_pass http://127.0.0.1:3000/; (met afsluitende slash) verwijdert het location-prefix. Dit is de bron van veel niet-werkende proxyconfiguraties.

Nginx configureren als reverse proxy

Hoe schakel ik gzip-compressie in?

Voeg toe aan het http {}-blok in /etc/nginx/nginx.conf of een snippetbestand:

gzip on;
gzip_vary on;
gzip_proxied any;
gzip_min_length 1024;
gzip_comp_level 5;
gzip_types
    text/plain
    text/css
    text/javascript
    application/json
    application/javascript
    application/xml
    image/svg+xml;

gzip_min_length 1024 slaat bestanden onder 1 KB over. Het comprimeren van kleine bestanden voegt CPU-overhead toe zonder noemenswaardige groottereductie. gzip_comp_level 5 biedt een goede balans tussen compressieverhouding en CPU-kosten. Boven 6 nemen de voordelen af.

Nginx Performance Tuning op een VPS

Hoe voeg ik rate limiting toe?

Definieer een zone in het http {}-blok en pas deze toe in een location- of server-blok.

# In http {} block
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

# In server or location block
location /api/ {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://127.0.0.1:8080;
}

$binary_remote_addr gebruikt 4 bytes per IPv4-adres. Een 10 MB-zone bevat ongeveer 160.000 adressen. burst=20 staat korte pieken toe. nodelay bedient burst-verzoeken direct in plaats van ze in de wachtrij te plaatsen.

Nginx Rate Limiting en DDoS-bescherming

Hoe proxy ik WebSocket-verbindingen?

location /ws/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400s;
}

proxy_http_version 1.1 is vereist. HTTP/1.0 ondersteunt de Upgrade-header niet. proxy_read_timeout 86400s houdt inactieve WebSocket-verbindingen 24 uur open in plaats van de standaard 60 seconden.

Hoe stel ik aangepaste foutpagina's in?

server {
    error_page 404 /404.html;
    error_page 500 502 503 504 /50x.html;

    location = /404.html {
        root /var/www/errors;
        internal;
    }

    location = /50x.html {
        root /var/www/errors;
        internal;
    }
}

De internal-directive voorkomt directe toegang tot de foutpagina-URL's. Zonder deze kunnen gebruikers rechtstreeks naar /404.html navigeren.

Hoe voeg ik beveiligingsheaders toe?

Maak /etc/nginx/snippets/security-headers.conf:

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

Neem het op in elk serverblok:

include snippets/security-headers.conf;

De always-parameter voegt headers ook toe bij foutresponsen (4xx, 5xx). Zonder deze voegt Nginx ze alleen toe bij 2xx/3xx. Nginx beveiligingshardening op Ubuntu en Debian

Minimaal TLS-serverblok

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;
    server_tokens off;

    # ... location blocks
}

Schakel TLSv1 of TLSv1.1 niet in. Beide hebben bekende kwetsbaarheden en worden geweigerd door moderne browsers. Let's Encrypt SSL/TLS instellen voor Nginx op Debian 12 en Ubuntu 24.04

Hoe lees en debug ik Nginx-logs?

Nginx schrijft standaard twee logs: access.log voor elk verzoek en error.log voor problemen. Beide staan in /var/log/nginx/.

Logs in realtime volgen

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

Of via journald:

journalctl -u nginx -f

Ernstniveaus van het foutenlog

De error_log-directive accepteert een niveau. Van meest naar minst uitgebreid:

debug > info > notice > warn > error > crit > alert > emerg

De standaard is error. Om tijdelijk debuglogging in te schakelen:

error_log /var/log/nginx/error.log debug;

Herlaad Nginx. Debuglogging is extreem uitgebreid. Schakel het uit na het diagnosticeren van het probleem, anders vult het je schijf.

JSON-formaat voor het toegangslog

Gestructureerde logs zijn makkelijker te verwerken met tools als jq, Loki of OpenObserve.

log_format json_combined escape=json
    '{'
        '"time":"$time_iso8601",'
        '"remote_addr":"$remote_addr",'
        '"method":"$request_method",'
        '"uri":"$request_uri",'
        '"status":$status,'
        '"body_bytes_sent":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"upstream_response_time":"$upstream_response_time",'
        '"http_user_agent":"$http_user_agent"'
    '}';

access_log /var/log/nginx/access.log json_combined;

Debugtoolkit

Commando Wat het doet
curl -I https://example.com Toont alleen responsheaders. Controleer statuscode, serverversie, cache-headers.
curl -v https://example.com 2>&1 | head -30 Uitgebreide output: TLS-handshake, verzoek-/responsheaders.
sudo nginx -T 2>/dev/null | grep server_name Lijst alle geconfigureerde servernamen over alle configbestanden.
sudo ss -tlnp | grep nginx Toont op welke poorten/adressen Nginx luistert.
sudo ls -la /var/log/nginx/ Controleer logbestandsgroottes en rechten.

stub_status inschakelen voor monitoring

location /nginx_status {
    stub_status;
    allow 127.0.0.1;
    allow ::1;
    deny all;
}

curl http://127.0.0.1/nginx_status

Active connections: 3
server accepts handled requests
 1542 1542 4890
Reading: 0 Writing: 1 Waiting: 2

Beperk stub_status tot localhost of je monitoring-IP. Het onthult informatie over de serverbelasting.

Wat betekenen de Nginx-foutcodes en hoe los ik ze op?

Wanneer Nginx een HTTP-fout retourneert, vertelt het error.log wat er is gebeurd. Dit zijn de meestvoorkomende codes, hun betekenis en hoe je ze oplost.

Code Naam Typisch error.log-bericht Veelvoorkomende oorzaak Oplossing
403 Forbidden directory index of "/var/www/html/" is forbidden Ontbrekend indexbestand, verkeerde bestandsrechten, autoindex off (standaard) Voeg een index.html toe, corrigeer rechten (chmod 644 voor bestanden, 755 voor mappen), of schakel autoindex on in
404 Not Found open() "/var/www/html/page" failed (2: No such file or directory) Verkeerd root-pad, verkeerde try_files, bestand bestaat niet Controleer de root-directive, verifieer het bestandspad op schijf
413 Request Entity Too Large client intended to send too large body Upload overschrijdt client_max_body_size (standaard: 1 MB) Stel client_max_body_size 50m; in het server- of location-blok in
502 Bad Gateway connect() failed (111: Connection refused) while connecting to upstream Backend draait niet, verkeerde poort/socket in proxy_pass Start de backend, controleer of de poort overeenkomt met proxy_pass
503 Service Unavailable no live upstreams while connecting to upstream Alle backends in een upstream-blok zijn down Start minstens één backend, controleer de health check-config
504 Gateway Timeout upstream timed out (110: Connection timed out) while reading response header Backend reageert te langzaam Verhoog proxy_read_timeout, optimaliseer de backend, controleer backend-logs

Een 502 diagnosticeren

De 502 is de meestvoorkomende proxyfout. Loop het stap voor stap door:

# 1. Is the backend running?
sudo ss -tlnp | grep 3000

# 2. Can Nginx reach it?
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3000/

# 3. What does the error log say?
sudo tail -20 /var/log/nginx/error.log

Als ss niets toont op poort 3000, is de backend gestopt. Als curl een antwoord geeft maar Nginx 502 retourneert, controleer dan socketrechten (vaak voorkomend bij PHP-FPM- of Gunicorn Unix-sockets).

Wat zijn de meestgemaakte Nginx-fouten?

Deze veroorzaken de meeste "ik heb de config gewijzigd en nu is het kapot"-momenten.

Ontbrekende puntkomma's

Elke directive moet eindigen met een puntkomma. Nginx geeft een duidelijke fout:

nginx: [emerg] unexpected "}" in /etc/nginx/sites-enabled/example.com:12

De fout wijst naar de regel na de ontbrekende puntkomma, niet naar de regel met het probleem. Kijk één regel hoger.

Verwarring tussen root en alias

# root: appends the location to the path
location /images/ {
    root /var/www;
    # serves /var/www/images/photo.jpg
}

# alias: replaces the location with the path
location /images/ {
    alias /var/www/media/;
    # serves /var/www/media/photo.jpg
}

Bij alias is de afsluitende slash vereist op zowel het location als het alias-pad. Het weglaten ervan veroorzaakt 404's zonder duidelijke reden in het foutenlog.

Verwarring over de location-evaluatievolgorde

Nginx evalueert locations in deze volgorde, ongeacht waar ze in het configbestand staan:

  1. = /exact - Exacte match. Eerst gecontroleerd. Bij match, stopt direct.
  2. ^~ /prefix - Preferentieel prefix. Langste match wint. Bij match, slaat alle regex over.
  3. ~ regex - Hoofdlettergevoelige regex. Van boven naar beneden geëvalueerd. Eerste match wint.
  4. ~* regex - Hoofdletterongevoelige regex. Dezelfde volgorde van boven naar beneden.
  5. /prefix - Standaard prefix. Langste match wint. Alleen gebruikt als geen regex matchte.

Bij prefixen telt de matchlengte, niet de volgorde in het configbestand. Bij regex telt de volgorde in het configbestand, niet de matchlengte. Ze mengen zonder dit te begrijpen creëert onvoorspelbare routing.

Afsluitende slash in proxy_pass

# No trailing slash: passes /app/foo to backend as /app/foo
location /app/ {
    proxy_pass http://127.0.0.1:3000;
}

# Trailing slash: strips /app/ and passes /foo to backend
location /app/ {
    proxy_pass http://127.0.0.1:3000/;
}

Kies er één en wees consistent. De meeste backends verwachten het volledige pad (geen afsluitende slash op proxy_pass).

nginx -t vergeten voor het herladen

Als je herlaadt met een kapotte config, blijft Nginx draaien met de oude config en logt een fout. Het crasht niet. Maar je hebt nu een config op schijf die niet overeenkomt met de draaiende config. Dit veroorzaakt later verwarring.

Maak er een gewoonte van: sudo nginx -t && sudo systemctl reload nginx. De && zorgt dat het herladen alleen wordt uitgevoerd als de test slaagt.

Bestanden in /etc/nginx/sites-available/ worden niet automatisch geladen. Je moet ze symlinken naar /etc/nginx/sites-enabled/. Een directe kopie werkt ook, maar symlinks bewaren één bron van waarheid.

Gaat er iets mis?

Snelle diagnosevolgorde wanneer Nginx zich vreemd gedraagt:

# Check if Nginx is running
sudo systemctl status nginx

# Test the config
sudo nginx -t

# Check which config is actually loaded
sudo nginx -T 2>/dev/null | head -50

# Check the last 30 error log entries
sudo tail -30 /var/log/nginx/error.log

# Check what ports Nginx is listening on
sudo ss -tlnp | grep nginx

# Check file permissions on the web root
sudo ls -la /var/www/example.com/html/

Als de service gefaald is, geeft journalctl -u nginx --no-pager -n 50 het volledige verhaal. Zoek naar [emerg]-vermeldingen.

Klaar om het zelf te proberen?

Deploy uw eigen server in seconden. Linux, Windows of FreeBSD. →
Nginx-spiekbrief: commando's, config en foutoplossing