userblacklist(k): fix some doc errors, pointed out from Daniel Vukicevic, daniel...
[sip-router] / modules_k / userblacklist / README
1 userblacklist Module
2
3 Hardy Kahl
4
5    1&1 Internet AG
6
7 Edited by
8
9 Henning Westerholt
10
11    1&1 Internet AG
12    <henning.westerholt@1und1.de>
13
14    Copyright © 2008 1&1 Internet AG
15      __________________________________________________________________
16
17    Table of Contents
18
19    1. Admin Guide
20
21         1. Overview
22         2. Dependencies
23
24               2.1. Kamailio Modules
25               2.2. External Libraries or Applications
26
27         3. Parameters
28
29               3.1. use_domain (integer)
30               3.2. match_mode (integer)
31
32         4. Functions
33
34               4.1. check_user_blacklist (string user, string domain,
35                       string number, string table)
36
37               4.2. check_user_whitelist (string user, string domain,
38                       string number, string table)
39
40               4.3. check_blacklist ([string table])
41
42         5. MI Commands
43
44               5.1. reload_blacklist
45
46         6. Installation and Running
47
48               6.1. Database setup
49
50    2. Module parameter for database access.
51
52         1. db_url (String)
53         2. userblacklist_table (String)
54         3. userblacklist_id_col (string)
55         4. userblacklist_username_col (string)
56         5. userblacklist_domain_col (string)
57         6. userblacklist_prefix_col (string)
58         7. userblacklist_whitelist_col (string)
59         8. globalblacklist_table (String)
60         9. globalblacklist_id_col (string)
61         10. globalblacklist_prefix_col (string)
62         11. globalblacklist_whitelist_col (string)
63         12. globalblacklist_description_col (string)
64
65    List of Examples
66
67    1.1. Set use_domain parameter
68    1.2. Set match_mode parameter
69    1.3. check_user_blacklist usage
70    1.4. check_user_blacklist usage
71    1.5. check_blacklist usage
72    1.6. reload_blacklists usage
73    1.7. Example database content - globalblacklist table
74    1.8. Example database content - userblacklist table
75    2.1. Set db_url parameter
76    2.2. Set userblacklist_table parameter
77    2.3. Set userblacklist_id_col parameter
78    2.4. Set userblacklist_username_col parameter
79    2.5. Set userblacklist_domain_col parameter
80    2.6. Set userblacklist_prefix_col parameter
81    2.7. Set userblacklist_whitelist_col parameter
82    2.8. Set globalblacklist_table parameter
83    2.9. Set globalblacklist_id_col parameter
84    2.10. Set globalblacklist_prefix_col parameter
85    2.11. Set globalblacklist_whitelist_col parameter
86    2.12. Set globalblacklist_description_col parameter
87
88 Chapter 1. Admin Guide
89
90    Table of Contents
91
92    1. Overview
93    2. Dependencies
94
95         2.1. Kamailio Modules
96         2.2. External Libraries or Applications
97
98    3. Parameters
99
100         3.1. use_domain (integer)
101         3.2. match_mode (integer)
102
103    4. Functions
104
105         4.1. check_user_blacklist (string user, string domain, string
106                 number, string table)
107
108         4.2. check_user_whitelist (string user, string domain, string
109                 number, string table)
110
111         4.3. check_blacklist ([string table])
112
113    5. MI Commands
114
115         5.1. reload_blacklist
116
117    6. Installation and Running
118
119         6.1. Database setup
120
121 1. Overview
122
123    The userblacklist module allows Kamailio to handle blacklists on a per
124    user basis. This information is stored in a database table, which is
125    queried to decide if the number (more exactly, the request URI user) is
126    blacklisted or not.
127
128    An additional functionality that this module provides is the ability to
129    handle global blacklists. This lists are loaded on startup into memory,
130    thus providing a better performance then in the userblacklist case.
131    This global blacklists are useful to only allow calls to certain
132    international destinations, i.e. block all not whitelisted numbers.
133    They could also used to prevent the blacklisting of important numbers,
134    as whitelisting is supported too. This is useful for example to prevent
135    the customer from blocking emergency call number or service hotlines.
136
137    The module exports three functions, check_blacklist
138    check_user_blacklist and check_user_whitelist for usage in the config
139    file. Furthermore its provide a FIFO function to reload the global
140    blacklist cache.
141
142    Please note that only numerical strings for matching are supported at
143    the moment (the used library supports this already, but its not yet
144    implemented in the module). Non-digits on the beginning of the matched
145    string are skipped, any later non-digits will stop the matching on this
146    position.
147
148 2. Dependencies
149
150    2.1. Kamailio Modules
151    2.2. External Libraries or Applications
152
153 2.1. Kamailio Modules
154
155    The module depends on the following modules (in the other words the
156    listed modules must be loaded before this module):
157      * database -- Any database module
158
159 2.2. External Libraries or Applications
160
161    The following libraries or applications must be installed before
162    running Kamailio with this module loaded:
163      * none
164
165 3. Parameters
166
167    3.1. use_domain (integer)
168    3.2. match_mode (integer)
169
170 3.1. use_domain (integer)
171
172    If set to non-zero value, the domain column in the userblacklist is
173    used.
174
175    Default value is “0”.
176
177    Example 1.1. Set use_domain parameter
178 ...
179 modparam("userblacklist", "use_domain", 0)
180 ...
181
182 3.2. match_mode (integer)
183
184    The number of individual characters that are used for matching. Valid
185    values are 10 or 128. When you specifiy 10, only digits will be used
186    for matching, this operation mode is equivalent to the old behaviour.
187    When configured with 128, all standard ascii chars are available for
188    matching. Please be aware that memory requirements for storing the
189    routing tree in shared memory will also increase by a factor of 12.8.
190
191    Default value is “10”.
192
193    Example 1.2. Set match_mode parameter
194 ...
195 modparam("userblacklist", "match_mode", 128)
196 ...
197
198 4. Functions
199
200    4.1. check_user_blacklist (string user, string domain, string number,
201           string table)
202
203    4.2. check_user_whitelist (string user, string domain, string number,
204           string table)
205
206    4.3. check_blacklist ([string table])
207
208 4.1.  check_user_blacklist (string user, string domain, string number, string
209 table)
210
211    Finds the longest prefix that matches the request URI user (or the
212    number parameter) for the given user and domain name in the database.
213    If a match is found and it is not set to whitelist, false is returned.
214    Otherwise, true is returned. Pseudo-variables or AVPs can be used for
215    the user, domain and number parameters. The number and table variables
216    are optional, the defaults are used if they are ommited. The number
217    parameter can be used to check for example against the from URI user.
218
219    Example 1.3. check_user_blacklist usage
220 ...
221 $avp(i:80) = $rU;
222 # rewrite the R-URI
223 if (!check_user_blacklist("$avp(i:80)", "$avp(i:82)")) {
224         sl_send_reply("403", "Forbidden");
225         exit;
226 }
227 ...
228
229 4.2.  check_user_whitelist (string user, string domain, string number, string
230 table)
231
232    Finds the longest prefix that matches the request URI user (or the
233    number parameter) for the given user and domain name in the database.
234    If a match is found and it is set to whitelist, true is returned.
235    Otherwise, false is returned. Pseudo-variables or AVPs can be used for
236    the user, domain and number parameters. The number and table variables
237    are optional, the defaults are used if they are ommited. The number
238    parameter can be used to check for example against the from URI user.
239
240    Example 1.4. check_user_blacklist usage
241 ...
242 $avp(i:80) = $rU;
243 # rewrite the R-URI
244 if (!check_user_whitelist("$avp(i:80)", "$avp(i:82)")) {
245         # process request
246         exit;
247 }
248 ...
249
250 4.3.  check_blacklist ([string table])
251
252    Finds the longest prefix that matches the request URI for the given
253    table. If a match is found and it is not set to whitelist, false is
254    returned. Otherwise, true is returned. If no table is given, then
255    globalblacklist_table is used.
256
257    Example 1.5. check_blacklist usage
258 ...
259 if (!check_blacklist("globalblacklist")) {
260         sl_send_reply("403", "Forbidden");
261         exit;
262 }
263 ...
264
265 5. MI Commands
266
267    5.1. reload_blacklist
268
269 5.1.  reload_blacklist
270
271    Reload the internal global blacklist cache. This is necessary after the
272    database tables for the global blacklist have been changed.
273
274    Example 1.6. reload_blacklists usage
275 ...
276 kamctl fifo reload_blacklist
277 ...
278
279 6. Installation and Running
280
281    6.1. Database setup
282
283 6.1. Database setup
284
285    Before running Kamailio with userblacklist, you have to setup the
286    database table where the module will read the blacklist data. For that,
287    if the table was not created by the installation script or you choose
288    to install everything by yourself you can use the
289    userblacklist-create.sql SQL script in the database directories in the
290    kamailio/scripts folder as template. Database and table name can be set
291    with module parameters so they can be changed, but the name of the
292    columns must be as they are in the SQL script. You can also find the
293    complete database documentation on the project webpage,
294    http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
295
296    Example 1.7. Example database content - globalblacklist table
297 ...
298 +----+-----------+-----------+
299 | id | prefix    | whitelist |
300 +----+-----------+-----------+
301 |  1 |           |         0 |
302 |  2 | 1         |         1 |
303 |  3 | 123456    |         0 |
304 |  4 | 123455787 |         0 |
305 +----+-----------+-----------+
306 ...
307
308    This table will setup a global blacklist for all numbers, only allowing
309    calls starting with “1”. Numbers that starting with “123456” and
310    “123455787” are also blacklisted, because the longest prefix will be
311    matched.
312
313    Example 1.8. Example database content - userblacklist table
314 ...
315 +----+----------------+-------------+-----------+-----------+
316 | id | username       | domain      | prefix    | whitelist |
317 +----+----------------+-------------+-----------+-----------+
318 | 23 | 49721123456788 |             | 1234      |         0 |
319 | 22 | 49721123456788 |             | 123456788 |         1 |
320 | 21 | 49721123456789 |             | 12345     |         0 |
321 | 20 | 494675231      |             | 499034133 |         1 |
322 | 19 | 494675231      | test        | 499034132 |         0 |
323 | 18 | 494675453      | test.domain | 49901     |         0 |
324 | 17 | 494675454      |             | 49900     |         0 |
325 +----+----------------+-------------+-----------+-----------+
326 ...
327
328    This table will setup user specific blacklists for certain usernames.
329    For example for user “49721123456788” the prefix “1234” will be not
330    allowed, but the number “123456788” is allowed. Additionally a domain
331    could be specified that is used for username matching if the
332    “use_domain” parameter is set.
333
334 Chapter 2. Module parameter for database access.
335
336    Table of Contents
337
338    1. db_url (String)
339    2. userblacklist_table (String)
340    3. userblacklist_id_col (string)
341    4. userblacklist_username_col (string)
342    5. userblacklist_domain_col (string)
343    6. userblacklist_prefix_col (string)
344    7. userblacklist_whitelist_col (string)
345    8. globalblacklist_table (String)
346    9. globalblacklist_id_col (string)
347    10. globalblacklist_prefix_col (string)
348    11. globalblacklist_whitelist_col (string)
349    12. globalblacklist_description_col (string)
350
351 1. db_url (String)
352
353    URL to the database containing the data.
354
355    Default value is “mysql://openserro:openserro@localhost/openser”.
356
357    Example 2.1. Set db_url parameter
358 ...
359 modparam("userblacklist", "db_url", "dbdriver://username:password@dbhost/dbname"
360 )
361 ...
362
363 2. userblacklist_table (String)
364
365    Name of the userblacklist table for the userblacklist module.
366
367    Default value is “userblacklist”.
368
369    Example 2.2. Set userblacklist_table parameter
370 ...
371 modparam("userblacklist", "userblacklist_table", "userblacklist")
372 ...
373
374 3. userblacklist_id_col (string)
375
376    unique ID
377
378    Example 2.3. Set userblacklist_id_col parameter
379 ...
380 modparam("userblacklist", "userblacklist_id_col", "id")
381 ...
382
383 4. userblacklist_username_col (string)
384
385    The user that is used for the blacklist lookup.
386
387    Example 2.4. Set userblacklist_username_col parameter
388 ...
389 modparam("userblacklist", "userblacklist_username_col", "username")
390 ...
391
392 5. userblacklist_domain_col (string)
393
394    The domain that is used for the blacklist lookup.
395
396    Example 2.5. Set userblacklist_domain_col parameter
397 ...
398 modparam("userblacklist", "userblacklist_domain_col", "domain")
399 ...
400
401 6. userblacklist_prefix_col (string)
402
403    The prefix that is matched for the blacklist.
404
405    Example 2.6. Set userblacklist_prefix_col parameter
406 ...
407 modparam("userblacklist", "userblacklist_prefix_col", "prefix")
408 ...
409
410 7. userblacklist_whitelist_col (string)
411
412    Specify if this a blacklist (0) or a whitelist (1) entry.
413
414    Example 2.7. Set userblacklist_whitelist_col parameter
415 ...
416 modparam("userblacklist", "userblacklist_whitelist_col", "whitelist")
417 ...
418
419 8. globalblacklist_table (String)
420
421    Name of the globalblacklist table for the userblacklist module. Please
422    note that this table is used when the check_blacklist function is
423    called with no parameters.
424
425    Default value is “globalblacklist”.
426
427    Example 2.8. Set globalblacklist_table parameter
428 ...
429 modparam("userblacklist", "globalblacklist_table", "globalblacklist")
430 ...
431
432 9. globalblacklist_id_col (string)
433
434    unique ID
435
436    Example 2.9. Set globalblacklist_id_col parameter
437 ...
438 modparam("userblacklist", "globalblacklist_id_col", "id")
439 ...
440
441 10. globalblacklist_prefix_col (string)
442
443    The prefix that is matched for the blacklist.
444
445    Example 2.10. Set globalblacklist_prefix_col parameter
446 ...
447 modparam("userblacklist", "globalblacklist_prefix_col", "prefix")
448 ...
449
450 11. globalblacklist_whitelist_col (string)
451
452    Specify if this a blacklist (0) or a whitelist (1) entry.
453
454    Example 2.11. Set globalblacklist_whitelist_col parameter
455 ...
456 modparam("userblacklist", "globalblacklist_whitelist_col", "whitelist")
457 ...
458
459 12. globalblacklist_description_col (string)
460
461    A comment for the entry.
462
463    Example 2.12. Set globalblacklist_description_col parameter
464 ...
465 modparam("userblacklist", "globalblacklist_description_col", "description")
466 ...