Metadata-Version: 2.1
Name: telerembash
Version: 0.2.5
Summary: A Telegram Remote Shell Bot with HOTP authentication.
Home-page: https://github.com/kpe/telerembash/
Author: kpe
Author-email: kpe.git@gmailbox.org
License: MIT
Description: TeleRemBash
        ===========
        
        |Build Status| |Coverage Status| |Version Status| |Python Versions| |Downloads|
        
        ``TeleRemBash`` is a `Telegram`_ Remote Bash `Bot`_ for executing
        scripts on the remote system, baked with `TOTP`_ Authentication for
        easy and secure setup.
        
        To keep things simple ``TeleRamBash`` allows a single Telegram user
        after a successful `TOTP`_ Authentication to execute a pre-defined (bash) script
        by sending a command to the Bot in a Telegram chat, like this:
        
        .. code:: bash
        
            /do some-script optional-param1
        
        Usage
        -----
        To install from pypi:
        
        .. code:: bash
        
            pip install telerembash
        
        First create a configuration for your Telegram Bot instance by specifying
        the bot's ``API_TOKEN`` and the Telegram username of the whitelisted user:
        
        .. code:: bash
        
           telerem init --api_token API_TOKEN --username USERNAME
        
        this should create a ``telerem.config.yaml`` in the current directory
        and output a QR Code you can scan in your TOTP Authenticator App (i.e.
        `Google Authenticator`_, `andOTP`_, etc).
        
        To see all available options, try:
        
        .. code:: bash
        
            telerem --help
        
        you can edit ``telerem.config.yaml`` by hand or call ``telerem init`` multiple times,
        to tweak the config.
        Note the ``scripts_root`` in the config - this is the location (absolute or relative to
        the current working directory) of the directory containing the script your bot will
        execute.
        
        To start the bot:
        
        .. code:: bash
        
            telerem start --config config.yaml
        
        Once your bot is running, you should add it in a chat.
        It will ignore all your messages until it sees a
        
        .. code:: bash
        
            /auth <code>
        
        command, where ``<code>`` is the code generated by your TOTP Authenticator.
        
        And once you are successfully authenticated, you can execute a script
        with a Telegram message like this:
        
        .. code:: bash
        
            /do some-script-name param1 param2
        
        The bot will reply to such a command by looking under ``scripts_root`` for
        a file with the name ``some-script-name`` or ``some-script-name.sh``
        and executing it (with the provided optional parameters).
        
        Run as a Service (WIP)
        ----------------------
        You can also create a systemd service or a daemon script for
        starting your bot as a daemon with:
        
        .. code:: bash
        
            telerem install --systemd | sudo bash  # for systemd
            telerem install --initd   | sudo bash  #   otherwise
        
        this will:
        
         1. create a system user ``teleremd``
         2. setup a python venv under ``/home/teleremd/``
         3. create a service (either ``systemd`` or ``init.d``):
        
           * systemd service unit ``/etc/systemd/system/teleremd.service``
           * deamon script ``/etc/init.d/teleremd``
        
         4. populate the daemon configuration under ``/etc/teleremd.config.yaml``
        
        and finally:
        
        .. code:: bash
        
           sudo systemctl daemon-reload   # for systemd
           sudo systemctl start teleremd
        
        
        NEWS
        ----
         - **16.Jan.2021** - install as a systemd service (init.d still WIP)
         - **15.Jan.2021** - README: Usage instructions
         - **09.Jan.2021** - initial commit
        
        LICENSE
        -------
        
        MIT. See `License File <https://github.com/kpe/telerembash/blob/master/LICENSE.txt>`_.
        
        
        Resources
        ---------
        
        - `Telegram`_ - Telegram BOT API
        - `PyOTP`_ - The Python One-Time Password Library
        - `python-qrcode`_ - QR code generator for text terminals
        
        .. _`python-qrcode`: https://github.com/lincolnloop/python-qrcode
        .. _`PyOTP`: https://github.com/pyauth/pyotp
        .. _`TOTP`: https://en.wikipedia.org/wiki/Time-based_One-Time_Password
        .. _`Telegram`: https://core.telegram.org/api
        .. _`Bot`: https://core.telegram.org/bots
        .. _`Google Authenticator`: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2
        .. _`andOTP`: https://play.google.com/store/apps/details?id=org.shadowice.flocke.andotp
        
        
        .. |Build Status| image:: https://travis-ci.com/kpe/telerembash.svg?branch=master
           :target: https://travis-ci.com/kpe/telerembash
        .. |Coverage Status| image:: https://coveralls.io/repos/kpe/telerembash/badge.svg?branch=master
           :target: https://coveralls.io/r/kpe/telerembash?branch=master
        .. |Version Status| image:: https://badge.fury.io/py/telerembash.svg
           :target: https://badge.fury.io/py/telerembash
        .. |Python Versions| image:: https://img.shields.io/pypi/pyversions/telerembash.svg
        .. |Downloads| image:: https://img.shields.io/pypi/dm/telerembash.svg
        .. |Twitter| image:: https://img.shields.io/twitter/follow/siddhadev?logo=twitter&label=&style=
           :target: https://twitter.com/intent/user?screen_name=siddhadev
        
Keywords: telegram totp hotp authentication bot
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.5
Description-Content-Type: text/x-rst
