fixed typo
[rxpd] / README
1 RXPD Documentation
2
3 Overview
4
5 The RegexPolicyDaemon (rxpd) can be used to efficiently check data against
6 different lists of regular expressions. This can be used to build whitelists/
7 blacklists to protect many kinds of Internet services. It uses a simple textual
8 protocol that is easily implementable in scripting languages. Example usages
9 are access and content control (spam filtering) for CGI scripts, wikis, email,
10 revision control systems, IRC servers and clients, and so on.
11
12 Rxpd encourages users to distribute their lists in a friend2friend network. It
13 has features to fetch, updaten, filter and merge lists. The idea is that users/
14 administrators maintain manageable lists which cover single topics and then
15 merge them together.
16
17 Building and Installing
18
19 Release Tarballs
20
21 Release tarballs are attached to the wiki at:
22
23   * http://www.pipapo.org/pipawiki/RegexPolicyDaemon?action=AttachFile
24
25 I am using gpg signed tarballs for distribution. As first step one has to check
26 the signature
27
28 $ gpg rxpd-X.Y.tar.gz.gpg
29
30 This will produce a rxpd-X.Y.tar.gz and report if the signature could be
31 validated.
32
33 Since the package is built with gnu autotools, the usual build and install
34 procedure works:
35
36 $ tar xzvf rxpd-X.Y.tar.gz
37 $ cd rxpd-X.Y
38 $ mkdir build     # using a build directory is optional
39 & cd build
40 $ ../configure
41 $ make
42 $ make install
43
44 Development Version via git
45
46 The development version is available via git from 'git://git.pipapo.org/rxpd'
47 or mirrored at repo.or.cz 'git://repo.or.cz/rxpd.git'.
48
49 After you cloned the repository you need to bootstrap the autotools first
50
51 $ autoreconf -i
52
53 Then the usual configure / make will work.
54
55 There is a special makefile target make meta to bring several files (README,
56 AUTHORS, NEWS, TODO) in sync with the Rxpd Documentation wiki and update the
57 ChangeLog.
58
59 Dependencies
60
61 Rxpd requires gnu-pth and its development headers.
62
63 What gets installed
64
65 A single executable called 'rxpd' will be installed in $prefix/bin.
66
67 Concepts
68
69 Rxpd targets to be simple and efficently validating data against Regular
70 expressions. It has (yet) no configuration file for the daemon itself and is
71 controlled by commandline options. Most management of regular expression lists
72 can be done remotely over a simple protocol. By itself it has has no
73 authentication but there is a 'policy' check which validates incoming requests
74 against an special regex list which then defines if the client is allowed to do
75 a certain task. Any further management like distributing the lists,
76 authenticate sessions more strongly and so on should be done by other means and
77 are not planned to be included in rxpd.
78
79 The goal it to create a common place which applications can use to validate any
80 kind of data. This works efficently because short lived programs like CGI
81 scripts take the advantage of regular expressions which are precompiled in core
82 and generally such lists might be shared between different applications.
83
84 Commandline Options and Starting
85
86 <!> WIP
87
88        Increase verbosity level. Verbosity levels correspondend to syslog
89 -v     levels, where LOG_WARNING is the default. Thus -v can be given up to
90        three times to get LOG_DEBUG.
91 -V     Just shows version information and then exit.
92 -d     Detach from terminal and run in background.
93 -D     Run in debug mode, that is, increasing verbosity to at lest LOG_INFO and
94        don't detach. An additional -v can be used for LOG_DEBUG.
95 -b dir Give the basedir for rules. Rules have to be in a single directory, rxpd
96        will never access any data outside of this directory.
97 -q     Turn rxpd quiet, only LOG_ALERT or worse will be logged.
98 -t     Give a port number for a tcp port to listen on. This option can be
99 port   appear multiple times. Only root can listen on ports less than 1024.
100 -u     Path for a unix local socket to listen on. This option can appear
101 name   multiple times.
102 -p     Define which rules-list will be be used to limit access to the rxpd
103 policy itself. If not given, no access restrictions apply (everything
104        allowed!). Policy matching will be descriped in detail later.
105 -i     Turn all regular expressions case insensitive.
106 -4     Use only IPv4, default is IPv4 and IPv6 when compiled in.
107 -6     Use only IPv6.
108 -h     Give a short usage notice and then exit.
109 -U     When started as root, switch to 'user', if not given, 'nobody' is used.
110 user
111
112 List Syntax
113
114 There are only 2 things allowed in a list file:
115
116   * Comments
117       + Begining with a '#' at the first column followed by arbitary text.
118         Comments are preserved and have semantic meaning as they can be used to
119         organize the data. Comments in the form '#UPPERCASE: ' are special/
120         reserved, the engine uses them to disable rules when they expire or
121         flag errorneous rules, '#lowercase: ' can be used for custom enabling/
122         disableing of rules, see the FILTER command.
123   * Rules
124       + Starting with an optional accesstime entry, then a name, followed by a
125         regex. This three parts are delimited by colons.
126       + 'atime' will be maintained by the daemon to reflect the last time the
127         rule matched some data. This is time in seconds since epoch in UTC.
128       + 'name' is an arbitary string which has not special meaning for the rxpd
129         but will send back to the calling applications and be used there to
130         classify results.
131           o the name may start with a '>' this is used to jump into a sublist
132             which name is defined by the name of the current list appended by
133             what follows the '>'.
134       + the regex is a POSIX extended regular expression, regex are currently
135         case-insensitive this will become configureable later.
136
137 Lines in can be at most 4095 bytes long.
138
139 Example list file, let's name this 'example':
140
141 # Free things are good!
142 :accept:GNU|Linux
143 0:accept:FreeBSD
144 # Bad things
145 0:reject:M.*soft
146 # For everything which matches 'blah' jump into the sublist 'examplesub'
147 :>sub:blah
148
149 Matches will later report the line matched, without the atime and first colon
150 part. "Macrosoft" matches "M.*soft" thus "reject:M.*soft" will be returned.
151
152 Note that the first 'accept' rule has no atime, to initiate atimes they can be
153 initalized with '0' the daemon will update them on access and rewrite the List
154 files with the 'SAVE' command or when it recieves a SIGTERM.
155
156 When there is an error in a regular expression, it will be replaced with #
157 ERROR:, followed by the cause of the error, followed by the rules string in
158 quote.
159
160 A client can indicate that it is finished by sending !EXIT on a single line for
161 all commands which take multi line input except 'CHECK:'.
162
163 Protocol
164
165 Rxpd uses a simple line based text protocol. The first line is always the
166 command and list which will be used on the following data, it is not possible
167 to change the command throughout a session. Each session will generate at least
168 one line of response. When no other output is available '#OK:' is send, in case
169 of an error a line starting with '#ERROR:' is send.
170
171 Lines end with any combination of the 'newline' and/or 'carriage return'
172 character.
173
174 The protocol is line based where lines which are longer than 4095 characters
175 are broken (may be word-wraped on the last whitespace character in the line in
176 future). Many commands take multiple lines as input, all this commands except
177 'CHECK:' can be exited by sending a '!EXIT' statement.
178
179 Lists are autoloaded on demand and automatically saved when they are already
180 exist on disk.
181
182 Commands:
183
184   * 'CHECK:list\n..data..'
185       + check all following data against the list. Returns the first matching
186         rule (excluding the 'atime' field), if any. When a empty line is send,
187         the daemon answers with "#OK:". This can be used to syncronize the
188         queries before sending new data.
189   * 'APPEND:list\n..rules..'
190       + append the following lines to list.
191   * 'PREPEND:list\n..rules..'
192       + prepend the following lines to list.
193   * 'REMOVE:list\n..rules..'
194       + remove all matching lines from list.
195   * 'REPLACE:list\nrule\n..replacements..'
196       + find the position matching the first line, which can be a rule or a
197         comment and replaces it with the following rules. Updates are atomic
198         and done when either an empty line is send or when the connection gets
199         closed.
200   * 'CLEAR:list\n'
201       + Removes all rules from a list.
202   * 'DELETE:list\n'
203       + Deletes list completely including removing it from disk.
204   * 'LOAD:list\n'
205       + reload list from disk, this resets the 'atime' to the values stored on
206         disk. Existing lists will be autoloaded when first referenced.
207   * 'SAVE:list\n'
208       + save list to disk, saves new atime records. Lists have to be saved at
209         least once to be subject of automatic saving.
210   * 'EXPIRE:list\nseconds'
211       + marks all rules from list which are subject of atime updates and where
212         not touched for some (much) seconds with a '#EXPIRED:' comment,
213         effectively disabling them.
214   * 'FILTER:list\nfilters...'
215       + runs 'filters..' (also rules lists) over list and takes action for
216         matches. There are 2 Actions defined:
217           o 'DELETE' removes the matching rule completely from the list
218           o 'ACTIVATE' tries to reactivate a previously commented out rule (#
219             something: comment)
220           o any other name will just comment out the matching rule using the
221             name itself
222   * 'FETCH:list\nremote'
223       + fetches a list from remote storing it in local 'list'. 'remote' has the
224         form address/listname where address is either 'ip:port' or a path to a
225         unix domain socket.
226
227         Idea: do we want 'FETCH:list\
228         nremote:policylist' which gives a local list filtering remote first?
229   * 'UPDATE:list\nsource...'
230       + updates atimes in 'list' from sources, uses an efficent forward looking
231         algorithm, rule reordering in sources is not supported (adding/removing
232         rules works). sources have to be other local lists.
233   * 'MERGE:list\nsources..'
234       + Adds new lines from other 'sources..' to 'list', order will be
235         preserved. Does NOT delete removed lines.
236   * 'DUMP:list\n'
237       + dump the content of list.
238   * 'LIST:\n'
239       + list all loaded lists.
240   * 'SHUTDOWN:\n'
241       + exits the daemon gracefully, pending connections will still be served
242         but no new connections are accepted.
243   * 'VERSION:\n'
244       + prints package and version information.
245   * 'HELP:\n'
246       + gives a short list of available commands.
247
248 Signals
249
250 Rxpd acts on following signals:
251
252   * SIGHUP:
253       + Reload all files from disk
254   * SIGTERM:
255       + Save all files which are already exist on disk and exit
256   * SIGINT:
257       + Exit immediately without saving
258   * SIGALRM:
259       + Save all files which are already exist on disk while continue running
260
261 Using the rxpd
262
263 <!> WIP
264
265 Namespaces
266
267 Rxpd is intended to be used as distributed system, this makes clear that data
268 put into it has to follow some rules to avoid clashing with foreign data. While
269 rxpd doesn't enforce any naming rules I write some suggestions/proposals here.
270
271 Rule lists in rxpd are files, with 0.3 they are organized as directory hierachy
272 under the rules-basedir.
273
274 Most importantly we need to distinguish the authority for a rules list, this
275 can be either a specifc user or some server. For users we use the users email
276 as unique identifier, for servers their hostname will suffice. Further we need
277 to address the purpose or protocol for which a list is primary used and finally
278 the list shall have a descriptive name.
279
280 This triple forms a uniqe identifier for any list.
281
282 Access Policies
283
284 One list of rules can be used to define access policies for the rxpd itself (-p
285 option). Each command will be extended with access protocol (one of tcp4, tcp6
286 or unix) and the peer address and then checked against this policy list. When
287 this check yields in an 'ACCEPT:..' rule, the command is allowed, for
288 everything else will result in an error and drop the connection.
289
290 For example if '-p policy' is used:
291
292 # Syntax:
293 # [atime]:rulename:command:list:proto:address
294 #
295 # Allow dumping of the 'policy' list itself
296 :ACCEPT:DUMP:policy
297 # Clients from local network are allowed to do anything
298 :ACCEPT:.*:tcp.:10\..*$
299 # Forbid all others to do anything else with the policy
300 :REJECT:.*:policy
301 # Finally allow anything else
302 :ACCEPT:.*
303
304 Example
305
306 We want to protect a wiki or such against vandalism: blacklists are in
307 $blacklists.d/ lets say /etc/blacklists.d/
308
309 The wiki engine builds a tuple hostname;ip which is checked against a blacklist
310 which classify the 'hosts'
311
312 this is /etc/blacklist.d/hosts
313
314 # local access are always trusted, thats localhost any my local network
315 :allow:localhost;127.0.0.1
316 :allow:mydomain.org;10.10.
317 # some really bad guys are put on a blacklist which never ever shall get access
318 :deny:.*aol.com;
319 # everyone else shall just get the content checked
320 :check:
321
322 so printf("CHECK:hosts\n%s;%s\n", hostname, ipaddr) send to the blacklist
323 daemon will result in either 'allow', 'deny' or 'check' send back. The first
324 both (allow/deny) results are handled obliviously. With the 'check' result the
325 edited content will be filtered against another list '/etc/blacklists.d/
326 content'
327
328 #example .. see BadContent on this wiki
329 :deny:sex.com
330 :deny:warez
331
332 Demonstation
333
334 <!> WIP <!> Not always running
335
336 Note: there is an almost unrestricted rxpd running here as demo:
337
338 $ echo -e 'LIST:' | nc www.pipapo.org 2345
339 example
340 policy
341
342 $ echo -e 'DUMP:policy' | nc www.pipapo.org 2345
343 # syntax:
344 # rule:command:list:proto:address
345 #
346 # Allow dumping of the 'policy' list itself
347 :ACCEPT:DUMP:policy
348 # Clients from local network are allowed to do anything
349 :ACCEPT:.*:tcp.:10\..*$
350 # Forbid all others to do anything else with the policy
351 :REJECT:.*:policy
352 # Hey and no one shall remotely shutdown this daemon!
353 :REJECT:SHUTDOWN
354 # Finally allow anything else
355 :ACCEPT:.*
356
357 Also checkout the 'HELP:' and 'VERSION:' command. See this documentation for
358 more details.
359
360 This Documentation is maintained at:
361
362   * http://www.pipapo.org/pipawiki/RegexPolicyDaemon/Documentation
363
364 RegexPolicyDaemon/Documentation (last edited 2007-11-02 02:28:10 by ct)
365