3.9 Query Dispatch Rules

When a query arrives, smapd uses query dispatch rules to decide to what database to dispatch this query. Dispatch rules are somewhat similar to ACLs: each rule consists of a set of conditions and a target part. The rules are joined in a list. When applied to a particular query, this list is scanned from top down. The conditions of each rule are evaluated using the query as their argument. If all conditions return ‘True’, then the target part of this rule is applied. The target part may either transform the map name and/or key value (a transformation rule), or indicate a database to dispatch this query to (a destination rule). After applying a transformation rule, the scanning resumes at the next rule. Destination rules end the processing.

If the list is exhausted without having found a matching destination rule, smapd sends back the default ‘NOTFOUND’ reply.

Consider for example the following rule:

dispatch map eq alias database maildb

It says that if the map part of a query is the word ‘alias’, then this query must be handled by the database ‘maildb’.

The map condition allows for more sophisticated comparisons. If you use ‘like’, instead of ‘eq’, than shell-style globbing patterns are used. For example, this rule

dispatch map like us* database user

matches queries whose map part begins with ‘us’.

Finally, you may also use regular expressions:

dispatch map regexp /(alias)|(virtusers)/ database maildb

See The map condition, for a detailed description of this condition.

Another important condition is from. It returns ‘True’ if its argument, which is an IP address or a CIDR, matches the IP of the machine that sent the query. For example, the following rule directs all queries coming from IP addresses 192.168.0.1 through 192.168.0.31 to the database ‘local’:

dispatch from 192.168.0.0/27 database local

Several conditions may be used together. The result is ‘True’ if all conditions yield ‘True’. For example:

dispatch from 192.168.0.0/27 \
         map regexp /^(alias)|(virtuser)$/ \
         database local-maildb

This rule dispatches to the database ‘local-maildb’ all queries coming from the network 192.168.0.0/27 and having ‘alias’ or ‘virtuser’ as their map part.

The server condition is often used together with from. Its argument is the id of a server (see server id) declared in the configuration. The condition returns ‘True’ if the query was sent to that particular server. For example:

dispatch from 192.168.0.0/27 \
         server privileged
         database secret
dispatch from 192.168.0.0/27 database public

These rules dispatch to the database ‘secret’ any queries coming from IP address in network 192.168.0.0/27 and received by the server ‘privileged’. Queries from that network accepted by another servers are dispatched to the database ‘public’. It is, of course, supposed that somewhere in the configuration file there is a declaration, that looks like

server privileged inet://192.168.0.1:3145

The result of any condition may be reverted using the ‘not’ prefix before it, e.g.:

dispatch from 192.168.0.0/27 \
         not map regexp /^(alias)|(virtuser)$/ \
         database user

There is a special condition which is convenient for the last rule in the list. The ‘default’ condition always returns ‘True’, so this rule:

dispatch default database nomap

will match any rule and dispatch it to a database named ‘nomap’. The ‘default’ condition cannot be combined with other conditions.