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.
Almost every option has a short and a long format, e.g.,
-c
is the same as --config
.
-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.
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.
-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.
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.
Fourtytwo=42
N/A
This setting is used to test the presence of the config file. If it is not found, a warning is issued. Make sure it's in all your config files.
Name=OpenH323GK
OpenH323GK
Gatekeeper identifier of this gatekeeper. The gatekeeper will only respond to GRQs for this ID and will use it in a number of messages to its endpoints.
Home=192.168.1.1
0.0.0.0
The gatekeeper will listen for requests on this IP number. By default, the gatekeeper listens on all interfaces of your host. You should leave out this option, unless you want the gatekeeper only to bind to a specified IP.
NetworkInterfaces=192.168.1.1/24,10.0.0.1/0
N/A
Specify the network interfaces of the gatekeeper. By default the gatekeeper will detect the interfaces of your host automatically. There are two situations that you may want to use this option. One is automatical detection failed, another is the gatekeeper is behind an NAT box and allow endpoints with public IPs to register with. In this case you should set the option just as the gatekeeper is running on the NAT box.
EndpointIDSuffix=_gk1
_endp
The gatekeeper will assign a unique identifier to each registered endpoint. This option can be used to specify a suffix to append to the endpoint identifier. This is only usefull when using more than one gatekeeper.
TimeToLive=300
-1
An endpoint's registration with a gatekeeper may have a limited life span. The gatekeeper specifies the registration duration of an endpoint by including a timeToLive field in the RCF message. After the specified time, the registration has expired. The endpoint shall periodically send an RRQ having the keepAlive bit set prior to the expiration time. Such a message may include a minimum amount of information as described in H.225.0. This is called a lightweight RRQ.
This configuration setting specifies the time-to-live timer in seconds until the registration expires. Note the endpoint may request a shorter timeToLive in the RRQ message to the gatekeeper. To avoid an overload of RRQ messages, the gatekeeper automatically adjusts this timer to 60 seconds if you give a lesser value!
After the expiration time, the gatekeeper will subsequently send two IRQ messages to query if the endpoint is still alive. If the endpoint responds with an IRR, the registration will be extended. Otherwise the gatekeeper will send a URQ with reason ttlExpired to the endpoint. The endpoint must then re-register with the gatekeeper using a full RRQ message.
To disable this feature, set it to -1
.
TotalBandwidth=100000
-1
Total bandwidth available to be given to endpoints.
RedirectGK=Endpoints > 100 || Calls > 50
N/A
This option allow you to redirect endpoints to alternate gatekeepers when the gatekeeper overloaded. For example, with the above setting the gatekeeper will reject an RRQ if registered endpoints exceed 100, or reject an ARQ if concurrent calls exceed 50.
Furthermore, you may explicitly redirects all endpoints by
setting this option to temporary
or permanent
.
The gatekeeper will return an RAS rejection message with a list of
alternate gatekeepers defined in AlternateGKs
.
Note that a permanent
redirection means that the redirected endpoints
will not register with this gatekeeper again.
Please also note the function only takes effect to H.323 version 4
compliant endpoints.
AlternateGKs=1.2.3.4:1719:false:120:OpenH323GK
N/A
We allow for existence of another gatekeeper to provide 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 gatekeeper. You should even be able use the two gatekeepers in a round_robin fashion for load-sharing (that's untested, though :-)). If you read on, "primary GK" refers to the gatekeeper you're currently configuring and "alternate GK" means the other one. The primary GK includes a field in the RCF to tell endpoints which alternate IP and gatekeeper identifier to use. But the alternate GK needs to know about every registration with the primary GK or else it would reject calls. Therefore our gatekeeper 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 gatekeeper's identifier.
SendTo=1.2.3.4:1719
N/A
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
N/A
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 gatekeeper's IP in this list.
StatusPort=7000
7000
Status port to monitor the gatekeeper. See this section for details.
Most users will never need to change any of the following values. They are mainly used for testing or very sophisticated applications.
UseBroadcastListener=0
1
Defines whether to listen to broadcast RAS requests. This requires binding to all interfaces on a machine so if you want to run multiple instances of gatekeepers on the same machine you should turn this off.
UnicastRasPort=1719
1719
The RAS channel TSAP identifier for unicast.
MulticastPort=1718
1718
The RAS channel TSAP identifier for multicast.
MulticastGroup=224.0.1.41
224.0.1.41
The multicast group for the RAS channel.
EndpointSignalPort=1720
1720
Default port for call signalling channel of endpoints.
ListenQueueLength=1024
1024
Queue length for incoming TCP connection.
SignalReadTimeout=1000
1000
Time in miliseconds for read timeout on call signalling channels (Q931).
StatusReadTimeout=3000
3000
Time in miliseconds for read timeout on status channel.
StatusWriteTimeout=5000
5000
Time in miliseconds for write timeout on status channel.
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.
The gatekeeper doesn't route them. The H.245 control channel and logical channels are established directly between the endpoints.
The H.245 control channel is routed between the endpoints through the gatekeeper, while the logical channels are established directly between the endpoints.
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.
GKRouted=1
0
Whether to enable the gatekeeper routed mode.
H245Routed=1
0
Whether to route the H.245 control channel. Only takes effect if GKRouted=1
.
CallSignalPort=0
1721
The port of call signalling for the gatekeeper.
The default port is 1721
. We don't use the well-known port 1720
so you can run an H.323 endpoint in the same machine of the gatekeeper.
You may set it to 0
to let the gatekeeper choose an arbitrary port.
CallSignalHandlerNumber=2
1
The number of call signalling handler. You may increase this number in a heavy loaded gatekeeper. The number can only be increased at runtime. If you have a SMP machine, you can set this number to your number of CPUs.
AcceptNeighborsCalls=1
1
With this feature enabled, the call signalling thread will accept calls without a pre-existing CallRec found in the 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 gatekeeper will also use it's own call signalling address in LCF in responding to an LRQ. That means, the call signalling 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
0
With this feature enabled, the gatekeeper will accept calls from any unregistered endpoint. However, it raises security risks. Be careful to use it.
RemoveH245AddressOnTunneling=1
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 tunnelling mode.
RemoveCallOnDRQ=0
1
With this option turning off, the gatekeeper will not disconnect a call if it receives a DRQ for it. This avoids potential race conditions when a DRQ overtakes a Release Complete. This is only meaningful in routed mode because in direct mode, the only mechanism to signal end-of-call is a DRQ.
DropCallsByReleaseComplete=1
0
According to Recommendation H.323, the gatekeeper 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 gatekeeper will send Q.931 Release Complete instead of RAS DRQ to both endpoints to force them drop the call.
SendReleaseCompleteOnDRQ=1
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
gatekeeper to close the call signalling channel, thus preventing the
Release Complete from being forwarding to the other endpoint.
Though the gatekeeper 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 gatekeeper always send
Release Complete to both endpoints before closing the call when
it receives DRQ from one of the parties.
SupportNATedEndpoints=1
0
Whether to allow an endpoint behind an NAT box register to the gatekeeper. If yes, the gatekeeper will translate the IP address in Q.931 and H.245 channel into the IP of NAT box.
Since 2.0.2, the GnuGK supports NAT outbound calls (from an endpoint behind NAT to public networks) directly without any necessary modification of endpoints or NAT box. Just register the endpoint with the GnuGK and you can make call now.
ScreenDisplayIE=MyID
N/A
Modify the DisplayIE of Q.931 to the specified value.
ScreenCallingPartyNumberIE=0965123456
N/A
Modify the CallingPartyNumberIE of Q.931 to the specified value.
ForwardOnFacility=1
1
If yes, on receiving Q.931 Facility with reason callForwarded, the gatekeeper will forwards call Setup directly to the forwarded endpoint, instead of passing the message back to the caller. If you have broken endpoints that can't handle Q.931 Facility with reason callForwarded, turn on this option.
ShowForwarderNumber=0
0
Whether to rewrite the calling party number to the number of forwarder.
It's usually used for billing purpose.
Only valid if ForwardOnFacility=1
.
Q931PortRange=20000-20999
0
(random)
Specify the range of TCP port number for Q.931 signalling channels. Note the range size may limit the number of concurrent calls.
H245PortRange=30000-30999
0
(random)
Specify the range of TCP port number for H.245 control channels. Note the range size may limit the number of concurrent calls.
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.
Enable=1
0
Whether to enable the proxy function. You have to enable gatekeeper routed mode first (see the previous section). You don't have to specify H.245 routed. It will automatically be used if required.
InternalNetwork=10.0.1.0/24
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.
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.
InternalNetwork=10.0.0.0/255.0.0.0,192.168.0.0/24
T120PortRange=40000-40999
0
(random)
Specify the range of TCP port number for T.120 data channels. Note the range size may limit the number of concurrent calls.
RTPPortRange=50000-59999
10000-59999
Specify the range of UDP port number for RTP/RTCP channels. Note the range size may limit the number of concurrent calls.
ProxyForNAT=1
1
If yes, the gatekeeper will proxy for calls to which one of the endpoints participated is behind an NAT box. This ensure the RTP/RTCP stream can penetrate into the NAT box without modifying it. However, the endpoint behind the NAT box must use the same port to send and receive RTP/RTCP stream. If you have bad or broken endpoints that don't satisfy the precondition, you have better to disable this feature and let the NAT box forward RTP/RTCP stream for you.
ProxyForSameNAT=0
0
Whether to proxy for calls between endpoints from the same NAT box. You do not need to enable this feature in general, since usually endpoints from the same NAT box can communicate with each other.
Define a number of rules who is allowed to connect to the status port.
rule=allow
forbid
Possible values are
forbid
- disallow any connection.allow
- allow any connectionexplicit
- reads the parameter ip=value
where ip
is the IP address of the peering client,
value
is 1,0
or allow,forbid
or yes,no
.
If ip
is not listed the parameter default
is used.regex
- the IP of the client is matched against the given regular expression.
To allow client from 195.71.129.0/24 and 195.71.131.0/24:
regex=^195\.71\.(129|131)\.[0-9]+$
password
- the user has to input appropriate username and password to login. The format of username/password is the same as
[Password] section.
Moreover, these rules can be combined by "|" or "&". For example,
rule=explicit | regex
explicit
or regex
rule.
rule=regex & password
regex
rule, and the user has to login by username and password.
default=allow
forbid
Only used when rule=explicit
.
Shutdown=forbid
allow
Whether to allow shutdown the gatekeeper via status port.
This section lists what E.164 numbers are routed to a specific gateway.
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.
test-gw=02,03
This section defines the rewriting rules for dialedDigits (E.164 number).
[!]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.
08=18888
If you dial 08345718
, it is rewritten to 18888345718
.
Option:
Fastmatch=08
N/A
Only rewrite dialDigits beginning with the specified prefix.
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.
IP[:port]=alias[,alias,...;prefix,prefix,...]
For gateway,
10.0.1.5=Citron;009,008
For terminal,
10.0.1.10:1720=700
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.
GKID=ip[:port;prefix;password;dynamic]
GK1=192.168.0.5;*
GK2=10.0.1.1:1719;035;gk2
GK3=gk.citron.com.tw;;gk3;1
Defines some features of LRQ and LCF.
NeighborTimeout=1
2
Timeout value in seconds to wait responses from neighbors. If no response from all neighbors after timeout, the gatekeeper will reply an ARJ to the endpoint sending the ARQ.
ForwardHopCount=2
N/A
If the gatekeeper receives an LRQ that the destination is either unknown, it may forward this message to its neighbors. When the gatekeeper receives an LRQ and decides that the message should be forwarded on to another gatekeeeper, it first decrements hopCount field of the LRQ. If hopCount has reached 0, the gatekeeper shall not forward the message. This options defines the number of gatekeepers through which an LRQ may propagate. Note it only affects the sender of LRQ, not the forwarder.
AlwaysForwardLRQ=1
0
Force the gatekeeper to forward an LRQ even if there is no hopCount in the LRQ. To avoid LRQ loops, you should use this option very carefully.
AcceptForwardedLRQ=1
1
Whether to accept an LRQ forwarded from neighbors.
IncludeDestinationInfoInLCF=0
1
The gatekeeper replies LCFs containing destinationInfo and destinationType fields, the aliases and terminal type of the destination endpoint. The neighbor gatekeeper can then save the information to suppress later LRQs. However, some vendors' gatekeepers misuse the information, thus result in interoperability problems. Only turn off this option if you encounter problems upon communicating with a third-party gatekeeper.
CiscoGKCompatible=1
0
Include a NonStandardParameter in LRQs to compatible with Cisco gatekeepers.
AcceptEndpointIdentifier=1
1
Whether to accept endpointIdentifier specified in a full RRQ.
AcceptGatewayPrefixes=1
1
A gateway can register its prefixes with the gatekeeper by containing supportedPrefixes in the terminalType field of RRQ. This option defines whether to accept the specified prefixes of a gateway.
OverwriteEPOnSameAddress=1
0
In some networks an endpoint's IP address may change unexpectedly. This may happen when an endpoint is using a PPP connection (e.g. modem or ADSL). This option defines how to handle a registration request (RRQ) from an IP address which does not match what we have stored. The default action is to reject the request. With this option enabled the conflicting request will cause an unregister request (URQ) to be sent for the existing IP address and the entry to be removed allowing the endpoint to register with the new address.
ArjReasonRouteCallToSCN=0
1
If yes, the gatekeeper rejects a call from a gateway to itself by reason routeCallToSCN.
ArjReasonRouteCallToGatekeeper=1
1
If yes, the gatekeeper rejects an answered ARQ without a pre-existing CallRec found in the CallTable by reason routeCallToGatekeeper in routed mode. The endpoint shall release the call immediately and re-send call Setup to the gatekeeper.
CallUnregisteredEndpoints=0
1
With this option set on, the gatekeeper will accept an ARQ from a registered endpoint with destCallSignalAddress, no matter the address is belongs to a registered endpoint or not. That means you can explicitly specify the IP of endpoint (registered or not) you want to call.
RemoveTrailingChar=#
N/A
Specify the trailing character to be removed in destinationInfo. For example, if your endpoint incorrectly contains the termination character like `#' in destinationInfo, you may remove it by this option.
GenerateNBCDR=0
1
Generate CDRs for calls from neighbor zones. The IP and endpoint ID of the calling party is printed as empty. This is usually used for debug purpose.
GenerateUCCDR=0
0
Generate CDRs for calls that are unconnected. This is usually used for debug purpose. Note a call is considered unconnected only if the gatekeeper uses routed mode and a Q.931 Connect message is not received by the gatekeeper. In direct mode, a call is always considered connected.
DefaultCallTimeout=3600
0
Default timeout value in seconds to tear down a call.
Set it to 0
to disable this feature.
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.
Gatekeeper=10.0.1.1
no
Define a parent gatekeeper for the endpoint(gatekeeper) to register with.
Don't try to register with yourself, unless you want to be confusing.
To disable this feature, set the field to be no
.
Type=Gateway
Gateway
Define the terminal type for the endpoint.
The valid values are Gateway
or Terminal
.
H323ID=CitronProxy
<Name>
Specify the H.323 ID aliases for the endpoint. Multiple aliases can be separated by comma.
E164=18888600000,18888700000
N/A
Define the E.164 (dialedDigits) aliases for the endpoint. Multiple aliases can be separated by comma.
Password=123456
N/A
Specify a password to be sent to the parent gatekeeper. All RAS requests will contain the password in the cryptoTokens field. To send RAS requests without the cryptoTokens field, set the field to be empty.
Besides, the password is also used in LRQs sent to neighbor gatekeepers.
Prefix=188886,188887
N/A
Register the specified prefixes with the parent gatekeeper.
Only takes effect when the Type is Gateway
.
TimeToLive=900
N/A
Suggest a time-to-live value in second for the registration. Note that the real time-to-live timer is assigned by the parent gatekeeper in the RCF replied to the RRQ.
RRQRetryInterval=10
10
Define a retry interval in second for RRQs if no response received from the parent gatekeeper.
ARQTimeout=2
2
Define the timeout value in second for ARQs.
UnregisterOnReload=1
0
Defines whether the child gatekeeper unregisters and re-registers with it's parent when receiving a Reload command.
NATRetryInterval=60
60
Retry interval in second for NAT socket. Leave it out if you don't understand it.
NATKeepaliveInterval=86400
86400
Keepalive interval in second for NAT socket. Leave it out if you don't understand it.
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.
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.
The section defines the authentication mechanism for the gatekeeper.
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
ok
- The request is authenticated by this module.fail
- The authentication fails and should be rejected.next
- The rule cannot determine the request.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/MySQLPasswordAuth/LDAPPasswordAuth/ExternalPasswordAuth
These modules check 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,
MySQL database, LDAP or an external program
for SimplePasswordAuth
, MySQLPasswordAuth
, LDAPPasswordAuth
and ExternalPasswordAuth
modules, respectively.
Support for other backend databases is easily to add.
NeighborPasswordAuth
The module is used only to authenticate LRQs from neighbors defined in section [RasSrv::Neighbors].
AliasAuth/MySQLAliasAuth/LDAPAliasAuth
The module can only be used to authenticate RegistrationRequest (RRQ).
The IP of an endpoint with a 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.
PrefixAuth
Originally known as GkAuthorize
.
The IP or aliases of a request with a given prefix must match a specified
pattern. See section
[PrefixAuth] for details.
Currently the module can only authorize
AdmissionRequest (ARQ) and LocationRequest (LRQ).
RadAuth
Provides authentication based on H.235 username/password
security scheme. Authenticates RRQs and/or ARQs through remote
RADIUS servers. It passes to RADIUS servers usernames and passwords
extracted from CAT (Cisco Access Tokens) tokens carried
inside RRQ and ARQ packets. Therefore if your endpoints do not
support CATs or you do not need authentication scheme based on
individually assigned usernames/password - this module will not
work for you (but you may check RadAliasAuth
module).
See section
[RadAuth] for details.
RadAliasAuth
Provides authentication based on endpoint aliases
and/or call signalling IP addresses with remote RADIUS servers.
It does not need any H.235 tokens inside RAS messages,
so it can be used on a wider range of systems as compared to RadAuth
.
RRQ and ARQ messages can be authenticated using this module.
See section
[RadAliasAuth] for details.
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.
SimplePasswordAuth=optional;RRQ,ARQ
AliasAuth=sufficient;RRQ
default=allow
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:
KeyFilled=123
0
Default value to initialize the encryption key.
CheckID=1
0
Check if the aliases match the ID in the tokens.
PasswordTimeout=120
-1
The module SimplePasswordAuth
and all its descendants 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.
Define the MySQL database, table and fileds to retrieve the userid and password.
Host=localhost
localhost
Host name or IP of the MySQL server.
Database=billing
billing
The database to connect.
User=cwhuang
Password=123456
The user name and password used to connect to the database.
Table=customer
The table in the database to query.
IDField=IPN
The field name of user id.
PasswordField=Password
The field name of password.
ExtraCriterion=Kind > 0
N/A
Specify extra criterion.
The SQL command will be issused:
SELECT $PasswordField FROM $Table WHERE $IDField = %id [AND $ExtraCriterion]
Specify an external program to retrieve the password. The program should accept ID from stdin and print the password to stdout.
PasswordProgram=/usr/local/bin/getpasswd
N/A
The executable of the external program.
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.
<authrules> := empty | <authrule> "&" <authrules>
<authrule> := <authtype> ":" <authparams>
<authtype> := "sigaddr" | "sigip"
<autparams> := [!&]*
The notation and meaning of <authparams>
depends on
<authtype>
:
sigaddr
- extended regular expression that has to match agains the
``PrintOn(ostream)'' representation of the signal address of the request.
Example:
sigaddr:.*ipAddress .* ip = .* c0 a8 e2 a5 .*port = 1720.*
sigip
- specialized form of `sigaddr
'.
Write the signalling ip adresse using (commonly used) decimal notation:
``byteA.byteB.byteC.byteD:port
''.
Example:
sigip:192.168.242.165:1720
allow
- always accept the alias.
deny
- always reject the alias.
Define the MySQL database, table and fileds to retrieve a pattern for an alias.
Host=localhost
localhost
Host name or IP of the MySQL server.
Database=billing
billing
The database to connect.
User=cwhuang
Password=123456
The user name and password used to connect to the database.
Table=customer
The table in the database to query.
IDField=IPN
The field name of user id.
IPField=Address
The field name of IP address.
ExtraCriterion=Kind > 0
N/A
Specify extra criterion.
The SQL command will be issused:
SELECT $IPField FROM $Table WHERE $IDField = %alias [AND $ExtraCriterion]
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.
prefix=authrule[|authrule|...]
<authrule> := <result> <authrule>
<result> := deny | allow
<authrule> := [!]ipv4:<iprule> | [!]alias:<aliasrule>
<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.
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.
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.
Servers=SERVER1[:AUTH_PORT];SERVER2[:AUTH_PORT];...
N/A
RADIUS servers to be used for authentication RAS requests.
The list can contain an arbitrary number of servers.
The order of servers is important, because servers will be queried
by the RADIUS module in the order given. If no port information is given,
port number from DefaultAuthPort
will be used.
If these attributes are not set, then os services file will be queried
for 'radius' services port. Servers could be IP addresses or DNS names.
Servers=192.168.3.1:1645;192.168.3.2:1812;radius.mycompany.com
LocalInterface=IP_OR_FQDN
N/A
Particular local network interface that RADIUS client should use in order to communicate with RADIUS servers. This parameter can be useful on NAT machines to restrict number of network interfaces used for RADIUS communication. By default this value is empty and allows RADIUS requests to be sent on any (best suitable) network interface. If you are not sure what you are doing, it is better to leave this option unset.
RadiusPortRange=10000-11000
N/A
By default (if this option is not set) RADIUS client allocates ports dynamically as specified by the operating system. If you want to restrict RADIUS client to use ports from a particular range only - set this parameter.
DefaultAuthPort=PORT_NO
An entry for 'radius' service in services file or 1812
Default port number to be used for RADIUS authentication requests
(Access-Request packets), if not overriden by Servers
attribute.
SharedSecret=SECRET
N/A (empty string)
Secret used to authenticate this GNU GK (NAS client) to RADIUS server. It should be a cryptographically strong password.
RequestTimeout=TIMEOUT_MS
2000
(miliseconds)
Timeout (miliseconds) for RADIUS server response to a request sent by GNU GK. If no response is received within this time period, next RADIUS server is queried.
IdCacheTimeout=TIMEOUT_MS
9000
(miliseconds)
Timeout (miliseconds) for RADIUS request 8-bit identifiers to be unique. If all 8-bit identifier range is exhausted within this period, new client socket (UDP socket) is allocation by RADIUS module. Let's take the example: we have approximatelly 60 RRQs/sec - after ca. 4 seconds 8-bit identifiers range gets exhausted - new socket allocated - after next 4 seconds the second 8-bit identifiers range gets exhauted - third socket allocated - after 9th second identifiers from the pool 1 are available again - ... . In general, too long timeout - too much resources consumed, too short timeout - RADIUS server may take incoming packets as duplicated and therefore drop it.
SocketDeleteTimeout=TIMEOUT_MS
60000
(miliseconds) - 60 s
Timeout for unused RADIUS sockets to be closed. It is used
in conjunction with IdCacheTimeout
- additional sockets
created during heavy GK load time periods for serving incoming
requests are closed during idle periods.
RequestRetransmissions=NUMBER
2
How many times a single RADIUS request is transmissed to every
configured RADIUS server (if no response is received). 1 means
no retransmission, 2 - single retransmission, ... . Exact retransmission
method is defined by RoundRobinServers
attribute.
RoundRobinServers=BOOLEAN
1
RADIUS requests retransmission method.
If set to 1, RADIUS request is transmitted in the following way (until response is received):
Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions
If set to 0, the following sequence is preserved:
Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions
AppendCiscoAttributes=BOOLEAN
0
If set, Cisco Vendor Specific RADIUS attibutes are included in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).
IncludeEndpointIP=BOOLEAN
1
If set, endpoint IP address is passed as Framed-IP-Address RADIUS attribute inside Access-Requests. Can be used for additional (to the username/password) authentication. For RRQs, this attribute is equal to RRQ.m_radAddress[0] or RRQ.m_callSignalAddress[0] field. For ARQs, this attribute is equal to ARQ.m_srcCallSignalAddress field or call signal address reported by the gatekeeper registration table.
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.
Servers=SERVER1[:AUTH_PORT];SERVER2[:AUTH_PORT];...
N/A
RADIUS servers to be used for RAS requests authentication.
This list can contain an arbitrary number of servers.
The order of servers is important, because servers will be queried
by the RADIUS module in the order given. If no port information is given,
port number from DefaultAuthPort
will be used.
If these attributes are not set, then os services file will be queried
for 'radius' services port. Servers could be IP addresses or DNS names.
Servers=192.168.3.1:1645;192.168.3.2:1812;radius.mycompany.com
LocalInterface=IP_OR_FQDN
N/A
Particular local network interface that RADIUS client should use in order to communicate with RADIUS servers. This parameter can be useful on NAT machines to restrict number of network interfaces used for RADIUS communication. By default this value is empty and allows RADIUS requests to be sent on any (best suitable) network interface. If you are not sure what you are doing, it is better to leave this option unset.
RadiusPortRange=10000-11000
N/A
By default (if this option is not set) RADIUS client allocates ports dynamically as specified by the operating system. If you want to restrict RADIUS client to use ports from a particular range only - set this parameter.
DefaultAuthPort=PORT_NO
An entry for 'radius' service in services file or 1812
Default port number to be used for RADIUS authentication requests
(Access-Request packets), if not overriden by Servers
attribute.
SharedSecret=SECRET
N/A (empty string)
Secret used to authenticate this GNU GK (NAS client) to RADIUS server. It should be a cryptographically strong password.
RequestTimeout=TIMEOUT_MS
2000
(miliseconds)
Timeout (miliseconds) for RADIUS server response to a request sent by GNU GK. If no response is received within this time period, next RADIUS server is queried.
IdCacheTimeout=TIMEOUT_MS
9000
(miliseconds)
Timeout (miliseconds) for RADIUS request 8-bit identifiers to be unique. If all 8-bit identifier range is exhausted within this period, new client socket (UDP socket) is allocation by RADIUS module. Let's take the example: we have approximatelly 60 RRQs/sec - after ca. 4 seconds 8-bit identifiers range gets exhausted - new socket allocated - after next 4 seconds the second 8-bit identifiers range gets exhauted - third socket allocated - after 9th second identifiers from the pool 1 are available again - ... . In general, too long timeout - too much resources consumed, too short timeout - RADIUS server may take incoming packets as duplicated and therefore drop it.
SocketDeleteTimeout=TIMEOUT_MS
60000
(miliseconds) - 60 s
Timeout for unused RADIUS sockets to be closed. It is used
in conjunction with IdCacheTimeout
- additional sockets
created during heavy GK load time periods for serving incoming
requests are closed during idle periods.
RequestRetransmissions=NUMBER
2
How many times a single RADIUS request is transmissed to every
configured RADIUS server (if no response is received). 1 means
no retransmission, 2 - single retransmission, ... . Exact retransmission
method is defined by RoundRobinServers
attribute.
RoundRobinServers=BOOLEAN
1
RADIUS requests retransmission method.
If set to 1, RADIUS request is transmitted in the following way (until response is received):
Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions
If set to 0, the following sequence is preserved:
Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions
AppendCiscoAttributes=BOOLEAN
0
If set, Cisco Vendor Specific RADIUS attibutes are included in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).
IncludeEndpointIP=BOOLEAN
1
If set, endpoint IP address is passed as Framed-IP-Address RADIUS attribute inside Access-Requests. Can be used for additional (to the username/password) authentication. For RRQs, this attribute is equal to RRQ.m_radAddress[0] or RRQ.m_callSignalAddress[0] field. For ARQs, this attribute is equal to ARQ.m_srcCallSignalAddress field or call signal address reported by the gatekeeper registration table.
FixedUsername
N/A
If this parameter is set, it overwrites a value of User-Name RADIUS attribute
for outgoing RADIUS request. That means every Access-Request will be
authenticated as for user FixedUsername
.
FixedPassword
N/A
If not set, User-Password is a copy of User-Name. For example, if User-Name
is 'john' then User-Password will also be set to 'john'. Setting this
parameter overrides this behavious and User-Password attribute will be
always set to the value of FixedPassword
.
(Neither FixedUsername nor FixedPassword set)
All endpoints will be authenticated using their alias as the username
and the password. That means, for example, endpoint 'EP1' will be authenticated
with the username 'EP1 and the password 'EP1'.
(FixedUsername not set)
FixedPassword=ppp
All endpoints will be authenticated using their alias and the password 'ppp'.
FixedUsername=ppp
FixedPassword=ppp
All endpoints will be authenticated using the username 'ppp'
and the password 'ppp'.
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
For now, only a single value is allowed here.
H235PassWord
The plain text password to be compared against when using H.235
(LDAPPasswordAuth
in Gatekeeper::Auth).
For now, only a single value is allowed here.
This section defines the LDAP server and standard LDAP client operating parameters to be used.
ServerName
ldap
The LDAP server's DNS name.
ServerPort
389
The LDAP server's TCP port (usually 389).
SearchBaseDN
o=University of Michigan, c=US
Entry point into the server's LDAP tree structure. Searches are only made below this root node.
BindUserDN
cn=Babs Jensen,o=University of Michigan, c=US
The distinguished name the gatekeeper uses to bind to the LDAP server. Leave empty if you want to access the LDAP server anonymously.
BindUserPW
ReallySecretPassword
If you specified BindUserDN
, then specify the corresponding
password to be used for binding here.
sizelimit
0
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.
timelimit
0
Maximum number of seconds a query may take until it's considered as "failed".
The gatekeeper can automatically detect whether an endpoint is behind NAT. However, if the detection fails, you can specify it manually in this section.
alias=true,yes,1,...
Specify an endpoint with alias 601 is behind NAT.
601=true
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.
VirtualQueue
This defines the H.323 alias for the virtual queue.
CTI_Timeout
10
Timeout in seconds for the external application to answer the RouteRequest.
If no answer is received during this time an ARJ will be sent to
the caller.