registrar_user.sgml

性能优秀的SIP Proxy

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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.12 $</revnumber>
		<date>$Date: 2006/04/13 16:44:04 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<para>The module contains REGISTER processing logic.</para>
		<section>
		<title>PATH support</title>
		<para>
		Register module includes Path support (according to RFC 3327) 
		for usage in registrars and home-proxies.
		</para>
		<para>
		A call to save(...) stores, if path-support is enabled
		in the registrar-module, the values of the Path
		Header(s) along with the contact into usrloc. There are
		three modes regarding the reply to a REGISTER including
		one or more Path HFs:
		</para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>off</emphasis> - stores the value of the 
				Path headers into usrloc without passing it back to 
				the UAC in the reply.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>lazy</emphasis> - stores the Path header and 
				passes it back to the UAC if Path-support is indicated 
				by the <quote>path</quote> param in the Supported HF.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>strict</emphasis> - rejects the registration 
				with <quote>420 Bad Extension</quote> 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.
			</para>
			</listitem>
		</itemizedlist>
		<para>
		A call to lookup(...) always uses the path header if
		found, and inserts it as Route HF either in front of
		the first Route HF, or after the last Via HF if no
		Route is present. It also sets the destination uri to
		the first Path uri, thus overwriting the received-uri,
		because NAT has to be handled at the outbound-proxy of
		the UAC (the first hop after client's NAT).
		</para>
		<para>
		The whole process is transparent to the user, so no
		config changes are required beside setting the
		registrar-parameters <quote>use_path</quote> and 
		<quote>path_mode</quote>.
		</para>
		</section>
	</section>


	<section>
	<title>Dependencies</title>
	<section>
		<title>&ser; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>usrloc - User Location Module</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>sl - Stateless Replies</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Exported Parameters</title>
	<section>
		<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>
		<emphasis>
			Default value is 3600.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>default_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "default_expires", 1800)
...
</programlisting>
		</example>
	</section>
	<section>
		<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>
		<emphasis>
			Default value is 60.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>min_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "min_expires", 60)
...
</programlisting>
		</example>
	</section>
	<section>
		<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>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_expires</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "max_expires", 120)
...
</programlisting>
		</example>
	</section>

	<section>
		<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>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>default_q</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "default_q", 100)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>nat_flag</varname> (integer)</title>
		<para>
		The parameter specifies the flag to be used as NAT marker. The idea is
		to set this flag if a register come behind a NAT; the 
		<quote>save()</quote> functions will save the flag in the usrloc, flag
		that will be restore by the <quote>lookup()</quote> function.
		</para>
		<para>
		<emphasis>
			Default value is -1 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>nat_flag</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "nat_flag", 6)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>sip_natping_flag</varname> (integer)</title>
		<para>
		The parameter specifies the flat to be used to mark the contacts to 
		be NAT pinged via a SIP request instead if dummy UDP package. The flag
		will be stored in usrloc by the <quote>save()</quote> functions and
		internally used by the <quote>nathelper</quote> module. The flag
		will NOT be restore by the <quote>lookup()</quote> function.
		</para>
		<para>
		<emphasis>
			Default value is -1 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sip_natping_flag</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "sip_natping_flag", 7)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>tcp_persistent_flag</varname> (integer)</title>
		<para>
		The parameter specifies the flat 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 
		<quote>save()</quote> functions will set the lifetime of the TCP
		connection to the contact expire value. By doing this, the TCP 
		connection will stay on as long as the contact is valid.
		</para>
		<para>
		<emphasis>
			Default value is -1 (disabled).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>tcp_persistent_flag</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "tcp_persistent_flag", 7)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>realm_prefix</varname> (string)</title>
		<para>
		 Prefix to be automatically strip from realm. As an alternative to 
		 SRV records (not all SIP clients support SRV lookup), a subdomain of 
		 the master domain can be defined for SIP purposes (like 
		 sip.mydomain.net pointing to same IP address as the SRV record for 
		 mydomain.net). By ignoring the realm_prefix "sip.", at registration,
		 sip.mydomain.net will be equivalent to mydomain.net .
		</para>
		<para>
		<emphasis>
			Default value is NULL (none).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>realm_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "realm_prefix", "sip.")
...
</programlisting>
		</example>
	</section>


	<section>
		<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>
		<emphasis>
			Default value is 1.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>append_branches</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "append_branches", 0)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>use_domain</varname> (integer)</title>
		<para>
		If set to 1 then the registrar will use username@domain as address 
		of record. If the variable is set to 0 then only username will be 
		used as the address of record.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_domain</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "use_domain", 1)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>case_sensitive</varname> (integer)</title>
		<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>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>case_sensitive</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "case_sensitive", 1)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>desc_time_order</varname> (integer)</title>
		<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>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>desc_time_order</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "desc_time_order", 1)
...
</programlisting>
		</example>
	</section>

	<section>
		<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>
		<emphasis>
			Default value is 42.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>received_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "received_avp", 43)
...
</programlisting>
		</example>
	</section>

	<section>
		<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>
		<emphasis>
			Default value is "received".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>received_param</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("registrar", "received_param", "rcv")
...
</programlisting>
		</example>
	</section>

	<section>
		<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>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>max_contacts</varname> parameter</title>
		<programlisting format="linespecific">
...
# Allow no more than 10 contacts per AOR
modparam("registrar", "max_contacts", 10)
...
		</programlisting>
		</example>
	</section>