permissions_user.sgml

性能优秀的SIP Proxy

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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.9 $</revnumber>
		<date>$Date: 2006/03/20 00:28:57 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
	<title>Overview</title>
	<section id="sec-call-routing">
		<title>Call Routing</title>
		<para>
		The module can be used to determine if a call has appropriate 
		permission to be established. Permission rules are stored in 
		plaintext configuration files similar to
		<filename moreinfo="none">hosts.allow</filename> and <filename
		moreinfo="none">hosts.deny</filename> files used by tcpd.
		</para>
		<para>
		When <function moreinfo="none">allow_routing</function> function is 
		called it tries to find a rule that matches selected fields of the 
		message.
		</para>
		<para>
		&ser; is a forking proxy and therefore a single message can be sent 
		to different destinations simultaneously. When checking permissions 
		all the destinations must be checked and if one of them fails, the 
		forwarding will fail.
		</para>
		<para>
		The matching algorithm is as follows, first match wins:
		</para>
		<itemizedlist>
		<listitem>
			<para>
			Create a set of pairs of form (From, R-URI of branch 1), 
			(From, R-URI of branch 2), etc.
			</para>
		</listitem>
		<listitem>
			<para>
			Routing will be allowed when all pairs match an entry in the 
			allow file.
			</para>
		</listitem>
		<listitem>
			<para>
			Otherwise routing will be denied when one of pairs matches an 
			entry in the deny file.
			</para>
		</listitem>
		<listitem>
			<para>
			Otherwise, routing will be allowed.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		A non-existing permission control file is treated as if it were an 
		empty file. Thus, permission control can be turned off by providing 
		no permission control files.
		</para>
		<para>
		From header field and Request-URIs are always compared with regular 
		expressions! For the syntax see the sample file: 
		<filename moreinfo="none">config/permissions.allow</filename>.
		</para>
	</section>
	<section id="sec-registration-permissions">
		<title>Registration Permissions</title>
		<para>
		In addition to call routing it is also possible to check REGISTER 
		messages and decide--based on the configuration files--whether the 
		message should be allowed and the registration accepted or not.
		</para>
		<para>
		Main purpose of the function is to prevent registration of "prohibited" 
		IP addresses. One example, when a malicious user registers a contact 
		containing IP address of a PSTN gateway, he might be able to bypass 
		authorization checks performed by the SIP proxy. That is undesirable 
		and therefore attempts to register IP address of a PSTN gateway should 
		be rejected. Files <filename
		moreinfo="none">config/register.allow</filename> and <filename
		moreinfo="none">config/register.deny</filename> contain an example 
		configuration.
		</para>
		<para>
		Function for registration checking is called <function
		moreinfo="none">allow_register</function> and the algorithm is very 
		similar to the algorithm described in 
		<xref linkend="sec-call-routing">. The only difference is in the way 
		how pairs are created.
		</para>
		<para>
		Instead of From header field the function uses To header field because 
		To header field in REGISTER messages contains the URI of the person 
		being registered. Instead of the Request-URI of branches the function 
		uses Contact header field.
		</para>
		<para>
		Thus, pairs used in matching will look like this: (To, Contact 1), 
		(To, Contact 2), (To, Contact 3), and so on..
		</para>
		<para>
		The algorithm of matching is same as described in 
		<xref linkend="sec-call-routing">.
		</para>
	</section>
	<section id="sec-referral-permissions">
		<title>Referral Permissions</title>
		<para>
		The module can be used to determine if referral is
		allowed to the destination specified by Refer-To header
		of REFER request. Permission rules are stored in
		plaintext configuration files similar to
		<filename moreinfo="none">hosts.allow</filename> and
		<filename moreinfo="none">hosts.deny</filename> used by tcpd.
		</para>
		<para>
		When <function moreinfo="none">allow_refer_to</function>
		function is called, it tries to find a rule that matches
		selected fields of the message.
		The matching algorithm is as follows, first match wins:
		</para>
		<itemizedlist>
		<listitem>
			<para>
			Create a pair &lt;From URI, Refer-To URI&gt;.
			</para>
		</listitem>
		<listitem>
			<para>
			Referral will be allowed when the pair matches
			an entry in the allow file.
		</listitem>
		<listitem>
			<para>
			Otherwise referral will be denied when the pair
			matches an entry in the	deny file.
			</para>
		</listitem>
		<listitem>
			<para>
			Otherwise, referral will be allowed.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		A non-existing permission control file is treated as if it were an 
		empty file. Thus, permission control can be turned off by providing 
		no permission control files.
		</para>
		<para>
		From URI and Refer-To URI are always compared with regular 
		expressions! For the syntax see the sample file: 
		<filename moreinfo="none">config/permissions.allow</filename>.
		</para>
	</section>
	<section id="sec-trusted-requests">
		<title>Trusted Requests</title>
		<para>
		The module can be used to determine if an incoming
		request can be trusted without authentication.
		</para>
		<para>
		When <function moreinfo="none">allow_trusted</function>
		function is called, it tries to find a rule that matches
		the request.  Rules contain the following fields:
		&lt;source address, transport protocol, regular
		expression&gt;.
		<para>
		A requests is accepted if there exists a rule, where 
		</para>
		<itemizedlist>
		<listitem>
			<para>
			source address is equal to source address of request,
			</para>
		</listitem>
		<listitem>
			<para>
			transport protocol is either "any" or equal to
			transport protocol of request, and
		</listitem>
		<listitem>
			<para>
			regular expression is either empty (NULL in
			database) or matches From URI of request.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		Otherwise the request is rejected.
		</para>
		<para>
		Rules are stored in a database table specified by module
		parameters.  There also exists a module parameter that
		determines if rules are cached into memory for faster
		matching or if database is consulted for each invocation
		of allow_trusted function call.
		</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>No dependencies on other &ser; modules</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_allow_file</varname> (string)</title>
		<para>
		Default allow file used by functions without parameters. If you 
		don't specify full pathname then the directory in which is the main 
		config file is located will be used.
		</para>
		<para>
		<emphasis>
			Default value is <quote>permissions.allow</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>default_allow_file</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "default_allow_file", "/etc/permissions.allow")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>default_deny_file</varname> (string)</title>
		<para>
		Default file containing deny rules. The file is used by functions
		without parameters. If you don't specify full pathname then the 
		directory in which the main config file is located will be used.
		</para>
		<para>
		<emphasis>
			Default value is <quote>permissions.deny</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>default_deny_file</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "default_deny_file", "/etc/permissions.deny")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>check_all_branches</varname> (integer)</title>
		<para>
		If set then allow_routing functions will check Request-URI of all 
		branches (default). If disabled then only Request-URI of the first 
		branch will be checked.
		</para>
		<warning>
		<para>
		Do not disable this parameter unless you really know what you 
		are doing.
		</para>
		</warning>
		<para>
		<emphasis>
			Default value is 1.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>check_all_branches</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "check_all_branches", 0)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>allow_suffix</varname> (string)</title>
		<para>
		Suffix to be appended to basename to create filename of the allow 
		file when version with one parameter of either 
		<function moreinfo="none">allow_routing</function> or
		<function moreinfo="none">allow_register</function> is used.
		</para>
		<note>
		<para>
			Including leading dot.
		</para>
		</note>
		<para>
		<emphasis>
			Default value is <quote>.allow</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>allow_suffix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "allow_suffix", ".allow")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>deny_suffix</varname> (string)</title>
		<para>
		Suffix to be appended to basename to create filename of the deny file 
		when version with one parameter of either 
		<function moreinfo="none">allow_routing</function> or
		<function moreinfo="none">allow_register</function> is used.
		</para>
		<note>
		<para>
			Including leading dot.
		</para>
		</note>
		<para>
		<emphasis>
			Default value is <quote>.deny</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>deny_suffix</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "deny_suffix", ".deny")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>db_url</varname> (string)</title>
		<para>
		This is URL of the database to be used to store rules used by 
		<function moreinfo="none">allow_trusted</function> function.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "db_url", "mysql://openser:pass@db_host/openser")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>db_mode</varname> (integer)</title>
		<para>
		Database mode. 0 means non-caching, 1 means caching.
		</para>
		<para>
		<emphasis>
			Default value is 0 (non-caching).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "db_mode", 1)
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>trusted_table</varname> (string)</title>
		<para>
		Name of database table containing matching rules used by
		<function moreinfo="none">allow_register</function> function.
		</para>
		<para>
		<emphasis>
		Default value is <quote>trusted</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>trusted_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "trusted_table", "pbx")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>source_col</varname> (string)</title>
		<para>
		Name of trusted table column containing source IP
		address that is matched against source IP address of
		received request.
		</para>
		<para>
		<emphasis>
		Default value is <quote>src_ip</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>source_col</varname> parameter</title>