UAC Registrant Module


Table of Contents

1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. hash_size (integer)
1.3.2. timer_interval (integer)
1.3.3. enable_clustering (integer)
1.3.4. db_url (string)
1.3.5. table_name (string)
1.3.6. registrar_column (string)
1.3.7. proxy_column (string)
1.3.8. aor_column (string)
1.3.9. third_party_registrant_column (string)
1.3.10. username_column (string)
1.3.11. password_column (string)
1.3.12. binding_URI_column (string)
1.3.13. binding_params_column (string)
1.3.14. expiry_column (string)
1.3.15. forced_socket_column (string)
1.3.16. cluster_shtag_column (string)
1.3.17. state_column (string)
1.4. Exported Functions
1.5. Exported MI Functions
1.5.1. reg_list
1.5.2. reg_reload
1.5.3. reg_enable
1.5.4. reg_disable
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

List of Examples

1.1. Set hash_size parameter
1.2. Set timer_interval parameter
1.3. Set enable_clustering parameter
1.4. Set db_url parameter
1.5. Set table_name parameter
1.6. Set registrar_column parameter
1.7. Set proxy_column parameter
1.8. Set aor_column parameter
1.9. Set third_party_registrant_column parameter
1.10. Set username_column parameter
1.11. Set password_column parameter
1.12. Set binding_URI_column parameter
1.13. Set binding_params_column parameter
1.14. Set expiry_column parameter
1.15. Set forced_socket_column parameter
1.16. Set cluster_shtag_column parameter
1.17. Set state_column parameter

Chapter 1. Admin Guide

1.1. Overview

The module enable OpenSIPS to register itself on a remote SIP registrar.

At startup, the registrant records are loaded into a hash table in memory and a timer is started. The hash index is computed over the AOR field.

The timer interval for checking records in a hash bucket is computed by dividing the timer_interval module param by the number of hash buckets. When the timer fires for the first time, the first hash bucket will be checked and REGISTERs will be sent out for each record that is found. On the next timeout fire, the second hash bucket will be checked and so on. If the configured timer_interval module param is lower then the number of buckets, the module will fail to start.

Example: setting the timer_interval module to 8 with a hash_size of 2, will result in having 4 hash buckets (2^2=4) and buckets will be checked one by one every 2s (8/4=2).

Each registrant has it's own state. Registrant's status can be inspected via "reg_list" MI comand.

UAC registrant states:

  • 0 - NOT_REGISTERED_STATE - the initial state (no REGISTER has been sent out yet);

  • 1 - REGISTERING_STATE - waiting for a reply from the registrar after a REGISTER without authentication header was sent;

  • 2 - AUTHENTICATING_STATE - waiting for a reply from the registrar after a REGISTER with authentication header was sent;

  • 3 - REGISTERED_STATE - the uac is successfully registered;

  • 4 - REGISTER_TIMEOUT_STATE : no reply received from the registrar;

  • 5 - INTERNAL_ERROR_STATE - some errors were found/encountered during the processing of a reply;

  • 6 - WRONG_CREDENTIALS_STATE - credentials rejected by the registrar;

  • 7 - REGISTRAR_ERROR_STATE - error reply received from the registrar;

  • 8 - UNREGISTERING_STATE - waiting for a reply from the registrar after an unREGISTER without authentication header was sent;

  • 9 - AUTHENTICATING_UNREGISTER_STATE - waiting for a reply from the registrar after an unREGISTER with authentication header was sent;

1.2. Dependencies

1.2.1. OpenSIPS Modules

The following modules must be loaded before this module:

  • uac_auth - UAC authentication module

1.2.2. External Libraries or Applications

None.

1.3. Exported Parameters

1.3.1. hash_size (integer)

The size of the hash table internally used to keep the registrants. A larger table distributes better the registration load in time but consumes more memory. The hash size is a power of number two.

Default value is 1.

Example 1.1. Set hash_size parameter

...
modparam("uac_registrant", "hash_size", 2)
...

1.3.2. timer_interval (integer)

Defines the periodic timer for checking the registrations status.

Default value is 100.

Example 1.2. Set timer_interval parameter

...
modparam("uac_registrant", "timer_interval", 120)
...

1.3.3. enable_clustering (integer)

This parameter enables the clustering support in the module. This is used to share this registration between all the nodes in the cluster. When using this option, you should define (for each registrant record) a sharing tag - this sharing tag will control at the cluster level which node is entitled to perform the registation (only the node having that tag as active will do the registation, the onther nodes being idle).

Default value is 0 / off.

