<!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: Authentication Configuration</TITLE>
<LINK HREF="manual-9.html" REL=next>
<LINK HREF="manual-7.html" REL=previous>
<LINK HREF="manual.html#toc8" REL=contents>
</HEAD>
<BODY>
<A HREF="manual-9.html">Next</A>
<A HREF="manual-7.html">Previous</A>
<A HREF="manual.html#toc8">Contents</A>
<HR>
<H2><A NAME="s8">8.</A> <A HREF="manual.html#toc8">Authentication Configuration</A></H2>
<P>The following sections in the config file can be used to configure authentication.</P>
<H2><A NAME="gkauth"></A> <A NAME="ss8.1">8.1</A> <A HREF="manual.html#toc8.1">Section [Gatekeeper::Auth]</A>
</H2>
<P>The section defines the authentication mechanism for the gatekeeper.</P>
<P>
<DL>
<DT><B>Syntax:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
authrule=actions
<authrule> := SimplePasswordAuth | AliasAuth | FileIPAuth | PrefixAuth | RadAuth | RadAliasAuth | SQLAuth | SQLAliasAuth | SQLPasswordAuth | CapacityControl | ...
<actions> := <control>[;<ras>|<q931>,<ras>|<q931>,...]
<control> := optional | required | sufficient
<ras> := GRQ | RRQ | URQ | ARQ | BRQ | DRQ | LRQ | IRQ
<q931> := Setup | SetupUnreg
</PRE>
</CODE></BLOCKQUOTE>
</P>
</DL>
A rule may results in one of the three codes: ok, fail, pass.
<UL>
<LI><CODE>ok</CODE> - The request is authenticated by this module.</LI>
<LI><CODE>fail</CODE> - The authentication fails and should be rejected.</LI>
<LI><CODE>next</CODE> - The rule cannot determine the request.</LI>
</UL>
There are also three ways to control a rule:
<UL>
<LI><CODE>optional</CODE> - If the rule cannot determine the request, it is passed to next rule.</LI>
<LI><CODE>required</CODE> - The requests should be authenticated by this module, or it would be rejected. The authenticated request would then be passed to next rule.</LI>
<LI><CODE>sufficient</CODE> - 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.</LI>
</UL>
</P>
<P>Currently supported modules: (most of them only support a subset of the ras or q931 actions)
<UL>
<LI><CODE>SimplePasswordAuth/SQLPasswordAuth</CODE>
<P>These modules check the <B>tokens</B> or <B>cryptoTokens</B> fields of RAS message.
The tokens should contain at least generalID and password.
For <B>cryptoTokens</B>, <B>cryptoEPPwdHash</B> tokens hashed by simple MD5 and
<B>nestedcryptoToken</B> tokens hashed by HMAC-SHA1-96 (libssl must be installed!)
are supported now. For <B>tokens</B> tokens hashed by CAT (Cisco Access Token)
and a clear text username/password are supported now.
The ID and password are read from
<A HREF="#password">[SimplePasswordAuth]</A> section,
an SQL database for <CODE>SimplePasswordAuth</CODE> and <CODE>SQLPasswordAuth</CODE>
modules. <CODE>MySQLPasswordAuth</CODE>
module is supported for backward compatibility.</P>
</LI>
<LI><CODE>AliasAuth/SQLAliasAuth</CODE>
<P>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 <CODE>AliasAuth</CODE> the pattern is defined in
<A HREF="#rrqauth">[RasSrv::RRQAuth]</A> section.
For <CODE>SQLAliasAuth</CODE>, the pattern is retrieved from an SQL database,
defined in
<A HREF="#sqlaliasauth">[SQLAliasAuth]</A> section.</P>
</LI>
<LI><CODE>FileIPAuth</CODE>
<P>This module provides a simple way to restrict access to the gatekeeper
based on caller's IP/network.</P>
</LI>
<LI><CODE>PrefixAuth</CODE>
<P>The IP or aliases of a request with a given prefix must match a specified
pattern. See section
<A HREF="#prefixauth">[PrefixAuth]</A> for details.
Currently the module can only authorize
AdmissionRequest (ARQ) and LocationRequest (LRQ).</P>
</LI>
<LI><CODE>RadAuth</CODE>
<P>Provides authentication based on H.235 username/password
security scheme. Authenticates RRQ, ARQ and Q.931 Setup through remote
RADIUS servers. It passes to RADIUS servers usernames and passwords
extracted from CAT (Cisco Access Tokens) <B>tokens</B> carried
inside RRQ, ARQ or Setup 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 <CODE>RadAliasAuth</CODE> module).
See section
<A HREF="#radauth">[RadAuth]</A> for details.</P>
</LI>
<LI><CODE>RadAliasAuth</CODE>
<P>Provides authentication based on endpoint aliases
and/or call signaling IP addresses with remote RADIUS servers.
It does not need any H.235 <B>tokens</B> inside RAS messages,
so it can be used on a wider range of systems as compared to <CODE>RadAuth</CODE>.
RRQ, ARQ and Q.931 Setup messages can be authenticated using this module.
See section
<A HREF="#radaliasauth">[RadAliasAuth]</A> for details.</P>
</LI>
<LI><CODE>SQLAuth</CODE>
<P>A powerful module to authenticate and authorize RRQ, ARQ, LRQ and Setup
messages. It can perform checks based on various parameters, like
caller's number, destination number, username and more. It also supports
enforcing call duration limit, number rewriting, call routing, alias
verification and assignment.
See section
<A HREF="#sqlauth">[SQLAuth]</A> for more details.</P>
</LI>
<LI><CODE>CapacityControl</CODE>
<P>A flexible module to control inbound call volume with ability to configure
various conditions. IMPORTANT: It has to be used in conjunction with <CODE>CapacityControl</CODE>
accounting module. See section
<A HREF="#capctrl">[CapacityControl]</A> for more details.</P>
</LI>
</UL>
</P>
<P>You can also configure a rule to check only for some particular RAS messages.
The following example configures <CODE>SimplePasswordAuth</CODE> as an optional rule
to check RRQ and ARQ. If an RRQ is not checked (not contains
<B>tokens</B> or <B>cryptoTokens</B> fields), it is checked by <CODE>AliasAuth</CODE>.
The default is to accept all requests.</P>
<P>
<DL>
<DT><B>Example 1:</B><DD><P><CODE>SimplePasswordAuth=optional;RRQ,ARQ</CODE><BR>
<CODE>AliasAuth=sufficient;RRQ</CODE><BR></P>
</DL>
</P>
<P>The example below authenticates all calls, checking signaling Setup
message details, using RadAliasAuth module.</P>
<P>
<DL>
<DT><B>Example 2:</B><DD><P><CODE>RadAliasAuth=required;Setup</CODE><BR>
<CODE>default=allow</CODE></P>
</DL>
</P>
<P>This example checks endpoint registrations (RRQ) and call admissions (ARQ)
either by means of username/password (RadAuth) or alias/IP (RadAliasAuth).
Additionally, if the call is from an unregistered endpoint (and therefore
no RRQ or ARQ authentication has been performed), Setup message authentication
using RadAliasAuth takes place (SetupUnreg).</P>
<P>
<DL>
<DT><B>Example 3:</B><DD><P><CODE>RadAuth=optional;RRQ,ARQ</CODE><BR>
<CODE>RadAliasAuth=required;RRQ,ARQ,SetupUnreg</CODE><BR>
<CODE>default=allow</CODE></P>
</DL>
</P>
<H2><A NAME="fileipauth"></A> <A NAME="ss8.2">8.2</A> <A HREF="manual.html#toc8.2">Section [FileIPAuth]</A>
</H2>
<P>This section defines a list of IP addresses/networks which are allowed
to access gatekeeper resources. A list of allowed prefixes can be specified
together with an IP address. Supported Gatekeeper::Auth events are:
<CODE>GRQ</CODE>, <CODE>RRQ</CODE>, <CODE>LRQ</CODE>, <CODE>Setup</CODE> and <CODE>SetupUnreg</CODE>. Format
of a single entry is:</P>
<P><CODE>IP=[allow | reject][;prefix[,prefix...]]</CODE></P>
<P>where IP is a single IP address, a network address (in A.B.C.D/M.M.M.M or A.B.C.D/LENGTH format) or a string <CODE>'any'</CODE> or <CODE>'*'</CODE> to match any address.
The access list can also be loaded from an external file using <CODE>include</CODE> directive. During authentication, network mask length defines a priority for each
entry, so rule 192.168.1.1=allow takes precedence over 192.168.1.0/24=reject.</P>
<P>
<DL>
<DT><B>Example #1:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Auth]
FileIPAuth=required;RRQ,LRQ,Setup
[FileIPAuth]
192.168.1.240=reject
192.168.1.0/24=allow
192.168.2.0/255.255.255.0=allow;48,49,44
any=reject
</PRE>
</CODE></BLOCKQUOTE>
</P>
</DL>
</P>
<P>
<DL>
<DT><B>Example #2:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Auth]
FileIPAuth=required;Setup
[FileIPAuth]
include=/etc/gnugk/accesslist.ini
(EOF)
Contents of /etc/gnugk/accesslist.ini:
[FileIPAuth]
192.168.1.1=allow
192.168.1.100=allow
any=reject
</PRE>
</CODE></BLOCKQUOTE>
</P>
</DL>
</P>
<H2><A NAME="password"></A> <A NAME="ss8.3">8.3</A> <A HREF="manual.html#toc8.3">Section [SimplePasswordAuth]</A>
</H2>
<P>The section defines the userid and password pairs used by
<CODE>SimplePasswordAuth</CODE> module. All passwords are encrypted
using the <CODE>addpasswd</CODE> utility.</P>
<P>Usage:
<BLOCKQUOTE><CODE>
<PRE>
addpasswd config section userid password
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Example:
<BLOCKQUOTE><CODE>
<PRE>
addpasswd config.ini SimplePasswordAuth frank secret
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Options:
<UL>
<LI><CODE>KeyFilled=123</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Default value to use as a padding byte during password encryption/decryption.</P>
</LI>
<LI><CODE>CheckID=1</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Check if the aliases match the ID in the tokens.</P>
</LI>
<LI><CODE>PasswordTimeout=120</CODE><BR>
Default: <CODE>-1</CODE><BR>
<P>The module <CODE>SimplePasswordAuth</CODE> and all its descendants will cache an
authenticated password. This field define the cache timeout value in second.
<CODE>0</CODE> means never cache the password, while a negative value
means the cache never expires.</P>
</LI>
</UL>
</P>
<H2><A NAME="sqlpasswordauth"></A> <A NAME="ss8.4">8.4</A> <A HREF="manual.html#toc8.4">Section [SQLPasswordAuth]</A>
</H2>
<P>Authenticate H.235 enabled endpoints using passwords stored
in the SQL database. This section defines SQL driver to use,
SQL database connection parameters and the query to use to retrieve passwords.</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 an encrypted form and should be created using
the <CODE>addpasswd</CODE> utility.</P>
</LI>
<LI><CODE>CacheTimeout=120</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>This field defines how long (alias;password) pairs retrieved from the database
will be cached in the local memory. The cache timeout value is expressed in seconds.
<CODE>0</CODE> means to not cache passwords, while a negative value
means the cache never expires (only <CODE>reload</CODE> command will refresh the cache).</P>
</LI>
<LI><CODE>MinPoolSize=5</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Define the number of active SQL connections. This allows better performance
under heavy load, because more than 1 concurrent query can be executed
at the same time. <CODE>MinPoolSize=1</CODE> setting simulates old behavior,
when access to the SQL database is serialized (one query at time).</P>
</LI>
<LI><CODE>Query=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines SQL query used to retrieve H.235 password from the database. 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>SQLPasswordAuth</CODE> two parameters are defined:
<UL>
<LI><CODE>%1</CODE> - the actual alias to query the password for</LI>
<LI><CODE>%2</CODE> - the gatekeeper identifier</LI>
</UL>
</P>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
SELECT h235password FROM users WHERE alias = '%1' AND active
SELECT h235password FROM users WHERE alias = '%1' AND gk = '%2'
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
</UL>
</P>
<H2><A NAME="rrqauth"></A> <A NAME="ss8.5">8.5</A> <A HREF="manual.html#toc8.5">Section [RasSrv::RRQAuth]</A>
</H2>
<P>Specify the action on RRQ reception (confirm or deny) for <CODE>AliasAuth</CODE> 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.</P>
<P>
<DL>
<DT><B>Syntax:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
<authrules> := empty | <authrule> "&" <authrules>
<authrule> := <authtype> ":" <authparams>
<authtype> := "sigaddr" | "sigip"
<autparams> := [!&]*
</PRE>
</CODE></BLOCKQUOTE>
</P>
</DL>
</P>
<P>The notation and meaning of <CODE><authparams></CODE> depends on
<CODE><authtype></CODE>:</P>
<P>
<UL>
<LI><CODE>sigaddr</CODE> - extended regular expression that has to match against the
``PrintOn(ostream)'' representation of the signal address of the request.
<P>Example:
<BLOCKQUOTE><CODE>
<PRE>
sigaddr:.*ipAddress .* ip = .* c0 a8 e2 a5 .*port = 1720.*
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>sigip</CODE> - specialized form of `<CODE>sigaddr</CODE>'.
Write the signaling IP address using (commonly used) decimal notation:
``<CODE>byteA.byteB.byteC.byteD:port</CODE>''.
<P>Example:
<BLOCKQUOTE><CODE>
<PRE>
sigip:192.168.242.165:1720
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>allow</CODE> - always accept the alias.
</LI>
<LI><CODE>deny</CODE> - always reject the alias.
</LI>
</UL>
</P>
<H2><A NAME="sqlaliasauth"></A> <A NAME="ss8.6">8.6</A> <A HREF="manual.html#toc8.6">Section [SQLAliasAuth]</A>
</H2>
<P>Authenticate endpoints using rules stored in the SQL database
(the rules conform to the format defined in the
<A HREF="#rrqauth">[RasSrv::RRQAuth]</A> section).
This section defines SQL driver to use, SQL database connection parameters
and the query to use to retrieve the patterns.</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>CacheTimeout=120</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>This field defines how long (alias;authrule) pairs retrieved from the database
will be cached in the local memory. The cache timeout value is expressed in seconds.
<CODE>0</CODE> means to not cache rules, while a negative value
means the cache never expires (only <CODE>reload</CODE> command will refresh the cache).</P>
</LI>
<LI><CODE>MinPoolSize=5</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Define the number of active SQL connections. This allows better performance
under heave load, because more than 1 concurrent query can be executed
at the same time. <CODE>MinPoolSize=1</CODE> setting simulates old behavior,
when access to the SQL database is serialized (one query at time).</P>
</LI>
<LI><CODE>Query=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Defines SQL query used to retrieve alias rule from the database. 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>SQLAliasAuth</CODE> two parameters are defined:
<UL>
<LI><CODE>%1</CODE> - the actual alias to query the rule for</LI>
<LI><CODE>%2</CODE> - the gatekeeper identifier</LI>
</UL>
</P>
<P>Sample query strings:
<BLOCKQUOTE><CODE>
<PRE>
SELECT authrule FROM users WHERE alias = '%1' AND active
SELECT 'sigip:' || host(ip) || port FROM users WHERE alias = '%1'
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
</UL>
</P>
<H2><A NAME="sqlauth"></A> <A NAME="ss8.7">8.7</A> <A HREF="manual.html#toc8.7">Section [SQLAuth]</A>
</H2>
<P>Authenticate and authorize endpoints/calls using an SQL database.
Support for RRQ, ARQ, LRQ and Setup events is provided.</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>MinPoolSize=5</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>Define the number of active SQL connections. This allows better performance
under heave load, because more than 1 concurrent query can be executed
at the same time. <CODE>MinPoolSize=1</CODE> setting simulates old behavior,
when access to the SQL database is serialized (one query at time).</P>
</LI>
<LI><CODE>RegQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define an SQL query to be used to perform authentication and authorization
of endpoint registrations. The query is parameterized - that means parameter
replacement is made before each query is executed. The following parameters are defined:
<UL>
<LI><CODE>%g</CODE> - the gatekeeper identifier</LI>
<LI><CODE>%{gkip}</CODE> - a gatekeeper IP the request has been received on</LI>
<LI><CODE>%u</CODE> - username associated with an endpoint (usually an H.323 ID)</LI>
<LI><CODE>%{callerip}</CODE> - caller's IP (the request has been received from - NAT IP for natted endpoints)</LI>
<LI><CODE>%{aliases}</CODE> - a comma separated list of endpoint aliases</LI>
</UL>
</P>
<P>If the query returns no rows, the result is undefined, which basically
means failure for <CODE>required</CODE> rules and "try next" for optional rules.
Otherwise, the first result row is examined to determine authentication
result and get additional information:
<OL>
<LI>The first column is converted into a boolean value (1, T, TRUE, allow, y, yes means true)
and is an authentication result (accept/reject).</LI>
<LI>If the registration is authenticated successfully, remaining columns
are examined:
<OL>
<LI>If there exists a column called <CODE>'aliases'</CODE>, replace original endpoint
aliases with these new ones</LI>
<LI>If there exists a column called <CODE>'billingmode'</CODE>, set a billing mode
associated with the endpoint (0 - credit, </LI>
<LI>0 - debit)</LI>
<LI>If there exists a column called <CODE>'creditamount'</CODE>, set account balance
associated with the endpoint (this is an arbitrary string)</LI>
</OL>
</LI>
</OL>
</P>
<P>Query string examples:
<BLOCKQUOTE><CODE>
<PRE>
SELECT 1, 0 AS billingmode, '12.00 USD' AS creditamount
SELECT NOT disabled, assignaliases AS aliases, balance FROM users WHERE h323id = '%u'
SELECT * FROM get_registration_auth('%g', '%u', '%{callerip}', '%{aliases}') AS result(accept, aliases, billingmode, creditamount)
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>NbQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define an SQL query to be used to perform authentication and authorization
of location requests sent from neighbors. The query is parameterized - that means parameter
replacement is made before each query is executed. The following parameters are defined:
<UL>
<LI><CODE>%g</CODE> - the gatekeeper identifier</LI>
<LI><CODE>%{gkip}</CODE> - a gatekeeper IP the request has been received on</LI>
<LI><CODE>%{nbid</CODE> - neighbor identifier from the config</LI>
<LI><CODE>%{nbip}</CODE> - neighbor IP (the request has been received from)</LI>
<LI><CODE>%{Calling-Station-Id}</CODE> - caller's number, if available</LI>
<LI><CODE>%{src-info}</CODE> - content of sourceInfo LRQ field, if available</LI>
<LI><CODE>%{Called-Station-Id}</CODE> - destination number</LI>
<LI><CODE>%{dest-info}</CODE> - content of destinationInfo LRQ field</LI>
<LI><CODE>%{bandwidth}</CODE> - requested bandwidth, if present in the LRQ</LI>
</UL>
</P>
<P>If the query returns no rows, the result is undefined, which basically
means failure for <CODE>required</CODE> rules and "try next" for optional rules.
Otherwise, the first result row is examined to determine authentication
result and get additional information:
<OL>
<LI>The first column is converted into a boolean value (1, T, TRUE, allow, y, yes means true)
and is an authentication result (accept/reject).</LI>
<LI>If the request is authenticated successfully, remaining columns
are examined:
<OL>
<LI>If there exists a column called <CODE>'destination'</CODE>, populate the original
destinationInfo field with these new aliases - this may affect routing
decision, which is made after auth step</LI>
</OL>
</LI>
</OL>
</P>
<P>Query string examples:
<BLOCKQUOTE><CODE>
<PRE>
SELECT active FROM neighbors WHERE name = '%{nbid}' AND ip = '%{nbip}' UNION SELECT 0
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>CallQuery=SELECT ...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>Define an SQL query to be used to perform authentication and authorization
of calls (ARQ and Setup). The query is parameterized - that means parameter
replacement is made before each query is executed. The following parameters are defined:
<UL>
<LI><CODE>%g</CODE> - the gatekeeper identifier</LI>
<LI><CODE>%{gkip}</CODE> - a gatekeeper IP the request has been received on</LI>
<LI><CODE>%u</CODE> - an username associated with the caller</LI>
<LI><CODE>%{callerip}</CODE> - caller's IP (the request has been received from - NAT IP for natted endpoints)</LI>
<LI><CODE>%{Calling-Station-Id}</CODE> - caller's number, if available</LI>
<LI><CODE>%{Called-Station-Id}</CODE> - destination number</LI>
<LI><CODE>%{Dialed-Number}</CODE> - original destination number (before rewrite)</LI>
<LI><CODE>%{bandwidth}</CODE> - requested bandwidth, if present in the ARQ</LI>
<LI><CODE>%{answer}</CODE> - 1, if the request is an answering ARQ</LI>
<LI><CODE>%{arq}</CODE> - 1 for ARQ triggered query, 0 for Setup triggered query</LI>
</UL>
</P>
<P>If the query returns no rows, the result is undefined, which basically
means failure for <CODE>required</CODE> rules and "try next" for optional rules.
Otherwise, the first result row is examined to determine authentication
result and get additional information:
<OL>
<LI>The first column is converted into a boolean value (1, T, TRUE, allow, y, yes means true)
and is an authentication result (accept/reject the call).</LI>
<LI>If the request is authenticated successfully, remaining columns
are examined:
<OL>
<LI>If there exists a column called <CODE>'billingmode'</CODE>, set a billing mode
associated with the endpoint (0 - credit, </LI>
<LI>0 - debit)</LI>
<LI>If there exists a column called <CODE>'creditamount'</CODE>, set account balance
associated with the endpoint (this is an arbitrary string)</LI>
<LI>If there exists a column called <CODE>'credittime'</CODE>, use its integer
value to set call duration limit</LI>
<LI>If there exists a column called <CODE>'redirectnumber'</CODE>, replace
the original destination number with this one</LI>
<LI>If there exists a column called <CODE>'redirectip'</CODE>, force the call
to be sent to the specified IP (one can put multiple destinations
separated by a semicolon)</LI>
<LI>If there exists a column called <CODE>'proxy'</CODE>, force the gatekeeper
to enable/disable (depends on the 'proxy' column value) RTP proxy
for this call</LI>
</OL>
</LI>
</OL>
</P>
<P>Query string examples:
<BLOCKQUOTE><CODE>
<PRE>
SELECT 1, 360 AS credittime, 0 AS proxy
SELECT * FROM auth_call('%g', '%u', '%{Calling-Station-Id}', '%{callerip}', '%{Called-Station-Id}') AS result(accept, credittime)
SELECT 1, '1234' AS redirectnumber, '192.168.1.1' AS redirectip
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
</UL>
</P>
<H2><A NAME="prefixauth"></A> <A NAME="ss8.8">8.8</A> <A HREF="manual.html#toc8.8">Section [PrefixAuth]</A>
</H2>
<P>The section defines the authentication rule for <CODE>PrefixAuth</CODE> module.
Currently, only ARQs and LRQs can be authorized by this module.</P>
<P>First, a most specific prefix is selected according to the <B>destinationInfo</B>
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 <CODE>default</CODE> 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.</P>
<P>
<DL>
<DT><B>Format:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
prefix=authrule[|authrule|...]
</PRE>
</CODE></BLOCKQUOTE>
</P>
<DT><B>Syntax:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
<authrule> := <result> <authrule>
<result> := deny | allow
<authrule> := [!]ipv4:<iprule> | [!]alias:<aliasrule>
</PRE>
</CODE></BLOCKQUOTE>
</P>
</DL>
Where <CODE><iprule></CODE> can be specified in decimal dot notation or
CIDR notation, <CODE><aliasrule></CODE> is expressed in regular expression.
If the `<CODE>!</CODE>' flag precedes the rule, the sense is inverted.</P>
<P>
<DL>
<DT><B>Example:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
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
</PRE>
</CODE></BLOCKQUOTE>
</P>
</DL>
</P>
<P>In this configuration, all endpoints except from network <CODE>10.0.0.0/27</CODE>
are allow to call prefix 555 (except 5555).
Endpoints from <CODE>192.168.1.0/24</CODE> are not allowed to call prefix 5555,
except <CODE>192.168.1.1</CODE>.
Endpoints <B>not</B> from <CODE>172.16.0.0/24</CODE> 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.</P>
<H2><A NAME="radauth"></A> <A NAME="ss8.9">8.9</A> <A HREF="manual.html#toc8.9">Section [RadAuth]</A>
</H2>
<P>This section defines configuration settings that enable
RADIUS authentication based on H.235 CATs (Cisco Access Tokens)
present in RRQ, ARQ RAS requests and Q.931 Setup messages.
<UL>
<LI><CODE>Servers=SERVER1[:AUTH_PORT[:ACCT_PORT[:SECRET]]];SERVER2[:AUTH_PORT[:ACCT_PORT[:SECRET]]];...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>RADIUS servers to be used for authentication. 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 given order. If no port information
is provided, port number from <CODE>DefaultAuthPort</CODE> will be used. If no secret is set,
the default shared secret from <CODE>SharedSecret</CODE> is taken.
Servers names can be IP addresses or DNS names.</P>
<P>
<DL>
<DT><B>Sample <CODE>Servers</CODE> lines:</B><DD><P><CODE>Servers=192.168.1.1</CODE><BR>
<CODE>Servers=192.168.1.1:1645</CODE><BR>
<CODE>Servers=192.168.1.1:1645:1646:secret1</CODE><BR>
<CODE>Servers=radius1.mycompany.com:1812</CODE><BR>
<CODE>Servers=radius1.mycompany.com;radius2.mycompany.com</CODE><BR>
<CODE>Servers=radius1.mycompany.com:1812:1813:secret1;radius2.mycompany.com:1812:1813:secret2</CODE><BR></P>
</DL>
</P>
</LI>
<LI><CODE>LocalInterface=IP_OR_FQDN</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>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.</P>
</LI>
<LI><CODE>RadiusPortRange=10000-11000</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>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.</P>
</LI>
<LI><CODE>DefaultAuthPort=PORT_NO</CODE><BR>
Default: <CODE>1812</CODE><BR>
<P>Default port number to be used for RADIUS authentication requests
(Access-Request packets), if not overridden by <CODE>Servers</CODE> attribute.</P>
</LI>
<LI><CODE>SharedSecret=SECRET</CODE><BR>
Default: <CODE>N/A (empty string)</CODE><BR>
<P>Secret used to authenticate this GnuGk (NAS client) to RADIUS
server. It should be a cryptographically strong password. This is the default
value used, if no server-specific secret is set in the <CODE>Servers</CODE>.
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>RequestTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>2000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) for RADIUS server response to a request
sent by GnuGk. If no response is received within this time period,
next RADIUS server is queried.</P>
</LI>
<LI><CODE>IdCacheTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>9000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) 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 approximately 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 exhausted - 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.</P>
</LI>
<LI><CODE>SocketDeleteTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>60000</CODE> (milliseconds) - 60 s<BR>
<P>Timeout for unused RADIUS sockets to be closed. It is used
in conjunction with <CODE>IdCacheTimeout</CODE> - additional sockets
created during heavy GK load time periods for serving incoming
requests are closed during idle periods.</P>
</LI>
<LI><CODE>RequestRetransmissions=NUMBER</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>How many times a single RADIUS request is transmitted to every
configured RADIUS server (if no response is received). 1 means
no retransmission, 2 - single retransmission, ... . Exact retransmission
method is defined by <CODE>RoundRobinServers</CODE> attribute.</P>
</LI>
<LI><CODE>RoundRobinServers=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>RADIUS requests retransmission method.</P>
<P>If set to 1, RADIUS request
is transmitted in the following way (until response is received):
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>If set to 0, the following sequence is preserved:
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>AppendCiscoAttributes=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>If set, Cisco Vendor Specific RADIUS attributes are included
in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).</P>
</LI>
<LI><CODE>IncludeTerminalAliases=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>If set, Cisco VSA 'h323-ivr-out' attribute is sent with a list of aliases
the endpoint is registering (RRQ.m_terminalAlias). This attribute is provided
in order to provide fine control over the list of aliases the endpoint
is allowed to register with. Format of this attribute is:
<BLOCKQUOTE><CODE>
<PRE>
Cisco-AV-Pair = "h323-ivr-out=terminal-alias:" alias [,alias] [;]
Example:
Cisco-AV-Pair = "h323-ivr-out=terminal-alias:helpdesk,support,77771;"
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>UseDialedNumber=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Select Called-Station-Id number type between the original one (as dialed
by the user) - <CODE>UseDialedNumber=1</CODE> - and the rewritten one - <CODE>UseDialedNumber=0</CODE>.</P>
</LI>
</UL>
</P>
<H2><A NAME="radaliasauth"></A> <A NAME="ss8.10">8.10</A> <A HREF="manual.html#toc8.10">Section [RadAliasAuth]</A>
</H2>
<P>This section defines configuration settings that enable
RADIUS authentication based on endpoint aliases and/or IP addresses
present in RRQ RAS requests, ARQ RAS request or Q.931 Setup request.
This authentication scheme is useful both for endpoints registered
at the gatekeeper (ARQ,RRQ) and calls from unregistered endpoints (Setup).</P>
<P>
<UL>
<LI><CODE>Servers=SERVER1[:AUTH_PORT[:ACCT_PORT[:SECRET]]];SERVER2[:AUTH_PORT[:ACCT_PORT[:SECRET]]];...</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>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 given order. If no port information is specified, port number from
<CODE>DefaultAuthPort</CODE> will be used. If no secret is set,
the default shared secret from <CODE>SharedSecret</CODE> is used.
Servers can be IP addresses or DNS names.</P>
<P>
<DL>
<DT><B>Example:</B><DD><P><CODE>Servers=192.168.3.1:1645;192.168.3.2:1812:1813:mysecret;radius.mycompany.com</CODE></P>
</DL>
</P>
</LI>
<LI><CODE>LocalInterface=IP_OR_FQDN</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>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.</P>
</LI>
<LI><CODE>RadiusPortRange=10000-11000</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>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.</P>
</LI>
<LI><CODE>DefaultAuthPort=PORT_NO</CODE><BR>
Default: <CODE>1812</CODE><BR>
<P>Default port number to be used for RADIUS authentication requests
(Access-Request packets), if not overridden by <CODE>Servers</CODE> attribute.</P>
</LI>
<LI><CODE>SharedSecret=SECRET</CODE><BR>
Default: <CODE>N/A (empty string)</CODE><BR>
<P>Secret used to authenticate this GnuGk (NAS client) to RADIUS
server. It should be a cryptographically strong password. This is the default
value used, if no server-specific secret is set in the <CODE>Servers</CODE>.
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>RequestTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>2000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) for RADIUS server response to a request
sent by GnuGk. If no response is received within this time period,
next RADIUS server is queried.</P>
</LI>
<LI><CODE>IdCacheTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>9000</CODE> (milliseconds)<BR>
<P>Timeout (milliseconds) 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 approximately 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 exhausted - 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.</P>
</LI>
<LI><CODE>SocketDeleteTimeout=TIMEOUT_MS</CODE><BR>
Default: <CODE>60000</CODE> (milliseconds) - 60 s<BR>
<P>Timeout for unused RADIUS sockets to be closed. It is used
in conjunction with <CODE>IdCacheTimeout</CODE> - additional sockets
created during heavy GK load time periods for serving incoming
requests are closed during idle periods.</P>
</LI>
<LI><CODE>RequestRetransmissions=NUMBER</CODE><BR>
Default: <CODE>2</CODE><BR>
<P>How many times a single RADIUS request is transmitted to every
configured RADIUS server (if no response is received). 1 means
no retransmission, 2 - single retransmission, ... . Exact retransmission
method is defined by <CODE>RoundRobinServers</CODE> attribute.</P>
</LI>
<LI><CODE>RoundRobinServers=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>RADIUS requests retransmission method.</P>
<P>If set to 1, RADIUS request
is transmitted in the following way (until response is received):
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>If set to 0, the following sequence is preserved:
<BLOCKQUOTE><CODE>
<PRE>
Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>AppendCiscoAttributes=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>If set, Cisco Vendor Specific RADIUS attributes are included
in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).</P>
</LI>
<LI><CODE>IncludeTerminalAliases=BOOLEAN</CODE><BR>
Default: <CODE>1</CODE><BR>
<P>If set, Cisco VSA 'h323-ivr-out' attribute is sent with a list of aliases
the endpoint is registering (RRQ.m_terminalAlias). This attribute is provided
in order to provide fine control over the list of aliases the endpoint
is allowed to register with. Format of this attribute is:
<BLOCKQUOTE><CODE>
<PRE>
Cisco-AV-Pair = "h323-ivr-out=terminal-alias:" alias [,alias] [;]
Example:
Cisco-AV-Pair = "h323-ivr-out=terminal-alias:helpdesk,support,77771;"
</PRE>
</CODE></BLOCKQUOTE>
</P>
</LI>
<LI><CODE>FixedUsername</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>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 <CODE>FixedUsername</CODE>.</P>
</LI>
<LI><CODE>FixedPassword</CODE><BR>
Default: <CODE>N/A</CODE><BR>
<P>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 behavior and User-Password attribute will be
always set to the value of <CODE>FixedPassword</CODE>.
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>
<DL>
<DT><B>Example 1:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
(Neither FixedUsername nor FixedPassword set)
</PRE>
</CODE></BLOCKQUOTE>
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'.</P>
</DL>
</P>
<P>
<DL>
<DT><B>Example 2:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
(FixedUsername not set)
FixedPassword=ppp
</PRE>
</CODE></BLOCKQUOTE>
All endpoints will be authenticated using their alias and the password 'ppp'.</P>
</DL>
</P>
<P>
<DL>
<DT><B>Example 3:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
FixedUsername=ppp
FixedPassword=ppp
</PRE>
</CODE></BLOCKQUOTE>
All endpoints will be authenticated using the username 'ppp'
and the password 'ppp'.</P>
</DL>
</P>
</LI>
<LI><CODE>UseDialedNumber=BOOLEAN</CODE><BR>
Default: <CODE>0</CODE><BR>
<P>Select Called-Station-Id number type between the original one (as dialed
by the user) - <CODE>UseDialedNumber=1</CODE> - and the rewritten one - <CODE>UseDialedNumber=0</CODE>.</P>
</LI>
</UL>
</P>
<H2><A NAME="capctrl"></A> <A NAME="ss8.11">8.11</A> <A HREF="manual.html#toc8.11">Section [CapacityControl]</A>
</H2>
<P>This section contains a set of rules for controlling inbound call volume
depending on various conditions. In order this module to work, CapacityControl
authentication and accounting modules have to be enabled like this:
<BLOCKQUOTE><CODE>
<PRE>
[Gatekeeper::Auth]
CapacityControl=required;Setup
[Gatekeeper::Acct]
CapacityControl=required;start,stop
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>A capacity rule can be matched by a caller's IP, caller's H.323 ID and/or
caller's number (CLI) - in the order specified. In addition, the match can
be narrowed by specifying a called number pattern. This module works by keeping
lists of current call volume for each inbound route (rule) - this is done
by having <CODE>CapacityControl</CODE> accounting module configured to add/remove
active calls from matching routes. <CODE>CapacityControl</CODE> authentication module
checks rules and accepts/rejects a call based on current/max call volume
for a matching inbound route.</P>
<P>
<DL>
<DT><B>Format for an inbound route rule:</B><DD><P><CODE>[ip:CALLER_IP|h323id:CALLER_H323ID|cli:CALLER_NUMBER]=[CALLED NUMBER REGEX PATTERN] MAX_CAPACITY</CODE></P>
<P><CODE>ip:</CODE>, <CODE>h323id:</CODE> and <CODE>cli:</CODE> prefixes define rule type. An inbound call
will be matched either by caller's IP, H.323ID or CLI. The optional <CODE>CALLED NUMBER REGEX PATTERN</CODE>
is a regular expression that the called number should match to apply this rule to.
<CODE>MAX_CAPACITY</CODE> is maximum number of active calls for this route.</P>
<DT><B>Example 1:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[CapacityControl]
ip:192.168.1.0/24=30
ip:any=120
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>These rules tell that the 192.168.1.0/24 subnet can send up to 30 concurrent
calls, while all other IPs can send up to 120 concurrent calls.</P>
<DT><B>Example 2:</B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
[CapacityControl]
%r1% cli:1001=30
%r2% cli:1001=^48(50|51) 5
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>These rules limit caller with CLI 1001 to send up to 5 calls to 4850/4851
destinations and up to 30 calls to other destinations. %r1% and %r2% are
special constructs to allow having the same <CODE>cli:1001</CODE> config key more
than once.</P>
</DL>
</P>
<HR>
<A HREF="manual-9.html">Next</A>
<A HREF="manual-7.html">Previous</A>
<A HREF="manual.html#toc8">Contents</A>
</BODY>
</HTML>
