12. Advanced Configuration

12.1 Section [CallTable]

• GenerateNBCDR=0
  Default: 1
  

  Generate CDRs for calls from neighbor zones on the status port. The IP and endpoint ID of the calling party is printed as empty. This is usually used for debugging purposes. The accounting modules will always get CDR data for all calls.

• GenerateUCCDR=0
  Default: 0
  

  Generate CDRs for calls that are unconnected. This is usually used for debugging purposes. Note that a call is considered unconnected only if the gatekeeper uses routed mode and a Q.931 "Connect" message is not received by the gatekeeper. In direct mode, a call is always considered connected.

• DefaultCallDurationLimit=3600
  Default: 0
  

  Default maximum call duration limit (seconds). Set it to 0 to disable this feature and not limit call duration.

• AcctUpdateInterval=60
  Default: 0
  

  A time interval (seconds) for accounting updates to be logged for each call in progress. The exact details of the accounting updates depend on accounting logger modules selected (see section [Gatekeeper::Acct]). In general, the accounting update is to provide back-end services with incrementing call duration for connected calls. The default value "0" disables accounting updates. Please note that setting this to a short interval may decrease gatekeeper performance.

• TimestampFormat=Cisco
  Default: RFC822
  

  Format of timestamp strings printed inside CDRs. You can use the same list of formats as specified in the [Gatekeeper::Main] section.

• IRRFrequency=60
  Default: 120
  

  Set the irrFrequency in ACF messages. 0 turns it off.

• IRRCheck=TRUE
  Default: FALSE
  

  Check if both endpoints in a call send the requested IRRs. A call will be terminated if one of the endpoints do not send an IRR after 2 * irrFrequency.

• SingleFailoverCDR=FALSE
  Default: TRUE
  

  When failover is active, more than one gateway may be tried to establish a call. This switch defines if one or multiple CDRs are generated for such a call.

• DisabledCodecs=g711Alaw64k;g711Ulaw64k;h263VideoCapability;
  Default: N/A
  

  Filter out certain codecs. Please note the trailing semicolon. Calls must be H.245 routed or proxied for codec filtering to work. This setting can be overridden on a per-call basis by using the Radius attribute 'disable-codec'.

12.2 Section [H225toQ931]

When converting between H.225 reasons and Q.931 cause codes, GnuGk uses a conversion table. Using this section you can change this mapping.

[H225toQ931]
;0=34 # noBandwidth
;1=47 # gatekeeperResources
2=34 # unreachableDestination => NoCircuitChannelAvailable (default 3)
;3=16 # destinationRejection
;4=88 # invalidRevision
;5=111 # noPermission
;6=38 # unreachableGatekeeper
;7=42 # gatewayResources
;8=28 # badFormatAddress
;9=41 # adaptiveBusy
;10=17 # inConf
;11=31 # undefinedReason
;12=16 # facilityCallDeflection
;13=31 # securityDenied
14=34 # calledPartyNotRegistered => NoCircuitChannelAvailable (default 20)
;15=31 # callerNotRegistered
;16=47 # newConnectionNeeded
;17=127 # nonStandardReason
;18=31 # replaceWithConferenceInvite
;19=31 # genericDataReason
;20=31 # neededFeatureNotSupported
;21=127 # tunnelledSignallingRejected


12.3 Section [GkQoSMonitor]

Use H.460.9 to collect Quality of Service information from endpoints. Endpoints must support H.460.9 for this service to function.

• Enable=1
  Default: 0
  

  Defines whether to enable or disable the feature. If enabled, this function will respond to supportedFeature requests from clients so clients know to send QoS statistics to the gatekeeper.

• CallEndOnly=0
  Default: 1
  

  Defines whether to collect the information via IRR messages or only collect QoS information at the end of a call.

• DetailFile=qos.txt
  Default: N/A
  

  Define the output file for QoS logs. If a file is not defined the QoS information is output as an item in the Trace File at trace level 4.

12.4 Section [GkQoSMonitor::SQL]

