This is the manual for GNU Gatekeeper 5.14.
A manual for your version is in your GnuGk download archive.
A PDF version can be found in the download section.

Chapters: Contents · Introduction · Installation · Getting started · Basic Config · Routed Mode & Proxy · Routing · RAS Config · Authentication · Accounting · Neighbors · Per Endpoint Config · Advanced Config · Monitoring · Advanced Topics

Download GnuGk    Get support

The GNU Gatekeeper Manual Chapter 9

9. Accounting Configuration

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

9.1 Section [Gatekeeper::Acct]

This section defines a list of modules which may be used to perform accounting. The accounting function can be used for logging gatekeeper on/off events and call start/stop/update events. Each accounting module logs received events to module-specific storage. The various storage options include plain text file, 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 | HttpAcct | AMQPAcct | MQTTAcct | StatusAcct | SyslogAcct | LuaAcct | RequireOneNet | CapacityControl | ...
 <actions> := <control>[;<event>,<event>,...]
 <control> := optional | required | sufficient | alternative
 <event>   := start | stop | alert | connect | update | register | unregister | on | off | reject | mediafail

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)
  • alert - a call is alerting (only available in routed mode)
  • connect - a call has been connected (only available in routed mode)
  • update - a call is active and a periodic update is performed to reflect the new call duration. The frequency of these updates is determined by the AcctUpdateInterval variable from the [CallTable] section
  • register - an endpoint has registered
  • unregister - an endpoint has unregistered
  • stop - a call has been disconnected (removed from the gatekeeper call table)
  • reject - a call has been rejected (ARJ) before becoming a true call in GnuGk's terms
  • mediafail - port detection in a channel of this has failed
  • on - the gatekeeper has been started
  • off - the gatekeeper has been shut down
An event logged by a module may results in one of 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. The control flag for each module, along with result codes, define what is the final status of the event processing by the entire 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 immediately. 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 Call Detail Report ("CDR") text file logger. It outputs CDR status data to a specified text file. This module only supports the stop accounting event. Configuration settings are read from [FileAcct] section.

  • RadAcct

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

  • SQLAcct

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

  • HttpAcct

    This module logs all accounting events over HTTP. It supports (start, connect, stop, update, alert, reject, register, unregister, on, off) See section [HttpAcct] for configuration details.

  • AMQPAcct

    This module logs all accounting events to an AMQP queue, eg. RabbitMQ. It supports (start, connect, stop, update, alert, reject, register, unregister, on, off) See section [AMQPAcct] for configuration details.

  • MQTTAcct

    This module logs all accounting events to an MQTT server. It supports (start, connect, stop, update, alert, reject, register, unregister, on, off) See section [MQTTAcct] for configuration details.

  • StatusAcct

    This module logs all accounting events on the status port. It can be used to interface to external application in real-time. It supports (start, connect, stop, update, alert, register, unregister) event types. See section [StatusAcct] for configuration details.

  • SyslogAcct

    This module logs all accounting events to the Unix syslog. It supports (start, connect, stop, update) event types. See section [SyslogAcct] for configuration details.

  • LuaAcct

    This module runs a LUA script for each accounting event. It supports (start, connect, stop, update, alert, register, unregister) event types. See section [LuaAcct] for configuration details.

  • RequireOneNet

    Logically an authentication method that ensures all calls either start or terminate within one of your own networks. See section [RequireOneNet] for configuration details.

  • CapacityControl

    This module performs inbound call volume logging, required for the CapacityControl authentication module to work correctly. See the section [CapacityControl] for details.

  • default

    This is a special pseudo module - it is used to set the final status if other modules have not determined it. The format is:

    Syntax:

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

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

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 responds with a fail return code, it is passed down to the FileAcct module. The FileAcct module does not support start events, so it returns a next code. If there were no default rule, the final status would be failure, because no module has been able to log the event.

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 a fail code for the start event, the code is passed to the FileAcct module. The FileAcct module does not support start events, so it returns next return code. The default rule ensures that the call is disconnected if the call start event could not be logged with RadAcct. However, we still 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.

9.2 Customizing CDR strings and accounting data

