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:

• Address Translation
• Admissions Control
• Bandwidth Control
• Zone Management
• Call Control Signaling
• Call Authorization
• Bandwidth Management
• Call Management

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.

• OpenGatekeeper - by Egoboo

  A full featured gatekeeper freely available under MPL. The project has been inactive for a period of time now. There is an H.323 proxy based on OpenGatekeeper, see OpenH323Proxy.

• OpenGK - by Equivalence

  Only in a very primary grades.

• OpenH323 Gatekeeper - this one.

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:

• Enchanced prefix matching for routing policies. A dot (.) matches any digit.
• Enchanced prefix matching for neighbors. A dot (.) matches any digit, ! at the beginning disables the prefix.
• A missing lock during config reload caused the gatekeeper to crash.
• More reliable port number selection for Q.931, H.245, T.120 and RTP port ranges (earlier, a config reload could cause many calls to fail because of unability to allocate a new socket).
• Default value for RTPPortRange is now to let the OS select a port number.
• More flexible rewrite rules (both global and per-gw) with new '.' and '%' wildcard characters.
• Enchanced prefix matching for gateways. A dot (.) matches any digit, ! at the beginning disables the prefix.
• Insert missing Calling-Party-Number-IE/Display-IE if corresponing Screen... options are enabled.
• Shutdown the gatekeeper if there are errors in SQL auth/acct modules configuration.
• Called-Station-Id number type can be selected between the original one (dialed number) and the rewritten one. New UseDialedNumber config option for RadAuth/ RadAliasAuth / RadAcct modules, new %{Dialed-Number} variable for SQLAcct and FileAcct modules.
• Ability to customize timestamp formats. New TimestampFormat config variables for main, [SqlAcct], [RadAcct], [FileAcct] and [CallTable] sections.
• RadAuth/RadAliasAuth modules can now add/remove endpoint aliases during endpoint registration (using h323-ivr-in=terminal-alias: Cisco AV-Pair).
• New TcpKeepAlive option to solve the problem with network errors and calls hanging in the call table. See docs/keepalive.txt for more details.
• New status port RouteToGateway command.

The version 2.2.0 contains the following new features and bugfixes:

• New RoundRobinGateways config option.
• Call capacity limits and priority routing for gateways. New EP:: config sections for per-endpoint configuration settings (see Per-Endpoint Configuration Settings).
• RTP proxy handling moved to a separate RTP proxy threads, so processing of signaling messages does not block RTP packets. New RtpHandlerNumber config option.
• REUSE_ADDRESS option enabled on listening sockets in non-LARGE_FDSET mode to fix a bug with the gatekeeper being unable to open listening ports after restart.
• Ability to set call destination in auth modules. RADIUS based call routing.
• Support for SqlBill tariff table import from an OpenOffice.org Calc spreadsheet.
• Fixed sourceInfo LRQ field handling - now it contains an H.323 identifier of the gatekeeper. Nonstandard data and gatekeeperIdentifier fields are set only when the neighbor is defined as GnuGk.
• Ability to set shared secrets for each radius server separatelly.
• New, much faster, Radius client implementation.
• Called-Party-Number-IE rewrite occured too late, causing auth/acct modules to receive the original number instead of the rewritten one.
• Fixed proxying of RTP packets, so RTP sockets are not closed on temporary errors (like remote socket not yet ready). This bug affected especially NAT traversal and situation, when audio was sent very early, when reverse proxy path has not been yet established.
• Fixed handling of RRJ from an alternate GnuGk.
• New direct SQL accounting module ( [SQLAcct]).
• Handling multiple reply messages (RIP/LCF/LRJ) from neighbors fixed.
• Support for CallCreditServiceControl in RCF and ACF messages, which allows reporting call duration limit and user's account balance to endpoints. Currently RadAuth and RadAliasAuth modules support this feature.
• Log file rotation, new LogFile config section, new setlog and rotatelog status interface commands.
• Do not include an invalid access token (with null object identifier) in LCF to prevent interoperability problems.
• Better handling of multiple calls over a single signalling channel by setting multipleCalls and maintainConnection H.225.0 fields to FALSE in all messages passing through the gatekeeper.
• Better User-Name, Calling-Station-Id and Called-Station-Id handling.
• IncludeEndpointIP flag for RadAuth, RadAliasAuth and RadAcct is obsolete, these modules will always send Framed-IP-Address.
• New Gatekeeper::Auth flag SetupUnreg to toggle Q.931 Setup authentication for unregistered endpoints only.
• New RADIUS h323-ivr-out=h323-call-id parameter that contains an H.323 Call Identifier.
• The SQL billing from the contrib section can now authenticate users only by their IP (ignoring User-Name) and has a new, more flexible tariff/rating engine.
• RadAliasAuth can authenticate now Setup messages without sourceAddress field present (it will use Calling-Party-Number instead).
• Better signal handling to prevent accidental gatekeeper crashes (due to SIGPIPE, for example).
• CDR rotation per number of lines works correctly.

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

