%
% Achtung: Dateien muessen mit latin1-Encoding gespeichert werden!
% Attention: Files must be saved using latin1 encoding!
%

\chapter{Das CardDAV2FB-Paket}

    Dieses Paket erlaubt es Adressb"ucher eines CardDAV-Servers, z.B.
    von ownCloud\texttrademark \ in eine AVM FRITZ!Box\texttrademark\ zu
    "ubertragen.


\section{Die Einleitung}

    In diesem Paket wurden verschiedenste PHP-Komponenten zusammengestellt,
    die zusammen ein komplettes Paket ergeben.


\section{Die Funktionen}

    Das CardDAV2FB-Paket besteht aus folgenden Komponenten:

    \begin{itemize}
         \item{CardDAV2FB} Das Hauptskript f"ur den Datentransfer
            von einem CardDAV-Server zur FRITZ!Box\texttrademark.\\
            Lizenz: Public Domain, some parts under GNU AGPL
            (GNU Affero General Public License) or MIT
            (Massachusetts Institute of Technolog) license.\\
            (\url{https://github.com/andig/carddav2fb})
    \end{itemize}


\section{Die Lizenzen}

    Die verwendeten Dateien unterliegen den im Absatz 'Die Funktionen'
    genannten Lizenzen.


\section{Die Voraussetzungen}

    Dieses Paket ben"otigt ein installiertes php5\_ccpp-Paket um
    funktionieren zu k"onnen.


\section{Die Installation}

    Das CardDAV2FB-Paket wird "uber das Setup-Men"u installiert. Wird
    eine "altere Paketversion vorgefunden, so wird diese deinstalliert
    bevor die neuen Programmdateien installiert werden. Nach dem
    Installieren der Programmdateien wird direkt der Konfigurations-Editor
    gestartet um die Konfiguration anzupassen. Nach Beendigung dieses
    Schrittes werden die Konfigurationsdateien generiert und alle
    ben"otigten Programme gestartet.


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

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

    \begin{itemize}
        \item CardDAV2FB administration
        \begin{itemize}
            \item View documentation: Anzeigen der Dokumentation
            \item Edit configuration: Bearbeiten der Konfiguration
            \item Advanced configuration file handling: Konfigurationen
                verwalten
            \item Force manual FRITZ!Box\texttrademark\ update: Manuelle
                Aktualisierung ansto"sen
            \item View log file: Logdatei der letzten Aktualisierung ansehen
            \item Exit: Untermen"u verlassen
        \end{itemize}
    \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 in der Datei \texttt{/etc/config.d/carddav2fb}.


\section{Die Parameter}

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

    \config{START\_CARDDAV2FB}{START\_CARDDAV2FB}{STARTCARDDAV2FB}
        F"ur die Aktivierung des CardDAV2FB-Programms muss dieser Parameter
        lediglich auf den Wert `yes' gestellt werden. Die Einstellung `no'
        deaktiviert das CardDAV2FB-Programm.

        G"ultige Werte: yes, no

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

    \config{CARDDAV2FB\_FB\_HOST}{CARDDAV2FB\_FB\_HOST}{CARDDAV2FBFBHOST}
        "Uber diesen Parameter wird der DNS-Name der
        FRITZ!Box\texttrademark\ oder deren IP-Adresse festgelegt,
        welcher f"ur den Zugriff verwendet werden soll.

        G"ultige Werte: Domainname oder IP-Adresse

        Standardeinstellung: \texttt{CARDDAV2FB\_FB\_HOST='fritz.box'}

%%  JED - show this description only in the help file
 %  \config{CARDDAV2FB\_FB\_USER}{CARDDAV2FB\_FB\_USER}{CARDDAV2FBFBUSER}
 %      "Uber diese Parameter werden der f"ur den Zugriff auf die
 %      FRITZ!Box\texttrademark\ ben"otigte Login und das zugeh"orige
 %      Kennwort angegeben.\\\\
 %      \achtung{Unbedingt Klein- / Gro"sschreibung beachten!}
 %
 %      G"ultige Werte: Username bzw. Kennwort
 %
 %      Beispiel:
 %
 %      \texttt{CARDDAV2FB\_FB\_USER='frank'\\
 %              CARDDAV2FB\_FB\_PASS='geheim'}

    \index{CARDDAV2FB\_FB\_USER}
    \config{CARDDAV2FB\_FB\_USER / CARDDAV2FB\_FB\_PASS}{CARDDAV2FB\_FB\_PASS}{CARDDAV2FBFBPASS}
        "Uber diese Parameter werden der f"ur den Zugriff auf die
        FRITZ!Box\texttrademark\ ben"otigte Login und das zugeh"orige
        Kennwort angegeben.\\\\
        \achtung{Unbedingt Klein- / Gro"sschreibung beachten!}

        G"ultige Werte: Username bzw. Kennwort

        Beispiel:

        \texttt{CARDDAV2FB\_FB\_USER='frank'\\
                CARDDAV2FB\_FB\_PASS='geheim'}

    \config{CARDDAV2FB\_FB\_PBOOK\_NBR}{CARDDAV2FB\_FB\_PBOOK\_NBR}{CARDDAV2FBFBPBOOKNBR}
        "Uber diesen Parameter wird die Indexnummer des
        FRITZ!Box\texttrademark- Adressbuchs angegeben, in welches die
        aus dem CardDAV-Adressbuch "ubernommenen Adressen geschrieben
        werden sollen. Die Z"ahlung beginnt "ublicherweise bei `0' f"ur
        das standardm"a"sig genutzte `Telefonbuch'. Falls ein weiteres
        Adressbuch in der FRITZ!Box\texttrademark\ angelegt wurde, muss
        in diesem Fall die Indexnummer `1' angegeben werden.\\\\
        \achtung{Bevor auf ein neues Adressbuch zugegriffen werden kann
            muss dieses "uber das FRITZ!Box\texttrademark-Men"u angelegt
            werden.}

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{CARDDAV2FB\_FB\_PBOOK\_NBR='0'}

    \config{CARDDAV2FB\_FB\_PBOOK\_NAME}{CARDDAV2FB\_FB\_PBOOK\_NAME}{CARDDAV2FBFBPBOOKNAME}
        "Uber diesen Parameter wird der Name des
        FRITZ!Box\texttrademark-Adressbuchs angegeben, in welches die
        aus dem CardDAV-Adressbuch "ubernommenen Adressen geschrieben
        werden sollen.\\\\
        \achtung{Bevor auf ein neues Adressbuch zugegriffen werden kann
            muss dieses "uber das FRITZ!Box\texttrademark-Men"u angelegt
            werden.}

        G"ultige Werte: Adressbuchname

        Standardeinstellung: \texttt{CARDDAV2FB\_FB\_PBOOK\_NAME='Telefonbuch'}

    \config{CARDDAV2FB\_FB\_PBOOK\_GROUPS (Optionaler Parameter)}{CARDDAV2FB\_FB\_PBOOK\_GROUPS}{CARDDAV2FBFBPBOOKGROUPS}
        "Uber diesen Parameter k"onnen auf Wunsch individuelle
        Adressbuchgruppen angegeben werden, um die Menge der Daten die
        in die FRITZ!Box\texttrademark\ importiert werden sollen, zu
        beschr"anken. Die einzelnen Eintr"age sind jeweils durch einen
        Doppelpunkt voneinander zu trennen.

        G"ultige Werte: Vorhandene Adressbuchgruppen

        Beispiel: \texttt{CARDDAV2FB\_FB\_PBOOK\_GROUPS='Familie:Freunde:Gesch"aftlich'}

    \config{CARDDAV2FB\_FB\_PBOOK\_VIPGROUP (Optionaler Parameter)}{CARDDAV2FB\_FB\_PBOOK\_VIPGROUP}{CARDDAV2FBFBPBOOKVIPGROUP}
        "Uber diesen Parameter kann der Name der VIP-Gruppe (Very
        Important People) festgelegt werden.

        G"ultige Werte: Gruppenname

        Standardeinstellung: \texttt{CARDDAV2FB\_FB\_PBOOK\_VIPGROUP='VIP'}

    \config{CARDDAV2FB\_FB\_STORAGE\_NAME (Optionaler Parameter)}{CARDDAV2FB\_FB\_STORAGE\_NAME}{CARDDAV2FBFBSTORAGENAME}
        "Uber diesen Parameter kann der Name des Dateisystems angegeben
        werden auf welchem die Bilddateien der Adressbucheintr"age
        auf der FRITZ!Box\texttrademark\ abgelegt werden sollen.
        Standardm"a"sig wird der interne Speicher verwendet, soll
        jedoch beispielsweise ein USB-Stick genutzt werden, so muss
        der Name eventuell `Generic-FlashDisk-01' lauten.

        G"ultige Werte: Dateisystemname

        Standardeinstellung: \texttt{CARDDAV2FB\_FB\_STORAGE\_NAME=$''$}

    \config{CARDDAV2FB\_FB\_CHECK\_CERT (Optionaler Parameter)}{CARDDAV2FB\_FB\_CHECK\_CERT}{CARDDAV2FBFBCHECKCERT}
        "Uber diesen Parameter kann die Pr"ufung des TLS-Zertifikates
        der FRITZ!Box\texttrademark\ deaktiviert werden. Dies kann
        eventuell erforderlich werden, wenn ein selbst signiertes
        Zertifikat zur Absicherung der Verbindung genutzt wird.

        G"ultige Werte: yes, no
 
        Standardeinstellung: \texttt{CARDDAV2FB\_FB\_CHECK\_CERT='yes'}

    \config{CARDDAV2FB\_SOURCE\_PBOOK\_N}{CARDDAV2FB\_SOURCE\_PBOOK\_N}{CARDDAV2FBSOURCEPBOOKN}
        "Uber diesen Parameter wird die Anzahl der in das
        FRITZ!Box\texttrademark-Adressbuch zu importierenden CardDAV-
        Adressb"ucher angegeben, welche "uber die folgenden Parameter
        definiert werden.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{CARDDAV2FB\_SOURCE\_PBOOK\_N='1'}

    \config{CARDDAV2FB\_SOURCE\_PBOOK\_x\_ACTIVE}{CARDDAV2FB\_SOURCE\_PBOOK\_x\_ACTIVE}{CARDDAV2FBSOURCEPBOOKxACTIVE}
        Wird dieser Parameter auf den Wert `yes' gesetzt, so wird der
        zugeh"orige Datensatz aktiviert, `no' deaktiviert ihn.

        G"ultige Werte: yes oder no

        Beispiel: \texttt{CARDDAV2FB\_SOURCE\_PBOOK\_1\_ACTIVE='no'}

    \config{CARDDAV2FB\_SOURCE\_PBOOK\_x\_COMMENT}{CARDDAV2FB\_SOURCE\_PBOOK\_x\_COMMENT}{CARDDAV2FBSOURCEPBOOKxCOMMENT}
        "Uber diesen Parameter kann ein Kommentar eingegeben werden,
        welcher einzig der Beschreibung dieses Datensatzes dient.

        G"ultige Werte: beliebiger Text

        Beispiel: \texttt{CARDDAV2FB\_SOURCE\_PBOOK\_1\_COMMENT='Adressbuch von Frank'}

    \config{CARDDAV2FB\_SOURCE\_PBOOK\_x\_URL}{CARDDAV2FB\_SOURCE\_PBOOK\_x\_URL}{CARDDAV2FBSOURCEPBOOKxURL}
        "Uber diesen Parameter wird die URL f"ur den Zugriff auf das
        gew"unschte CardDAV-Adressbuch angegeben.

        G"ultige Werte: URL

        Standardeinstellung: \texttt{CARDDAV2FB\_SOURCE\_PBOOK\_x\_URL=}\\
            \texttt{'https://server.local.lan/owncloud/remote.php/carddav/addressbooks}\\
            \texttt{/user/kontakte'}

%%  JED - show this description only in the help file
 %  \config{CARDDAV2FB\_SOURCE\_PBOOK\_x\_USER}{CARDDAV2FB\_SOURCE\_PBOOK\_x\_USER}{CARDDAV2FBSOURCEPBOOKxUSER}
 %      "Uber diese Parameter werden der f"ur den Zugriff auf das
 %      CardDAV-Adressbuch ben"otigte Login und das zugeh"orige Kennwort
 %      angegeben.\\\\
 %      \achtung{Unbedingt Klein- / Gro"sschreibung beachten!}
 %
 %      G"ultige Werte: Username bzw. Kennwort
 %
 %      Beispiel:
 %
 %      \texttt{CARDDAV2FB\_SOURCE\_PBOOK\_1\_USER='frank'\\
 %              CARDDAV2FB\_SOURCE\_PBOOK\_1\_PASS='geheim'}

    \index{CARDDAV2FB\_SOURCE\_PBOOK\_x\_USER}
    \config{CARDDAV2FB\_SOURCE\_PBOOK\_x\_USER / CARDDAV2FB\_SOURCE\_PBOOK\_x\_PASS}{CARDDAV2FB\_SOURCE\_PBOOK\_x\_PASS}{CARDDAV2FBSOURCEPBOOKxPASS}
        "Uber diese Parameter werden der f"ur den Zugriff auf das
        CardDAV-Adressbuch ben"otigte Login und das zugeh"orige Kennwort
        angegeben.\\\\
        \achtung{Unbedingt Klein- / Gro"sschreibung beachten!}

        G"ultige Werte: Username bzw. Kennwort

        Beispiel:

        \texttt{CARDDAV2FB\_SOURCE\_PBOOK\_1\_USER='frank'\\
                CARDDAV2FB\_SOURCE\_PBOOK\_1\_PASS='geheim'}

    \config{CARDDAV2FB\_CRON\_SCHEDULE}{CARDDAV2FB\_CRON\_SCHEDULE}{CARDDAV2FBCRONSCHEDULE}
        "Uber diesen Parameter wird festgelegt zu welchem Zeitpunkt
        bzw.  in welchem Intervall automatisch ein Adressbuchabgleich
        durchgef"uhrt werden sollen. Die f"unf Teilparameter haben dabei
        folgende Bedeutung:\\
        1 - Minuten, 2 - Stunden, 3 - Tag des Monats, 4 - Monat, 5 - Wochentag.

        D.h. bei Verwendung der Standardeinstellung wird jeden Sonntag
        um 00:15h das FRITZ!Box\texttrademark-Adressbuch durch den
        Inhalt des CardDAV- Adressbuchs "uberschrieben. Wer N"aheres
        "uber die verwendete Befehlssyntax erfahren m"ochte, sollte
        "uber eine Internet-Suchmaschine nach `man' und `crontab'
        suchen.

        G"ultige Werte: Crontab-spezifischer Parametereintrag

        Standardeinstellung: \texttt{CARDDAV2FB\_CRON\_SCHEDULE='15 0 * * 0'}
\end{description}
