2. "Debug Proxy" for troubleshooting


This functionality only makes sense on Sipwise C5 CARRIER appliance environment that has an inactive proxy node available.

In order to troubleshoot/debug/capture a scenario, the "debug proxy" allows defining a list of "debug subscribers" that will be matched against From/To headers for every SIP message on a specific lb node. If matched that SIP message will be delivered to the assigned proxy node. In summary, any call to/from that subscriber will be easily traced since no calls are delivered by default to an inactive "debug proxy" node. Also, you can enable extra debug levels on the "debug proxy" node which will NOT affect production traffic on the platform.


The subscribers have to be specified in the same format as they are received on Kamailio LB (before all the rewrite rules applied).


In the following examples both proxy node prx99a and prx99b must be set to inactive nodes hosts.prx99a.status=inactive and hosts.prx99b.status=inactive in network.yml!

To enable the feature for INACTIVE prx99 proxy pair, execute:

ngcpcfg set /etc/ngcp-config/network.yml hosts.prx99a.status=inactive # for the safety
ngcpcfg set /etc/ngcp-config/network.yml hosts.prx99b.status=inactive # for the safety
ngcpcfg set /etc/ngcp-config/config.yml kamailio.lb.debug_uri.enable=yes
ngcpcfg apply 'Enable debug proxy on node prx99'
ngcpcfg push-parallel all

And make sure prx99 active node has this new config applied.

There’s a command-line tool available to manage the subscriber list. An example of use:

ngcp-debug-subscriber add lb01 +4310001000@example.org sipuser@example.org prx99
ngcp-debug-subscriber delete lb01 +4310001000@example.org
ngcp-debug-subscriber list lb01

Be aware that the list of debug subscribers belongs to just one lb pair, the info is kept in REDIS local database, it is necessary to survive LB restarts and/or HA switchovers. To skip saving in REDIS local database, specifying the option --no-store (in this case the information will stay in memory only and will be void on Kamailio LB restart):

ngcp-debug-subscriber add --no-store lb01 +10001042@example.org prx99

See more available options in general and per-action help messages:

ngcp-debug-subscriber --help
ngcp-debug-subscriber add --help

It is recommended to keep the amount of "debug subscribers" as small as possible (for performance reasons).

The "debug subscribers" is keept in a kamailio htable. htable index size value can be changed if necessary in config.yml using the option kamailio.lb.debug_uri.htable_idx_size. This is not the maximum size. From Kamailio htable documentation:

size - number to control how many slots (buckets) to create for the hash table.
A larger value means more slots with a higher probability for fewer collisions.
The actual number of slots (or buckets) created for the table is 2^size.
The possible range for this value is from 2 to 31, smaller or larger values
will be increased to 3 (8 slots) or decreased to 14 (16384 slots).
Note that each slot can store more than one item, when there are collisions of
hash ids computed for keys. The items in the same slot are stored in a linked list.
In other words, the size is not setting a limit of how many items can be
stored in a hash table, as long as there is enough free shared memory,
new items can be added.

The default value kamailio.lb.debug_uri.htable_idx_size=4 is enough for all the use cases in production.