Reference-Manual for OpenH323 Gatekeeper v2.0 ============================================= A. Command line options ----------------------- -h help -b 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 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 write trace to this file, default is to write on the console -l limit TTL (time to live) for client registration to n overrides the TimeToLive= setting in the config file -c 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
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: : allow registering if the signal address is . sigaddr: : allow registering only if the PString (see pwlib class) representation of the signal address of the registering endpoint matches . 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 := SimplePasswordAuth | LDAPPasswordAuth | AliasAuth | LDAPAliasAuth | ... := [;,,...] := optional | required | sufficient := 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