acct.sgml

gnugk软交换产品

<sect>Accounting Configuration
<p>
The following sections in the config file can be used to configure accounting.

<sect1>Section &lsqb;Gatekeeper::Acct&rsqb;
<label id="gkacct">
<p>
The section defines a list of modules that will be performing accounting.
The accounting is for logging gatekeeper on/off events and call start/stop/update
events. Each accounting module logs received events to a module specific storage.
Such storage can be a plain text file or a RADIUS server and many
more. The configuration is very similar to the one for gatekeeper authentication
(see <ref id="gkauth" name="[Gatekeeper::Auth]">).


All CDRs are also sent to the status port and can be used by external applications.

<descrip>
<tag/Syntax:/
<tscreen><verb>
acctmod=actions

 <acctmod> := FileAcct | RadAcct | SQLAcct | ...
 <actions> := <control>[;<event>,<event>,...]
 <control> := optional | required | sufficient | alternative
 <event>   := start | stop | connect | update | on | off
</verb></tscreen>
</descrip>
The event list tells the gatekeeper, which events should trigger logging
with the given accounting module (if an event type is supported by the module):
<itemize>
<item><tt/start/ - a call has been started and a Setup message has been received (only available in routed mode),
<item><tt/connect/ - a call has been connected (only available in routed mode),
<item><tt/update/ - a call is active and the periodic update is performed
	to reflect the new call duration. Frequency of such updates is determined
	by <bf/AcctUpdateInterval/ variable from <ref id="calltable" name="[CallTable]">
	section,
<item><tt/stop/ - a call has been disconnected (removed from the GK call table),
<item><tt/on/ - the gatekeeper has been started,
<item><tt/off/ - the gatekeeper has been shut down.
</itemize>
An event logging by a module may results in one of the three result codes:
<bf/ok/, <bf/fail/, <bf/next/.
<itemize>
<item><tt/ok/ - the event has been logged successfully by this module,
<item><tt/fail/ - the module failed to log the event,
<item><tt/next/ - the event has not been logged by this module, because the module
  is not configured for/does not support this event type.
</itemize>
Accounting modules can be stacked to log events by multiple modules or to create
failover setups. <bf/control/ flag for each module, along with result codes,
define what is the final status of the event processing by the whole module stack.
If the final result is <bf/failure/, some special actions may take place. Currently,
if a call <bf/start/ event logging fails, the call is disconnected immediatelly.
The following <bf/control/ flags are recognized:
<itemize>
<item><tt/required/ - if the module fails to log an event, the final status
                      is set to failure and the event is passed down to any remaining
					  modules,
<item><tt/optional/ - the module tries to log an event, but the final status
                      is not affected by success or failure (except when the module
					  is last on the list). The event is always passed down
					  to any remaining modules,
<item><tt/sufficient/ - the module determines the final status. If an event
                        is logged successfully, no remaining modules are processed.
						Otherwise the final status is set to failure and the event
						is passed down to any remaining modules,
<item><tt/alternative/ - if the module logs an event successfully, no remaining
                         modules are processed. Otherwise the final status is
						 not modified and the event is passed down to any remaining
						 modules.
</itemize>

Currently supported accounting modules:
<itemize>
<item><tt>FileAcct</tt>
<p>
A plain CDR text file logger. It outputs status line like CDR lines to
a specified text file. This module supports only <bf/stop/ accounting event.
Configuration settings are read from <ref id="fileacct" name="[FileAcct]"> section.

<item><tt>RadAcct</tt>
<p>
This module performs RADIUS accounting. It supports all event types
(start, stop, update, on, off).
See the section <ref id="radacct" name="[RadAcct]"> for configuration details.

<item><tt>SQLAcct</tt>
<p>
This module performs direct SQL accounting. It supports (start, stop, update)
event types. 
See the section <ref id="sqlacct" name="[SQLAcct]"> for configuration details.

<item><tt>default</tt>
<p>
This is a special pseudo module - it is used to set the final status
if preceeding modules have not determined it. The format is as follows:
<descrip>
<tag/Syntax:/
<tscreen><verb>
 default=<status>[;<event>,<event>,...]
 <status> := accept | fail
 <event>  := start | stop | update | on | off
</verb></tscreen>
</descrip>

</itemize>

The sample configuration #1 (try to log call start/stop with RADIUS server,
and always write a CDR to a text file):
<descrip>
<tag/Example:/
<tt/RadAcct=optional;start,stop/<newline>
<tt/FileAcct=required/<newline>
</descrip>

The sample configuration #2 (try to log call start/stop with RADIUS server,
if it fails use a CDR log file):
<descrip>
<tag/Example:/
<tt/RadAcct=alternative;start,stop/<newline>
<tt/FileAcct=sufficient;stop/<newline>
<tt/default=accept/<newline>
</descrip>
The <bf/default/ rule is required here to prevent calls from being rejected
because of RadAcct start event logging failure. If RadAcct returns <bf/fail/
return code, it is passed down to FileAcct module. FileAcct module does not
support <bf/start/ events, so it returns <bf/next/ return code. If there were
no the <bf/default/ rule, the final status would be failure, because no module
has been able to log the event.

The sample configuration #3 (always log call start and stop events with RADIUS
server, if it fails for call stop event, use a CDR file to store call info):
<descrip>
<tag/Example:/
<tt/RadAcct=alternative;start,stop/<newline>
<tt/FileAcct=sufficient;stop/<newline>
<tt/default=fail;start/<newline>
</descrip>
The <bf/default/ rule is optional here. If RadAcct returns <bf/fail/
return code for <bf/start/ event, the code is passed down to FileAcct module.
FileAcct module does not support <bf/start/ events, so it returns <bf/next/
return code. The <bf/default/ rule ensures, that the call is disconnected
if call start event could not has been logged with RadAcct. But we want
to store a CDR in a text file in case the RADIUS server is down when the call
disconnects, so we can fetch call duration into a billing system later.

