[GH-ISSUE #4972] [Feature Request] Custom response for unregistered HTTP vhost (rules, wildcard, headers)

gitea-mirror commented

2026-05-05 14:29:58 -06:00

Owner

Originally created by @mnasruul on GitHub (Sep 8, 2025).
Original GitHub issue: https://github.com/fatedier/frp/issues/4972

Describe the feature request

Summary

Add support for configurable customResponse in FRPS HTTP vhost, so requests with unknown/unregistered Host header return a user-defined response (status, content-type, body, headers).

Why

Currently, FRPS always returns default 404 for unregistered hostnames. This is not customizable. Custom responses improve UX and debugging, especially in multi-tenant setups.

## Proposed config (TOML)
[customResponse]
enable = false

[[customResponse.rules]]
hostname    = ["*.example.com", "example.com"]
statusCode  = 503
contentType = "text/html"
body = """
<!doctype html><html><body>
<h1>Service Unavailable</h1>
<p>The server is currently unavailable.<br/>Please try again later.</p>
</body></html>
"""
[customResponse.rules.headers]
Cache-Control = "no-store"
X-Error-Code  = "UNREGISTERED_HOST"

[[customResponse.rules]]
hostname    = ["spesific.example2.com"]
statusCode  = 404
contentType = "application/json"
body        = "{\"error\":\"unregistered_host\",\"hint\":\"register frpc for this hostname\"}"
[customResponse.rules.headers]
Cache-Control = "no-store"

Behavior

If feature disabled, behavior unchanged (default 404).
Rules support exact, wildcard (*.example.com), and "*" catch-all.
First match wins.

Next step

I can prepare a PR with implementation + unit tests if this direction is acceptable.

Describe alternatives you've considered

No response

Affected area

Docs
Installation
Performance and Scalability
Security
User Experience
Test and Release
Developer Infrastructure
Client Plugin
Server Plugin
Extensions
Others

Originally created by @mnasruul on GitHub (Sep 8, 2025). Original GitHub issue: https://github.com/fatedier/frp/issues/4972 ### Describe the feature request ## Summary Add support for configurable `customResponse` in FRPS HTTP vhost, so requests with unknown/unregistered Host header return a user-defined response (status, content-type, body, headers). ## Why Currently, FRPS always returns default 404 for unregistered hostnames. This is not customizable. Custom responses improve UX and debugging, especially in multi-tenant setups. ``` ## Proposed config (TOML) [customResponse] enable = false [[customResponse.rules]] hostname = ["*.example.com", "example.com"] statusCode = 503 contentType = "text/html" body = """ <!doctype html><html><body> <h1>Service Unavailable</h1> <p>The server is currently unavailable.<br/>Please try again later.</p> </body></html> """ [customResponse.rules.headers] Cache-Control = "no-store" X-Error-Code = "UNREGISTERED_HOST" [[customResponse.rules]] hostname = ["spesific.example2.com"] statusCode = 404 contentType = "application/json" body = "{\"error\":\"unregistered_host\",\"hint\":\"register frpc for this hostname\"}" [customResponse.rules.headers] Cache-Control = "no-store" ``` ## Behavior - If feature disabled, behavior unchanged (default 404). - Rules support exact, wildcard (`*.example.com`), and `"*"` catch-all. - First match wins. ## Next step I can prepare a PR with implementation + unit tests if this direction is acceptable. ### Describe alternatives you've considered _No response_ ### Affected area - [x] Docs - [ ] Installation - [ ] Performance and Scalability - [ ] Security - [x] User Experience - [ ] Test and Release - [ ] Developer Infrastructure - [ ] Client Plugin - [x] Server Plugin - [ ] Extensions - [ ] Others

gitea-mirror closed this issue

2026-05-05 14:29:59 -06:00

gitea-mirror commented

2026-05-05 14:30:02 -06:00

Author

Owner

@fatedier commented on GitHub (Sep 15, 2025):

Thanks for the proposal! We’re not expanding L7 HTTP/HTTPS features right now. The current L7 pieces are fragmented and need a redesign. We’ll revisit ideas like this after the L7 refactor. For now, please consider putting a reverse proxy (Nginx/Caddy/Traefik) in front of frps to handle custom fallback pages. Appreciate your understanding!

@fatedier commented on GitHub (Sep 15, 2025): Thanks for the proposal! We’re not expanding L7 HTTP/HTTPS features right now. The current L7 pieces are fragmented and need a redesign. We’ll revisit ideas like this after the L7 refactor. For now, please consider putting a reverse proxy (Nginx/Caddy/Traefik) in front of frps to handle custom fallback pages. Appreciate your understanding!

gitea-mirror commented

2026-05-05 14:30:03 -06:00

Author

Owner

@mnasruul commented on GitHub (Sep 16, 2025):

As mentioned in the related PR, this proposal is on hold until the L7 HTTP/HTTPS refactor.

If anyone needs this feature earlier, I’ve published my fork with a working implementation here:
👉 https://github.com/mnasruul/frp

The fork adds a [customResponse] block in frps.toml that allows returning custom status, content type, body, and headers when a Host is not registered by any FRPC.

Once the L7 redesign is ready, I’d be glad to help contribute this feature upstream again.

Thanks @fatedier

@mnasruul commented on GitHub (Sep 16, 2025): As mentioned in the related PR, this proposal is on hold until the L7 HTTP/HTTPS refactor. If anyone needs this feature earlier, I’ve published my fork with a working implementation here: 👉 https://github.com/mnasruul/frp The fork adds a [customResponse] block in frps.toml that allows returning custom status, content type, body, and headers when a Host is not registered by any FRPC. Once the L7 redesign is ready, I’d be glad to help contribute this feature upstream again. Thanks @fatedier