OpenH323 Gatekeeper - The GNU Gatekeeper

Maintainer of this manual: Jan Willamowius <jan@willamowius.de>

This is the User Manual how to compile, install, configure and monitor OpenH323 Gatekeeper - The GNU Gatekeeper.

1. Introduction

1.1 About

OpenH323 Gatekeeper - The GNU Gatekeeper is an open-source project that implements an H.323 gatekeeper. A gatekeeper provides call control services to the H.323 endpoints. It is an integral part of most usefull internet telephony installations that are based on the H.323 standard.

According to Recommendation H.323, a gatekeeper shall provide the following services:

The GNU Gatekeeper implements most of these functions based on the OpenH323 protocol stack.

Recommendation H.323 is an international standard published by the ITU. It is a communications standard for audio, video, and data over the Internet. See also Paul Jones' primer on H.323.

For a detailed description of what a gatekeeper does, see here.

1.2 Copyright

It is covered by the GNU General Public License (GNU GPL). In addition to that, we explicitely grant the right to link this code to the OpenH323 and OpenSSL library.

Generally speaking, the GNU GPL allows you to copy, distribute, resell or modify the softwares, but it requires that all derived works must be published under GNU GPL also. That means that you must publish full source for all extensions to the gatekeeper and for all programs you include the gatekeeper into. See the file COPYING for details.

If that's not what you want, you must interface to the gatekeeper through the status port and communicate via TCP with it. That way you only have to integrate the basic funtionality into the gatekeeper (and provide source for that) and can keep other parts of your application private.

1.3 Name

The formal name of this project is OpenH323 Gatekeeper - The GNU Gatekeeper, short GnuGk. Please don't confuse it with other gatekeeper projects.

There are several open-source gatekeeper projects based on the OpenH323 protocol stack.

To have different gatekeepers with very similar names is really confusing for most users. Since our "OpenH323 Gatekeeper" was the first on the scene, it is not our fault that others have chosen similar names. But to make the destinction a little more clear without confusing people even more, we have decided to give the project a subtitle "OpenH323 Gatekeeper - The GNU Gatekeeper" and start using gnugk as name for executables.

1.4 Features

The version 2.2.1 contains the following new features and bugfixes:

The version 2.2.0 contains the following new features and bugfixes:

The version 2.2beta4 contains the following new features and bugfixes:

The version 2.2beta3 contains the following new features and bugfixes:

The version 2.2beta2 contains the following new features and bugfixes:

The version 2.2beta1 contains the following new features:

The version 2.0.6 has became a base for the new 2.2 gatekeeper version.

The version 2.0.6 is a bugfix release, plus the following enchancements:

The version 2.0.6 is a bugfix release, plus the following enchancements:

The version 2.0.5 is a bugfix release, plus the following enchancements:

The version 2.0.3 is a bugfix release, plus a little enhancement:

The new features added to version 2.0.2 are:

Of course, the major functions in version 2.0 are also included:

1.5 Download

The newest stable and a development version are available at the download page.

The very latest source code is in the CVS at Sourceforge ( Web-GUI). Beware - that's the bleeding edge.

You can also download some executables from the download page. Only some versions are made available as executables.

1.6 Mailing Lists

There are two mailing list for the project, one for the developers and one for the users.

General user questions should be send to the users mailing list. You can find the list archive here. To join this mailing list, click here.

To report problems or submit bugs/patches, send mails to the developers mailing list. The list archive is here. Please send user questions to the users mailinglist and keep this list to development! If you want to contribute to the project, please join the mailing list.

Note: Please don't send your questions as private emails to individual developer. We are usually busy. We would not like to be your private consultant, unless you'd like to pay us. Send your problems to the appropriate public mailing list so everybody can help you.

Also please don't send the GnuGk specific problems to the OpenH323 mailing list, or vice versa. They are different projects, though closely related.

Before you sending an email, make sure you have read the related documents carefully. Describe your problems clearly and precisely. Show us the error messages or logs if there is any.

1.7 Contributors

The current project coordinator is Jan Willamowius <jan@willamowius.de>

The main features and functions of version 2.0 are contributed by Chih-Wei Huang <cwhuang@linux.org.tw> and Citron Network Inc., including thread-safe registration and call tables, new routed mode architecture, H.323 proxy, H.235 authentication and MySQL backend.

Michal Zygmuntowicz <m.zygmuntowicz@onet.pl> has done some great work on Radius support and other improvements.

The initial version of the gatekeeper has been developed by Xiang Ping Chen, Joe Metzger and Rajat Todi.

2. Compiling and Installing

2.1 Compiling the Gatekeeper

To build the gatekeeper you need at least PWLib 1.5.0 and OpenH323 1.12.0 or later. The development version of the gatekeeper usually needs the most recent OpenH323 version available. These libraries are available at OpenH323 Download Page. See the instructions on how to compile the OpenH323 code.

