%
% automx.tex
% Last Update: $Id$
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Kapitel Automx %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Achtung: Dateien muessen mit latin1-Encoding gespeichert werden!
% Attention: Files must be saved using latin1 encoding!
%

\chapter{Das automx-Paket}

\section{Die Einleitung}

    Das automx-Paket (\url{https://automx.org/}) stellt einen Webservice
    bereit, welcher vollautomatisch Provisionierungsanfragen ihrer
    E-Mail-Programme beantwortet. Anwender m"ussen nur ihren Namen, die
    E-Mail-Adresse und ihr Kennwort angeben, das E-Mail-Programm und
    automx erledigen den Rest. Aktuell werden die Provisionierungsstandards
    von Apple, Microsoft und Mozilla unterst"utzt.

\section{Die Funktionen}

    Das automx-Paket besteht aus folgender Komponente:

    \begin{itemize}
        \item automx - Der automx-Webservice.\\
              (\url{https://automx.org/})
    \end{itemize}


\section{Die Voraussetzungen}

    Zur Nutzung des Programms werden ein installiertes apache2-mod\_wsgi-
    und diverse Python-Programmpakete ben"otigt.


\section{Die Installation}

    Das automx-Paket wird "uber das Setup-Men"u installiert. Wird
    eine "altere Paketversion vorgefunden, so wird diese deinstalliert
    bevor die neuen Programmdateien installiert werden.


\section{Das Men"u im Setup-Programm}

    Das Men"u im Setup-Programm ist wie folgt aufgebaut:

    \begin{itemize}
        \item View documentation: Anzeigen der Dokumentation
        \item Edit configuration: Bearbeiten der Konfiguration
        \item Check email account data: Pr"ufen von individuellen E-Mail-Daten
        \item Check automx email configuration: Pr"ufen einer individuellen
              automx-Konfiguration
        \item View log file: Die Logmeldungen anzeigen
        \item Return: Untermen"u verlassen
    \end{itemize}

    Die Men"upunkte d"urften selbsterkl"arend sein, da sie keinerlei weitere
    Eingaben erwarten. Aus diesem Grund wird auf deren Funktion nicht weiter
    eingegangen.


\section{Die "Anderung der Konfiguration}

    Die Konfiguration kann "uber den Men"upunkt 'Edit configuration'
    ge"andert werden. Standardm"a"sig wird der Editor aufgerufen, der in
    der Environment-Konfiguration "uber die Variable 'EDITOR' festgelegt
    wurde. Nachdem der Editor beendet wurde wird abgefragt, ob die
    Konfiguration aktiviert werden soll. Wird dies best"atigt, werden "uber
    ein Skript die Anpassungen umgehend wirksam gemacht.


\section{Die Konfigurationsdatei}

    In der Konfigurationsdatei, die "uber das Men"u zug"anglich ist, sind
    folgende Parameter vorhanden; wer sie von Hand editieren will findet
    sie unter /etc/config.d/automx.


\section{Die Parameter}

\begin{description}
%% JED - show this description only in the help file
 %  \config{AUTOMX\_DO\_DEBUG (Optionaler Parameter)}{AUTOMX\_DO\_DEBUG}{AUTOMXDODEBUG}
 %      Um den Debug-Modus zu aktivieren muss diese Parameter
 %      lediglich auf den Wert `yes' gestellt werden, die Einstellung
 %      `no' deaktiviert den Debug-Modus.
 %
 %      G"ultige Werte: yes, no
 %
 %      Standardeinstellung: \texttt{AUTOMX\_DO\_DEBUG='no'}

    \config{START\_AUTOMX}{START\_AUTOMX}{STARTAUTOMX}
        F"ur die Aktivierung des automx-Dienstes muss diese Variable
        lediglich auf den Wert `yes' gestellt werden. Die Einstellung
        'no' deaktiviert den automx-Dienst.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{START\_AUTOMX='no'}

    \config{AUTOMX\_ORDER}{AUTOMX\_ORDER}{AUTOMXORDER}
        "Uber diesen Parameter wird eingestellt in welcher Reihenfolge
        die verschiedenen E-Mail-Services zur Konfiguration angeboten
        werden sollen.

        G"ultige Werte: imap-pop3-smtp, pop3-imap-smtp

        Standardeinstellung: \texttt{AUTOMX\_ORDER='imap-pop3-smtp'}

    \config{AUTOMX\_ACCESS\_CONTROL\_IP (Optionaler Parameter)}{AUTOMX\_ACCESS\_CONTROL\_IP}{AUTOMXACCESSCONTROLIP}
        "Uber diesen Parameter legt man IP Adressen und/oder IP Netzwerke
        fest von bzw. aus denen ein Zugriff auf diesen Dienst zugelassen
        werden soll.\\
        Wird dieser Parameter nicht gesetzt, so werden standardm"a"sig die
        "uber die base-Konfiguration festgelegten Netzwerke (IP\_ETH\_x\_NETWORK
        und IP\_ETH\_x\_NETMASK) f"ur den Zugriff freigeschaltet.

        G"ultige Werte: Eine oder mehrere IP Adressen oder IP Netzwerke

        Beispiel: \texttt{AUTOMX\_ACCESS\_CONTROL\_IP='192.168.0.0/24'}

    \config{AUTOMX\_CERT\_NAME}{AUTOMX\_CERT\_NAME}{AUTOMXCERTNAME}
        "Uber diesen Parameter legt man das Serverzertifikat des
        automx-Dienstes fest, welcher E-Mail-Konfigurationsprofile
        bereitstellt.

        G"ultige Werte: Serverzertifikat

        Beispiel: \texttt{AUTOMX\_CERT\_NAME='autoconfig.local.lan'}

     \config{AUTOMX\_DOCUMENT\_ROOT (Optionaler Parameter)}{AUTOMX\_DOCUMENT\_ROOT}{AUTOMXDOCUMENTROOT}
        "Uber diesen Parameter kann ein vom Standard abweichendes
        Dokumentenstammverzeichnis festgelegt werden. Wird dieser
        Parameter nicht gesetzt, so wird der folgende Verzeichnispfad
        verwendet: /var/www/htdocs/automx .

        G"ultige Werte: absolute Pfadangabe

        Beispiel: \texttt{AUTOMX\_DOCUMENT\_ROOT='/srv/www/automx'}

    \config{AUTOMX\_APACHE2\_PREFIX (Optionaler Parameter)}{AUTOMX\_APACHE2\_PREFIX}{AUTOMXAPACHE2PREFIX}
        "Uber diesen Parameter kann auf Wunsch ein Dateinamensprefix
        f"ur die Apache2-Konfigurationsdatei festgelegt werden, um
        so die Ladereihenfolge der virtuellen Hostkonfigurationen zu
        beeinflussen.

        G"ultige Werte: Text, bestehend aus den Zeichen a-z, 0-9, -, \_, .

        Standardeinstellung: \texttt{AUTOMX\_APACHE2\_PREFIX=$''$}

    \config{AUTOMX\_CALDAV\_CARDDAV\_SERVER (Optionaler Parameter)}{AUTOMX\_CALDAV\_CARDDAV\_SERVER}{AUTOMXCALDAVCARDDAVSERVER}
        "Uber diesen Parameter legt man den zu verwendenden
        CalDAV/CardDAV-Server fest.

        G"ultige Werte: Nextcloud oder ownCloud

        Beispiel: \texttt{AUTOMX\_CALDAV\_CARDDAV\_SERVER='nextcloud'}

    \config{AUTOMX\_CALDAV\_ENABLED}{AUTOMX\_CALDAV\_ENABLED}{AUTOMXCALDAVENABLED}
        "Uber diesen kann auf Wunsch die Unterst"utzung f"ur eine
        automatische CalDAV-Konfiguration aktiviert werden.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{AUTOMX\_CALDAV\_ENABLED='no'}

    \config{AUTOMX\_CALDAV\_URL}{AUTOMX\_CALDAV\_URL}{AUTOMXCALDAVURL}
        "Uber diesen Parameter legt man die URL des CalDAV-Servers fest.

        G"ultige Werte: Server URL

        Beispiel: \texttt{AUTOMX\_CALDAV\_URL='https://example.local.lan/'}

    \config{AUTOMX\_CARDDAV\_ENABLED}{AUTOMX\_CARDDAV\_ENABLED}{AUTOMXCARDDAVENABLED}
        "Uber diesen kann auf Wunsch die Unterst"utzung f"ur eine
        automatische CardDAV-Konfiguration aktiviert werden.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{AUTOMX\_CARDDAV\_ENABLED='no'}

    \config{AUTOMX\_CARDDAV\_URL}{AUTOMX\_CARDDAV\_URL}{AUTOMXCARDDAVURL}
        "Uber diesen Parameter legt man die URL des CardDAV-Servers fest.

        G"ultige Werte: Server URL

        Beispiel: \texttt{AUTOMX\_CARDDAV\_URL='https://example.local.lan/'}

    \config{AUTOMX\_LOG\_COUNT}{AUTOMX\_LOG\_COUNT}{AUTOMXLOGCOUNT}
        "Uber diesen Parameter wird eingestellt, wie viele Logdateien
        vorgehalten werden sollen. Wird dieser Wert "uberschritten, so
        wird die "alteste Logdatei gel"oscht.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{AUTOMX\_LOG\_COUNT='10'}

    \config{AUTOMX\_LOG\_INTERVAL}{AUTOMX\_LOG\_INTERVAL}{AUTOMXLOGINTERVAL}
        "Uber diesen Parameter wird eingestellt, in welchen Intervallen
        die Logdateien archiviert werden sollen. Zur Auswahl stehen die
        Schl"usselw"orter `daily' - t"aglich, `weekly' - w"ochentlich
        und `monthly - monatlich.

        G"ultige Werte: daily, weekly, monthly

        Standardeinstellung: \texttt{AUTOMX\_LOG\_INTERVAL='weekly'}
\end{description}


\section{Verschiedenes}

\begin{description}
    Um den automx-Webservice nutzen zu k"onnen, m"ussen sowohl virtuelle
    Webhosts, als auch zugeh"orige DNS-Eintr"age f"ur die eigene Domain
    gesetzt werden.

    \config{Die DNS-Konfiguration}{Die DNS-Konfiguration}{DieDNS-Konfiguration}
        Im eigene DNS-Server sind Eintr"age anzulegen "uber welche
        standardm"a"sig der Abruf der Konfiguration erfolgt. F"ur eine
        Domain `local.lan' w"urden die ben"otigten Eintr"age wie folgt
        lauten:

        \begin{verbatim}
autoconfig.local.lan     A       192.168.6.11
autodiscover.local.lan   CNAME   autoconfig.local.lan
dav.local.lan            CNAME   autoconfig.local.lan
        \end{verbatim}

        \hinweis{Der Eintrag 'dav.local.lan' kann entfallen, wenn keine
            automatische CalDAV-/CardDAV-Konfiguration erfolgen soll}

        Die folgenden DNS SRV-Eintr"age sollten eingerichtet werden,
        um Programmen eine automatische Konfiguration zu erleichtern.
        Die genau Funktionsweise wird in RFC 2782 und auch RFC 6186
        beschrieben.

        \begin{verbatim}
_autodiscover._tcp 86400 IN SRV 0 0 443 autodiscover.local.lan.

_submission._tcp   86400 IN SRV 0 1 587 mail.local.lan.
_imaps._tcp        86400 IN SRV 1 1 993 imap.local.lan.
_imap._tcp         86400 IN SRV 2 1 143 imap.local.lan.
_pop3s._tcp        86400 IN SRV 3 1 995 pop3.local.lan.
_pop3._tcp         86400 IN SRV 4 1 110 pop3.local.lan.

_caldavs._tcp      86400 IN SRV 0 1 443 dav.local.lan.
_caldav._tcp       86400 IN SRV 1 1  80 dav.local.lan.
_carddavs._tcp     86400 IN SRV 0 1 443 dav.local.lan.
_carddav._tcp      86400 IN SRV 1 1  80 dav.local.lan.
        \end{verbatim}

        \hinweis{Die Eintr"age '\_caldavs.\_tcp', '\_caldav.\_tcp',
            '\_carddavs.\_tcp' und '\_carddav.\_tcp' k"onnen entfallen,
            wenn keine automatische CalDAV-/CardDAV-Konfiguration
            erfolgen soll}

    \config{Die Zertifikate}{Die Zertifikate}{DieZertifikate}
        Da E-Mail-Programme auf die Webservices "ublicherweise mittels
        https zugreifen ist ein entsprechendes Serverzertifikat zu erzeugen,
        welches auf die zuvor genannten Domainnamen ausgestellt wurde.
        F"ur eine Domain `local.lan' m"usste das Zertifikat auf folgende
        Domains ausgestellt werden:

        \begin{verbatim}
autoconfig.local.lan
autodiscover.local.lan
dav.local.lan
        \end{verbatim}

        \hinweis{Im certs-Paket muss man dazu im Common name-Feld
            "DNS:autoconfig.local.lan,DNS:autodiscover.local.lan"
            eingeben.}

        \achtung{Bei Verwendung von selbst signierten Zertifikaten ist
            unbedingt sicher zu stellen, dass das eigene CA-Zertifikat
            in den Zertifikatsspeicher des E-Mail-Programms importiert
            wurde um eine fehlerfrei Pr"ufung des angebotenen Zertifikats
            zu erm"oglichen.}

    \config{Die Apache2-Konfiguration}{Die Apache2-Konfiguration}{DieApache2-Konfiguration}
        Um die korrekte Konfiguration der virtuellen Hosts sicher zu stellen,
        pr"uft man mittels eines Webbrowsers den https-Zugriff. Nur wenn
        keine Fehlermeldung angezeigt wird, sollte man davon ausgehen k"onnen,
        dass das korrekte Zertifikat verwendet wird.

        \achtung{Bei Verwendung von selbst signierten Zertifikaten ist
            unbedingt sicher zu stellen, dass das eigene CA-Zertifikat
            in den Zertifikatsspeicher des E-Mail-Programms importiert
            wurde um eine fehlerfrei Pr"ufung des angebotenen Zertifikats
            zu erm"oglichen.}

    \config{Der Test mittels eines Webbrowsers}{Der Test mittels eines Webbrowsers}{DerTestmittelseinesWebbrowsers}
        Um mittels eines Webbrowser die korrekte Programmfunktion zu
        testen, gibt man folgende URL, gefolgt von einer E-Mail-Adresse
        welche im lokalen mail-Paket eingerichtet wurde, ein:

        \url{https://autoconfig.cwlocal.lan/mail/config-v1.1.xml?emailaddress=john.doe@local.lan}
\end{description}
