blob: 646f9eaa1255ac50800a2b234fe58020bf4c99cd [file] [log] [blame]
Willy Tarreau8263b912011-09-05 01:04:44 +020012011/02/25 - Description of the different entities in haproxy - w@1wt.eu
2
3
41) Definitions
5--------------
6
7Listener
8--------
9
10A listener is the entity which is part of a frontend and which accepts
11connections. There are as many listeners as there are ip:port couples.
12There is at least one listener instanciated for each "bind" entry, and
13port ranges will lead to as many listeners as there are ports in the
14range. A listener just has a listening file descriptor ready to accept
15incoming connections and to dispatch them to upper layers.
16
17
18Initiator
19---------
20
21An initiator is instanciated for each incoming connection on a listener. It may
22also be instanciated by a task pretending to be a client. An initiator calls
23the next stage's accept() callback to present it with the parameters of the
24incoming connection.
25
26
27Session
28-------
29
30A session is the only entity located between an initiator and a connector.
31This is the last stage which offers an accept() callback, and all of its
32processing will continue with the next stage's connect() callback. It holds
33the buffers needed to forward the protocol data between each side. This entity
34sees the native protocol, and is able to call analysers on these buffers. As it
35is used in both directions, it always has two buffers.
36
37When transformations are required, some of them may be done on the initiator
38side and other ones on the connector side. If additional buffers are needed for
39such transforms, those buffers cannot replace the session's buffers, but they
40may complete them.
41
42A session only needs to be instanciated when forwarding of data is required
43between two sides. Accepting and filtering on layer 4 information only does not
44require a session.
45
46For instance, let's consider the case of a proxy which receives and decodes
47HTTPS traffic, processes it as HTTP and recodes it as HTTPS before forwarding
48it. We'd have 3 layers of buffers, where the middle ones are used for
49forwarding of the protocol data (HTTP here) :
50
51 <-- ssl dec --> <-forwarding-> <-- ssl enc -->
52
53 ,->[||||]--. ,->[||||]--. ,->[||||]--.
54 client (|) (|) (|) (|) server
55 ^--[||||]<-' ^--[||||]<-' ^--[||||]<-'
56
57 HTTPS HTTP HTTPS
58
59The session handling code is only responsible for monitoring the forwarding
60buffers here. It may declare the end of the session once those buffers are
61closed and no analyser wants to re-open them. The session is also the entity
62which applies the load balancing algorithm and decides the server to use.
63
64The other sides are responsible for propagating the state up to the session
65which takes decisions.
66
67
68Connector
69---------
70
71A connector is the entity which permits to instanciate a connection to a known
72destination. It presents a connect() callback, and as such appears on the right
73side of diagrams.
74
75
76Connection
77----------
78
79A connection is the entity instanciated by a connector. It may be composed of
80multiple stages linked together. Generally it is the part of the stream
81interface holding a file descriptor, but it can also be a processing block or a
82transformation block terminated by a connection. A connection presents a
83server-side interface.
84
85
862) Sequencing
87-------------
88
89Upon startup, listeners are instanciated by the configuration. When an incoming
90connection reaches a listening file descriptor, its read() callback calls the
91corresponding listener's accept() function which instanciates an initiator and
92in turn recursively calls upper layers' accept() callbacks until
93accept_session() is called. accept_session() instanciates a new session which
94starts protocol analysis via process_session(). When all protocol analysis is
95done, process_session() calls the connect() callback of the connector in order
96to get a connection.