proxyproto

README

proxyproto

This library provides the proxyproto package which can be used for servers listening behind HAProxy of Amazon ELB load balancers. Those load balancers support the use of a proxy protocol (http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt), which provides a simple mechansim for the server to get the address of the client instead of the load balancer.

This library provides both a net.Listener and net.Conn implementation that can be used to handle situation in which you may be using the proxy protocol. Only proxy protocol version 1, the human-readable form, is understood.

The only caveat is that we check for the "PROXY " prefix to determine if the protocol is being used. If that string may occur as part of your input, then it is ambiguous if the protocol is being used and you may have problems.

Documentation

Full documentation can be found here.

Examples

Using the library is very simple:

// Create a listener
list, err := net.Listen("tcp", "...")

// Wrap listener in a proxyproto listener
proxyList := &proxyproto.Listener{Listener: list}
conn, err :=proxyList.Accept()

...

Documentation

Index

• Variables
• type Conn
  • func NewConn(conn net.Conn, timeout time.Duration) *Conn
  • func (p *Conn) Close() error
  • func (p *Conn) LocalAddr() net.Addr
  • func (p *Conn) Read(b []byte) (int, error)
  • func (p *Conn) ReadFrom(r io.Reader) (int64, error)
  • func (p *Conn) RemoteAddr() net.Addr
  • func (p *Conn) SetDeadline(t time.Time) error
  • func (p *Conn) SetReadDeadline(t time.Time) error
  • func (p *Conn) SetWriteDeadline(t time.Time) error
  • func (p *Conn) Write(b []byte) (int, error)
  • func (p *Conn) WriteTo(w io.Writer) (int64, error)
• type Listener
  • func (p *Listener) Accept() (net.Conn, error)
  • func (p *Listener) Addr() net.Addr
  • func (p *Listener) Close() error
• type SourceChecker

Variables

var (
	ErrInvalidUpstream = errors.New("upstream connection address not trusted for PROXY information")
)

Types

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

func (*Conn) LocalAddr

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

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) ReadFrom

func (p *Conn) ReadFrom(r io.Reader) (int64, error)

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

func (*Conn) SetReadDeadline

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

func (*Conn) SetWriteDeadline

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

func (*Conn) Write

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

func (*Conn) WriteTo

func (p *Conn) WriteTo(w io.Writer) (int64, error)

type Listener

type Listener struct {
	Listener           net.Listener
	ProxyHeaderTimeout time.Duration
	SourceCheck        SourceChecker
	UnknownOK          bool // allow PROXY UNKNOWN
}

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 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.

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.