From b50472340d63bd8325ea43425bbb0243f5320c64 Mon Sep 17 00:00:00 2001 From: Muhammad Nasrul Date: Mon, 8 Sep 2025 17:14:20 +0700 Subject: [PATCH] feat(vhost): add customResponse config example with explanations in frps.toml Add commented example for [customResponse] section in frps.toml: - Document how to enable/disable feature (enable flag). - Explain supported hostname patterns (exact, wildcard, catch-all). - Clarify first-match-wins behavior. - Show example rule returning HTML 503 for *.example.com and example.com. - Show example rule returning JSON 404 for spesific.example2.com. - Add headers example (Cache-Control, X-Error-Code). This improves usability and helps users configure custom responses for unregistered HTTP vhosts. --- conf/frps_full_example.toml | 57 +++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/conf/frps_full_example.toml b/conf/frps_full_example.toml index aba37435..606dd8f0 100644 --- a/conf/frps_full_example.toml +++ b/conf/frps_full_example.toml @@ -167,3 +167,60 @@ name = "port-manager" addr = "127.0.0.1:9001" path = "/handler" ops = ["NewProxy"] + +# ======================================================================== +# Custom response configuration (for HTTP vhost requests) +# ======================================================================== +# This section allows FRPS to return a custom response when a client sends +# an HTTP request with a Host header that is not registered by any FRPC. +# +# - Set enable = true to turn this feature on. +# - Rules are matched in order; the first match wins. +# - Supported hostname patterns: +# * Exact domain: "example.com" +# * Wildcard: "*.example.com" (matches foo.example.com, bar.example.com, but NOT example.com itself) +# * Catch-all: "*" (matches any host) +# - Each rule can define: +# * statusCode : HTTP status code (e.g. 404, 503) +# * contentType : MIME type of the response (e.g. text/html, application/json) +# * body : Response body (string, multi-line supported with """ ... """) +# * headers : Extra headers (map of key:value) +# +# If no rule matches or enable = false, FRPS falls back to the default 404. +# ======================================================================== + +[customResponse] +# Enable or disable the custom response feature. Default = false (disabled). +enable = false + +# ------------------------------------------------------------------------ +# Rule 1: Return a 503 HTML page for *.example.com and example.com +# ------------------------------------------------------------------------ +[[customResponse.rules]] +hostname = ["*.example.com", "example.com"] +statusCode = 503 +contentType = "text/html" +body = """ + + + +

Service Unavailable

+

The server is currently unavailable.
+Please try again later.

+ + +""" +[customResponse.rules.headers] +Cache-Control = "no-store" +X-Error-Code = "UNREGISTERED_HOST" + +# ------------------------------------------------------------------------ +# Rule 2: Return a 404 JSON payload for spesific.example2.com +# ------------------------------------------------------------------------ +[[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"