<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
<TITLE>OpenH323 Gatekeeper - The GNU Gatekeeper: Advanced Configuration</TITLE>
<LINK HREF="manual-13.html" REL=next>
<LINK HREF="manual-11.html" REL=previous>
<LINK HREF="manual.html#toc12" REL=contents>
</HEAD>
<BODY>
<A HREF="manual-13.html">Next</A>
<A HREF="manual-11.html">Previous</A>
<A HREF="manual.html#toc12">Contents</A>
<HR>
<H2><A NAME="s12">12.</A> <A HREF="manual.html#toc12">Advanced Configuration</A></H2>
<H2><A NAME="calltable"></A> <A NAME="ss12.1">12.1</A> <A HREF="manual.html#toc12.1">Section [CallTable]</A>
</H2>
<P>
<UL>
<LI><CODE>GenerateNBCDR=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>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.</P>
</LI>
<LI><CODE>GenerateUCCDR=0</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>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.</P>
</LI>
<LI><CODE>DefaultCallDurationLimit=3600</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Default maximum call duration limit (seconds).
Set it to <CODE>0</CODE> to disable this feature and not limit
calls duration.</P>
</LI>
<LI><CODE>AcctUpdateInterval=60</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>A time interval (seconds) for accounting updates to be logged
for each call in progress. The exact details of the accounting updates
depend on accounting logger modules selected (see section
<A HREF="manual-9.html#gkacct">[Gatekeeper::Acct]</A>). In general, the accounting
update is to provide back-end services with incrementing call duration
for connected calls.
The default value 0 tells the gatekeeper to not send accounting updates
at all. Please note that setting short periods may decrease GK performance.</P>
</LI>
<LI><CODE>TimestampFormat=Cisco</CODE><BR>
Default: <CODE>RFC822</CODE><BR>
<P>Format of timestamp strings printed inside CDRs.</P>
</LI>
<LI><CODE>IRRFrequency=60</CODE><BR>
Default: <CODE>120</CODE><BR>
<P>Set the irrFrequency in ACF messages. 0 turns it off.</P>
</LI>
<LI><CODE>IRRCheck=TRUE</CODE><BR>
Default: <CODE>FALSE</CODE><BR>
<P>Check if both endpoints in a call send the requested IRRs.
A call will be terminated if one of the endpoints didn't send
an IRR after 2 * irrFrequency.</P>
</LI>
<LI><CODE>SingleFailoverCDR=FALSE</CODE><BR>
Default: <CODE>TRUE</CODE><BR>
<P>When failover is active, more than one gateway may be tried to
establish a call. This switch defines if one or multiple CDRs
are generated for such a call.</P>
</LI>
</UL>
</P>
<H2><A NAME="h225toq931"></A> <A NAME="ss12.2">12.2</A> <A HREF="manual.html#toc12.2">Section [H225toQ931]</A>
</H2>
<P>When converting between H.225 reasons and Q.931 cause codes, GnuGk
uses a conversion table. Using this section you can change this mapping.</P>
<P>
<BLOCKQUOTE>
<CODE>[H225toQ931]<BR>
;0=34 # noBandwidth<BR>
;1=47 # gatekeeperResources<BR>
2=34 # unreachableDestination => NoCircuitChannelAvailable (default 3)<BR>
;3=16 # destinationRejection<BR>
;4=88 # invalidRevision<BR>
;5=111 # noPermission<BR>
;6=38 # unreachableGatekeeper<BR>
;7=42 # gatewayResources<BR>
;8=28 # badFormatAddress<BR>
;9=41 # adaptiveBusy<BR>
;10=17 # inConf<BR>
;11=31 # undefinedReason<BR>
;12=16 # facilityCallDeflection<BR>
;13=31 # securityDenied<BR>
14=34 # calledPartyNotRegistered => NoCircuitChannelAvailable (default 20)<BR>
;15=31 # callerNotRegistered<BR>
;16=47 # newConnectionNeeded<BR>
;17=127 # nonStandardReason<BR>
;18=31 # replaceWithConferenceInvite<BR>
;19=31 # genericDataReason<BR>
;20=31 # neededFeatureNotSupported<BR>
;21=127 # tunnelledSignallingRejected<BR></CODE>
</BLOCKQUOTE>
</P>
<H2><A NAME="endpoint"></A> <A NAME="ss12.3">12.3</A> <A HREF="manual.html#toc12.3">Section [Endpoint]</A>
</H2>
<P>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.</P>
<P>
<UL>
<LI><CODE>Gatekeeper=10.0.1.1</CODE><BR>
Default: <CODE>no</CODE><BR>
<P>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 <CODE>no</CODE>.</P>
</LI>
<LI><CODE>Type=Gateway</CODE><BR>
Default: <CODE>Gateway</CODE><BR>
<P>Define the terminal type for the endpoint.
The valid values are <CODE>Gateway</CODE> or <CODE>Terminal</CODE>.</P>
</LI>
<LI><CODE>Vendor=Cisco | GnuGk | Generic</CODE><BR>
Default: <CODE>GnuGk</CODE><BR>
<P>Choose parent gatekeeper type to enable vendor specific
extensions.</P>
</LI>
<LI><CODE>H323ID=CitronProxy</CODE><BR>
Default: <CODE><Name></CODE><BR>
<P>Specify the H.323 ID aliases for the endpoint.
Multiple aliases can be separated by comma.</P>
</LI>
<LI><CODE>E164=18888600000,18888700000</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define the E.164 (dialedDigits) aliases for the endpoint.
Multiple aliases can be separated by comma.</P>
</LI>
<LI><CODE>Password=123456</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Specify a password to be sent to the parent gatekeeper.
All RAS requests will contain the password in the <B>cryptoTokens</B> field
(MD5 & HMAC-SHA1-96) and the <B>tokens</B> field (CAT).
To send RAS requests without both <B>cryptoTokens</B> and <B>tokens</B> fields,
set the password to be empty.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.</P>
<P>Besides, the password is also used in LRQs sent to neighbor gatekeepers.</P>
</LI>
<LI><CODE>Prefix=188886,188887</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Register the specified prefixes with the parent gatekeeper.
Only takes effect when the Type is <CODE>Gateway</CODE>.</P>
</LI>
<LI><CODE>TimeToLive=900</CODE><BR>
Default: <CODE>60</CODE><BR>
<P>Suggest a time-to-live value in seconds for the registration.
Note that the real time-to-live timer is assigned by the parent
gatekeeper in the RCF replied to the RRQ.</P>
</LI>
<LI><CODE>RRQRetryInterval=10</CODE><BR>
Default: <CODE>3</CODE><BR>
<P>Define a retry interval in seconds for resending an RRQ if no response
is received from the parent gatekeeper. This interval is doubled with each
failure, up to a maximum RRQRetryInterval * 128 timeout.</P>
</LI>
<LI><CODE>ARQTimeout=2</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>Define the timeout value in second for ARQs.</P>
</LI>
<LI><CODE>UnregisterOnReload=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Defines whether the child gatekeeper unregisters and re-registers with
it's parent when receiving a Reload command.</P>
</LI>
<LI><CODE>NATRetryInterval=60</CODE><BR>
Default: <CODE>60</CODE><BR>
<P>How long to wait before trying to reconnect TCP NAT signaling socket (seconds).
This can happen when either the connection cannot be established or it has
been broken.</P>
</LI>
<LI><CODE>NATKeepaliveInterval=86400</CODE><BR>
Default: <CODE>86400</CODE><BR>
<P>Define how often the TCP NAT signaling connection with a parent gatekeeper
is refreshed. As NAT boxes usually keep TCP mappings for a definite time only,
it is good to set this to some value a bit shorter than NAT box mapping timeout.
Refreshing is done by sending a special Q.931 IncomingCallProceeding message.
If you NAT performs TCP port translation, you may need to set it to a values
as short as 60 seconds.</P>
</LI>
<LI><CODE>Discovery=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Decide whether to discover the parent gatekeeper by sending GRQ first.</P>
</LI>
<LI><CODE>UseAlternateGK=0</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Enable alternate gatekeepers feature. If GRJ/GCF/RFC messages received
from a parent gatekeeper contain a list of alternate gatekeepers, this
information is stored and can be used to reregister with another gatekeeper
in case of any failure. If you don't want to use this feature, set this
variable to <CODE>0</CODE>.</P>
</LI>
<LI><CODE>GatekeeperIdentifier=ParentGK</CODE><BR>
Default: <CODE>Not set</CODE><BR>
<P>Define it if you want to accept only such parent gatekeepers that match
this gatekeeper identifier. Useful with GRQ discovery and can prevent
an accidental gatekeeper match. Do not set this variable, if you do not
care about gatekeeper identifiers or you use alternate gatekeepers that
can have different gatekeeper identifiers set.</P>
</LI>
<LI><CODE>EndpointIdentifier=OpenH323GK</CODE><BR>
Default: <CODE>Not set</CODE><BR>
<P>Set this if you want to use a specific endpoint identifier for this child
gatekeeper. If this option is not set (default), the identifier is assigned
by a parent gatekeeper in a GCF/RCF message.</P>
</LI>
</UL>
</P>
<H2><A NAME="ss12.4">12.4</A> <A HREF="manual.html#toc12.4">Section [CTI::Agents]</A>
</H2>
<P>This section allows the configuration of a so called virtual queues to
allow inbound call distribution by an external application via the
status port.
A virtual queue has an H.323 alias that can be called like an endpoint.</P>
<P>Upon arrival of an ARQ or LRQ on a virtual queue, the gatekeeper signals
a RouteRequest on the status port and waits for an external application
to respond with either a RouteReject (then the ARQ/LRQ will be rejected)
or with RouteToAlias/RouteToGateway which leads to the ARQ/LRQ being rewritten so the call
will be routed to the alias (eg. call center agent) specified by
the external application.</P>
<P>If no answer is received after a timeout period, the call is terminated.</P>
<P>You can specify virtual queues in three ways:
<UL>
<LI><CODE>exact alias name</CODE> - a list of aliases is given. If a request destination
alias matches one these names, the virtual queue is activated,</LI>
<LI><CODE>prefix</CODE> - a list of prefixes is given. If a request destination alias
starts with one these prefixes, the virtual queue is activated,</LI>
<LI><CODE>regular expression</CODE> - a regular expression is given. If a request destination
alias matches the expression, the virtual queue is activated.</LI>
</UL>
</P>
<P>See the monitoring section for details on the messages and responses.</P>
<P>
<UL>
<LI><CODE>VirtualQueueAliases</CODE><BR>
Default: <CODE>none</CODE><BR>
<P>This defines a list of H.323 aliases for the virtual queues (used with the vqueue RoutingPolicy).</P>
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE>
<CODE>VirtualQueueAliases=sales,support</CODE>
</BLOCKQUOTE>
<BR></P>
</DL>
</P>
</LI>
<LI><CODE>VirtualQueuePrefixes</CODE><BR>
Default: <CODE>none</CODE><BR>
<P>This defines a list of prefixes for the virtual queues (used with the vqueue RoutingPolicy).</P>
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE>
<CODE>VirtualQueuePrefixes=001215,1215</CODE>
</BLOCKQUOTE>
<BR></P>
</DL>
</P>
</LI>
<LI><CODE>VirtualQueueRegex</CODE><BR>
Default: <CODE>none</CODE><BR>
<P>This defines a regular expression for the virtual queues (used with the vqueue RoutingPolicy).</P>
<P>
<DL>
<DT><B>Example (numbers starting with 001215 or 1215):</B><DD><P>
<BLOCKQUOTE>
<CODE>VirtualQueueRegex=^(001|1)215[0-9]*$</CODE>
</BLOCKQUOTE>
<BR></P>
</DL>
</P>
</LI>
<LI><CODE>RequestTimeout</CODE><BR>
Default: <CODE>10</CODE><BR>
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.</LI>
</UL>
</P>
<H2><A NAME="sqlconf"></A> <A NAME="ss12.5">12.5</A> <A HREF="manual.html#toc12.5">Section [SQLConfig]</A>
</H2>
<P>Load gatekeeper settings from an SQL database (in addition to settings
read from the config file). A generic <CODE>ConfigQuery</CODE> can be used
to read almost all setting from the database and/or one of <CODE>[RasSrv::RewriteE164]</CODE>,
<CODE>[RasSrv::PermanentEndpoints]</CODE>, <CODE>[RasSrv::Neighbors]</CODE>,
<CODE>[RasSrv::GWPrefixes]</CODE> queries can be used to load particular settings.
Entries read from the SQL database take precedence over settings found
in the config file.</P>
<P>
<UL>
<LI><CODE>Driver=MySQL | PostgreSQL | Firebird</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>SQL database driver to use. Currently, <CODE>MySQL</CODE>, <CODE>PostgreSQL</CODE> and <CODE>Firebird</CODE> drivers
are implemented.</P>
</LI>
<LI><CODE>Host=DNS[:PORT] | IP[:PORT]</CODE><BR>
Default: <CODE>localhost</CODE><BR>
<P>SQL server host address. Can be in the form of <CODE>DNS[:PORT]</CODE> or <CODE>IP[:PORT]</CODE>.
Like <CODE>sql.mycompany.com</CODE> or <CODE>sql.mycompany.com:3306</CODE> or <CODE>192.168.3.100</CODE>.</P>
</LI>
<LI><CODE>Database=billing</CODE><BR>
Default: <CODE>billing</CODE><BR>
<P>The database name to connect to.</P>
</LI>
<LI><CODE>Username=gnugk</CODE><BR>
<P>The username used to connect to the database.</P>
</LI>
<LI><CODE>Password=secret</CODE><BR>
<P>The password used to connect to the database.
If the password is not specified, a database connection attempt
without any password will be made.
If <CODE>EncryptAllPasswords</CODE> is enabled, or a <CODE>KeyFilled</CODE> variable is defined
in this section, the password is in encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.</P>
</LI>
<LI><CODE>ConfigQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define an SQL query used to read gatekeeper settings from the database.
The query is parameterized - that means parameter replacement occurs before
the query is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ...
strings. Specify %% to embed a percent character before a digit into string
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions
like <B>%{1}123</B>. For <CODE>ConfigQuery</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>
It is expected that the query returns zero or more rows of data,
with each row consisting of <B>three</B> columns:
<UL>
<LI><CODE>column at index 0</CODE> - config section name</LI>
<LI><CODE>column at index 1</CODE> - config key (option name)</LI>
<LI><CODE>column at index 2</CODE> - config value (option value)</LI>
</UL>
</P>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
ConfigQuery=SELECT secname, seckey, secval FROM sqlconfig WHERE gk = '%1'
ConfigQuery=SELECT 'RasSrv::RRQAuth', alias, rule FROM rrqauth WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>RewriteE164Query=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define an SQL query used to retrieve from the database rewrite rules
for <CODE>[RasSrv::RewriteE164]</CODE> section. The query is parameterized
- that means parameter replacement occurs before each query is executed.
Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ... strings.
Specify %% to embed a percent character before a digit into string
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions
like <B>%{1}123</B>. For <CODE>RewriteE164Query</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>
It is expected that the query returns zero or more rows of data,
with each row consisting of two columns:
<UL>
<LI><CODE>column at index 0</CODE> - rewrite rule key</LI>
<LI><CODE>column at index 1</CODE> - rewrite rule value</LI>
</UL>
</P>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
RewriteE164Query=SELECT rkey, rvalue FROM rewriterule WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>NeighborsQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define an SQL query used to retrieve from the database neighbor entries
for <CODE>[RasSrv::Neighbors]</CODE> section . The query is parameterized
- that means parameter replacement occurs before each query
is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ...
strings. Specify %% to embed a percent character before a digit into string
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions
like <B>%{1}123</B>. For <CODE>NeighborsQuery</CODE> one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>
It is expected that the query returns zero or more rows of data,
with each row consisting of six columns:
<UL>
<LI><CODE>column at index 0</CODE> - neighbor name (identifier)</LI>
<LI><CODE>column at index 1</CODE> - neighbor IP address</LI>
<LI><CODE>column at index 2</CODE> - neighbor port number</LI>
<LI><CODE>column at index 3</CODE> - optional prefixes (comma separated)</LI>
<LI><CODE>column at index 4</CODE> - optional password</LI>
<LI><CODE>column at index 5</CODE> - optional dynamic IP flag</LI>
</UL>
</P>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
NeighborsQuery=SELECT nid, nip, nport, npfx, NULL, 0 FROM neighbor WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>PermanentEndpointsQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define an SQL query used to retrieve permanent endpoints from the database
for <CODE>[RasSrv::PermanentEndpoints]</CODE> section . The query is parameterized
- that means parameter replacement occurs before each query
is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ...
strings. Specify %% to embed a percent character before a digit into string
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions
like <B>%{1}123</B>. For <CODE>PermanentEndpointsQuery</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>
It is expected that the query returns zero or more rows of data,
with each row consisting of four columns:
<UL>
<LI><CODE>column at index 0</CODE> - permanent endpoint IP address</LI>
<LI><CODE>column at index 1</CODE> - permanent endpoint port number</LI>
<LI><CODE>column at index 2</CODE> - permanent endpoint alias</LI>
<LI><CODE>column at index 3</CODE> - optional permanent endpoint prefixes (comma separated)</LI>
</UL>
</P>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
PermanentEndpointsQuery=SELECT peip, 1720, pealias, NULL FROM permanentep WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>GWPrefixesQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define an SQL query used to retrieve gateway prefixes from the database
for <CODE>[RasSrv::GWPrefixes]</CODE> section . The query is parameterized
- that means parameter replacement is made before each query
is executed. Parameter placeholders are denoted by <B>%1</B>, <B>%2</B>, ...
strings. Specify %% to embed a percent character before a digit into string
(like <B>%%1</B>), specify <B>%{1}</B> to allow expansion inside complex expressions
like <B>%{1}123</B>. For <CODE>GWPrefixesQuery</CODE> only one parameter is defined:
<UL>
<LI><CODE>%1</CODE> - the gatekeeper identifier</LI>
</UL>
It is expected that the query returns zero or more rows of data,
with each row consisting of two columns:
<UL>
<LI><CODE>column at index 0</CODE> - gateway alias</LI>
<LI><CODE>column at index 1</CODE> - gateway prefixes (comma separated)</LI>
</UL>
</P>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
GWPrefixesQuery=SELECT gwalias, gwpfx FROM gwprefix WHERE gk = '%1'
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
</UL>
</P>
<HR>
<A HREF="manual-13.html">Next</A>
<A HREF="manual-11.html">Previous</A>
<A HREF="manual.html#toc12">Contents</A>
</BODY>
</HTML>
