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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1827 $</revnumber>
		<date>$Date: 2007-03-12 17:22:53 +0200 (Mon, 12 Mar 2007) $</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-uri-permissions">
		<title>URI Permissions</title>
		<para>
		The module can be used to determine if request is
		allowed to the destination specified by an URI stored in
		a pseudo-variable.  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_uri</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, URI stored in pseudo-variable&gt;.
			</para>
		</listitem>
		<listitem>
			<para>
			Request will be allowed when the pair matches
			an entry in the allow file.
		</listitem>
		<listitem>
			<para>
			Otherwise request will be denied when the pair
			matches an entry in the	deny file.
			</para>
		</listitem>
		<listitem>
			<para>
			Otherwise, request 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 URI stored in pseudo-variable 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-address-permissions">
		<title>Address Permissions</title>
		<para>
		The module can be used to determine if an address (IP
		address and port) matches any of the IP subnets
		stored in cached openser database table.
		Port 0 in cached database table matches any port.  IP
		address and port to be matched can be either taken from
		the request (allow_source_address) or given as pseudo
		value arguments (allow_address).
		</para>
		<para>
		Addresses stored in cached database table can be grouped
		together into one or more groups specified by a group
		identifier (unsigned integer).  Group
		identifier is given as argument to
		allow_source_address function or assigned separately
		for subsequent allow_address function calls using
		set_address_group function.
		</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>address_table</varname> (string)</title>
		<para>
		Name of database table containing IP subnet information used by
		<function moreinfo="none">allow_address</function> and
                <function moreinfo="none">allow_source_address</function>
                functions.
		</para>
		<para>
		<emphasis>
		Default value is <quote>address</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>address_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "address_table", "addr")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>grp_col</varname> (string)</title>
		<para>
		Name of address table column containing group
		identifier of the address.
		</para>
		<para>
		<emphasis>
		Default value is <quote>grp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>grp_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "grp_col", "group_id")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>ip_addr_col</varname> (string)</title>
		<para>
		Name of address table column containing IP address
		part of the address.
		</para>
		<para>
		<emphasis>
		Default value is <quote>ip_addr</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>ip_addr_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "ip_addr_col", "ip_address")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>mask_col</varname> (string)</title>
		<para>
		Name of address table column containing network mask of
		the address.  Possible values are 0-32.
		</para>
		<para>
		<emphasis>
		Default value is <quote>mask</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>mask_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "mask_col", "subnet_length")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>port_col</varname> (string)</title>
		<para>
		Name of address table column containing port
		part of the address.
		</para>
		<para>
		<emphasis>
		Default value is <quote>port</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>port_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "port_col", "prt")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>db_mode</varname> (integer)</title>
		<para>
		Database mode. 0 means non-caching, 1 means caching.
		Valid only for allow_trusted function.
		</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>
		<programlisting format="linespecific">
...
modparam("permissions", "source_col", "source_ip_address")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>proto_col</varname> (string)</title>
		<para>
		Name of trusted table column containing transport
		protocol that is matched against transport protocol of
		received request.  Possible values that can be stored in
		proto_col are <quote>any</quote>, <quote>udp</quote>,
		<quote>tcp</quote>, <quote>tls</quote>,
		<quote>sctp</quote>, and <quote>none</quote>.  Value
		<quote>any</quote> matches always and value
		<quote>none</quote> never.
		</para>
		<para>
		<emphasis>
			Default value is <quote>proto</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>proto_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "proto_col", "transport")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>from_col</varname> (string)</title>
		<para>
		Name of trusted table column containing regular
		expression that is matched against From URI.
		</para>
		<para>
		<emphasis>
		Default value is <quote>from_pattern</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>from_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "from_col", "regexp")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>tag_col</varname> (string)</title>
		<para>
		Name of trusted table column containing a string
		that is added as value to peer_tag AVP if peer_tag AVP
                has been defined and if the peer matches.
		</para>
		<para>
		<emphasis>
		Default value is <quote>tag</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>tag_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "tag_col", "peer_tag")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>peer_tag_avp</varname> (string)</title>
		<para>
		AVP spec of peer tag AVP.  If defined, the AVP will be
                set as side effect of allow_trusted() call to not NULL
                tag column value of the matching peer.
		</para>
		<para>
		<emphasis>
		Default value is <quote>undefined</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>peer_tag_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("permissions", "peer_tag_avp", "i:707")