This section allows you to store QoS information in a database. You can use the same database parameters as defined in [SQLPasswordAuth].

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

  Defines the SQL query used to store the QoS information.

  The following parameters are defined:

  • %g - gatekeeper ID
  • %{ConfId} - conference ID
  • %{session} - session
  • %{caller-ip} - caller IP
  • %{caller-port} - caller port
  • %{caller-nat} - is caller NATted (0 or 1)
  • %{callee-ip} - caller IP
  • %{callee-port} - caller port
  • %{avgdelay} - average delay
  • %{packetloss} - packet loss
  • %{packetloss-percent} - packet loss percentage
  • %{avgjitter} - average jitter
  • %{bandwidth} - bandwidth (in units of 100 bits per second)
  • %t - timestamp

  Sample query string:

  INSERT INTO qos SET caller_ip="%{caller-ip}", bandwidth="%{bandwidth}, timestamp=%t
  

12.5 Section [Endpoint]

The gatekeeper can function as an endpoint by registering with another gatekeeper, allowing you to build gatekeeper hierarchies. This section defines the endpoint features for the gatekeeper.

• Gatekeeper=10.0.1.1
  Default: no
  

  Define a parent gatekeeper for GnuGk to register with. When a call in the routing process reaches the 'parent' routing policy, it will route all calls to this gatekeeper. If you set this to auto, GnuGk will send an IPv4 broadcast GRQ.

  Make sure you don't register with yourself, the results can be very confusing.

• Type=Gateway
  Default: Gateway
  

  Define the terminal type GnuGk will use when it registers. Valid options are Gateway or Terminal.

• Vendor=Cisco | GnuGk | Generic
  Default: GnuGk
  

  Choose parent gatekeeper type to enable vendor specific extensions.

• H323ID=ProxyGK
  Default: <Name>
  

  Specify the H.323 ID aliases for the endpoint. Multiple aliases can be separated with a comma.

• E164=18888600000,18888700000
  Default: N/A
  

  Define the E.164 (dialedDigits) aliases for the endpoint. Multiple aliases can be separated with a comma.

• Password=123456
  Default: N/A
  

  Specify a password to be sent to the parent gatekeeper.

  All RAS requests will contain the password in the cryptoTokens field (MD5 & HMAC-SHA1-96) and the tokens field (CAT). To send RAS requests without the cryptoTokens and tokens fields, configure an empty password. 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.

  The password will be used in LRQs sent to neighbor gatekeepers.

• Prefix=188886,188887
  Default: N/A
  

  Register the specified prefixes with the parent gatekeeper. Only takes effect when the Type is Gateway.

• TimeToLive=900
  Default: 60
  

  Suggest a time-to-live value (in seconds) for the registration. Note that the real time-to-live timer is assigned by the parent gatekeeper in the RCF is sends to us in response to our RRQ.

• RRQRetryInterval=10
  Default: 3
  

  Define a retry interval in seconds for resending an RRQ if no response is received from the parent gatekeeper. This interval is doubled with each failure, up to a maximum RRQRetryInterval * 128 timeout.

• UnregisterOnReload=1
  Default: 0
  

  Defines whether the child gatekeeper unregisters and re-registers with its parent after receiving a Reload command from the status port.

• NATRetryInterval=60
  Default: 60
  

  How long to wait before trying to reconnect TCP NAT signaling socket (seconds). This can happen when either the connection cannot be established or it has been broken.

• NATKeepaliveInterval=86400
  Default: 86400
  

  Define how often the TCP NAT signaling connection with a parent gatekeeper is refreshed. As NAT boxes usually keep TCP mappings for a certain duration, it's strongly suggested to set this to a value slightly shorter than the NAT box mapping timeout. Refreshing is done by sending a special Q.931 IncomingCallProceeding message. If your NAT performs TCP port translation, you may need to set it to a value as short as 60 seconds.

• Discovery=0
  Default: 1
  

  Configures GnuGk to attempt to discover the parent gatekeeper by first sending a GRQ.

• UseAlternateGK=0
  Default: 1
  

  Enable alternate gatekeepers feature. If GRJ/GCF/RCF messages received from a parent gatekeeper contain a list of alternate gatekeepers, this information is stored and can be used to re-register with another gatekeeper in case of failure. If you don't want to use this feature, set this variable to 0.

