Skip to content

Latest commit

 

History

History
110 lines (83 loc) · 5.04 KB

config.adoc

File metadata and controls

110 lines (83 loc) · 5.04 KB

Configuring automx2

automx2 uses a file to read runtime instructions from and a database to lookup mail account configuration data.

Placeholders

To make configuration more convenient, automx2 supports Mozilla-style placeholders. For example, the string %EMAILADDRESS% in database records will be replaced with the email address specified during the query. While based on a proprietary feature of Autoconfig, automx2 also applies placeholders to Autodiscover and Mobileconfig responses.

Runtime configuration

The configuration file defines automx2 runtime behaviour, and it specifies the backend automx2 should read mailbox account configuration data from.

Note
Running without runtime config

If you launch automx2 without a configuration file, it will use internal defaults. These are suitable for testing only. Launched without a config it will use an in-memory SQLite database and all data will be lost once the application terminates.

During startup automx2 searches for runtime configuration instructions in the following locations. The first match will determine the configuration used.

env  : AUTOMX2_CONF  (1)
file : ~/.automx2.conf
file : /etc/automx2/automx2.conf
file : /etc/automx2.conf

  1. If present, the environment variable AUTOMX2_CONF must point to the absolute path of a configuration file.

To specify parameters and options automx2 uses an INI file syntax. The example configuration that ships with automx2 looks like this:

link:../contrib/automx2-sample.conf[role=include]

Place the content of the example configuration into one of the configuration locations automx2 looks for and adapt it to your needs. Then configure the database backend with data that suits your setup, as described below.

Testing standalone automx2

If you want to verify a vanilla installation of automx2 works, you can populate it with internal test data. Start automx2 as described in section [run] and send the following request to populate your database:

curl http://127.0.0.1:4243/initdb/

This example assumes you are running automx2 on localhost listening on TCP port 4243, which is the suggested default port.

Once you have populated the database with sample data you can test if automx2 works. Use curl to send an account configuration request for [email protected]:

curl 'http://127.0.0.1:4243/mail/[email protected]&name=Alice%20Jones'

As shown in the example, make sure to quote the URL as necessary. Otherwise, your command shell might perform pattern matching for characters like the question mark ? (FISH does).

Password support

For a long time I have been averse to supporting passwords in the generated configuration data, because of the risks involved. By the very nature of the process, cleartext passwords are required. This means that passwords can potentially be intercepted in transit, e.g. between a HTTPS proxy and automx2. Even worse, should the receiving user decide to save a configuration file locally, that file will contain the user’s password in plain text, visible for everybody with read access to the file. Also, depending on how automx2 is configured, cleartext passwords can potentially be written to log files.

Alas, my reluctance to implement password support has resulted in some code forks where people added the feature anyway. To mitigate this, I decided to provide a limited implementation. automx2 version 2024.2 introduced password support for Apple’s Mobileconfig. iOS devices download configuration profiles into a staging area by default, not offering the user an easy method to save the data elsewhere.

The password support feature is deliberately disabled by default. To opt in, you need to set the environment variable PERMIT_CLEARTEXT_PASSWORDS=I_understand_the_risks.

Important
Your responsibility

Caveat emptor: By opting in to this feature, you acknowledge that you take responsibility for any possible harm that could result from leaked passwords. Please ask yourself if a small amount of added convenience for users, i.e. having to enter their passwords less often during infrequently occurring device setups, is worth the risks.

Once the feature is activated, you can send GET requests with additional parameters. Sending a password with support disabled will result in an error log message, and the supplied password will be ignored. URL encoding is very important here. I suggest that you create a HTML landing page for your users, with explanation about the risks inolved. Include a <form> to submit the necessary fields to automx2.

curl 'http://127.0.0.1:4243/[email protected]&name=John%20Doe&password=ThisIsInsecure'