This is the manual for GNU Gatekeeper 4.9.
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 3

3. Getting Started (Tutorial)

3.1 A simple first call

To confirm that all components are up and running, we will use two Linux workstations, both connected to the same LAN. In the examples, the H.323 client is a softphone called "SimpH323" which comes as a sample application with H323Plus in the samples/simple/ folder. If your Linux distribution doesn't include it, you can download the H323Plus source code and compile it yourself or you can use another H.323 endpoint.

On the first server start the gatekeeper in direct mode:

jan@server1> gnugk -ttt

The "-ttt" option tells the gatekeeper that it should be verbose and print extra debug output to the console. You can direct the output to a file with "-o logfilename.log"

Now, start SimpH323 on another console on the same system:

jan@server1> simph323 -l --listenport 1722 -a -u jan

SimpH323 is now listening (-l) for calls and will automatically accept them (-a). It has also registered with the gatekeeper as user "jan" thereby allowing the gatekeeper to creating an association between the user "jan" and their IP address.

SimpH323 will attempt to automatically locate the gatekeeper, but if the auto detection fails, use "-g" to specify the IP address.

On the second client run simph323 this way:

peter@client2> simph323 --listenport 1724 -u peter jan

This instance of SimpH323 registers with the auto-detected gatekeeper as user "peter" and tries to call user "jan". The gatekeeper will accept the request from "peter" and will determine if it can locate the IP address of a user name "jan".

Because "jan" has already registered with the gatekeeper, it will send "jan"s IP address to "peter". "peter"s SimpH323 will then use that IP address to setup a direct session to "jan"s SimpH323 running on server1.

The instance of SimpH323 on server1 will automatically accept the call and Peter and Jan can chat.

3.2 Using the Status interface to monitor the gatekeeper

The status interface presents a text-based means of interacting with an already-running gatekeeper.

On a new console we use telnet to connect to the gatekeeper:

jan@server1> telnet localhost 7000

You should receive an "Access forbidden!" message because by default, access to the status port is restricted.

Create a file called gatekeeper.ini in the directory where we start the gatekeeper. gatekeeper.ini will contain the following three lines:


Stop the gatekeeper with Ctrl-C and restart it, but specify that it should use the gatekeeper.ini we just created:

jan@server1> gnugk -ttt -c ./gatekeeper.ini

Use telnet to connect to port 7000 and you should now be allowed to connect to the gatekeeper:

jan@server1>  telnet localhost 7000
Connected to localhost.
Escape character is '^]'.
Gatekeeper(GNU) Version(2.3.5) Ext(pthreads=1,radius=1,mysql=0,pgsql=0,firebird=0,odbc=0,sqlite=0,
large_fdset=0,crypto/ssl=0,h46018=1,h46023=1,ldap=0,ssh=0) H323Plus(1.22.2) PTLib(2.8.5)
Build(Jul 31 2011, 09:03:11) Sys(Linux x86_64 2.6.32-33-generic)
Startup: Sun, 31 Jul 2011 08:07:36 -0600   Running: 102 days 01:08:15

Now repeat the first experiment where Peter calls Jan and see which messages are handled by the gatekeeper in non-routed mode.

There are a number of commands that can be issued in the telnet session - type "help" to see them.

To end the telnet session with the gatekeeper type "quit" and hit Enter.

The example configuration file we created is very insecure because it has a default allow rule, so there are no restrictions on who can connect to the status port and which commands they may execute.

Change the configuration file to:


The fourth line was added by the addpasswd utility, which was used to create a user "gkadmin" with password "secret". This change now enforces authentication to the status port.

Restart the gatekeeper with this new configuration and perform the telnet again. You should now be prompted for a username and password:

jan@server1>  telnet localhost 7000
Connected to localhost.
Escape character is '^]'.

