Table of Contents
default_expires (integer)min_expires (integer)max_expires (integer)default_q (integer)tcp_persistent_flag (string)realm_prefix (string)case_sensitive (integer)received_avp (str)received_param (string)expires_max_deviation (integer)max_contacts (integer)max_username_len (integer)max_domain_len (integer)max_aor_len (integer)max_contact_len (integer)retry_after (integer)sock_hdr_name (string)mcontact_avp (string)attr_avp (string)gruu_secret (string)disable_gruu (int)pn_enable (boolean)pn_providers (string)pn_ct_match_params (string)pn_pnsreg_interval (integer)pn_trigger_interval (integer)pn_skip_pn_interval (integer)pn_refresh_timeout (integer)pn_enable_purr (boolean)save(domain[, flags[, aor[, ownership_tag]]])
remove(domain, AOR[, [contact][, [next_hop][, [sip_instance], [bflag]]]])
remove_ip_port(IP,Port, domain, [AOR])
lookup(domain [, flags [, aor]])
is_registered(domain ,[AOR])
is_contact_registered(domain ,[AOR],[contact],[callid])
is_ip_registered(domain ,[AOR],IPvar,[PORTvar])
add_sock_hdr(hdr_name)
List of Tables
List of Examples
default_expires parametermin_expires parametermax_expires parameterdefault_q parametertcp_persistent_flag parameterrealm_prefix parametercase_sensitive parameterreceived_avp parameterreceived_param parameterexpires_max_deviation parametermax_contacts parameterretry_after parametersock_hdr_namer parametermcontact_avp parameterattr_avp parametergruu_secret parametergruu_secret parameterpn_enable parameterpn_providers parameterpn_ct_match_params parameterpn_pnsreg_interval parameterpn_trigger_interval parameterpn_skip_pn_interval parameterpn_refresh_timeout parameterpn_enable_purr parametersave usageremove usageremove_ip_port usagelookup usageis_registered usageis_contact_registered usageis_ip_registered usageadd_sock_hdr usageasync pn_process_purr() usageThe module contains SIP REGISTER request processing logic, per RFC 3261. On top of this support, several extensions are available:
The registrar module includes SIP Path header field support according to RFC 3327, for usage in registrars and home-proxies.
A call to save() stores, if path support is enabled in the registrar module, the values of the Path Header(s) along with the Contact information into usrloc. There are three modes for building the reply to a REGISTER message which includes one or more Path header fields:
off - stores the value of the Path headers into usrloc without passing it back to the UAC in the reply.
lazy - stores the Path header and passes it back to the UAC if Path-support is indicated by the “path” param in the Supported HF.
strict - rejects the registration with “420 Bad Extension” if there's a Path header but no support for it is indicated by the UAC. Otherwise it's stored and passed back to the UAC.
A call to lookup() always uses the Path header if found, and inserts it as Route HF either in front of the first Route HF, or after the last Via HF if no Route is present. It also sets the destination URI to the first Path URI, thus overwriting the received-URI, because NAT has to be handled at the outbound-proxy of the UAC (the first hop after client's NAT).
The whole process is transparent to the user, so no config changes are required besides enabling one of the "p0" / "p1" / "p2" flags when calling save().
The registrar module includes support for Globally Routable User Agent URIs according to RFC 5627.
A call to save() stores, if the phone supports GRUU, the values of the SIP Instance along with the contact into usrloc. The module will generate two types of GRUUs:
public - exposes the underlying AOR, constructed just by attaching the SIP Instance as the ;gr parameter value. These are persistent, valid as long as the contact registration is valid.
temporary - hides the underlying AOR Each new Register request leads to the construction of a new temporary GRUU, while Register requests with a different Call-ID lead to the invalidation of all the previous generated temporary GRUUs.
A call to lookup() will try to detect if the R-URI contains a GRUU. If it does, it will route the request just for the Contact that the specific AOR belongs to, without appending any other branches.
Even if the the GRUU handling during the registration process is transparent to the user, so no config changes are required, you need to take care of the GRUU specifics when handling mid-dialog requests.
As the GRUU will be present in the contact header of the initial requests generated byt GRUU enabled devices, you will have to also do a lookup() when receiving a mid-dialog request with the GRUU indication in the RURI.
The registrar module includes support for standards-based SIP Push Notifications, per RFC 8599. Support for the basic version of the draft can be enabled by switching pn_enable to true. The module also includes optional support for sending Push Notifications during long-lived dialogs (see RFC section 6), through the pn_enable_purr switch.
Essential mechanics behind the Push Notification (PN) support:
the PN support is fully compatible with the existing logic and enabling it does not impose any limitations, as the registrar can simultaneously handle both SIP PN compliant and standard SIP User Agents
OpenSIPS will raise a E_UL_CONTACT_REFRESH event any time a Push Notification needs to be sent to a PN-enabled contact. The event includes the PN coordinates of the contact -- they may be found in the Contact URI ('uri' event parameter) and may be extracted using the {uri.param,name} transformation. From here onwards, it is up to the script developer to trigger the Push Notification (e.g. possibly by sending an HTTP POST with the rest_client module), thus forcing a re-registration from the device.
REGISTER processing is unchanged -- PN-enabled UAs are saved just as regular UAs, with the former ones additionally having the 4 bitflag set in the "Flags" field of any MI listing of contacts, for differentiation purposes
initial INVITE processing is barely changed, with the lookup() function now additionally returning a value of 2 if the only found contacts were PN-enabled contacts, all which required a Push Notification. This means that PNs have been triggered for each of them and t_relay() is not required, since they are not reachable until they re-register!
Using the event_routing module, OpenSIPS will transparently fork a new branch from the current INVITE on each re-registration from these contacts within the accepted pn_refresh_timeout
mid-dialog requests: In some cases (e.g. long-lived dialogs), a PN may be required before being able to route a mid-dialog request to a SIP UA. The pn_process_purr() async function will take care of triggering the PN event and resuming the script as soon as a re-registration from the concerned contact is received.
For more information or examples, refer to the documentation of the "pn_xxx" module parameters or the OpenSIPS blog posts around the "SIP Push Notification" topic.
The following modules must be loaded before this module:
usrloc - User Location Module.
signaling - Signaling module.
event_routing, if pn_enable is set to true.
If the processed message contains neither Expires HFs nor expires contact parameters, this value will be used for newly created usrloc records. The parameter contains number of second to expire (for example use 3600 for one hour).
Default value is 3600.
The minimum expires value of a Contact, values lower than this minimum will be automatically set to the minimum. Value 0 disables the checking.
Default value is 60.
The maximum expires value of a Contact, values higher than this maximum will be automatically set to the maximum. Value 0 disables the checking.
Default value is 0.
The parameter represents default q value for new contacts. Because OpenSIPS doesn't support float parameter types, the value in the parameter is divided by 1000 and stored as float. For example, if you want default_q to be 0.38, use value 380 here.
Default value is 0.
The parameter specifies the message flag to be used to control the module behaviour regarding TCP connections. If the flag is set for a REGISTER via TCP containing a TCP contact, the module, via the “save()” function, will set the lifetime of the TCP connection to the contact expire value. By doing this, the TCP connection will stay on as long as the contact is valid.
Default value is -1 (disabled).
Example 1.5. Set tcp_persistent_flag parameter
...
modparam("registrar", "tcp_persistent_flag", "TCP_PERSIST_DURATION")
...
Prefix to be automatically strip from realm. As an alternative to SRV records (not all SIP clients support SRV lookup), a subdomain of the master domain can be defined for SIP purposes (like sip.mydomain.net pointing to same IP address as the SRV record for mydomain.net). By ignoring the realm_prefix "sip.", at registration, sip.mydomain.net will be equivalent to mydomain.net .
Default value is NULL (none).
If set to 1 then AOR comparison will be case sensitive (as RFC3261 instructs), if set to 0 then AOR comparison will be case insensitive.
Default value is 1.
Registrar will store the value of the AVP configured by this parameter in the received column in the user location database. It will leave the column empty if the AVP is empty. The AVP should contain a SIP URI consisting of the source IP, port, and protocol of the REGISTER message being processed.
The value of this parameter should be the same as the value of corresponding parameter of nathelper module.
Default value is "NULL" (disabled).
The name of the parameter that will be appended to Contacts of 200 OK when the received URI was set by nathelper module.
Default value is "received".
Set this parameter in order to add a random +/- deviation up to and including the given value to the expiration interval of a newly registered contact. For example, if this parameter is set to 100 and a phone registers for 1800 sec, the final expiry will be a random number in the [1700, 1900] interval.
By randomizing the registration lifetimes of the contacts, the server is better equipped to deal with a post-restart registration storm, when all TCP connections are lost and a significant portion of UAs will re-register at the same time. Thanks to the contact lifetime randomization, the registration storm will only happen once rather than, e.g., every 1800 seconds following the restart.
Default value is 0 (no deviation).
Example 1.10. Setting the expires_max_deviation parameter
...
# add a random +/- 0-100 seconds to each registration lifetime
modparam("registrar", "expires_max_deviation", 100)
...
The parameter can be used to limit the number of contacts per AOR (Address of Record) in the user location database. Value 0 disables the check.
This is the default value and will be used only if no other value (for max_contacts) is passed as parameter to the save() function. That's it - the function parameter overwride this global parameter.
Default value is 0.
Example 1.11. Set max_contacts parameter
...
# Allow no more than 10 contacts per AOR
modparam("registrar", "max_contacts", 10)
...
The maximum length of the "username" part of an Address-of-Record SIP URI.
Default value is 64.
Example 1.12. Setting the max_username_len module parameter
modparam("registrar", "max_username_len", 128)
The maximum length of the "domain" part of an Address-of-Record SIP URI.
Default value is 64.
Example 1.13. Setting the max_domain_len module parameter
modparam("registrar", "max_domain_len", 128)
The maximum length of an Address-of-Record SIP URI.
Default value is 256.
The maximum length of a Contact header field SIP URI.
Default value is 255.
Example 1.15. Setting the max_contact_len module parameter
modparam("registrar", "max_contact_len", 512)
The registrar can generate 5xx reply to REGISTER in various
situations. It can, for example, happen when the
max_contacts parameter is set and the
processing of REGISTER request would exceed the limit. In this case
the registrar would generate "503 Service Unavailable" response.
If you want to add the Retry-After header field in 5xx replies, set this parameter to a value grater than zero (0 means do not add the header field). See section 20.33 of RFC3261 for more details.
Default value is 0 (disabled).
Header which contains a socket description (proto:IP:port) to override the received socket info. The header will be search and used only if the flag 's' (Socket header) is set at "save()" time.
This makes sense only in multiple replicated servers scenarios.
Default value is NULL.
Example 1.17. Set sock_hdr_namer parameter
...
modparam("registrar", "sock_hdr_name", "Sock-Info")
...
AVP to store the modified binding/contact that is set during cached registrations scenario (when REGISTER is forwarded to another registrar). The AVP will be used to extract the "expires" value returned in the 200 OK by the main registrar.
This makes sense only in cached registrations scenario, where your OpenSIPS is caching registrations before forwarding them to the main registrar.
Default value is NULL.
Example 1.18. Set mcontact_avp parameter
...
modparam("registrar", "mcontact_avp", "$avp(orig_ct)")
...
route {
...
# before forwarding the REGISTER request, save the outgoing contact.
# Be SURE to do it after all the possible changes over the contact,
# like fix_nated_contact()
$avp(orig_ct) = $ct.fields(uri);
t_on_reply("do_save");
t_relay("udp:ip:port");
...
}
...
onreply_route[do_save] {
if ($rs=="200")
save("location");
}
...
AVP to store specific additional information for each registration. This information is read from the AVP and stored (in memory, db or both) at every registrar 'save'. When a registrar 'lookup' or 'is_registered' function is called, the attr_avp is populated with the value saved at [re]registration.
When doing call forking, the avp will hold multiple values. The position of the corresponding attribute information in attr_avp is equal to the branch index. An example scenario is given below.
Default value is NULL.
Example 1.19. Set attr_avp parameter
# reading attributes from the attr_pvar when doing parallel forking
...
modparam("registrar", "attr_avp", "$avp(attr)")
...
if (is_method("REGISTER")) {
$avp(attr) = "contact_info";
save("location");
exit;
}
...
lookup("location");
t_on_branch("parallel_fork");
...
branch_route [parallel_fork] {
xlog("Attributes for branch $T_branch_idx: $(avp(attr)[$T_branch_idx])\n");
}
The string that will be used in XORing when generating temporary GRUUs.
If not set, 'OpenSIPS' is the default secret.
Globally disable GRUU handling
Default value is 1 ( GRUU will not be handled ).
Enable SIP Push Notification support (RFC 8599). If enabled, Contact header field URIs which include all pn_ct_match_params will be matched against existing bindings using only these parameters. Otherwise, the module will attempt to match them as usual, using the current usrloc matching_mode.
Default value is false.
A list of supported Push Notification providers. While only three possible values are defined by RFC 8599 ("apns", "fcm" and "webpush"), non-standard values may be specified as well.
Default value is NULL (not set).
Example 1.23. Setting the pn_providers parameter
...
modparam("registrar", "pn_providers", "apns, fcm, webpush")
...
The minimally required list of RFC 8599 parameters (custom ones are accepted as well) which must be present in a Contact URI and identically match an existing binding in order for the binding to be refreshed during a SIP re-REGISTER. If at least one such parameter is missing from a Contact header field URI, the module will fall back to performing regular contact matching.
Note that if all above PN Contact URI parameters match an existing binding, the match is considered to be successful regardless if other parts of the SIP URI do not match (e.g. hostname, port, other URI parameters, etc.).
After calling lookup() or pn_process_purr(), the above PN-related parameters will be automatically stripped from the resulting Request and Contact URI event parameter, respectively.
Default value is "pn-provider, pn-prid, pn-param".
Example 1.24. Setting the pn_ct_match_params parameter
...
modparam("registrar", "pn_ct_match_params", "pn-provider, pn-prid")
...
For devices capable of waking up and refreshing their binding on their own (signified by the ";+sip.pnsreg" Contact header field parameter), this setting denotes the prior-to-expiration interval advertised by the server at which the device should issue its binding refresh request.
Default value is 130 (seconds before expiry).
Example 1.25. Setting the pn_pnsreg_interval parameter
...
modparam("registrar", "pn_pnsreg_interval", 140)
...
If a binding refresh REGISTER request from a given SIP endpoint does not arrive within at least pn_trigger_interval seconds prior to expiration (e.g. because the device does not support ";+sip.pnsreg" or because of other error conditions), the E_UL_CONTACT_REFRESH usrloc event will be triggered.
Once E_UL_CONTACT_REFRESH is triggered, the script writer should use the RFC 8599 parameters from the Contact URI in order to generate a Push Notification request to the PN provider of the device, in order to cause the device to wake up and re-register.
Default value is 120 (seconds before expiry).
Example 1.26. Setting the pn_trigger_interval parameter
...
modparam("registrar", "pn_trigger_interval", 130)
...
Following a successful (re)registration of a contact, this setting denotes a time interval, in seconds, during which the contact is assumed to be reachable, so any Push Notifications will be skipped.
Default value is 0 seconds (always generate Push Notifications).
Example 1.27. Setting the pn_skip_pn_interval parameter
...
modparam("registrar", "pn_skip_pn_interval", 10)
...
This timeout starts counting following a lookup() or a pn_process_purr() which triggers a Push Notification. The value represents the maximum allowed sum of the duration required for the Push Notification to be sent and the duration required for the corresponding re-registration from the device to arrive.
Once this timeout is exceeded for an initial or a mid-dialog request, any further re-registrations which match the pending Push Notification will no longer cause the desired effects. For example:
pending initial INVITE transactions will complete and will no longer auto-fork an additional branch for each REGISTER sent by the callee side
pending BYE messages will time out and OpenSIPS will attempt to route them despite not having received a confirmation that the target device is actually reachable
Default value is 6 seconds.
Example 1.28. Setting the pn_refresh_timeout parameter
...
modparam("registrar", "pn_refresh_timeout", 10)
...
Enable the SIP Push Notification mechanism for long-lived dialogs. If enabled, the registrar will include a "+sip.pnspurr" Feature-Caps header field tag in 200 OK replies to REGISTER requests. This tag represents a unique identifier for the registration (PURR - Proxy Unique Registration Reference).
During dialog setup, each UA may include, in its Contact header, the PURR value returned by OpenSIPS during registration. By including the PURR (e.g. ";pn-purr=XXX"), an agent indicates that it expects to be first awoken by a PN before being able to receive a mid-dialog request sent by the other party.
When enabling this parameter, make sure to also add logic for pn_process_purr().
Default value is false.
Example 1.29. Setting the pn_enable_purr parameter
...
modparam("registrar", "pn_enable_purr", true)
...
The function processes a REGISTER message. It can add, remove or modify usrloc records depending on Contact and Expires HFs in the REGISTER message. On success, 200 OK will be returned listing all contacts that are currently in usrloc. On an error, error message will be send with a short description in reason phrase.
Meaning of the parameters is as follows:
domain (static string) - Logical domain within registrar. If database is used then this must be name of the table which stores the contacts.
flags (string, optional) - string composed of one or more of the following flags, comma-separated:
'memory-only' - (old m flag) save the contacts only in memory cache without no DB operation;
'no-reply' - (old r flag) do not generate a SIP reply to the current REGISTER request.
'max-contacts=[int]' - (old c flag) this flag can be used to limit the number of contacts for this AOR (Address of Record) in the user location database. Value 0 disables the check. This parameter overrides the global "max_contacts" module parameter.
'force-registration' - (old f flag) this flag can be used to force the registration of NEW contacts even if the maximum number of contacts is reached. In such a case, older contacts will be removed to make space to the new ones, without exceeding the maximum allowed number. This flag makes sense only if "max-contacts" is used.
'matching-mode=[val]' - (old M flag) How the matching should be performed between the uploaded contacts (by the currently handled REGISTER) and the already know contacts (in memory or DB). This options will be used only for the current operation and can be:
'0' - contact URI matching only
'1' - contact URI and SIP Call-ID matching
'<param_name>' - only the value of the given URI param will be used for matching (for example <rinstance>)
'path-off' - (old p0 flag) (Path support - 'off' mode) - The Path header is saved into usrloc, but is never included in the reply.
'path-lazy' - (old p1 flag) (Path support - lazy mode) The Path header is saved into usrloc, but is only included in the reply if path support is indicated in the registration request by the “path” option of the “Supported” header.
'path-strict' - (old p2 flag) (Path support - strict mode) - The path header is only saved into usrloc, if path support is indicated in the registration request by the “path” option of the “Supported” header. If no path support is indicated, the request is rejected with “420 - Bad Extension” and the header “Unsupported: path” is included in the reply along with the received “Path” header. This mode is the one recommended by RFC-3327.
'path-received' - (old v flag) if set, the “received” parameter of the first Path URI of a registration is set as received-uri and the NAT branch flag is set for this contact. This is useful if the registrar is placed behind a SIP loadbalancer, which passes the nat'ed UAC address as “received” parameter in it's Path uri.
'only-request-contacts' - (old o flag) Only include the REGISTER request's Contacts in the 200 OK reply, in case the registration is successful. While this is against RFC 3261, it may be useful in certain scenarios.
'socket-header' - (old s flag) look into REGISTER request for a header which contains a socket description (proto:IP:port). This socket info will be stored by register instead of the received socket info.
'min-expires=[int]' - (old e flag) this flag can be used to set minimum register expiration time. Values lower than this minimum will be automatically set to the minimum. Value 0 disables the checking. This parameter overrides the global min_expires module parameter.
'max-expires=[int]' - (old E flag) this flag can be used to set maximum register expiration time. Values higher than this maximum will be automatically set to the maximum. Value 0 disables the checking. This parameter overrides the global max_expires module parameter.
This parameter is a string composed of a set of flags.
aor (string, optional) - a custom AOR; if missing, the AOR will be taken from the default place - the TO header URI.
ownership_tag (string, optional) - a cluster-shared tag (see the clusterer module documentation for more details) which will be attached to each contact saved from the current request. This tag is only relevant in clustered user location scenarios and helps determine the current logical owner node of a contact. This, in turn, is useful in order to restrict nodes which are not currently responsible for this contact from performing certain actions (for example: incorrectly originating pings from a non-owned virtual IP address in highly-available setups).
This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
If you plan to use the “save()” function in reply route, please refer to mcontact_avp module parameter.
Example 1.30. save usage
...
# save into 'location', no flags, use default AOR (TO URI)
save("location");
...
# save into 'location', do not update DB, max 5 contacts per AOR,
# use default AOR (TO URI)
save("location","memory-only, max-contacts=5");
...
# save into 'location', no flags, use as AOR the FROM URI
save("location","",$fu);
...
# save into 'location', no DB update, force registration, take AOR from AVP
save("location","memory-only, no-reply", $avp(aor));
...
# save into 'location', mark the contacts with the "vip" ownership tag and
# replicate these contacts to the backup node, which does not currently own "vip"
save("location", , , "vip");
...
Explicitly remove contacts behind a given address-of-record.
Meaning of the parameters is as follows:
domain (static string - Logical domain within the registrar. If a database is used, then this must be name of the table which stores the contacts.
AOR (string) - address-of-record to be searched (SIP URI)
contact (string, optional) - SIP URI filter for the contact to be removed. This must be the full SIP URI as used during registered.
next_hop (string, optional) - the next SIP IP address/hostname on the way back to this contact. See the section below for details on how the next hop is computed. Hostnames are resolved before matching.
sip_instance (string, optional) - a "+sip.instance" value to be used for filtering purposes.
blfag (string, optional) - a Branch Flag to be used for filtering purposes.
IMPORTANT: the IP address of each contact (for matching purposes) is computed as follows:
a. if a Path header is present, the hostname part of the Path URI will be resolved as the contact's IP address.
b. otherwise, if by using nathelper, the "Received" value (source IP of the next hop) is set for a contact, this becomes the chosen hostname to be resolved as the contact's IP address.
c. otherwise, the "hostname" part of the Contact header field URI is chosen to be resolved as the contact's IP address.
This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
Example 1.31. remove usage
...
# remove all contacts belonging to the "bob" AOR
remove("location", "sip:bob@atlanta.com");
...
# remove only bob's home phone contact
remove("location", "sip:bob@atlanta.com", "sip:bob@46.50.64.78");
...
# remove all bob's phones which are behind "50.60.50.60"
# note that "contact" parameter has to be specified with NULL value even though not used
$var(next_hop) = "50.60.50.60"
remove("location", "sip:bob@atlanta.com", , $var(next_hop));
...
# remove bob's phone with contact "sip:bob@46.50.64.78" that is behind "50.60.50.60"
remove("location", "sip:bob@atlanta.com", "sip:bob@46.50.64.78", "50.60.50.60");
...
# remove all contacts behind bob's mobile device X
remove("location", "sip:bob@atlanta.com", , , "<urn:uuid:e5e68d40-f08a-4600-b82e-ff4d5d8c1a8f>")
Remove all contacts behind a specific IP and Port, optionally filtering by AOR.
Meaning of the parameters is as follows:
IP (string) - IP of the Contact to be removed
Port (integer) - Port of the Contact to be removed
domain (static string - Logical domain within the registrar. If a database is used, then this must be name of the table which stores the contacts.
AOR (string, optional) - address-of-record to be searched (SIP URI)
This function can be used from ALL ROUTES.
Example 1.32. remove_ip_port usage
...
# remove all contacts behind 8.8.8.8 port 43213
remove_ip_port("8.8.8.8",43213,"location");
...
# remove only bob's contacts behind the 8.8.8.8:43213 host
remove_ip_port("8.8.8.8",43213,"location","sip:bob@atlanta.com");
...
The functions extracts username from Request-URI and tries to find all contacts for the username in usrloc. If there are no such contacts, -1 will be returned. If there are such contacts, Request-URI will be overwritten with the contact that has the highest q value and optionally the rest will be appended to the message (depending on append_branches parameter value).
If the method_filtering option is enabled, the lookup function will return only the contacts that support the method of the processed request.
Meaning of the parameters is as follows:
domain (static string) - Name of table that should be used for the lookup.
flags (string, optional) - string composed of one or more of the following flags, comma-separated:
'no-branches' - (old b flag) this flag controls how the lookup() function processes multiple contacts. If there are multiple contacts for the given username in usrloc and this flag is not set, Request-URI will be overwritten with the highest-q rated contact and the rest will be appended to sip_msg structure and can be later used by tm for forking. If the flag is set, only Request-URI will be overwritten with the highest-q rated contact and the rest will be left unprocessed.
'to-branches-only' - (old B flag) this flags forces all found contacts to be uploaded only as branches (in the destination set) and not at all in the R-URI of the current message. Using this option allows the lookup() function to also be used in the context of a SIP reply.
'branch' - (old r flag) this flag enables searching through existing branches for aor's and expanding them to contacts. For example, you have got AOR A in your ruri but you also want to forward your calls to AOR B. In order to do this, you must put AOR B in a branch, and if this flag enabled, the function will also expand AOR B to contacts, which will be put back into the branches. The AOR's that were in branches before the function call shall be removed.
WARNING: if you want this flag activated, the 'no-branches' flag must not be set, because by setting that flag you won't allow lookup() to write in a branch.
'method-filtering' - (old m flag) setting this flag will enable contact filtering based on the supported methods listed in the "Allow" header field during registration. Contacts which did not present an "Allow" header field during registration are assumed to support all standard SIP methods.
'ua-filtering=[val]' (old u flag) (User-Agent filtering) - this flag enables regexp filtering by user-agent. It's useful with enabled append_branches parameter. The value must use the format '/regexp/'.
'case-insensitive' (old i flag) - this flag enables case insensitive filtering for the 'ua-filtering' flag.
'extended-regexp' - (old e flag) this flag enables using of extended regexp format for the 'ua-filtering' flag.
'global' (old g flag) (Global lookup) - this flag is only relevant with federated user location clustering. If set, the lookup() function will not only perform the classic in-memory "search-AoR-and-push-branches" operation, but will also perform a metadata lookup and append an additional branch for each returned result. The "in-memory branches" correspond to local contacts (current location), while the "metadata branches" correspond to contacts available on one or more of the remaining locations of the platform.
The AoR metadata consists of the minimally required information in order for one of the VoIP platform's locations (data centers) to advertise the presence of a locally registered AoR for the global platform. Specifically, this consists of two pieces of information:
the AoR (e.g. "vladimir@federation-cluster")
the home IP (e.g. "10.0.0.223")
'max-ping-latency=[int]' - (old y flag) maximally accepted contact pinging latency (microseconds). Contacts of an AoR with a higher latency will be discarded during lookup().
'sort-by-latency' - (old Y flag) contacts will be picked in ascending order of their last successful pinging latency (fastest ping -> slowest ping). This flag may work together with the "max-ping-latency" flag.
AOR (string, optional) - AOR to lookup for; if missing, the RURI is used as AOR;
Return codes:
1 - contacts found and successfully pushed as branches. Contacts which required awakening prior to being reachable are being notified via async Push Notifications.
2 - successfully started at least one async Push Notification for the found contacts, however no extra branches were populated (i.e. there is no need to call t_relay()).
-1 - no contact found.
-2 - contacts found, but neither of them supports the current SIP method.
-3 - internal error during processing.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
Example 1.33. lookup usage
...
lookup("location"); # simple lookup
#or
lookup("location", "method-filtering"); # lookup with method filtering
#or
lookup("location", "branch"); # lookup with aor branch search;
# all contacts except the first one shall be put
# in the branches
#or
lookup("location", "ua-filtering=/phone/i"); # lookup with user-agent filtering
#or
lookup("location", "", $var(aor)); # simple lookup with AOR from var
switch ($retcode) {
case -1:
case -3:
sl_send_reply(404, "Not Found");
exit;
case -2:
sl_send_reply(405, "Not Found");
exit;
};
...
The function returns true if an AOR is registered, false otherwise. The function does not modify the message being process.
NOTE: if called for a reply (from onreply_route), you must pass an AOR (as parameter), otherwise the function will fail.
Meaning of the parameters is as follows:
domain (static string) - Name of table that should be used for the lookup.
AOR (string, optional) - AOR to lookup for; if missing, the source if the AOR is the "To" header for REGISTER request, "From" header for any other sip request.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.
Example 1.34. is_registered usage
...
/**/
if (is_method("REGISTER")) {
/* automatically uses the URI from the To header */
if (is_registered("location")) {
xlog("this AOR is registered\n")
...
}
};
/* check the From uri whether this aor is registered or not */
if (is_registered("location",$fu)) {
xlog("caller is registered\n");
}
...
The function returns true if a contact and/or a callid from a certain AOR is registered, false otherwise. The function does not modify the message being process.
Meaning of the parameters is as follows:
domain (static string) - Name of table that should be used for the lookup.
AOR (string, optional) - AOR to lookup for; if missing, the source if the AOR is the "To" header for REGISTER request, "From" header for any other sip request.
contact (contact, optional) (optional)- SIP URI to check if there is a registration with this URI as cotact (this may help you to make distinction between multiple registrations for the same user/AOR).
callid (string, optional) - callid to check if a contact if registered with this callid (this may help you to make distinction between newly registered contact (callid not registered so far) and re-registration (callid already registered).
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.
Example 1.35. is_contact_registered usage
...
/*let's say you want to block users that are not registered*/
if (is_method("INVITE")) {
if (!is_contact_registered("location")) {
sl_send_reply(401, "Unauthorized");
...
}
}
/* you want to check the second contact from the message whether it is
registered or not */
if(is_method("INVITE")) {
if (is_contact_registered("location",$fu,$(ct[1]),))
xlog("caller is registered\n");
}
...
The function returns true if there is at least one contact that has been registered from the IP in the IPvar variable ( and from the optional PORTvar variable ). The IP is matched against the received host, if it exists, or the contact host otherwise. This function does not modify the message being process. This function replaces the old "is_other_contact" function.
Meaning of the parameters is as follows:
domain (static string) - Name of table that should be used for the lookup.
AOR (string, optional) - AOR to lookup for; if missing, the source if the AOR is the "To" header for REGISTER request, "From" header for any other sip request.
IPvar (var) - the variable containing the IP matched against the contact host or the received host (see above). If the IPvar is an AVP containing multiple values/IPs, then all the values are checked.
PORTvar (var, optional) - the variable containing the port to be matched against the contact host or the received host (see above). If the IPvar is an AVP containing multiple values/IPs, then the PORTvar is expected to contain the same number of entries, and all the values are checked.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.
Example 1.36. is_ip_registered usage
...
/* check the source ip whether it is already registered */
if (is_method("REGISTER")) {
if (is_ip_registered("location",$tu,$si)) {
xlog("already registered from this ip\n");
...
}
};
...
Adds to the current REGISTER request a new header with “hdr_name” which contains the description of the received socket (proto:ip:port)
This makes sense only in multiple replicated servers scenarios.
Meaning of the parameters is as follows:
hdr_name (string) - header name to be used.
This function can be used from REQUEST_ROUTE.
Perform mid-dialog request processing, according to RFC 8599. For such requests, search the R-URI and topmost Route header field URI for a ";pn-purr" parameter value that both matches the OpenSIPS PURR format and corresponds to an usrloc registration. Once a usrloc contact is located, trigger an E_UL_CONTACT_REFRESH event and place the request on async hold for at most pn_refresh_timeout seconds, until a matching REGISTER request arrives.
If processing ends before triggering the Push Notification, the request will no longer be put on async hold, with the resume route being immediately called.
Meaning of the parameters is as follows:
domain (static string) - Logical domain within registrar. If a database is used, then this must be name of the table which stores the contacts.
Return Codes
1 - Success, PN was launched.
2 - Success, but PN was not launched (due to missing PURR, foreign PURR or offline contact)
-1 - Internal Error
Example 1.38. async pn_process_purr() usage
route {
...
if (has_totag()) {
if (is_method("ACK") && t_check_trans()) {
t_relay();
exit;
}
if (!loose_route()) {
send_reply(404, "Not Found");
exit;
}
if (!is_method("ACK"))
async (pn_process_purr("location"), resume_route);
route(relay);
exit;
}
}
route [resume_route] {
$var(rc) = $rc;
xlog("pn_process_purr() finished with $var(rc)\n");
...
}
2.1. | What happened with the old “append_branch” module parameter? |
It was removed as global option, as the “lookup” function takes this option via the flag "b" (append Branches) See the documentation of the “lookup” function. | |
2.2. | What happened with the old “method_filtering” module parameter? |
It was removed as global option, as the “lookup” function takes this option via the flag "m" (Method filtering) See the documentation of the “lookup” function. | |
2.3. | What happened with the old “sock_flag” module parameter? |
It was removed as global option, as the “save” function takes this option via the flag "s" (Socket header) See the documentation of the “save” function. | |
2.4. | What happened with the old “use_path” and “path_mode” module parameters? |
They were removed as global option, as the “save” function takes these options via the flag "px" (path support) See the documentation of the “save” function. | |
2.5. | What happened with the old “path_use_received” module parameter? |
It was removed as global option, as the “save” function takes this option via the flag "v" (path receiVed) See the documentation of the “save” function. | |
2.6. | What happened with the old “nat_flag” module parameter? |
It was removed, as the module internally loads this value from the “USRLOC” module (see the “nat_bflag” USRLOC parameter). | |
2.7. | What happened with the old “use_domain” module parameter? |
It was removed, as the module internally loads this option from the “USRLOC” module. This was done in order to simplify the configuration. | |
2.8. | What happened with the old “save_noreply” and “save_memory” functions? |
There functions were merged into the new “save(domain,flags)” functions. If a reply should be sent or if the DB should be updated also is controlled via the flags. | |
2.9. | Where can I find more about OpenSIPS? |
Take a look at https://opensips.org/. | |
2.10. | 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:
E-mails regarding any stable OpenSIPS release should be sent to
If you want to keep the mail private, send it to
| |
2.11. | How can I report a bug? |
Please follow the guidelines provided at: https://github.com/OpenSIPS/opensips/issues. | |
2.12. | What happened to the desc_time_order parameter? |
It was removed, as its functionality was mmigrate into usrloc module, were there is a parameter with the same name. |
Table 3.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| Name | DevScore | Commits | Lines ++ | Lines -- | |
|---|---|---|---|---|---|
| 1. | Liviu Chircu (@liviuchircu) | 195 | 121 | 2851 | 3020 |
| 2. | Bogdan-Andrei Iancu (@bogdan-iancu) | 170 | 115 | 2410 | 2047 |
| 3. | Jan Janak (@janakj) | 121 | 73 | 3465 | 1102 |
| 4. | Daniel-Constantin Mierla (@miconda) | 23 | 19 | 160 | 105 |
| 5. | Vlad Paiu (@vladpaiu) | 21 | 12 | 729 | 96 |
| 6. | Vlad Patrascu (@rvlad-patrascu) | 21 | 9 | 243 | 497 |
| 7. | Razvan Crainea (@razvancrainea) | 20 | 15 | 267 | 75 |
| 8. | Ionut Ionita (@ionutrazvanionita) | 16 | 4 | 763 | 248 |
| 9. | Jiri Kuthan (@jiriatipteldotorg) | 15 | 9 | 538 | 45 |
| 10. | Andreas Granig | 13 | 7 | 527 | 36 |
All remaining contributors: Henning Westerholt (@henningw), Maksym Sobolyev (@sobomax), Andrei Pelinescu-Onciul, Ovidiu Sas (@ovidiusas), Juha Heinanen (@juha-h), Nick Altmann (@nikbyte), Ancuta Onofrei, Elena-Ramona Modroiu, Peter Lemenkov (@lemenkov), Dan Pascu (@danpascu), Sergio Gutierrez, Carsten Bock, Jeffrey Magder, Kobi Eshun (@ekobi), Dudu Ben Moshe, Marcus Hunger, Julián Moreno Patiño, Phil D'Amore, Klaus Darilion, Irina-Maria Stanescu, Dmitry Semyonov, Konstantin Bokarius, Jesus Rodrigues, Dusan Klinec (@ph4r05), Ruslan Bukin, Saúl Ibarra Corretgé (@saghul), @jalung, Tolga Tarhan, Edson Gellert Schubert.
(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
Table 3.2. Most recently active contributors(1) to this module
| Name | Commit Activity | |
|---|---|---|
| 1. | Liviu Chircu (@liviuchircu) | Mar 2013 - Sep 2024 |
| 2. | Bogdan-Andrei Iancu (@bogdan-iancu) | Sep 2003 - Apr 2024 |
| 3. | Dudu Ben Moshe | Feb 2024 - Feb 2024 |
| 4. | Maksym Sobolyev (@sobomax) | Jul 2004 - Nov 2023 |
| 5. | Vlad Patrascu (@rvlad-patrascu) | May 2017 - May 2023 |
| 6. | Razvan Crainea (@razvancrainea) | Apr 2011 - Apr 2023 |
| 7. | Vlad Paiu (@vladpaiu) | Sep 2011 - Nov 2022 |
| 8. | Peter Lemenkov (@lemenkov) | Jun 2018 - Feb 2020 |
| 9. | @jalung | Aug 2017 - Aug 2017 |
| 10. | Ovidiu Sas (@ovidiusas) | May 2011 - Mar 2017 |
All remaining contributors: Ionut Ionita (@ionutrazvanionita), Julián Moreno Patiño, Dusan Klinec (@ph4r05), Nick Altmann (@nikbyte), Tolga Tarhan, Saúl Ibarra Corretgé (@saghul), Ruslan Bukin, Irina-Maria Stanescu, Kobi Eshun (@ekobi), Phil D'Amore, Sergio Gutierrez, Klaus Darilion, Henning Westerholt (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Jesus Rodrigues, Dan Pascu (@danpascu), Ancuta Onofrei, Marcus Hunger, Juha Heinanen (@juha-h), Elena-Ramona Modroiu, Jeffrey Magder, Carsten Bock, Andreas Granig, Dmitry Semyonov, Jan Janak (@janakj), Andrei Pelinescu-Onciul, Jiri Kuthan (@jiriatipteldotorg).
(1) including any documentation-related commits, excluding merge commits
Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu Chircu (@liviuchircu), Dudu Ben Moshe, Vlad Patrascu (@rvlad-patrascu), Razvan Crainea (@razvancrainea), Vlad Paiu (@vladpaiu), Peter Lemenkov (@lemenkov), Ionut Ionita (@ionutrazvanionita), Julián Moreno Patiño, Nick Altmann (@nikbyte), Ovidiu Sas (@ovidiusas), Irina-Maria Stanescu, Kobi Eshun (@ekobi), Sergio Gutierrez, Klaus Darilion, Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Jesus Rodrigues, Marcus Hunger, Juha Heinanen (@juha-h), Elena-Ramona Modroiu, Carsten Bock, Andreas Granig, Jan Janak (@janakj).
Documentation Copyrights:
Copyright © 2003 FhG FOKUS
Copyright © 2020 OpenSIPS Solutions