Order of compiling:

  1. PWLib (release + debug version)
  2. OpenH323
  3. OpenH323 test application (not needed, just to make sure everything works so far)
  4. The Gatekeeper

On Unix do a configure and make debug or make opt in the gatekeeper directory to build debug or release version, respectively. Use make both to build both versions. Note you have to use GCC 3.3.x or later. The older version may not work. Good practice is to do a make debugdepend or make optdepend in the gatekeeper directory before starting actual compilation (make debug or make opt) - these commands build approtiate dependency lists, so after you will update your sources from CVS, all affected files will get recompiled. Otherwise you can finish with the Gatekeeper partially compiled with the older headers and partially with the updated headers - a very bad thing. On Windows just open and compile the provided project (gk.dsw) for Microsoft Visual C++ 6.0 or 7.0 (Visual C++ 5.0 is too old).

Type configure --help to see a detailed list of all compile time options. You can use them to enable or disable some features of the gatekeeper. For example, if you do not need RADIUS just type: configure --disable-radius.

To build the gatekeeper that is statically linked with system and OpenH323 libraries, make optnoshared or make debugnoshared has to be used.

In order to use the gatekeeper under heavy load, enabling LARGE_FDSET feature is recommended (configure --with-large-fdset=1024). Most systems also need kernel reconfiguration/recompilation in order to allow more than 1024 sockets to be allocated for a single process. Note that the PWLib library starting from version 1.5.3 supports a similar feature too, so you can choose between LARGE_FDSET GnuGk and PWLib implementation. GnuGk native implementation gives better performance results. Maximum LARGE_FDSET value should be calculated based upon predicted maximum sockets usage. A rule of thumb may be: 

MAX_NUMBER_OF_CONCURRENT_CALLS * 10 * 120%

Where:
10 = 2 sockets for Q.931 + 2 sockets for H.245 + 6 sockets for RTP and other stuff
So for 100 concurrent calls you don't need more than ca. 1024 sockets in the LARGE_FDSET.

2.2 Installing the Gatekeeper

There is no special installation procedure needed. Just copy the executable to the directory you like and create a config file for it. There are several config examples in the etc/ subdirectory of source tree. See section Configuration File for detailed explanations.

For example, in Linux x86 platform, the optimized executable gnugk is produced in obj_linux_x86_r/ subdirectory. You may copy it to /usr/sbin/, create a config in /etc/gnugk.ini and start it by 

$ /usr/sbin/gnugk -c /etc/gnugk.ini -o /var/log/gnugk.log -ttt
See section Command Line Options for details.

2.3 Pre-Built Binaries

