ranch_proxy_header(3)

Name

ranch_proxy_header - PROXY protocol

Description

The module ranch_proxy_header provides functions for parsing and building the PROXY protocol header.

Exports

• ranch_proxy_header:parse(3) - Parse a PROXY protocol header
• ranch_proxy_header:header(3) - Build a PROXY protocol header
• ranch_proxy_header:to_connection_info(3) - Convert proxy_info() to ssl:connection_info()

Types

proxy_info()

proxy_info() = #{
    %% Mandatory part.
    version := 1 | 2,
    command := local | proxy,
    transport_family   => undefined | ipv4 | ipv6 | unix,
    transport_protocol => undefined | stream | dgram,

    %% Addresses.
    src_address  => inet:ip_address() | binary(),
    src_port     => inet:port_number(),
    dest_address => inet:ip_address() | binary(),
    dest_port    => inet:port_number(),

    %% Extra TLV-encoded data.
    alpn      => binary(), %% US-ASCII.
    authority => binary(), %% UTF-8.
    unique_id => binary(), %% Opaque byte sequence of up to 128 bytes.
    netns     => binary(), %% US-ASCII.
    ssl       => #{
        client   := [ssl | cert_conn | cert_sess],
        verified := boolean(),
        version  => binary(), %% US-ASCII.
        cipher   => binary(), %% US-ASCII.
        sig_alg  => binary(), %% US-ASCII.
        key_alg  => binary(), %% US-ASCII.
        cn       => binary()  %% UTF-8.
    },

    %% Unknown TLVs can't be parsed so the raw data is given.
    raw_tlvs => [{0..255, binary()}]
}.

The PROXY protocol information.

The following fields may be found, although most of them are optional:

version

The PROXY protocol version used.

command

proxy is used for proxied connections. local for non-proxied connections. Those do not have any additional information.

transport_family

The transport family of the original connection.

transport_protocol

The transport protocol of the original connection.

src_address

The source address of the original connection. This is the original address of the client.

src_port

The source port of the original connection. This is the port the client opened on its end for the connection. It is not defined for UNIX domain sockets.

dest_address

The destination address of the original connection.

dest_port

The destination port of the original connection. It is not defined for UNIX domain sockets.

alpn

The upper layer protocol in use over the connection. This is typically negotiated via the ALPN extension for TLS.

authority

The host name serving as authority for the connection. This is typically passed using the SNI extension for TLS.

unique_id

An opaque byte sequence of up to 128 bytes generated by the upstream proxy that uniquely identifies the connection.

netns

The namespace's name for the original connection.

ssl

Various information pertaining to the original SSL/TLS connection.

client

A list containing a number of flags. ssl indicates that the client connected over SSL/TLS. cert_conn indicates that the client provided a certificate over the original connection. cert_sess indicates that the client provided a certificate at least once over the TLS session this connection belongs to.

verified

Whether the client presented a certificate and it was successfully verified.

version

The US-ASCII string containing the SSL/TLS version used for the original connection.

cipher

The US-ASCII string name of the cipher used.

sig_alg

The US-ASCII string name of the algorithm used to sign the certificate provided by the client.

key_alg

The US-ASCII string name of the algorithm used to generate the key of the certificate provided by the client.

cn

The UTF-8 string representation of the Common Name field of the client certificate's Distinguished Name.

raw_tlvs

The non-standard TLVs that Ranch was not able to parse.

Changelog

• 2.2: The unique_id TLV was added.
• 1.7: Module introduced.

See also

ranch(7)