A first simple experiment with the gatekeeper
=============================================

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

jan@machine1 > gk -ttt

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

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

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

On the second machine run ohphone only:

peter@machine2 > ohphone -u peter jan

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

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


Using the Status interface to spy on the gatekeeper
===================================================

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

jan@machine1 > telnet machine1 7000

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

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

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


Starting the gatekeeper in routed mode
======================================

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

jan@machine1 > gk -r

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

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

Since gatekeeper routed signaling 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. ;-)


A virtual PBX: Disconnecting calls via the gatekeeper
=====================================================

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

Since the gatekeeper has a lot of control over the calls,
it can terminate them for example. When we are
connected to the status port, we can list all active calls
with "PrintCurrentCalls". To terminate a call, we can
say "Disconnect 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.)


Routing calls over a gateway to reach external users
=====================================================

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

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

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

[RasSvr::GWPrefixes]
gw1=0

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


Rewriting E.164 numbers
=======================

When using a gateway you often have to use different numbers internally
and rewrite them before sending them over a gateway into the telephone
network. You can use the [RasSvr::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".

[RasSvr::GWPrefixes]
gw1=0

[RasSvr::RewriteE164]
12345=08765