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 6

6. Routing Configuration

The following sections in the config file can be used to configure how calls are routed.

For GnuGk, "routing" means that the gatekeeper must find a destination IP for each new call.

For example GnuGk may need to decide where to send a voice call given a particular E.164 destination; there may be multiple IP-to-ISDN gateways which it may choose from for that E.164 address.

Routing decisions are typically made by examining the called name or number, but GnuGk has flexibility in what it evaluates in order to successfully route the call.

Each call gets passed down a chain of routing policies. Each policy may route the call and terminate the chain or modify it and pass it on. You can use the setting in the following sections to specify which policies to use and modify their behavior.

6.1 Section [RoutingPolicy]

This section explains how GNU Gatekeeper routing policies are configured.

An incoming call request can be routed using the following methods:

  • explicit

    The destination is explicitly specified in the call to be routed. This policy is needed for dialing by IP address. You can define mappings for the destination IP in the Routing::Explicit section.

  • internal

    The classic rule; search for the destination in RegistrationTable

  • parent

    Route the call using information sent by the parent gatekeeper in reply to an ARQ the gatekeeper will send (only LRQs to the child will be forwarded as LRQs). You can define your parent gatekeeper using the Endpoint section.

  • neighbor

    Route the call using neighbors by exchanging LRQ messages.

  • dns

    The destination is resolved using DNS A records or IP addresses in the called alias. This policy can be configured in the Routing::DNS section.

  • sql

    Route calls by rewriting the called alias with a database query or send them directly to a destination IP. The database parameters are specified in the Routing::Sql section.

  • http

    Route calls by rewriting the called alias with a HTTP query. The HTTP parameters are specified in the Routing::Http section.

  • ldap

    Route calls by looking up the called alias in an LDAP server (searching the H323ID and TelephoneNo attribute) and send the call to the IP in the CallDestination attribute.

    The LDAP server is configured in the GkLDAP::Settings section and the attributes are defined in the GkLDAP::LDAPAttributeNames section.

  • vqueue

    Use the virtual queue mechanism and generate a RouteRequest event to allow an external application to make a routing decision.

  • numberanalysis

    Provides support for overlapped digit sending for ARQ messages. This also partially supports Setup messages (no overlapped sending - only number length validation).

  • enum

    ENUM (RFC3761) is a method to use DNS lookups to convert real International Direct Dialing E.164 numbers into H.323 dialing information. The default server is e164.arpa. To specify your own list of servers use the ENUMservers switch in the RoutedMode section.

    The enum policy replaces the destination with the information returned by the ENUM server, so you must have the appropriate routing policies to continue processing the call after the enum policy. You should have the srv and dns policies after the enum policy, because the new location is often returned in the form of 'number@gatekeeper' and the srv and dns policies are needed to resolve this.

    Finally, keep in mind that each routing check with the enum policy requires a DNS lookup. To speed up your routing, make sure you resolve internal destinations before the enum policy is applied.

    This policy can be configured in the Routing::ENUM section.

    Additional ENUM schemas for gateways aside from the default "E2U+h323" may be supported via the "enum::id" Routing policy refer Routing::ENUM section.

  • srv

    DNS SRV or H.323 Annex O allows for the routing of calls using a H.323 URI. Addresses can be configured as user (at) domain. H.323 URIs are stored in the SRV DNS records of the domain and are queried to find the destination.

    This policy can be configured in the Routing::SRV section.

    Additional SRV schemas for gateways aside from the default "h323ls._udp." and "h323cs._tcp." may be supported via the "srv::id" Routing policy refer Routing::SRV section.

  • rds

    RDS Resolver Discovery Service or DDDS Dynamic Delegation Discovery Service (examples in RFC3404 sect 5.2/5.3) This policy is a mechanism whereby domain name SRV records are hosted in central DNS servers. The servers are set by [RoutedMode] RDSServers and are queried in order to resolve H323+D2U NAPTR records which contain H.323 Annex O SRV records for domains. This can be used to virtually host URL domains or centralize the control of SRV records.

    This policy can be configured in the Routing::RDS section.

  • forwarding

    This policy will perform a database lookup if calls to this destination should be forwarded. The configuration for this policy must be in the Routing::Forwarding section.

  • catchall

    This policy will route all calls that reach it to one endpoint specified in the Routing::CatchAll section. You can use it as a fallback at the end of the policy chain to route all calls which would otherwise fail.

  • lua

    This policy runs the LUA script defined in Routing::Lua section to set a call destination.

  • neighborsql

    Same as neighbor policy except the target for the LRQ messages are retrieved from a database. The database parameters are identical to the sql routing policy.

  • uriservice

    Apply a routing policy based on the URI schema eg xmpp:[email protected] or xmpp:192.168.1.1. The schemas is defined in Routing::URIService section. If schema is an IP address will return the [Routing::URIService] gateway setting. This can be used chained with [Routing::ENUM::schema] and [Routing::SRV::schema] to completely resolve addresses.

