Crate proxy_header

source ·
Expand description

PROXY protocol decoder and encoder

This crate provides a decoder and encoder for the PROXY protocol, which is used to preserve original client connection information when proxying TCP connections for protocols that do not support this higher up in the stack.

The PROXY protocol is supported by many load balancers and proxies, including HAProxy, Amazon ELB, Amazon ALB, and others.

This crate implements the entire specification, except parsing the AF_UNIX address type (the header is validated / parsed, but the address is not decoded or exposed in the API).

§Usage

§Decoding

To decode a PROXY protocol header from an existing buffer, use ProxyHeader::parse:

use proxy_header::{ProxyHeader, ParseConfig};

let buf = b"PROXY TCP6 2001:db8:1::1 2001:db8:2::1 52953 25\r\nHELO example.com\r\n";

let (header, len) = ProxyHeader::parse(buf, ParseConfig::default())?;
match header.proxied_address() {
   Some(addr) => {
      println!("Proxied connection from {} to {}", addr.source, addr.destination);
   }
   None => {
      println!("Local connection (e.g. healthcheck)");
  }
}

println!("Client sent: {:?}", &buf[len..]);

In addition to the address information, the PROXY protocol version 2 header can contain additional information in the form of TLV (type-length-value) fields. These can be accessed through the ProxyHeader::tlvs iterator or through convenience accessors such as ProxyHeader::authority.

See Tlv for more information on the different types of TLV fields.

use proxy_header::Tlv;

for tlv in header.tlvs() {
    match tlv? {  // TLV can be malformed
        Tlv::UniqueId(v) => {
            println!("Unique connection ID: {:?}", v);
        }
        Tlv::Authority(v) => {
            println!("Authority string (SNI): {:?}", v);
        }
        _ => {}
    }
}

See also io module for a stream wrapper that can automatically parse PROXY protocol.

§Encoding

To encode a PROXY protocol header, use ProxyHeader::encode_v1 for version 1 headers and ProxyHeader::encode_v2 for version 2 headers.

use proxy_header::{ProxyHeader, ProxiedAddress, Protocol};

let addrs = ProxiedAddress::stream(
   "[2001:db8::1:1]:51234".parse().unwrap(),
   "[2001:db8::2:1]:443".parse().unwrap()
);
let header = ProxyHeader::with_address(addrs);

let mut buf = [0u8; 1024];
let len = header.encode_to_slice_v2(&mut buf).unwrap();

Modules§

  • io
    IO wrapper for proxied streams.

Structs§

  • ParseConfig
    Configuration for parsing PROXY protocol headers
  • ProxiedAddress
    Address information from a PROXY protocol header
  • ProxyHeader
    A PROXY protocol header
  • SslInfo
    SSL information from a PROXY protocol header
  • Tlvs
    Iterator over PROXY protocol TLV (type-length-value) fields

Enums§