<!doctype linuxdoc system>
<!-- This is the User Manual for OpenH323 Gatekeeper - The GNU Gatekeeper -->
<!-- Maintained:   Chih-Wei Huang <cwhuang@linux.org.tw>                  -->
<!-- Citron Network Inc. 2002                                             -->

<article>
<!-- Title information -->
<title>OpenH323 Gatekeeper - The GNU Gatekeeper
<author>Maintainer of this manual:
<htmlurl url="http://www.cwhuang.idv.tw/" name="Chih-Wei Huang">
<tt><htmlurl url="mailto:cwhuang@linux.org.tw" name="&lt;cwhuang@linux.org.tw&gt;"></tt>
<date>v2.0.1, 8 November 2002
<!-- v2.0, 1 August 2002 -->
<!-- bgein on 19 April 2002 -->

<abstract>
This is the User Manual for
how to compile, install, configure and monitor
OpenH323 Gatekeeper - The GNU Gatekeeper.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin of document -->

<!----------          Next Section          ---------->
<sect>Introduction
<sect1>About
<p>
<bf>
<url url="http://www.gnugk.org/" name="OpenH323 Gatekeeper - The GNU Gatekeeper">
</bf>
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:
<itemize>
<item>Address Translation
<item>Admissions Control
<item>Bandwidth Control
<item>Zone Management
<item>Call Control Signaling
<item>Call Authorization
<item>Bandwidth Management
<item>Call Management
</itemize>

The GNU Gatekeeper implements most of these functions
based on the
<url url="http://www.openh323.org/" name="OpenH323">
protocol stack.

Recommendation H.323 is an international standard published by the
<url url="http://www.itu.int/" name="ITU">.
It is a communications standard for audio, video, and data over the Internet.
See also Paul Jones'
<url url="http://www.packetizer.com/iptel/h323/" name="primer on H.323">.

For a detailed description of what a gatekeeper does, see
<url url="http://www.webproforum.com/h323/topic06.html" name="here">.

<sect1>Copyright
<p>
It is covered by the
<htmlurl url="http://www.gnu.org/licenses/gpl.html" name="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 thread and communicatie 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.

<sect1>Name
<p>
The formal name of this project is
<em>OpenH323 Gatekeeper - The GNU Gatekeeper</em>,
shortly <em/OpenH323GK/ or <em/GnuGK/.
Please don't confuse it with other gatekeeper projects.

There are several open-source gatekeeper projects based on the OpenH323 protocol stack.
<itemize>
<item><url url="http://opengatekeeper.sourceforge.net/" name="OpenGatekeeper"> - by <url url="http://www.egoboo.com/" name="Egoboo">
<quote>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 <url url="http://openh323proxy.sourceforge.net/" name="OpenH323Proxy">.</quote>
<item><url url="http://www.openh323.org/code.html" name="OpenGK"> - by <url url="http://www.equival.com.au/" name="Equivalence">
<quote>Only in a very primary grades.</quote>
<item>OpenH323 Gatekeeper - this one.
</itemize>

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 <tt/gnugk/ as name for executables.

<sect1>Features
<p>
The new features added to version 2.0.1 are:
<itemize>
<item>
Add Citron's NAT Technology that allows transparently penetrate NAT boxes.Support multiple endpoints and calls concurrently.

<item>
The gatekeeper can sit behind an NAT box and registered by endpoints with
public IPs.

<item>
New extended fd_set structure, which allow the gatekeeper to support
thousands of concurrent calls in routed mode.

<item>
Support QoS by adding TOS flag to RTP/RTCP packets.

<item>
Login status port by username and password.
</itemize>

Of course, the major functions in version 2.0 are also included:
<itemize>
<item>
The registration table and call record table are redesigned, thread-safe,
and very efficient. Support ten thousands of registrations and thousands of
concurrent calls.

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

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

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

<item>
Support various authentication methods for selectable RAS requests, including
H.235 password (MD5 & SHA-1), IP pattern and prefixes matching. MySQL and
LDAP are supported as backend database for authentication.

<item>
Support alternate gatekeepers for redundancy and load balancing. If the
GnuGK is overloaded, the endpoints can be redirected to other gatekeepers.

<item>
Can work as an endpoint (gateway or terminal) by resigtering with a parent
gatekeeper. With this feature, building gatekeeper hierarchies is easily.

<item>
Monitor and control the GnuGK via TCP status port, including registration
and call statistics.

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

<item>
Most configurations are changeable at runtime. The GnuGK rereads the
configurations on receiving `<tt/reload/' command via status port, or on
receiving <tt/HUP/ signal (Unix platform).
</itemize>

<sect1>Download
<label id="download">
<p>
The newest stable and a development version are available at
<url url="http://www.gnugk.org/h323download.html" name="the download page">.

The very latest source code is in the CVS at
<url url="http://sourceforge.net/cvs/?group_id=4797" name="Sourceforge">
(<url url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/openh323gk/" name="Web-GUI">).
Beware - that's the bleeding edge.

You can also download executables from
<url url="http://sourceforge.net/project/showfiles.php?group_id=4797" name="Sourceforge">. Only some versions are made available as executables.

<sect1>Mailing Lists
<p>
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
<url url="mailto:Openh323gk-users@sourceforge.net" name="users mailing list">. You can find the list archive
<url url="http://sourceforge.net/mailarchive/forum.php?forum_id=8549" name="here">.
To join this mailing list, click
<url url="http://lists.sourceforge.net/lists/listinfo/openh323gk-users" name="here">.

To report problems or submit bugs/patches, send mails to the
<url url="mailto:Openh323gk-developer@sourceforge.net" name="developers mailing list">.
The list archive is
<url url="http://sourceforge.net/mailarchive/forum.php?forum_id=3079" name="here">. Please send user questions to the users mailinglist and keep this list to development! If you want to contribute to the project, please
<url url="http://lists.sourceforge.net/lists/listinfo/openh323gk-developer" name="join the mailing list">.

<bf/Note/:
Please don't send your questions as private emails to individual developer.
We are usually busy. We would <bf/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.

Please also note don't send the GnuGK specific problems to the OpenH323
mailing list, or vice versa. Or you will definitely be ignored.
They are different projects, though closely related.
The developers are also different, though they usually work together
in some ways.

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.
If you don't know how to ask questions in a public forum,
read Eric S. Raymond's famous article
<url url="http://www.tuxedo.org/~esr/faqs/smart-questions.html" name="How To Ask Questions The Smart Way"> before you asking.

<sect1>Contributors
<p>
The current project coordinator is
<url url="http://www.willamowius.de/" name="Jan Willamowius">
<tt><htmlurl url="mailto:jan@willamowius.de" name="&lt;jan@willamowius.de&gt;"></tt>

The main features and functions of version 2.0 are contributed by
<url url="http://www.cwhuang.idv.tw/" name="Chih-Wei Huang">
<tt><htmlurl url="mailto:cwhuang@linux.org.tw" name="&lt;cwhuang@linux.org.tw&gt;"></tt>
and
<url url="http://www.citron.com.tw/" name="Citron Network Inc.">,
including thread-safe registration and call tables,
new routed mode architecture, H.323 proxy,
H.235 authentication and MySQL backend.

A team at
<url url="http://www.mediaways.net/" name="mediaWays">
is working on LDAP database-subsystem, overlapped sending
and advanced routing mechanisms.

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


<!----------          Next Section          ---------->
<sect>Compiling and Installing
<p>
<sect1>Compiling the Gatekeeper
<p>
To build the gatekeeper you need at least PWLib 1.2 and OpenH323 1.8 or later.
The development version of the gatekeeper usually needs the
most recent OpenH323 version available.
These libraries are available at
<url url="http://www.openh323.org/code.html" name="OpenH323 Download Page">.
See the instructions on
<url url="http://www.openh323.org/build.html" name="how to compile the OpenH323 code">.

Order of compiling:
<enum>
<item>PWLib (release + debug version)
<item>OpenH323
<item>OpenH323 test application (not needed, just to make sure everything works so far)
<item>The Gatekeeper
</enum>

On Unix do a <tt/make debug/ or <tt/make opt/ in the gatekeeper directory
to build debug or release version, respectively.
Use <tt/make both/ to build both versions.
Note you have to use GCC 2.95.2 or later. The older version may not work.

On Windows just open and compile the provided project (<tt/gk.dsw/) for
Microsoft Visual C++ 6.0 or 7.0 (Visual C++ 5.0 is too old).

Since version 2.0, the Gatekeeper supports MySQL and LDAP backend databases.
If you don't want MySQL support, you may set NO_MYSQL environment
before making:
<tscreen><verb>
$ NO_MYSQL=1 make both
</verb></tscreen>

To leave out LDAP support:
<tscreen><verb>
$ NO_LDAP=1 make both
</verb></tscreen>

Or disable both with
<tscreen><verb>
$ NO_MYSQL=1 NO_LDAP=1 make both
</verb></tscreen>

In version 2.0.1 the Gatekeeper has implemented an extended fd_set structure
that enables the Gatekeeper to support thousands of concurrent calls
in routed mode. To enable this feature, export LARGE_FDSET environment variable
to the maximum number of file descriptors. For example,
<tscreen><verb>
$ LARGE_FDSET=16384 make opt
</verb></tscreen>

<sect1>Installing the Gatekeeper
<p>
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 <tt>etc/</tt> subdirectory
of source tree. See section <ref id="config" name="Configuration File">
for detailed explanations.

For example, in Linux x86 platform, the optimized executable <tt/gnugk/
is produced in <tt>obj_linux_x86_r/</tt> subdirectory.
You may copy it to <tt>/usr/sbin/</tt>, create a config in
<tt>/etc/gnugk.ini</tt> and start it by
<tscreen><verb>
$ /usr/sbin/gnugk -c /etc/gnugk.ini -o /var/log/gnugk.log -ttt
</verb></tscreen>
See section <ref id="commandline" name="Command Line Options"> for details.

<sect1>Pre-Built Binaries
<p>
If you do not wish to compile the gatekeeper from source,
there are several pre-built `packages' available from
<url url="http://sourceforge.net/project/showfiles.php?group_id=4797" name="SourceForge">.
Not all versions will be made available as binaries - check what is avilable.

