This guide covers the complete WordPress + NGINX + PHP-FPM stack on Debian and Ubuntu: server block configuration, PHP-FPM pool tuning, FastCGI caching for anonymous traffic, object caching with Redis, security hardening, and performance verification. Uses the optimised myguard packages throughout.

NGINX Server Block for WordPress

server {
    listen 443 ssl;
    http2 on;
    server_name example.com www.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_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

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

    # Serve static assets directly with long cache headers
    location ~* .(js|css|png|jpg|jpeg|webp|svg|woff2|woff|ttf|ico|pdf)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        log_not_found off;
        access_log off;
    }

    # WordPress permalink rewriting
    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    # PHP via PHP-FPM
    location ~ .php$ {
        try_files $uri =404;  # Security: don't execute non-existent PHP files
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 300s;
    }

    # Block direct access to sensitive files
    location ~* /.(?:git|env|htaccess|htpasswd)$ { deny all; }
    location ~* /(wp-config.php|xmlrpc.php)$ { deny all; }
    location = /wp-config.php { deny all; }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

PHP-FPM Pool Tuning

Edit /etc/php/8.4/fpm/pool.d/www.conf. The default settings are for shared hosting. Tune for a dedicated server:

[www]
user = www-data
group = www-data

; Use Unix socket (faster than TCP for local connections)
listen = /run/php/php8.4-fpm.sock
listen.owner = www-data
listen.group = www-data

; Dynamic process management
pm = dynamic
pm.max_children = 20        ; Max concurrent PHP processes
pm.start_servers = 5        ; Start with 5 workers
pm.min_spare_servers = 3    ; Keep at least 3 idle
pm.max_spare_servers = 8    ; Keep at most 8 idle
pm.max_requests = 500       ; Recycle workers after 500 requests (prevents memory leaks)

; Slower request logging for debugging
slowlog = /var/log/php/www-slow.log
request_slowlog_timeout = 5s

; PHP settings for WordPress
php_admin_value[memory_limit] = 256M
php_admin_value[upload_max_filesize] = 64M
php_admin_value[post_max_size] = 64M
php_admin_value[max_execution_time] = 120
php_admin_value[error_log] = /var/log/php/www-error.log
php_admin_flag[log_errors] = on

How to calculate pm.max_children: check your average PHP process memory usage (ps --no-headers -o rss -C php-fpm8.4 | awk '{sum+=$1} END {print sum/NR/1024 " MB"}'), then divide available RAM (minus OS and NGINX overhead) by that number. For a 2GB VPS: (2048MB – 400MB overhead) / ~80MB per process = ~20 workers.

FastCGI Cache: Serve WordPress Pages Without PHP

For unauthenticated visitors reading blog posts and pages, NGINX can cache the full PHP response and serve subsequent requests without touching PHP at all. A cached page serves in ~1ms instead of ~80ms. For a blog with most traffic being anonymous readers, this is transformative.

http {
    # Cache zone: 256MB storage
    fastcgi_cache_path /var/cache/nginx/wordpress
        levels=1:2 keys_zone=wp_cache:100m
        max_size=256m inactive=60m use_temp_path=off;

    fastcgi_cache_key "$scheme$request_method$host$request_uri";

    server {
        # Cache settings per request
        set $skip_cache 0;

        # Don't cache POST requests
        if ($request_method = POST) { set $skip_cache 1; }

        # Don't cache URLs with query strings (search results, paginated)
        if ($query_string != "") { set $skip_cache 1; }

        # Don't cache logged-in users or cart pages
        if ($http_cookie ~* "comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_no_cache|wordpress_logged_in|woocommerce_items_in_cart") {
            set $skip_cache 1;
        }

        location ~ .php$ {
            fastcgi_pass unix:/run/php/php8.4-fpm.sock;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;

            fastcgi_cache        wp_cache;
            fastcgi_cache_valid 200 60m;  # Cache 200 responses for 60 minutes
            fastcgi_cache_bypass  $skip_cache;
            fastcgi_no_cache      $skip_cache;

            add_header X-FastCGI-Cache $upstream_cache_status;
        }
    }
}

Create the cache directory:

mkdir -p /var/cache/nginx/wordpress
chown www-data:www-data /var/cache/nginx/wordpress

To purge the cache when WordPress publishes or updates a post, install the Nginx Cache or Nginx Helper WordPress plugin, or use the myguard cache purge module.

Object Cache with Redis

WordPress’s default object cache is per-request — database queries are cached in memory but the cache dies at the end of each request. Redis persists the object cache between requests, dramatically reducing database load:

apt-get install redis-server php8.4-redis

# Verify Redis is running
redis-cli ping  # Should return PONG

In WordPress, install the Redis Object Cache plugin, or add to wp-config.php:

define('WP_REDIS_HOST', '127.0.0.1');
define('WP_REDIS_PORT', 6379);
define('WP_CACHE', true);

With Redis object cache, a typical WordPress page that runs 30 database queries on the first load runs 2–3 on subsequent loads (just cache miss checks). For WooCommerce sites with heavy product catalog queries, the improvement is even more dramatic.

Compression for WordPress

Enable Brotli and gzip for all text content:

http {
    brotli on;
    brotli_comp_level 6;
    brotli_types text/html text/css application/javascript application/json image/svg+xml;

    gzip on;
    gzip_comp_level 6;
    gzip_vary on;
    gzip_types text/html text/css application/javascript application/json image/svg+xml;
}

Install the Brotli module: apt-get install libnginx-mod-http-brotli

Security Hardening Checklist

Beyond the server block config above:

• PHP-Snuffleupagus: apt-get install php8.4-snuffleupagus — blocks dangerous PHP functions at the interpreter level, protects against webshells even if a plugin is compromised
• ModSecurity WAF: apt-get install libnginx-mod-http-modsecurity — blocks SQLi, XSS, and scanner traffic before it reaches PHP
• Rate limiting on /wp-login.php: 5 req/min per IP blocks credential stuffing
• Block xmlrpc.php: Unless you use Jetpack or mobile app editing, add location = /xmlrpc.php { deny all; }
• File upload validation: Snuffleupagus upload validation rejects PHP files disguised as images

Performance Verification

# Test FastCGI cache is working
curl -I https://example.com/ | grep X-FastCGI-Cache
# First request: X-FastCGI-Cache: MISS
# Second request: X-FastCGI-Cache: HIT

# Check PHP-FPM worker status
curl http://127.0.0.1/fpm-status  # Add status page in pool config

# Benchmark with ab (Apache Bench)
ab -n 1000 -c 10 https://example.com/
# Look for 'Requests per second' and 'Time per request'

# Check Brotli is serving
curl -H 'Accept-Encoding: br' -I https://example.com/ | grep Content-Encoding
# Should show: Content-Encoding: br

Frequently Asked Questions

Related Posts

• NGINX Brotli Compression Module — detailed Brotli setup and pre-compression for static assets
• PHP-Snuffleupagus: Harden PHP-FPM — interpreter-level PHP security essential for WordPress
• NGINX ModSecurity WAF Setup — HTTP-layer WAF to pair with PHP hardening
• NGINX Rate Limiting Guide — protect wp-login.php and xmlrpc.php from brute force
• TLS Configuration for NGINX — A+ SSL Labs config for your WordPress HTTPS
• How to Add the myguard APT Repository — where the optimised NGINX packages come from

Changes

• Full rebuild and backport with latest Mainline
• Merged with the source package from Debian Trixie in november 2023
• See for more information https://deb.myguard.nl/nginx-modules/
• Changelog: https://deb.myguard.nl/forums/topic/changelog/

Distributions

• bookworm
• jammy
• noble
• resolute
• trixie

This is the most common NGINX deployment pattern in 2026. SSL termination at NGINX, backend over plain HTTP on localhost. Caching, rate limiting, and load balancing all handled by NGINX before your application code runs. It’s clean, fast, and secure.

Why Use NGINX as a Reverse Proxy?

• SSL termination: NGINX handles TLS; your backend speaks plain HTTP. No TLS library needed in your app.
• Connection pooling: NGINX keeps persistent connections to your backend, amortizing TCP handshake overhead
• Buffering: NGINX buffers slow client connections so your backend thread is freed immediately after sending the response
• Static file serving: NGINX serves CSS, JS, and images directly without touching your application
• Security: Backend never exposed to the internet; rate limiting, WAF, and auth can be applied at the proxy layer
• HTTP/3 and HTTP/2: NGINX handles modern protocols; your backend can stay on HTTP/1.1