Most accounting modules let you customize the CDR data they store. They use a common set of parameters to define the CDR string.

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 the final CDR string. The following parameters are recognized in all call related accounting events:

  • %g - gatekeeper name
  • %n - call number (not unique after gatekeeper restart)
  • %d - call duration (seconds)
  • %t - total call duration (from Setup to Release Complete)
  • %c - Q.931 disconnect cause (decimal integer) as originally received
  • %{cause-translated} - Q.931 disconnect cause (decimal integer) after translation rules
  • %r - who disconnected the call (-1 - unknown, 0 - the gatekeeper, 1 - the caller, 2 - the callee)
  • %p - PDD (Post Dial Delay) in seconds
  • %s - unique (for this gatekeeper) session identifier (Acct-Session-Id)
  • %u - H.323 ID of the calling party
  • %{event-uuid} - UUID of this event
  • %{event-time} - time when the event is generated
  • %{gkip} - IP address of the gatekeeper
  • %{external-ip} - external IP address of the gatekeeper, if set
  • %{CallId} - H.323 call identifier (16 hex 8-bit digits)
  • %{ConfId} - H.323 conference identifier (16 hex 8-bit digits)
  • %{CallLink} - Linked H.323 conference identifier (billing account for H.450 call transfer)
  • %{setup-time} - timestamp string for Q.931 Setup message
  • %{alerting-time} - timestamp string for Q.931 Alerting message
  • %{connect-time} - timestamp string for a call connected event
  • %{disconnect-time} - timestamp string for a call disconnect event
  • %{ring-time} - time a remote phone was ringing for (from Alerting till Connect or Release Complete)
  • %{caller-ip} - signaling IP address of the caller (only available in routed mode)
  • %{caller-port} - signaling port of the caller (only available in routed mode)
  • %{callee-ip} - signaling IP address of the called party (only available in routed mode)
  • %{callee-port} - signaling port of the called party (only available in routed mode)
  • %{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)
  • %{caller-epid} - endpoint identifier of the calling party
  • %{callee-epid} - endpoint identifier of the called party
  • %{call-attempts} - number of attempts to establish the calls (with failover this can be > 1)
  • %{last-cdr} - is this the last CDR for this call ? (0 / 1) only when using failover this can be 0
  • %{client-auth-id} - a 64 bit integer ID provided to GnuGk when authenticating the call (through SQLAuth)
  • %{caller-vendor} - vendor and version info of the calling endpoint
  • %{callee-vendor} - vendor and version info of the called endpoint
  • %{sinfo-ip} - IP from Sorenson SInfo (only available when TranslateSorensonSourceInfo=1)
  • %{bandwidth} - bandwidth for this call
  • %{bandwidth-kbps} - bandwidth granted to this call (in kbps)
  • %{caller-audio-codec} - audio codec used by the caller for sending
  • %{callee-audio-codec} - audio codec used by the called for sending
  • %{caller-video-codec} - video codec used by the caller for sending
  • %{callee-video-codec} - video codec used by the called for sending
  • %{caller-audio-bitrate} - audio bitrate used by the caller for sending (in kbps)
  • %{callee-audio-bitrate} - audio bitrate used by the called for sending (in kbps)
  • %{caller-video-bitrate} - video bitrate used by the caller for sending (in kbps)
  • %{callee-video-bitrate} - video bitrate used by the called for sending (in kbps)
  • %{caller-media-ip} - media IP (audio) used by the caller
  • %{callee-media-ip} - media IP (audio) used by the called
  • %{encryption} - "On" if all audio and video chanels are encrypted, otherwise "Off"
  • %{env1} - content of environment variable GNUGK_ENV1
  • ...
  • %{env9} - content of environment variable GNUGK_ENV9
  • %{media-oip} - caller's RTP media IP (only for H.245 routed/tunneled calls) DEPRECATED
  • %{codec} - audio codec used during the call (only for H.245 routed/tunneled calls) DEPRECATED
  • %{registrations} - number of endpoints currently registered
  • %{calls} - number of ongoing calls
  • %{total-calls} - total number of calls
  • %{successful-calls} - total number of successful calls
  • %{allocated-bandwidth} - currently allocated-bandwidth for all calls together

For Register and Unregister events you can use the following parameters:

  • %g - gatekeeper name
  • %{gkip} - IP address of the gatekeeper
  • %{external-ip} - external IP address of the gatekeeper, if set
  • %u - H.323 ID of the registering party
  • %{event-uuid} - UUID of this event
  • %{event-time} - time when the event is generated
  • %{endpoint-ip} - IP number of the endpoint
  • %{endpoint-port} - port number of the endpoint
  • %{endpoint-vendor} - vendor and version info of the endpoint
  • %{epid} - the endpoint ID
  • %{aliases} - the comma separated list of aliases the endpoint has registered with
  • %{Calling-Station-Id} - the caaling party number of this endpoint
  • %{env1} - content of environment variable GNUGK_ENV1
  • ...
  • %{env9} - content of environment variable GNUGK_ENV9
  • %{registrations} - number of endpoints currently registered
  • %{calls} - number of ongoing calls
  • %{total-calls} - total number of calls
  • %{successful-calls} - total number of successful calls
  • %{allocated-bandwidth} - currently allocated-bandwidth for all calls together

