cfgutils Module

The initial value of the probability.

Default value is “10”.

   
modparam("cfgutils", "initial_probability", 15)
   

The config file name for that a hash value should be calculated on startup.

There is no default value, is no parameter is given the hash functionality is disabled.

   
modparam("cfgutils", "hash_file", "/etc/opensips/opensips.cfg")
   

The size of the hash table used to store the shared variables ($shv).

Default value is “64”.

modparam("cfgutils", "shv_hash_size", 1024)

Set the value of a shared variable ($shv(name)). The parameter can be set many times.

The value of the parameter has the format: _name_ '=' _type_ ':' _value_

Default value is “NULL”.

...
modparam("cfgutils", "shvset", "debug=i:1")
modparam("cfgutils", "shvset", "pstngw=s:sip:10.10.10.10")
...

Set the value of a script variable ($var(name)). The parameter can be set many times.

The value of the parameter has the format: _name_ '=' _type_ ':' _value_

Default value is “NULL”.

...
modparam("cfgutils", "varset", "init=i:1")
modparam("cfgutils", "varset", "gw=s:sip:11.11.11.11;transport=tcp")
...

The number of dynamic script locks to be allocated at OpenSIPS startup. This number must be a power of 2. (i.e. 1, 2, 4, 8, 16, 32, 64 ...)

Note that the lock_pool_size parameter only affects the number of dynamic locks created at startup. The pool of static locks only depends on the number of unique static strings supplied throughout the script to the set of static lock functions.

Default value is “32”.

modparam("cfgutils", "lock_pool_size", 64)

Generates a random floating point value between 0 - 100 and returns true if the value is less or equal to the currently set probability. If "probability" parameter is given, it will override the global parameter set by rand_set_prob().

Parameters:

...
if (rand_event()) {
  append_to_reply("Retry-After: 120\n");
  sl_send_reply(503, "Try later");
  exit;
}
# normal message processing follows
...

Set the “probability” of the decision.

Parameters:

...
rand_set_prob(4);
...

Reset the probability back to the initial_probability value.

...
rand_reset_prob();
...

Return the current probability setting, e.g. for logging purposes.

...
rand_get_prob();
   

Waits "time" seconds.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
sleep(1);
...
$var(secs) = 10;
sleep($var(secs));
...
			

Waits "time" micro-seconds.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
usleep(500000); # sleep half a sec
...
			

Debugging function that aborts the server. Depending on the configuration of the server a core dump will be created.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
abort();
...
			

Debugging function that dumps the status for the private (PKG) memory. This information is logged to the default log facility, depending on the general log level and the memlog setting. You need to compile the server with activated memory debugging to get detailed informations.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
pkg_status();
...
			

Debugging function that dumps the status for the shared (SHM) memory. This information is logged to the default log facility, depending on the general log level and the memlog setting. You need to compile the server with activated memory debugging to get detailed informations.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
shm_status();
...
			

Counts the number of values of a given variable. It makes sense to call this function only for variables that can take more values (AVPs, headers).

The result is returned in the second parameter.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
set_count($avp(dids), $var(num_dids));
...
			

This function selects an element from a set formed by the integer values of the given "int_list_var" variable. It applies the genetic algorithm - roulette-wheel selection to choose an element from a set. The probability of selecting a certain element is proportionate with its weight. It will return the index of that selected element.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
$var(next_gw_idx) = set_select_weight($avp(gw_success_rates));
...
			

This function returns the absolute difference between the two given timestamps. The result is expressed as microseconds and can be returned as either string or integer.

WARNING: when using delta_int, the function will return error code -1 in case the difference overflows the signed integer holder! (i.e. a diff of ~35 minutes or more)

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.

...
ts_usec_delta($var(t1s), 300, 10, $var(t2us), $var(diff_str));
...
			

The function returns a positive value if the specified time recurrence string matches the current time, or a negative value otherwise.

For checking some other Unix timestamp than the current one, the second parameter will contain the intended timestamp to check.

The syntax of each field is identical to the corresponding field from RFC 2445.

This function may be used from any route. It returns 1 on success and -1, -2 or -3 on failure, parsing or internal errors, respectively.

