reference.txt

开发h323ip电话的朋友

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.