Default configuration for routing policies is:

[RoutingPolicy]
default=explicit,internal,parent,neighbor

If one policy does not match, the next policy is tried.

These policies can be applied to a number of routing request types and routing input data. The different types are ARQ, LRQ, Setup and Facility (with the callForwarded reason). There is also the general routing policy, which is a default for the other types.

Example:

[RoutingPolicy]
h323_ID=dns,internal
002=neighbor,internal
Default=internal,neighbor,parent

When a message is received which requires a routing decision, all calls to an alias of the h323_ID type will be resolved using DNS. If DNS fails to resolve the alias, it is matched against the internal registration table. If a call is requested to an alias starting with 002, the neighbors will be checked first, then the internal registration table. If the requested alias is not an h323_ID or an alias starting with 002, the default policy is used by querying the internal registration table, then the neighbors, and if those fail, the parent.

Routing policies are applied to the first message of a call: The ARQ for calls from registered endpoints, the Setup for calls from unregistered endpoints, the LRQ for calls from neighbors and certain Facility messages for calls that are forwarded by GnuGk using the ForwardOnFacility feature. You can specify different routing policies for each type of call by using the [RoutingPolicy::OnARQ], [RoutingPolicy::OnLRQ], [RoutingPolicy::OnSetup] and [RoutingPolicy::OnFacility] sections using the same syntax explained above.

Example:

[RoutingPolicy::OnARQ]
default=numberanalysis,internal,neighbor

A typical ENUM routing setup would look like this:

Example:

[RoutingPolicy]
default=explicit,internal,enum,srv,dns,internal,parent,neighbor

6.2 Section [RasSrv::RewriteE164]

This section defines the rewriting rules for dialedDigits (E.164 number).

Format:

[!]original-prefix=target-prefix

If the number begins with original-prefix, it is rewritten to target-prefix. If the `!' flag precedes the original-prefix, the sense is inverted and the target-prefix is prepended to the dialed number. Special wildcard characters ('.' and '%') are available.

Example:

08=18888

If you dial 08345718, it is rewritten to 18888345718.

Example:

!08=18888

If you dial 09345718, it is rewritten to 1888809345718.

Option:

  • Fastmatch=08
    Default: N/A

    Only rewrite dialDigits beginning with the specified prefix.

6.3 Section [RasSrv::RewriteAlias]

This section defines the rewriting rules for aliases. This can be used to map gatekeeper assigned aliases to registered endpoints.

Format:

[!]original-alias=target-alias

If the alias is original-alias, it is rewritten to target-alias.

Example:

bill=033123456

6.4 Section [RasSrv::GWRewriteE164]

This section describes rewriting the dialedDigits E.164 number depending on the gateway a call has come from or is being sent to. This allows for more flexible manipulation of the dialedDigits for routing etc.

Despite the name of the section, you can not only rewrite calls from and to gateways, but also calls from terminals (regular endpoints) and neighbor gatekeepers.

In combination with the RasSrv::RewriteE164 you can have triple stage rewriting:

Call from "gw1", dialedDigits 0867822
                |
                |
                V
Input rules for "gw1", dialedDigits now 550867822
                |
                |
                V
Global rules, dialedDigits now 440867822
                |
                |
                V
Gateway selection, dialedDigits now 440867822, outbound gateway "gw2"
                |
                |
                V
Output rules for "gw2", dialedDigits now 0867822
                |
                |
                V
Call to "gw2", dialedDigits 0867822

Format:

alias=in|out=[!]original-prefix=target-prefix[;in|out...]

If the call matches the alias, the direction and begins with original-prefix it is rewritten to target-prefix. If the `!' flag precedes the original-prefix, the sense is inverted. Special wildcard characters ('.' and '%') are available. '.' matches one character and '%' matches any number of characters. Multiple rules for the same gateway are separated by ';'.

To convert dialed digits into post dial digits that are sent to the remote side after the call connects as UserInputIndications, use 'I' (for Input) on the prefix side and 'P' (for Postdial) on the target side. Please note that H.245 routing through the gatekeeper must be active to send post dial digits.

Calls from and to gateways and terminals are matched by their first alias. Calls from and to neighbors are matched by the neighbor ID in the GnuGk config (the XXX in the [Neighbor::XXX] section name) or the gatekeeper identifier of the neighbor if it is set.

Note that when you have multi-homed neighbors or are accepting non-neighbor LRQs, the source of the call can not always be determined and no IN rule for a neighbor will match. In these cases you should only use OUT and [RasSrv::RewriteE164] rules.

Example:

gw1=in=123=321

If a call is received from "gw1" to 12377897, it is rewritten to 32177897 before further action is taken.

Post Dial Example:

gw1=out=09III=09PPP

If a call is sent out through "gw1" to 09123, it is rewritten to 09 and 123 are sent as post dial digits.

Neighbor Example 1:

In this example the neighbor is identified by its ID and incoming calls from NbGk will have their 01 prefix replaced by a 04 prefix. Outgoing calls will have 04 replaced with 01. 

[RasSrv::Neighbors]
NbGk=GnuGk

[Neighbor::NbGk]
GatekeeperIdentifier=GK-PW-Prox
Host=192.168.1.100
SendPrefixes=*
AcceptPrefixes=*

[RasSrv::GWRewriteE164]
NbGk=in=01=04;out=04=01

Neighbor Example 2:

In this example the neighbor is identified by its gatekeeper identifier and incoming calls from GK-PW-Prox that don't have a 0049 prefix get the prefix prepended. A call to "1234" would be rewritten to "00491234", while a call to "00496789" would proceed unchanged because the "If incoming does not start with 0049 and any number of digits after 0049, then prepend 0049" logic would be false (because we already have 0049 at the beginning.)

[RasSrv::Neighbors]
NbGk=GnuGk

[Neighbor::NbGk]
GatekeeperIdentifier=GK-PW-Prox
Host=192.168.1.100
SendPrefixes=*
AcceptPrefixes=*

[RasSrv::GWRewriteE164]
GK-PW-Prox=in=!0049.=0049.

6.5 Section [Endpoint::RewriteE164]

Once you specify prefix(es) for your gatekeeper endpoint, the parent gatekeeper will route calls with dialedDigits beginning with that prefixes. The child gatekeeper can rewrite the destination according to the rules specified in this section. By contrast, when an internal endpoint calls an endpoint registered to the parent gatekeeper, the source will be rewritten reversely.

Format:

external prefix=internal prefix

For example, if you have the following configuration,

                        [Parent GK]
                        ID=MainGK
                        /         \
                       /           \
                      /             \
                     /               \
                [Child GK]          [EP3]
                ID=ProxyGK          E164=18888200
                Prefix=188886
                /       \
               /         \
              /           \
           [EP1]         [EP2]
           E164=601      E164=602

With this rule: 

188886=6

When EP1 calls EP3 by 18888200, the CallingPartyNumber in the Q.931 Setup will be rewritten to 18888601. Conversely, EP3 can reach EP1 and EP2 by calling 18888601 and 18888602, respectively. In consequence, an endpoint registered to the child gatekeeper with prefix '6' will appear as an endpoint with prefix '188886', for endpoints registered to the parent gatekeeper.

The section does not relate to the section RasSrv::RewriteE164, though the latter will take effect first.

6.6 Section [Routing::DNS]

  • ResolveNonLocalLRQ=0
    Default: 1

    This switch determines whether the DNS policy should resolve hostnames or IPs in LRQs that don't terminate locally.

  • RewriteARQDestination=0
    Default: 1

    Preserve the full URL in the destination from ARQs, don't tell the endpoint to use only the local name part of the URL in the subsequent Setup. Needed if the call destination requires the full URL.

6.7 Section [Routing::ENUM]

  • ResolveLRQ=1
    Default: 0

    This switch toggles whether the 'enum' policy should resolve LRQs.

Additional ENUM schemas may be configured by the [Routing::ENUM::id]

Format:

<enum schema>=<protocol gateway>

Example:

[Routing::ENUM::2]
[email protected]

6.8 Section [Routing::SRV]

  • ResolveNonLocalLRQ=1
    Default: 0

    This switch selects if the 'srv' policy should resolve hostnames in LRQs that don't terminate locally.

  • ConvertURLs=1
    Default: 0

    Convert URL_IDs into H323_IDs before sending out an LRQ to an LS service found in an SRV record. This is useful if the called LS service doesn't understand URL_IDs.

Additional SRV schemas may be configured by the [Routing::SRV::id]

Format:

<SRV schema>=<protocol gateway>[;default schema port]

Example:

[Routing::SRV::2]
[email protected]

6.9 Section [Routing::RDS]

  • ResolveLRQ=1
    Default: 0

    This switch selects if the 'rds' policy should resolve hostnames in LRQs.

6.10 Section [Routing::Explicit]

You can define a mapping where calls to certain IPs should be routed by the 'explicit' policy. The new destination can either be another IP or an alias destination of any type. If you rewrite the destination to something other than an IP, make sure you have other routing policies in the chain behind the 'explicit' policy that can handle the new destination.

Format:

IP=newIP[:port] | E.164 | alias

Example:

[Routing::Explicit]
192.168.1.100=10.10.1.100
192.168.1.101=10.10.1.101:1720
192.168.1.102=654251
192.168.1.103=peter
[email protected]

6.11 Section [Routing::Sql]

Rewrite the called alias with a SQL query. Supports routing OnARQ, OnLRQ and OnSetup.

If the string returned from the database is 'REJECT' (upper or lower case), the call is rejected. If the string matches a dotted IP address, it is taken as destination IP otherwise it is treated as a new destination alias. If 2 columns are returned, the first is treated as the new destination alias and the second is treated as new destination IP. If the 2nd column contains 'IGNORE', the database result is treated as if it would only contain 1 result column. (This allows simpler SQL queries in some cases.)