Basic Reverse Proxy Configuration

server {
    listen 443 ssl;
    http2 on;
    server_name api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:3000;   # Backend on port 3000

        # Pass real client IP to backend
        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;
    }
}

That’s the minimum working config. The four proxy_set_header lines are important — without them, your backend sees NGINX’s loopback IP as the client address, not the real user’s IP.

Timeouts: The Most Important Tuning

Default NGINX proxy timeouts are generous. For most applications, tighten them:

location / {
    proxy_pass http://127.0.0.1:3000;

    proxy_connect_timeout  5s;    # Max time to establish connection to backend
    proxy_send_timeout    60s;    # Max time to send request to backend
    proxy_read_timeout    60s;    # Max time to receive response from backend

    # For long-polling / streaming responses, increase read timeout:
    # proxy_read_timeout 3600s;
}

A backend that takes more than 60 seconds to respond is either broken or overwhelmed. Failing fast (with a 504) is better than keeping the connection open indefinitely.

Upstream Blocks: Clean Backend Management

Instead of hardcoding http://127.0.0.1:3000 everywhere, use an upstream block. This makes it easy to add servers later, and enables keepalive connection pooling:

http {
    upstream app_backend {
        server 127.0.0.1:3000;
        keepalive 32;   # Keep 32 persistent connections to the backend
    }

    server {
        location / {
            proxy_pass http://app_backend;

            # Required for keepalive to work with HTTP/1.1
            proxy_http_version 1.1;
            proxy_set_header Connection "";
        }
    }
}

The keepalive 32 keeps 32 idle connections to the backend alive in each NGINX worker. This eliminates the TCP handshake overhead for most requests. On a busy server, this alone reduces backend connection setup latency by 30–50%.

Buffering: For Slow Clients

By default, NGINX buffers the full response from your backend before sending it to the client. This frees your backend worker immediately, even if the client is on a slow connection:

location / {
    proxy_pass http://app_backend;

    proxy_buffering        on;           # Buffer responses (default: on)
    proxy_buffer_size      4k;           # Header buffer size
    proxy_buffers          8 16k;        # Response body buffers
    proxy_busy_buffers_size 32k;         # Max buffer before writing to temp file

    # For large file downloads, disable buffering to stream directly:
    # proxy_buffering off;

    # For Server-Sent Events / long-polling, disable buffering:
    # proxy_buffering off;
    # proxy_cache off;
}

Proxy Caching

NGINX can cache backend responses and serve them directly without hitting your backend at all. For content that doesn’t change per-user (public API responses, rendered pages), this is a massive performance win:

http {
    # Define cache zone: 100MB storage, 10 minutes inactive TTL
    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=app_cache:10m
                     max_size=100m inactive=10m use_temp_path=off;

    upstream app_backend {
        server 127.0.0.1:3000;
        keepalive 32;
    }

    server {
        location /api/public/ {
            proxy_pass http://app_backend;

            proxy_cache            app_cache;
            proxy_cache_valid 200  60s;  # Cache 200 responses for 60 seconds
            proxy_cache_valid 404  10s;  # Cache 404s for 10 seconds
            proxy_cache_use_stale  error timeout updating;

            # Add cache status to response headers (for debugging)
            add_header X-Cache-Status $upstream_cache_status;
        }
    }
}

Cache status values in the X-Cache-Status header: HIT (served from cache), MISS (fetched from backend and cached), BYPASS (cache bypassed), EXPIRED (cache entry expired, re-fetched).

WebSocket Proxying

WebSocket upgrades require specific headers to work through a reverse proxy:

location /ws/ {
    proxy_pass http://app_backend;

    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;   # Keep WebSocket connections alive
    proxy_send_timeout 3600s;
}

Serving Static Files Directly

For maximum performance, serve static files directly from NGINX’s file system, bypassing your backend entirely:

server {
    root /var/www/app/public;

    # Serve static assets directly
    location ~* .(js|css|png|jpg|webp|svg|woff2|ico)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        try_files $uri =404;
    }

    # Everything else goes to the backend
    location / {
        try_files $uri @backend;
    }

    location @backend {
        proxy_pass http://app_backend;
        proxy_set_header Host            $host;
        proxy_set_header X-Real-IP       $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Security Headers and Hardening

server {
    # Hide backend server header
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;

    # Add security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options SAMEORIGIN always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    location / {
        proxy_pass http://app_backend;

        # Don't pass internal headers to the backend
        proxy_set_header X-Internal-Auth "";
        proxy_set_header Authorization  "";
    }
}

Proxying to Unix Sockets

If your backend runs on the same server, Unix sockets are faster than TCP loopback — no network stack overhead:

upstream app_backend {
    server unix:/run/app/gunicorn.sock;  # Python/Gunicorn
    # or:
    server unix:/run/php/php8.4-fpm.sock;  # PHP-FPM
    keepalive 16;
}

location / {
    proxy_pass http://app_backend;
}

Frequently Asked Questions

Related Posts

• NGINX Load Balancing Guide — extend this to multiple backends with health checks and failover
• TLS Configuration for NGINX — the SSL termination config that pairs with reverse proxy
• Enable HTTP/3 on NGINX — add QUIC to your reverse proxy for modern browsers
• NGINX Performance Expert Guide — full tuning guide including proxy cache and upstream configuration
• Angie Web Server Complete Guide — Angie handles reverse proxy identically to NGINX with extra monitoring features

This guide covers NGINX rate limiting from scratch: the core concepts, the directives, how to limit different endpoints differently, how to handle burst traffic without breaking legitimate users, and how to combine rate limiting with the dynamic modules from the myguard repository for even more control.

How NGINX Rate Limiting Works

NGINX rate limiting uses the leaky bucket algorithm. Think of it as a bucket with a small hole in the bottom. Requests flow in from the top; they drain out the bottom at a fixed rate. If requests arrive faster than the drain rate, the bucket fills up. Once full, excess requests are either delayed (held in a queue) or rejected with a 429 status code.

Two directives do the work:

• limit_req_zone — defined in the http block; declares a shared memory zone and sets the rate
• limit_req — applied in a server or location block; activates rate limiting using a named zone

Basic Rate Limiting Configuration

http {
    # Define a zone: track by IP, 10MB shared memory, 10 req/sec per IP
    limit_req_zone $binary_remote_addr zone=general:10m rate=10r/s;

    server {
        listen 443 ssl;
        server_name example.com;

        location / {
            limit_req zone=general;
            # ... rest of config
        }
    }
}

The $binary_remote_addr variable uses the binary representation of the IP address (4 bytes for IPv4, 16 for IPv6) as the key — more memory-efficient than the string form. A 10MB zone holds about 160,000 IP state entries.

Understanding Burst

A rate of 10r/s means NGINX allows one request per 100ms. If a user sends two requests in a 50ms window, the second one gets a 503 immediately. That’s too strict for real browsers — a page load triggers many simultaneous requests (HTML, CSS, JS, images).

The burst parameter adds a queue for excess requests:

location / {
    limit_req zone=general burst=20;
    # The burst queue holds up to 20 excess requests
    # They're delayed (not rejected) until the rate allows them through
}

With burst=20 and rate=10r/s: up to 20 requests can queue up and be processed in order. A 21st request gets a 503. This handles legitimate page load bursts without breaking the overall rate limit.

Add nodelay to process burst requests immediately instead of delaying them:

limit_req zone=general burst=20 nodelay;
# Burst requests are processed immediately, not queued
# The burst allowance still refills at the zone's rate

Protecting Specific Endpoints

Different endpoints need different limits. A login page needs much tighter limits than a static page. Define multiple zones:

http {
    # General traffic: 20 req/sec per IP
    limit_req_zone $binary_remote_addr zone=general:10m rate=20r/s;

    # Login endpoint: 5 req/min per IP (credential stuffing protection)
    limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;

    # API: 100 req/sec per IP
    limit_req_zone $binary_remote_addr zone=api:10m rate=100r/s;

    # Search: 10 req/min per IP (expensive queries)
    limit_req_zone $binary_remote_addr zone=search:10m rate=10r/m;

    server {
        location / {
            limit_req zone=general burst=30 nodelay;
        }

        location /wp-login.php {
            limit_req zone=login burst=3;
            # At 5r/min with burst=3: allows a brief login attempt
            # but hammering with 100 attempts/second gets a 429 immediately
        }

        location /api/ {
            limit_req zone=api burst=50 nodelay;
        }

        location /?s= {
            limit_req zone=search burst=2;
        }
    }
}

