proxyprotocol

package
v1.20240719.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 19, 2024 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package proxyprotocol implements network reader shims for terminating proxy protocol connections.

Index

Constants

This section is empty.

Variables

View Source 
var (
	SIGV1 = []byte{'\x50', '\x52', '\x4F', '\x58', '\x59'}
	SIGV2 = []byte{'\x0D', '\x0A', '\x0D', '\x0A', '\x00', '\x0D', '\x0A', '\x51', '\x55', '\x49', '\x54', '\x0A'}
)

Protocol Headers

View Source 
var (
	ErrCantReadVersion1Header               = errors.New("proxyproto: can't read version 1 header")
	ErrVersion1HeaderTooLong                = errors.New("proxyproto: version 1 header must be 107 bytes or less")
	ErrLineMustEndWithCrlf                  = errors.New("proxyproto: version 1 header is invalid, must end with \\r\\n")
	ErrCantReadProtocolVersionAndCommand    = errors.New("proxyproto: can't read proxy protocol version and command")
	ErrCantReadAddressFamilyAndProtocol     = errors.New("proxyproto: can't read address family or protocol")
	ErrCantReadLength                       = errors.New("proxyproto: can't read length")
	ErrCantResolveSourceUnixAddress         = errors.New("proxyproto: can't resolve source Unix address")
	ErrCantResolveDestinationUnixAddress    = errors.New("proxyproto: can't resolve destination Unix address")
	ErrNoProxyProtocol                      = errors.New("proxyproto: proxy protocol signature not present")
	ErrUnknownProxyProtocolVersion          = errors.New("proxyproto: unknown proxy protocol version")
	ErrUnsupportedProtocolVersionAndCommand = errors.New("proxyproto: unsupported proxy protocol version and command")
	ErrUnsupportedAddressFamilyAndProtocol  = errors.New("proxyproto: unsupported address family and protocol")
	ErrInvalidLength                        = errors.New("proxyproto: invalid length")
	ErrInvalidAddress                       = errors.New("proxyproto: invalid address")
	ErrInvalidPortNumber                    = errors.New("proxyproto: invalid port number")
	ErrSuperfluousProxyHeader               = errors.New("proxyproto: upstream connection sent PROXY header but isn't allowed to send one")
)

Errors

View Source 
var (
	ErrTruncatedTLV    = errors.New("proxyproto: truncated TLV")
	ErrMalformedTLV    = errors.New("proxyproto: malformed TLV Value")
	ErrIncompatibleTLV = errors.New("proxyproto: incompatible TLV type")
)

Error constants

View Source 
var (

	// ErrInvalidUpstream is a common error.
	ErrInvalidUpstream ex.Class = "upstream connection address not trusted for PROXY information"
)

Functions

func CreateListener added in v1.20201204.1 

func CreateListener(network, addr string, opts ...CreateListenerOption) (net.Listener, error)

CreateListener creates a new proxy protocol listener.

func JoinTLVs added in v1.20210815.2 

func JoinTLVs(tlvs []TLV) ([]byte, error)

JoinTLVs joins multiple Type-Length-Value records.

Types

type AddressFamilyAndProtocol added in v1.20210815.2 

type AddressFamilyAndProtocol byte

AddressFamilyAndProtocol represents address family and transport protocol. 

const (
	AddressFamilyAndProtocolUnknown      AddressFamilyAndProtocol = '\x00'
	AddressFamilyAndProtocolTCPv4        AddressFamilyAndProtocol = '\x11'
	AddressFamilyAndProtocolUDPv4        AddressFamilyAndProtocol = '\x12'
	AddressFamilyAndProtocolTCPv6        AddressFamilyAndProtocol = '\x21'
	AddressFamilyAndProtocolUDPv6        AddressFamilyAndProtocol = '\x22'
	AddressFamilyAndProtocolUnixStream   AddressFamilyAndProtocol = '\x31'
	AddressFamilyAndProtocolUnixDatagram AddressFamilyAndProtocol = '\x32'
)

Address family and protocol constants

