<!-- Module User's Guide -->

<chapter id="sec-admin-guide">
	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		The <emphasis>mid_registrar</emphasis> 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.
	</para>
	<para>
		Acting as a registration front-end to the main SIP registrar, the
		mid-registrar is able to:
		<itemizedlist>
			<listitem>
			<para>
			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.
			</para>
			</listitem>
			<listitem>
			<para>
				stay synchronized with the main registrar (from a user
				location perspective), by properly
				accepting the contact states and expirations it decides.
			</para>
			</listitem>
		</itemizedlist>
	</para>

	&supported_rfc;

	</section>

	<section id="sec-working-modes">
	<title>Working modes</title>
	<para>
		The mid_registrar may function in one of several modes:
	</para>

	<section id="sec-mirror-mode">
		<title>Contact mirroring (default)</title>
		<para>
		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
		<xref linkend="sip-flow-insertion"/> 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.
		</para>
		<para>
		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).
		</para>
	</section>

	<section id="sec-device-throttling-mode">
		<title>Contact throttling</title>
		<para>
		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.
		</para>
		<para>
		Traffic conversion is done in a <emphasis>"per-device"</emphasis>
		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.
		</para>
		<para>
		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.
		</para>
		<para>
		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.
		</para>
	</section>

	<section id="sec-user-throttling-mode">
		<title>AOR throttling</title>
		<para>
		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.
		</para>
		<para>
		Traffic conversion is done in a <emphasis>"per-user"</emphasis>
		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.
		</para>
		<para>
		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.
		</para>
		<para>
			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.
		</para>
		<para>
			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.
		</para>
		<para>
		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.
		</para>
	</section>
	</section>

	<section id="sip-flow-insertion">
	<title>Auto-Insertion Into Future SIP Flows</title>
	<para>
		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.
	</para>
	<para>
		Regardless of its configured working <xref linkend="param_mode"/>, 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.
	</para>
	<para>
		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 <xref linkend="param_contact_id_insertion"/> modparam
		controls how this information is included.
	</para>
	</section>

	<section  id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section id="sec-module-dependencies">
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>usrloc</emphasis>
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>signaling</emphasis>
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tm</emphasis>
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>event_routing</emphasis>,
				if <xref linkend="param_pn_enable"/> is set to <emphasis>true</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>

	<section id="sec-external-dependencies">
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before
		running &osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section  id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>

	<section id="param_mode" xreflabel="mode">
		<title><varname>mode</varname> (integer)</title>

		<para>
			Working mode of the module.
			Refer to <xref linkend="sec-working-modes"/> for
			more details.
		</para>

		<para>
			The following is true for <emphasis role='bold'>all</emphasis> working modes:
			<itemizedlist>
			<listitem>
			<para>
			when a REGISTER is received, the script writer must call
			<emphasis><xref linkend="func_mid_registrar_save"/></emphasis>
			</para>
			</listitem>
			<listitem>
			<para>
			the mid-registrar will insert itself on the call flow of
			all registrations according to the
			<emphasis><xref linkend="param_contact_id_insertion"/></emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
			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.
			</para>
			</listitem>
			</itemizedlist>
		</para>

		<para>
			Each working mode behaves differently, as follows:
		</para>

		<itemizedlist>
		<listitem>
		<para>
			<emphasis>0 (Contact mirroring mode)</emphasis>
			<para>
			The module will only insert itself on the call flow.
			Contact expirations are left unchanged.
			</para>
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>1 (Contact throttling mode)</emphasis>
			<para>
			Contact throttling is a first step in lowering registration traffic rates. This
			is possible through the use of the
			<emphasis><xref linkend="param_outgoing_expires"/></emphasis> module
			parameter or the corresponding parameter to
			<emphasis><xref linkend="func_mid_registrar_save"/></emphasis>,
			which allow the script writer to prolong the life of the registrations on the way
			to the main registrar.
			</para>

			<para>
			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
			<emphasis><xref linkend="param_outgoing_expires"/></emphasis>
			</para>
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>2 (AOR throttling mode)</emphasis>
		<para>
		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
		<emphasis><xref linkend="param_outgoing_expires"/></emphasis> module
		parameter or the corresponding parameter to
		<emphasis><xref linkend="func_mid_registrar_save"/></emphasis>,
		which allow the script writer to prolong the life of the registrations on the way
		to the main registrar.
		</para>
		<para>
		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 
		<emphasis><xref linkend="param_outgoing_expires"/></emphasis>.
		</para>
		</para>
		</listitem>
		</itemizedlist>


		<para>
			Default value is <emphasis role='bold'>0</emphasis> (contact mirroring mode)
		</para>
		<example>
		<title>Setting the <emphasis>mode</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "mode", 2)