• Parametrized FileAcct CDR output.
• Do not list H.235 Auth Procedure I support in GCF messages, as it is not fully implemented.
• Fixed interoperability problem with some Cisco IOSes, because of copying nonStandardData field from RAS requests to RAS replies.
• Multiple calls over a single signalling channel are now gracefully handled using ReleaseComplete with the newConnectionNeeded indication
• Permanent endpoints are correctly reloaded now, with removal of permanent endpoints for which config entries have been deleted
• Support for ExternalPasswordAuth module finally removed (although the source code is only commented out for those who need this module).
• SQL engine rewritten completelly to use a concept of SQL driver. New modules SQLPasswordAuth and SQLAliasAuth added. MySQL and PostgreSQL drivers implemented. Backward compatibility (MySQLAliasAuth and MySQLPasswordAuth) is maintained.
• Per gateway E.164 rewriting of dialedDigits in addition to the global E.164 rewriting. Thanks to Ian Campbell!
• A sample SQL/RADIUS billing example has been added to the contrib directory
• A new config parameter ScreenSourceAddress introduced to screen calling party aliases present in the UUIE Setup element
• Q.931 Setup authentication added to RadAuth module to allow authentication based on crypto tokens carried inside Setup messages
• Log rotation added
• Applied the concept of output trace levels for the status interface. It allows to select amount of information a status client receives (level 0 - silent mode + reloads; level 1 - CDRs, RouteRequests, reloads; level 2 - everything: the default mode)
• The GNU Gatekeeper Service for Windows contributed by Franz J Ehrengruber
• Makefile to force users running configure script before the compilation
• Better LOG_OFF Windows event handling to prevent gatekeeper shutdown when the user logs out
• Fixed SimplePasswordAuth module to read settings from SimplePasswordAuth section instead of Password section. Fixed MySQLPasswordAuth module to accept CacheTimeout parameter. Default CacheTimeout for MySQLPasswordAuth and MySQLAliasAuth set to 0 (do not cache passwords/aliases at all).
• RTP proxy fixed to (usually) not require RTCP channel and work better with T.38 faxes
• Treat MCUs as gateways and allow MCUs to register prefixes
• Fixed referencing to a temporary PString object after it is destroyed when logging routing policy information
• Flexible FileAcct CDR file rotation.

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

• The config variable VirtualQueue has been renamed to VirtualQueueAliases (backward compatibility is maintained)
• New VirtualQueuePrefixes and VirtualQueueRegex config variables introduced
• Handling of multiple accounting modules has changed (new "alternative" control type added)
• PostgreSQL authenticator modules have been added to the contrib directory
• Q.931/H.225 Setup authentication (RadAliasAuth module implementation) added
• addpasswd utility changed to require section name where the encrypted username/password will be stored
• Fixed NULL reference in CallRec::SetSocket - caused crash in ForwardCall. Thanks to kubuqui cn!
• Fixed invalid signed/unsigned conversions in RADIUS modules that caused some functions to return unexpected results under certain circumstances

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

• configure script to detect and control system settings and the compilation
• RADIUS auth/acct modules ported from 2.0 and optimized
• Plain text CDR accounting logger module (FileAcct) from Tamas Jalsovszky
• Added "run as user" feature
• New CTI virtual queues implementation from Chih-Wei Huang
• Status line improvements (command expansion, repeat last command, backspace handling for windows) from Hu Yuxin