If you do not wish to compile the gatekeeper from source, there are several pre-built `packages' available from SourceForge. Not all versions will be made available as binaries - check what is avilable.

Tar packages (.tgz or .tar.gz)

Download the tar file and enter the following command as root, substitute in the name of the file you downloaded. 

$ tar xvzf gnugk-x.x.x.tar

Debian packages (.deb)

Debian includes the gatekeeper as openh323gk package. You can install it by using the following command as root: 

$ apt-get install openh323gk

3. Getting Started (Tutorial)

3.1 A first simple experiment

To see that all components are up and running, get 2 Linux workstations, both connected to the LAN. Make sure you have at least version 1.1 of OpenH323 and OhPhone installed. On the first machine run the gatekeeper and ohphone (on different consoles): 

jan@machine1 > gnugk -ttt

Now the gatekeeper is running in direct mode. The "-ttt" option tells the gatekeeper to do a lot of debug output on the console (you can direct that output to a file with "-o logfile"). 

jan@machine1 > ohphone -l -a -u jan

Now this OhPhone is listening (-l) for calls and will automatically accept them (-a). It has registered as user jan with the gatekeeper that it will automatically detect. (If the auto detect fails for some reason use "-g 1.2.3.4" to specify the IP number the gatekeeper is running on.)

On the second machine run ohphone only: 

peter@machine2 > ohphone -u peter jan

The second instance of OhPhone registers with the auto detected gatekeeper as user peter and tries to call user jan. The gatekeeper will resolve the username to the IP number from where user jan has registered (machine1 in this case) and OhPhone will call the other instance of OhPhone on machine one.

The first instance of OhPhone will accept that call and Peter and Jan can chat.

3.2 Using the Status interface to monitor the gatekeeper

Now we try to see which messages are handled by the gatekeeper. On a new console on machine1 we use telnet to connect to the gatekeeper: 

jan@machine1 > telnet machine1 7000

Most probably we'll get an "Access forbidden!" message, because not everybody is allowed to spy.

Now we create a file called gatekeeper.ini and put it in the directory where we start the gatekeeper. gatekeeper.ini only contains 4 lines: 

[Gatekeeper::Main]
Fourtytwo=42
[GkStatus::Auth]
rule=allow

Stop the gatekeeper with Ctrl-C and restart it. When we do the telnet again, we stay connected with the gatekeeper. Now repeat the first experiment where Peter calls Jan and see which messages are handled by the gatekeeper in non-routed mode. There is a number of commands that can be issued in this telnet session: Type "help" to see them. To end the telnet session with the gatekeeper type "quit" and hit Enter.

3.3 Starting the gatekeeper in routed mode

Starting the gatekeeper in routed mode means that the gatekeeper uses "gatekeeper routed signalling" for all calls. In this mode the gatekeeper all signalling messages go through the gatekeeper and it has much greater control over the calls. 

jan@machine1 > gnugk -r

Now the gatekeeper is running in routed mode. Telnet to the status port and make a call to see what messages are now handled by the gatekeeper.

Note that all media packets (audio and video) are still sent directly between the endpoints (the 2 instances of ohphone).

Since gatekeeper routed signalling is much more complicated you are much more likely to hit a bug n the gatekeeper in this mode. But if it breaks, you get to keep the pieces. ;-)

3.4 A virtual PBX: Disconnecting calls

Until now the gatekeeper has only acted as a mechanism to resolve symbolic names to IP addresses. Thats an important function but hardly exciting.

Since the gatekeeper has a lot of control over the calls, it can terminate them for example. When we are connected to the status port, we can list all active calls with "PrintCurrentCalls". To terminate a call, we can say "Disconnectip 1.2.3.4" for one of its endpoints.

One could for example write a simple script that connects to the status port and listens for all ongoing calls and terminates them after 5 minutes, so no user can over use system resources.

Take a look at the other telephony functions like TransferCall to see what else is available.

3.5 Routing calls over a gateway to reach external users

Without using a gateway you can only call other people with an IP phone over the Internet. To reach people with ordinary telephones you must use a gateway. 

_________________          ______________
| endpoint "jan"|          |            |
| 192.168.88.35 |--------->| Gatekeeper |
|_______________|          |            |
_________________          |            |
| gateway "gw1" | outgoing |            |
| 192.168.88.37 |<---------|____________|
|_______________|

The gatekeeper has to know which calls are supposed to be routed over the gateway and what numbers shall be called directly. Use the [RasSrv::GWPrefixes] section of the config file to tell the gatekeeper the prefix of numbers that shall be routed over the gateway. 

[RasSrv::GWPrefixes]
gw1=0

This entry tells the gatekeeper to route all calls to E.164 numbers starting with 0 to the gateway that has registered with the H.323 alias "gw1". If there is no registered gateway with that alias the call will fail. (Note that you must use the gateway alias - you can't just tell the gatekeeper the IP number of the gateway.)

A prefix can contain digits 0-9, # and *. It can also contain a special character . (a dot) that matches any digit and can be prefixed with ! (an exclamation mark) to disable the prefix. Prefix matching is done accordingly to the longest matching prefix rule, with ! rules having higher priority if lengths are equal. Some examples: 

[RasSrv::GWPrefixes]
; This entry will route numbers starting with 0048 (but not with 004850 and 004860)
; to the gw1
gw1=0048,!004850,!004860
; This entry will match only 001 with 10 digits following
gw2=001..........

3.6 Rewriting E.164 numbers

When using a gateway you often have to use different numbers internally and rewrite them before sending them over a gateway into the telephone network. You can use the RasSrv::RewriteE164 section to configure that.

Example: You want to call number 12345 with you IP Phone and would like to reach number 08765 behind a gateway called "gw1". 

[RasSrv::GWPrefixes]
gw1=0

[RasSrv::RewriteE164]
12345=08765

You can also configure rewriting of E.164 numbers based on which gateway you are receiving a call from or sending a call to using the RasSrv::GWRewriteE164 section.

Example: You have two different gateways ("gw1" and "gw2") which you are sending calls with prefix 0044 to, but which require a different prefix to be added to the number after the routing has selected the gateway. This might be for identification purposes for example. 

[RasSrv::GWPrefixes]
gw1=0044
gw2=0044

[RasSrv::GWRewriteE164]
gw1=out=0044=77770044
gw2=out=0044=88880044

Example: You want to identify calls from a particular gateway "gw1" with a specific prefix before passing these calls to another gateway "gw2". 

[RasSrv::GWPrefixes]
gw2=1

[RasSrv::GWRewriteE164]
gw1=in=00=123400

Rewrite expressions accept dot '.' and percent sign '%' wildcard characters to allow building more general rules. The dot character can occur at both left and right hand sides of expressions, the percent sign can occur only at the left side only. Use '.' to match any character and copy it to the rewritten string and '%' to match any character and skip it. A few simple examples: 

[RasSrv::RewriteE164]
; Rewrite 0044 + min. 7 digits to 44 + min. 7 digits
0044.......=44.......
; Rewrite numbers starting with 11 + 4 digits + 11  to 22 + 4 digits + 22 (like 11333311 => 22333322, 110000112345 => 220000222345)
11....11=22....22
; strip the first four digits from all numbers (11114858345 => 4858345)
; this is equivalent of 10 rules %%%%1=1, %%%%2=2, ... 
%%%%.=.
; insert two zeros in the middle of the number (111148581234 => 11110048581234)
....48=....0048
; even this is possible (415161 => 041051061)
4.5.6=04.05.06

4. Using the Gatekeeper (Reference)

The behavior of the gatekeeper is completely determined by the command line options and configuration file. Some command line options may override the setting of the configuration file. For example, the option -l overrides the setting TimeToLive in the configuration file.

4.1 Command Line Options

Almost every option has a short and a long format, e.g., -c is the same as --config.

Basic

-h --help

Show all available options and quit the program.

-c --config filename

Specify the configuration file to use.

-s --section section

Specify which main section to use in the configuration file. The default is [Gatekeeper::Main].

-i --interface IP

Specify the interface (IP number) that the gatekeeper listens to. You should leave out this option to let the gatekeeper automatically determine the IP it listens to, unless you want the gatekeeper only binds to a specified IP.

-l --timetolive n

Specify the time-to-live timer (in seconds) for endpoint registration. It overrides the setting TimeToLive in the configuration file. See there for detailed explanations.

-b --bandwidth n

Specify the total bandwidth available for the gatekeeper. Without specifying this option, the bandwidth management is disable by default.

--pid filename

Specify the pid file, only valid for Unix version.

-u --user name

Run the gatekeeper process as this user. Only valid for Unix versions.

Gatekeeper Mode

The options in this subsection override the settings in the [RoutedMode] section of the configuration file.

-d --direct

Use direct endpoint call signalling.

-r --routed

Use gatekeeper routed call signalling.

-rr --h245routed

Use gatekeeper routed call signalling and H.245 control channel.

Debug Information

-o --output filename

Write trace log to the specified file.

-t --trace

Set trace verbosity. The more -t you add, the more verbose to output. For example, use -ttttt to set the trace level to 5.

4.2 Configuration File

The configuration file is a standard text file. The basic format is: 

[Section String]
Key Name=Value String

Comments are marked with a hash (#) or a semicolon (;) at the beginning of a line.

The file complete.ini contains all available sections for the GnuGk. In most cases it doesn't make sense to use them all at once. The file is just meant as a collection of examples for many settings.

The configuration file can be changed at runtime. Once you modify the configuration file, you may issue reload command via status port, or send a signal HUP to the gatekeeper process on Unix. For example, 

kill -HUP `cat /var/run/gnugk.pid`

Note Some section names in GnuGk 2.0.0 are named [RasSrv::*], while others are named [RasSvr::*]. This inconsistency confused users. In 2.0.1 all sections are corrected to [RasSrv::*]. If you upgrade from 2.0.0 or earlier version, remember to change the section names, or GnuGk will refuse to start.

Section [Gatekeeper::Main]

Most users will never need to change any of the following values. They are mainly used for testing or very sophisticated applications.

Section [LogFile]

This section defines log file related parameters. Currently it allows users to specify log file rotation options.

Section [RoutedMode]

Call signalling messages may be passwd in two ways. The first method is Direct Endpoint Call Signalling, in which case the call signalling messages are passed directly between the endpoints. The second method is Gatekeeper Routed Call Signalling. In this method, the call signalling messages are routed through the gatekeeper between the endpoints. The choice of which methods is used is made by the gatekeeper.

When Gatekeeper Routed call signalling is used, the gatekeeper may choose whether to route the H.245 control channel and logical channels.

Case I.

The gatekeeper doesn't route them. The H.245 control channel and logical channels are established directly between the endpoints.

Case II.

The H.245 control channel is routed between the endpoints through the gatekeeper, while the logical channels are established directly between the endpoints.

Case III.

The gatekeeper routes the H.245 control channel, as well as all logical channels, including RTP/RTCP for audio and video, and T.120 channel for data. In this case, no traffic is passed directly between the endpoints. This is usually called an H.323 Proxy, which can be regarded as an H.323-H.323 gateway.

This section defines the gatekeeper routed mode options (case I & II). The proxy feature is defined in the next section. All settings in this section are affected by reloading.

Section [Proxy]

The section defines the H.323 proxy features. It means the gatekeeper will route all the traffic between the calling and called endpoints, so there is no traffic between the two endpoints directly. Thus it is very useful if you have some endpoints using private IP behind an NAT box and some endpoints using public IP outside the box.

The gatekeeper can do proxy for logical channels of RTP/RTCP (audio and video) and T.120 (data). Logical channels opened by fast-connect procedures or H.245 tunnelling are also supported.

Note to make proxy work, the gatekeeper must have direct connection to both networks of the caller and callee.

Section [RoutingPolicy]

This section explains how the various possible routing policies within the gatekeeper work.

The incoming call requests can be routed using a number of routing providers:

If one policy does not match, the next policy is tried.

These policies can be applied to a number of routing request types, and routing input data. The different types are: ARQ, LRQ, Setup and Facility (with the callForwarded reason) There is also the general routing policy, which is kind of a default for the other types.

Example:

[RoutingPolicy]
h323_ID=dns,internal
002=neighbor,internal
Default=internal,neighbor,parent

When one of the messages is received which calls for a routing decision, all calls to an alias of the h323_ID type will be resolved using DNS. If DNS fails to resolve the alias, it is matched against the internal registration table. If a call is requested to an alias starting with 002, first the neighbours are checked and then the internal registration table. If the requested alias is not an h323_ID or an alias starting with 002, the default policy is used by querying the internal registration table, then the neighbours, and if that fails the parent.

For the ARQ, LRQ, Setup and Facility messages one would use the [RoutingPolicy::OnARQ], [RoutingPolicy::OnLRQ], [RoutingPolicy::OnSetup] and [RoutingPolicy::OnFacility] sections using the syntax explained above.

Section [GkStatus::Auth]

Define a number of rules who is allowed to connect to the status port. Whoever has access to the status port has full control over your gatekeeper. Make sure this is set correctly.

Section [RasSrv::GWPrefixes]

This section lists what E.164 numbers are routed to a specific gateway.

Format:

gw-alias=prefix[,prefix,...]

Note you have to specify the alias of the gateway. If a gateway registered with the alias, all numbers beginning with the prefixes are routed to this gateway. Special characters . and ! can be used here to match any digit and disable the prefix.

Example:

test-gw=02,03

Section [RasSrv::RewriteE164]

This section defines the rewriting rules for dialedDigits (E.164 number).

Format:

[!]original-prefix=target-prefix[,target-prefix,...]

If the number is beginning with original-prefix, it is rewritten to target-prefix. Multiple targets are possible. If the `!' flag precedes the original-prefix, the sense is inverted and the target-prefix is prepended to the dialed number. Special wildcard characters ('.' and '%') are available.