For On and Off events you can use the following parameters:

  • %g - gatekeeper name
  • %{gkip} - IP address of the gatekeeper
  • %{external-ip} - external IP address of the gatekeeper, if set
  • %{env1} - content of environment variable GNUGK_ENV1
  • ...
  • %{env9} - content of environment variable GNUGK_ENV9

9.3 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 string from the CDRString parametrized string.

    The StandardCDRFormat is equivalent to this definition:

    TimestampFormat=RFC822
    CDRString=CDR|%n|%{CallId}|%d|%{connect-time}|%{disconnect-time}|%{caller-ip}:%{caller-port}|%{caller-epid}|%{callee-ip}:%{callee-port}|%{callee-epid}|%{dest-info}|%{src-info}|%g;

  • 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 parametrized string instructs the gatekeeper on how to build a custom CDR. You can use the common CDR parameters to define what to include into your CDRs.

  • TimestampFormat=Cisco
    Default: N/A

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

  • 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 specify thousands (kilobytes) and millions (megabytes).

    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

9.4 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, a port number from DefaultAcctPort is be used. If no secret is set, the default shared secret from SharedSecret is used. Server names may be specified by IP address or DNS name. IPv6 addresses must always be written in brackets.

    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
    Servers=[2501:4f3:61:2143::2]
    Servers=[2501:4f3:61:2143::2]:1645
    Servers=[2501:4f3:61:2143::2]:1645:1646
    Servers=[2501:4f3:61:2143::2]:1645:1646:secret1
    Servers=[2501:4f3:61:2143::2]:1645:1646:secret1;[2501:4f3:61:2143::3]:1645:1646:secret2

  • LocalInterface=IP_OR_FQDN
    Default: N/A

    Specific local network interface that GnuGk should use in order to communicate with RADIUS servers.

  • RadiusPortRange=10000-11000
    Default: N/A

    By default (if this option is not set) GnuGk allocates ports dynamically as specified by the operating system. In order to restrict the ports which GnuGk will use then configure this parameter appropriately.

  • DefaultAcctPort=PORT_NO
    Default: 1813

    Default port number to be used for RADIUS accounting requests. May be overridden by the Servers attribute.

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

    A secret used to authenticate this GnuGk (NAS client) to a 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 (milliseconds)

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

  • IdCacheTimeout=TIMEOUT_MS
    Default: 9000 (milliseconds)

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

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

    Timeout for unused RADIUS sockets to be closed.

  • RequestRetransmissions=NUMBER
    Default: 2

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

  • RoundRobinServers=BOOLEAN
    Default: 1

    RADIUS requests retransmission method.

    If set to 1, RADIUS request is transmitted in the following way (until response is received): 

    Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions

    If set to 0, the following sequence is preserved: 

    Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions

  • AppendCiscoAttributes=BOOLEAN
    Default: 0

    If set, Cisco Vendor Specific RADIUS attributes 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, the 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.

[RadAcct] Accounting-Request RADIUS Attributes

