Next Previous Contents

12. Advanced Configuration

12.1 Section [CallTable]

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.

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

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.

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:

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.

12.7 Section [CTI::MakeCall]

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

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.

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:

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.

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.

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:

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:

Traps may have 3 optional data elements:

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.

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:

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.

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