Das Telegram-Paket Die Einleitung Telegram ([1]https://telegram.org/) erlaubt das Versenden und Empfangen von Kurznachrichten ueber den kostenfreien Telegram-Instant Messaging Service. Der Fokus liegt dabei auf den Themen Sicherheit und Geschwindigkeit. Darueber hinaus erlaubt Telegram den Abgleich von Chat-Dateien ueber verschiedenste Klienten hinweg. ACHTUNG Um das Paket verwenden zu koennen ist eine einmalige Registrierung erforderlich, welche im Absatz [2]Der Registierungsprozess erklaert wird. Die Funktionen Das Telegram-Paket besteht aus folgender Komponente: * telegram-cli - Das Telegram CLI-Programmpaket. ([3]https://github.com/vysheng/tg) Die Voraussetzungen Zur Nutzung des Programms werden keine weiteren Programmpakete benoetigt. Die Installation Das Telegram-Paket wird ueber das Setup-Menue installiert. Wird eine aeltere Paketversion vorgefunden, so wird diese deinstalliert bevor die neuen Programmdateien installiert werden. Das Menue im Setup-Programm Das Menue im Setup-Programm ist wie folgt aufgebaut: * View documentation: Anzeigen der Dokumentation * Edit configuration: Bearbeiten der Konfiguration * Advanced configuration file handling: Konfigurationen verwalten * Show status: Status der Telegram-CLI Dienstes anzeigen * Start service: Starten des Telegram-CLI Dienstes * Stop service: Stoppen des Telegram-CLI Dienstes * Restart service: Neustarten des Telegram-CLI Dienstes * Send test message: Eine Testnachricht versenden * Start Telegram Client: Das Telegram Klientenprogramm starten * View log file: Die Logmeldungen anzeigen * Return: Untermenue verlassen Die Menuepunkte duerften selbsterklaerend sein, da sie keinerlei weitere Eingaben erwarten. Aus diesem Grund wird auf deren Funktion nicht weiter eingegangen. Die Aenderung der Konfiguration Die Konfiguration kann ueber den Menuepunkt 'Edit configuration' geaendert werden. Standardmaessig wird der Editor aufgerufen, der in der Environment-Konfiguration ueber die Variable 'EDITOR' festgelegt wurde. Nachdem der Editor beendet wurde wird abgefragt, ob die Konfiguration aktiviert werden soll. Wird dies bestaetigt, werden ueber ein Skript die Anpassungen umgehend wirksam gemacht. Die Konfigurationsdatei In der Konfigurationsdatei, die ueber das Menue zugaenglich ist, sind folgende Parameter vorhanden; wer sie von Hand editieren will findet sie unter /etc/config.d/telegram. Die Parameter START_TELEGRAM Fuer die Aktivierung des Telegram-Dienstes muss diese Variable lediglich auf den Wert `yes' gestellt werden. Die Einstellung 'no' deaktiviert den Telegram-Dienst. Gueltige Werte: yes, no Standardeinstellung: START_TELEGRAM='no' TELEGRAM_LISTEN_PORT (Optionaler Parameter) Ueber diesen Parameter wird der TCP-Port festgelegt, auf dem der Telegram-Dienst Verbindungen entgegennehmen soll. Gueltige Werte: Zahl Standardeinstellung: TELEGRAM_LISTEN_PORT='2391' TELEGRAM_BOT_ENABLED Ueber 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. Gueltige Werte: yes, no Standardeinstellung: TELEGRAM_BOT_ENABLED='no' TELEGRAM_BOT_USER_N Ueber diesen Parameter wird die Anzahl der authorisierten Anwender festgelegt, auf deren Befehle der BOT reagieren soll. Gueltige Werte: Zahl Standardeinstellung: TELEGRAM_BOT_USER_N='1' TELEGRAM_BOT_USER_x_ACTIVE Wird dieser Parameter auf den Wert `yes' gesetzt, so wird der zugehoerige Datensatz aktiviert, `no' deaktiviert ihn. Gueltige Werte: yes, no Standardeinstellung: TELEGRAM_BOT_USER_1_ACTIVE='no' TELEGRAM_BOT_USER_x_COMMENT Ueber diesen Parameter kann auf Wunsch ein Kommentar angegeben werden, da die Zuordnung des Datensatzes erleichtert. Gueltige Werte: beliebiger Text Beispiel: TELEGRAM_BOT_USER_1_COMMENT='Id of Theo Test' TELEGRAM_BOT_USER_x_ID Ueber 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. Gueltige Werte: gueltige Telegram-ID Beispiel: TELEGRAM_BOT_USER_x_ID='$010000000abcdef01234567890abcdef' TELEGRAM_BOT_CMD_N Ueber diesen Parameter wird die Anzahl der zu akzeptierenden Telegram-Befehle festgelegt. Gueltige Werte: Zahl Standardeinstellung: TELEGRAM_BOT_CMD_N='6' TELEGRAM_BOT_CMD_x_ACTIVE Wird dieser Parameter auf den Wert `yes' gesetzt, so wird der zugehoerige Datensatz aktiviert, `no' deaktiviert ihn. Gueltige Werte: yes, no Standardeinstellung: TELEGRAM_BOT_CMD_1_ACTIVE='no' TELEGRAM_BOT_CMD_x_COMMENT Ueber diesen Parameter kann auf Wunsch ein Kommentar angegeben werden, da die Zuordnung des Datensatzes erleichtert. Gueltige Werte: beliebiger Text Beispiel: TELEGRAM_BOT_CMD_1_COMMENT='Show current date/time.' TELEGRAM_BOT_CMD_x_COMMAND Ueber diesen Parameter wird das Befehlsschluesselwort festgelegt, auf welches der BOT reagieren soll. Gueltige Werte: beliebiger Text (max. 10 Zeichen) Beispiel: TELEGRAM_BOT_CMD_1_COMMAND='datetime' TELEGRAM_BOT_CMD_x_ACTION PMquot;Uber diesen Parameter wird festgelegt, welcher Befehl beim Empfang des zuvor definierten Befehlsschluesselwortes ausgefuehrt werden soll. Gueltige Werte: absoluter Befehlspfad, gefolgt von optionalen Parametern Beispiel: TELEGRAM_BOT_CMD_1_ACTION='/bin/date +"%d.%m.%Y %H:%M:%Sh"' TELEGRAM_KEEP_ALIVE Ueber diesen Parameter wird festgelegt, ob zyklisch eine Telegram-Nachricht versandt werden soll um so zu bestaetigen, dass der Dienst noch fehlerfrei funktioniert. Gueltige Werte: yes, no Standardeinstellung: TELEGRAM_KEEP_ALIVE='no' TELEGRAM_KEEP_ALIVE_ADDR Ueber diesen Parameter wird der Empfaenger oder die Gruppe festgelegt an welche zyklisch eine Telegram-Nachricht gesandt werden soll. Gueltige Werte: existierender Telegram-Anwender oder Gruppe Standardeinstellung: TELEGRAM_KEEP_ALIVE_ADDR='' TELEGRAM_KEEP_ALIVE_TEXT Ueber diesen Parameter wird der Text der Telegram-Nachricht festgelegt, welche zyklisch an den zuvor festgelegten Empfaenger bzw. Gruppe versandt werden soll. Gueltige Werte: Text Standardeinstellung: TELEGRAM_KEEP_ALIVE_TEXT='Hello world!' TELEGRAM_KEEP_ALIVE_CRON_SCHEDULE Ueber diesen Parameter wird festgelegt zu welchem Zeitpunkt bzw. in welchem Intervall eine Telegram-Nachricht versandt werden soll. Die fuenf 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 naeheres ueber die verwendete Befehlssyntax erfahren moechte, sollte ueber eine Internet- Suchmaschine nach 'man' und 'crontab' suchen. Gueltige Werte: Crontab-spezifischer Parametereintrag Standardeinstellung: TELEGRAM_KEEP_ALIVE_CRON_SCHEDULE='0 0 * * *' TELEGRAM_LOG_COUNT Ueber diesen Parameter wird eingestellt, wie viele Logdateien vorgehalten werden sollen. Wird dieser Wert ueberschritten, so wird die aelteste Logdatei geloescht. Gueltige Werte: Zahl Standardeinstellung: TELEGRAM_LOG_COUNT='10' TELEGRAM_LOG_INTERVAL Ueber diesen Parameter wird eingestellt, in welchen Intervallen die Logdateien archiviert werden sollen. Zur Auswahl stehen die Schluesselwoerter `daily' - taeglich, `weekly' - woechentlich und `monthly - monatlich. Gueltige Werte: daily, weekly, monthly Standardeinstellung: TELEGRAM_LOG_INTERVAL='weekly' Verschiedenes Der Registierungsprozess Um das Programm verwenden zu koennen, ist eine einmalige Registrierung am Service notwendig. Hierzu kann jede Telefonnummer verwendet werden, ueber welche man SMS- oder Sprachnachrichten empfangen kann. Hinweis: Bei der Erstellung der folgenden Beschreibung wurde auf Informationen von folgender Webseite zurueck gegriffen: http://www.home-automation-community.com/telegram-messenger-on- the-raspberry-pi/ 1. Zur Registrierung der Telefonnummer startet man das telegram-cli-Programm ueber den Menuepunkt `Start Telegram Client' und gibt bei der Frage nach der Telefonnummer eine Rufnummer in internationaler Schreibweise an, d.h. im Format Laenderkode inkl. vorangestelltem `+'-Zeichen, Ortsvorwahl ohne fuehrende Null und die Rufnummer. 2. Nach kurzer Zeit sollte eine SMS mit dem benoetigten Freischaltungskode auf dem Telefon eingegangen sein. Direkt nach der Eingabe des Freischaltungskodes kann man den Service verwenden. 3. Abschliessend muss nun noch einmal der Telegram-Dienst ueber den Menuepunkt `Restart service' neu gestartet werden um die Einstellungen dauerhaft zu aktivieren. Dies sind die Bildschirmausgaben waehrend der Registrierung: 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 Das Telegram-Klientenprogramm Ueber das Menue bzw. die Kommandozeile kann das Telegram-Klientenprogramm (telegram-cli) gestartet werden. Man verlaesst das Programm durch Eingabe von `safe_quit'. Der Kommandozeilenbefehl lautet hierbei: # telegram-cli -W Sobald der Client gestartet wurde, kann man diesen mit bestimmten Kommandos bedienen. Ueber das Kommando `help' erhaelt man z.B. folgende Ausgabe: > help accept_secret_chat Accepts secret chat. Only useful with -E option add_contact Tries to add user to contact list block_user Blocks user broadcast + Sends text to several users at once chat_add_user [msgs-to-forward] Adds user to chat. Sends him last msgs-to-forward message from this chat. Default 100 chat_del_user Deletes user from chat chat_info Prints info about chat (id, members, admin, etc.) chat_set_photo Sets chat photo. Photo will be cropped to square chat_with_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 + Creates group chat with users create_secret_chat Starts creation of secret chat del_contact Deletes contact from contact list delete_msg 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 + Forwards message to peer. Forward to secret chats is forbidden fwd_media Forwards message media to peer. Forward to secret chats is forbidden. Result slightly differs from fwd get_message Get message by id get_self Get our user info help Prints this help history [limit] [offset] Prints messages with this peer (most recent message lower). Also marks messages as read import_card Gets user by card and prints it name. You can then send messages to him as usual import_chat_link Joins to chat by link load_audio + load_chat_photo | load_document | load_document | load_document_thumb | load_file |- Downloads file to downloads load_file_thumb | dirs. Prints file name after load_photo | download end load_user_photo | load_video | load_video_thumb + main_session Sends updates to this connection (or terminal). Useful only with listening socket mark_read Marks messages with peer as read msg Sends text message to peer msg Sends text message to peer with custom kbd quit Quits immediately rename_chat Renames chat rename_contact Renames contact reply Sends text reply to message reply_audio Sends audio to peer reply_contact Sends contact (not necessary telegram user) reply_document Sends document to peer reply_file Sends document to peer reply_location Sends geo location reply_photo [caption] Sends photo to peer reply_video 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 Sends audio to peer send_contact Sends contact (not necessary telegram user) send_document Sends document to peer send_file Sends document to peer send_location Sends geo location send_photo [caption] Sends photo to peer send_text Sends contents of text file as plain text message send_typing [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 Sends typing notification abort send_video [caption] Sends video to peer set Sets value of param. Currently available: log_level, debug_verbosity, alarm, msg_num set_password Sets password set_profile_name Sets profile name. set_profile_photo Sets profile photo. Photo will be cropped to square set_ttl Sets secret chat ttl. Client itself ignores ttl set_username Sets username. show_license Prints contents of GPL license start_bot Adds bot to chat stats For debug purpose status_online Sets status as online status_offline Sets status as offline unblock_user Unblocks user user_info Prints info about user (id, last online, phone) view_audio + view_chat_photo | view_document | view_document_thumb | view_file |- Downloads file to downloads view_file_thumb | dirs. Then tries to open it view_photo | with system default action view_user_photo | view_video | view_video_thumb + view Tries to view message contents visualize_key Prints visualization of encryption key (first 16 bytes sha1 of it in fact} > safe_quit halt Das Telegram-Kommandozeilenprogramm Um von der Kommandozeile Nachrichten bzw. Dateien direkt zu versenden, z.B. aus einem Monitorprogramm heraus, stehen die folgenden Befehlsoptionen zur Verfuegung: Hinweis Leerzeichen im Peer-Namen muessen jeweils durch Unterstriche ersetzt werden. send-telegram-message.sh --peer 'peer-name' ACTION oder send-telegram-message.sh --peer '!_user' ACTION ACTIONs: --file - sendet eine Audio-, Photo-, Text- oder Videodatei --file2msg - sendet eine Textdatei als Nachricht --file2audio - 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 Beispiele: 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. Der Telegram-BOT-Modus Auf Wunsch kann durch Setzen des Parameters TELEGRAM_BOT_ENABLED='yes' der sogenannte BOT-Modus aktiviert werden. Hierdurch erlaubt man dem Telegram-Dienst auf Schluesselwoerter zu hoeren, die ihm als Telegram-Nachricht zugesandt werden, um dann zugeordnete Befehle auszufuehren und deren Ergebnis an den Sender zurueck zu senden. Um diese Funktion nutzen zu koennen, 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 Schluesselwort `show-my-sender-details' an den Telegram Dienst um eine Antwort nach folgendem Muster zu erhalten: user: T_TEST name: Theo_Test phone: 4917299887766 id: $010000000abcdef01234567890abcdef Nun uebernimmt man die angezeigte ID und den Namen in die Konfigurationsdatei, speichert diese und laesst anschliessend die Konfiguration neu erzeugen: TELEGRAM_BOT_USER_N = '1' TELEGRAM_BOT_USER_1_ACTIVE = 'yes' TELEGRAM_BOT_USER_1_COMMENT = 'Theo_Test' TELEGRAM_BOT_USER_1_ID = '$010000000abcdef01234567890abcdef' Falls die Konfiguration korrekt vorgenommen wurde sollten ab diesem Zeitpunkt bereits die beiden Schluesselwoerter `cmdlist' und `datetime' zur Verfuegung stehen. Durch Senden des Schluesselwortes `cmdlist' verifizieren wir dies und erhalten folgende Antwort: cmdlist - Zeigt die Liste der verfuegbaren Befehle. datetime - Zeigt das aktuelle Datum und die Zeit. Das jeweilige Programm, welches beim Empfang eines Schluesselwortes ausgefuehrt werden soll, definiert man z.B. ueber folgende Parameter: 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"' An einen Programmaufruf koennen bei Bedarf mit Hilfe der folgenden Variablen Daten uebergeben werden: ${TG_CMD} - enthaelt das Schluesselswort. ${TG_MSG} - enthaelt alle weiteren Daten die mit dem Befehl eingegangen sind. z.B. die Paketznamen. Weitere, vordefinierte Funktionen lassen sich durch Aktivieren der entsprechenden Parameter in der Konfigurationsdatei freischalten. ACHTUNG Aus Sicherheitsgruenden wird die Eingabe von absoluten Befehlspfaden erwartet. Darueber hinaus muss sicher gestellt werden, dass sich der gewuenschte Befehl auch mit den Rechten des Systemuser `telegramd' ausfuehren laesst. 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. Hinweis Um die vordefinierten Befehle `getupd', `listupd' und `instupd' nutzen zu koennen, muss die sudoers-Konfiguration dahingehend erweitert werden, dass der eisman-Befehl vom telegramd-Systemuser ausgefuehrt werden kann. Hierzu ist eine Datei /etc/sudoers.d/telegram anzulegen, welche mindestens die folgende Zeile enthaelt: telegramd ALL=(root) NOPASSWD:/usr/bin/eisman __________________________________________________________________ Juergen Edner 2018-05-10