mirrors/haproxy
1
0
Fork 0
mirror of https://git.haproxy.org/git/haproxy.git/ synced 2025-08-07 15:47:01 +02:00
Code Issues Projects Releases Wiki Activity

DOC: spoe: Update SPOE documentation to reflect recent refactoring

Browse Source 
The SPOE was refactored. Several parameters were deprecated. Fragmentation
and async capabilities support were removed. The default log-format was
updated too.

So, the SPOE documentation was updated accordingly.

The related issue is #2502.
This commit is contained in:
Christopher Faulet 2024-07-12 16:38:47 +02:00
parent e83ab972cc
commit b353232641
1 changed files with 117 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

317
doc/SPOE.txt
View File

@ -1,7 +1,7 @@
----------------------------------------------- -----------------------------------------------
Stream Processing Offload Engine (SPOE) Stream Processing Offload Engine (SPOE)
Version 1.2 Version 1.2
( Last update: 2020-06-13 ) ( Last update: 2024-07-12 )
----------------------------------------------- -----------------------------------------------
Author : Christopher Faulet Author : Christopher Faulet
Contact : cfaulet at haproxy dot com Contact : cfaulet at haproxy dot com
@ -69,13 +69,10 @@ systems (often at least the connect() is blocking). So, it is hard to properly
implement Single Sign On solution (SSO) in HAProxy. The SPOE will ease this implement Single Sign On solution (SSO) in HAProxy. The SPOE will ease this
kind of processing, or we hope so. kind of processing, or we hope so.
Now, the aim of SPOE is to allow any kind of offloading on the streams. First The aim of SPOE is to allow any kind of offloading on the streams. It can
releases won't do lot of things. As we will see, there are few handled events offload the processing before "tcp-request content", "tcp-response content",
and even less actions supported. Actually, for now, the SPOE can offload the "http-request" and "http-response" rules. It is also possible to offload the
processing before "tcp-request content", "tcp-response content", "http-request" processing via an TCP/HTTP rule.
and "http-response" rules. And it only supports variables definition. But, in
spite of these limited features, we can easily imagine to implement SSO
solution, ip reputation or ip geolocation services.
Some example implementations in various languages are linked to from the Some example implementations in various languages are linked to from the
HAProxy Wiki page dedicated to this mechanism: HAProxy Wiki page dedicated to this mechanism:
@ -85,8 +82,8 @@ HAProxy Wiki page dedicated to this mechanism:
2. SPOE configuration 2. SPOE configuration
---------------------- ----------------------
Because SPOE is implemented as a filter, To use it, you must declare a "filter Because SPOE is implemented as a filter, To use it, a "filter spoe" line must
spoe" line in a proxy section (frontend/backend/listen) : be declared xin a proxy section (frontend/backend/listen) :
frontend my-front frontend my-front
... ...
@ -99,9 +96,10 @@ the SPOE configuration. So it is possible to use the same SPOE configuration
for several engines. If no name is provided, the SPOE configuration must not for several engines. If no name is provided, the SPOE configuration must not
contain any scope directive. contain any scope directive.
We use a separate configuration file on purpose. By commenting SPOE filter Using a separate configuration file makes possible to disable completely an
line, you completely disable the feature, including the parsing of sections engine by only commenting the SPOE filter line, including the parsing of
reserved to SPOE. This is also a way to keep the HAProxy configuration clean. sections reserved to SPOE. This is also a way to keep the HAProxy configuration
clean.
A SPOE configuration file must contains, at least, the SPOA configuration A SPOE configuration file must contains, at least, the SPOA configuration
("spoe-agent" section) and SPOE messages/groups ("spoe-message" or "spoe-group" ("spoe-agent" section) and SPOE messages/groups ("spoe-message" or "spoe-group"
@ -114,12 +112,13 @@ file.
2.1. SPOE scope 2.1. SPOE scope
------------------------- -------------------------
If you specify an engine name on the SPOE filter line, then you need to define If an engine name is specified on the SPOE filter line, then the corresponding
scope in the SPOE configuration with the same name. You can have several SPOE scope must be defined in the SPOE configuration with the same name. It is
scope in the same file. In each scope, you must define one and only one possible to have several SPOE scopes in the same file. In each scope, one and
"spoe-agent" section to configure the SPOA linked to your SPOE and several only one "spoe-agent" section must be defined, to configure the SPOA linked to
"spoe-message" and "spoe-group" sections to describe, respectively, messages and the defined engine and several "spoe-message" and "spoe-group" sections to
group of messages sent to servers managed by your SPOA. describe, respectively, messages and group of messages sent to servers managed
the SPOA.
A SPOE scope starts with this kind of line : A SPOE scope starts with this kind of line :
@ -148,15 +147,15 @@ If no engine name is provided on the SPOE filter line, no SPOE scope must be
found in the SPOE configuration file. All the file is considered to be in the found in the SPOE configuration file. All the file is considered to be in the
same anonymous and implicit scope. same anonymous and implicit scope.
The engine name must be uniq for a proxy. If no engine name is provided on the The engine name must be unique for a proxy. If no engine name is provided on
SPOE filter line, the SPOE agent name is used by default. the SPOE filter line, the SPOE agent name is used by default.
2.2. "spoe-agent" section 2.2. "spoe-agent" section
-------------------------- --------------------------
For each engine, you must define one and only one "spoe-agent" section. In this For each engine, exactly one "spoe-agent" section must be defined. Enabled SPOE
section, you will declare SPOE messages and the backend you will use. You will messages are declared in this section, and all the parameters (timeout,
also set timeouts and options to customize your agent's behaviour. options, ...) used to customize the agent behavior.
spoe-agent <name> spoe-agent <name>
@ -169,15 +168,10 @@ spoe-agent <name>
following keywords are supported : following keywords are supported :
- groups - groups
- log - log
- maxconnrate
- maxerrrate
- max-frame-size - max-frame-size
- max-waiting-frames
- messages - messages
- [no] option async
- [no] option dontlog-normal - [no] option dontlog-normal
- [no] option pipelining - [no] option pipelining
- [no] option send-frag-payload
- option continue-on-error - option continue-on-error
- option force-set-var - option force-set-var
- option set-on-error - option set-on-error
@ -185,9 +179,16 @@ spoe-agent <name>
- option set-total-time - option set-total-time
- option var-prefix - option var-prefix
- register-var-names - register-var-names
- timeout hello|idle|processing - timeout processing
- use-backend - use-backend
following keywords are deprecated and ignored:
- maxconnrate
- maxerrrate
- max-waiting-frames
- [no] option async
- [no] option send-frag-payload
- timeout hello|idle
groups <grp-name> ... groups <grp-name> ...
Declare the list of SPOE groups that an agent will handle. Declare the list of SPOE groups that an agent will handle.
@ -196,11 +197,11 @@ groups <grp-name> ...
<grp-name> is the name of a SPOE group. <grp-name> is the name of a SPOE group.
Groups declared here must be found in the same engine scope, else an error is Groups declared here must be found in the same engine scope, else an error is
triggered during the configuration parsing. You can have many "groups" lines. triggered during the configuration parsing. Several "groups" lines can be
defined.
See also: "spoe-group" section. See also: "spoe-group" section.
log global log global
log <address> [len <length>] [format <format>] <facility> [<level> [<minlevel>]] log <address> [len <length>] [format <format>] <facility> [<level> [<minlevel>]]
no log no log
@ -211,28 +212,35 @@ no log
See the HAProxy Configuration Manual for details about this option. See the HAProxy Configuration Manual for details about this option.
maxconnrate <number> maxconnrate <number> [DEPRECATED]
Set the maximum number of connections per second to <number>. The SPOE will Set the maximum number of connections per second to <number>. The SPOE will
stop to open new connections if the maximum is reached and will wait to stop to open new connections if the maximum is reached and will wait to
acquire an existing one. So it is important to set "timeout hello" to a acquire an existing one. So it is important to set "timeout hello" to a
relatively small value. relatively small value.
This parameter is now deprecated and ignored. It will be removed in future
versions.
maxerrrate <number> maxerrrate <number> [DEPRECATED]
Set the maximum number of errors per second to <number>. The SPOE will stop Set the maximum number of errors per second to <number>. The SPOE will stop
its processing if the maximum is reached. its processing if the maximum is reached.
This parameter is now deprecated and ignored. It will be removed in future
versions.
max-frame-size <number> max-frame-size <number>
Set the maximum allowed size for frames exchanged between HAProxy and SPOA. Set the maximum allowed size for frames exchanged between HAProxy and SPOA.
It must be in the range [256, tune.bufsize-4] (4 bytes are reserved for the It must be in the range [256, tune.bufsize-4] (4 bytes are reserved for the
frame length). By default, it is set to (tune.bufsize-4). frame length). By default, it is set to (tune.bufsize-4).
max-waiting-frames <number> max-waiting-frames <number> [DEPRECATED]
Set the maximum number of frames waiting for an acknowledgement on the same Set the maximum number of frames waiting for an acknowledgement on the same
connection. This value is only used when the pipelinied or asynchronous connection. This value is only used when the pipelinied or asynchronous
exchanges between HAProxy and SPOA are enabled. By default, it is set to 20. exchanges between HAProxy and SPOA are enabled. By default, it is set to 20.
This parameter is now deprecated and ignored. It will be removed in future
versions.
messages <msg-name> ... messages <msg-name> ...
Declare the list of SPOE messages that an agent will handle. Declare the list of SPOE messages that an agent will handle.
@ -240,23 +248,24 @@ messages <msg-name> ...
<msg-name> is the name of a SPOE message. <msg-name> is the name of a SPOE message.
Messages declared here must be found in the same engine scope, else an error Messages declared here must be found in the same engine scope, else an error
is triggered during the configuration parsing. You can have many "messages" is triggered during the configuration parsing. Several "messages" lines can
lines. be defined.
See also: "spoe-message" section. See also: "spoe-message" section.
option async [DEPRECATED]
option async
no option async no option async
Enable or disable the support of asynchronous exchanges between HAProxy and Enable or disable the support of asynchronous exchanges between HAProxy and
SPOA. By default, this option is enabled. SPOA. By default, this option is enabled.
This parameter is now deprecated and ignored. It will be removed in future
versions.
option continue-on-error option continue-on-error
Do not stop the events processing when an error occurred on a stream. Do not stop the events processing when an error occurred on a stream.
By default, for a specific stream, when an abnormal/unexpected error occurs, By default, for a specific stream, when an abnormal/unexpected error occurs,
the SPOE is disabled for all the transaction. So if you have several events the SPOE is disabled for all the transaction. if several events are
configured, such error on an event will disabled all following. For TCP configured, such error on an event will disabled all following. For TCP
streams, this will disable the SPOE for the whole session. For HTTP streams, streams, this will disable the SPOE for the whole session. For HTTP streams,
this will disable it for the transaction (request and response). this will disable it for the transaction (request and response).
@ -264,7 +273,6 @@ option continue-on-error
When set, this option bypass this behaviour and only the current event will When set, this option bypass this behaviour and only the current event will
be ignored. be ignored.
option dontlog-normal option dontlog-normal
no option dontlog-normal no option dontlog-normal
Enable or disable logging of normal, successful processing. Enable or disable logging of normal, successful processing.
@ -273,29 +281,27 @@ no option dontlog-normal
See also: "log" and section 4 about logging. See also: "log" and section 4 about logging.
option force-set-var option force-set-var
By default, SPOE filter only register already known variables (mainly from By default, SPOE filter only register already known variables (mainly from
parsing of the configuration), and process-wide variables (those of scope parsing of the configuration), and process-wide variables (those of scope
"proc") cannot be created. If you want that haproxy trusts the agent and "proc") cannot be created. If HAProxy trusts the agent and registers all
registers all variables (ex: can be useful for LUA workload), activate this variables (ex: can be useful for LUA workload), this option can be sets.
option.
Caution : this option opens to a variety of attacks such as a rogue SPOA that Caution : this option opens to a variety of attacks such as a rogue SPOA that
asks to register too many variables. asks to register too many variables.
option pipelining option pipelining
no option pipelining no option pipelining
Enable or disable the support of pipelined exchanges between HAProxy and Enable or disable the support of pipelined exchanges between HAProxy and
SPOA. By default, this option is enabled. SPOA. By default, this option is enabled.
option send-frag-payload [DEPRECATED]
option send-frag-payload
no option send-frag-payload no option send-frag-payload
Enable or disable the sending of fragmented payload to SPOA. By default, this Enable or disable the sending of fragmented payload to SPOA. By default, this
option is enabled. option is enabled.
This parameter is now deprecated and ignored. It will be removed in future
versions.
option set-on-error <var name> option set-on-error <var name>
Define the variable to set when an error occurred during an event processing. Define the variable to set when an error occurred during an event processing.
@ -307,13 +313,13 @@ option set-on-error <var name>
This variable will only be set when an error occurred in the scope of the This variable will only be set when an error occurred in the scope of the
transaction. As for all other variables define by the SPOE, it will be transaction. As for all other variables define by the SPOE, it will be
prefixed. So, if your variable name is "error" and your prefix is prefixed. So, if the variable name is "error" and the prefix is
"my_spoe_pfx", the variable will be "txn.my_spoe_pfx.error". "my_spoe_pfx", the variable will be "txn.my_spoe_pfx.error".
When set, the variable is an integer representing the error reason. For values When set, the variable is an integer representing the error reason. For values
under 256, it represents an error coming from the engine. Below 256, it under 256, it represents an error coming from the engine. Below 256, it
reports a SPOP error. In this case, to retrieve the right SPOP status code, reports a SPOP error. In this case, to retrieve the right SPOP status code,
you must remove 256 to this value. Here are possible values: 256 must be removed from this value. Here are possible values:
* 1 a timeout occurred during the event processing. * 1 a timeout occurred during the event processing.
@ -347,8 +353,8 @@ option set-process-time <var name>
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
This variable will be set in the scope of the transaction. As for all other This variable will be set in the scope of the transaction. As for all other
variables define by the SPOE, it will be prefixed. So, if your variable name variables define by the SPOE, it will be prefixed. So, if the variable name
is "process_time" and your prefix is "my_spoe_pfx", the variable will be is "process_time" and the prefix is "my_spoe_pfx", the variable will be
"txn.my_spoe_pfx.process_time". "txn.my_spoe_pfx.process_time".
When set, the variable is an integer representing the delay to process the When set, the variable is an integer representing the delay to process the
@ -360,7 +366,6 @@ option set-process-time <var name>
See also: "option set-total-time". See also: "option set-total-time".
option set-total-time <var name> option set-total-time <var name>
Define the variable to set to report the total processing time SPOE for a Define the variable to set to report the total processing time SPOE for a
stream. stream.
@ -371,8 +376,8 @@ option set-total-time <var name>
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
This variable will be set in the scope of the transaction. As for all other This variable will be set in the scope of the transaction. As for all other
variables define by the SPOE, it will be prefixed. So, if your variable name variables define by the SPOE, it will be prefixed. So, if the variable name
is "total_time" and your prefix is "my_spoe_pfx", the variable will be is "total_time" and the prefix is "my_spoe_pfx", the variable will be
"txn.my_spoe_pfx.total_time". "txn.my_spoe_pfx.total_time".
When set, the variable is an integer representing the sum of processing times When set, the variable is an integer representing the sum of processing times
@ -384,7 +389,6 @@ option set-total-time <var name>
See also: "option set-process-time". See also: "option set-process-time".
option var-prefix <prefix> option var-prefix <prefix>
Define the prefix used when variables are set by an agent. Define the prefix used when variables are set by an agent.
@ -399,19 +403,19 @@ option var-prefix <prefix>
The prefix will be added between the variable scope and its name, separated The prefix will be added between the variable scope and its name, separated
by a '.'. It may only contain characters 'a-z', 'A-Z', '0-9', '.' and '_', as by a '.'. It may only contain characters 'a-z', 'A-Z', '0-9', '.' and '_', as
for variables name. In HAProxy configuration, you need to use this prefix as for variables name. In HAProxy configuration, this prefix must be used as a
a part of the variables name. For example, if an agent define the variable part of the variables name. For example, if an agent define the variable
"myvar" in the "txn" scope, with the prefix "my_spoe_pfx", then you should "myvar" in the "txn" scope, with the prefix "my_spoe_pfx", then
use "txn.my_spoe_pfx.myvar" name in your HAProxy configuration. "txn.my_spoe_pfx.myvar" name must be used in HAProxy configuration.
By default, an agent will never set new variables at runtime: It can only set By default, an agent will never set new variables at runtime: It can only set
new value for existing ones. If you want a different behaviour, see new value for existing ones. To change this behaviour, see "force-set-var"
force-set-var option and register-var-names directive. option and "register-var-names" directive.
register-var-names <var name> ... register-var-names <var name> ...
Register some variable names. By default, an agent will not be allowed to set Register some variable names. By default, an agent will not be allowed to set
new variables at runtime. This rule can be totally relaxed by setting the new variables at runtime. This rule can be totally relaxed by setting the
option "force-set-var". If you know all the variables you will need, this option "force-set-var". If all the required variables are known, this
directive is a good way to register them without letting an agent doing what directive is a good way to register them without letting an agent doing what
it want. This is only required if these variables are not referenced anywhere it want. This is only required if these variables are not referenced anywhere
in the HAProxy configuration or the SPOE one. in the HAProxy configuration or the SPOE one.
@ -420,12 +424,12 @@ register-var-names <var name> ...
<var name> is a variable name without the scope. The name may only <var name> is a variable name without the scope. The name may only
contain characters 'a-z', 'A-Z', '0-9', '.' and '_'. contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
The prefix will be automatically added during the registration. You can have The prefix will be automatically added during the registration. Several
many "register-var-names" lines. "register-var-names" lines can be used.
See also: "option force-set-var", "option var-prefix". See also: "option force-set-var", "option var-prefix".
timeout hello <timeout> timeout hello <timeout> [DEPRECATED]
Set the maximum time to wait for an agent to receive the AGENT-HELLO frame. Set the maximum time to wait for an agent to receive the AGENT-HELLO frame.
It is applied on the stream that handle the connection with the agent. It is applied on the stream that handle the connection with the agent.
@ -437,8 +441,10 @@ timeout hello <timeout>
This timeout is an applicative timeout. It differ from "timeout connect" This timeout is an applicative timeout. It differ from "timeout connect"
defined on backends. defined on backends.
This parameter is now deprecated and ignored. It will be removed in future
versions.
timeout idle <timeout> timeout idle <timeout> [DEPRECATED]
Set the maximum time to wait for an agent to close an idle connection. It is Set the maximum time to wait for an agent to close an idle connection. It is
applied on the stream that handle the connection with the agent. applied on the stream that handle the connection with the agent.
@ -447,6 +453,8 @@ timeout idle <timeout>
can be in any other unit if the number is suffixed by the unit, can be in any other unit if the number is suffixed by the unit,
as explained at the top of this document. as explained at the top of this document.
This parameter is now deprecated and ignored. It will be removed in future
versions.
timeout processing <timeout> timeout processing <timeout>
Set the maximum time to wait for a stream to process an event, i.e to acquire Set the maximum time to wait for a stream to process an event, i.e to acquire
@ -482,21 +490,19 @@ spoe-message <name>
Arguments : Arguments :
<name> is the name of the SPOE message. <name> is the name of the SPOE message.
Here you define a message that can be referenced in a "spoe-agent" Here a message that can be referenced in a "spoe-agent" section is
section. Following keywords are supported : defined. Following keywords are supported :
- acl - acl
- args - args
- event - event
See also: "spoe-agent" section. See also: "spoe-agent" section.
acl <aclname> <criterion> [flags] [operator] <value> ... acl <aclname> <criterion> [flags] [operator] <value> ...
Declare or complete an access list. Declare or complete an access list.
See section 7 about ACL usage in the HAProxy Configuration Manual. See section 7 about ACL usage in the HAProxy Configuration Manual.
args [name=]<sample> ... args [name=]<sample> ...
Define arguments passed into the SPOE message. Define arguments passed into the SPOE message.
@ -510,7 +516,6 @@ args [name=]<sample> ...
For example: For example:
args frontend=fe_id src dst args frontend=fe_id src dst
event <name> [ { if | unless } <condition> ] event <name> [ { if | unless } <condition> ]
Set the event that triggers sending of the message. It may optionally be Set the event that triggers sending of the message. It may optionally be
followed by an ACL-based condition, in which case it will only be evaluated followed by an ACL-based condition, in which case it will only be evaluated
@ -552,13 +557,12 @@ spoe-group <name>
Arguments : Arguments :
<name> is the name of the SPOE group. <name> is the name of the SPOE group.
Here you define a group of SPOE messages that can be referenced in a Here a group of SPOE messages is defined. It can be referenced in a
"spoe-agent" section. Following keywords are supported : "spoe-agent" section. Following keywords are supported :
- messages - messages
See also: "spoe-agent" and "spoe-message" sections. See also: "spoe-agent" and "spoe-message" sections.
messages <msg-name> ... messages <msg-name> ...
Declare the list of SPOE messages belonging to the group. Declare the list of SPOE messages belonging to the group.
@ -567,7 +571,7 @@ messages <msg-name> ...
Messages declared here must be found in the same engine scope, else an error Messages declared here must be found in the same engine scope, else an error
is triggered during the configuration parsing. Furthermore, a message belongs is triggered during the configuration parsing. Furthermore, a message belongs
at most to a group. You can have many "messages" lines. at most to a group. Several "messages" lines can be defined.
See also: "spoe-message" section. See also: "spoe-message" section.
@ -598,7 +602,7 @@ and 0 a blacklisted IP with no doubt).
server http A.B.C.D:80 server http A.B.C.D:80
backend iprep-servers backend iprep-servers
mode tcp mode spop
balance roundrobin balance roundrobin
timeout connect 5s # greater than hello timeout timeout connect 5s # greater than hello timeout
@ -616,8 +620,6 @@ and 0 a blacklisted IP with no doubt).
option var-prefix iprep option var-prefix iprep
timeout hello 2s
timeout idle 2m
timeout processing 10ms timeout processing 10ms
use-backend iprep-servers use-backend iprep-servers
@ -714,62 +716,37 @@ actions.
+---+---+----------+ +---+---+----------+
FIN: Indicates that this is the final payload fragment. The first fragment FIN: Indicates that this is the final payload fragment. The first fragment
may also be the final fragment. may also be the final fragment. The payload fragmentation was removed
and is now deprecated. It means the FIN flag must be set on all
frames.
ABORT: Indicates that the processing of the current frame must be ABORT: Indicates that the processing of the current frame must be
cancelled. This bit should be set on frames with a fragmented cancelled.
payload. It can be ignore for frames with an unfragemnted
payload. When it is set, the FIN bit must also be set.
Frames cannot exceed a maximum size negotiated between HAProxy and agents Frames cannot exceed a maximum size negotiated between HAProxy and agents
during the HELLO handshake. Most of time, payload will be small enough to send during the HELLO handshake. Most of time, payload will be small enough to send
it in one frame. But when supported by the peer, it will be possible to it in one frame.
fragment huge payload on many frames. This ability is announced during the
HELLO handshake and it can be asynmetric (supported by agents but not by
HAProxy or the opposite). The following rules apply to fragmentation:
* An unfragemnted payload consists of a single frame with the FIN bit set.
* A fragemented payload consists of several frames with the FIN bit clear and
terminated by a single frame with the FIN bit set. All these frames must
share the same STREAM-ID and FRAME-ID. The first frame must set the right
FRAME-TYPE (e.g, NOTIFY). The following frames must have an unset type (0).
Beside the support of fragmented payload by a peer, some payload must not be
fragmented. See below for details.
IMPORTANT : The maximum size supported by peers for a frame must be greater IMPORTANT : The maximum size supported by peers for a frame must be greater
than or equal to 256 bytes. than or equal to 256 bytes. A good common value is the HAProxy
buffer size minus 4 bytes, reserved for the frame length
(tune.bufsize - 4). It is the default value announced by HAproxy.
3.2.1. Frame capabilities 3.2.1. Frame capabilities
-------------------------- --------------------------
Here are the list of official capabilities that HAProxy and agents can support: Here are the list of official capabilities that HAProxy and agents can support:
* fragmentation: This is the ability for a peer to support fragmented
payload in received frames. This is an asymmectical
capability, it only concerns the peer that announces
it. This is the responsibility to the other peer to use it
or not.
* pipelining: This is the ability for a peer to decouple NOTIFY and ACK * pipelining: This is the ability for a peer to decouple NOTIFY and ACK
frames. This is a symmectical capability. To be used, it must frames. This is a symmectical capability. To be used, it must
be supported by HAProxy and agents. Unlike HTTP pipelining, the be supported by HAProxy and agents. Unlike HTTP pipelining, the
ACK frames can be send in any order, but always on the same TCP ACK frames can be send in any order, but always on the same TCP
connection used for the corresponding NOTIFY frame. connection used for the corresponding NOTIFY frame.
* async: This ability is similar to the pipelining, but here any TCP
connection established between HAProxy and the agent can be used to
send ACK frames. if an agent accepts connections from multiple
HAProxy, it can use the "engine-id" value to group TCP
connections. See details about HAPROXY-HELLO frame.
Unsupported or unknown capabilities are silently ignored, when possible. Unsupported or unknown capabilities are silently ignored, when possible.
NOTE: HAProxy does not support the fragmentation for now. This means it is not NOTE: Fragmentation and async capabilities were deprecated and are now ignored.
able to handle fragmented frames. However, if an agent announces the
fragmentation support, HAProxy may choose to send fragemented frames.
3.2.2. Frame types overview 3.2.2. Frame types overview
---------------------------- ----------------------------
@ -778,9 +755,6 @@ Here are types of frame supported by SPOE. Frames sent by HAProxy come first,
then frames sent by agents : then frames sent by agents :
TYPE | ID | DESCRIPTION TYPE | ID | DESCRIPTION
-----------------------------+-----+-------------------------------------
UNSET | 0 | Used for all frames but the first when a
| | payload is fragmented.
-----------------------------+-----+------------------------------------- -----------------------------+-----+-------------------------------------
HAPROXY-HELLO | 1 | Sent by HAProxy when it opens a HAPROXY-HELLO | 1 | Sent by HAProxy when it opens a
| | connection on an agent. | | connection on an agent.
@ -801,7 +775,8 @@ then frames sent by agents :
ACK | 103 | Sent to acknowledge a NOTIFY frame ACK | 103 | Sent to acknowledge a NOTIFY frame
-----------------------------+-----+------------------------------------- -----------------------------+-----+-------------------------------------
Unknown frames may be silently skipped. Unknown frames may be silently skipped or trigger an error, depending on the
implementation.
3.2.3. Workflow 3.2.3. Workflow
---------------- ----------------
@ -865,37 +840,6 @@ Unknown frames may be silently skipped.
| <-------------------------- | | <-------------------------- |
| | | |
* Notify / Ack exchange (fragmented payload):
HAPROXY AGENT SRV
| NOTIFY (frag 1) |
| --------------------------> |
| |
| UNSET (frag 2) |
| --------------------------> |
| ... |
| UNSET (frag N) |
| --------------------------> |
| |
| ACK |
| <-------------------------- |
| |
* Aborted fragmentation of a NOTIFY frame:
HAPROXY AGENT SRV
| ... |
| UNSET (frag X) |
| --------------------------> |
| |
| ACK/ABORT |
| <-------------------------- |
| |
| UNSET (frag X+1) |
| -----------X |
| |
| |
* Connection closed by haproxy: * Connection closed by haproxy:
HAPROXY AGENT SRV HAPROXY AGENT SRV
@ -917,8 +861,8 @@ Unknown frames may be silently skipped.
---------------------------- ----------------------------
This frame is the first one exchanged between HAProxy and an agent, when the This frame is the first one exchanged between HAProxy and an agent, when the
connection is established. The payload of this frame is a KV-LIST. It cannot be connection is established. The payload of this frame is a KV-LIST. STREAM-ID
fragmented. STREAM-ID and FRAME-ID are must be set 0. and FRAME-ID are must be set 0.
Following items are mandatory in the KV-LIST: Following items are mandatory in the KV-LIST:
@ -963,7 +907,7 @@ AGENT-DISCONNECT frame must be returned.
This frame is sent in reply to a HAPROXY-HELLO frame to finish a HELLO This frame is sent in reply to a HAPROXY-HELLO frame to finish a HELLO
handshake. As for HAPROXY-HELLO frame, STREAM-ID and FRAME-ID are also set handshake. As for HAPROXY-HELLO frame, STREAM-ID and FRAME-ID are also set
0. The payload of this frame is a KV-LIST and it cannot be fragmented. 0. The payload of this frame is a KV-LIST.
Following items are mandatory in the KV-LIST: Following items are mandatory in the KV-LIST:
@ -997,8 +941,7 @@ will close the connection at the end of the health check.
Information are sent to the agents inside NOTIFY frames. These frames are Information are sent to the agents inside NOTIFY frames. These frames are
attached to a stream, so STREAM-ID and FRAME-ID must be set. The payload of attached to a stream, so STREAM-ID and FRAME-ID must be set. The payload of
NOTIFY frames is a LIST-OF-MESSAGES and, if supported by agents, it can be NOTIFY frames is a LIST-OF-MESSAGES.
fragmented.
NOTIFY frames must be acknowledge by agents sending an ACK frame, repeating NOTIFY frames must be acknowledge by agents sending an ACK frame, repeating
right STREAM-ID and FRAME-ID. right STREAM-ID and FRAME-ID.
@ -1008,8 +951,7 @@ right STREAM-ID and FRAME-ID.
ACK frames must be sent by agents to reply to NOTIFY frames. STREAM-ID and ACK frames must be sent by agents to reply to NOTIFY frames. STREAM-ID and
FRAME-ID found in a NOTIFY frame must be reuse in the corresponding ACK FRAME-ID found in a NOTIFY frame must be reuse in the corresponding ACK
frame. The payload of ACK frames is a LIST-OF-ACTIONS and, if supported by frame. The payload of ACK frames is a LIST-OF-ACTIONS.
HAProxy, it can be fragmented.
3.2.8. Frame: HAPROXY-DISCONNECT 3.2.8. Frame: HAPROXY-DISCONNECT
--------------------------------- ---------------------------------
@ -1019,8 +961,8 @@ frame is sent with information describing the error. HAProxy will wait an
AGENT-DISCONNECT frame in reply. All other frames will be ignored. The agent AGENT-DISCONNECT frame in reply. All other frames will be ignored. The agent
must then close the socket. must then close the socket.
The payload of this frame is a KV-LIST. It cannot be fragmented. STREAM-ID and The payload of this frame is a KV-LIST. STREAM-ID and FRAME-ID are must be set
FRAME-ID are must be set 0. 0.
Following items are mandatory in the KV-LIST: Following items are mandatory in the KV-LIST:
@ -1042,8 +984,8 @@ is sent, with information describing the error. such frame is also sent in reply
to a HAPROXY-DISCONNECT. The agent must close the socket just after sending to a HAPROXY-DISCONNECT. The agent must close the socket just after sending
this frame. this frame.
The payload of this frame is a KV-LIST. It cannot be fragmented. STREAM-ID and The payload of this frame is a KV-LIST. STREAM-ID and FRAME-ID are must be set
FRAME-ID are must be set 0. 0.
Following items are mandatory in the KV-LIST: Following items are mandatory in the KV-LIST:
@ -1060,10 +1002,10 @@ For more information about known errors, see section "Errors & timeouts"
3.3. Events & Messages 3.3. Events & Messages
----------------------- -----------------------
Information about streams are sent in NOTIFY frames. You can specify which kind Information about streams are sent in NOTIFY frames. It is possible to specify
of information to send by defining "spoe-message" sections in your SPOE which kind of information to send by defining "spoe-message" sections in the
configuration file. for each "spoe-message" there will be a message in a NOTIFY SPOE configuration file. for each "spoe-message" there will be a message in a
frame when the right event is triggered. NOTIFY frame when the right event is triggered.
A NOTIFY frame is sent for an specific event when there is at least one A NOTIFY frame is sent for an specific event when there is at least one
"spoe-message" attached to this event. All messages for an event will be added "spoe-message" attached to this event. All messages for an event will be added
@ -1185,21 +1127,15 @@ An agent can define its own errors using a not yet assigned status code.
IMPORTANT NOTE: By default, for a specific stream, when an abnormal/unexpected IMPORTANT NOTE: By default, for a specific stream, when an abnormal/unexpected
error occurs, the SPOE is disabled for all the transaction. So error occurs, the SPOE is disabled for all the transaction. So
if you have several events configured, such error on an event if several events are configured, such error on an event will
will disabled all following. For TCP streams, this will disabled all following. For TCP streams, this will disable the
disable the SPOE for the whole session. For HTTP streams, this SPOE for the whole session. For HTTP streams, this will disable
will disable it for the transaction (request and response). it for the transaction (request and response). See 'option
See 'option continue-on-error' to bypass this limitation. continue-on-error' to bypass this limitation.
To avoid a stream to wait undefinetly, you must carefully choose the To avoid a stream to wait undefinetly, A processing timeout should be carefully
acknowledgement timeout. In most of cases, it will be quiet low. But it depends defined. Most of time, it will be quiet low. But it depends on the SPOA
on the responsivness of your service. responsivness.
You must also choose idle timeout carefully. Because connection with your
service depends on the backend configuration used by the SPOA, it is important
to use a lower value for idle timeout than the server timeout. Else the
connection will be closed by HAProxy. The same is true for hello timeout. You
should choose a lower value than the connect timeout.
4. Logging 4. Logging
----------- -----------
@ -1214,40 +1150,19 @@ LOG_NOTICE. Otherwise, the message is logged with the level LOG_WARNING.
The messages are logged using the agent's logger, if defined, and use the The messages are logged using the agent's logger, if defined, and use the
following format: following format:
SPOE: [AGENT] <TYPE:NAME> sid=STREAM-ID st=STATUS-CODE reqT/qT/wT/resT/pT \ SPOE: [AGENT] <TYPE:NAME> sid=STREAM-ID st=STATUS-CODE pT <nb_error>/<nb_processed>
<idles>/<applets> <nb_sending>/<nb_waiting> <nb_error>/<nb_processed>
AGENT is the agent name AGENT is the agent name
TYPE is EVENT of GROUP TYPE is EVENT of GROUP
NAME is the event or the group name NAME is the event or the group name
STREAM-ID is an integer, the unique id of the stream STREAM-ID is an integer, the unique id of the stream
STATUS_CODE is the processing's status code STATUS_CODE is the processing's status code
reqT/qT/wT/resT/pT are the following time events: pT is the delay to process the event or the group.
From the stream point of view, it is the latency added
* reqT : the encoding time. It includes ACLs processing, if any. For by the SPOE processing.
fragmented frames, it is the sum of all fragments.
* qT : the delay before the request gets out the sending queue. For
fragmented frames, it is the sum of all fragments.
* wT : the delay before the response is received. No fragmentation
supported here.
* resT : the delay to process the response. No fragmentation supported
here.
* pT : the delay to process the event or the group. From the stream
point of view, it is the latency added by the SPOE processing.
It is more or less the sum of values above.
<idle> is the numbers of idle SPOE applets
<applets> is the numbers of SPOE applets
<nb_sending> is the numbers of streams waiting to send data
<nb_waiting> is the numbers of streams waiting for a ack
<nb_error> is the numbers of processing errors <nb_error> is the numbers of processing errors
<nb_processed> is the numbers of events/groups processed <nb_processed> is the numbers of events/groups processed
For all these time events, -1 means the processing was interrupted before the
end. So -1 for the queue time means the request was never dequeued. For
fragmented frames it is harder to know when the interruption happened.
/* /*
* Local variables: * Local variables:
* fill-column: 79 * fill-column: 79