• GatekeeperIdentifier=ParentGK
  Default: Not set
  

  Define this parameter if you only want to accept parent gatekeepers that match this gatekeeper identifier. Useful with GRQ discovery and can prevent an accidental gatekeeper match. Do not set this variable if you do not care about gatekeeper identifiers or you use alternate gatekeepers that can have different gatekeeper identifiers.

• EndpointIdentifier=ChildGK
  Default: Not set
  

  Set this if you want to use a specific endpoint identifier for this child gatekeeper. If this option is not set (default), the identifier is assigned by a parent gatekeeper in a GCF/RCF message.

• ForwardDestIp=0
  Default: 1
  

  Forward the destCallSignalAddress in ARQs to the parent gatekeeper.

12.6 Section [CTI::Agents]

This section allows the configuration of a so-called virtual queue to allow inbound call distribution by an external application via the status port. A virtual queue has a H.323 alias that can be called like an endpoint or it can answer to a set of aliases.

Once a call arrives on the virtual queue, the gatekeeper signals a RouteRequest on the status port and waits for an external application to respond with either a RouteReject (which will cause the call to be rejected) or with RouteToAlias/RouteToGateway which leads to the destination being rewritten so the call will be routed to the alias (eg. call center agent) specified by the external application.

If no answer is received after a timeout period, the call is terminated.

You can specify virtual queues in three ways:

• exact alias name - a list of aliases is given. If a request destination alias matches one these names, the virtual queue is activated.
• prefix - a list of prefixes is given. If a request destination alias starts with one these prefixes, the virtual queue is activated.
• regular expression - a regular expression is given. If a request destination alias matches the expression, the virtual queue is activated.

To apply the virtual queue to all calls, specify a regular expression that matches everything, see the example below.

See the monitoring section for details on the messages and responses.

• VirtualQueueAliases
  Default: none
  

  This defines a list of H.323 aliases for the virtual queues (used with the vqueue RoutingPolicy).

  Example:

  VirtualQueueAliases=sales,support

  
  

• VirtualQueuePrefixes
  Default: none
  

  This defines a list of prefixes for the virtual queues (used with the vqueue RoutingPolicy).

  Example:

  VirtualQueuePrefixes=001215,1215

  
  

• VirtualQueueRegex
  Default: none
  

  This defines a regular expression for the virtual queues (used with the vqueue RoutingPolicy).

  Example (numbers starting with 001215 or 1215):

  VirtualQueueRegex=^(001|1)215[0-9]*$

  
  

  Example to match all calls:

  VirtualQueueRegex=^.*$

  
  

• RequestTimeout
  Default: 10
  Timeout in seconds for the external application to answer the RouteRequest. If no answer is received during this time the call will be rejected.

12.7 Section [CTI::MakeCall]

This section contains the settings for the status port command MakeCall.

• EndpointAlias=DialOut
  Default: InternalMakeCallEP
  

  This defines the endpoint alias for the pseudo endpoint used to dial.

• TransferMethod=H.450.2
  Default: FacilityForward
  

  Set the method to transfer the call from the pseudo endpoint to the actual destination. Possible values are: FacilityForward, FacilityRouteCallToMC and H.450.2.

• UseH450=1
  Default: 0
  

  Use a H.450.2 transfer instead of a Facility message to transfer the call from the pseudo endpoint to the actual destination. Deprecated: Use TransferMethod= instead.

• Gatekeeper=192.168.1.2
  Default: 127.0.0.1
  

  Gatekeeper IP for the pseudo endpoint to register with.

• Interface=192.168.1.1:1730
  Default: *:1722
  

  Interface and port to use for the pseudo endpoint.

• DisableFastStart=1
  Default: 0
  

  Disable FastStart for the pseudo endpoint.

• DisableH245Tunneling=1
  Default: 0
  

  Disable H.245 tunneling for the pseudo endpoint.

12.8 Section [SQLConfig]

