go-proxyproto

The PROXY protocol for UDP requires a header in every datagram. Because net.Listener and net.Conn are designed for continuous streams, they cannot be used for UDP. Instead, use proxyproto.ParseUDPDatagram to read headers and Header.FormatUDPDatagram to prepare outgoing packets.

Note: ParseUDPDatagram does not have a built-in trusted-source policy. You must manually verify the sender's address from net.PacketConn.ReadFrom before trusting the address returned by the header.

When using TLS, the order of wrapping depends on when the PROXY header is sent:

1. Header before TLS (Cleartext): Wrap the PROXY listener inside the TLS listener. tls.NewListener(&proxyproto.Listener{Listener: l}, tlsConfig)

2. Header inside TLS (Encrypted): Wrap the TLS listener inside the PROXY listener. &proxyproto.Listener{Listener: tls.NewListener(l, tlsConfig)}

Install the library using go get to add it to your Go project.

$ go get github.com/pires/go-proxyproto

When implementing a custom Policy or ConnPolicy for a proxyproto.Listener, you should wrap address-classification failures in ErrInvalidUpstream.

This allows the Listener.Accept() loop to distinguish between a single unclassifiable peer (which should be ignored) and a fatal error that should stop the entire server. If your policy returns ErrInvalidUpstream, the listener will close that specific connection and keep listening for others.

var ErrInvalidUpstream = fmt.Errorf("proxyproto: upstream connection address not trusted for PROXY information")

AWS NLB may not send the PROXY v2 header until the client sends payload (default: on_first_ack_with_payload). This causes failures for server-first protocols like SMTP, FTP, or SSH.

To fix this, change the target group attribute proxy_protocol_v2.client_to_server.header_placement to on_first_ack so the header arrives before the backend begins communication.

To receive PROXY protocol headers on a server, wrap your existing net.Listener with &proxyproto.Listener{}. When you call Accept(), the returned connection will have its RemoteAddr() populated with the client address extracted from the PROXY header.

proxyListener := &proxyproto.Listener{Listener: ln}
conn, err := proxyListener.Accept()
// Connections must open with a PROXY header (the default policy is REQUIRE);
// conn.RemoteAddr() then reports the client address from that header.

To send PROXY protocol headers from a client, create a header using proxyproto.HeaderProxyFromAddrs and write it to the connection using Header.WriteTo before sending any application data.

header := proxyproto.HeaderProxyFromAddrs(1, sourceAddr, destinationAddr)
_, err := header.WriteTo(conn) // write the PROXY header before application data

The DefaultPolicy variable determines the behavior when no explicit policy is configured. By default, it is set to REQUIRE to comply with the PROXY protocol specification.

If you are migrating a deployment that relies on the older behavior where the PROXY header was optional, you can set this at program initialization:

proxyproto.DefaultPolicy = proxyproto.USE

Warning: This is a package-level variable. It must be set during init() or at the start of your program and must not be modified concurrently while accepting connections.

Once a Header is parsed, you can extract connection details using type-specific methods. These methods return a boolean ok to indicate if the header actually contains that type of information.

• TCPAddrs(): Returns (*net.TCPAddr, *net.TCPAddr, bool) for stream-based TCP headers.
• UDPAddrs(): Returns (*net.UDPAddr, *net.UDPAddr, bool) for datagram-based UDP headers.
• UnixAddrs(): Returns (*net.UnixAddr, *net.UnixAddr, bool) for UNIX-based headers.
• IPs(): Returns (net.IP, net.IP, bool) for TCP/UDP headers.
• Ports(): Returns (int, int, bool) for TCP/UDP headers.

if src, dest, ok := header.TCPAddrs(); ok {
    fmt.Printf("Source: %s, Dest: %s\n", src, dest)
}

if srcIP, destIP, ok := header.IPs(); ok {
    fmt.Printf("Source IP: %s, Dest IP: %s\n", srcIP, destIP)
}