EXIM4-CONFIG_FILES(5)

💌 EXIM4-CONFIG_FILES 💌

okay bestie, this is the manual page for exim4-config_files, from the File Formats Manual section. it's a whole tour of the files that the Debian exim4 packages use. buckle up, grab a boba, we're doing this 💅

---

✨ NAME ✨

exim4-config_files — the files that the Debian exim4 packages are out here using. fr fr

---

✨ SYNOPSIS ✨

/etc/aliases
/etc/email-addresses
/etc/exim4/local_host_blacklist
/etc/exim4/host_local_deny_exceptions
/etc/exim4/local_sender_blacklist
/etc/exim4/sender_local_deny_exceptions
/etc/exim4/local_sender_callout
/etc/exim4/local_rcpt_callout
/etc/exim4/local_domain_dnsbl_whitelist
/etc/exim4/hubbed_hosts
/etc/exim4/passwd
/etc/exim4/passwd.client
/etc/exim4/exim.crt
/etc/exim4/exim.key
/etc/mailname

---

🌸 DESCRIPTION 🌸

this page is basically the group chat for all the files the Debian exim4 packages use — specifically the ones that are not part of an exim install you'd do from source. so if you compiled exim yourself, these aren't your files, bestie. iykyk

---

🎀 /etc/aliases

this one is a table, and its whole thing is redirecting mail for local recipients. /etc/aliases is a text file that's roughly compatible with Sendmail (we love a legacy moment 💀).

the file should have lines that look like this:

name: address, address, ...

name is a local address, no domain part. and the way all local domains get treated? equally. every single one. no favours.

for the full deep dive, go read /usr/share/doc/exim4-base/spec.txt.gz, chapter 22, and also /usr/share/doc/exim4-base/README.Debian.gz. homework assigned, bestie 📚

⚠️ heads up: it is not possible to use delivery to arbitrary files, directories, or pipes. that's straight-up forbidden in Debian's exim4 default configuration. no sneaky piping, we don't do that here.

you should at least set up an alias for postmaster in the /etc/aliases file. seriously. do it. it's giving responsible sysadmin energy. 👑

---

🎀 /etc/email-addresses

this file rewrites users' email addresses, which is so useful if you're a user who uses their ISP's domain for email. relatable tbh.

the file should contain lines like:

user: someone@isp.com
otheruser: someoneelse@anotherisp.com

so with that, emails from user will show up as being from someone@isp.com to the outside world. slay. ✨

technically speaking: the from, reply-to, and sender addresses, plus the envelope sender, all get rewritten for users that appear to be in the local domain.

---

🎀 /etc/exim4/local_host_blacklist

this one is an [exim host list] and it's optional. it's a list of IP addresses, networks, and host names whose messages get denied with the error message "locally blacklisted". 🚫

it's a full exim 4 host list, so every feature is fair game. that includes negative items — which means you can exclude addresses from being blacklisted. the versatility, the range, we love her.

as a convenience, there's also an extra way to whitelist addresses: an explicit whitelist read in from /etc/exim4/host_local_deny_exceptions. entries in that whitelist override the matching blacklist entries. whitelist stays winning

in the blacklist, the trick is: read a line break as "or" if it follows a positive item, and as "and" if it follows a negative item.

example time, a /etc/exim4/local_host_blacklist:

192.168.10.0/24
!172.16.10.128/26
172.16.10.0/24
10.0.0.0/8

Exim just evaluates left to right (or up-down in the file listing context, same vibe), so you don't get the same kind of operator binding you'd get in a programming language. no fancy precedence, it's just vibes in order 💅

---

🎀 /etc/exim4/host_local_deny_exceptions

this is an [exim host list] containing IP addresses, networks, and host names whose messages will be accepted — even though the address is also listed in /etc/exim4/local_host_blacklist. it overrides a blacklisting. the exception era 🦋

---

🎀 /etc/exim4/local_sender_blacklist

an optional file, marked as an [exim address list], holding a list of envelope senders whose messages get denied with the error message "locally blacklisted". 🚫

again, this is a full exim 4 address list and every available feature can be used. negative items included, so yes, you can 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. the override is real

same trick as before: in the blacklist, 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:

domain1.example
!local@domain2.example
domain2.example
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. again, no precedence drama, just order 🙈

---

🎀 /etc/exim4/sender_local_deny_exceptions

an optional file, an [exim address list], containing envelope senders whose messages will be accepted despite the address being also listed in /etc/exim4/local_sender_blacklist. it overrides a blacklisting. the save ✨

---

🎀 /etc/exim4/local_sender_callout

an optional file, an [exim address list], containing envelope senders whose messages are subject to sender verification with a callout. it's a full exim4 address list and all available features can be used. verification era 🔥

---

🎀 /etc/exim4/local_rcpt_callout

an optional file, an [exim address list], containing envelope recipients for which incoming messages are subject to recipient verification with a callout. also a full exim4 address list, also all features available. rcpt edition, equally iconic 👑

---

🎀 /etc/exim4/local_domain_dnsbl_whitelist

an optional file, an [exim address list], containing envelope senders whose messages are exempt from blacklisting via a domain-based DNSBL. full exim4 address list, all features available. exempt bestie 🌈

