- applied patch from Dragos Vingarzan <vingarzan@fokus.fraunhofer.de> which
[sip-router] / doc / dst_blacklist.txt
1 # $Id$
2 #
3 # History:
4 # --------
5 # 2006-09-08  created by andrei
6 #
7
8 Overview
9
10  The destination blacklist (dst_blacklist) is used to try to mark bad
11   destination and avoid possible future expensive send operation to them.
12  A destination is added to the blacklist when trying to send to it fails (e.g.
13  timeout while trying to send or connect on tcp), or when a sip timeout occurs
14  while trying to forward statefully an invite (using tm) and the remote side
15  doesn't send back any response.
16  The blacklist (if enabled) is checked before any send attempt.
17
18
19 Drawbacks
20
21
22  Using the destination blacklist will cause some performance degradation,
23  especially on multi cpu machines. If you don't need it you can easily
24   disable it, either in ser's config or at compile time. Disabling it at
25   compile time is slightly better (but not in a "measurable" way) then
26    disabling it at runtime, from the config file.
27  Whether the destination blacklist is better to be on or off depends a lot
28   on the setup. In general is better to turn it on when:
29    - sending to clients that don't respond is expensive (e.g. lots of clients
30    use tcp and they have the habit of silently discarding tcp traffic from time
31    to time)
32    - statefull forwarding is used (tm) and lower memory usage is desired
33    (a transaction will fail immediately if the destination is already 
34    blacklisted by a previous transaction to the same destination that failed
35    due to timeout)
36    - faster dns failover is desired, especially when statefull forwarding (tm)
37    and udp are used
38    - better chances of DOS survival are important
39
40
41 Config Variables
42
43  use_dst_blacklist = on | off (default off) - enable the destination blacklist:
44   if on each failed send attempt will cause the destination to be blacklisted.
45   Before any send this blacklist will be checked and if a match is found the
46   send is no longer attempted (an error is returned immediately).
47   Note: using the blacklist incurs a small performance penalty.
48
49  dst_blacklist_mem = size in Kb (default 250 Kb) - maximum
50   shared memory amount used for keeping the blacklisted destinations.
51
52  dst_blacklist_expire = time in s (default 60 s) - how much time a 
53   blacklisted destination will be kept in the blacklist (w/o any update).
54
55  dst_blacklist_gc_interval = time in s (default 60 s) - how often the 
56   garbage collection will run (eliminating old, expired entries).
57
58
59 Compile Options
60
61  USE_DST_BLACKLIST - if defined the blacklist support will be compiled-in
62   (default).
63
64
65  Note: To remove a compile options,  edit ser's Makefile.defs and remove it 
66    form DEFS list. To add a compile options add it to the make command line,
67      e.g.: make proper; make all extra_defs=-DUSE_DNS_FAILOVER
68    or for a permanent solution, edit Makefile.defs and add it to DEFS 
69    (don't forget to prefix it with -D).