<bf/Red Hat packages (.rpm)/<p>
Download the RPMs and enter the following command as <tt/root/,
substitute in the name of the file you downloaded.
<tscreen><verb>
$ rpm -Uvh gnugk-x.x.x.rpm
</verb></tscreen>

<bf/Debian packages (.deb)/<p>
If you are using the `stable' (woody) branch of Debian,
you can install the gatekeeper by using the following command as <tt/root/:
<tscreen><verb>
$ apt-get install openh323gk
</verb></tscreen>


<!----------          Tutorial Section          ---------->
<sect>Getting Started (Tutorial)
<p>
<sect1>A first simple experiment
<p>
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):

<tscreen><verb>
jan@machine1 > gnugk -ttt
</verb></tscreen>

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

<tscreen><verb>
jan@machine1 > ohphone -l -a -u jan
</verb></tscreen>

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

On the second machine run ohphone only:

<tscreen><verb>
peter@machine2 > ohphone -u peter jan
</verb></tscreen>

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.

<sect1>Using the Status interface to spy on the gatekeeper
<p>
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:

<tscreen><verb>
jan@machine1 > telnet machine1 7000
</verb></tscreen>

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

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

<tscreen><verb>
[Gatekeeper::Main]
Fourtytwo=42
[GkStatus::Auth]
rule=allow
</verb></tscreen>

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.

<sect1>Starting the gatekeeper in routed mode
<p>
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.

<tscreen><verb>
jan@machine1 > gnugk -r
</verb></tscreen>

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

<p>
<sect1>A virtual PBX: Disconnecting calls
<p>
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 "<tt/PrintCurrentCalls/". To terminate a call, we can
say "<tt/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.

This mechanism could also be used to call transfers between users
or call forwarding. (But thats not yet implemented in the gatekeeper.)

<sect1>Routing calls over a gateway to reach external users
<p>
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.

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

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.

<tscreen><verb>
[RasSrv::GWPrefixes]
gw1=0
</verb></tscreen>

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


<sect1>Rewriting E.164 numbers
<p>
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 <ref id="rewrite" name="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".

<tscreen><verb>
[RasSrv::GWPrefixes]
gw1=0

[RasSrv::RewriteE164]
12345=08765
</verb></tscreen>


<!----------          Reference Section          ---------->
<sect>Using the Gatekeeper (Reference)
<p>
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 <tt/-l/ overrides the setting <tt/TimeToLive/
in the configuration file.

<sect1>Command Line Options
<label id="commandline">
<p>
Almost every option has a short and a long format, e.g.,
<tt/-c/ is the same as <tt/--config/.
<p>
<sect2>Basic
<p>
<descrip>
<tag/<tt/-h  --help//
Show all available options and quit the program.
<tag/<tt/-c  --config filename//
Specify the configuration file to use.
<tag/<tt/-s  --section section//
Specify which main section to use in the configuration file. The default is [Gatekeeper::Main].
<tag/<tt/-i  --interface IP//
Specify the interface(IP) 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.
<tag/<tt/-l  --timetolive n//
Specify the time-to-live timer in seconds for endpoint registration.
It overrides the setting <tt/TimeToLive/ in the configuration file.
See <ref id="ttl" name="there"> for detailed explanations.
<tag/<tt/-b  --bandwidth n//
Specify the total bandwidth available for the gatekeeper.
Without specifying this option, the bandwidth management
is disable by default.
<tag/<tt/--pid filename//
Specify the pid file, only valid for Unix version.
</descrip>

<sect2>Gatekeeper Mode
<p>
The options in this subsection override the settings in the
<ref id="routed" name="[RoutedMode] section"> of the configuration file.
<descrip>
<tag/<tt/-d  --direct//
Use direct endpoint call signalling.
<tag/<tt/-r  --routed//
Use gatekeeper routed call signalling.
<tag/<tt/-rr  --h245routed//
Use gatekeeper routed call signalling and H.245 control channel.
</descrip>

<sect2>Debug Information
<p>
<descrip>
<tag/<tt/-o  --output filename//
Write trace log to the specified file.
<tag/<tt/-t  --trace//
Set trace verbosity. The more <tt/-t/ you add, the more verbose to output.
For example, use <tt/-ttttt/ to set the trace level to 5.
</descrip>

<sect1>Configuration File
<label id="config">
<p>
The configuration file is a standard text file. The basic format is:

<tscreen><verb>
[Section String]
Key Name=Value String
</verb></tscreen>

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

The file
<tt/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 <tt/reload/ command
via status port, or send a signal <tt/HUP/ to the gatekeeper process on Unix.
For example,
<tscreen><verb>
kill -HUP `cat /var/run/gnugk.pid`
</verb></tscreen>

<bf/Note/
It is said that some section names in GnuGK 2.0 are &lsqb;RasSrv::*&rsqb;,
while others are &lsqb;RasSvr::*&rsqb;. This inconsistency confuses users.
In 2.0.1 all sections are corrected to &lsqb;RasSrv::*&rsqb;.
If you upgrade from 2.0 or eariler version, remember to change the
section names, or the GnuGK will refuse to start.

<sect2>Section &lsqb;Gatekeeper::Main&rsqb;
<p>
<itemize>
<item><tt/Fourtytwo=42/<newline>
Default: <tt>N/A</tt>
<p>
This setting is used to test the presence of the config file. If it
is not found, a warning is issued.
Make sure it's in all your config files.

<item><tt/Name=OpenH323GK/<newline>
Default: <tt/OpenH323GK/
<p>
Gatekeeper identifier of this gatekeeper. The gatekeeper will only respond to
GRQs for this ID and will use it in a number of messages to its endpoints.

<item><tt/Home=192.168.1.1/<newline>
Default: <tt/0.0.0.0/
<p>
The gatekeeper will listen for requests on this IP number.
By default, the gatekeeper listens on all interfaces of your host.
You should leave out this option,
unless you want the gatekeeper only to bind to a specified IP.

<item><tt>NetworkInterfaces=192.168.1.1/24,10.0.0.1/0</tt><newline>
Default: <tt>N/A</tt>
<p>
Specify the network interfaces of the gatekeeper. By default the gatekeeper
will detect the interfaces of your host automatically. There are two situations
that you may want to use this option. One is automatical detection failed,
another is the gatekeeper is behind an NAT box and allow endpoints with
public IPs to register with. In this case you should set the option just as
the gatekeeper is running on the NAT box.

<item><tt/EndpointIDSuffix=_gk1/<newline>
Default: <tt/_endp/
<p>
The gatekeeper will assign a unique identifier to each registered endpoint.
This option can be used to specify a suffix to append to the endpoint identifier. This is only usefull when using more than one gatekeeper.

<item><label id="ttl"><tt/TimeToLive=300/<newline>
Default: <tt/-1/
<p>
An endpoint's registration with a gatekeeper may have a limited life span.
The gatekeeper specifies the registration duration of an endpoint
by including a <bf/timeToLive/ field in the RCF message.
After the specified time, the registration has expired.
The endpoint shall periodically send an RRQ having the <bf/keepAlive/
bit set prior to the expiration time. Such a message may include a
minimum amount of information as described in H.225.0.
This is called a lightweight RRQ.

This configuration setting specifies the time-to-live timer in seconds until the registration expires.
Note the endpoint may request a shorter <bf/timeToLive/ in the RRQ message
to the gatekeeper.
To avoid an overload of RRQ messages,
the gatekeeper automatically adjusts this timer
to 60 seconds if you give a lesser value!

After the expiration time,
the gatekeeper will subsequently send two IRQ messages to query
if the endpoint is still alive. If the endpoint responds with an IRR,
the registration will be extended. Otherwise the gatekeeper will send
a URQ with reason <bf/ttlExpired/ to the endpoint.
The endpoint must then re-register with the gatekeeper using a full RRQ message.

To disable this feature, set it to <tt/-1/.

<item><tt/TotalBandwidth=100000/<newline>
Default: <tt/-1/
<p>
Total bandwidth available to be given to endpoints.

<item><tt/RedirectGK=Endpoints > 100 || Calls > 50/<newline>
Default: <tt>N/A</tt>
<p>
This option allow you to redirect endpoints to alternate gatekeepers
when the gatekeeper overloaded.
For example, with the above setting the gatekeeper will
reject an RRQ if registered endpoints exceed 100,
or reject an ARQ if concurrent calls exceed 50.

Furthermore, you may explicitly redirects all endpoints by
setting this option to <tt/temporary/ or <tt/permanent/.
The gatekeeper will return an RAS rejection message with a list of
alternate gatekeepers defined in <tt/AlternateGKs/.
Note that a <tt/permanent/ redirection means that the redirected endpoints
will not register with this gatekeeper again.
Please also note the function only takes effect to H.323 version 4
compliant endpoints.

<item><tt/AlternateGKs=1.2.3.4:1719:false:120:OpenH323GK/<newline>
Default: <tt>N/A</tt>
<p>
We allow for existence of another gatekeeper to provide redundancy.
This is implemented in a active-active manner. Actually, you might get
into a (valid !) situation where some endpoints are registered with the
first and some are registered with the second gatekeeper.
You should even be able use the two gatekeepers in a round_robin fashion
for load-sharing (that's untested, though :-)).
If you read on, "primary GK" refers to the gatekeeper you're currently
configuring and "alternate GK" means the other one.
The primary GK includes a field in the RCF to tell endpoints which alternate
IP and gatekeeper identifier to use.
But the alternate GK needs to know about every
registration with the primary GK or else it would reject calls.
Therefore our gatekeeper can forward every RRQ to an alternate IP address.

The AlternateGKs config option specifies the fields contained in
the primary GK's RCF. The first and second fields of this string define
where (IP, port) to forward to.
The third tells endpoints whether they need to register with the alternate GK
before placing calls. They usually don't because we forward their RRQs, so they
get registered with the alternate GK, too.
The fourth field specified the priority for this GK.
Lower is better, usually the primary GK is considered to have priority 1.
The last field specifies the alternate gatekeeper's identifier.

<item><tt/SendTo=1.2.3.4:1719/<newline>
Default: <tt>N/A</tt>
<p>
Although this information is contained in AlternateGKs, you must still
specify which address to forward RRQs to. This might differ from AlternateGK's
address, so it's a separate config option (think of multihomed machines).

<item><tt/SkipForwards=1.2.3.4:5.6.7.8/<newline>
Default: <tt>N/A</tt>
<p>
To avoid circular forwarding, you shouldn't forward RRQs you get from the
other GK (this statement is true for both, primary and alternate GK).
Two mechanisms are used to identify whether a request should be forwarded.
The first one looks for a flag in RRQ. Since few endpoints implement this,
we need a second, more reliable way.
Specify the other gatekeeper's IP in this list.

<item><tt/StatusPort=7000/<newline>
Default: <tt/7000/
<p>
Status port to monitor the gatekeeper.
See <ref id="monitor" name="this section"> for details.

</itemize>

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

<itemize>
<item><tt/UseBroadcastListener=0/<newline>
Default: <tt/1/
<p>
Defines whether to listen to broadcast RAS requests. This requires
binding to all interfaces on a machine so if you want to run multiple
instances of gatekeepers on the same machine you should turn this off.

<item><tt/UnicastRasPort=1719/<newline>
Default: <tt/1719/
<p>
The RAS channel TSAP identifier for unicast.

<item><tt/MulticastPort=1718/<newline>
Default: <tt/1718/
<p>
The RAS channel TSAP identifier for multicast.

<item><tt/MulticastGroup=224.0.1.41/<newline>
Default: <tt/224.0.1.41/
<p>
The multicast group for the RAS channel.

<item><tt/EndpointSignalPort=1720/<newline>
Default: <tt/1720/
<p>
Default port for call signalling channel of endpoints.

<item><tt/ListenQueueLength=1024/<newline>
Default: <tt/1024/
<p>
Queue length for incoming TCP connection.

<item><tt/SignalReadTimeout=1000/<newline>
Default: <tt/1000/
<p>
Time in miliseconds for read timeout on status channel.

<item><tt/StatusReadTimeout=3000/<newline>
Default: <tt/3000/
<p>
Time in miliseconds for read timeout on call signalling channels (Q931).
</itemize>

<sect2>Section &lsqb;RoutedMode&rsqb;
<label id="routed">
<p>
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.

<descrip>
<tag/Case I./
The gatekeeper doesn't route them.
The H.245 control channel and logical channels are established directly
between the endpoints.
<tag/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.
<tag/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.
</descrip>

This section defines the gatekeeper routed mode options (case I &amp; II).
The proxy feature is defined in the <ref id="proxy" name="next section">.
All settings in this section are affected by reloading.

<itemize>
<item><tt/GKRouted=1/<newline>
Default: <tt/0/
<p>
Whether to enable the gatekeeper routed mode.

<item><tt/H245Routed=1/<newline>
Default: <tt/0/
<p>
Whether to route the H.245 control channel. Only takes effect if <tt/GKRouted=1/.

<item><tt/CallSignalPort=0/<newline>
Default: <tt/1721/
<p>
The port of call signalling for the gatekeeper.
The default port is <tt/1721/. We don't use the well-known port <tt/1720/
so you can run an H.323 endpoint in the same machine of the gatekeeper.
You may set it to <tt/0/ to let the gatekeeper choose an arbitrary port.

<item><tt/CallSignalHandlerNumber=2/<newline>
Default: <tt/1/
<p>
The number of call signalling handler. You may increase this number
in a heavy loaded gatekeeper. The number can only be increased
at runtime. If you have a SMP machine, you can set this number
to your number of CPUs.

<item><tt/AcceptNeighborsCalls=1/<newline>
Default: <tt/1/
<p>
With this feature enabled, the call signalling thread will accept calls
without a pre-existing CallRec found in the CallTable, provided an endpoint
corresponding to the destinationAddress in Setup can be found in the
RegistrationTable, and the calling party is its neighbors or parent GK.
The gatekeeper will also use it's own call signalling address in LCF
in responding to an LRQ. That means, the call signalling will be routed
to GK2 in GK-GK calls.
As a result, the CDRs in GK2 can correctly show the connected
time, instead of 'unconnected'.

<item><tt/AcceptUnregisteredCalls=1/<newline>
Default: <tt/0/
<p>
With this feature enabled, the gatekeeper will accept calls
from any unregistered endpoint.
However, it raises security risks. Be careful to use it.

<item><tt/RemoveH245AddressOnTunneling=1/<newline>
Default: <tt/0/
<p>
Some endpoints send h245Address in the UUIE of Q.931 even when h245Tunneling
is set to TRUE. This may cause interoperability problems. If the option
is TRUE, the gatekeeper will remove h245Address when h245Tunneling flag
is TRUE. This enforces the remote party to stay in tunnelling mode.

<item><tt/RemoveCallOnDRQ=0/<newline>
Default: <tt/1/
<p>
With this option turning off, the gatekeeper will not disconnect a call
if it receives a DRQ for it. This avoids potential race conditions when
a DRQ overtakes a Release Complete.
This is only meaningful in routed mode because in direct mode, the only
mechanism to signal end-of-call is a DRQ.

<item><tt/DropCallsByReleaseComplete=1/<newline>
Default: <tt/0/
<p>
According to Recommendation H.323, the gatekeeper could tear down a call
by sending RAS DisengageRequest to endpoints.
However, some bad endpoints just ignore this command.
With this option turning on, the gatekeeper will send Q.931
Release Complete instead of RAS DRQ to both endpoints to force them
drop the call.

<item><tt/SendReleaseCompleteOnDRQ=1/<newline>
Default: <tt/0/
<p>
On hangup, the endpoint sends both Release Complete within H.225/Q.931 and
DRQ within RAS. It may happen that DRQ is processed first, causing the
gatekeeper to close the call signalling channel, thus preventing the
Release Complete from being forwarding to the other endpoint.
Though the gatekeeper closes the TCP channel to the destination,
some endpoints (e.g. Cisco CallManager) don't drop the call even if
the call signalling channel is closed.
This results in phones that keep ringing if the caller hangs up
before the callee pickups.
Setting this parameter to <tt/1/ makes the gatekeeper always send
Release Complete to both endpoints before closing the call when
it receives DRQ from one of the parties.

<item><tt/SupportNATedEndpoints=1/<newline>
Default: <tt/0/
<p>
Whether to allow an endpoint behind an NAT box register to the gatekeeper.
If yes, the gatekeeper will translate the IP address in Q.931 and H.245
channel into the IP of NAT box.

Since 2.0.1, the GnuGK supports NAT outbound calls (from an endpoint behind NAT
to public networks) directly without any necessary modification
of endpoints or NAT box. Just register the endpoint with the GnuGK
and you can make call now.

<item><tt/Q931PortRange=20000-20999/<newline>
Default: <tt/0/ (random)
<p>
Specify the range of TCP port number for Q.931 signalling channels.
Note the range size may limit the number of concurrent calls.

<item><tt/H245PortRange=30000-30999/<newline>
Default: <tt/0/ (random)
<p>
Specify the range of TCP port number for H.245 control channels.
Note the range size may limit the number of concurrent calls.
</itemize>

<p>
<sect2>Section &lsqb;Proxy&rsqb;
<label id="proxy">
<p>
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 <bf/direct connection/
to both networks of the caller and callee.

<itemize>
<item><tt/Enable=1/<newline>
Default: <tt/0/
<p>
Whether to enable the proxy function. You have to enable gatekeeper
routed mode first (see the <ref id="routed" name="previous section">).
You don't have to specify H.245 routed.
It will automatically be used if required.

<item><tt>InternalNetwork=10.0.1.0/24</tt><newline>
Default: <tt>N/A</tt>
<p>
Define the networks behind the proxy. Multiple internal networks are allow.
The proxy route channels only of the communications between one endpoint
in the internal network and one external. If you don't specify it, all calls
will be proxied.

<descrip>
<tag/Format:/
<tt>InternalNetwork=network address/netmask[,network address/netmask,...]</tt>
<p>
The netmask can be expressed in decimal dot notation or
CIDR notation (prefix length), as shown in the example.
<tag/Example:/
<tt>InternalNetwork=10.0.0.0/255.0.0.0,192.168.0.0/24</tt>
</descrip>

<item><tt/T120PortRange=40000-40999/<newline>
Default: <tt/0/ (random)
<p>
Specify the range of TCP port number for T.120 data channels.
Note the range size may limit the number of concurrent calls.

<item><tt/RTPPortRange=50000-59999/<newline>
Default: <tt/10000-59999/
<p>
Specify the range of UDP port number for RTP/RTCP channels.
Note the range size may limit the number of concurrent calls.
</itemize>

<sect2>Section &lsqb;GkStatus::Auth&rsqb;
<p>
Define a number of rules who is allowed to connect to the status port.
<itemize>
<item><tt/rule=allow/<newline>
Default: <tt/forbid/
<p>
Possible values are
<itemize>
<item><tt/forbid/ - disallow any connection.
<item><tt/allow/ - allow any connection
<item><tt/explicit/ - reads the parameter <tt>ip=value</tt>
where <tt/ip/ is the IP address of the peering client,
<tt/value/ is <tt/1,0/ or <tt/allow,forbid/ or <tt/yes,no/.
If <tt/ip/ is not listed the parameter <tt/default/ is used.
<item><tt/regex/ - the IP of the client is matched against the given regular expression.
<p><descrip>
<tag/Example:/
To allow client from 195.71.129.0/24 and 195.71.131.0/24:
<quote><tt>regex=^195\.71\.(129|131)\.[0-9]+$</tt></quote>
</descrip>
<item><tt/password/ - the user has to input appropriate username and password to login. The format of username/password is the same as <ref id="password" name="[Password]"> section.

</itemize>

Moreover, these rules can be combined by "|" or "&amp;". For example,
<itemize>
<item><tt>rule=explicit | regex</tt><newline>
The IP of client must match <tt/explicit/ <bf/or/ <tt/regex/ rule.
<p>
<item><tt>rule=regex & password</tt><newline>
The IP of client must match <tt/regex/ rule, <bf/and/ the user has to login by username and password.
</itemize>

<item><tt/default=allow/<newline>
Default: <tt/forbid/
<p>
Only used when <tt/rule=explicit/.
</itemize>

<sect2>Section &lsqb;RasSrv::GWPrefixes&rsqb;
<p>
This section lists what E.164 numbers are routed to a specific gateway.

<descrip>
<tag/Format:/
<tt>gw-alias=prefix[,prefix,...]</tt>
<p>
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.
<tag/Example:/
<tt/test-gw=02,03/
</descrip>

<sect2>Section &lsqb;RasSrv::RewriteE164&rsqb;
<label id="rewrite">
<p>
This section defines the rewriting rules for dialedDigits (E.164 number).

<descrip>
<tag/Format:/
<tt>[!]original-prefix=target-prefix[,target-prefix,...]</tt>
<p>
If the number is beginning with <tt/original-prefix/,
it is rewritten to <tt/target-prefix/. Multi targets are possible.
If the `<tt/!/' flag precedes the <tt/original-prefix/, the sense is inverted.
<tag/Example:/
<tt/08=18888/
<p>
If you dial <tt/08345718/, it is rewritten to <tt/18888345718/.
</descrip>

