proxyprotocol

Documentation

Index

• type ListenerWrapper
  • func (ListenerWrapper) CaddyModule() caddy.ModuleInfo
  • func (pp *ListenerWrapper) Provision(ctx caddy.Context) error
  • func (w *ListenerWrapper) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (pp *ListenerWrapper) WrapListener(l net.Listener) net.Listener
• type Policy
  • func (x Policy) MarshalText() ([]byte, error)
  • func (x *Policy) UnmarshalText(text []byte) error

Types

type ListenerWrapper

type ListenerWrapper struct {
	// Timeout specifies an optional maximum time for
	// the PROXY header to be received.
	// If zero, timeout is disabled. Default is 5s.
	Timeout caddy.Duration `json:"timeout,omitempty"`

	// Allow is an optional list of CIDR ranges to
	// allow/require PROXY headers from.
	Allow []string `json:"allow,omitempty"`

	// Deny is an optional list of CIDR ranges to
	// deny PROXY headers from.
	Deny []string `json:"deny,omitempty"`

	// FallbackPolicy specifies the policy to use if the downstream
	// IP address is not in the Allow list nor is in the Deny list.
	//
	// NOTE: The generated docs which describe the value of this
	// field is wrong because of how this type unmarshals JSON in a
	// custom way. The field expects a string, not a number.
	//
	// Accepted values are: IGNORE, USE, REJECT, REQUIRE, SKIP
	//
	// - IGNORE: address from PROXY header, but accept connection
	//
	// - USE: address from PROXY header
	//
	// - REJECT: connection when PROXY header is sent
	//   Note: even though the first read on the connection returns an error if
	//   a PROXY header is present, subsequent reads do not. It is the task of
	//   the code using the connection to handle that case properly.
	//
	// - REQUIRE: connection to send PROXY header, reject if not present
	//   Note: even though the first read on the connection returns an error if
	//   a PROXY header is not present, subsequent reads do not. It is the task
	//   of the code using the connection to handle that case properly.
	//
	// - SKIP: accepts a connection without requiring the PROXY header.
	//   Note: an example usage can be found in the SkipProxyHeaderForCIDR
	//   function.
	//
	// Default: IGNORE
	//
	// Policy definitions are here: https://pkg.go.dev/github.com/pires/go-proxyproto@v0.7.0#Policy
	FallbackPolicy Policy `json:"fallback_policy,omitempty"`
	// contains filtered or unexported fields
}

ListenerWrapper provides PROXY protocol support to Caddy by implementing the caddy.ListenerWrapper interface. If a connection is received via Unix socket, it's trusted. Otherwise, it's checked against the Allow/Deny lists, then it's handled by the FallbackPolicy.

It must be loaded before the `tls` listener because the PROXY protocol encapsulates the TLS data.

Credit goes to https://github.com/mastercactapus/caddy2-proxyprotocol for having initially implemented this as a plugin.

func (ListenerWrapper) CaddyModule

func (ListenerWrapper) CaddyModule() caddy.ModuleInfo

func (*ListenerWrapper) Provision

func (pp *ListenerWrapper) Provision(ctx caddy.Context) error

Provision sets up the listener wrapper.

func (*ListenerWrapper) UnmarshalCaddyfile

func (w *ListenerWrapper) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the listener Listenerwrapper from Caddyfile tokens. Syntax:

proxy_protocol {
	timeout <duration>
	allow <IPs...>
	deny <IPs...>
	fallback_policy <policy>
}

func (*ListenerWrapper) WrapListener

func (pp *ListenerWrapper) WrapListener(l net.Listener) net.Listener

WrapListener adds PROXY protocol support to the listener.

type Policy

type Policy int

const (
	// IGNORE address from PROXY header, but accept connection
	PolicyIGNORE Policy = iota
	// USE address from PROXY header
	PolicyUSE
	// REJECT connection when PROXY header is sent
	// Note: even though the first read on the connection returns an error if
	// a PROXY header is present, subsequent reads do not. It is the task of
	// the code using the connection to handle that case properly.
	PolicyREJECT
	// REQUIRE connection to send PROXY header, reject if not present
	// Note: even though the first read on the connection returns an error if
	// a PROXY header is not present, subsequent reads do not. It is the task
	// of the code using the connection to handle that case properly.
	PolicyREQUIRE
	// SKIP accepts a connection without requiring the PROXY header
	// Note: an example usage can be found in the SkipProxyHeaderForCIDR
	// function.
	PolicySKIP
)

as defined in: https://pkg.go.dev/github.com/pires/go-proxyproto@v0.7.0#Policy

func (Policy) MarshalText

func (x Policy) MarshalText() ([]byte, error)

MarshalText implements the text marshaller method.

func (*Policy) UnmarshalText

func (x *Policy) UnmarshalText(text []byte) error

UnmarshalText implements the text unmarshaller method.