Example 1.3. Set enable_clustering parameter

...
modparam("uac_registrant", "enable_clustering", 1)
...

1.3.4. db_url (string)

Database where to load the registrants from.

Default value is NULL (use default DB URL from core).

Example 1.4. Set db_url parameter

...
modparam("uac_registrant", "db_url", "mysql://user:passw@localhost/database")
...

1.3.5. table_name (string)

The database table that holds the registrant records.

Default value is registrant.

Example 1.5. Set table_name parameter

...
modparam("uac_registrant", "table_name", "my_registrant")
...

1.3.6. registrar_column (string)

The column's name in the database storing the URI pointing to the remote registrar (mandatory field). OpenSIPS expects a valid URI.

Default value is registrar.

Example 1.6. Set registrar_column parameter

...
modparam("uac_registrant", "registrar_column", "registrant_uri")
...

1.3.7. proxy_column (string)

The column's name in the database storing the URI pointing to the outbond proxy (not mandatory field). An empty or NULL value means no outbound proxy, otherwise OpenSIPS expects a valid URI.

Default value is proxy.

Example 1.7. Set proxy_column parameter

...
modparam("uac_registrant", "proxy_column", "proxy_uri")
...

1.3.8. aor_column (string)

The column's name in the database storing the URI defining the address of record (mandatory field). The URI stored here will be used in the To URI of the REGISTER. OpenSIPS expects a valid URI.

Default value is aor.

Example 1.8. Set aor_column parameter

...
modparam("uac_registrant", "aor_column", "to_uri")
...

1.3.9. third_party_registrant_column (string)

The column's name in the database storing the URI defining the third party registrant (not mandatory field). The URI stored here will be used in the From URI of the REGISTER. An empty or NULL value means no third party registration (the From URI will be identical to To URI), otherwise OpenSIPS expects a valid URI.

Default value is third_party_registrant.

Example 1.9. Set third_party_registrant_column parameter

...
modparam("uac_registrant", "third_party_registrant_column", "from_uri")
...

1.3.10. username_column (string)

The column's name in the database storing the username for authentication (mandatory if the registrar requires authentication).

Default value is username.

Example 1.10. Set username_column parameter

...
modparam("uac_registrant", "username_column", "auth_username")
...

1.3.11. password_column (string)

The column's name in the database storing the password for authentication (mandatory if the registrar requires authntication).

Default value is password.

Example 1.11. Set password_column parameter

...
modparam("uac_registrant", "password_column", "auth_passowrd")
...

1.3.12. binding_URI_column (string)

The column's name in the database storing the binding URI in REGISTER (mandatory field). The URI stored here will be used in the Contact URI of the REGISTER. OpenSIPS expects a valid URI.

Default value is binding_URI.

Example 1.12. Set binding_URI_column parameter

...
modparam("uac_registrant", "binding_URI_column", "contact_uri")
...

1.3.13. binding_params_column (string)

The column's name in the database storing the binding params in REGISTER (not mandatory field). If not NULL or not empty, the string stored here will be added as params to the Contact URI in REGISTER (it MUST start with ;.

If the following two params are present, then the binding will be enforced to be unique (if two bindings are received in a 200ok, a complete binding removal will be performed before re-registering):

  • reg-id

  • +sip.instance

Example of params that will force unique binding:

;reg-id=1;+sip.instance="<urn:uuid:11111111-AABBCCDDEEFF>"
		

Default value is binding_params.

Example 1.13. Set binding_params_column parameter

...
modparam("uac_registrant", "binding_params_column", "contact_params")
...

1.3.14. expiry_column (string)

The column's name in the database storing the expiration time (not mandatory).

Default value is expiry.

Example 1.14. Set expiry_column parameter

...
modparam("uac_registrant", "expiry_column", "registration_timeout")
...

1.3.15. forced_socket_column (string)

The column's name in the database storing the socket for sending the REGISTER (not mandatory). If a forced socket is provided, the socket MUST be explicitely set as a global listening socket in the config (see listen core parameter).

Default value is forced_socket.

Example 1.15. Set forced_socket_column parameter

...
modparam("uac_registrant", "forced_socket_column", "fs")
...

1.3.16. cluster_shtag_column (string)

The column's name in the database storing the cluster sharing tag in [tag_name/cluster_id] format (not mandatory). If a cluster sharing tag is provided, the REGISTER requests will be fired out only when the tag is active.

Default value is cluster_shtag.

Example 1.16. Set cluster_shtag_column parameter

...
modparam("uac_registrant", "cluster_shtag_column", "sh")
...