Option:
<itemize>
<item><tt/Fastmatch=08/<newline>
Default: <tt>N/A</tt>
<p>
Only rewrite dialDigits beginning with the specified prefix.
</itemize>

<sect2>Section &lsqb;RasSrv::PermanentEndpoints&rsqb;
<p>
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.

<descrip>
<tag/Format:/
<tt>IP[:port]=alias[,alias,...;prefix,prefix,...]</tt>
<tag/Example:/
For gateway,
<quote/<tt/10.0.1.5=Citron;009,008//
For terminal,
<quote/<tt/10.0.1.10:1720=700//
</descrip>

<sect2>Section &lsqb;RasSrv::Neighbors&rsqb;
<label id="neighbor">
<p>
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 its prefix match the destination or it has prefix
``<tt/*/''. Currently only one prefix is supported.

Conversely, the gatekeeper only reply 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.

The <tt/password/ field is used to authenticate LRQs from that neighbor.
See section <ref id="gkauth" name="[Gatekeeper::Auth]"> for details.

<descrip>
<tag/Format:/
<tt>GKID=ip[:port;prefix;password;dynamic]</tt>
<p>
<tag/Example:/
<tt/GK1=192.168.0.5;*/<newline>
<tt/GK2=10.0.1.1:1719;035;gk2/<newline>
<tt/GK3=gk.citron.com.tw;;gk3;1/
</descrip>

