// vim: ts=4 sw=4 et ft=asciidoc

[[configure]]
== Configuring automx2

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

[[placeholders]]
=== Placeholders

To make configuration more convenient, automx2 supports https://wiki.mozilla.org/Thunderbird:Autoconfiguration:ConfigFileFormat#Placeholders[Mozilla-style placeholders,window=_blank].
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.

[source,txt]
----
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
link:https://docs.python.org/3.9/library/configparser.html#supported-ini-file-structure[INI
file] syntax.
The
link:https://github.com/rseichter/automx2/blob/master/contrib/automx2-sample.conf[example
configuration] that ships with automx2 looks like this:

[source,ini]
----
include::../contrib/automx2-sample.conf[]
----

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:

[source,bash]
----
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 +user@example.com+:

[source,bash]
----
curl 'http://127.0.0.1:4243/mail/config-v1.1.xml?emailaddress=alice@example.com&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 years I have refused to support 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, if the receiving user foolishly decides 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.

My reluctance to implement password support has resulted in some code forks where people added the feature anyway.
Recognising the desire for password support, I have decided on a compromise.
automx2 version 2025.2 introduces password support, but for the time being only for Apple's Mobileconfig.
This is due to iOS devices downloading configuration profiles to a staging area by default, not offering the user an easy method to save the data elsewhere.

Note that 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`.
If you don't know what that means, I suggest you hold off on this feature until you have done some research.

[IMPORTANT]
.Your responsibility
====
Caveat emptor: By opting in, and I recommend that you do _not_ opt in, you acknowledge that you take full responsibility for any and all harm that could result from leaked passwords.
Please ask yourself if a bit of added convenience for users, i.e. having to enter passwords less frequently during a one-time device setup, 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.

[source,bash]
----
curl 'http://127.0.0.1:4243/mobileconfig?emailaddress=jd@example.com&name=John%20Doe&password=ThisIsInsecure'
----