GnuGk login: gkadmin
Password: secret
Gatekeeper(GNU) Version(2.3.5) Ext(pthreads=1,radius=1,mysql=0,pgsql=0,firebird=0,odbc=0,sqlite=0,
large_fdset=0,crypto/ssl=0,h46018=1,h46023=1,ldap=0,ssh=0) H323Plus(1.22.2) PTLib(2.8.5)
Build(Jul 31 2011, 09:03:11) Sys(Linux x86_64 2.6.32-33-generic)
Startup: Sun, 31 Jul 2011 08:07:36 -0600   Running: 102 days 01:10:15

The [GkStatus::Auth] section contains additional information on securing the status port.

3.3 Running the gatekeeper in routed mode

Starting the gatekeeper in routed mode means that the gatekeeper uses "gatekeeper routed signaling". All signaling messages go through the gatekeeper, giving it much greater control over the calls.

Start GnuGk like this:

jan@server2> gnugk -r

will put the gatekeeper 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 SimpH323).

3.4 Routing calls to 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"|          |            |
| |--------->| Gatekeeper |
|_______________|          |            |
_________________          |            |
| gateway "gw1" | outgoing |            |
| |<---------|____________|

The gatekeeper must be configured to specify which calls should be routed to the gateway and which numbers can be called directly. Use the [RasSrv::GWPrefixes] section of the config file to tell the gatekeeper the prefix of numbers that should be routed to the gateway.


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: You must use the gateway alias - you cannot use the IP address 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 according to the longest matching prefix rule, with ! rules having higher priority if lengths are equal. You may also use := syntax to set the priority between several gateways matching the same prefix (see section [RasSrv::GWPrefixes] for details). Some examples:

; This entry will route numbers starting with 0048 (but not with 004850 and 004860)
; to gw1
; This entry will match only 001 with 10 digits following and route the call to
; gw2

3.5 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 your IP Phone and would like to reach number 08765 behind a gateway called "gw1".



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.



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



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

; Rewrite 0044 + min. 7 digits to 44 + min. 7 digits
; Rewrite numbers starting with 11 + 4 digits + 11  to 22 + 4 digits + 22
; (like 11333311 => 22333322, 110000112345 => 220000222345)
; 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)
; even this is possible (415161 => 041051061)

3.6 Firewalls and NAT

The H.323 protocol places IP numbers inside the signaling messages and establishes multiple TCP and UDP connections for a single call. You can't even be sure beforehand of the direction in which some of these connections are established. This makes it harder to get H.323 through a NAT than other protocols.

To get through firewalls and NATs, GnuGk supports a lot of different traversal methods and protocols. The combination of H.460.18 and H.460.19 (usually called "H.460 NAT traversal" for short) is by far the most common NAT traversal protocol and is supported by virtually all H.323 endpoints today.

The best approach is to place a GNU Gatekeeper on a public IP address in front of your firewall and enable H.460.18 NAT traversal. You don't have to open any inbound port - just allow outgoing connections in your firewall, which is usually the default anyway.

If you have a highly configurable firewall, make sure you don't set the NAT timeouts too low: H.460.18 assumes that GnuGk can send a UDP packet to the same port where it received a packet from for at least 30 seconds. If you set your firewall rules to 90 seconds you are on the safe side. Most consumer products work with much longer timeouts, so you don't have to worry.

If not all of your endpoints support H.460.18 or if you have a lot of internal calls, you can place a 2nd GnuGk inside your firewall and let it tunnel calls out for all internal endpoints combined. This called a "traversal zone". See later chapters how to configure the outside GnuGk as traversal server and the GnuGk inside the firewall as traversal client.

A simple, one gatekeeper configuration for NAT traversal looks like this:




Register all your endpoints with the gatekeeper, whether they are inside or outside the firewall, and you should be able to make calls in and out.

3.7 A virtual PBX: Disconnecting calls

Until now the gatekeeper has acted only as a mechanism to resolve symbolic names to IP addresses. This is a critical function of a gatekeeper, but the gatekeeper is capable of much more.