</programlisting>
		</example>
	</section>
	<section id="param_contact_id_insertion" xreflabel="contact_id_insertion">
		<title><varname>contact_id_insertion</varname> (integer)</title>
		<para>
		Only relevant in a "mirroring" or "contact throttling"
			<xref linkend="param_mode"/>. Controls where the additional
		unique Contact identification information (64-bit, hex-encoded integer)
		will be placed within outgoing Contact header field URIs. Refer to
		<xref linkend="sip-flow-insertion"/> for more details.
		</para>
		<para>
		Possible values are:
		</para>
		<itemizedlist>
		<listitem>
		<para>
			<emphasis>"ct-param" (default)</emphasis> - the contact IDs shall
			be appended to outgoing Contact URIs as ";ctid=" parameters.
		</para>
		</listitem>
		<listitem>
		<para>
			<emphasis>"ct-username"</emphasis> - the contact IDs will
			substitute the "username" parts of outgoing Contact URIs
		</para>
		</listitem>
		</itemizedlist>
		<example>
		<title>Setting the <emphasis>contact_id_insertion</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "contact_id_insertion", "ct-username")
</programlisting>
		</example>
	</section>

	<section id="param_contact_id_param" xreflabel="contact_id_param">
		<title><varname>contact_id_param</varname> (string)</title>
		<para>
			Only relevant in a "mirroring" or "contact throttling"
			<xref linkend="param_mode"/>. Specifies the name of the
			Contact URI parameter which is used by the module in order to
			match contacts and route SIP requests.
		</para>

		<para>
			Default value is <emphasis role='bold'><quote>ctid</quote></emphasis>
		</para>
		<example>
		<title>Setting the <emphasis>contact_id_param</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "contact_id_param", "ctid")

# Example resulting Contact header field:
# Contact: &lt;sip:liviu@10.0.0.10:5060;ctid=619244948763447138&gt;;expires=180.
</programlisting>
		</example>
	</section>

	<section id="param_at_escape_str" xreflabel="at_escape_str">
		<title><varname>at_escape_str</varname> (string)</title>
		<para>
			Only relevant when in "AoR throttling" <xref linkend="param_mode"/>
			and with the usrloc <ulink url='usrloc#param_use_domain'>use_domain</ulink>
			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.
		</para>

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

		<para>
			Default value is <emphasis role='bold'><quote>%40</quote></emphasis>
		</para>
		<example>
		<title>Setting the <emphasis>at_escape_str</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "at_escape_str", "___")

# Example Contact header field generated by mid-registrar:
# Contact: &lt;sip:zach%40sipdomain.invalid@127.0.0.1:5060&gt;;expires=120
</programlisting>
		</example>
	</section>

	<section id="param_outgoing_expires" xreflabel="outgoing_expires">
		<title><varname>outgoing_expires</varname> (integer)</title>
		<para>
			Only relevant in Contact/AOR throttling modes. Sets a minimal
			value for the expiration intervals of egressing contacts.
		</para>

		<para>
		Default value is <emphasis role='bold'>3600</emphasis> (seconds)
		</para>
		<example>
		<title>Setting the <emphasis>outgoing_expires</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "outgoing_expires", 3600)
