debian/manpages/exim4-config_files.5

   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.
   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
 294 ^smtp[0\-9]*\\.mail\\.server\\.example:user:password
 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
 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!
 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