Automx2

automx2 - Dienst zur automatischen Konfiguration von E-Mail-Clients

Beschreibung

automx2 ist ein Webdienst.

• Es befindet sich normalerweise hinter einem Webserver und wartet auf Konfigurationsanfragen
• Wenn ein E-Mail-Benutzeragent (MUA), auch als E-Mail-Client bezeichnet, eine Konfiguration anfordert, kontaktiert er den Webserver.
• Der Webserver fungiert dann als Proxy und leitet alle Anfragen an automx2 weiter und gibt Antworten an den MUA zurück.

Image:Bild1.png

Installation

automx2 benötigt zur Ausführung Python ab Version 3.7, idealerweise in Form einer virtuellen Python-Umgebung. Überprüfen Sie die Python3-Version wie folgt:

$ python3 --version
Python 3.9.9

Nicht als root ausführen

Wenn Sie eine Portnummer größer als 1024 verwenden (ich schlage Port 4243 vor), benötigt die Anwendung beim Ausführen keine Superuser-Rechte.

• Dies würde ein Sicherheitsrisiko darstellen und wird daher dringend davon abgeraten.
• Ich empfehle die Erstellung eines neuen Benutzerkontos namens automx2.

Bereiten Sie die virtuelle Umgebung für den automx2-Webdienst vor, indem Sie den Installationspfad nach Ihrem Geschmack anpassen (automx2 selbst kümmert sich nicht darum).

• Der Weg /srv/web/automx2wird in dieser Dokumentation als Beispiel verwendet.
• Die folgenden BASH-Shell-Befehle sollten mit jeder modernen Linux-Distribution funktionieren.

1. Best practice: Create a fresh user account.

# useradd --home-dir /srv/web/automx2 --create-home automx2

1. Alternative: If the user account already exists.

# bash -c 'mkdir -p /srv/web/automx2 && chown automx2 /srv/web/automx2'

Stellen Sie als Nächstes sicher, dass Sie sich entweder als der oben erstellte Benutzer anmelden oder über den Befehl „su“ zu diesem Benutzer wechseln.

• Dies ist wichtig, um die richtigen Dateiberechtigungen sicherzustellen.
• Laden Sie das Skript herunter, das Ihren automx2-Dienst herunterlädt und einrichtet:

cd /srv/web/automx2
wget https://github.com/rseichter/automx2/raw/master/contrib/setupvenv.sh
chmod u+x setupvenv.sh

Durch Ausführen des Setup-Skripts wird eine virtuelle Python-Umgebung namens erstellt .venvim aktuellen Verzeichnis.

./setupvenv.sh

Aktivieren Sie die virtuelle Umgebung und installieren Sie die neueste automx2-Version von PyPI.

• Stellen Sie sicher, dass Sie die richtige Aktivierung für Ihre Shell aus der auswählen .venv/binVerzeichnis.
• Dies ist ein Beispiel für BASH:

source .venv/bin/activate
pip install automx2

Aktualisieren auf eine neuere automx2-Version Wechseln Sie in das Verzeichnis, in dem zuvor automx2 installiert wurde. Aktivieren Sie die virtuelle Umgebung wie gewohnt und verwenden Sie Pips --upgrade option: cd /srv/web/automx2 source .venv/bin/activate pip install --upgrade automx2

Konfiguration

automx2 verwendet eine Datei, um Laufzeitanweisungen zu lesen, und eine Datenbank, um Konfigurationsdaten für E-Mail-Konten nachzuschlagen.

Platzhalter

Um die Konfiguration bequemer zu machen, unterstützt automx2 Platzhalter im Mozilla-Stil .

• Zum Beispiel die Zeichenfolge %EMAILADDRESS%in Datenbankeinträgen wird durch die bei der Abfrage angegebene E-Mail-Adresse ersetzt.
• Obwohl automx2 auf einer proprietären Funktion von Autoconfig basiert, wendet es Platzhalter auch auf Autodiscover- und Mobileconfig-Antworten an.

Laufzeitkonfiguration

Die Konfigurationsdatei definiert das Laufzeitverhalten von automx2 und gibt das Backend an, aus dem automx2 die Konfigurationsdaten des Postfachkontos lesen soll.

Läuft ohne Laufzeitkonfiguration
Wenn Sie automx2 ohne Konfigurationsdatei starten, verwendet es interne Standardeinstellungen. 
* Diese sind nur zum Testen geeignet. 
* Wird es ohne Konfiguration gestartet, verwendet es eine In-Memory-SQLite-Datenbank und alle Daten gehen verloren, sobald die Anwendung beendet wird. 