</programlisting>
		</example>
	</section>
	<section id="param_received_avp" xreflabel="received_avp">
		<title><varname>received_avp</varname> (string)</title>
		<para>
		The module will store the value of the AVP configured by this
		parameter in the <emphasis>received</emphasis> 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.
		</para>
		<note>
		<para>
			The value of this parameter should be the same as the value of
			corresponding parameter of nathelper module.
		</para>
		</note>
		<para>
		Default value is <emphasis role='bold'>"NULL"</emphasis> (disabled)
		</para>
		<example>
		<title>Setting the <emphasis>received_avp</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "received_avp", "$avp(rcv)")
</programlisting>
		</example>
	</section>
	<section id="param_received_param" xreflabel="received_param">
		<title><varname>received_param</varname> (string)</title>
		<para>
		The name of the parameter that will be appended to Contacts of
		200 OK replies if the received URI is set by nathelper module.
		</para>
		<note>
		<para>
			The value of this parameter should be the same as the value of
			corresponding parameter of nathelper module.
		</para>
		</note>
		<para>
		Default value is <emphasis role='bold'>"received"</emphasis>
		</para>
		<example>
		<title>Setting the <emphasis>received_param</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "received_param", "rcv")
</programlisting>
		</example>
	</section>
	<section id="param_extra_contact_params_avp" xreflabel="extra_contact_params_avp">
		<title><varname>extra_contact_params_avp</varname> (string)</title>
		<para>
		An AVP specification. This AVP is evaluated during
		<emphasis><xref linkend="func_mid_registrar_save"/></emphasis>:
		if it holds a valid string, its content will be appended to
		<emphasis>each</emphasis> new Contact URI built by the mid-registrar,
		for the outgoing request.
		</para>
		<para>
			Default value is <emphasis role='bold'>None</emphasis> (not used)
		</para>
		<example>
		<title>Setting the <emphasis>extra_contact_params_avp</emphasis> module parameter</title>
		<programlisting format="linespecific">
# 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";
</programlisting>
		</example>
	</section>

	<section id="param_attr_avp" xreflabel="attr_avp">
		<title><varname>attr_avp</varname> (string)</title>
		<para>
		AVP to store specific additional information for each registration.
		This information is read from the AVP and stored (in memory, DB or both)
		at <xref linkend="func_mid_registrar_save"/>.  When the
		<xref linkend="func_mid_registrar_lookup"/> or 'is_registered()' (registrar)
		functions are called, the <emphasis>attr_avp</emphasis> will be
		populated with the value saved at [re]registration.
		</para>
		<para>
		When doing call forking, the AVP will hold multiple values. The position of
		the corresponding attribute information in <emphasis>attr_avp</emphasis> is
		equal to the branch index.  An example scenario is given below.
		</para>
		<para>
		<emphasis>
			Default value is NULL.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>attr_avp</varname> parameter</title>
		<programlisting format="linespecific">
# 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");
}

		</programlisting>
		</example>
	</section>

	<section id="param_min_expires" xreflabel="min_expires">
		<title><varname>min_expires</varname> (integer)</title>
		<para>
			The minimum expires value of a Contact, values lower than this
			minimum will be automatically set to the minimum. Value 0 disables the checking.
		</para>
		<para>
		Default value is <emphasis role='bold'>10</emphasis> (seconds)
		</para>
		<example>
		<title>Setting the <emphasis>min_expires</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "min_expires", 600)
</programlisting>
		</example>
	</section>
	<section id="param_default_expires" xreflabel="default_expires">
		<title><varname>default_expires</varname> (integer)</title>
		<para>
			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.
		</para>
		<para>
		Default value is <emphasis role='bold'>3600</emphasis> (seconds)
		</para>
		<example>
		<title>Setting the <emphasis>default_expires</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "default_expires", 1800)
