Frontend Real IP Header Configuration

The Frontend Real IP Request Header lets Dashboard identify the real client IP of visitors accessing the admin frontend and user frontend. Online users, login brute-force protection, OAuth2 brute-force protection, API Token brute-force protection, Agent connection-secret brute-force protection, audit records, and the Web Application Firewall (WAF) all rely on this IP.

Configure this in the admin frontend under avatar → System Settings → System Configuration → Frontend Real IP Request Header. The corresponding configuration file field is web_real_ip_header.

Frontend and Agent headers are different

The Frontend Real IP Request Header only applies to browser or user access to Dashboard. The Agent Real IP Request Header only applies to Agent connections to Dashboard. Their entry points, proxy chains, and purposes may be different. Do not mix them.

---

What to Use

Deployment	Recommended value	Notes
Dashboard directly exposed to the public network	Use Direct IP	Equivalent to web_real_ip_header: "NZ::Use-Peer-IP"
Common reverse proxy	X-Real-IP or nz-realip from the reverse proxy examples	The upstream Nginx, Caddy, Apache, or other proxy must pass the same header
Cloudflare CDN	CF-Connecting-IP	For other CDNs, use the real-IP header provided by that CDN
Not sure whether the proxy passes the header correctly	Leave it empty first, or use direct IP	Enable a custom header only after checking proxy logs and headers

Only trust real-IP headers from trusted reverse proxies or CDNs. If users can bypass the proxy and reach Dashboard directly, they may forge this header and cause WAF false positives or bypasses.

---

Scenario 1: Direct Public Access to Dashboard

If browsers access Dashboard directly without Nginx, Caddy, Apache, Cloudflare, or another CDN in front of it, select Use Direct IP.

The equivalent configuration file value is:

web_real_ip_header: "NZ::Use-Peer-IP"

In this mode, Dashboard uses the connection IP directly and does not need an upstream application to pass a request header.

---

Scenario 2: Nginx, Caddy, Apache, or Another Reverse Proxy

When Dashboard is behind a reverse proxy, the connection IP seen by Dashboard is usually the reverse proxy server's IP. You need the reverse proxy to write the client IP into a header, then set Frontend Real IP Request Header in Dashboard to the same header name.

Common choices:

• Use the common X-Real-IP header.
• If you follow the Reverse Proxy Configuration examples in this documentation, you can use nz-realip.
• If you use X-Forwarded-For, make sure the proxy chain is trusted and confirm Dashboard reads the expected client IP.

Minimal Nginx Example

location / {
    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_pass http://127.0.0.1:8008;
}

Set Dashboard to:

web_real_ip_header: "X-Real-IP"

If you use the nz-realip example from the documentation:

location / {
    proxy_set_header Host $host;
    proxy_set_header nz-realip $remote_addr;
    proxy_pass http://127.0.0.1:8008;
}

Set Dashboard to:

web_real_ip_header: "nz-realip"

Minimal Caddy Example

example.com {
    reverse_proxy 127.0.0.1:8008 {
        header_up X-Real-IP {remote_host}
    }
}

Set Dashboard to:

web_real_ip_header: "X-Real-IP"

---

Scenario 3: Cloudflare or Another CDN

When Dashboard is proxied by Cloudflare, set Dashboard to:

web_real_ip_header: "CF-Connecting-IP"

For other CDNs, use the real client IP header provided by that CDN, such as the Real IP, Client IP, or Connecting IP header described in the vendor documentation.

Make sure only the trusted CDN or reverse proxy can access the Dashboard origin. If the origin is still directly reachable from the public network, attackers can bypass the CDN and forge the header.

---

How WAF Uses This IP

Dashboard's built-in WAF records risky behavior by IP + block identifier. WAF records and blocks a source when any of these events occur:

• Too many failed login attempts.
• OAuth2 login brute force.
• API Token brute force.
• Agent connection secret brute force.
• Manual block by an administrator on the Online Users page.

The more times the same entry is recorded, the longer the block duration becomes. Administrators can go to System Settings → Web Application Firewall to view blocked IPs, block identifiers, counts, reasons, and times, and can delete one or multiple block entries.

---

What Happens If It Is Misconfigured

If you set a header that does not exist, is not trusted, or is not passed by the proxy, these problems may occur:

• Dashboard cannot obtain the IP, making online users and audit records inaccurate.
• All visitors are identified as the reverse proxy or CDN IP, causing multiple users to share one block record.
• Users can forge the header to bypass WAF or cause another IP to be blocked by mistake.
• The administrator's own IP may be blocked by mistake, preventing access to the backend.

If you are unsure, leave this setting empty or select Use Direct IP first. Enable a custom header only after confirming that the reverse proxy passes the correct header.

---

How to Verify

After saving the configuration and restarting Dashboard, verify it this way:

1. Visit Dashboard with a browser.
2. Go to System Settings → Online Users and check whether your IP is the real public client IP, not the reverse proxy, CDN, or an internal address.
3. Check the reverse proxy access logs and confirm the client IP matches the IP shown on Dashboard's Online Users page.
4. If possible, temporarily log the header passed from the reverse proxy to Dashboard and confirm the header name and value exactly match web_real_ip_header.

Do not intentionally test WAF by repeatedly entering wrong passwords, as this may block you or other users by mistake.

---

How to Recover

If a wrong configuration causes abnormal IP detection or prevents login:

1. Modify the Dashboard configuration file, usually /data/config.yaml.

2. Set web_real_ip_header to an empty value or direct-IP mode:

   web_real_ip_header: ""

   Or:

   web_real_ip_header: "NZ::Use-Peer-IP"

3. Restart Dashboard.

4. Log in again, then go to System Settings → Web Application Firewall and delete the mistakenly blocked IP or related block entries.

If you can already access the backend, you can also update Frontend Real IP Request Header directly in System Settings, save it, and then delete the related block entry on the WAF page.