proxyprotocol

README

go-proxyprotocol

PROXY protocol implementation in Go.

Usage

import

import (
	proxyprotocol "github.com/blacktear23/go-proxyprotocol"
)

basic usage

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

// Wrap listener as PROXY protocol listener
ppl, err := proxyprotocol.NewListener(l, "*", 5, false)

for {
    conn, err := ppl.Accept()
    if err != nil {
        // PROXY protocol related errors can be output by log and
        // continue accept next one.
        if proxyprotocol.IsProxyProtocolError(err) {
            log.Errorf("PROXY protocol error: %s", err.Error())
            continue
        }
        panic(err)
    }
    go processConn(conn)
}

Notice For AWS NLB

If using AWS NLB, as default NLB will not send ProxyProtocol v2 header to server until client send data. This will cause read timeout error if your server send data first. For example: SMTP, FTP, SSH, MySQL etc.

The default value for NLB target group attribute proxy_protocol_v2.client_to_server.header_placement is on_first_ack_with_payload. User need to contact AWS support to change it to on_first_ack.

Lazy Mode

go-proxyprotocol support lazy mode for ProxyProtocol header parse. Using this mode the header parse step will postpone to first Conn.Read function call. This will handle AWS NLB problem. And user must ensure that the client IP address must be get after a Conn.Read call.

Using lazy mode is simple:

// Create listener
l, err := net.Listener("tcp", "...")


// Wrap listener as PROXY protocol listener and enable lazy mode.
ppl, err := proxyprotocol.NewLazyListener(l, "*", 5, false)

...

Fallback-able

go-proxyprotocol support fallback-able mode for ProxyProtocol header process. When multiple client with different system connect to the server and some using PROXY protocol some not and it's hard to determine the allowed IP range, just set fallbackable parameter to true, it can handle this.

// Create listener
l, err := net.Listener("tcp", "...")


// Wrap listener as PROXY protocol listener and enable lazy mode and fallback-able
ppl, err := proxyprotocol.NewLazyListener(l, "*", 5, true)

...

Get Underlay Raw Connection

go-proxyprotocol provide a UnderlayConn interface that can let user get the raw connection.

// Create listener
l, err := net.Listener("tcp", "...")

// Wrap listener as PROXY protocol listener and enable lazy mode.
ppl, err := proxyprotocol.NewLazyListener(l, "*", 5, false)

// Accept the connection
conn, err := ppl.Accept()

// Get the underlay raw connection
var rawConn net.Conn = nil
if netConn, ok := conn.(UnderlayConn); ok {
    rawConn := netConn.NetConn()
}

...

Documentation

Index

• Variables
• func IsProxyProtocolError(err error) bool
• func NewLazyListener(listener net.Listener, allowedIPs string, headerReadTimeout int, ...) (net.Listener, error)
• func NewListener(listener net.Listener, allowedIPs string, headerReadTimeout int, ...) (net.Listener, error)
• type UnderlayConn

Variables

var (
	ErrProxyProtocolV1HeaderInvalid = errors.New("PROXY Protocol v1 header is invalid")
	ErrProxyProtocolV2HeaderInvalid = errors.New("PROXY Protocol v2 header is invalid")
	ErrProxyProtocolInvalid         = errors.New("Invalid PROXY Protocol Header")
	ErrHeaderReadTimeout            = errors.New("Header read timeout")
)

Functions

func IsProxyProtocolError

func IsProxyProtocolError(err error) bool

func NewLazyListener

func NewLazyListener(listener net.Listener, allowedIPs string, headerReadTimeout int, fallbackable bool) (net.Listener, error)

Create new PROXY protocol listener for lazy mode. Lazy mode means PROXY protocol header will be processed at first `Read` call. * listener is basic listener for TCP * allowedIPs is protocol allowed addresses or CIDRs split by `,` if use '*' means allow any address * headerReadTimeout is timeout for PROXY protocol header read

func NewListener

func NewListener(listener net.Listener, allowedIPs string, headerReadTimeout int, fallbackable bool) (net.Listener, error)

Create new PROXY protocol listener * listener is basic listener for TCP * allowedIPs is protocol allowed addresses or CIDRs split by `,` if use '*' means allow any address * headerReadTimeout is timeout for PROXY protocol header read

Types

type UnderlayConn

type UnderlayConn interface {
	// NetConn returns the underlying net.Conn that this connection wraps.
	NetConn() net.Conn
}

UnderlayConn is implemented by connections that wrap an underlying net.Conn and can hand it back. Its single method mirrors the exported API of *crypto/tls.Conn (NetConn() net.Conn), so callers can unwrap either kind of connection through one shared interface, for example to reach syscall.Conn and inspect the underlying file descriptor.