Commit | Line | Data |
---|---|---|
de45f55a AM |
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) | |
0baa7b9d | 5 | .TH EXIM4-CONFIG_FILES 5 "Jan 4, 2015" EXIM4 |
de45f55a AM |
6 | .\" Please adjust this date whenever revising the manpage. |
7 | .\" | |
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 | |
20 | .SH NAME | |
21 | exim4-config_files \- Files in use by the Debian exim4 packages | |
22 | .SH SYNOPSIS | |
23 | .br | |
24 | /etc/aliases | |
25 | .br | |
26 | /etc/email\-addresses | |
27 | .br | |
28 | /etc/exim4/local_host_blacklist | |
29 | .br | |
30 | /etc/exim4/host_local_deny_exceptions | |
31 | .br | |
32 | /etc/exim4/local_sender_blacklist | |
33 | .br | |
34 | /etc/exim4/sender_local_deny_exceptions | |
35 | .br | |
36 | /etc/exim4/local_sender_callout | |
37 | .br | |
38 | /etc/exim4/local_rcpt_callout | |
39 | .br | |
40 | /etc/exim4/local_domain_dnsbl_whitelist | |
41 | .br | |
42 | /etc/exim4/hubbed_hosts | |
43 | .br | |
44 | /etc/exim4/passwd | |
45 | .br | |
46 | /etc/exim4/passwd.client | |
47 | .br | |
48 | /etc/exim4/exim.crt | |
49 | .br | |
50 | /etc/exim4/exim.key | |
51 | .SH DESCRIPTION | |
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 | |
54 | from source. | |
55 | .SH /etc/aliases | |
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 | |
59 | .br | |
60 | name: address, address, ... | |
61 | .br | |
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. | |
68 | ||
69 | You should at least set up an alias for postmaster in the /etc/aliases | |
70 | file. | |
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. | |
74 | ||
75 | The file should contain lines of the form | |
76 | ||
77 | .br | |
78 | user: someone@isp.com | |
79 | .br | |
80 | otheruser: someoneelse@anotherisp.com | |
81 | ||
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. | |
86 | ||
87 | .SH /etc/exim4/local_host_blacklist | |
88 | .I [exim host list] | |
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. | |
98 | ||
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. | |
101 | ||
102 | For example, a /etc/exim4/local_host_blacklist | |
103 | ||
104 | .br | |
105 | 192.168.10.0/24 | |
106 | .br | |
107 | !172.16.10.128/26 | |
108 | .br | |
109 | 172.16.10.0/24 | |
110 | .br | |
111 | 10.0.0.0/8 | |
112 | ||
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. | |
116 | ||
117 | .SH /etc/exim4/host_local_deny_exceptions | |
118 | .I [exim host list] | |
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. | |
122 | ||
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. | |
133 | ||
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. | |
136 | ||
137 | For example, a /etc/exim4/local_sender_blacklist | |
138 | ||
139 | .br | |
140 | domain1.example | |
141 | .br | |
142 | !local@domain2.example | |
143 | .br | |
144 | domain2.example | |
145 | .br | |
146 | domain3.example | |
147 | ||
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. | |
151 | ||
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. | |
157 | ||
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. | |
163 | ||
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 | |
169 | can be used. | |
170 | ||
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. | |
179 | ||
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. | |
188 | ||
189 | The file should contain key-value pairs of domain pattern and route | |
190 | data of the form | |
191 | ||
192 | .br | |
193 | domain: host-list options | |
194 | .br | |
195 | dict.ref.example: mail\-1.ref.example:mail\-2.ref.example | |
196 | .br | |
197 | foo.example: internal.mail.example.com | |
198 | .br | |
199 | bar.example: 192.168.183.3 | |
200 | ||
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. | |
204 | ||
205 | See spec.txt chapter 20.3 through 20.7 for a more detailed explanation | |
206 | of host list format and available options. | |
207 | ||
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. | |
211 | ||
212 | The file should contain lines of the form | |
213 | ||
214 | .br | |
215 | username:crypted-password:clear-password | |
216 | ||
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. | |
221 | ||
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 | |
224 | omitted completely. | |
225 | ||
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. | |
228 | ||
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. | |
232 | ||
233 | The file should contain lines of the form | |
234 | ||
235 | .br | |
236 | target.mail.server.example:login-user-name:password | |
237 | ||
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. | |
244 | ||
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. | |
251 | ||
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. | |
254 | ||
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. | |
260 | ||
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. | |
265 | ||
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 | |
268 | guess. | |
269 | ||
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. | |
272 | ||
273 | .br | |
274 | # example for CONFDIR/passwd.client | |
275 | .br | |
276 | # this will only match if the server's generic name matches exactly | |
277 | .br | |
278 | mail.server.example:user:password | |
279 | .br | |
280 | # this will deliver the password to any server | |
281 | .br | |
282 | *:username:password | |
283 | .br | |
284 | # this will deliver the password to servers whose generic name ends in | |
285 | .br | |
286 | # mail.server.example | |
287 | .br | |
288 | *.mail.server.example:user:password | |
289 | .br | |
290 | # this will deliver the password to servers whose generic name matches | |
291 | .br | |
292 | # the regular expression | |
293 | .br | |
0baa7b9d | 294 | ^smtp[0\-9]*\\.mail\\.server\\.example:user:password |
de45f55a AM |
295 | .br |
296 | ||
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. | |
302 | ||
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. | |
308 | ||
309 | .SH BUGS | |
310 | Plenty. Please report them through the Debian BTS | |
311 | ||
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. | |
315 | ||
316 | .SH NOTES | |
317 | .SS Unresolvable items in host lists | |
318 | ||
319 | Adding or keeping items in the abovementioned host lists which are not | |
320 | resolvable by DNS has severe consequences. | |
321 | ||
322 | e.g. if resolving a | |
323 | .B hostname | |
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 | |
327 | .I every | |
328 | connecting host. | |
329 | ||
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 | |
333 | ||
334 | notresolvable.example.com:rejectme.example.com | |
335 | ||
336 | is equivalent to an empty one. - Exim tries to match the IP-address of the | |
0baa7b9d | 337 | connecting host to notresolvable.example.com, resolving this IP by DNS |
de45f55a AM |
338 | fails, exim behaves as if the connecting host does not match the list. List |
339 | processing stops at this point! | |
340 | ||
341 | Starting the list with the special pattern +ignore_unknown as a | |
342 | safeguard against this behavior is strongly recommended if hostnames are | |
343 | used in hostlists. | |
344 | ||
345 | See Exim specification Chapter | |
346 | .I Domain, host, address, and local part lists | |
347 | , section | |
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> | |
350 | ||
351 | .SH SEE ALSO | |
352 | .br | |
353 | .BR exim (8), | |
354 | .br | |
355 | .BR update\-exim4.conf(8), | |
356 | .br | |
357 | .BR /usr/share/doc/exim4\-base/, | |
358 | .br | |
359 | and for general notes and details about interaction with debconf | |
360 | .BR /usr/share/doc/exim4\-base/README.Debian.gz | |
361 | ||
362 | .SH AUTHOR | |
363 | Marc Haber <mh+debian-packages@zugschlus.de> with help from Ross Boylan. | |
364 |