<sect2>Section &lsqb;RasSrv::LRQFeatures&rsqb;
<p>
Defines some features of LRQ and LCF.
<itemize>
<item><tt/NeighborTimeout=1/<newline>
Default: <tt/2/
<p>
Timeout value in seconds to wait responses from neighbors.
If no response from all neighbors after timeout, the gatekeeper will
reply an ARJ to the endpoint sending the ARQ.

<item><tt/ForwardHopCount=2/<newline>
Default: <tt>N/A</tt>
<p>
If the gatekeeper receives an LRQ that the destination is either unknown,
it may forward this message to its neighbors.
When the gatekeeper receives an LRQ and decides that the message
should be forwarded on to another gatekeeeper, it first decrements
<bf/hopCount/ field of the LRQ.
If <bf/hopCount/ has reached 0, the gatekeeper shall not forward the message.
This options defines the number of gatekeepers through which an LRQ
may propagate. Note it only affects the sender of LRQ, not the forwarder.

<item><tt/AlwaysForwardLRQ=1/<newline>
Default: <tt>0</tt>
<p>
Force the gatekeeper to forward an LRQ even if there is no <bf/hopCount/
in the LRQ. To avoid LRQ loops, you should use this option very carefully.

<item><tt/IncludeDestinationInfoInLCF=0/<newline>
Default: <tt/1/
<p>
The gatekeeper replies LCFs containing <bf/destinationInfo/ and
<bf/destinationType/ fields, the aliases and terminal type of the destination
endpoint. The neighbor gatekeeper can then save the information to suppress
later LRQs. However, some vendors' gatekeepers misuse the information, thus
result in interoperability problems.
Only turn off this option if you encounter problems upon communicating
with a third-party gatekeeper.

