UAC REGISTRANT module

Admin Guide

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 “uac_registrant:list” MI command.

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;

Dependencies

OpenSIPS Modules

The following modules must be loaded before this module:

uac_auth - UAC authentication module

External Libraries or Applications

None.

Exported Parameters

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.

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

timer_interval (integer)

Defines the periodic timer for checking the registrations status.

Default value is 100.

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

failure_retry_interval (integer)

Defines a custom interval to retry the registration upon error/failure. Normally, after any kind of failure (timeout, credentials, internal error), the registration is re-taken after “expires” seconds. The parameter here, if set, overrides that value.

Default value is 0 (not set).

...
modparam("uac_registrant", "failure_retry_interval", 3600)
...

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.

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

db_url (string)

Database where to load the registrants from.

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

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

table_name (string)

The database table that holds the registrant records.

Default value is “registrant”.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

expiry_column (string)

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

Default value is “expiry”.

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

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 “socket” core parameter).

Default value is “forced_socket”.

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

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

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

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

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

reregister_expiry_percentage (integer)

Percentage describing how much sooner a RE-REGISTER needs to be send based on the Expiry. a 100 value means the RE-REGISTER will be send right on the edge of expiry ( old behavior ), which might lead to registration loss. a 90 value means the RE-REGISTER will be sent sooner , at 90% of the Expiry, etc.

Default value is “100”.

...
modparam("uac_registrant", "reregister_expiry_percentage", 90)
...

Exported Functions

None to be used in configuration file.

Exported MI Functions

uac_registrant:list

Replaces obsolete MI command: reg_list.

Lists the registrant records and their status.

Name: uac_registrant: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 uac_registrant:list
...
opensips-cli -x mi uac_registrant:list sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org

uac_registrant:reload

Replaces obsolete MI command: reg_reload.

Reloads the registrant records from the database.

Name: uac_registrant: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 uac_registrant:reload
...
opensips-cli -x mi reg_leload sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org

uac_registrant:enable

Replaces obsolete MI command: 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: uac_registrant: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 uac_registrant:enable sip:alice@opensips.org  sip:alice@127.0.0.1:5060 sip:opensips.org

uac_registrant:disable

Replaces obsolete MI command: 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: uac_registrant: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 disabled.
contact - Contact URI. If provided, aor and registrar parameters are also required and only a specific record will be disabled.
registrar - URI pointing to the remote registrar. If provided, aor and contact parameters are also required and only a specific record will be disabled.

MI FIFO Command Format:

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

uac_registrant:force_register

Replaces obsolete MI command: reg_force_register.

Forces the re-registration (or registation) of a specific registrant (depending on its state). Note that the registrant must be enabled.

Name: uac_registrant:force_register

Parameters:

aor - URI defining the address of record. If provided, contact and registrar parameters are also required and only a specific record will be forced to re-register.
contact - Contact URI. If provided, aor and registrar parameters are also required and only a specific record will be forced to re-register.
registrar - URI pointing to the remote registrar. If provided, aor and contact parameters are also required and only a specific record will be forced to re-register.

MI FIFO Command Format:

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

uac_registrant:upsert

Replaces obsolete MI command: reg_upsert.

Inserts or updates the in-memory contents of the AOR/Contact/Registrar. No Database queries are done when calling this MI command, all parameters are passed via MI

Name: uac_registrant:upsert

Parameters:

aor - URI defining the address
contact - Contact URI
registrar - URI pointing to the remote registrar
proxy - URI of a registration proxy
third_party_registrant - 3rd party registrant
username - the username for auth purposes
password - the password for auth purposes
binding_params - params to be added to the registration
expiry - number of seconds that the registration will be valid
forced_socket - opensips socket to send out the register out through
cluster_shtag - the sharing tag for this registration
state - 0 for enabled, 1 for disabled

MI FIFO Command Format:

opensips-cli -x mi uac_registrant:upsert aor=sip:vlad@test.com contact=sip:test@localhost registrar=sip:127.0.0.1:5061 proxy="" third_party_registrant="" username="vlad" password="1234" binding_params="" expiry=60 forced_socket="" cluster_shtag="" state=0

uac_registrant:delete

Replaces obsolete MI command: reg_delete.

Deletes the in-memory contents of the AOR/Contact/Registrar. No Database queries are done when calling this MI command, all parameters are passed via MI

Name: uac_registrant:delete

Parameters:

aor - URI defining the address
contact - Contact URI
registrar - URI pointing to the remote registrar

MI FIFO Command Format:

opensips-cli -x mi uac_registrant:delete aor=sip:vlad@test.com contact=sip:test@localhost registrar=sip:127.0.0.1:5061

Exported Events

E_REGISTRANT_REGISTERING

This event is raised when the module sent the initial REGISTER and started the registration process.

Parameters:

aor - the AOR
contact - the Contact
registrar - the Registrar

E_REGISTRANT_AUTHENTICATING

This event is raised when the initial REGISTER has been challenged and a new REGISTER with credentials has been sent out.

Parameters:

