cfgutils Module

Henning Westerholt

1und1 Internet AG

Carsten Bock

BASIS AudioNet GmbH

Table of Contents
1. User's Guide
1.1. Overview
1.2. Dependencies
1.3. Exported Parameters
1.3.1. initial_probability (string)
1.4. Exported Functions
1.4.1. rand_event()
1.4.2. rand_set_prob(probabiltiy)
1.4.3. rand_reset_prob()
1.4.4. rand_get_prob()
1.4.5. sleep(time)
1.4.6. usleep(time)
1.5. MI Commands
1.5.1. rand_set_prop
1.5.2. rand_reset_prob
1.5.3. rand_get_prob
1.6. Exported pseudo-variables
1.6.1. $RANDOM
2. Developer's Guide
3. Frequently Asked Questions
List of Examples
1-1. initial_probability parameter usage
1-2. rand_event() usage
1-3. rand_set_prob() usage
1-4. rand_reset_prob() usage
1-5. rand_get_prob() usage
1-6. sleep usage
1-7. usleep usage
1-8. rand_set_prob usage
1-9. rand_reset_prob usage
1-10. rand_get_prob usage
1-11. RANDOM pseudo-variable usage

Chapter 1. User's Guide

1.1. Overview

The cfgutils module can be used to introduce some randomness to the behaviour of the server. It provides some 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.

Due the openser architecture the module uses only one seed for all the children, that means if you have for example three children, the random descision and the returned random value will repeat three times.

The module provides as well some 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.


1.2. Dependencies

The module depends on the following modules (in the other words the listed modules must be loaded before this module):

  • none


1.3. Exported Parameters

1.3.1. initial_probability (string)

The initial value of the probability.

Default value is "10".

Example 1-1. initial_probability parameter usage

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

1.4. Exported Functions

1.4.1. rand_event()

Return true or false, depending on a random value and a probability value.

Example 1-2. rand_event() usage

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

1.4.2. rand_set_prob(probabiltiy)

Set the "probability" of the decision.

"probability" can have a value from the range 0..100.

Example 1-3. rand_set_prob() usage

...
rand_set_prob("4");
...

1.4.3. rand_reset_prob()

Reset the probability back to the inital value.

Example 1-4. rand_reset_prob() usage

...
rand_reset_prob();
...

1.4.4. rand_get_prob()

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

Example 1-5. rand_get_prob() usage

...
rand_get_prob();
   

1.4.5. sleep(time)

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.

Example 1-6. sleep usage

...
sleep("1");
...
			

1.4.6. usleep(time)

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.

Example 1-7. usleep usage

...
usleep("500");
...
			

1.5. MI Commands

1.5.1. rand_set_prop

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.

Example 1-8. rand_set_prob usage

...
$ openserctl fifo rand_set_prob 10
200 OK
...

1.5.2. rand_reset_prob

Reset the probability value to the inital start value.

This command don't need a parameter.

Example 1-9. rand_reset_prob usage

...
$ openserctl fifo rand_reset_prob
200 OK
...

1.5.3. rand_get_prob

Return the actual probability setting.

The function return the actual probability value.

Example 1-10. rand_get_prob usage

...
$ openserctl fifo get_prob
200 OK
The actual probability is 50 percent.
...

1.6. Exported pseudo-variables

1.6.1. $RANDOM

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

Example 1-11. RANDOM pseudo-variable usage

...
if (get_random()) {
  $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
   
				 

Chapter 2. Developer's Guide

The module does not provide any API to use in other OpenSER modules.


Chapter 3. Frequently Asked Questions

3.1. Where can I find more about OpenSER?
3.2. Where can I post a question about this module?
3.3. How can I report a bug?

3.1. Where can I find more about OpenSER?

3.2. Where can I post a question about this module?

First at all check if your question was already answered on one of our mailing lists:

E-mails regarding any stable OpenSER release should be sent to and e-mails regarding development versions should be sent to .

If you want to keep the mail private, send it to .

3.3. How can I report a bug?

Please follow the guidelines provided at: http://sourceforge.net/tracker/?group_id=139143.