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) 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.

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 It is said that some section names in GnuGK 2.0 are [RasSrv::*], while others are [RasSvr::*]. This inconsistency confuses users. In 2.0.1 all sections are corrected to [RasSrv::*]. If you upgrade from 2.0 or eariler version, remember to change the section names, or the 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.

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 its prefix match the destination or it has prefix ``*''. Currently only one prefix is supported.

Conversely, the gatekeeper only reply 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.

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

Format:

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

Example:

GK1=192.168.0.5;*
GK2=10.0.1.1:1719;035;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
                        /         \
                       /           \
                      /             \
                     /               \
                [Child GK]          [EP3]
                ID=ProxyGK          E164=18888200
                Prefix=188886
                /       \
               /         \
              /           \
           [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>,<ras>,...]
 <control>  := optional | required | sufficient
 <ras>      := GRQ | RRQ | URQ | ARQ | BRQ | DRQ | LRQ | IRQ
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:

SimplePasswordAuth=optional;RRQ,ARQ
AliasAuth=sufficient;RRQ
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.

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>
Where <iprule> can be specified in decimal dot notation or CIDR notation, <aliasrule> is expressed in regular expression. If the `!' flag precedes the rule, the sense is inverted.

Example:

555=deny ipv4:10.0.0.0/27|allow ipv4:0/0
5555=allow ipv4:192.168.1.1|deny ipv4:192.168.1.0/255.255.255.0
86=deny !ipv4:172.16.0.0/24
09=deny alias:^188884.*
ALL=allow ipv4:ALL

In this configuration, all endpoints except from network 10.0.0.0/27 are allow to call prefix 555 (except 5555). Endpoints from 192.168.1.0/24 are not allowed to call prefix 5555, except 192.168.1.1. Endpoints not from 172.16.0.0/24 are denied to call prefix 86. Endpoints having an alias beginning with 188884 are not allowed to call prefix 09. All other situations are allowed.

Section [RadAuth]

This section defines configuration settings that enable RADIUS authentication based on H.235 CATs (Cisco Access Tokens) present in RRQ and ARQ RAS requests. This authentication scheme is useful only for endpoints registered at the gatekeeper.

Section [RadAliasAuth]

This section defines configuration settings that enable RADIUS authentication based on endpoint aliases and/or IP adresses present in RRQ and ARQ RAS requests. This authentication scheme is useful only for endpoints registered at the gatekeeper.

Section [GkLDAP::LDAPAttributeNames]

This section defines which LDAP attribute names to use.

Section [GkLDAP::Settings]

This section defines the LDAP server and standard LDAP client operating parameters to be used.

Section [NATedEndpoints]

The gatekeeper can automatically detect whether an endpoint is behind NAT. However, if the detection fails, you can specify it manually in this section.

Format:

alias=true,yes,1,...

Example:

Specify an endpoint with alias 601 is behind NAT.

601=true

Section [CTI::Agents]

This section allows the configuration of a so called virtual queue to allow inbound call distribution by an external application. A virtual queue has an H.323 alias that can be called like an endpoint.

Upon arrival of an ARQ on a virtual queue, the gatekeeper signals a RouteRequest on the status port and waits for an external application to resond with either a RouteReject (then the ARQ will be rejected) or with RouteToAlias which leads to the ARQ being rewritten so the call will be routed to the alias (eg. acll center agent) specified by the external application.

If no answer is received after a timeout period, the call is terminated.

Right now you can have only one virtual queue per gatekeeper.

See the monitoring section for details on the messages and responses.


Next Previous Contents