1. Migration to 1.6.0
A manual for how to migrate/update from 1.5.x to 1.6.0 is now available on site.
2. What is new in 1.6.0
2.1 Core
- new 'statistic classes for network and pkg_mem information: NET class , to provide information about the network sockets and PKMEM class, to provide information about the private memory of each process - see http://lists.opensips.org/pipermail/users/2009-April/004868.html
- new mem_dump core parameter for a better control on logging memory info. Former "mem_log" was split in mem_log (only for debug log during mallog/free/realloc ops) and mem_dump (for dumping the mem status at runtime/shutdown). This will help in debugging memory leaks - you can request only the mem dumping without actually getting all the debugs during mem ops.
For backward compatibility, setting mem_log will automatically set to the same value the mem_dump.
To get distinct setting, do:
mem_log = 6; # do not report mem logs (report them as debugs)
mem_dump = 0; # report mem dumps (report on ERR level)
- new '''db_version_table" core parameter to allow configuration of custom names for "version" table. There are cases when a single DB contains tables from 2 versions of OpenSIPS, so distinct version tables are needed.
db_version_table = "version_1_6";
- extendes the idea of the advertised_address and advertised_port parameters so that it is possible to bind such an address to each listen= statement. Syntax-wise, it works like this:
listen=[proto:]host[:port][ AS host[:port]]
See Patch #2706135 (see https://sourceforge.net/tracker/?func=detail&aid=2706135&group_id=232389&atid=1086412)
2.2 Script Routes
- The routes can have string names also, not only numerical IDs as it was until now. This way the routing flow will be more meaningful and easier to understand and follow. The backward compatibility was kept - and you can also use number IDs as route names.
- new startup_route type of script route - called only once when the server is started and before the listener processes are created. You can configure here some initialization actions to ease up the future processing. For example, you could take some values from database and store them in cache or in shared memory pseudovariables to have faster access to those values when needed.
- new timer_route type of script route - called on a timer basis at a given interval. This can be used to configure some periodical actions that do some data refresh actions for example. The time interval is given after the name of the route separated by comma and it represents a value in seconds.
2.3 Pseudo variables
- $an - the nonce from Authorization or Proxy-Authorization header
- $ar - the authentication response from Authorization or Proxy-Authorization header
- $branch - replaces the $br variable (check here)
- $(branch()[n]) - this variable provides read/write access to all fields/attributes of an already existing branch (priorly created with append_branch()). The variable accepts also index $(branch(uri)[1]) for accessing a specific branch (multiple branches can be defined at a moment). The index starts from 0 (first branch). If the index is negative, it is considered the n-th branch from the end ( index -1 means the last branch).To get all branches, use the * index - $(branch(uri)[*]). - see here. The fields of the branch are:
- uri - the RURI of the branch (string value)
- duri - destination URI of the branch (outbound proxy of the branch) (string value)
- q - q value of the branch (int value)
- path - the PATH string for this branch (string value)
- flags - the branch flags of this branch (int value)
- socket - the local socket to be used for relaying this branch (string value)
- $TS - startup time stamp
- delete the value at a certain index; syntax: $pvar[index]= NULL;
- overwrite the value at a certain index; syntax: $pvar[index] = new_val
- new PV $time(format) to print time is dynamic formatted time string. Format: see "man strftime" ; Ex: $time(B %Y) -> Thursday September 2009
- added context meaning to pseudovariables - a new token added in front of the pv type name that specifies the context where the pv should be taken from; for now there are 2 pv contexts: reply and request, registered by the tm module
- $(<request>ru) from a reply route will get the Request-URI from the request
- $(<reply>hdr(Contact)) context can be used from failure route to access information from the reply
2.4 Transformations
- added a new nameaddr transformation: param; it extract the value of a certain parameter
- example: avp(i:4) = $(hdr(From){nameaddr.param, tag});
2.5 AAA API and enhancement of RADIUS support(NEW)
AAA API
The AAA API represents a set of generic callbacks and structures needed for AAA operations.
The purpose of the API is to move all the AAA specific (Radius) implementations in a single module. The AAA API will hide the implementations details from the modules that want to use AAA support, making it easier to use.
Currently, only one module implements the AAA API - aaa_radius, offering Radius support.
Because both standardized AAA protocols, Radius and Diameter, use lists of attribute-value pairs, the API is designed based on attribute-value pairs, as well.
One of the advantages of using the API is that any module that wishes to do AAA operations does not depend on a certain protocol implementation, therefore it is not linked with a certain AAA library.
Hence, any module that was previously using Radius, for example, is not linked with the radiusclient library any more, which is obviously an advantage, especially when the module uses more than one API (DB, AAA, etc).
The AAA protocol to be used by a module is specified from the script using a so called "aaa_url" that encodes the protocol used and other useful information depending on the protocol.
The way the generic AAA API is used makes it very similar to the generic database API.
The ability to make custom Radius requests directly from the script
This feature is very useful because of its flexibility. Basically, any type of Radius queries can be yielded directly from the script, and also, Radius replies can be inspected for certain attributes.
Radius implementation for the generic AAA API
The handling of Radius AVP "SIP-AVP" (used for fetching variables from the Radius server) was integrated in this module. All SIP-AVPs are automatically and transparently handled by the module, so that this functionality is by default available for all the modules that use Radius.
Module changes
Due to the fact that the modules that were previously using Radius were ported to the generic AAA API, the following changes have been made:
- auth_radius modules became auth_aaa module
- group_radius module was merged with group module
- uri_radius and uri_db were merged with uri module
2.6 B2BUA support (NEW)
A signaling B2BUA implementation has been added in OpenSIPS. It can keep the state of the dialogs, create new dialogs and control dialogs to offer some PBX specific services.
This feature is implemented in two modules: b2b_entities and b2b_logic.
The services are defined in XML documents that are parsed and applied by the b2b_logic module. It uses the basic dialog management functions offered by the b2b_entities module to command the actions needed to implement the service.
Find more here.
2.7 MEMCACHED module (NEW)
A new module that provides a new caching method using memcached servers was added.
It provides a way to access memcached servers using the existing memcache API.
Advantages over the existing "localcache" module:
- memory costs are no longer on the server
- many servers may be used so the memory is virtually unlimited
- the cache is persistent so a restart of the server will not affect the cache
- memcached is an open-source project so it can be used to exchange data with various other applications
- servers may be grouped together (e.g. for security purposes : some can be inside a private network, some can be in a public one).
Find more on http://lists.opensips.org/pipermail/users/2009-July/007024.html or
http://www.opensips.org/html/docs/modules/devel/memcached.html
2.8 DB_HTTP module (NEW)
This module provides access to a database that is implemented as a HTTP server. It may be used in special cases where traversing firewalls is a problem, or where data encryption is required.
In order to use this module you must have a server that can communicate via HTTP or HTTPS with this module that follows exactly the format decribed in the specifications section.
The module can provide SSL, authentication, and all the functionalities of an opensips db as long as the server supports them ( except result_fetch).
There is a slight difference between the url of db_http and the urls of the other db modules. The url doesn't have to contain the database name. Instead, everything that is after the address is considered to be a path to the db resource, it may be missing.
Find more on http://www.opensips.org/html/docs/modules/devel/db_http.html
2.9 DB_VIRTUAL module (NEW)
The DB_VIRTUAL module allows you to create virtual DB connection on top of real connections. A virtual connection may use multiple real connection (a set), acting as a mixer layer - based on different algorithms, the DB operation pushed on the virtual DB will be pushed further to one or more real DB connections.
The DB_VIRTUAL provides failover mode (you have a master real connection and when this is down, the queries will be pushed via the next real connection from the set), parallel mode (the received query is pushed via all real connections) and round-robin mode ( the received queries are spread across the set of real connections).
The purpose of this module is to provide failover and load-balancing at DB connection level in a totally transparent way for the modules that needs DB support.
Read more on http://www.opensips.org/Main/News0035.
2.10 JSON module (NEW)
This module introduces a new type of variable that provides both serialization and de-serialization from JSON format. The Json format it is very useful as you can encode an unlimited number (and types) of info elements into a single string. For example a gateway description may contain several infos on the GW (if SST is accepted, RPID/PAI, etc), also a user profile (with all its date) can be condensed into a single string, so that DB ops are reduced to a maximum.
The variable provides ways to access objects and arrays to add,replace or delete values from the script.
The correct approach is to consider a json object as a hashtable ( you can put (key;value) pairs, and you can delete and get values by key) and a json array as an array ( you can append, delete and replace values).
Since the JSON format can have objects inside other objects you can have multiple nested hashtables or arrays and you can access these using paths.
See more on http://www.opensips.org/html/docs/modules/devel/json.html
2.11 STUN server module (NEW)
There is a new STUN server(rfc 3489) module integrated in OpenSIPS.
Why an integrated STUN server module?
- A STUN server uses 2 ips and 2 ports to create 4 sockets on which to listen or respond.
- This integrated STUN module uses the SIPS sockets created by the OpenSIPS core:
- one (or two) of the sockets will overlap with the SIP signaling socket
- the rest will be created by this module for STUN only purposes.
In the case of a bad behaving NATs (such as symmetric NAT) only this integrated STUN server will increase the likelihood of STUN to solve the NAT traversal for a wider range of NAT implementations. This translates into less need of media relaying (for NAT traversal purposes).
Note:
- It is important to set the primary_ip:primary_port to match the OpenSIPS signalling ip and ports.
- If OpenSIPS binds one more interface this module will use that too; so make sure you set the correct alternate_ip:primary_port.
- STUN requires 2 routable ip addresses; if in shortage create a virtual interface (i don't recommend because it destroys the purpose for some usages).
Example:
Opensips listening for signaling traffic:
89.89.89.12:5060
for stun module we configure :
primary_ip = 89.89.89.12; primary_port = 5060 - overlapping with signaling socket
primary_ip = 89.89.89.12; alternate_port = 3478 - dedicated stun socket
alternate_ip = 34.34.34.12; primary_port = 5060 - dedicated stun socket
alternate_ip = 34.34.34.12; alternate_port = 3478 - dedicated stun socket
Documentation can be found here: http://www.opensips.org/html/docs/modules/devel/stun.html
2.12 ALIAS_DB module
- new function alias_db_find("table","input_var","output_var") - similar to alias_db_lookup(), but instead of using fixed input (RURI) and output (RURI) is able to get the input SIP URI from a pseudo-variable and place the result back also in a pseudo-variable.
The function is usefull as the alias lookup does not affect the request it self (no RURI changes), can be used in a reply context (as it does not work with RURI only) and can be used for others URI than the RURI ( To URI, From URI, custom URI).
The function returns TRUE any alias mapping was found and returned.
->See http://www.opensips.org/html/docs/modules/1.6.x/alias_db.html#id228302
- both alias_db_lookup() and alias_db_find() may take an optional param, a list of flags (char based flags):
- 'd' - do not use domain part in the lookup (by default domain is used)
- 'r' - do reverse lookup - the input is the ID URI and the result is alias URI (normally the input is the alias URI and the result is the ID URI)
- use_domain module parameter was removed as replaced by the "d" per-lookup option.
2.13 AVPOPS module
- New function avp_insert(_pvar_name_, value, index) - inserts a value to an avp set at a certain position
2.14 AVP_RADIUS module
important - Removed as its functionality is now part of the AAA_RADIUS module - see the AAA API and module changes.
2.15 AUTH_RADIUS module
important - Renamed as AUTH_AAA module - see the AAA API and module changes.
2.16 BENACHMARK module
- allow granularity == 0 (disables automatic logging)
- add bm_poll_results MI command (poll current results and restart local counters)
- reject granularity < 0
2.17 CALL_CONTROL module
- new parameters init, start, stop added to support customized call_control messages directly from the script
- example:
modparam("call_control", "init", "call-id=$ci to=$tu from=$fu
authruri=$du another_field = $avp(i:10)")
- the message sent if one of these parameter is set will be the string resulted after expanding the pvars
2.18 CFGUTILS module
- New function set_count(_pvar_name_) - returns the number of values of the pseudovariable
- New function set_select_weight(_pvar_name_) - selects an element from the set formed by the values of the pseudovariable; the selection algorithm is the genetic algorithm roulette-wheel selection; it return the index of the element
2.19 DIALOG module
- added support for early dialogs in order to properly support PRACK requests
- dialog script flags, dialog profiles and dialog variables have DB persistence - all these data will be kept over an OpenSIPS restart.
- new function validate_dialog() for verifying the in-dialog requests against the date stored in dialog internal structure (cseq, rr set, contact) - this is used to discover bogus or malicious sequential requests.
- new PV $DLG_dir to return (as string) the direction of an in-dialog request.
2.20 DISPATCHER module
- ds_is_from_list() replaced with a more generic function ds_is_in_list("ip","port"). The new function takes as parameters the IP and PORT to test against the dispatcher list, instead of using only the source IP and PORT (as ds_is_from_list()).
ds_is_from_list() == ds_is_in_list("$si","$sp")
The new function can be used also if the destination is part of a dispatching set :
ds_is_in_list("$rd","$rp")
2.21 DROUTING module
- goes_to_gw() takes a second optional parameter (flags) to control the strip, the prefix and attr when GW matches
2.22 GROUP module
- is_user_in() renamed as db_is_user_in()
- get_user_group() renamed as db_get_user_group()
2.23 GROUP_RADIUS module
important - Removed as merged into GROUP module - see the AAA API and module changes.
2.24 LOAD_BALANCER module
2.25 MI_DATAGRAM
- the UDP communication is symmetric - the UDP reply packages are sent back from the RX socket - this helps when firewalls, nat , etc are in the middle; also from security point of view is a plus to know all the time the ports involved in the communication.
2.26 NAT_TRAVERSAL
- new UAC test "8" - tests if client has contacted OpenSIPS from an address that is different from the one in the Contact field. Only IP is compared by this test.
2.27 NATHELPER module
- MI command "nh_enable_ping", if triggered with no parameter, will return the internal status of natping (if enabled or disabled)
- new UAC test "32" - address in Contact is compared against source IP address of signaling
2.28 PERMISSIONS module
- this module was reorganized to use only one database table (so that no duplicate information is used) : trusted database table is no longer used and there is a new schema for the address database table
- the following script parameters are no longer used: peer_tag_avp, trusted_table, source_col
- ip_addr_col parameter was renamed as ip_col
- tag_col parameter was renamed as info_col
- from_col parameter was renamed as pattern_col
- the following functions were introduced: check_address(), check_source_address(), get_source_group() to replace allow_address(), allow_source_address(), allow_trusted()
- the new functions perform the same, but they are more flexible and use only one database table
2.29 PIKE module
New extensions on the pike module for extending the flood detection : (1) from checking requests only, to checking all SIP traffic and (2) from checking the valid SIP packages to checking all received data (even if junk). New way of using the module -> automatic - the module will install internal hooks to catch all incoming requests and replies (even if not well formed from SIP point of view) - more or less the module will monitor all incoming packages (from the network) on the SIP sockets. Each time the source IP of a package
needs to be analyse (to see if trusted or not), the module will run a script route - see "check_route" module parameter -, where, based on custom logic, you can decide if that IP needs to be monitored for flooding or not. As action, when flood is detected, the module will automatically drop the packages.
2.30 REGISTRAR module
- former global parameters like method_filtering, max_contacts, append_branches, use_path, path_mode and path_use_received are now per AOR / function parameters ; also
- lookup() function takes char flags (see http://www.opensips.org/html/docs/modules/devel/registrar.html#id271073):
- if parallel forking should be done or not for this lookup (if branches should be appended or not)
- if method filtering should be performed or not for this lookup
- save() function takes char flags (see http://www.opensips.org/html/docs/modules/devel/registrar.html#id228571):
- if contacts should not be saved in DB (cache update only)
- if no reply should be sent out
- the maximum number of contacts allowed for AOR
- path support control (what path mode should be used) - (former global params)
- path received (former global param)
- registered() function takes a third optional parameter - a callid ; in this case, the function will check if a contact with that callid is already registered or not.
- sock_flag was moved as flag of the save() function
2.31 TEXTOPS module
- new functions were added for SDP codec manipulation (see http://lists.opensips.org/pipermail/users/2009-July/007196.html):
- codec_exists(name[,clock]); //test if a codec exists
- codec_delete(name[,clock]); //delete a codec
- codec_move_up(name[,clock]); //move a codec to the front of the list
- codec_move_down(name[,clock]);//move a codec to the back of the list
- codec_exists_re ( regexp ); //test if a codec exists based on a POSIX regular expression.
- codec_delete_re( regexp ); //delete a codec based on a POSIX regular expression.
- codec_move_up_re( regexp ); //move a codec to the front of the list, based on a POSIX regular expression.
- codec_move_down_re( regexp );//move a codec to the back of the list, based on a POSIX regular expression.
2.32 TM module
- RFC 3326 support (Call Completed Elsewhere) added: A proxy forks an INVITE request and one of the branches returns a 200 (OK). The forking proxy includes this status code in a Reason header field in the CANCEL request that it sends to the rest of the branches.
- t_reply() function does not requires any more a prior create Transaction (as in 1.5). If no transaction is found, it will be automatically created.
- t_cancel_branch() take flags ("a" - cancel all branches; "o" - cancel all other branches except current; "" - current branch); t_cancel_call() is obsoleted and removed (same as t_cancel_branch("a")).
- per branch onreply route - when calling "t_on_reply()" from branch route, the reply route will be set only for the current branch (and not for the whole transaction) - that's it, it will be called only for relies belonging to that particular branch. Of course, from branch route, you can set different reply routes for each branch.
- - removed the dependency to Retry-After in 503 in order to do DNS based failure. This was debated on the sip-implementers mailing list and as the RFC3261 is a bit ambigous in that area, we prefer to have the common sense taking over.
2.33 UAC module
- new functions uac_replace_to() and uac_restore_to() to perform TO header changing in a safe manner - similar to uac_replace_from() and uac_restore_from()
2.34 URI_DB module
important - This module does not exists anymore as its was merged into URI module (see AAA API and module changes). All functions from this module are now in URI module and prefixed db_ string.
- New function get_auth_id() - Checks given uri-string username against URI table (if use_uri_table is set) or subscriber table database backend required). Returns true if the user exists in the database, and sets the given variables to the authentication id and realm corresponding to the given uri.
2.35 URI_RADIUS module
important - This module does not exists anymore as its was merged into URI module (see AAA API and module changes). All functions from this module are now in URI module and prefixed radius_ prefix from the name of the functions was replaced with aaa_.