1.3.17. state_column (string)

The column's name in the database storing the current state of the registrant. When a registrant is disabled, OpenSIPS will no longer send REGISTERs for it. A value of 0 for this column means enabled and 1 disabled.

Default value is state.

Example 1.17. Set state_column parameter

...
modparam("uac_registrant", "state_column", "status")
...

1.4. Exported Functions

None to be used in configuration file.

1.5. Exported MI Functions

1.5.1. reg_list

Lists the registrant records and their status.

Name: reg_list

Parameters:

  • aor (optional) - URI defining the address of record. If provided, contact and registrar parameters are also required and only a specific record will be listed.

  • contact (optional) - Contact URI. If provided, aor and registrar parameters are also required and only a specific record will be listed.

  • registrar (optional) - URI pointing to the remote registrar. If provided, aor and contact parameters are also required and only a specific record will be listed.

MI FIFO Command Format:

opensips-cli -x mi reg_list
...
opensips-cli -x mi reg_list sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org
		

1.5.2. reg_reload

Reloads the registrant records from the database.

Name: reg_reload

Parameters: none

  • aor (optional) - URI defining the address of record. If provided, contact and registrar parameters are also required and only a specific record will be reloaded.

  • contact (optional) - Contact URI. If provided, aor and registrar parameters are also required and only a specific record will be reloaded.

  • registrar (optional) - URI pointing to the remote registrar. If provided, aor and contact parameters are also required and only a specific record will be reloaded.

MI FIFO Command Format:

opensips-cli -x mi reg_reload
...
opensips-cli -x mi reg_leload sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org
		

1.5.3. reg_enable

Enables a specific registrant. OpenSIPS will immediately send a REGISTER if the registrant was previously disabled and will update the state in the database.

Name: reg_enable

Parameters: none

  • aor - URI defining the address of record.

  • contact - Contact URI.

  • registrar - URI pointing to the remote registrar.

MI FIFO Command Format:

opensips-cli -x mi reg_enable sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org
		

1.5.4. reg_disable

Disables a specific registrant. OpenSIPS will immediately send an unREGISTER if the registrant was previously enabled and will update the state in the database.

Name: reg_disable

Parameters: none

  • aor - URI defining the address of record. If provided, contact and registrar parameters are also required and only a specific record will be reloaded.

  • contact - Contact URI. If provided, aor and registrar parameters are also required and only a specific record will be reloaded.

  • registrar - URI pointing to the remote registrar. If provided, aor and contact parameters are also required and only a specific record will be reloaded.

MI FIFO Command Format:

opensips-cli -x mi reg_disable sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org
		

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Ovidiu Sas (@ovidiusas)1414056873266
2. Liviu Chircu (@liviuchircu)17145768
3. Vlad Patrascu (@rvlad-patrascu)157732118
4. Bogdan-Andrei Iancu (@bogdan-iancu)141030920
5. Razvan Crainea (@razvancrainea)1192636
6. Nick Altmann (@nikbyte)42354
7. Vlad Paiu (@vladpaiu)4263
8. Maksym Sobolyev (@sobomax)311612
9. sagarmalam31151
10. Walter Doekes (@wdoekes)3122

All remaining contributors: Peter Lemenkov (@lemenkov).

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Bogdan-Andrei Iancu (@bogdan-iancu)Dec 2012 - Jun 2023
2. Razvan Crainea (@razvancrainea)Sep 2011 - Nov 2021
3. Liviu Chircu (@liviuchircu)Mar 2014 - Jul 2021
4. Walter Doekes (@wdoekes)Apr 2021 - Apr 2021
5. Maksym Sobolyev (@sobomax)Mar 2021 - Mar 2021
6. sagarmalamJan 2021 - Jan 2021
7. Vlad Patrascu (@rvlad-patrascu)May 2017 - Dec 2020
8. Ovidiu Sas (@ovidiusas)Feb 2011 - Mar 2019
9. Peter Lemenkov (@lemenkov)Jun 2018 - Jun 2018
10. Nick Altmann (@nikbyte)Nov 2015 - Dec 2015

All remaining contributors: Vlad Paiu (@vladpaiu).

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Vlad Patrascu (@rvlad-patrascu), Ovidiu Sas (@ovidiusas), Razvan Crainea (@razvancrainea), Bogdan-Andrei Iancu (@bogdan-iancu), Peter Lemenkov (@lemenkov), Liviu Chircu (@liviuchircu).

Documentation Copyrights:

Copyright © 2011-2014 VoIP Embedded, Inc.