This is the manual for GNU Gatekeeper 5.13.
A manual for your version is in your GnuGk download archive.
A PDF version can be found in the download section.

Chapters: Contents · Introduction · Installation · Getting started · Basic Config · Routed Mode & Proxy · Routing · RAS Config · Authentication · Accounting · Neighbors · Per Endpoint Config · Advanced Config · Monitoring · Advanced Topics

Download GnuGk    Get support

The GNU Gatekeeper Manual Chapter 8

8. Authentication Configuration

The following sections in the config file can be used to configure authentication.

8.1 Section [Gatekeeper::Auth]

The section defines the authentication mechanism / modules for the GNU Gatekeeper. After defining which modules to use, you have to add the corresponding config sections for each module.

Syntax:

authrule=actions

 <authrule> := SimplePasswordAuth | AliasAuth | FileIPAuth | PrefixAuth | RadAuth | RadAliasAuth | SQLAuth | SQLAliasAuth | SQLPasswordAuth | H350PasswordAuth | LDAPPasswordAuth | LDAPAliasAuth | LuaAuth | LuaPasswordAuth | HttpPasswordAuth | GeoIPAUth | TwoAliasAuth | CapacityControl | ...
 <actions>  := <control>[;<ras>|<q931>,<ras>|<q931>,...]
 <control>  := optional | required | sufficient | alternative
 <ras>      := GRQ | RRQ | URQ | ARQ | BRQ | DRQ | LRQ | IRQ | RAI
 <q931>     := Setup | SetupUnreg | Connect | CallProceeding | Alerting | Information | ReleaseComplete | Facility | Progress | Empty | Status | StatusEnquiry | SetupAck | Notify

A rule may result in one of three codes: ok, fail, next.

  • ok - The request is authenticated by this module.
  • fail - The authentication fails and should be rejected.
  • next - The rule cannot determine the request.
There are also three ways to control a rule:
  • optional - If the rule cannot determine the request or accepts it, it is passed to next rule. Otherwise processing stops and the request is rejected.
  • required - The requests should be authenticated by this module, or it would be rejected. The authenticated request would then be passed 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.
  • alternative - similar to the sufficient rule, except that if the module cannot determine the result the request is passed to a next module.

Currently supported modules: (most only support a subset of the RAS or Q.931 actions)

  • SimplePasswordAuth/SQLPasswordAuth/H350PasswordAuth/LuaPasswordAuth/HttpPasswordAuth

    These modules check the tokens or cryptoTokens fields of a 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 are supported. For tokens hashed by CAT (Cisco Access Token) a clear text username/password are supported. The ID and password are read from the [SimplePasswordAuth] section, or a SQL database for SimplePasswordAuth and SQLPasswordAuth modules. With LuaPasswordAuth you can use a Lua script to lookup the passwords and HttpPasswordAuth lets you fetch passowrds from an HTTP server (eg. from a REST service).

    For H.350.2 authentication (H350PasswordAuth) the [GkH350::Settings] connection information must be completed. The [H350PasswordAuth] section is optional.

  • AliasAuth/SQLAliasAuth

    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 the [RasSrv::RRQAuth] section. For SQLAliasAuth, the pattern is retrieved from a SQL database as defined in the [SQLAliasAuth] section.

  • FileIPAuth

    This module provides a simple way to restrict access to the gatekeeper based on caller's IP or network.

  • PrefixAuth

    The IP or aliases of a request with a given prefix must match a specified pattern. See section [PrefixAuth] for details. The module can authorize AdmissionRequest (ARQ), LocationRequest (LRQ), Setup and SetupUnreg.

  • RadAuth

    Provides authentication based on H.235 username/password security scheme. Authenticates RRQ, ARQ and Q.931 Setup through remote RADIUS servers. It sends usernames and passwords extracted from CAT (Cisco Access Tokens) tokens carried inside RRQ, ARQ or Setup packets to the RADIUS servers. If your endpoints do not support CATs or you do not need an authentication scheme based on individually assigned usernames/password then this module would not be appropriate (but you may check the RadAliasAuth module). See section [RadAuth] for details.

  • RadAliasAuth

    Provides authentication based on endpoint aliases and/or call signaling 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, ARQ and Q.931 Setup messages can be authenticated using this module. See section [RadAliasAuth] for details.

  • SQLAuth

    A powerful module to authenticate and authorize RRQ, ARQ, LRQ and Setup messages. It can perform checks based on various parameters such as 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 [SQLAuth] for more details.

  • LDAPPasswordAuth

    This module will lookup the called aliases in your LDAP schema searching the H323ID and telephoneNumber attribute and checks if the password in the H235Password attribute matches the H.235 crypto token.

    The LDAP server is configured in the GkLDAP::Settings section and the attribute matching is defined in the GkLDAP::LDAPAttributeNames section.

  • LDAPAliasAuth

    This module will lookup the called aliases in your LDAP schema searching the H323ID and telephoneNumber attribute and checks if the IP matches the IPAddress attribute.

    The LDAP server is configured in the GkLDAP::Settings section and the attribute matching is defined in the GkLDAP::LDAPAttributeNames section.

  • LuaAuth

    This module utilizes user-defined LUA scripts to perform authentication. The scripts are configured in the LuaAuth section.

  • GeoIPAuth

    This module checks the which country the message comes from by looking at the IP. The module is configured in the GeoIPAuth section.

  • TwoAliasAuth

    This module checks if the endpoint has 2 matching aliases. This is a very weak authentication, only to be used when nothing else is possible. The module is configured in the TwoAliasAuth section.

    The module can authorize RegistrationRequest (RRQ), Setup and SetupUnreg.

  • CapacityControl

    A flexible module to control inbound call volume with the ability to configure various conditions. IMPORTANT: It must be used in conjunction with the CapacityControl accounting module. See section [CapacityControl] for more details.

You can also configure a rule to check only for specific RAS messages. The following example configures SimplePasswordAuth as an optional rule to check RRQ and ARQ. If a RRQ is not checked (does not contain tokens or cryptoTokens fields), it is checked by AliasAuth. The default is to check all supported requests.

