db_sqlite: rename database scheme files, to allow automatic updates
[sip-router] / NEWS
1 Release notes for SIP Router (sr)
2 ***********************************************
3
4 $Id$
5
6 sip-router 3.1 chages
7
8 core:
9   - Dragonfly BSD support
10   - statistics / counters support for tcp and sctp (enable by default)
11   - statistics / counters api
12   - networks addresses support in ip comparisons (src_ip, dst_ip, to_ip)
13     with strings or rvalue expressions.
14     E.g.: $ip=10.0.0.0;  if (src_ip == $ip +"/8") ....
15   - lots of module functions automatically support now expressions or
16       variables in function parameters. This applies to all the module
17       functions declared without a fixup, with a fixup and the corresponding
18       free_fixup function or with a compatible ser or kamailio style standard
19       fixup (declared in sr_module.h or mod_fix.h).
20       E.g.: f($a, "b = " + $b);  t_set_fr($v + 2 + $x).
21             t_set_fr($foo) (equivalent now with t_set_fr("$foo")).
22   - all the module functions can now be called with any constant expression
23       as parameters. E.g.: f("7 *" +" 6 = " + 7 * 6);
24   - major performance increase on Linux multi-cpu machines that send a lot
25      of UDP IPv4 packets (40-50% faster in stateless mode). For it to work
26      udp4_raw must be enabled or set into auto mode in sr.cfg and sr must be
27      started as root or with CAP_NET_RAW. Note that even if udp4_raw is
28      off (default), if sr was started with enough privileges, it can be
29      enabled at runtime.
30      The support for using raw sockets is also available on FreeBSD (compiled
31      by default but not tested for performance yet), NetBSD, OpenBSD and
32      Darwin (not tested and not compiled by default, needs
33      make cfg extra_defs=-DUSE_RAW_SOCKS). To check if the support is
34      compiled, use ser -V |grep --color RAW_SOCKS or for a running
35      ser: sercmd core.udp4_raw_info.
36      See udp4_raw, udp4_raw_mtu and udp4_raw_ttl below.
37   - asynchronous TLS support
38   - onreply_route {...} is now equivalent with onreply_route[0] {...}
39   - global, per protocol blacklist ignore masks (via extended send_flags).
40     See dst_blacklist_udp_imask a.s.o (dst_blacklist_*_imask).
41   - per message blacklist ignore masks
42   - route() now supports rvalue expressions (e.g. route("test"+$i))
43   - support for permanent entries in the DNS cache.
44
45 new config variables:
46   - udp4_raw - enables raw socket support for sending UDP IPv4 datagrams 
47       (40-50% performance increase on linux multi-cpu).
48       Possible values: 0 - disabled (default), 1 - enabled, -1 auto.
49       In "auto" mode it will be enabled if possible (sr started as root or
50       with CAP_NET_RAW).
51       udp4_raw can be used on Linux and FreeBSD. For other BSDs and Darwin
52       one must compile with -DUSE_RAW_SOCKS.
53       On Linux one should also set udp4_raw_mtu if the MTU on any network
54       interface that could be used for sending is smaller then 1500.
55       Can be set at runtime as long as sr was started with enough privileges
56       (core.udp4_raw).
57   - udp4_raw_mtu - MTU value used for UDP IPv4 packets when udp4_raw is
58       enabled.  It should be set to the minimum MTU of all the network
59       interfaces that could be used for sending. The default value is 1500.
60       Note that on BSDs it does not need to be set (if set it will be ignored,
61       the proper MTU will be used automatically by the kernel). On Linux it
62       should be set.
63       Can be set at runtime (core.udp4_raw_mtu).
64   - udp4_raw_ttl - TTL value used for UDP IPv4 packets when udp4_raw is
65       enabled. By default it is set to auto mode (-1), meaning that the
66       same TTL will be used as for normal UDP sockets.
67       Can be set at runtime (core.udp4_raw_ttl).
68   - dst_blacklist_udp_imask - global blacklist events ignore mask for udp
69     (a blacklist event/reason set in this variable will be ignored when 
70     deciding whether or not to blacklist an udp destination). Can be set
71     at runtime. Default: 0 (no blacklist reason is ignored).
72     Possible values:  0 -disabled, 2 - send error; 4 - connect error,
73                       8 - icmp (reserverd), 16 - transaction timeout,
74                      32 - 503 received, 64 - administratively prohibited
75                      (manually set).
76    - dst_blacklist_tcp_imask - like dst_blacklist_udp_imask, but for tcp.
77    - dst_blacklist_tls_imask - like dst_blacklist_tls_imask, but for tcp.
78    - dst_blacklist_sctp_imask -like dst_blacklist_sctp_imask, but for tcp.
79    - dns_cache_rec_pref - DNS cache record preference:
80                 0 - do not check duplicates (default)
81                 1 - prefer old records
82                 2 - prefer new records
83                 3 - prefer records with longer lifetime
84
85 modules:
86    - counters: functions and RPCs for manipulating counters (statistics):
87            modparam("counters", "script_counter", name)
88            cnt_inc(name)
89            cnt_add(name, val)
90            cnt_reset(name)
91    - blst: functions for ignoring blacklist events per message:
92            blst_set_ignore(mask):  set the events in mask in the per
93             per message blacklist ignore mask for a request
94             (see dst_blacklist_udp_imask for possible values).
95             The basic operation is: msg_blst_ignore_mask|=mask.
96            blst_clear_ignore(mask): like blst_set_ignore(mask), but instead
97             of setting some events, it clears them
98             (msg_blst_ignore_mask&=~mask).
99            blst_rpl_set_ignore(mask): like blst_set_ignore(mask), but sets
100             the mask for possible local replies to the current message.
101            blst_rpl_clear_ignore(mask): like blst_rpl_ignore(mask), but
102             clears instead of setting.
103    - tls:
104           certificate revocation list (CRL) support.
105           asynchronous TLS support
106           new TLS RPCs (tls.info, tls.options), tls.list more detailed.
107           removed handshake_timeout and send_timeout module parameters /
108             config variables. The values from tcp are used instead
109             (tcp_connect_timeout and tcp_send_timeout).
110           runtime config support
111           more config options:
112             crl - certificate revocation list file path (PEM format).
113             send_close_notify - enables/disables sending close notify
114               alerts prior to closing the corresponding TCP connection.
115               Sending the close notify prior to tcp shutdown is "nicer"
116               from a TLS point of view, but it has a measurable
117               performance impact. Default: off. Can be set at runtime
118               (tls.send_close_notify).
119             con_ct_wq_max - per connection tls maximum clear text write
120               queue size.  The TLS clear-text write queues are used when a
121               send attempt has to be delayed due to an on-going TLS level
122               renegotiation. Can be set at runtime (tls.con_ct_wq_max).
123               Default: 65536 (64 Kb).
124             ct_wq_max - maximum total for all the tls clear text write
125               queues (summed). Can be set at runtime (tls.ct_wq_max).
126               Default: 10485760 (10 Mb).
127             ct_wq_blk_size - internal TLS pre-write (clear-text) queue
128               minimum block size (advance tunning or debugging).
129               Can be set at runtime (tls.ct_wq_blk_size).
130               Default: 4096 (4 Kb).
131           verbose debug messages can be enable by re-compiling with
132             -DTLS_RD_DEBUG (for the read path) and -DTLS_WR_DEBUG
133             (for the write path).
134           new options for better tuning memory usage for modern openssl
135             versions: ssl_release_buffers (default 1), ssl_freelist_max_len
136             (default 0), ssl_max_send_fragment, ssl_read_ahead (default 0).
137             For more info see modules/doc/tls/README.
138           compression is now disabled by default. To enable it set
139             tls_disable_compression to 0, but note that memory usage will
140             increase dramatically especially for large number of
141             connections (>1000).
142 tm:
143    - reason header support (RFC3326) both for CANCELs generated due to a
144       received final reply and for hop by hop CANCELs generated because of a
145       received CANCEL.
146       E.g.: reason header added for a CANCEL generated after a 200 reply was
147             received on one of the branches "Reason: SIP;cause=200".
148       The reason header support can be turned on/off using either tm
149       module parameters or in the end to end CANCEL case also on a per
150       transaction basis, using a script function:
151        local_cancel_reason = 0 | 1 (default 1/on) - turns on adding reason
152          headers for CANCELs generated due to a final reply. Can be changed
153          at runtime.
154        e2e_cancel_reason = 0 | 1 (default 1/on) - turns on copying reason
155          headers from a received end to end CANCEL (the generated hop by hop
156          CANCELs will have the same reason headers as the received CANCEL).
157          Can be changed at runtime.
158        t_set_no_e2e_cancel_reason(0|1) - enable/disable cancel reason 
159          header copying on a per transaction basis (0 - enable, 1 disable).
160    - t_reply() can be used both from the main/core onreply_route{} and tm
161      onreply_route[...]{}s.
162
163
164
165 sip-router 3.0 changes
166
167 core:
168   - type casts operators: (int), (str).
169   - new operators eq, ne for string compares and ieq, ine for interger 
170     compares. The names are not yet final (use them at your own risk).
171     Future version might use ==/!= only for ints (ieq/ine) and eq/ne for
172     strings (under debate).
173     They are almost equivalent to == or !=, but they force the conversion 
174     of their operands (eq to string and ieq to int), allowing among other
175     things better type checking on startup and more optimizations.
176     Non equiv. examples: 0 == "" (true) is not equivalent to 0 eq ""
177     (false: it evaluates to "0" eq ""). "a" ieq "b" (true: (int)"a" is 0
178      and (int)"b" is 0) is not equivalent to "a" == "b" (false).
179     Note: internally == and != are converted on startup to eq/ne/ieq/ine 
180     whenever possible (both operand types can be safely determined at
181     start time and they are the same).
182   - try to guess what the user wanted when operators that support multiple
183      types are used on different typed operands. In general convert the
184      the right operand to the type of the left operand and then perform the
185      operation. Exception: the left operand is undef.
186      This applies to the following operators: +, == and !=.
187      Special case: undef as left operand:
188      For +: undef + expr -> undef is converted to string => "" + expr.
189      For == and !=:   undef == expr -> undef is converted to type_of expr.
190      If expr is undef, then undef == undef is true (internally is converted
191      to string).
192   - expression evaluation changes: auto-convert to interger or string
193      in function of the operators: 
194        int(undef)==0,  int("")==0, int("123")==123, int("abc")==0
195        str(undef)=="", str(123)=="123".
196   - new script operators: defined, strlen, strempty
197       defined expr - returns true if expr is defined, and false if not.
198                      Note: only a standalone avp or pvar can be
199                      undefined, everything else is defined.
200       strlen(expr) - returns the lenght of expr evaluated as string.
201       strempty(expr) - returns true if expr evaluates to the empty
202                        string (equivalent to expr=="").
203     e.g.: if (defined $v && !strempty($v)) $len=strlen($v);
204   - msg:len max_len comparison obsoleted and removed (it did not make any
205     sense, msg:len > max_len was always false, use something like 
206     4096 or 16384 in its place).
207   - module search path support: loadpath takes now a list of directories
208     separated by ':'. The list is searched in-order. For each directory d
209     $d/${module_name}.so and $d/${module_name}/${module_name}.so are tried.
210   - dns TXT, EBL and PTR support (both cache and non-cached resolver)
211   - support for dual module interfaces: ser and kamailio
212 config script changes:
213   - script mode can be switched between ser compatible, kamailio compatible
214     and max compatibility (compatible with both as much as possible), using
215       #!SER
216       #!KAMAILIO
217       #!OPENSER
218       #!ALL
219       #!MAXCOMPAT
220     where #!KAMAILIO is equivalent with #!OPENSER and #!ALL with #!MAXCOMPAT
221   - support for kamailio style pvars
222   - C-like switch()/case (integer only)
223   - while()
224   - include file support: include_file "somefile"
225   - event route support: event_route[module_name:eventid]
226   - user and shm_force_alloc must now appear prior to any modparam() or route
227      block.
228   - per message send_flags support (see set_forward_no_connect(),
229      set_forward_reply_no_connect(), set_forward_close() & set_reply_close())
230
231 build system:
232   - multiple modules directories are now supported (defined in Makefile.dirs)
233
234 new config variables:
235   - max_while_loops - maximum iterations allowed for a while  (can be changed
236        at runtime). Default 100.
237   - log_name - set the application name used when printing to syslog.
238   - mem_summary - memory debugging info logged on exit or on SIGUSR1.
239        The value is a combination of flags: 0 - off,
240        1 - dump all used memory blocks and some statistics (lots of output),
241        2 - dump a summary of the used memory blocks (works only if
242            compiled with DBG_QM_MALLOC or DBG_F_MALLOC).
243        Default: 1.
244        Can be changed at runtime.
245   - shm = number  or shm_mem = number  - size of shared memory in MB. It's
246        overwritten if a value is specified on the command line (-m val).
247        Default: 32 Mb. Must appear prior to any modparam() or route block.
248
249 new script commands:
250   add_local_rport() - adds the rport parameter to the added via header
251        (rfc3581).
252   set_forward_no_connect() - the message will be forwarded only if there is
253        already an existing connection to the destination (it applies only to
254        connection oriented protocols like tcp, tls and in the future sctp).
255   set_reply_no_connect() - like set_forward_no_connect(),  but works for
256        replies to the current message.
257   set_forward_close()  - try to close the connection after forwarding the
258        current message (it applies only when the underlying protocol is
259        connection oriented).
260   set_reply_close() - like set_forward_close(), but it works for replies to
261        the current message.
262
263 tm:
264   disable_6xx_block parameter - if set, will treat 6xx replies like normal
265        replies (non rfc conformant). Default: off.
266        See also t_set_disable_6xx().
267   t_set_disable_6xx(0|1) - can be used to turn off/on the special 6xx handling
268        on a per transaction basis.
269   t_set_disable_failover(0|1) - can be used to turn off/on dns failover on a
270        per transaction basis.
271
272
273
274 2.1.0 changes
275
276 modules:
277  - textops   - functions:
278                         - remove_hf_re("regexp") -- filter message headers out
279                           by matching the header name field against a regular
280                           expression.
281  - avp       - export new selects table to allow dissecting the content of an
282                attribute by interpreting it as a "name-addr" value 
283  - auth      - experimental support for one-time nonces: when enabled a nonce
284                will be accepted only for one response (each new request will
285                be challenged). See one_time_nonce.
286              - experimental support for nc checking when qop=auth
287                (fast, non-locking implementation, see nonce_count, 
288                 nc_array_size, nc_array_order and nid_pool_no) 
289              - switched to base64 nonces
290              - record nonce generation time inside the nonce so that a 
291                received nonce can be checked against ser start time
292                (if older => stale). This allows gracefully handling ser
293                restarts with different auth configs.
294              - added extra authentication checks support, to protect
295                against various reply attacks.
296              - params:
297                        - nonce_auth_max_drift - maximum difference in seconds
298                           from the current time, if a nonce appears to be
299                           created in the future (if exceeded the nonce is 
300                           considered stale).
301                        - one_time_nonce - if enabled each nonce is allowed 
302                           only once => each new request (including 
303                           retransmissions!) will be challenged. It should be
304                           used only in stateful mode (so that tm deals with
305                           the retransmissions). The major disadvantage is that
306                           the UA won't be able to used any cached credentials
307                           (=> extra messages, extra round trips, more work for
308                            the proxy)
309                        - otn_in_flight_no - maximum number of in-flight nonces
310                           for one-time-nonces. It must be a number of the form
311                           2^k (if not it will be automatically rounded down).
312                           The memory used will be otn_in_flight_no/8
313                        - otn_in_flight_order - like otn_in_flight_no, but 
314                           instead of specifying the number as 2^k, it directly
315                           sets k (otn_in_flight_no=2^otn_in_flight_order)
316                        - nonce_count - if enabled and qop=auth or 
317                           qop=auth-int, store and check received nc values
318                           (for details see rfc2617 and auth/doc). It should be
319                           used only in stateful mode (so that tm deals with
320                           the retransmissions which would otherwise be 
321                           challenged). The major advantage is greatly 
322                           enhanced security (extremely small probability of
323                           a succesfull replay attack) combine with support
324                           for cached credentials (if the UAs do support qop 
325                           and auth)
326                        - nc_array_size - size of the array used for storing
327                           nc values, default 1Mb. It will be rounded down to
328                           a 2^k value. It represents the maximum number of
329                           in-flight nonces supported
330                        - nc_array_order - equivalent to nc_array_size, but 
331                           instead of specifying the size in bytes, it can 
332                           be used to directly set the power of 2 used
333                           (nc_array_size=2^nc_array_order)
334                        - nid_pool_no - number of nc and one-time-nonce array 
335                           and index partitions, useful for increasing 
336                           performance on multi-cpu systems (default 1,
337                           recommended 4)
338                        - auth_checks_register, auth_checks_no_dlg, 
339                          auth_checks_in_dlg - flags specifying which extra
340                           message part/parts will be checked for change before
341                           allowing nonce reuse. See the auth module docs for
342                           for more information (modules/auth/README).
343  - blst      - new module containing script blacklist manipulations functions
344                (the source of a message can be blacklisted, removed from the
345                 blacklist or checked for presence in the blacklist).
346  - tm        - added API function t_get_canceled_ident(): returns the hash 
347                coordinates (bucket/index) of the transaction the currently 
348                processed CANCEL is targeting. Requires AS support enabled.
349              - added API function ack_local_uac(): allow generating the ACKs 
350                for 2xx'ed locally originated INVITEs - new headers and body can
351                now also be appended to it. Requires AS support enabled.
352              - matching of E2E ACKs no longer requires full From HF identity,
353                but rather only tag equality (this behaviour can be changed by
354                defining TM_E2E_ACK_CHECK_FROM_URI)
355              - added t_reset_fr(), t_reset_retr(), t_reset_max_lifetime()
356              - t_relay_to renamed to t_relay_to_avp (undocumented function)
357              - t_relay() can now also take host and port parameters (e.g.
358                t_relay(host, port)), behaving like a statefull 
359                forwad(host, port) version (forward to host:port using the same
360                protocol on which the message was received)
361              - t_relay_to_udp(), t_relay_to_tcp() and t_relay_to_tls() work
362                now even with no parameters: in this case the message is 
363                forwarded using the request uri, but with the specified protocol
364                (equivalent to a t_relay() with a forced protocol)
365              - method for canceling unreplied branches can now be selected
366                using the new cancel_b_method tm parameter.
367              - support for adding a 503 reply source to the blacklist for
368                the time specified in the Retry-After header (see the new tm
369                parameters blst_503, blst_503_def_timeout, blst_503_min_timeout
370                and blst_503_max_timeout).
371              - different error replies for too many branches (500 but with
372                different text), resolve error (478) or send error
373                (477).
374              - tm can be configured not to automatically send 100 replies
375                for invites either globally (see the auto_inv_100 parameter)
376                or on a per transaction basis (see t_set_auto_inv_100(...))
377              - t_relay* error reply are delayed till the end of the script
378                to allow the script writer to overwrite them
379              - branches are always canceled hop by hop
380              - cancels for silently canceled branches (no replies ever 
381                received) are automatically generated if later a provisional
382                reply arrives on such a branch
383              - noisy_ctimer is now 1 (on) by default
384              - added maximum transaction lifetime - a transaction is not
385                allowed to be active longer then this interval. See
386                t_set_max_lifetime(), max_inv_lifetime and max_noninv_lifetime.
387              - support for changing the retransmission intervals on the fly,
388                on a per transaction basis (it is enabled if tm is compiled
389                with -DTM_DIFF_RT_TIMEOUT -- default): t_set_retr(t1, t2).
390              - transaction are deleted the moment they are not referenced 
391                anymore (removed the need for the delete timer) -- this 
392                should improve memory usage on very busy proxies.
393              - lots of callbacks added
394              - new onsend callbacks support (require defining TMCB_ONSEND prior
395                to compiling tm)
396              - behaviour when receiving a CANCEL which doesn't match any 
397                transaction can be selected using the unmatched_cancel param.
398              - params: 
399                         - cancel_b_method - selects one of the three methods
400                           for dealing with unreplied branches when the 
401                           transaction must be canceled. The possible values
402                           are 0 (old behaviour) for stopping request 
403                           retransmission on the branch and act as if 
404                           the branch was immediately replied with a 487,
405                           1 for continuing to retransmit the request until an
406                           answer is received or the timeout kicks in (default)
407                           and
408                           2 for stopping the request retransmission and sending
409                           CANCEL on the branch (not rfc conforming).
410                           For more information see tm docs.
411                         - blst_503 - if set and if the blacklist is used
412                           (use_dst_blacklist=1), add the source of a 503 reply
413                           to the blacklist
414                         - blst_503_def_timeout - if the Retry-After header from
415                           a 503 reply is missing, use this value for the 
416                           blacklist timeout (in s). Depends on blst_503.
417                           The default value is 0 ( do not blacklist if no
418                           Retry-After is present).
419                         - blst_503_min_timeot (in s) - if the 503 reply 
420                           Retry-After header value is less, use this value
421                           for the blacklist timeout. Depends on blst_503.
422                           The default value is 0.
423                         - blst_503_max_timeout (in s) - if the 503 reply 
424                           Retry-After header value is greater, use this value
425                           instead. Depends on blst_503.
426                           The default value is 3600 s.
427                         - auto_inv_100 - if set (default) tm will automatically
428                           send an 100 reply to INVITEs (see also 
429                          t_set_auto_inv_100())
430                         - noisy_ctimer is now 1 by default
431                         - max_inv_lifetime & max_noninv_lifetime - default
432                           maximum lifetimes for an invite or non-invite 
433                           transaction. After this interval has passed from 
434                           the transaction creation the transaction will be 
435                           either switched into the wait state or in the
436                           final response retransmission state => a transaction
437                           will be kept in memory for maximum: 
438                            max_*inv_lifetime + fr_timer /*ack w.*/ +wait_timer.
439                         - unmatched_cancel - selects between forwarding cancels
440                            that do not match any transaction statefully (0, 
441                            default value), statelessly (1) or dropping them
442                            (2). Note that the statefull forwarding has an 
443                            additional hidden advantage: tm will be able to
444                            recognize INVITEs that arrive after their CANCEL.
445                            Note also that this feature could be used to try
446                            a memory exhaustion DOS attack against a proxy that
447                            authenticates all requests, by continuously flooding
448                            the victim with CANCELs to random destinations 
449                            (since the CANCEL cannot be authenticated, each
450                            received bogus CANCEL will create a new transaction 
451                            that will live by default 30s).
452              - functions:
453                         - t_reset_fr() -- resets the current transaction 
454                           fr_inv_timer and fr_timer to the default values
455                           (set via the tm modparams fr_inv_timer and fr_timer).
456                         - t_reset_retr() -- resets the current transaction
457                           retransmission intervals on the fly, to the default
458                           values (set via the tm modparams retr_timer1 and 
459                           retr_timer2).
460                         - t_reset_max_lifetime() -- resets the current 
461                           transaction maximum lifetime to the default value
462                           (set via the tm  modparam max_inv_lifetime or 
463                            max_noninv_lifetime).
464                         - t_grep_status("code") -- returns true if any branch
465                           received code as the final reply (or if no final 
466                           reply was yet received, but a "code" provisional 
467                           reply).
468                         - t_set_auto_inv_100(on/off) - switch automatically
469                           sending 100 replies to INVITEs on/off on a per
470                           transaction basis. It overrides the tm param.
471                           auto_inv_100.
472                         - t_set_max_lifetime(inv, noninv) - changes the 
473                           maximum transaction lifetime on the fly, for the
474                           current or next to be created transaction.
475                         - t_set_retr(t1, t2) - changes the retransmissions
476                            intervals on the fly, on a per transaction basis.
477 core:
478              - most tcp config vars migrated to the dynamic config framework
479                (can be changed at runtime, e.g. 
480                  sercmd cfg.set_now_int tcp connection_lifetime 180 )
481              - fallback to tcp or other congestion controlled transport 
482                protocol if a forwarded udp sip request is greater then 
483                udp_mtu (config). Default off. See udp_mtu and 
484                udp_mtu_try_proto.
485              - sctp support (one-to-many, work in progress, for now linux
486                and freebsd only)
487              - partial cygwin (windows) support revived: core+static modules, 
488                no ipv6, no tcp, no dynamic modules
489              - most of the config variables can now be changed on the fly,
490                without ser restart  (migration work in progress)
491              - tcp improvements (better tcp timers, send fd cache, special
492                 options support)
493              - dns naptr support (see dns_try_naptr and dns_<proto>_pref)
494              - dns srv based load balancing support (see dns_srv_lb)
495              - support for locking ser's pages in memory, pre-mapping
496                all the shared memory on startup (fill it with 0)
497              - real time options
498              - devel: new PROC_INIT rank, init_child(PROC_INIT) called first
499              - futex support on linux (better behaviour when waiting on 
500                long held locks, almost no performance impact otherwise)
501              - when dns search list was used for resolution, store the "link"
502                between the short name and long name in cache as CNAME record
503
504 new config variables:
505   tcp_rd_buf_size = buffer size used for tcp reads.
506                     A high buffer size increases performance on server with few
507                     connections and lot of traffic on them, but also increases
508                      memory consumption (so for lots of connection is better 
509                     to use a low value). Note also that this value limits the
510                     maximum datagram size that can be received over tcp.
511                     Default: 4096, can be changed at runtime.
512   tcp_wq_blk_size = block size used for tcp async writes. It should be big
513                     enough to hold a few datagrams. If it's smaller then a
514                     datagram (in fact a tcp write()) size, it will be rounded
515                     up. It has no influenced on the number of datagrams 
516                     queued (for that see tcp_conn_wq_max or tcp_wq_max).
517                     It has mostly debugging and testing value (can be ignored).
518                     Default: 2100 (~ 2 INVITEs), can be changed at runtime.
519   tcp_no_connect = yes/no - disable connects, ser will only accept new 
520                      connections, it will never try to open new ones.
521                      Default: no, can be changed at runtime.
522   udp_mtu = number - fallback to another protocol (udp_mtu_try_proto must be
523                      set also either globally or per packet) if the constructed
524                      request size is greater then udp_mtu.
525                      Recommended size: 1300. Default: 0 (off).
526   udp_mtu_try_proto = TCP|TLS|SCTP|UDP - if udp_mtu !=0 and udp forwarded
527                      request size (after adding all the "local" headers) >
528                      udp_mtu, use this protocol instead of udp. Only the
529                      Via header will be updated (e.g. The Record-Route
530                      will be the one built for udp).
531                      Default: UDP (off). Recommended: TCP.
532   force_rport =yes/no - like force_rport(), but works globally.
533   disable_sctp = yes/no - disable sctp support (default auto, see enable_sctp)
534   enable_sctp = 0/1/2  - disable (0)/enable (1)/auto (2) sctp support, 
535                          default auto (2)
536   sctp_children = number - sctp children no (similar to udp children)
537   sctp_socket_rcvbuf = number - size for the sctp socket receive buffer
538   sctp_socket_sndbuf = number - size for the sctp socket send buffer
539   sctp_autoclose = seconds - number of seconds before autoclosing an idle
540                    association (default: 180 s).
541                    Can be changed at runtime, but it will affect only new
542                    associations. E.g.:
543                    $ sercmd cfg.set_now_int sctp autoclose 120
544   sctp_send_ttl = milliseconds - number of milliseconds before an unsent
545                   message/chunk is dropped (default: 32000 ms or 32 s).
546                   Can be changed at runtime, e.g.:
547                   $ sercmd cfg.set_now_int sctp send_ttl 180000
548   sctp_send_retries - how many times to attempt re-sending a message on a
549                       re-opened association, if the sctp stack did give up
550                       sending it (it's not related to sctp protocol level
551                       retransmission). Useful to improve reliability with
552                       peers that reboot/restart or fail over to another 
553                       machine. WARNING: use with care and low values (e.g.
554                       1-3) to avoid "multiplying" traffic to unresponding 
555                       hosts (default: 0).
556                       Can be changed at runtime.
557   sctp_assoc_tracking = yes/no - controls whether or not sctp associations
558      are tracked inside ser/sip-router. Turning it off would result in
559      less memory being used and slightly better performance, but it will also
560      disable some other features that depend on it (e.g. sctp_assoc_reuse).
561      Default: yes.
562      Can be changed at runtime (sercmd sctp assoc_tracking 0), but changes
563      will be allowed only if all the other features that depend on it are
564      turned off (for example it can be turned off only if first
565      sctp_assoc_reuse was turned off).
566      Note: turning sctp_assoc_tracking on/off will delete all the tracking
567      information for all the currently tracked associations and might introduce
568      a small temporary delay in the sctp processing if lots of associations
569      were tracked.
570      Config options depending on sctp_assoc_tracking being on:
571       sctp_assoc_reuse.
572   sctp_assoc_reuse = yes/no - controls sctp association reuse. For now only
573      association reuse for replies is affected by it. Default: yes.
574      Depends on sctp_assoc_tracking being on.
575      Note that even if turned off, if the port in via corresponds to the
576      source port of the association the request was sent on or if rport is
577      turned on (force_rport() or via containing a rport option), the
578      association will be automatically reused by the sctp stack.
579      Can be changed at runtime (sctp assoc_reuse), but it can be turned on
580      only if sctp_assoc_tracking is on.
581   sctp_max_assocs = number - maximum number of allowed open sctp associations.
582      -1 means maximum allowed by the OS. Default: -1.
583      Can be changed at runtime (e.g.:
584       sercmd cfg.set_now_int sctp max_assocs 10 ).
585      When the maximum associations number is exceeded and a new associations
586      is opened by a remote host, the association will be immediately closed.
587      However it is possible that some sip packets get through (especially if
588      they are sent early, as part of the 4-way handshake).
589      When ser/sip-router tries to open a new association and the max_assocs
590      is exceeded the exact behaviour depends on whether or not
591      sctp_assoc_tracking is on. If on, the send triggering the active open
592      will gracefully fail, before actually opening the new association and no
593      packet will be sent. However if sctp_assoc_tracking is off, the
594      association will first be opened and then immediately closed. In general
595      this means that the initial sip packet will be sent (as part of the 4-way
596      handshake).
597   sctp_srto_initial = milliseconds - initial value of the retr. timeout, used
598      in RTO calculations (default: OS specific).
599      Can be changed at runtime (sctp srto_initial) but it will affect only new
600      associations.
601   sctp_srto_max = milliseconds - maximum value of the retransmission timeout
602      (RTO) (default: OS specific).
603      WARNING: values lower then the sctp sack_delay will cause lots of
604      retransmissions and connection instability (see sctp_srto_min for more
605      details).
606      Can be changed at runtime (sctp srto_max) but it will affect only new
607      associations.
608   sctp_srto_min = milliseconds - minimum value of the retransmission timeout
609      (RTO) (default: OS specific).
610      WARNING: values lower then the sctp sack_delay of any peer might cause
611      retransmissions and possible interoperability problems. According to the
612      standard the sack_delay should be between 200 and 500 ms, so avoid trying
613      values lower then 500 ms unless you control all the possible sctp peers
614      and you do make sure their sack_delay is higher or their sack_freq is 1.
615      Can be changed at runtime (sctp srto_min) but it will affect only new
616      associations.
617   sctp_asocmaxrxt   = number - maximum retransmissions attempts per association
618      (default: OS specific). It should be set to sctp_pathmaxrxt * no. of
619      expected paths.
620      Can be changed at runtime (sctp asocmaxrxt) but it will affect only new
621      associations.
622   sctp_init_max_attempts = number - maximum INIT retransmission attempts
623      (default: OS specific).
624      Can be changed at runtime (sctp init_max_attempts).
625   sctp_init_max_timeo = milliseconds - maximum INIT retransmission timeout (RTO
626      max for INIT). Default: OS specific.
627      Can be changed at runtime (sctp init_max_timeo).
628   sctp_hbinterval = milliseconds - sctp heartbeat interval. Setting it to -1
629      will disable the heartbeats. Default: OS specific.
630      Can be changed at runtime (sctp hbinterval) but it will affect only new
631      associations.
632   sctp_pathmaxrxt = number - maximum retransmission attempts per path (see also
633      sctp_asocmaxrxt). Default: OS specific.
634      Can be changed at runtime (sctp pathmaxrxt) but it will affect only new
635      associations.
636   sctp_sack_delay = milliseconds - delay until an ACK is generated after
637      receiving a packet. Default: OS specific.
638      WARNING: a value higher then srto_min can cause a lot of retransmissions
639      (and strange problems). A value higher then srto_max will result in very
640      high connections instability. According to the standard the sack_delay
641      value should be between 200 and 500 ms.
642      Can be changed at runtime (sctp sack_delay) but it will affect only new
643      associations.
644   sctp_sack_freq = number - number of packets received before an ACK is sent
645      (without waiting for the sack_delay to expire).  Default: OS specific.
646      Note: on linux with lksctp up to and including 1.0.9 is not possible to
647      set this value (having it in the config will produce a warning on
648      startup).
649      Can be changed at runtime (sctp sack_freq) but it will affect only new
650      associations.
651   sctp_max_burst = number - maximum burst of packets that can be emitted by an
652      association. Default: OS specific.
653      Can be changed at runtime (sctp max_burst) but it will affect only new 
654      associations.
655   server_id = number - A configurable unique server id that can be used to
656                        discriminate server instances within a cluster of
657                        servers when all other information, such as IP addresses
658                        are the same.
659   loadpath = <modules path> - directory where to load the modules from (-L
660      equivalent); modules can be loaded simply by specifying their name
661      (loadmodule "maxfwd")
662   tcp_fd_cache = yes | no (default yes) - if enabled FDs used for sending
663      will be cached inside the process calling tcp_send (performance increase
664      for sending over tcp at the cost of slightly slower connection closing and
665      extra FDs kept open)
666   tcp_async = yes | no (default yes) - if enabled all the tcp  writes that 
667      would block / wait for connect to finish, will be queued and attempted
668      latter (see also tcp_conn_wq_max and tcp_wq_max).
669   tcp_buf_write = obsoleted synonim for tcp_async
670   tcp_conn_wq_max = bytes (default 32 K) - maximum bytes queued for write 
671      allowed per connection. Attempting to queue more bytes would result
672      in an error and in the connection being closed (too slow). If 
673      tcp_write_buf is not enabled, it has no effect.
674   tcp_wq_max = bytes (default 10 Mb) - maximum bytes queued for write allowed
675      globally. It has no effect if tcp_write_buf is not enabled.
676   tcp_defer_accept =  yes | no (default no) on freebsd  / number of seconds
677         before timeout on linux (default disabled) - tcp accepts will be 
678         delayed until some data is received (improves performance on proxies
679         with lots of opened tcp connections). See linux tcp(7) TCP_DEFER_ACCEPT
680         or freebsd ACCF_DATA(0). For now linux and freebsd only.
681         WARNING: the  linux TCP_DEFER_ACCEPT is buggy (<=2.6.23) and doesn't 
682          work exactly as expected (if no data is received it will retransmit 
683          syn acks for ~ 190 s, irrespective of the set timeout and then it will
684          silently drop the connection without sending a RST or FIN). Try to 
685          use it together with tcp_syncnt (this way the number of retrans.
686           SYNACKs can be limited => the timeout can be controlled in some way).
687   tcp_delayed_ack  = yes | no (default yes when supported) - initial ACK for
688         opened connections will be delayed and sent with the first data
689         segment (see linux tcp(7) TCP_QUICKACK). For now linux only.
690   tcp_syncnt = number of syn retr. (default not set) - number of SYN 
691         retransmissions before aborting a connect attempt (see linux tcp(7)
692         TCP_SYNCNT). Linux only.
693   tcp_linger2 = seconds (not set by default) - lifetime of orphaned sockets
694         in FIN_WAIT2 state (overrides tcp_fin_timeout on, see linux tcp(7) 
695         TCP_LINGER2). Linux only.
696   tcp_keepalive = yes | no (default yes) - enables keepalive for tcp.
697   tcp_keepidle  = seconds (not set by default) - time before starting to send
698          keepalives, if the connection is idle. Linux only.
699   tcp_keepintvl = seconds (not set by default) - time interval between 
700          keepalive probes, when the previous probe failed. Linux only.
701   tcp_keepcnt = number (not set by default) - number of keepalives sent before
702          dropping the connection. Linux only.
703   tcp_crlf_ping = yes | no (set by default) - enable CRLF keepalives aka
704          SIP outbound.
705   pmtu_discovery = 0 | 1 (default 0) - set DF bit in outbound IP if enabled
706   dns_srv_lb = yes | no (default no) - enable dns srv weight based load 
707     balancing (see doc/dns.txt)
708   dns_try_naptr = yes | no (default no) - enable naptr support 
709     (see doc/dns.txt for more info)
710   dns_{udp,tcp,tls,sctp}_pref = number - ser preference for each protocol
711     when doing naptr lookups. By default dns_udp_pref=30, dns_tcp_pref=20, 
712     dns_tls_pref=10 and dns_sctp_pref=20. To use the remote site preferences
713     set all dns_*_pref to the same positive value (e.g. dns_udp_pref=1,
714     dns_tcp_pref=1, dns_tls_pref=1, dns_sctp_pref=1). To completely ignore 
715     NAPTR records for a specific protocol, set the corresponding protocol 
716     preference to -1 (or any other negative number).  (see doc/dns.txt for 
717     more info)
718   dns_search_full_match = yes | no (default yes) - when name was resolved 
719     using dns search list, check the domain added in the answer matches with
720     one from the search list (small performance hit, but more safe)
721   mlock_pages = yes |no (default no) - locks all ser pages into memory making 
722     it unswappable (in general one doesn't want his sip proxy swapped out :-))
723   shm_force_alloc = yes | no (default no) - tries to pre-fault all the 
724     shared memory, before starting. When on start time will increase, but
725     combined with mlock_pages will guarantee ser will get all its memory from
726     the beginning (no more kswapd slow downs)
727   real_time = <int> (flags) (default off). - sets real time priority
728      for all the ser processes, or the timers. 
729      Possible values:   0  - off
730                         1  - the "fast" timer
731                         2  - the "slow" timer
732                         4  - all processes, except the timers
733      Example: real_time= 7 => everything switched to real time priority.
734   rt_prio = <int> (default 0) - real time priority used for everything except
735      the timers, if real_time is enabled
736   rt_policy= <0..3> (default 0)- real time scheduling policy, 0 = SCHED_OTHER,
737      1= SCHED_RR and 2=SCHED_FIFO
738   rt_timer1_prio=<int> (default 0) - like rt_prio but for the "fast" timer
739      process (if real_time & 1)
740   rt_timer1_policy=<0..3> (default 0) - like rt_policy but for the "fast" timer
741   rt_timer2_prio=<int> (default 0) - like rt_prio but for the "slow" timer
742   rt_timer2_policy=<0..3> (default 0) - like rt_policy but for the "slow" timer
743   tcp_source_ipv4 = IPv4 address
744   tcp_source_ipv6 = IPv6 address
745     Set the given source IP for all outbound TCP connections.
746     If setting the IP fails the TCP connection will use the default.
747   dns_cache_init = on | off (default on) - if off, the dns cache is not
748     initialized at startup and cannot be enabled runtime, that saves some
749     memory.
750   dst_blacklist_init = on | off (default on) - if off, the blacklist
751     is not initialized at startup and cannot be enabled runtime,
752     that saves some memory.
753
754 new script commands:
755   udp_mtu_try_proto(TCP|TLS|SCTP|UDP) - same as udp_mtu_try_proto=... (see
756     above), but works per packet and not globally.
757
758
759 build system:
760  - check defines and includes used at compile time and if different 
761    force rebuilding everything in the current dir (creates a new file: 
762    makecfg.lst that stores the compile defines & includes used at compile 
763    time)
764  - make cfg / config support: store the build config in an autogenerated file 
765    (config.mak) and use it for future compiles (e.g.: 
766    make cfg include_modules=mysql skip_modules=print CPU=pentium-m; make all).
767    Main advantages are easier usage and faster builds (e.g. make proper is
768     +16 times faster, make clean ~9 times, make with previously generated
769     config is 2.6 times faster and a make that has nothing to do is ~9 times
770     faster).
771
772
773
774
775 2.0.0 changes
776
777
778 new archs:
779
780
781 modules:
782  - tls        - new module that enables tls support (set enable_tls=yes
783                 in the config file and load the tls module)
784  - ctl        - new  fifo/unixsocket/xmlrpc like module, using a space 
785                 efficient binary encoding for the requests.
786                 It supports multiple clients on tcp, udp, unix stream or
787                 unix datagram modes. By default (no modparams) it opens
788                 one unix stream control socket in /tmp/ser_ctl.
789                 It also includes extended fifo support: multiple fifos,
790                 fifo over tcp, udp and unix sockets (see ctl/ctl.cfg).
791                 Use utils/sercmd/sercmd to send commands to it.
792  - dispatcher - added hashing after request uri and to uri
793               - added a new flag parameter which can be used (for now) to
794                 select only the username or the username, host and port when
795                 hashing after an uri (to, from or request uri)
796               - improved uri hashing (password is ignored, port is used only
797                 if != 5060 or 5061)
798  - tm        - aggregate challenges (WWW/Proxy-Authenticate) from all the
799                401 & 407 if the final reply is a 401/407. To turn this off
800                and fall back to the old behaviour set tm aggregate_challenges
801                parameter to 0.
802              - if a relayed 503 is the final reply, replace it by a 500
803              - if a 503 reply is received try the dns based failover
804                (forward to another ip if the original destination uri 
805                 resolved to several SRV, A or AAAA records)
806              - on 6xx immediately cancel all the branches for which a 
807                provisional response was received and wait for all the 
808                branches to finish (either timeout, the 487 from the CANCEL
809                or a final response still on the wire in the moment the
810                CANCEL was sent)
811              - better final reply selection: 6xx is preferred over other 
812                negative replies; from several 4xx prefer 401, 407, 415, 420,
813                484 (in this order). For all the other cases, return the lowest
814                code (as before)
815              - special functions for checking for timeout, if a reply was
816                received or if the current transaction was canceled
817              - dns failover and dst blacklist support
818              - migrated to the new timers (tm timers completely rewritten)
819              - improved speed and less memory usage
820              - much more precise retransmissions timing
821              - params: - retr_timer1p1, retr_timer1p2, retr_timer1p3 removed
822                          and replaced by retr_timer1 and retr_timer2
823                        - all timer values are now expressed in milliseconds
824                          (they were in seconds before).
825                          Affected params: fr_timer, fr_inv_timer, wt_timer,
826                          delete_timer, retr_timer1, retr_timer2
827                        - retr_timer1 (first retransmission) changed to 500 ms
828                        - delete_timer changed to 200 ms
829                        - unix_tx_timeout expressed now in milliseconds; default
830                          value changed to 500 ms
831              - functions:
832                        - t_branch_timeout() -- returns true if the failure
833                          route is executed for a branch that did timeout
834                          (failure_route only).
835                        - t_branch_replied() -- returns true if the failure 
836                          route is executed for a branch that did receive at
837                          least one reply in the past (the current reply 
838                           is not taken into account). It can be used
839                          together with t_branch_timeout() to distinguish 
840                          between a remote side that doesn't respond (some 
841                          provisional reply received) and one that is completely
842                           dead. (failure_route only)
843                        - t_any_timeout() -- returns true if any of the current
844                          transaction branches did timeout.
845                        - t_any_replied() -- returns true if at least one branch
846                           of the current transaction received one reply in the
847                           past. If called from a failure_route or an
848                           onreply_route, the "current" reply is not taken into
849                           account.
850                        - t_is_canceled() -- returns true if the current 
851                          transaction  has been canceled.
852                        - new t_set_fr(timeout_fr_inv, timeout_fr) -- allows
853                          changing the transaction timer from script, even if
854                          the transaction was already created (see tm docs for
855                          more).
856             - t_relay will not stop script execution anymore in case of
857               send error
858  - textops  - search() can be used in the onsend_route where it will search
859               on the "new" message (after applying all script changes, adding
860               Vias a.s.o) and not on the original message
861  
862 core:
863  - compiled by default with tls hooks support (so that no recompile is
864    needed before loading the tls module and enabling the tls support)
865  -  enable_tls config option added (the reverse of disable_tls)
866  - added STUN keep-alive functionality in accordance with 
867    draft-ietf-behave-rfc3489bis-04.txt
868  - dns cache and dns failover support added (see doc/dns.txt)
869  - destination blacklist added -- destinations to which forwarding fails
870    (send error, tm timeout a.s.o) are temporarily added to a blacklist which 
871     is consulted before each send => faster send error detection
872     in the near future (see doc/dst_blacklist.txt)
873  - default log level switched to 0 (only messages < L_WARN will be printed
874    by default)
875  - separate memdbg log level which controls the memory/malloc related
876    debug messages (to see them ser must be compiled with malloc debuging:
877      -DDBG_QM_MALLOC or -DDBG_FM_MALLOC and memdbg must be <= debug )
878  - added named routes: names can be used instead of numbers in all the
879    route commads or route declarations. route(number) is equivalent to
880    route("number").
881    Example:
882      route("test");
883       route["test"]{
884            ...
885      }
886  - added named flags, declared at the beginning of the config file with:
887      flags  flag1_name[:position],  flag2_name ...
888    Example:
889        flags test, a:1, b:2 ;
890        route{
891               setflag(test);
892               if (isflagset(a)){ # equiv. to isflagset(1)
893                 ....
894               }
895               resetflag(b);  # equiv. to resetflag(2) 
896  - added return [val] which returns from a route. if no value is specified, or
897    a route reaches its end without executing a return statement, it returns 1.
898    If return is used in the top level route is equivalent with exit [val].
899  - drop /exit [n] now will end the script execution
900    exit n will exit with code n (usefull in onreply/onsend routes where
901    if script code !=0 a reply is generated/the message is sent or to force
902    script errors)
903  - added $? which can be used to check the return code of the last executed
904    route{} (e.g. route(1); if ($?==1){ /* ... */}else if ($?==2) ... )
905  - onsend_route added: special route executed before a request is sent.
906                        Only a limited number of commands are allowed (drop, if
907                        + all the checks, msg flag manipulations, send(), log(),
908                        textops::search()). In this route the final destination
909                        of the message is available an can be checked (with
910                        snd_ip, snd_port, to_ip, to_port, snd_proto, snd_af).
911                        This route is executed only when forwarding requests.
912                        It's not executed for replies, retransmissions, or
913                        locally generated messages (e.g. via fifo uac).
914       short example:
915             onsend_route{  if(to_ip==1.2.3.4 && !isflagset(12)){
916                               log(1, "message blocked\n");
917                               drop;
918                            }
919                          }
920  - onsend_route specific checks:
921      - snd_ip, snd_port - behave like src_ip/src_port, but contain the
922        ip/port ser will use to send the message
923      - to_ip, to_port - like above, but contain the ip/port the message will
924        be sent to (not to be confused with dst_ip/dst-port, which are the
925        destination of the original message: ser's ip and port on which the
926        message was received)
927      - snd_proto, snd_af - behave like proto/af but contain the 
928        protocol/address family that ser will use to send the message
929      - msg:len - when used in an onsend_route, msg:len will contain the length
930        of the message on the wire (after all the changes in the script are
931        applied, Vias are added a.s.o) and not the lentgh of the original 
932        message
933  - timer: - improved performance/precision, new api, see doc/timers.txt 
934  - tcp: - improved  performance (io event handling), using OS specific
935            optimizations
936         - 1024 connections limit removed (see tcp_max_connections)
937 -  resolver: - timeouts, retries a.s.o can now be set from ser.cfg
938              (see below dns_* and man resolv.conf(6)).
939              The maximum time a dns request can take (before failing) is:
940               (dns_retr_time*dns_retr_no)*(search_list_domains)
941              If dns_try_ipv6 is yes, mutliply it again by 2.
942              The fastest possible dns config (max 1s):
943                 dns_try_ipv6=no
944                 dns_retr_time=1
945                 dns_retr_no=1
946                 dns_use_search_list=no
947 - default on reply route added: onreply_route {.. } will add a default 
948     onreply route that will be executed for any reply (usefull to catch
949     replies without using tm)
950 - branch_routes added (tm triggered), only a very limited number of commands
951    are available (see tm docs)
952 - avps directly accessible from script with %avp_name (variable style)
953 new config variables:
954    enable_tls/disable_tls = enable/disable tls support, default disable.
955        Note: a tls "engine" is still needed (e.g. the tls module must
956               be loaded, enable_tls by itself is not enough).
957    exit_timeout = seconds - how much time ser will wait for all the shutdown
958        procedures to complete. If this time is exceeded, all the remaining
959        processes are immediately killed and ser exits immediately (it might
960        also generate a core dump if the cleanup part takes too long).
961        Default: 60 s. Use 0 to disable.
962    stun_refresh_interval = number in millisecond (default 0); value for 
963       attribute REFRESH INTERVAL
964    stun_allow_stun = 0 | 1 (off | on - default 1); use STUN or not if compiled
965    stun_allow_fp = 0 | 1 (off | on - default 1); use FINGERPRINT attribute
966    use_dns_cache = on | off  (default on)  
967    use_dns_failover = on | off (default off)
968    dns_cache_flags = number (default 0)
969    dns_cache_negative_ttl = number in seconds (default 60)
970    dns_cache_min_ttl = time in seconds (default 0)
971    dns_cache_max_ttl = time in seconds (default MAXINT)
972    dns_cache_mem = maximum memory used for the dns cache in Kb (default 500 K)
973    dns_cache_gc_interval = interval in seconds after which the dns cache is
974       garbage collected (default: 120 s)
975    use_dst_blacklist = on | off (default off)
976    dst_blacklist_expire = time in s (default 60)
977    dst_blacklist_mem = maximum memory used for the blacklist in Kb (default 250
978       K)
979    dst_blacklist_gc_interval = interval in seconds after which the destination 
980       blacklist is garbage collected (default 60)
981    tos = number  - ip type of service (TOS) value
982    dns_try_ipv6 = yes/no - if yes and a dns lookup fails, it will retry it
983       for ipv6 (AAAA record). Default: yes
984    dns_retr_time = time - time in s before retrying a dns request.
985       Default: system specific, depends also on the/etc/resolv.conf content
986       (usually 5s).
987    dns_retr_no = no. - number of dns retransmissions before giving up.
988       Default: see above (usually 4)
989    dns_servers_no = no. - how many dns servers from the ones defined in 
990       /etc/resolv.conf will be used. Default: all of them.
991    dns_use_search_list= yes/no - if no, the search list in /etc/resolv.conf
992       will be ignored (=> fewer lookups => gives up faster). Default: yes.
993       HINT: even if you don't have a search list defined, setting this option
994       to "no" will still be "faster", because an empty search list is in 
995       fact search "" (so even if the search list is empty/missing there will
996       still be 2 dns queries, eg. foo+'.' and foo+""+'.')
997    tcp_connection_lifetime = value (s) - how long the lifetime of a
998       tcp connection will be exteneded after an IO event (accept, connect, 
999       read, write). Default: 120 s.
1000    tcp_poll_method = poll|select|sigio_rt|epoll_et|epoll-lt|kqueue|devpoll - 
1001       poll method used (by default the best one for the current OS is selected)
1002    tcp_max_connections = no. - maximum number of tcp connections (if the number
1003       is exceeded no new tcp connections will be accepted). Default: 2048.
1004
1005 tools:
1006   utils/sercmd - command line serctl like tool for interrogating ser ctl
1007                  module (uses the binrpc encoding). Supports various
1008                  connection methods (udp, tcp, unix stream & datagram sockets),
1009                  reply formating (see -f, e.g. sercmd -f "pid:%v %v\n" core.ps)
1010                  , interactive mode, command line completion (if compiled with 
1011                  libreadline) a.s.o.
1012
1013 WARNING: - older 0.10.99-dev version (< 0.10.99-dev46) returned a 480 reply
1014  on invite transaction timeout, if a provisional reply was received. Newer
1015  versions reverted to returning 408 on all timeouts (one can use 
1016   t_branch_timeout() and t_branch_replied() to distinguish between the two
1017   timeout types)
1018
1019
1020
1021 0.9.4 fixes/improvements (0.9.4 is a bug fix release for 0.9.3)
1022  
1023 general:
1024  - gcc 4.0 support
1025  - mutlicast options are set for all the sockets
1026  - mediaproxy: memory leak, unchecked memory allocations
1027  - postgress: some bugs and cleanups (compiles cleanly now)
1028  - tm: shm cloned lumps (SER-55) 
1029  - tm: t_fifo: 64-bit fix
1030  - tm: dst_uri clone fix
1031  - tm: t_newtran/t_restransmit* races  (!)
1032  - usloc: memory leak
1033
1034 solaris:
1035  - serctl, better ISA detection, signals
1036 *bsd:
1037  - multicast options are properly set
1038 openbsd:
1039  - tcp 64 bit fix
1040
1041
1042
1043 0.9.3 changes
1044
1045
1046 new archs:
1047  - alpha experimental support
1048  - mips2/cobalt experimental support
1049  - x86_64 support
1050  - OS X (darwin) support
1051  - sparc32 single cpu highly experimental support
1052  - ppc64 support
1053
1054 modules:
1055  - enum - support for more than one NAPTR
1056  - msilo - explicit multidomain support -- recipient's user ID is stored in
1057    the columns username and domain -- r_uri column kept for compatibility
1058    reasons (will be removed in future) but not filled by this version of
1059    module
1060  - mysql - implements a connection pool, all modules will use same connection
1061    to access the database
1062  - nathelper received port  test (flag 16 for nat_uac_test): compares the
1063    source port of the message with sip port in the first Via and returns
1064    true if different.
1065  - permsions - support for multiple allow/deny files, allow_register function
1066  - TM has a new parameter: restart_fr_on_each_reply. If set (default)
1067    fr_inv timer will be restarted for each provisional reply, if not set
1068    it will be restarted only for the first reply and for replies >=180
1069    (but only if increasing, eg.: 180, 181 ...). Usefull when dealing with bad
1070    UAs that re-transmit 180s.
1071  - TM saves the avp list into transactions, and make it available into
1072    callbacks, failure and reply routes.
1073  - TM contains new command - t_write_unix("/tmp/sems.sock", "announcement")
1074    sends a message using unix socket interface instead of FIFO interface.
1075  - TM contains new config variable - unix_tx_timeout -- it specifies the
1076    transmit timeout of t_write_sock
1077  - VM functionality was transfered into TM module. Instead of fetching the
1078    email value from DB (as VM), TM looks for the "email" attribute to get the
1079    value.
1080    vm() function was replaced with t_write_req()
1081    vm_reply() fifo functions was replcated by TM with t_reply() fifo function
1082    NOTE!! because current version of SEMS/AA try to send reply via vm_reply,
1083    it will not work with the TM version.
1084  - xlog - printing the body of any header by specifying the name; new
1085    specifiers for user-agent, message buffer, message length, message's flags,
1086    message id.
1087
1088 new modules:
1089  - avp / avp_db / avp_radius - load and check avps per caller or callee
1090  - avpops - flexible module for operations with avps and database, introducing
1091    a pseudo-varible support in SER configuration file
1092  - cpl-c - implementation of Call Processing Language
1093  - dispatcher - implements a dispatcher for incoming requests using hashes
1094    over parts of the request to select the destination
1095  - diversion - implements the Diversion extensions as per 
1096    draft-levy-sip-diversion-08
1097  - flatstore - simple module that implements very fast inserts for accounting
1098    purposes
1099  - gflags - keeps a bitmap of flags in shared memory and may be used to change
1100    behaviour of server based on value of the flags
1101  - options - answer server options requests
1102  - speeddial - provides on-server speed dial facilities
1103  - uri_db - split from uri module, performs various checks related to SIP URI
1104    over database fields
1105
1106 removed modules:
1107  - vm - the functionality was transfered to tm module (see t_write_req(...)
1108    method)
1109
1110 core:
1111  - new parts:
1112        UNIX domain socket server implemented
1113  - changes: 
1114     - command line: removed -p port and extended -l:
1115        -l [proto:]addr[:port] , where proto=udp|tcp and 
1116        addr= host|ip_address|interface_name. The format is the same
1117        as for listen in the config file. ipv6 addresses must be enclosed in
1118        [].
1119     - added from_uri & to_uri: behave exactly like uri but use the
1120       "From:"/"To:" uris
1121        (e.g.: if (from_uri==myself) ..., if (to_uri=~"^sip:test@")... )
1122     - config: better escape support in strings (e.g. \", \<cr>, \x0a, \012)
1123     - bad network addresses are now automatically fixed
1124       (e.g. 192.168.1.80/27 => 192.168.1.64/27)
1125     - avp (Attribute-Value Pair) support added
1126     - avp alias support added
1127     - multicast support added (see mcast_loopback & mcast_ttl)
1128     - saving of procces group id enabled, if the -G option is specified
1129       (a safe way to quickly kill all ser processes)
1130     - core dump-ing is enabled by default, see also disable_core_dump
1131     - protocol and port can be specified in the alias and listen lines, e.g.:
1132         alias= tcp:foo.bar:* udp:test.bar:5080 foo.com
1133         listen= eth0   tcp:eth0:5065 udp:127.0.0.1 [3ffe::1]
1134     - multiple operator support: ==, != for special operations (e.g myself, ip)
1135                               ==, !=, ~= for strings
1136                               ==, !=, >, <, >=, <= for integers
1137     - database api changed to support usage of different drivers
1138       simultaneously. The database URL must start now with the name of the
1139       driver (module). Example: for mysql the DB URL
1140       'sql://user:password@dbhost:port/database' must be specified now as
1141       'mysql://user:password@dbhost:port/database'
1142  - new config variables:
1143    mcast_loopback = <yes/no> - loopback sent multicast datagram, default no.
1144    mcast_ttl = number - set multicast ttl, default OS specific (usually 1).
1145    sock_mode = <permissions> (e.g. sock_mode=0600:  default value = 0660)
1146        ser unix sockets and fifo will be created with this permissions
1147        (old name fifo_mode is still supported, but deprecated)
1148    sock_user = username|"uid"
1149    sock_group = groupname|"gid"
1150       change the owner and/or group of the ser unix sockets or fifo
1151       Short example config snippet:
1152            sock_mode=0600        # ser socket/fifo mode
1153            sock_user="www-data"  # ser socket/fifo owner
1154            sock_group=nogroup  
1155            user=nobody       # ser user (ser will suid to it)
1156    disable_core_dump= yes|no 
1157        by default core dump limits are set to unlimited or a high enough
1158        value, set this config variable o yes to disable core dump-ing
1159        (will set core limits to 0)
1160    open_files_limit= number
1161        if set and bigger than the current open file limit, ser will try
1162        to increase its open file limit to this number. Note: ser must be
1163        started as root to be able to increase a limit past the hard limit
1164        (which, for open files, is 1024 on most systems)
1165    tcp_connect_timeout= seconds
1166        time before an ongoing connect will be aborted
1167    tcp_send_timeout= seconds
1168        time after a tcp connection will be closed if it is not available 
1169        for writing in this interval (and ser wants to send something on it)
1170    tcp_accept_aliases= yes|no
1171        if a message received over a tcp connection has "alias" in its via
1172        a new tcp alias port will be created for the connection the message
1173        came from (the alias port will be set to the via one).
1174        Based on draft-ietf-sip-connect-reuse-00.txt, but using only the port
1175        (host aliases are too dangerous IMHO, involve extra DNS
1176         lookups and the need for them is questionable)
1177        See force_tcp_alias for more details.
1178    log_facility = LOG_LOCAL0
1179        if ser logs to syslog, you can control the facility for logging. Very
1180        useful when you want to divert all ser logs to a different log file.
1181        See man page syslog(3) for more detailes.
1182    unix_sock = "/tmp/ser.sock"
1183        The name of the socket the unixsock server should listen on.
1184    unix_sock_children = 1
1185        The number of children that will listen on the unix domain socket.
1186    unix_tx_timeout = 2000
1187        Timeout (in ms) used when sending replies through unix sockets.
1188  - new script commands:
1189    force_send_socket([proto:]address[:port])
1190        sends the message from the specified socket (it _must_ be one of the
1191        sockets ser listens on). If the protocol doesn't match (e.g. udp
1192        message "forced" to a tcp socket) the closest socket of the same
1193        protocol is used.
1194    force_tcp_alias()
1195    force_tcp_alias(port)
1196        adds a tcp port alias for the current connection (if tcp).
1197        Usefull if you want to send all the trafic to port_alias through
1198        the same connection this request came from [it could help 
1199        for firewall or nat traversal].
1200        With no parameters adds the port from the message via as the alias.
1201        When the "aliased" connection is closed (e.g. it's idle for too
1202        much time), all the port aliases are removed.
1203        Note: by default ser closes idle connection after 3 minutes (stable)
1204        or 1 minute (unstable) so to take full advantage of tcp aliases for
1205        things like firewall and nat traversal, redefine TCP_CON_*TIMEOUT
1206        in tcp_conn.h and recompile. Also right now there can be maximum
1207        3 port aliases to a connection (you shouldn't need more than one).
1208        To change this redefine TCP_CON_MAX_ALIASES in the same file
1209        (set it to you desired value + 1; 1 is needed for the real port).
1210
1211 utilities:
1212  - ngrep patch for displaying new lines in captured SIP messages is no longer
1213    needed; use ngrep V 1.42 with the option "-W byline"
1214
1215
1216
1217 ***********************************************
1218 * Changes/fixes introduced in 0.8.12
1219 ***********************************************
1220 +--------------------------------------------------------+
1221 | WARNING: if you want to use a 0.8.11 config script     |
1222 | with 0.8.12, replace if ( len_gt(number) ) with:       |
1223 |                      if ( msg:len > bumber )           |
1224 +--------------------------------------------------------+
1225
1226 New Features
1227 ============
1228
1229 texops:
1230  - subst('s/re/repl/flags') support
1231 core:
1232  - added switch to check the config file (-c)
1233  - changes: removed len_gt() and replaced with if (msg:len op number|max_len)
1234  - multiple operator support: ==, != for special operations (e.g myself, ip)
1235                               ==, !=, ~= for strings
1236                               ==, !=, >, <, >=, <= for integers
1237  - new config variables:
1238      advertised_address= ip | string
1239        address advertised in via and in the DST_* lumps (e.g RR)
1240        This is the default value, if empty (default) the socket
1241        address will be used.
1242        WARNING: - don't set it unless you know what you are doing
1243                  (e.g. nat traversal)
1244                - you can set anything here, no check is made
1245                 (e.g. foo.bar will be accepted even if 
1246                  foo.bar doesn't exist)
1247     advertised_port= no
1248        port advertised in via and in the DST_*lumps (e.g. RR)
1249        This is the default value, if empty (default) the socket
1250        port will be used.
1251        Same warnings as above.
1252  - new script commands:
1253     set_advertised_address(ip|string)
1254        same as advertised_address but it affects only the current message:
1255        Message host/lump address= the set_advertised one if
1256        present, else advertised_address else socket address.
1257     set_advertised_port(no)
1258        same as advertised_port but it affects only the current
1259        message; see set_advertised_address & s/address/port/g
1260
1261 usrloc:
1262  - usernames are case insensitive
1263  
1264 registrar:
1265  - lookup function succeeds when appending of a branch failed
1266
1267 auth_db:
1268  - support for rpid stored in database (thanks to Jakob Schlyter)
1269
1270 Bug fixes
1271 =========
1272 - memory leak in digest credentials parser fixed
1273 - authenticathion ha1 didn't include domain if username was of the form
1274   user@domain and calculate_ha1 was set to yes (modules/auth_db)
1275 - tm reply processing race condition (modules/tm), special thanks go to
1276  Dong Liu
1277 - Many bugs in pa module fixed, works with registrar again.
1278  
1279 Security updates
1280 ================
1281  
1282 - fifo processing code will write responses only to other
1283  fifos and only if they are not hard-linked, also default
1284  ser fifo persmissions were changed to 0600.
1285                                                                                 
1286 Performance improvements
1287 ========================
1288 - tuned internal malloc implementation parameters to better reflect the
1289 actual workload (malloc is a little bit faster now)
1290
1291
1292
1293 ***********************************************
1294 * Changes introduced in 0.8.11
1295 ***********************************************
1296
1297 +--------------------------------------------------------+
1298 | CAUTION: the 0.8.11 release include changes which      |
1299 | are incompatible with scripts and databases used       |
1300 | in previous versions. Care is advised when upgrading   |
1301 | from previous releases to 0.8.11.                      |
1302 +--------------------------------------------------------+
1303
1304 New features
1305 =============
1306 - RFC3261 support
1307     - TCP support and cross-transport forwarding [core]
1308     - loose routing support [rr module]
1309 - New modules
1310     - vm -- voicemail interface [vm]
1311     - ENUM support [enum]
1312     - presence agent [pa]
1313     - dynamic domain management -- allows to manipulate 
1314       hosting of multiple domains in run-time [module]
1315     - flat-text-file database support [dbtext]
1316     - rich access control lists [permissions]
1317 - Feature Improvements
1318     - click-to-dial, which is based on improved tm/FIFO 
1319       that better supports external applications [tm module]
1320     - web accounting -- acc module can report to serweb
1321         on placed calls [acc module]
1322     - improved exec module (header fields passed now
1323       as environment variables to scripts) [exec module]
1324 - Architectural Improvements
1325     - powerpc fast locking support
1326     - netbsd support
1327     - 64 bits arch. support (e.g. netbsd/sparc64).
1328 - New Experimental Features (not tested at all yet)
1329     - nathelper utility for Cisco/ATA NAT traversal [nathelper]
1330     - another NAT traversal utility [mangler]
1331     - postgress support [postgress]
1332     - fcp module [fcp]
1333     - pdt module (prefix2domain) [pdt]
1334
1335 Changes to use of ser scripts
1336 =============================
1337
1338 About Multiple Transport Support
1339 --------------------------------
1340 SER now suports multiple transport protocols: UDP and TCP. As there
1341 may be UAs which support only either protocol and cannot speak to
1342 each other directly, we recommend to alway record-route SIP requests,
1343 to keep the transport-translating SER in path. Also, if a destination
1344 transport is not known, stateful forwarding is recommended -- use of
1345 stateless forwarding for TCP2UDP would result in loss of reliability.
1346
1347
1348 core
1349 ----
1350 - reply_route has been renamed to failure_route -- the old name caused
1351   too much confusion
1352 - forward_tcp and forward_udp can force SER to forward via specific
1353   transport protocol
1354
1355 acc module:
1356 -----------
1357 - radius and sql support integrated in this module; you need to
1358   recompile to enable it
1359 - acc_flag is now called log_flag to better reflect it relates
1360   to the syslog mode (as opposed to sql/radius); for the same
1361   reasons, the accounting action is now called "acc_log_request"
1362   and the option for missed calls "log_missed_calls"
1363 - log_fmt allows now to specify what will be printed to syslog
1364
1365 auth module:
1366 ------------
1367 - auth module has been split in auth, auth_db, auth_radius, group
1368   group_radius, uri and uri_radius 
1369 - all the parameters that were part of former auth module are now 
1370   part of auth_db module
1371 - auth_db module contains all functions needed for database
1372   authentication
1373 - auth_radius contains functions needed for radius authentication
1374 - group module contains group membership checking functions
1375 - group_radius contains radius group membeship checking functions
1376 - is_in_group has been renamed to is_user_in and places to groups
1377   module
1378 - check_to and check_from have been moved to the uri module
1379  
1380
1381 im module:
1382 ----------
1383 - im is no longer used and has been obsoleted by TM
1384
1385 exec module:
1386 ------------
1387 - exec_uri and exec_user have been obsoleted by exec_dset; 
1388   exec_dset is identical to exec_uri in capabilities; it 
1389   additionaly passes content of request elements (header 
1390   fields and URI parts) in environment variables; users of 
1391   exec_user can use exec_dset now and use the "URI_USER"  
1392   variable to learn user part of URI
1393 - exec_dset and exec_msg return false, if return value of 
1394   script does not euqal zero
1395 - exec_dset takes an additional parameter, which enables 
1396   validation of SIP URIs returned by external application
1397
1398 jabber module:
1399 --------------
1400 - presence support for Jabber users is enabled loading the PA
1401   module and using handle_subscribe("jabber") for SUBSCRIBE 
1402   requests to jabber user 
1403
1404 msilo module:
1405 -------------
1406 - m_store has now a parameter to set what should be considered
1407   for storing as destination uri. This enables support for saving
1408   the messages on negative replies.
1409
1410 radius_acc module:
1411 ------------------
1412 - radius_acc module has been removed and radius accounting 
1413   is now part of acc module
1414
1415 registrar/usrloc modules:
1416 -------------------------
1417 - multi domain support, the modules user username@domain as AOR
1418   if enabled
1419 - descent modification time ordering of contacts
1420 - case sensitive/insensitive comparison of URI can be enabled
1421
1422 rr module:
1423 ----------
1424 - addRecordRoute has been replaced with record_route
1425 - rewriteFromRoute has been replaced with loose_route()
1426 - a new option, "enable_full_lr" can be set to make life
1427   with misimplemented UAs easier and put LR in from "lr=on"
1428 - rr module can insert two Record-Route header fields when
1429   necesarry (disconnected networks, UDP->TCP and so on)
1430
1431 tm module:
1432 ----------
1433 - t_reply_unsafe, used in former versions within reply_routes,
1434   is deprecated; now t_reply is used from any places in script
1435 - t_on_negative is renamed to t_on_failure -- the old name just
1436   caused too much confusion
1437 - FIFO t_uac used by some applications (like serweb) has been
1438   replaced with t_uac_dlg (which allows easier use by dialog-
1439   oriented applications, like click-to-dial) 
1440 - if you wish to do forward to another destination from 
1441   failure_route (reply_route formerly), you need to call t_relay
1442   or t_relay_to explicitely now
1443 - t_relay_to has been replaced with t_relay_to_udp and t_relay_to_tcp
1444