script parsing: fix bug in expression error checking
[sip-router] / modules_s / acc_syslog / README
1 1. Acc Module
2
3 Jiri Kuthan
4
5    iptel.org
6    <jiri@iptel.org>
7
8    Copyright © 2002, 2003 FhG FOKUS
9    Revision History
10    Revision $Revision$ $Date$
11      __________________________________________________________________
12
13    1.1. Overview
14    1.2. Dependencies
15    1.3. Parameters
16
17         1.3.1. secret (string)
18         1.3.2. log_level (integer)
19         1.3.3. log_fmt (string)
20         1.3.4. early_media (integer)
21         1.3.5. failed_transactions (integer)
22         1.3.6. log_flag (integer)
23         1.3.7. log_missed_flag (integer)
24         1.3.8. report_ack (integer)
25         1.3.9. report_cancels (integer)
26         1.3.10. radius_config (string)
27         1.3.11. service_type (integer)
28         1.3.12. radius_flag (integer)
29         1.3.13. radius_missed_flag (integer)
30         1.3.14. db_url (string)
31         1.3.15. db_flag (integer)
32         1.3.16. db_missed_flag (integer)
33         1.3.17. diameter_flag (integer)
34         1.3.18. diameter_missed_flag (integer)
35         1.3.19. diameter_client_host (string)
36         1.3.20. diameter_client_port (int)
37
38    1.4. Functions
39
40         1.4.1. acc_log_request(comment)
41         1.4.2. acc_db_request(comment, table)
42         1.4.3. acc_rad_request(comment)
43         1.4.4. acc_diam_request(comment)
44
45 1.1. Overview
46
47    acc module is used to report on transactions to syslog, SQL and RADIUS.
48
49    To report on a transaction using syslog, use "setflag" to mark a
50    transaction you are interested in with a flag, load accounting module
51    and set its "log_flag" to the same flag number. The acc module will
52    then report on completed transaction to syslog. A typical usage of the
53    module takes no acc-specific script command -- the functionality binds
54    invisibly through transaction processing. Script writers just need to
55    mark the transaction for accounting with proper setflag.
56
57    What is printed depends on module's "log_fmt" parameter. It's a string
58    with characters specifying which parts of request should be printed:
59      * c = Call-Id
60      * d = To tag (Dst)
61      * f = From
62      * i = Inbound Request-URI
63      * m = Method
64      * o = Outbound Request-URI
65      * r = fRom
66      * s = Status
67      * t = To
68      * u = digest Username
69      * p = username Part of inbound Request-URI
70
71    If a value is not present in request, "n/a" is accounted instead.
72
73 Note
74
75      * A single INVITE may produce multiple accounting reports -- that's
76        due to SIP forking feature
77      * Subsequent ACKs and other requests do not hit the server and can't
78        be accounted unless record-routing is enforced. The ACKs assert
79        very little useful information anyway and reporting on INVITE's 200
80        makes most accounting scenarios happy.
81      * There is no session accounting -- ser maintains no sessions. If one
82        needs to correlate INVITEs with BYEs for example for purpose of
83        billing, then it is better done in the entity which collects
84        accounting information. Otherwise, SIP server would have to become
85        sessions-stateful, which would very badly impact its scalability.
86      * If a UA fails in middle of conversation, a proxy will never learn
87        it. In general, a better practice is to account from an end-device
88        (such as PSTN gateway), which best knows about call status
89        (including media status and PSTN status in case of the gateway).
90
91    Support for SQL and RADIUS works analogously. You need to enable it by
92    recompiling the module with properly set defines. Uncomment the SQL_ACC
93    and RAD_ACC lines in modules/acc/Makefile. To compile SQL support, you
94    need to have mysqlclient package on your system. To compile RADIUS
95    support, you need to have radiusclient installed on your system
96    (version 0.5.0 or higher is required) which is available from
97    http://developer.berlios.de/projects/radiusclient-ng/. The radius
98    client needs to be configured properly. To do so, use the template in
99    sip_router/etc/radiusclient.conf and make sure that module's
100    radius_config parameter points to its location. In particular,
101    accounting secret must match that one configured in server and proper
102    dictionary is used (one is available in ). Uses along with FreeRADIUS
103    and Radiator servers have been reported to us.
104
105    Both mysql and radius libraries must be dynamically linkable. You need
106    to configure your OS so that SER, when started, will find them.
107    Typically, you do so by manipulating LD_LIBRARY_PATH environment
108    variable or configuring ld.so.
109
110    Example 1. General Example
111 loadmodule "modules/acc/acc.so"
112 modparam("acc", "log_level", 1)
113 modparam("acc", "log_flag", 1)
114
115 if (uri=~"sip:+49") /* calls to Germany */ {
116     if (!proxy_authorize("iptel.org" /* realm */,
117                          "subscriber" /* table name */))  {
118         proxy_challenge("iptel.org" /* realm */, "0" /* no qop */ );
119         break;
120     }
121
122     if (method=="INVITE" & !check_from()) {
123         log("from!=digest\n");
124         sl_send_reply("403","Forbidden");
125         break;
126     }
127
128     setflag(1); /* set for accounting (the same value as in log_flag!)
129     t_relay();  /* enter stateful mode now */
130 };
131
132 1.2. Dependencies
133
134    The module depends on the following modules (in the other words the
135    listed modules must be loaded before this module):
136      * tm. Transaction Manager
137      * A database module (mysql,postgres,dbtext). If compiled with
138        database support.
139
140 1.3. Parameters
141
142    Revision History
143    Revision $Revision$ $Date$
144
145 1.3.1. secret (string)
146
147    The secret string used to generate nonce. Inclusion of this string in
148    nonce ensures that only the proxy server that knows the secret string
149    will be able to generate the nonce and verify it later when received
150    from the user agent.
151
152    Default value is randomly generated string.
153
154    Example 2. Setting secret module parameter
155 modparam("auth", "secret", "johndoessecretphrase")
156
157 1.3.2. log_level (integer)
158
159    Log level at which accounting messages are issued to syslog.
160
161    Default value is L_NOTICE.
162
163    Example 3. log_level example
164 modparam("acc", "log_level", 2)   # Set log_level to 2
165
166 1.3.3. log_fmt (string)
167
168    Defines what parts of header fields will be printed to syslog, see
169    "overview" for list of accepted values.
170
171    Default value is "miocfs".
172
173    Example 4. log_fmt example
174 modparam("acc", "log_fmt", "mfs")
175
176 1.3.4. early_media (integer)
177
178    Should be early media (183) accounted too ?
179
180    Default value is 0 (no).
181
182    Example 5. early_media example
183 modparam("acc", "early_media", 1)
184
185 1.3.5. failed_transactions (integer)
186
187    This parameter controls whether failed transactions (with final reply
188    >= 300) should be accounted too.
189
190    Default value is 0 (no).
191
192    Example 6. failed_transactions example
193 modparam("acc", "failed_transactions", 1)
194
195 1.3.6. log_flag (integer)
196
197    Request flag which needs to be set to account a transaction.
198
199    Default value is 1.
200
201    Example 7. log_flag example
202 modparam("acc", "log_flag", 2)
203
204 1.3.7. log_missed_flag (integer)
205
206    Request flag which needs to be set to account missed calls.
207
208    Default value is 2.
209
210    Example 8. log_missed_flag example
211 modparam("acc", "log_missed_flag", 3)
212
213 1.3.8. report_ack (integer)
214
215    Shall acc attempt to account e2e ACKs too ? Note that this is really
216    only an attempt, as e2e ACKs may take a different path (unless RR
217    enabled) and mismatch original INVITE (e2e ACKs are a separate
218    transaction).
219
220    Default value is 1 (yes).
221
222    Example 9. report_ack example
223 modparam("acc", "report_ack", 0)
224
225 1.3.9. report_cancels (integer)
226
227    By default, CANCEL reporting is disabled -- most accounting
228    applications are happy to see INVITE's cancellation status. Turn on if
229    you explicitly want to account CANCEL transactions.
230
231    Default value is 0 (no).
232
233    Example 10. report_cancels example
234 modparam("acc", "report_cancels", 1)
235
236 1.3.10. radius_config (string)
237
238    This parameter is radius specific. Path to radius client configuration
239    file, set the referred config file correctly and specify there address
240    of server, shared secret (should equal that in
241    /usr/local/etc/raddb/clients for freeRadius servers) and dictionary,
242    see etc for an example of config file and dictionary.
243
244    Default value is "/usr/local/etc/radiusclient/radiusclient.conf".
245
246    Example 11. radius_config example
247 modparam("acc", "radius_config", "/etc/radiusclient/radiusclient.conf")
248
249 1.3.11. service_type (integer)
250
251    Radius service type used for accounting.
252
253    Default value is 15 (SIP).
254
255    Example 12. service_type example
256 modparam("acc", "service_type", 16)
257
258 1.3.12. radius_flag (integer)
259
260    Request flag which needs to be set to account a transaction -- RADIUS
261    specific.
262
263    Default value is 1.
264
265    Example 13. radius_flag example
266                 modparam("acc", "radius_flag", 2)
267
268 1.3.13. radius_missed_flag (integer)
269
270    Request flag which needs to be set to account missed calls -- RADIUS
271    specific.
272
273    Default value is 2.
274
275    Example 14. radius_missed_flag example
276 modparam("acc", "radius_missed_flag", 3)
277
278 1.3.14. db_url (string)
279
280    SQL address -- database specific.
281
282    Default value is "mysql://ser:heslo@localhost/ser"
283
284    Example 15. db_url example
285 modparam("acc", "db_url", "mysql://user:password@localhost/ser")
286
287 1.3.15. db_flag (integer)
288
289    Request flag which needs to be set to account a transaction -- database
290    specific.
291
292    Default value is 1.
293
294    Example 16. db_flag example
295 modparam("acc", "db_flag", 2)
296
297 1.3.16. db_missed_flag (integer)
298
299    Request flag which needs to be set to account missed calls -- database
300    specific.
301
302    Default value is 2.
303
304    Example 17. db_missed_flag example
305 modparam("acc", "db_missed_flag", 3)
306
307 1.3.17. diameter_flag (integer)
308
309    Request flag which needs to be set to account a transaction -- DIAMETER
310    specific.
311
312    Default value is 1.
313
314    Example 18. diameter_flag example
315 modparam("acc", "diameter_flag", 2)
316
317 1.3.18. diameter_missed_flag (integer)
318
319    Request flag which needs to be set to account missed calls -- DIAMETER
320    specific.
321
322    Default value is 2.
323
324    Example 19. diameter_missed_flag example
325 modparam("acc", "diameter_missed_flag", 3)
326
327 1.3.19. diameter_client_host (string)
328
329    Hostname of the machine where the DIAMETER Client is running --
330    DIAMETER specific.
331
332    Default value is "localhost".
333
334    Example 20. diameter_client_host example
335 modparam("acc", "diameter_client_host", "iptel.org")
336
337 1.3.20. diameter_client_port (int)
338
339    Port number where the Diameter Client is listening -- DIAMETER
340    specific.
341
342    Default value is 3000.
343
344    Example 21. diameter_client_host example
345 modparam("acc", "diameter_client_port", 3000)
346
347 1.4. Functions
348
349    Revision History
350    Revision $Revision$ $Date$
351
352 1.4.1. acc_log_request(comment)
353
354    acc_request reports on a request, for example, it can be used to report
355    on missed calls to off-line users who are replied 404. To avoid
356    multiple reports on UDP request retransmission, you would need to embed
357    the action in stateful processing.
358
359    Meaning of the parameters is as follows:
360      * comment - Comment to be appended.
361
362    Example 22. acc_log_request usage
363 ...
364 acc_log_request("Some comment");
365 ...
366
367 1.4.2. acc_db_request(comment, table)
368
369    Like acc_log_request, acc_db_request reports on a request. The report
370    is sent to database at "db_url", in the table referred to in the second
371    action parameter
372
373    Meaning of the parameters is as follows:
374      * comment - Comment to be appended.
375      * table - Database table to be used.
376
377    Example 23. acc_db_request usage
378 ...
379 acc_log_request("Some comment", "Some table");
380 ...
381
382 1.4.3. acc_rad_request(comment)
383
384    Like acc_log_request, acc_rad_request reports on a request. It reports
385    to radius server as configured in "radius_config".
386
387    Meaning of the parameters is as follows:
388      * comment - Comment to be appended.
389
390    Example 24. acc_rad_request usage
391 ...
392 acc_rad_request("Some comment");
393 ...
394
395 1.4.4. acc_diam_request(comment)
396
397    Like acc_log_request, acc_diam_request reports on a request. It reports
398    to Diameter server.
399
400    Meaning of the parameters is as follows:
401      * comment - Comment to be appended.
402
403    Example 25. acc_diam_request usage
404 ...
405 acc_diam_request("Some comment");
406 ...