Ceci est le manuel Français pour GNU Gatekeeper 2.2.1 (partially updated for 2.3.2).
Une version plus récente (Anglais) du manuel se trouve dans l'archive téléchargée de GnuGk.

Chapitres: Contenu · Introduction · Installation · Pour commencer · Config basique · Routage · Config RAS · Authentification · Accounting · Voisins · Config par terminal · Config avancée · Surveillance

8. Accounting Configuration

The following sections in the config file can be used to configure accounting.

8.1 Section [Gatekeeper::Acct]

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 [Gatekeeper::Auth]).

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

Syntax:

acctmod=actions

 <acctmod> := FileAcct | RadAcct | SQLAcct | ...
 <actions> := <control>[;<event>,<event>,...]
 <control> := optional | required | sufficient | alternative
 <event>   := start | stop | connect | update | on | off

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):
  • start - a call has been started and a Setup message has been received (only available in routed mode),
  • connect - a call has been connected (only available in routed mode),
  • update - a call is active and the periodic update is performed to reflect the new call duration. Frequency of such updates is determined by AcctUpdateInterval variable from [CallTable] section,
  • stop - a call has been disconnected (removed from the GK call table),
  • on - the gatekeeper has been started,
  • off - the gatekeeper has been shut down.
An event logging by a module may results in one of the three result codes: ok, fail, next.
  • ok - the event has been logged successfully by this module,
  • fail - the module failed to log the event,
  • next - the event has not been logged by this module, because the module is not configured for/does not support this event type.
Accounting modules can be stacked to log events by multiple modules or to create failover setups. 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 failure, some special actions may take place. Currently, if a call start event logging fails, the call is disconnected immediatelly. The following control flags are recognized:
  • 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,
  • 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,
  • 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,
  • 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.

Currently supported accounting modules:

  • FileAcct

    A plain CDR text file logger. It outputs status line like CDR lines to a specified text file. This module supports only stop accounting event. Configuration settings are read from [FileAcct] section.

  • RadAcct

    This module performs RADIUS accounting. It supports all event types (start, stop, update, on, off). See the section [RadAcct] for configuration details.

  • SQLAcct

    This module performs direct SQL accounting. It supports (start, stop, update) event types. See the section [SQLAcct] for configuration details.

  • default

    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:

    Syntax:

     default=<status>[;<event>,<event>,...]
 <status> := accept | fail
 <event>  := start | stop | update | on | off

The sample configuration #1 (try to log call start/stop with RADIUS server, and always write a CDR to a text file):

Example:

RadAcct=optional;start,stop
FileAcct=required

The sample configuration #2 (try to log call start/stop with RADIUS server, if it fails use a CDR log file):

Example:

RadAcct=alternative;start,stop
FileAcct=sufficient;stop
default=accept

The default rule is required here to prevent calls from being rejected because of RadAcct start event logging failure. If RadAcct returns fail return code, it is passed down to FileAcct module. FileAcct module does not support start events, so it returns next return code. If there were no the 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):

Example:

RadAcct=alternative;start,stop
FileAcct=sufficient;stop
default=fail;start

The default rule is optional here. If RadAcct returns fail return code for start event, the code is passed down to FileAcct module. FileAcct module does not support start events, so it returns next return code. The 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.

