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

\chapter{Das coturn-Paket}

\section{Die Einleitung}

    Bei coTURN handelt es sich um eine freie Open Source Implementierung
    eines TURN- und STUN-Servers.

    Ein TURN-Server (Traversal Using Relays around NAT) im Internet,
    erm"oglicht es zwei Klienten, Daten ohne eine direkte Verbindung
    auszutauschen. Dies wird notwendig, wenn es keine M"oglichkeit gibt
    eine direkte Klient-zu-Klient-Verbindung aufzubauen, weil sich z.B.
    einer der Klienten hinter einer Firewall befindet.

    Ein STUN-Server (Session Traversal Utilities for NAT) erlaubt es einem
    rufenden Klienten im LAN dem angerufenen Klienten au"serhalb des LAN
    mitteilen, welche IPv4-Adresse (und Portnummer) verwendet werden kann
    um eine direkte Kommunikation mit ihm zu erm"oglichen (`Peer-to-Peer'
    Verbindung).

\section{Die Funktionen}

    Das coturn-Paket besteht aus folgender Komponente:

    \begin{itemize}
        \item coTURN - Die coTURN-Programmdateien.\\
              (\url{https://github.com/coturn/coturn/})
    \end{itemize}


\section{Die Voraussetzungen}

    Zur Nutzung des Programms werden keine weiteren Programmpakete
    ben"otigt.


\section{Die Installation}

    Das coturn-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 Advanced configuration file handling: Konfigurationen verwalten
        \item Show status: Status der coTRUN-Dienstes anzeigen
        \item Start service: Starten des coTRUN-Dienstes
        \item Stop service: Stoppen des coTRUN-Dienstes
        \item Restart service: Neustarten des coTRUN-Dienstes
        \item View log files: 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/coturn.


\section{Die Parameter}

\begin{description}
%% JED - show this description only in the help file
 %  \config{COTURN\_DO\_DEBUG (Optionaler Parameter)}{COTURN\_DO\_DEBUG}{COTURNDODEBUG}
 %      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{COTURN\_DO\_DEBUG='no'}

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

        G"ultige Werte: yes, no

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

    \config{COTURN\_SERVER\_NAME}{COTURN\_SERVER\_NAME}{COTURNSERVERNAME}
        "Uber diesen Parameter wird der vollst"andige Domainname des
        Servers (FQDN) festgelegt, unter welchem dieser zuk"unftig "uber
        das Internet erreicht werden kann. Dieser Name wird u.a. auch
        zum Setzen des Realm verwendet. Wird dieser Parameter nicht
        gesetzt, so wird automatisch der aktuelle Hostname des Servers
        verwendet.

        G"ultige Werte: vollst"andige Domainname des Servers (FQDN)

        Beispiel: \texttt{COTURN\_SERVER\_NAME='mein-coturn.server.de'}

    \config{COTURN\_SERVER\_CERT\_NAME (optionaler Parameter)}{COTURN\_SERVER\_CERT\_NAME}{COTURNSERVERCERTNAME}
        "Uber diesen Parameter kann ein individuelles Serverzertifikat
        f"ur den coTURN-Dienst festgelegt werden. Wird dieser Parameter
        nicht gesetzt, so wird standardm"a"sig nach einem Zertifikat
        gesucht welches dem Servernamen (COTURN\_SERVER\_NAME) entspricht.

        G"ultige Werte: Serverzertifikat

        Beispiel: \texttt{COTURN\_SERVER\_CERT\_NAME='coturn.local.lan'}

    \config{COTURN\_STATIC\_AUTH\_SECRET}{COTURN\_STATIC\_AUTH\_SECRET}{COTURNSTATICAUTHSECRET}
        "Uber diesen Parameter wird ein statisches Authentifizierungsgeheimnis
        festgelegt, welches von der TURN REST API verwendet wird. Wird
        dieser Parameter nicht gesetzt, so wird automatisch `dynamic'
        angenommen, sodass ein in der Benutzerdatenbank gespeicherter
        Wert zur Anwendung kommt. Dieser kann dann mittels eines
        separaten Programms `on-the-fly' gesetzt werden.

        G"ultige Werte: Authentifizierungsgeheimnis

        Beispiel: \texttt{COTURN\_STATIC\_AUTH\_SECRET='geheim'}

    \config{COTURN\_TELNET\_CLI\_ENABLED}{COTURN\_TELNET\_CLI\_ENABLED}{COTURNTELNETCLIENABLED}
        Um den coTURN-Dienst "uber die Telnet-Schnittstelle steuern zu
        k"onnen, muss der Wert dieses Parameters auf `yes' gesetzt werden,
        'no' deaktiviert die Schnittstelle.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{COTURN\_TELNET\_CLI\_ENABLED='no'}

    \config{COTURN\_TELNET\_CLI\_PASS}{COTURN\_TELNET\_CLI\_PASS}{COTURNTELNETCLIPASS}
        "Uber diesen Parameter wird das Kennwort festgelegt, welches zur
        Anmeldung an der Telnet-Schnittstelle des coTURN-Dienstes verwendet
        werden soll.

        G"ultige Werte: Kennwort

        Standardeinstellung: \texttt{COTURN\_TELNET\_CLI\_PASS=''}

    \config{COTURN\_LOG\_COUNT}{COTURN\_LOG\_COUNT}{COTURNLOGCOUNT}
        "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{COTURN\_LOG\_COUNT='10'}

    \config{COTURN\_LOG\_INTERVAL}{COTURN\_LOG\_INTERVAL}{COTURNLOGINTERVAL}
        "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{COTURN\_LOG\_INTERVAL='weekly'}
\end{description}

\section{Verschiedenes}

    \subsection{Port-Weiterleitungen im Internet-Router einrichten}

        Um aus dem Internet auf den TURN- und STUN-Dienst zugreifen zu
        k"onnen, ist es erforderlich Port-Weiterleitungen f"ur TCP und
        UDP einzurichten. Folgende eingehende Verbindungen aus dem
        Internet sind zuzulassen:

        \begin{verbatim}
3478/tcp    # coTRUN (stun-turn)
3478/udp    # coTRUN (stun-turn)
5349/tcp    # coTRUN (stun-turn-tls)
5349/udp    # coTRUN (stun-turn-tls)
        \end{verbatim}

    \subsection{Nextcloud-Talk-App konfigurieren}

        Damit die Talk-App den TURN- und STUN-Dienst verwenden kann,
        muss man diese der Software bekannt machen. Hierzu "offnet man
        die Konfiguration der App (Einstellungen->Verwaltung->Talk)
        und nimmt folgende Einstellungen vor:

        \achtung{Der vollst"andige Servername (FQDN) sollte dem Namen
            entsprechen, der "uber den Parameter
            \jump{COTURNSERVERNAME}{COTURN\_SERVER\_NAME} gesetzt wurde.}

        \achtung{Das TURN-Geheimnis sollte dem Kennwort entsprechen,
            welches "uber den Parameter
            \jump{COTURNSTATICAUTHSECRET}{COTURN\_STATIC\_AUTH\_SECRET}
            gesetzt wurde.}

        \begin{verbatim}
STUN-Server    : mein-coturn.server.de:5349

TURN-Server    : mein-coturn.server.de:3478
TURN-Geheimnis : statisches Authentifizierungsgeheimnis
TURN-Protokolle: UDP und TCP
        \end{verbatim}

\section{Das Glossar}

    \begin{itemize}
        \item FQDN - Fully Qualified Domain Name
        \item STUN - Session Traversal Utilities for NAT
        \item TURN - Traversal Using Relays around NAT
    \end{itemize}

