<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	[ <!ENTITY % local.common.attrib
	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
	 <!-- Include general documentation entities -->
	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
	 %docentities;
	]
>

<section id="registrar.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
    </sectioninfo>

    <title>Parameters</title>

    <section id="registar.default_expires">
	<title><varname>default_expires</varname> (integer)</title>
	<para>
	    If the processed message contains neither Expires
	    <acronym>HFs</acronym> 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).
	</para>
	<para>
	    Default value is 3600.
	</para>
	<example>
	    <title>Set <varname>default_expires</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "default_expires", 1800)
...
	    </programlisting>
	</example>
    </section>

    <section id="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 60.
	</para>
	<example>
	    <title>Set <varname>min_expires</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "min_expires", 60)
...
	    </programlisting>
	</example>
    </section>

    <section id="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 0.
	</para>
	<example>
	    <title>Set <varname>max_expires</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "max_expires", 120)
...
	    </programlisting>
	</example>
    </section>

    <section id="default_q">
	<title><varname>default_q</varname> (integer)</title>
	<para>
	    The parameter represents default q value for new contacts. Because
	    ser doesn't support float parameter types, the value in the
	    parameter is divided by 100 and stored as float. For example, if
	    you want default_q to be 0.38, use value 38 here.
	</para>
	<para>
	    Default value is 0.
	</para>
	<example>
	    <title>Set <varname>default_q</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "default_q", 100)
...
	    </programlisting>
	</example>
    </section>

    <section id="append_branches">
	<title><varname>append_branches</varname> (integer)</title>
	<para>
	    The parameter controls how lookup function processes multiple
	    contacts.  If there are multiple contacts for the given username in
	    usrloc and this parameter is set to 1, 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 parameter is set to 0, only Request-URI will be
	    overwritten with the highest-q rated contact and the rest will be
	    left unprocessed.
	</para>
	<para>
	    Default value is 1.
	</para>
	<example>
	    <title>Set <varname>append_branches</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "append_branches", 0)
...
	    </programlisting>
	</example>
    </section>

    <section id="case_sensitive">
	<title><varname>case_sensitive</varname> (integer)</title>
	<note><para>
		This parameter was removed (obsolete since ser 2.0).
	</para></note>
	<para>
	    If set to 1 then <acronym>AOR</acronym> comparison will be case
	    sensitive, if set to 0 then <acronym>AOR</acronym> comparison will
	    be case insensitive--This is recommended.
	</para>
	<para>
	    Default value is 0.
	</para>
	<example>
	    <title>Set <varname>case_sensitive</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "case_sensitive", 1)
...
	    </programlisting>
	</example>
    </section>

    <section id="desc_time_order">
	<title><varname>desc_time_order</varname> (integer)</title>
	<note><para>
		This parameter was removed (obsolete since ser 2.0).
	</para></note>
	<para>
	    If set to 1 then all contacts will be ordered in descending
	    modification time order. In this case the most recently
	    updated/created contact will be used.
	</para>
	<para>
	    Default value is 0.
	</para>
	<example>
	    <title>Set <varname>desc_time_order</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "desc_time_order", 1)
...
	    </programlisting>
	</example>
    </section>

    <section id="registrar.received_avp">
	<title><varname>received_avp</varname> (integer)</title>
	<para>
	    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.
	</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 42.
	</para>
	<example>
	    <title>Set <varname>received_avp</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "received_avp", 43)
...
	    </programlisting>
	</example>
    </section>

    <section id="received_param">
	<title><varname>received_param</varname> (integer)</title>
	<para>
	    The name of the parameter that will be appended to Contacts of 200
	    OK when the received URI was set by nathelper module.
	</para>
	<para>
	    Default value is "received".
	</para>
	<example>
	    <title>Set <varname>received_param</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "received_param", "rcv")
...
	    </programlisting>
	</example>
    </section>

    <section id="max_contacts">
	<title><varname>max_contacts</varname> (integer)</title>
	<para>
	    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.
	</para>
	<para>
	    Default value is 0.
	</para>
	<example>
	    <title>Set <varname>max_contacts</varname> parameter</title>
	    <programlisting>
