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

\chapter{Das Telegram-Paket}

\section{Die Einleitung}

    Telegram (\url{https://telegram.org/}) erlaubt das Versenden und
    Empfangen von Kurznachrichten "uber den kostenfreien Telegram-Instant
    Messaging Service. Der Fokus liegt dabei auf den Themen Sicherheit
    und Geschwindigkeit. Dar"uber hinaus erlaubt Telegram den Abgleich
    von Chat-Dateien "uber verschiedenste Klienten hinweg.

    \achtung{Um das Paket verwenden zu k"onnen ist eine einmalige Registrierung
        erforderlich, welche im Absatz \jump{DerRegistierungsprozess}
        {Der Registierungsprozess} erkl"art wird.}

\section{Die Funktionen}

    Das Telegram-Paket besteht aus folgender Komponente:

    \begin{itemize}
        \item telegram-cli - Das Telegram CLI-Programmpaket.\\
              (\url{https://github.com/vysheng/tg})
    \end{itemize}


\section{Die Voraussetzungen}

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


\section{Die Installation}

    Das Telegram-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 Telegram-CLI Dienstes anzeigen
        \item Start service: Starten des Telegram-CLI Dienstes
        \item Stop service: Stoppen des Telegram-CLI Dienstes
        \item Restart service: Neustarten des Telegram-CLI Dienstes
        \item Send test message: Eine Testnachricht versenden
        \item Start Telegram Client: Das Telegram Klientenprogramm starten
        \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/telegram.


\section{Die Parameter}

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

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

        G"ultige Werte: yes, no

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

    \config{TELEGRAM\_LISTEN\_PORT (Optionaler Parameter)}{TELEGRAM\_LISTEN\_PORT}{TELEGRAMLISTENPORT}
        "Uber diesen Parameter wird der TCP-Port festgelegt, auf dem der
        Telegram-Dienst Verbindungen entgegennehmen soll.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{TELEGRAM\_LISTEN\_PORT='2391'}

    \config{TELEGRAM\_BOT\_ENABLED}{TELEGRAM\_BOT\_ENABLED}{TELEGRAMBOTENABLED}
        "Uber diesen Parameter wird festgelegt, ob der Telegram-Dienst
        den BOT-Modus aktivieren, d.h. auf eingehende Befehle reagieren
        soll. Die Einstellung 'no' deaktiviert den BOT-Modus.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{TELEGRAM\_BOT\_ENABLED='no'}

    \config{TELEGRAM\_BOT\_USER\_N}{TELEGRAM\_BOT\_USER\_N}{TELEGRAMBOTUSERN}
        "Uber diesen Parameter wird die Anzahl der authorisierten
        Anwender festgelegt, auf deren Befehle der BOT reagieren
        soll.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{TELEGRAM\_BOT\_USER\_N='1'}

    \config{TELEGRAM\_BOT\_USER\_x\_ACTIVE}{TELEGRAM\_BOT\_USER\_x\_ACTIVE}{TELEGRAMBOTUSERxACTIVE}
        Wird dieser Parameter auf den Wert `yes' gesetzt, so wird
        der zugeh"orige Datensatz aktiviert, `no' deaktiviert ihn.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{TELEGRAM\_BOT\_USER\_1\_ACTIVE='no'}

    \config{TELEGRAM\_BOT\_USER\_x\_COMMENT}{TELEGRAM\_BOT\_USER\_x\_COMMENT}{TELEGRAMBOTUSERxCOMMENT}
        "Uber diesen Parameter kann auf Wunsch ein Kommentar
        angegeben werden, da die Zuordnung des Datensatzes
        erleichtert.

        G"ultige Werte: beliebiger Text

        Beispiel: \texttt{TELEGRAM\_BOT\_USER\_1\_COMMENT='Id of Theo Test'}

    \config{TELEGRAM\_BOT\_USER\_x\_ID}{TELEGRAM\_BOT\_USER\_x\_ID}{TELEGRAMBOTUSERxID}
        "Uber diesen Parameter wird die Telegram-ID des authorisierten
        Anwenders festgelegt, auf deren Befehle der BOT reagieren soll.
        Um die Telegram-ID seines Accounts heraus zu bekommen, reicht
        es den Text `show-my-sender-details' an den BOT zu senden.

        G"ultige Werte: g"ultige Telegram-ID

        Beispiel: \texttt{TELEGRAM\_BOT\_USER\_x\_ID='\$010000000abcdef01234567890abcdef'}

    \config{TELEGRAM\_BOT\_CMD\_N}{TELEGRAM\_BOT\_CMD\_N}{TELEGRAMBOTCMDN}
        "Uber diesen Parameter wird die Anzahl der zu akzeptierenden
        Telegram-Befehle festgelegt.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{TELEGRAM\_BOT\_CMD\_N='6'}

    \config{TELEGRAM\_BOT\_CMD\_x\_ACTIVE}{TELEGRAM\_BOT\_CMD\_x\_ACTIVE}{TELEGRAMBOTCMDxACTIVE}
        Wird dieser Parameter auf den Wert `yes' gesetzt, so wird
        der zugeh"orige Datensatz aktiviert, `no' deaktiviert ihn.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{TELEGRAM\_BOT\_CMD\_1\_ACTIVE='no'}

    \config{TELEGRAM\_BOT\_CMD\_x\_COMMENT}{TELEGRAM\_BOT\_CMD\_x\_COMMENT}{TELEGRAMBOTCMDxCOMMENT}
        "Uber diesen Parameter kann auf Wunsch ein Kommentar angegeben
        werden, da die Zuordnung des Datensatzes erleichtert.

        G"ultige Werte: beliebiger Text

        Beispiel: \texttt{TELEGRAM\_BOT\_CMD\_1\_COMMENT='Show current date/time.'}

    \config{TELEGRAM\_BOT\_CMD\_x\_COMMAND}{TELEGRAM\_BOT\_CMD\_x\_COMMAND}{TELEGRAMBOTCMDxCOMMAND}
        "Uber diesen Parameter wird das Befehlsschl"usselwort festgelegt,
        auf welches der BOT reagieren soll.

        G"ultige Werte: beliebiger Text (max. 10 Zeichen)

        Beispiel: \texttt{TELEGRAM\_BOT\_CMD\_1\_COMMAND='datetime'}

    \config{TELEGRAM\_BOT\_CMD\_x\_ACTION}
        "Uber diesen Parameter wird festgelegt, welcher Befehl
        beim Empfang des zuvor definierten Befehlsschl"usselwortes
        ausgef"uhrt werden soll.

        G"ultige Werte: absoluter Befehlspfad, gefolgt von optionalen Parametern

        Beispiel:
        \begin{verbatim}
TELEGRAM_BOT_CMD_1_ACTION='/bin/date +"%d.%m.%Y %H:%M:%Sh"'
        \end{verbatim}

    \config{TELEGRAM\_KEEP\_ALIVE}{TELEGRAM\_KEEP\_ALIVE}{TELEGRAMKEEPALIVE}
        "Uber diesen Parameter wird festgelegt, ob zyklisch eine
        Telegram-Nachricht versandt werden soll um so zu best"atigen,
        dass der Dienst noch fehlerfrei funktioniert.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{TELEGRAM\_KEEP\_ALIVE='no'}

    \config{TELEGRAM\_KEEP\_ALIVE\_ADDR}{TELEGRAM\_KEEP\_ALIVE\_ADDR}{TELEGRAMKEEPALIVEADDR}
        "Uber diesen Parameter wird der Empf"anger oder die Gruppe
        festgelegt an welche zyklisch eine Telegram-Nachricht gesandt
        werden soll.

        G"ultige Werte: existierender Telegram-Anwender oder Gruppe

        Standardeinstellung: \texttt{TELEGRAM\_KEEP\_ALIVE\_ADDR=$''$}

    \config{TELEGRAM\_KEEP\_ALIVE\_TEXT}{TELEGRAM\_KEEP\_ALIVE\_TEXT}{TELEGRAMKEEPALIVETEXT}
        "Uber diesen Parameter wird der Text der Telegram-Nachricht
        festgelegt, welche zyklisch an den zuvor festgelegten Empf"anger
        bzw. Gruppe versandt werden soll.

        G"ultige Werte: Text

        Standardeinstellung: \texttt{TELEGRAM\_KEEP\_ALIVE\_TEXT='Hello world!'}

   \config{TELEGRAM\_KEEP\_ALIVE\_CRON\_SCHEDULE}{TELEGRAM\_KEEP\_ALIVE\_CRON\_SCHEDULE}{TELEGRAMKEEPALIVECRONSCHEDULE}
        "Uber diesen Parameter wird festgelegt zu welchem Zeitpunkt bzw.
        in welchem Intervall eine Telegram-Nachricht versandt werden soll.
        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 an jedem Tag um
        00:00h eine Nachricht versandt. 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{TELEGRAM\_KEEP\_ALIVE\_CRON\_SCHEDULE='0 0 * * *'}

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

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


\section{Verschiedenes}

\begin{description}
    \config{Der Registierungsprozess}{Der Registierungsprozess}{DerRegistierungsprozess}
        Um das Programm verwenden zu k"onnen, ist eine einmalige Registrierung
        am Service notwendig. Hierzu kann jede Telefonnummer verwendet werden,
        "uber welche man SMS- oder Sprachnachrichten empfangen kann.

        Hinweis: Bei der Erstellung der folgenden Beschreibung wurde
        auf Informationen von folgender Webseite zur"uck gegriffen:\\
        http://www.home-automation-community.com/telegram-messenger-on-
               the-raspberry-pi/

        \begin{itemize}
            \item[1.] Zur Registrierung der Telefonnummer startet man das
                      telegram-cli-Programm "uber den Men"upunkt `Start
                      Telegram Client' und gibt bei der Frage nach der
                      Telefonnummer eine Rufnummer in internationaler
                      Schreibweise an, d.h. im Format L"anderkode inkl.
                      vorangestelltem `+'-Zeichen, Ortsvorwahl ohne f"uhrende
                      Null und die Rufnummer.

            \item[2.] Nach kurzer Zeit sollte eine SMS mit dem ben"otigten
                      Freischaltungskode auf dem Telefon eingegangen sein.
                      Direkt nach der Eingabe des Freischaltungskodes kann
                      man den Service verwenden.\\

            \item[3.] Abschlie"send muss nun noch einmal der Telegram-Dienst
                      "uber den Men"upunkt `Restart service' neu gestartet
                      werden um die Einstellungen dauerhaft zu aktivieren.
        \end{itemize}

        Dies sind die Bildschirmausgaben w"ahrend der Registrierung:

                      \begin{verbatim}
Telegram-cli version 1.3.3, Copyright (C) 2013-2015 Vitaly Valtman
Telegram-cli comes with ABSOLUTELY NO WARRANTY; for details type
`show_license'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show_license' for details.
Telegram-cli uses libtgl version 2.0.3
Telegram-cli includes software developed by the OpenSSL Project
for use in the OpenSSL Toolkit. (http://www.openssl.org/)
Telegram-cli uses libpython version 2.7.10
I: config dir=[/home/telegramd/.telegram-cli]
[/home/telegramd/.telegram-cli] created
[/home/telegramd/.telegram-cli/downloads] created
phone number: +49222445566                          # <<< Telefonnummer
code ('CALL' for phone code): 1234                  # <<< PIN-Code
User Eisfair-Statusmeldungen online (was online [2016/01/06 11:21:15])
> safe_quit                                         # <<< safe_quit-Befehl
halt
                      \end{verbatim}

    \config{Das Telegram-Klientenprogramm}{Das Telegram-Klientenprogramm}{DasTelegramKlientenprogramm}
        "Uber das Men"u bzw. die Kommandozeile kann das
        Telegram-Klientenprogramm (telegram-cli) gestartet werden.
        Man verl"asst das Programm durch Eingabe von `safe\_quit'.

        Der Kommandozeilenbefehl lautet hierbei:
        \begin{verbatim}
# telegram-cli -W
        \end{verbatim}

        Sobald der Client gestartet wurde, kann man diesen mit bestimmten
        Kommandos bedienen. "Uber das Kommando `help' erh"alt man z.B.
        folgende Ausgabe:

        \begin{verbatim}
> help
accept_secret_chat <secret chat>
                                Accepts secret chat. Only useful
                                with -E option
add_contact <phone> <first name> <last name>
                                Tries to add user to contact list
block_user <user>               Blocks user
broadcast <user>+ <text>        Sends text to several users at
                                once
chat_add_user <chat> <user> [msgs-to-forward]
                                Adds user to chat. Sends him last
                                msgs-to-forward message from this
                                chat. Default 100
chat_del_user <chat> <user>     Deletes user from chat
chat_info <chat>                Prints info about chat (id,
                                members, admin, etc.)
chat_set_photo <chat> <filename>
                                Sets chat photo. Photo will be
                                cropped to square
chat_with_peer <peer>           Interface option. All input will
                                be treated as messages to this
                                peer. Type /quit to end this mode
clear                           Clears all data and exits. For
                                debug.
contact_list                    Prints contact list
contact_search username         Searches user by username
create_group_chat <name> <user>+
                                Creates group chat with users
create_secret_chat <user>       Starts creation of secret chat
del_contact <user>              Deletes contact from contact list
delete_msg <msg-id>             Deletes message
dialog_list [limit=100] [offset=0]
                                List of last conversations
export_card                     Prints card that can be imported
                                by another user with import_card
                                method
export_chat_link                Prints chat link that can be used
                                to join to chat
fwd <peer> <msg-id>+            Forwards message to peer. Forward
                                to secret chats is forbidden
fwd_media <peer> <msg-id>       Forwards message media to peer.
                                Forward to secret chats is
                                forbidden. Result slightly
                                differs from fwd
get_message <msg-id>            Get message by id
get_self                        Get our user info
help                            Prints this help
history <peer> [limit] [offset] Prints messages with this peer
                                (most recent message lower). Also
                                marks messages as read
import_card <card>              Gets user by card and prints it
                                name. You can then send messages
                                to him as usual
import_chat_link <hash>         Joins to chat by link
load_audio <msg-id>             +
load_chat_photo <chat>          |
load_document <msg-id>          |
load_document <msg-id>          |
load_document_thumb <msg-id>    |
load_file <msg-id>              |- Downloads file to downloads
load_file_thumb <msg-id>        |  dirs. Prints file name after
load_photo <msg-id>             |  download end
load_user_photo <user>          |
load_video <msg-id>             |
load_video_thumb <msg-id>       +
main_session                    Sends updates to this connection
                                (or terminal). Useful only with
                                listening socket
mark_read <peer>                Marks messages with peer as read
msg <peer> <text>               Sends text message to peer
msg <peer> <kbd> <text>         Sends text message to peer with
                                custom kbd
quit                            Quits immediately
rename_chat <chat> <new name>   Renames chat
rename_contact <user> <first name> <last name>
                                Renames contact
reply <msg-id> <text>           Sends text reply to message
reply_audio <msg-id> <file>     Sends audio to peer
reply_contact <msg-id> <phone> <first-name> <last-name>
                                Sends contact (not necessary
                                telegram user)
reply_document <msg-id> <file>  Sends document to peer
reply_file <msg-id> <file>      Sends document to peer
reply_location <msg-id> <latitude> <longitude>
                                Sends geo location
reply_photo <msg-id> <file> [caption]
                                Sends photo to peer
reply_video <msg-id> <file>     Sends video to peer
resolve_username username       Searches user by username
safe_quit                       Waits for all queries to end,
                                then quits
search [peer] [limit] [from] [to] [offset] pattern
                                Search for pattern in messages
                                from date from to date to
                                (unixtime) in messages with peer
                                (if peer not present, in all
                                messages)
send_audio <peer> <file>        Sends audio to peer
send_contact <peer> <phone> <first-name> <last-name>
                                Sends contact (not necessary
                                telegram user)
send_document <peer> <file>     Sends document to peer
send_file <peer> <file>         Sends document to peer
send_location <peer> <latitude> <longitude>
                                Sends geo location
send_photo <peer> <file> [caption]
                                Sends photo to peer
send_text <peer> <file>         Sends contents of text file as
                                plain text message
send_typing <peer> [status]     Sends typing notification. You
                                can supply a custom status (range
                                0-10): none, typing, cancel,
                                record video, upload video,
                                record audio, upload audio,
                                upload photo, upload document,
                                geo, choose contact.
send_typing_abort <peer>        Sends typing notification abort
send_video <peer> <file> [caption]
                                Sends video to peer
set <param> <value>             Sets value of param. Currently
                                available: log_level,
                                debug_verbosity, alarm, msg_num
set_password <hint>             Sets password
set_profile_name <first-name> <last-name>
                                Sets profile name.
set_profile_photo <filename>    Sets profile photo. Photo will be
                                cropped to square
set_ttl <secret chat>           Sets secret chat ttl. Client
                                itself ignores ttl
set_username <name>             Sets username.
show_license                    Prints contents of GPL license
start_bot <bot> <chat> <data>   Adds bot to chat
stats                           For debug purpose
status_online                   Sets status as online
status_offline                  Sets status as offline
unblock_user <user>             Unblocks user
user_info <user>                Prints info about user (id, last
                                online, phone)
view_audio <msg-id>             +
view_chat_photo <chat>          |
view_document <msg-id>          |
view_document_thumb <msg-id>    |
view_file <msg-id>              |- Downloads file to downloads
view_file_thumb <msg-id>        |  dirs. Then tries to open it
view_photo <msg-id>             |  with system default action
view_user_photo <user>          |
view_video <msg-id>             |
view_video_thumb <msg-id>       +
view <msg-id>                   Tries to view message contents
visualize_key <secret chat>     Prints visualization of
                                encryption key (first 16 bytes
                                sha1 of it in fact}
> safe_quit
halt
        \end{verbatim}

    \config{Das Telegram-Kommandozeilenprogramm}{Das Telegram-Kommandozeilenprogramm}{DasTelegramKommandozeilenprogramm}
        Um von der Kommandozeile Nachrichten bzw. Dateien direkt zu
        versenden, z.B. aus einem Monitorprogramm heraus, stehen
        die folgenden Befehlsoptionen zur Verf"ugung:\\
        \hinweis{Leerzeichen im Peer-Namen m"ussen jeweils durch
            Unterstriche ersetzt werden.}
% 14.01.2015/JED - Secret Chat-Nachrichten koennen zur Zeit nicht
%                  direkt ueber das telegram-cli Programm versandt
%                  werden! Aus diesem Grund wurde das Skript
%                  erstellt, welches mittels netcat die Daten an
%                  den Dienst uebergiebt.
        \begin{verbatim}
  send-telegram-message.sh --peer 'peer-name' ACTION
  oder
  send-telegram-message.sh --peer '!_user' ACTION

  ACTIONs:
    --file <file-name>        - sendet eine Audio-, Photo-, Text-
                                oder Videodatei
    --file2msg <file-name>    - sendet eine Textdatei als Nachricht
    --file2audio <file-name>  - sendet eine Textdatei als Audio-
                                nachricht
    --msg MESSAGE-TEXT        - sendet einen Text als Nachricht
    --msg2audio MESSAGE-TEXT  - sendet einen Text als Audionachricht
    --filedesc DESCRIPTION    - uebergibt eine Beschreibung fuer
                                Photo- oder Videodateien
        \end{verbatim}

        Beispiele:
        \begin{verbatim}
  send-telegram-message.sh --peer 'peer-name' --msg 'Hallo Welt'
  oder
  send-telegram-message.sh --peer '!_user' --msg 'Hallo Welt'
  oder
  send-telegram-message.sh --peer 'peer-name' --file /path/to/file.txt
  usw.
        \end{verbatim}

    \config{Der Telegram-BOT-Modus}{Der Telegram-BOT-Modus}{DerTelegramBOTModus}
        Auf Wunsch kann durch Setzen des Parameters TELEGRAM\_BOT\_ENABLED='yes'
        der sogenannte BOT-Modus aktiviert werden. Hierdurch erlaubt man
        dem Telegram-Dienst auf Schl"usselw"orter zu h"oren, die ihm als
        Telegram-Nachricht zugesandt werden, um dann zugeordnete Befehle
        auszuf"uhren und deren Ergebnis an den Sender zur"uck zu senden.

        Um diese Funktion nutzen zu k"onnen, ist nach der Aktivierung
        des oben genannten Parameters jedoch erst einmal mindestens eine
        korrekte Benutzer-ID in die Konfiguration aufzunehmen. Hierzu
        sendet man als Erstes das Schl"usselwort `\textbf{show-my-sender-details}'
        an den Telegram Dienst um eine Antwort nach folgendem Muster zu
        erhalten:

        \begin{verbatim}
  user: T_TEST
  name: Theo_Test
  phone: 4917299887766
  id: $010000000abcdef01234567890abcdef
        \end{verbatim}

        Nun "ubernimmt man die angezeigte ID und den Namen in die
        Konfigurationsdatei, speichert diese und l"asst anschlie"send
        die Konfiguration neu erzeugen:

        \begin{verbatim}
  TELEGRAM_BOT_USER_N           = '1'
    TELEGRAM_BOT_USER_1_ACTIVE  = 'yes'
    TELEGRAM_BOT_USER_1_COMMENT = 'Theo_Test'
    TELEGRAM_BOT_USER_1_ID      = '$010000000abcdef01234567890abcdef'
        \end{verbatim}

        Falls die Konfiguration korrekt vorgenommen wurde sollten ab 
        diesem Zeitpunkt bereits die beiden Schl"usselw"orter
        `\textbf{cmdlist}' und `\textbf{datetime}' zur Verf"ugung
        stehen. Durch Senden des Schl"usselwortes `\textbf{cmdlist}'
        verifizieren wir dies und erhalten folgende Antwort:

        \begin{verbatim}
  cmdlist              - Zeigt die Liste der verfuegbaren Befehle.

  datetime             - Zeigt das aktuelle Datum und die Zeit.
        \end{verbatim}

        Das jeweilige Programm, welches beim Empfang eines Schl"usselwortes
        ausgef"uhrt werden soll, definiert man z.B. "uber folgende Parameter:

        \begin{verbatim}
  TELEGRAM_BOT_CMD_N             = '1'
    TELEGRAM_BOT_CMD_1_ACTIVE    = 'yes'
    TELEGRAM_BOT_CMD_1_COMMENT   = 'Show current date/time.'
    TELEGRAM_BOT_CMD_1_COMMAND   = 'datetime'
    TELEGRAM_BOT_CMD_1_ACTION    = '/bin/date +"%d.%m.%Y %H:%M:%Sh"'
        \end{verbatim}

        An einen Programmaufruf k"onnen bei Bedarf mit Hilfe der
        folgenden Variablen Daten "ubergeben werden:

        \begin{verbatim}
  ${TG_CMD}    - enthaelt das Schluesselswort.
  ${TG_MSG}    - enthaelt alle weiteren Daten die mit dem Befehl
                 eingegangen sind. z.B. die Paketznamen.
        \end{verbatim}
% ${TG_SWITCH} - enhaelt den Schalter '--showresult' wenn dies
%                ueber einen Befehl veranlasst wurde.

        Weitere, vordefinierte Funktionen lassen sich durch Aktivieren
        der entsprechenden Parameter in der Konfigurationsdatei
        freischalten.

        \achtung{Aus Sicherheitsgr"unden wird die Eingabe von 
            absoluten Befehlspfaden erwartet. Dar"uber hinaus muss
            sicher gestellt werden, dass sich der gew"unschte Befehl
            auch mit den Rechten des Systemuser `telegramd' ausf"uhren
            l"asst.}

        \begin{verbatim}
  getupd               - Aktualisiert die Paketdatebank.
  listupd              - Zeigt alle verfuegbaren Updates.
  instupd package-name - Installiert das 'package-name'-Update.
                         (Wird ein +-Zeichen an das Schluesselswort
                          angehangt, so wird die vollstaendige
                          Bildschirmausgabe als Antwort zurueck
                          gesandt).
  uptime               - Zeigt die Uptime des Servers.
        \end{verbatim}

        \hinweis{Um die vordefinierten Befehle `\textbf{getupd}',
            `\textbf{listupd}' und `\textbf{instupd}' nutzen zu k"onnen,
            muss die sudoers-Konfiguration dahingehend erweitert werden,
            dass der eisman-Befehl vom telegramd-Systemuser ausgef"uhrt
            werden kann. Hierzu ist eine Datei /etc/sudoers.d/telegram
            anzulegen, welche mindestens die folgende Zeile enth"alt:\\

            \texttt{telegramd ALL=(root) NOPASSWD:/usr/bin/eisman}}

\end{description}