If multiple rows of destination IPs are returned they are used as alternative routes for failover and GnuGk will try them in order.

When at least one destination IP is specified or the call is rejected, the SQL policy will end the routing chain. If only the alias is changed, the chain continues with this updated alias.

When rejecting a call, the 2nd column can contain an integer designating the reject reason (H.225 AdmissionRejectReason for registered calls, H.225 LocationRejectReason for neighbor calls, H.225 disconnect reason for unregistered calls).

If the database returns nothing, the call is passed on unchanged.

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

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

    Define a SQL query to fetch the new destination number. The query is parameterized - that means parameter replacement is made before each query is executed. The following parameters are defined:

    • %c - the called alias
    • %p - the called IP (only available on Setup, empty otherwise)
    • %s - the calling IP
    • %r - the calling aliases
    • %{Calling-Station-Id} - the calling station ID (same value as used in accounting and authentication events)
    • %i - the call ID
    • %m - the message type (ARQ, LRQ or Setup)
    • %{client-auth-id} - a 64 bit integer ID provided to GnuGk when authenticating the call (through SQLAuth)
    • %{language} - language if available
    Some of these can be empty if they aren't included in the ARQ, LRQ or Setup message.

    If the query returns no rows, the current alias is used. Otherwise, the first result row is used.

    Query string examples. Note that these are examples; the actual structure and schema are user defined, as are the various field names in these examples. GnuGk is simply expecting either IP addresses or aliases as a result of the query.

    SELECT destination FROM routes WHERE called = '%c'
SELECT concat(prefix,'%c') FROM routes WHERE prefix = LEFT('%c', 5)
SELECT gatewayip FROM routes WHERE prefix = LEFT('%c',5)
SELECT concat(prefix,'%c'), gatewayip FROM routes WHERE route = LEFT('%c', 5) limit 3

  • EnableRegexRewrite=1
    Default: 0

    Enable basic regex rewriting where parts of the original called alias are inserted into the result of the database query.

    Regular expressions:

    • {\1} - all of the original called alias
    • {^\d(4)} - first 4 digits
    • {\d(4)$} - last 4 digits

    Examples:

    Assuming the called alias was "12345678" and the database returns "{\1}@my.com" then all character are inserted so the new destination is "[email protected]".

    If the database returns "{^\d(4)}@my.com" the first 4 digits are inserted so the new destination is "[email protected]" and with "{\d(4)$}@my.com" from the database, the call is sent to "[email protected]".

6.12 Section [Routing::Http]

Rewrite the called alias with a HTTP query. Supports routing OnARQ, OnLRQ and OnSetup.

If the string returned from the is 'REJECT' (upper or lower case), the call is rejected. If the string matches a dotted IP address, it is taken as destination IP otherwise it is treated as a new destination alias.

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

    The URL to fetch the routing destination from. You can use the parameters specified below to parameterize the URL.

  • 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 destination from the HTTP response.

  • DeleteRegex=5544
    Default: N/A

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

  • ErrorRegex=error
    Default: ^$

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

  • JSONResponse=1
    Default: 0

    Use JSON as HTTP response for structured results. You may still use the ErrorRegex switch when using JSON, but the ResultRegex and DeleteRegex switch will be ignored.

The following parameters are available for the URL and Body strings:

  • %c - the called alias
  • %p - the called IP (only available on Setup, empty otherwise)
  • %s - the calling IP
  • %r - the calling aliases
  • %{Calling-Station-Id} - the calling station ID (same value as used in accounting and authentication events)
  • %i - the call ID
  • %m - the message type (ARQ, LRQ or Setup)
  • %{client-auth-id} - a 64 bit integer ID provided to GnuGk when authenticating the call (through SQLAuth)
  • %{language} - language if available

A JSON response may contain any of the below fields:

  • reject - boolean value whether to reject the call or not
  • reject-reason - integer, interpreted as either AdmissionRejectReason of registered calls or Q.931 reject reason or unregistered calls
  • destination - string where to route the call, either an alias or an IP number
  • gateway - string with IP where to route the call, the destination field must be present and will be interpreted as an alias

A JSON response should contain either a reject field or a destination field. All other fields are optional. You may send an array of response objects to use as multiple routes for call failover. A call rejection must be sent as a single JSON object, not inside an array.

Example JSON responses:

  • { "reject": true }
  • { "reject": true, "reject-reason": 2 }
  • { "destination": "support" }
  • { "destination": "192.0.2.4" }
  • { "destination": "support", "gateway": "192.0.2.4:1720" }
  • [ { "destination": "support", "gateway": "192.0.2.4:1720" }, { "destination": "support", "gateway": "192.0.2.8:1720" } ]

6.13 Section [Routing::NeighborSql]