<item><tt/CiscoGKCompatible=1/<newline>
Default: <tt/0/
<p>
Include a NonStandardParameter in LRQs to compatible with Cisco gatekeepers.

</itemize>

<sect2>Section &lsqb;RasSrv::RRQFeatures&rsqb;
<p>
<itemize>
<item><tt/AcceptGatewayPrefixes=1/<newline>
Default: <tt/1/
<p>
A gateway can register its prefixes with the gatekeeper by containing
<bf/supportedPrefixes/ in the <bf/terminalType/ field of RRQ.
This option defines whether to accept the specified prefixes of a gateway.
</itemize>

<sect2>Section &lsqb;RasSrv::ARQFeatures&rsqb;
<p>
<itemize>
<item><tt/ArjReasonRouteCallToSCN=0/<newline>
Default: <tt/1/
<p>
If yes, the gatekeeper rejects a call from a gateway to itself by reason
<bf/routeCallToSCN/.

<item><tt/ArjReasonRouteCallToGatekeeper=1/<newline>
Default: <tt/1/
<p>
If yes, the gatekeeper rejects an answered ARQ without a pre-existing
CallRec found in the CallTable by reason <bf/routeCallToGatekeeper/
in routed mode.
The endpoint shall release the call immediately and re-send call Setup
to the gatekeeper.

<item><tt/CallUnregisteredEndpoints=0/<newline>
Default: <tt/1/
<p>
With this option set on, the gatekeeper will accept an ARQ from a registered
endpoint with <bf/destCallSignalAddress/, no matter the address is belongs
to a registered endpoint or not.
That means you can explicitly specify the IP of endpoint (registered or not)
you want to call.

<item><tt/RemoveTrailingChar=#/<newline>
Default: <tt>N/A</tt>
<p>
Specify the trailing character to be removed in <bf/destinationInfo/.
For example, if your endpoint incorrectly contains the termination character
like `&num;' in <bf/destinationInfo/, you may remove it by this option.
</itemize>

<sect2>Section &lsqb;CallTable&rsqb;
<p>
<itemize>
<item><tt/GenerateNBCDR=0/<newline>
Default: <tt/1/
<p>
Generate CDRs for calls from neighbor zones.
The IP and endpoint ID of the calling party is printed as empty.
This is usually used for debug purpose.

<item><tt/GenerateUCCDR=0/<newline>
Default: <tt/0/
<p>
Generate CDRs for calls that are unconnected. This is usually
used for debug purpose. Note a call is considered unconnected
only if the gatekeeper uses routed mode and a Q.931 Connect message is not
received by the gatekeeper. In direct mode, a call is always considered
connected.

<item><tt/DefaultCallTimeout=3600/<newline>
Default: <tt/0/
<p>
Default timeout value in seconds to tear down a call.
Set it to <tt/0/ to disable this feature.
</itemize>


<sect2>Section &lsqb;Endpoint&rsqb;
<p>
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.

<itemize>
<item><tt/Gatekeeper=10.0.1.1/<newline>
Default: <tt/no/
<p>
Define a parent gatekeeper for the endpoint(gatekeeper) to register with.
Don't try to register with yourself, unless you want to be confusing.
To disable this feature, set the field to be <tt/no/.

<item><tt/Type=Gateway/<newline>
Default: <tt/Gateway/
<p>
Define the terminal type for the endpoint.
The valid values are <tt/Gateway/ or <tt/Terminal/.

<item><tt/H323ID=CitronProxy/<newline>
Default: <tt>&lt;Name&gt;</tt>
<p>
Specify the H.323 ID aliases for the endpoint.
Multiple aliases can be separated by comma.

<item><tt/E164=18888600000,18888700000/<newline>
Default: <tt>N/A</tt>
<p>
Define the E.164 (dialedDigits) aliases for the endpoint.
Multiple aliases can be separated by comma.

<item><tt/Password=123456/<newline>
Default: <tt>N/A</tt>
<p>
Specify a password to be sent to the parent gatekeeper.
All RAS requests will contain the password in the <bf/cryptoTokens/ field.
To send RAS requests without the <bf/cryptoTokens/ field,
set the field to be empty.
<p>
Besides, the password is also used in LRQs sent to neighbor gatekeepers.

<item><tt/Prefix=188886,188887/<newline>
Default: <tt>N/A</tt>
<p>
Register the specified prefixes with the parent gatekeeper.
Only takes effect when the Type is <tt/Gateway/.

<item><tt/TimeToLive=900/<newline>
Default: <tt>N/A</tt>
<p>
Suggest a time-to-live value in second for the registration.
Note that the real time-to-live timer is assigned by the parent
gatekeeper in the RCF replied to the RRQ.

<item><tt/RRQRetryInterval=10/<newline>
Default: <tt/10/
<p>
Define a retry interval in second for RRQs if no response
received from the parent gatekeeper.

<item><tt/ARQTimeout=2/<newline>
Default: <tt/2/
<p>
Define the timeout value in second for ARQs.

<item><tt/UnregisterOnReload=1/<newline>
Default: <tt/0/
<p>
Defines whether the child gatekeeper unregisters and re-registers with
it's parent when receiving a Reload command.

<item><tt/NATRetryInterval=60/<newline>
Default: <tt/60/
<p>
Retry interval in second for NAT socket.
Leave it out if you don't understand it.

<item><tt/NATKeepaliveInterval=86400/<newline>
Default: <tt/86400/
<p>
Keepalive interval in second for NAT socket.
Leave it out if you don't understand it.
</itemize>


<sect2>Section &lsqb;Endpoint::RewriteE164&rsqb;
<p>
Once you specify prefix(es) for your gatekeeper endpoint, the parent
gatekeeper will route calls with <bf/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.

<descrip>
<tag/Format:/
<tt/external prefix=internal prefix/
</descrip>

For example, if you have the following configuration,

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

With this rule:
<tscreen><verb>
188886=6
</verb></tscreen>

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

The section does not relate to the section
<ref id="rewrite" name="RasSrv::RewriteE164">,
though the later will take effect first.

<sect2>Section &lsqb;Gatekeeper::Auth&rsqb;
<label id="gkauth">
<p>
The section defines the authentication mechanism for the gatekeeper.

<descrip>
<tag/Syntax:/
<tscreen><verb>
authrule=actions

 <authrule> := SimplePasswordAuth | AliasAuth | PrefixAuth | ...
 <actions>  := <control>[;<ras>,<ras>,...]
 <control>  := optional | required | sufficient
 <ras>      := GRQ | RRQ | URQ | ARQ | BRQ | DRQ | LRQ | IRQ
</verb></tscreen>
</descrip>
A rule may results in one of the three codes: ok, fail, pass.
<itemize>
<item><tt/ok/ - The request is authenticated by this module.
<item><tt/fail/ - The authentication fails and should be rejected.
<item><tt/next/ - The rule cannot determine the request.
</itemize>
There are also three ways to control a rule:
<itemize>
<item><tt/optional/ - If the rule cannot determine the request, it is passed to next rule. 
<item><tt/required/ - The requests should be authenticated by this module, or it would be rejected. The authenticated request would then be passwd to next rule.
<item><tt/sufficient/ - If the request is authenticated, it is accepted, or it would be rejected. That is, the rule determines the fate of the request. No rule should be put after a sufficient rule, since it won't take effect.
</itemize>

Currently supported modules:
<itemize>
<item><tt>SimplePasswordAuth/MySQLPasswordAuth/LDAPPasswordAuth/ExternalPasswordAuth</tt>
<p>
These modules check the <bf/tokens/ or <bf/cryptoTokens/ fields of RAS message.
The tokens should contain at least generalID and password.
For <bf/cryptoTokens/, <bf/cryptoEPPwdHash/ tokens hashed by simple MD5 and 
<bf/nestedcryptoToken/ tokens hashed by HMAC-SHA1-96 (libssl must be installed!)
are supported now.
The ID and password are read from <ref id="password" name="[Password]"> section,
MySQL database, LDAP or an external program
for <tt/SimplePasswordAuth/, <tt/MySQLPasswordAuth/, <tt/LDAPPasswordAuth/
and <tt/ExternalPasswordAuth/ modules, respectively.
Support for other backend databases is easily to add.

<item><tt>NeighborPasswordAuth</tt>
<p>
The module is used only to authenticate LRQs from
neighbors defined in section <ref id="neighbor" name="[RasSrv::Neighbors]">.

<item><tt>AliasAuth/MySQLAliasAuth/LDAPAliasAuth</tt>
<p>
The module can only be used to authenticate RegistrationRequest (RRQ).
The IP of an endpoint with a given alias should match a specified pattern.
For <tt/AliasAuth/ the pattern is defined in
<ref id="rrqauth" name="[RasSrv::RRQAuth]"> section.
For <tt/MySQLAliasAuth/, the pattern is retrieved from MySQL database, defined in
<ref id="mysqlaliasauth" name="[MySQLAliasAuth]"> section.
For <tt/LDAPAliasAuth/ the alias (default: mail attribute) and IP
(default: voIPIpAddress attribute) must be found in one LDAP entry.

<item><tt>PrefixAuth</tt>
<p>
Originally known as <tt/GkAuthorize/.
The IP or aliases of a request with a given prefix must match a specified
pattern. See section <ref id="prefixauth" name="[PrefixAuth]"> for details.
Currently the module can only authorize
AdmissionRequest (ARQ) and LocationRequest (LRQ).
</itemize>

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

<descrip>
<tag/Example:/
<tt/SimplePasswordAuth=optional;RRQ,ARQ/<newline>
<tt/AliasAuth=sufficient;RRQ/<newline>
<tt/default=allow/
</descrip>

<sect2>Section &lsqb;Password&rsqb;
<label id="password">
<p>
The section defines the userid and password pairs used by
<tt/SimplePasswordAuth/ module.
Use `<tt/make addpasswd/' to generate the utility <tt/addpasswd/.

