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

<chapter>

	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		This module provides a Radius implementation for the AAA API from the core.
	</para>
	<para>
		It also provides two functions to be used from the script for generating custom Radius acct and auth requests.
		Detection and handling of SIP-AVPs from Radius replies is automatically and transparently done by the module.
	</para>

	<para>
		Since version 2.2, aaa_radius module supports asynchronous operations. But in order to use them, one must apply
		the patch contained by the modules/aaa_radius folder, called <emphasis>radius_async_support.patch</emphasis>.In
		order to do this, you must have freeradius-client sources. In order to do this you can follow
		the tutorial in the end of the documentation.
	</para>

	<para>
		Any module that wishes to use it has to do the following:
	</para>
	<itemizedlist>
		<listitem>
			<para><emphasis>include aaa.h</emphasis>
			</para>
		</listitem>
		<listitem>
			<para><emphasis>make a bind call with a proper radius specific url</emphasis>
			</para>
		</listitem>

	</itemizedlist>

	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		None.
		</para>
	</section>

	<section>
		<title>External Libraries or Applications</title>
		<para>
		One of the following libraries must be installed before running
		&osips; with this module loaded:
		</para>
			<itemizedlist>
			<listitem>
			<para><emphasis>radiusclient-ng</emphasis> 0.5.0 or higher
				See <ulink
				url='http://developer.berlios.de/projects/radiusclient-ng/'>
				http://developer.berlios.de/projects/radiusclient-ng/</ulink>.
			</para>
			</listitem>
			<listitem>
			<para><emphasis>freeradius-client</emphasis>
				See <ulink
				url='http://freeradius.org/'>
				http://freeradius.org/</ulink>.
			</para>
			</listitem>
			</itemizedlist>
			<para>
				One can force the radius library that is usedby setting RADIUSCLIENT env, before compiling the module, to one of the following values:
				<itemizedlist>
					<listitem>
						<para><emphasis>RADCLI  ***</emphasis> libradcli-dev library shall be used;</para>
					</listitem>

					<listitem>
						<para><emphasis>FREERADIUS  ***</emphasis> libfreeradius-client-dev library shall be used;</para>
					</listitem>

					<listitem>
						<para><emphasis>RADIUSCLIENT  ***</emphasis> libradiusclient-ng library shall be used;</para>
					</listitem>
				</itemizedlist>

				<para>IMPORTANT: If the selected library is not installed the module won't compile.</para>
				<para>NOTE: If RADIUSCLIENT env not set, the module will try to find one of the three radius libraries in
				the following order: radcli, freeradius, radiusclient-ng. That is if radcli library is installed
				it shall be used, else freeradius shall be looked for and so on.</para>
			</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
		<section id="param_sets" xreflabel="sets">
		<title><varname>sets (string)</varname></title>
		<para>
			Sets of Radius AVPs to be used when building custom RADIUS requests (set of input RADIUS AVPs)
			or when fetching data from the RADIUS reply (set of output RADIUS AVPs).
		</para>

		<para>
			The format for a set definition is the following:
		</para>
		<itemizedlist>
			<listitem>
			<para>
			" set_name = ( attribute_name1 = var1 [, attribute_name2 = var2 ]* ) "
			</para>
			</listitem>
		</itemizedlist>
		<para>
			The left-hand side of the assignment must be an attribute name known by the RADIUS dictionary.
		</para>
		<para>
			The right-hand side of the assignment must be a script pseudo variable or
			a script AVP. For more information about them see <ulink
				url='https://opensips.org/Resources/DocsCoreVar15'>
				CookBooks - Scripting Variables</ulink>.
		</para>
		<example>
		<title>Set <varname>sets</varname> parameter</title>
		<programlisting format="linespecific">

...
modparam("aaa_radius","sets","set4  =  (  Sip-User-ID  =   $avp(10)
			,   Sip-From-Tag=$si,Sip-To-Tag=$tt      )      ")
...

...
modparam("aaa_radius","sets","set1 = (User-Name=$var(usr), Sip-Group = $var(grp),
			Service-Type = $var(type)) ")
...

...
modparam("aaa_radius","sets","set2 = (Sip-Group = $var(sipgrup)) ")
...

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

		<section id="param_radius_config" xreflabel="radius_config">
		<title><varname>radius_config (string)</varname></title>
		<para>
			Radiusclient configuration file.
		</para>
		<para>
			This parameter is optional. It must be set only if the radius_send_acct
			and radius_send_auth functions are used.
		</para>
		<example>
		<title>Set <varname>radius_config</varname> parameter</title>
		<programlisting format="linespecific">

...
modparam("aaa_radius", "radius_config", "/etc/radiusclient-ng/radiusclient.conf")
...

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

		<section id="param_syslog_name" xreflabel="syslog_name">
		<title><varname>syslog_name (string)</varname></title>
		<para>
		Enable logging of the client library to syslog, using the given log name.
		</para>
		<para>
		This parameter is optional. Radius client libraries will try to use syslog
		to report errors (such as problems with dictionaries) with the given ident
		string .If this parameter is set, then these errors are visible in syslog.
		Otherwise errors are hidden.
		</para>
		<para>
		By default this parameter is not set (no logging).
		</para>
		<example>
		<title>Set <varname>syslog_name</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("aaa_radius", "syslog_name", "aaa-radius")
