"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "amavisd-new-2.6.1/README_FILES/README.ldap" of archive amavisd-new-2.6.1.tar.gz:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 LDAP LOOKUPS
2 ------------
3
4 This text contains general LDAP-related documentation. Please also
5 see README.lookups for additional lookup information.
6
7 LDAP lookups are enabled in amavisd.conf with:
8
9 $enable_ldap = 1;
10
11 Definitions and default values of LDAP parameters.
12
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
24 by 'hostname'.
25 (Default = 389 (636 if using TLS/SSL))
26 version : The protocol version to use.
27 (Default = 3)
28 timeout : Timeout (in sec) passed when connecting the remote
29 server.
30 (Default = 120)
31 tls : Enable TLS/SSL if true.
32 (Default = 0)
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.
37 (Default = undef)
38 scope : Scope can be 'base', 'one' or 'sub'.
39 (Default = '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.
45 (Default = undef)
46 bind_password : Binding password.
47 (Default = undef)
48
49 The desired parameters can be specified in amavisd.conf and defaults
50 will be supplied for any parameters not specified, ex:
51
52 $default_ldap = {
53 hostname => [ 'localhost', 'ldap2.example.com' ],
54 timeout => 5,
55 tls => 0,
56 base => ou=People,dc=example,dc=com,
57 query_filter => '(&(objectClass=amavisAccount)(mail=%m))',
58 };
59
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
62
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
68 program.
69
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
74 done by default:
75
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
82 - lookup for @.com
83 - lookup for @. (catchall)
84
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
91 of the key).
92
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.
99
100 LDAP white/black listing
101 ------------------------
102
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
106 a match is made.
107
108 amavisBlacklistSender: user@example.com
109 amavisBlacklistSender: @example.com
110 amavisBlacklistSender: @.example.com
111
112 A domain specification with a leading '@.' matches a domain as well
113 as its subdomains.
114
115 LDAP banned rule names
116 ----------------------
117
118 amavisBannedRuleNames may contain a comma-separated list of names mapped
119 through %banned_rules to actual banned_filename tables.
120
121 amavisBannedRuleNames: ALLOW_EXE, DEFAULT
122
123 <amavisd.conf>
124
125 %banned_rules = (
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,
131 );
132
133 Special handling of optional LDAP attribute 'amavisLocal'
134 ---------------------------------------------------------
135
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.
148
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
151 identical.