– Kamailio SIP Server –

New LCR Module Design (proposal)

A new design for Kamailio's LCR module making it simpler, more powerful, and easier to manage via an admin interface.

Introduction

Current LCR module lacks some useful features and it's hard to manage via an admin interface due to the complexity and not good relationship between its DB tables.

Some of the current design issues are:

  • LCR rule definitions are mixed with rule steps/targets in same 'lcr' table.
  • In order to reuse some gateway in two different groups it's required to duplicate all the information for the given gateway (ip, port, flags, ping…).
  • Summarizing, making an admin interface for LCR tables is difficult as the current design doesn't follow a good pattern.

Some desired features would be:

  • There si no way to make a rule stop if it fails to handle the request and we don't want other matching rules to be loaded (i.e: “I want calls to 001 just to use gw3 and not to use default gateways, those belonging to rule with NULL prefix, if gw3 is down).
  • Rules should be disabled without having to delete them.

In order to simplify implementation and use, gateway groups are no longer supported. Instead, gateways are directly specified as rule targets, where each rule target has a priority and weight.

New DB schema

lcr_rule

Column Description Possible values Default value
id Primary key: identifier of this rule Integer
lcr_id Identifier of LCR instance Integer
prefix Prefix of Request URI user part NULL / String NULL
from_uri Regular expression to match the From URI (or given pseudo-variable) NULL / String (regular expression) NULL
stopper If it's 1 no other rules would be inspected after finding this one Integer (1=on / 0=off) 0
enabled Is it this rule active so it can be loaded? Integer (1=on / 0=off) 1

Keys:

  • PRIMARY KEY: id
  • UNIQUE: lcr_id + prefix + from_uri

lcr_rule_target table

Column Description Possible values Default value
id Primary key Integer
rule_id Integer pointing to the id of an entry in lcr_rule table Integer
gw_id Gateway for this rule target (points to id in lcr_gw table) Integer
priority Priority of this rule target within all targets for the same rule Integer (0-255)
weight Weight of this rule target within all equal priority targets for the same rule Integer (1-254)

Keys:

  • PRIMARY KEY: id
  • UNIQUE: rule_id + gw_id
  • INDEX: rule_id

lcr_gw table

Column Description Possible values Default value
id Primary key, identifier of the gateway Integer
lcr_id Identifier of LCR instance Integer
gw_name Name of the gateway (only for documentation) String NULL
ip_addr IP of the gateway NULL / String NULL
port Port of the gateway NULL (no port is added) / Integer (5060=sip / 5061=sips) NULL
uri_scheme Scheme of the Request URI NULL / Integer (NULL and 1 = sip / 2=sips) NULL
transport Transport used for this gateway NULL (no transport is added) / Integer (0=udp / 1=tcp / 2=tls / 3=sctp) NULL
params URI params to be added to Request URI NULL / String NULL
hostname Hostname to set in Request URI host part NULL / String NULL
strip Number of characters to be stripped from the front of Request URI user NULL / Integer NULL
tag Prefix to be added to Request URI user part after removing strip characters NULL / String NULL
flags Flags enabled when loading this gateway Integer 0
defunct Gateway is defunct until this Linux timestamp time NULL (= 0) / Integer NULL

Keys:

  • PRIMARY KEY: id
  • UNIQUE: lcr_id + ip_addr + port + transport + hostname

New module parameters, functions and flags

flag(DONT_STRIP_OR_TAG)

When calling next_gw() function the value of flag(DONT_STRIP_OR_TAG) is inspected. If it is set then strip and tag values of the selected gateway are ignored so the Request URI user part is not modified.

This is an optional module parameter. If it's not defined then strip and tag are always applied for each gateway.

An use case in which this flag is useful:

  • The PSTN gateway allows national format (NNNNNNNNN) and international format with “00” (00NNNNNNNNNNNN).
  • Kamailio is configured to normalize destination numbers to E.164 (+NNNNNNNNN) if the call is international, or leave it in national format (no E.164).
  • In this case it's required to replace ”+“ with “00” when such gateway is selected by LCR module.
  • But it's also required not to modify the RURI user part if the number format is national.

The following configuration would do the job:

  • lcr_gw entry for the PSTN gateway:
    • strip: 1
    • tag: 00
  • Script configuration:
    # This route ensures that the dialed number is in the form +XXXXXX
    # (international E164) or national (XXXXXXX without + or 00):
    route(NORMALIZE_NUMBER);
     
    # Load gateways as usual.
    load_gws(...);
     
    # If the dialed number is national then enable the flag(DONT_USE_STRIP_TAG)
    # to avoid the RURI user part being striped and tagged with gw values.
    if !(starts_with("$rU", "+"))
      setflag(DONT_STRIP_OR_TAG);
     
    next_gw();