For an Accounting-Request, the following RADIUS attributes are included within Accounting-Request packets. Each attribute is followed by a list of accounting event types.

  • Acct-Status-Type (start,update,stop,on,off)

    The accounting event type (Start, Interim-Update, Stop, Accounting-On, Accounting-Off).

  • NAS-IP-Address (start,update,stop,on,off)

    An IP address of the gatekeeper.

  • NAS-Identifier (start,update,stop,on,off)

    The gatekeeper identifier (Name= gk parameter).

  • NAS-Port-Type (start,update,stop,on,off)

    Fixed value Virtual.

  • Service-Type (start,update,stop)

    Fixed value Login-User.

  • Acct-Session-Id (start,update,stop)

    A unique accounting session identifier string.

  • User-Name (start,update,stop)

    Calling party's account name.

  • Framed-IP-Address (start,update,stop)

    An IP address for the calling party. Either an endpoint call signaling address or a remote socket address for the signaling channel.

  • Acct-Session-Time (update,stop)

    Call duration (seconds) - for interim-update events this is the actual duration.

  • Calling-Station-Id (start,update,stop)

    Calling party's number.

  • Called-Station-Id (start,update,stop)

    Called party's number.

  • (optional) VSA: VendorId=Cisco, h323-gw-id (start,update,stop)

    The same as NAS-Identifier.

  • (optional) VSA: VendorId=Cisco, h323-conf-id (start,update,stop)

    H.323 Conference ID for the call.

  • (optional) VSA: VendorId=Cisco, h323-call-origin (start,update,stop)

    Fixed string "proxy".

  • (optional) VSA: VendorId=Cisco, h323-call-type (start,update,stop)

    Fixed string "VoIP".

  • (optional) VSA: VendorId=Cisco, h323-setup-time (start,update,stop)

    Timestamp when the Q.931 Setup message has been received by the gk.

  • (optional) VSA: VendorId=Cisco, h323-connect-time (update,stop)

    Timestamp when the call has been connected (Q.931 Setup message has been received or ACF has been sent in direct signaling mode).

  • (optional) VSA: VendorId=Cisco, h323-disconnect-time (stop)

    Timestamp when the call has been disconnected (ReleaseComplete or DRQ has been received).

  • (optional) VSA: VendorId=Cisco, h323-disconnect-cause (stop)

    Q.931 two digit hexadecimal disconnect cause.

  • (optional) VSA: VendorId=Cisco, h323-remote-address (start,update,stop)

    An IP address of the called party (if known).

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-out (start, update, stop)

    h323-call-id variable that contains an H.323 Call Identifier. The syntax is: "h323-ivr-out=h323-call-id:123FDE 12348765 9abc1234 12".

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-out (start, update, stop)

    rewritten-e164-num contains the rewritten called party's number (independent of the setting of the UseDialedNumber switch).

  • Acct-Delay-Time (start,update,stop)

    Amount of time (seconds) the gatekeeper is trying to send the request. Currently always 0.

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, h323_rtp_proxy (stop)

    Proxy mode of call (0=off, 1=on)

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTP_source_IP (stop)

    RTCP source report data

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTP_destination_IP (stop)

    RTCP source report data

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_source_packet_count (stop)

    RTCP source report data

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_source_packet_lost (stop)

    RTCP source report data

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_source_jitter (stop)

    RTCP source report data

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_source_sdes_XXX (stop)

    RTCP source report data (for each source description (sdes))

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_destination_packet_count (stop)

    RTCP destination report data

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_destination_packet_lost (stop)

    RTCP destination report data

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_destination_jitter (stop)

    RTCP destination report data

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, RTCP_destination_sdes_XXX (stop)

    RTCP destination report data (for each source description (sdes))

[RadAcct] Accounting-Response Radius Attributes

The gatekeeper ignores all attributes present in Accounting-Response Radius packets.

9.5 Section [SQLAcct]

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

Use the common database configuration options to define your database connection for this module.

  • 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. You can use the common CDR parameters to define what to include into your CDRs.

    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 a 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 a SQL query used to update a call record in the database with the current call state. It is used for connect and update accounting events. 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 a 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 a 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)

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

    Defines SQL query used to update a call record in the database when the call is alerting.

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

    Defines SQL query used to update the database when an endpoint registers.

  • UnregisterQuery=DELETE ...
    Default: N/A

    Defines SQL query used to update the database when an endpoint unregisters.

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

    Defines SQL query used to update a record in the database when the gatekeeper is starting.

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

    Defines SQL query used to update a record in the database when the gatekeeper is stopping.

  • TimestampFormat=MySQL
    Default: N/A

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

  • MinPoolSize=5
    Default: 1

    Number of concurrent SQL connections in the pool. The first available connection in the pool is used to store accounting data.

A Sample MySQL Schema

The SQLAcct module is designed to adapt to whatever database structure you already have. You can define all queries so they fit your existing tables. Here is an example of what those tables might look like in MySQL and which you can use as a starting point.

Create a new database; here we use the name 'GNUGK':

create database GNUGK;

Then create a table in this database to store you accounting data; we call the table 'CDR'.

