LDAP LOOKUPS ------------ This text contains general LDAP-related documentation. Please also see README.lookups for additional lookup information. LDAP lookups are enabled in amavisd.conf with: $enable_ldap = 1; Definitions and default values of LDAP parameters. hostname : The hostname or IP address of the LDAP server to connect to. A TCP port may be specified after the host name followed by a colon (ex. localhost:389). You can also specify a URI, such as: 'ldaps://127.0.0.1:636' or 'ldapi://%2Fvar%2Frun%2Fopenldap%2Fldapi/'. May also be a reference to an array of hosts, host:port pairs, or URI's, each will be tried in order until a connection is made. (Default = 'localhost') port : The port where LDAP sends queries. May be overridden by 'hostname'. (Default = 389 (636 if using TLS/SSL)) version : The protocol version to use. (Default = 3) timeout : Timeout (in sec) passed when connecting the remote server. (Default = 120) tls : Enable TLS/SSL if true. (Default = 0) base : The DN that is the base object entry relative to which the search is to be performed. The string may also contain a '%d' token that will be replaced by the e-mail address domain. (Default = undef) scope : Scope can be 'base', 'one' or 'sub'. (Default = 'sub') query_filter : The filter used to find the amavis account. The string must contain a '%m' token that will be replaced by the actual e-mail address. (Default = '(&(objectClass=amavisAccount)(mail=%m))') bind_dn : If binding is needed, this is specifies the DN to bind as. (Default = undef) bind_password : Binding password. (Default = undef) The desired parameters can be specified in amavisd.conf and defaults will be supplied for any parameters not specified, ex: $default_ldap = { hostname => [ 'localhost', 'ldap2.example.com' ], timeout => 5, tls => 0, base => 'ou=People,dc=example,dc=com', query_filter => '(&(objectClass=amavisAccount)(mail=%m))', }; The amavisd-new LDAP schema is available in file LDAP.schema of the distribution, and at http://www.ijs.si/software/amavisd/LDAP.schema LDAP 'search' requests all available fields from the specified directory and the result is cached (just for the duration of this mail message processing). Individual attributes can be extracted one at a time from this cache very quickly, so there is no penalty in using several calls to lookup for different attributes (for the same key) in different parts of the program. lookup_ldap() performs a lookup for an e-mail address in an LDAP directory. If a match is found it returns whatever the map returns (a reference to a hash containing values of requested attributes), otherwise returns undef. Given an e-mail address the following lookups are done by default: with $ldap_lookups_no_at_means_domain = 0 (default): - lookup for user+foo@example.com - lookup for user@example.com (only if $recipient_delimiter is '+') - lookup for user+foo (only if domain part is local) - lookup for user (only local; only if $recipient_delimiter is '+') - lookup for @example.com - lookup for @.example.com - lookup for @.com - lookup for @. (catchall) With $ldap_lookups_no_at_means_domain = 1 : - lookup for user+foo@example.com - lookup for user@example.com (only if $recipient_delimiter is '+') - lookup for user+foo@ (only if domain part is local) - lookup for user@ (only local; only if $recipient_delimiter is '+') - lookup for example.com - lookup for .example.com - lookup for .com - lookup for . (catchall) NOTE: a null reverse path e-mail address used by MTA for delivery status notifications (DSN) has empty local part and empty domain. As far as the lookup is concerned (which uses raw, i.e. non-quoted and non-bracketed address form), this address is @, i.e. a single character "@". The LDAP lookup for null address goes through the following sequence of keys: "", "@", "@." (double quotes added for clarity, they are not part of the query key). lookup_ldap_attr() also performs a lookup for an e-mail address against a LDAP directory. It first calls lookup_ldap() if it hasn't been called yet for this key, but instead of returning all available attributes, it returns just a value of one particular attribute. This is the subroutine that gets called from lookup() for arguments (objects) of type Amavis::Lookup::LDAPattr. LDAP white/black listing ------------------------ amavisWhitelistSender/amavisBlacklistSender are multivalued attributes containing either full email addresses or domain specifications. The envelope sender address is compared against each attribute value until a match is made. amavisBlacklistSender: user@example.com amavisBlacklistSender: @example.com amavisBlacklistSender: @.example.com A domain specification with a leading '@.' matches a domain as well as its subdomains. LDAP banned rule names ---------------------- amavisBannedRuleNames may contain a comma-separated list of names mapped through %banned_rules to actual banned_filename tables. amavisBannedRuleNames: ALLOW_EXE, DEFAULT <amavisd.conf> %banned_rules = ( 'NO-MS-EXEC'=> new_RE( qr'^\.(exe-ms)$' ), 'PASSALL' => new_RE( [qr'^' => 0] ), 'ALLOW_EXE' => new_RE( qr'.\.(vbs|pif|scr|bat)$'i, [qr'^\.exe$' => 0] ), 'ALLOW_VBS' => new_RE( [qr'.\.vbs$' => 0] ), 'DEFAULT' => $banned_filename_re, ); Special handling of optional LDAP attribute 'amavisLocal' --------------------------------------------------------- A special shorthand is provided when LDAP lookups are used: when a match for a recipient address (or domain) is found in LDAP tables (regardless of attribute values), the recipient is considered local, regardless of static @local_domains_acl or %local_domains lookup tables. This simplifies life when a large number of dynamically changing domains is hosted. To overrule this behaviour, add an explicit boolean attribute 'amavisLocal' (missing field defaults to true, meaning record match implies locality) The default value for local_domains_ldap lookup for the catchall key '@.' is undef under conditions: when user record with key '@.' is present in the database and the attribute 'amavisLocal' is not present. Previously it surprisingly defaulted to true, now it falls back to static lookup table defaults, the same as if the record '@.' were not present in the table. In general LDAP lookups are similar to SQL lookups except for the low level LDAP/SQL specific code. The overall functionality, lookup rules, etc. are identical.