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 or a socket path 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 supplied by Net::LDAP: 389, or 636 if using TLS/SSL) localaddr : Will be passed to IO::Socket as the "LocalAddr" parameter, which sets the client's IP address (as opposed to the server's IP address.) (Default: undef (i.e. unspecified)) scheme : Connection scheme to use when not using an URI as "HOST", possible values are: 'ldap', 'ldaps', or 'ldapi'. (Default: 'ldap', unless a hostname starts with a string 'ldaps', in which case the default scheme is 'ldaps') inet6 : Try to connect to the server using IPv6 if "HOST" resolves to an IPv6 target address. If it resolves to an IPv4 address, the connection is tried using IPv4. (Default: 1 if a module IO::Socket::INET6 is available, 0 otherwise) version : The protocol version to use. (Default = 3) timeout : Timeout (in sec) passed when connecting the remote server. (Default = 120) 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))') deref : By default aliases are dereferenced to locate the base object for the search, but not when searching subordinates of the base object. This may be changed by specifying a "deref" parameter with one of the following values: 'never', 'search', 'find', 'always'. (Default = 'find') bind_dn : If binding is needed, this specifies the DN to bind as. (Default = undef) bind_password : Binding password. (Default = undef) sasl : Enable SASL if true. (Default = 0) sasl_mech : A space-separated list of SASL mechanisms. (Default = '') sasl_auth_id : SASL authentication id (e.g. a username) (Default = undef) tls : Enable TLS/SSL if true. (Default = 0) sslversion : SSL version: sslv2, sslv3, sslv2/3, tlsv1 (Default = 'tlsv1') clientcert : A filename with a client certificate. (Default = undef) clientkey : A filename with a client certificate private key. (Default = undef) cafile : A filename containing the certificate of the CA who signed the server's certificate. (Default = undef) capath : A pathname of a directory containing CA certificates. (Default = undef) verify : How to verify the server's certificate: none, optional, require (Default = 'none') 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 an 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 %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, have an explicit boolean attribute 'amavisLocal' with a value of True returned for each local domain, and False for other domains which might be present in LDAP for some reason, but are nonlocal. 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.