This is the manual for GNU Gatekeeper 4.8.
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    Join the community    Get support

The GNU Gatekeeper Manual Chapter 12

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=0
    Default: 1

    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=0
    Default: 1

    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.

  • UseDestCallSignalIPAsDialedNumber=1
    Default: 0

    Use the destCallSignalIP for CDRs in %{DialedNumber} if no dialed alias is available in ARQ or Setup.

  • SetCalledStationIdToDialedIP=1
    Default: 0

    Alwways set %{called_station_id} to the dialed IP in CDRs if %{DialedNumber} contains an IP number.

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

    Filter out certain codecs. Calls must be H.245 routed or proxied for codec filtering to work. You can also filter out whole capability sets, eg. "receiveVideoCapability", "receiveAndTransmitDataApplicationCapability" of "nonStandard". This setting can be overridden on a per-call basis by using the Radius attribute 'disable-codec' or per endpoint in the [EP::...] section.

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. This setting can also be configured by specifying the triplet of T.35 IDs (<country>,<manufacturer>,<extension>) for the vendor to set the vendor ID without enabling any extensions.

    Example:

    Vendor=GnuGk
    ; Aculab ID
    Vendor=222,173,0
    

  • HideGk=1
    Default: 0

    Hide the fact that a gatekeeper is registering, eg. don't set gatekeeper flag in terminal type.

  • ProductId=Any Product Name
    Default: GnuGk's name

    This setting will allow you to configure the "product ID" string used in the registration request. The primary use of this setting would be to solve interoperability issues.

  • ProductVersion=1.2.3
    Default: GnuGk version

    This setting allows you to configure the product version string in the registration request in order to solve interoperability issues.

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

  • Authenticators=H.235.1,CAT
    Default: H.235.1,MD5,CAT

    Selects the authenticators to sent be to the parent gatekeeper in GRQ The default options are: H.235.1 (HMAC SHA1 / old H235AnnexD), MD5 (Digest Authentication) and CAT (Cisco Access Tokens ie RADIUS). Setting a value of NONE will disable all authenticators. If this setting is omitted, all authenticators are enmabled by default. Note: H.235.1 requires OpenSSL support compiled into GnuGk.

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

  • EnableAdditiveRegistration=1
    Default: 0

    Whether the child gatekeeper supports passing registration information to the parent. Use this if you wish to manage registrations including authentication in the parent gatekeeper and not the child.

  • EnableGnuGkNATTraversal=1
    Default: 0

    Enable support for GnuGk's old NAT traversal method. You should use H.460.18/.19 for new installations.

  • EnableH46018=1
    Default: 0

    Whether the child offers H.460.18/.19 support to the parent.

  • EnableH46023=1
    Default: 0

    Whether the child offers H.460.23/.24 support to the parent.

  • UseTLS=1
    Default: 0

    Use TLS (transport layer security) with this gatekeeper. See also [TLS] section.

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, Reroute and H.450.2.

  • UseH450=1
    Default: 0

    Deprecated: Use TransferMethod switch instead.

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

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

  • DisableH245Tunneling=1
    Default: 0

    Disable H.245 tunneling for the pseudo endpoint.

  • Bandwidth=786
    Default: 384

    Bandwidth for the call in kbps. Many endpoints won't establish a call with higher bandwidth than specified here.

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'
    

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

    Define a SQL query used to retrieve neighbor entries for new style format 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 type (GnuGk, Cisco, Generic)
    • column at index 2 - neighbor Host (IP [and port])
    • column at index 3 - optional SendPrefixes (comma separated)
    • column at index 4 - optional AcceptPrefixes (comma separated)
    • column at index 5 - optional ForwardHopCount
    • column at index 6 - optional AcceptForwardedLRQ
    • column at index 7 - optional ForwardResponse
    • column at index 8 - optional H46018Type (0-none 1-server 2-client)
    • column at index 9 - optional SendAuthUser (H46018)
    • column at index 10 - optional SendPassword (H46018)

    Sample query strings:

    NeighborsQuery2=SELECT id, gtype, host, sendPrefix, recvPrefix 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 3 or 5 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 and priorities (comma separated)
    • column at index 4 - optional: permanent endpoint vendor
    • column at index 5 - optional: permanent endpoint product

    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

12.10 Section [SNMP]

The Simple Network Management Protocol (SNMP) lets you monitor the GNU Gatekeeper during operation and allows you to configure a destination system for notifications ("traps") when an error occurs.

  • EnableSNMP=1
    Default: 0

    Enable SNMP support. GnuGk must be compiled with SNMP support.

  • Implementation=PTLib
    Default: Net-SNMP

    Select the SNMP implementation to use. Possible values are Net-SNMP, PTLib and Windows.

  • EnableWarningTraps=1
    Default: 0
    Also throw traps with warnings. If you enable warning traps, make sure you have good trap filtering in place in your management application. Many warnings can be generated in harmles situations where GnuGk can't decide if its a real error or not.

