Email Client Autoconfiguration (Thunderbird and Outlook, using static files)

Many email clients include the ability to automatically look up mail server settings once a user enters an email address, which saves the user time and reduces the chance for user error. Mozilla have developed one standard, and Microsoft another, and of course they aren't compatible, though they can both be implemented fairly simply on your Neth server. Many other email clients will use one or the other of these methods; a notable exception is Apple Mail on both iOS and OS X–Apple Mail uses yet a different method that will be addressed separately at a later time.

This guide is heavily based on this blog post, this page and this page from Mozilla's documentation, and this page from Microsoft's documentation.

Overview

When a user sets up a new mail account, both email clients try several methods to determine the correct server settings. The simplest one for us to use is to set up a configuration server. This will be a virtual host with a hostname of autoconfig.yourdomain, whose only purpose will be to serve up an XML file. Unfortunately, Microsoft and Mozilla can’t agree on what that XML file should look like, so you’ll need to create two separate files to cover both clients.

The Virtual Host

Begin by creating a DNS entry for autoconfig.yourdomain, pointing to your Nethserver installation. Since every DNS host is different, you’re on your own here.

Next, create a virtual host. In the Nethserver server manager, go to the Virtual Hosts page and click the Create New button. Enter autoconfig as the name, any description you like, and autoconfig.yourdomain in the Virtual Host Names (FQDN) field. If you handle email for more than one domain, you can enter them all here: autoconfig.domain1,autoconfig.domain2. If users will be accessing their email remotely, uncheck the “Allow access from trusted networks only” box. Check “Require SSL”, and uncheck “Enable FTP”. Click the red Submit button.

SSL Certificate

Since you've added a hostname to your system, you'll need to update your TLS certificate to include that hostname. If you added a Let's Encrypt certificate through the server-manager, consult the manual for further information. If you used another method to obtain the certificate, you'll again be on your own here.

Thunderbird Configuration

Now that the virtual host is created, you’ll need to create the config file. SSH in to your Nethserver, cd /var/lib/nethserver/vhost/autoconfig/, mkdir mail, and nano mail/config-v1.1.xml. Substitute your favorite text editor, if it isn’t nano.

You’ll now need to enter the contents of the configuration file. It should look like the sample below, although the displayName and displayShortName fields can be changed to whatever you like (they are what will be used as the “account name” in Thunderbird).

<?xml version="1.0" encoding="UTF-8"?>

<clientConfig version="1.1">
  <emailProvider id="yourdomain">
    <domain>yourdomain</domain>
    <displayName>Yourdomain Mail</displayName>
    <displayShortName>Yourdomain</displayShortName>
    <incomingServer type="imap">
      <hostname>imap.yourdomain</hostname>
      <port>143</port>
      <socketType>STARTTLS</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <outgoingServer type="smtp">
      <hostname>smtp.yourdomain</hostname>
      <port>587</port>
      <socketType>STARTTLS</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </outgoingServer>
  </emailProvider>
</clientConfig>

Save that file, then chown -R apache mail.

You’re done with the configuration for Thunderbird. When a Thunderbird user sets up a new email account, and enters an email address of user@yourdomain, Thunderbird will retrieve http://autoconfig.yourdomain/mail/config-v1.1.xml1 and read how to set up the account. Your user will only need to know their email address and password.

Outlook Configuration

Outlook works similarly, but we’ll also need to publish another DNS record to tell it to look at your autoconfig Virtual Host for this file. To do this, log in to your DNS provider and create a SRV record for _autodiscover._tcp.yourdomain with a setting of 0 0 443 autoconfig.yourdomain. Then, back at the shell for your Neth server, change back to the directory for your virtual host (cd /var/lib/nethserver/vhost/autoconfig/), make a new directory called Autodiscover (mkdir Autodiscover), and create the autodiscover XML file (nano Autodiscover/Autodiscover.xml). Its contents should look like the example below, but again, DisplayName can be changed to whatever you like:

<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/responseschema/2006">
  <Response xmlns="http://schemas.microsoft.com/exchange/autodiscover/outlook/responseschema/2006a">
    <User>
      <DisplayName>YourDomain</DisplayName>
    </User>
    <Account>
      <AccountType>email</AccountType>
      <Action>settings</Action>
      <Protocol>
        <Type>IMAP</Type>
        <Server>imap.yourdomain</Server>
        <Port>143</Port>
        <DomainRequired>off</DomainRequired>
        <SPA>off</SPA>
        <Encryption>TLS</Encryption>
        <AuthRequired>on</AuthRequired>
      </Protocol>
      <Protocol>
        <Type>SMTP</Type>
        <Server>smtp.yourdomain</Server>
        <Port>587</Port>
        <DomainRequired>off</DomainRequired>
        <SPA>off</SPA>
       	<Encryption>TLS</Encryption>
        <AuthRequired>on</AuthRequired>
      </Protocol>
    </Account>
  </Response>
</Autodiscover>

Again, chown -R apache Autodiscover to make the apache user the owner of that directory and file.

Conclusion

Once you've completed these steps, your users will be able to configure email clients who follow either Thunderbird's or Outlook's standard by simply entering their email address and password. This will give faster, easier, more accurate setup for them, and should mean fewer support requests for you.