The lookup is a handy thing to master when it comes to Exim. I would put this as one of the most useful tools in your basket. The more you use Exim, the more you'll be using the lookup.

There are two basic types of lookups and their syntax is slightly different. Although, it is fairly straight forward.

• Single Key - lookup a key in a file or file type database and retrieve data associated with that key.
• Query Style - lookup a dataset in a relational database.

I would recommend mastering the basic lookup strategy before getting complicated. However, lookup can get complicated.

The Syntax for the single key lookup goes like this:

${lookup \
   {KeyYouAreLookingUp} \
   LookupType{WhereToFindIt} \
}

An alternate syntax would return one value if the lookup was a success and another if it failed. Like in an acl condition...

${lookup /
   {KeyYouAreLookingUp} /
   LookupType{WhereToFindIt} /
   [{ValueIfFound}] /
   [{ValueIfNotFound}] /
}

The Key can be any key you want to lookup. Most always a variable.

The lookup type is going to be one of these...

• cdb - Constant DataBase (a fast lookup utility available on most linux systems)
• dbm - key value file format
• dbmjz - (joined zero) key value file format but the lookup key is an Exim list joined with an ASCII 0 or null character
• dbmnz - (no zero) key value file but the terminating null is not included in the call to the dbm library
• dbmnzdesarch desarch - Directory Search
• iplsearch - key value file format but the keys are ip addresses terminated by a colon
• json - text file with a json structure
• lmdb - lightning memory mapped database
• lsearch - linear search
• nis - NIS map
• wildsearch/nwildsearch - lsearch but allows wild cards

A real life example would be looking up a domain in a file...

${lookup {$domain} lsearch{/path/to/list/of/domains}}

cdb, dbm*, lmdb, nis are binary formats with their own libraries to access them. These files and faster to access than text files which are useful in high volume situations. Information on the mechanics and how to use them can readily be found on the web. Search for the file extention.

The rest... ipsearch, lsearch, json, wildsearch and nwildsearch all use text files. Text files that should be in a somewhat standard format.

Facts about the file layout...

• Empty lines and lines are ignored.
• Lines begining with # are ignored.
• Each line in the file begins with the key.
• The key is terminated by whitespace (any kind), a colon or end of line
• The first matching key in the file is used.
• The search is NOT case sensitive.
• If the data begins with a colon (:) the key must be terminated with one.
• Any white space around the data is removed.
• The data can span multiple lines as long as subsequent lines begin with white space

key1: Data For Key 1
key2: Data For Key 2
key3: :Data For Key 3:
keyn: :Data::For::Key::n:

However, if you looking up a key in a file just to see if it is there, you can forget the colon. Example... a list of ip addresses:

1.2.3.4
5.6.7.8
10.11.12.13
14.15.16.17

Adding the word partial- in front of any single-key lookup type allows the lookup to match on part of the key.

First the lookup file needs to have astrisks in front of the keys...

*.example.com
*.leistware.com
*.kenny-l.com

Now the lookup type should have the partial keyword in front of it...

${lookup \
   {$sender_address_domain} \
   partial-lsearch{/path/to/bad/addresses} \
   {true} \
   {false} \
}

If the senders domain is email.leistware.com then Exim will lookup that domain in the file first. When it fails it will remove the first part of the domain... i.e. email and look for *.leistware.com which will find a match.

It will do this down to two elements (the default) unless you specify a different amount after the partial keyword. Example: partial3- will search down to three elements. partial1- will search down to one element.

Query Style lookups are basically the same with the exception of the query which is different.