this feature is intended for when a domain-based DNSBL is being a little too heavy handed — like, say, listing entire top-level domains over their registry policies. rude of them honestly

---

🎀 /etc/exim4/hubbed_hosts

an optional file, an [exim domain list], containing route_data records that can override or augment MX information from the DNS. obsessed

this is especially useful for mail hubs that are the highest-priority MX for a domain in the DNS but are not the final destination of the messages — they pass them on to a host that isn't publicly reachable. it's also great for temporarily fixing mail routing when DNS setups are broken. emergency routing moment 🚑

the file should contain key-value pairs of domain pattern and route data, like:

domain: host-list options
dict.ref.example:  mail-1.ref.example:mail-2.ref.example
foo.example: internal.mail.example.com
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. look at her go 💫

see spec.txt chapter 20.3 through 20.7 for a more detailed explanation of host list format and available options.

---

🎀 /etc/exim4/passwd

this file holds account and password data for SMTP authentication when the local exim is the SMTP server and clients authenticate to the local exim.

the file should contain lines like:

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. please, for the love of everything, not 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. optional third column, we love a flexible queen

🔒 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.

---

🎀 /etc/exim4/passwd.client

this one holds account and password data for SMTP authentication when exim is authenticating as a client to some remote server.

the file should contain lines like:

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 (that's determined in Debconf) — it only creates the correlation between host name and authentication credentials, so we avoid exposing passwords to the wrong host. safety first bestie 🛡️

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. no cap.

currently, you need to manually look up 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. and when your ISP changes the alias, you will need to manually fix that. the maintenance, the labour 😭

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. we've all been there 🙈

🔒 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.

# example for CONFDIR/passwd.client
# this will only match if the server's generic name matches exactly
mail.server.example:user:password
# this will deliver the password to any server
*:username:password
# this will deliver the password to servers whose generic name ends in
# mail.server.example
*.mail.server.example:user:password
# this will deliver the password to servers whose generic name matches
# the regular expression
^smtp[0-9]*\.mail\.server\.example:user:password

---

🎀 /etc/exim4/exim.crt

this file contains the certificate that exim uses to initiate TLS connections. this is public information and can be world readable. public info, no secrets here ✨

/usr/share/doc/exim4-base/examples/exim-gencert can be used to generate a private key and self-signed certificate.

---

🎀 /etc/exim4/exim.key

this file contains the private key belonging to the certificate in exim.crt. this file's contents must be kept secret 🔐 and it 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.

---

🎀 /etc/mailname

the "mail name" of the system. see Debian policy Chapter Customized programs and exim4-base's README.Debian for further details.

---

💀 BUGS 💀

plenty. please report them through the Debian BTS. the honesty, honestly iconic

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. volunteer era, bestie? 👑

---

📝 NOTES 📝

okay bestie this is the part where things get real. like, genuinely read this before you go putting hostnames in host lists, because the vibes can go from ✨immaculate✨ to 💀real fast💀.

🚨 Unresolvable items in host lists 🚨

so. adding stuff to the host lists we talked about above (or just leaving stuff there) that doesn't resolve via DNS? that has severe consequences. not like "oops" consequences, like severe. i'm not being dramatic, the manpage said it first.

let me break it down because it's giving "two completely different outcomes depending on which flavour of DNS fail you get":

• if resolving a hostname in local_host_blacklist comes back with a temporary error (like a DNS timeout), exim literally cannot check whether the connecting host is part of the list. so what does it do? it returns a temporary SMTP error for every connecting host. every single one. the whole thing just stops working 🫠
• if instead there's a permanent error resolving a name in the host list (because the record got removed from DNS), exim acts like the host just... doesn't match the list. which sounds chill but is actually a sneaky little trap, watch this:

so a local_host_blacklist that looks like

notresolvable.example.com:rejectme.example.com

is equivalent to an empty one. yeah. for real. here's why: exim tries to match the IP address of the connecting host against notresolvable.example.com, the DNS resolution of that IP fails, so exim behaves as if the connecting host does not match the list. and then — and this is the part that gets you — list processing stops at this point! 🛑 so rejectme.example.com never even gets a chance to reject anybody. it's giving "the understudy never got to go on stage."

💡 the fix, and the manpage is strongly recommending this one: if you're using hostnames in host lists, start the list with the special pattern +ignore_unknown as a safeguard against this behavior. do it. protect yourself. 🫶

if you want the full lore on this, go read the Exim specification chapter Domain, host, address, and local part lists, specifically the section 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>

---

👀 SEE ALSO 👀

go read these bestie, they're the rest of the lore:

• exim(8)
• update-exim4.conf(8)
• /usr/share/doc/exim4-base/
• and for general notes and details about interaction with debconf: /usr/share/doc/exim4-base/README.Debian.gz

---

👑 AUTHOR 👑

this iconic page was written by Marc Haber <mh+debian-packages@zugschlus.de>, with help from Ross Boylan. tag team. ate. 💅

---

and that's the whole thing, bestie — you made it to the end of EXIM4-CONFIG_FILES(5), source EXIM4, dated Jan 4, 2015. go configure something responsibly 🌸✨🦋