blob: 2ed7878bebb53c1f6f9560229384cfba2a87a0a8 [file] [log] [blame]
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001 -----------------------------------------------
2 Stream Processing Offload Engine (SPOE)
Christopher Faulet57583e42017-09-04 15:41:09 +02003 Version 1.2
Christopher Faulet3b788092020-05-13 08:25:12 +02004 ( Last update: 2020-06-13 )
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02005 -----------------------------------------------
6 Author : Christopher Faulet
7 Contact : cfaulet at haproxy dot com
8
9
10SUMMARY
11--------
12
13 0. Terms
14 1. Introduction
15 2. SPOE configuration
16 2.1. SPOE scope
17 2.2. "spoe-agent" section
18 2.3. "spoe-message" section
Christopher Faulet11610f32017-09-21 10:23:10 +020019 2.4. "spoe-group" section
20 2.5. Example
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020021 3. SPOP specification
22 3.1. Data types
23 3.2. Frames
24 3.2.1. Frame capabilities
25 3.2.2. Frame types overview
26 3.2.3. Workflow
27 3.2.4. Frame: HAPROXY-HELLO
28 3.2.5. Frame: AGENT-HELLO
29 3.2.6. Frame: NOTIFY
30 3.2.7. Frame: ACK
31 3.2.8. Frame: HAPROXY-DISCONNECT
32 3.2.9. Frame: AGENT-DISCONNECT
33 3.3. Events & messages
34 3.4. Actions
Christopher Fauletd1307ce2017-02-27 21:59:39 +010035 3.5. Errors & timeouts
Christopher Fauletb2dd1e02018-03-22 09:07:41 +010036 4. Logging
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020037
38
390. Terms
40---------
41
42* SPOE : Stream Processing Offload Engine.
43
Ilya Shipitsin11057a32020-06-21 21:18:27 +050044 A SPOE is a filter talking to servers managed by a SPOA to offload the
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020045 stream processing. An engine is attached to a proxy. A proxy can have
Christopher Fauletd1307ce2017-02-27 21:59:39 +010046 several engines. Each engine is linked to an agent and only one.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020047
48* SPOA : Stream Processing Offload Agent.
49
50 A SPOA is a service that will receive info from a SPOE to offload the
51 stream processing. An agent manages several servers. It uses a backend to
52 reference all of them. By extension, these servers can also be called
53 agents.
54
55* SPOP : Stream Processing Offload Protocol, used by SPOEs to talk to SPOA
56 servers.
57
58 This protocol is used by engines to talk to agents. It is an in-house
59 binary protocol described in this documentation.
60
61
621. Introduction
63----------------
64
65SPOE is a feature introduced in HAProxy 1.7. It makes possible the
66communication with external components to retrieve some info. The idea started
67with the problems caused by most ldap libs not working fine in event-driven
68systems (often at least the connect() is blocking). So, it is hard to properly
69implement Single Sign On solution (SSO) in HAProxy. The SPOE will ease this
70kind of processing, or we hope so.
71
72Now, the aim of SPOE is to allow any kind of offloading on the streams. First
Christopher Faulet3b788092020-05-13 08:25:12 +020073releases won't do lot of things. As we will see, there are few handled events
74and even less actions supported. Actually, for now, the SPOE can offload the
75processing before "tcp-request content", "tcp-response content", "http-request"
76and "http-response" rules. And it only supports variables definition. But, in
77spite of these limited features, we can easily imagine to implement SSO
78solution, ip reputation or ip geolocation services.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020079
Willy Tarreau86951992021-04-21 09:39:06 +020080Some example implementations in various languages are linked to from the
81HAProxy Wiki page dedicated to this mechanism:
82
83 https://github.com/haproxy/wiki/wiki/SPOE:-Stream-Processing-Offloading-Engine
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +020084
852. SPOE configuration
86----------------------
87
88Because SPOE is implemented as a filter, To use it, you must declare a "filter
89spoe" line in a proxy section (frontend/backend/listen) :
90
91 frontend my-front
92 ...
93 filter spoe [engine <name>] config <file>
94 ...
95
96The "config" parameter is mandatory. It specififies the SPOE configuration
97file. The engine name is optional. It can be set to declare the scope to use in
98the SPOE configuration. So it is possible to use the same SPOE configuration
99for several engines. If no name is provided, the SPOE configuration must not
100contain any scope directive.
101
102We use a separate configuration file on purpose. By commenting SPOE filter
Michael Prokop4438c602019-05-24 10:25:45 +0200103line, you completely disable the feature, including the parsing of sections
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200104reserved to SPOE. This is also a way to keep the HAProxy configuration clean.
105
106A SPOE configuration file must contains, at least, the SPOA configuration
Christopher Faulet11610f32017-09-21 10:23:10 +0200107("spoe-agent" section) and SPOE messages/groups ("spoe-message" or "spoe-group"
108sections) attached to this agent.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200109
110IMPORTANT : The configuration of a SPOE filter must be located in a dedicated
111file. But the backend used by a SPOA must be declared in HAProxy configuration
112file.
113
1142.1. SPOE scope
115-------------------------
116
117If you specify an engine name on the SPOE filter line, then you need to define
118scope in the SPOE configuration with the same name. You can have several SPOE
119scope in the same file. In each scope, you must define one and only one
120"spoe-agent" section to configure the SPOA linked to your SPOE and several
Ilya Shipitsin2a950d02020-03-06 13:07:38 +0500121"spoe-message" and "spoe-group" sections to describe, respectively, messages and
Christopher Faulet11610f32017-09-21 10:23:10 +0200122group of messages sent to servers mananged by your SPOA.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200123
124A SPOE scope starts with this kind of line :
125
126 [<name>]
127
128where <name> is the same engine name specified on the SPOE filter line. The
129scope ends when the file ends or when another scope is found.
130
131 Example :
132 [my-first-engine]
133 spoe-agent my-agent
134 ...
135 spoe-message msg1
136 ...
137 spoe-message msg2
138 ...
Christopher Fauletb2dd1e02018-03-22 09:07:41 +0100139 spoe-group grp1
Christopher Faulet11610f32017-09-21 10:23:10 +0200140 ...
Christopher Fauletb2dd1e02018-03-22 09:07:41 +0100141 spoe-group grp2
142 ...
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200143
144 [my-second-engine]
145 ...
146
147If no engine name is provided on the SPOE filter line, no SPOE scope must be
148found in the SPOE configuration file. All the file is considered to be in the
149same anonymous and implicit scope.
150
Christopher Faulet7ee86672017-09-19 11:08:28 +0200151The engine name must be uniq for a proxy. If no engine name is provided on the
Joseph Herlant71b4b152018-11-13 16:55:16 -0800152SPOE filter line, the SPOE agent name is used by default.
Christopher Faulet7ee86672017-09-19 11:08:28 +0200153
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001542.2. "spoe-agent" section
155--------------------------
156
157For each engine, you must define one and only one "spoe-agent" section. In this
158section, you will declare SPOE messages and the backend you will use. You will
159also set timeouts and options to customize your agent's behaviour.
160
161
162spoe-agent <name>
163 Create a new SPOA with the name <name>. It must have one and only one
164 "spoe-agent" definition by SPOE scope.
165
166 Arguments :
167 <name> is the name of the agent section.
168
169 following keywords are supported :
Christopher Faulet11610f32017-09-21 10:23:10 +0200170 - groups
Christopher Faulet7250b8f2018-03-26 17:19:01 +0200171 - log
Christopher Faulet48026722016-11-16 15:01:12 +0100172 - maxconnrate
173 - maxerrrate
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100174 - max-frame-size
Christopher Faulete8ade382018-01-25 15:32:22 +0100175 - max-waiting-frames
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200176 - messages
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100177 - [no] option async
Christopher Faulet0e0f0852018-03-26 17:20:36 +0200178 - [no] option dontlog-normal
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100179 - [no] option pipelining
180 - [no] option send-frag-payload
Christopher Fauletea62c2a2016-11-14 10:54:21 +0100181 - option continue-on-error
Christopher Faulet336d3ef2017-12-22 10:00:55 +0100182 - option force-set-var
Christopher Faulet985532d2016-11-16 15:36:19 +0100183 - option set-on-error
Christopher Faulet36bda1c2018-03-22 09:08:20 +0100184 - option set-process-time
185 - option set-total-time
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200186 - option var-prefix
Christopher Faulet336d3ef2017-12-22 10:00:55 +0100187 - register-var-names
Christopher Faulet03a34492016-11-19 16:47:56 +0100188 - timeout hello|idle|processing
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200189 - use-backend
190
191
Christopher Faulet11610f32017-09-21 10:23:10 +0200192groups <grp-name> ...
193 Declare the list of SPOE groups that an agent will handle.
194
195 Arguments :
196 <grp-name> is the name of a SPOE group.
197
Joseph Herlant71b4b152018-11-13 16:55:16 -0800198 Groups declared here must be found in the same engine scope, else an error is
Christopher Faulet11610f32017-09-21 10:23:10 +0200199 triggered during the configuration parsing. You can have many "groups" lines.
200
201 See also: "spoe-group" section.
202
203
Christopher Faulet7250b8f2018-03-26 17:19:01 +0200204log global
205log <address> [len <length>] [format <format>] <facility> [<level> [<minlevel>]]
206no log
207 Enable per-instance logging of events and traffic.
208
209 Prefix :
210 no should be used when the logger list must be flushed.
211
212 See the HAProxy Configuration Manual for details about this option.
213
Christopher Faulet48026722016-11-16 15:01:12 +0100214maxconnrate <number>
215 Set the maximum number of connections per second to <number>. The SPOE will
216 stop to open new connections if the maximum is reached and will wait to
217 acquire an existing one. So it is important to set "timeout hello" to a
218 relatively small value.
219
220
221maxerrrate <number>
222 Set the maximum number of errors per second to <number>. The SPOE will stop
223 its processing if the maximum is reached.
224
225
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100226max-frame-size <number>
227 Set the maximum allowed size for frames exchanged between HAProxy and SPOA.
228 It must be in the range [256, tune.bufsize-4] (4 bytes are reserved for the
229 frame length). By default, it is set to (tune.bufsize-4).
230
Christopher Faulete8ade382018-01-25 15:32:22 +0100231max-waiting-frames <number>
232 Set the maximum number of frames waiting for an acknowledgement on the same
233 connection. This value is only used when the pipelinied or asynchronus
234 exchanges between HAProxy and SPOA are enabled. By default, it is set to 20.
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100235
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200236messages <msg-name> ...
237 Declare the list of SPOE messages that an agent will handle.
238
239 Arguments :
240 <msg-name> is the name of a SPOE message.
241
242 Messages declared here must be found in the same engine scope, else an error
243 is triggered during the configuration parsing. You can have many "messages"
244 lines.
245
246 See also: "spoe-message" section.
247
248
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100249option async
250no option async
251 Enable or disable the support of asynchronus exchanges between HAProxy and
252 SPOA. By default, this option is enabled.
253
254
Christopher Fauletea62c2a2016-11-14 10:54:21 +0100255option continue-on-error
256 Do not stop the events processing when an error occurred on a stream.
257
258 By default, for a specific stream, when an abnormal/unexpected error occurs,
259 the SPOE is disabled for all the transaction. So if you have several events
Ilya Shipitsin11057a32020-06-21 21:18:27 +0500260 configured, such error on an event will disabled all following. For TCP
Christopher Fauletea62c2a2016-11-14 10:54:21 +0100261 streams, this will disable the SPOE for the whole session. For HTTP streams,
262 this will disable it for the transaction (request and response).
263
264 When set, this option bypass this behaviour and only the current event will
265 be ignored.
266
Christopher Faulet0e0f0852018-03-26 17:20:36 +0200267
268option dontlog-normal
269no option dontlog-normal
270 Enable or disable logging of normal, successful processing.
271
272 Arguments : none
273
274 See also: "log" and section 4 about logging.
275
276
Etienne Carriereaec89892017-12-14 09:36:40 +0000277option force-set-var
278 By default, SPOE filter only register already known variables (mainly from
279 parsing of the configuration). If you want that haproxy trusts the agent and
280 registers all variables (ex: can be useful for LUA workload), activate this
281 option.
282
283 Caution : this option opens to a variety of attacks such as a rogue SPOA that
284 asks to register too many variables.
285
Christopher Fauletea62c2a2016-11-14 10:54:21 +0100286
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100287option pipelining
288no option pipelining
289 Enable or disable the support of pipelined exchanges between HAProxy and
290 SPOA. By default, this option is enabled.
291
292
293option send-frag-payload
294no option send-frag-payload
295 Enable or disable the sending of fragmented payload to SPOA. By default, this
296 option is enabled.
297
298
Christopher Faulet985532d2016-11-16 15:36:19 +0100299option set-on-error <var name>
300 Define the variable to set when an error occurred during an event processing.
301
302 Arguments :
303
304 <var name> is the variable name, without the scope. The name may only
305 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
306
307 This variable will only be set when an error occurred in the scope of the
308 transaction. As for all other variables define by the SPOE, it will be
309 prefixed. So, if your variable name is "error" and your prefix is
310 "my_spoe_pfx", the variable will be "txn.my_spoe_pfx.error".
311
Christopher Fauletb067b062017-01-04 16:39:11 +0100312 When set, the variable is an integer representing the error reason. For values
313 under 256, it represents an error coming from the engine. Below 256, it
314 reports a SPOP error. In this case, to retrieve the right SPOP status code,
315 you must remove 256 to this value. Here are possible values:
316
317 * 1 a timeout occurred during the event processing.
318
Michael Prokop4438c602019-05-24 10:25:45 +0200319 * 2 an error was triggered during the resources allocation.
Christopher Fauletb067b062017-01-04 16:39:11 +0100320
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100321 * 3 the frame payload exceeds the frame size and it cannot be
322 fragmented.
323
324 * 4 the fragmentation of a payload is aborted.
325
Christopher Faulet344c4ab2017-09-22 10:20:13 +0200326 * 5 The frame processing has been interrupted by HAProxy.
327
Christopher Fauletb067b062017-01-04 16:39:11 +0100328 * 255 an unknown error occurred during the event processing.
329
330 * 256+N a SPOP error occurred during the event processing (see section
331 "Errors & timeouts").
332
333 Note that if "option continue-on-error" is set, the variable is not
334 automatically removed between events processing.
Christopher Faulet985532d2016-11-16 15:36:19 +0100335
336 See also: "option continue-on-error", "option var-prefix".
337
Christopher Faulet36bda1c2018-03-22 09:08:20 +0100338
339option set-process-time <var name>
340 Define the variable to set to report the processing time of the last event or
341 group.
342
343 Arguments :
344
345 <var name> is the variable name, without the scope. The name may only
346 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
347
348 This variable will be set in the scope of the transaction. As for all other
349 variables define by the SPOE, it will be prefixed. So, if your variable name
350 is "process_time" and your prefix is "my_spoe_pfx", the variable will be
351 "txn.my_spoe_pfx.process_time".
352
353 When set, the variable is an integer representing the delay to process the
354 event or the group, in milliseconds. From the stream point of view, it is the
355 latency added by the SPOE processing for the last handled event or group.
356
357 If several events or groups are processed for the same stream, this value
358 will be overrideen.
359
360 See also: "option set-total-time".
361
362
363option set-total-time <var name>
364 Define the variable to set to report the total processing time SPOE for a
365 stream.
366
367 Arguments :
368
369 <var name> is the variable name, without the scope. The name may only
370 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
371
372 This variable will be set in the scope of the transaction. As for all other
373 variables define by the SPOE, it will be prefixed. So, if your variable name
374 is "total_time" and your prefix is "my_spoe_pfx", the variable will be
375 "txn.my_spoe_pfx.total_time".
376
377 When set, the variable is an integer representing the sum of processing times
378 for a stream, in milliseconds. From the stream point of view, it is the
379 latency added by the SPOE processing.
380
381 If several events or groups are processed for the same stream, this value
382 will be updated.
383
384 See also: "option set-process-time".
385
386
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200387option var-prefix <prefix>
388 Define the prefix used when variables are set by an agent.
389
390 Arguments :
391
392 <prefix> is the prefix used to limit the scope of variables set by an
393 agent.
394
395 To avoid conflict with other variables defined by HAProxy, all variables
396 names will be prefixed. By default, the "spoe-agent" name is used. This
397 option can be used to customize it.
398
399 The prefix will be added between the variable scope and its name, separated
400 by a '.'. It may only contain characters 'a-z', 'A-Z', '0-9', '.' and '_', as
401 for variables name. In HAProxy configuration, you need to use this prefix as
402 a part of the variables name. For example, if an agent define the variable
403 "myvar" in the "txn" scope, with the prefix "my_spoe_pfx", then you should
404 use "txn.my_spoe_pfx.myvar" name in your HAProxy configuration.
405
Etienne Carriereaec89892017-12-14 09:36:40 +0000406 By default, an agent will never set new variables at runtime: It can only set
407 new value for existing ones. If you want a different behaviour, see
Christopher Faulet336d3ef2017-12-22 10:00:55 +0100408 force-set-var option and register-var-names directive.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200409
Christopher Faulet336d3ef2017-12-22 10:00:55 +0100410register-var-names <var name> ...
411 Register some variable names. By default, an agent will not be allowed to set
412 new variables at runtime. This rule can be totally relaxed by setting the
413 option "force-set-var". If you know all the variables you will need, this
414 directive is a good way to register them without letting an agent doing what
415 it want. This is only required if these variables are not referenced anywhere
416 in the HAProxy configuration or the SPOE one.
417
418 Arguments:
419 <var name> is a variable name without the scope. The name may only
420 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
421
422 The prefix will be automatically added during the registration. You can have
423 many "register-var-names" lines.
424
425 See also: "option force-set-var", "option var-prefix".
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200426
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200427timeout hello <timeout>
428 Set the maximum time to wait for an agent to receive the AGENT-HELLO frame.
Christopher Fauletf7a30922016-11-10 15:04:51 +0100429 It is applied on the stream that handle the connection with the agent.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200430
431 Arguments :
432 <timeout> is the timeout value specified in milliseconds by default, but
433 can be in any other unit if the number is suffixed by the unit,
434 as explained at the top of this document.
435
436 This timeout is an applicative timeout. It differ from "timeout connect"
437 defined on backends.
438
439
440timeout idle <timeout>
Christopher Fauletf7a30922016-11-10 15:04:51 +0100441 Set the maximum time to wait for an agent to close an idle connection. It is
442 applied on the stream that handle the connection with the agent.
443
444 Arguments :
445 <timeout> is the timeout value specified in milliseconds by default, but
446 can be in any other unit if the number is suffixed by the unit,
447 as explained at the top of this document.
448
449
450timeout processing <timeout>
451 Set the maximum time to wait for a stream to process an event, i.e to acquire
452 a stream to talk with an agent, to encode all messages, to send the NOTIFY
453 frame, to receive the corrsponding acknowledgement and to process all
454 actions. It is applied on the stream that handle the client and the server
455 sessions.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200456
457 Arguments :
458 <timeout> is the timeout value specified in milliseconds by default, but
459 can be in any other unit if the number is suffixed by the unit,
460 as explained at the top of this document.
461
462
463use-backend <backend>
464 Specify the backend to use. It must be defined.
465
466 Arguments :
467 <backend> is the name of a valid "backend" section.
468
469
4702.3. "spoe-message" section
471----------------------------
472
473To offload the stream processing, SPOE will send messages with specific
474information at a specific moment in the stream life and will wait for
475corresponding replies to know what to do.
476
477
478spoe-message <name>
479 Create a new SPOE message with the name <name>.
480
481 Arguments :
482 <name> is the name of the SPOE message.
483
484 Here you define a message that can be referenced in a "spoe-agent"
485 section. Following keywords are supported :
Christopher Faulet57583e42017-09-04 15:41:09 +0200486 - acl
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200487 - args
488 - event
489
490 See also: "spoe-agent" section.
491
492
Christopher Faulet57583e42017-09-04 15:41:09 +0200493acl <aclname> <criterion> [flags] [operator] <value> ...
Christopher Faulet57583e42017-09-04 15:41:09 +0200494 Declare or complete an access list.
495
496 See section 7 about ACL usage in the HAProxy Configuration Manual.
497
498
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200499args [name=]<sample> ...
500 Define arguments passed into the SPOE message.
501
502 Arguments :
503 <sample> is a sample expression.
504
505 When the message is processed, if a sample expression is not available, it is
506 set to NULL. Arguments are processed in their declaration order and added in
Joseph Herlant71b4b152018-11-13 16:55:16 -0800507 the message in that order. It is possible to declare named arguments.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200508
509 For example:
510 args frontend=fe_id src dst
511
512
Christopher Faulet57583e42017-09-04 15:41:09 +0200513event <name> [ { if | unless } <condition> ]
514 Set the event that triggers sending of the message. It may optionally be
515 followed by an ACL-based condition, in which case it will only be evaluated
516 if the condition is true.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200517
Christopher Faulet57583e42017-09-04 15:41:09 +0200518 ACL-based conditions are executed in the context of the stream that handle
519 the client and the server connections.
520
521 Arguments :
522 <name> is the event name.
523 <condition> is a standard ACL-based condition.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200524
525 Supported events are:
526 - on-client-session
Christopher Faulet1002aac2016-12-09 17:41:54 +0100527 - on-server-session
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200528 - on-frontend-tcp-request
529 - on-backend-tcp-request
530 - on-tcp-response
531 - on-frontend-http-request
532 - on-backend-http-request
533 - on-http-response
534
Christopher Faulet57583e42017-09-04 15:41:09 +0200535 See section "Events & Messages" for more details about supported events.
536 See section 7 about ACL usage in the HAProxy Configuration Manual.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200537
Christopher Faulet11610f32017-09-21 10:23:10 +02005382.4. "spoe-group" section
539--------------------------
540
541This section can be used to declare a group of SPOE messages. Unlike messages
542referenced in a "spoe-agent" section, messages inside a group are not sent on a
543specific event. The sending must be triggered by TCP or HTTP rules, from the
544HAProxy configuration.
545
546
547spoe-group <name>
548 Create a new SPOE group with the name <name>.
549
550 Arguments :
551 <name> is the name of the SPOE group.
552
553 Here you define a group of SPOE messages that can be referenced in a
554 "spoe-agent" section. Following keywords are supported :
555 - messages
556
557 See also: "spoe-agent" and "spoe-message" sections.
558
559
560messages <msg-name> ...
561 Declare the list of SPOE messages belonging to the group.
562
563 Arguments :
564 <msg-name> is the name of a SPOE message.
565
566 Messages declared here must be found in the same engine scope, else an error
567 is triggered during the configuration parsing. Furthermore, a message belongs
568 at most to a group. You can have many "messages" lines.
569
570 See also: "spoe-message" section.
571
572
5732.5. Example
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200574-------------
575
576Here is a simple but complete example that sends client-ip address to a ip
577reputation service. This service can set the variable "ip_score" which is an
578integer between 0 and 100, indicating its reputation (100 means totally safe
579and 0 a blacklisted IP with no doubt).
580
581 ###
582 ### HAProxy configuration
583 frontend www
584 mode http
585 bind *:80
586
587 filter spoe engine ip-reputation config spoe-ip-reputation.conf
588
589 # Reject connection if the IP reputation is under 20
590 tcp-request content reject if { var(sess.iprep.ip_score) -m int lt 20 }
591
592 default_backend http-servers
593
594 backend http-servers
595 mode http
596 server http A.B.C.D:80
597
598 backend iprep-servers
599 mode tcp
600 balance roundrobin
601
602 timeout connect 5s # greater than hello timeout
603 timeout server 3m # greater than idle timeout
604
605 server iprep1 A1.B1.C1.D1:12345
606 server iprep2 A2.B2.C2.D2:12345
607
608 ####
609 ### spoe-ip-reputation.conf
610 [ip-reputation]
611
612 spoe-agent iprep-agent
613 messages get-ip-reputation
614
615 option var-prefix iprep
616
Christopher Faulet03a34492016-11-19 16:47:56 +0100617 timeout hello 2s
618 timeout idle 2m
619 timeout processing 10ms
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200620
621 use-backend iprep-servers
622
623 spoe-message get-ip-reputation
624 args ip=src
Christopher Faulet57583e42017-09-04 15:41:09 +0200625 event on-client-session if ! { src -f /etc/haproxy/whitelist.lst }
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200626
627
6283. SPOP specification
629----------------------
630
6313.1. Data types
632----------------
633
634Here is the bytewise representation of typed data:
635
636 TYPED-DATA : <TYPE:4 bits><FLAGS:4 bits><DATA>
637
638Supported types and their representation are:
639
640 TYPE | ID | DESCRIPTION
641 -----------------------------+-----+----------------------------------
642 NULL | 0 | NULL : <0>
643 Boolean | 1 | BOOL : <1+FLAG>
644 32bits signed integer | 2 | INT32 : <2><VALUE:varint>
645 32bits unsigned integer | 3 | UINT32 : <3><VALUE:varint>
646 64bits signed integer | 4 | INT64 : <4><VALUE:varint>
647 32bits unsigned integer | 5 | UNIT64 : <5><VALUE:varint>
648 IPV4 | 6 | IPV4 : <6><STRUCT IN_ADDR:4 bytes>
649 IPV6 | 7 | IPV6 : <7><STRUCT IN_ADDR6:16 bytes>
650 String | 8 | STRING : <8><LENGTH:varint><BYTES>
651 Binary | 9 | BINARY : <9><LENGTH:varint><BYTES>
652 10 -> 15 unused/reserved | - | -
653 -----------------------------+-----+----------------------------------
654
655Variable-length integer (varint) are encoded using Peers encoding:
656
657
658 0 <= X < 240 : 1 byte (7.875 bits) [ XXXX XXXX ]
659 240 <= X < 2288 : 2 bytes (11 bits) [ 1111 XXXX ] [ 0XXX XXXX ]
660 2288 <= X < 264432 : 3 bytes (18 bits) [ 1111 XXXX ] [ 1XXX XXXX ] [ 0XXX XXXX ]
661 264432 <= X < 33818864 : 4 bytes (25 bits) [ 1111 XXXX ] [ 1XXX XXXX ]*2 [ 0XXX XXXX ]
662 33818864 <= X < 4328786160 : 5 bytes (32 bits) [ 1111 XXXX ] [ 1XXX XXXX ]*3 [ 0XXX XXXX ]
663 ...
664
665For booleans, the value (true or false) is the first bit in the FLAGS
666bitfield. if this bit is set to 0, then the boolean is evaluated as false,
667otherwise, the boolean is evaluated as true.
668
6693.2. Frames
670------------
671
672Exchange between HAProxy and agents are made using FRAME packets. All frames
673must be prefixed with their size encoded on 4 bytes in network byte order:
674
675 <FRAME-LENGTH:4 bytes> <FRAME>
676
677A frame always starts with its type, on one byte, followed by metadata
678containing flags, on 4 bytes and a two variable-length integer representing the
679stream identifier and the frame identifier inside the stream:
680
681 FRAME : <FRAME-TYPE:1 byte> <METADATA> <FRAME-PAYLOAD>
682 METADATA : <FLAGS:4 bytes> <STREAM-ID:varint> <FRAME-ID:varint>
683
684Then comes the frame payload. Depending on the frame type, the payload can be
685of three types: a simple key/value list, a list of messages or a list of
686actions.
687
688 FRAME-PAYLOAD : <LIST-OF-MESSAGES> | <LIST-OF-ACTIONS> | <KV-LIST>
689
690 LIST-OF-MESSAGES : [ <MESSAGE-NAME> <NB-ARGS:1 byte> <KV-LIST> ... ]
691 MESSAGE-NAME : <STRING>
692
693 LIST-OF-ACTIONS : [ <ACTION-TYPE:1 byte> <NB-ARGS:1 byte> <ACTION-ARGS> ... ]
694 ACTION-ARGS : [ <TYPED-DATA>... ]
695
696 KV-LIST : [ <KV-NAME> <KV-VALUE> ... ]
697 KV-NAME : <STRING>
698 KV-VALUE : <TYPED-DATA>
699
Thierry FOURNIERc4dcaff2018-05-18 12:25:39 +0200700 FLAGS :
701
702 Flags are a 32 bits field. They are encoded on 4 bytes in network byte
703 order, where the bit 0 is the LSB.
704
705 0 1 2-31
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100706 +---+---+----------+
707 | | A | |
708 | F | B | |
709 | I | O | RESERVED |
710 | N | R | |
711 | | T | |
712 +---+---+----------+
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200713
714 FIN: Indicates that this is the final payload fragment. The first fragment
715 may also be the final fragment.
716
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100717 ABORT: Indicates that the processing of the current frame must be
718 cancelled. This bit should be set on frames with a fragmented
719 payload. It can be ignore for frames with an unfragemnted
720 payload. When it is set, the FIN bit must also be set.
721
722
Joseph Herlant71b4b152018-11-13 16:55:16 -0800723Frames cannot exceed a maximum size negotiated between HAProxy and agents
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200724during the HELLO handshake. Most of time, payload will be small enough to send
725it in one frame. But when supported by the peer, it will be possible to
726fragment huge payload on many frames. This ability is announced during the
727HELLO handshake and it can be asynmetric (supported by agents but not by
728HAProxy or the opposite). The following rules apply to fragmentation:
729
730 * An unfragemnted payload consists of a single frame with the FIN bit set.
731
732 * A fragemented payload consists of several frames with the FIN bit clear and
733 terminated by a single frame with the FIN bit set. All these frames must
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100734 share the same STREAM-ID and FRAME-ID. The first frame must set the right
735 FRAME-TYPE (e.g, NOTIFY). The following frames must have an unset type (0).
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200736
737Beside the support of fragmented payload by a peer, some payload must not be
738fragmented. See below for details.
739
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100740IMPORTANT : The maximum size supported by peers for a frame must be greater
741than or equal to 256 bytes.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200742
7433.2.1. Frame capabilities
744--------------------------
745
746Here are the list of official capabilities that HAProxy and agents can support:
747
Christopher Fauleta1cda022016-12-21 08:58:06 +0100748 * fragmentation: This is the ability for a peer to support fragmented
749 payload in received frames. This is an asymmectical
750 capability, it only concerns the peer that announces
751 it. This is the responsibility to the other peer to use it
752 or not.
753
754 * pipelining: This is the ability for a peer to decouple NOTIFY and ACK
755 frames. This is a symmectical capability. To be used, it must
756 be supported by HAproxy and agents. Unlike HTTP pipelining, the
757 ACK frames can be send in any order, but always on the same TCP
758 connection used for the corresponding NOTIFY frame.
759
760 * async: This ability is similar to the pipelining, but here any TCP
761 connection established between HAProxy and the agent can be used to
762 send ACK frames. if an agent accepts connections from multiple
763 HAProxy, it can use the "engine-id" value to group TCP
764 connections. See details about HAPROXY-HELLO frame.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200765
766Unsupported or unknown capabilities are silently ignored, when possible.
767
Christopher Faulet9536ad72021-03-02 10:05:03 +0100768NOTE: HAProxy does not support the fragmentation for now. This means it is not
769 able to handle fragmented frames. However, if an agent announces the
770 fragmentation support, HAProxy may choose to send fragemented frames.
771
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02007723.2.2. Frame types overview
773----------------------------
774
775Here are types of frame supported by SPOE. Frames sent by HAProxy come first,
776then frames sent by agents :
777
778 TYPE | ID | DESCRIPTION
779 -----------------------------+-----+-------------------------------------
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100780 UNSET | 0 | Used for all frames but the first when a
781 | | payload is fragmented.
782 -----------------------------+-----+-------------------------------------
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200783 HAPROXY-HELLO | 1 | Sent by HAProxy when it opens a
784 | | connection on an agent.
785 | |
786 HAPROXY-DISCONNECT | 2 | Sent by HAProxy when it want to close
787 | | the connection or in reply to an
788 | | AGENT-DISCONNECT frame
789 | |
790 NOTIFY | 3 | Sent by HAProxy to pass information
791 | | to an agent
792 -----------------------------+-----+-------------------------------------
793 AGENT-HELLO | 101 | Reply to a HAPROXY-HELLO frame, when
794 | | the connection is established
795 | |
796 AGENT-DISCONNECT | 102 | Sent by an agent just before closing
797 | | the connection
798 | |
799 ACK | 103 | Sent to acknowledge a NOTIFY frame
800 -----------------------------+-----+-------------------------------------
801
802Unknown frames may be silently skipped.
803
8043.2.3. Workflow
805----------------
806
807 * Successful HELLO handshake:
808
809 HAPROXY AGENT SRV
810 | HAPROXY-HELLO |
Christopher Fauletba7bc162016-11-07 21:07:38 +0100811 | (healthcheck: false) |
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200812 | --------------------------> |
813 | |
814 | AGENT-HELLO |
815 | <-------------------------- |
816 | |
817
Christopher Fauletba7bc162016-11-07 21:07:38 +0100818 * Successful HELLO healthcheck:
819
820 HAPROXY AGENT SRV
821 | HAPROXY-HELLO |
822 | (healthcheck: true) |
823 | --------------------------> |
824 | |
825 | AGENT-HELLO + close() |
826 | <-------------------------- |
827 | |
828
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200829
830 * Error encountered by agent during the HELLO handshake:
831
832 HAPROXY AGENT SRV
833 | HAPROXY-HELLO |
834 | --------------------------> |
835 | |
836 | DISCONNECT + close() |
837 | <-------------------------- |
838 | |
839
840 * Error encountered by HAProxy during the HELLO handshake:
841
842 HAPROXY AGENT SRV
843 | HAPROXY-HELLO |
844 | --------------------------> |
845 | |
846 | AGENT-HELLO |
847 | <-------------------------- |
848 | |
849 | DISCONNECT |
850 | --------------------------> |
851 | |
852 | DISCONNECT + close() |
853 | <-------------------------- |
854 | |
855
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100856 * Notify / Ack exchange (unfragmented payload):
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200857
858 HAPROXY AGENT SRV
859 | NOTIFY |
860 | --------------------------> |
861 | |
862 | ACK |
863 | <-------------------------- |
864 | |
865
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100866 * Notify / Ack exchange (fragmented payload):
867
868 HAPROXY AGENT SRV
869 | NOTIFY (frag 1) |
870 | --------------------------> |
871 | |
872 | UNSET (frag 2) |
873 | --------------------------> |
874 | ... |
875 | UNSET (frag N) |
876 | --------------------------> |
877 | |
878 | ACK |
879 | <-------------------------- |
880 | |
881
882 * Aborted fragmentation of a NOTIFY frame:
883
884 HAPROXY AGENT SRV
885 | ... |
886 | UNSET (frag X) |
887 | --------------------------> |
888 | |
889 | ACK/ABORT |
890 | <-------------------------- |
891 | |
892 | UNSET (frag X+1) |
893 | -----------X |
894 | |
895 | |
896
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200897 * Connection closed by haproxy:
898
899 HAPROXY AGENT SRV
900 | DISCONNECT |
901 | --------------------------> |
902 | |
903 | DISCONNECT + close() |
904 | <-------------------------- |
905 | |
906
907 * Connection closed by agent:
908
909 HAPROXY AGENT SRV
910 | DISCONNECT + close() |
911 | <-------------------------- |
912 | |
913
9143.2.4. Frame: HAPROXY-HELLO
915----------------------------
916
917This frame is the first one exchanged between HAProxy and an agent, when the
918connection is established. The payload of this frame is a KV-LIST. It cannot be
919fragmented. STREAM-ID and FRAME-ID are must be set 0.
920
921Following items are mandatory in the KV-LIST:
922
923 * "supported-versions" <STRING>
924
925 Last SPOP major versions supported by HAProxy. It is a comma-separated list
926 of versions, following the format "Major.Minor". Spaces must be ignored, if
927 any. When a major version is announced by HAProxy, it means it also support
928 all previous minor versions.
929
930 Example: "2.0, 1.5" means HAProxy supports SPOP 2.0 and 1.0 to 1.5
931
932 * "max-frame-size" <UINT32>
933
934 This is the maximum size allowed for a frame. The HAPROXY-HELLO frame must
935 be lower or equal to this value.
936
937 * "capabilities" <STRING>
938
939 This a comma-separated list of capabilities supported by HAProxy. Spaces
940 must be ignored, if any.
941
Christopher Fauletba7bc162016-11-07 21:07:38 +0100942Following optional items can be added in the KV-LIST:
943
944 * "healthcheck" <BOOLEAN>
945
946 If this item is set to TRUE, then the HAPROXY-HELLO frame is sent during a
947 SPOE health check. When set to FALSE, this item can be ignored.
948
Christopher Fauleta1cda022016-12-21 08:58:06 +0100949 * "engine-id" <STRING>
950
951 This is a uniq string that identify a SPOE engine.
952
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200953To finish the HELLO handshake, the agent must return an AGENT-HELLO frame with
954its supported SPOP version, the lower value between its maximum size allowed
955for a frame and the HAProxy one and capabilities it supports. If an error
956occurs or if an incompatibility is detected with the agent configuration, an
957AGENT-DISCONNECT frame must be returned.
958
9593.2.5. Frame: AGENT-HELLO
960--------------------------
961
962This frame is sent in reply to a HAPROXY-HELLO frame to finish a HELLO
963handshake. As for HAPROXY-HELLO frame, STREAM-ID and FRAME-ID are also set
9640. The payload of this frame is a KV-LIST and it cannot be fragmented.
965
966Following items are mandatory in the KV-LIST:
967
968 * "version" <STRING>
969
970 This is the SPOP version the agent supports. It must follow the format
971 "Major.Minor" and it must be lower or equal than one of major versions
972 announced by HAProxy.
973
974 * "max-frame-size" <UINT32>
975
976 This is the maximum size allowed for a frame. It must be lower or equal to
977 the value in the HAPROXY-HELLO frame. This value will be used for all
978 subsequent frames.
979
980 * "capabilities" <STRING>
981
982 This a comma-separated list of capabilities supported by agent. Spaces must
983 be ignored, if any.
984
985At this time, if everything is ok for HAProxy (supported version and valid
986max-frame-size value), the HELLO handshake is successfully completed. Else,
987HAProxy sends a HAPROXY-DISCONNECT frame with the corresponding error.
988
Christopher Fauletba7bc162016-11-07 21:07:38 +0100989If "healthcheck" item was set to TRUE in the HAPROXY-HELLO frame, the agent can
990safely close the connection without DISCONNECT frame. In all cases, HAProxy
Ilya Shipitsin11057a32020-06-21 21:18:27 +0500991will close the connection at the end of the health check.
Christopher Fauletba7bc162016-11-07 21:07:38 +0100992
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02009933.2.6. Frame: NOTIFY
994---------------------
995
996Information are sent to the agents inside NOTIFY frames. These frames are
997attached to a stream, so STREAM-ID and FRAME-ID must be set. The payload of
998NOTIFY frames is a LIST-OF-MESSAGES and, if supported by agents, it can be
999fragmented.
1000
1001NOTIFY frames must be acknowledge by agents sending an ACK frame, repeating
1002right STREAM-ID and FRAME-ID.
1003
10043.2.7. Frame: ACK
1005------------------
1006
1007ACK frames must be sent by agents to reply to NOTIFY frames. STREAM-ID and
1008FRAME-ID found in a NOTIFY frame must be reuse in the corresponding ACK
1009frame. The payload of ACK frames is a LIST-OF-ACTIONS and, if supported by
1010HAProxy, it can be fragmented.
1011
10123.2.8. Frame: HAPROXY-DISCONNECT
1013---------------------------------
1014
1015If an error occurs, at anytime, from the HAProxy side, a HAPROXY-DISCONNECT
1016frame is sent with information describing the error. HAProxy will wait an
1017AGENT-DISCONNECT frame in reply. All other frames will be ignored. The agent
1018must then close the socket.
1019
1020The payload of this frame is a KV-LIST. It cannot be fragmented. STREAM-ID and
1021FRAME-ID are must be set 0.
1022
1023Following items are mandatory in the KV-LIST:
1024
1025 * "status-code" <UINT32>
1026
1027 This is the code corresponding to the error.
1028
1029 * "message" <STRING>
1030
1031 This is a textual message describing the error.
1032
1033For more information about known errors, see section "Errors & timeouts"
1034
10353.2.9. Frame: AGENT-DISCONNECT
1036-------------------------------
1037
1038If an error occurs, at anytime, from the agent size, a AGENT-DISCONNECT frame
Michael Prokop4438c602019-05-24 10:25:45 +02001039is sent, with information describing the error. such frame is also sent in reply
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001040to a HAPROXY-DISCONNECT. The agent must close the socket just after sending
1041this frame.
1042
1043The payload of this frame is a KV-LIST. It cannot be fragmented. STREAM-ID and
1044FRAME-ID are must be set 0.
1045
1046Following items are mandatory in the KV-LIST:
1047
1048 * "status-code" <UINT32>
1049
1050 This is the code corresponding to the error.
1051
1052 * "message" <STRING>
1053
1054 This is a textual message describing the error.
1055
1056For more information about known errors, see section "Errors & timeouts"
1057
10583.3. Events & Messages
1059-----------------------
1060
1061Information about streams are sent in NOTIFY frames. You can specify which kind
1062of information to send by defining "spoe-message" sections in your SPOE
1063configuration file. for each "spoe-message" there will be a message in a NOTIFY
1064frame when the right event is triggered.
1065
1066A NOTIFY frame is sent for an specific event when there is at least one
1067"spoe-message" attached to this event. All messages for an event will be added
1068in the same NOTIFY frame.
1069
1070Here is the list of supported events:
1071
1072 * on-client-session is triggered when a new client session is created.
1073 This event is only available for SPOE filters
1074 declared in a frontend or a listen section.
1075
1076 * on-frontend-tcp-request is triggered just before the evaluation of
1077 "tcp-request content" rules on the frontend side.
1078 This event is only available for SPOE filters
1079 declared in a frontend or a listen section.
1080
1081 * on-backend-tcp-request is triggered just before the evaluation of
1082 "tcp-request content" rules on the backend side.
1083 This event is skipped for SPOE filters declared
1084 in a listen section.
1085
1086 * on-frontend-http-request is triggered just before the evaluation of
1087 "http-request" rules on the frontend side. This
1088 event is only available for SPOE filters declared
1089 in a frontend or a listen section.
1090
1091 * on-backend-http-request is triggered just before the evaluation of
1092 "http-request" rules on the backend side. This
1093 event is skipped for SPOE filters declared in a
1094 listen section.
1095
1096 * on-server-session is triggered when the session with the server is
1097 established.
1098
1099 * on-tcp-response is triggered just before the evaluation of
1100 "tcp-response content" rules.
1101
1102 * on-http-response is triggered just before the evaluation of
1103 "http-response" rules.
1104
1105
1106The stream processing will loop on these events, when triggered, waiting the
1107agent reply.
1108
11093.4. Actions
1110-------------
1111
1112An agent must acknowledge each NOTIFY frame by sending the corresponding ACK
1113frame. Actions can be added in these frames to dynamically take action on the
1114processing of a stream.
1115
1116Here is the list of supported actions:
1117
1118 * set-var set the value for an existing variable. 3 arguments must be
1119 attached to this action: the variable scope (proc, sess, txn,
Kevin Zhu730323e2018-06-01 05:38:00 +02001120 req or res), the variable name (a string) and its value.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001121
1122 ACTION-SET-VAR : <SET-VAR:1 byte><NB-ARGS:1 byte><VAR-SCOPE:1 byte><VAR-NAME><VAR-VALUE>
1123
1124 SET-VAR : <1>
1125 NB-ARGS : <3>
1126 VAR-SCOPE : <PROCESS> | <SESSION> | <TRANSACTION> | <REQUEST> | <RESPONSE>
1127 VAR-NAME : <STRING>
1128 VAR-VALUE : <TYPED-DATA>
1129
1130 PROCESS : <0>
1131 SESSION : <1>
1132 TRANSACTION : <2>
1133 REQUEST : <3>
Christopher Fauleta1cda022016-12-21 08:58:06 +01001134 RESPONSE : <4>
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001135
1136 * unset-var unset the value for an existing variable. 2 arguments must be
1137 attached to this action: the variable scope (proc, sess, txn,
Kevin Zhu730323e2018-06-01 05:38:00 +02001138 req or res) and the variable name (a string).
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001139
Christopher Faulet1002aac2016-12-09 17:41:54 +01001140 ACTION-UNSET-VAR : <UNSET-VAR:1 byte><NB-ARGS:1 byte><VAR-SCOPE:1 byte><VAR-NAME>
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001141
Christopher Faulet1002aac2016-12-09 17:41:54 +01001142 UNSET-VAR : <2>
1143 NB-ARGS : <2>
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001144 VAR-SCOPE : <PROCESS> | <SESSION> | <TRANSACTION> | <REQUEST> | <RESPONSE>
1145 VAR-NAME : <STRING>
1146
1147 PROCESS : <0>
1148 SESSION : <1>
1149 TRANSACTION : <2>
1150 REQUEST : <3>
Christopher Fauleta1cda022016-12-21 08:58:06 +01001151 RESPONSE : <4>
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001152
1153
1154NOTE: Name of the variables will be automatically prefixed by HAProxy to avoid
1155 name clashes with other variables used in HAProxy. Moreover, unknown
1156 variable will be silently ignored.
1157
Christopher Fauletd1307ce2017-02-27 21:59:39 +010011583.5. Errors & timeouts
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001159----------------------
1160
1161Here is the list of all known errors:
1162
1163 STATUS CODE | DESCRIPTION
1164 ----------------+--------------------------------------------------------
1165 0 | normal (no error occurred)
1166 1 | I/O error
1167 2 | A timeout occurred
1168 3 | frame is too big
1169 4 | invalid frame received
1170 5 | version value not found
1171 6 | max-frame-size value not found
1172 7 | capabilities value not found
1173 8 | unsupported version
1174 9 | max-frame-size too big or too small
Christopher Fauletd1307ce2017-02-27 21:59:39 +01001175 10 | payload fragmentation is not supported
1176 11 | invalid interlaced frames
1177 12 | frame-id not found (it does not match any referenced frame)
1178 13 | resource allocation error
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001179 99 | an unknown error occurrde
1180 ----------------+--------------------------------------------------------
1181
1182An agent can define its own errors using a not yet assigned status code.
1183
Christopher Fauletea62c2a2016-11-14 10:54:21 +01001184IMPORTANT NOTE: By default, for a specific stream, when an abnormal/unexpected
1185 error occurs, the SPOE is disabled for all the transaction. So
1186 if you have several events configured, such error on an event
Ilya Shipitsin11057a32020-06-21 21:18:27 +05001187 will disabled all following. For TCP streams, this will
Christopher Fauletea62c2a2016-11-14 10:54:21 +01001188 disable the SPOE for the whole session. For HTTP streams, this
1189 will disable it for the transaction (request and response).
1190 See 'option continue-on-error' to bypass this limitation.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001191
Joseph Herlant71b4b152018-11-13 16:55:16 -08001192To avoid a stream to wait undefinetly, you must carefully choose the
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001193acknowledgement timeout. In most of cases, it will be quiet low. But it depends
1194on the responsivness of your service.
1195
1196You must also choose idle timeout carefully. Because connection with your
1197service depends on the backend configuration used by the SPOA, it is important
1198to use a lower value for idle timeout than the server timeout. Else the
1199connection will be closed by HAProxy. The same is true for hello timeout. You
1200should choose a lower value than the connect timeout.
1201
Christopher Fauletb2dd1e02018-03-22 09:07:41 +010012024. Logging
1203-----------
1204
1205Activity of an SPOE is logged using HAProxy's logger. The messages are logged
1206in the context of the streams that handle the client and the server
1207connections. A message is emitted for each event or group handled by an
1208SPOE. Depending on the status code, the log level will be different. In the
1209normal case, when no error occurred, the message is logged with the level
1210LOG_NOTICE. Otherwise, the message is logged with the level LOG_WARNING.
1211
Christopher Faulet3b8e3492018-03-26 17:20:58 +02001212The messages are logged using the agent's logger, if defined, and use the
1213following format:
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001214
Christopher Faulet6e0d5e72018-04-26 14:25:43 +02001215 SPOE: [AGENT] <TYPE:NAME> sid=STREAM-ID st=STATUS-CODE reqT/qT/wT/resT/pT \
Christopher Fauletcaf2fec2018-04-04 10:25:50 +02001216 <idles>/<applets> <nb_sending>/<nb_waiting> <nb_error>/<nb_processed>
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001217
1218 AGENT is the agent name
1219 TYPE is EVENT of GROUP
1220 NAME is the event or the group name
1221 STREAM-ID is an integer, the unique id of the stream
1222 STATUS_CODE is the processing's status code
1223 reqT/qT/wT/resT/pT are the following time events:
1224
1225 * reqT : the encoding time. It includes ACLs processing, if any. For
1226 fragmented frames, it is the sum of all fragments.
1227 * qT : the delay before the request gets out the sending queue. For
1228 fragmented frames, it is the sum of all fragments.
Joseph Herlant71b4b152018-11-13 16:55:16 -08001229 * wT : the delay before the response is received. No fragmentation
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001230 supported here.
1231 * resT : the delay to process the response. No fragmentation supported
Christopher Faulet36bda1c2018-03-22 09:08:20 +01001232 here.
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001233 * pT : the delay to process the event or the group. From the stream
Christopher Faulet36bda1c2018-03-22 09:08:20 +01001234 point of view, it is the latency added by the SPOE processing.
1235 It is more or less the sum of values above.
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001236
Christopher Fauletcaf2fec2018-04-04 10:25:50 +02001237 <idle> is the numbers of idle SPOE applets
1238 <applets> is the numbers of SPOE applets
1239 <nb_sending> is the numbers of streams waiting to send data
1240 <nb_waiting> is the numbers of streams waiting for a ack
1241 <nb_error> is the numbers of processing errors
1242 <nb_processed> is the numbers of events/groups processed
1243
1244
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001245For all these time events, -1 means the processing was interrupted before the
1246end. So -1 for the queue time means the request was never dequeued. For
1247fragmented frames it is harder to know when the interruption happened.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001248
1249/*
1250 * Local variables:
1251 * fill-column: 79
1252 * End:
1253 */