---
title: "mid_registrar Module"
description: "The *mid_registrar* is a mid-component of a SIP platform, designed to work between end users and the platform's main registration component."
---

## Admin Guide


### Overview


The *mid_registrar* is a mid-component of a SIP
platform, designed to work between end users and the platform's main
registration component.

It opens up new possibilities for leveraging existing infrastructure in
order to continue to grow (as subscribers and as registration traffic)
while keeping an existing low-resources registrar server.


Acting as a registration front-end to the main SIP registrar, the
mid-registrar is able to:


- convert incoming high-rate registration traffic into a low-rate
variant, towards the main registrar layer. With proper
configuration, it can absorb over 90% of existing registration
traffic while correctly managing the back-end's user location
state, effectively reducing resource usage at the respective layer.
- stay synchronized with the main registrar (from a user
location perspective), by properly
accepting the contact states and expirations it decides.


#### Path Support (RFC 3327)


The mid_registrar module includes SIP Path header field support
according to
[RFC 3327](https://tools.ietf.org/html/rfc3327),
for usage in registrars and home-proxies.


A call to *mid_registrar_save()* stores, if path support is enabled
in the mid_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 *mid_registrar_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 *mid_registrar_save()*.


#### GRUU Support (RFC 5627)


The mid_registrar module includes support for Globally Routable User
Agent URIs according to [RFC 5627](https://tools.ietf.org/html/rfc5627).


A call to *mid_registrar_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 *mid_registrar_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.


#### SIP Push Notification Support (RFC 8599)


The mid_registrar module includes support for standards-based SIP Push
Notifications, per
[RFC 8599](https://tools.ietf.org/html/rfc8599).
Support for the basic version of the draft can be enabled by switching
[pn enable](#pn_enable-boolean) to *true*.  The
module also includes optional support for sending Push Notifications
during long-lived dialogs ([see RFC section 6](https://tools.ietf.org/html/rfc8599#page-23)),
through the [pn enable purr](#pn_enable_purr-boolean) 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
mid_registrar can simultaneously handle both SIP PN compliant
and standard SIP User Agents
- OpenSIPS will raise a
[E_UL_CONTACT_REFRESH](../usrloc/README.md#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](../rest_client/README.md) 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 *mid_registrar_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](#pn_refresh_timeout-integer)
- 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 [afunc pn process purr](#pn_process_purrdomain)
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.


### Working modes


The mid_registrar may function in one of several modes:


#### Contact mirroring (default)


In "contact mirroring" mode, the mid-registrar will only insert itself
in the SIP traffic flow between end user and main registrar by
altering the Contact header field values. See section
[sip flow insertion](#auto-insertion-into-future-sip-flows) for a detailed description of
possible Contact-based insertion modes. The incoming REGISTER requests
will be proxied further to the main registrar; the registered contact
will be stored in the mid-registrar only on 2xx replies, according to
the information returned by the main registrar.


A possible usage of this mode, for example, would be to clone
registrations on a SIP front-end that extends the main platform with
new services (like adding IM/messaging routing).


#### Contact throttling


In "contact throttling" mode, the mid-registrar can significantly
reduce the registration rate on the main registrar side (between
mid-registrar and main registrar), while coping with a high registration
rate on the end-user side (between end-user and mid-registrar). This
is useful in scenarios were the end-users are very dynamic and
short-lived  (e.g. mobile devices), but the main registrar cannot cope
with large amounts of registration traffic.


Traffic conversion is done in a *"per-device"*
manner, according to each unique SIP Contact header field value. It is
achieved by increasing the "expires" parameter value of each contact,
when relaying registrations to the main registrar.
Once such a registration is completed, subsequent registrations for the
same SIP Contact header field value will be continuously absorbed by
the mid-registrar until, eventually, the lifetime of the remote
registration will have decreased enough that a refresh (i.e. simply
forwarding the next REGISTER request) is mandatory.


A common occurence is for some SIP User Agents to lose their network
connection (especially when dealing with mobile devices), hence they do
not properly de-register from the mid-registrar. In this case, in order
to avoid stale registrations on the main registrar (which contains SIP
contacts with greatly extended lifetimes!), the mid-registrar will
appropriately generate De-REGISTER requests and remove these contacts
from the main registrar's location service as soon as it considers
them to have expired.


The main practical use for this mode is registration traffic conversion.
By minimizing the strain of processing registrations on the main
registrar, we allow it to dedicate more system resources to critical
areas of the platform, such as advanced SIP calling features and/or
media handling.


#### AOR throttling


In "AOR throttling" mode, the mid-registrar helps with handling multiple
registrations per user/AOR. This is done by aggregating all the end-user
registered contacts from a single AOR under a single registration into
the main registrar. This can dramatically reduce the incoming rate of
registrations (to a single registration per AOR), but also helps in dealing
with registrar servers which are not able to implement parallel forking/ringing.


Traffic conversion is done in a *"per-user"*
manner, according to each unique SIP AOR. It is achieved by
providing a contact with a large "expires" parameter value,
when relaying registrations to the main registrar.
Once such a registration is completed, subsequent registrations to the same
Address-of-record  will be continuously absorbed by the mid-registrar until,
eventually, the lifetime of the remote registration will have decreased enough
that a refresh (i.e. simply forwarding the next REGISTER request) is mandatory.


A common occurence is for some SIP User Agents to lose their network connection
(especially when dealing with mobile devices), hence they do not properly de-register
from the mid-registrar. In this case, in order to avoid stale registrations on the
main registrar (which contains SIP AORs with greatly extended lifetimes!),
the mid-registrar will appropriately generate De-REGISTER requests and remove
these contacts from the main registrar's location service as soon as it considers
them to have expired.


Of all three modes, "AOR throttling" potentially offers the best reduction in
traffic on the way to the main registrar. By aggregating contacts, it also
has the added benefit of reducing the number of contacts that the main registrar
must handle.


Regarding SIP request mangling in this mode, the module will always
replace all Contact header field values with a single Contact header
field value when proxying registrations to the main registrar, indicating
that the AOR is local to the front-end, and its contacts can be found there.


The main practical uses for this mode are registration traffic conversion
towards the main registrar, as well as taking over its call forking
duties. By minimizing the
strain of processing registrations / forking calls on the main registrar,
we allow it to dedicate more system resources to critical areas of the
platform, such as advanced SIP calling features and/or media handling.


### Auto-Insertion Into Future SIP Flows


A defining feature of the mid-registrar is that it must be easy to
integrate, ideally a "plug-and-play" SIP component. It should not
impose any "outbound-proxy" configurations on any of the platform's
layers and automatically insert itself on the call flows which follow
successful registrations.


Regardless of its configured working [mode](#mode-integer), the
mid-registrar will mangle the Contact header field URIs of all
forwarded REGISTER requests and replace the original "hostname" and
"port" parts of a Contact URI with one of its listening interfaces.


Additionally, in modes "0" and "1", each Contact will be assigned an
unique identifier, which will be utilized in future contact-based
lookup operations. This information will be included in each forwarded
Contact URI. The [contact id insertion](#contact_id_insertion-integer) modparam
controls how this information is included.


### Dependencies


#### OpenSIPS Modules


The following modules must be loaded before this module:


- *usrloc*
- *signaling*
- *tm*
- *event_routing*,
if [pn enable](#pn_enable-boolean) is set to *true*.


#### External Libraries or Applications


The following libraries or applications must be installed before
running OpenSIPS with this module loaded:


- *None*


### Exported Parameters


#### mode (integer)


Working mode of the module.
Refer to [sec working modes](#working-modes) for
more details.


The following is true for **all** working modes:


- when a REGISTER is received, the script writer must call
*[mid registrar save](#mid_registrar_savedomain-flags-aor-outgoing_expires-ownership_tag)*
- the mid-registrar will insert itself on the call flow of
all registrations according to the
*[contact id insertion](#contact_id_insertion-integer)*.
- registrations forwarded by the mid-registrar will transparently
result in a user location update only if the reply status code from
the downstream registrar is 2xx.


Each working mode behaves differently, as follows:


- *0 (Contact mirroring mode)*
The module will only insert itself on the call flow.
Contact expirations are left unchanged.
- *1 (Contact throttling mode)*
Contact throttling is a first step in lowering registration traffic rates. This
is possible through the use of the
*[outgoing expires](#outgoing_expires-integer)* module
parameter or the corresponding parameter to
*[mid registrar save](#mid_registrar_savedomain-flags-aor-outgoing_expires-ownership_tag)*,
which allow the script writer to prolong the life of the registrations on the way
to the main registrar.

			In this mode, the
			mid-registrar may alter Expires header field values or "expires" Contact
			header field parameters found in the initial request when forwarding registrations, according to
			*[outgoing expires](#outgoing_expires-integer)*
- *2 (AOR throttling mode)*
AOR throttling is a step beyond "Contact throttling", as the main registrar
is only made aware of the network presence of AORs, rather than
Contacts. This behaviour is also made possible through the
*[outgoing expires](#outgoing_expires-integer)* module
parameter or the corresponding parameter to
*[mid registrar save](#mid_registrar_savedomain-flags-aor-outgoing_expires-ownership_tag)*,
which allow the script writer to prolong the life of the registrations on the way
to the main registrar.
In this mode, the mid-registrar will fully replace the Contact
set of all forwarded registrations with a single Contact, advertising
that the AOR is available to the main registrar. The expiration value
for this Contact is given by 
*[outgoing expires](#outgoing_expires-integer)*.


Default value is **0** (contact mirroring mode)


```opensips title="Setting the *mode* module parameter"
modparam("mid_registrar", "mode", 2)
```


#### contact_id_insertion (integer)


Only relevant in a "mirroring" or "contact throttling"
[mode](#mode-integer). Controls where the additional
unique Contact identification information (64-bit, hex-encoded integer)
will be placed within outgoing Contact header field URIs. Refer to
[sip flow insertion](#auto-insertion-into-future-sip-flows) for more details.


Possible values are:


- *"ct-param" (default)* - the contact IDs shall
be appended to outgoing Contact URIs as ";ctid=" parameters.
- *"ct-username"* - the contact IDs will
substitute the "username" parts of outgoing Contact URIs


```opensips title="Setting the *contact_id_insertion* module parameter"
modparam("mid_registrar", "contact_id_insertion", "ct-username")
```


#### contact_id_param (string)


Only relevant in a "mirroring" or "contact throttling"
[mode](#mode-integer). Specifies the name of the
Contact URI parameter which is used by the module in order to
match contacts and route SIP requests.


Default value is **"ctid"**


```opensips title="Setting the *contact_id_param* module parameter"
modparam("mid_registrar", "contact_id_param", "ctid")

# Example resulting Contact header field:
# Contact: <sip:liviu@10.0.0.10:5060;ctid=619244948763447138>;expires=180.
```


#### at_escape_str (string)


Only relevant when in "AoR throttling" [mode](#mode-integer)
and with the usrloc [use_domain](../usrloc/README.md#use_domain-boolean)
setting enabled.  This string represents the escape sequence for
the "@" character, which must be included, in one way or another,
in mid-registrar's generated Contact URI usernames.


Setting this parameter to a different value may be useful in
situations where the backend registrar is incompatible with the
default escape string.


Default value is **"%40"**


```opensips title="Setting the *at_escape_str* module parameter"
modparam("mid_registrar", "at_escape_str", "___")

# Example Contact header field generated by mid-registrar:
# Contact: <sip:zach%40sipdomain.invalid@127.0.0.1:5060>;expires=120
```


#### outgoing_expires (integer)


Only relevant in Contact/AOR throttling modes. Sets a minimal
value for the expiration intervals of egressing contacts.


Default value is **3600** (seconds)


```opensips title="Setting the *outgoing_expires* module parameter"
modparam("mid_registrar", "outgoing_expires", 3600)
```


#### received_avp (string)


The module will store the value of the AVP configured by this
parameter in the *received* column of the user
location table. 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.


> [!NOTE]
> The value of this parameter should be the same as the value of
corresponding parameter of nathelper module.


Default value is **"NULL"** (disabled)


```opensips title="Setting the *received_avp* module parameter"
modparam("mid_registrar", "received_avp", "$avp(rcv)")
```


#### received_param (string)


The name of the parameter that will be appended to Contacts of
200 OK replies if the received URI is set by nathelper module.


> [!NOTE]
> The value of this parameter should be the same as the value of
corresponding parameter of nathelper module.


Default value is **"received"**


```opensips title="Setting the *received_param* module parameter"
modparam("mid_registrar", "received_param", "rcv")
```


#### extra_contact_params_avp (string)


An AVP specification. This AVP is evaluated during
*[mid registrar save](#mid_registrar_savedomain-flags-aor-outgoing_expires-ownership_tag)*:
if it holds a valid string, its content will be appended to
*each* new Contact URI built by the mid-registrar,
for the outgoing request.


Default value is **None** (not used)


```opensips title="Setting the *extra_contact_params_avp* module parameter"
# NB: AVPs are cleared with every new SIP request
modparam("mid_registrar", "extra_contact_params_avp", "$avp(extra_ct_params)")

# setting the AVP during SIP message processing
$avp(extra_ct_params) = ";transport=tls";
```


#### attr_avp (string)


AVP to store specific additional information for each registration.
This information is read from the AVP and stored (in memory, DB or both)
at [mid registrar save](#mid_registrar_savedomain-flags-aor-outgoing_expires-ownership_tag).  When the
[mid registrar lookup](#mid_registrar_lookupdomain-flags-aor) or 'is_registered()' (registrar)
functions are called, the *attr_avp* will be
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.*


```opensips title="Set attr_avp parameter"
# reading attributes from the attr_pvar when doing parallel forking
...
modparam("mid_registrar", "attr_avp", "$avp(attr)")

...
if (is_method("REGISTER")) {
	$avp(attr) = "contact_info";
	mid_registrar_save("location");
	exit;
}
...
mid_registrar_lookup("location");
t_on_branch("parallel_fork");
...
branch_route [parallel_fork] {
	xlog("Attributes for branch $T_branch_idx: $(avp(attr)[$T_branch_idx])\n");
}

		
```


#### min_expires (integer)


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 **10** (seconds)


```opensips title="Setting the *min_expires* module parameter"
modparam("mid_registrar", "min_expires", 600)
```


#### default_expires (integer)


If the processed message contains neither Expires HFs nor expires
contact parameters, this value will be used as the expiration
interval of any newly created usrloc records.


Default value is **3600** (seconds)


```opensips title="Setting the *default_expires* module parameter"
modparam("mid_registrar", "default_expires", 1800)
```


#### max_expires (integer)


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 **3600** (seconds)


```opensips title="Setting the *max_expires* module parameter"
modparam("mid_registrar", "max_expires", 7200)
```


#### default_q (integer)


Sets the default *"q"* value for new contacts.
Because OpenSIPS does not support floating point module parameters,
the supplied *"q"* value must be multiplied by 1000.
For example, if you want
*[default q](#default_q-integer)*
to be 0.38, set this parameter to 380.


Default value is **0**


```opensips title="Setting the *default_q* module parameter"
modparam("mid_registrar", "default_q", 380)
```


#### tcp_persistent_flag (string)


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
*[mid registrar save](#mid_registrar_savedomain-flags-aor-outgoing_expires-ownership_tag)*
function, will set the lifetime of the TCP
connection to the contact expire value. By doing this, the TCP
connection will stay up as long as its contacts are valid.


Default value is **-1** (not set)


```opensips title="Setting the *tcp_persistent_flag* module parameter"
modparam("mid_registrar", "tcp_persistent_flag", "TCP_PERSIST_REGISTRATIONS")
```


#### realm_prefix (string)


In multi-domain user location scenarios
(**"use_domain"** usrloc module parameter
set to *"1"*),
this parameter denotes a prefix to be automatically stripped from the
hostname part of *To* header field URIs when doing
a save, or *Request-URIs* when doing a lookup.


It is meant as an alternative to DNS SRV records (not all SIP clients
support SRV lookups), 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 translated to "mydomain.net".


Default value is **NULL** (none)


```opensips title="Setting the *realm_prefix* module parameter"
modparam("mid_registrar", "realm_prefix", "sip.")
```


#### case_sensitive (integer)


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** (true)


```opensips title="Setting the *case_sensitive* module parameter"
modparam("mid_registrar", "case_sensitive", 0)
```


#### allow_dup_cseq (boolean)


Some SIP stacks will re-REGISTER using the same Call-ID and CSeq values.
While rejecting such requests is consistent with RFC 3261 § 10.3.7, enabling
this parameter instructs the mid_registrar to accept them instead,
improving interoperability.


*Default value is *true* (duplicate CSeq is accepted).*


```opensips title="Setting the allow_dup_cseq parameter"
...
# strict RFC 3261 compliance: reject REGISTER requests with duplicate CSeq
modparam("
```


#### expires_max_deviation (integer)


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).*


```opensips title="Setting the expires_max_deviation parameter"
...
# add a random +/- 0-100 seconds to each registration lifetime
modparam("
```


#### max_contacts (integer)


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


```opensips title="Set max_contacts parameter"
...
# Allow no more than 10 contacts per AOR
modparam("
```


#### max_username_len (integer)


The maximum length of the "username" part of an Address-of-Record SIP URI.


Default value is **64**.


```opensips title="Setting the *max_username_len* module parameter"
modparam("
```


#### max_domain_len (integer)


The maximum length of the "domain" part of an Address-of-Record SIP URI.


Default value is **64**.


```opensips title="Setting the *max_domain_len* module parameter"
modparam("
```


#### max_aor_len (integer)


The maximum length of an Address-of-Record SIP URI.


Default value is **256**.


```opensips title="Setting the *max_aor_len* module parameter"
modparam("
```


#### max_contact_len (integer)


The maximum length of a Contact header field SIP URI.


Default value is **255**.


```opensips title="Setting the *max_contact_len* module parameter"
modparam("
```


#### retry_after (integer)


The mid-registrar can generate 5xx replies to registrations in various
situations. It could, for example, happen when the
*[max contacts](#max_contacts-integer)* parameter
is set and the processing of REGISTER request would exceed the limit.
In this case, OpenSIPS would respond with "503 Service Unavailable".


If you want to add the Retry-After header field in 5xx replies, set
this parameter to a value greater than zero (0 means: do not add the
header field). See section 20.33 of RFC3261 for more details.


Default value is **0** (disabled)


```opensips title="Setting the *retry_after* module parameter"
modparam("mid_registrar", "retry_after", 30)
```


#### disable_gruu (integer)


Globally disable GRUU handling.


Default value is **1** (GRUUs will not be handled)


```opensips title="Setting the *gruu_secret* module parameter"
modparam("mid_registrar", "disable_gruu", 0)
```


#### gruu_secret (string)


The string that will be used in XORing when generating
temporary GRUUs.


Default value is **"0p3nS1pS"**


```opensips title="Setting the *gruu_secret* module parameter"
modparam("mid_registrar", "gruu_secret", "my_secret")
```


#### pn_enable (boolean)


Enable SIP Push Notification support ([RFC 8599](https://tools.ietf.org/html/rfc8599)).
If enabled, Contact header field URIs which include all
[pn ct match params](#pn_ct_match_params-string) 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](../usrloc/README.md#matching_mode-integer).


*Default value is **false**.*


```opensips title="Setting the pn_enable parameter"
...
modparam("mid_registrar", "pn_enable", true)
...
```


#### pn_providers (string)


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).*


```opensips title="Setting the pn_providers parameter"
...
modparam("mid_registrar", "pn_providers", "apns, fcm, webpush")
...
```


#### pn_ct_match_params (string)


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 *mid_registrar_lookup()* or
[afunc pn process purr](#pn_process_purrdomain), 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"**.*


```opensips title="Setting the pn_ct_match_params parameter"
...
modparam("mid_registrar", "pn_ct_match_params", "pn-provider, pn-prid")
...
```


#### pn_pnsreg_interval (integer)


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).*


```opensips title="Setting the pn_pnsreg_interval parameter"
...
modparam("mid_registrar", "pn_pnsreg_interval", 140)
...
```


#### pn_trigger_interval (integer)


If a binding refresh REGISTER request from a given SIP endpoint does
not arrive within at least [pn trigger interval](#pn_trigger_interval-integer)
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/README.md#e_ul_contact_refresh)
usrloc event will be triggered.


Once [E_UL_CONTACT_REFRESH](../usrloc/README.md#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).*


```opensips title="Setting the pn_trigger_interval parameter"
...
modparam("mid_registrar", "pn_trigger_interval", 130)
...
```


#### pn_skip_pn_interval (integer)


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).*


```opensips title="Setting the pn_skip_pn_interval parameter"
...
modparam("mid_registrar", "pn_skip_pn_interval", 10)
...
```


#### pn_refresh_timeout (integer)


This timeout starts counting following a *mid_registrar_lookup()* or a
[afunc pn process purr](#pn_process_purrdomain) 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.*


```opensips title="Setting the pn_refresh_timeout parameter"
...
modparam("mid_registrar", "pn_refresh_timeout", 10)
...
```


#### pn_enable_purr (boolean)


Enable the SIP Push Notification mechanism for long-lived dialogs.
If enabled, the mid_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
[afunc pn process purr](#pn_process_purrdomain).


*Default value is **false**.*


```opensips title="Setting the pn_enable_purr parameter"
...
modparam("mid_registrar", "pn_enable_purr", true)
...
```


### Exported Functions


#### mid_registrar_save(domain[, flags[, aor[, outgoing_expires[, ownership_tag]]]])


Function to be called when handling REGISTER requests. This function
decides if a REGISTER should be forwarded to the main registrar and
performs all the necessary changes over the registered contacts. The
function is also covering the handling of the 2xx REGISTER replies -
the contacts confirmed by the main registrar will be automatically
saved in the local user location (without any additional scripting).


In Contact/AOR throttling modes (more info about working modes in [sec working modes](#working-modes)),
the return value of this function indicates whether the script
writer must forward the REGISTER request to the main registrar,
or just wrap up any left-over processing and exit script execution, as
the current REGISTER request has been answered with 200 OK
(absorbed at mid-registrar level).


Depending on the current working
*[mode](#mode-integer)* and
*[contact id insertion](#contact_id_insertion-integer)*,
the function may additionally perform
the following series of transformations when relaying REGISTER requests:


- in *"Contact throttling"* mode

  - change the value of the *Expires*
header field to the value of
*outgoing_expires*, if given,
otherwise the value given by the
*[outgoing expires](#outgoing_expires-integer)*
module parameter.
The same applies to any *";expires"*
Contact URI parameter.
  - replace the "host:port" part of all Contact URIs of the
incoming REGISTER request with an OpenSIPS listening interface
  - append a parameter to each
*Contact* URI, which will
allow the module to match the reply contacts
and also route calls. The name of this URI
parameter is configurable via
*[contact id param](#contact_id_param-string)*
- in *"AOR throttling"* mode

  - change the value of the *Expires*
header field to the value of
*outgoing_expires*, if given,
otherwise the value given by the
*[outgoing expires](#outgoing_expires-integer)*
module parameter.
  - replace all *Contact* header
fields of the request with a single *Contact* header field,
which will contain the following SIP URI: "sip:address-of-record@proxy_ip:proxy_port"


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 *usrloc*
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.
- *aor (string, optional)* - a custom Address-of-Record.
If not given, the AOR will be taken from the *To* header URI
- *outgoing_expires (int, optional)* - only relevant
in Contact/AOR throttling modes, this is a custom value
for the contact expiration interval of the outgoing REGISTER
request, which overrides the default
*[outgoing expires](#outgoing_expires-integer)* module parameter.
- *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).


**Return value**


- 1 (success) - current REGISTER request must be dispatched by the
script writer over to the main registrar
- 2 (success) - current REGISTER request has been absorbed by the
mid-registrar; a 200 OK reply has been sent upstream
- -1 (error) - generic error code; the logs should provide more help


This function can only be used from the request route.


```opensips title="*mid_registrar_save* usage"
...
if (is_method("REGISTER")) {
	mid_registrar_save("location");
	switch ($retcode) {
	case 1:
		xlog("L_INFO", "forwarding REGISTER to main registrar...\n");
		$ru = "sip:10.0.0.3:5070";
		if (!t_relay()) {
			send_reply(500, "Server Internal Error 1");
		}

		break;
	case 2:
		xlog("L_INFO", "REGISTER has been absorbed!\n");
		break;
	default:
		xlog("L_ERR", "mid-registrar error!\n");
		send_reply(500, "Server Internal Error 2");
	}

	exit;
}
...
```


#### mid_registrar_lookup(domain[, [flags][, [aor]]])


Function to be called when receiving requests from the main registrar
(to be routed to the end-user). It performs the local lookup
(in user location) and the necessary RURI processing in order to route
the requests further to the end-user registered contacts (note that
multiple branches/destinations may result after the lookup).


Depending on the current working
*[mode](#mode-integer)*,
the function will behave as follows:


- in *"mirror"* mode

  - extract the username (Address-of-Record) from the Request-URI
and look up all of its contact bindings stored in the user
location. The Request-URI (**$ru**
variable) will be overwritten with the highest q-value contact,
with additional branches for each contact being optionally
created. (depending on the *flags* parameter)
- in *"Contact throttling"* mode

  - extract the *[contact id param](#contact_id_param-string)*
from the Request-URI, derive the actual SIP URI of the destination
from it and set it as the new Request-URI of the INVITE
(**$ru** variable).
- in *"AOR throttling"* mode

  - extract the username (Address-of-Record) from the Request-URI
and look up all of its contact bindings stored in the user
location. The Request-URI (**$ru**
variable) will be overwritten with the highest q-value contact,
with additional branches for each contact being optionally
created. (depending on the *flags* parameter)


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 *usrloc*
table which stores the contacts
- *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 *mid_registrar_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 *mid_registrar_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 *mid_registrar_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 *mid_registrar_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 *mid_registrar_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)* - a custom Address-of-Record.
If not given, the AOR will be taken from the *Request-URI*


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 only be used from the request route.


```opensips title="*mid_registrar_lookup* usage"
...
	# initial invites from the main registrar - need to look them up!
	if (is_method("INVITE") and $si == "10.0.0.3" and $sp == 5070) {
		if (!mid_registrar_lookup("location")) {
			t_reply(404, "Not Found");
			exit;
		}

		if (!t_relay())
			send_reply(500, "Server Internal Error 3");

	    exit;
	}
...
```


### Exported Asynchronous Functions


#### pn_process_purr(domain)


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](../usrloc/README.md#e_ul_contact_refresh)
event and place the request on async hold for at most
[pn refresh timeout](#pn_refresh_timeout-integer) 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


```opensips title="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");

	...
}
```
<!-- CONTRIBUTORS -->

### License

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