</programlisting>
		</example>
	</section>
	<section id="param_max_expires" xreflabel="max_expires">
		<title><varname>max_expires</varname> (integer)</title>
		<para>
			The maximum expires value of a Contact, values higher than this
			maximum will be automatically set to the maximum. Value 0 disables the checking.
		</para>
		<para>
		Default value is <emphasis role='bold'>3600</emphasis> (seconds)
		</para>
		<example>
		<title>Setting the <emphasis>max_expires</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "max_expires", 7200)
</programlisting>
		</example>
	</section>
	<section id="param_default_q" xreflabel="default_q">
		<title><varname>default_q</varname> (integer)</title>
		<para>
		Sets the default <emphasis>"q"</emphasis> value for new contacts.
		Because &osips; does not support floating point module parameters,
		the supplied <emphasis>"q"</emphasis> value must be multiplied by 1000.
		For example, if you want
		<emphasis><xref linkend="param_default_q"/></emphasis>
		to be 0.38, set this parameter to 380.
		</para>

		<para>
		Default value is <emphasis role='bold'>0</emphasis>
		</para>
		<example>
		<title>Setting the <emphasis>default_q</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "default_q", 380)
</programlisting>
		</example>
	</section>
	<section id="param_tcp_persistent_flag" xreflabel="tcp_persistent_flag">
		<title><varname>tcp_persistent_flag</varname> (string)</title>
		<para>
		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
		<emphasis><xref linkend="func_mid_registrar_save"/></emphasis>
		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.
		</para>

		<para>
		Default value is <emphasis role='bold'>-1</emphasis> (not set)
		</para>
		<example>
		<title>Setting the <emphasis>tcp_persistent_flag</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "tcp_persistent_flag", "TCP_PERSIST_REGISTRATIONS")
</programlisting>
		</example>
	</section>
	<section id="param_realm_prefix" xreflabel="realm_prefix">
		<title><varname>realm_prefix</varname> (string)</title>
		<para>
		In multi-domain user location scenarios
		(<emphasis role='bold'>"use_domain"</emphasis> usrloc module parameter
		set to <emphasis>"1"</emphasis>),
		this parameter denotes a prefix to be automatically stripped from the
		hostname part of <emphasis>To</emphasis> header field URIs when doing
		a save, or <emphasis>Request-URIs</emphasis> when doing a lookup.
		</para>
		<para>
		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".
		</para>

		<para>
		Default value is <emphasis role='bold'>NULL</emphasis> (none)
		</para>
		<example>
		<title>Setting the <emphasis>realm_prefix</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "realm_prefix", "sip.")
</programlisting>
		</example>
	</section>
	<section id="param_case_sensitive" xreflabel="case_sensitive">
		<title><varname>case_sensitive</varname> (integer)</title>
		<para>
		If set to 1, then <acronym>AOR</acronym> comparison will be case
		sensitive (as RFC3261 instructs), if set to 0 then
		<acronym>AOR</acronym> comparison will be case insensitive.
		</para>
		<para>
		Default value is <emphasis role='bold'>1</emphasis> (true)
		</para>
		<example>
		<title>Setting the <emphasis>case_sensitive</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "case_sensitive", 0)
</programlisting>
		</example>
	</section>

	&reg_modparams;

	<section id="param_retry_after" xreflabel="retry_after">
		<title><varname>retry_after</varname> (integer)</title>
		<para>
		The mid-registrar can generate 5xx replies to registrations in various
		situations. It could, for example, happen when the
		<emphasis><xref linkend="param_max_contacts"/></emphasis> parameter
		is set and the processing of REGISTER request would exceed the limit.
		In this case, OpenSIPS would respond with "503 Service Unavailable".
		</para>
		<para>
		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.
		</para>
		<para>
		Default value is <emphasis role='bold'>0</emphasis> (disabled)
		</para>
		<example>
		<title>Setting the <emphasis>retry_after</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "retry_after", 30)