create table GNUGK.CDR (
        gatekeeper_name varchar(255),
        call_number int zerofill,
        call_duration mediumint unsigned zerofill,
                index duration_idx (call_duration),
        disconnect_cause smallint unsigned zerofill,
                index dcc_idx (disconnect_cause),
        acct_session_id varchar(255),
        h323_id varchar(255),
        gkip varchar(15),
        CallId varchar(255),
        ConfID varchar(255),
        setup_time datetime,
        connect_time datetime,
        disconnect_time datetime,
        caller_ip varchar(15),
                index srcip_idx (caller_ip),
        caller_port smallint unsigned zerofill,
        callee_ip varchar(15),
                index destip_idx (callee_ip),
        callee_port smallint unsigned zerofill,
        src_info varchar(255),
        dest_info varchar(255),
        Calling_Station_Id varchar(255),
        Called_Station_Id varchar(255),
                index dialednumber_idx (Called_Station_Id (20)),
        Dialed_Number varchar(255)
);

Then you need to create a username for accessing the data.

mysql> GRANT delete,insert,select,update ON GNUGK.* TO 'YourDesiredUsername'@'localhost' IDENTIFIED BY 'APassword';
mysql> flush privileges;

With this command you will permit access to the data only from the local server. If you need to access the data from any other computer then you have to set the proper security options.

For example, to permit access from the 192.168.1.0/24 network:

mysql> GRANT delete,insert,select,update ON GNUGK.* TO 'YourDesiredUsername'@'192.168.1.%' IDENTIFIED BY 'APassword';
mysql> flush privileges;

Then you can add the following settings into your gnugk.ini file to insert and update the history of the calls into your database. 

[Gatekeeper::Acct]
SQLAcct=optional;start,stop,update
FileAcct=sufficient;stop

[FileAcct]
DetailFile=Add your desire path here something like /var/log/cdr.log
StandardCDRFormat=0
CDRString=%g|%n|%d|%c|%s|%u|%{gkip}|%{CallId}|%{ConfId}|%{setup-time}|%{connect-time}|%{disconnect-time}|%{caller-ip}|%{caller-port}|%{callee-ip}|%{callee-port}|%{src-info}|%{dest-info}|%{Calling-Station-Id}|%{Called-Station-Id}|%{Dialed-Number}
Rotate=daily
RotateTime=23:59

[SQLAcct]
Driver=MySQL
Database=GNUGK
Username=YourDesiredUsername
Password=APassword
StartQuery= insert into CDR (gatekeeper_name, call_number, call_duration, disconnect_cause, acct_session_id, h323_id, gkip, CallId, ConfId, setup_time, connect_time, disconnect_time, caller_ip, caller_port, callee_ip, callee_port, src_info, dest_info, Calling_Station_Id, Called_Station_Id, Dialed_Number) values ('%g', '%n', %d, %c, '%s', '%u', '%{gkip}', '%{CallId}', '%{ConfId}', '%{setup-time}', '%{connect-time}', '%{disconnect-time}', '%{caller-ip}', '%{caller-port}', '%{callee-ip}', '%{callee-port}', '%{src-info}', '%{dest-info}', '%{Calling-Station-Id}', '%{Called-Station-Id}', '%{Dialed-Number}')

StartQueryAlt= insert into CDR (gatekeeper_name, call_number, call_duration, disconnect_cause, acct_session_id, h323_id, gkip, CallId, ConfID, setup_time, connect_time, disconnect_time, caller_ip, caller_port, callee_ip, callee_port, src_info, dest_info, Calling_Station_Id, Called_Station_Id, Dialed_Number) values ('%g', '%n', %d, %c, '%s', '%u', '%{gkip}', '%{CallId}', '%{ConfID}', '%{setup-time}', '%{connect-time}', '%{disconnect-time}', '%{caller-ip}', '%{caller-port}', '%{callee-ip}', '%{callee-port}', '%{src-info}', '%{dest-info}', '%{Calling-Station-Id}', '%{Called-Station-Id}', '%{Dialed-Number}')

UpdateQuery= update CDR set call_duration=%d where gatekeeper_name='%g' and acct_session_id='%s'

StopQuery= update CDR set connect_time='%{connect-time}', call_duration=%d, disconnect_cause=%c, disconnect_time='%{disconnect-time}' where gatekeeper_name='%g' and acct_session_id='%s'

StopQueryAlt= insert into CDR (gatekeeper_name, call_number, call_duration, disconnect_cause, acct_session_id, h323_id, gkip, CallId, ConfID, setup_time, connect_time, disconnect_time, caller_ip, caller_port, callee_ip, callee_port, src_info, dest_info, Calling_Station_Id, Called_Station_Id, Dialed_Number) values ('%g STOP Alt', '%n', %d, %c, '%s', '%u', '%{gkip}', '%{CallId}', '%{ConfID}', '%{setup-time}', '%{connect-time}', '%{disconnect-time}', '%{caller-ip}', '%{caller-port}', '%{callee-ip}', '%{callee-port}', '%{src-info}', '%{dest-info}', '%{Calling-Station-Id}', '%{Called-Station-Id}', '%{Dialed-Number}')