Load gatekeeper settings from a SQL database (in addition to settings read from the config file). A generic ConfigQuery can be used to read almost all setting from the database and/or one of [RasSrv::RewriteE164], [RasSrv::PermanentEndpoints], [RasSrv::Neighbors], [RasSrv::GWPrefixes] queries can be used to load particular settings. Entries read from the SQL database take precedence over settings found in the config file.

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

• ConfigQuery=SELECT ...
  Default: N/A
  

  Define a SQL query used to read gatekeeper settings from the database. The query is parameterized - that means parameter replacement occurs before the query is executed. Parameter placeholders are denoted by %1, %2, ... strings. Specify %% to embed a percent character before a digit in a string (like %%1), specify %{1} to allow expansion inside complex expressions like %{1}123. For ConfigQuery only one parameter is defined:

  • %1 - the gatekeeper identifier
  It is expected that the query returns zero or more rows of data, with each row consisting of three columns:
  • column at index 0 - config section name
  • column at index 1 - config key (option name)
  • column at index 2 - config value (option value)

  Sample query strings:

  ConfigQuery=SELECT secname, seckey, secval FROM sqlconfig WHERE gk = '%1'
  ConfigQuery=SELECT 'RasSrv::RRQAuth', alias, rule FROM rrqauth WHERE gk = '%1'
  

• RewriteE164Query=SELECT ...
  Default: N/A
  

  Define a SQL query used to retrieve rewrite rules from the database for the [RasSrv::RewriteE164] section. The query is parameterized - that means parameter replacement occurs before each query is executed. Parameter placeholders are denoted by %1, %2, ... strings. Specify %% to embed a percent character before a digit into string (like %%1), specify %{1} to allow expansion inside complex expressions like %{1}123. For RewriteE164Query only one parameter is defined:

  • %1 - the gatekeeper identifier
  It is expected that the query returns zero or more rows of data, with each row consisting of two columns:
  • column at index 0 - rewrite rule key
  • column at index 1 - rewrite rule value

  Sample query strings:

  RewriteE164Query=SELECT rkey, rvalue FROM rewriterule WHERE gk = '%1'
  

• RewriteAliasQuery=SELECT ...
  Default: N/A
  

  Define a SQL query used to retrieve rewrite rules from the database for the [RasSrv::RewriteAlias] section. The query is parameterized - that means parameter replacement occurs before each query is executed. Parameter placeholders are denoted by %1, %2, ... strings. Specify %% to embed a percent character before a digit into string (like %%1), specify %{1} to allow expansion inside complex expressions like %{1}123. For RewriteAliasQuery only one parameter is defined:

  • %1 - the gatekeeper identifier
  It is expected that the query returns zero or more rows of data, with each row consisting of two columns:
  • column at index 0 - rewrite rule key
  • column at index 1 - rewrite rule value

  Sample query strings:

  RewriteAliasQuery=SELECT rkey, rvalue FROM assignedalias WHERE gk = '%1'
  

• AssignedAliasQuery=SELECT ...
  Default: N/A
  

  Define a SQL query used to retrieve rewrite rules from the database for the [RasSrv::AssignedAlias] section. The query is parameterized - that means parameter replacement occurs before each query is executed. Parameter placeholders are denoted by %1, %2, ... strings. Specify %% to embed a percent character before a digit into string (like %%1), specify %{1} to allow expansion inside complex expressions like %{1}123. For AssignedAliasQuery only one parameter is defined:

  • %1 - the gatekeeper identifier
  It is expected that the query returns zero or more rows of data, with each row consisting of two columns:
  • column at index 0 - rewrite rule key
  • column at index 1 - rewrite rule value

  Sample query strings:

  AssignedAliasQuery=SELECT rkey, rvalue FROM assignedalias WHERE gk = '%1'
  