aor - the AOR
contact - the Contact
registrar - the Registrar

E_REGISTRANT_REGISTERED

This event is raised when a REGISTER has been 200 OKd.

Parameters:

aor - the AOR
contact - the Contact
registrar - the Registrar

E_REGISTRANT_REGISTER_TIMEOUT

This event is raised when a REGISTER received no reply from the registrar.

Parameters:

aor - the AOR
contact - the Contact
registrar - the Registrar

E_REGISTRANT_INTERNAL_ERROR

This event is raised when a REGISTER procesing was stopped due to an internal OpenSIPS error.

Parameters:

aor - the AOR
contact - the Contact
registrar - the Registrar

E_REGISTRANT_WRONG_CREDENTIALS

This event is raised when a REGISTER with credentials was still rejected by the registrar

Parameters:

aor - the AOR
contact - the Contact
registrar - the Registrar

E_REGISTRANT_REGISTRAR_ERROR

This event is raised when a REGISTER is rejected by the registrar with a non-standard sip code.

Parameters:

aor - the AOR
contact - the Contact
registrar - the Registrar

E_REGISTRANT_UNREGISTERING

This event is raised when a de-REGISTER is sent by OpenSIPS.

Parameters:

aor - the AOR
contact - the Contact
registrar - the Registrar

E_REGISTRANT_AUTHENTICATING_UNREGISTER

This event is raised when a de-REGISTER is challenged and auth is sent by OpenSIPS.

Parameters:

aor - the AOR
contact - the Contact
registrar - the Registrar

Exported Status/Report Identifiers

The module provides the “uac_registrant” Status/Report group, where each UAC registrant is defined as a separate SR identifier.

The name of each individual identitfier is built as follows:

   "aor=_AOR_;contact=_SIP_CONTACT_URI_;registrar=_SIP_REGISTAR_URI_"
   Ex:
   "aor=sip:vlad@test.com;contact=sip:test@mycontact.com;registrar=sip:127.0.0.1:5061"

In terms of status, the following values will be reported:

STATUS_READY, if REGISTERED
STATUS_LOADING_DATA, if REGISTERING, UNREGISTERING, AUTHENTICATING
STATUS_NOT_READY, any other state of the registrant

As reports, each identifier may provide information like:

$ opensips-cli -x mi  sr_list_reports uac_registrant
[
   {
       "Name": "aor=sip:vlad@test.com;contact=sip:test@mycontact.com;registrar=sip:127.0.0.1:5061",
       "Reports": [
           {
               "Timestamp": 1769604697,
               "Date": "Wed Jan 28 14:51:37 2026",
               "Log": "created with state NOT_REGISTERED_STATE\n"
           },
           {
               "Timestamp": 1769604707,
               "Date": "Wed Jan 28 14:51:47 2026",
               "Log": "state changed to REGISTERING_STATE\n"
           },
           {
               "Timestamp": 1769604712,
               "Date": "Wed Jan 28 14:51:52 2026",
               "Log": "state changed to REGISTER_TIMEOUT_STATE\n"
           }
       ]
   }
]

For how to access and use the Status/Report information, please see /manual/devel/interface-statusreport/.

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Ovidiu Sas (@ovidiusas)	147	41	5807	3387
2.	Bogdan-Andrei Iancu (@bogdan-iancu)	26	19	545	67
3.	Vlad Paiu (@vladpaiu)	26	10	1267	249
4.	Vlad Patrascu (@rvlad-patrascu)	18	7	796	182
5.	Razvan Crainea (@razvancrainea)	17	14	106	89
6.	Liviu Chircu (@liviuchircu)	17	14	59	70
7.	Stefan Darius (@dariusstefan)	17	5	1059	149
8.	Nick Altmann (@nikbyte)	5	3	44	5
9.	Maksym Sobolyev (@sobomax)	5	3	20	16
10.	James Stanley	4	2	21	14

All remaining contributors: sagarmalam, Walter Doekes (@wdoekes), James Stanley, Peter Lemenkov (@lemenkov), okhowang(王沛文).

(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

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

By Commit Activity

#	Name	Commit Activity
1.	Bogdan-Andrei Iancu (@bogdan-iancu)	Dec 2012 - Jul 2026
2.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
3.	Razvan Crainea (@razvancrainea)	Sep 2011 - Jun 2026
4.	Vlad Paiu (@vladpaiu)	Jul 2011 - Jan 2026
5.	Nick Altmann (@nikbyte)	Nov 2015 - Mar 2025
6.	okhowang(王沛文)	Jul 2024 - Jul 2024
7.	James Stanley	Dec 2023 - Jun 2024
8.	Ovidiu Sas (@ovidiusas)	Feb 2011 - Dec 2023
9.	Maksym Sobolyev (@sobomax)	Mar 2021 - Nov 2023
10.	James Stanley	Mar 2023 - Mar 2023

All remaining contributors: Liviu Chircu (@liviuchircu), Walter Doekes (@wdoekes), sagarmalam, Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov (@lemenkov).

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

Documentation

Contributors

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

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0