...
</programlisting>
		</example>
		</section>

		<section id="param_fetch_all_values" xreflabel="fetch_all_values">
		<title><varname>fetch_all_values (integer)</varname></title>
		<para>
		For the output sets, this parameter controls if all the values (for the same
		RADIUS AVP) should be returned (otherwise only the first value will be
		returned). When enabling this options, be sure that the variable you use
		to get the RADIUS output can store multiple values (like the AVP variables).
		</para>
		<para>
		By default this parameter is disabled (set to 0) for backward compatibility
		reasons.
		</para>
		<example>
		<title>Set <varname>fetch_all_values</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("aaa_radius", "fetch_all_values", 1)
...
</programlisting>
		</example>
		</section>

	</section>

	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>

		<section id="func_radius_send_auth" xreflabel="radius_send_auth()">

		<title>
		<function moreinfo="none">radius_send_auth(input_set_name, output_set_name)</function>
		</title>
		<para>
			This function can be used from the script to make custom
			radius authentication request. The function takes two parameters.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>input_set_name</emphasis> (string) - the name of the
				set that contains the list of attributes and pvars that will
				form the authentication request (see the <quote>sets</quote>
				module parameter).
			</para></listitem>
			<listitem><para>
				<emphasis>output_set_name</emphasis> (string) - the name of the
				set that contains the list of attributes and pvars that will be
				extracted form the authentication reply (see the <quote>sets</quote>
				module parameter).
			</para></listitem>
		</itemizedlist>
		<para>
			The sets must be defined using the <quote>sets</quote> exported
			parameter.
		</para>
		<para>
			The function return TRUE (retcode 1) if authentication was
			successful, FALSE (retcode -1) if an error (any kind of error)
			occurred during authentication processes or FALSE (retcode -2) if
			authentication was rejected or denied by RADIUS server.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, ERROR_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>radius_send_auth</function> usage</title>
		<programlisting format="linespecific">

...
radius_send_auth("set1","set2");
switch ($rc) {
	case 1:
		xlog("authentication ok \n");
		break;
	case -1:
		xlog("error during authentication\n");
		break;
	case -2:
		xlog("authentication denied \n");
		break;
}
...

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

		<section id="func_radius_send_acct" xreflabel="radius_send_acct()">
		<title>
		<function moreinfo="none">radius_send_acct(input_set_name)</function>
		</title>
		<para>
			This function can be used from the script to make custom
			radius authentication request. The function takes only one string parameter
			that represents the name of the set that contains the list of attributes
			and pvars that will form the accounting request.
		</para>
		<para>
			Only one set is needed as a parameter because no AVPs can be extracted
			from the accounting replies.
		</para>
		<para>
			The set must be defined using the "sets" exported parameter.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, ERROR_ROUTE and LOCAL_ROUTE.
		</para>
		<example>

		<title><function>radius_send_acct</function> usage</title>
		<programlisting format="linespecific">

...
radius_send_acct("set1");
...

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

	<section>
		<title>Exported Async Functions</title>

		<section id="afunc_radius_send_auth" xreflabel="radius_send_auth()">

		<title>
		<function moreinfo="none">radius_send_auth(input_set_name, output_set_name)</function>
		</title>
		<para>
			This function can be used from the script to make custom
			radius authentication request.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>input_set_name</emphasis> (string) - the name of the
				set that contains the list of attributes and pvars that will
				form the authentication request (see the <quote>sets</quote>
				module parameter).
			</para></listitem>
			<listitem><para>
				<emphasis>output_set_name</emphasis> (string) - the name of the
				set that contains the list of attributes and pvars that will be
				extracted form the authentication reply (see the <quote>sets</quote>
				module parameter).
			</para></listitem>
		</itemizedlist>
		<para>
			The sets must be defined using the <quote>sets</quote> exported
			parameter.
		</para>
		<para>
			The function return TRUE (retcode 1) if authentication was
			successful, FALSE (retcode -1) if an error (any kind of error)
			occurred during authentication processes or FALSE (retcode -2) if
			authentication was rejected or denied by RADIUS server.
		</para>
		<example>
		<title><function>radius_send_auth</function> usage</title>
		<programlisting format="linespecific">

...
{
async( radius_send_auth("set1","set2"), resume);
}

route[resume] {
switch ($rc) {
	case 1:
		xlog("authentication ok \n");
		break;
	case -1:
		xlog("error during authentication\n");
		break;
	case -2:
		xlog("authentication denied \n");
		break;
}
...

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

		<section id="afunc_radius_send_acct" xreflabel="radius_send_acct()">
		<title>
		<function moreinfo="none">radius_send_acct(input_set_name)</function>
		</title>
		<para>
			This function can be used from the script to make custom
			radius authentication request. The function takes only one string parameter
			that represents the name of the set that contains the list of attributes
			and pvars that will form the accounting request.
		</para>
		<para>
			Only one set is needed as a parameter because no AVPs can be extracted
			from the accounting replies.
		</para>
		<para>
			The set must be defined using the "sets" exported parameter.
		</para>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, ERROR_ROUTE and LOCAL_ROUTE.
		</para>
		<example>

		<title><function>radius_send_acct</function> usage</title>
		<programlisting format="linespecific">

...
{
async( radius_send_acct("set1","set2"), resume);
}

route[resume] {
xlog(" accounting finished\n");
}

...

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