• NeighborsQuery=SELECT ...
  Default: N/A
  

  Define a SQL query used to retrieve neighbor entries from the database for the [RasSrv::Neighbors] section. The query is parameterized - that means parameter replacement occurs before each query is executed. Parameter placeholders are denoted by %1, %2, ... strings. Specify %% to embed a percent character before a digit into string (like %%1), specify %{1} to allow expansion inside complex expressions like %{1}123. For NeighborsQuery one parameter is defined:

  • %1 - the gatekeeper identifier
  It is expected that the query returns zero or more rows of data, with each row consisting of six columns:
  • column at index 0 - neighbor name (identifier)
  • column at index 1 - neighbor IP address
  • column at index 2 - neighbor port number
  • column at index 3 - optional prefixes (comma separated)
  • column at index 4 - optional password
  • column at index 5 - optional dynamic IP flag

  Sample query strings:

  NeighborsQuery=SELECT nid, nip, nport, npfx, NULL, 0 FROM neighbor WHERE gk = '%1'
  

• PermanentEndpointsQuery=SELECT ...
  Default: N/A
  

  Define a SQL query used to retrieve permanent endpoints from the database for the [RasSrv::PermanentEndpoints] section. The query is parameterized - that means parameter replacement occurs before each query is executed. Parameter placeholders are denoted by %1, %2, ... strings. Specify %% to embed a percent character before a digit into string (like %%1), specify %{1} to allow expansion inside complex expressions like %{1}123. For PermanentEndpointsQuery only one parameter is defined:

  • %1 - the gatekeeper identifier
  It is expected that the query returns zero or more rows of data, with each row consisting of four columns:
  • column at index 0 - permanent endpoint IP address
  • column at index 1 - permanent endpoint port number
  • column at index 2 - permanent endpoint alias
  • column at index 3 - optional permanent endpoint prefixes (comma separated)

  Sample query strings:

  PermanentEndpointsQuery=SELECT peip, 1720, pealias, NULL FROM permanentep WHERE gk = '%1'
  

• GWPrefixesQuery=SELECT ...
  Default: N/A
  

  Define a SQL query used to retrieve gateway prefixes from the database for the [RasSrv::GWPrefixes] section. The query is parameterized - that means parameter replacement is made before each query is executed. Parameter placeholders are denoted by %1, %2, ... strings. Specify %% to embed a percent character before a digit into string (like %%1), specify %{1} to allow expansion inside complex expressions like %{1}123. For GWPrefixesQuery only one parameter is defined:

  • %1 - the gatekeeper identifier
  It is expected that the query returns zero or more rows of data, with each row consisting of two columns:
  • column at index 0 - gateway alias
  • column at index 1 - gateway prefixes (comma separated)

  Sample query strings:

  GWPrefixesQuery=SELECT gwalias, gwpfx FROM gwprefix WHERE gk = '%1'
  

12.9 Section [PortNotifications]

GnuGk can execute a system command whenever it opens a new port for listening. For example, this can be used to automatically update the firewall configuration.

The following placeholder are available:

• %p - protocol ("udp" or "tcp")
• %n - port number
• %i - IP

By configuring a command to run for some types of ports, but not for others, you can easily choose which ports to handle and which to ignore.

• Q931PortOpen=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• Q931PortClose=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• H245PortOpen=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• H245PortClose=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• RTPPortOpen=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• RTPPortClose=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• T120PortOpen=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• T120PortClose=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• RASPortOpen=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• RASPortClose=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• StatusPortOpen=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• StatusPortClose=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• RadiusPortOpen=/usr/local/bin/ports.sh %p %n %i
  Default: none
  
• RadiusPortClose=/usr/local/bin/ports.sh %p %n %i
  Default: none
  

Example:

[PortNotifications]
Q931PortOpen=/usr/local/bin/ports.sh %p %n %i
Q931PortClose=/usr/local/bin/ports.sh %p %n %i
H245PortOpen=/usr/local/bin/ports.sh %p %n %i
H245PortClose=/usr/local/bin/ports.sh %p %n %i
RTPPortOpen=/usr/local/bin/ports.sh %p %n %i
RTPPortClose=/usr/local/bin/ports.sh %p %n %i
RASPortOpen=/usr/local/bin/ports.sh %p %n %i
RASPortClose=/usr/local/bin/ports.sh %p %n %i
T120PortOpen=/usr/local/bin/ports.sh %p %n %i
T120PortClose=/usr/local/bin/ports.sh %p %n %i