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 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 address the following lookups are
done by 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)
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 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 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.