Example:

08=18888

If you dial 08345718, it is rewritten to 18888345718.

Example:

!08=18888

If you dial 09345718, it is rewritten to 1888809345718.

Option:

Section [RasSrv::GWRewriteE164]

This section describes rewriting the dialedDigits E.164 number depending on the gateway a call has come from or is being sent to. This allows for more flexible manipulation of the dialedDigits for routing etc. In combination with the RasSrv::RewriteE164 you can have triple stage rewriting: 

Call from "gw1", dialedDigits 0867822
                |
                |
                V
Input rules for "gw1", dialedDigits now 550867822
                |
                |
                V
Global rules, dialedDigits now 440867822
                |
                |
                V
Gateway selection, dialedDigits now 440867822, outbound gateway "gw2"
                |
                |
                V
Output rules for "gw2", dialedDigits now 0867822
                |
                |
                V
Call to "gw2", dialedDigits 0867822

Format:

gw-alias=in|out=[!]original-prefix=target-prefix[;in|out...]

If the call matches the gateway, the direction and begins with original-prefix it is rewritten to target-prefix. If the `!' flag precedes the original-prefix, the sense is inverted. Special wildcard characters ('.' and '%') are available. Multiple rules for the same gateway should be seperated by ';'.

Example:

gw1=in=123=321

If a call is received from "gw1" to 12377897, it is rewritten to 32177897 before further action is taken.

Section [RasSrv::PermanentEndpoints]

In this section you can put endpoints that don't have RAS support or that you don't want to be expired. The records will always keep in registration table of the gatekeeper. However, You can still unregister it via status port. Special characters . and ! can be used with prefixes here to match any digit and disable the prefix.

Format:

IP[:port]=alias[,alias,...;prefix,prefix,...]

Example:

For gateway,

10.0.1.5=Citron;009,008
For terminal,
10.0.1.10:1720=700

Section [RasSrv::Neighbors]

If the destination of an ARQ is unknown, the gatekeeper sends LRQs to its neighbors to ask if they have the destination endpoint. A neighbor is selected if one of its prefixes matches the destination or it has ``*'' prefix. More than one prefix can be specified. You can use special characters ``.'' and ``!'' to do wildcard matching and disable a specific prefix.

Conversely, the gatekeeper will only reply to LRQs sent from neighbors defined in this section. If you specify an empty prefix, no LRQ will be sent to that neighbor, but the gatekeeper will accept LRQs from it. By the empty prefix it is meant a single semicolon appended to the neighbor entry. Example:

GK1=192.168.0.5;

If you skip the semicolon, LRQs will be always sent to this neighbor.

The password field is used to authenticate LRQs from that neighbor. See section [Gatekeeper::Auth] for details.

Neighbor handling has changed significantly from version 2.0 to version 2.2. Neighbors can be specified now in two ways - the old one and the new one.

Entry in the old format:

GKID=ip[:port;prefixes;password;dynamic]

Example:

GK1=192.168.0.5;*
GK2=10.0.1.1:1719;035,036;gk2
GK3=gk.citron.com.tw;;gk3;1

Entry in the new format:

GKID="GnuGK" | "CiscoGK" | "ClarentGK" | "GlonetGK"

Example:

[RasSrv::Neighbors]
GK1=CiscoGK
GK2=GnuGK

[Neighbor::GK1]
GatekeeperIdentifier=GK1
Host=192.168.1.1
SendPrefixes=02
AcceptPrefixes=*
ForwardLRQ=always

[Neighbor::GK2]
GatekeeperIdentifier=GK2
Host=192.168.1.2
SendPrefixes=03,0048
AcceptPrefixes=0049,001
ForwardHopCount=2
ForwardLRQ=depends

The new format specifies in [RasSrv::Neighbors] section only gatekeeper types and configuration for each neighbor is placed in a separate section.

Section [RasSrv::LRQFeatures]

Defines some features of LRQ and LCF.

Section [Neighbor::...]

Sections starting with [Neighbor:: are for neighbor specific configuration.

Section [RasSrv::RRQFeatures]

Section [RasSrv::ARQFeatures]

Section [CallTable]

Section [Endpoint]

The gatekeeper can work as an endpoint by registering with another gatekeeper. With this feature, you can easily build gatekeeper hierarchies. The section defines the endpoint features for the gatekeeper.

Section [Endpoint::RewriteE164]

Once you specify prefix(es) for your gatekeeper endpoint, the parent gatekeeper will route calls with dialedDigits beginning with that prefixes. The child gatekeeper can rewrite the destination according to the rules specified in this section. By contrast, when an internal endpoint calls an endpoint registered to the parent gatekeeper, the source will be rewritten reversely.

Format:

external prefix=internal prefix

For example, if you have the following configuration, 

                        [Parent GK]
                        ID=CitronGK
                        /         \
                       /           \
                      /             \
                     /               \
                [Child GK]          [EP3]
                ID=ProxyGK          E164=18888200
                Prefix=188886
                /       \
               /         \
              /           \
           [EP1]         [EP2]
           E164=601      E164=602

With this rule: 

188886=6

When EP1 calls EP3 by 18888200, the CallingPartyNumber in the Q.931 Setup will be rewritten to 18888601. Conversely, EP3 can reach EP1 and EP2 by calling 18888601 and 18888602, respectively. In consequence, an endpoint registered to the child GK with prefix '6' will appear as an endpoint with prefix '188886', for endpoints registered to the parent gatekeeper.

The section does not relate to the section RasSrv::RewriteE164, though the later will take effect first.

Section [Gatekeeper::Auth]

The section defines the authentication mechanism for the gatekeeper.

Syntax:

authrule=actions

 <authrule> := SimplePasswordAuth | AliasAuth | PrefixAuth | RadAuth | RadAliasAuth | ...
 <actions>  := <control>[;<ras>|<q931>,<ras>|<q931>,...]
 <control>  := optional | required | sufficient
 <ras>      := GRQ | RRQ | URQ | ARQ | BRQ | DRQ | LRQ | IRQ
 <q931>     := Setup | SetupUnreg
A rule may results in one of the three codes: ok, fail, pass. There are also three ways to control a rule:

Currently supported modules:

You can also configure a rule to check only for some particular RAS messages. The following example configures SimplePasswordAuth as an optional rule to check RRQ and ARQ. If an RRQ is not checked (not contains tokens or cryptoTokens fields), it is checked by AliasAuth. The default is to accept all requests.

Example 1:

SimplePasswordAuth=optional;RRQ,ARQ
AliasAuth=sufficient;RRQ

The example below authenticates all calls, checking signalling Setup message details, using RadAliasAuth module.

Example 2:

RadAliasAuth=required;Setup
default=allow

This example checks endpoint registrations (RRQ) and call admissions (ARQ) either by means of username/password (RadAuth) or alias/IP (RadAliasAuth). Additionally, if the call is from an unregistered endpoint (and therefore no RRQ or ARQ authentication has been performed), Setup message authentication using RadAliasAuth takes place (SetupUnreg).

Example 3:

RadAuth=optional;RRQ,ARQ
RadAliasAuth=required;RRQ,ARQ,SetupUnreg
default=allow

Section [SimplePasswordAuth]

The section defines the userid and password pairs used by SimplePasswordAuth module. Use `make addpasswd' to generate the utility addpasswd.

