Copyright © 2007, 2008, 2004 1und1 Internet AG, BASIS AudioNet GmbH, Elena-Ramona Modroiu, FhG FOKUS
Table of Contents
rand_event()
rand_set_prob(probabiltiy)
rand_reset_prob()
rand_get_prob()
sleep(time)
usleep(time)
abort()
pkg_status()
pkg_summary()
shm_status()
shm_summary()
set_gflag(flag)
reset_gflag(flag)
is_gflag(flag)
lock(key)
unlock(key)
core_hash(string1, string2, size)
List of Examples
initial_probability parameter usagehash_file parameter usageinitial parameter usagelock_set_size parameter usagerand_event() usagerand_set_prob() usagerand_reset_prob() usagerand_get_prob() usagesleep usageusleep usageabort usagepkg_status usagepkg_summary usageshm_status usageshm_summary usageset_gflag() usagereset_gflag() usageis_gflag() usagelock() usageunlock() usagecore_hash() usagerand_set_prob usagerand_reset_prob usagerand_get_prob usagecheck_config_hash usageget_config_hash usageset_gflag usagereset_gflag usageis_gflag usageget_gflags usageRANDOM pseudo-variable usageTable of Contents
rand_event()
rand_set_prob(probabiltiy)
rand_reset_prob()
rand_get_prob()
sleep(time)
usleep(time)
abort()
pkg_status()
pkg_summary()
shm_status()
shm_summary()
set_gflag(flag)
reset_gflag(flag)
is_gflag(flag)
lock(key)
unlock(key)
core_hash(string1, string2, size)
Useful extensions for the server configuration.
The cfgutils module can be used to introduce randomness to the behaviour of the server. It provides setup functions and the “rand_event” function. This function return either true or false, depending on a random value and a specified probability. E.g. if you set via fifo or script a probability value of 5%, then 5% of all calls to rand_event will return true. The pseudovariable “$RANDOM” could be used to introduce random values e.g. into a SIP reply.
The benefit of this module is the probability of the decision can be manipulated by external applications such as web interface or command line tools. The probability must be specified as percent value, ranging from 0 to 100.
The module exports commands to FIFO server that can be used to change the global settings via FIFO interface. The FIFO commands are: “set_prob”, “reset_prob” and “get_prob”.
This module can be used for simple load-shedding, e.g. reply 5% of the Invites with a 503 error and a adequate random Retry-After value.
The module provides as well functions to delay the execution of the server. The functions “sleep” and “usleep” could be used to let the server wait a specific time interval.
It can also hash the config file used from the server with a (weak) cryptographic hash function on startup. This value is saved and can be later compared to the actual hash, to detect modifications of this file after the server start. This functions are available as the FIFO commands “check_config_hash” and “get_config_hash”.
The gflags functionality (global flags) keeps a bitmap of flags in shared memory and may be used to change behaviour of server based on value of the flags. Example:
if (is_gflag("1")) {
t_relay("udp:10.0.0.1:5060");
} else {
t_relay("udp:10.0.0.2:5060");
}
The benefit of this is the value of the switch flags can be manipulated by external applications such as web interface or command line tools. The size of bitmap is 32.
The module exports external commands that can be used to change the global flags via Management Interface. The MI commands are: “set_gflag”, “reset_gflag” and “is_gflag”.
The module depends on the following modules (in the other words the listed modules must be loaded before this module):
none
The initial value of the probability.
Default value is “10”.
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.
Example 1.2. hash_file parameter usage
modparam("cfgutils", "hash_file", "/etc/kamailio/kamailio.cfg")
The initial value of global flags bitmap.
Default value is “0”.
Return true or false, depending on a random value and a probability value.
Example 1.5. rand_event() usage
...
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.
“probability” can have a value from the range 0..100.
Reset the probability back to the inital value.
Return the current probability setting, e.g. for logging purposes.
Waits "time" seconds.
Meaning of the parameters is as follows:
time - Time to wait in seconds.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
Waits "time" milli-seconds.
Meaning of the parameters is as follows:
time - Time to wait in milli-seconds.
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
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.
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.
Debugging function that dumps the summary for the private (PKG) memory usage. 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 ANY_ROUTE.
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.
Debugging function that dumps the summary for the shared (SHM) memory usage. 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 ANY_ROUTE.
Set the bit at the position “flag” in global flags.
“flag” can have a value in the range of 0..31.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Reset the bit at the position “flag” in global flags.
“flag” can have a value in the range of 0..31.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Check if bit at the position “flag” in global flags is set.
“flag” can have a value in the range of 0..31.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Example 1.18. is_gflag() usage
...
if(is_gflag("4"))
{
log("global flag 4 is set\n");
} else {
log("global flag 4 is not set\n");
};
...
Lock the key. Can be used to syncronize operations in config file, a hash id is computed over the key and appropriate lock is set in the lock array controlled by parameter "lock_set_size". Do not use lock() after another lock() unless you are sure the keys hit different array entries.
“key” can be static string or string with PVs.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Unlock the key.
“key” can be static string or string with PVs.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
Exported function that enables the core_hash() function to be used from the configuration file.
This is a quick and simple hash function and it is not cryptographically secure. This function should not be used for any security related purposes.
Parameters:
“string1” first string to hash
“string2” (optional) second string to hash (set to "" if not needed)
“size” size of the hash space (used as a power of 2)
This function can be used from ANY_ROUTE.
Functions that check or change some global flags accepts one parameter which is the flag bitmap/mask specifing the corresponding flags. It is not possible to specify directly the flag position that should be changed as in the functions available in the routing script.
Set the probability value to the given parameter. The parameter should be a percent value.
The parameter value must be a number from 0 to 100.
Reset the probability value to the inital start value.
This command don't need a parameter.
Return the actual probability setting.
The function return the actual probability value.
Example 1.24. rand_get_prob usage
... $ kamctl fifo 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.
Example 1.25. check_config_hash usage
... $ kamctl fifo 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.
Example 1.26. get_config_hash usage
... $ kamctl fifo get_config_hash 1580a37104eb4de69ab9f31ce8d6e3e0 ...
Set the value of some flags (specified by bitmask) to 1.
The parameter value must be a bitmask in decimal or hexadecimal format. The bitmask has a 32 bit size.
Reset the value of some flags to 0.
The parameter value must be a bitmask in decimal or hexadecimal format. The bitmask has a 32 bit size.
Returns true if the all the flags from the bitmask are set.
The parameter value must be a bitmask in decimal or hexadecimal format. The bitmask has a 32 bit size.
The function returns TRUE if all the flags from the set are set and FALSE if at least one is not set.
Example 1.29. is_gflag usage
... $ kamctl fifo set_gflag 1024 $ kamctl fifo is_gflag 1024 TRUE $ kamctl fifo is_gflag 1025 TRUE $ kamctl fifo is_gflag 1023 FALSE $ kamctl fifo set_gflag 0x10 $ kamctl fifo is_gflag 1023 TRUE $ kamctl fifo is_gflag 1007 FALSE $ kamctl fifo is_gflag 16 TRUE ...
Returns a random value from the [0 - 2^31) range.
Example 1.31. RANDOM pseudo-variable usage
...
if (rand_event()) {
$avp(i:10) = ($RANDOM / 16777216); # 2^24
if ($avp(i:10) < 10) {
$avp(i:10) = 10;
}
append_to_reply("Retry-After: $avp(i:10)\n");
sl_send_reply("503", "Try later");
exit;
};
# normal message processing follows