Meaning of the parameters is as follows:

Additionally, more complex time recurrence strings may be built by connecting multiple time recurrence strings (described above) using the logical AND ("&"), OR ("/") and NEG ("!") operators. Furthermore, the expressions may be paranthesized. Some examples:

...
# Only passing if still in 2012 and on a Bucharest-compatible timezone
if (check_time_rec("Europe/Bucharest|20120101T000000|20130101T000000"))
	xlog("Current system time matches the given Romanian time interval\n");
...
# Only passing if less than 30 days have passed from "dtstart", system timezone
if (check_time_rec("20121101T000000||p30d"))
	xlog("Current time matches the given interval\n");
...
			

Acquire the static lock which corresponds to "key". In case the lock is taken by another process, script execution will halt until the lock is released. Attempting to acquire the lock a second time by the same process, without releasing it first, will result in a deadlock.

The static lock functions guarantee that two different strings will never point to the same lock, thus avoiding introducing unnecessary (and transparent!) synchronization between processes. Their disadvantage is the nature of their parameters (static strings), making them inappropriate in certain scenarios.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE, STARTUP_ROUTE, TIMER_ROUTE, EVENT_ROUTE.

# acquire and release a static lock 
...
get_static_lock("Zone_1");
...
release_static_lock("Zone_1");
...

Release the static lock corresponding to "key". Nothing will happen if the lock is not acquired.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE, STARTUP_ROUTE, TIMER_ROUTE|EVENT_ROUTE.

# acquire and release a static lock 
...
get_static_lock("Zone_1");
...
release_static_lock("Zone_1");
...

Acquire the dynamic lock corresponding to "key". In case the lock is taken by another process, script execution will halt until the lock is released. Attempting to acquire the lock a second time by the same process, without releasing it first, will result in a deadlock.

The dynamic lock functions have the advantage of allowing string variables to be given as parameters, but the drawback to this is that two strings may have the same hashed value, thus pointing to the same lock. As a consequence, either two totally separate regions of the script will be synchronized (they will not execute in parallel), or a process could end up in a deadlock by acquiring two locks in a row on two different (but equally hashed) strings. To address the latter issue, use the strings_share_lock() function to test if two strings hash into the same dynamic lock.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE, STARTUP_ROUTE, TIMER_ROUTE|EVENT_ROUTE.

