Router

Intro
Installation
SysAdmin
Network
Objects
Transfer 
Router
Rules 
VirusScan 
SMTP 
Local 
RPOP 
LIST 
PIPE 
Access
Services
Directory
Data Files
Clusters
WebApp
WebMail
Miscellaneous
HowTo
HelpMe
Licensing
This chapter is for advanced administrators only. In most situations the default routing methods are enough. Only if your Server is working as a message relay for other systems, or it has to support several domains, or if you want to use sophisticated routing schemes, should you read this chapter.

When the Server processes a submitted message, it extracts the information about recipients from the message "envelope" and places the message into the queues of the communication modules. The part of the Server kernel that does this job is called the Router.

Domain and Local Parts of E-mail Addresses

Each E-mail 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.
An E-mail address can be more complicated, for example, an address can include some path information:
<@zzzz:xxxx@yyyyy> or zzzz!yyyyy!xxxx or xxxx%yyyyy@zzzz
These addresses specify that a message 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 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.

Note: if the local part contains a complex address (i.e. it also contains domain name(s) and a local part), the local part is presented in the '%' notation: local%domain1%domain2. This information can be used for sophisticated aliasing methods.


Mail 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 stalker.com, then the following addresses will be converted as shown:

E-mail addresslocal partdomain part
support@stalker.com support stalker.com
-- routed --> support  
 
 <@stalker.com:sales@gamma.com>   sales@gamma.com stalker.com
-- routed --> sales@gamma.com  
-- routed --> sales gamma.com


Multiple Domains. MX records

Your server may receive and process E-mail messages directed not only to the Main Server Domain set in the General settings, but sent to other domains, too. If your server has to process mail for a certain domain, you should ensure that the messages sent to that domain comes to your server.

For example, your server (mycompany.com) may act 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 messages sent to the client1.com domain will be routed to the Unified Domain-Wide Account client1, etc. But you should also ensure that when a message is sent to the client1.com domain, that message is routed to your server (mycompany.com).

Internet mail routing is controlled with the DNS - Domain Name System. Domain Name Servers contain the information about each domain name. So, when the client registers the client1.com domain name, the client should have an MX (mail exchange) DNS record created and that record should point to your Server domain - mycompany.com.


Routing Table

When an address is parsed and the domain part is extracted, and that name is not the Main Domain Name of your Server, the Router checks the routing records in the Routing Table.

Open the Router page in the Settings section of the WebAdmin Interface to manage the Routing Table:

fax.stalker.co      = stalker.com       ; -> to the same domain
hq.stalker.com      = newhq.stalker.com ; -> to some other server
Relay:*.test.com    = stalker.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 the left part, the equals sign (=) and the right part. The semicolon sign (;) 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 sign.

The Router takes a parsed E-mail 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 local and/or domain parts are processed with the Router from the beginning.

Any Routing record can contain the Relay: prefix (can be shorten to R:), the NoRelay: prefix (can be shorten to N:) or the RelayAll: prefix. See the Protection section for the details. If no prefix is specified, the Relay: prefix is assumed.

A Routing record can contain one of the following prefices:

Log
The CommuniGate Pro Router has the Log Setting that you can modify using a Web browser. 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.


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.stalker.com = twisted.stalker.com
All messages directed to the domain name hq.stalker.com will be redirected to the domain twisted.stalker.com. The Router restarts, trying to find a path to deliver messages to twisted.stalker.com.

A routing path can specify relays.

Example:
hq.stalker.com = hq.stalker.com@relay.stalker.com
All messages directed to the domain name hq.stalker.com will be redirected to the domain relay.stalker.com, and then, from that machine, to the domain hq.stalker.com.

If mail to several domains should be routed in the same or similar way, you may use the asterisk sign as the wild-card symbol.

Example:
*.old_company.com = new_company.com
In this case messages to all the domains ending with .old_company.com will be routed to the domain new_company.com, 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 messages sent to all subdomains of its Main Domain as messages sent to the Main domain, the address user@mail.mycompany.com will be processed as the user@mycompany.com address.