Während des Starts sucht automx2 an den folgenden Stellen nach Anweisungen zur Laufzeitkonfiguration.

• Die erste Übereinstimmung bestimmt die verwendete Konfiguration.

env  : AUTOMX2_CONF  
file : ~/.automx2.conf
file : /etc/automx2/automx2.conf
file : /etc/automx2.conf

Falls vorhanden, muss die Umgebungsvariable AUTOMX2_CONF auf den absoluten Pfad einer Konfigurationsdatei zeigen.

Um Parameter und Optionen anzugeben, verwendet automx2 eine INI Dateisyntax .

• Die Beispiel Konfiguration , die mit automx2 geliefert wird, sieht so aus:

[automx2]
# A typical production setup would use loglevel WARNING.
loglevel = DEBUG
# Echo SQL commands into log? Used for debugging.
db_echo = no
# In-memory SQLite database
db_uri = sqlite:///:memory:

# SQLite database in a UNIX-like file system
#db_uri = sqlite:////var/lib/automx2/db.sqlite

# MySQL database on a remote server. 

• This example does not use an encrypted

# connection and is therefore *not* recommended for production use.
#db_uri = mysql://username:password@server.example.com/db

# Number of proxy servers between automx2 and the client (default: 0).
# If your logs only show 127.0.0.1 or ::1 as the source IP for incoming
# connections, proxy_count probably needs to be changed.
proxy_count = 1

Platzieren Sie den Inhalt der Beispielkonfiguration an einem der von automx2 gesuchten Konfigurationsorte und passen Sie ihn an Ihre Bedürfnisse an.

• Konfigurieren Sie dann das Datenbank-Backend mit Daten, die zu Ihrem Setup passen, wie unten beschrieben.

Automx2 eigenständig testen

Wenn Sie überprüfen möchten, ob eine Vanilla-Installation von automx2 funktioniert, können Sie sie mit internen Testdaten füllen.

• Starten Sie automx2 wie im Abschnitt Ausführen von automx2 und senden Sie die folgende Anfrage, um Ihre Datenbank zu füllen:

curl http://127.0.0.1:4243/initdb/

Dieses Beispiel geht davon aus, dass Sie automx2 auf localhost ausführen und TCP-Port 4243 abhören, was der vorgeschlagene Standardport ist.

Nachdem Sie die Datenbank mit Beispieldaten gefüllt haben, können Sie testen, ob automx2 funktioniert.

• Verwenden Sie curl, um eine Kontokonfigurationsanforderung für user@example.com zu senden:

curl 'http://127.0.0.1:4243/mail/config-v1.1.xml?emailaddress=user@example.com'

Achten Sie, wie im Beispiel gezeigt, darauf, die URL nach Bedarf in Anführungszeichen zu setzen.

• Andernfalls führt Ihre Befehlsshell möglicherweise einen Musterabgleich für Zeichen wie das Fragezeichen durch ?(FISCH tut es).

Datenbankkonfiguration

automx2 verwendet das SQLAlchemy-Toolkit, um auf Datenbanken zuzugreifen.

• Dadurch können verschiedene Datenbanken, auch Dialekte genannt , verwendet werden, indem einfach die entsprechende Verbindungs-URL definiert wird.

API-basierte Konfiguration Ich erwäge das Hinzufügen einer API für Konfigurationsänderungen in einer kommenden Version, habe aber noch nicht entschieden, wann dies geschehen könnte. können Sie mich gerne kontaktieren Patenschaft .

Datenbankunterstützung

Während Sie wahrscheinlich bereits SQLite-Unterstützung auf Ihrem lokalen Computer haben, müssen Sie möglicherweise zusätzliche Python-Pakete für PostgreSQL, MySQL usw.

• installieren.
• Detaillierte Anweisungen zur Unterstützung eines bestimmten Datenbankdialekts sind in diesem Dokument nicht enthalten.
• Bitte suchen Sie im Internet nach detaillierten Anweisungen zur Unterstützung eines bestimmten Dialekts.
• Die SQLAlchemy-Dokumentation bietet einen nützlichen Ausgangspunkt.

Während contribVerzeichnis Beispieldatenbankschemata enthält, die Sie als Referenz verwenden können, empfehle ich die Verwendung der integrierten Methode, um die erforderliche DB-Struktur von Grund auf neu zu erstellen, indem Sie auf die zugreifen /initdb/Dienstendpunkt.

• Dadurch wird die Datenbank auch mit einigen Beispieldaten gefüllt.

Wenn Sie von einer frühen automx2-Version aktualisieren und Ihre vorhandene Datenbank migrieren möchten, können Sie die integrierte Alembic-Unterstützung verwenden.

