1A 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      100ms
40        timeout idle       30s
41        timeout processing 15ms
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).
89