Next Previous Contents

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:

Default configuration for routing policies is as follows:

[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:

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

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.

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=MasterGK
                        /         \
                       /           \
                      /             \
                     /               \
                [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]

6.7 Section [Routing::ENUM]

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

Format:

<enum schema>=<protocol gateway>

Example:

[Routing::ENUM::2]
E2U+xmpp=mygateway@mydomain.com

6.8 Section [Routing::SRV]

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

Format:

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

Example:

[Routing::SRV::2]
_xmpp-server._tcp=mygateway@mydomain.com

6.9 Section [Routing::RDS]

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
192.168.1.104=joe@company.com

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.

6.12 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.13 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:

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:

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.14 Section [Routing::CatchAll]

6.15 Section [Routing::Lua]

NOTE: This policy is still experimental and may change in the next release. Please contact the GNU Gatekeeper authors if you want to use it in production.

The LUA script has the following input variables available:

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

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

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

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:

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:

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

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.

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.17 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 rules may also influence the sourceAddress.)

Next Previous Contents