Usage: 

addpasswd config userid password

Options:

Section [SQLPasswordAuth]

Authenticate H.235 enabled endpoints using passwords stored in the SQL database. This section defines SQL driver to use, SQL database connection parameters and the query to use to retrieve passwords.

Section [MySQLPasswordAuth]

Define the MySQL database, table and fileds to retrieve the userid and password. This is obsolete, use [SQLPasswordAuth] instead.

The SQL command will be issused: 

SELECT $DataField FROM $Table WHERE $KeyField = %id [AND $ExtraCriterion]

Section [RasSrv::RRQAuth]

Specify the action on RRQ reception (confirm or deny) for AliasAuth module. The first alias (this will mostly be an H323ID) of the endpoint to register is looked up in this section. If a parameter is found the value will apply as a rule. A rule consists of conditions separated by "&". A registration is accepted when all conditions apply.

Syntax:

<authrules> :=  empty  |  <authrule> "&" <authrules>

  <authrule>  := <authtype> ":" <authparams>
  <authtype>  := "sigaddr" | "sigip"
  <autparams> := [!&]*

The notation and meaning of <authparams> depends on <authtype>:

Section [SQLAliasAuth]

Authenticate endpoints using rules stored in the SQL database (the rules conform to the format defined in the [RasSrv::RRQAuth] section). This section defines SQL driver to use, SQL database connection parameters and the query to use to retrieve the patterns.

