diff options
Diffstat (limited to 'debian/manpages/exim4-config_files.5')
| -rw-r--r-- | debian/manpages/exim4-config_files.5 | 364 |
1 files changed, 364 insertions, 0 deletions
diff --git a/debian/manpages/exim4-config_files.5 b/debian/manpages/exim4-config_files.5 new file mode 100644 index 0000000..b217377 --- /dev/null +++ b/debian/manpages/exim4-config_files.5 @@ -0,0 +1,364 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH EXIM4-CONFIG_FILES 5 "Jan 4, 2015" EXIM4 +.\" Please adjust this date whenever revising the manpage. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp <n> insert n+1 empty lines +.\" for manpage-specific macros, see man(7) +.\" \(oqthis text is enclosed in single quotes\(cq +.\" \(lqthis text is enclosed in double quotes\(rq +.SH NAME +exim4-config_files \- Files in use by the Debian exim4 packages +.SH SYNOPSIS +.br +/etc/aliases +.br +/etc/email\-addresses +.br +/etc/exim4/local_host_blacklist +.br +/etc/exim4/host_local_deny_exceptions +.br +/etc/exim4/local_sender_blacklist +.br +/etc/exim4/sender_local_deny_exceptions +.br +/etc/exim4/local_sender_callout +.br +/etc/exim4/local_rcpt_callout +.br +/etc/exim4/local_domain_dnsbl_whitelist +.br +/etc/exim4/hubbed_hosts +.br +/etc/exim4/passwd +.br +/etc/exim4/passwd.client +.br +/etc/exim4/exim.crt +.br +/etc/exim4/exim.key +.SH DESCRIPTION +This manual page describes the files that are in use by the Debian +exim4 packages and which are not part of an exim installation done +from source. +.SH /etc/aliases +is a table providing a mechanism to redirect mail for local +recipients. /etc/aliases is a text file which is roughly compatible +with Sendmail. The file should contain lines of the form +.br +name: address, address, ... +.br +The name is a local address without domain part. All local domains are +handled equally. For more detailed documentation, please refer to +/usr/share/doc/exim4\-base/spec.txt.gz, chapter 22, and to +/usr/share/doc/exim4\-base/README.Debian.gz. Please note that it +is not possible to use delivery to arbitrary files, directories and to +pipes. This is forbidden in Debian's exim4 default configuration. + +You should at least set up an alias for postmaster in the /etc/aliases +file. +.SH /etc/email\-addresses +is used to rewrite the email addresses of users. This is particularly +useful for users who use their ISP's domain for email. + +The file should contain lines of the form + +.br +user: someone@isp.com +.br +otheruser: someoneelse@anotherisp.com + +This way emails from user will appear to be from someone@isp.com to +the outside world. Technically, the from, reply\-to, and sender +addresses, along with the envelope sender, are rewritten for users that +appear to be in the local domain. + +.SH /etc/exim4/local_host_blacklist +.I [exim host list] +is an optional file containing a list of IP addresses, networks and +host names whose messages will be denied with the error message +"locally blacklisted". This is a full exim 4 host list, and all +available features can be used. This includes negative items, and so +it is possible to exclude addresses from being blacklisted. For +convenience, as an additional method to whitelist addresses from being +blocked, an explicit whitelist is read in from +/etc/exim4/host_local_deny_exceptions. Entries in the whitelist override +corresponding blacklist entries. + +In the blacklist, the trick is to read a line break as "or" if it +follows a positive item, and as "and" if it follows a negative item. + +For example, a /etc/exim4/local_host_blacklist + +.br +192.168.10.0/24 +.br +!172.16.10.128/26 +.br +172.16.10.0/24 +.br +10.0.0.0/8 + +Exim just evaluates left to right (or up-down in the file listing +context), so you don't get the same kind of operator binding as in a +programming language. + +.SH /etc/exim4/host_local_deny_exceptions +.I [exim host list] +contains a list of IP addresses, networks and host names whose +messages will be accepted despite the address is also listed in +/etc/exim4/local_host_blacklist, overriding a blacklisting. + +.SH /etc/exim4/local_sender_blacklist +.I [exim address list] +is an optional files containing a list of envelope senders whose +messages will be denied with the error message "locally blacklisted". +This is a full exim 4 address list, and all available features can be +used. This includes negative items, and so it is possible to exclude +addresses from being blacklisted. For convenience, as an additional +method to whitelist addresses from being blocked, an explicit +whitelist is read in from /etc/exim4/sender_local_deny_exceptions. Entries +in the whitelist override corresponding blacklist entries. + +In the blacklist, the trick is to read a line break as "or" if it +follows a positive item, and as "and" if it follows a negative item. + +For example, a /etc/exim4/local_sender_blacklist + +.br +domain1.example +.br +!local@domain2.example +.br +domain2.example +.br +domain3.example + +Exim just evaluates left to right (or up-down in the file listing +context), so you don't get the same kind of operator binding as in a +programming language. + +.SH /etc/exim4/sender_local_deny_exceptions +.I [exim address list] +is an optional file containing a list of envelope senders whose messages +will be accepted despite the address being also listed in +/etc/exim4/local_sender_blacklist, overriding a blacklisting. + +.SH /etc/exim4/local_sender_callout +.I [exim address list] +is an optional file containing a list of envelope senders whose +messages are subject to sender verification with a callout. This is a +full exim4 address list, and all available features can be used. + +.SH /etc/exim4/local_rcpt_callout +.I [exim address list] +is an optional file containing a list of envelope recipients for which +incoming messages are subject to recipient verification with a +callout. This is a full exim4 address list, and all available features +can be used. + +.SH /etc/exim4/local_domain_dnsbl_whitelist +.I [exim address list] +is an optional file containing a list of envelope senders whose +messages are exempt from blacklisting via a domain-based DNSBL. This +is a full exim4 address list, and all available features can be used. +This feature is intended to be used in case of a domain-based DNSBL +being too heavy handed, for example listing entire top-level domains +for their registry policies. + +.SH /etc/exim4/hubbed_hosts +.I [exim domain list] +is an optional file containing a list of route_data records which can +be used to override or augment MX information from the DNS. This is +particularly useful for mail hubs which are highest-priority MX for a +domain in the DNS but are not final destination of the messages, +passing them on to a host which is not publicly reachable, or to +temporarily fix mail routing in case of broken DNS setups. + +The file should contain key-value pairs of domain pattern and route +data of the form + +.br +domain: host-list options +.br +dict.ref.example: mail\-1.ref.example:mail\-2.ref.example +.br +foo.example: internal.mail.example.com +.br +bar.example: 192.168.183.3 + +which will cause mail for foo.example to be sent to the host +internal.mail.example (IP address derived from A record only), and +mail to bar.example to be sent to 192.168.183.3. + +See spec.txt chapter 20.3 through 20.7 for a more detailed explanation +of host list format and available options. + +.SH /etc/exim4/passwd +contains account and password data for SMTP authentication when the +local exim is SMTP server and clients authenticate to the local exim. + +The file should contain lines of the form + +.br +username:crypted-password:clear-password + +crypted-password is the crypt(3)-created hash of your password. You +can, for example, use the mkpasswd program from the whois package to +create a crypted password. It is recommended to use a modern hash +algorithm, see mkpasswd \-\-method=help. Consider not using crypt or MD5. + +clear-password is only necessary if you want to offer CRAM-MD5 +authentication. If you don't plan on doing so, the third column can be +omitted completely. + +This file must be readable for the Debian\-exim user and should not be +readable for others. Recommended file mode is root:Debian\-exim 640. + +.SH /etc/exim4/passwd.client +contains account and password data for SMTP authentication when exim +is authenticating as a client to some remote server. + +The file should contain lines of the form + +.br +target.mail.server.example:login-user-name:password + +which will cause exim to use login-user-name and password when sending +messages to a server with the canonical host name +target.mail.server.example. Please note that this does not configure +the mail server to send to (this is determined in Debconf), but only +creates the correlation between host name and authentication +credentials to avoid exposing passwords to the wrong host. + +Please note that target.mail.server.example is currently the value +that exim can read from reverse DNS: It first follows the host name of +the target system until it finds an IP address, and then looks up the +reverse DNS for that IP address to use the outcome of this query (or +the IP address itself should the query fail) as index into +/etc/exim4/passwd.client. + +This goes inevitably wrong if the host name of the mail server is a +CNAME (a DNS alias), or the reverse lookup does not fit the forward one. + +Currently, you need to manually lookup all reverse DNS names for all +IP addresses that your SMTP server host name points to, for example by +using the host command. If the SMTP smarthost alias expands to +multiple IPs, you need to have multiple lines for all the hosts. When +your ISP changes the alias, you will need to manually fix that. + +You may minimize this trouble by using a wild card entry or regular +expressions, thus reducing the risk of divulging the password to the +wrong SMTP server while reducing the number of necessary lines. For a +deeper discussion, see the Debian BTS #244724. + +password is your SMTP password in clear text. If you do not know about +your SMTP password, you can try using your POP3 password as a first +guess. + +This file must be readable for the Debian\-exim user and should not be +readable for others. Recommended file mode is root:Debian\-exim 640. + +.br +# example for CONFDIR/passwd.client +.br +# this will only match if the server's generic name matches exactly +.br +mail.server.example:user:password +.br +# this will deliver the password to any server +.br +*:username:password +.br +# this will deliver the password to servers whose generic name ends in +.br +# mail.server.example +.br +*.mail.server.example:user:password +.br +# this will deliver the password to servers whose generic name matches +.br +# the regular expression +.br +^smtp[0\-9]*\\.mail\\.server\\.example:user:password +.br + +.SH /etc/exim4/exim.crt +contains the certificate that exim uses to initiate TLS connections. +This is public information and can be world readable. +/usr/share/doc/exim4\-base/examples/exim\-gencert can +be used to generate a private key and self-signed certificate. + +.SH /etc/exim4/exim.key +contains the private key belonging to the certificate in exim.crt. +This file's contents must be kept secret and should have mode +root:Debian\-exim 640. /usr/share/doc/exim4\-base/examples/exim\-gencert +can be used to generate a private key and self-signed certificate. + +.SH BUGS +Plenty. Please report them through the Debian BTS + +This manual page needs a major re-work. If somebody knows better groff +than us and has more experience in writing manual pages, any patches +would be greatly appreciated. + +.SH NOTES +.SS Unresolvable items in host lists + +Adding or keeping items in the abovementioned host lists which are not +resolvable by DNS has severe consequences. + +e.g. if resolving a +.B hostname +in local_host_blacklist returns a temporary error (DNS timeout) exim +will not be able to check whether a connecting host is part of the list. +Exim will therefore return a temporary SMTP error for +.I every +connecting host. + +On the other hand if there is a permanent error in resolving a name in the +host list (the record was removed from DNS) exim behaves as if the host +does not match the list. e.g. a local_host_blacklist consisting of + +notresolvable.example.com:rejectme.example.com + +is equivalent to an empty one. - Exim tries to match the IP-address of the +connecting host to notresolvable.example.com, resolving this IP by DNS +fails, exim behaves as if the connecting host does not match the list. List +processing stops at this point! + +Starting the list with the special pattern +ignore_unknown as a +safeguard against this behavior is strongly recommended if hostnames are +used in hostlists. + +See Exim specification Chapter +.I Domain, host, address, and local part lists +, section +.I Behaviour when an IP address or name cannot be found. +<http://www.exim.org/exim\-html\-current/doc/html/spec_html/ch\-domain_host_address_and_local_part_lists.html> + +.SH SEE ALSO +.br +.BR exim (8), +.br +.BR update\-exim4.conf(8), +.br +.BR /usr/share/doc/exim4\-base/, +.br +and for general notes and details about interaction with debconf +.BR /usr/share/doc/exim4\-base/README.Debian.gz + +.SH AUTHOR +Marc Haber <mh+debian-packages@zugschlus.de> with help from Ross Boylan. + |