~ubuntu-branches/debian/stretch/haproxy/stretch

Viewing changes to doc/proxy-protocol.txt

Committer: Package Import Robot
Author(s): Vincent Bernat
Date: 2015-05-02 16:38:28 UTC
mfrom: (1.3.13)
Revision ID: package-import@ubuntu.com-20150502163828-lph2toctaqrw41x5

Tags: 1.5.12-1

* New upstream stable release including the following fixes:
  - BUG/MAJOR: http: don't read past buffer's end in http_replace_value
  - BUG/MAJOR: http: prevent risk of reading past end with balance
               url_param
  - BUG/MEDIUM: Do not consider an agent check as failed on L7 error
  - BUG/MEDIUM: patern: some entries are not deleted with case
                insensitive match
  - BUG/MEDIUM: buffer: one byte miss in buffer free space check
  - BUG/MEDIUM: http: thefunction "(req|res)-replace-value" doesn't
                respect the HTTP syntax
  - BUG/MEDIUM: peers: correctly configure the client timeout
  - BUG/MEDIUM: http: hdr_cnt would not count any header when called
                without name
  - BUG/MEDIUM: listener: don't report an error when resuming unbound
                listeners
  - BUG/MEDIUM: init: don't limit cpu-map to the first 32 processes only
  - BUG/MEDIUM: stream-int: always reset si->ops when si->end is
                nullified
  - BUG/MEDIUM: http: remove content-length from chunked messages
  - BUG/MEDIUM: http: do not restrict parsing of transfer-encoding to
                HTTP/1.1
  - BUG/MEDIUM: http: incorrect transfer-coding in the request is a bad
                request
  - BUG/MEDIUM: http: remove content-length form responses with bad
                transfer-encoding
  - BUG/MEDIUM: http: wait for the exact amount of body bytes in
                wait_for_request_body

Show diffs side-by-side

added added

removed removed

doc/proxy-protocol.txt

2014/07/25 Willy Tarreau

2015/05/02 Willy Tarreau

HAProxy Technologies

The PROXY protocol

Versions 1 & 2

2014/06/11 - fix example code to consider ver+cmd merge

2014/06/14 - fix v2 header check in example code, and update Forwarded spec

2014/07/12 - update list of implementations (add Squid)

2015/05/02 - update list of implementations and format of the TLV add-ons

1. Background

515

516

the Type and Length bytes), and following the length field is the number of

516

517

bytes specified by the length.

517

518

struct {

519

struct pp2_tlv {

519

520

uint8_t type;

520

521

uint8_t length_hi;

521

522

uint8_t length_lo;

522

523

uint8_t value[0];

523

} tlv;

524

};

525

526

The following types have already been registered for the <type> field :

527

528

#define PP2_TYPE_ALPN 0x01

529

#define PP2_TYPE_AUTHORITY 0x02

530

#define PP2_TYPE_SSL 0x20

531

#define PP2_TYPE_SSL_VERSION 0x21

532

#define PP2_TYPE_SSL_CN 0x22

533

#define PP2_TYPE_NETNS 0x30

534

535

For the type PP2_TYPE_SSL, the value is itselv a defined like this :

536

537

struct pp2_tlv_ssl {

538

uint8_t client;

539

uint32_t verify;

540

struct pp2_tlv sub_tlv[0];

541

};

542

543

And the <client> field is made of a bit field from the following values,

544

indicating which element is present :

545

546

#define PP2_CLIENT_SSL 0x01

547

#define PP2_CLIENT_CERT_CONN 0x02

548

#define PP2_CLIENT_CERT_SESS 0x04

549

550

Each of these elements may lead to extra data being appended to this TLV using

551

a second level of TLV encapsulation. It is thus possible to find multiple TLV

552

values after this field. The total length of the upper TLV will reflect this.

553

554

PP2_CLIENT_SSL indicates that the client connected over SSL/TLS. When this

555

field is present, the string representation of the TLS version is appended at

556

the end of the field in the TLV format using the type PP2_TYPE_SSL_VERSION.

557

558

PP2_CLIENT_CERT_CONN indicates that the client provided a certificate over the

559

current connection. PP2_CLIENT_CERT_SESS indicates that the client provided a

560

certificate at least once over the TLS session this connection belongs to. In

561

both cases, the string representation of the client certificate's CN may be

562

appended after the SSL/TLS version using the TLV format using the type

563

PP2_TYPE_SSL_CN.

564

565

The type PP2_TYPE_NETNS defines the value as the string representation of the

566

namespace's name.

524

567

525

568

526

569

3. Implementations

554

597

A patch is available for Stud[5] to implement version 1 of the protocol on

555

598

incoming connections.

556

599

557

Support for the protocol in the Varnish cache is being considered [6].

600

Support for versions 1 and 2 of the protocol was added to Varnish 4.1 [6].

558

601

559

602

Exim added support for version 1 and version 2 of the protocol for incoming

560

603

connections on 2014/05/13, and will be released as part of version 4.83.

561

604

605

Squid added support for versions 1 and 2 of the protocol in version 3.5 [7].

606

607

Jetty 9.3.0 supports protocol version 1.

608

562

609

The protocol is simple enough that it is expected that other implementations

563

610

will appear, especially in environments such as SMTP, IMAP, FTP, RDP where the

564

611

client's address is an important piece of information for the server and some

743

790

[3] http://www.stunnel.org/

744

791

[4] https://github.com/bumptech/stud

745

792

[5] https://github.com/bumptech/stud/pull/81

746

[6] https://www.varnish-cache.org/trac/wiki/Future_Protocols

793

[6] https://www.varnish-cache.org/docs/trunk/phk/ssl_again.html

794

[7] http://wiki.squid-cache.org/Squid-3.5

747

795

748

796

749

797

9. Sample code

Older »