8.2 Section [FileAcct]

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).

  • DetailFile=FULL_PATH_AND_FILENAME
    Default: N/A

    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.

  • StandardCDRFormat=0
    Default: 1

    Use a CDR format compatible with the status interface CDR format (1) or build a custom CDR strings from the CDRString parametrized string.

  • CDRString=%s|%g|%u|%{Calling-Station-Id}|%{Called-Station-Id}|%d|%c
    Default: N/A

    If 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 % character and can be one letter (like %n) or longer (like %{CallId}). Any remaining characters that are not parameter names are simply copied to a final CDR string. The following parameters are recognized:

    • %g - gatekeeper name
    • %n - call number (not unique after gatekeeper restart)
    • %d - call duration (seconds)
    • %c - Q.931 disconnect cause (decimal integer)
    • %s - unique (for this gatekeeper) session identifier (Acct-Session-Id)
    • %u - H.323 ID of the calling party
    • %{CallId} - H.323 call identifier (16 hex 8-bit digits)
    • %{ConfId} - H.323 conference identifier (16 hex 8-bit digits)
    • %{setup-time} - timestamp string for Q.931 Setup message
    • %{connect-time} - timestamp string for a call connected event
    • %{disconnect-time} - timestamp string for a call disconnect event
    • %{caller-ip} - signaling IP addres of the caller
    • %{caller-port} - signaling port of the caller
    • %{callee-ip} - signaling IP addres of the called party
    • %{callee-port} - signaling port of the called party
    • %{src-info} - a colon separated list of source aliases
    • %{dest-info} - a colon separated list of destination aliases
    • %{Calling-Station-Id} - calling party number
    • %{Called-Station-Id} - called party number (rewritten)
    • %{Dialed-Number} - dialed number (as received from the calling party)

  • TimestampFormat=Cisco
    Default: N/A

    Format of timestamp strings printed in CDR strings. If this setting is not specified, a global one from the main gatekeeper section is applied.

  • Rotate=hourly | daily | weekly | monthly | L... | S...
    Default: N/A

    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.
    In addition, rotation per number of CDRs written (L...) and per file size (S...) is supported. The L prefix specifies a number of CDR lines written, the S prefix specifies CDR file size. k and m suffixes can be used to speficy throusands (kilobytes) and millions (megabytes). See the examples for more details.

    Example 1 - no rotation:

    [FileAcct]
    DetailFile=/var/log/gk/cdr.log

    Example 2 - rotate every hour (00:45, 01:45, ..., 23:45):

    [FileAcct]
    DetailFile=/var/log/gk/cdr.log
    Rotate=hourly
    RotateTime=45

    Example 3 - rotate every day at 23:00 (11PM):

    [FileAcct]
    DetailFile=/var/log/gk/cdr.log
    Rotate=daily
    RotateTime=23:00

    Example 4 - rotate every Sunday at 00:59:

    [FileAcct]
    DetailFile=/var/log/gk/cdr.log
    Rotate=weekly
    RotateDay=Sun
    RotateTime=00:59

    Example 5 - rotate on the last day of each month:

    [FileAcct]
    DetailFile=/var/log/gk/cdr.log
    Rotate=monthly
    RotateDay=31
    RotateTime=23:00

    Example 6 - rotate per every 10000 CDRs:

    [FileAcct]
    DetailFile=/var/log/gk/cdr.log
    Rotate=L10000

    Example 7 - rotate per every 10 kilobytes:

    [FileAcct]
    DetailFile=/var/log/gk/cdr.log
    Rotate=S10k

8.3 Section [RadAcct]

This accounting module sends accounting data to a RADIUS server. Module configuration is almost the same as for RADIUS authenticators (see [RadAuth] and [RadAliasAuth] for more details on the parameters).

  • Servers=SERVER1[:AUTH_PORT:ACCT_PORT[:SECRET]];SERVER2[:AUTH_PORT:ACCT_PORT[:SECRET]];...
    Default: N/A

    RADIUS servers to send accounting data to. If no port information is given, port number from DefaultAcctPort is be used. If no secret is set, the default shared secret from SharedSecret is used. Server names could be either IP addresses or DNS names.

    Sample Servers lines:

    Servers=192.168.1.1
    Servers=192.168.1.1:1645:1646
    Servers=192.168.1.1:1645:1646:secret1
    Servers=radius1.mycompany.com:1812:1813
    Servers=radius1.mycompany.com;radius2.mycompany.com
    Servers=radius1.mycompany.com:1812:1813:secret1;radius2.mycompany.com:1812:1813:secret2

  • LocalInterface=IP_OR_FQDN
    Default: N/A

    Particular local network interface that RADIUS client should use in order to communicate with RADIUS servers.

  • RadiusPortRange=10000-11000
    Default: N/A

    By default (if this option is not set) RADIUS client allocates ports dynamically as specified by the operating system. If you want to restrict RADIUS client to use ports from a particular range only - set this parameter.

  • DefaultAcctPort=PORT_NO
    Default: 1813

    Default port number to be used for RADIUS accounting requests, if not overriden by Servers attribute.

  • SharedSecret=SECRET
    Default: N/A (empty string)

    A secret used to authenticate this GnuGk (NAS client) to RADIUS server. It should be a cryptographically strong password. This is the default value used, if no server-specific secret is set in the Servers. If EncryptAllPasswords is enabled, or a KeyFilled variable is defined in this section, the password is in encrypted form and should be created using the addpasswd utility.

  • RequestTimeout=TIMEOUT_MS
    Default: 2000 (miliseconds)

    Timeout (miliseconds) for RADIUS server response to a request sent by GnuGk. If no response is received within this time period, next RADIUS server is queried.

  • IdCacheTimeout=TIMEOUT_MS
    Default: 9000 (miliseconds)

    Timeout (miliseconds) for RADIUS request 8-bit identifiers to be unique.

  • SocketDeleteTimeout=TIMEOUT_MS
    Default: 60000 (miliseconds) - 60 s

    Timeout for unused RADIUS sockets to be closed.

  • RequestRetransmissions=NUMBER
    Default: 2

    How many times a single RADIUS request is transmissed to every configured RADIUS server (if no response is received).

  • RoundRobinServers=BOOLEAN
    Default: 1

    RADIUS requests retransmission method.

  • AppendCiscoAttributes=BOOLEAN
    Default: 0

    If set, Cisco Vendor Specific RADIUS attibutes are included in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).

  • TimestampFormat=ISO8601
    Default: N/A

    Format of timestamp strings sent in RADIUS attributes. If this setting is not specified, a global one from the main gatekeeper section is applied.

  • UseDialedNumber=BOOLEAN
    Default: 0

    Select Called-Station-Id number type between the original one (as dialed by the user) - UseDialedNumber=1 - and the rewritten one - UseDialedNumber=0.

