"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/internals/filters.txt" between
haproxy-2.0.13.tar.gz and haproxy-2.0.14.tar.gz

About: HAProxy is a TCP/HTTP reverse proxy which is particularly suited for high availability environments. LTS (Long-Term Support) release.

filters.txt  (haproxy-2.0.13):filters.txt  (haproxy-2.0.14)
skipping to change at line 52 skipping to change at line 52
First of all, to fully understand how filters work and how to create one, it is First of all, to fully understand how filters work and how to create one, it is
best to know, at least from a distance, what is a proxy (frontend/backend), a best to know, at least from a distance, what is a proxy (frontend/backend), a
stream and a channel in HAProxy and how these entities are linked to each other. stream and a channel in HAProxy and how these entities are linked to each other.
doc/internals/entities.pdf is a good overview. doc/internals/entities.pdf is a good overview.
Then, to support filters, many callbacks has been added to HAProxy at different Then, to support filters, many callbacks has been added to HAProxy at different
places, mainly around channel analyzers. Their purpose is to allow filters to places, mainly around channel analyzers. Their purpose is to allow filters to
be involved in the data processing, from the stream creation/destruction to be involved in the data processing, from the stream creation/destruction to
the data forwarding. Depending of what it should do, a filter can implement all the data forwarding. Depending of what it should do, a filter can implement all
or part of these callbacks. For now, existing callbacks are focused on or part of these callbacks. For now, existing callbacks are focused on
streams. But futur improvements could enlarge filters scope. For example, it streams. But future improvements could enlarge filters scope. For example, it
could be useful to handle events at the connection level. could be useful to handle events at the connection level.
In HAProxy configuration file, a filter is declared in a proxy section, except In HAProxy configuration file, a filter is declared in a proxy section, except
default. So the configuration corresponding to a filter declaration is attached default. So the configuration corresponding to a filter declaration is attached
to a specific proxy, and will be shared by all its instances. it is opaque from to a specific proxy, and will be shared by all its instances. it is opaque from
the HAProxy point of view, this is the filter responsibility to manage it. For the HAProxy point of view, this is the filter responsibility to manage it. For
each filter declaration matches a uniq configuration. Several declarations of each filter declaration matches a uniq configuration. Several declarations of
the same filter in the same proxy will be handle as different filters by the same filter in the same proxy will be handle as different filters by
HAProxy. HAProxy.
skipping to change at line 82 skipping to change at line 82
It is important to remember the configuration of a filter is shared by all its It is important to remember the configuration of a filter is shared by all its
instances, while the context of an instance is owned by a uniq stream. instances, while the context of an instance is owned by a uniq stream.
Filters are designed to be chained. It is possible to declare several filters in Filters are designed to be chained. It is possible to declare several filters in
the same proxy section. The declaration order is important because filters will the same proxy section. The declaration order is important because filters will
be called one after the other respecting this order. Frontend and backend be called one after the other respecting this order. Frontend and backend
filters are also chained, frontend ones called first. Even if the filters filters are also chained, frontend ones called first. Even if the filters
processing is serialized, each filter will bahave as it was alone (unless it was processing is serialized, each filter will bahave as it was alone (unless it was
developed to be aware of other filters). For all that, some constraints are developed to be aware of other filters). For all that, some constraints are
imposed to filters, especially when data exchanged between the client and the imposed to filters, especially when data exchanged between the client and the
server are processed. We will dicuss again these contraints when we will tackle server are processed. We will discuss again these constraints when we will tackl e
the subject of writing a filter. the subject of writing a filter.
2. HOW TO USE FILTERS 2. HOW TO USE FILTERS
--------------------- ---------------------
To use a filter, you must use the parameter 'filter' followed by the filter name To use a filter, you must use the parameter 'filter' followed by the filter name
and, optionnaly, its configuration in the desired listen, frontend or backend and, optionnaly, its configuration in the desired listen, frontend or backend
section. For example: section. For example:
listen test listen test
skipping to change at line 116 skipping to change at line 116
[...] [...]
Available filters : Available filters :
[COMP] compression [COMP] compression
[TRACE] trace [TRACE] trace
Multiple filter lines can be used in a proxy section to chain filters. Filters Multiple filter lines can be used in a proxy section to chain filters. Filters
will be called in the declaration order. will be called in the declaration order.
Some filters can support implicit declarartions in certain circumstances Some filters can support implicit declarations in certain circumstances
(without the filter line). This is not recommanded for new features but are (without the filter line). This is not recommended for new features but are
useful for existing ones moved in a filter, for backward compatibility useful for existing ones moved in a filter, for backward compatibility
reasons. Implicit declarartions are supported when there is only one filter used reasons. Implicit declarations are supported when there is only one filter used
on a proxy. When several filters are used, explicit declarartions are mandatory. on a proxy. When several filters are used, explicit declarations are mandatory.
The HTTP compression filter is one of these filters. Alone, using 'compression' The HTTP compression filter is one of these filters. Alone, using 'compression'
keywords is enough to use it. But when at least a second filter is used, a keywords is enough to use it. But when at least a second filter is used, a
filter line must be added. filter line must be added.
# filter line is optionnal # filter line is optionnal
listen t1 listen t1
bind *:80 bind *:80
compression algo gzip compression algo gzip
compression offload compression offload
server srv x.x.x.x:80 server srv x.x.x.x:80
skipping to change at line 272 skipping to change at line 272
field must be set during the parsing phase (See § 3.2) and can be refine field must be set during the parsing phase (See § 3.2) and can be refine
during the initialization phase (See § 3.3). If it is dynamically allocated, during the initialization phase (See § 3.3). If it is dynamically allocated,
it is the filter responsibility to free it. it is the filter responsibility to free it.
The filter configuration is global and shared by all its instances. A filter The filter configuration is global and shared by all its instances. A filter
instance is created in the context of a stream and attached to this stream. in instance is created in the context of a stream and attached to this stream. in
the structure 'stream', the field 'strm_flt' is the state of all filter the structure 'stream', the field 'strm_flt' is the state of all filter
instances attached to a stream: instances attached to a stream:
/* /*
* Structure reprensenting the "global" state of filters attached to a * Structure representing the "global" state of filters attached to a
* stream. * stream.
*/ */
struct strm_flt { struct strm_flt {
struct list filters; /* List of filters attached to a str eam */ struct list filters; /* List of filters attached to a str eam */
struct filter *current[2]; /* From which filter resume processi ng, for a specific channel. struct filter *current[2]; /* From which filter resume processi ng, for a specific channel.
* This is used for resumable callba cks only, * This is used for resumable callba cks only,
* If NULL, we start from the first filter. * If NULL, we start from the first filter.
* 0: request channel, 1: response c hannel */ * 0: request channel, 1: response c hannel */
unsigned short flags; /* STRM_FL_* */ unsigned short flags; /* STRM_FL_* */
unsigned char nb_req_data_filters; /* Number of data filters registered on the request channel */ unsigned char nb_req_data_filters; /* Number of data filters registered on the request channel */
unsigned char nb_rsp_data_filters; /* Number of data filters registered on the response channel */ unsigned char nb_rsp_data_filters; /* Number of data filters registered on the response channel */
}; };
Filter instances attached to a stream are stored in the field Filter instances attached to a stream are stored in the field
'strm_flt.filters', each instance is of type 'struct filter *': 'strm_flt.filters', each instance is of type 'struct filter *':
/* /*
* Structure reprensenting a filter instance attached to a stream * Structure representing a filter instance attached to a stream
* *
* 2D-Array fields are used to store info per channel. The first index * 2D-Array fields are used to store info per channel. The first index
* stands for the request channel, and the second one for the response * stands for the request channel, and the second one for the response
* channel. Especially, <next> and <fwd> are offets representing amount of * channel. Especially, <next> and <fwd> are offets representing amount of
* data that the filter are, respectively, parsed and forwarded on a * data that the filter are, respectively, parsed and forwarded on a
* channel. Filters can access these values using FLT_NXT and FLT_FWD * channel. Filters can access these values using FLT_NXT and FLT_FWD
* macros. * macros.
*/ */
struct filter { struct filter {
struct flt_conf *config; /* the filter's configuration */ struct flt_conf *config; /* the filter's configuration */
skipping to change at line 634 skipping to change at line 634
/* ... */ /* ... */
} }
3.5. ANALYZING THE CHANNELS ACTIVITY 3.5. ANALYZING THE CHANNELS ACTIVITY
------------------------------------ ------------------------------------
The main purpose of filters is to take part in the channels analyzing. To do so, The main purpose of filters is to take part in the channels analyzing. To do so,
there is 2 callbacks, 'flt_ops.channel_pre_analyze' and there is 2 callbacks, 'flt_ops.channel_pre_analyze' and
'flt_ops.channel_post_analyze', called respectively before and after each 'flt_ops.channel_post_analyze', called respectively before and after each
analyzer attached to a channel, execpt analyzers responsible for the data analyzer attached to a channel, except analyzers responsible for the data
parsing/forwarding (TCP or HTTP data). Concretely, on the request channel, these parsing/forwarding (TCP or HTTP data). Concretely, on the request channel, these
callbacks could be called before following analyzers: callbacks could be called before following analyzers:
* tcp_inspect_request (AN_REQ_INSPECT_FE and AN_REQ_INSPECT_BE) * tcp_inspect_request (AN_REQ_INSPECT_FE and AN_REQ_INSPECT_BE)
* http_wait_for_request (AN_REQ_WAIT_HTTP) * http_wait_for_request (AN_REQ_WAIT_HTTP)
* http_wait_for_request_body (AN_REQ_HTTP_BODY) * http_wait_for_request_body (AN_REQ_HTTP_BODY)
* http_process_req_common (AN_REQ_HTTP_PROCESS_FE) * http_process_req_common (AN_REQ_HTTP_PROCESS_FE)
* process_switching_rules (AN_REQ_SWITCHING_RULES) * process_switching_rules (AN_REQ_SWITCHING_RULES)
* http_process_req_ common (AN_REQ_HTTP_PROCESS_BE) * http_process_req_ common (AN_REQ_HTTP_PROCESS_BE)
* http_process_tarpit (AN_REQ_HTTP_TARPIT) * http_process_tarpit (AN_REQ_HTTP_TARPIT)
 End of changes. 7 change blocks. 
9 lines changed or deleted 9 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)