TimestampFormat=MySQL

9.6 Section [StatusAcct]

This accounting module sends all accounting information to the status port where it can be used to interface to external systems in real time.

You can use the common CDR parameters to define what to include into your event strings.

  • StartEvent=CALL|Start|%{CallId}
    Default: CALL|Start|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines the event to display for a new call. The string is parametrized with the same variables as the other accounting modules (See [SQLAcct]).

  • StopEvent=CALL|Stop|%{CallId}
    Default: CALL|Stop|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines the event when a call is finished (disconnected). The syntax and parameters are the same as for StartEvent. This event is equivalent to the old status port CDR event, but more flexible.

  • UpdateEvent=CALL|Update|%{CallId}
    Default: CALL|Update|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines event used to update the current call state. The syntax and parameters are the same as for StartEvent.

  • AlertEvent=CALL|Alert|%{CallId}
    Default: CALL|Alert|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines the event when a call is alerting. The syntax and parameters are the same as for StartEvent.

  • ConnectEvent=CALL|Connect|%{CallId}
    Default: CALL|Connect|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines the event when a call is connected. The syntax and parameters are the same as for StartEvent.

  • RejectEvent=CALL|Reject|%{CallId}
    Default: CALL|Reject|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines the event when a call is rejected. The syntax and parameters are the same as for StartEvent.

  • MediaFailEvent=CALL|MediaFail|%{CallId}
    Default: CALL|MediaFail|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines the message for the MediaFail event. The syntax and parameters are the same as for StartEvent.

  • RegisterEvent=EP|Register|%{endpoint-ip}
    Default: EP|Register|%{endpoint-ip}:%{endpoint-port}|%{aliases}

    Defines the event when an endpoint registers. The syntax and parameters are the same as for StartEvent.

  • UnregisterEvent=EP|Unregister|%{endpoint-ip}
    Default: EP|Unregister|%{endpoint-ip}:%{endpoint-port}|%{aliases}

    Defines the event when an endpoint registers. The syntax and parameters are the same as for StartEvent.

  • TimestampFormat=MySQL
    Default: N/A

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

9.7 Section [SyslogAcct]

This accounting module sends accounting information to the Unix syslog and is not available on Windows. The local syslog daemon will then route the messages according to its configuration, generally specified in /etc/syslog.conf.

You can use the common CDR parameters to define what to include into your event strings.

  • SyslogFacility=LOG_LOCAL1
    Default: LOG_USER

    Set the syslog facility to one of LOG_USER, LOG_DAEMON, LOG_AUTH, LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7.

  • SyslogLevel=LOG_NOTICE
    Default: LOG_INFO

    Set the syslog level to LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO or LOG_DEBUG.

  • StartEvent=CALL|Start|%{CallId}
    Default: CALL|Start|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines the event to display for a new call. The string is parametrized with the same variables as the other accounting modules (See [SQLAacct]).

  • StopEvent=CALL|Stop|%{CallId}
    Default: CALL|Stop|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines the event when a call is finished (disconnected). The syntax and parameters are the same as for StartEvent. This event is equivalent to the old status port CDR event, but more flexible.

  • UpdateEvent=CALL|Update|%{CallId}
    Default: CALL|Update|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines event used to update the current call state. The syntax and parameters are the same as for StartEvent.

  • ConnectEvent=CALL|Connect|%{CallId}
    Default: CALL|Connect|%{caller-ip}:%{caller-port}|%{callee-ip}:%{callee-port}|%{CallId}

    Defines the event when a call is connected. The syntax and parameters are the same as for StartEvent.

  • TimestampFormat=MySQL
    Default: N/A

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

9.8 Section [LuaAcct]

This accounting module runs a LUA script for each accounting event.

The common CDR parameters are available as LUA variables as param_g or param_Called_Station_Id. The minus sign in parameter names is replaced by an underscore to construct valid LUA variable names.

The name of the event currently being processed is available in the variable event and a result ("OK", "Fail", "Next") can be stored in the result variable.

  • Script=script
    Default: N/A

    LUA script to run for every event.

  • ScriptFile=script
    Default: N/A

    LUA file to run for every event.

  • TimestampFormat=MySQL
    Default: N/A

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

