| Version 5.4
Introduction
Installation
SysAdmin
Network
Objects
Storage
E-mail
Real-Time
Access
Services
Directory
Clusters
Applications
Miscellaneous
Licensing
WebMail
Pronto!
PBX
Sys Admin | Logs | Router | Protection | Security | PKI | Intercept | Scalability | Alerts | Statistics
# Router Address Structure Main Domain Name Domains and DNS Records Routing Table Prefix Sample Route Domain-Level Records Account-Level Records All-Local Records Special Addresses Explicit Routing via Remote Systems Routing to Real-Time Applications Phone Number Routing Routing by IP Addresses Routing via Modules External Helper Routing ENUM Routing `tel:` Routing Default Records Extending Non-Qualified Domain Names All-Domain Aliases Cluster-wide Routing Table This section is for advanced administrators only. In most situations the default routing methods are sufficient. Only if your Server is working as a message or signal relay for other systems, or if you want to use sophisticated routing schemes, should you read this section. When the Server processes a submitted Message, it extracts the information about recipients from the message "envelope" and decides into which module queue the message should be placed, which entity the module should send the message to, and how it should address that entity. Similar operations are performed with Real-time Signals received from external sources or generated with internal components and directed to local or external entities. Access modules (such as POP, IMAP, WebUser Interface, etc.) also deal with addresses. When a client application or program logs in, it provides a name of the Account it wants to log into. This address is processed using the same operations as ones used to process Message and Signal addresses. The CommuniGate Pro Router component implements these routing operations. Whenever your Server gets some address, that address is processed using the Router component. This provides additional consistency to all Server components: when, for example, you create an Alias for some Account, that Alias can be used to send E-mail and Signals to that Account, and the Alias name can be used to log into that Account.

## Address Structure

Each E-mail or Signal address consists of two strings: a domain name and a local part. Usually, an address looks like `xxxx@yyyyy`, where yyyyy is the domain name (the unique name of the recipient mail system) and xxxx is the local part, i.e. a user name or an account name in that system.

Addresses can be more complicated, for example, an E-mail address can include some path information:
  `<@zzzz:xxxx@yyyyy>` or `zzzz!yyyyy!xxxx` or `xxxx%yyyyy@zzzz`
  These addresses specify that an E-mail message or a Signal should be sent to the system zzzz first, and then that system should deliver it to xxxx@yyyyy (to the account xxxx on the system yyyyy).

When the Router parses an address, it extracts the name of the system the message should be delivered to. It becomes the domain name part of the address. The rest of the address is placed into the local part, i.e. the local part defines the recipient when the message or the signal is delivered to the system specified with the domain name. In the examples above, the domain name part is zzzz, while the local part is xxxx@yyyyy.

See the RFC822 and related documents for details on E-mail address formats.

If a local part contains a complex address (i.e. the local part itself contains domain name(s) and a local part), the local part is presented using the '%' notation: local%domain1%domain2, so the full address in the CommuniGate Pro canonical form would be `local%domain1%domain2@domain`.

## Main Domain Name

When the domain name is extracted from an address, the Router compares it against the domain name of the Server (set in the General settings). If they match, the domain name is set to an empty string. When the domain part becomes an empty string, the Router restarts processing with the local part, trying to divide it into the domain and local parts again.
For example, if the Main Domain name of your Server is company.com, then the following addresses will be converted as shown:

Address | local part | domain part
--- | --- | ---
`support@company.com` | `support` | `company.com`
-- routed --> | `support` |
`<@company.com:sales@example.com>` | `sales@example.com` | `company.com`
-- routed --> | `sales@example.com` |
-- routed --> | `sales` | `example.com`

## Domains and DNS records

Your Server can support many independent Domains in addition to the Main Server Domain.

In order to process Messages and Signals directed to your Server Domains, you should ensure that the Messages sent to that domain are directed to your Server with the global DNS system.

Example 1: your server (example.com) serves the example.com Domain and a partners-example.com Domain. Make sure that DNS MX records are created for both Domains, and that those records point to your example.com Server.

Example 2: your server (example.com) acts as an "Remote POP" mail host relay for some client systems. Each client has its own domain name (client1.com, client2.com, and client3.com), and you have configured your Router to ensure that all E-mails sent to the client1.com domain will be routed to the Unified Domain-Wide Account client1, etc.
You should also ensure that when an E-mail is sent to the client1.com domain, that E-mail is routed to your server (example.com). The client1.com MX record should be created in the DNS system and that record should point to your Server (example.com).

## Routing Table

When an address is parsed and its domain part is extracted, the Router checks the routing records in the Routing Table.