• Dies erfordert jedoch das Klonen des Git-Repositorys, das Ändern alembic.iniund Aufrufen der Migration von der Befehlszeile.
• Es ist normalerweise einfacher, Ihre vorhandenen Daten zu exportieren, eine neue DB zu erstellen und die Daten zu importieren.

SQLite

Dieser Abschnitt zeigt, was Sie tun müssen, um SQLite Version 3 oder höher als Backend-Datenbank für automx2 zu verwenden.

Schritt 1: Legen Sie den Datenbank-URI in Ihrer automx2-Konfiguration fest.

• Bitte beachten Sie, dass die Angabe eines absoluten Pfades für die Datenbank insgesamt vier Schrägstriche nach der Schema-Kennung erfordert:

[automx2]
db_uri = sqlite:////var/lib/automx2/db.sqlite

Schritt 2: Starten Sie automx2 und greifen Sie auf die DB-Initialisierungs-URL zu:

curl http://127.0.0.1:4243/initdb/

Das Git-Repository enthält ein sqlite-generate.sh-Hilfsskript , das demonstriert, wie die Datenbank programmgesteuert gefüllt werden kann.

• Sie müssen nur wenige Einstellungen Ihren Bedürfnissen anpassen:

PROVIDER_NAME='Example Inc.'
PROVIDER_SHORTNAME='Example'
PROVIDER_ID=100

DOM='example'
TLD='com'

Das Skript gibt die SQL-Anweisungen auf der Standardausgabe aus, an die weitergeleitet werden kann sqlite3zum Bearbeiten.

• Stellen Sie sicher, dass die automx2.conf übereinstimmt db_uriEinstellung bei der Angabe der Datenbank.

contrib/sqlite-generate.sh | sqlite3 /var/lib/automx2/db.sqlite

Sobald Sie die Datenbank gefüllt haben, ist automx2 betriebsbereit.

MySQL

Schritt 1: Erstellen Sie eine Datenbank.

CREATE DATABASE `automx2` COLLATE 'utf8mb4_general_ci';

Schritt 2: Legen Sie den Datenbank-URI in Ihrer automx2-Konfiguration fest.

• Das folgende Beispiel verwendet pymysql als DB-Treiber, der nicht in der automx2-Distribution enthalten ist.

[automx2]
db_uri = mysql+pymysql://user:pass@dbhost/automx2?charset=utf8mb4

Schritt 3: Starten Sie automx2 und greifen Sie auf die DB-Initialisierungs-URL zu:

curl http://127.0.0.1:4243/initdb/

Alembic

Wie in einem vorherigen Abschnitt erwähnt, können Sie Alembic , um Ihre Datenbank zu erstellen oder zu aktualisieren.

• Sie müssen Ihren ersten Lauf mit einer leeren Datenbank starten, damit dies funktioniert, da Alembic Versionsinformationen in dieser Datenbank speichert.
• Datenbank-Upgrades basieren auf diesen Informationen.
• Befolgen Sie die nachstehenden Schritte, um die einzustellen RELEASE-Variable zum GitHub-Tag oder zur Release-Nummer Ihrer Wahl.

export RELEASE="2021.6"
wget https://github.com/rseichter/automx2/archive/refs/tags/$RELEASE.zip
unzip $RELEASE.zip
cd automx2-$RELEASE/alembic

Ändern Sie als Nächstes den Wert für sqlalchemy.url in alembic.inipassend zu Ihrer automx2-Konfiguration.

• Erstellen Sie eine leere Datenbank, es sei denn, Sie verwenden SQLite.
• In diesem Fall erstellt Alembic die Datenbank für Sie.
• Die letzten Schritte sind die Aktivierung der virtuellen Python-Umgebung automx2 und das Aufrufen von make .

source /path/to/automx2/.venv/bin/activate
make upgrade

Sie sollten eine Ausgabe ähnlich der folgenden sehen:

PYTHONPATH=.. 

• FLASK_APP=automx2.server:app flask db upgrade -d .

Running automx2 version 2021.6
INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [alembic.runtime.migration] Running upgrade  -> f62e64b43d2f, DB schema for automx2 version 2020.0
Created: 2020-01-17 22:30:05.748651
INFO  [alembic.runtime.migration] Running upgrade f62e64b43d2f -> 5334f8a8282c, Add "prio" column to "server" table.
Created: 2020-12-15 15:04:49.371802
INFO  [alembic.runtime.migration] Running upgrade 5334f8a8282c -> 43ebb40d0578, DAV server support

Konfigurieren eines Webservers

