I’ve been reading up a bit on how to automate, or at least simplify, configuration of email clients to connect to Nethserver. Unfortunately, there doesn’t appear to be any one standard–Thunderbird, Outlook, and iOS/Mac OSX Mail all use different methods to accomplish this. Thunderbird and Outlook are relatively simple, and fairly straightforward, so I’ll describe them here.
The issue
The purpose of this short write-up is to make it easier on your users to correctly configure their email accounts in Thunderbird or Outlook. Once you set this up, they’ll only need to enter their email address and password, and the mail client will contact your server for the rest of the details (mail server names, protocols, port numbers, encryption support, etc.). This how-to is heavily based on Mozilla’s documentation here and here, this blog post, and 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.
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.
<?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.xml 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.
Note: The information for Outlook above is based on the documentation–I don’t have a copy of MS Outlook here to test with. However, test results from Microsoft indicate it’s working on my system.