Use the WebAdmin Interface to manage the Routing Table. Open the Router page in the Settings realm:

Log Level:
fax.company.com = company.com ; -> to the same domain hq.company.com = newhq.company.com ; -> to some other server Relay:*.test.com = company.com ; aaa.test.com, bbb.test.com ; just a comment line <sales> = john ; simple alias <sales@client1.com> = sales-client1 ; simple foreign alias <info@client1.com> = info@otherhost.com; account -> other account <*@client2.com> = *.cl2 ; sales@.. -> sales.cl2 test.com = Unified.local ; unified Domain-Wide Account
Add to Non-Qualified Domain Names

Each line in the Routing Table is a routing record. A routing record contains optional prefixes, a left part, the equals (`=`) symbol and a right part. The semicolon (`;`) symbol can be used to place a comment after the right part of a routing record. A comment line can be added to the Table by inserting a line starting with the semicolon symbol.

The Router takes a parsed address (i.e. the domain and local parts of the address) and uses the Table, scanning its records from top to bottom. If an applicable record is found, it is applied as described below and the modified address is processed with the Router again.

`Log Level`
  Use this setting to specify what kind of information the CommuniGate Pro Router should put in the System Log. Usually you should use the `Major` (address routing) level. But when you experience problems with the Router, you may want to set the Log setting to `Low-Level` or `All Info`: in this case more low-level information about the Router activity will be recorded in the System Log as well. The Router component records in the System Log are marked with the `ROUTER` tag.

### Prefix

A Routing record can contain a Relay-mode prefix: `Relay:` (can be shorten to `R:`), `NoRelay:` (can be shorten to `N:`), or `RelayAll:`. See the Protection section for the details.
If none of these prefixes is specified, the `NoRelay:` prefix is assumed.

A Routing record can contain zero, one, or several of the following operation-type prefixes:

- `Mail:` (can be shorten to `M:`). Records with this prefix take effect when an address is routed for some E-mail delivery operation.
- `Access:` (can be shorten to `A:`). Records with this prefix take effect when an address is routed for some account access operation.
- `Signal:` (can be shorten to `S:`). Records with this prefix take effect when an address is routed for some Signal operation.

These prefixes should be specified after an optional Relay-mode prefix. If none of these prefixes is specified, the Routing record is applied to addresses used in all operations.

### Sample

The left part of a Routing record contains a Sample: a string with an optional wildcard.

The following wildcards are supported:

`*`
  this wildcard matches zero or more symbols.
  Example:
    sta*r
    This sample matches any `staXXXXXXr` string where XXXXXX is any substring (including an empty substring inside the star string).
`(size type)`
  type is the substring type:
  - `d` - decimal digits (`0` .. `9`)
  - `h` - hexadecimal digits (`0` .. `9`, `A` .. `F`, `a` .. `f`)
  - `L` - alpha-numeric symbols (`0` .. `9`, `A` .. `Z`, `a` .. `z`)
  - `*` - any symbols
  size is an optional substring length. It can be specified in the following forms:
  - `nnn` (where nnn a decimal number): a matched substring should have nnn symbols.
  - `nnn+` : a matched substring should have nnn or more symbols.
  - `nnn-mmm` (where mmm a decimal number, mmm >= nnn): a matched substring should have between nnn and mmm symbols.
  Example:
    sta(3*)r
    This sample matches any `staXXXr` string where XXX are any 3 symbols.
  Example:
    sta(4+d)r
    This sample matches any `staDDDDDr` string where DDDDD are 4 or more decimal digits.
  Example:
    sta(3-5h)r
    This sample matches any `staHHHr` string where HHH are 3,4, or 5 hexadecimal digits.

