MINOR/DOC: spoe-server: Add documentation
This is the documentation and examples.
diff --git a/contrib/spoa_server/README b/contrib/spoa_server/README
index 7e376ee..57ec9c4 100644
--- a/contrib/spoa_server/README
+++ b/contrib/spoa_server/README
@@ -1,12 +1,20 @@
-A Random IP reputation service acting as a Stream Processing Offload Agent
---------------------------------------------------------------------------
+Multi script langyage Stream Processing Offload Agent
+-----------------------------------------------------
-This is a very simple service that implement a "random" ip reputation
-service. It will return random scores for all checked IP addresses. It only
-shows you how to implement a ip reputation service or such kind of services
-using the SPOE.
+This agent receive SPOP message and process it with script languages. The
+language register callback with a message. Each callback receive the list
+of arguments with types according with the language capabilities. The
+callback write variables which are sent as response when the processing
+is done.
+ Compilation
+---------------
+
+Actually, the server support Lua and Python. Type "make" with the options:
+USE_LUA=1 and/or USE_PYTHON=1.
+
+
Start the service
---------------------
@@ -19,70 +27,47 @@
-d Enable the debug mode
-p <port> Specify the port to listen on (default: 12345)
-n <num-workers> Specify the number of workers (default: 5)
-
-Note: A worker is a thread.
-
-
- Configure a SPOE to use the service
----------------------------------------
+ -f <file> Load script according with the supported languages
-All information about SPOE configuration can be found in "doc/SPOE.txt". Here is
-the configuration template to use for your SPOE:
+The file processor is recognized using the extension. .lua or .luac for lua and
+.py for python. Start example:
- [ip-reputation]
+ $> ./spoa -d -f ps_lua.lua
- spoe-agent iprep-agent
- messages check-client-ip
+ $> ./spoa -d -f ps_pyhton.py
- option var-prefix iprep
- timeout hello 100ms
- timeout idle 30s
- timeout processing 15ms
+ Configure
+-------------
- use-backend iprep-backend
+Sample configuration are join to this server:
- spoe-message check-client-ip
- args src
- event on-client-session
+ spoa-server.conf : The HAProxy configuration file using SPOE server
+ spoa-server.spoe.conf : The SPOP description file used by HAProxy
+ ps_lua.lua : Processing Lua example
+ ps_python.py : Processing Python example
-The engine is in the scope "ip-reputation". So to enable it, you must set the
-following line in a frontend/listener section:
+ Considerations
+------------------
- frontend my-front
- ...
- filter spoe engine ip-reputation config /path/spoe-ip-reputation.conf
- ....
+This server is a beta version. It works fine, but some improvement will be
+welcome:
-where "/path/spoe-ip-reputation.conf" is the path to your SPOE configuration
-file. The engine name is important here, it must be the same than the one used
-in the SPOE configuration file.
+Main process:
-IMPORTANT NOTE:
- Because we want to send a message on the "on-client-session" event, this
- SPOE must be attached to a proxy with the frontend capability. If it is
- declared in a backend section, it will have no effet.
+ * Improve log management: Today the log are sent on stdout.
+ * Improve process management: The dead process are ignored.
+ * Implement systemd integration.
+ * Implement threads: It would be fine to implement thread working. Shared
+ memory is welcome for managing database connection pool and something like
+ that.
+ * Add PHP support and some other languages.
+Python:
-Because, in SPOE configuration file, we declare to use the backend
-"iprep-backend" to communicate with the service, you must define it in HAProxy
-configuration. For example:
-
- backend iprep-backend
- mode tcp
- timeout server 1m
- server iprep-srv 127.0.0.1:12345 check maxconn 5
-
-
-In reply to the "check-client-ip" message, this service will set the variable
-"ip_score" for the session, an integer between 0 and 100. If unchanged, the
-variable prefix is "iprep". So the full variable name will be
-"sess.iprep.ip_score".
-
-You can use it in ACLs to experiment the SPOE feature. For example:
-
- tcp-request content reject if { var(sess.iprep.ip_score) -m int lt 20 }
+ * Improve repporting: Catch python error message and repport it in the right
+ place. Today the error are dumped on stdout. How using syslog for logging
+ stack traces ?
-With this rule, all IP address with a score lower than 20 will be rejected
-(Remember, this score is random).
+Maybe some other things...