4
This text contains general LDAP-related documentation. Please also
5
see README.lookups for additional lookup information.
7
LDAP lookups are enabled in amavisd.conf with:
11
Definitions and default values of LDAP parameters.
13
hostname : The hostname or IP address of the LDAP server to
14
connect to. A TCP port may be specified after the
15
host name followed by a colon (ex. localhost:389).
16
You can also specify a URI, such as:
17
'ldaps://127.0.0.1:636' or
18
'ldapi://%2Fvar%2Frun%2Fopenldap%2Fldapi/'.
19
May also be a reference to an array of hosts,
20
host:port pairs, or URI's, each will be tried in
21
order until a connection is made.
22
(Default = 'localhost')
23
port : The port where LDAP sends queries. May be overridden
25
(Default = 389 (636 if using TLS/SSL))
26
version : The protocol version to use.
28
timeout : Timeout (in sec) passed when connecting the remote
31
tls : Enable TLS/SSL if true.
33
base : The DN that is the base object entry relative to
34
which the search is to be performed. The string may
35
also contain a '%d' token that will be replaced by
36
the e-mail address domain.
38
scope : Scope can be 'base', 'one' or 'sub'.
40
query_filter : The filter used to find the amavis account. The string
41
must contain a '%m' token that will be replaced by the
42
actual e-mail address.
43
(Default = '(&(objectClass=amavisAccount)(mail=%m))')
44
bind_dn : If binding is needed, this is specifies the DN to bind as.
46
bind_password : Binding password.
49
The desired parameters can be specified in amavisd.conf and defaults
50
will be supplied for any parameters not specified, ex:
53
hostname => [ 'localhost', 'ldap2.example.com' ],
56
base => ou=People,dc=example,dc=com,
57
query_filter => '(&(objectClass=amavisAccount)(mail=%m))',
60
The amavisd-new LDAP schema is available in file LDAP.schema of the
61
distribution, and at http://www.ijs.si/software/amavisd/LDAP.schema
63
LDAP 'search' requests all available fields from the specified directory
64
and the result is cached (just for this mail message processing).
65
Individual attributes can be extracted one at a time from this cache
66
very quickly, so there is no penalty in using several calls to lookup
67
for different attributes (for the same key) in different parts of the
70
lookup_ldap() performs a lookup for an e-mail address in an LDAP
71
directory. If a match is found it returns whatever the map returns
72
(a reference to a hash containing values of requested attributes),
73
otherwise returns undef. Given an address the following lookups are
76
- lookup for user+foo@example.com
77
- lookup for user@example.com (only if $recipient_delimiter is '+')
78
- lookup for user+foo (only if domain part is local)
79
- lookup for user (only local; only if $recipient_delimiter is '+')
80
- lookup for @example.com
81
- lookup for @.example.com
83
- lookup for @. (catchall)
85
NOTE: a null reverse path e-mail address used by MTA for delivery status
86
notifications (DSN) has empty local part and empty domain. As far as the
87
lookup is concerned (which uses raw, i.e. non-quoted and non-bracketed
88
address form), this address is @, i.e. a single character "@".
89
The LDAP lookup for null address goes through the following sequence
90
of keys: "", "@", "@." (double quotes added for clarity, they are not part
93
lookup_ldap_attr() also performs a lookup for an e-mail address against
94
a LDAP directory. It first calls lookup_ldap() if it hasn't been called
95
yet for this key, but instead of returning all available attributes,
96
it returns just a value of one particular attribute. This is the
97
subroutine that gets called from lookup() for arguments (objects) of
98
type Amavis::Lookup::LDAPattr.
100
LDAP white/black listing
101
------------------------
103
amavisWhitelistSender/amavisBlacklistSender are multivalued attributes
104
containing either full email addresses or domain specifications. The
105
envelope sender address is compared against each attribute value until
108
amavisBlacklistSender: user@example.com
109
amavisBlacklistSender: @example.com
110
amavisBlacklistSender: @.example.com
112
A domain specification with a leading '@.' matches a domain as well
115
LDAP banned rule names
116
----------------------
118
amavisBannedRuleNames may contain a comma-separated list of names mapped
119
through %banned_rules to actual banned_filename tables.
121
amavisBannedRuleNames: ALLOW_EXE, DEFAULT
126
'NO-MS-EXEC'=> new_RE( qr'^\.(exe-ms)$' ),
127
'PASSALL' => new_RE( [qr'^' => 0] ),
128
'ALLOW_EXE' => new_RE( qr'.\.(vbs|pif|scr|bat)$'i, [qr'^\.exe$' => 0] ),
129
'ALLOW_VBS' => new_RE( [qr'.\.vbs$' => 0] ),
130
'DEFAULT' => $banned_filename_re,
133
Special handling of optional LDAP attribute 'amavisLocal'
134
---------------------------------------------------------
136
A special shorthand is provided when LDAP lookups are used: when a match
137
for recipient address (or domain) is found in LDAP tables (regardless of
138
attribute values), the recipient is considered local, regardless of static
139
@local_domains_acl or %local_domains lookup tables. This simplifies
140
life when a large number of dynamically changing domains is hosted.
141
To overrule this behaviour, add an explicit boolean attribute 'amavisLocal'
142
(missing field defaults to true, meaning record match implies locality)
143
The default value for local_domains_ldap lookup for the catchall key '@.'
144
is undef under conditions: when user record with key '@.' is present in the
145
database and the attribute 'amavisLocal' is not present. Previously it
146
surprisingly defaulted to true, now it falls back to static lookup table
147
defaults, the same as if the record '@.' were not present in the table.
149
In general LDAP lookups are similar to SQL lookups except for the low level
150
LDAP/SQL specific code. The overall functionality, lookup rules, etc. are
added
removed
README_FILES/README.ldap