...
# Allow no more than 10 contacts per AOR
modparam("registrar", "max_contacts", 10)
...
	    </programlisting>
	</example>
    </section>
    
    <section id="retry_after">
	<title><varname>retry_after</varname> (integer)</title>
	<para>
	    The registrar can generate 5xx reply to REGISTER in various
	    situations. It can, for example, happen when the
	    <varname>max_contacts</varname> parameter is set and the processing
	    of REGISTER request would exceed the limit. In this case the
	    registrar would generate "503 Service Unavailable" response.
	</para>
	<para>
	    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.
	</para>
	<para>
	    Default value is 0 (disabled).
	</para>
	<example>
	    <title>Set <varname>retry_after</varname> parameter</title>
	    <programlisting>
...
modparam("registrar", "retry_after", 30)
...
	    </programlisting>
	</example>
    </section>

	<section id="save_nat_flag">
		<title><varname>save_nat_flag</varname> (flagname or integer)</title>
		<para>
			The contact will be marked as behind the NAT if this flag is set
			before calling one of registrar save*() functions.
		</para>
		<para>
			See also <varname>load_nat_flag</varname>.
		</para>
		<para>
			The default value is 4 (flag number 4).
		</para>
		<example>
			<title>Set <varname>save_nat_flag</varname> parameter</title>
			<programlisting>
flags FLAG_NAT;
...
modparam("registrar", "save_nat_flag", "FLAG_NAT")
...
route{
...
	if (nat_uac_test("19"))
		setflag(FLAG_NAT);
...
}
			</programlisting>
		</example>
	</section>

	<section id="load_nat_flag">
		<title><varname>load_nat_flag</varname> (flagname or integer)</title>
		<para>
			This flag will be set by the registrar lookup*() functions if
			the contact was marked as behind the NAT during its registration.
		</para>
		<para>
			See also <varname>save_nat_flag</varname>.
		</para>
		<para>
			The default value is 4 (flag number 4).
		</para>
		<example>
			<title>Set <varname>load_nat_flag</varname> parameter</title>
			<programlisting>
flags FLAG_NAT;
...
modparam("registrar", "load_nat_flag", "FLAG_NAT")
...
route{
...
	if (lookup_contacts("location")) {
		if (isflagset(FLAG_NAT)){
			log(1, "natted contact");
			# use rtpproxy a.s.o
		}
...
	}
...
}
			</programlisting>
		</example>
	</section>

	<section id="trust_received_flag">
		<title><varname>trust_received_flag</varname> (flagname or integer)
		</title>
		<para>
			If this flag is set, the received information added to the REGISTER
			contacts on another machine (e.g. upstream proxy or replication
			 peer) by the <function>fix_nated_register()</function> function
			from the <emphasis>nathelper</emphasis> module (ser version,
			under modules_s/) is trusted. If it is not set, it will be
			ignored.
		</para>
		<para>
			It is especially useful in REGISTER replication scenarios of
			registrars behind a transparent load balancer (one IP) or a proxy /
			load balancer that can make use of the original received
			information (in this case combined with 
			<varname>received_to_uri</varname>).
		</para>
		<para>
			A contact with received information looks like:
&lt;sip:foo@10.0.0.3:5060&gt;;received="sip:1.2.3.4:3412;transport=TCP;dstip=4.5.6.7;dstport=5060".
		</para>
		<para>
			Besides the normal flags values (flag names or positive integers),
			there are 2 special integer values: -1 and -2.
			If <varname>trust_received_flag</varname> is set to 
			<emphasis>-1</emphasis> it is equivalent with disabling it
			globally (no contact "received" parameter will be trusted, they
			will be all ignored). If set to <emphasis>-2</emphasis> all the
			contact "received" parameters will be trusted.
		</para>
		<para>
			See also <function>fix_nated_register()</function> in
			ser nathelper version (modules_s/nathelper).
		</para>
		<para>
			The default value is -2 (always trust received), due to config
			compatibility reasons with older ser versions.
		</para>
		<example>
			<title>Set <varname>trust_received_flag</varname> parameter</title>
			<programlisting>