Because the gatekeeper has a lot of control over the calls, it can also be used to terminate them. While connected to the status port, you can list all active calls with "PrintCurrentCalls". To terminate a call, type "Disconnectip" for one of the endpoints.

For example, a simple script could be written to connect to the status port, obtain a list of ongoing calls and terminate them after 5 minutes to prevent users from using too many system resources.

Other functions such as TransferCall are also available.

3.8 Using IPv6

To use IPv6 with GnuGk, you must enable it in the config file:


Calls between IPv4 and IPv6 endpoints are automatically put into proxy-mode to allow GnuGk to perform address translation. If your endpoints can automatically handle mixed IPv4-IPv6 calls the auto-proxying can be disabled using the AutoProxyIPv4ToIPv6Calls switch in the [RoutedMode] section. As of 2011-11-10 there don't appear to be any endpoints which can do this.

Make sure you assign regular IPv6 addresses to your server. GnuGk won't use any link-local addresses (fe80::/10).

To support IPv4 and IPv6 endpoints at the same time, GnuGk relies on the operating system to manage IPv4 mapped IPv6 addresses. With a few exception, most current operating systems support this.

Operating System Overview:

  • Linux OK
  • Windows 7 OK
  • Windows Server 2008 OK
  • Windows Vista OK
  • Windows XP either IPv4 or IPv6
  • FreeBSD OK
  • NetBSD OK
  • OpenBSD either IPv4 or IPv6
  • Solaris OK

For Windows, you need at least Windows Vista, Windows Server 2008, Windows 7 or newer. On Windows XP GnuGk will run as a IPv6-only gatekeeper if you enable IPv6 support. OpenBSD doesn't support IPv4 mapped addresses at all (latest version tested: OpenBSD 5.0), so it can only run GnuGk as either an IPv4 or IPv6 gatekeeper.

As of December 2011, IPv6 support in endpoints is known to work with the following:

  • Most Tandberg devices with a recent firmware support IPv6 (eg. C series, EX90 or VCS).
  • Polycom HDX endpoints with firmware 3.0 or higher.
  • Spranto or higher.

Known to not work:

  • LifeSize endpoints do not support an IPv6 gatekeeper.

3.9 Using servers with multiple IPs

By default GnuGk will listen to all IPs on a server and will automatically select the correct sending IP to reach an endpoint. There are a number of config switches to select which IPs to use specifically.

With Home= you can select the interfaces GnuGk should listen on. Usually you would select 1 or 2 interfaces on a machine with multiple IPs. Thats something every user might consider.

With Bind= you can select which IP to use for outgoing messages. This can be useful if your gatekeeper listens to many IPs, but it can also have some non-obvious consequences and this switch should be avoided by most users.

Another related switch is ExternalIP= which can be used to send different IPs inside of your messages than you are actually listening on. This can be usefull if you are doing port forwarding, but should also be avoided and you should use one of the firewall traversal protocols instead.

3.10 Enabling Audio and Video Encryption

You can configure GnuGk as an encryption proxy to ensure that more or all outgoing calls are encrypted, whether your endpoint support encryption themselves or not.

First, enable "half call media" which means GnuGk will add encryption if only one side of the call supports encryption. This will enable encryption for those of your endpoints that might not support encryption by themselves. You can also set if you want 128 or 256 bit AES. (Check "h235media=1" in the startup message to make sure your GnuGk has the encryption features enabled.)


To make sure no call goes through without encryption, you can set


When you have this switch on, calls without encryption will be aborted.

Finally, you can take precautions that its always the "outside" connection that gets encryption added. The GnuGk feature is "half call media" and you have to make sure its not only the internal half of the call that gets encrypted. Thus you can remove the encryption from all endpoint on your internal network and with the above settings GnuGk will add encryption to all outgoing calls.


The next step after media encryption would be to add TLS (transport layer security) encryption to the signalling channel.

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: 09. Jun 2018