Example 1:

SimplePasswordAuth=alternative;RRQ,ARQ
AliasAuth=sufficient;RRQ

The example below authenticates all calls, checking signaling Setup message details, using the RadAliasAuth module.

Example 2:

RadAliasAuth=required;Setup
default=allow

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).

Example 3:

RadAuth=alternative;RRQ,ARQ
RadAliasAuth=alternative;RRQ,ARQ,SetupUnreg
default=reject

8.2 Section [FileIPAuth]

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: GRQ, RRQ, ARQ, LRQ, Setup and SetupUnreg. Format of a single entry is:

IP=[allow | reject | onlyTLS][;prefix[,prefix...]]

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 IPv6 format) or a string 'any' or '*' to match any address. The access list can also be loaded from an external file using include 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.

'onlyTLS' is equivalent to 'allow' if the call comes in via a TLS secured connection and means 'reject' for unencrypted calls.

In addition the to endpoint's IP, you can specify a list of prefixes that the endpoint may call. The destination prefixes are only checked on ARQ and Setup messages.

Example #1:

[Gatekeeper::Auth]
FileIPAuth=required;RRQ,ARQ,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
2a01:4f8:61:2243::2=allow
2a01:4f8:61:2243::10/128=allow
2a01:4f8:61:2243::/64=allow
any=reject

Example #2:

Placing the list of IP rules into another file.