Select which neighbor to query for a call with a database query.

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

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

    Define a SQL query to fetch the new neighbor IP and port.

6.14 Section [Routing::NumberAnalysis]

This section defines rules for the numberanalysis routing policy. The policy checks a dialed number for minimum and/or maximum number of digits and sends ARJ, if necessary (number of digits is out of range), to support overlapped digit sending. It also partially supports Setup messages (no overlapped sending - only number length validation).

Format:

prefix=MIN_DIGITS[:MAX_DIGITS]

If the number matches the prefix, it is verified to consist of at least MIN_DIGITS digits and (if MAX_DIGITS is present) at most MAX_DIGITS digits. Special wildcard characters (!, '.' and '%') are available. If the number is too short, an ARJ is send with rejectReason set to incompleteAddress. If the number is too long, an ARJ is send with rejectReason set to undefinedReason. Prefix list is searched from the longest to the shortest prefix for a match. For Setup messages, a Release Complete with "badFormatAddress" is sent when the number has an incorrect length.

Example:

[RoutingPolicy::OnARQ]
default=numberanalysis,internal

[Routing::NumberAnalysis]
0048=12
48=10
.=6:20

Calls to destinations starting with 0048 require at least 12 digits, to 48 we require 10 digits and to all other destinations at least 6 and at most 20 digits.

6.15 Section [Routing::Forwarding]

This routing policy performs a database lookup if calls to an endpoint should be forwarded to another endpoint. It supports routing OnARQ, OnSetup and OnLRQ.

There are different types of forwards:

  • Call Forwarding Unconditional (CFU, code 1): Calls are always forwarded.
  • Call Forwarding on Busy (CFB, code 2): Calls are forwarded if the called endpoint is already in a call.
  • Call Forwarding on No Answer (CFNA, code 3): Calls are forwarded if the called endpoint doesn't answer the call within the AlertingTimeout.
  • Call Forwarding on Error (CFE, code 4): Calls are forwarded if there is an error routing the call to the endpoint. Currently this behaves like Call Forwarding on No Answer and only one of them should be defined.

The destination where calls are forwarded to should either be aliases of local endpoints (incl. permanent endpoints) or IP numbers. For local aliases, GnuGk will check if the destination also has forwarding configured and take it into account.

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

Specifically for this module, you can specify a query to read the forwarding rules:

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

    Define a SQL query to fetch the forwarding rules. The query must return 2 columns: First the code for the forwarding type and second the new destination. It must ensure that the results are ordered ascending by forwarding code.

    The query is parameterized - that means parameter replacement is made before each query is executed. The following parameters are defined:

    • %c - the called alias
    • %p - the called IP (only available on Setup, empty otherwise)
    • %s - the calling IP
    • %r - the calling aliases
    • %{Calling-Station-Id} - the calling station ID (same value as used in accounting and authentication events)
    • %i - the call ID
    • %m - the message type (ARQ or Setup)
    • %{client-auth-id} - a 64 bit integer ID provided to GnuGk when authenticating the call (through SQLAuth)
    • %{language} - language if available
    Some of these can be empty if they aren't included in the ARQ or Setup message. In most cases you should only use the called alias in the SQL query, since they apply only to the incoming call and won't change when looking up chained forwarding rules.

Example:

[RoutedMode]
GKRouted=1
AcceptUnregisteredCalls=1
; failover must be on for forward on timeout
ActivateFailover=1
FailoverCauses=1-15,17-127
DisableRetryChecks=1
; 10 sec alerting timeout (for forward on no answer)
AlertingTimeout=10000

[RoutingPolicy]
default=explicit,forwarding,internal,neighbor,explicit

[Routing::Forwarding]
Driver=MySQL
Host=localhost
Database=gnugk
Username=gnugk
Password=secret
Query=SELECT forwardtype, destination FROM forwards WHERE called = '%c' order by forwardtype asc
MinPoolSize=1

Sample MySQL Schema:

create table gnugk.forwards (
    called varchar(30) not null,
    forwardtype smallint not null,
    destination varchar(30) not null default "",
    PRIMARY KEY (called, forwardtype)
);

Sample Forwarding Rules:

"1234", 1, "2000"
"5678", 2, "4000"
"5678", 3, "4000"
"9876", 4, "5000"

6.16 Section [Routing::CatchAll]

  • CatchAllIP=192.0.2.4
    Default: (empty)

    Specify an IP address to route all calls to. This overrides CatchAllAlias.

  • CatchAllAlias=Frank
    Default: catchall

    If CatchAllIP is not specified, then route all calls to this alias.

6.17 Section [Routing::Lua]

This section configures the scripts for LUA routing.

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

The LUA script has the following input variables available:

  • source - source IP
  • calledAlias - called alias (only first alias)
  • calledIP - called IP address if IP dialing was used
  • caller - aliasses of the caller
  • callingStationId - calling station ID
  • callid - the call ID
  • messageType - the message that triggered the routing process ('ARQ', 'LRQ', 'Setup' or 'Facility')
  • clientauthid - client auth ID

