Proxy Host Management

This page explains Nginx Proxy Guard's core feature, proxy host management, in detail.

Basic Features

Multi-Domain Support

• SNI support: Bind multiple domains to a single host
• Wildcards: Supports the *.example.com format
• Subdomains: Configure subdomains independently

Forwarding Configuration

WebSocket Support

Full support for WebSocket upgrades for real-time bidirectional communication.

• Automatic Connection Upgrade
• Custom header forwarding
• Timeout configuration

Caching

Supports caching configuration for static resources.

• Enable/disable caching
• Configure cache lifetime
• Customize cache keys

DDNS Auto-Registration

On the Basic tab you can enable DDNS auto-registration so NPG keeps the host's DNS A record pointed at the server's current public IP — useful on home connections with a dynamic IP.

• Toggle on the Basic tab: Turn on DDNS and pick a DNS provider.
• Supported providers: Cloudflare, DuckDNS, and Dynu. (Only providers whose A record can be updated programmatically qualify; Route53/Manual providers are not selectable for DDNS.)
• Provider reuse: The DDNS provider list is drawn from the DNS providers you already configured under Certificates, so you can reuse an existing Cloudflare/DuckDNS/Dynu provider.

TCP/UDP Stream (Layer 4)

In addition to HTTP/HTTPS virtual hosts, NPG supports a TCP/UDP stream (Layer 4) reverse proxy. When adding a host, simply select TCP / UDP Stream as the proxy mode.

Use Cases

• Databases (PostgreSQL, MySQL, etc.)
• Game servers
• SSH
• Other custom TCP/UDP services

Stream TLS Termination

Stream hosts can also select a certificate to perform TLS termination (SNI-based). NPG handles TLS and forwards plaintext to the backend.

Security Coverage (Important)

Because streams operate at L4, HTTP-layer protection features do not apply. All of the following features are HTTP-only:

Note: fail2ban and GeoIP for stream listeners are tracked as follow-up work and are not yet applied. Only IP-based blocking (banned IPs) operates at L4 and is injected automatically.

Advanced Configuration

Custom Location Blocks

Add Nginx location blocks directly for fine-grained configuration.

# Configuration for a specific path
location /api/ {
    proxy_pass http://api-server:8080;
    proxy_read_timeout 300s;
}

# Static file handling
location /static/ {
    alias /var/www/static/;
    expires 30d;
}

Advanced Configuration

You can edit the Nginx configuration directly.

Caution: For security, the following directives are blocked:

• load_module - loading external modules
• lua_*, perl_*, js_* - script execution
• proxy_pass containing shell commands

Configuration Example

# Request timeout settings
proxy_connect_timeout 60s;
proxy_read_timeout 120s;
proxy_send_timeout 60s;

# Buffer settings
proxy_buffer_size 128k;
proxy_buffers 4 256k;

# Header settings
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Docker Container Browser

Easily select a proxy target server in a Docker environment.

Auto-Discovery

• Automatically discovers running Docker containers
• Displays container name, image, and network information
• NPG's own containers (npg-*) are automatically excluded
• Click a container's IP address and port to auto-fill them

Container Info

Forwarding to a Container by Name

Instead of a fixed IP, you can set a Docker container name as the forward target. NPG resolves the container name to its current IP automatically, so you do not have to edit anything when the IP changes after a container restart.

• Select a container: Pick the target container in the container selector on the proxy host form, and its name is stored as the forward target.
• Automatic IP resolution: On save, the name is resolved to the container's current IP and applied to the Nginx configuration.
• Automatic refresh (re-resolution): A background scheduler periodically (every 30 seconds by default) re-checks the container IP and regenerates the configuration only when the IP has changed. If resolution fails, the last known-good configuration is kept (fail-safe).
• Network selection: When a container is attached to multiple Docker networks, you can choose which network's IP to resolve to. The selected network is stored alongside the container name so resolution always targets the correct network's IP.

Note: Background re-resolution can be disabled with the environment variable NPG_CONTAINER_RECONCILE_DISABLED=true.

Host Cloning

Clone an existing proxy host to quickly create a new one.

Cloning Capabilities

• Clone all settings from the original: WAF, bot filter, GeoIP, Rate Limiting, caching, advanced settings, and more
• Specify a new domain: Enter a new domain name when cloning
• Forwarding override: Change the target server address/port
• Certificate selection: Choose between using an existing certificate, issuing a new Let's Encrypt certificate, or self-signed

Configurable Options When Cloning

Upstream Load Balancing

Configure multiple backend servers for a single proxy host to provide load balancing and high availability.

Load Balancing Methods

Upstream Server Settings

Health Check

Periodically checks the status of backend servers and automatically excludes failed servers.

Keepalive

• Number of keepalive connections: Set the number of idle connections to upstream servers
• Improves performance through connection reuse
• Default: 32 connections

Host Management

Favorites / Pinning

Pin frequently managed hosts to the top of the list.

• Toggle favorite by clicking the star
• Favorite hosts appear at the very top of the list
• Always stays on top regardless of sort order

Enable/Disable

Temporarily disable a host without deleting it.

• When disabled, traffic to that host is blocked
• Settings are preserved
• Quick toggle between enabled and disabled

Configuration Sync

Synchronizes the Nginx configuration of all proxy hosts.

• Apply configuration changes in bulk
• Fix mismatched settings
• Applied without restarting Nginx

Host Testing

Tests whether the proxy configuration works correctly.

• Verify backend connectivity
• Validate SSL/TLS configuration
• Check response status

Integrated Security Settings

Apply independent security settings to each proxy host.

Per-Host Security Features

SSL/TLS Settings

Certificate Binding

• Automatic Let's Encrypt certificate binding
• Custom certificate upload
• Self-signed certificate generation

Force HTTPS

Automatically redirects HTTP requests to HTTPS.

HTTP/2 & HTTP/3

• HTTP/2 enabled by default
• HTTP/3 (QUIC) support
• ALPN protocol negotiation

Best Practices

When Creating a New Host

1. Configure the basic proxy settings
2. Issue/bind an SSL certificate
3. Apply security settings (WAF, bot filter, etc.)
4. Enable after testing

Troubleshooting

• 502 Bad Gateway: Check the backend server connection
• 504 Gateway Timeout: Increase the timeout settings
• SSL errors: Verify certificate validity and configuration