If the GnuGk configuration file enables SNMP, and the Net-SNMP implementation is selected, then GnuGk will register as an AgentX sub-agent with the Net-SNMP daemon. By default GnuGk will connect to the localhost IP address (127.0.0.1) and TCP port 705. Registering as a sub-agent allows you to continue querying Net-SNMP about the general health of the server and adds a GnuGk specific object.

All GET / SET requests and SNMP traps are performed by the Net-SNMP daemon, so configuration of access control, trap destination and SNMP version information must be done in the Net-SNMP .conf file.

If PTLib's SNMP implementation is selected, GnuGk starts a standalone SNMP agent. NOTE: Only one SNMP agent can bind to UDP/161, so you might have to use a non-standard port if you are using another SNMP agent on your server.

NOTE: By default, PTLib enables SNMP during the configuration process, so if SNMP doesn't work ensure that your PTLib wasn't compiled with --disable-snmp

Using PTLib rather than the fully-featured Net-SNMP means that only traps and GET requests are supported. See below for the additional switches which are required when using PTLib for SNMP.

The Windows implementation integrates as a sub-agent into Windows' SNMP service. This implementation is incomplete. You can use the PTLib implementation on Windows, for the sam elimited SNMP support as on Unix. Please contact the authors if you need full SNMP support on Windows.

GNU Gatekeeper Enterprise MIB

The GNU Gatekeeper Project was assigned the enterprise number 27938 by IANA (Internet Assigned Number Authority), so all of GnuGk's OIDs are under 1.3.6.1.4.1.27938.

The formal MIB specification (SMIv2) can be found in the file 'gnugk.mib' that is distributed with GnuGk. You might want to import it into your SNMP management software to see symbolic names for GnuGk's OIDs.

The following OIDs are available:

  • 1.3.6.1.4.1.27938.11.1.1 GnuGk version (GET)
  • 1.3.6.1.4.1.27938.11.1.2 GnuGk version with module flags (GET)
  • 1.3.6.1.4.1.27938.11.1.3 Current number of endpoint registrations (GET)
  • 1.3.6.1.4.1.27938.11.1.4 Number of ongoing calls (GET)
  • 1.3.6.1.4.1.27938.11.1.5 Trace level (GET, SET)
  • 1.3.6.1.4.1.27938.11.1.6 CatchAll destination (GET, SET)
  • 1.3.6.1.4.1.27938.11.1.7 Total calls since startup (GET)
  • 1.3.6.1.4.1.27938.11.1.8 Successful calls since startup (GET)
All of these OIDs are scalars, so please remember to append '.0' when querying them eg. with 'snmpget'.

Note: Setting the CatchAll destination via SNMP will update the config file to make the change permanent. Setting the trace level is a temporary setting.

The following traps are defined:

  • 1 GnuGk started
  • 2 GnuGk stopped
  • 3 Config Reload
  • 4 Module creation failed
  • 5 Database operation failure
  • 6 IO operation failure
  • 7 General error
  • 8 Authentication error
  • 9 Message encoding/decoding error
  • 10 Network error
  • 11 Neighbor error

Traps may have 3 optional data elements:

  • Severity level (OID 1.3.6.1.4.1.27938.11.2.1): Error=1, Warning=2, Info=3
  • Group (OID 1.3.6.1.4.1.27938.11.2.2): General=1, Network=2, Database=3, Accounting=4, Authentication=5, Configuration=6
  • Display string (OID 1.3.6.1.4.1.27938.11.2.3)

Configuring Net-SNMP

Net-SNMP configuration is usually found in /etc/snmp/snmpd.conf. This configuration file defines access control rules for the SNMP manager and where settings such as readonly and read-write community names are defined, where to send traps, etc.

Depending on which trap host definition you use, Net-SNMP will convert the traps to the appropriate version. Use 'trapsink' if you want to send version 1 traps, 'trap2sink' if you want to send version 2 traps and 'informsink' for SNMP v3 inform messages.

Please make sure AgentX support is enabled in the Net-SNMP daemon.

Simple example of a snmpd.conf for SNMP version 2c:

# server location and contact
syslocation Server Room
syscontact Sysadmin (root@example.com)

# read-only access only from this network, access to all MIBs
rocommunity public 192.168.1.0/24
# read-write access only from this network, restricted to the GnuGk MIB
rwcommunity mysecret 192.168.1.0/24     1.3.6.1.4.1.27938

# send traps as version 2 to this host with community string 'public'
trap2sink   192.168.1.64    public

# enable AgentX support
master agentx
agentxsocket tcp:localhost:705

