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 -l overrides the setting TimeToLive
in the configuration file.
Almost every option has a short and a long format, e.g.,
-c is the same as --config.
-h --helpShow all available options and quit the program.
-c --config filenameSpecify the configuration file to use.
-s --section sectionSpecify which main section to use in the configuration file. The default is [Gatekeeper::Main].
-i --interface IPSpecify the interface (IP number) 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.
-l --timetolive nSpecify the time-to-live timer (in seconds) for endpoint registration.
It overrides the setting TimeToLive in the configuration file.
See
there for detailed explanations.
-b --bandwidth nSpecify the total bandwidth available for the gatekeeper. Without specifying this option, the bandwidth management is disable by default.
--pid filenameSpecify the pid file, only valid for Unix version.
-u --user nameRun the gatekeeper process as this user. Only valid for Unix versions.
--core n(Unix only) Enable writting core dump files when the application crashes. A core dump file will not exceed n bytes in size. A special constant "unlimited" may be used to not enforce any particular limit.
The options in this subsection override the settings in the [RoutedMode] section of the configuration file.
-d --directUse direct endpoint call signalling.
-r --routedUse gatekeeper routed call signalling.
-rr --h245routedUse gatekeeper routed call signalling and H.245 control channel.
-o --output filenameWrite trace log to the specified file.
-t --traceSet trace verbosity. The more -t you add, the more verbose to output.
For example, use -ttttt to set the trace level to 5.
The configuration file is a standard text file. The basic format is:
[Section String]
Key Name=Value String
Comments are marked with a hash (#) or a semicolon (;)
at the beginning of a line.
The file
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 reload command
via status port, or send a signal HUP to the gatekeeper process on Unix.
For example,
kill -HUP `cat /var/run/gnugk.pid`
Fourtytwo=42N/A
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.
Name=OpenH323GKOpenH323GK
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.
Home=192.168.1.10.0.0.0
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. Multiple Home addresses can be used and have to be separated with a semicolon (;) or comma (,).
NetworkInterfaces=192.168.1.1/24,10.0.0.1/0N/A
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.
EndpointIDSuffix=_gk1_endp
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.
TimeToLive=300-1
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 timeToLive field in the RCF message. After the specified time, the registration has expired. The endpoint shall periodically send an RRQ having the 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 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 alivef 10 rule on machine one.
The first instance of OhPhone will accept that call and Peter and Jan can chat.
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.
But this is very insecure - everyboy could connect to the status interface and see this. Lets change the the configuration file to
[Gatekeeper::Main]
Fourtytwo=42
[GkStatus::Auth]
rule=password
gkadmin=QC7VyAo5jEw=
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.
Take a look at the GkStatus::Auth section for more details on securing the status ports.
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.
jan@machine1 > gnugk -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 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. ;-)
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 "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.
Take a look at the other telephony functions like TransferCall to see what else is available.
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 [RasSrv::GWPrefixes] section of the config file to tell the gatekeeper the prefix of numbers that shall be routed over the gateway.
[RasSrv::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.)
A prefix can contain digits 0-9, # and *. It can also
contain a special character . (a dot) that matches any digit
and can be prefixed with ! (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. Some examples:
[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..........
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 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".
[RasSrv::GWPrefixes]
gw1=0
[RasSrv::RewriteE164]
12345=08765
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 RasSrv::GWRewriteE164 section.
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.
[RasSrv::GWPrefixes]
gw1=0044
gw2=0044
[RasSrv::GWRewriteE164]
gw1=out=0044=77770044
gw2=out=0044=88880044
Example: You want to identify calls from a particular gateway "gw1" with a specific prefix before passing these calls to another gateway "gw2".
[RasSrv::GWPrefixes]
gw2=1
[RasSrv::GWRewriteE164]
gw1=in=00=123400
Rewrite expressions accept dot '.' and percent sign '%' 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 '.' to match any character and copy it
to the rewritten string and '%' to match any character and skip it.
A few simple examples:
[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