...
# acquire and release a dynamic lock on the "Call-ID" header field value
if (!get_dynamic_lock($ci)) {
	xlog("Error while getting dynamic lock!\n");
}
...
if (!release_dynamic_lock($ci) {
	xlog("Error while releasing dynamic lock!\n");
}
...

Release the dynamic lock corresponding to "key". Nothing will happen if the lock is not acquired.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE, STARTUP_ROUTE, TIMER_ROUTE|EVENT_ROUTE.

...
# acquire and release a dynamic lock on the "Call-ID" header field value
if (!get_dynamic_lock($ci)) {
	xlog("Error while getting dynamic lock!\n");
}
...
if (!release_dynamic_lock($ci) {
	xlog("Error while releasing dynamic lock!\n");
}
...

A function used to test if two strings will generate the same hash value. Its purpose is to prevent deadlocks resulted when a process successively acquires two dynamic locks on two strings which happen to point to the same lock.

Theoretically, the chance of two strings generating the same hash value decreases proportionally to the increase of the lock_pool_size parameter. In other words, the more dynamic locks you configure the module with, the higher the chance that all individual protected regions of your script will run in parallel, without waiting for each other.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE, STARTUP_ROUTE, TIMER_ROUTE|EVENT_ROUTE.

...
# Proper way of acquiring two dynamic locks successively
if (!get_dynamic_lock($avp(foo))) {
	xlog("Error while getting dynamic lock!\n");
}

if (!strings_share_lock($avp(foo), $avp(bar)) {
	if (!get_dynamic_lock($avp(bar))) {
		xlog("Error while getting dynamic lock!\n");
	}
}
...
if (!strings_share_lock($avp(foo), $avp(bar)) {
	if (!release_dynamic_lock($avp(bar)) {
		xlog("Error while releasing dynamic lock!\n");
	}
}

if (!release_dynamic_lock($avp(foo)) {
	xlog("Error while releasing dynamic lock!\n");
}
...

Fetch the current Unix time epoch with microsecond precision. Optionally, print this value as a floating point number (3rd parameter).

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE, STARTUP_ROUTE, TIMER_ROUTE, EVENT_ROUTE.

...
get_accurate_time($var(sec), $var(usec));
xlog("Current Unix timestamp: $var(sec) s, $var(usec) us\n");
...

Randomly shuffles AVPs with name.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.

...
$avp(foo) := "str1";
$avp(foo)  = "str2";
$avp(foo)  = "str3";
xlog("Initial AVP list is: $(avp(foo)[*])\n");       # str3 str2 str1
if(shuffle_avps( $avp(foo) ))
    xlog("Shuffled AVP list is: $(avp(foo)[*])\n");  # str1, str3, str2 (for example)
...
				

Waits a number of seconds. This function does exactly the same as sleep(), but in an asynchronous way. The script execution is suspended until the waiting is done; then OpenSIPS resumes the script execution via the resume route.

To read and understand more on the asynchronous functions, how to use them and what are their advantages, please refer to the OpenSIPS online Manual.

{
...
async( sleep("5"), after_sleep );
}

route[after_sleep] {
...
}

Waits a number of micro-seconds. This function does exactly the same as usleep(), but in an asynchronous way. The script execution is suspended until the waiting is done; then OpenSIPS resumes the script execution via the resume route.

To read and understand more on the asynchronous functions, how to use them and what are their advantages, please refer to the OpenSIPS online Manual.

{
...
async( usleep("1000"), after_usleep );
}

route[after_usleep] {
...
}

Set the probability value to the given parameter.

Parameters:

...
$ opensips-cli -x mi rand_set_prob 10
...

Reset the probability value to the inital start value.

This command don't need a parameter.

...
$ opensips-cli -x mi rand_reset_prob
...

Return the actual probability setting.

The function return the actual probability value.

...
$ opensips-cli -x mi get_prob
The actual probability is 50 percent.
...

Check if the actual config file hash is identical to the stored one.

The function returns 200 OK if the hash values are identical, 400 if there are not identical, 404 if no file for hashing has been configured and 500 on errors. Additional a short text message is printed.

...
$ opensips-cli -x mi check_config_hash
The actual config file hash is identical to the stored one.
...

Return the stored config file hash.

The function returns 200 OK and the hash value on success or 404 if no file for hashing has been configured.

...
$ opensips-cli -x mi get_config_hash
1580a37104eb4de69ab9f31ce8d6e3e0
...

Set the value of a shared variable ($shv(name)).

Parameters:

...
$ opensips-cli -x mi shv_set debug int 0
...

Get the value of a shared variable ($shv(name)).

Parameters:

...
$ opensips-cli -x mi shv_get debug
$ opensips-cli -x mi shv_get
...

This PV provides access to the environment variable 'name'.

...
xlog("PATH environment variable is $env(PATH)\n");
...
				 

Returns a random value from the [0 - 2^31) range.

...
$avp(10) = ($RANDOM / 16777216); # 2^24
if ($avp(10) < 10) {
   $avp(10) = 10;
}
append_to_reply("Retry-After: $avp(10)\n");
sl_send_reply(503, "Try later");
exit;
# normal message processing follows
   
				 

The PV provides access to broken-down time attributes.

The “name” can be:

...
if ($ctime(year) == 2008) {
	xlog("request: $rm from $fu to $ru in year 2008\n");
}
...
				 

It is a class of pseudo-variables stored in shared memory. The value of $shv(name) is visible across all opensips processes. Each “shv” has single value and it is initialized to integer 0. You can use “shvset” parameter to initialize the shared variable. The module exports a set of MI functions to get/set the value of shared variables.

...
modparam("cfgutils", "shvset", "debug=i:1")
...
if ($shv(debug) == 1) {
	xlog("request: $rm from $fu to $ru\n");
}
...