For SNMP version 3 the config file could look like this:

# server location and contact
syslocation Server Room
syscontact Sysadmin (root@example.com)

# read-only access for user 'peter'
rouser peter
# full read-write access for user 'paul'
rwuser paul
# read-write access only for the GnuGk MIB for user 'mary'
rwuser mary auth 1.3.6.1.4.1.27938

# create the user accounts and set passwords
createUser peter MD5 peterpeter DES
createUser paul MD5 paulpaul DES
createUser mary MD5 marymary DES

# send traps as version 3 Inform messages with community string 'public'
informsink   192.168.1.64    public

# enable AgentX support
master agentx
agentxsocket tcp:localhost:705

You can also configure the Net-SNMP based agent to run standalone without the Net-SNMP daemon, but this is not suggested.

  • Standalone=1
    Default: 0
    Run SNMP-Agent standalone, and don't connect to AgentX master agent.

Using PTLib's SNMP implementation

PTlib supports SNMP version 1 and 2 GET requests and will always send version 1 traps in a version 2c message. GETNEXT (for 'walk') and SET requests are not supported.

When using PTLib, you can use these additional switches:

  • TrapHost=192.168.1.100
    Default: none

    Define the trap destination host. No traps will be sent if no host is defined. You may specify an IP or DNS name.

  • TrapCommunity=public
    Default: public

    Define the community string for traps.

  • AgentListenIP=192.168.1.100
    Default: 127.0.0.1

    Define the IP the SNMP agent should listen on.

  • AgentListenPort=11161
    Default: 161

    Define the UDP port the SNMP agent should listen on.

  • AllowRequestsFrom=192.168.1.0/22
    Default: n/a

    A comma separated list of IPs or networks which are allowed to send us SNMP requests.

12.11 Section [TLS]

Using TLS (transport layer security), you can encrypt the Q.931 signalling channel (and eg. H.245 when it is tunneled). When TLS is enabled, GnuGk will listen on port 1300 for TLS connections.

Each leg of the call can use not not use TLS individually. For example one endpoint might encrypt its signalling to the GNU Gatekeeper and the 2nd half of the call going out to another endpoint may be unencrypted.

You have to define manually which endpoints use TLS when we call them, by setting a switch in their [EP::...] section. Similar you can enable TLS for neighbor and parent gatekeeper. Since not many endpoints support TLS encryption, so this feature can be very usefull to secure "trunk" connections or traversal zones to branch offices etc.

Using TLS is also important to avoid man-in-the-middle attacks on H.235.6 media encryption.

Note: Currently you must use H.245 tunneling when using TLS, consider H245TunnelingTranslation=1 to tunnel H.245 between gatekeepers when not all of your endpoints enable tunneling natively.

  • EnableTLS=1
    Default: 0

    Enable TLS support. GnuGk must have been compiled with OpenSSL support.

  • PrivateKey=server_key.pem
    Default: tls_private_key.pem

    File with private key for this server.

  • Certificates=server_cert.pem
    Default: tls_certificate.pem

    File with certificate for this server.

  • CAFile=root_cert.pem
    Default: n/a

    File with root CA certificates.

  • CADir=/etc/certs/
    Default: n/a

    Directory where to search for root CA certificates.

  • Passphrase=whatever
    Default: n/a

    The passphrase to open the above certificate files, if you have set one.

  • CipherList=ALL:!ADH:!LOW:!EXP:!MD5:!RC4:!SHA1:!ECDH:!ECDSA:@STRENGTH
    Default: ALL:!ADH:!LOW:!EXP:!MD5:!RC4:!SHA1:!ECDH:!ECDSA:@STRENGTH

    Set the OpenSSL cipher list to be used for TLS connections.

  • CheckCertificateIP=1
    Default: 0

    In addition to checking if a peer certificate is signed correctly, GnuGk can check if one of the X.509 extensions contains a DNS name or if the commonName in the certificate match the IP, the connections actually comming from.

    Not all certificates contain proper DNS names and if your peers are behind a NAT you might not be able to see their true IPs. Also DNS lookups may be slow, so this check is disabled by default.

  • RequireRemoteCertificate=1
    Default: 1

    WARNING: USE SWITCH WITH CAUTION. It is highly recommended that TLS be established between 2 parties that both authenticate each other via digital certificates. However there are use cases where generation and distribution of certificates to remote/distant endpoints becomes difficult or impossible. This switch when set to 0 will only authenticate TLS connections that the gatekeeper initiates and NOT ones it receives. For this reason it should ONLY be used in a gatekeeper environment where other security is present such as defining explicit Neighbors in Neighbors policy. For Endpoints it should ONLY be used with trusted endpoints and in conjunction with H.460.17 (recommended) and .18 where the endpoint always initiates the TLS connection and can vertify the certificate of the gatekeeper. If H.460.18 is used it is highly recommended to set [RoutedMode]NATStdMin=18 to ensure all endpoints MUST support H.460.18.

    This switch is only available if GnuGk is compiled with --eanble-weaktls and might be removed from future versions.