func (AddressFamilyAndProtocol) IsDatagram added in v1.20210815.2 

func (ap AddressFamilyAndProtocol) IsDatagram() bool

IsDatagram returns true if the transport protocol is UDP or DGRAM (SOCK_DGRAM), false otherwise.

func (AddressFamilyAndProtocol) IsIPv4 added in v1.20210815.2 

func (ap AddressFamilyAndProtocol) IsIPv4() bool

IsIPv4 returns true if the address family is IPv4 (AF_INET4), false otherwise.

func (AddressFamilyAndProtocol) IsIPv6 added in v1.20210815.2 

func (ap AddressFamilyAndProtocol) IsIPv6() bool

IsIPv6 returns true if the address family is IPv6 (AF_INET6), false otherwise.

func (AddressFamilyAndProtocol) IsStream added in v1.20210815.2 

func (ap AddressFamilyAndProtocol) IsStream() bool

IsStream returns true if the transport protocol is TCP or STREAM (SOCK_STREAM), false otherwise.

func (AddressFamilyAndProtocol) IsUnix added in v1.20210815.2 

func (ap AddressFamilyAndProtocol) IsUnix() bool

IsUnix returns true if the address family is UNIX (AF_UNIX), false otherwise.

func (AddressFamilyAndProtocol) IsUnspec added in v1.20210815.2 

func (ap AddressFamilyAndProtocol) IsUnspec() bool

IsUnspec returns true if the transport protocol or address family is unspecified, false otherwise.

type Conn 

type Conn struct {
	// contains filtered or unexported fields
}

Conn is used to wrap and underlying connection which may be speaking the Proxy Protocol. If it is, the RemoteAddr() will return the address of the client instead of the proxy address.

func NewConn 

func NewConn(conn net.Conn, timeout time.Duration) *Conn

NewConn is used to wrap a net.Conn that may be speaking the proxy protocol into a proxyproto.Conn

func (*Conn) Close 

func (p *Conn) Close() error

Close closes the underlying connection.

func (*Conn) LocalAddr 

func (p *Conn) LocalAddr() net.Addr

LocalAddr returns the local address of the underlying connection.

func (*Conn) Read 

func (p *Conn) Read(b []byte) (int, error)

Read is check for the proxy protocol header when doing the initial scan. If there is an error parsing the header, it is returned and the socket is closed.

func (*Conn) RemoteAddr 

func (p *Conn) RemoteAddr() net.Addr

RemoteAddr returns the address of the client if the proxy protocol is being used, otherwise just returns the address of the socket peer. If there is an error parsing the header, the address of the client is not returned, and the socket is closed. Once implication of this is that the call could block if the client is slow. Using a Deadline is recommended if this is called before Read()

func (*Conn) SetDeadline 

func (p *Conn) SetDeadline(t time.Time) error

SetDeadline sets a field.

func (*Conn) SetReadDeadline 

