Next Previous Contents

4. Using the Gatekeeper (Reference)

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.

4.1 Command Line Options

Almost every option has a short and a long format, e.g., -c is the same as --config.

Basic

-h --help

Show all available options and quit the program.

-c --config filename

Specify the configuration file to use.

-s --section section

Specify which main section to use in the configuration file. The default is [Gatekeeper::Main].

-i --interface IP

Specify 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 n

Specify 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 n

Specify the total bandwidth available for the gatekeeper. Without specifying this option, the bandwidth management is disable by default.

--pid filename

Specify the pid file, only valid for Unix version.

-u --user name

Run the gatekeeper process as this user. Only valid for Unix versions.

Gatekeeper Mode

The options in this subsection override the settings in the [RoutedMode] section of the configuration file.

-d --direct

Use direct endpoint call signalling.

-r --routed

Use gatekeeper routed call signalling.

-rr --h245routed

Use gatekeeper routed call signalling and H.245 control channel.

Debug Information

-o --output filename

Write trace log to the specified file.

-t --trace

Set trace verbosity. The more -t you add, the more verbose to output. For example, use -ttttt to set the trace level to 5.

4.2 Configuration File

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`

Note Some section names in GnuGk 2.0.0 are named RasSrv::*, while others are named RasSvr::*. This inconsistency confused users. In 2.0.1 all sections are corrected to RasSrv::*. If you upgrade from 2.0.0 or earlier version, remember to change the section names, or GnuGk will refuse to start.

Section Gatekeeper::Main

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

Section RoutedMode

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.

Case I.

The gatekeeper doesn't route them. The H.245 control channel and logical channels are established directly between the endpoints.

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.

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.

This section defines the gatekeeper routed mode options (case I II). The proxy feature is defined in the next section. All settings in this section are affected by reloading.

Section Proxy

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 direct connection to both networks of the caller and callee.

Section GkStatus::Auth

Define a number of rules who is allowed to connect to the status port. Whoever has access to the status port has full control over your gatekeeper. Make sure this is set correctly.

Section RasSrv::GWPrefixes

This section lists what E.164 numbers are routed to a specific gateway.

Format:

gw-alias=prefix[,prefix,...]

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.

Example:

test-gw=02,03

Section RasSrv::RewriteE164

This section defines the rewriting rules for dialedDigits (E.164 number).

Format:

[!]original-prefix=target-prefix[,target-prefix,...]

If the number is beginning with original-prefix, it is rewritten to target-prefix. Multi targets are possible. If the `!' flag precedes the original-prefix, the sense is inverted.

Example:

08=18888

If you dial 08345718, it is rewritten to 18888345718.

Option:

Section RasSrv::PermanentEndpoints

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.

Format:

IP[:port]=alias[,alias,...;prefix,prefix,...]

Example:

For gateway,

10.0.1.5=Citron;009,008
For terminal,
10.0.1.10:1720=700

Section RasSrv::Neighbors

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 one of its prefixes matches the destination or it has ``*'' prefix. More than one prefix can be specified.

Conversely, the gatekeeper will only reply to 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. By the empty prefix it is meant a single semicolon appended to the neighbor entry. Example:

GK1=192.168.0.5;

If you skip the semicolon, LRQs will be always sent to this neighbor.

The password field is used to authenticate LRQs from that neighbor. See section [Gatekeeper::Auth] for details.

Format:

GKID=ip[:port;prefixes;password;dynamic]

Example:

GK1=192.168.0.5;*
GK2=10.0.1.1:1719;035,036;gk2
GK3=gk.citron.com.tw;;gk3;1

Section RasSrv::LRQFeatures

Defines some features of LRQ and LCF.

Section RasSrv::RRQFeatures

Section RasSrv::ARQFeatures

Section CallTable

Section Endpoint

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.

Section Endpoint::RewriteE164

Once you specify prefix(es) for your gatekeeper endpoint, the parent gatekeeper will route calls with 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.

Format:

external prefix=internal prefix

For example, if you have the following configuration,

                        [Parent GK]
                        ID=CitronGK
                        /         {[bsol  ]}
                       /           {[bsol  ]}
                      /             {[bsol  ]}
                     /               {[bsol  ]}
                [Child GK]          [EP3]
                ID=ProxyGK          E164=18888200
                Prefix=188886
                /       {[bsol  ]}
               /         {[bsol  ]}
              /           {[bsol  ]}
           [EP1]         [EP2]
           E164=601      E164=602

With this rule:

188886=6

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

The section does not relate to the section RasSrv::RewriteE164, though the later will take effect first.

Section Gatekeeper::Auth

The section defines the authentication mechanism for the gatekeeper.

Syntax:

authrule=actions

 <authrule> := SimplePasswordAuth | AliasAuth | PrefixAuth | RadAuth | RadAliasAuth | ...
 <actions>  := <control>[;<ras>|<q931>,<ras>|<q931>,...]
 <control>  := optional | required | sufficient
 <ras>      := GRQ | RRQ | URQ | ARQ | BRQ | DRQ | LRQ | IRQ
 <q931>     := Setup
 
A rule may results in one of the three codes: ok, fail, pass. There are also three ways to control a rule:

Currently supported modules:

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

Example 1:

SimplePasswordAuth=optional;RRQ,ARQ
AliasAuth=sufficient;RRQ
default=allow

Example 2:

RadAliasAuth=required;Setup
default=allow

Section Password

The section defines the userid and password pairs used by SimplePasswordAuth module. Use `make addpasswd' to generate the utility addpasswd.

Usage:

addpasswd config userid password

Options:

Section MySQLAuth

Define the MySQL database, table and fileds to retrieve the userid and password.

The SQL command will be issused:

SELECT $PasswordField FROM $Table WHERE $IDField = %id [AND $ExtraCriterion]

Section ExternalPasswordAuth

Specify an external program to retrieve the password. The program should accept ID from stdin and print the password to stdout. You can use this mechanism to integrate almost any external system for authentication. But beware, this is not the fastest way to authenticate.

Section RasSrv::RRQAuth

Specify the action on RRQ reception (confirm or deny) for 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.

Syntax:

authrules :=  empty  |  authrule "&" authrules

  authrule  := authtype ":" authparams
  authtype  := "sigaddr" | "sigip"
  autparams := [!&]*

The notation and meaning of authparams depends on authtype:

Section MySQLAliasAuth

Define the MySQL database, table and fileds to retrieve a pattern for an alias.

The SQL command will be issused:

SELECT $IPField FROM $Table WHERE $IDField = %alias [AND $ExtraCriterion]

Section PrefixAuth

The section defines the authentication rule for PrefixAuth module. Currently, only ARQs and LRQs can be authorized by this module.

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

Format:

prefix=authrule[|authrule|...]

Syntax:

authrule :=  result authrule

  result    := deny | allow
  authrule  := [!]ipv4:iprule | [!]alias:aliasrule
Next Previous Contents