flags FLAG_REPLICATED;
...
modparam("registrar", "trust_received_flag", "FLAG_REPLICATED")
...
route{
...
	if (dst_ip==224.0.1.75 &amp;&amp; method == "REGISTER") {
		# REGISTER replicated on multicast (trusted)
		setflag(FLAG_REPLICATED);
		save_mem_nr("location");
...
	}
...
}
			</programlisting>
		</example>
	</section>

	<section id="received_to_uri">
		<title><varname>received_to_uri</varname> (boolean)</title>
		<para>
			If set the lookup*() functions will add a contact received
			information to the uri, instead of using the contact received
			information as a destination for the message.
		</para>
		<para>
			The resulting message uri will look like:
			&lt;sip:contact&gt;;received="sip:src_ip:src_port;transport=proto;dstip=iface_ip;dstport=iface_port".
		</para>
		<para>
			Is is useful when the registrar is behind some other proxy (e.g.
			load balancer) and using Path is not desired. In this case the
			outer proxy would have to look at the message uri, remove
			the "received" parameter from the uri and use it as destination
			for the message.
		</para>
		<para>
			The default value is 0 (off).
		</para>
		<example>
			<title>Set <varname>received_to_uri</varname> parameter</title>
			<programlisting>
...
modparam("registrar", "received_to_uri", 1)
# example uri for a message received on 1.2.3.4:5060 from 192.168.1.1:5060:
# &lt;sip:foo@10.0.0.3&gt;;received="sip:192.168.1.1:5060;dstip=1.2.3.4;dstport=5060"
			</programlisting>
		</example>
	</section>

	<section id="reply_code_attr">
		<title><varname>reply_code_attr</varname> (avp name)</title>
		<para>
			If one of the save*() functions that do not send a reply is
			used (<function>save_contacts_no_reply()</function>,
			<function>save_noreply()</function> or
			<function>save_mem_nr()</function>), an AVP with the given
			name will be set to the code of the reply that should be send
			by other means.
		</para>
		<para>
			See also <varname>reply_reason_attr</varname> and
					 <varname>contact_attr</varname>.
		</para>
		<para>
			The default value is "$code".
		</para>
		<example>
			<title>Set <varname>reply_code_attr</varname>,
			<varname>reply_reason_attr</varname> parameters and
			<varname>contact_attr</varname></title>
			<programlisting>
modparam("registrar", "reply_code_attr", "$repl_code")
modparam("registrar", "reply_reason_attr", "$repl_reason")
modparam("registrar", "contact_attr", "$contact")
...
route{
...
	if (!save_noreply("location")) {
		append_to_reply("$contact");
		sl_send_reply($reply_code, $repl_reason);
	}
...
}
			</programlisting>
		</example>
	</section>

	<section id="reply_reason_attr">
		<title><varname>reply_reason_attr</varname> (avp name)</title>
		<para>
			See <varname>reply_code_attr</varname> above.
		</para>
		<para>
			The default value is "$reason".
		</para>
	</section>

	<section id="contact_attr">
		<title><varname>contact_attr</varname> (avp name)</title>
		<para>
			See <varname>reply_code_attr</varname> above.
		</para>
		<para>
			The default value is "$contact".
		</para>
	</section>

	<section id="aor_attr">
		<title><varname>aor_attr</varname> (avp name)</title>
		<para>
			If set to an AVP name, the AOR will be taken from this AVP, 
			instead of the message "To:" header (when using one of the save*()
			functions).
		</para>
		<para>
			The default value is "$aor".
		</para>
		<example>
			<title>Set <varname>aor_attr</varname></title>
			<programlisting>
modparam("registrar", "aor_attr", "$my_aor")
...
route{
...
	if (src_ip==1.2.3.4)
		$my_aor=@msg.header["From"];
	save("location");
...
}
			</programlisting>
		</example>
	</section>

	<section id="server_id_attr">
		<title><varname>server_id_attr</varname> (avp name)</title>
		<para>
			If set to an AVP name, the server ID associated to the contact
			will be set to the AVP value. If not set or the AVP is not found,
			the server ID will be set to the <varname>server_id</varname> of
			the current server.
		</para>
		<para>
			The default value is "$server_id".
		</para>
		<para>
			See also <varname>server_id</varname> (core parameter).
		</para>
		<example>
			<title>Set <varname>server_id_attr</varname></title>
			<programlisting>
...
modparam("registrar", "server_id_attr", "$remote_server_id")
...
route{
...
	if (dst_ip==224.0.1.75 &amp;&amp; method == "REGISTER") {
		# REGISTER replicated on multicast, use the originator server_id
		# (saved in the custom SER-Server-ID header)
		$remote_server_id = @msg.header["SER-Server-ID"];
		setflag(FLAG_REPLICATED);
		save_mem_nr("location");
...
	}
...
}
			</programlisting>
		</example>
	</section>
</section>