The LUA script can set these output variables to specify a routing destination:

  • action - set this to either 'SKIP' or 'REJECT' if you don' want to route the call, otherwise the call is routed to destAlias or destIp (see below)
  • rejectCode - reject reason to use with 'REJECT'
  • destAlias - call destination alias
  • destIP - call destination IP

To access external resources, LUA scripts can use LUA libraries, eg. LuaSocket.

  • Script=destAlias=string.gsub(calledAlias, "#", "*")
    Default: (empty)

    Define the LUA script to run, right in the config file.

  • ScriptFile=script.lua
    Default: (empty)

    Specify a file with a LUA script to run for the 'lua' policy.

6.18 Section [Routing::URIService]

URI Service specific routing policy.

Format:

<schema>=<protocol gateway>

Example:

[Routing::URIService]
xmpp=mygateway.mydomain.com

This switch sets the service type and default gateway for a given URI schema. This can be used in a chain with [Routing::ENUM::<schema>] and [Routing::SRV::<schema>] to provide a service specific routing policy.

6.19 Section [RewriteCLI]

This section contains a set of rewrite rules for ANI/CLI/H.323_ID numbers (Caller ID). The rewrite process is done in two stages - inbound rewrite and outbound rewrite. The inbound rewrite is done before any other Q.931 Setup message processing (such as inbound GWRewrite, authentication, accounting, ...), and because it alters the Calling-Station-Id it will have an effect in the authorization and accounting modules. The outbound rewrite takes place just before the Setup message is to be forwarded and its effect is visible only to the callee.

An inbound rewrite rule can be matched by a caller's IP and a dialed number or an original CLI/ANI. An outbound rewrite rule can be matched by a caller's IP, callee's IP and a dialed number or a destination number (the dialed number after rewrite) or a CLI/ANI (after inbound rewrite).

This module also provides CLIR (Calling Line Identification Restriction) feature that can be configured for each endpoint (rule).

  • ProcessSourceAddress=1
    Default: 1

    In addition to rewriting a Calling-Party-Number Information Element ("IE"), the sourceAddress element of a H.225.0 Setup message can be rewritten, so both contain consistent information.

  • RemoveH323Id=1
    Default: 1

    When a sourceInfo element of an H.225.0 Setup message is rewritten, aliases of type H323_ID, email_ID and url_ID can be left untouched if this option is disabled.

  • CLIRPolicy=apply
    Default: N/A

    A global Presentation Indicator ("PI") processing policy can be set up. This policy will be applied to all CLI rewrite rules that do not override it. Possible choices are forward - just forward the received PI as-is, apply - examine the received PI and hide CLI if it is set to "presentation restricted" and applyforterminals - similar to apply except that the number is removed only when the call is sent to a terminal, not a gateway.

Format for an inbound rule:

in:CALLER_IP=[pi=[allow|restrict][,forward|apply|applyforterminals]] [cli:|dno:]number_prefix(=|*=|~=|^=|/=)NEW_CLI[,NEW_CLI]...

The in: prefix specifies that this is an inbound rule and the CALLER_IP will be used to match the rule (it can be a single IP or an entire subnet). You can use IPv4 or IPv6 addresses for the CALLER_IP.

The optional pi= parameter controls CLIR (Calling Line Identification Restriction) features. Specifying either allow or restrict forces presentation indicator to be set to "presentation allowed" or "presentation restricted". forward, apply and applyforterminals controls how the received (if any) presentation indicator is processed by the gatekeeper. forward means forward it to the callee as-is, apply is used to hide the CLI if the PI is set to "presentation restricted", applyforterminals is similar to apply, except that CLI is hidden only when sending the call to a terminal, not a gateway.

The prefix cli: or dno: (the default) selects what number will be used to match the number_prefix - a caller id (CLI/ANI) or a dialed number. Number matching/rewriting can be done in five ways:

  • = - a cli or dno number will be matched using a prefix match against number_prefix and, if the match is found, CLI will be replaced with NEW_CLI.
  • ~= - a cli or dno number will be matched using an identity match against number_prefix and, if both numbers are the same, CLI will be replaced with NEW_CLI.
  • *= - (VALID ONLY FOR cli) a cli number will be matched using a prefix match against number_prefix and, if the match is found, the matched CLI prefix (number_prefix) will be replaced with a NEW_CLI prefix.
  • ^= - a cli or dno number will be matched using a prefix match against number_prefix and, if the match is found, H.323_ID will be replaced with NEW_CLI, Calling-Station-Id will remain unchanged.
  • /= - a cli or dno number will be matched using an identity match against number_prefix and, if both numbers are the same, H.323_ID will be replaced with NEW_CLI, Calling-Station=Id will remain unchanged,