Rate Limiting by Multiple Keys

Rate limiting by IP alone can be too coarse — legitimate users behind corporate NAT or proxies share an IP. Rate limiting by IP + user agent or IP + URL gives more granular control:

http {
    # Rate limit by IP + URI (different budget per URL per IP)
    limit_req_zone "$binary_remote_addr$uri" zone=per_uri:20m rate=5r/s;

    # Rate limit authenticated users by user ID header
    # (your backend sets X-User-ID after auth)
    limit_req_zone $http_x_user_id zone=per_user:10m rate=50r/s;
}

Returning Custom 429 Responses

By default, rate-limited requests get a plain 503. Change this to a proper 429 (Too Many Requests) with a Retry-After header:

http {
    limit_req_status 429;

    server {
        # Custom JSON error for API clients
        error_page 429 /rate-limited.json;
        location = /rate-limited.json {
            internal;
            default_type application/json;
            return 429 '{"error":"rate_limit_exceeded","retry_after":60}';
            add_header Retry-After 60 always;
        }
    }
}

Whitelisting Trusted IPs

Internal monitoring tools, load balancer health checks, and your own IP should bypass rate limiting:

http {
    # Geo-based bypass: set $limit to empty string for trusted IPs
    geo $limit {
        default         $binary_remote_addr;  # Apply limit
        10.0.0.0/8      "";                   # Internal: no limit
        192.168.0.0/16  "";                   # Private: no limit
        203.0.113.42    "";                   # Your office IP: no limit
    }

    limit_req_zone $limit zone=general:10m rate=10r/s;

    # When $limit is empty, no rate-limit state is tracked
    # This is the correct zero-overhead bypass approach
}

Monitoring Rate Limit Events

NGINX logs rate limit rejections to the error log at warn level by default. To log them at error level (so they appear in your monitoring), or to suppress the log noise for expected traffic patterns:

location /wp-login.php {
    limit_req zone=login burst=3;
    limit_req_log_level error;   # Log rejections as errors (default: warn)
    # or:
    limit_req_log_level info;    # Suppress from error monitoring
}

# Count rate limit events in real-time
grep 'limiting requests' /var/log/nginx/error.log | wc -l
tail -f /var/log/nginx/error.log | grep 'limiting'

WordPress-Specific Rate Limiting

For a WordPress site, these are the endpoints worth rate limiting most aggressively:

http {
    limit_req_zone $binary_remote_addr zone=wp_login:10m   rate=5r/m;
    limit_req_zone $binary_remote_addr zone=wp_comments:5m rate=1r/m;
    limit_req_zone $binary_remote_addr zone=xmlrpc:5m      rate=1r/m;
    limit_req_zone $binary_remote_addr zone=general:20m    rate=30r/s;

    server {
        # Credential stuffing protection
        location = /wp-login.php {
            limit_req zone=wp_login burst=3;
        }

        # XML-RPC is a DDoS amplification target — block entirely if unused
        location = /xmlrpc.php {
            limit_req zone=xmlrpc burst=1;
            # Or just block it: return 403;
        }

        # Comment spam protection
        location = /wp-comments-post.php {
            limit_req zone=wp_comments burst=1;
        }

        # wp-admin: protect but allow legitimate admin use
        location /wp-admin/ {
            limit_req zone=general burst=20 nodelay;
        }
    }
}

Redis-Backed Cross-Server Rate Limiting

NGINX’s built-in rate limiting uses shared memory within a single server. If you have multiple NGINX instances behind a load balancer, each one has independent rate limit state — a bot that hits different servers can exceed your intended rate by a factor of N.

For true cross-server rate limiting, use the NGINX Lua module with Redis:

location /wp-login.php {
    access_by_lua_block {
        local redis = require "resty.redis"
        local red = redis:new()
        red:set_timeouts(50, 50, 50)
        red:connect("127.0.0.1", 6379)

        local key = "rl:login:" .. ngx.var.binary_remote_addr
        local count = red:incr(key)
        if count == 1 then red:expire(key, 60) end
        red:set_keepalive(10000, 20)

        if count and count > 5 then
            ngx.header["Retry-After"] = "60"
            return ngx.exit(429)
        end
    }
}

Frequently Asked Questions

Related Posts

• NGINX ModSecurity WAF Setup — pair rate limiting with WAF for comprehensive attack protection
• NGINX Lua Module Guide — Redis-backed rate limiting for multi-server setups
• NGINX Dynamic Modules Overview — all 50+ modules including the GeoIP2 module for geo-based limits
• NGINX Performance and Security Expert Guide — full security and performance hardening guide
• Angie Web Server Complete Guide — rate limiting works identically on Angie

The myguard APT repository ships a native Brotli dynamic module for both NGINX and Angie — install it with one apt command, load it with one config line, and your server starts serving Brotli to every browser that supports it.

Brotli vs Gzip: The Actual Numbers

Brotli uses a combination of LZ77, Huffman coding, and a 2nd-order context modeling that gzip doesn’t have. The practical result:

Brotli level 11 (maximum) achieves 20–26% better compression than gzip, but is extremely slow to encode — suitable only for pre-compressed static assets, not on-the-fly. Level 4–6 is the sweet spot for on-the-fly dynamic compression: better than gzip, fast enough for real-time use.

Step 1 — Install the Brotli Module

# Add the myguard repository if not already done
wget https://deb.myguard.nl/pool/myguard.deb
dpkg -i myguard.deb
apt-get update

# Install NGINX with the Brotli module
apt-get install nginx libnginx-mod-http-brotli

# Or for Angie:
apt-get install angie angie-module-http-brotli

New to the myguard repository? Follow the two-minute setup guide.

Step 2 — Load the Module

The myguard package installs a load snippet automatically. Verify it’s in place:

ls /etc/nginx/modules-enabled/ | grep brotli
# Should show: 50-mod-http-brotli-filter.conf and 50-mod-http-brotli-static.conf

If not present, add to the top of nginx.conf (before the http block):

load_module modules/ngx_http_brotli_filter_module.so;
load_module modules/ngx_http_brotli_static_module.so;

Step 3 — Configure Brotli

Add this inside your http block in nginx.conf:

http {
    # Brotli dynamic compression (on-the-fly)
    brotli             on;
    brotli_comp_level  6;        # 0-11, sweet spot is 4-6
    brotli_min_length  256;      # Don't compress tiny responses
    brotli_types
        text/plain
        text/css
        text/javascript
        text/xml
        text/x-component
        application/javascript
        application/json
        application/xml
        application/rss+xml
        application/atom+xml
        application/vnd.ms-fontobject
        image/svg+xml
        font/truetype
        font/opentype;

    # Brotli static files (serve pre-compressed .br files)
    brotli_static on;

    # Keep gzip as fallback for browsers that don't support Brotli
    gzip            on;
    gzip_comp_level 6;
    gzip_min_length 256;
    gzip_vary       on;
    gzip_types
        text/plain text/css text/javascript application/javascript
        application/json application/xml image/svg+xml font/opentype;
}

Step 4 — Test and Reload

nginx -t && systemctl reload nginx

Verify Brotli is working:

# curl with Brotli accept header
curl -H 'Accept-Encoding: br,gzip' -I https://example.com
# Look for: Content-Encoding: br

# Check Chrome DevTools: Network tab > select a request > Response Headers > Content-Encoding: br

Pre-Compressed Static Assets (Best Performance)

For static files that don’t change (CSS, JS, fonts), pre-compress them at build time with level 11 and let NGINX serve the .br files directly. This gives maximum compression with zero runtime CPU cost:

# Pre-compress all JS and CSS files in your web root
find /var/www/html -name '*.js' -o -name '*.css' | while read f; do
    brotli -Z -f "$f" -o "${f}.br"   # -Z = level 11
    gzip -9 -k -f "$f"               # -k = keep original, for fallback
done

With brotli_static on in your NGINX config, when a browser requests app.js with Accept-Encoding: br, NGINX automatically serves app.js.br without doing any runtime compression. Zero CPU, maximum compression.

