1 .\" Hey, EMACS: -*- nroff -*-
2 .\" First parameter, NAME, should be all caps
3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
4 .\" other parameters are allowed: see man(7), man(1)
5 .TH EXIM4-CONFIG_FILES 5 "Jan 4, 2015" EXIM4
6 .\" Please adjust this date whenever revising the manpage.
8 .\" Some roff macros, for reference:
9 .\" .nh disable hyphenation
10 .\" .hy enable hyphenation
11 .\" .ad l left justify
12 .\" .ad b justify to both left and right margins
13 .\" .nf disable filling
14 .\" .fi enable filling
15 .\" .br insert line break
16 .\" .sp <n> insert n+1 empty lines
17 .\" for manpage-specific macros, see man(7)
18 .\" \(oqthis text is enclosed in single quotes\(cq
19 .\" \(lqthis text is enclosed in double quotes\(rq
21 exim4-config_files \- Files in use by the Debian exim4 packages
28 /etc/exim4/local_host_blacklist
30 /etc/exim4/host_local_deny_exceptions
32 /etc/exim4/local_sender_blacklist
34 /etc/exim4/sender_local_deny_exceptions
36 /etc/exim4/local_sender_callout
38 /etc/exim4/local_rcpt_callout
40 /etc/exim4/local_domain_dnsbl_whitelist
42 /etc/exim4/hubbed_hosts
46 /etc/exim4/passwd.client
52 This manual page describes the files that are in use by the Debian
53 exim4 packages and which are not part of an exim installation done
56 is a table providing a mechanism to redirect mail for local
57 recipients. /etc/aliases is a text file which is roughly compatible
58 with Sendmail. The file should contain lines of the form
60 name: address, address, ...
62 The name is a local address without domain part. All local domains are
63 handled equally. For more detailed documentation, please refer to
64 /usr/share/doc/exim4\-base/spec.txt.gz, chapter 22, and to
65 /usr/share/doc/exim4\-base/README.Debian.gz. Please note that it
66 is not possible to use delivery to arbitrary files, directories and to
67 pipes. This is forbidden in Debian's exim4 default configuration.
69 You should at least set up an alias for postmaster in the /etc/aliases
71 .SH /etc/email\-addresses
72 is used to rewrite the email addresses of users. This is particularly
73 useful for users who use their ISP's domain for email.
75 The file should contain lines of the form
80 otheruser: someoneelse@anotherisp.com
82 This way emails from user will appear to be from someone@isp.com to
83 the outside world. Technically, the from, reply\-to, and sender
84 addresses, along with the envelope sender, are rewritten for users that
85 appear to be in the local domain.
87 .SH /etc/exim4/local_host_blacklist
89 is an optional file containing a list of IP addresses, networks and
90 host names whose messages will be denied with the error message
91 "locally blacklisted". This is a full exim 4 host list, and all
92 available features can be used. This includes negative items, and so
93 it is possible to exclude addresses from being blacklisted. For
94 convenience, as an additional method to whitelist addresses from being
95 blocked, an explicit whitelist is read in from
96 /etc/exim4/host_local_deny_exceptions. Entries in the whitelist override
97 corresponding blacklist entries.
99 In the blacklist, the trick is to read a line break as "or" if it
100 follows a positive item, and as "and" if it follows a negative item.
102 For example, a /etc/exim4/local_host_blacklist
113 Exim just evaluates left to right (or up-down in the file listing
114 context), so you don't get the same kind of operator binding as in a
115 programming language.
117 .SH /etc/exim4/host_local_deny_exceptions
119 contains a list of IP addresses, networks and host names whose
120 messages will be accepted despite the address is also listed in
121 /etc/exim4/local_host_blacklist, overriding a blacklisting.
123 .SH /etc/exim4/local_sender_blacklist
124 .I [exim address list]
125 is an optional files containing a list of envelope senders whose
126 messages will be denied with the error message "locally blacklisted".
127 This is a full exim 4 address list, and all available features can be
128 used. This includes negative items, and so it is possible to exclude
129 addresses from being blacklisted. For convenience, as an additional
130 method to whitelist addresses from being blocked, an explicit
131 whitelist is read in from /etc/exim4/sender_local_deny_exceptions. Entries
132 in the whitelist override corresponding blacklist entries.
134 In the blacklist, the trick is to read a line break as "or" if it
135 follows a positive item, and as "and" if it follows a negative item.
137 For example, a /etc/exim4/local_sender_blacklist
142 !local@domain2.example
148 Exim just evaluates left to right (or up-down in the file listing
149 context), so you don't get the same kind of operator binding as in a
150 programming language.
152 .SH /etc/exim4/sender_local_deny_exceptions
153 .I [exim address list]
154 is an optional file containing a list of envelope senders whose messages
155 will be accepted despite the address being also listed in
156 /etc/exim4/local_sender_blacklist, overriding a blacklisting.
158 .SH /etc/exim4/local_sender_callout
159 .I [exim address list]
160 is an optional file containing a list of envelope senders whose
161 messages are subject to sender verification with a callout. This is a
162 full exim4 address list, and all available features can be used.
164 .SH /etc/exim4/local_rcpt_callout
165 .I [exim address list]
166 is an optional file containing a list of envelope recipients for which
167 incoming messages are subject to recipient verification with a
168 callout. This is a full exim4 address list, and all available features
171 .SH /etc/exim4/local_domain_dnsbl_whitelist
172 .I [exim address list]
173 is an optional file containing a list of envelope senders whose
174 messages are exempt from blacklisting via a domain-based DNSBL. This
175 is a full exim4 address list, and all available features can be used.
176 This feature is intended to be used in case of a domain-based DNSBL
177 being too heavy handed, for example listing entire top-level domains
178 for their registry policies.
180 .SH /etc/exim4/hubbed_hosts
181 .I [exim domain list]
182 is an optional file containing a list of route_data records which can
183 be used to override or augment MX information from the DNS. This is
184 particularly useful for mail hubs which are highest-priority MX for a
185 domain in the DNS but are not final destination of the messages,
186 passing them on to a host which is not publicly reachable, or to
187 temporarily fix mail routing in case of broken DNS setups.
189 The file should contain key-value pairs of domain pattern and route
193 domain: host-list options
195 dict.ref.example: mail\-1.ref.example:mail\-2.ref.example
197 foo.example: internal.mail.example.com
199 bar.example: 192.168.183.3
201 which will cause mail for foo.example to be sent to the host
202 internal.mail.example (IP address derived from A record only), and
203 mail to bar.example to be sent to 192.168.183.3.
205 See spec.txt chapter 20.3 through 20.7 for a more detailed explanation
206 of host list format and available options.
208 .SH /etc/exim4/passwd
209 contains account and password data for SMTP authentication when the
210 local exim is SMTP server and clients authenticate to the local exim.
212 The file should contain lines of the form
215 username:crypted-password:clear-password
217 crypted-password is the crypt(3)-created hash of your password. You
218 can, for example, use the mkpasswd program from the whois package to
219 create a crypted password. It is recommended to use a modern hash
220 algorithm, see mkpasswd \-\-method=help. Consider not using crypt or MD5.
222 clear-password is only necessary if you want to offer CRAM-MD5
223 authentication. If you don't plan on doing so, the third column can be
226 This file must be readable for the Debian\-exim user and should not be
227 readable for others. Recommended file mode is root:Debian\-exim 640.
229 .SH /etc/exim4/passwd.client
230 contains account and password data for SMTP authentication when exim
231 is authenticating as a client to some remote server.
233 The file should contain lines of the form
236 target.mail.server.example:login-user-name:password
238 which will cause exim to use login-user-name and password when sending
239 messages to a server with the canonical host name
240 target.mail.server.example. Please note that this does not configure
241 the mail server to send to (this is determined in Debconf), but only
242 creates the correlation between host name and authentication
243 credentials to avoid exposing passwords to the wrong host.
245 Please note that target.mail.server.example is currently the value
246 that exim can read from reverse DNS: It first follows the host name of
247 the target system until it finds an IP address, and then looks up the
248 reverse DNS for that IP address to use the outcome of this query (or
249 the IP address itself should the query fail) as index into
250 /etc/exim4/passwd.client.
252 This goes inevitably wrong if the host name of the mail server is a
253 CNAME (a DNS alias), or the reverse lookup does not fit the forward one.
255 Currently, you need to manually lookup all reverse DNS names for all
256 IP addresses that your SMTP server host name points to, for example by
257 using the host command. If the SMTP smarthost alias expands to
258 multiple IPs, you need to have multiple lines for all the hosts. When
259 your ISP changes the alias, you will need to manually fix that.
261 You may minimize this trouble by using a wild card entry or regular
262 expressions, thus reducing the risk of divulging the password to the
263 wrong SMTP server while reducing the number of necessary lines. For a
264 deeper discussion, see the Debian BTS #244724.
266 password is your SMTP password in clear text. If you do not know about
267 your SMTP password, you can try using your POP3 password as a first
270 This file must be readable for the Debian\-exim user and should not be
271 readable for others. Recommended file mode is root:Debian\-exim 640.
274 # example for CONFDIR/passwd.client
276 # this will only match if the server's generic name matches exactly
278 mail.server.example:user:password
280 # this will deliver the password to any server
284 # this will deliver the password to servers whose generic name ends in
286 # mail.server.example
288 *.mail.server.example:user:password
290 # this will deliver the password to servers whose generic name matches
292 # the regular expression
294 ^smtp[0\-9]*\\.mail\\.server\\.example:user:password
297 .SH /etc/exim4/exim.crt
298 contains the certificate that exim uses to initiate TLS connections.
299 This is public information and can be world readable.
300 /usr/share/doc/exim4\-base/examples/exim\-gencert can
301 be used to generate a private key and self-signed certificate.
303 .SH /etc/exim4/exim.key
304 contains the private key belonging to the certificate in exim.crt.
305 This file's contents must be kept secret and should have mode
306 root:Debian\-exim 640. /usr/share/doc/exim4\-base/examples/exim\-gencert
307 can be used to generate a private key and self-signed certificate.
310 Plenty. Please report them through the Debian BTS
312 This manual page needs a major re-work. If somebody knows better groff
313 than us and has more experience in writing manual pages, any patches
314 would be greatly appreciated.
317 .SS Unresolvable items in host lists
319 Adding or keeping items in the abovementioned host lists which are not
320 resolvable by DNS has severe consequences.
324 in local_host_blacklist returns a temporary error (DNS timeout) exim
325 will not be able to check whether a connecting host is part of the list.
326 Exim will therefore return a temporary SMTP error for
330 On the other hand if there is a permanent error in resolving a name in the
331 host list (the record was removed from DNS) exim behaves as if the host
332 does not match the list. e.g. a local_host_blacklist consisting of
334 notresolvable.example.com:rejectme.example.com
336 is equivalent to an empty one. - Exim tries to match the IP-address of the
337 connecting host to notresolvable.example.com, resolving this IP by DNS
338 fails, exim behaves as if the connecting host does not match the list. List
339 processing stops at this point!
341 Starting the list with the special pattern +ignore_unknown as a
342 safeguard against this behavior is strongly recommended if hostnames are
345 See Exim specification Chapter
346 .I Domain, host, address, and local part lists
348 .I Behaviour when an IP address or name cannot be found.
349 <http://www.exim.org/exim\-html\-current/doc/html/spec_html/ch\-domain_host_address_and_local_part_lists.html>
355 .BR update\-exim4.conf(8),
357 .BR /usr/share/doc/exim4\-base/,
359 and for general notes and details about interaction with debconf
360 .BR /usr/share/doc/exim4\-base/README.Debian.gz
363 Marc Haber <mh+debian-packages@zugschlus.de> with help from Ross Boylan.