Table of Contents
Abstract
This document contains step by step instructions to install automx.
If you haven't done so yet download automx from its website.
$ wget http://automx.org/download/latest.tar.gz
Unpack the tar archive and change into the newly created directory.
$ tar xzf latest.tar.gz
$ cd automx-VERSION
automx is a Python application. You must install a few extra modules to handle frontend and backend communication as well to deal with XML data.
Install mod_wsgi for the Apache web server and the python-wsgi module.
If you plan to use either LDAP or SQL as backends to retrieve configuration options from install ldap for LDAP and python-sqlalchemy for SQL. Further you also need to install the SQL backend driver that communicates with your database. For MySQL this might be mysqldb.
Install python lxml or automx will not be able to handle the XML data it needs to deal with.
Once you've satisfied the requirements, you can start to install automx.
automx is a wsgi script depending on some automx-specific libraries. It reads its configuration from a single configuration file. The program, the libraries and the configuration file need to be installed at different locations.
Create a directory for the automx program and copy it to that location:
% mkdir -p
/usr/local/lib/automx
% cp automx-VERSION/automx.wsgi /usr/local/lib/automx/
Copy the automx-test program to a location that
is in your $PATH
:
% cp automx-VERSION/automx-test /usr/local/bin/automx-test
Python provides a directory with site specific packages, called site-packages. Copy the automx directory including all its files to site-packages:
% cp automx-VERSION/automx /usr/local/lib/python2.6/site-packages/
site-packages | |
---|---|
The location of that directory depends on the Python version and the distribution you use. |
Place the sample automx.conf file into /etc.
% cp automx-VERSION/src/conf/automx.conf /etc/
Follow automx.conf(5) Adopt this configuration file to your needs. You may find detailed information in the man page automx.conf(5).
Tip | |
---|---|
Set |
Mail clients seeking mail account autoconfiguration will either
request an IP address for
autoconfig.
(Mozilla schema) or
example.com
autodiscover.
(Microsoft schema). Provide settings in your DNS that directs them to the
server running the automx service:example.com
autoconfig.example.com. IN A 192.168.2.1 autodiscover.example.com. IN A 192.168.2.1
Finally configure the web server. It will accept configuration requests from mail clients, pass the information to automx and in turn will respond with account profiles once automx has figured out the details.
First enable the wsgi module. Follow your OS documentation to find out how it needs to be done.
automx is able to provision mail clients following the Mozilla autoconfig schema as well as mail clients following the Microsoft autodiscover schema. Both schemas have different requirements regarding hostname, port and level of security when a request is sent to the configuration server:
Mail clients following the Microsoft autodiscover schema
require a https connection. The web server must identify itself as
autodiscover.example.com
on port
443
and it must use a
valid server certificate that is trusted by the mail client
requesting configuration.
Mail clients following the Mozilla autoconfig schema can use
either a http or a https connection. The web server must identify
itself as autoconfig.example.com
on port
80
or 443
. If it connects on 443
a valid server certificate that is
trusted by the mail client requesting configuration has to be
used.
Here is a simple example that configures an autoconfig and an autodiscover service - both use the same automx script:
<VirtualHost *:80> ServerName example.com ServerAlias autoconfig.example.com ServerAdmin webmaster@example.com <IfModule mod_wsgi.c> WSGIScriptAlias /mail/config-v1.1.xml /usr/local/lib/automx/automx.wsgi <Directory "/usr/local/lib/automx"> Order allow,deny Allow from all </Directory> </IfModule> </VirtualHost> <VirtualHost *:443> ServerName example.com:443 ServerAlias autoconfig.example.com:443 ServerAdmin webmaster@example.com <IfModule mod_wsgi.c> WSGIScriptAlias /Autodiscover/Autodiscover.xml /usr/local/lib/automx/automx.wsgi WSGIScriptAlias /autodiscover/autodiscover.xml /usr/local/lib/automx/automx.wsgi <Directory "/usr/local/lib/automx"> Order allow,deny Allow from all </Directory> </IfModule> </VirtualHost>
ISPs | |
---|---|
In an advanced environment with thousands of domains, you can
redirect mail clients via DNS entries to your ISP
autoconfig.example.com. IN A 192.168.2.1 autodiscover.example.com. IN A 192.168.2.1 |
automx comes with a little utility that helps testing proper operation. The next section explains how to use it.
The automx-test utility sends configuration requests for Microsoft and Mozilla clients to the web server:
$ automx-test
user@example.com
The domainpart in the address determines the list of hostnames
that will be queried. In this example
|
You should see the web server header and get XML results from the server.
If things go wrong, the
is your friend. It
will indicate configuration issues, if python modules are missing, if your
database can not be queried or anything else that might go wrong.error.log
Note | |
---|---|
If you split error logs by port, e.g. port
|