func (p *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline reads a field.

func (*Conn) SetWriteDeadline 

func (p *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets a field.

func (*Conn) Write 

func (p *Conn) Write(b []byte) (int, error)

type CreateListenerOption added in v1.20201204.1 

type CreateListenerOption func(*CreateListenerOptions) error

CreateListenerOption is a mutator for the options used when creating a listener.

func OptKeepAlive added in v1.20201204.1 

func OptKeepAlive(keepAlive bool) CreateListenerOption

OptKeepAlive sets if we should keep TCP connections alive or not.

func OptKeepAlivePeriod added in v1.20201204.1 

func OptKeepAlivePeriod(keepAlivePeriod time.Duration) CreateListenerOption

OptKeepAlivePeriod sets the duration we should keep connections alive for.

func OptTLSConfig added in v1.20201204.1 

func OptTLSConfig(tlsConfig *tls.Config) CreateListenerOption

OptTLSConfig sets the listener tls config.

func OptUseProxyProtocol added in v1.20201204.1 

func OptUseProxyProtocol(useProxyProtocol bool) CreateListenerOption

OptUseProxyProtocol sets if we should decode proxy protocol or not.

type CreateListenerOptions added in v1.20201204.1 

type CreateListenerOptions struct {
	TLSConfig        *tls.Config
	UseProxyProtocol bool
	KeepAlive        bool
	KeepAlivePeriod  time.Duration
}

CreateListenerOptions are the options for creating listeners.

type Dialer added in v1.20210815.2 

type Dialer struct {
	*net.Dialer
	HeaderProvider func(context.Context, net.Conn) *Header
}

Dialer wraps a dialer with proxy protocol header injection.

func NewDialer added in v1.20210815.2 

func NewDialer(opts ...DialerOption) *Dialer

NewDialer returns a new proxy protocol dialer.

func (*Dialer) Dial added in v1.20210815.2 

func (d *Dialer) Dial(network, addr string) (net.Conn, error)

Dial implements the dialer, calling `HeaderProvider` for a the context passed to it.

func (*Dialer) DialContext added in v1.20210815.2 

func (d *Dialer) DialContext(ctx context.Context, network, addr string) (net.Conn, error)

DialContext implements the dialer, calling `HeaderProvider` for a the context passed to it.

type DialerOption added in v1.20210815.2 

type DialerOption func(*Dialer)

DialerOption mutates a dialer.

func OptDialerConstSourceAdddr added in v1.20210815.2 

func OptDialerConstSourceAdddr(addr net.Addr) DialerOption

OptDialerConstSourceAdddr sets the header provider to be a constant source.

func OptDialerHeaderProvider added in v1.20210815.2 

func OptDialerHeaderProvider(provider func(context.Context, net.Conn) *Header) DialerOption

OptDialerHeaderProvider sets the header provider. 

type Header struct {
	Version           byte
	Command           ProtocolVersionAndCommand
	TransportProtocol AddressFamilyAndProtocol
	SourceAddr        net.Addr
	DestinationAddr   net.Addr
	// contains filtered or unexported fields
}

Header is the placeholder for proxy protocol header.

func (*Header) EqualTo added in v1.20210815.2 

func (header *Header) EqualTo(otherHeader *Header) bool

EqualTo returns true if headers are equivalent, false otherwise. Deprecated: use EqualsTo instead. This method will eventually be removed.

func (*Header) EqualsTo added in v1.20210815.2 

func (header *Header) EqualsTo(otherHeader *Header) bool

EqualsTo returns true if headers are equivalent, false otherwise.

func (*Header) Format added in v1.20210815.2 

func (header *Header) Format() ([]byte, error)

Format renders a proxy protocol header in a format to write over the wire.

func (*Header) IPs added in v1.20210815.2 

func (header *Header) IPs() (sourceIP, destIP net.IP, ok bool)

IPs returns the ip addresses for the proxy protocol header.

func (*Header) Ports added in v1.20210815.2 

func (header *Header) Ports() (sourcePort, destPort int, ok bool)

Ports returns the ports for the proxy protocol header.

func (*Header) SetTLVs added in v1.20210815.2 

func (header *Header) SetTLVs(tlvs []TLV) error

SetTLVs sets the TLVs stored in this header. This method replaces any previous TLV.

func (*Header) TCPAddrs added in v1.20210815.2 

func (header *Header) TCPAddrs() (sourceAddr, destAddr *net.TCPAddr, ok bool)

TCPAddrs returns the tcp addresses for the proxy protocol header.

func (*Header) TLVs added in v1.20210815.2 

func (header *Header) TLVs() ([]TLV, error)

TLVs returns the TLVs stored into this header, if they exist. TLVs are optional for v2 of the protocol.

func (*Header) UDPAddrs added in v1.20210815.2 

func (header *Header) UDPAddrs() (sourceAddr, destAddr *net.UDPAddr, ok bool)

UDPAddrs returns the udp addresses for the proxy protocol header.

func (*Header) UnixAddrs added in v1.20210815.2 

func (header *Header) UnixAddrs() (sourceAddr, destAddr *net.UnixAddr, ok bool)

UnixAddrs returns the uds addresses for the proxy protocol header.

func (*Header) WriteTo added in v1.20210815.2 

func (header *Header) WriteTo(w io.Writer) (int64, error)

WriteTo renders a proxy protocol header in a format and writes it to an io.Writer.

type Listener 

type Listener struct {
	Listener           net.Listener
	ProxyHeaderTimeout time.Duration
	SourceCheck        SourceChecker
}

Listener is used to wrap an underlying listener, whose connections may be using the HAProxy Proxy Protocol (version 1). If the connection is using the protocol, the RemoteAddr() will return the correct client address.

Optionally define ProxyHeaderTimeout to set a maximum time to receive the Proxy Protocol Header. Zero means no timeout.

func (*Listener) Accept 

func (p *Listener) Accept() (net.Conn, error)

Accept waits for and returns the next connection to the listener.

func (*Listener) Addr 

func (p *Listener) Addr() net.Addr

Addr returns the underlying listener's network address.

func (*Listener) Close 

func (p *Listener) Close() error

Close closes the underlying listener.

type PP2Type added in v1.20210815.2 

type PP2Type byte

PP2Type is the proxy protocol v2 type 

const (
	PP2TypeNoop      PP2Type = 0x04
	PP2TypeAuthority PP2Type = 0x02
)

Proxy Protocol Type 2 constants

type ProtocolVersionAndCommand added in v1.20210815.2 

type ProtocolVersionAndCommand byte

ProtocolVersionAndCommand represents the command in proxy protocol v2. Command doesn't exist in v1 but it should be set since other parts of this library may rely on it for determining connection details. 

const (
	// ProtocolVersionAndCommandLocal represents the ProtocolVersionAndCommandLocal command in v2 or UNKNOWN transport in v1,
	// in which case no address information is expected.
	ProtocolVersionAndCommandLocal ProtocolVersionAndCommand = '\x20'
	// ProtocolVersionAndCommandProxy represents the PROXY command in v2 or transport is not UNKNOWN in v1,
	// in which case valid local/remote address and port information is expected.
	ProtocolVersionAndCommandProxy ProtocolVersionAndCommand = '\x21'
)

func (ProtocolVersionAndCommand) IsLocal added in v1.20210815.2 

func (pvc ProtocolVersionAndCommand) IsLocal() bool

IsLocal returns true if the command in v2 is ProtocolVersionAndCommandLocal or the transport in v1 is UNKNOWN, i.e. when no address information is expected, false otherwise.

func (ProtocolVersionAndCommand) IsProxy added in v1.20210815.2 

func (pvc ProtocolVersionAndCommand) IsProxy() bool

IsProxy returns true if the command in v2 is PROXY or the transport in v1 is not UNKNOWN, i.e. when valid local/remote address and port information is expected, false otherwise.

func (ProtocolVersionAndCommand) IsUnspec added in v1.20210815.2 

func (pvc ProtocolVersionAndCommand) IsUnspec() bool

IsUnspec returns true if the command is unspecified, false otherwise.

type SourceChecker 

type SourceChecker func(net.Addr) (bool, error)

SourceChecker can be used to decide whether to trust the PROXY info or pass the original connection address through. If set, the connecting address is passed in as an argument. If the function returns an error due to the source being disallowed, it should return ErrInvalidUpstream.

Behavior is as follows: * If error is not nil, the call to Accept() will fail. If the reason for triggering this failure is due to a disallowed source, it should return ErrInvalidUpstream. * If bool is true, the PROXY-set address is used. * If bool is false, the connection's remote address is used, rather than the address claimed in the PROXY info.

type TLV added in v1.20210815.2 

type TLV struct {
	Type  PP2Type
	Value []byte
}

TLV is a uninterpreted Type-Length-Value for V2 protocol, see section 2.2

func SplitTLVs added in v1.20210815.2 

func SplitTLVs(raw []byte) ([]TLV, error)

SplitTLVs splits the Type-Length-Value vector, returns the vector or an error.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.