[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

Example #3:

Allow all connects from the local network, but require TLS encryption and authentication for everything else.

[Gatekeeper::Auth]
FileIPAuth=required;Setup

[FileIPAuth]
192.168.1.0/24=allow
any=onlyTLS

8.3 Section [H235]

This section contains setting that apply to all authentication policies using H.235.1 passwords.

When using H.235 authentication, it is very important that the gatekeeper and all endpoints have the correct time configured (eg. using NTP). If they vary by more than the defined grace period (see below), otherwise valid tokens will be rejected!

  • UseEndpointIdentifier=0
    Default: 1

    Use the endpoint identifier as RemoteID. When calling Innovaphone r6 endpoints, this must be off. With Innovaphone r11 it may be on.

  • RequireGeneralID=1
    Default: 0

    The H.235v3 spec requires endpoints to send a GeneralID inside H.235.1 tokens. Some endpoint vendors don't include the GeneralID, eg. AudioCodes and Innovaphone.

  • FullQ931Checking=1
    Default: 0

    The H.235v3 spec mandates all Q,931 signaling messages (Setup, Alerting, Connect etc.) be secured with H.235.1 tokens. This is very good practice, but not all vendors implement it. (AudioCodes and Innovaphone do.)

  • CheckSendersID=0
    Default: 1

    Check if the SendersID inside tokens matches their alias or endpointID. This switch replaces the CheckID= switch in the [...PasswordAuth] sections.

  • VerifyRandomNumber=0
    Default: 1

    Disable the check if the endpoint sends the same random number multiple times for the same timestamp. Innovaphone r6 - r11 sometimes sends 32bit random numbers with the high bit set that are all decoded into -1 by H323Plus causing the check to fail. This might be a bug in the PTLib ASN decoder.

  • TimestampGracePeriod=60
    Default: 7210

    Acceptable difference in timestamps inside H.235.1 tokens between endpoint and gatekeeper in seconds.

    The default is 2 hours and 10 seconds to accommodate endpoints with bad clock settings and in different time zones.

    It is suggested that you use NTP to synchronize clocks in all your devices and tighten this grace period accordingly.

Example #1

A very relaxed H.235 configuration, allowing many variations in vendor implementations.

[H235]
UseEndpointIdentifier=0
RequireGeneralID=0
FullQ931Checking=0
CheckSendersID=0
VerifyRandomNumber=0
TimestampGracePeriod=7210

Example #2

A very secure H.235 configuration, checking all aspects as defined by the ITU.

[H235]
UseEndpointIdentifier=1
RequireGeneralID=1
FullQ931Checking=1
CheckSendersID=1
VerifyRandomNumber=1
TimestampGracePeriod=60

8.4 Section [SimplePasswordAuth]

This section defines the userid and password pairs used by SimplePasswordAuth module. All passwords are encrypted using the addpasswd utility.

Usage: 

addpasswd config section userid password

Example: 

addpasswd config.ini SimplePasswordAuth frank secret

Options:

  • KeyFilled=123
    Default: 0

    Default value to use as a padding byte during password encryption/decryption.

  • CheckID=1
    Default: 0

    DEPRECATED: Please use the CheckSendersID= switch in the [H235] section.

    Check if the aliases match the ID in the tokens. Some endpoints use separate names for their alias and for authentication. If all your endpoints use their alias as ID in the tokens, you can tighten security by checking it.

    This switch applies to the RAS tokens of all password authenticators.

  • PasswordTimeout=120
    Default: -1

    The module SimplePasswordAuth will cache an authenticated password. This field defines the cache timeout value in seconds. 0 means never cache the password, while a negative value means the cache never expires.

  • DisableAlgorithm=MD5,H.235.1,CAT
    Default: N/A

    Disable H.235 authentication algorithms in the GRQ/GCF negotiation, otherwise all algorithms supported by GnuGk are used. A disabled algorithm will still be used if it is used by an endpoint without negotiation. This switch can be used to avoid incompatibilities with vendor implementations.

8.5 Section [SQLPasswordAuth]

Authenticate H.235 enabled endpoints using passwords stored in a SQL database. This section defines the SQL driver to use, SQL database connection parameters and the query to use to retrieve passwords.

Use the common database configuration options to define your database connection for this module.

  • CacheTimeout=120
    Default: 0

    This field defines how long (alias;password) pairs retrieved from the database will be cached. The cache timeout value is expressed in seconds. 0 means to not cache passwords, while a negative value means the cache never expires (only reload command will refresh the cache).

  • Query=SELECT ...
    Default: N/A

    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 %1, %2, ... strings. Specify %% to embed a percent character before a digit into string (like %%1), specify %{1} to allow expansion inside complex expressions like %{1}123. For SQLPasswordAuth two parameters are defined:

    • %1 - the actual alias to query the password for
    • %2 - the gatekeeper identifier

    Sample query strings: 

    SELECT h235password FROM users WHERE alias = '%1' AND active
SELECT h235password FROM users WHERE alias = '%1' AND gk = '%2'

8.6 Section [H350PasswordAuth]

  • PasswordTimeout=120
    Default: -1

    The module SimplePasswordAuth will cache an authenticated password. This field defines the cache timeout value in seconds. 0 means never cache the password, while a negative value means the cache never expires.

8.7 Section [RasSrv::RRQAuth]

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. If an endpoint is using H.460.18, the port in the authentication rule will be ignored.

Syntax:

<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 against 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 signaling IP address. If the port is omitted, 1720 is assumed.

    Examples: 

    sigip:192.168.242.165:1720
sigip:[2a01:4f8:61:2243::2]:1720
sigip:2a01:4f8:61:2243::2

  • allow - always accept the alias.
  • deny - always reject the alias.

Example: 

[RasSrv::RRQAuth]
; The endpoint with alias 'cwhuang' must register from 10.0.1.10:1720
cwhuang=sigip:10.0.1.10:1720
; The endpoint with alias 'gw1' must register from 10.0.1.0/24
gw1=sigaddr:.*ipAddress .* ip = .* 0a 00 01 .*port = 1720.*
; The endpoint with alias 'gw2' must register from [2a01:4f8:61:2243::2]:1720
gw2=sigip:[2a01:4f8:61:2243::2]:1720

8.8 Section [SQLAliasAuth]

Authenticate endpoints using rules stored in the SQL database (the rules conform to the format defined in the [RasSrv::RRQAuth] section). This section defines which SQL driver to use, SQL database connection parameters and the query to use to retrieve the patterns.

Use the common database configuration options to define your database connection for this module.

  • CacheTimeout=120
    Default: 0

    This field defines how long (alias;authrule) pairs retrieved from the database will be cached. The cache timeout value is expressed in seconds. 0 means not to cache rules, while a negative value means the cache never expires (only reload command will refresh the cache).

  • Query=SELECT ...
    Default: N/A

    Defines the 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 %1, %2, ... strings. Specify %% to embed a percent character before a digit into string (like %%1), specify %{1} to allow expansion inside complex expressions like %{1}123. For SQLAliasAuth two parameters are defined:

    • %1 - the actual alias to query the rule for
    • %2 - the gatekeeper identifier

    Sample query strings: 

    SELECT authrule FROM users WHERE alias = '%1' AND active
SELECT 'sigip:' || host(ip) || port FROM users WHERE alias = '%1'

8.9 Section [SQLAuth]

Authenticate and authorize endpoints/calls using a SQL database. Support for RRQ, ARQ, LRQ and Setup events is provided.

Use the common database configuration options to define your database connection for this module.

  • RegQuery=SELECT ...
    Default: N/A

    Defines the 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:

    • %g - the gatekeeper identifier
    • %{gkip} - a gatekeeper IP the request has been received on
    • %u - username associated with the endpoint (usually a H.323 ID)
    • %{Calling-Station-Id} - E.164 associated with the endpoint
    • %{callerip} - caller's/registrant's IP (where the registration request has been received from - NAT IP for NATed endpoints)
    • %{aliases} - a comma separated list of endpoint aliases
    • %{additive-rrq} - whether it is an additive rrq (0 = false, 1 = true)
    • %{Vendor} - productId and versionId

    If the query returns no rows, the result is undefined, which basically means failure for required rules and "try next" for optional rules. Otherwise, the first result row is examined to determine the result of the authentication request and to get additional information:

    1. The first column is converted into a boolean value (1, T, TRUE, allow, y, yes means true) and is an authentication result (accept/reject).
    2. If the registration is successfully authenticated the remaining columns are examined:
      1. If there exists a column called 'aliases', replace original endpoint aliases with these new ones
      2. If there exists a column called 'billingmode', set a billing mode associated with the endpoint (0 - credit, <>0 - debit)
      3. If there exists a column called 'creditamount', set account balance associated with the endpoint (this is an arbitrary string)

    Query string examples: 

    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)

  • NbQuery=SELECT ...
    Default: N/A

    Defines the 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:

    • %g - the gatekeeper identifier
    • %{gkip} - a gatekeeper IP the request has been received on
    • %{nbid - neighbor identifier from the config
    • %{nbip} - neighbor IP (where the request has been received from)
    • %{Calling-Station-Id} - caller's number, if available
    • %{src-info} - content of sourceInfo LRQ field, if available
    • %{Called-Station-Id} - destination number
    • %{dest-info} - content of destinationInfo LRQ field
    • %{bandwidth} - requested bandwidth, if present in the LRQ

    If the query returns no rows, the result is undefined, which basically means failure for required rules and "try next" for optional rules. Otherwise, the first result row is examined to determine the result of the authentication and to get additional information:

    1. The first column is converted into a boolean value (1, T, TRUE, allow, y, yes means true) and is an authentication result (accept/reject).
    2. If the request is authenticated successfully, remaining columns are examined:
      1. If there exists a column called 'destination', populate the original destinationInfo field with these new aliases - this may affect routing decision, which is made after auth step.

    Query string examples: 

    SELECT active FROM neighbors WHERE name = '%{nbid}' AND ip = '%{nbip}' UNION SELECT 0

  • CallQuery=SELECT ...
    Default: N/A

    Define a 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:

    • %g - the gatekeeper identifier
    • %{gkip} - a gatekeeper IP the request has been received on
    • %u - a username associated with the caller
    • %{callerip} - caller's IP (where the request has been received from - NAT IP for NATed endpoints)
    • %{Calling-Station-Id} - caller's number, if available
    • %{Called-Station-Id} - destination number
    • %{Dialed-Number} - original destination number (before rewrite)
    • %{CallId} - H.323 call identifier (16 hex 8-bit digits)
    • %{SrcInfo} - srcInfo field of the ARQ or sourceAddress from Setup
    • %{Vendor} - productId and versionId
    • %{bandwidth} - requested bandwidth, if present in the ARQ
    • %{answer} - 1, if the request is an answering ARQ
    • %{arq} - 1 for ARQ triggered query, 0 for Setup triggered query
    • %{from-registered} - 1 calls from registered endpoints, 0 for other calls
    • %{from-neighbor} - 1 calls from neighbor gatekeeper, 0 for other calls

    If the query returns no rows, the result is undefined, which basically means failure for required rules and "try next" for optional rules. Otherwise, the first result row is examined to determine the authentication result and to get additional information:

    1. 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).
    2. If the request is authenticated successfully, remaining columns are examined:
      1. If there exists a column called 'billingmode', set a billing mode associated with the endpoint (0 - credit, <>0 - debit)
      2. If there exists a column called 'creditamount', set account balance associated with the endpoint (this is an arbitrary string)
      3. If there exists a column called 'credittime', use its integer value to set call duration limit
      4. If there exists a column called 'redirectnumber', replace the original destination number with this one. You can put multiple numbers (that correspond to multiple 'redirectip' entries) separated by a semicolon. You can also specify an outbound number (to be sent to a terminating gateway) by appending it with an '=' to the rewritten number (like 485811001001=1234485811001001)
      5. If there exists a column called 'redirectip', force the call to be sent to the specified IP (one can put multiple destinations separated by a semicolon, that will be used for failover, if failover is activated)
      6. If there exists a column called 'proxy', force the gatekeeper to enable/disable (depends on the 'proxy' column value) RTP proxy for this call
      7. If there exists a column called 'clientauthid', the gatekeeper will store this ID in its call record and send it back on all accounting events. This must be an unsigned integer with a maximum of 64 bits (eg. 'bigint unsigned' in MySQL).
    3. If the request is denied, the remaining columns are examined:
      1. If there exists a column called 'q931cause', set a Q.931 cause in a Release Complete to this value
      2. If there exists a column called 'clientauthid', the gatekeeper will store this ID in its call record and send it back on all accounting events. This must be an unsigned integer with a maximum of 64 bits (eg. 'bigint unsigned' in MySQL).

    Query string examples: 

    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

