Home
· Download
· Support
· Success Stories
· Imprint

Documentation
· English Manual
· French Manual
· Spanish Manual
· Persian Manual
· Portuguese Manual
· Chinese Manual
· FAQ
· Interoperability
· Intro to H.323
· Usage Examples
· Configuration Notes
· GnuGk and SIP

Tools & Addons
· Java GUI
· ISDN Gateway
· CTI / ACD
· GnuGk Addons
· Endpoints
· Gateways
· MCUs
· IVRs
· Billing
· Commercial Addons

Development
· Compiling
· Development
· NAT Traversal
· Tools
· Authors

Misc
· Events
· Logos
· Recommended Books
· Site Map

This is the manual for GNU Gatekeeper 3.0.
A manual for your version is in your GnuGk download archive.

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

2. Compiling and Installing

2.1 Pre-requisites for Compiling

To build the gatekeeper you need PWLib and OpenH323 or PTLib and H323Plus. Please see http://www.gnugk.org/compiling-gnugk.html for up-to-date information on required library versions.

NOTE: In order to use any H.460 features, you must build with H323Plus.

To successfully compile the GNU Gatekeeper you must first compile the pre-requisites in this order:

1. PWLib or PTLib
2. OpenH323 or H323Plus

On Unix, run configure and make debugnoshared or make optnoshared in the gatekeeper directory to build debug or release version, respectively.

NOTE: You must use either make debugnoshared or make optnoshared throughout the compile process. For example, if a library is compiled with make optnoshared then everything must be compiled the same way.

2.2 Installing on Unix

The first step is to get an executable: You can either download an executable for your flavour of Unix from gnugk.org, use the executable your distribution provides or compile the GNU Gatekeeper yourself. For simple installations or to try the features of the gatekeeper, using pre-built executables shouldn't pose any issues, but for professional installations it is always recommended that you self-compile GnuGk.

Installing a binary of GnuGk

Copy the executable to the directory you like and create a config file. There are several config examples and auto startup scripts in the etc/ subdirectory of the source tree. See section Configuration File for detailed explanations of the parameters.

For example you may copy GnuGk to /usr/sbin/, create a config in /etc/gatekeeper.ini and start it by

/usr/sbin/gnugk -c /etc/gatekeeper.ini -o /var/log/gnugk.log -ttt

Compiling the Gatekeeper

NOTE: you must use GCC 3.3.x or later.

You are strongly encouraged to execute make debugdepend or make optdepend in the gatekeeper directory before starting actual compilation - these commands build appropriate dependency lists, so any CVS updates to the source code will force all affected files to get recompiled and will prevent the resulting binary from being compiled with a mix of old and updated headers.

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

In order to use the gatekeeper under heavy load, enabling the LARGE_FDSET feature (only available on Unix) is recommended (configure --with-large-fdset=4096). Some systems also need to use ulimit in order to allow more than 1024 sockets to be allocated for a single process. Maximum LARGE_FDSET value for voice calls should be calculated based upon predicted maximum sockets usage using the following formula:

MAX_NUMBER_OF_CONCURRENT_CALLS * 10 * 120%

Where:
10 = 2 sockets for Q.931 + 2 sockets for H.245 + 6 sockets for RTP

As a final step, you must either use make debugnoshared or make optnoshared, depending on how you compiled the libraries.

2.3 Installing on Windows

The first step is to obtain the executable program; you can either download it from gnugk.org or compile the GNU Gatekeeper yourself.

There are two versions of the gatekeeper available: A regular program and a service.

Installing as a Program

These are the steps for a manual installation:

Copy gnugk.exe to the folder you like and create a config file. There are several config examples in the etc/ subdirectory of the download archive. See section Configuration File for detailed explanations.

Then start the gatekeeper manually from the command line ('cmd.exe') or create a batch file to start it.

For example you may copy GnuGk to C:\GnuGk\, create a config in C:\GnuGk\gatekeeper.ini and start it as

C:\GnuGk\gnugk.exe -c C:\GnuGk\gatekeeper.ini -o C:\GnuGk\gnugk.log -ttt

Remember to add GnuGk as an exception for the Windows Firewall so it can communicate freely with the network.

Installing as a Service

These are the steps for a manual installation; there may be a binary version of the Gatekeeper-as-service which includes a GUI installer program available in the download location.

First, ensure that you have the service version of GnuGk before you proceed.

Copy gnugk.exe to the folder you like and create a config file named gatekeeper.ini in the same folder. See section Configuration File for detailed explanations. When you run GnuGk as a service, no command line options are available.

To register the service, run the following command from the command line ('cmd.exe'):

gnugk.exe install

Your service is now installed and will be started on the next reboot, or you may start it manually using the Windows Control Panel -> Services function. On Windows Vista and Windows 7, you may have to disable UAC during the service installation.

When running GnuGk as a service, it will always look for a config file named gatekeeper.ini in the current directory. Any changes to the trace level and location of the trace file must be made in the config file rather than the command line.

Remember to add GnuGk as an exception for the Windows Firewall so it can communicate freely with the network.

Compiling the Gatekeeper

Once you have compiled the pre-requisites as specified at the beginning of this section and have the appropriate include/library paths configured, open and compile one of the provided solution files (.sln) for your version of Microsoft Visual Studio. If you need MySQL or PostgreSQL support, install/compile appropriate client libraries before you compile GnuGk.

2.4 The addpasswd utility

Status port authentication and many other authentication modules, like SimplePasswordAuth, require encrypted passwords to be stored in the gatekeeper configuration file. The gatekeeper also supports encryption of all passwords in the config. The addpasswd utility is required to generate and store these encrypted passwords. This utility is included with the gatekeeper and can be compiled using:

$ cd addpasswd
$ make optnoshared

The usage is as follows:

$ addpasswd CONFIG SECTION KEYNAME PASSWORD

Example 1: 'gkadmin' user with 'secret' password has to be added to the [GkStatus::Auth] config section to enable authentication on the status port:

$ addpasswd gatekeeper.ini GkStatus::Auth gkadmin secret

Example 2: 'joe' user with 'secret' password has to be added to the [Password] config section to enable endpoint authentication:

$ addpasswd gatekeeper.ini Password joe secret

Example 3: An encrypted shared secret is added to a RadAuth config section:

$ addpasswd gatekeeper.ini RadAuth SharedSecret VerySecretPassword

IMPORTANT: The KeyFilled variable defines a default initializer for password encryption keys. It can be omitted in the config (and therefore defaults to 0), but if it is specified, each time it changes, encrypted passwords have to be regenerated (encrypted again using the addpasswd utility).

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