cfgutils Module

Henning Westerholt

   1und1 Internet AG

Carsten Bock

   BASIS AudioNet GmbH

   Copyright  2007 1und1 Internet AG, 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
   false. 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..99.

   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 99.

   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?

   Take a look at http://openser.org/.

   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:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

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