8.10 Section [PrefixAuth]

The section defines the authentication rule for the PrefixAuth module. You can authorized ARQs, LRQs and Setups with this module.

First, the 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 the 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 the next authentication module according to the module requirement.

Format:

prefix=authrule[|authrule|...]

Syntax:

<authrule> :=  <result> <authrule>

  <result>    := deny | allow
  <authrule>  := [!]ip:<iprule> | [!]ipv4:<iprule> | [!]ipv6:<iprule> | [!]alias:<aliasrule>

Where <iprule> can be specified in decimal dot notation or CIDR notation or IPv6 notation, <aliasrule> is expressed in regular expression. If the `!' flag precedes the rule, the sense is inverted. Rules for IP numbers with ip:, ipv4:, ipv6: all behave the same. The different prefixes are just for documentation and compatibility with older versions of GnuGk.

Example:

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.*
99=deny ipv6:2021:4ad0:ff00:99a::/64
ALL=allow ipv4:0/0|allow ipv6:::/0

In this configuration, all endpoints except those from network 10.0.0.0/27 are allowed 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. IPv6 endpoints from 2021:4ad0:ff00:99a::/64 are not allowed to call prefix 99. All other situations are allowed.

8.11 Section [RadAuth]

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.

  • Servers=SERVER1[:AUTH_PORT[:ACCT_PORT[:SECRET]]];SERVER2[:AUTH_PORT[:ACCT_PORT[:SECRET]]];...
    Default: N/A

    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 DefaultAuthPort will be used. If no secret is set, the default shared secret from SharedSecret is taken. Servers names can be IP addresses or DNS names. IPv6 addresses must always be written in brackets.

    Sample Servers lines:

    Servers=192.168.1.1
    Servers=192.168.1.1:1645
    Servers=192.168.1.1:1645:1646:secret1
    Servers=radius1.mycompany.com:1812
    Servers=radius1.mycompany.com;radius2.mycompany.com
    Servers=radius1.mycompany.com:1812:1813:secret1;radius2.mycompany.com:1812:1813:secret2
    Servers=[2501:4f3:61:2143::2]
    Servers=[2501:4f3:61:2143::2]:1645
    Servers=[2501:4f3:61:2143::2]:1645:1646
    Servers=[2501:4f3:61:2143::2]:1645:1646:secret1
    Servers=[2501:4f3:61:2143::2]:1645:1646:secret1;[2501:4f3:61:2143::3]:1645:1646:secret2

  • LocalInterface=IP_OR_FQDN
    Default: N/A

    The specific local network interface that GnuGk should use in order to communicate with RADIUS servers. This parameter can be useful on NAT machines to restrict which network interfaces are 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
    Default: N/A

    By default, GnuGk allocates ports dynamically as specified by the operating system. If you want to restrict which ports it should use then configure this parameter.

  • DefaultAuthPort=PORT_NO
    Default: 1812

    Default port number to be used for RADIUS authentication requests (Access-Request packets). Can be overridden by Servers attribute.

  • SharedSecret=SECRET
    Default: N/A (empty string)

    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 Servers configuration option. If EncryptAllPasswords is enabled, or a KeyFilled variable is defined in this section, the password is in encrypted form and should be created using the addpasswd utility.

  • RequestTimeout=TIMEOUT_MS
    Default: 2000 (milliseconds)

    Timeout (milliseconds) for RADIUS server response to a request sent by GnuGk. If no response is received within this time period, the next RADIUS server is queried.

  • IdCacheTimeout=TIMEOUT_MS
    Default: 9000 (milliseconds)

    Timeout (milliseconds) for RADIUS request 8-bit identifiers to be unique. If the entire 8-bit identifier range is exhausted within this period, a new client socket (UDP socket) will be allocated by the 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, if you have too long a timeout then too many resources will be consumed. If you have too short a timeout, then the RADIUS server may take incoming packets as duplicates and therefore drop them.

  • SocketDeleteTimeout=TIMEOUT_MS
    Default: 60000 (milliseconds) - 60 s

    Timeout for unused RADIUS sockets to be closed. It is used in conjunction with IdCacheTimeout - additional sockets created during heavy gatekeeper load periods for serving incoming requests are closed during idle periods.

  • RequestRetransmissions=NUMBER
    Default: 2

    How many times a single RADIUS request is transmitted to every configured RADIUS server (if no response is received). 1 means one transmission attempt and no re-transmission, 2 - single re-transmission, ... . Exact retransmission method is defined by RoundRobinServers attribute.

  • RoundRobinServers=BOOLEAN
    Default: 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
    Default: 0

    If set, Cisco Vendor Specific RADIUS attributes are included in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).

  • IncludeTerminalAliases=BOOLEAN
    Default: 1

    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: 

            Cisco-AV-Pair = "h323-ivr-out=terminal-alias:" alias [,alias] [;]
Example:
        Cisco-AV-Pair = "h323-ivr-out=terminal-alias:helpdesk,support,77771;"

  • UseDialedNumber=BOOLEAN
    Default: 0

    Select Called-Station-Id number type between the original one (as dialed by the user) - UseDialedNumber=1 - and the rewritten one - UseDialedNumber=0.

[RadAuth] Access-Request Radius Attributes

For RRQs, the following RADIUS attributes are included within Access-Request packets:

  • User-Name

    H225_RegistrationRequest.tokens[CAT].m_generalID

  • CHAP-Password

    H225_RegistrationRequest.tokens[CAT].m_random + H225_RegistrationRequest.tokens[CAT].m_challenge

  • CHAP-Challenge

    H225_RegistrationRequest.tokens[CAT].m_timeStamp

  • NAS-IP-Address

    GnuGk Home or a particular local network interface set by 'LocalInterface' config parameter

  • NAS-Identifier

    GnuGk Name

  • NAS-Port-Type

    Virtual (GnuGk does not have concept of physical ports)

  • Framed-IP-Address

    An IP address of registering endpoint signaling channel

  • Service-Type

    Login-User

  • (optional) VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-out

    A list of aliases an endpoint is registering with (only if IncludeTerminalAliases config option is set)

    NOTE: The list of aliases inside h323-ivr-out is in the following form:
    h323-ivr-out="h323-ivr-out=terminal-alias:alias1,alias2,...,aliasN;"
    The h323-ivr-out attribute can be (in future) instantiated multiple times inside a single Access-Request and may also contain variables other than "terminal-alias", so a RADIUS server should be flexible enough with processing of this attribute.

For ARQ and Setup messages, the following RADIUS attributes are included inside Access-Request packets:

  • User-Name

    ARQ.tokens[CAT].m_generalID

  • CHAP-Password

    ARQ.tokens[CAT].m_random + ARQ.tokens[CAT].m_challenge

  • CHAP-Challenge

    ARQ.tokens[CAT].m_timeStamp

  • NAS-IP-Address

    GnuGk Home or a particular local network interface set by 'LocalInterface' config parameter

  • NAS-Identifier

    GnuGk Name

  • NAS-Port-Type

    Virtual (GnuGk does not have concept of physical ports)

  • Framed-IP-Address

    An IP address of registering endpoint signaling channel

  • Service-Type

    Login-User (for ARQs from originating endpoint) or Call-Check (for ARQs from answering endpoint)

  • Calling-Station-Id

    Calling party's number (if available)

  • Called-Station-Id

    Called party's number

  • (optional) VSA: VendorId=Cisco, h323-conf-id

    H.323 conference ID from ARQ

  • (optional) VSA: VendorId=Cisco, h323-call-type

    Call type (fixed value: "h323-call-type=VoIP")

  • (optional) VSA: VendorId=Cisco, h323-call-origin

    Call origin ("answer","originate")

  • (optional) VSA: VendorId=Cisco, h323-gw-id

    The same as NAS-Identifier

[RadAuth] Access-Accept Radius Attributes

For RRQs, the following RADIUS attributes are recognized inside Access-Accept packets:

  • VSA: VendorId=Cisco, h323-return-code

    If present and not 0, the request is rejected. This check is provided to allow interoperability with some poor billing systems, which send Access-Accept with non-zero h323-return-code to reject the call instead of Access-Reject. The attribute can be in the form h323-return-code="1" or h323-return-code="h323-return-code=1". Note that the return code is a string, not an integer.

  • VSA: VendorId=Cisco, h323-billing-model

    Billing mode for this account. Can be 0 (credit), 1 or 2 (debit). If an endpoint can understand H.225.0 CallCreditServiceControl messages, this information is used to build the message.

  • VSA: VendorId=Cisco, h323-credit-amount

    A string representing current user's account balance. If an endpoint can understand H.225.0 CallCreditServiceControl messages, this information is used to build the message.

  • VSA: VendorId=Cisco, Cisco-AVPair, h323-ivr-in

    If present, it is scanned for 'terminal-alias' variable that can contain a list of aliases that should be assigned to the endpoint being registered. All RRQ aliases that do not match this list are removed. The 'disable-codec' variable is also supported to disallow certain codecs for this call. The 'proxy' variable that can contain 'yes' or 'no' for enabling/disabling proxy mode for this call. The format of these attributes is:

    Cisco-AVPair = "h323-ivr-in=variable:value;[variable:value;]"

    where the "variable" can be "terminal-alias":

    Cisco-AVPair = "h323-ivr-in=terminal-alias:alias1[,alias2,...];"

    Example 1:

    RRQ {
        m_terminalAlias = { "myalias", "1234" }
}

if RADIUS server returns the following h323-ivr-in:

Access-Accept {
        Cisco-AVPair = "h323-ivr-in=terminal-alias:anotheralias,6789;"
}

the endpoint will get registered with aliases "anotheralias" and "6789".
Also RCF will contain:

RCF {
        m_terminalAlias = { "anotheralias", "6789" }
}

    Example 2 (add E164 to an existing alias):

    RRQ {
        m_terminalAlias = { "it_s_me" }
}

if RADIUS server returns the following h323-ivr-in:

Access-Accept {
        Cisco-AVPair = "h323-ivr-in=terminal-alias:it_s_me,48586259732;"
}

RCF will contain:

RCF {
        m_terminalAlias = { "it_s_me", "48586259732" }
}

    Example 3 (disable G.711 and G.729 codecs):

    Access-Accept {
        Cisco-AVPair = "h323-ivr-in=codec-disable:g711Ulaw64k;g729;g711Alaw64k;g729AnnexA;"
}

    Example 4 (enable proxy mode):

    Access-Accept {
        Cisco-AVPair = "h323-ivr-in=proxy:yes"
}

For ARQs, the following RADIUS attributes are recognized within Access-Accept packets:

  • VSA: VendorId=Cisco, h323-return-code

    If present and not 0, the request is rejected. This check is provided to allow interoperability with some poor billing systems, that send Access-Accept with non-zero h323-return-code to reject the call instead of Access-Reject. The attribute can be in form h323-return-code="1" or h323-return-code="h323-return-code=1". Note that the return code is a string, not an integer.

  • VSA: VendorId=Cisco, h323-billing-model

    Billing mode for this account. Can be 0 (credit), 1 or 2 (debit). If an endpoint can understand H.225.0 CallCreditServiceControl messages, this information is used to build the message.

  • VSA: VendorId=Cisco, h323-credit-amount

    A string representing current user account balance. If an endpoint can understand H.225.0 CallCreditServiceControl messages, this information is used to build the message.

  • VSA: VendorId=Cisco, h323-credit-time

    If present, it enforces maximum call duration (in seconds). The attribute can be in form of h323-credit-time="120" or h323-credit-time="h323-credit-time=120". Note that the return code is a string, not an integer.

  • Session-Timeout

    If present, it enforces maximum call duration (in seconds). This is a standard RADIUS attribute of integer type.

  • VSA: VendorId=Cisco, h323-redirect-ip-address

    If present, a call is sent to the IP address present in this attribute. You can put multiple destinations separated with a semicolon.

  • VSA: VendorId=Cisco, h323-redirect-number

    If present, a called station id is rewritten to this number. You can put multiple numbers separated by a semicolon. For each number you can also specify an outbound number (that is sent to a terminating gateway) by appending it with a '='.

NOTE: If both Session-Timeout and h323-credit-time are present, the smaller value is used.

NOTE: If multiple failover mechanisms are specified, eg. multiple numbers in h323-redirect-number and multiple IPs in h323-redirect-ip-address, there is no guarantee that the the first number is used for the first IP and the 2nd number for the 2nd IP. This will usually the case, but for example when a capacity limit disables one IP, the association will change.

8.12 Section [RadAliasAuth]

This section defines configuration settings that enable RADIUS authentication based on endpoint aliases and/or IP addresses present in a RRQ RAS, ARQ RAS 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).

  • Servers=SERVER1[:AUTH_PORT[:ACCT_PORT[:SECRET]]];SERVER2[:AUTH_PORT[:ACCT_PORT[:SECRET]]];...
    Default: 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 given order. If no port information is specified, the port number from DefaultAuthPort will be used. If no secret is set, the default shared secret from SharedSecret is used. Servers can be IP addresses or DNS names.

    Example:

    Servers=192.168.3.1:1645;192.168.3.2:1812:1813:mysecret;radius.mycompany.com

  • LocalInterface=IP_OR_FQDN
    Default: N/A

    Specific local network interface that GnuGk 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
    Default: 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
    Default: 1812

    Default port number to be used for RADIUS authentication requests (Access-Request packets), if not overridden by Servers attribute.

  • SharedSecret=SECRET
    Default: N/A (empty string)

    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 Servers. If EncryptAllPasswords is enabled, or a KeyFilled variable is defined in this section, the password is in encrypted form and should be created using the addpasswd utility.

  • RequestTimeout=TIMEOUT_MS
    Default: 2000 (milliseconds)

    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.

  • IdCacheTimeout=TIMEOUT_MS
    Default: 9000 (milliseconds)

    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.

  • SocketDeleteTimeout=TIMEOUT_MS
    Default: 60000 (milliseconds) - 60 s

    Timeout for unused RADIUS sockets to be closed. It is used in conjunction with IdCacheTimeout - additional sockets created during heavy gatekeeper load periods for serving incoming requests are closed during idle periods.

  • RequestRetransmissions=NUMBER
    Default: 2

    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 RoundRobinServers attribute.

  • RoundRobinServers=BOOLEAN
    Default: 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
    Default: 1

    If set, Cisco Vendor Specific RADIUS attributes are included in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).

  • IncludeTerminalAliases=BOOLEAN
    Default: 1

    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: 

            Cisco-AV-Pair = "h323-ivr-out=terminal-alias:" alias [,alias] [;]
Example:
        Cisco-AV-Pair = "h323-ivr-out=terminal-alias:helpdesk,support,77771;"

  • EmptyUsername
    Default: N/A

    If this parameter is set, the value is used if the call doesn't provide a username for authentication.

  • FixedUsername
    Default: 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
    Default: 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 behavior and User-Password attribute will be always set to the value of FixedPassword. If EncryptAllPasswords is enabled, or a KeyFilled variable is defined in this section, the password is in encrypted form and should be created using the addpasswd utility.

    Example 1:

    (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'.

    Example 2:

    (FixedUsername not set)
FixedPassword=ppp
    All endpoints will be authenticated using their alias and the password 'ppp'.

    Example 3:

    FixedUsername=ppp
FixedPassword=ppp
    All endpoints will be authenticated using the username 'ppp' and the password 'ppp'.

  • UseDialedNumber=BOOLEAN
    Default: 0

    Select Called-Station-Id number type between the original one (as dialed by the user) - UseDialedNumber=1 - and the rewritten one - UseDialedNumber=0.

[RadAliasAuth] Access-Request Radius Attributes

For RRQs, the same attributes as with RadAuth are sent, with an exception of username/password attributes (CHAP-Password, CHAP-Challenge, User-Name):

  • User-Name

    Either an endpoint alias from RRQ or a value of FixedUsername config parameter. If no alias is present, an IP address is used

  • User-Password

    Either the same as User-Name or a value of FixedPassword config parameter

For ARQ and Setup messages, the same attributes as with RadAuth are sent, with an exception of username/password attributes (CHAP-Password, CHAP-Challenge, User-Name):

  • User-Name

    Either an endpoint alias or a value of FixedUsername config parameter

  • User-Password

    Either the same as User-Name or a value of FixedPassword config parameter

[RadAliasAuth] Access-Accept Radius Attributes

Exactly the same attributes are recognized as with RadAuth module.

8.13 Section [CapacityControl]

This section contains a set of rules for controlling inbound call volume depending on various conditions. In order for this module to work, CapacityControl authentication and accounting modules have to be enabled like this: 

[Gatekeeper::Auth]
CapacityControl=required;Setup
 
[Gatekeeper::Acct]
CapacityControl=required;start,stop

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 CapacityControl accounting module configured to add/remove active calls from matching routes. The CapacityControl authentication module checks rules and accepts/rejects a call based on current/max call volume for a matching inbound route.

Format for an inbound route rule:

[ip:CALLER_IP|h323id:CALLER_H323ID|cli:CALLER_NUMBER]=[CALLED NUMBER REGEX PATTERN] MAX_CAPACITY

ip:, h323id: and cli: prefixes define rule type. An inbound call will be matched either by caller's IP, H.323ID or CLI. The optional CALLED NUMBER REGEX PATTERN is a regular expression that the called number should match to apply this rule to. MAX_CAPACITY is maximum number of active calls for this route.

The rules are match in the following order:

  • IP rules
  • H.323ID rules
  • CLI rules

The longest match in the first matching category is used.

Example 1:

[CapacityControl]
ip:192.168.1.0/24=30
ip:any=120

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.

Example 2:

[CapacityControl]
%r1% cli:1001=30
%r2% cli:1001=^48(50|51) 5

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 cli:1001 config key more than once.

8.14 Section [GkH350::Settings]

This section defines the LDAP server and standard H.350 directory operating parameters to be used.

  • ServerName=127.0.0.1
    Default: 127.0.0.1

    The LDAP server IP address.

  • ServerPort=389
    Default: 389

    The LDAP server's TCP port (usually 389).

  • StartTLS=1
    Default: 0

    Use StartTLS to encrypt the LDAP connection.

  • SearchBaseDN=ou=commObjects,dc=gnugk,dc=org
    Default: N/A

    Entry point into the server's H.350 directory structure. Searches are only made below this root node.

  • BindUserDN=cn=admin,dc=gnugk,dc=org
    Default: N/A

    The distinguished name the gatekeeper uses to bind to the LDAP server. Leave empty if you want to access the LDAP server anonymously.

  • BindUserPW=secret
    Default: N/A

    If you specified BindUserDN, then specify the corresponding password to be used for binding here. If EncryptAllPasswords is enabled, or a KeyFilled variable is defined in this section, the password is in an encrypted form and should be created using the addpasswd utility.

  • BindAuthMode=simple
    Default: simple

    Bind Authentication method choices are simple,sasl,kerberos

  • ServiceControl=1
    Default: 0

    Use RRQ/RCF service control field to advise an endpoint of the H.350 directory and searchDN to use for white page lookups.

  • AssignedAliases=1
    Default: 0

    Use H.350.1 to advise endpoints of their assigned aliases.

  • GatekeeperDiscovery=1
    Default: 0

    Use H.350.1 to resolve on GRQ/GCF the registering endpoints assigned gatekeeper (h323IdentityGKDomain).

8.15 Section [GkLDAP::Settings]

This section defines the LDAP server and connection parameters for the LDAP authentication modules (LDAPAliasAuth and LDAPPasswordAuth) and the LDAP routing policy ('ldap').

  • ServerName=127.0.0.1
    Default: 127.0.0.1

    The LDAP server IP address.

  • ServerPort=389
    Default: 389

    The LDAP server's TCP port (usually 389).

  • StartTLS=1
    Default: 0

    Use StartTLS to encrypt the LDAP connection.

  • SearchBaseDN=ou=commObjects,dc=gnugk,dc=org
    Default: N/A

    Entry point into the server's directory structure. Searches are only made below this root node.

  • BindUserDN=cn=admin,dc=gnugk,dc=org
    Default: N/A

    The distinguished name the gatekeeper uses to bind to the LDAP server. Leave empty if you want to access the LDAP server anonymously.

  • BindUserPW=secret
    Default: N/A

    If you specified BindUserDN, then specify the corresponding password to be used for binding here. If EncryptAllPasswords is enabled, or a KeyFilled variable is defined in this section, the password is in an encrypted form and should be created using the addpasswd utility.

  • BindAuthMode=simple
    Default: simple

    Bind Authentication method choices are simple,sasl,kerberos

Example:

[GkLDAP::Settings]
ServerName=192.168.1.1
BindAuthMode=simple
SearchBaseDN=dc=gnugk,dc=org
BindUserDN=cn=admin,dc=gnugk,dc=org
BindUserPW=secret

8.16 Section [GkLDAP::LDAPAttributes]

With this section you can map the LDAP attributes GnuGk queries to your LDAP schema.

  • CallDestination=H323IP
    Default: voIPIpAddress

    The IP where calls for the LDAP entity should be routed.

  • H323ID=mail
    Default: mail

    The H.323 alias for the LDAP entity. This attribute is used to find the called entity in the LDAP schema.

  • H235PassWord=secret
    Default: none

    The password attribute to use in LDAPPasswordAuth.

  • IPAddress=voIPIpAddress
    Default: voIPIpAddress

    The H.323 IP for the LDAP entity. This attribute is used to find the called entity in the LDAP schema.

  • TelephoneNo=telephoneNumber
    Default: telephoneNumber

    The phone number for the LDAP entity. This attribute is used to find the called entity in the LDAP schema.

Example:

[GkLDAP::LDAPAttributeNames]
IPAddress=voIPIpAddress
H235PassWord=plaintextPassword
H323ID=sn
TelephonNo=telephoneNumber
CallDestination=roomNumber

8.17 Section [LuaAuth]

This section configures the scripts for LUA authentication.

For general information on LUA scripting in GnuGk, please see the chapter LUA Scripting.

  • RegistrationScript=script
    Default: N/A

    LUA script to be used for RRQs. Short scripts can be put directly into the config file. For longer scripts use RegistrationScriptFile=.

  • RegistrationScriptFile=/path/to/script
    Default: N/A

    LUA script to be used for RRQs.

  • CallScript=script
    Default: N/A

    LUA script to be used for ARQs and Setups. Short scripts can be put directly into the config file. For longer scripts use CallScriptFile=.

  • CallScriptFile=/path/to/script
    Default: N/A

    LUA script to be used for ARQs and Setups.

Registration authentication scripts can use the following variables

  • username - a username associated with the caller
  • callingStationId - caller's number, if available
  • callerIP - caller's IP (the request has been received from - NAT IP for NATed endpoints)
  • aliases - the list of aliases in the registration
  • vendor - productId and versionId
  • messageType - always "RRQ" for registrations
  • message - the full RRQ message as multi-line text block

Call authentication scripts can use the following variables

  • messageType - either "ARQ" or "Setup"
  • message - the full ARQ or Setup message as multi-line text block
  • source - signaling IP of the calling endpoint
  • calledAlias - the called alias
  • calledIP - the called IP
  • callingStationId - caller's number, if available
  • caller - srcInfo of calling endpoint from ARQ or callingStationId from Setup
  • callid - the call ID
  • srcInfo - srcInfo field of the ARQ or sourceAddress from Setup
  • vendor - productId and versionId

The scripts have to store the authentication result in the variable result. Possible values are "OK", "FAIL" and "NEXT"; everything else will be treated as "FAIL".

Example:

[LuaAuth]
; only let use "boss" register
RegistrationScript=if (username == "boss") then result = "OK" else result = "FAIL" end
; call authentication is in a script file
CallScriptFile=/path/to/callauth.lua

8.18 Section [LuaPasswordAuth]

This section configures the script for LUA password authentication.

For general information on LUA scripting in GnuGk, please see the chapter LUA Scripting.

  • Script=script
    Default: N/A

    LUA script to be used to lookup the password for a user. Short scripts can be put directly into the config file. For longer scripts use ScriptFile=.

  • ScriptFile=/path/to/script
    LUA script to be used to lookup the password for a user.
  • PasswordTimeout=120
    Default: -1

    This module will cache requested passwords. This field defines the cache timeout value in seconds. 0 means never cache the password, while a negative value means the cache never expires.

The script can use the following variables

  • alias - the alias of the user to be authenticated
  • gk - the name of the gatekeeper running

The script must store the password for the user in alias into the password variable for GnuGk to process further.

8.19 Section [HttpPasswordAuth]

This section defines fow to fetch password information from an HTTP server.

  • URL=http://example.com/passwords
    Default: N/A

    The URL to fetch the passwords from. You can use the parameters specified below to parameterize the URL. Currently GnuGk expects the cleartext password in the response.

  • Body=user=%u
    Default: empty

    The HTTP body to use with POST requests. You can use the parameters specified below to parameterize the URL.

  • Method=GET
    Default: POST

    HTTP method to use. Currently GET and POST are supported.

  • ContentType=application/json
    Default: text/plain

    The content type header to send in POST requests.

  • ResultRegex=[0-9]+
    Default: .*

    The regular expression to extract the password from the HTTP response.

  • DeleteRegex=5544
    Default: N/A

    A regular expression to use remove additional patterns from the extracted password. Optional.

  • ErrorRegex=error
    Default: ^$

    If the HTTP response matches this regular expression it is considered invalid.

  • PasswordTimeout=120
    Default: -1

    This module will cache requested passwords. This field defines the cache timeout value in seconds. 0 means never cache the password, while a negative value means the cache never expires.

For HttpPasswordAuth these parameters are defined:

  • %u - the actual alias to query the password for
  • %g - the gatekeeper identifier (name)
  • %{message} - message that caused this authentication process (eg. RRQ, ARQ etc.)
  • %{caller-ip} - IP of the calling party
  • %{called-ip} - IP of the interface GnuGk received this call on (only available for RAS messages)
  • %{caller-vendor} - product name and version of the caller (only available for RRQ and Setup)
  • %{caller-product-name} - product name of the caller (only available for RRQ and Setup)
  • %{caller-product-version} - product version of the caller (only available for RRQ and Setup)
  • %{env1} - content of environment variable GNUGK_ENV1
  • ...
  • %{env9} - content of environment variable GNUGK_ENV9

8.20 Section [GeoIPAuth]

This section configure the GeoIP authentication.

  • Database=/path/to/GeoIP.dat
    Default: N/A

    Path to the Maxmind GeoIP database. You can download the latest copy of the GeoIP database from https://dev.maxmind.com/geoip/legacy/geolite/

  • AllowedCountries=US,CA,PRIVATE
    Default: N/A

    Define which countries you want to accept messages from. The special country 'PRIVATE' denotes private IPs.

8.21 Section [TwoAliasAuth]

This section configure the TwoAlias authentication. It contains a list of aliases with a second ("secret") alias that needs to be present. Endpoints are accepted if they have a matching pair of aliases.

Please not that all this information is transmitted as clear text and can be easily intercepted by packet capturing. This is an extremly weak form of authentication.

Also note that the sourceAddress field in Setup messages is optional, and many endpoints do not send it when they are not registered witha gatekeeper and thus fail authentication even if they have matching aliases.

Example:

[TwoAliasAuth]
100=SecretA
101=MoreSecretB
102=WhateverSecretC

Next Previous Contents

Chapters: Contents · Introduction · Installation · Getting started · Basic Config · Routed Mode & Proxy · Routing · RAS Config · Authentication · Accounting · Neighbors · Per Endpoint Config · Advanced Config · Monitoring · Advanced Topics


Last updated: 21. Jan 2025