8.4 Section [SQLAcct]

This accounting module stores accounting information directly to an SQL database. Many configuration settings are common with other SQL modules.

  • Driver=MySQL | PostgreSQL
    Default: N/A

    SQL database driver to use. Currently, MySQL and PostgreSQL drivers are implemented.

  • Host=DNS[:PORT] | IP[:PORT]
    Default: localhost

    SQL server host address. Can be in the form of DNS[:PORT] or IP[:PORT]. Like sql.mycompany.com or sql.mycompany.com:3306 or 192.168.3.100.

  • Database=billing
    Default: billing

    The database name to connect to.

  • Username=gnugk

    The username used to connect to the database.

  • Password=secret

    The password used to connect to the database. If the password is not specified, a database connection attempt without any password will be made. If EncryptAllPasswords is enabled, or a KeyFilled variable is defined in this section, the password is in an encrypted form and should be created using the addpasswd utility.

  • StartQuery=INSERT ...
    Default: N/A

    Defines SQL query used to insert a new call record to the database. The query is parametrized - that means parameter replacement is made before each query is executed. Parameter placeholders are denoted by % character and can be one letter (like %u) or whole strings (like %{src-info}). Specify %% to embed a percent character inside the query string (like %%). For SQLAcct the following parameters are defined:

    • %g - gatekeeper name
    • %n - call number (not unique after gatekeeper restart)
    • %d - call duration (seconds)
    • %c - Q.931 disconnect cause (hexadecimal integer)
    • %s - unique (for this gatekeeper) call (Acct-Session-Id)
    • %u - H.323 ID of the calling party
    • %{gkip} - IP address of the gatekeeper
    • %{CallId} - H.323 call identifier (16 hex 8-bit digits)
    • %{ConfId} - H.323 conference identifier (16 hex 8-bit digits)
    • %{setup-time} - timestamp string for Q.931 Setup message
    • %{connect-time} - timestamp string for a call connected event
    • %{disconnect-time} - timestamp string for a call disconnect event
    • %{caller-ip} - signaling IP addres of the caller
    • %{caller-port} - signaling port of the caller
    • %{callee-ip} - signaling IP addres of the called party
    • %{callee-port} - signaling port of the called party
    • %{src-info} - a colon separated list of source aliases
    • %{dest-info} - a colon separated list of destination aliases
    • %{Calling-Station-Id} - calling party number
    • %{Called-Station-Id} - called party number (rewritten Dialed-Number)
    • %{Dialed-Number} - dialed number (as received from the calling party)

    Sample query string: 

    INSERT INTO call (gkname, sessid, username, calling, called) 
        VALUES ('%g', '%s', '%u', '%{Calling-Station-Id}', '%{Called-Station-Id}')

  • StartQueryAlt=INSERT ...
    Default: N/A

    Defines SQL query used to insert a new call record to the database in case the StartQuery failed for some reason (the call already exists, for example). The syntax and parameters are the same as for StartQuery.

  • UpdateQuery=UPDATE ...
    Default: N/A

    Defines SQL query used to update call record in the database with the current call state. The syntax and parameters are the same as for StartQuery.

    Sample query string: 

    UPDATE call SET duration = %d WHERE gkname = '%g' AND sessid = '%s'

  • StopQuery=UPDATE ...
    Default: N/A

    Defines SQL query used to update call record in the database when the call is finished (disconnected). The syntax and parameters are the same as for StartQuery.

    Sample query string: 

    UPDATE call SET duration = %d, dtime = '%{disconnect-time}' WHERE gkname = '%g' AND sessid = '%s'

  • StopQueryAlt=INSERT ...
    Default: N/A

    Defines SQL query used to update call record in the database when the call is finished (disconnected) in case the regular StopQuery failed (because the call record does not yet exist, for example). The syntax and parameters are the same as for StartQuery.

    Sample query string: 

    INSERT INTO call (gkname, sessid, username, calling, called, duration) 
        VALUES ('%g', '%s', '%u', '%{Calling-Station-Id}', '%{Called-Station-Id}', %d)

  • TimestampFormat=MySQL
    Default: N/A

    Format of timestamp strings used in queries. If this setting is not specified, a global one from the main gatekeeper section is applied.

Page suivante Page précédente Table des matières

Chapitres: Contenu · Introduction · Installation · Pour commencer · Config basique · Routage · Config RAS · Authentification · Accounting · Voisins · Config par terminal · Config avancée · Surveillance


Last updated: 21. Jan 2025