Usage:
<tscreen><verb>
addpasswd config userid password
</verb></tscreen>

Options:
<itemize>
<item><tt/KeyFilled=123/<newline>
Default: <tt/0/
<p>
Default value to initialize the encryption key.

<item><tt/CkeckID=1/<newline>
Default: <tt/0/
<p>
Check if the aliases match the ID in the tokens.

<item><tt/PasswordTimeout=120/<newline>
Default: <tt/-1/
<p>
The module <tt/SimplePasswordAuth/ and all its descendants will cache an
authenticated password. This field define the cache timeout value in second.
<tt/0/ means never cache the password, while a negative value
means the cache never expires.
</itemize>

<sect2>Section &lsqb;MySQLAuth&rsqb;
<p>
Define the MySQL database, table and fileds to retrieve the userid and password.

<itemize>
<item><tt/Host=localhost/<newline>
Default: <tt/localhost/
<p>
Host name or IP of the MySQL server.

<item><tt/Database=billing/<newline>
Default: <tt/billing/
<p>
The database to connect.

<item><tt/User=cwhuang/<newline>
<item><tt/Password=123456/<newline>
<p>
The user name and password used to connect to the database.

<item><tt/Table=customer/<newline>
<p>
The table in the database to query.

<item><tt/IDField=IPN/<newline>
<p>
The field name of user id.

<item><tt/PasswordField=Password/<newline>
<p>
The field name of password.

<item><tt/ExtraCriterion=Kind > 0/<newline>
Default: <tt>N/A</tt>
<p>
Specify extra criterion.
</itemize>

The SQL command will be issused:
<tscreen><verb>
SELECT $PasswordField FROM $Table WHERE $IDField = %id [AND $ExtraCriterion]
</verb></tscreen>

<sect2>Section &lsqb;ExternalPasswordAuth&rsqb;
<p>
Specify an external program to retrieve the password.
The program should accept ID from stdin and print the password to stdout.

<itemize>
<item><tt>PasswordProgram=/usr/local/bin/getpasswd</tt><newline>
Default: <tt>N/A</tt>
<p>
The executable of the external program.
</itemize>

<sect2>Section &lsqb;RasSrv::RRQAuth&rsqb;
<label id="rrqauth">
<p>
Specify the action on RRQ reception (confirm or deny) for <tt/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. 

<descrip>
<tag/Syntax:/
<tscreen><verb>
<authrules> :=  empty  |  <authrule> "&" <authrules>

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

The notation and meaning of <tt/&lt;authparams&gt;/ depends on
<tt/&lt;authtype&gt;/:

<itemize>
<item><tt/sigaddr/ - extended regular expression that has to match agains the
``PrintOn(ostream)'' representation of the signal address of the request.
<p>
Example:
<tscreen><verb>
sigaddr:.*ipAddress .* ip = .* c0 a8 e2 a5 .*port = 1720.*
</verb></tscreen>

