Reference-Manual for OpenH323 Gatekeeper v2.0
=============================================


A. Command line options
-----------------------

-h		help

-b <n>		limit the sum of bandwidth to be given to clients

-r		use gatekeeper routed signaling

-rr		use routed signaling and H.245

-d		use direct signaling

		the above options override the RoutedMode
		setting in the config file

-i <ip>		gatekeeper will only listen on this IP number (eg. useful,
		when running client and gatekeeper on the same machine)
		overrides the Home= setting in the config file

-t		set trace verbosity: -t = a little , -tt = more, -ttt a lot, ...

-o <file>	write trace to this file, default is to write on the console

-l <n>		limit TTL (time to live) for client registration to n
		overrides the TimeToLive= setting in the config file

-c <file>	specify which config file to use, default is to look for
		gatekeeper.ini in the current directory or
		~/.pwlib_config/Gatekeeper.ini (on Unix)

-s <section>	specify which [Main] section to use in the config file,
		default is [Gatekeeper::Main]


B. Configuration file reference
-------------------------------

Comments are marked with a hash (#) at the beginning of a line.

B.1 Section [Gatekeeper::Main]

Fourtytwo=42		Default: n/a
This setting is used to test the presence of the config file. If none
is found, a warning is issued.

Name=OpenH323GK		Default: OpenH323GK
Gatekeeper ID of this gatekeeper. The GK will only respond to GRQs
for this ID and will use it in a number of messages to its endpoints.

Home=195.71.129.69	Default: 0.0.0.0 (= all interfaces)
The GK will listen form requests on this IP number.
This setting is most useful on multi-homed machines with more
than one IP number.

AlternateGKs=1.2.3.4:1719:false:120:OpenH323GK
We allow for existence of another gatekeeper to allow for redundancy.
This is implemented in a active-active manner. Actually, you might get
into a (valid !) situation where some endpoints are registered with the
first and some are registered with the second GK.
You should even be able use the 2 GKs in a round_robin fashion for load-sharing
(that's untested, though :-)).
If you read on, "primary GK" refers to the GK you're currently configuring
and "alternate GK" means the other one. Only ONE alternate GK may be specified.
The primary GK includes a field in the RCF to tell endpoints which alternate IP and
GK alias to use. But the alternate GK needs to know about every registration with
the primary GK or else it would reject calls. Therefore our GK can forward every RRQ
to an alternate IP address. The AlternateGKs config option specifies the fields
contained in the primary GK's RCF. The first and second fields of this string define where (IP, port) to forward to.
The third tells endpoints whether they need to register with the alternate GK
before placing calls. They usually don't because we forward their RRQs, so they
get registered with the alternate GK, too.
The fourth field specified the priority for this GK. Lower is better, usually the
primary GK is considered to have priority 1.
The last field specifies the alternate's gatekeeperId .

SendTo=1.2.3.4:1719
Although this information is contained in AlternateGKs, you must still
specify which address to forward RRQs to. This might differ from AlternateGK's
address, so it's a separate config option (think of multihomed machines).

SkipForwards=1.2.3.4:5.6.7.8
To avoid circular forwarding, you shouldn't forward RRQs you get from the
other GK (this statement is true for both, primary and alternate GK).
Two mechanisms are used to identify whether a request should be forwarded.
The first one looks for a flag in RRQ. Since few endpoints implement this,
we need a second, more reliable way. Specify the other GK's IP in this list

EndpointIDSuffix=_gk1
We need to identify which gatekeeper an endpoint currently thinks is his
primary one.

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

UnicastRasPort=1719		Default: 1719

MulticastPort=1718		Default: 1718

MulticastGroup=224.0.1.41	Default: 224.0.1.41

EndpointSignalPort=1720		Default: 1720

StatusPort=7000			Default: 7000

ListenQueueLength=1024		Default: 1024

SignalReadTimeout=1000		Default: 1000
Time in ms for read timeout on status channel.

StatusReadTimeout=3000		Default: 3000
Time in ms when for read timeout on signaling channels (Q931).

TimeToLive=300			Default: -1
Time to live for client registration in seconds.
Use -1 to disable this feature.

TotalBandwidth=100000		Default: -1
Total available bandwidth to be given to clients.


B.2 Section [RoutedMode]

This section defines the gatekeeper routed mode options.
The section is affected by reloading.

GKRouted=1		Default: 0

Whether to enable gatekeeper routed mode.

H245Routed=1		Default: 0

Whether to enable H.245 routed. Only take effect if GKRouted=1.

CallSignalPort=1721	Default: 1721

The call signaling port. You can set it to 0 to let the GK choose
an arbitrary port (replace the old option RouteSignalPort).

CallSignalHandlerNumber=1	Default: 1

The number of call signaling handler. You may increase this number
in a heavy loaded gatekeeper. The number can only be increased
at runtime.

RemoveH245AddressOnTunneling=1	Default: 0

Some endpoints send h245Address in the UUIE of Q.931 even when h245Tunneling
is set to TRUE. This may cause interoperability problems. If the option
is TRUE, the gatekeeper will remove h245Address when h245Tunneling flag
is TRUE. This enforces the remote party to stay in tunneling mode.

AcceptNeighborsCalls=1		Default: 1

With this feature enabled, the call signaling thread will accept calls
without a pre-existing CallRec found in CallTable, provided an endpoint
corresponding to the destinationAddress in Setup can be found in the
RegistrationTable, and the calling party is its neighbors or parent GK.
The GK will also use it's own call signaling address in LCF replied to
an LRQ.  That means, the call signaling will be routed to GK2 in GK-GK
calls. As a result, the CDRs in GK2 can correctly show the connected
time, instead of 'unconnected'.

AcceptUnregisteredCalls=1	Default: 0

With this feature enabled, the call signaling thread will accept calls
from any calling party. So the GK works exactly like a gateway.

SupportNATedEndpoints=1		Default: 0

Whether to allow an endpoint behind an NAT box register to the GK.
If yes, the GK will translate the IP address in Q.931 and H.245
into the IP of NAT box.

DropCallsByReleaseComplete=1	Default: 0

According to H.323 spec, the GK could tear down a call by sending RAS
DisengageRequest to endpoints. However, some bad endpoints just ignore
this command. With this option turning on, the GK will send Q.931
Release Complete instead of RAS DRQ to both endpoints to force them
drop the call.

SendReleaseCompleteOnDRQ=1	Default: 0

On hangup, the endpoint sends both, RELEASE COMPLETE within H.225/Q.931 and
DRQ within RAS. It may happen that DRQ is processed first, causing the gk to
close the call signalling channel, thus preventnig the RELEASE COMPLETE from
being forwarding to the other endpoint.
Though the gk closes the TCP channel to the destination, some endpoints (e.g.
 Cisco CallManager) don't drop the call even if the call signalling channel
is closed. This results in phones that keep ringing if the caller hangs up
before the callee pickups.
Setting this parameter to "1" makes the gk always send RELEASE COMPLETE
to both endpoints before closing the call when it receives DRQ from one of
the parties.


B.3 Section [GkStatus::Auth]

rule=allow		Default: forbid
Define a number of rules who is allowed to connect to the status port.
Possible values are...


B.4 Section [RasSvr::GWPrefixes]

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

test-gw=02,03
All numbers starting with 02 or 03 go to the gateway with the alias name
"test-gw". The gateway must be currently registered with the gatekeeper to be serviced.


B.7 Section [RasSvr::ARQFeatures]
ArjReasonRouteCallToSCN=FALSE		Default: FALSE
If TRUE, when an ARQ arrives from the very same gateway that this call
would be routed back to, gatekeeper sends ARJ with reason RouteCallToSCN.

ArjReasonRouteCallToGatekeeper=TRUE	Default: TRUE
If TRUE, when an answered ARQ arrives without a pre-existing CallRec
found in CallTable, gatekeeper sends ARJ with reason RouteCallToGatekeeper.

B.8 Section [RasSrv::RRQAuth]

default=deny				Default: confirm

Specify the default action on RRQ reception (confirm or deny).
First, the first alias (this will mostly be a h323id) of the endpoint to register is looked
up in this section.  If a parameter is found the value will apply as a rule. If no parameter
is found, the value of the parameter "default" will apply. If no "default" is found all
registrations are accepted. A rule consists of conditions separated by "&". A registration
is accepted when all conditions apply. 

A condition has the notation authtype:param1[:param2[...]]. The number of params depends on
the authtype. Currently the following authtypes are implemented: 

  confirm (or allow)        : allow this endpoint to register. 
  reject (or deny, forbid)  : may not register. 
  sigip:<a.b.c.d:p>         : allow registering if the signal address is <a.b.c.d:p>. 
  sigaddr:<regex>           : allow registering only if the PString (see pwlib class)
                              representation of the signal address of the registering endpoint
			      matches <regex>. This is a more general form then "sigip" and
			      will allow future extension (ie by IPv6). 

  Example:
  rossi-gt2=sigaddr:.*ipAddress .* ip = .* c3 47 e2 a2 .*port = 1720.*
  rossi-gt3=sigip:195.71.226.165:1720
  gkt1=confirm
  gkt2=confirm
  default=reject

  Note that the "alias" is the PString representation of the RRQ.m_aliasAddress[0]. This
  should be a h323id but it is thinkable to have any option of H225_AliasAddress
  (e164, h323_ID, url_ID, transportID, email_ID, partyNumber).


B.9 Section [RasSvr::RewriteE164]

Fastmatch=0190		Default: (empty)
Number rewriting rules only apply if the to-be-rewritten-number's matches one of
the prefixes contained (string-wise) in Fastmatch

B.10 Section [SignalConnection::StatusEnquiry]

UsePing=TRUE		Default: FALSE
Turn usage of Q.931 StatusEnquiry on or off. If the endpoint doesn't
answer, the call will be terminated.
Note that Netmeeting will not respond to StatusEnquiry, even though
it is a mandatory feature! So if you want to use Netmeeting, turn
this feature off.

AllowedPendings=3	Default: 3
Maximum allowed number of outstanding responses

Timeout=5			Default: 1
Time between 'pings'


B.11 Section [RasSvr::Neighbors]

The GK would send LRQ to its neighbors if the destination of ARQ is unknown.
A neighbor is selected if its prefix match the destination or it has
prefix '*'. If prefix is empty, no LRQs will be sent to that neighbor.
This is useful if you want to only receive LRQs from that neighbor.

Currently only one prefix is supported.

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

  Example:
    GK1=203.60.151.5:1719;*;gk1
    GK2=203.60.151.9:1719;02
    GK3=203.60.152.6:1719;;

B.12 Section [RasSvr::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 are always
in GK's registration table.
However, You can still unregister it via status thread.

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

  Example:
    10.0.1.5=Citron;009,008  (For gateway)
    10.0.1.10=798            (For terminal)

B.13 Section [Gatekeeper::Auth]

default=reject				Default: allow

Syntax:
   authrule=actions

   <authrule> := SimplePasswordAuth | LDAPPasswordAuth
                 | AliasAuth | LDAPAliasAuth | ...
   <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.

  ok         The request is authenticated by this module
  fail       The authentication fails and should be rejected
  next       The rule cannot determine the request

There are also three ways to control a rule:

  optional      If the rule cannot determine the request, it is passed
                to next rule.
  required      The requests should be authenticated by this module,
                or it would be rejected. The authenticated request would
                then be passwd to next rule.
  sufficient    If the request is authenticated, it is accepted,
                or it would be rejected. That is, the rule determines
                the fate of the request. No rule should be put after
                a sufficient rule, since it won't take effect.

Currently supported modules:

  SimplePasswordAuth/
  LDAPPasswordAuth    The module checks the tokens or cryptoTokens
                      fields of RAS message. The tokens should contain
                      at least generalID and password. For cryptoTokens,
                      cryptoEPPwdHash tokens hashed by simple MD5 and 
                      nestedcryptoToken tokens hashed by HMAC-SHA1-96
                      (libssl must be installed!) are supported now.
                      The ID and password are read from [Password] section 
                      / LDAP (default: plaintextpassword attribute).
		      Support for other backend databases is easily to add.

  AliasAuth/
  MySQLAliasAuth/
  LDAPAliasAuth       The IP of an endpoint with given alias should
                      match a specified pattern. For AliasAuth the pattern 
                      is defined in [RasSrv::RRQAuth] section.
                      For MySQLAliasAuth, the pattern is retrieved from
                      MySQL database, defined in [MySQLAliasAuth] section.
                      For LDAPAliasAuth the alias (default: mail attribute)
                      and IP (default: voIPIpAddress attribute) must be 
                      found in one LDAP entry.

You can also configure a rule to check only for some particular RAS
messages. For example, to configure SimplePasswordAuth as a required
rule to check RRQ, ARQ and LRQ:
SimplePasswordAuth=required;RRQ,ARQ,LRQ

  Example:
    SimplePasswordAuth=optional
    AliasAuth=sufficient;RRQ
    default=reject

B.14 Section [Password]

The section defines the userid and password pairs used by SimplePasswordAuth.
Use 'make addpasswd' to generate the utility addpasswd.
Usage:
   addpasswd config userid password

KeyFilled=123           Default: 0

Default value to initialize the encryption key.

CkeckID=TRUE            Default: FALSE

Check if the aliases match the ID in the tokens.

PasswordTimeout=120	Default: -1

SimplePasswordAuth will cache an authenticated password.
This field define the cache timeout value in second.
0 means never cache the password, while a negative value
means the cache never expires.

B.15 Section [CallTable]

GenerateNBCDR=FALSE	Default: TRUE

Allow generate CDR for call that calling from neighbor zones.
The IP and endpoint ID of the calling party is printed
as empty. This is usually used for debug purpose.

GenerateUCCDR=FALSE	Default: FALSE

Allow generate CDR for call that is unconnected. This is usually
used for debug purpose. Note a call is considered unconnected
only if the GK is in routed mode and Q.931 connect message is not
received by the GK. In direct mode, a call is always considered
connected.

DefaultCallTimeout	Default: 0

Default timeout value in seconds to tear down a call.
Set it to 0 to disable this feature.

B.16 Section [MySQLAuth]

Host=localhost          Default: localhost

Host name or IP of the MySQL server.

Database=billing        Default: billing

The database to connect.

User=cwhuang
Password=123456

Isn't it clear?

Table=customer

The table in the database to query.

IDField=IPN

The field name of user id.

PasswordField=Password

The password field name.

ExtraCriterion=Kind>0	Default: n/a

Specify extra criterion.

The GK will issue the SQL command:
SELECT $PasswordField FROM $Table WHERE $IDField = %alias [AND $ExtraCriterion]


B.17 Section [MySQLAliasAuth]

Host=localhost          Default: localhost
Database=billing        Default: billing
User=cwhuang
Password=123456
Table=customer
IDField=IPN
IPField=Address
ExtraCriterion=Kind>0	Default: n/a

The SQL command is
SELECT $IPField FROM $Table WHERE $IDField = %alias [AND $ExtraCriterion]

The format is exactly as MySQLAuth, except the selected result
is used as a specified pattern to match the IP of endpoint,
as described in section [RasSrv::RRQAuth].

CacheTimeout=100	Default: -1

Timeout value in second to cache the result. See option
PasswordTimeout in section [SimplePasswordAuth] for details.


B.18 Section [GkAuthorize]

This section authorizes arq by source call signal address.

default=deny  #Defaul: allow
#default policy for unclassified arq

prf: 555
#phone prefix
deny ipv4:10.0.0.0/27
#deny access for network to the perfix
allow ipv4:ALL
#allow access for all to the prefix

prf: 5555
deny ipv4:192.168.1.0/255.255.255.0
#deny access for network to the perfix
allow ipv4:192.168.1.1
#allow access for a host to the prefix

prf: ALL
allow ipv4:0/0
#allow access for all networks to all prefixes


#We choose the most specific prefix and then
#we choose the most specific network from list

B.19 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 real IP outside the box.

Enable=1		Default: 0

Whether to enable the proxy function. You have to enable gatekeeper
routed mode first (see Section B.2). You don't have to specify
H.245 routed. It will automatically be used if required.

InternalNetwork=10.0.1.0/24	Default: n/a

Define the networks behind the proxy. Multiple internal networks are allow.
The proxy route channels only of the communications between one endpoint
in the internal network and one external. If you don't specify it, all calls
will be proxied.

  Format:
    InternalNetwork=network address/netmask[,network address/netmask,...]

    The netmask can be expressed in decimal dot notation or
    CIDR notation (prefix length), as shown in the example.

  Example:
    InternalNetwork=10.0.0.0/255.0.0.0,192.168.0.0/24

B.20 Section [Endpoint]

The gatekeeper can work as an endpoint by registering to another gatekeeper.
With this feature, you can easily build gatekeeper hierarchies.
The section defines the endpoint features for the gatekeeper.

Gatekeeper=10.0.1.1		Default: no

Define a parent gatekeeper for the endpoint(gatekeeper) to register to.
Don't try to register to yourself, unless you want to be confusing.
To disable this feature, set the field to be no.

Type=Gateway			Default: Gateway

Define the terminal type for the endpoint.
The valid values are Gateway or Terminal.

H323ID=CitronProxy
E164=18888600000,18888700000

Define the H.323 ID and E.164 (dialedDigits) aliases for the endpoint.
Multiple aliases can be specified.

Password=123456

Specify a password to be sent to the parent gatekeeper.
All RAS requests will contain the password in the cryptoTokens field.

Besides, the password is also used in LRQs sent to neighbor gatekeepers.

Prefix=188886,188887

Register the specified prefixes to the parent gatekeeper.
Only take effect when the Type is Gateway.

TimeToLive=900

Suggest a time-to-live value in second for the registration.
Note that the real time-to-live value is assigned by the parent
gatekeeper in the RCF replied to the RRQ.

RRQRetryInterval=10		Default: 10

Define a retry interval in second for RRQs if no response
received from the parent gatekeeper.

ARQTimeout=2			Default: 2

Define the timeout value for ARQs in second.


B.21 Section [Endpoint::RewriteE164]

Once you specify prefix(es) for your gatekeeper endpoint, the parent
gatekeeper will route calls with dialed digits 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 RasSvr::RewriteE164,
though the later will take effect first.


B.22 Section [GkLDAP::LDAPAttributeNames]

This section defines which LDAP attribute names to use.

H323ID:		the endpoint's H.323 alias. Needs to be unique within
		the used LDAP tree (this i why we use the mail address by default).
TelephonNo:	the endpoint's E.164 alias
voIPIpAddress:	the IP address to be compared against when using LDAPAliasAuth
		Format: 1.2.3.4.
		For now, only a single value is allowed here.
H235PassWord:	the plaintext password to be compared against when using H.235 
		(LDAPPasswordAuth in Gatekeeper::Auth).
		For now, only a single value is allowed here.

Defaults:
H323ID=mail
TelephonNo=telephoneNumber
IPAddress=voIPIpAddress
H235PassWord=plaintextPassword


B.23 Section [GkLDAP::Settings]

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

ServerName:	The LDAP server's DNS name.
ServerPort:	The LDAP server's TCP port (usually 389).
SearchBaseDN:	entry point into the server's LDAP tree structure.
             	Searches are only made below this root node.
BindUserDN:	The distinguished name the gatekeeper uses to bind
           	to the LDAP server. Leave empty if you want to access
           	the LDAP server anonymously.
BindUserPW:	If you specified BindUserDN, then specify the corresponding
           	password to be used for binding here.
sizelimit:	Maximum number of results the server may return in response
          	to a single search query. The gatekeeper expects each LDAP
          	to only yields one or zero results anyway, so this parameter
          	is rather useless.
          	Usually that's restricted on the server side, anyway.
timelimit:	maximum number of seconds a query may take until it's
          	considered as "failed".

Defaults:
#ServerName=ldap
#ServerPort=389
#SearchBaseDN=o=University of Michigan, c=US
#BindUserDN=cn=Babs Jensen,o=University of Michigan, c=US
#BindUserPW=ReallySecretPassword
#sizelimit=0
#timelimit=0