The asterisk symbol can be used in the right path, in this case it is substituted with the symbols matching the wildcard symbol in the left part.

Example:
*.old_company.com = *.new_company.com
When such a routing line is entered and a message comes for the domain host5.old_company.com, it is routed to host5.new_company.com.

In most cases, the wildcard symbol is the first symbol in the domain name, but it is allowed to be used anywhere:

system-*.mycompany.com = uu*.local
This routing line will redirect system-abc.mycompany.com to uuabc.local.

Only one wildcard symbol is allowed in one routing record.

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


Account-Level (Alias) Routing Records

If the left part of a routing record contains an E-mail address in the angle brackets (< and >), the record specifies an alias - a routing rule for a specific address.

When an E-mail address is parsed and the Router scans the Table records, it compares the address domain part with the domain part of all alias records met. If the domain parts match, the Router compares the local part of the address with the local part of the alias record address. The local part of the alias record address can contain a wildcard symbol (*). If both domain and local parts match, the right part of the alias routing record is used as the new address. The Router restarts from the beginning, parsing and processing this new address.

Note: Because the Server Main Domain Name in the parsed address is immediately replaced with an empty string, alias 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 alias for the local name xxxx, there is no need to actually register the real xxxx account with the Server. Additionally, that real account would be useless, since no message will ever be stored in that account: everything directed to the xxxx name is routed elsewhere.

Note: the Router Alias record:

<sales@mycompany.com> = Bill
will never work: the alias records should NOT contain the name of the Server Main Domain.

The right side of an alias record can be any E-mail 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 the alias 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 messages sent to dept-sales@mycompany.com to the user postmaster at the sales-dept.mycompany.com department mail server.

You can use Router Alias records to reroute mail 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 Router Alias Records: if you need to provide an alternative name for an account in the main domain, use Account Aliases instead. If you need to re-route all mail sent to some name in a local domain to some external address, use Forwarders instead.

Sometimes it is necessary to create an alias for a specific account on a foreign system. For example, all 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:
<sales@client1.com> = sales-client1
client1.com = new.client1.com
These records route all messages 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 @ sign).

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-*

Mail to sales@client5.com address will be stored on your server in the cl5-sales Main Domain account, messages to info@client5.com address will be stored in the cl5-info Main Domain account, while messages to sales@client7.com address will be stored in the cl7-sales Main Domain account.

This method can be used when you do not want to create full-scale CommuniGate Domains for many domains that should host 1-2 accounts.


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 marked as "delivered" without any processing. This 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 the "Blacklisted Address" error report.

Example:
bad.company.com = error
<junk> = error
With these records entered, the Server will reject 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 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 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
Mail to all subdomains of the xyz.com domain is rerouted to the subdomains of the abc.com domain, except for mail to dept1.xyz.com and dept2.xyz.com subdomains which is routed to the local dept1.xyz.com and dept2.xyz.com CommuniGate Pro domains.


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 a dedicated IP address of some secondary domain. If a secondary 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.


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:

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 an address, the message is enqueued to this module for delivery.

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 created 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 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 E-mail 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 details.


Default Records

When the server is first installed, the following records are placed into the Routing Table:
<root> = postmaster
This record reroutes all mail to the user "root" 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 domain name "localhost" is a synonym for the local IP address of this computer, 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 main server domain.
 
<blacklist-admin*@blacklisted> = postmaster
This record implements "white hole" processing for blacklisted hosts.
All these default records can be modified or removed, if needed.


Extending Non-Qualified Domain Names

Users working on sites that have many different mail 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 E-mail 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 E-mail 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 addresses. Enable this option only if you can not enforce a policy that requires your users to specify correct, fully-qualified domain names in E-mail addresses.


All-Domain Aliases

All-Domain Aliases
Local AddressReroute To
This table allows you to specify aliases that will work for all local Domains. When the CommuniGate Pro Server detects that a message 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 message 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 mail 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


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-2005, Stalker Software, Inc.