Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS
Mirrored from https://github.com/Slazee/caddy.git
Synced Nov 12, 07:00 UTC
docs: expand proxy protocol docs (#6620)
Mohammed Al Sahaf committed
Oct 10, 2024 at 23:21 UTC
c8a76d003f700b448291845b7879f27c2f19d1dc
1 file changed
+35
-3
modules/caddyhttp/proxyprotocol/listenerwrapper.go
+35
-3
@@ -25,7 +25,12 @@ import (
25
)
26
27
// ListenerWrapper provides PROXY protocol support to Caddy by implementing
28
-// the caddy.ListenerWrapper interface. It must be loaded before the `tls` listener.
28
+// the caddy.ListenerWrapper interface. If a connection is received via Unix
29
+// socket, it's trusted. Otherwise, it's checked against the Allow/Deny lists,
30
+// then it's handled by the FallbackPolicy.
31
+//
32
+// It must be loaded before the `tls` listener because the PROXY protocol
33
+// encapsulates the TLS data.
34
//
35
// Credit goes to https://github.com/mastercactapus/caddy2-proxyprotocol for having
36
// initially implemented this as a plugin.
@@ -45,8 +50,35 @@ type ListenerWrapper struct {
50
Deny []string `json:"deny,omitempty"`
51
deny []netip.Prefix
52
48
- // Accepted values are: ignore, use, reject, require, skip
49
- // default: ignore
53
+ // FallbackPolicy specifies the policy to use if the downstream
54
+ // IP address is not in the Allow list nor is in the Deny list.
55
+ //
56
+ // NOTE: The generated docs which describe the value of this
57
+ // field is wrong because of how this type unmarshals JSON in a
58
+ // custom way. The field expects a string, not a number.
59
+ //
60
+ // Accepted values are: IGNORE, USE, REJECT, REQUIRE, SKIP
61
+ //
62
+ // - IGNORE: address from PROXY header, but accept connection
63
+ //
64
+ // - USE: address from PROXY header
65
+ //
66
+ // - REJECT: connection when PROXY header is sent
67
+ // Note: even though the first read on the connection returns an error if
68
+ // a PROXY header is present, subsequent reads do not. It is the task of
69
+ // the code using the connection to handle that case properly.
70
+ //
71
+ // - REQUIRE: connection to send PROXY header, reject if not present
72
+ // Note: even though the first read on the connection returns an error if
73
+ // a PROXY header is not present, subsequent reads do not. It is the task
74
+ // of the code using the connection to handle that case properly.
75
+ //
76
+ // - SKIP: accepts a connection without requiring the PROXY header.
77
+ // Note: an example usage can be found in the SkipProxyHeaderForCIDR
78
+ // function.
79
+ //
80
+ // Default: IGNORE
81
+ //
82
// Policy definitions are here: https://pkg.go.dev/github.com/pires/go-proxyproto@v0.7.0#Policy
83
FallbackPolicy Policy `json:"fallback_policy,omitempty"`
84