Skip to content

kpe/telerembash

Repository files navigation

TeleRemBash

Build Status Coverage Status Version Status Python Versions Downloads

TeleRemBash is a Telegram Bot for executing scripts on a remote system, baked with TOTP Authentication for a secure and easy setup (QR codes).

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:

/do some-script optional-param1

ASCIINEMA

Usage

To install from pypi:

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:

telerem init --api-token API_TOKEN --username USERNAME

this should create a telerem.config.yaml in the current directory and output a QR Code to be scanned in your TOTP Authenticator App (i.e. Google Authenticator, andOTP, etc).

To see all available options, try:

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:

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

/auth <code>

command, where <code> is the authentication code generated by your TOTP Authenticator.

And once you are successfully authenticated, you can execute a script by sending a Telegram message like this:

/do some-script-name param1 param2

The bot will reply to a /do 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 running your bot in the background like this:

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
  1. populate the daemon configuration under /etc/teleremd.config.yaml

and finally:

sudo systemctl daemon-reload   # for systemd
sudo systemctl start teleremd

NEWS

  • 21.Jan.2021 - available on pypi
  • 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.

Resources