modules/ims_qos: added patch for flow-description bug when request originates from...
[sip-router] / modules / acc_radius / doc / acc_radius_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10
11 <!-- Acc Module User's Guide -->
12
13 <chapter>
14
15         <title>&adminguide;</title>
16
17         <section>
18         <title>Overview</title>
19         <para>
20                 ACC_RADIUS module is used to account transaction information to
21                 <acronym>RADIUS</acronym> server. It binds to ACC module API and uses the
22                 same accounting mechanisms as for other backends.
23         </para>
24         <para>
25                 Therefore you need this module just to send accounting data to a
26                 RADIUS server - for more documentation regarding accounting, see the ACC
27                 readme.
28         </para>
29         </section>
30
31         <section>
32                 <title>Dependencies</title>
33                 <section>
34                         <title>&kamailio; Modules</title>
35                         <para>
36                         The module depends on the following modules (in the other words
37                         the listed modules must be loaded before this module):
38                         <itemizedlist>
39                                 <listitem>
40                                 <para><emphasis>acc</emphasis> - accounting module</para>
41                                 </listitem>
42                         </itemizedlist>
43                         </para>
44                 </section>
45                 <section>
46                         <title>External Libraries or Applications</title>
47                         <para>
48                         The following libraries or applications must be installed
49                         before running &kamailio; with this module loaded:
50                         </para>
51                         <itemizedlist>
52                                 <listitem>
53                                 <para><emphasis>radiusclient-ng</emphasis> 0.5.0 or higher,
54                                 <emphasis>freeradius-client</emphasis> <ulink
55                                 url='https://github.com/FreeRADIUS/freeradius-client/'>
56                                 https://github.com/FreeRADIUS/freeradius-client/</ulink> or
57                                 <emphasis>radcli</emphasis> <ulink
58                                         url='http://radcli.github.io/radcli/'>
59                                 http://radcli.github.io/radcli/</ulink>.
60                                 </para>
61                                 </listitem>
62                                 <listitem>
63                                 <para>
64                                 <emphasis>freeradius-client</emphasis> library can be used after
65                                 setting FREERADIUS variable in source code with
66                                 <emphasis>'export FREERADIUS=1'</emphasis> before compile.
67                                 </para>
68                                 </listitem>
69                                 <listitem>
70                                 <para>
71                                 <emphasis>radcli</emphasis> library can be used after
72                                 setting RADCLI variable in source code with
73                                 <emphasis>'export RADCLI=1'</emphasis> before compile.
74                                 </para>
75                                 </listitem>
76                         </itemizedlist>
77                 </section>
78         </section>
79
80         <section id="ACC-param-id">
81         <title>Parameters</title>
82         <section id="acc_radius.p.radius_config">
83                 <title><varname>radius_config</varname> (string)</title>
84                 <para>
85                 <emphasis>This parameter is radius specific.</emphasis> Path to
86                 radius client configuration file, set the referred config file
87                 correctly and specify there address of server, shared secret
88                 (should equal that in /usr/local/etc/raddb/clients for
89                 freeRadius servers) and dictionary, see etc for an example of
90                 config file and dictionary.
91                 </para>
92                 <para>
93                 If the parameter is set to empty string, the RADIUS accounting support
94                 will be disabled (even if compiled).
95                 </para>
96                 <para>
97                 Default value is <quote>NULL</quote>.
98                 </para>
99                 <example>
100                 <title>radius_config example</title>
101                 <programlisting format="linespecific">
102 ...
103 modparam("acc_radius", "radius_config", "/etc/radiusclient/radiusclient.conf")
104 ...
105 </programlisting>
106                 </example>
107         </section>
108         <section id="acc_radius.p.radius_flag">
109                 <title><varname>radius_flag</varname> (integer)</title>
110                 <para>
111                 Request flag which needs to be set to account a
112                 transaction -- RADIUS specific.
113                 </para>
114                 <para>
115                 Default value is not-set (no flag).
116                 </para>
117                 <example>
118                 <title>radius_flag example</title>
119                 <programlisting format="linespecific">
120 ...
121 modparam("acc_radius", "radius_flag", 2)
122 ...
123 </programlisting>
124                 </example>
125         </section>
126         <section id="acc_radius.p.radius_missed_flag">
127                 <title><varname>radius_missed_flag</varname> (integer)</title>
128                 <para>
129                 Request flag which needs to be set to account missed
130                 calls -- RADIUS specific.
131                 </para>
132                 <para>
133                 Default value is not-set (no flag).
134                 </para>
135                 <example>
136                 <title>radius_missed_flag example</title>
137                 <programlisting format="linespecific">
138 ...
139 modparam("acc_radius", "radius_missed_flag", 3)
140 ...
141 </programlisting>
142                 </example>
143         </section>
144         <section id="acc_radius.p.service_type">
145                 <title><varname>service_type</varname> (integer)</title>
146                 <para>
147                 Radius service type used for accounting.
148                 </para>
149                 <para>
150                 Default value is 15 (SIP).
151                 </para>
152                 <example>
153                 <title>service_type example</title>
154                 <programlisting format="linespecific">
155 ...
156 modparam("acc_radius", "service_type", 16)
157 ...
158 </programlisting>
159                 </example>
160         </section>
161         <section id="acc_radius.p.radius_extra">
162                 <title><varname>radius_extra</varname> (string)</title>
163                 <para>
164                 Extra values to be logged via RADIUS - RADIUS specific.
165                 </para>
166                 <para>
167                 Default value is NULL.
168                 </para>
169                 <example>
170                 <title>radius_extra example</title>
171                 <programlisting format="linespecific">
172 ...
173 modparam("acc_radius", "radius_extra", "via=$hdr(Via[*]); email=$avp(s:email)")
174 ...
175 </programlisting>
176                 </example>
177         </section>
178         <section id="acc_radius.p.rad_time_mod">
179                 <title><varname>rad_time_mode</varname>(integer)</title>
180                 <para>
181                 Radius Event-Timestamp for accounting.
182                 </para>
183                 <para>
184                 Values can be:
185                 </para>
186                 <itemizedlist>
187                 <listitem>
188                         <para><emphasis>0</emphasis> -  (default), format is only unix
189                                 timestamp for Event-Timestamp (For example: 1445590624)</para>
190                 </listitem>
191                 <listitem>
192                         <para><emphasis>1</emphasis> - format is unix timestamp with microseconds
193                         in Addition, it needs to change Event-Timestamp attribute type in dictionary to string
194                         both radius server and client
195                         (For example: 1445590624.377372)   </para>
196                 </listitem>
197                 </itemizedlist>
198
199                 <para>
200                 Default value is 0 (Unix timestamp).
201                 </para>
202                 <example>
203                 <title>rad_time_mode example</title>
204                 <programlisting format="linespecific">
205 ...
206 modparam("acc_radius", "rad_time_mode", 1)
207 ...
208 </programlisting>
209                 </example>
210 </section>
211         </section>
212
213         <section>
214         <title>Functions</title>
215         <section id="acc_radius.f.acc_rad_request">
216                 <title>
217                         <function moreinfo="none">acc_rad_request(comment)</function>
218                 </title>
219                 <para>
220                 Like <function moreinfo="none">acc_log_request</function> of acc module,
221                 <function moreinfo="none">acc_rad_request</function> reports on
222                 a SIP request event. It reports to radius server as configured in
223                 <quote>radius_config</quote>.
224                 </para>
225                 <para>
226                 Meaning of the parameters is as follows:</para>
227                 <itemizedlist>
228                 <listitem>
229                         <para><emphasis>comment</emphasis> - Comment to be appended. The
230                                 first token can be a SIP response code that it is wanted to
231                                 be interpreted as event type (e.g., using 200 means the
232                                 transaction is considered successfully responded).
233                         </para>
234                 </listitem>
235                 </itemizedlist>
236                 <para>
237                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
238                 </para>
239                 <example>
240                 <title>acc_rad_request usage</title>
241                 <programlisting format="linespecific">
242 ...
243 acc_rad_request("Some comment");
244 ...
245 # write record as when the transaction was responded with a 200 code
246 acc_rad_request("200 From Config");
247 ...
248 </programlisting>
249                 </example>
250         </section>
251         </section>
252 </chapter>
253