diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/example-exim4.conf | 134 | ||||
| -rw-r--r-- | doc/smtp.md | 66 |
2 files changed, 200 insertions, 0 deletions
diff --git a/doc/example-exim4.conf b/doc/example-exim4.conf new file mode 100644 index 0000000..2f2c906 --- /dev/null +++ b/doc/example-exim4.conf @@ -0,0 +1,134 @@ +# Specify local domains HERE, these are names that might appear in email +domainlist local_domains = +domainlist relay_to_domains = +hostlist relay_from_hosts = localhost +# Create this file HERE +# It has single lines in the format: +# domain.com: host=smtp.office365.com::587 helo=cms user=user@domain.com oauth=/home/XX/mail/.cms/exim/unix +# oauth= may also be replaced with password= to do basic authentication. The +# file is searched based on the Envelope From when invoking sendmail +SMARTFN = /etc/exim4/exim-smart-hosts + +# We don't have IPv6, do not even try. +disable_ipv6=true + +# It is also a good idea to edit /etc/default/exim4 and switch to 'queueonly' mode (Debian) +local_interfaces = <; [127.0.0.1]:25 + +acl_smtp_rcpt = acl_check_rcpt +acl_smtp_data = acl_check_data + +tls_advertise_hosts = + +# Trusted users are allowed to override the sender envelope +trusted_users = # Add your user name HERE + +never_users = root + +host_lookup = * + +prdr_enable = true + +log_selector = +smtp_protocol_error +smtp_syntax_error \ + +tls_certificate_verified + +ignore_bounce_errors_after = 2d +timeout_frozen_after = 7d + +keep_environment = +add_environment = <; PATH=/bin:/usr/bin + +begin acl +acl_check_rcpt: + + # Standard input + accept hosts = : + control = dkim_disable_verify + + deny message = Restricted characters in address + domains = +local_domains + local_parts = ^[.] : ^.*[@%!/|] + + + deny message = Restricted characters in address + domains = !+local_domains + local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ + + + accept local_parts = postmaster + domains = +local_domains + + + require verify = sender + + accept hosts = +relay_from_hosts + control = submission + control = dkim_disable_verify + + accept authenticated = * + control = submission + control = dkim_disable_verify + + require message = relay not permitted + domains = +local_domains : +relay_to_domains + + require verify = recipient + + accept + +begin routers + +# The router is sensitive to the sender address and will use the correct outgoing server. +# Use something like: +# exim -f 'user@domain.com' -bt user@otherdomain.com +# To quick test +smarthost: + debug_print = "R: smarthost for $local_part@$domain" + driver = manualroute + domains = ! +local_domains + transport = remote_smtp_smarthost + route_data = ${extract{host}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}} + no_more + +begin transports + +remote_smtp_smarthost: + debug_print = "T: remote_smtp_smarthost for $local_part@$domain" + driver = smtp + helo_data = ${extract{helo}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}{wakko.ziepe.ca}} + hosts_require_auth = ${extract{user}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{*}{}} + hosts_require_tls = * + tls_tempfail_tryclear = false + tls_verify_certificates = system + +begin retry + +* * F,2h,15m; G,16h,1h,1.5; F,4d,6h + +begin rewrite + +# Replace user and domain HERE +root@+local_domains user@domain.com Ffrs +user@+local_domains user@domain.com Ffrs + +begin authenticators + +xoauth2_smart: + driver = plaintext + client_condition = ${if and {{!eq{$tls_out_cipher}{}} {eq{${extract{oauth}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{}fail}}{}}} } + public_name = XOAUTH2 + client_ignore_invalid_base64 = true + client_send = : ${readsocket{${extract{oauth}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}fail}}{SMTP ${extract{user}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}fail}}} + +# Plain has fewer round trips, so prefer to use it +plain_smart: + driver = plaintext + client_condition = ${if and {{!eq{$tls_out_cipher}{}} {eq{${extract{password}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{}fail}}{}}} } + public_name = PLAIN + client_send = ^${extract{user}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}fail}^${extract{password}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}} + +login_smart: + driver = plaintext + client_condition = ${if and {{!eq{$tls_out_cipher}{}} {eq{${extract{password}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{}fail}}{}}} } + public_name = LOGIN + client_send = : ${extract{user}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}{$value}fail} : ${extract{password}{${lookup{$sender_address_domain}lsearch{SMARTFN}}}} diff --git a/doc/smtp.md b/doc/smtp.md new file mode 100644 index 0000000..48f3d6c --- /dev/null +++ b/doc/smtp.md @@ -0,0 +1,66 @@ +# Outbound mail through SMTP + +The cloud services now all support OAUTH2 as an authentication method for +SMTP, and CMS provides an internal broker service to acquire and expose the +OAUTH access token needed for SMTP. + +This allows the use of several normal SMTP tools without having to revert +to BASIC authentication. + +## CMS Configuration + +CMS uses a UNIX domain socket to expose the access token. CMS must be running +to maintain a fresh token. + +This feature is enabled in the configuration file: + +```Python +account = Office365_Account(user="user@domain.com") +Office365("inbox", account) +CredentialServer("/var/run/user/XXX/cms.sock", + accounts=[account]) +``` + +Upon restart CMS will acquire and maintain a OAUTH token with the SMTP scope +for the specified accounts, and serve token requests on the specified path. + +# exim 4 + +Exim is a long standing UNIX mail system that is fully featured. exim's flexible +authentication can support the use of OAUTH tokens: + +``` +begin authenticators + +xoauth2_smart: + driver = plaintext + client_condition = ${if !eq{$tls_out_cipher}{}} + public_name = XOAUTH2 + client_ignore_invalid_base64 = true + client_send = : ${readsocket{/home/XX/mail/.cms/exim/cms.sock}{SMTP user@domain}} +``` + +Since exim runs as a system daemon, permissions must be set to allow access to +the socket: + +```sh +cd /home/XX/mail/.cms +mkdir exim +chmod 0750 exim +sudo chgrp Debian-exim cms +``` + +And the CMS configuration must specify a umask: + +```Python +CredentialServer("/home/XX/mail/.cms/exim/cms.sock", + accounts=[account], + umask=0o666) +``` + +A fully functional [exim4.conf](example-exim4.conf) is provided. This minimal, +relay only config can replace the entire configuration from the distro, after +making the adjustments noted. In this mode /usr/bin/sendmail will be fully +functional for outbound mail and if multiple accounts are required, it will +automatically choose the account to send mail through based on the Envelope +From header. |