After the equality (=/ =/*=/^=//=) sign, there follows a list of new CLI values to be used. If more than one value is specified, one will be chosen on a random basis. It's possible to specify whole number ranges, like 49173600000-49173699999 (for number ranges CLIs should have a fixed length). There is a special string constant "any" which may be used in place of the CALLER_IP or the number_prefix. To enable CLIR for this rule, use the special string constant "hide" instead of the list of new CLI values. Note that CLIR is far more useful for outbound rules.

Example 1:

[RewriteCLI]
in:192.168.1.1=dno:5551=3003
in:192.168.1.1=cli:1001=2222
in:192.168.1.1=any=1111

These rules state that for calls from the IP 192.168.1.1: 1) if the user dialed a number beginning with 5551, set CLI to 3003, 2) if the call is from user with CLI beginning with 1001, set CLI to 2222, 3) for other calls from this IP, set CLI to 1111.

Example 2:

[RewriteCLI]
in:192.168.1.0/24=any=18001111
in:192.168.2.0/24=any=18002222
in:2002:4ad0:ff00:79a::2/64=any=18003333
in:any=any=0

These rules state that: 1) for calls from the network 192.168.1.0/24, set CLI to 18001111, 2) for calls from the network 192.168.2.0/24, set CLI to 18002222, 3) for calls from the network 2002:4ad0:ff00:79a::2/64, set CLI to 18003333, 4) for other calls, set CLI to 0.

Example 3:

[RewriteCLI]
in:192.168.1.0/24=0048*=48
in:192.168.1.0/24=0*=48
in:any=100.~=48900900900

These rules state that: 1) for calls from the network 192.168.1.0/24, rewrite 0048 to 48 (example - 0048900900900 => 48900900900), 2) for other calls from the network 192.168.1.0/24, rewrite 0 to 48 (example - 0900900900 => 48900900900), 3) for other calls, if CLI is 4 digits and starts with 100, set it to 48900900900.

Example 4 (CLIR):

[RewriteCLI]
in:192.168.1.0/24=any=hide

This example causes caller's number to be removed from Setup messages originating from the 192.168.1.0/24 network. It also causes proper presentation and screening indicators to be set in Setup messages.

Format for an outbound rule:

out:CALLER_IP=CALLEE_IP [pi=[allow|restrict][,forward|apply|applyforterminals]] [cli:|dno:|cno:]number_prefix(=|~=|*=)NEW_CLI[,NEW_CLI]...

The out: prefix tells that this is an outbound rule, the CALLER_IP and the CALLEE_IP will be used to match the rule and can be a single IP or a subnet address.

The optional pi= parameter controls CLIR (Calling Line Identification Restriction) features. Specifying either allow or restrict forces the presentation indicator to be set to "presentation allowed" or "presentation restricted". forward, apply and applyforterminals controls how the received (if any) presentation indicator is processed by the gatekeeper. forward means just to forward it to the callee as-is, apply means hiding CLI if the PI is set to "presentation restricted", applyforterminals is similar to apply, except that the CLI is hidden only when sending the call to a terminal, not a gateway.

The prefix cli:, dno: (the default) or cno: selects what number will be used to match the number_prefix - a caller id (CLI/ANI), a dialed number or a destination/called number (the dialed number after rewrite). Number matching/rewriting can be done in three ways:

  • = - a cli or dno number will be matched using a prefix match against number_prefix and, if the match is found, CLI will be replaced with NEW_CLI,
  • ~= - a cli or dno number will be matched using an identity match against number_prefix and, if both numbers are the same, CLI will be replaced with NEW_CLI,
  • *= - (VALID ONLY FOR cli) a cli number will be matched using a prefix match against number_prefix and, if the match is found, the matched CLI prefix (number_prefix) will be replaced with a NEW_CLI prefix.
After the equality sign (=/ =/*=), a list of new CLI values to be used is specified. If more than one value is configured, one will be chosen on a random basis. It's possible to specify entire number ranges, like 49173600000-49173699999. There is a special string constant "any" which can be used in place of the CALLER_IP, the CALLEE_IP or the number_prefix. To enable CLIR for this rule, use a special string constant "hide" or "hidefromterminals" instead of the list of new CLI values.

Example 1:

[RewriteCLI]
out:any=192.168.1.1 any=1001
out:any=192.168.1.2 any=1002
out:any=any cno:123=1003

These rules set a fixed ANI/CLI for each terminating IP: 1) present myself with ANI 1001, when sending calls to IP 192.168.1.1, 2) present myself with ANI 1002, when sending calls to IP 192.168.1.2. 3) present myself with ANI 1003, when calling 123

Example 2:

[RewriteCLI]
out:any=192.168.1.1 any=1001-1999,3001-3999

This rule randomly selects ANI/CLI from range 1001-1999, 3001-3999 for calls sent to 192.168.1.1.

Example 3 (CLIR):

[RewriteCLI]
out:any=any any=hidefromterminals
out:192.168.1.1=any any=hide

In this example each subscriber has enabled CLIR, so all calls to terminals will have a caller's number removed and presentation/screening indicators set. Calls to gateways will have the presentation indicator set to "presentation restricted" and the caller's number will not be removed to allow proper call routing and number removal at the destination equipment.
One exception to these rules are calls from 192.168.1.1 which will have a caller's number always removed, no matter whether calling a terminal or a gateway.

Example 4 (CLIP):

[RewriteCLI]
out:any=192.168.1.1 any=hide

In this example CLIP (Calling Line Identification Presentation) feature is disabled for the user 192.168.1.1.

Example 5 (CLIR):

[RewriteCLI]
out:192.168.1.1=any pi=restrict,apply cli:.*=.
out:any=any pi=allow cli:.*=.

These rules do not change CLI (.*=.) and: 1) enable CLIR for an endpoint 192.168.1.1. apply tells the gatekeeper to not only set the PI, but also to hide the number. 2) force CLI presentation for other endpoints.

The rule matching process has a strictly defined order:

  1. the closest caller's IP match is determined (closest means with the longest network mask - single IPs have the highest priority, "any" has the lowest priority),
  2. (outbound rules) the closest callee's IP match is determined,
  3. the longest matching prefix/number is searched for the given IP/IP pair in the following order:
    1. dno: type (dialed number) rules are searched,
    2. cno: type (destination/called number) rules are searched,
    3. cli: type (caller id) rules are searched.
After a match for caller's/caller's IP is found, no more rules are checked, even if no prefix/number is matched inside the set of rules for these IPs.

On the Windows platform, there is a problem with duplicated config keys in INI files, so GnuGk provides a workaround for this restriction. This example will not work because of the same key (in:192.168.1.1): 

[RewriteCLI]
in:192.168.1.1=1001=2001
in:192.168.1.1=any=2000
As a workaround, you can use a string with percent signs (%) at the beginning and at the end before the key. This prefix will be automatically stripped from the key name before loading rules: 
[RewriteCLI]
%r1% in:192.168.1.1=1001=2001
%r2% in:192.168.1.1=any=2000

6.20 Section [RewriteCLI::SQL]

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

Please note that the switches (not the rules) from the RewriteCLI section, like ProcessSourceAddress=, RemoveH323Id= and CLIRPolicy= also apply to the rewrite rules from this section.

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

    Define a rewriting query to run when the call comes in.

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

    Define a rewriting query to run when the call is sent out. The called number parameter has already passed all rewriting steps.

The first field returned by the query is used as the new CLI. If the query returns no rows, the CLI is left unchanged. The queries can be parameterized - that means parameter replacement is made before each query is executed. The following parameters are defined:

  • %{cli} - the original CLI or first sourceAddress if no CLI exists (on outbound queries, it can already be rewritten by an Inbound query)
  • %{callerip} - the calling IP
  • %{called} - the called number (the dialed number on inbound queries and the rewritten number in outbound queries)

In most cases you will probably only use the %{cli} parameter.

6.21 Section [RewriteSourceAddress]

With the switches in this section you can filter the sourceAddress elements that are transported in a Setup message. (Please note that the RewriteCLI and RewriteCLI::SQL rules also influence the sourceAddress.)

  • OnlyE164=1
    Default: 0

    With this switch you can filter out all elements that are not of type E.164.

  • OnlyValid10Dand11D=1
    Default: 0

    With this switch you can filter out all elements that are not valid 10-digit or 11-digit US numbers. They may be of any alias type (unless OnlyE164 is set), but no formatting characters are allowed. 11-digit numbers must start with 1 and area codes must start with 2..9.

  • MatchSourceTypeToDestination=1
    Default: 0

    With this switch you can filter out all elements that do not match the destination Type (E.164 or URI) If you call an E.164 number (Q931 IE: Called-Party-Number present) everything other then dialdigit source will be filtered. If you call a URI (destination AliasAddress type) everything other then URI source will be filtered. This switch has no effect on any other destination type. For example H323ID or TransportID AliasTypes.

  • ForceAliasType=1
    Default: -1

    values 0-dialedDigits 1-h323_ID 2-URI-ID With this switch you can force the source and destination AliasAddress to the supplied type. Used in conjunction with MatchSourceTypeToDestination to change the AliasType. for instance change url_ID to h323_ID so the remote gateway can process the message.

  • ReplaceChar=+,0;#,*
    Default: N/A

    With this switch you can remove/replace characters on the callers source address such as +.

  • Rules=01,18001234567
    Default: N/A

    With this switch you can replace the CallSourceAddress if there is a prefix match. You can use this to assign a common valid E.164 number to non-E.164 numbers for the purpose of callerID.

  • TreatNumberURIDialedDigits=1
    Default: 0

    Where MatchSourceTypeToDestination is set and the destination is a URI and the host part is numeric this ensures the source address is numeric URI as well by taking the DialedDigits source address and mixing it with the URI address if present so the same format is for the source and destination address.

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