<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
<TITLE>OpenH323 Gatekeeper - The GNU Gatekeeper: Getting Started (Tutorial)</TITLE>
<LINK HREF="manual-4.html" REL=next>
<LINK HREF="manual-2.html" REL=previous>
<LINK HREF="manual.html#toc3" REL=contents>
</HEAD>
<BODY>
<A HREF="manual-4.html">Next</A>
<A HREF="manual-2.html">Previous</A>
<A HREF="manual.html#toc3">Contents</A>
<HR>
<H2><A NAME="s3">3.</A> <A HREF="manual.html#toc3">Getting Started (Tutorial)</A></H2>
<H2><A NAME="ss3.1">3.1</A> <A HREF="manual.html#toc3.1">A first simple experiment</A>
</H2>
<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):</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > gnugk -ttt
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Now the gatekeeper is running in direct mode.
The "<CODE>-ttt</CODE>" option tells the gatekeeper to do a lot of debug output
on the console (you can direct that output to a file with "<CODE>-o logfile</CODE>").</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > ohphone -l -a -u jan
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Now this OhPhone is listening (<CODE>-l</CODE>) for calls and will automatically
accept them (<CODE>-a</CODE>). It has registered as user jan with the gatekeeper
that it will automatically detect. (If the auto detect fails for some
reason use "<CODE>-g 1.2.3.4</CODE>" to specify the IP number the gatekeeper
is running on.)</P>
<P>On the second machine run ohphone only:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
peter@machine2 > ohphone -u peter jan
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>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.</P>
<P>The first instance of OhPhone will accept that call and Peter and Jan can chat.</P>
<H2><A NAME="ss3.2">3.2</A> <A HREF="manual.html#toc3.2">Using the Status interface to monitor the gatekeeper</A>
</H2>
<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:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > telnet machine1 7000
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Most probably we'll get an "Access forbidden!" message, because
not everybody is allowed to spy.</P>
<P>Now we create a file called <CODE>gatekeeper.ini</CODE> and put it in the
directory where we start the gatekeeper.
<CODE>gatekeeper.ini</CODE> only contains 4 lines:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Main]
Fortytwo=42
[GkStatus::Auth]
rule=allow
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>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.</P>
<P>But this is very insecure - everybody could connect to the status interface and see this.
Lets change the configuration file to</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Main]
Fortytwo=42
[GkStatus::Auth]
rule=password
gkadmin=QC7VyAo5jEw=
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The 5th line is added by addpasswd utility, it creates a user "gkadmin" with
password "secret" which will limit access to the status port.
Restart the gatekeeper with this new configuration and do the telnet again.
Now you will be asked for a username and password before you can login.</P>
<P>Take a look at the
<A HREF="manual-4.html#gkstatusauth">GkStatus::Auth</A> section for more details on securing the status ports.</P>
<H2><A NAME="ss3.3">3.3</A> <A HREF="manual.html#toc3.3">Starting the gatekeeper in routed mode</A>
</H2>
<P>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.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > gnugk -r
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>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.</P>
<P>Note that all media packets (audio and video) are still sent
directly between the endpoints (the 2 instances of ohphone).</P>
<H2><A NAME="ss3.4">3.4</A> <A HREF="manual.html#toc3.4">A virtual PBX: Disconnecting calls</A>
</H2>
<P>Until now the gatekeeper has only acted as a mechanism
to resolve symbolic names to IP addresses. That's an important
function but hardly exciting.</P>
<P>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 "<CODE>PrintCurrentCalls</CODE>". To terminate a call, we can
say "<CODE>Disconnectip 1.2.3.4</CODE>" for one of its endpoints.</P>
<P>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.</P>
<P>Take a look at the other telephony functions like TransferCall to see what else is available.</P>
<H2><A NAME="ss3.5">3.5</A> <A HREF="manual.html#toc3.5">Routing calls over a gateway to reach external users</A>
</H2>
<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.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
_________________ ______________
| endpoint "jan"| | |
| 192.168.88.35 |--------->| Gatekeeper |
|_______________| | |
_________________ | |
| gateway "gw1" | outgoing | |
| 192.168.88.37 |<---------|____________|
|_______________|
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>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.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
gw1=0
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>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.)</P>
<P>A prefix can contain digits <CODE>0-9</CODE>, <CODE>#</CODE> and <CODE>*</CODE>. It can also
contain a special character <CODE>.</CODE> (a dot) that matches any digit
and can be prefixed with <CODE>!</CODE> (an exclamation mark) to disable the prefix.
Prefix matching is done accordingly to the longest matching prefix rule,
with ! rules having higher priority if lengths are equal. You may also use := syntax to set the priority between several gateways matching the same prefix (see section
<A HREF="manual-7.html#gwprefixes">[RasSrv::GWPrefixes]</A> for details). Some examples:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
; This entry will route numbers starting with 0048 (but not with 004850 and 004860)
; to the gw1
gw1=0048,!004850,!004860
; This entry will match only 001 with 10 digits following
gw2=001..........
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss3.6">3.6</A> <A HREF="manual.html#toc3.6">Rewriting E.164 numbers</A>
</H2>
<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
<A HREF="manual-6.html#rewrite">RasSrv::RewriteE164</A>
section to configure that.</P>
<P>Example:
You want to call number 12345 with you IP Phone and would like to
reach number 08765 behind a gateway called "gw1".</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
gw1=0
[RasSrv::RewriteE164]
12345=08765
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>You can also configure rewriting of E.164 numbers based on which gateway
you are receiving a call from or sending a call to using the
<A HREF="manual-6.html#gwrewrite">RasSrv::GWRewriteE164</A> section.</P>
<P>Example:
You have two different gateways ("gw1" and "gw2") which you are sending
calls with prefix 0044 to, but which require a different prefix to be
added to the number after the routing has selected the gateway. This
might be for identification purposes for example.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
gw1=0044
gw2=0044
[RasSrv::GWRewriteE164]
gw1=out=0044=77770044
gw2=out=0044=88880044
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Example:
You want to identify calls from a particular gateway "gw1" with a specific
prefix before passing these calls to another gateway "gw2".</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::GWPrefixes]
gw2=1
[RasSrv::GWRewriteE164]
gw1=in=00=123400
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Rewrite expressions accept dot <CODE>'.'</CODE> and percent sign <CODE>'%'</CODE> wildcard
characters to allow building more general rules. The dot character can occur
at both left and right hand sides of expressions, the percent sign can occur
only at the left side only. Use <CODE>'.'</CODE> to match any character and copy it
to the rewritten string and <CODE>'%'</CODE> to match any character and skip it.
A few simple examples:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
[RasSrv::RewriteE164]
; Rewrite 0044 + min. 7 digits to 44 + min. 7 digits
0044.......=44.......
; Rewrite numbers starting with 11 + 4 digits + 11 to 22 + 4 digits + 22
; (like 11333311 => 22333322, 110000112345 => 220000222345)
11....11=22....22
; strip the first four digits from all numbers (11114858345 => 4858345)
; this is equivalent of 10 rules %%%%1=1, %%%%2=2, ...
%%%%.=.
; insert two zeros in the middle of the number (111148581234 => 11110048581234)
....48=....0048
; even this is possible (415161 => 041051061)
4.5.6=04.05.06
</PRE>
</CODE></BLOCKQUOTE>
</P>
<HR>
<A HREF="manual-4.html">Next</A>
<A HREF="manual-2.html">Previous</A>
<A HREF="manual.html#toc3">Contents</A>
</BODY>
</HTML>
