diff options
author | Loïc Hoguin <[email protected]> | 2018-11-14 10:55:23 +0100 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2018-11-14 10:55:23 +0100 |
commit | 2f502078fd0f56e3e61e58f1d57ae15f9f736ffe (patch) | |
tree | cd80952cbe2f336a0485535ef82a8c59d49a593d /doc/src/manual/ranch_proxy_header.asciidoc | |
parent | 4d0ae7e8c646d00eb868fdee11756b1770a3b976 (diff) | |
download | ranch-2f502078fd0f56e3e61e58f1d57ae15f9f736ffe.tar.gz ranch-2f502078fd0f56e3e61e58f1d57ae15f9f736ffe.tar.bz2 ranch-2f502078fd0f56e3e61e58f1d57ae15f9f736ffe.zip |
Document the PROXY-related functions; prepare 1.7.0
Diffstat (limited to 'doc/src/manual/ranch_proxy_header.asciidoc')
-rw-r--r-- | doc/src/manual/ranch_proxy_header.asciidoc | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/doc/src/manual/ranch_proxy_header.asciidoc b/doc/src/manual/ranch_proxy_header.asciidoc new file mode 100644 index 0000000..7155c5e --- /dev/null +++ b/doc/src/manual/ranch_proxy_header.asciidoc @@ -0,0 +1,164 @@ += 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 + +== 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 informations 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)] |