The version 2.2beta1 contains the following new features:

• A new method to detect NATed endpoints
• Configurable, flexible routing policies
• New neighboring system
• Multithreaded RAS server
• Support for multiple MySQL servers, MySQL can now be compiled on Windows

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:

• RadAuth/RadAliasAuth modules can now add/remove endpoint aliases during endpoint registration (see radauth.txt for more info).
• added utilities to the contrib dir that allow the gnugk ro run as a Windows service process. Thanks to Franz J Ehrengruber!
• Windows improvements (project icon, version info, better console handler). Thanks to Franz J Ehrengruber!
• Radius Q.931 Setup authentication routines optimized.
• gateway and neighbor prefixes match can also occur with alias types (in addition to dialedDigits) partyNumber and h323_ID (containing only 0-9#*)
• Added new VirtualQueuePrefixes and VirtualQueueRegex config variables. These make possible to call virtual queue not only with the exact alias name, but also with an alias that matches configured prefixes or configured regular expression. Thanks to Max Speransky
• accounting updates for calls in progress. Currenly only RadAcct module implements this type of accounting event
• improved Radius h323-xxx attributes handling (now understands attributes both with embedded name strings and without them)

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

• FileAcct - plain CDR text accounting logger module.
• Commandline option (-u) to change the gatekeeper process owner.
• Improved virtual queues.
• Full pre-paid support - both for registered endpoints (ARQ) and for unregistered endpoints (Q.931 Setup). Call duration limit is fully supported by RADIUS authenticators at the moment.

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

• a first TransferCall implementation
• RADIUS H.235 (username/password) and alias authentication.
• Modular accounting framework.
• RADIUS accounting module.
• Signalling channel authentication/authorization (Q.931/H.225.0 Setup). Call duration limit (pre-paid services) can be controlled using this authorization scheme. RADIUS Q.931 authentication/authorization module is provided.

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

• Forward a call Setup to the specified endpoint directly on receiving Q.931 Facility with reason callForwarded.
• Allow specify NATed endpoints manually.
• Added a simple form of inbound call distribution. Calls to a VirtualQueue can be routed to agents by an external distribution application.

The new features added to version 2.0.2 are:

• Add Citron's NAT Technology that allows transparently penetrate NAT boxes.Support multiple endpoints and calls concurrently.
• The gatekeeper can sit behind an NAT box and registered by endpoints with public IPs.
• New extended fd_set structure, which allow the gatekeeper to support thousands of concurrent calls in routed mode.
• Support QoS by adding TOS flag to RTP/RTCP packets.
• Login status port by username and password.

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

• The registration table and call record table are redesigned, thread-safe, and very efficient. Support ten thousands of registrations and thousands of concurrent calls.
• A new routed mode architecture that support H.225.0/Q.931 routed and H.245 routed without forking additional threads. Thus the thread number limit will not restrict the number of concurrent calls.
• Support H.323 proxy by routing all logical channels, including RTP/RTCP media channels and T.120 data channels. Logical channels opened by H.245 tunnelling and fast-connect procedure are also supported. In proxy mode, there is no traffic between the calling and called parties 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.
• Support gatekeepers cluster by exchanging LRQ/LCF/LRJ (neighboring function). If the destination of a received LRQ is unknown, the GnuGk can forward it to next hop. Therefore the GnuGk can work as a directory gatekeeper.
• Support various authentication methods for selectable RAS requests, including H.235 password (MD5, SHA-1 and CAT), IP pattern and prefixes matching. MySQL and LDAP are supported as backend database for authentication.
• Support alternate gatekeepers for redundancy and load balancing. If the GnuGk is overloaded, the endpoints can be redirected to other gatekeepers.
• Can work as an endpoint (gateway or terminal) by resigtering with a parent gatekeeper. With this feature, building gatekeeper hierarchies is easily.
• Monitor and control the GnuGk via TCP status port, including registration and call statistics.
• Output CDR(call detail record) to status port for backend billing system. The CDR contains call identifier, calling and called IP, start and end time and call duration.
• Most configurations are changeable at runtime. The GnuGk rereads the configurations on receiving reload command via status port, or on receiving HUP signal (Unix platform).

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.