<sect1>Section &lsqb;FileAcct&rsqb;
<label id="fileacct">
<p>
This accounting module writes CDR lines to a specified text file. The CDR
format can be a standard one (the same as displayed by the status interface)
or a customized one (using parametrized query string).

<itemize>
<item>
<tt/DetailFile=FULL_PATH_AND_FILENAME/<newline>
Default: N/A
<p>
A full path to the CDR plain text file. If a file with the given name already 
exists, new CDRs will be appended at the end of the file.

<item>
<tt/StandardCDRFormat=0/<newline>
Default: <tt/1/
<p>
Use a CDR format compatible with the status interface CDR format (<tt/1/)
or build a custom CDR strings from the <bf/CDRString/ parametrized string.

<item>
<tt/CDRString=%s|%g|%u|%{Calling-Station-Id}|%{Called-Station-Id}|%d|%c/<newline>
Default: N/A
<p>
If <bf/StandardCDRFormat/ is disabled (0) or not specified at all, 
this paramterized string instructs the gatekeeper how to build a custom
CDRs. Parameters are specified using <tt/%/ character and can be one letter
(like <tt/%n/) or longer (like <tt/%{CallId}/). Any remaining characters that
are not parameter names are simply copied to a final CDR string. The following
parameters are recognized:
<itemize>
<item><tt/%g/ - gatekeeper name
<item><tt/%n/ - call number (not unique after gatekeeper restart)
<item><tt/%d/ - call duration (seconds)
<item><tt/%c/ - Q.931 disconnect cause (decimal integer)
<item><tt/%s/ - unique (for this gatekeeper) session identifier (Acct-Session-Id)
<item><tt/%u/ - H.323 ID of the calling party
<item><tt/%{CallId}/ - H.323 call identifier (16 hex 8-bit digits)
<item><tt/%{ConfId}/ - H.323 conference identifier (16 hex 8-bit digits)
<item><tt/%{setup-time}/ - timestamp string for Q.931 Setup message
<item><tt/%{connect-time}/ - timestamp string for a call connected event
<item><tt/%{disconnect-time}/ - timestamp string for a call disconnect event
<item><tt/%{caller-ip}/ - signaling IP addres of the caller
<item><tt/%{caller-port}/ - signaling port of the caller
<item><tt/%{callee-ip}/ - signaling IP addres of the called party
<item><tt/%{callee-port}/ - signaling port of the called party
<item><tt/%{src-info}/ - a colon separated list of source aliases
<item><tt/%{dest-info}/ - a colon separated list of destination aliases
<item><tt/%{Calling-Station-Id}/ - calling party number
<item><tt/%{Called-Station-Id}/ - called party number (rewritten)
<item><tt/%{Dialed-Number}/ - dialed number (as received from the calling party)
</itemize><newline>

<item><tt/TimestampFormat=Cisco/<newline>
Default: <tt>N/A</tt>
<p>
Format of timestamp strings printed in CDR strings. If this setting
is not specified, a global one from the main gatekeeper section is applied.

<item>
<tt/Rotate=hourly | daily | weekly | monthly | L... | S.../<newline>
Default: N/A
<p>
If set, the CDR file will be rotated based on this setting. Hourly rotation
enables rotation once per hour, daily - once per day, weekly - once per week
and monthly - once per month. An exact rotation moment is determined by a combination
of RotateDay and RotateTime. During rotation, an existing file is renamed 
to CURRENT_FILENAME.YYYYMMDD-HHMMSS, where YYYYMMDD-HHMMSS is replaced with 
the current timestamp, and new CDRs are logged to an empty file.<newline>
In addition, rotation per number of CDRs written (L...) and per file size (S...)
is supported. The <tt/L/ prefix specifies a number of CDR lines written,
the <tt/S/ prefix specifies CDR file size. <tt/k/ and <tt/m/ suffixes can
be used to speficy throusands (kilobytes) and millions (megabytes). 
See the examples for more details.

<descrip>
<tag/Example 1 - no rotation:/
<tt/&lsqb;FileAcct&rsqb;/<newline>
<tt>DetailFile=/var/log/gk/cdr.log</tt><newline>
</descrip>

<descrip>
<tag/Example 2 - rotate every hour (00:45, 01:45, ..., 23:45):/
<tt/&lsqb;FileAcct&rsqb;/<newline>
<tt>DetailFile=/var/log/gk/cdr.log</tt><newline>
<tt>Rotate=hourly</tt><newline>
<tt>RotateTime=45</tt><newline>
</descrip>

<descrip>
<tag/Example 3 - rotate every day at 23:00 (11PM):/
<tt/&lsqb;FileAcct&rsqb;/<newline>
<tt>DetailFile=/var/log/gk/cdr.log</tt><newline>
<tt>Rotate=daily</tt><newline>
<tt>RotateTime=23:00</tt><newline>
</descrip>

<descrip>
<tag/Example 4 - rotate every Sunday at 00:59:/
<tt/&lsqb;FileAcct&rsqb;/<newline>
<tt>DetailFile=/var/log/gk/cdr.log</tt><newline>
<tt>Rotate=weekly</tt><newline>
<tt>RotateDay=Sun</tt><newline>
<tt>RotateTime=00:59</tt><newline>
</descrip>

<descrip>
<tag/Example 5 - rotate on the last day of each month:/
<tt/&lsqb;FileAcct&rsqb;/<newline>