Section [MySQLAliasAuth]

Define the MySQL database, table and fileds to retrieve a pattern for an alias. This section is OBSOLETE and provided only for backward compatibility. Please use [SQLAliasAuth] instead.

The SQL command will be issused: 

SELECT $DataField FROM $Table WHERE $KeyField = %alias [AND $ExtraCriterion]

Section [PrefixAuth]

The section defines the authentication rule for PrefixAuth module. Currently, only ARQs and LRQs can be authorized by this module.

First, a most specific prefix is selected according to the destinationInfo field of the received request. Then the request is accepted or rejected according to the matched rules with most specific netmask. If no matched prefix is found, and the default option is specified, the request is accepted or rejected according to that. Otherwise it is rejected or passed to next authentication module according to the module requirement.

Format:

prefix=authrule[|authrule|...]

Syntax:

<authrule> :=  <result> <authrule>

  <result>    := deny | allow
  <authrule>  := [!]ipv4:<iprule> | [!]alias:<aliasrule>
Where <iprule> can be specified in decimal dot notation or CIDR notation, <aliasrule> is expressed in regular expression. If the `!' flag precedes the rule, the sense is inverted.

Example:

555=deny ipv4:10.0.0.0/27|allow ipv4:0/0
5555=allow ipv4:192.168.1.1|deny ipv4:192.168.1.0/255.255.255.0
86=deny !ipv4:172.16.0.0/24
09=deny alias:^188884.*
ALL=allow ipv4:ALL

In this configuration, all endpoints except from network 10.0.0.0/27 are allow to call prefix 555 (except 5555). Endpoints from 192.168.1.0/24 are not allowed to call prefix 5555, except 192.168.1.1. Endpoints not from 172.16.0.0/24 are denied to call prefix 86. Endpoints having an alias beginning with 188884 are not allowed to call prefix 09. All other situations are allowed.

Section [RadAuth]

This section defines configuration settings that enable RADIUS authentication based on H.235 CATs (Cisco Access Tokens) present in RRQ, ARQ RAS requests and Q.931 Setup messages.

Section [RadAliasAuth]

This section defines configuration settings that enable RADIUS authentication based on endpoint aliases and/or IP adresses present in RRQ RAS requests, ARQ RAS request or Q.931 Setup request. This authentication scheme is useful both for endpoints registered at the gatekeeper (ARQ,RRQ) and calls from unregistered endpoints (Setup).

Section [GkLDAP::LDAPAttributeNames]

This section defines which LDAP attribute names to use.

Section [GkLDAP::Settings]

This section defines the LDAP server and standard LDAP client operating parameters to be used.

Section [Gatekeeper::Acct]

The section defines a list of modules that will be performing accounting. The accounting is for logging gatekeeper on/off events and call start/stop/update events. Each accounting module logs received events to a module specific storage. Such storage can be a plain text file or a RADIUS server and many more. The configuration is very similar to the one for gatekeeper authentication (see [Gatekeeper::Auth]).

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

Syntax:

acctmod=actions

 <acctmod> := FileAcct | RadAcct | SQLAcct | ...
 <actions> := <control>[;<event>,<event>,...]
 <control> := optional | required | sufficient | alternative
 <event>   := start | stop | connect | update | on | off
The event list tells the gatekeeper, which events should trigger logging with the given accounting module (if an event type is supported by the module): An event logging by a module may results in one of the three result codes: ok, fail, next. Accounting modules can be stacked to log events by multiple modules or to create failover setups. control flag for each module, along with result codes, define what is the final status of the event processing by the whole module stack. If the final result is failure, some special actions may take place. Currently, if a call start event logging fails, the call is disconnected immediatelly. The following control flags are recognized:

Currently supported accounting modules:

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

Example:

RadAcct=optional;start,stop
FileAcct=required

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

Example:

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

The default rule is required here to prevent calls from being rejected because of RadAcct start event logging failure. If RadAcct returns fail return code, it is passed down to FileAcct module. FileAcct module does not support start events, so it returns next return code. If there were no the default rule, the final status would be failure, because no module has been able to log the event.

The sample configuration #3 (always log call start and stop events with RADIUS server, if it fails for call stop event, use a CDR file to store call info):

Example:

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

The default rule is optional here. If RadAcct returns fail return code for start event, the code is passed down to FileAcct module. FileAcct module does not support start events, so it returns next return code. The default rule ensures, that the call is disconnected if call start event could not has been logged with RadAcct. But we want to store a CDR in a text file in case the RADIUS server is down when the call disconnects, so we can fetch call duration into a billing system later.

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

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

Section [SQLAcct]

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

Section [NATedEndpoints]

The gatekeeper can automatically detect whether an endpoint is behind NAT. However, if the detection fails, you can specify it manually in this section.

Format:

alias=true,yes,1,...

Example:

Specify an endpoint with alias 601 is behind NAT.

601=true

Section [CTI::Agents]

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

Upon arrival of an ARQ on a virtual queue, the gatekeeper signals a RouteRequest on the status port and waits for an external application to respond with either a RouteReject (then the ARQ will be rejected) or with RouteToAlias/RouteToGateway which leads to the ARQ 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:

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

4.3 Per-Endpoint Configuration Settings

In addition to the standard configuration file options, per-endpoint configuration settings can be specified in the config file. The syntax is as follows: 

[EP::ALIAS]
Key Name=Value String

ALIAS is replaced with an actual alias for an endpoint the settings should apply to. Currently, the following options are recognized:

Example: 

[RasSrv::PermanentEndpoints]
192.168.1.1=gw1;48
192.168.1.2=gw2;48,!4850,!4860,!4869,!4888

[EP::gw1]
Capacity=60
GatewayPriority=1

[EP::gw2]
Capacity=30
GatewayPriority=2

In this example, calls will be sent to the gateway gw1 until its capacity is fully utilized (60 concurrent calls) and then to the gateway gw2.

5. Monitoring the Gatekeeper (Reference)

5.1 Status Port

The status port is the external interface for monitoring and controlling the gatekeeper. The gatekeeper will send out messages about ongoing calls to all connected clients and it can receive commands via this interface.

The messages sent by the gatekeeper to the status port are groupped into three output trace levels:

The client connected to the status port can choose the output level it is interested in.

The interface is a simple TCP port (default: 7000), you can connect to with telnet or another client. One example of a different client is the Java GUI, aka GkGUI. Another example is the Automatic Call Distribution application, aka GnuGk ACD.

Application Areas

What you do with the powers of the Status Interface is up to you, but here are a few ideas:

Examples

Suppose you are just interested in the CDRs (call details records) and want to process them as a batch at regular intervals.

Here is a simple Perl script (gnugk_cdr.pl) that starts the gatekeeper and also forks a very simple client for the Status Interface and writes just the CDRs into a logfile. You'll have to modify it a little to fit your needs. 

#!/usr/bin/perl
# sample program that demonstrates how to write the CDRs to a log file
use strict;
use IO::Socket;
use IO::Handle;

my $logfile = "/home/jan/cdr.log";      # CHANGE THIS
my $gk_host = "localhost";
my $gk_port = 7000;
my $gk_pid;

if ($gk_pid = fork()) {
        # parent will listen to gatekeeper status
        sleep(1);       # wait for gk to start
        my $sock = IO::Socket::INET->new(PeerAddr => $gk_host, PeerPort => $gk_port, Proto => 'tcp');
        if (!defined $sock) {
                die "Can't connect to gatekeeper at $gk_host:$gk_port";
        }
        $SIG{HUP} = sub { kill 1, $gk_pid; };   # pass HUP to gatekeeper
        $SIG{INT} = sub { close (CDRFILE); kill 2, $gk_pid; };  # close file when terminated

        open (CDRFILE, ">>$logfile");
        CDRFILE->autoflush(1);  # don't buffer output
        while (!$sock->eof()) {
                my $msg = $sock->getline();
                $msg = (split(/;/, $msg))[0];   # remove junk at end of line
                my $msgtype = (split(/\|/, $msg))[0];
                if ($msgtype eq "CDR") {
                        print CDRFILE "$msg\n";
                }
        }
        close (CDRFILE);
} else {
        # child starts gatekeeper
        exec("gnugk");
}

Keep in mind that this is just an example to show the usage of the status port. You can use the FileAcct module to log CDRs in a production system.

GUI for the Gatekeeper

There are several Graphical User Interface (GUI) frontends for the gatekeeper.

5.2 Commands (Reference)

This section lists all commands that you can isue to the status port (manually or with an external application). All commands are case-insensitive. But some parameters may be case-sensitive.

The command help or h will show you a list of all available commands.

5.3 Messages (Reference)

The section describes the messages output to the status interface.