blob: 2b4cc3b566d0c424e715e0540a85382f88de0078 [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
4 ( Last update: 2017-09-22 )
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
44 A SPOE is a filter talking to servers managed ba a SPOA to offload the
45 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
73releases, besides being experimental, won't do lot of things. As we will see,
74there are few handled events and even less actions supported. Actually, for
75now, the SPOE can offload the processing before "tcp-request content",
76"tcp-response content", "http-request" and "http-response" rules. And it only
77supports variables definition. But, in spite of these limited features, we can
78easily imagine to implement SSO solution, ip reputation or ip geolocation
79services.
80
81
822. SPOE configuration
83----------------------
84
85Because SPOE is implemented as a filter, To use it, you must declare a "filter
86spoe" line in a proxy section (frontend/backend/listen) :
87
88 frontend my-front
89 ...
90 filter spoe [engine <name>] config <file>
91 ...
92
93The "config" parameter is mandatory. It specififies the SPOE configuration
94file. The engine name is optional. It can be set to declare the scope to use in
95the SPOE configuration. So it is possible to use the same SPOE configuration
96for several engines. If no name is provided, the SPOE configuration must not
97contain any scope directive.
98
99We use a separate configuration file on purpose. By commenting SPOE filter
100line, you completly disable the feature, including the parsing of sections
101reserved to SPOE. This is also a way to keep the HAProxy configuration clean.
102
103A SPOE configuration file must contains, at least, the SPOA configuration
Christopher Faulet11610f32017-09-21 10:23:10 +0200104("spoe-agent" section) and SPOE messages/groups ("spoe-message" or "spoe-group"
105sections) attached to this agent.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200106
107IMPORTANT : The configuration of a SPOE filter must be located in a dedicated
108file. But the backend used by a SPOA must be declared in HAProxy configuration
109file.
110
1112.1. SPOE scope
112-------------------------
113
114If you specify an engine name on the SPOE filter line, then you need to define
115scope in the SPOE configuration with the same name. You can have several SPOE
116scope in the same file. In each scope, you must define one and only one
117"spoe-agent" section to configure the SPOA linked to your SPOE and several
Christopher Faulet11610f32017-09-21 10:23:10 +0200118"spoe-message" and "spoe-group" sections to describe, respecively, messages and
119group of messages sent to servers mananged by your SPOA.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200120
121A SPOE scope starts with this kind of line :
122
123 [<name>]
124
125where <name> is the same engine name specified on the SPOE filter line. The
126scope ends when the file ends or when another scope is found.
127
128 Example :
129 [my-first-engine]
130 spoe-agent my-agent
131 ...
132 spoe-message msg1
133 ...
134 spoe-message msg2
135 ...
Christopher Fauletb2dd1e02018-03-22 09:07:41 +0100136 spoe-group grp1
Christopher Faulet11610f32017-09-21 10:23:10 +0200137 ...
Christopher Fauletb2dd1e02018-03-22 09:07:41 +0100138 spoe-group grp2
139 ...
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200140
141 [my-second-engine]
142 ...
143
144If no engine name is provided on the SPOE filter line, no SPOE scope must be
145found in the SPOE configuration file. All the file is considered to be in the
146same anonymous and implicit scope.
147
Christopher Faulet7ee86672017-09-19 11:08:28 +0200148The engine name must be uniq for a proxy. If no engine name is provided on the
149SPOE filter line, the SPOE agent name is unsed by default.
150
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001512.2. "spoe-agent" section
152--------------------------
153
154For each engine, you must define one and only one "spoe-agent" section. In this
155section, you will declare SPOE messages and the backend you will use. You will
156also set timeouts and options to customize your agent's behaviour.
157
158
159spoe-agent <name>
160 Create a new SPOA with the name <name>. It must have one and only one
161 "spoe-agent" definition by SPOE scope.
162
163 Arguments :
164 <name> is the name of the agent section.
165
166 following keywords are supported :
Christopher Faulet11610f32017-09-21 10:23:10 +0200167 - groups
Christopher Faulet7250b8f2018-03-26 17:19:01 +0200168 - log
Christopher Faulet48026722016-11-16 15:01:12 +0100169 - maxconnrate
170 - maxerrrate
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100171 - max-frame-size
Christopher Faulete8ade382018-01-25 15:32:22 +0100172 - max-waiting-frames
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200173 - messages
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100174 - [no] option async
Christopher Faulet0e0f0852018-03-26 17:20:36 +0200175 - [no] option dontlog-normal
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100176 - [no] option pipelining
177 - [no] option send-frag-payload
Christopher Fauletea62c2a2016-11-14 10:54:21 +0100178 - option continue-on-error
Christopher Faulet336d3ef2017-12-22 10:00:55 +0100179 - option force-set-var
Christopher Faulet985532d2016-11-16 15:36:19 +0100180 - option set-on-error
Christopher Faulet36bda1c2018-03-22 09:08:20 +0100181 - option set-process-time
182 - option set-total-time
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200183 - option var-prefix
Christopher Faulet336d3ef2017-12-22 10:00:55 +0100184 - register-var-names
Christopher Faulet03a34492016-11-19 16:47:56 +0100185 - timeout hello|idle|processing
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200186 - use-backend
187
188
Christopher Faulet11610f32017-09-21 10:23:10 +0200189groups <grp-name> ...
190 Declare the list of SPOE groups that an agent will handle.
191
192 Arguments :
193 <grp-name> is the name of a SPOE group.
194
195 Groups delcared here must be found in the same engine scope, else an error is
196 triggered during the configuration parsing. You can have many "groups" lines.
197
198 See also: "spoe-group" section.
199
200
Christopher Faulet7250b8f2018-03-26 17:19:01 +0200201log global
202log <address> [len <length>] [format <format>] <facility> [<level> [<minlevel>]]
203no log
204 Enable per-instance logging of events and traffic.
205
206 Prefix :
207 no should be used when the logger list must be flushed.
208
209 See the HAProxy Configuration Manual for details about this option.
210
Christopher Faulet48026722016-11-16 15:01:12 +0100211maxconnrate <number>
212 Set the maximum number of connections per second to <number>. The SPOE will
213 stop to open new connections if the maximum is reached and will wait to
214 acquire an existing one. So it is important to set "timeout hello" to a
215 relatively small value.
216
217
218maxerrrate <number>
219 Set the maximum number of errors per second to <number>. The SPOE will stop
220 its processing if the maximum is reached.
221
222
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100223max-frame-size <number>
224 Set the maximum allowed size for frames exchanged between HAProxy and SPOA.
225 It must be in the range [256, tune.bufsize-4] (4 bytes are reserved for the
226 frame length). By default, it is set to (tune.bufsize-4).
227
Christopher Faulete8ade382018-01-25 15:32:22 +0100228max-waiting-frames <number>
229 Set the maximum number of frames waiting for an acknowledgement on the same
230 connection. This value is only used when the pipelinied or asynchronus
231 exchanges between HAProxy and SPOA are enabled. By default, it is set to 20.
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100232
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200233messages <msg-name> ...
234 Declare the list of SPOE messages that an agent will handle.
235
236 Arguments :
237 <msg-name> is the name of a SPOE message.
238
239 Messages declared here must be found in the same engine scope, else an error
240 is triggered during the configuration parsing. You can have many "messages"
241 lines.
242
243 See also: "spoe-message" section.
244
245
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100246option async
247no option async
248 Enable or disable the support of asynchronus exchanges between HAProxy and
249 SPOA. By default, this option is enabled.
250
251
Christopher Fauletea62c2a2016-11-14 10:54:21 +0100252option continue-on-error
253 Do not stop the events processing when an error occurred on a stream.
254
255 By default, for a specific stream, when an abnormal/unexpected error occurs,
256 the SPOE is disabled for all the transaction. So if you have several events
257 configured, such error on an event will disabled all followings. For TCP
258 streams, this will disable the SPOE for the whole session. For HTTP streams,
259 this will disable it for the transaction (request and response).
260
261 When set, this option bypass this behaviour and only the current event will
262 be ignored.
263
Christopher Faulet0e0f0852018-03-26 17:20:36 +0200264
265option dontlog-normal
266no option dontlog-normal
267 Enable or disable logging of normal, successful processing.
268
269 Arguments : none
270
271 See also: "log" and section 4 about logging.
272
273
Etienne Carriereaec89892017-12-14 09:36:40 +0000274option force-set-var
275 By default, SPOE filter only register already known variables (mainly from
276 parsing of the configuration). If you want that haproxy trusts the agent and
277 registers all variables (ex: can be useful for LUA workload), activate this
278 option.
279
280 Caution : this option opens to a variety of attacks such as a rogue SPOA that
281 asks to register too many variables.
282
Christopher Fauletea62c2a2016-11-14 10:54:21 +0100283
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100284option pipelining
285no option pipelining
286 Enable or disable the support of pipelined exchanges between HAProxy and
287 SPOA. By default, this option is enabled.
288
289
290option send-frag-payload
291no option send-frag-payload
292 Enable or disable the sending of fragmented payload to SPOA. By default, this
293 option is enabled.
294
295
Christopher Faulet985532d2016-11-16 15:36:19 +0100296option set-on-error <var name>
297 Define the variable to set when an error occurred during an event processing.
298
299 Arguments :
300
301 <var name> is the variable name, without the scope. The name may only
302 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
303
304 This variable will only be set when an error occurred in the scope of the
305 transaction. As for all other variables define by the SPOE, it will be
306 prefixed. So, if your variable name is "error" and your prefix is
307 "my_spoe_pfx", the variable will be "txn.my_spoe_pfx.error".
308
Christopher Fauletb067b062017-01-04 16:39:11 +0100309 When set, the variable is an integer representing the error reason. For values
310 under 256, it represents an error coming from the engine. Below 256, it
311 reports a SPOP error. In this case, to retrieve the right SPOP status code,
312 you must remove 256 to this value. Here are possible values:
313
314 * 1 a timeout occurred during the event processing.
315
316 * 2 an error was triggered during the ressources allocation.
317
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100318 * 3 the frame payload exceeds the frame size and it cannot be
319 fragmented.
320
321 * 4 the fragmentation of a payload is aborted.
322
Christopher Faulet344c4ab2017-09-22 10:20:13 +0200323 * 5 The frame processing has been interrupted by HAProxy.
324
Christopher Fauletb067b062017-01-04 16:39:11 +0100325 * 255 an unknown error occurred during the event processing.
326
327 * 256+N a SPOP error occurred during the event processing (see section
328 "Errors & timeouts").
329
330 Note that if "option continue-on-error" is set, the variable is not
331 automatically removed between events processing.
Christopher Faulet985532d2016-11-16 15:36:19 +0100332
333 See also: "option continue-on-error", "option var-prefix".
334
Christopher Faulet36bda1c2018-03-22 09:08:20 +0100335
336option set-process-time <var name>
337 Define the variable to set to report the processing time of the last event or
338 group.
339
340 Arguments :
341
342 <var name> is the variable name, without the scope. The name may only
343 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
344
345 This variable will be set in the scope of the transaction. As for all other
346 variables define by the SPOE, it will be prefixed. So, if your variable name
347 is "process_time" and your prefix is "my_spoe_pfx", the variable will be
348 "txn.my_spoe_pfx.process_time".
349
350 When set, the variable is an integer representing the delay to process the
351 event or the group, in milliseconds. From the stream point of view, it is the
352 latency added by the SPOE processing for the last handled event or group.
353
354 If several events or groups are processed for the same stream, this value
355 will be overrideen.
356
357 See also: "option set-total-time".
358
359
360option set-total-time <var name>
361 Define the variable to set to report the total processing time SPOE for a
362 stream.
363
364 Arguments :
365
366 <var name> is the variable name, without the scope. The name may only
367 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
368
369 This variable will be set in the scope of the transaction. As for all other
370 variables define by the SPOE, it will be prefixed. So, if your variable name
371 is "total_time" and your prefix is "my_spoe_pfx", the variable will be
372 "txn.my_spoe_pfx.total_time".
373
374 When set, the variable is an integer representing the sum of processing times
375 for a stream, in milliseconds. From the stream point of view, it is the
376 latency added by the SPOE processing.
377
378 If several events or groups are processed for the same stream, this value
379 will be updated.
380
381 See also: "option set-process-time".
382
383
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200384option var-prefix <prefix>
385 Define the prefix used when variables are set by an agent.
386
387 Arguments :
388
389 <prefix> is the prefix used to limit the scope of variables set by an
390 agent.
391
392 To avoid conflict with other variables defined by HAProxy, all variables
393 names will be prefixed. By default, the "spoe-agent" name is used. This
394 option can be used to customize it.
395
396 The prefix will be added between the variable scope and its name, separated
397 by a '.'. It may only contain characters 'a-z', 'A-Z', '0-9', '.' and '_', as
398 for variables name. In HAProxy configuration, you need to use this prefix as
399 a part of the variables name. For example, if an agent define the variable
400 "myvar" in the "txn" scope, with the prefix "my_spoe_pfx", then you should
401 use "txn.my_spoe_pfx.myvar" name in your HAProxy configuration.
402
Etienne Carriereaec89892017-12-14 09:36:40 +0000403 By default, an agent will never set new variables at runtime: It can only set
404 new value for existing ones. If you want a different behaviour, see
Christopher Faulet336d3ef2017-12-22 10:00:55 +0100405 force-set-var option and register-var-names directive.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200406
Christopher Faulet336d3ef2017-12-22 10:00:55 +0100407register-var-names <var name> ...
408 Register some variable names. By default, an agent will not be allowed to set
409 new variables at runtime. This rule can be totally relaxed by setting the
410 option "force-set-var". If you know all the variables you will need, this
411 directive is a good way to register them without letting an agent doing what
412 it want. This is only required if these variables are not referenced anywhere
413 in the HAProxy configuration or the SPOE one.
414
415 Arguments:
416 <var name> is a variable name without the scope. The name may only
417 contain characters 'a-z', 'A-Z', '0-9', '.' and '_'.
418
419 The prefix will be automatically added during the registration. You can have
420 many "register-var-names" lines.
421
422 See also: "option force-set-var", "option var-prefix".
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200423
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200424timeout hello <timeout>
425 Set the maximum time to wait for an agent to receive the AGENT-HELLO frame.
Christopher Fauletf7a30922016-11-10 15:04:51 +0100426 It is applied on the stream that handle the connection with the agent.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200427
428 Arguments :
429 <timeout> is the timeout value specified in milliseconds by default, but
430 can be in any other unit if the number is suffixed by the unit,
431 as explained at the top of this document.
432
433 This timeout is an applicative timeout. It differ from "timeout connect"
434 defined on backends.
435
436
437timeout idle <timeout>
Christopher Fauletf7a30922016-11-10 15:04:51 +0100438 Set the maximum time to wait for an agent to close an idle connection. It is
439 applied on the stream that handle the connection with the agent.
440
441 Arguments :
442 <timeout> is the timeout value specified in milliseconds by default, but
443 can be in any other unit if the number is suffixed by the unit,
444 as explained at the top of this document.
445
446
447timeout processing <timeout>
448 Set the maximum time to wait for a stream to process an event, i.e to acquire
449 a stream to talk with an agent, to encode all messages, to send the NOTIFY
450 frame, to receive the corrsponding acknowledgement and to process all
451 actions. It is applied on the stream that handle the client and the server
452 sessions.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200453
454 Arguments :
455 <timeout> is the timeout value specified in milliseconds by default, but
456 can be in any other unit if the number is suffixed by the unit,
457 as explained at the top of this document.
458
459
460use-backend <backend>
461 Specify the backend to use. It must be defined.
462
463 Arguments :
464 <backend> is the name of a valid "backend" section.
465
466
4672.3. "spoe-message" section
468----------------------------
469
470To offload the stream processing, SPOE will send messages with specific
471information at a specific moment in the stream life and will wait for
472corresponding replies to know what to do.
473
474
475spoe-message <name>
476 Create a new SPOE message with the name <name>.
477
478 Arguments :
479 <name> is the name of the SPOE message.
480
481 Here you define a message that can be referenced in a "spoe-agent"
482 section. Following keywords are supported :
Christopher Faulet57583e42017-09-04 15:41:09 +0200483 - acl
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200484 - args
485 - event
486
487 See also: "spoe-agent" section.
488
489
Christopher Faulet57583e42017-09-04 15:41:09 +0200490acl <aclname> <criterion> [flags] [operator] <value> ...
Christopher Faulet57583e42017-09-04 15:41:09 +0200491 Declare or complete an access list.
492
493 See section 7 about ACL usage in the HAProxy Configuration Manual.
494
495
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200496args [name=]<sample> ...
497 Define arguments passed into the SPOE message.
498
499 Arguments :
500 <sample> is a sample expression.
501
502 When the message is processed, if a sample expression is not available, it is
503 set to NULL. Arguments are processed in their declaration order and added in
504 the message in that order. It is possible to declare named arguements.
505
506 For example:
507 args frontend=fe_id src dst
508
509
Christopher Faulet57583e42017-09-04 15:41:09 +0200510event <name> [ { if | unless } <condition> ]
511 Set the event that triggers sending of the message. It may optionally be
512 followed by an ACL-based condition, in which case it will only be evaluated
513 if the condition is true.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200514
Christopher Faulet57583e42017-09-04 15:41:09 +0200515 ACL-based conditions are executed in the context of the stream that handle
516 the client and the server connections.
517
518 Arguments :
519 <name> is the event name.
520 <condition> is a standard ACL-based condition.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200521
522 Supported events are:
523 - on-client-session
Christopher Faulet1002aac2016-12-09 17:41:54 +0100524 - on-server-session
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200525 - on-frontend-tcp-request
526 - on-backend-tcp-request
527 - on-tcp-response
528 - on-frontend-http-request
529 - on-backend-http-request
530 - on-http-response
531
Christopher Faulet57583e42017-09-04 15:41:09 +0200532 See section "Events & Messages" for more details about supported events.
533 See section 7 about ACL usage in the HAProxy Configuration Manual.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200534
Christopher Faulet11610f32017-09-21 10:23:10 +02005352.4. "spoe-group" section
536--------------------------
537
538This section can be used to declare a group of SPOE messages. Unlike messages
539referenced in a "spoe-agent" section, messages inside a group are not sent on a
540specific event. The sending must be triggered by TCP or HTTP rules, from the
541HAProxy configuration.
542
543
544spoe-group <name>
545 Create a new SPOE group with the name <name>.
546
547 Arguments :
548 <name> is the name of the SPOE group.
549
550 Here you define a group of SPOE messages that can be referenced in a
551 "spoe-agent" section. Following keywords are supported :
552 - messages
553
554 See also: "spoe-agent" and "spoe-message" sections.
555
556
557messages <msg-name> ...
558 Declare the list of SPOE messages belonging to the group.
559
560 Arguments :
561 <msg-name> is the name of a SPOE message.
562
563 Messages declared here must be found in the same engine scope, else an error
564 is triggered during the configuration parsing. Furthermore, a message belongs
565 at most to a group. You can have many "messages" lines.
566
567 See also: "spoe-message" section.
568
569
5702.5. Example
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200571-------------
572
573Here is a simple but complete example that sends client-ip address to a ip
574reputation service. This service can set the variable "ip_score" which is an
575integer between 0 and 100, indicating its reputation (100 means totally safe
576and 0 a blacklisted IP with no doubt).
577
578 ###
579 ### HAProxy configuration
580 frontend www
581 mode http
582 bind *:80
583
584 filter spoe engine ip-reputation config spoe-ip-reputation.conf
585
586 # Reject connection if the IP reputation is under 20
587 tcp-request content reject if { var(sess.iprep.ip_score) -m int lt 20 }
588
589 default_backend http-servers
590
591 backend http-servers
592 mode http
593 server http A.B.C.D:80
594
595 backend iprep-servers
596 mode tcp
597 balance roundrobin
598
599 timeout connect 5s # greater than hello timeout
600 timeout server 3m # greater than idle timeout
601
602 server iprep1 A1.B1.C1.D1:12345
603 server iprep2 A2.B2.C2.D2:12345
604
605 ####
606 ### spoe-ip-reputation.conf
607 [ip-reputation]
608
609 spoe-agent iprep-agent
610 messages get-ip-reputation
611
612 option var-prefix iprep
613
Christopher Faulet03a34492016-11-19 16:47:56 +0100614 timeout hello 2s
615 timeout idle 2m
616 timeout processing 10ms
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200617
618 use-backend iprep-servers
619
620 spoe-message get-ip-reputation
621 args ip=src
Christopher Faulet57583e42017-09-04 15:41:09 +0200622 event on-client-session if ! { src -f /etc/haproxy/whitelist.lst }
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200623
624
6253. SPOP specification
626----------------------
627
6283.1. Data types
629----------------
630
631Here is the bytewise representation of typed data:
632
633 TYPED-DATA : <TYPE:4 bits><FLAGS:4 bits><DATA>
634
635Supported types and their representation are:
636
637 TYPE | ID | DESCRIPTION
638 -----------------------------+-----+----------------------------------
639 NULL | 0 | NULL : <0>
640 Boolean | 1 | BOOL : <1+FLAG>
641 32bits signed integer | 2 | INT32 : <2><VALUE:varint>
642 32bits unsigned integer | 3 | UINT32 : <3><VALUE:varint>
643 64bits signed integer | 4 | INT64 : <4><VALUE:varint>
644 32bits unsigned integer | 5 | UNIT64 : <5><VALUE:varint>
645 IPV4 | 6 | IPV4 : <6><STRUCT IN_ADDR:4 bytes>
646 IPV6 | 7 | IPV6 : <7><STRUCT IN_ADDR6:16 bytes>
647 String | 8 | STRING : <8><LENGTH:varint><BYTES>
648 Binary | 9 | BINARY : <9><LENGTH:varint><BYTES>
649 10 -> 15 unused/reserved | - | -
650 -----------------------------+-----+----------------------------------
651
652Variable-length integer (varint) are encoded using Peers encoding:
653
654
655 0 <= X < 240 : 1 byte (7.875 bits) [ XXXX XXXX ]
656 240 <= X < 2288 : 2 bytes (11 bits) [ 1111 XXXX ] [ 0XXX XXXX ]
657 2288 <= X < 264432 : 3 bytes (18 bits) [ 1111 XXXX ] [ 1XXX XXXX ] [ 0XXX XXXX ]
658 264432 <= X < 33818864 : 4 bytes (25 bits) [ 1111 XXXX ] [ 1XXX XXXX ]*2 [ 0XXX XXXX ]
659 33818864 <= X < 4328786160 : 5 bytes (32 bits) [ 1111 XXXX ] [ 1XXX XXXX ]*3 [ 0XXX XXXX ]
660 ...
661
662For booleans, the value (true or false) is the first bit in the FLAGS
663bitfield. if this bit is set to 0, then the boolean is evaluated as false,
664otherwise, the boolean is evaluated as true.
665
6663.2. Frames
667------------
668
669Exchange between HAProxy and agents are made using FRAME packets. All frames
670must be prefixed with their size encoded on 4 bytes in network byte order:
671
672 <FRAME-LENGTH:4 bytes> <FRAME>
673
674A frame always starts with its type, on one byte, followed by metadata
675containing flags, on 4 bytes and a two variable-length integer representing the
676stream identifier and the frame identifier inside the stream:
677
678 FRAME : <FRAME-TYPE:1 byte> <METADATA> <FRAME-PAYLOAD>
679 METADATA : <FLAGS:4 bytes> <STREAM-ID:varint> <FRAME-ID:varint>
680
681Then comes the frame payload. Depending on the frame type, the payload can be
682of three types: a simple key/value list, a list of messages or a list of
683actions.
684
685 FRAME-PAYLOAD : <LIST-OF-MESSAGES> | <LIST-OF-ACTIONS> | <KV-LIST>
686
687 LIST-OF-MESSAGES : [ <MESSAGE-NAME> <NB-ARGS:1 byte> <KV-LIST> ... ]
688 MESSAGE-NAME : <STRING>
689
690 LIST-OF-ACTIONS : [ <ACTION-TYPE:1 byte> <NB-ARGS:1 byte> <ACTION-ARGS> ... ]
691 ACTION-ARGS : [ <TYPED-DATA>... ]
692
693 KV-LIST : [ <KV-NAME> <KV-VALUE> ... ]
694 KV-NAME : <STRING>
695 KV-VALUE : <TYPED-DATA>
696
Thierry FOURNIERc4dcaff2018-05-18 12:25:39 +0200697 FLAGS :
698
699 Flags are a 32 bits field. They are encoded on 4 bytes in network byte
700 order, where the bit 0 is the LSB.
701
702 0 1 2-31
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100703 +---+---+----------+
704 | | A | |
705 | F | B | |
706 | I | O | RESERVED |
707 | N | R | |
708 | | T | |
709 +---+---+----------+
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200710
711 FIN: Indicates that this is the final payload fragment. The first fragment
712 may also be the final fragment.
713
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100714 ABORT: Indicates that the processing of the current frame must be
715 cancelled. This bit should be set on frames with a fragmented
716 payload. It can be ignore for frames with an unfragemnted
717 payload. When it is set, the FIN bit must also be set.
718
719
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200720Frames cannot exceed a maximum size negociated between HAProxy and agents
721during the HELLO handshake. Most of time, payload will be small enough to send
722it in one frame. But when supported by the peer, it will be possible to
723fragment huge payload on many frames. This ability is announced during the
724HELLO handshake and it can be asynmetric (supported by agents but not by
725HAProxy or the opposite). The following rules apply to fragmentation:
726
727 * An unfragemnted payload consists of a single frame with the FIN bit set.
728
729 * A fragemented payload consists of several frames with the FIN bit clear and
730 terminated by a single frame with the FIN bit set. All these frames must
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100731 share the same STREAM-ID and FRAME-ID. The first frame must set the right
732 FRAME-TYPE (e.g, NOTIFY). The following frames must have an unset type (0).
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200733
734Beside the support of fragmented payload by a peer, some payload must not be
735fragmented. See below for details.
736
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100737IMPORTANT : The maximum size supported by peers for a frame must be greater
738than or equal to 256 bytes.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200739
7403.2.1. Frame capabilities
741--------------------------
742
743Here are the list of official capabilities that HAProxy and agents can support:
744
Christopher Fauleta1cda022016-12-21 08:58:06 +0100745 * fragmentation: This is the ability for a peer to support fragmented
746 payload in received frames. This is an asymmectical
747 capability, it only concerns the peer that announces
748 it. This is the responsibility to the other peer to use it
749 or not.
750
751 * pipelining: This is the ability for a peer to decouple NOTIFY and ACK
752 frames. This is a symmectical capability. To be used, it must
753 be supported by HAproxy and agents. Unlike HTTP pipelining, the
754 ACK frames can be send in any order, but always on the same TCP
755 connection used for the corresponding NOTIFY frame.
756
757 * async: This ability is similar to the pipelining, but here any TCP
758 connection established between HAProxy and the agent can be used to
759 send ACK frames. if an agent accepts connections from multiple
760 HAProxy, it can use the "engine-id" value to group TCP
761 connections. See details about HAPROXY-HELLO frame.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200762
763Unsupported or unknown capabilities are silently ignored, when possible.
764
7653.2.2. Frame types overview
766----------------------------
767
768Here are types of frame supported by SPOE. Frames sent by HAProxy come first,
769then frames sent by agents :
770
771 TYPE | ID | DESCRIPTION
772 -----------------------------+-----+-------------------------------------
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100773 UNSET | 0 | Used for all frames but the first when a
774 | | payload is fragmented.
775 -----------------------------+-----+-------------------------------------
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200776 HAPROXY-HELLO | 1 | Sent by HAProxy when it opens a
777 | | connection on an agent.
778 | |
779 HAPROXY-DISCONNECT | 2 | Sent by HAProxy when it want to close
780 | | the connection or in reply to an
781 | | AGENT-DISCONNECT frame
782 | |
783 NOTIFY | 3 | Sent by HAProxy to pass information
784 | | to an agent
785 -----------------------------+-----+-------------------------------------
786 AGENT-HELLO | 101 | Reply to a HAPROXY-HELLO frame, when
787 | | the connection is established
788 | |
789 AGENT-DISCONNECT | 102 | Sent by an agent just before closing
790 | | the connection
791 | |
792 ACK | 103 | Sent to acknowledge a NOTIFY frame
793 -----------------------------+-----+-------------------------------------
794
795Unknown frames may be silently skipped.
796
7973.2.3. Workflow
798----------------
799
800 * Successful HELLO handshake:
801
802 HAPROXY AGENT SRV
803 | HAPROXY-HELLO |
Christopher Fauletba7bc162016-11-07 21:07:38 +0100804 | (healthcheck: false) |
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200805 | --------------------------> |
806 | |
807 | AGENT-HELLO |
808 | <-------------------------- |
809 | |
810
Christopher Fauletba7bc162016-11-07 21:07:38 +0100811 * Successful HELLO healthcheck:
812
813 HAPROXY AGENT SRV
814 | HAPROXY-HELLO |
815 | (healthcheck: true) |
816 | --------------------------> |
817 | |
818 | AGENT-HELLO + close() |
819 | <-------------------------- |
820 | |
821
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200822
823 * Error encountered by agent during the HELLO handshake:
824
825 HAPROXY AGENT SRV
826 | HAPROXY-HELLO |
827 | --------------------------> |
828 | |
829 | DISCONNECT + close() |
830 | <-------------------------- |
831 | |
832
833 * Error encountered by HAProxy during the HELLO handshake:
834
835 HAPROXY AGENT SRV
836 | HAPROXY-HELLO |
837 | --------------------------> |
838 | |
839 | AGENT-HELLO |
840 | <-------------------------- |
841 | |
842 | DISCONNECT |
843 | --------------------------> |
844 | |
845 | DISCONNECT + close() |
846 | <-------------------------- |
847 | |
848
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100849 * Notify / Ack exchange (unfragmented payload):
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200850
851 HAPROXY AGENT SRV
852 | NOTIFY |
853 | --------------------------> |
854 | |
855 | ACK |
856 | <-------------------------- |
857 | |
858
Christopher Fauletd1307ce2017-02-27 21:59:39 +0100859 * Notify / Ack exchange (fragmented payload):
860
861 HAPROXY AGENT SRV
862 | NOTIFY (frag 1) |
863 | --------------------------> |
864 | |
865 | UNSET (frag 2) |
866 | --------------------------> |
867 | ... |
868 | UNSET (frag N) |
869 | --------------------------> |
870 | |
871 | ACK |
872 | <-------------------------- |
873 | |
874
875 * Aborted fragmentation of a NOTIFY frame:
876
877 HAPROXY AGENT SRV
878 | ... |
879 | UNSET (frag X) |
880 | --------------------------> |
881 | |
882 | ACK/ABORT |
883 | <-------------------------- |
884 | |
885 | UNSET (frag X+1) |
886 | -----------X |
887 | |
888 | |
889
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200890 * Connection closed by haproxy:
891
892 HAPROXY AGENT SRV
893 | DISCONNECT |
894 | --------------------------> |
895 | |
896 | DISCONNECT + close() |
897 | <-------------------------- |
898 | |
899
900 * Connection closed by agent:
901
902 HAPROXY AGENT SRV
903 | DISCONNECT + close() |
904 | <-------------------------- |
905 | |
906
9073.2.4. Frame: HAPROXY-HELLO
908----------------------------
909
910This frame is the first one exchanged between HAProxy and an agent, when the
911connection is established. The payload of this frame is a KV-LIST. It cannot be
912fragmented. STREAM-ID and FRAME-ID are must be set 0.
913
914Following items are mandatory in the KV-LIST:
915
916 * "supported-versions" <STRING>
917
918 Last SPOP major versions supported by HAProxy. It is a comma-separated list
919 of versions, following the format "Major.Minor". Spaces must be ignored, if
920 any. When a major version is announced by HAProxy, it means it also support
921 all previous minor versions.
922
923 Example: "2.0, 1.5" means HAProxy supports SPOP 2.0 and 1.0 to 1.5
924
925 * "max-frame-size" <UINT32>
926
927 This is the maximum size allowed for a frame. The HAPROXY-HELLO frame must
928 be lower or equal to this value.
929
930 * "capabilities" <STRING>
931
932 This a comma-separated list of capabilities supported by HAProxy. Spaces
933 must be ignored, if any.
934
Christopher Fauletba7bc162016-11-07 21:07:38 +0100935Following optional items can be added in the KV-LIST:
936
937 * "healthcheck" <BOOLEAN>
938
939 If this item is set to TRUE, then the HAPROXY-HELLO frame is sent during a
940 SPOE health check. When set to FALSE, this item can be ignored.
941
Christopher Fauleta1cda022016-12-21 08:58:06 +0100942 * "engine-id" <STRING>
943
944 This is a uniq string that identify a SPOE engine.
945
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +0200946To finish the HELLO handshake, the agent must return an AGENT-HELLO frame with
947its supported SPOP version, the lower value between its maximum size allowed
948for a frame and the HAProxy one and capabilities it supports. If an error
949occurs or if an incompatibility is detected with the agent configuration, an
950AGENT-DISCONNECT frame must be returned.
951
9523.2.5. Frame: AGENT-HELLO
953--------------------------
954
955This frame is sent in reply to a HAPROXY-HELLO frame to finish a HELLO
956handshake. As for HAPROXY-HELLO frame, STREAM-ID and FRAME-ID are also set
9570. The payload of this frame is a KV-LIST and it cannot be fragmented.
958
959Following items are mandatory in the KV-LIST:
960
961 * "version" <STRING>
962
963 This is the SPOP version the agent supports. It must follow the format
964 "Major.Minor" and it must be lower or equal than one of major versions
965 announced by HAProxy.
966
967 * "max-frame-size" <UINT32>
968
969 This is the maximum size allowed for a frame. It must be lower or equal to
970 the value in the HAPROXY-HELLO frame. This value will be used for all
971 subsequent frames.
972
973 * "capabilities" <STRING>
974
975 This a comma-separated list of capabilities supported by agent. Spaces must
976 be ignored, if any.
977
978At this time, if everything is ok for HAProxy (supported version and valid
979max-frame-size value), the HELLO handshake is successfully completed. Else,
980HAProxy sends a HAPROXY-DISCONNECT frame with the corresponding error.
981
Christopher Fauletba7bc162016-11-07 21:07:38 +0100982If "healthcheck" item was set to TRUE in the HAPROXY-HELLO frame, the agent can
983safely close the connection without DISCONNECT frame. In all cases, HAProxy
984will close the connexion at the end of the health check.
985
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02009863.2.6. Frame: NOTIFY
987---------------------
988
989Information are sent to the agents inside NOTIFY frames. These frames are
990attached to a stream, so STREAM-ID and FRAME-ID must be set. The payload of
991NOTIFY frames is a LIST-OF-MESSAGES and, if supported by agents, it can be
992fragmented.
993
994NOTIFY frames must be acknowledge by agents sending an ACK frame, repeating
995right STREAM-ID and FRAME-ID.
996
9973.2.7. Frame: ACK
998------------------
999
1000ACK frames must be sent by agents to reply to NOTIFY frames. STREAM-ID and
1001FRAME-ID found in a NOTIFY frame must be reuse in the corresponding ACK
1002frame. The payload of ACK frames is a LIST-OF-ACTIONS and, if supported by
1003HAProxy, it can be fragmented.
1004
10053.2.8. Frame: HAPROXY-DISCONNECT
1006---------------------------------
1007
1008If an error occurs, at anytime, from the HAProxy side, a HAPROXY-DISCONNECT
1009frame is sent with information describing the error. HAProxy will wait an
1010AGENT-DISCONNECT frame in reply. All other frames will be ignored. The agent
1011must then close the socket.
1012
1013The payload of this frame is a KV-LIST. It cannot be fragmented. STREAM-ID and
1014FRAME-ID are must be set 0.
1015
1016Following items are mandatory in the KV-LIST:
1017
1018 * "status-code" <UINT32>
1019
1020 This is the code corresponding to the error.
1021
1022 * "message" <STRING>
1023
1024 This is a textual message describing the error.
1025
1026For more information about known errors, see section "Errors & timeouts"
1027
10283.2.9. Frame: AGENT-DISCONNECT
1029-------------------------------
1030
1031If an error occurs, at anytime, from the agent size, a AGENT-DISCONNECT frame
1032is sent, with information desribing the error. such frame is also sent in reply
1033to a HAPROXY-DISCONNECT. The agent must close the socket just after sending
1034this frame.
1035
1036The payload of this frame is a KV-LIST. It cannot be fragmented. STREAM-ID and
1037FRAME-ID are must be set 0.
1038
1039Following items are mandatory in the KV-LIST:
1040
1041 * "status-code" <UINT32>
1042
1043 This is the code corresponding to the error.
1044
1045 * "message" <STRING>
1046
1047 This is a textual message describing the error.
1048
1049For more information about known errors, see section "Errors & timeouts"
1050
10513.3. Events & Messages
1052-----------------------
1053
1054Information about streams are sent in NOTIFY frames. You can specify which kind
1055of information to send by defining "spoe-message" sections in your SPOE
1056configuration file. for each "spoe-message" there will be a message in a NOTIFY
1057frame when the right event is triggered.
1058
1059A NOTIFY frame is sent for an specific event when there is at least one
1060"spoe-message" attached to this event. All messages for an event will be added
1061in the same NOTIFY frame.
1062
1063Here is the list of supported events:
1064
1065 * on-client-session is triggered when a new client session is created.
1066 This event is only available for SPOE filters
1067 declared in a frontend or a listen section.
1068
1069 * on-frontend-tcp-request is triggered just before the evaluation of
1070 "tcp-request content" rules on the frontend side.
1071 This event is only available for SPOE filters
1072 declared in a frontend or a listen section.
1073
1074 * on-backend-tcp-request is triggered just before the evaluation of
1075 "tcp-request content" rules on the backend side.
1076 This event is skipped for SPOE filters declared
1077 in a listen section.
1078
1079 * on-frontend-http-request is triggered just before the evaluation of
1080 "http-request" rules on the frontend side. This
1081 event is only available for SPOE filters declared
1082 in a frontend or a listen section.
1083
1084 * on-backend-http-request is triggered just before the evaluation of
1085 "http-request" rules on the backend side. This
1086 event is skipped for SPOE filters declared in a
1087 listen section.
1088
1089 * on-server-session is triggered when the session with the server is
1090 established.
1091
1092 * on-tcp-response is triggered just before the evaluation of
1093 "tcp-response content" rules.
1094
1095 * on-http-response is triggered just before the evaluation of
1096 "http-response" rules.
1097
1098
1099The stream processing will loop on these events, when triggered, waiting the
1100agent reply.
1101
11023.4. Actions
1103-------------
1104
1105An agent must acknowledge each NOTIFY frame by sending the corresponding ACK
1106frame. Actions can be added in these frames to dynamically take action on the
1107processing of a stream.
1108
1109Here is the list of supported actions:
1110
1111 * set-var set the value for an existing variable. 3 arguments must be
1112 attached to this action: the variable scope (proc, sess, txn,
Kevin Zhu730323e2018-06-01 05:38:00 +02001113 req or res), the variable name (a string) and its value.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001114
1115 ACTION-SET-VAR : <SET-VAR:1 byte><NB-ARGS:1 byte><VAR-SCOPE:1 byte><VAR-NAME><VAR-VALUE>
1116
1117 SET-VAR : <1>
1118 NB-ARGS : <3>
1119 VAR-SCOPE : <PROCESS> | <SESSION> | <TRANSACTION> | <REQUEST> | <RESPONSE>
1120 VAR-NAME : <STRING>
1121 VAR-VALUE : <TYPED-DATA>
1122
1123 PROCESS : <0>
1124 SESSION : <1>
1125 TRANSACTION : <2>
1126 REQUEST : <3>
Christopher Fauleta1cda022016-12-21 08:58:06 +01001127 RESPONSE : <4>
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001128
1129 * unset-var unset the value for an existing variable. 2 arguments must be
1130 attached to this action: the variable scope (proc, sess, txn,
Kevin Zhu730323e2018-06-01 05:38:00 +02001131 req or res) and the variable name (a string).
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001132
Christopher Faulet1002aac2016-12-09 17:41:54 +01001133 ACTION-UNSET-VAR : <UNSET-VAR:1 byte><NB-ARGS:1 byte><VAR-SCOPE:1 byte><VAR-NAME>
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001134
Christopher Faulet1002aac2016-12-09 17:41:54 +01001135 UNSET-VAR : <2>
1136 NB-ARGS : <2>
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001137 VAR-SCOPE : <PROCESS> | <SESSION> | <TRANSACTION> | <REQUEST> | <RESPONSE>
1138 VAR-NAME : <STRING>
1139
1140 PROCESS : <0>
1141 SESSION : <1>
1142 TRANSACTION : <2>
1143 REQUEST : <3>
Christopher Fauleta1cda022016-12-21 08:58:06 +01001144 RESPONSE : <4>
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001145
1146
1147NOTE: Name of the variables will be automatically prefixed by HAProxy to avoid
1148 name clashes with other variables used in HAProxy. Moreover, unknown
1149 variable will be silently ignored.
1150
Christopher Fauletd1307ce2017-02-27 21:59:39 +010011513.5. Errors & timeouts
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001152----------------------
1153
1154Here is the list of all known errors:
1155
1156 STATUS CODE | DESCRIPTION
1157 ----------------+--------------------------------------------------------
1158 0 | normal (no error occurred)
1159 1 | I/O error
1160 2 | A timeout occurred
1161 3 | frame is too big
1162 4 | invalid frame received
1163 5 | version value not found
1164 6 | max-frame-size value not found
1165 7 | capabilities value not found
1166 8 | unsupported version
1167 9 | max-frame-size too big or too small
Christopher Fauletd1307ce2017-02-27 21:59:39 +01001168 10 | payload fragmentation is not supported
1169 11 | invalid interlaced frames
1170 12 | frame-id not found (it does not match any referenced frame)
1171 13 | resource allocation error
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001172 99 | an unknown error occurrde
1173 ----------------+--------------------------------------------------------
1174
1175An agent can define its own errors using a not yet assigned status code.
1176
Christopher Fauletea62c2a2016-11-14 10:54:21 +01001177IMPORTANT NOTE: By default, for a specific stream, when an abnormal/unexpected
1178 error occurs, the SPOE is disabled for all the transaction. So
1179 if you have several events configured, such error on an event
1180 will disabled all followings. For TCP streams, this will
1181 disable the SPOE for the whole session. For HTTP streams, this
1182 will disable it for the transaction (request and response).
1183 See 'option continue-on-error' to bypass this limitation.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001184
1185To avoid a stream to wait infinitly, you must carefully choose the
1186acknowledgement timeout. In most of cases, it will be quiet low. But it depends
1187on the responsivness of your service.
1188
1189You must also choose idle timeout carefully. Because connection with your
1190service depends on the backend configuration used by the SPOA, it is important
1191to use a lower value for idle timeout than the server timeout. Else the
1192connection will be closed by HAProxy. The same is true for hello timeout. You
1193should choose a lower value than the connect timeout.
1194
Christopher Fauletb2dd1e02018-03-22 09:07:41 +010011954. Logging
1196-----------
1197
1198Activity of an SPOE is logged using HAProxy's logger. The messages are logged
1199in the context of the streams that handle the client and the server
1200connections. A message is emitted for each event or group handled by an
1201SPOE. Depending on the status code, the log level will be different. In the
1202normal case, when no error occurred, the message is logged with the level
1203LOG_NOTICE. Otherwise, the message is logged with the level LOG_WARNING.
1204
Christopher Faulet3b8e3492018-03-26 17:20:58 +02001205The messages are logged using the agent's logger, if defined, and use the
1206following format:
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001207
Christopher Faulet6e0d5e72018-04-26 14:25:43 +02001208 SPOE: [AGENT] <TYPE:NAME> sid=STREAM-ID st=STATUS-CODE reqT/qT/wT/resT/pT \
Christopher Fauletcaf2fec2018-04-04 10:25:50 +02001209 <idles>/<applets> <nb_sending>/<nb_waiting> <nb_error>/<nb_processed>
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001210
1211 AGENT is the agent name
1212 TYPE is EVENT of GROUP
1213 NAME is the event or the group name
1214 STREAM-ID is an integer, the unique id of the stream
1215 STATUS_CODE is the processing's status code
1216 reqT/qT/wT/resT/pT are the following time events:
1217
1218 * reqT : the encoding time. It includes ACLs processing, if any. For
1219 fragmented frames, it is the sum of all fragments.
1220 * qT : the delay before the request gets out the sending queue. For
1221 fragmented frames, it is the sum of all fragments.
1222 * wT : the delay before the reponse is received. No fragmentation
1223 supported here.
1224 * resT : the delay to process the response. No fragmentation supported
Christopher Faulet36bda1c2018-03-22 09:08:20 +01001225 here.
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001226 * pT : the delay to process the event or the group. From the stream
Christopher Faulet36bda1c2018-03-22 09:08:20 +01001227 point of view, it is the latency added by the SPOE processing.
1228 It is more or less the sum of values above.
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001229
Christopher Fauletcaf2fec2018-04-04 10:25:50 +02001230 <idle> is the numbers of idle SPOE applets
1231 <applets> is the numbers of SPOE applets
1232 <nb_sending> is the numbers of streams waiting to send data
1233 <nb_waiting> is the numbers of streams waiting for a ack
1234 <nb_error> is the numbers of processing errors
1235 <nb_processed> is the numbers of events/groups processed
1236
1237
Christopher Fauletb2dd1e02018-03-22 09:07:41 +01001238For all these time events, -1 means the processing was interrupted before the
1239end. So -1 for the queue time means the request was never dequeued. For
1240fragmented frames it is harder to know when the interruption happened.
Christopher Fauletf7e4e7e2016-10-27 22:29:49 +02001241
1242/*
1243 * Local variables:
1244 * fill-column: 79
1245 * End:
1246 */