Generating keys and certificates with OpenSSL

You don't have to trust the same CAs (certification authorities) that you are using for web browsing etc. By default GnuGk ignores the root certificates installed with OpenSSL on your server, but you can enable them by setting CADir=.

To have tight control over who you trust, you can generate your own CA using OpenSSL and only allow connections with certificates signed by your CA. Set you own CA with the CAFile= switch and leave CADir= unset.

To follow the step-by-step instructions, you need a definition file for your CA, called root.cnf and one for the server called server.cnf (see below). While following these steps, you will be asked a few times for the passphrase for the generated files. You should use the same for all of them and add it to your GnbuGk config with the Passphrase= switch.

First, generate your CA and self-sign it:

openssl req -newkey rsa:2048 -sha256 -keyout root_key.pem -out root_req.pem -config root.cnf
openssl x509 -req -in root_req.pem -sha256 -extfile root.cnf -days 365 -extensions certificate_extensions -signkey root_key.pem -out root_cert.pem

Then generate one key for each server or endpoint and sign them with the CA certificate:

openssl req -newkey rsa:2048 -sha256 -keyout server_key.pem -out server_req.pem -config server.cnf -reqexts req_extensions
openssl x509 -req -in server_req.pem -sha256 -extfile root.cnf -days 365 -extensions certificate_extensions -CA root_cert.pem -CAkey root_key.pem -CAcreateserial -out server_cert.pem
And then repeat to generate as many certificates as necessary.

The certificates generated above are valid for 365 days. Make sure you replace them before they expire, otherwise you won't be able to make calls!

To check then content of a generated certificate (eg. to see if it has expired or if the DNS name is OK), you can use

openssl x509 -text -in server_cert.pem

Here is a sample root.cnf file that you can adapt:

[ ca ]
default_ca       = gnugk_ca

[ gnugk_ca ]
dir              = /opt/gnugk-ca
certificate      = $dir/cacert.pem
database         = $dir/index.txt
new_certs_dir    = $dir/certs
private_key      = $dir/private/cakey.pem
serial           = $dir/serial
 
default_crl_days = 7
default_days     = 365
default_md       = sha256
 
policy           = gnugk_ca_policy
x509_extensions  = certificate_extensions
 
[ gnugk_ca_policy ]
commonName             = supplied
stateOrProvinceName    = supplied
countryName            = supplied
emailAddress           = supplied
organizationName       = supplied
organizationalUnitName = optional
 
[ req ]
default_bits        = 2048
default_keyfile     = privkey.pem
default_md          = sha256

prompt              = no
distinguished_name  = req_distinguished_name
x509_extensions     = req_extensions

# the following sections are specific to the request we're building

[ certificate_extensions ]
basicConstraints = CA:true
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always

[ req_distinguished_name ]
countryName         = US
stateOrProvinceName = Virginia
localityName        = Fairfax
organizationName    = Zork.org
commonName          = GnuGk Root CA

[ req_extensions ]
basicConstraints = CA:true

Here is a sample server.cnf file that you can adapt:

[ ca ]
default_ca       = gnugk_ca

[ gnugk_ca ]
dir              = /opt/gnugk-ca
certificate      = $dir/cacert.pem
database         = $dir/index.txt
new_certs_dir    = $dir/certs
private_key      = $dir/private/cakey.pem
serial           = $dir/serial
 
default_crl_days = 7
default_days     = 365
default_md       = sha256
 
policy           = gnugk_ca_policy
x509_extensions  = certificate_extensions
 
[ gnugk_ca_policy ]
countryName            = supplied
stateOrProvinceName    = supplied
localityName           = supplied
organizationName       = supplied
organizationalUnitName = optional
commonName             = supplied
emailAddress           = optional
 
[ req ]
default_bits        = 2048
default_keyfile     = privkey.pem
default_md          = sha256

prompt              = no
distinguished_name  = req_distinguished_name
x509_extensions     = req_extensions

# the following sections are specific to the request we're building       

[ certificate_extensions ]
basicConstraints = CA:false
subjectAltName = DNS:gk1.zork.org

[ req_distinguished_name ]
countryName            = US
stateOrProvinceName    = Virginia
localityName           = Fairfax
organizationName       = Zork.org
commonName             = gatekeeper.zork.org

[ req_extensions ]
basicConstraints = CA:true
subjectAltName = DNS:gk1.zork.org


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: 16. Nov 2017
Page maintained by Jan Willamowius