simplified atime init
[rxpd] / README
1 <!> please help to improve this documentation <!>
2
3 /!\ Further Notice: I already document some non existing planned features here
4
5 RXPD Documentation
6
7 Overview
8
9 The RegexPolicyDaemon (rxpd) can be used to efficiently check data against
10 different lists of regular expressions. This can be used to build whitelists/
11 blacklists to protect many kinds of Internet services. It uses a simple textual
12 protocol that is easily implementable in scripting languages. Example usages
13 are access and content control (spam filtering) for CGI scripts, wikis, email,
14 revision control systems, IRC servers and clients, and so on.
15
16 Building and Installing
17
18 Release Tarballs
19
20 Release tarballs are attached to the wiki at:
21
22   * http://www.pipapo.org/pipawiki/RegexPolicyDaemon?action=AttachFile
23
24 I am using gpg signed tarballs for distribution. As first step one has to check
25 the signature
26
27 $ gpg rxpd-X.Y.tar.gz.gpg
28
29 This will produce a rxpd-X.Y.tar.gz and report if the signature could be
30 validated.
31
32 Since the package is built with gnu autotools, the usual build and install
33 procedure works:
34
35 $ tar xzvf rxpd-X.Y.tar.gz
36 $ cd rxpd-X.Y
37 $ mkdir build     # using a build directory is optional
38 & cd build
39 $ ../configure
40 $ make
41 $ make install
42
43 Development Version via git
44
45 The development version is available via git from 'git://git.pipapo.org/rxpd'
46 or mirrored at repo.or.cz 'git://repo.or.cz/rxpd.git'.
47
48 After you cloned the repository you need to bootstrap the autotools first
49
50 $ autoreconf -i
51
52 Then the usual configure / make will work.
53
54 There is a special makefile target make meta to bring several files (README,
55 AUTHORS, NEWS, TODO) in sync with the Rxpd Documentation wiki and update the
56 ChangeLog.
57
58 Dependencies
59
60 Rxpd requires libevent and its development headers.
61
62 What gets installed
63
64 A single executable called 'rxpd' will be installed in $prefix/bin.
65
66 Concepts
67
68 Rxpd targets to be simple and efficently validating data against Regular
69 expressions. It has (yet) no configuration file for the daemon itself and is
70 controlled by commandline options. Most management of regular expression lists
71 can be done remotely over a simple protocol. By itself it has has no
72 authentication but there is a 'policy' check which validates incoming requests
73 against an special regex list which then defines if the client is allowed to do
74 a certain task. Any further management like distributing the lists,
75 authenticate sessions more strongly and so on should be done by other means and
76 are not planned to be included in rxpd.
77
78 The goal it to create a common place which applications can use to validate any
79 kind of data. This works efficently because short lived programs like CGI
80 scripts take the advantage of regular expressions which are precompiled in core
81 and generally such lists might be shared between different applications.
82
83 Commandline Options and Starting
84
85 <!> WIP
86
87        Increase verbosity level. Verbosity levels correspondend to syslog
88 -v     levels, where LOG_WARNING is the default. Thus -v can be given up to
89        three times to get LOG_DEBUG.
90 -V     Just shows version information and then exit.
91 -d     Detach from terminal and run in background.
92 -D     Run in debug mode, that is, increasing verbosity to at lest LOG_INFO and
93        don't detach. An additional -v can be used for LOG_DEBUG.
94 -b dir Give the basedir for rules. Rules have to be in a single directory, rxpd
95        will never access any data outside of this directory.
96 -q     Turn rxpd quiet, only LOG_ALERT or worse will be logged.
97 -t     Give a port number for a tcp port to listen on. This option can be
98 port   appear multiple times. Only root can listen on ports less than 1024.
99 -u     Path for a unix local socket to listen on. This option can appear
100 name   multiple times.
101 -p     Define which rules-list will be be used to limit access to the rxpd
102 policy itself. If not given, no access restrictions apply (everything
103        allowed!). Policy matching will be descriped in detail later.
104 -i     Turn all regular expressions case insensitive.
105 -4     Use only IPv4, default is IPv4 and IPv6 when compiled in.
106 -6     Use only IPv6.
107 -h     Give a short usage notice and then exit.
108 -U     When started as root, switch to 'user', if not given, 'nobody' is used.
109 user
110
111 List Syntax
112
113 There are only 2 things allowed in a list file:
114
115   * Comments
116       + Begining with a '#' at the first column followed by arbitary text.
117         Comments are preserved and have semantic meaning as they can be used to
118         organize the data. Comments beginning with #OK: and #ERROR: have
119         special meaning, see below.
120   * Rules
121       + Starting with an optional accesstime entry, then a name, followed by a
122         regex. This three parts are delimited by colons.
123       + 'atime' will be maintained by the daemon to reflect the last time the
124         rule matched some data. This is time in seconds since epoch in UTC.
125       + 'name' is an arbitary string which has not special meaning for the rxpd
126         but will send back to the calling applications and be used there to
127         classify results.
128       + the regex is a POSIX extended regular expression, regex are currently
129         case-insensitive this will become configureable later.
130
131 Lines in can be at most 4095 bytes long.
132
133 Example list file:
134
135 # Free things are good!
136 :accept:GNU|Linux
137 0:accept:FreeBSD
138 # Bad things
139 0:reject:M.*soft
140
141 Matches will later report the line matched, without the atime and first colon
142 part. "Macrosoft" matches "M.*soft" thus "reject:M.*soft" will be returned.
143
144 Note that the first 'accept' rule has no atime, to initiate atimes they can be
145 initalized with '0' the daemon will update them on access and rewrite the List
146 files with the 'SAVE' command or when it recieves a SIGTERM.
147
148 When there is an error in a regular expression, it will be replaced with #
149 ERROR:, followed by the cause of the error, followed by the rules string in
150 quote.
151
152 Protocol
153
154 Rxpd uses a simple line based text protocol. The first line is always the
155 command and list which will be used on the following data, it is not possible
156 to change the command throughout a session. Each session will generate at least
157 one line of response. When no other output is available '#OK:' is send, in case
158 of an error a line starting with '#ERROR:' is send.
159
160 Lines end with any combination of the 'newline' and/or 'carriage return'
161 character.
162
163 The protocol is line based where lines which are longer than 4095 characters
164 are broken (may be word-wraped on the last whitespace character in the line in
165 future).
166
167 Commands:
168
169   * 'CHECK:list\n..data..'
170       + check all following data against the list. Returns the first matching
171         rule (excluding the 'atime' field), if any. When a empty line is send,
172         the daemon answers with "#OK:". This can be used to syncronize the
173         queries before sending new data.
174   * 'APPEND:list\n..rules..'
175       + append the following lines to list.
176   * 'PREPEND:list\n..rules..'
177       + prepend the following lines to list.
178   * 'REMOVE:list\n..rules..'
179       + remove all matching lines from list.
180   * 'REPLACE:list\nrule\n..replacements..'
181       + find the position matching the first line, which can be a rule or a
182         comment and replaces it with the following rules. Updates are atomic
183         and done when either an empty line is send or when the connection gets
184         closed.
185   * 'LOAD:list\n'
186       + reload list from disk, this resets the 'atime' to the values stored on
187         disk.
188   * 'SAVE:list\n'
189       + save list to disk, saves new atime records.
190   * 'EXPIRE:list\nseconds'
191       + removes all rules from list which are subject of atime updates and
192         where not touched for some (much) seconds.
193   * 'SYNC:list\nremote'
194       + fetches a list from remote which has the form address/listname where
195         address is either 'ip:port' or a path to a unix domain socket. Then
196         updates 'list' atimes to newer ones from the remote list.
197
198         Idea: do we want 'SYNC:list\
199         nremote:policylist' which gives a local list filtering remote first?
200   * 'MERGE:list\nremote'
201       + fetches a list from remote which has the form address/listname where
202         address is either 'ip:port' or a path to a unix domain socket. Then
203         merges new rules from remote.
204
205         Idea: do we want 'SYNC:list\
206         nremote:policylist' which gives a local list filtering remote first?
207   * 'DUMP:list\n'
208       + dump the content of list.
209   * 'LIST:\n'
210       + list all loaded lists.
211   * 'SHUTDOWN:\n'
212       + exits the daemon gracefully, pending connections will still be served
213         but no new connections are accepted.
214   * 'VERSION:\n'
215       + prints package and version information.
216   * 'HELP:\n'
217       + gives a short list of available commands.
218
219 Using the rxpd
220
221 <!> WIP
222
223 Access Policies
224
225 One list of rules can be used to define access policies for the rxpd itself (-p
226 option). Each command will be extended with access protocol (one of tcp4, tcp6
227 or unix) and the peer address and then checked against this policy list. When
228 this check yields in an 'ACCEPT:..' rule, the command is allowed, for
229 everything else will result in an error and drop the connection.
230
231 For example if '-p policy' is used:
232
233 # Syntax:
234 # [atime]:rulename:command:list:proto:address
235 #
236 # Allow dumping of the 'policy' list itself
237 :ACCEPT:DUMP:policy
238 # Clients from local network are allowed to do anything
239 :ACCEPT:.*:tcp.:10\..*$
240 # Forbid all others to do anything else with the policy
241 :REJECT:.*:policy
242 # Finally allow anything else
243 :ACCEPT:.*
244
245 Example
246
247 We want to protect a wiki or such against vandalism: blacklists are in
248 $blacklists.d/ lets say /etc/blacklists.d/
249
250 The wiki engine builds a tuple hostname;ip which is checked against a blacklist
251 which classify the 'hosts'
252
253 this is /etc/blacklist.d/hosts
254
255 # local access are always trusted, thats localhost any my local network
256 :allow:localhost;127.0.0.1
257 :allow:mydomain.org;10.10.
258 # some really bad guys are put on a blacklist which never ever shall get access
259 :deny:.*aol.com;
260 # everyone else shall just get the content checked
261 :check:
262
263 so printf("CHECK:hosts\n%s;%s\n", hostname, ipaddr) send to the blacklist
264 daemon will result in either 'allow', 'deny' or 'check' send back. The first
265 both (allow/deny) results are handled obliviously. With the 'check' result the
266 edited content will be filtered against another list '/etc/blacklists.d/
267 content'
268
269 #example .. see BadContent on this wiki
270 :deny:sex.com
271 :deny:warez
272
273 Demonstation
274
275 <!> WIP <!> Not always running
276
277 Note: there is an almost unrestricted rxpd running here as demo:
278
279 $ echo "LIST:" | nc www.pipapo.org 2345
280 policy
281
282 $ echo "DUMP:policy" | nc www.pipapo.org 2345
283 # syntax:
284 # rule:command:list:proto:address
285 #
286 # reject this policy file itself to external users, except dumping
287 ACCEPT:DUMP:policy
288 REJECT:.*:policy
289 # accept all other for tests
290 ACCEPT:.*
291
292 This Documentation is maintained at:
293
294   * http://www.pipapo.org/pipawiki/RegexPolicyDaemon/Documentation
295
296 RegexPolicyDaemon/Documentation (last edited 2007-10-16 08:15:35 by ct)
297