The backslash (`\`) symbol is used as an escape symbol: `\\` is processed as a single backslash symbol, `\*` is processed as an asterisk symbol, etc.

Only one wildcard symbol is allowed in a sample.

### Route

The right part of a Routing record contains a Route: a string with an optional `*` wildcard.

When the Record Sample matches an address, the address is changed to the Record Route. The substring matching the Sample wildcard substitutes the Route wildcard.

The backslash (`\`) symbol is used as an escape symbol: `\\` is processed as a single backslash symbol, `\*` is processed as an asterisk symbol, etc.

Only one wildcard symbol is allowed in a Route.

### Domain-Level Routing Records

If the left part of a Routing record contains a domain name, the record specifies domain-level routing.

When some address is being processed and the domain name matches a domain name specified in such a record, the domain part is substituted with the right part of the routing record.

Example:
  hq.company.com = twisted.company.com
  All addresses with the hq.company.com domain part are changed to have the twisted.company.com domain part. The Router restarts, trying to route the modified address.

A routing path can specify relays.

Example:
  hq.company.com = hq.company.com@relay.company.com
  All E-mails and Signals directed to the domain name hq.company.com will be redirected to the system (domain) relay.company.com, and then, from that system, to the domain hq.company.com.

If E-mails and Signals to several domains should be routed in the same or similar way, you may use the asterisk (`*`) symbol as the wildcard symbol.

Example:
  *.old_company.com = new_company.com
  In this case addresses in all the domains ending with .old_company.com will be changed to have the new_company.com domain part, with the local parts (user names) unchanged.

Very often this type of routing is used to process all subdomains of the some domain.

Example:
  *.mycompany.com = mycompany.com
  If the mycompany.com is the Server's Main Domain name, then this routing record makes the Server process E-mails and Signals sent to all subdomains of its Main Domain as E-mail and Signals sent to the Main domain, the address user@mail.mycompany.com will be processed as the user@mycompany.com address.
Example:
  *.old_company.com = *.new_company.com
  When such a routing line is entered and an E-mail or a Signal comes in for the domain host5.old_company.com, it is routed to host5.new_company.com.
Example:
  system-*.mycompany.com = uu*.local
  This routing line will redirect system-abc.mycompany.com to uuabc.local .

Besides domain-level routing records, routing for domains can be specified using account-level records (see below).
Records for Unified Domain-Wide Accounts are domain-level routing records, too.

### Account-Level Routing Records

If the left part of a routing record contains an address in the angle brackets (`<` and `>`), the record is an Account-level record - a routing rule for a specific address.

When an address is parsed and the Router scans the Table records, it compares the address domain part with the domain part of all Account-Level routing records.

If the domain parts match, the Router compares the local part of the address with the local part of the account-level record address. If both domain and local parts match, the right part of the account-level routing record is used as the new address. The Router restarts, parsing and processing this new address.

Note: Because the Server Main Domain Name in the parsed address is immediately replaced with an empty string, account-level records that should apply to addresses in the Main Domain should not contain any domain part at all.

In the all examples below `mycompany.com` is the Server Main Domain name.

Example:
  <sales> = bill
  in this case, all messages to sales@mycompany.com will go to bill, as if they were sent to bill@mycompany.com.

Note: if there is an account-level record for the local name `xxxx`, there is no need to actually create a real `xxxx` Account on the Server. Additionally, that Account would be useless, since no message or signal will ever reach that Account: everything directed to the `xxxx` name will be routed elsewhere.

The right side of an account-level record can be any address.

Example:
  <sales> = Bill@thatcompany.com
  All messages directed to sales@mycompany.com will be directed to Bill@thatcompany.com. The Router takes the new address, extracts the domain name (thatcompany.com) and local (Bill) parts, then the Router restarts trying to find a route to thatcompany.com.

You can use the wildcard symbol (`*`) in the local part of account-level records. The same symbol can be used in any part of the right-side address to specify substring substitution.

Example:
  <dept-*> = postmaster@*-dept.mycompany.com
  This record will redirect all E-mails and Signals sent to dept-sales@mycompany.com to the user postmaster at the sales-dept.mycompany.com department server.

You can use Router account-level records to reroute E-mails and Signals sent to some of the your Server Secondary Domains. In the following example, the client.com is a local Secondary Domain.

Example:
  <sales@client.com> = Bill@client.com
  All messages directed to sales@client.com will be directed to Bill@client.com.
Example:
  <sales@client.com> = Bill
  All messages directed to sales@client.com will be directed to Bill@mycompany.com (i.e. to the address Bill in the Main Domain).

In most cases you do not have to use account-level Router Records: if you need to provide an alternative name some Account, use Account Aliases instead. If you need to re-route all E-mails and Signals sent to some name in a local Server Domain to some other address, use Forwarders instead.

You may need to create an alias for a specific account on a foreign system. For example, if all E-mail sent to some domain should be routed to a specific mail host or to a unified account, but certain accounts in that domain should be routed to accounts on your or other systems.

Example:
  Mail:<sales@client1.com> = sales-client1
  Mail:client1.com = new.client1.com
  These records route all E-mails directed to the account sales at the domain client1.com to the Account sales-client1 in your Server Main Domain, while messages to all other accounts in the client1.com domain are routed to the new.client1.com system.

The wildcard symbol (`*`) can be used only in the local part of the full account name (i.e. it can be used before the `@` symbol).

You can use the wildcard feature to host several domains in one CommuniGate Pro Domain creating a unique "address space" for each domain name.

Example:
  <*@client5.com> = cl5-*
  <*@client7.com> = cl7-*
  E-mails and Signals sent to sales@client5.com address will be directed to the cl5-sales Account in the Main Domain, E-mails and Signals sent to info@client5.com address will be directed to the cl5-info Account in the Main Domain, while E-mails and Signals sent to sales@client7.com address will be directed to the in the cl7-sales Account in the Main Domain.

  This method can be used when you do not want to create full-scale CommuniGate Pro Domains for many domains containing very few Accounts.

### All-Local Routing Records

Account-level records can use wildcard symbol (`*`) as the domain part. This records are applied to the addresses that contain any local Domain (i.e. a Domain created on this CommuniGate Pro Server or Cluster). The right-side address of such record specifies an address in the same local Domain.

Example:
  <abuse@*> = postmaster
  This record reroutes an abuse@domainX.dom address into postmaster@domainX.dom for all domainX.dom Domains created in your CommuniGate Pro system.

If the right-side address contains a domain part, the address is routed to that domain.

Example:
  <abuse@*> = postmaster@somedomain.com
  This record reroutes abuse@domainX.dom addresses into the postmaster%somedomain.com@domainX.dom addresses for all domainX.dom Domains created in your CommuniGate Pro system. Then the postmaster%somedomain.com@domainX.dom addresses are rerouted to the postmaster@somedomain.com address.

The local part of the left-side address can contain a wildcard (as in regular account-level records). The string matching this wildcard symbol can be used in the right-side address.

Example:
  <+*@*> = 011*
  This record reroutes the `+490088899@domainX.dom` address into the `011490088899@domainX.dom` address for all domainX.dom Domains created in your CommuniGate Pro system.

## Special Addresses

If the domain part of an address is `NULL`, or if the domain name part is empty, and the local part is `NULL`, the address is directed to a fictitious internal "Black hole" module.

When an E-mail message is routed to the "Black hole", the address is marked as "delivered" immediately, without any additional processing.

This feature allows you to use a local name `NULL` or the domain `NULL` as a "black hole" address: all messages sent to that address are just discarded. The `MAILER-DAEMON` address is automatically rerouted to `NULL`.

Example:
  bad.company.com = null
  <junk> = null
  With these records in the Routing Table, the Server will discard all mail sent to the domain bad.company.com, as well as all mail sent to the Main Domain address junk.

If the domain name part of an address is `ERROR`, or if the domain name part is empty, and the local name part is `ERROR`, the address is rejected without processing, generating an error report/response.

Example:
  bad.company.com = error
  <junk> = error
  With these records entered, the Server will reject all E-mail messages and Signals sent to the bad.company.com domain or to the Main Domain address junk.

If the domain name part of an address is `BlackListed`, or if the domain name part is empty, and the local name part is `BlackListed` , the address is rejected without processing, generating the "Blacklisted Address" error report. See the SMTP module description for the details.

If the domain name part is empty, and the local name part is `spamtrap`, routing stops. Addresses of that type are rejected as the `ERROR` addresses, but the SMTP module processes them in a special manner. See the Protection section for the details.

If the domain name part is empty, and the local name part is `incomplete`, routing stops. Signals sent to these addresses are rejected with the "Address Incomplete" error code.

Example:
  <(1-4d)@*> = incomplete
  With these records entered, dialing a 1-,2-, or 3-digit numbers will return the "Address Incomplete" error code to the client, forcing it to wait for additional input from the user.

If the domain name part ends with the symbols `.here`, this suffix is removed, and the remaining part of the domain name is used as the name of a local CommuniGate Pro Domain. This suffix allows you to avoid routing loops in certain situations.

Example:
  dept1.xyz.com = dept1.xyz.com.here
  dept2.xyz.com = dept2.xyz.com.here
  *.xyz.com = *.abc.com
  E-Mails and Signals sent to all subdomains of the xyz.com domain are rerouted to the subdomains of the abc.com domain, except for the addresses in the dept1.xyz.com and dept2.xyz.com subdomains, which are routed to the local dept1.xyz.com and dept2.xyz.com CommuniGate Pro Domains.

## Explicit Routing via Remote Systems

After all Routing Table records are applied, the Router checks if the domain name part ends with the `.via` suffix. The suffix is removed, and the domain name is used as the target host name, and the local part of the address is used as the address to pass to that host. The address is routed to the SIP module for Signal operation, or to the SMTP module for E-mail transfer and access operations.

Example:
  The Server Main Domain name is `company.com`.
  E-Mails and Signals sent to the `sales.company.com` Domain should be relayed to a separate sales.company.com server, while addresses in all other subdomains of the company.com domain should be processed as addresses in the Main Domain, i.e. user@subdomain.company.com addresses should be processed as user@company.com addresses.
  You can implement this routing using the following records:
  sales.company.com = sales.company.com.via ; explicitly relay to a remote host
  *.company.com = company.com ; all other subdomains are rerouted
  You can also specify this routing using IP addresses:
  sales.company.com = [192.0.0.1] ; explicitly relay to the IP address
  *.company.com = company.com ; all other subdomains are rerouted

  Note: addresses in the sales.company.com domain will be relayed with the domain part removed, i.e. the address <user@sales.company.com> will be relayed to sales.company.com host as <user>.
  This may cause troubles if the sales.company.com server does not accept addresses without domains. See the next sample for a possible solution.

Example:
  E-Mails and Signals sent to the client1.com, client2, and client3.com domains should be sent to the site host.com.
  You can implement this routing using the following records:
  client1.com = client1.com@host.com.via
  client2.com = client2.com@host.com.via
  client3.com = client3.com@host.com.via
  or, in a more flexible way:
  client1.com = client1.com@relay
  client2.com = client2.com@relay
  client3.com = client3.com@relay
  relay = host.com.via

  Note: You can specify just `host.com` instead of `host.com.via` here (given there is no other router record for host.com), but in this case mail to `user@client1.com` will be sent to the host.com as `user%client1.com@host.com`. By specifying the `.via` suffix you not only tell the Router to route the address to a relaying module, but you also force that module to send only the local part of the address to the remote server.

  Address Processing without the `.via` suffix
  `user @ client1.host` | Router converts to | `user%client1.host @ relay`
  `user%client1.host @ relay` | Router converts to | `user%client1.host @ host.com`
  `user%client1.host @ host.com` | Router stops | no rule for host.com
  `user%client1.host @ host.com` | Router accepts | for SIP/SMTP `host.com` host as `user%client1.host@host.com`
  Address Processing with the `.via` suffix
  `user @ client1.host` | Router converts to | `user%client1.host @ relay`
  `user%client1.host @ relay` | Router converts to | `user%client1.host @ host.com.via`
  `user%client1.host @ host.com.via` | Router accepts | for `host.com` as `user@client1.host`

If the domain part of the address contains the `.via` suffix, the module checks the last domain name part after removing this suffix. If that part is a number, the dot (`.`) symbol separating this part is changed to the colon (`:`) symbol:

host.domain.dom.26.via --> host.domain.dom:26 When the domain name contains a colon symbol, the SIP and SMTP modules:

- Do not use DNS MX/SRV records for that name, and retrieve the DNS A-records only.
- Use the number after the colon symbol as the number of the TCP port to connect to, instead of using the standard port number (25 for SMTP, 5060 for SIP).

The Router also checks if the domain part of the address ends with the `.relay` suffix. This suffix is removed and the resulting domain name is used as the target host name (after changing the optional port name separator to the colon symbol).
This domain name (after removal of the optional port name and its separator) is added to the local name, using the `@` symbol as the separator.

Example:
  The Server Main Domain is `company.com`.
  E-mails and Signals for the `xxxx.department.company.com` domains (where xxxx can be sales, marketing, etc.) should be sent to separate servers, according to their DNS records, while addresses in all other subdomains of company.com should be processed as addresses in the Main Domain, i.e. user@subdomain.company.com addresses should be processed as user@company.com addresses.
  You can implement this routing using the following records:
  *.sales.company.com = *.sales.company.com.relay ; explicitly relay outside
  *.company.com = company.com ; all other subdomains are rerouted

## Routing to Real-Time Applications

Many Signals (especially phone calls) should be handled with the "stock" or custom Real-Time Applications. To Route a Signal to an Application you need to specify the Application name and, separated with the hash (`#`) symbol, the name of the Account that will be used to run the application:

The following record routes Signals sent to the someName@someDomain address to the application `myProgram` started on behalf of the `user@domain` Account:
  <someName@someDomain> = myProgram#user@domain

You can specify the application parameters by adding them after the application name, enclosed into the `{` and `}` brackets and separated with the comma (`,`) symbol.

The following record routes Signals sent to the someName@someDomain address to the application `myProgram` started on behalf of the `user@domain` Account. The program is started with 2 parameters - "mixer" and "fast":
  <someName@someDomain> = myProgram{mixer,fast}#user@domain

The wildcards in the right part of a Router record are substituted before any processing begins, so you can use the wildcard value as the application parameter.

The following record routes Signals sent to the `+(20d)@someDomain` addresses to the application `myProgram` started on behalf of the `user@domain` Account. The program is started with a parameter. The parameter is the catenation of the string `num=` and the wildcard value - the phone number without the leading `+` symbol:
  <+(20d)@someDomain> = myProgram{num=*}#user@domain

## Phone Number Routing

If the domain part of an address is `telnum`, the address local part is processed as a E.164 phone number.

The following steps are taken by the Router before it applies its Routing Table(s) and other routing methods:

- The Router checks if the phone number is assigned to any Account in any CommuniGate Pro Domain. If such an account is found, the Signal is redirected to that Account. See the Accounts section for more details on Assigned Phone Number.
- The Router applies the ENUM Routing method, using all Telephony ENUM DNS domains specified. In a Dynamic Cluster environment, the Server-wide ENUM domains are checked first, then the Cluster-wide ENUM domains are used.

If the phone number is not rerouted by any of the above methods, the Router processes it as a regular address.

Phone Number ENUM Domains

To add a ENUM domain, enter its name into the empty field, and click the Update button.
To remove a ENUM domain, remove its name from the field and click the Update button.
Domains are used in the specified order.

See the PSTN section to learn more about PSTN and telephone number routing.

## Routing by IP Addresses

After all Routing Table records are applied, the Router checks if the domain name is actually an IP address. If the IP-address domain name is not enclosed into the square brackets, the Router encloses it: `user@10.34.45.67` is converted into `user@[10.34.45.67]`. This allows you to specify Routing Table records for IP addresses assuming that the address is always enclosed into square brackets.

For IP addresses enclosed in square brackets, the Router checks if the IP address is assigned to one of this Server Domains. If a Domain is found, the IP address is substituted with that Domain name. If the IP address is the IP address of the Server Main Domain, an empty string is placed into the domain name part, and the Router makes the next iteration after parsing the local name part of the address.

If an IP address is not assigned to a local Domain, the Router processes the `[10.34.45.67]` domain name as the `10.34.45.67.default_port.via` name:
the Router sends the address to the SIP or SMTP module, cutting off the domain part and using it as the host name to relay to.

## Routing via Modules

If no Routing Table record can be applied to an address, and the address is not a special address or an IP address of a local domain, the Router calls each communication module requesting a routing operation.

Each module looks at the address passed and can:

- ignore the address if the module does not know how to handle it;
- modify the address (for example, the LIST module converts addresses `listname-admin@listdomain` into the real address of the mailing list owner);
- reject the address (for example, the Local Delivery module rejects `username@domainname` addresses if the domain name is a name of a local domain, and there is no username Account or Alias in that domain);
- accept the address.

If a module has modified an address, the Router makes a new iteration, repeating all steps for the new, modified address.

If the Router is called from the Message Enqueuer component, and a module has accepted the address, the message is enqueued to this module for delivery.

If the Router is called from the Signal component, and a module has accepted the address, the Signal Request is sent to this module for processing.

Each module is called twice. First, the Router calls each module asking to process "obvious" addresses. On this call the modules process only the addresses that are definitely directed to that module: the SMTP module processes addresses with the domain part ending with `.smtp`, the LIST module processes the addresses of the exiting mailing lists, etc.

If all modules have ignored an address, the Router calls each module again, asking for a "final" attempt. On that stage, the Local Delivery module processes all addresses directed to local domains, the SIP module accepts all signal-type addresses, the SMTP module processes all addresses with domain names that have at least one dot, etc.

This two-step method allows several modules to correctly process addresses without relying to a particular module call order. If each module would process an address in one step, `listname@domainname` addresses (that look like Local account addresses), would be rejected with the Local Delivery module if it is called before the LIST module, `user@accountName.local` addresses would be taken with the SMTP module instead of the Local Delivery module, etc.

See the module descriptions for the details.

## External Helper Routing

After all Routing Table records are applied, the Router checks if the domain name is the `external` string. In this case, the domain part is cut off, and the local part is passed to the External Authenticator program.

The external program can use any method to process the supplied address, and it should return a modified address or an error code.

If a modified address is returned, the Router makes the next iteration with this new address.

Example:
  Signals to addresses starting with `011` in any local Domain should be routed using an external Helper program.
  You can implement this routing using the following record:
  NoRelay:Signal:<011*@*> = tele-*@external ; route using an external program

  If a Signal is sent to 0115556666@local.domain.dom, where local.domain.dom is a local Domain, the address will be rerouted to tele-5556666@external and the External Helper will receive a request to route the tele-5556666 address.

## ENUM Routing

The Router supports DNS-based routing for telephone numbers. This method is usually applied to E.164 numbers - telephone numbers starting with the plus symbol followed with the country code, area code, and the local number.

If the domain name has the `.enum` suffix, then the Router:

- follows RFC2916 and issues the DNS NAPTR request for the number in the address local part, using the domain name (without the `.enum` suffix) as the search suffix.
- processes all result records of the `E2U+SIP` type for Signal-type addresses, or the E2U+EMAIL for other addresses.
- if the found mapping string starts with the `sip:`, `sips:`, `mailto:` prefix, removes the prefix.

The Router restarts, processing the found mapping string as the new destination address.

If the DNS search returns the "unknown host name" error, the `.enum` domain name suffix is replaced with the `.noenum` suffix, and the Router restarts to process the modified address.

Example:
  Router records:
  <+(d)@*> = +*@telnum ; direct +number to e164 "telnum" domain
  telnum = e164.arpa.enum ; direct +number to e164.arpa
  e164.arpa.noenum = pstn
  <+44*@pstn> = gatewaycaller{+44*}#pbx
  pstn = main.office.dom

  A sample address +14153837164@some.local.domain.dom will be processed using the following steps:
  - The first Router record converts this address to `+14153837164@telnum`
  - The second Router record converts this address to `+14153837164@e164.arpa.enum`
  - The Router looks for a DNS NAPTR record `4.6.1.7.3.8.3.5.1.4.1.e164.arpa`
  - The resulting record `sip:pbx@communigate.com` is found, the `sip:` prefix is removed, and the Router restarts to process the `pbx@communigate.com` address

  A sample address +14155551212@some.local.domain.dom will be processed using the following steps:
  - The first Router record converts this address to `+14155551212@telnum`
  - The second Router record converts this address to `+14155551212@e164.arpa.enum`
  - The Router looks for a DNS NAPTR record `2.1.2.1.5.5.5.5.1.4.1.e164.arpa`
  - There is no NAPTR record for this domain name, so the address is converted to `+14155551212@e164.arpa.noenum` and the Router restarts to process this address
  - The third Router record converts the address into `+14155551212@pstn` and the Router restarts to process this address
  - The fourth Router record directs all calls to the `+44` country code to the local `gatewaycaller` PBX application, but this record does not match the `+14155551212@pstn` address
  - The fifth Router record redirects this address to `+14155551212@main.office.dom` so the Signal is relayed to the `main.office.dom` server.

## `tel:` Routing

When a `tel:phoneNumber` URI is being parsed, it is converted into `sip:phoneNumber@tel` URI internally. The fictitious `tel` domain is usually routed to the `telnum` domain (see above) to provide unified handling of all phone numbers.

When composing a URI from an internal form, any `sip:phoneNumber@tel` URI is composed as `tel:phoneNumber`.

## Default Records

When the CommuniGate Pro Server is installed, the following records are placed into the Routing Table:

<root> = postmaster
  This record reroutes all E-mails and Signals sent to the `root` name to the postmaster Account.
  This is useful on Unix systems, where many logging utilities are preconfigured to mail reports to the user `root`.
localhost =
  On many systems the `localhost` domain name used for the local IP address of that system, and some mailer programs use this name as a domain name.
  This record routes addresses within the "localhost" domain to the main server domain.
mailhost =
  Some mailer programs use the `mailhost` name as the domain name of the local mail server.
  This record routes such addresses to the Accounts in the CommuniGate Pro Main Domain.
<blacklist-admin*@blacklisted> = postmaster
  This record implements White Hole processing for blacklisted hosts.
<\*(3-4d)@*> = voicemail#*
  This record redirects all Signals (calls) sent to `*nnn` and `*nnnn` addresses in any local Domain to the PBX Voicemail application started for the Account with the nnn alias.
<7(2d)@*> = pbx{*}#pbx
  This record redirects all Signals (calls) sent to `7nn` addresses in any local Domain to the pbx Account in the same Domain.
  This Router record is needed to implement certain functions of the stock PBX Center application.
<8(3d)@*> = pickup{*}#pbx
  This record redirects all Signals (calls) sent to `8nnn` addresses in any local Domain to the pbx Account in the same Domain, starting the `pickup` application. The application then routes the nnn@callerDomain address and "picks up" an incoming call pending for that Account.
  See the PBX Services section for the details.
tel = telnum
  This record is used to process `tel:phoneNumber` URIs (see above).
<+(8-20d)@*> = +*@telnum
  This record redirects all `+nnnn...nn` addresses in any local Domain to the fictitious `telnum` domain.
Signal:telnum = pstn
  This record redirects all Signals (calls) sent to the fictitious domain `telnum` to the fictitious `pstn` domain.
Signal:<*@pstn> = gatewaycaller{*}#pbx
  This record redirects all Signals (calls) sent to the fictitious `pstn` domain to the `gatewaycaller` application started on behalf of the `pbx` Account in the Main Domain.
  The phone number (the local part of the address in the `pstn` domain) is passed to the application as a parameter.
Signal:<911@*> = emergency@localhost
  This record redirects all Signals (calls) sent to the `911` addresses in any local Domain to the `emergency` name in the `localhost` domain (this name is usually Routed to the Main Domain).
Signal:<112@*> = emergency@localhost
  This record redirects all Signals (calls) sent to the `112` addresses in any local Domain to the `emergency` name in the `localhost` domain (this name is usually Routed to the Main Domain).
Signal:<emergency> = emergency#pbx
  This record redirects all Signals (calls) sent to the `emergency` addresses in the Main Domain to the `emergency` application started on behalf of the `pbx` Account in the Main Domain.
Signal:<(7d)@*> = localAreaCall{*}#pbx@localhost
  This record redirects all Signals (calls) sent to 7-digit numbers in each local Domain to the `localAreaCall` application started on behalf of the `pbx` Account in the Main Domain.
  The phone number (the local part of the address) is passed to the application as a parameter.

All these default records can be modified or removed, if needed.

## Extending Non-Qualified Domain Names

Users working on sites that have many different Servers (`server1.myorg.org`, `server2.myorg.org`, `server3.myorg.org`) tend to use addresses with non-qualified domain names (`user@server1`, `user@server2`, `user@server3`). When you have only few servers in your myorg.org "upper level" domain, you can "fix" those addresses by specifying several Router Table records:

server1 = server1.myorg.org
server2 = server2.myorg.org
server3 = server3.myorg.org

If you have many servers in your myorg.org "upper level" domain, it becomes impossible to provide Router Table records for all of them. In this case you may want to enable the Add `myorg.org` to Non-Qualified Domain Names option. If this option is enabled, and an address cannot be routed using CommuniGate Pro Router Table and Modules, and the domain part of the address does not contain a dot symbol, the specified string (`myorg.org`) is added to the address domain name (separated with the dot symbol). The address `user@someserver` will be converted to the `user@someserver.myorg.org` address and the Router will try to route this new, corrected address.

Note: It is a very bad practice to use non-qualified domain names in E-mail or Signal addresses. Enable this option only if you can not enforce a policy that requires your users to specify correct, fully-qualified domain names in all addresses they use.

## All-Domain Aliases

All-Domain Aliases
Local Name | Reroute to
--- | ---

This table allows you to specify aliases that will work for all local Domains.

When the CommuniGate Pro Server detects that a message or a signal should be directed to some name in one of the Server local domains, these records are checked. If the local part of the address matches the Local Address field in one of these records, the address is rerouted to the address specified in the Reroute To field.

If, for example, the `abuse` and `postmaster@maindomain.dom` addresses are entered into the All-Domain Aliases table (as shown above), then all messages directed to any `abuse@domain.dom` address (where domain.com is one of the CommuniGate Pro Domains) are rerouted to the `postmaster@maindomain.com`.

Note: it is very easy to create routing loops using these records: if you enter

  `postmaster -> postmaster@maindomain.dom`

into this table, you will create a loop that will make it impossible to connect to the Server as `postmaster`. If you want E-mails and Signals to all `postmaster` names in all Domains to go to the postmaster account in the main CommuniGate Pro domain, you should use:

  `postmaster -> anyname@postmaster.local`

or, if the Direct Mailbox Addressing option is enabled:

  `postmaster -> mailboxName#postmaster`

You can use wildcard (`*`) symbols in these fields.

For example, you may want to create a "dial plan" for your organization that has 10 different departments, each served with its own Domain:

All-Domain Aliases
Local Name | Reroute to
--- | ---

If Accounts in each Domain have aliases in the `200-299` range, then the users can call other users within the same Domain by dialing the `2xx` number.
They dial the `91` prefix (a `912xx` number) to reach users in the domain1.com Domain.
They will use the `92` prefix to reach users in the domain2.com Domain, etc.

## Cluster-wide Routing Table

The CommuniGate Pro Dynamic Cluster maintains the Cluster-Wide Routing Table. When you open the Router WebAdmin page on any Cluster member, you see the link that opens a Cluster-Wide Routing Table page. All modifications made to this Table are automatically propagated to all Cluster Members.

The Cluster-Wide Router Table is processed as an extension of the Server Router Table: the Cluster-Wide Router Table records are checked when no Server Router Table record can be applied.

CommuniGate® Pro Guide. Copyright © 1998-2012, Stalker Software, Inc.