# Install the brotli CLI tool
apt-get install brotli

Brotli for WordPress

WordPress sites benefit significantly from Brotli because WordPress generates a lot of HTML, CSS, and JavaScript. The main caveat: PHP responses are compressed dynamically, so set a sane compression level (4–6) to avoid adding more than ~1ms of CPU time per request.

Typical page size reduction for a WordPress homepage:

• Uncompressed HTML: ~180KB
• Gzip level 6: ~28KB
• Brotli level 6: ~23KB
• Brotli level 11 (pre-compressed): ~19KB

The 5KB difference between gzip and Brotli level 6 saves ~40ms on a typical 4G connection. Across thousands of page views, that’s meaningful for Core Web Vitals.

Brotli + zstd: Running Both

The myguard repository also ships a zstd NGINX module. zstd excels at server-side API compression (faster decode, great for JSON) while Brotli excels at browser-facing content (better compression ratio). Run both:

apt-get install libnginx-mod-http-brotli libnginx-mod-http-zstd

# In http block:
brotli on;        # For browsers (HTML, CSS, JS)
brotli_types text/html text/css application/javascript image/svg+xml;

zstd on;          # For API clients that support it
zstd_types application/json application/x-ndjson;
zstd_comp_level 3;

Frequently Asked Questions

Related Posts

• zstd NGINX Module: What It Does and 22 Bug Fixes — the other modern compression option, great for API workloads
• NGINX Dynamic Modules Overview — Brotli is one of 50+ available modules
• NGINX Performance and Security Expert Guide — full performance tuning guide including compression strategy
• NGINX vs Apache Benchmark 2026 — performance comparison including compression overhead
• How to Add the myguard APT Repository — where the Brotli module comes from

The good news: the myguard APT repository has shipped Trixie packages since day one of the testing cycle. Install NGINX or Angie from deb.myguard.nl and you automatically get builds compiled natively on Trixie’s toolchain — not backports, not compatibility shims, not “should work” guesswork.

What Is Debian 13 Trixie?

Trixie is the development codename for Debian’s next stable release. Debian names its releases after Toy Story characters — after Bookworm (Debian 12) comes Trixie, the triceratops. Once Trixie is declared stable (expected 2025–2026), it will become “Debian 13” and receive five-plus years of security support.

Right now, Trixie is in “testing” status: it receives updates continuously, packages are more recent than Bookworm’s, and it’s broadly stable but not yet officially blessed for production. Many sysadmins run Trixie on servers where they want newer software without compiling from source. The myguard repository treats Trixie as a first-class target.

What Changed in Trixie That Affects NGINX

GCC 14 Compiler

Our Trixie NGINX and Angie packages are compiled with GCC 14, which enables more aggressive auto-vectorization and improved link-time optimization. GCC 14 is also stricter about certain C code patterns — this pushed a few module patches to ensure clean compilation. The result: measurably better performance on modern CPUs, especially for compression (brotli, zstd, gzip) which is heavily vectorized.

Approximate GCC 14 gains on amd64:

• Brotli compression: ~8–12% faster encoding from improved Huffman codec vectorization
• zstd compression: ~6–10% faster at level 3 via AVX2 path improvements
• TLS handshakes: ~5% improvement from better P-256 curve codegen

OpenSSL 3.3 (vs 3.0 on Bookworm)

Bookworm shipped with OpenSSL 3.0 LTS. Trixie upgrades to OpenSSL 3.3, which brings improved TLS 1.3 internals, better QUIC support, and performance improvements in elliptic curve operations. This matters even if you use our dedicated openssl-nginx package (which is compiled independently), because the system OpenSSL is used by tools you run alongside NGINX — certbot, curl, the openssl CLI, Python scripts.

OpenSSL 3.3 is also stricter about malformed certificates that 3.0 accepted with warnings. Validate internal/self-signed certs before upgrading: openssl verify -CAfile /path/to/ca.pem /path/to/cert.pem

PHP 8.4 Default

Trixie’s default PHP version is 8.4. If you’re running PHP-FPM with NGINX for WordPress, check plugin compatibility before upgrading. PHP 8.4 promoted some dynamic property deprecation warnings to errors — well-maintained plugins are fine, but older ones that haven’t been updated since 2020 may throw fatal errors.

Quick compatibility check before upgrading:

php8.4 -f /path/to/wp-config.php 2>&1 | grep -i fatal
php8.4 -m | grep -v '[' | sort  # List loaded modules

For PHP security hardening, the myguard repository ships php8.4-snuffleupagus — install it alongside PHP-FPM for interpreter-level protection.

systemd 256

Trixie ships systemd 256, which introduces more aggressive cgroup isolation defaults. This is mostly transparent for NGINX, but if you use custom systemd service overrides touching PrivateTmp, ProtectSystem, or cgroup limits, review them. The standard NGINX and Angie systemd units from the myguard packages are already updated for systemd 256 compatibility.

Linux Kernel 6.11+

Trixie tracks a much newer kernel than Bookworm’s 6.1. For NGINX specifically, the newer kernel improves kTLS (Kernel TLS offload) performance, improves io_uring support, and has better QUIC-layer socket handling. If you enable kTLS on Trixie, you’re getting noticeably better TLS offload than on Bookworm.

# Verify kTLS is available
modprobe tls && lsmod | grep tls

# Enable in nginx.conf
ssl_conf_command Options KTLS;

Installing NGINX or Angie on Trixie

Same as any other Debian release — add the myguard repository and install:

wget https://deb.myguard.nl/pool/myguard.deb
dpkg -i myguard.deb
apt-get update
apt-get install nginx    # or: apt-get install angie

Verify build info and check for the Trixie toolchain:

nginx -V 2>&1

New to the myguard repository? Follow the two-minute setup guide.

Upgrading from Bookworm to Trixie

# Step 1 — Back up NGINX config
tar -czf /tmp/nginx-config-backup.tar.gz /etc/nginx/

# Step 2 — Note current versions
nginx -V 2>&1 > /tmp/nginx-v-before.txt

# Step 3 — Update Debian sources
sed -i 's/bookworm/trixie/g' /etc/apt/sources.list
apt update
apt full-upgrade

# Step 4 — myguard repo auto-detects Trixie, no changes needed
apt install nginx   # refresh to Trixie build

# Step 5 — Test and reload
nginx -t && systemctl reload nginx

Fresh Install Checklist for Trixie

1. Add myguard repository: wget https://deb.myguard.nl/pool/myguard.deb && dpkg -i myguard.deb
2. Install NGINX: apt-get install nginx — pulls in openssl-nginx automatically
3. Add modules: brotli, ModSecurity, Lua, GeoIP2 — all available as dynamic modules
4. Open UDP 443: HTTP/3 requires it — ufw allow 443/udp
5. Configure TLS: Use the TLS guide for A+ on SSL Labs
6. Install PHP-FPM: apt-get install php8.4-fpm php8.4-mysql php8.4-xml php8.4-curl
7. Harden PHP: apt-get install php8.4-snuffleupagus

Module Compatibility on Trixie

All 50+ dynamic modules in the myguard repository are compiled natively for Trixie — no compatibility layer, built against the same NGINX and library versions as the main packages:

apt-get install libnginx-mod-http-brotli       # Brotli compression
apt-get install libnginx-mod-http-modsecurity  # ModSecurity WAF
apt-get install libnginx-mod-http-lua          # Lua scripting
apt-get install libnginx-mod-http-zstd         # Zstandard compression
apt-get install libnginx-mod-http-geoip2       # GeoIP2 routing

Known Issues and Gotchas

PHP 8.4 strict deprecations

Some older WordPress plugins throw deprecation notices under PHP 8.4. They won’t break your site but may spam the error log. Suppress them with error_reporting = E_ALL & ~E_DEPRECATED in your FPM pool config while waiting for plugin updates.

systemd 256 PrivateTmp changes

If you use a custom /etc/systemd/system/nginx.service.d/override.conf that modifies PrivateTmp with custom paths, review it. systemd 256 changed how PrivateTmp interacts with bind-mounted directories. The default myguard service unit is already correct.

Frequently Asked Questions

Related Posts