9.9 Section [HttpAcct]

This accounting module sends accounting information via HTTP.

You can use the common CDR parameters to define what to include into your request URL or body.

  • Method=GET
    Default: N/A

    HTTP method to use. Currently GET and POST are supported. When you use, post, you can specify a docuemnt body with on eof the switches below. In the body, \r and \n are replaced with carriage return and line feed characters.

  • ContentType=application/json
    Default: text/plain

    The content type header to send in POST requests.

  • Authorization=Token abcdef
    Default: N/A

    The authorization header to send in HTTP requests.

  • TimestampFormat=MySQL
    Default: N/A

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

  • StartURL=http://example.com/call-start
    Default: N/A

    The URL to fetch for call start events. You can use the parameters specified below to parameterize the URL.

  • StartBody=gatekeeper=%g
    Default: empty

    The HTTP body for call start events to use with POST requests. You can use the parameters specified below to parameterize the URL. if no body is specified for POSTs, the body will be constructed from the URL parameters, if present.

  • StopURL=http://example.com/call-stop
    Default: N/A

    The URL to fetch for call stop events.

  • StopBody=gatekeeper=%g
    Default: empty

    The HTTP body for call stop events to use with POST requests.

  • UpdateURL=http://example.com/call-update
    Default: N/A

    The URL to fetch for call update events.

  • UpdateBody=gatekeeper=%g
    Default: empty

    The HTTP body for call update events to use with POST requests.

  • AlertURL=http://example.com/call-alert
    Default: N/A

    The URL to fetch for call alert events.

  • AlertBody=gatekeeper=%g
    Default: empty

    The HTTP body for call alert events to use with POST requests.

  • ConnectURL=http://example.com/call-connect
    Default: N/A

    The URL to fetch for call connect events.

  • ConnectBody=gatekeeper=%g
    Default: empty

    The HTTP body for call connect events to use with POST requests.

  • RejectURL=http://example.com/call-rejected
    Default: N/A

    The URL to fetch for call reject events.

  • RejectBody=gatekeeper=%g
    Default: empty

    The HTTP body for call reject events to use with POST requests.

  • MediaFailURL=http://example.com/media-fail
    Default: N/A

    The URL to fetch for MediaFail events.

  • MediaFailBody=gatekeeper=%g
    Default: empty

    The HTTP body for MediaFail events to use with POST requests.

  • RegisterURL=http://example.com/ep-register
    Default: N/A

    The URL to fetch for endpoint registration events.

  • RegisterBody=gatekeeper=%g
    Default: empty

    The HTTP body for endpoint registration events to use with POST requests.

  • UnregisterURL=http://example.com/ep-unregister
    Default: N/A

    The URL to fetch for endpoint unregistration events.

  • UnregisterBody=gatekeeper=%g
    Default: empty

    The HTTP body for endpoint unregistration events to use with POST requests.

  • OnURL=http://example.com/gatekeeper-up
    Default: N/A

    The URL to fetch for gatekeeper start events.

  • OnBody=gatekeeper=%g
    Default: empty

    The HTTP body for gatekeeper start events to use with POST requests.

  • OffURL=http://example.com/gatekeeper-down
    Default: N/A

    The URL to fetch for gatekeeper ststop events.

  • OffBody=gatekeeper=%g
    Default: empty

    The HTTP body for gatekeeper stop events to use with POST requests.

9.10 Section [AMQPAcct]

This accounting module sends accounting information to AMQP queues, eg, RabbitMQ.