<item><tt/sigip/ - specialized form of `<tt/sigaddr/'.
Write the signalling ip adresse using (commonly used) decimal notation:
``<tt/byteA.byteB.byteC.byteD:port/''.
<p>
Example:
<tscreen><verb>
sigip:192.168.242.165:1720
</verb></tscreen>

<item><tt/allow/ - always accept the alias.

<item><tt/deny/ - always reject the alias.

</itemize>

<sect2>Section &lsqb;MySQLAliasAuth&rsqb;
<label id="mysqlaliasauth">
<p>
Define the MySQL database, table and fileds to retrieve a pattern for an alias.

<itemize>
<item><tt/Host=localhost/<newline>
Default: <tt/localhost/
<p>
Host name or IP of the MySQL server.

<item><tt/Database=billing/<newline>
Default: <tt/billing/
<p>
The database to connect.

<item><tt/User=cwhuang/<newline>
<item><tt/Password=123456/<newline>
<p>
The user name and password used to connect to the database.

<item><tt/Table=customer/<newline>
<p>
The table in the database to query.

<item><tt/IDField=IPN/<newline>
<p>
The field name of user id.

<item><tt/IPField=Address/<newline>
<p>
The field name of IP address.

<item><tt/ExtraCriterion=Kind > 0/<newline>
Default: <tt>N/A</tt>
<p>
Specify extra criterion.
</itemize>

The SQL command will be issused:
<tscreen><verb>
SELECT $IPField FROM $Table WHERE $IDField = %alias [AND $ExtraCriterion]
</verb></tscreen>

<sect2>Section &lsqb;PrefixAuth&rsqb;
<label id="prefixauth">
<p>
The section defines the authentication rule for <tt/PrefixAuth/ module.
Currently, only ARQs and LRQs can be authorized by this module.

First, a most specific prefix is selected according to the <bf/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 <tt/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.

<descrip>
<tag/Format:/
<tscreen><verb>
prefix=authrule[|authrule|...]
</verb></tscreen>

<tag/Syntax:/
<tscreen><verb>
<authrule> :=  <result> <authrule>

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

<descrip>
<tag/Example:/
<tscreen><verb>
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
</verb></tscreen>
</descrip>

In this configuration, all endpoints except from network <tt>10.0.0.0/27</tt>
are allow to call prefix 555 (except 5555).
Endpoints from <tt>192.168.1.0/24</tt> are not allowed to call prefix 5555,
except <tt/192.168.1.1/.
Endpoints <bf/not/ from <tt>172.16.0.0/24</tt> 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.

<sect2>Section &lsqb;GkLDAP::LDAPAttributeNames&rsqb;
<p>
This section defines which LDAP attribute names to use.

<itemize>
<item><tt/H323ID/<newline>
<p>
The endpoint's H.323 alias. Needs to be unique within the used LDAP tree
(this i why we use the mail address by default).

<item><tt/TelephonNo/<newline>
<p>
The endpoint's E.164 alias.

<item><tt/voIPIpAddress/<newline>
<p>
The IP address to be compared against when using <tt/LDAPAliasAuth/
For now, only a single value is allowed here.

<item><tt/H235PassWord/<newline>
<p>
The plain text password to be compared against when using H.235 
(<tt/LDAPPasswordAuth/ in Gatekeeper::Auth).
For now, only a single value is allowed here.
</itemize>

<sect2>Section &lsqb;GkLDAP::Settings&rsqb;
<p>
This section defines the LDAP server and standard LDAP client operating
parameters to be used.

<itemize>
<item><tt/ServerName/<newline>
Default: <tt/ldap/
<p>
The LDAP server's DNS name.

<item><tt/ServerPort/<newline>
Default: <tt/389/
<p>
The LDAP server's TCP port (usually 389).

<item><tt/SearchBaseDN/<newline>
Default: <tt/o=University of Michigan, c=US/
<p>
Entry point into the server's LDAP tree structure.
Searches are only made below this root node.

<item><tt/BindUserDN/<newline>
Default: <tt/cn=Babs Jensen,o=University of Michigan, c=US/
<p>
The distinguished name the gatekeeper uses to bind
to the LDAP server. Leave empty if you want to access
the LDAP server anonymously.

<item><tt/BindUserPW/<newline>
Default: <tt/ReallySecretPassword/
<p>
If you specified <tt/BindUserDN/, then specify the corresponding
password to be used for binding here.

<item><tt/sizelimit/<newline>
Default: <tt/0/
<p>
Maximum number of results the server may return in response
to a single search query. The gatekeeper expects each LDAP
to only yields one or zero results anyway, so this parameter
is rather useless.

<item><tt/timelimit/<newline>
Default: <tt/0/
<p>
Maximum number of seconds a query may take until it's considered as "failed".

</itemize>


<!----------          Next Section          ---------->
<sect>Monitoring the Gatekeeper (Reference)
<label id="monitor">
<p>
<sect1>Status Interface
<p>
The Status Interface 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 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.

<sect2>Application Areas
<p>
What you do with the powers of the Status Interface is up to you, but here are a few ideas:
<itemize>
<item>Call Monitoring
<item>Monitoring the registered endpoints
<item>Graphical User Interface
<quote>
See GkGUI.
</quote>
<item>Billing Applications
<quote>
Analyse the CDR messages and forward them to a billing application.
</quote>
<item>Interfacing external extensions
<quote>
If you don't want to publish the source code to additinal features, just publish the core functionality and interface to it through the status interface and keep the external part private.
</quote>
</itemize>
<p>
<sect2>Examples
<p>
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 (<tt/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.

<verb>
#!/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";
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");
}
</verb>
<p>

<sect2>GUI for the Gatekeeper
<p>
There are several Graphical User Interface (GUI) frontend for the gatekeeper.

<itemize>
<item>Java GUI<p>
Developed by Jan Willamowius.
You can monitor the registrations and calls that go through the gatekeeper.
A right-click on a button gives you a popup menu for that endpoint.

This GUI works with Java 1.0 built into most web browsers.
For security reasons the GUI must be run as a standalone application
or served by a web server on the same IP number as the gatekeeper
(you cannot run it as an applet via a local file).

Screenshots are available at
<url url="http://www.gnugk.org/h323download.html#java">.

<item>GkGUI<p>
A new standalone Java program developed by 
<url url="http://www.citron.com.tw/" name="Citron Network Inc.">
It requires Java 1.4. New features include:

<itemize>
<item>Monitor multiple gatekeepers simultaneously.
<item>Two view modes: Button List and Tree List.
<item>Call Detail Record(CDR) and statistics.
<item>GK Status Log.
<item>Different colors for different endpoint types.
<item>Modify gatekeeper configuration.
<item>Forcedly unregister endpoints.
<item>Save and print status log and CDR.
</itemize>

The GkGUI is released under GNU General Public License.
</itemize>

<sect1>Commands (Reference)
<p>
The command <tt/help/ or <tt/h/ will show you a list of all available commands.
<p>
<itemize>
<item><tt/Reload/
<p>Reload the configuration.

<item><tt/Version/, <tt/v/
<p>Show the version and OS information of the gatekeeper.

<item><tt/Statistics/, <tt/s/
<p>Show the statistics information of the gatekeeper.
<descrip>
<tag/Example:/
<tscreen><verb>
Statistics
-- Endpoint Statistics --
Total Endpoints: 21  Terminals: 17  Gateways: 4  NATed: 2
Cached Endpoints: 1  Terminals: 1  Gateways: 0
-- Call Statistics --
Current Calls: 1 Active: 1 From Neighbor: 0 From Parent: 0
Total Calls: 1539  Successful: 1076  From Neighbor: 60  From Parent: 5
Startup: Fri, 21 Jun 2002 10:50:22 +0800   Running: 11 days 04:22:59
;
</verb></tscreen>
</descrip>

<item><tt/PrintAllRegistrations/, <tt/r/, <tt/?/
<p>Show all registered endpoints.
<descrip>
<tag/Format:/
<tscreen><verb>
AllRegistrations
RCF|IP:Port|Aliases|Terminal_Type|EndpointID
...
Number of Endpoints: n
;
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
AllRegistrations
RCF|10.1.1.10:1720|800:dialedDigits=Wei:h323_ID|terminal|1289_endp
RCF|10.0.1.43:1720|613:dialedDigits=Jacky Tsai:h323_ID|terminal|1328_endp
RCF|10.0.1.55:1720|705:dialedDigits=Sherry Liu:h323_ID|terminal|1333_endp
Number of Endpoints: 3
;
</verb></tscreen>
</descrip>

<item><tt/PrintAllRegistrationsVerbose/, <tt/rv/, <tt/??/
<p>Show details of all registered endpoints.
<descrip>
<tag/Format:/
<tscreen><verb>
AllRegistrations
RCF|IP:Port|Aliases|Terminal_Type|EndpointID
Registration_Time C(Active_Call/Connected_Call/Total_Call) <r>
[Prefixes: ##] (gateway only)
...
Number of Endpoints: n
;
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
AllRegistrations
RCF|10.0.1.8:1720|Accel-GW2:h323_ID|gateway|1322_endp
Wed, 26 Jun 2002 16:40:03 +0800 C(1/5/33) <1>
Prefixes: 09,002
RCF|10.1.1.10:1720|800:dialedDigits=Wei:h323_ID|terminal|1289_endp
Wed, 26 Jun 2002 16:40:55 +0800 C(0/32/39) <1>
RCF|10.0.1.66:1720|716:dialedDigits=Vicky:h323_ID|terminal|1425_endp
Wed, 26 Jun 2002 16:40:58 +0800 C(1/47/53) <1>
Number of Endpoints: 2
;
</verb></tscreen>
</descrip>

<item><tt/PrintCurrentCalls/, <tt/c/, <tt/!/
<p>Show all current calls.
<descrip>
<tag/Format:/
<tscreen><verb>
CurrentCalls
Call No. # | CallID | Call_Duration | Left_Time
Dialed_Number
ACF|Caller_IP:Port|Caller_EPID|CRV
ACF|Callee_IP:Port|Callee_EPID|CRV
...
Number of Calls: Current_Call Active: Active_Call From Neighbor: Call_From_Neighbor From Parent: Call_From_Parent
;
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
CurrentCalls
Call No. 29 | CallID bd c6 17 ff aa ea 18 10 85 95 44 45 53 54 77 77 | 109 | 491
Dial 0953378875:dialedDigits
ACF|10.0.1.49:1720|4048_CGK1|25263
ACF|10.1.1.1:1720|4037_CGK1|25263
Call No. 30 | CallID 70 0e dd c0 9a cf 11 5e 00 01 00 05 5d f9 28 4d | 37 | 563
Dial 0938736860:dialedDigits
ACF|10.0.1.48:1032|4041_CGK1|11896
ACF|10.1.1.1:1720|4037_CGK1|11896
Number of Calls: 2 Active: 2 From Neighbor: 0 From Parent: 0
;
</verb></tscreen>
</descrip>

<item><tt/PrintCurrentCallsVerbose/, <tt/cv/, <tt/!!/
<p>Show details of all current calls.
<descrip>
<tag/Format:/
<tscreen><verb>
CurrentCalls
Call No. # | CallID | Call_Duration | Left_Time
Dialed_Number
ACF|Caller_IP:Port|Caller_EPID|CRV
ACF|Callee_IP:Port|Callee_EPID|CRV
# Caller_Aliases|Callee_Aliases|Bandwidth|Connected_Time <r>
...
Number of Calls: Current_Call Active: Active_Call From NB: Call_From_Neighbor
;
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
CurrentCalls
Call No. 48 | CallID 7d 5a f1 0a ad ea 18 10 89 16 00 50 fc 3f 0c f5 | 30 | 570
Dial 0225067272:dialedDigits
ACF|10.0.1.200:1720|1448_endp|19618
ACF|10.0.1.7:1720|1325_endp|19618
# Sherry:h323_ID|Accel-GW1:h323_ID|200000|Wed, 26 Jun 2002 17:29:55 +0800 <2>
Number of Calls: 1 Active: 1 From NB: 0
;
</verb></tscreen>
</descrip>

<item><tt/Find/, <tt/f/
<p>Find a registered endpoint by an alias or a prefix.
<descrip>
<tag/Format:/
<tscreen><verb>
Find Alias
RCF|IP:Port|Aliases|Terminal_Type|EndpointID
;
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
f 800
RCF|10.1.1.10:1720|800:dialedDigits=Wei:h323_ID|terminal|1289_endp
;
f 801
SoftPBX: alias 801 not found!
</verb></tscreen>
</descrip>

<item><tt/FindVerbose/, <tt/fv/
<p>Find details of a registered endpoint by an alias or a prefix.
<descrip>
<tag/Format:/
<tscreen><verb>
FindVerbose Alias
RCF|IP:Port|Aliases|Terminal_Type|EndpointID
Registration_Time C(Active_Call/Connected_Call/Total_Call) <r>
[Prefixes: ##] (gateway only)
;
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
fv 02
RCF|10.0.1.100:1720|TFN:h323_ID|gateway|4037_CGK1
Wed, 26 Jun 2002 17:47:29 +0800 C(0/84/120) <1>
Prefixes: 02,09
;
</verb></tscreen>
</descrip>

<item><tt/UnregisterIP/
<p>Forcedly unregister an endpoint by IP and call signalling port.
<descrip>
<tag/Format:/
<tscreen><verb>
UnregisterIP IP[:Port]
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
UnregisterIP 10.0.1.31:1720
URQ|10.0.1.31:1032|1326_endp|maintenance;
SoftPBX: Endpoint 10.0.1.31:1720 unregistered!
</verb></tscreen>
</descrip>

<item><tt/UnregisterAlias/
<p>Forcedly unregister an endpoint by one of its aliases.
<descrip>
<tag/Format:/
<tscreen><verb>
UnregisterAlias Alias
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
UnregisterAlias 601
URQ|10.0.1.31:1032|1326_endp|maintenance;
SoftPBX: Endpoint 601 unregistered!
</verb></tscreen>
</descrip>

<item><tt/UnregisterAllEndpoints/
<p>Forcedly unregister all registered endpoints.
<descrip>
<tag/Format:/
<tscreen><verb>
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
UnregisterAllEndpoints
URQ|10.0.1.7:1024|1325_endp|maintenance;
URQ|10.0.1.8:1024|1322_endp|maintenance;
URQ|10.0.1.32:1032|1324_endp|maintenance;
URQ|10.0.1.36:1032|1323_endp|maintenance;
URQ|10.0.1.42:1032|1318_endp|maintenance;
Done
;
</verb></tscreen>
</descrip>

<item><tt/DisconnectCall/
<p>Disconnect a call with given number.
<descrip>
<tag/Format:/
<tscreen><verb>
DisconnectCall Number
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
DisconnectCall 1533
</verb></tscreen>
</descrip>

<item><tt/DisconnectIP/
<p>Disconnect all calls of an endpoint by IP and call signalling port.
<descrip>
<tag/Format:/
<tscreen><verb>
DisconnectIP IP[:Port]
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
DisconnectIP 10.0.1.31:1720
</verb></tscreen>
</descrip>

<item><tt/DisconnectAlias/
<p>Disconnect all calls of an endpoint by one of its aliases.
<descrip>
<tag/Format:/
<tscreen><verb>
DisconnectAlias Alias
</verb></tscreen>
<tag/Example:/
<tscreen><verb>
DisconnectAlias 601
</verb></tscreen>
</descrip>

<item><tt/ClearCalls/
<p>Disconnect all calls on the gatekeeper.

<item><tt/GK/
<p>Show the information of the parent gatekeeper.

<item><tt/Debug/
<p>Only used for debug purpose. Options:
<itemize>
<item><tt/trc [+|-|n]/
<p>Show/modify trace level.
<item><tt/cfg SEC PAR/
<p>Read and print a config parameter in a section.
<item><tt/set SEC PAR VAL/
<p>Write a config value parameter in a section.
<item><tt/remove SEC PAR/
<p>Remove a config value parameter in a section.
<item><tt/remove SEC/
<p>Remove a section.
<item><tt/printrm VERBOSE/
<p>Print all removed endpoint records.
</itemize>
<descrip>
<tag/Example:/
<tscreen><verb>
debug trc 3
debug set RoutedMode H245Routed 1
</verb></tscreen>
</descrip>

<item><tt/Who/
<p>Show all people on the status port.

<item><tt/Exit/, <tt/q/
<p>Quit the status port.

</itemize>

<sect1>Messages (Reference)
<p>The section describes the messages output to the status interface.

<itemize>
<item><tt/GCF|IP|Aliases|Endpoint_Type;/
<p>The gatekeeper receives a GatekeeperRequest (GRQ) and responds with
a GatekeeperConfirm (GCF).

<item><tt/GRJ|IP|Aliases|Endpoint_Type|RejectReason;/
<p>The gatekeeper receives a GatekeeperRequest (GRQ) and responds with
a GatekeeperReject (GRJ).

<item><tt/RCF|IP:Port|Aliases|Endpoint_Type|EndpointID;/
<p>The gatekeeper receives a RegistrationRequest (RRQ) and responds with
a RegistrationConfirm (RCF).

<item><tt/RRJ|IP|Aliases|Endpoint_Type|RejectReason;/
<p>The gatekeeper receives a RegistrationRequest (RRQ) and responds with
a RegistrationReject (RRJ).

<item><tt/ACF|Caller_IP:Port|Caller_EndpointID|CRV|DestinationInfo|SrcInfo|IsAnswered;/
<p>The gatekeeper receives an AdmissionRequest (ARQ) and responds with
an AdmissionConfirm (ACF).

<item><tt/ARJ|Caller_IP:Port|DestinationInfo|SrcInfo|IsAnswered|RejectReason;/
<p>The gatekeeper receives an AdmissionRequest (ARQ) and responds with
an AdmissionReject (ARJ).

<item><tt/DCF|IP|EndpointID|CRV|DisengageReason;/
<p>The gatekeeper receives a DisengageRequest (DRQ) and responds with
a DisengageConfirm (DCF).

<item><tt/DRJ|IP|EndpointID|CRV|RejectReason;/
<p>The gatekeeper receives a DisengageRequest (DRQ) and responds with
a DisengageReject (DRJ).

<item><tt/LCF|IP|EndpointID|DestinationInfo|SrcInfo;/
<p>The gatekeeper receives a LocationRequest (LRQ) and responds with
a LocationConfirm (LCF).

<item><tt/LRJ|IP|DestinationInfo|SrcInfo|RejectReason;/
<p>The gatekeeper receives a LocationRequest (LRQ) and responds with
a LocationReject (LRJ).

<item><tt/BCF|IP|EndpointID|Bandwidth;/
<p>The gatekeeper receives a BandwidthRequest (BRQ) and responds with
a BandwidthConfirm (BCF).

<item><tt/BRJ|IP|EndpointID|Bandwidth|RejectReason;/
<p>The gatekeeper receives a BandwidthRequest (BRQ) and responds with
a BandwidthReject (BRJ).

<item><tt/UCF|IP|EndpointID;/
<p>The gatekeeper receives an UnregistrationRequest (URQ) and responds with
an UnregistrationConfirm (UCF).

<item><tt/URJ|IP|EndpointID|RejectReason;/
<p>The gatekeeper receives an UnregistrationRequest (URQ) and responds with
an UnregistrationReject (URJ).

<item><tt/IRQ|IP:Port|EndpointID;/
<p>The gatekeeper sends an InfoRequest (IRQ) to an endpoint to query if it
is still alive. The endpoint shall respond with an InfoRequestResponse (IRR)
immediately.

<item><tt/URQ|IP:Port|EndpointID|Reason;/
<p>The gatekeeper sends an UnregistrationRequest (URQ) to an endpoint to
cancel its registration. The endpoint shall respond with
an UnregistrationConfirm (UCF).

<item><tt/CDR|CallNo|CallId|Duration|Starttime|Endtime|CallerIP|CallerEndId|/ \
<newline><tt/CalledIP|CalledEndId|DestinationInfo|SrcInfo|GatekeeperID;/
<p>After a call disconnected, the call detail record is shown (in one line).

</itemize>


<!----------          FAQ Section          ---------->
<!--
<sect>Frequently Asked Questions
<sect1>General Questions
<p>

<itemize>
<item>What is an H.323 gatekeeper?
<p>
An H.323 gatekeeper controls all H.323 endpoints (like MS Netmeeting)
in his zone. Its most important function is address translation between
symbolic alias addresses and IP addresses. This way you can call
"jan" instead of knowing which IP address he currently works on.

<item>Why should I use a gatekeeper?
<p>
If you currently use a client and are happy with the way it works
there may be no reason to use a gatekeeper. However, if you work in a larger
VoIP setup using symbolic addresses is definitely a great plus.
More importantly the gatekeeper is the key to the management of a VoIP network.

VoIP gateways for example register at the gatekeeper and the gatekeeper
finds the right one for you to use to call a specific number.

A gatekeeper can also manage the bandwidth used by the clients.
Currently we grant all bandwidth requests until a predefined limit is reached.
In the future we could implement a more detailed schema. 

<item>What OS do I need to compile / run the gatekeeper?
<p>
Stable version of the gatekeeper run on all platforms supported by the OpenH323
library, which include a wide variety of Unixes such as Linux, FreeBSD,
Solaris, and MS-Windows and others OSes.
However, not all platforms are well-tested.
The developers use Linux and MS-Windows to test the gatekeeper.
Be careful if you're using other OS and report problems if you find bugs.

<item>Can I get a pre-compiled binary?
<p>
There are a few pre-compiled binaries on the project homepage,
but they might not be the most recent version.
See the <ref id="download" name="Download section">.

</itemize>

<sect1>Authentication
<p>
<sect1>Firewall/NAT Issues
<p>
<itemize>
<item>
</itemize>

<sect1>Redundancy
<p>
-->
</article>
