<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
<TITLE>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 confirm that all components are up and running, get
2 Linux workstations, both connected to the LAN.
In addition to GnuGk the examples use a softphone called "OhPhone".
On the first machine run the gatekeeper in direct mode:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > gnugk -ttt
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The "<CODE>-ttt</CODE>" option tells the gatekeeper that it should be verbose with the debug output
to the console. You can direct the output to a file with "<CODE>-o logfilename.log</CODE>"</P>
<P>Now start OhPhone on another console:
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > ohphone -l -a -u jan
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>OhPhone is now listening (<CODE>-l</CODE>) for calls and will automatically accept
them (<CODE>-a</CODE>). It has also registered with the gatekeeper as user jan. OhPhone
will attempt to automatically locate the gatekeeper, but if the auto
detect fails, use "<CODE>-g 1.2.3.4</CODE>" to specify the IP address of the gatekeeper.</P>
<P>On the second machine run ohphone this way:</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 address from
where user jan has registered (machine1 in this case) and OhPhone
will call the other instance of OhPhone on machine1.</P>
<P>The instance of OhPhone on machine1 will automatically accept the 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>The status interface presents a text-based means of interacting with an already-running gatekeeper.</P>
<P>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>You should receive an "Access forbidden!" message because access to the status port is restricted by default.</P>
<P>Create a file called <CODE>gatekeeper.ini</CODE> in the
directory where we start the gatekeeper.
<CODE>gatekeeper.ini</CODE> will contain the following 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, but specify that it should use the <CODE>gatekeeper.ini</CODE> we just created:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > gnugk -ttt -c ./gatekeeper.ini
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Use telnet to connect to port 7000 and you should now be allowed to connect to the gatekeeper:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > telnet localhost 7000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Version:
Gatekeeper(GNU) Version(2.3.1) Ext(pthreads=1,radius=1,mysql=0,pgsql=0,firebird=0,odbc=0,sqlite=0,large_fdset=0,crypto/ssl=1,h46018=1,h46023=1) Build(Aug 12 2009, 09:30:37) Sys(Linux i686 2.6.28-14-generic)
Startup: Tue, 25 Aug 2009 15:30:44 -0500 Running: 2 days 21:30:50
;
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Now repeat the first experiment where Peter calls Jan and see which
messages are handled by the gatekeeper in non-routed mode.</P>
<P>There are a number of commands that can be issued in the telnet session - type "help" to see them.</P>
<P>To end the telnet session with the gatekeeper type "quit" and hit Enter.</P>
<P>However, the example configuration file we created is very insecure because it has a default <B>allow</B> rule, so there are no
restrictions on who can connect and which commands they may execute.</P>
<P>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 was added by the addpasswd utility, which was used to create a user "gkadmin" with
password "secret". This change now enforces authentication to the status port.</P>
<P>Restart the gatekeeper with this new configuration and perform the telnet again.
You should now be prompted for a username and password:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > telnet localhost 7000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
GnuGk login: gkadmin
Password: secret
Version:
Gatekeeper(GNU) Version(2.3.1) Ext(pthreads=1,radius=1,mysql=0,pgsql=0,firebird=0,odbc=0,sqlite=0,large_fdset=0,crypto/ssl=1,h46018=1,h46023=1) Build(Aug 12 2009, 09:30:37) Sys(Linux i686 2.6.28-14-generic)
Startup: Tue, 25 Aug 2009 15:30:44 -0500 Running: 2 days 21:33:32
;
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The
<A HREF="manual-4.html#gkstatusauth">GkStatus::Auth</A> section contains additional information on securing the status port.</P>
<H2><A NAME="ss3.3">3.3</A> <A HREF="manual.html#toc3.3">Running the gatekeeper in routed mode</A>
</H2>
<P>Starting the gatekeeper in routed mode means that the gatekeeper
uses "gatekeeper routed signaling".
All signaling messages go through the gatekeeper, giving it
much greater control over the calls.</P>
<P>Start GnuGk like this:
<BLOCKQUOTE><CODE>
<PRE>
jan@machine1 > gnugk -r
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>will put the gatekeeper 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 acted only as a mechanism
to resolve symbolic names to IP addresses. This is a critical function of
a gatekeeper, but the gatekeeper is capable of much more.</P>
<P>Because the gatekeeper has a lot of control over the calls,
it can also be used to terminate them. While
connected to the status port, you can list all active calls
with "<CODE>PrintCurrentCalls</CODE>". To terminate a call, type
"<CODE>Disconnectip 1.2.3.4</CODE>" for one of the endpoints.</P>
<P>For example, a simple script could be written to connect to
the status port, obtain a list of ongoing calls and terminate
them after 5 minutes to prevent users from using too many system resources.</P>
<P>Other functions such as TransferCall are also available.</P>
<H2><A NAME="ss3.5">3.5</A> <A HREF="manual.html#toc3.5">Routing calls to 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 must be configured to specify which calls should be routed
to the gateway and which numbers can be called directly.
Use the [RasSrv::GWPrefixes] section of the config file to tell
the gatekeeper the prefix of numbers that should be routed to 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. </P>
<P><B>NOTE:</B> You must use the gateway alias - you cannot use the IP address 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 according 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 gw1
gw1=0048,!004850,!004860
; This entry will match only 001 with 10 digits following and route the call to
; gw2
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 your 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
on both the left and right hand sides of expressions. The percent sign can occur
only at the left side. 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>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
contrib-release
>
by-pkgid
>
aa0a0c745bf74bd0c70c4944117a40d3
>
files
>
166