You can use the common CDR parameters to define what to include into your request URL or body.

  • Host=192.168.1.1
    Default: localhost

    Set the host where the message broker runs.

  • Port=5672
    Default: 5672

    The port of the message broker.

  • User=admin
    Default: guest

    The user name.

  • Password=secret
    Default: guest

    The password.

  • UseSSL=1
    Default: 0

    Use SSL for the AMQP connection.

  • CACert=/path/to/cert
    Default: n/a

    Path to certificate file.

  • Exchange=foo
    Default: N/A

    The exchange to use.

  • RoutingKey=bar
    Default: N/A

    The routing key for the message broker. If you don't specify a routing key in the configuration, GnuGk will set "gnugk.call.status" or "gnugk.registration.status" as routing key.

  • VHost=/
    Default: /

    The virtual host.

  • ContentType=application/json
    Default: text/plain

    The content type header to send.

  • StartEvent=Start Call GK=%g
    Default: N/A

    The text for call start events. You can use the standard account parameters.

  • StopEvent=End Call GK=%g
    Default: N/A

    The text for call stop events. You can use the standard account parameters.

  • UpdateEvent=Update Call GK=%g
    Default: N/A

    The text for call update events. You can use the standard account parameters.

  • AlertEvent=Alert Call GK=%g
    Default: N/A

    The text for call alert events. You can use the standard account parameters.

  • ConnectEvent=Connect Call GK=%g
    Default: N/A

    The text for call conect events. You can use the standard account parameters.

  • RejectEvent=Reject Call GK=%g
    Default: N/A

    The text for call reject events. You can use the standard account parameters.

  • RegisterEvent=Register Endpoint GK=%g
    Default: N/A

    The text for endpoint registration events. You can use the standard account parameters.

  • UnregisterEvent=Unregister Endpoint GK=%g
    Default: N/A

    The text for endpoint unregistration events. You can use the standard account parameters.

  • OnEvent=GK Start %g
    Default: N/A

    The text for ON events. You can use the standard account parameters.

  • OffEvent=GK Stop %g
    Default: N/A

    The text for OFF events. You can use the standard account parameters.

  • TimestampFormat=MySQL
    Default: N/A

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

In the settings for Host, Port, User, Password, UseSSL, CACert, Exchange and RoutingKey you can use %{env1} to %{env9} to insert the environment variables GNUGK_ENV1 ... GNUGK_ENV9.

9.11 Section [MQTTAcct]

This accounting module sends accounting information to an MQTT server.

You can use the common CDR parameters to define what to include into your request URL or body.

  • Host=192.168.1.1
    Default: localhost

    Set the host where the message broker runs.

  • Port=1883
    Default: 1883

    The port of the message broker.

  • UseSSL=0
    Default: 0

    Currently not implemented.

  • CACert=/path/to/cert
    Default: n/a

    Currently not implemented.

  • User=admin
    Default: guest

    The user name.

  • Password=secret
    Default: guest

    The password.

  • CallTopic=foo/bar
    Default: gnugk/call/status

    The topic for call related events.

  • RegistrationTopic=foo/bar
    Default: gnugk/registration/status

    The topic for registration related events.

  • StartEvent=Start Call GK=%g
    Default: N/A

    The text for call start events. You can use the standard account parameters.

  • StopEvent=End Call GK=%g
    Default: N/A

    The text for call stop events. You can use the standard account parameters.

  • UpdateEvent=Update Call GK=%g
    Default: N/A

    The text for call update events. You can use the standard account parameters.

  • AlertEvent=Alert Call GK=%g
    Default: N/A

    The text for call alert events. You can use the standard account parameters.

  • ConnectEvent=Connect Call GK=%g
    Default: N/A

    The text for call conect events. You can use the standard account parameters.

  • RejectEvent=Reject Call GK=%g
    Default: N/A

    The text for call reject events. You can use the standard account parameters.

  • RegisterEvent=Register Endpoint GK=%g
    Default: N/A

    The text for endpoint registration events. You can use the standard account parameters.

  • UnregisterEvent=Unregister Endpoint GK=%g
    Default: N/A

    The text for endpoint unregistration events. You can use the standard account parameters.

  • OnEvent=GK Start %g
    Default: N/A

    The text for ON events. You can use the standard account parameters.

  • OffEvent=GK Stop %g
    Default: N/A

    The text for OFF events. You can use the standard account parameters.

  • TimestampFormat=MySQL
    Default: N/A

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

In the settings for Host, Port, User, Password, UseSSL and CACert you can use %{env1} to %{env9} to insert the environment variables GNUGK_ENV1 ... GNUGK_ENV9.

9.12 Section [RequireOneNet]

While this is technically an accounting module, its logical purpose is to authenticate calls and make sure at least one end of the call is inside one of your own networks. This is designed to protect traversal gatekeepers from abuse that by nature need to be accessible for everybody who wants to call into your network, but that should not be allowed to support external to external calls.

  • Networks=192.168.1.0/24,192.0.2.0/24
    Default: N/A

    List the networks your gatekeeper supports. Either the source or the destination of all calls must be within one of these networks.

Next Previous Contents

Chapters: Contents · Introduction · Installation · Getting started · Basic Config · Routed Mode & Proxy · Routing · RAS Config · Authentication · Accounting · Neighbors · Per Endpoint Config · Advanced Config · Monitoring · Advanced Topics


Last updated: 07. Nov 2025