summaryrefslogtreecommitdiffstats
path: root/debian/manpages/exim4-config_files.5
diff options
context:
space:
mode:
Diffstat (limited to 'debian/manpages/exim4-config_files.5')
-rw-r--r--debian/manpages/exim4-config_files.5364
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.
+