Obwohl es technisch möglich ist, automx2 ohne einen Webserver davor zu betreiben, empfehle ich dies nicht in einer Produktionsumgebung.

• Ein Webserver kann Funktionen bereitstellen, für die automx2 nicht entwickelt wurde.
• Features wie die Kryptografie der Transportschicht für HTTPS (erforderlich für Mobileconfig ) oder beispielsweise die Möglichkeit, Clients zu begrenzen, werden von vollwertigen Webservern, die als Reverse-Proxys arbeiten, sehr gut gehandhabt.
• Es wäre Verschwendung, all dies in einem Webdienst neu zu implementieren.

In diesem Abschnitt wird erläutert, wie Sie einen Webserver als Reverse-Proxy vor automx2 konfigurieren.

• Bevor Sie den Proxy einrichten, müssen Sie automx2 mitteilen, dass er hinter einem Proxy arbeitet.
• Ergänzen Sie die proxy_countParameter in Ihre automx2-Konfigurationsdatei oder kommentieren Sie den Parameter aus, wenn er bereits vorhanden ist:

[automx2]
# A typical production setup would use loglevel = WARNING
loglevel = WARNING

# Disable SQL command echo.  
db_echo = no

# SQLite database in a UNIX-like file system
db_uri = sqlite:////var/lib/automx2/db.sqlite

# Number of proxy servers between automx2 and the client (default: 0).
# If your logs only show 127.0.0.1 or ::1 as the source IP for incoming
# connections, proxy_count probably needs to be changed.  
proxy_count = 1

Das Echoen von SQL-Befehlen ist nur für Debugging-Zwecke gedacht
Stellen Sie die Zahl so ein, dass sie die Anzahl der Proxys widerspiegelt, die vor automx2 verkettet sind, dh die Anzahl der "Proxy-Hops", die eine Client-Anfrage passieren muss, bevor sie automx2 erreicht. 

Apache

Das folgende Beispiel zeigt eine ähnliche Apache-Konfiguration wie oben. ProxyPreserveHostAnweisungen veranlassen Apache, relevante Daten über die Herkunft eingehender Anfragen weiterzugeben.

# Apache 2.4 example configuration snippet to forward incoming requests to automx2.
# vim:ts=4:sw=4:et:ft=apache

<VirtualHost *:80>
    ServerName autoconfig.example.com
    ServerAlias autodiscover.example.com
    ProxyPreserveHost On
    ProxyPass "/" "http://127.0.0.1:4243/"
    ProxyPassReverse "/" "http://127.0.0.1:4243/"
    <Location /initdb>
        # Limit access to clients connecting from localhost
        Order Deny,Allow
        Deny from all
        Allow from 127.0.0.1
    </Location>
</VirtualHost>

Anwendung

Automx2 lokal testen

Sie können curl in einer Befehlsshell verwenden, um eine GET-Anforderung an Ihre lokale automx2-Instanz zu senden.

• Das folgende Beispiel geht davon aus, dass Ihr Dienst auf localhost auf Port 4243 ausgeführt wird.
• Die genaue Ausgabe hängt von Ihrem Datenbankinhalt ab, sollte aber ähnlich aussehen.

curl 'http://127.0.0.1:4243/mail/config-v1.1.xml?emailaddress=user@example.com'
<clientConfig version="1.1">
    <emailProvider id="automx2-100">
        <identity/>
        <domain>example.com</domain>
        <displayName>Example Inc.</displayName>
        <displayShortName>Example</displayShortName>
        <incomingServer type="imap">
            <hostname>mail.example.com</hostname>
            <port>993</port>
            <socketType>SSL</socketType>
            <username>%EMAILADDRESS%</username>
            <authentication>plain</authentication>
        </incomingServer>
        <incomingServer type="pop3">
            <hostname>mail.example.com</hostname>
            <port>110</port>
            <socketType>STARTTLS</socketType>
            <username>%EMAILADDRESS%</username>
            <authentication>plain</authentication>
        </incomingServer>
        <outgoingServer type="smtp">
            <hostname>mail.example.com</hostname>
            <port>587</port>
            <socketType>STARTTLS</socketType>
            <username>%EMAILADDRESS%</username>
            <authentication>plain</authentication>
        </outgoingServer>
    </emailProvider>
</clientConfig>

Nachdem Sie überprüft haben, dass automx2 Konfigurationsdaten zurückgibt, sollten Sie den Dienst mithilfe eines Webservers als Proxy verfügbar machen.

Links

Weblinks

1. Mailingliste
2. Issue-Tracker
3. https://rseichter.github.io/automx2/#muaconf