...
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">allow_routing()</function>
		</title>
		<para>
		Returns true if all pairs constructed as described in <xref
		linkend="sec-call-routing"> have appropriate permissions according to 
		the configuration files. This function uses default configuration 
		files specified in <varname>default_allow_file</varname> and
		<varname>default_deny_file</varname>.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>allow_routing</function> usage</title>
		<programlisting format="linespecific">
...
if (allow_routing()) {
	t_relay();
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">allow_routing(basename)</function>
		</title>
		<para>
		Returns true if all pairs constructed as described in <xref
		linkend="sec-call-routing"> have appropriate permissions according 
		to the configuration files given as parameters.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>basename</emphasis> - Basename from which allow 
			and deny filenames will be created by appending contents of
			<varname>allow_suffix</varname> and <varname>deny_suffix</varname>
			parameters.
			</para>
			<para>
			If the parameter doesn't contain full pathname then the function 
			expects the file to be located in the same directory as the main 
			configuration file of the server.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>allow_routing(basename)</function> usage</title>
		<programlisting format="linespecific">
...
if (allow_routing("basename")) {
	t_relay();
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">allow_routing(allow_file,deny_file)</function>
		</title>
		<para>
		Returns true if all pairs constructed as described in 
		<xref linkend="sec-call-routing"> have appropriate permissions 
		according to the configuration files given as parameters.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>allow_file</emphasis> - File containing allow rules.
			</para>
			<para>
			If the parameter doesn't contain full pathname then the function 
			expects the file to be located in the same directory as the main 
			configuration file of the server.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>deny_file</emphasis> - File containing deny rules.
			</para>
			<para>
			If the parameter doesn't contain full pathname then the function 
			expects the file to be located in the same directory as the main 
			configuration file of the server.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>allow_routing(allow_file, deny_file)</function> usage</title>
		<programlisting format="linespecific">
...
if (allow_routing("rules.allow", "rules.deny")) {
	t_relay();
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">allow_register(basename)</function>
		</title>
		<para>
		The function returns true if all pairs constructed as described in <xref
		linkend="sec-registration-permissions"> have appropriate permissions 
		according to the configuration files given as parameters.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>basename</emphasis> - Basename from which allow 
			and deny filenames will be created by appending contents of
			<varname>allow_suffix</varname> and <varname>deny_suffix</varname>
			parameters.
			</para>
			<para>
			If the parameter doesn't contain full pathname then the function 
			expects the file to be located in the same directory as the main 
			configuration file of the server.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>allow_register(basename)</function> usage</title>
		<programlisting format="linespecific">
...
if (method=="REGISTER") {
	if (allow_register("register")) {
		save("location");
		break;
	} else {
		sl_send_reply("403", "Forbidden");
	};
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">allow_register(allow_file, deny_file)</function>
		</title>
		<para>
		The function returns true if all pairs constructed as described in 
		<xref linkend="sec-registration-permissions"> have appropriate 
		permissions according to the configuration files given as parameters.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>allow_file</emphasis> - File containing allow rules.
			</para>
			<para>
			If the parameter doesn't contain full pathname then the function 
			expects the file to be located in the same directory as the main 
			configuration file of the server.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>deny_file</emphasis> - File containing deny rules.
			</para>
			<para>
			If the parameter doesn't contain full pathname then the function 
			expects the file to be located in the same directory as the main 
			configuration file of the server.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>allow_register(allow_file, deny_file)</function> usage</title>
		<programlisting format="linespecific">
...
if (method=="REGISTER") {
	if (allow_register("register.allow", "register.deny")) {
		save("location");
		break;
	} else {
		sl_send_reply("403", "Forbidden");
	};
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">allow_uri(basename, pseudo-variable)</function>
		</title>
		<para>
		Returns true if the pair constructed as described in <xref
		linkend="sec-uri-permissions"> have appropriate permissions 
		according to the configuration files specified by the parameter.
		</para>
		<para>Meaning of the parameter is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>basename</emphasis> - Basename from which allow 
			and deny filenames will be created by appending contents of
			<varname>allow_suffix</varname> and <varname>deny_suffix</varname>
			parameters.
			</para>
			<para>
			If the parameter doesn't contain full pathname then the function 
			expects the file to be located in the same directory as the main 
			configuration file of the server.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>pseudo-variable</emphasis> - Any
			pseudo-variable defined in OpenSER.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>allow_uri(basename, pseudo-variable)</function> usage</title>
		<programlisting format="linespecific">
...
if (allow_uri("basename", "$rt")) {  // Check Refer-To URI
	t_relay();
};
if (allow_uri("basename", "$avp(i:705)") {  // Check URI stored in $avp(i:705)
	t_relay();
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">set_address_group(group_id)</function>
		</title>
		<para>
		Sets address group to be used in subsequent allow_address
		function calls to an unsigned integer value given as
		argument.  Argument can be an integer string or a pseudo
		variable.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>set_address_group(group_id)</function> usage</title>
		<programlisting format="linespecific">
...

// Set address group identifier to 1.
set_address_group("1");
// Set address group identifier to value of pseudo variable i:100.
set_address_group("$avp(i:100)");
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">allow_address(ip_addr_pv, port_pv)</function>
		</title>
		<para>
		Returns true if IP address and port given as values of pseudo
		variable arguments and belonging to an earlier
		assigned address group matches an IP subnet found in
		cached address table.  Cached address table entry
		containing port value 0 matches any port.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>allow_address(ip_addr_pv, port_pv)</function> usage</title>
		<programlisting format="linespecific">
...

// Check source address/port of request
if (!allow_address("$si", "$sp")) {
	sl_send_reply("403", "Forbidden");
};
// Check IP address/port stored in AVPs i:704/i:705
if (!allow_address("$avp(i:704)", "$avp(i:705)") {
	sl_send_reply("403", "Forbidden");
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">allow_source_address(group_id)</function>
		</title>
		<para>
		Equal to set_address_group(group_id);
		allow_address("$si", "$sp"), but faster.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>allow_source_address(group_id)</function> usage</title>
		<programlisting format="linespecific">
...

// Check source address/port of request
if (!allow_source_address("0")) {
	sl_send_reply("403", "Forbidden");
};
...
</programlisting>
		</example>
	</section>
	<section>
		<title>
		<function moreinfo="none">allow_trusted()</function>
		</title>
		<para>
		Checks based on request's source address, transport
		protocol, and From URI if request can be trusted without
		authentication.  Returns 1 if a match is found
		as described in <xref linkend="sec-trusted-requests">
		and -1 otherwise.  If a match is found
		and peer_tag_avp has been defined, adds a
                non-NULL tag column value of the
		matching peer to AVP peer_tag_avp.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>allow_trusted()</function> usage</title>
		<programlisting format="linespecific">
...
if (allow_trusted()) {
	t_relay();
};
...
</programlisting>
		</example>
	</section>
	</section>
	
	<section>
	<title>Exported MI Functions</title>
	<section>
		<title>
		<function moreinfo="none">address_reload</function>
		</title>
		<para>
				Causes permissions module to re-read the contents of
				address database table into cache
				memory.  In cache memory the entries are
				for performance reasons stored in two
                                different tables:  address table and
				subnet table depending on the value of
				the mask field (32 or smaller).

		</para>
		<para>
		Name: <emphasis>address_reload</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:address_reload:_reply_fifo_file_
		_empty_line_
		</programlisting>



		
	</section>
	
	<section>
		<title>
		<function moreinfo="none">address_dump</function>
		</title>
		<para>
				Causes permissions module to dump
                   contents of cache memory address table.

				</para>
		<para>
		Name: <emphasis>address_dump</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:address_dump:_reply_fifo_file_
		_empty_line_
		</programlisting>


	</section>
	<section>
		<title>
		<function moreinfo="none">subnet_dump</function>
		</title>
		<para>
				Causes permissions module to dump
                   contents of cache memory subnet table.

				</para>
		<para>
		Name: <emphasis>subnet_dump</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:subnet_dump:_reply_fifo_file_
		_empty_line_
		</programlisting>
	</section>
	<section>
		<title>
		<function moreinfo="none">trusted_reload</function>
		</title>
		<para>
				Causes permissions module to re-read the contents of
				trusted table into cache memory.
				</para>
		<para>
		Name: <emphasis>trusted_reload</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:trusted_reload:_reply_fifo_file_
		_empty_line_
		</programlisting>
	</section>
	<section>
		<title>
		<function moreinfo="none">trusted_dump</function>
		</title>
		<para>
				Causes permissions module to dump contents of trusted
				table from cache memory.
				</para>
		<para>
		Name: <emphasis>trusted_dump</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:trusted_dump:_reply_fifo_file_
		_empty_line_
		</programlisting>
	</section>
	</section>

</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("permissions.sgml" "Book" "chapter")
End:
-->