• How to Add the myguard APT Repository — two-minute setup for Debian and Ubuntu
• NGINX Dynamic Modules Overview — all 50+ modules, with Trixie packages available for each
• TLS Configuration Guide for NGINX and Angie — A+ SSL Labs config with TLS 1.3 and HSTS
• Angie Web Server: The Complete Guide — review, ACME, migration guide, and monitoring
• How to Enable HTTP/3 on NGINX — QUIC setup that works on Trixie out of the box

Changes

• Full rebuild and backport with latest Mainline
• Merged with the source package from Debian Trixie in november 2023
• See for more information https://deb.myguard.nl/nginx-modules/
• Changelog: https://deb.myguard.nl/forums/topic/changelog/

Distributions

• bookworm
• jammy
• noble
• resolute
• trixie

PHP-Snuffleupagus is a PHP extension that adds a security layer inside the PHP interpreter itself. Not at the HTTP layer. Not at the network layer. Inside PHP, where function calls actually happen. An attacker can craft an HTTP request that bypasses your WAF. They cannot bypass the PHP interpreter — Snuffleupagus runs inside it.

Think of it like this: ModSecurity is a bouncer at the front door of your restaurant. Snuffleupagus is a bouncer who lives in the kitchen. Even if someone sneaks in through the window, they still can’t touch the knives.

The myguard APT repository ships php-snuffleupagus as a pre-built package for Debian and Ubuntu, covering PHP 7.4 through 8.4. No compilation required. This guide goes deeper than the official docs — which are sparse — and covers everything from basic installation to WordPress-specific hardening to production tuning.

What Snuffleupagus actually blocks

Unlike a WAF that pattern-matches HTTP strings, Snuffleupagus controls what PHP is allowed to do. Here’s what that means in practice:

Dangerous function blocking

PHP has a set of functions that legitimate applications almost never need but attackers always want: eval(), system(), exec(), passthru(), shell_exec(), popen(), proc_open(). If an attacker injects code and it reaches PHP, these are what they call to execute commands on your server. Snuffleupagus blocks them at the interpreter — before execution, not after.

The crucial difference from PHP’s built-in disable_functions: Snuffleupagus is conditional. Block exec() only in requests coming from the uploads directory. Block file_get_contents() only when called with a remote URL. Block system() everywhere except one specific legacy script that genuinely needs it. Surgical, not blunt.

Cookie encryption and hardening

Snuffleupagus can transparently encrypt all cookies your application sets, adding an HMAC to detect tampering. It also enforces HttpOnly, Secure, and SameSite flags on every cookie, even ones your application forgot to flag. Session hijacking via cookie theft becomes dramatically harder.

File upload protection

One of the most common attack patterns: upload a PHP file disguised as an image, then trigger its execution via a URL. Snuffleupagus can block PHP from including or executing files from your upload directory entirely. A PHP file in wp-content/uploads/ cannot execute, period — no matter how it got there.

Type juggling prevention

PHP’s loose comparison operator (==) has infamous edge cases: "0e12345" == "0" is true because both evaluate as floating-point zero in scientific notation. Attackers exploit this to bypass password hash comparisons (the “magic hash” vulnerability). Snuffleupagus enforces strict comparisons in sensitive contexts.

Remote file inclusion blocking

PHP can include files from remote URLs if allow_url_include is on (it shouldn’t be, but legacy apps). Snuffleupagus blocks file_get_contents(), include(), and require() from fetching remote resources, regardless of PHP’s config.

XSS output filtering

Snuffleupagus can inject htmlspecialchars() calls transparently before PHP outputs content to the browser. This is a last-resort safety net for applications you can’t modify — it won’t catch every XSS vector but it catches the most common ones.

Snuffleupagus vs ModSecurity: use both

People always ask whether Snuffleupagus replaces ModSecurity. It doesn’t. They live at completely different layers and catch completely different attacks.

The attack chain typically goes: HTTP request → WAF layer → PHP layer → application. ModSecurity blocks at the WAF layer. Snuffleupagus blocks at the PHP layer. Run both and an attacker has to bypass two independent security systems at different levels of the stack. See the ModSecurity setup guide for the WAF side of this.

Step 1 — Install php-snuffleupagus

wget https://deb.myguard.nl/pool/myguard.deb
dpkg -i myguard.deb
apt-get update
apt-get install php-snuffleupagus

The package installs the extension for all PHP versions it finds on your system. Check it’s available:

ls /usr/lib/php/*/snuffleupagus.so
# You should see one file per installed PHP version

Step 2 — Enable the extension

You need to both load the extension and point it at a rules file. Do this per PHP version. For PHP 8.3:

cat > /etc/php/8.3/fpm/conf.d/20-snuffleupagus.ini <<'EOINI'
extension=snuffleupagus.so
sp.configuration_file=/etc/php/8.3/snuffleupagus.rules
EOINI

If you’re running multiple PHP versions (common with multiple sites), repeat for each version. The rules file path can be the same or different per version — using version-specific paths gives you more flexibility.

Create the rules file (empty for now — the extension requires it to exist):

touch /etc/php/8.3/snuffleupagus.rules

Restart PHP-FPM and verify the extension loaded:

systemctl restart php8.3-fpm
php8.3 -m | grep snuffleupagus
# Should output: snuffleupagus

Step 3 — The golden rule: start in log mode

Before you write a single blocking rule, understand this: every blocking rule is a potential outage. WordPress and its plugins use a broad range of PHP features. A rule that blocks exec() globally will break any plugin that calls it for legitimate image processing or PDF generation.

The workflow is always: log → review → whitelist false positives → block. Never jump straight to blocking on a live site.

In Snuffleupagus rules, .simulation() logs a violation but doesn’t block. .log() also just logs. .drop() blocks the call and returns false. .kill() terminates the PHP process entirely.

Start your rules file with simulation on the scary stuff:

sp.enable();

# Dangerous execution functions — simulation first
sp.disable_function.function("system").simulation();
sp.disable_function.function("exec").simulation();
sp.disable_function.function("passthru").simulation();
sp.disable_function.function("shell_exec").simulation();
sp.disable_function.function("proc_open").simulation();
sp.disable_function.function("popen").simulation();

Restart PHP-FPM, then watch the log:

systemctl restart php8.3-fpm
tail -f /var/log/php8.3-fpm.log | grep -i snuffleupagus

Browse your site. Send some test requests. If you see violations in the log, read them carefully before deciding whether they’re legitimate. A WordPress plugin calling exec() to run ImageMagick is probably legitimate. Same call from a request touching wp-content/uploads/ is not.

Step 4 — Production baseline rules

Once you’ve done a day or two of simulation and confirmed your false positive picture, build your production rules file. This baseline is conservative — it blocks things nearly all PHP applications never legitimately need:

sp.enable();

# ---- Cookie hardening ----
# Encrypt all cookies and enforce security flags
# WARNING: This invalidates existing sessions. Deploy during maintenance window
# or exclude specific cookies with sp.cookie.name("PHPSESSID").attribute().drop();
sp.cookie.name("*").encrypt();

# ---- Kill eval() ----
# Almost no legitimate application needs eval(). Template engines and ORMs
# that used to need it have moved on. Legacy apps: test first.
sp.disable_function.function("eval").drop();

# ---- Block remote command execution ----
sp.disable_function.function("system").drop();
sp.disable_function.function("exec").drop();
sp.disable_function.function("passthru").drop();
sp.disable_function.function("shell_exec").drop();
sp.disable_function.function("popen").drop();
sp.disable_function.function("proc_open").drop();

# ---- Block remote file inclusion ----
# Blocks file_get_contents("http://...") and file_get_contents("https://...")
# Add whitelists for APIs your code legitimately calls:
# sp.disable_function.function("file_get_contents").param("filename").value_r("^https://api.trusted.com").allow();
sp.disable_function.function("file_get_contents").param("filename").value_r("^https?://").drop();

# ---- Block PHP execution from upload directories ----
# Webshells in uploads can't execute if PHP can't include files from there
sp.disable_function.function("include").filename_r("/uploads/").drop();
sp.disable_function.function("include_once").filename_r("/uploads/").drop();
sp.disable_function.function("require").filename_r("/uploads/").drop();
sp.disable_function.function("require_once").filename_r("/uploads/").drop();

# ---- Information disclosure ----
sp.disable_function.function("phpinfo").drop();
sp.disable_function.function("getenv").param("varname").value("AWS_SECRET_ACCESS_KEY").drop();
sp.disable_function.function("getenv").param("varname").value("DB_PASSWORD").drop();

Step 5 — WordPress-specific hardening

WordPress is the most common PHP application and the most commonly attacked. These rules are tuned specifically for WordPress’s function usage patterns.

# ---- WordPress-specific rules ----

# Block PHP execution in WordPress upload directory
sp.disable_function.function("include").filename_r("/wp-content/uploads/").drop();
sp.disable_function.function("include_once").filename_r("/wp-content/uploads/").drop();
sp.disable_function.function("require").filename_r("/wp-content/uploads/").drop();
sp.disable_function.function("require_once").filename_r("/wp-content/uploads/").drop();

# Suspicious base64 decode output — log only (WP legitimately uses base64)
# Long base64-decoded strings are often shellcode. Log first, block once confirmed.
sp.disable_function.function("base64_decode").ret_r(".{500,}").log();

# Block use of assert() as eval() substitute (old WordPress exploit technique)
sp.disable_function.function("assert").param("assertion").value_r("\$").drop();

# Prevent direct access to wp-config.php via LFI
sp.disable_function.function("file_get_contents").param("filename").value_r("wp-config.php").drop();

# Cookie hardening for WordPress sessions
# Use specific cookie name instead of wildcard to avoid breaking payment plugins
sp.cookie.name("wordpress_logged_in*").encrypt();
sp.cookie.name("PHPSESSID").encrypt();

Testing your WordPress rules

After applying, test these WordPress functions work correctly:

• Log in and out — cookies must work
• Upload an image — the upload must work but PHP execution in uploads must fail
• Edit a post — the Gutenberg editor uses REST API calls, verify these work
• Run any background WP-Cron jobs manually: wp cron event run --due-now --allow-root

Step 6 — Per-site rules with PHP-FPM pools

If you’re running multiple sites on the same server, you can apply different rule sets per PHP-FPM pool. A legacy application that legitimately calls exec() gets lenient rules. A modern WordPress site gets strict rules. No cross-contamination.

In each pool config (/etc/php/8.3/fpm/pool.d/mysite.conf):

[mysite]
user = www-data
group = www-data
listen = /run/php/php8.3-fpm-mysite.sock

; Override the snuffleupagus rules file for this pool
php_admin_value[extension] = snuffleupagus.so
php_admin_value[sp.configuration_file] = /etc/php/8.3/snuffleupagus-mysite.rules

[legacyapp]
user = www-data
group = www-data
listen = /run/php/php8.3-fpm-legacy.sock

; Minimal rules for legacy app that needs exec()
php_admin_value[extension] = snuffleupagus.so
php_admin_value[sp.configuration_file] = /etc/php/8.3/snuffleupagus-legacy.rules

The legacy rules file can block everything except the specific functions the legacy app needs:

sp.enable();

# Legacy app needs exec() for PDF generation — allow it but log
sp.disable_function.function("system").drop();
sp.disable_function.function("passthru").drop();
sp.disable_function.function("shell_exec").drop();
# exec() allowed — only log unusual calls
sp.disable_function.function("exec").param("command").value_r("[;&|`]").log();

Step 7 — Advanced rules

Block specific parameter patterns

You can match on function arguments, not just function names:

# Block file_get_contents() when the path looks like a traversal attack
sp.disable_function.function("file_get_contents").param("filename").value_r("../").drop();

# Block unserialize() on user-controlled data (common deserialization attack vector)
# The variable name check is heuristic — adjust to your app
sp.disable_function.function("unserialize").param("data").value_r("[Oo]:d+:").drop();

# Block preg_replace() with /e modifier (executes replacement as PHP code)
# This was deprecated in PHP 5.5 and removed in 7.0 but some legacy code still has it
sp.disable_function.function("preg_replace").param("pattern").value_r("/e").drop();

Global request-level rules

# Enable XSS output filtering as a last-resort safety net
# This transparently runs htmlspecialchars() on outputs when enabled
# Only use on applications you can't modify — it has false positives
# sp.global_strict = true;

# Log all calls to dangerous functions regardless of whether they're blocked
# Useful for forensics and building a whitelist before blocking
sp.disable_function.function("eval").simulation();
sp.disable_function.function("exec").simulation();

Environment-specific tuning

# Harden unserialize() with an allowed classes list
# Prevents object injection attacks — only allow specific classes to be unserialized
sp.disable_function.function("unserialize").param("allowed_classes").value_r("false").drop();

# Block PHP reflection API (used in some deserialization exploit chains)
sp.disable_function.function("ReflectionObject").drop();

# Block symbolic link creation (used in some privilege escalation chains)
sp.disable_function.function("symlink").drop();

Reading the logs

Snuffleupagus logs to the PHP-FPM error log. Each violation entry contains the rule that triggered, the function called, the file and line number, and the actual arguments. Learn to read these — they tell you exactly what happened:

tail -f /var/log/php8.3-fpm.log | grep -i "snuffleupagus|sp_"

# A blocked call looks like:
# [snuffleupagus][eval][block] in /var/www/html/wp-content/plugins/bad-plugin/shell.php:1
# [snuffleupagus][file_get_contents][drop] in /var/www/html/wp-content/uploads/cmd.php:1

# A simulation (would-have-been-blocked) looks like:
# [snuffleupagus][exec][simulation] called in /path/to/file.php:42

The file path tells you which application or plugin triggered the rule. If it’s from uploads/, it’s almost certainly an attack. If it’s from a known plugin directory, investigate whether the plugin legitimately needs that function.

Building a whitelist from simulation logs

After running in simulation mode, look for patterns in the log:

grep "snuffleupagus" /var/log/php8.3-fpm.log | grep simulation | awk '{print $NF}' | sort | uniq -c | sort -rn

The most common violations are usually the ones you need to whitelist. Add specific exceptions for them before switching to .drop():

# Whitelist exec() only for the specific ImageMagick plugin path
sp.disable_function.function("exec").param("command").value_r("convert").allow();
sp.disable_function.function("exec").drop();   # block everything else

Performance impact

A common question: does Snuffleupagus slow PHP down? The honest answer: yes, slightly. How slightly depends on your rules.

• Cookie encryption: adds one AES operation per cookie per request. On modern CPUs this is microseconds.
• Function call checking: each disabled function check adds a small overhead at the opcode level. For rules that fire rarely (blocked functions), this is negligible.
• Global strict mode (XSS filter): this touches every output operation and has measurable overhead. Only enable it if you genuinely can’t modify the application.

For a typical WordPress site serving PHP pages, expect 1–3ms additional processing time per request. On a well-cached site where most requests are served from cache by NGINX before reaching PHP, the impact on user-facing performance is essentially zero.

Frequently asked questions

Related posts

• NGINX ModSecurity WAF Setup — the HTTP layer to pair with Snuffleupagus for full-stack defence
• TLS Configuration for NGINX and Angie — hardening the transport layer alongside your PHP security stack
• Postfix + Dovecot Mail Server Setup — complete mail server guide for the same Debian/Ubuntu stack
• NGINX modules overview — ModSecurity is one of 50+ modules available via APT
• Full package list — php-snuffleupagus, libmodsecurity3, and all security packages
• How to add the myguard APT repository

Postfix + Dovecot + Rspamd is the production standard combination in 2026. Postfix handles SMTP (sending and receiving), Dovecot handles IMAP (what your mail client connects to), and Rspamd filters spam, signs outgoing mail with DKIM, and plugs into Postfix as a milter. All three are available from the myguard APT repository — updated within hours of upstream releases, so you’re never stuck on a version Debian stable froze two years ago.

This guide is thorough by design. You’ll finish with a fully working mail server on Debian 12 (Bookworm) or Debian 13 (Trixie), including TLS everywhere, SPF, DKIM, DMARC, spam filtering, and a 10/10 score on mail-tester.com. No shortcuts that come back to bite you at 2am.

What you’re building

A complete inbound + outbound mail server with:

• Postfix — receives mail on port 25 from the internet, accepts submissions from your users on port 587 (STARTTLS) and 465 (SMTPS)
• Dovecot — serves mail to your IMAP clients on port 993 (IMAPS), delivers mail from Postfix to Maildir via LMTP
• Rspamd — scans inbound mail for spam, signs outbound mail with DKIM, integrates with Postfix as a milter
• Redis — Rspamd’s backend for Bayes learning and rate limiting
• Let’s Encrypt TLS — proper certificates so mail clients don’t complain
• SPF, DKIM, DMARC — the three DNS records that prevent your mail from being treated as spam

Before you start — prerequisites

• A VPS or dedicated server with a static IP. Dynamic IPs are blacklisted by virtually every major mail provider. Hetzner, OVH, Contabo, and DigitalOcean all work well.
• Port 25 unblocked. Many providers block outbound port 25 by default. Contact support and ask them to unblock it. Hetzner does it within minutes. DigitalOcean requires account verification.
• A domain you control. You need to be able to edit DNS records — MX, TXT, and PTR.
• Reverse DNS (PTR record). Your server’s IP must resolve back to your mail hostname. Log in to your provider’s control panel and set the PTR record for your IP to mail.example.com. This is separate from your regular DNS — it’s set at the IP level.
• A valid hostname. Set your server’s hostname to match your PTR record: hostnamectl set-hostname mail.example.com.
• Firewall rules. Open ports 25 (SMTP), 465 (SMTPS), 587 (SMTP submission), 993 (IMAPS). Block 110 (POP3) and 143 (plain IMAP) — there’s no reason to offer unencrypted access.

Step 1 — Add the repository and install packages

wget https://deb.myguard.nl/pool/myguard.deb
dpkg -i myguard.deb
apt-get update
apt-get install postfix postfix-pcre dovecot-core dovecot-imapd dovecot-lmtpd rspamd redis-server

The installer will ask two questions during Postfix installation:

• Configuration type: select Internet Site
• System mail name: enter your domain — example.com, not mail.example.com

After installation, get a TLS certificate before touching any config. Everything breaks without one:

apt-get install certbot
certbot certonly --standalone -d mail.example.com

Step 2 — Configure Postfix

Postfix is configured through two files: /etc/postfix/main.cf (settings) and /etc/postfix/master.cf (service definitions). Replace your main.cf with this production configuration:

# Identity
myhostname = mail.example.com
mydomain = example.com
myorigin = $mydomain
mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain

# Network
inet_interfaces = all
inet_protocols = ipv4
mynetworks = 127.0.0.0/8

# Mailbox delivery via Dovecot LMTP
mailbox_transport = lmtp:unix:private/dovecot-lmtp
virtual_transport = lmtp:unix:private/dovecot-lmtp

# TLS inbound (from other mail servers)
smtpd_tls_cert_file = /etc/letsencrypt/live/mail.example.com/fullchain.pem
smtpd_tls_key_file = /etc/letsencrypt/live/mail.example.com/privkey.pem
smtpd_tls_security_level = may
smtpd_tls_protocols = !SSLv2,!SSLv3,!TLSv1,!TLSv1.1
smtpd_tls_mandatory_protocols = !SSLv2,!SSLv3,!TLSv1,!TLSv1.1
smtpd_tls_mandatory_ciphers = high
smtpd_tls_session_cache_database = btree:${data_directory}/smtpd_scache
smtpd_tls_loglevel = 1

# TLS outbound (to other mail servers)
smtp_tls_cert_file = /etc/letsencrypt/live/mail.example.com/fullchain.pem
smtp_tls_key_file = /etc/letsencrypt/live/mail.example.com/privkey.pem
smtp_tls_security_level = may
smtp_tls_protocols = !SSLv2,!SSLv3,!TLSv1,!TLSv1.1
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
smtp_tls_loglevel = 1

# SASL authentication (Dovecot handles this)
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_sasl_auth_enable = yes
smtpd_sasl_security_options = noanonymous

# Anti-spam restrictions
smtpd_recipient_restrictions =
  permit_mynetworks,
  permit_sasl_authenticated,
  reject_unauth_destination,
  reject_invalid_hostname,
  reject_non_fqdn_hostname,
  reject_non_fqdn_sender,
  reject_non_fqdn_recipient,
  reject_unknown_sender_domain,
  reject_unknown_recipient_domain,
  reject_rbl_client zen.spamhaus.org

# Rspamd milter
smtpd_milters = inet:127.0.0.1:11332
non_smtpd_milters = inet:127.0.0.1:11332
milter_protocol = 6
milter_default_action = accept

# Limits
message_size_limit = 52428800
mailbox_size_limit = 0

Now enable the submission ports in /etc/postfix/master.cf. Find (or uncomment) these lines:

submission inet n       -       y       -       -       smtpd
  -o syslog_name=postfix/submission
  -o smtpd_tls_security_level=encrypt
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_tls_auth_only=yes
  -o smtpd_reject_unlisted_recipient=no
  -o smtpd_relay_restrictions=permit_sasl_authenticated,reject
  -o milter_macro_daemon_name=ORIGINATING

smtps     inet  n       -       y       -       -       smtpd
  -o syslog_name=postfix/smtps
  -o smtpd_tls_wrappermode=yes
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_relay_restrictions=permit_sasl_authenticated,reject
  -o milter_macro_daemon_name=ORIGINATING

Step 3 — Configure Dovecot

Dovecot’s configuration lives in /etc/dovecot/dovecot.conf and the /etc/dovecot/conf.d/ directory. The conf.d approach is clean — each file handles one concern. Edit these key files:

/etc/dovecot/dovecot.conf

protocols = imap lmtp

/etc/dovecot/conf.d/10-mail.conf

mail_location = maildir:~/Maildir
namespace inbox {
  inbox = yes
}

/etc/dovecot/conf.d/10-ssl.conf

ssl = required
ssl_cert = </etc/letsencrypt/live/mail.example.com/fullchain.pem
ssl_key = </etc/letsencrypt/live/mail.example.com/privkey.pem
ssl_min_protocol = TLSv1.2
ssl_cipher_list = ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256
ssl_prefer_server_ciphers = yes

/etc/dovecot/conf.d/10-auth.conf

disable_plaintext_auth = yes
auth_mechanisms = plain login

!include auth-system.conf.ext

/etc/dovecot/conf.d/10-master.conf

This is the most important file — it wires Dovecot to Postfix via LMTP and auth sockets:

service imap-login {
  inet_listener imap {
    port = 0   # disable plain IMAP
  }
  inet_listener imaps {
    port = 993
    ssl = yes
  }
}

service lmtp {
  unix_listener /var/spool/postfix/private/dovecot-lmtp {
    mode = 0600
    user = postfix
    group = postfix
  }
}

service auth {
  unix_listener /var/spool/postfix/private/auth {
    mode = 0666
    user = postfix
    group = postfix
  }
  unix_listener auth-userdb {
    mode = 0600
    user = dovecot
  }
}

Create mail users

For a simple setup, use system users. Create a mail user for each mailbox:

useradd -m -s /sbin/nologin alice
useradd -m -s /sbin/nologin bob
passwd alice   # set a password for IMAP login

Step 4 — Configure Rspamd

Rspamd is a modern spam filter that replaces SpamAssassin — it’s significantly faster and has better default rules. It integrates with Postfix as a milter (mail filter), meaning Postfix runs every message through Rspamd before accepting it.

Enable Redis backend

cat > /etc/rspamd/local.d/redis.conf <<'EOF'
servers = "127.0.0.1";
EOF

Generate DKIM keys

DKIM cryptographically signs your outgoing mail. Every major mail provider (Gmail, Outlook, Yahoo) checks DKIM before deciding whether your mail is legitimate. Without it, you’ll land in spam.

mkdir -p /var/lib/rspamd/dkim
rspamadm dkim_keygen -s mail -d example.com -k /var/lib/rspamd/dkim/mail.key > /tmp/dkim-dns.txt
cat /tmp/dkim-dns.txt   # you'll need this DNS record shortly
chmod 640 /var/lib/rspamd/dkim/mail.key
chown rspamd:rspamd /var/lib/rspamd/dkim/mail.key

Configure DKIM signing

cat > /etc/rspamd/local.d/dkim_signing.conf <<'EOF'
path = "/var/lib/rspamd/dkim/$domain.$selector.key";
selector = "mail";
EOF

Set spam action thresholds

cat > /etc/rspamd/local.d/actions.conf <<'EOF'
reject = 15;      # reject outright (clear spam)
greylist = 4;     # greylist suspicious mail
add_header = 6;   # add X-Spam header
EOF

Enable the Rspamd web UI (optional)

cat > /etc/rspamd/local.d/worker-controller.inc <<'EOF'
bind_socket = "127.0.0.1:11334";
password = "$(rspamadm pw -p YOUR_PASSWORD_HERE)";
EOF

Access the UI through an SSH tunnel: ssh -L 11334:127.0.0.1:11334 yourserver, then open http://localhost:11334.

Step 5 — DNS records

These are the records that determine whether your mail gets delivered or dumped in spam. Every single one matters.

MX record — where to deliver mail to your domain

example.com.    IN  MX  10  mail.example.com.

A record — your mail server’s IP

mail.example.com.  IN  A  YOUR_SERVER_IP

PTR record (reverse DNS) — set at your provider, not in your DNS panel

Log into your VPS provider control panel. Find the IP management section. Set the PTR/reverse DNS for your server IP to mail.example.com. This is checked by most receiving servers. If it’s wrong, your mail will be rejected or flagged.

SPF record — which servers are allowed to send mail for your domain

example.com.  IN  TXT  "v=spf1 mx -all"

The mx means your MX server is allowed to send. The -all means everyone else is a hard fail. If you also send from a third-party service (Mailchimp, Sendgrid), add their include: clause before the -all.

DKIM record — the public key that validates your DKIM signatures

The public key was output in /tmp/dkim-dns.txt in the previous step. It looks like:

mail._domainkey.example.com.  IN  TXT  "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA..."

Copy the full string from your file. The key is long — make sure you get all of it.

DMARC record — policy for failed SPF/DKIM

_dmarc.example.com.  IN  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com; ruf=mailto:dmarc@example.com; fo=1"

Start with p=quarantine (send failures to spam) rather than p=reject (block them). Once you’ve monitored DMARC reports for a month and confirmed everything is aligned, switch to p=reject.

MTA-STS and TLSRPT (optional but recommended)

MTA-STS tells sending servers they must use TLS when delivering to you. Add:

_mta-sts.example.com.  IN  TXT  "v=STSv1; id=20260512"
_smtp._tls.example.com.  IN  TXT  "v=TLSRPTv1; rua=mailto:tlsrpt@example.com"

Then create a policy file at https://mta-sts.example.com/.well-known/mta-sts.txt:

version: STSv1
mode: enforce
mx: mail.example.com
max_age: 86400

Step 6 — Start and verify

systemctl enable --now redis-server rspamd dovecot postfix
systemctl restart redis-server rspamd dovecot postfix

Check each service is up

systemctl status postfix dovecot rspamd redis-server

Check ports are listening

ss -tlnp | grep -E '25|465|587|993|11332'

You should see Postfix on 25, 465, 587; Dovecot on 993; Rspamd milter on 11332.

Test SMTP inbound

telnet mail.example.com 25
# Should see: 220 mail.example.com ESMTP Postfix

Test IMAP

openssl s_client -connect mail.example.com:993
# Should see: * OK Dovecot ready.

Send a test email

echo "Test mail" | mail -s "Test" you@gmail.com
tail -f /var/log/mail.log

Watch the log for errors. A clean delivery looks like:

postfix/smtp[12345]: ... status=sent (250 2.0.0 OK)

Step 7 — Test your score at mail-tester.com

Go to mail-tester.com. It gives you a unique address to send a test email to, then scores your setup from 1–10 across deliverability, authentication, blacklists, and content.

echo "Testing my mail server" | mail -s "Mail tester" [your-unique-address]@mail-tester.com

Common issues and fixes:

• SPF fails: Check your TXT record syntax. Wait up to 10 minutes for DNS propagation.
• DKIM fails: Check the DKIM public key matches the private key. Re-run rspamadm dkim_keygen if needed.
• DMARC fails: Both SPF and DKIM must pass (or at least one aligned with the From domain).
• Listed on a blacklist: Check MXToolbox. Fresh IPs can be pre-listed on some blocklists — most accept a quick request for removal.
• PTR mismatch: Verify dig -x YOUR_IP returns mail.example.com. If not, fix the PTR at your provider.

Step 8 — Ongoing maintenance

Let’s Encrypt certificate renewal

Add a post-renewal hook to restart mail services after certificate renewal:

cat > /etc/letsencrypt/renewal-hooks/post/mail.sh <<'EOF'
#!/bin/bash
systemctl reload postfix
systemctl reload dovecot
EOF
chmod +x /etc/letsencrypt/renewal-hooks/post/mail.sh

Monitor the mail log

tail -f /var/log/mail.log

Common things to watch for: repeated delivery failures to a domain (their mail server may be down), spikes in rejected connections (potential attack), and authentication failures (someone testing your credentials).

Train Rspamd’s Bayes filter

After a week or two, train Rspamd with actual spam and ham to improve accuracy:

# Train as spam
rspamc learn_spam < /path/to/spam-message.eml

# Train as ham (legitimate mail)
rspamc learn_ham < /path/to/good-message.eml

DMARC reports

Once you’ve set up the rua address in your DMARC record, you’ll receive aggregate reports from major mail providers. These show which IPs are sending mail claiming to be from your domain. If you see IPs you don’t recognise, someone is spoofing you — tighten your DMARC policy from quarantine to reject.

Adding virtual mailboxes (multiple domains)

The system user approach works for small setups. For multiple domains or many users, virtual mailboxes are cleaner — users exist only in a database, not as Unix accounts.

Install a simple flat-file virtual setup

# /etc/postfix/main.cf additions:
virtual_mailbox_domains = example.com otherdomain.com
virtual_mailbox_base = /var/mail/virtual
virtual_mailbox_maps = hash:/etc/postfix/vmailbox
virtual_minimum_uid = 100
virtual_uid_maps = static:5000
virtual_gid_maps = static:5000

# Create the user that owns all virtual mail
groupadd -g 5000 vmail
useradd -u 5000 -g 5000 -s /sbin/nologin -d /var/mail/virtual vmail
mkdir -p /var/mail/virtual
chown vmail:vmail /var/mail/virtual

# /etc/postfix/vmailbox
alice@example.com     example.com/alice/
bob@example.com       example.com/bob/
info@otherdomain.com  otherdomain.com/info/

postmap /etc/postfix/vmailbox
postfix reload

For large deployments (100+ users), store virtual mailboxes in MySQL or PostgreSQL using postfix-mysql and dovecot-mysql.

Security hardening

A mail server open to the internet is a constant target. These settings close common attack vectors.

Postfix hardening

# Add to /etc/postfix/main.cf

# Prevent open relay
smtpd_relay_restrictions = permit_mynetworks, permit_sasl_authenticated, reject

# Rate limiting
smtpd_client_connection_rate_limit = 20
smtpd_client_message_rate_limit = 30
anvil_rate_time_unit = 60s

# Disable VRFY (stops address enumeration)
disable_vrfy_command = yes

# Don't expose version info
smtpd_banner = $myhostname ESMTP

Fail2ban for mail

apt-get install fail2ban

# /etc/fail2ban/jail.d/postfix.conf
[postfix]
enabled = true
port = smtp,465,587
logpath = /var/log/mail.log
maxretry = 5
bantime = 3600

[dovecot]
enabled = true
port = imaps
logpath = /var/log/mail.log
maxretry = 5
bantime = 3600

Rspamd DMARC enforcement

# /etc/rspamd/local.d/dmarc.conf
reporting = false;   # disable reporting (handle manually via rua address)
enforce_blackhole = true;
enforce_reject = true;

Frequently asked questions

Related posts

• TLS Configuration for NGINX and Angie: A+ on SSL Labs — the same TLS hardening principles apply to your mail server
• PHP Snuffleupagus Tutorial: Harden PHP-FPM — if you’re running a web app on the same server, add PHP-level security too
• NGINX ModSecurity WAF Setup — WAF protection for any web applications running alongside your mail server
• Full package list — Postfix, Dovecot, Rspamd, Redis and all dependencies available via APT
• How to add the myguard APT repository — two-minute setup

Changes

• Full rebuild and backport with latest Mainline
• Merged with the source package from Debian Trixie in november 2023
• See for more information https://deb.myguard.nl/nginx-modules/
• Changelog: https://deb.myguard.nl/forums/topic/changelog/

Distributions

• bookworm
• jammy
• noble
• resolute
• trixie