Lookup is generalized interface for searching objects and receiving their values. Values are separated by commas. Some values have a prefix denoting a specific type of Lookup. The prefix is separated by a colon:
[prefix1:]value1, [prefix2:]value2, ...
If a prefix is not specified, values are used directly.
Special symbols
You can use the following special symbols in Lookup queries:
•$s - is substituted with the requested element. For example, if an address is requested, $s is substituted with the full address (without angle brackets), if a domain is requested, $s is substituted with the domain name.
•$d - if an address is requested, $d is substituted with the domain part of this address. Otherwise, the full address is inserted.
•$u - if an address is requested, $u is substituted with the username from this address. If a domain is requested, an empty string is inserted.
•$$ - is substituted with a single $.
|
Note that in some cases values of special symbols cannot be determined for substitution during Lookup. Primarily it concerns parameters used by Receiver component to check SMTP restrictions (SMTP/LMTP on the INTRO stage of SMTP-session (connection of a client). On this stage: •For all checks whether the client's IP address is in the network list (see the ProtectedNetworks parameter in the [Maild] section): o$s – IP address of the connected client. o$d, $u – empty as the corresponding value is not determined. •For all checks whether the client's domain is in the domain list (see the ProtectedDomains parameter in the [Maild] section): o$s – domain name of the client's host (if FQDN was resolved), otherwise - its IP address. o$d = $s. o$u – empty as the corresponding value is not determined. On next SMTP session stages (MAIL FROM, RCPT TO) values of all special symbols are determined: o$s – full address of user@domain. o$d – domain (domain part of the address). o$u – user name (user part of the address). |
Prefixes
You can use the following prefixes to specify a data source:
•value - specify the requested value after this prefix. This is default prefix and can be skipped. You can use this prefix when, for example, the value contains ':' symbol.
•file - the value is a file path. Each value in the file must be set in a separate line. That allows rapid searching, because assortment and binary search can be used.
|
Please note that for parameters having special restricted type LookupLite, allowed only these two prefixes, and other prefixes, presented below, are prohibited! |
•regex - the value is a regular expression (compatible with Perl regular expressions) - the object is searched by a substring, absolute matching is not required.
•rfile - the value is a file path. The file contains a set of regular expressions (compatible with Perl regular expressions), and each of them must be set in a separate line. The object is searched by a substring, absolute matching is not required.
|
Please note that contents of files used as data source of file and rfile types are not checked in advance. Before using the files, ensure that: •files are of the text type (contain only text lines); •files do not contain empty and "garbage" lines (such as separators or comments) which cannot be used as Lookup values; •regular expressions (for rfile) are given correctly to match the Perl regular expressions syntax; •files do not contain superfluous data; •file size is not too large, as when a file of large size is read, a memory allocation error can occur (in this case, Dr.Web MailD is terminated). |
•ldap - the value is the path to the LDAP server. The value is set in the following format:
[param1=val1|param2=val2|...|] ldap_url
where ldap_url – is an URL of LDAP query. Specify param1, param2 and others to override their values in the Lookup query (the values are set in the [LDAP] section of Dr.Web MailD configuration file). You can specify only those parameters, for which this option is explicitly stated (see description of the section parameters). For parameters that are not specified, values from the [LDAP] section of Dr.Web MailD configuration file are used.
URL of LDAP query (ldap_url) is as follows:
ldap://hostport/dn[?attrs[?scope[?filter[?exts]]]]
where:
ohostport - host name (can be specified with a port number separated by a colon - ":portnumber");
odn - database name where search is performed;
oattrs - comma separated list of request attributes;
oscope - can have one of the following values: base, one, sub;
ofilter - filter name;
oexts - set of LDAP and/or API extensions.
Example:
ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*)
•odbc, postgres, oracle, mysql, firebird, sqlite – the value is an SQL-query to the database in the corresponding DBMS (for ODBC – to DSN data source). SQL-query is of the following format:
[param1=val1|param2=val2|...|] sql_request
where sql_request – is a text of SQL query to the database and param1, param2 and others are parameters from the [<DATASOURCE>] section of Dr.Web MailD configuration file for the given Lookup (<DATASOURCE> – is name of used DBMS or ODBC, and is always equal to prefix which is used in the given Lookup: that is, [ODBC], [PostgeSQL], [Oracle], [MySQL], [Firebird], [SQLite]). From this section, only those parameters can be specified, for which this option is explicitly stated (see description of the section parameters). Pairs param=value must be included only if it is necessary to override their values in the given Lookup query. For parameters that are not specified, values from the [<DATASOURCE>] section of Dr.Web MailD configuration file are used.
You can use special symbols as in the Lookup queries.
|
Important notes: 1.If a SELECT query returns records which contain more than one string (query of the following type: SELECT field1,field2,... FROM ...), all strings returned by DBMS are assigned to Lookup values. It is not recommended to use such queries because different DBMS can return such responses in different formats (some DBMS separate fields with a whitespace, some – with a comma or semicolon). 2.Lookups with the sqlite prefix are used for interaction with SQLite version 3.x. See also notes on features of working with SQLite DBMS |
•cdb – the value is an alphanumerical name of the key in the CDB database. CDB database does not support the SQL query input language, that is why driver emulates the single SQL command for operating with lookups:
select * from @tablename where key='@string'
where @tablename must be changed to the name of any file specified as a source item in the [CDB] section of Dr.Web MailD configuration file.
You can use special symbols in Lookup queries.
Example:
cdb:skipdomains=regex:^inbox|select * from my_file where key='$s'
Note that the SkipDomains parameter, locally overridden in this Lookup, is of the LookupLite type (that is, Lookup for whoch only file: and value: prefixes are allowed).
•berkeley – enables interaction with Berkeley DB. Format of the query is similar to that of cdb prefix. Parameters from the [Berkeley] section of Dr.Web MailD configuration file are used.
You can use special symbols as in the Lookup queries.
Local overriding of parameters in Lookup queries
After a prefix, you can optionally specify a list of values for the SkipDomains and OnError parameters to be used in this Lookup. The local values are specified in the following format:
NAME1 = VALUE1 | NAME2 = VALUE2 | ... |
where:
•NAME - case-insensitive parameter name;
•VALUE - parameter value.
If a parameter is not locally overridden in a Lookup, their default values or values from the corresponding [<DATASOURCE>] section of Dr.Web MailD configuration are used (where <DATASOURCE> corresponds to the Lookup prefix).
|
Note that usage of SkipDomains in Lookup has no meaning if the Lookup is to determine parameter values on those SMTP session stages when the domain cannot be determined (that is, $d special symbol is empty). Domain cannot be determined on the INTRO stage of SMTP session (see above). |
Features of Lookups processing
Please note that during Lookup processing, Dr.Web MailD waits for connection to a data source (DBMS or LDAP server) during a timeout specified in the the data source settings or overridden locally in the Lookup prefix. This can slow down the performance of Dr.Web MailD if the network connection is not stable or specified connection parameters are incorrect.
If connection attempt fails during the timeout, the error is fixed and processed according to the OnError parameter value specified either in the data source settings or overridden locally in the Lookup prefix.
If a Lookup is used as the Router parameter value (specified in the [Sender] section) and the OnError=exception error handling mode is used (this mode can be set in the data source settings or locally overridden in the Lookup value expression), the state when Sender cannot receive required route from the used data source is handled as an error in Sender operation. Error message is logged. In this case:
•in the synchronous mode, Receiver returns the SMTP error code 451 (Requested action aborted: local error in processing) to the message sender, and the email message is deleted from all queues of Dr.Web MailD.
•in the asynchronous mode, the message is marked as 'stalled' and Sender tries to send it at intervals specified in the StalledProcessingInterval parameter value.
|
Incorrect Lookup string can cause Dr.Web MailD to terminate on its startup (when reading a configuration file) if Dr.Web MailD cannot parse the Lookup string structure and recognize the type. It is recommended to use a special utility for testing correctness of Lookups. Note that full information on queries to data sources sent via Lookups is output only if the log verbosity level is not less detailed than DEBUG. |