Nginx Proxy Guard

Make Your Nginx Smarter & Safer

English | 한국어

A secure and fast solution to manage proxy hosts, SSL certificates,
and security rules through an intuitive web UI

🌐 Website • 📖 Docs • ✨ Features • 🚀 Quick Start • 🛠 Tech Stack • 📚 API

Love this project? Your sponsorship keeps it going ↓

---

Robust Security, Easy Management - Reduced Nginx complexity, maximized security

Let's Encrypt integration with automatic renewal. Supports wildcard certificates via DNS-01 challenge. Multiple DNS providers supported: Cloudflare, AWS Route 53, DuckDNS, Dynu.

Block 80+ malicious bots and 50+ AI crawlers automatically. Search engine allowlist ensures legitimate traffic. CAPTCHA challenge mode for suspicious requests.

Real-time traffic monitoring, security block logs, certificate status, and server health at a glance.

Block or allow traffic by country with interactive world map visualization. MaxMind GeoIP2 integration with auto-update.

Analyze Nginx access/error logs with powerful filtering and exclusion patterns. TimescaleDB time-series optimization with automatic compression.

ModSecurity v3 with OWASP Core Rule Set v4.26. Paranoia Level 1-4, a global WAF default with per-host override, rule exclusions that are global or per host and can be scoped host-wide, to a URI path, or to a single argument, plus exploit blocking rules.

Protect against DDoS and brute-force attacks with configurable rate limits per IP, URI, or IP+URI combination.

Multiple backend servers with round-robin, least-connections, IP-hash or random distribution, per-server weights and backup servers (down, max_fails, fail_timeout per server via the API). Failed backends are taken out of rotation passively by nginx (max_fails/fail_timeout); active HTTP health probes are not implemented yet.

Manage Nginx stream reverse proxies from the same UI. Supports TCP and UDP listeners, optional SNI preread routing (TCP only), PROXY protocol in/out, stream timeouts, config testing, and backup/restore. Banned IPs are auto-applied to stream listeners.

Stream security scope — stream operates at L4 (TCP/UDP), so HTTP-layer protections do not apply: ModSecurity (WAF), exploit blocking, bot filter, URI blocking, rate limit, and access lists are HTTP-only. IP-based controls (banned IPs) work at L4 and are auto-injected. fail2ban and GeoIP for stream listeners are tracked as follow-ups.

Stream traffic is logged to /var/log/nginx/stream_access.log (and stream_error.log) inside the nginx container. LogCollector ingestion of stream traffic into the NPG dashboard is tracked as a follow-up; for now use docker logs npg-proxy or read the file directly.

worker_connections is shared between HTTP and stream listeners. Large numbers of long-lived stream sessions can pressure HTTP capacity — increase worker_connections (Settings → Global → "Apply recommended" raises it to 8192) if you run heavy stream workloads.

CustomStreamConfig (Advanced tab) accepts raw nginx stream directives and can bind arbitrary ports on any interface. Treat it as an admin-only capability.

HSTS, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy, and Content-Security-Policy.

IP-based access control lists for whitelisting or blacklisting. Support for CIDR notation.

Full configuration backup including certificates, settings, and database. Scheduled auto-backup support.

Create API tokens with granular permissions, IP restrictions, and expiration. Perfect for CI/CD integration.

HTTP to HTTPS redirects, domain redirects, and custom redirect rules.

Track all configuration changes with user attribution and timestamps.

Optional 2FA for admin accounts using TOTP (Google Authenticator, Authy, etc.).

Modern protocol support for faster, more reliable connections over UDP.

Strong password policy (10+ chars, complexity requirements). IP/CIDR input validation. Regex ReDoS prevention. Automatic Nginx config rollback on failure.

Subscribe to external IP/CIDR blocklists that automatically sync and integrate with Nginx. Preset blocklists included, auto-refresh scheduling, entry deduplication across subscriptions and banned IPs. Up to 25K entries per list, 100K total.

ML-KEM (X25519MLKEM768) hybrid key exchange support for future-proof TLS connections. Configurable via global SSL settings with OpenSSL 3.5 compatibility.

Global proxy request/response buffering settings for fine-tuned performance. Useful for WebSocket, streaming, and large file upload scenarios.

Actionable error guides for proxy host configuration failures. Clickable error badges with detailed troubleshooting. Auto-disable broken configs on Nginx startup.

Built-in DDNS keeps your domains pointed at your home server as your public IP changes (Cloudflare / DuckDNS / Dynu). Enable per proxy host with one toggle — the host's domains become managed DDNS records that auto-sync on domain changes and are cleaned up when the host is deleted. Bulk-enable existing hosts, and configure the refresh interval from the DDNS settings.

Put Authelia, Authentik, or a custom auth_request provider in front of a proxy host, with per-host bypass paths. (A host uses either ForwardAuth or the geo/bot challenge, not both.)

Built-in Administrator / Operator / Viewer roles plus custom roles with per-area read/write permissions. Each person gets their own account and 2FA; API tokens can never exceed their owner's role.

Sign in through any OpenID Connect provider (Keycloak preset included). Password login always stays available, and just-in-time account creation is fail-closed behind an allowlist.

