blob: 3494256c4aff97a7270df64c90a392585dbe1f5e [file] [log] [blame]
Christopher Faulet010fded2016-11-03 22:49:37 +01001A Random IP reputation service acting as a Stream Processing Offload Agent
2--------------------------------------------------------------------------
3
4This is a very simple service that implement a "random" ip reputation
5service. It will return random scores for all checked IP addresses. It only
6shows you how to implement a ip reputation service or such kind of services
7using the SPOE.
8
9
10 Start the service
11---------------------
12
13After you have compiled it, to start the service, you just need to use "spoa"
14binary:
15
16 $> ./spoa -h
17 Usage: ./spoa [-h] [-d] [-p <port>] [-n <num-workers>]
18 -h Print this message
19 -d Enable the debug mode
20 -p <port> Specify the port to listen on (default: 12345)
21 -n <num-workers> Specify the number of workers (default: 5)
22
23Note: A worker is a thread.
24
25
26 Configure a SPOE to use the service
27---------------------------------------
28
29All information about SPOE configuration can be found in "doc/SPOE.txt". Here is
30the configuration template to use for your SPOE:
31
32 [ip-reputation]
33
34 spoe-agent iprep-agent
35 messages check-client-ip
36
37 option var-prefix iprep
38
39 timeout hello 1s
40 timeout ack 10ms
41 timeout idle 30s
42
43 use-backend iprep-backend
44
45 spoe-message check-client-ip
46 args src
47 event on-client-session
48
49
50The engine is in the scope "ip-reputation". So to enable it, you must set the
51following line in a frontend/listener section:
52
53 frontend my-front
54 ...
55 filter spoe engine ip-reputation config /path/spoe-ip-reputation.conf
56 ....
57
58where "/path/spoe-ip-reputation.conf" is the path to your SPOE configuration
59file. The engine name is important here, it must be the same than the one used
60in the SPOE configuration file.
61
62IMPORTANT NOTE:
63 Because we want to send a message on the "on-client-session" event, this
64 SPOE must be attached to a proxy with the frontend capability. If it is
65 declared in a backend section, it will have no effet.
66
67
68Because, in SPOE configuration file, we declare to use the backend
69"iprep-backend" to communicate with the service, you must define it in HAProxy
70configuration. For example:
71
72 backend iprep-backend
73 mode tcp
74 timeout server 1m
75 server iprep-srv 127.0.0.1:12345 check maxconn 5
76
77
78In reply to the "check-client-ip" message, this service will set the variable
79"ip_score" for the session, an integer between 0 and 100. If unchanged, the
80variable prefix is "iprep". So the full variable name will be
81"sess.iprep.ip_score".
82
83You can use it in ACLs to experiment the SPOE feature. For example:
84
85 tcp-request content reject if { var(sess.iprep.ip_score) -m int lt 20 }
86
87With this rule, all IP address with a score lower than 20 will be rejected
88(Remember, this score is random).