</programlisting>
		</example>
	</section>
	<section id="param_disable_gruu" xreflabel="disable_gruu">
		<title><varname>disable_gruu</varname> (integer)</title>
		<para>
			Globally disable GRUU handling.
		</para>
		<para>
		Default value is <emphasis role='bold'>1</emphasis> (GRUUs will not be handled)
		</para>
		<example>
		<title>Setting the <emphasis>gruu_secret</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "disable_gruu", 0)
</programlisting>
		</example>
	</section>
	<section id="param_gruu_secret" xreflabel="gruu_secret">
		<title><varname>gruu_secret</varname> (string)</title>
		<para>
		The string that will be used in XORing when generating
		temporary GRUUs.
		</para>
		<para>
		Default value is <emphasis role='bold'>"0p3nS1pS"</emphasis>
		</para>
		<example>
		<title>Setting the <emphasis>gruu_secret</emphasis> module parameter</title>
		<programlisting format="linespecific">
modparam("mid_registrar", "gruu_secret", "my_secret")
</programlisting>
		</example>
	</section>

	&pn_modparams;

	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_mid_registrar_save" xreflabel="mid_registrar_save()">
		<title>
		<function moreinfo="none">mid_registrar_save(domain[, flags[, aor[, outgoing_expires[, ownership_tag]]]])</function>
		</title>
		<para>
		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).
		</para>
		<para>
			In Contact/AOR throttling modes (more info about working modes in <xref linkend="sec-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).
		</para>
		<para>
			Depending on the current working
			<emphasis><xref linkend="param_mode"/></emphasis> and
			<emphasis><xref linkend="param_contact_id_insertion"/></emphasis>,
			the function may additionally perform
			the following series of transformations when relaying REGISTER requests:
		</para>
		<para>
			<itemizedlist>
				<listitem>
					<para> in <emphasis>"Contact throttling"</emphasis> mode </para>
					<itemizedlist>
						<listitem>
							<para>
								change the value of the <emphasis>Expires</emphasis>
								header field to the value of
								<emphasis>outgoing_expires</emphasis>, if given,
								otherwise the value given by the
								<emphasis><xref linkend="param_outgoing_expires"/></emphasis>
								module parameter.
								The same applies to any <emphasis>";expires"</emphasis>
								Contact URI parameter.
							</para>
						</listitem>
						<listitem>
							<para>
								replace the "host:port" part of all Contact URIs of the
								incoming REGISTER request with an OpenSIPS listening interface
							</para>
						</listitem>
						<listitem>
							<para>
								append a parameter to each
								<emphasis>Contact</emphasis> URI, which will
								allow the module to match the reply contacts
								and also route calls. The name of this URI
								parameter is configurable via
								<emphasis><xref linkend="param_contact_id_param"/></emphasis>
							</para>
						</listitem>
					</itemizedlist>
				</listitem>
				<listitem>
					<para> in <emphasis>"AOR throttling"</emphasis> mode </para>
					<itemizedlist>
						<listitem>
							<para>
								change the value of the <emphasis>Expires</emphasis>
								header field to the value of
								<emphasis>outgoing_expires</emphasis>, if given,
								otherwise the value given by the
								<emphasis><xref linkend="param_outgoing_expires"/></emphasis>
								module parameter.
							</para>
						</listitem>
						<listitem>
							<para>
								replace all <emphasis>Contact</emphasis> header
								fields of the request with a single <emphasis>Contact</emphasis> header field,
								which will contain the following SIP URI: "sip:address-of-record@proxy_ip:proxy_port"
							</para>
						</listitem>
					</itemizedlist>
				</listitem>
			</itemizedlist>
		</para>

		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>domain</emphasis> (static string) - logical domain within the registrar.
			If a database is used, then this must be name of the <emphasis>usrloc</emphasis>
			table which stores the contacts
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>flags</emphasis> (string, optional) - string composed of
				one or more of the following flags, comma-separated:
			</para>
			<itemizedlist>
				&save_common_flags;
			</itemizedlist>
		</listitem>
		<listitem>
			<para><emphasis>aor (string, optional)</emphasis> - a custom Address-of-Record.
				If not given, the AOR will be taken from the <emphasis>To</emphasis> header URI
			</para>
		</listitem>
		<listitem>
			<para><emphasis>outgoing_expires (int, optional) </emphasis> - 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
			<emphasis><xref linkend="param_outgoing_expires"/></emphasis> module parameter.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>ownership_tag</emphasis> (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).
			</para>
		</listitem>
		</itemizedlist>
		<para><emphasis role='bold'>Return value</emphasis></para>
		<itemizedlist>
		<listitem>
			<para>
				1 (success) - current REGISTER request must be dispatched by the
				script writer over to the main registrar
			</para>
		</listitem>
		<listitem>
			<para>
				2 (success) - current REGISTER request has been absorbed by the
				mid-registrar; a 200 OK reply has been sent upstream
			</para>
		</listitem>
		<listitem>
			<para>
				-1 (error) - generic error code; the logs should provide more help
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can only be used from the request route.
		</para>
		<example>
			<title><function moreinfo="none"><emphasis>mid_registrar_save</emphasis></function> usage</title>
		<programlisting format="linespecific">
...
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;
}
...
</programlisting>
		</example>
	</section>

	<section id="func_mid_registrar_lookup" xreflabel="mid_registrar_lookup()">
		<title>
		<function moreinfo="none">mid_registrar_lookup(domain[, [flags][, [aor]]])</function>
		</title>
		<para>
		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).
		</para>
		<para>
		Depending on the current working
		<emphasis><xref linkend="param_mode"/></emphasis>,
		the function will behave as follows:
		</para>

		<para>
		<itemizedlist>
		<listitem>
		<para> in <emphasis>"mirror"</emphasis> mode </para>
		<itemizedlist>
		<listitem>
			<para>
				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 (<emphasis role='bold'>$ru</emphasis>
				variable) will be overwritten with the highest q-value contact,
				with additional branches for each contact being optionally
				created. (depending on the <emphasis>flags</emphasis> parameter)
			</para>
		</listitem>
		</itemizedlist>
		</listitem>
		<listitem>
		<para> in <emphasis>"Contact throttling"</emphasis> mode </para>
		<itemizedlist>
		<listitem>
			<para>
				extract the <emphasis><xref linkend="param_contact_id_param"/></emphasis>
				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
				(<emphasis role='bold'>$ru</emphasis> variable).
			</para>
		</listitem>
		</itemizedlist>
		</listitem>
		<listitem>
		<para> in <emphasis>"AOR throttling"</emphasis> mode </para>
		<itemizedlist>
		<listitem>
			<para>
				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 (<emphasis role='bold'>$ru</emphasis>
				variable) will be overwritten with the highest q-value contact,
				with additional branches for each contact being optionally
				created. (depending on the <emphasis>flags</emphasis> parameter)
			</para>
		</listitem>
		</itemizedlist>
		</listitem>
		</itemizedlist>
		</para>

		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>domain (static string)</emphasis> - logical domain within the registrar.
			If a database is used, then this must be name of the <emphasis>usrloc</emphasis>
			table which stores the contacts
			</para>
		</listitem>
		<listitem>
			&lookup_flags;
		</listitem>
		<listitem>
			<para><emphasis>aor (string, optional)</emphasis> - a custom Address-of-Record.
				If not given, the AOR will be taken from the <emphasis>Request-URI</emphasis>
			</para>
		</listitem>
		</itemizedlist>
		&lookup_retcodes;
		<para>
		This function can only be used from the request route.
		</para>
		<example>
			<title><function moreinfo="none"><emphasis>mid_registrar_lookup</emphasis></function> usage</title>
		<programlisting format="linespecific">
...
	# 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;
	}
...
</programlisting>
		</example>
	</section>

	</section>


	<section>
	<title>Exported Asynchronous Functions</title>

	&pn_async_func;

	</section>


</chapter>