cloudflared ships inside the nginx image — paste a tunnel token and your hosts are reachable without port forwarding, still behind the full WAF/GeoIP/ban stack. Managed mode lets NPG maintain the tunnel's catch-all rule for you.

Discord, Telegram and generic webhook channels. Each of the ten alerts can be off, immediate, or held for a daily summary that also reports CPU/memory/disk.

Set GeoIP restriction, bot filter, security headers, cloud-provider blocking, rate limit and WAF mode/paranoia once, globally; every host inherits the default or overrides it.

Running behind Cloudflare or another proxy? Settings → Trusted Proxies (Cloudflare preset or custom CIDRs) tells nginx which hops to trust for the real client IP, so bans, access lists, GeoIP and fail2ban act on the visitor instead of the proxy.

Counts requests that matched no proxy host (direct-IP scanners, unknown hostnames answered with 444) — traffic a per-host jail can never see. Ships disabled in Log-Only mode and requires Trusted Proxies to be configured.

Also since June: saved log filter presets (v2.33.0), a per-IP activity view for banned addresses (v2.38.0), an in-app update check (v2.29.0), and WAF rule exclusions scoped to a path or argument (v2.37.0, fully working since v2.54.0).

Solid Tech Stack - Designed with modern technologies, a microservices architecture

Get Started in 1 Minute - Run Nginx Proxy Guard using Docker Compose

• Docker 24.0+ and Docker Compose v2
• A linux/amd64 or linux/arm64 host (Raspberry Pi 4/5 and other ARM64 servers are supported)
• (Optional) MaxMind License Key for GeoIP

# 1. Create directory
mkdir -p ~/nginx-proxy-guard && cd ~/nginx-proxy-guard

# 2. Download files
wget https://raw.githubusercontent.com/svrforum/nginxproxyguard/main/docker-compose.yml
wget -O .env https://raw.githubusercontent.com/svrforum/nginxproxyguard/main/env.example

# 3. Auto-generate secure secrets
sed -i "s/DB_PASSWORD=.*/DB_PASSWORD=$(openssl rand -base64 24)/" .env
sed -i "s/JWT_SECRET=.*/JWT_SECRET=$(openssl rand -hex 32)/" .env

# 4. Start services
docker compose up -d

Default Login: admin / admin (Change immediately after first login!)

Security notes

• Since v2.24.6 the server blocks every protected API until the default credentials are changed (initial-setup gate), so a freshly-installed instance cannot be hijacked via admin/admin.
• Do not expose the Admin Panel (port 81) to the internet. Keep it on your LAN/VPN, or front it with its own proxy host protected by access lists and 2FA.
• Found a vulnerability? Please report it privately — see SECURITY.md.

Password Policy (v2.2.0+): New passwords must be at least 10 characters with uppercase, lowercase, digit, and special character. Common passwords are blocked.

docker compose pull
docker compose up -d

Lost your admin password (or 2FA device)? If you have shell access to the host, recover from the CLI without touching the database directly:

# Auto-target the sole admin and print a freshly generated random password
docker compose exec api ./server reset-password

# Pick a specific user
docker compose exec api ./server reset-password --username alice

# Set a known password instead of the auto-generated one (≥ 8 chars, ≤ 72 bytes)
docker compose exec api ./server reset-password --username alice --password 'S3cure-Pwd!'

# Also wipe the user's TOTP secret and disable 2FA
docker compose exec api ./server reset-password --clear-2fa

Each successful reset:

• writes a fresh bcrypt password_hash
• clears the user's failed login_attempts (lifts any stale per-IP lockout)
• invalidates every active auth_session for that user — they (and any holder of a stolen token) must sign in again
• records a Password reset via CLI entry in system_logs (source=audit)

Sign in with the printed password and change it immediately from Account Settings in the UI.

All versions are fully backward compatible. No manual migration needed — database schema upgrades are applied automatically on startup. Just pull the latest image and recreate the containers.

Compose-level options (port overrides, API/login rate limits, TRUSTED_PROXY_CIDR, container log caps, capability drops) only reach installs whose docker-compose.yml is refreshed — pulling images alone keeps your old compose file. Compare yours with the current docker-compose.yml after upgrading. See the latest releases and Key Features for what changed.

Nginx Proxy Guard provides a comprehensive REST API for automation and integration.

All API endpoints require authentication via:

• Session token: Authorization: Bearer <token> (the token field returned by POST /api/v1/auth/login, or by POST /api/v1/auth/verify-2fa when 2FA is enabled)
• API Token: Authorization: Bearer ng_<api_token> (for automation)

The API documentation (Swagger UI) is served at:

https://localhost:81/api/docs

The raw OpenAPI 3.0 spec is at https://localhost:81/api/docs/swagger.yaml.

• Website: nginxproxyguard.com
• Documentation: nginxproxyguard.com/docs

If you find Nginx Proxy Guard useful, consider supporting the project! GitHub Sponsors is the best way to help — it goes directly to development with zero platform fees.

This project is licensed under the MIT License - see the LICENSE file for details.

• Website - Documentation and guides
• GitHub Issues - Bug reports and feature requests
• Discussions - Questions and community
• GitHub Sponsors - Support the project (zero fees)
• Buy Me a Coffee - Support the project