dudeswave2/ranch/doc/src/manual/ranch_proxy_header.asciidoc

= 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

* link:man:ranch_proxy_header:parse(3)[ranch_proxy_header:parse(3)] - Parse a PROXY protocol header
* link:man:ranch_proxy_header:header(3)[ranch_proxy_header:header(3)] - Build a PROXY protocol header
* link:man:ranch_proxy_header:to_connection_info(3)[ranch_proxy_header:to_connection_info(3)] - Convert proxy_info() to ssl:connection_info()

== Types

=== proxy_info()

[source,erlang]
----
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.
    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.

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

* *1.7*: Module introduced.

== See also

link:man:ranch(7)[ranch(7)]