telegram-bot-bash/README.txt

325 lines
12 KiB
Plaintext
Raw Normal View History

<h2><img align="middle"
2019-05-14 19:47:50 +00:00
src="https://raw.githubusercontent.com/odb/official-bash-logo/master/assets/Logo
s/Icons/PNG/64x64.png" >
Bashbot - A Telegram bot written in bash.
</h2>
2020-07-25 13:15:15 +00:00
Written by Drew (@topkecleon) and Kay M (@gnadelwartz).
2020-07-25 13:15:15 +00:00
Contributions by Daniil Gentili (@danogentili), JuanPotato, BigNerd95,
TiagoDanin, and iicc1.
2019-04-28 07:54:51 +00:00
Released to the public domain wherever applicable.
Elsewhere, consider it released under the
[WTFPLv2](http://www.wtfpl.net/txt/copying/).
2020-07-27 11:12:56 +00:00
Linted by [#ShellCheck](https://github.com/koalaman/shellcheck)
2019-04-28 07:54:51 +00:00
## Prerequisites
2020-06-26 09:01:56 +00:00
Uses [JSON.sh](http://github.com/dominictarr/JSON.sh) and the magic of sed.
2019-04-28 07:54:51 +00:00
Bashbot is written in bash. It depends on commands typically available in
2021-01-02 05:18:48 +00:00
a Linux/Unix Environment.
For more concrete information on the common commands provided by recent versions of
[coreutils](https://en.wikipedia.org/wiki/List_of_GNU_Core_Utilities_commands),
[busybox](https://en.wikipedia.org/wiki/BusyBox#Commands) or
2019-05-14 18:55:24 +00:00
[toybox](https://landley.net/toybox/help.html), see [Developer
Notes](doc/7_develop.md#common-commands).
**Note for MacOS and BSD Users:** Bashbot will not run without installing
additional software as it uses modern bash and (gnu) grep/sed features.
See [Install Bashbot](doc/0_install.md).
2020-05-19 12:58:29 +00:00
**Note for embedded systems:** You need to install a "real" bash as the
vanilla installation of busybox or toybox is not sufficient.
See [Install Bashbot](doc/0_install.md).
2019-04-28 07:54:51 +00:00
Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and
[Downloads](https://github.com/topkecleon/telegram-bot-bash/releases) are
available on [www.github.com](https://www.github.com).
2019-04-28 07:54:51 +00:00
## Documentation
2020-09-06 09:08:10 +00:00
* [Introduction to Telegram Bots](https://core.telegram.org/bots)
2019-04-28 07:54:51 +00:00
* [Install Bashbot](doc/0_install.md)
* Install release
2020-09-06 09:08:10 +00:00
* Install from github
2019-04-28 07:54:51 +00:00
* Update Bashbot
* Notes on Updates
* [Get Bottoken from Botfather](doc/1_firstbot.md)
2019-04-28 07:54:51 +00:00
* [Getting Started](doc/2_usage.md)
* Managing your Bot
2020-06-23 14:11:45 +00:00
* Receive data
2019-04-28 07:54:51 +00:00
* Send messages
* Send files, locations, keyboards
* [Advanced Features](doc/3_advanced.md)
* Access Control
* Interactive Chats
* Background Jobs
* Inline queries
2020-06-11 10:17:07 +00:00
* Send message errors
2019-04-28 07:54:51 +00:00
* [Expert Use](doc/4_expert.md)
* Handling UTF-8 character sets
* Run as other user or system service
2020-06-23 14:11:45 +00:00
* Schedule bashbot from Cron
2019-05-30 10:03:40 +00:00
* Use from CLI and Scripts
* Customize Bashbot Environment
2019-04-28 07:54:51 +00:00
* [Best Practices](doc/5_practice.md)
2019-06-01 10:41:12 +00:00
* Customize mycommands.sh
* Overwrite/disable commands
2020-06-23 14:11:45 +00:00
* Separate logic from commands
2019-04-28 07:54:51 +00:00
* Test your Bot with shellcheck
2019-05-10 10:04:49 +00:00
* [Function Reference](doc/6_reference.md)
* Sending Messages, Files, Keyboards
* User Access Control
* Inline Queries
* jsshDB Bashbot key-value storage
2019-05-10 10:04:49 +00:00
* Background and Interactive Jobs
2020-06-23 14:35:50 +00:00
* [Developer Notes](doc/7_develop.md)
2019-05-30 10:03:40 +00:00
* Debug bashbot
* Modules, addons, events
2019-04-28 07:54:51 +00:00
* Setup your environment
2020-06-23 14:11:45 +00:00
* Bashbot test suite
* [Examples Directory](examples/README.md)
2019-04-28 07:54:51 +00:00
### Your very first bashbot in a nutshell
2020-05-17 11:16:01 +00:00
2021-01-02 05:17:02 +00:00
To install and run bashbot you need access to a Linux/Unix command line with
2020-12-27 15:22:38 +00:00
bash, a [Telegram client](https://telegram.org) and a mobile phone [with a
Telegram account](https://telegramguide.com/create-a-telegram-account/).
First you need to [create a new Telegram Bot token](doc/1_firstbot.md) for your
bot and write it down.
2020-09-23 08:58:18 +00:00
2021-01-02 05:17:02 +00:00
Now open a Linux/Unix terminal with bash, create a new directory, change to it
2020-12-27 15:22:38 +00:00
and install telegram-bot-bash:
2019-05-24 14:21:51 +00:00
```bash
2020-12-27 15:22:38 +00:00
# create bot dir
mkdir mybot
cd mybot
# download latest release with wget or from
https://github.com/topkecleon/telegram-bot-bash/releases/latest
wget "https://github.com/$(wget -q
"https://github.com/topkecleon/telegram-bot-bash/releases/latest" -O - | egrep
'/.*/download/.*/.*tar.gz' -o)"
2020-12-27 16:13:37 +00:00
# Extract the tar archive and go into bot dir
2020-12-27 15:22:38 +00:00
tar -xzf *.tar.gz
cd telegram-bot-bash
# initialize your bot
# Enter your bot token when asked, all other questions can be answered by
hitting the \<Return\> key.
./bashbot.sh init
# Now start your bot
./bashbot.sh start
Bottoken is valid ...
Bot Name: yourbotname_bot
Session Name: yourbotname_bot-startbot
Bot started successfully.
2019-05-24 14:21:51 +00:00
```
Now open the Telegram App on your mobile phone and start a chat with your
2020-12-27 15:22:38 +00:00
bot (_your bot's username is shown after 'Bot Name:'_):
2019-05-24 14:21:51 +00:00
```
/start
You are Botadmin
*Available commands*:
*• /start*: _Start bot and get this message_.
*• /help*: _Get this message_.
*• /info*: _Get shorter info message about this bot_....
/info
2020-09-06 09:08:10 +00:00
This is bashbot, the Telegram bot written entirely in bash.
2019-05-24 14:21:51 +00:00
It features background tasks and interactive chats, and can serve as an
interface for CLI programs.
```
For more Information on how to install, customize and use your new bot, read
the [Documentation](#Documentation).
2019-05-24 14:21:51 +00:00
2020-06-14 11:50:44 +00:00
### Log files
Bashbot actions are logged to `BASHBOT.log`. Telegram send/receive errors are
2020-12-29 12:03:46 +00:00
logged to `ERROR.log`.
Start bashbot in debug mode to see all messages sent to / received from
Telegram, as well as bash command error messages.
2020-06-14 11:50:44 +00:00
To enable debug mode, start bashbot with debug as third argument: `bashbot start
2020-06-14 11:50:44 +00:00
debug`
```
├── logs
2020-06-18 14:20:42 +00:00
│   ├── BASHBOT.log # log what your bot is doing ...
│   ├── ERROR.log # connection errors from / to Telegram API
2020-06-14 11:50:44 +00:00
│   │
2020-11-29 16:20:57 +00:00
│   ├── DEBUG.log # stdout/stderr of you bot (debug mode enabled)
│   └── MESSAGE.log # full text of all message send/received (debug mode
2020-06-18 14:20:42 +00:00
enabled)
2020-06-14 11:50:44 +00:00
```
2019-05-24 14:21:51 +00:00
----
2019-04-28 07:54:51 +00:00
## Security Considerations
Running a Telegram Bot means it is connected to the public and you never know
2020-06-23 14:35:50 +00:00
what's send to your Bot.
2019-04-28 07:54:51 +00:00
Bash scripts in general are not designed to be bulletproof, so consider this
2020-12-29 12:03:46 +00:00
Bot as a proof of concept.
Bash programmers often struggle with 'quoting hell' and globbing,
see [Implications of wrong
2019-04-28 07:54:51 +00:00
quoting](https://unix.stackexchange.com/questions/171346/security-implications-o
f-forgetting-to-quote-a-variable-in-bash-posix-shells).
2019-04-28 07:54:51 +00:00
2020-07-25 13:15:15 +00:00
Whenever you are processing input from untrusted sources (messages, files,
network) you must be as careful as possible
(e.g. set IFS appropriately, disable globbing wity `set -f` and quote everything). In
2020-12-29 12:03:46 +00:00
addition remove unused scripts and examples
from your Bot (e.g. everything in `example/`) and disable/remove all unused
2020-12-29 12:03:46 +00:00
bot commands.
It's important to escape or remove `$` in input from user, files or network
(_as bashbot does_).
One of the powerful features of Unix shells is variable and command
substitution using `${}` and`$()`
can lead to remote code execution (RCE) or remote information disclosure
(RID) bugs if unescaped `$` is included in untrusted input (e.g. `$$` or `$(rm
-rf /*)`).
2020-12-29 12:03:46 +00:00
A powerful tool to improve your scripts is `shellcheck`. You can [use it
online](https://www.shellcheck.net/) or
[install shellcheck
2019-05-01 12:36:34 +00:00
locally](https://github.com/koalaman/shellcheck#installing). Shellcheck is used
2020-12-29 12:03:46 +00:00
extensively in bashbot development
to ensure a high code quality (e.g. it's not allowed to push changes without
passing all shellcheck tests).
2019-05-01 12:36:34 +00:00
In addition bashbot has a [test suite](doc/7_develop.md) to check if important
functionality is working as expected.
2019-04-28 07:54:51 +00:00
2020-07-25 13:15:15 +00:00
### Use printf whenever possible
If you're writing a script that accepts external input (e.g. from the user as
arguments or the file system),
you shouldn't use echo to display it. [Use printf whenever
possible](https://unix.stackexchange.com/a/6581).
2019-04-28 07:54:51 +00:00
### Run your Bot as a restricted user
**I recommend running your bot as a user with almost no access rights.**
All files your Bot has write access to are in danger of being overwritten/deleted
2019-04-28 07:54:51 +00:00
if your bot is hacked.
For the same reason every file your Bot can read is in danger of being disclosed.
2020-07-25 13:15:15 +00:00
Restrict your Bots access rights to the absolute minimum.
2019-04-28 07:54:51 +00:00
**Never run your Bot as root, this is the most dangerous you can do!** Usually
2021-01-02 05:17:02 +00:00
the user 'nobody' has almost no rights on Linux/Unix systems. See [Expert
2019-04-28 07:54:51 +00:00
use](doc/4_expert.md) on how to run your Bot as an other user.
### Secure your Bot installation
**Your Bot configuration must not be readable by other users.** Everyone who
2020-07-25 13:15:15 +00:00
can read your Bots token is able to act as your Bot and has access to all chats
the Bot is in!
2019-04-28 07:54:51 +00:00
Everyone with read access to your Bot files can extract your Bots data.
2020-12-29 12:03:46 +00:00
Especially your Bot config in`config.jssh` must be protected against other
2020-07-28 07:19:01 +00:00
users. No one except you should have write access to the Bot files. The Bot
2020-12-29 12:03:46 +00:00
should be restricted to have write access to`count.jssh` and `data-bot-bash`
only, all other files must be write protected.
2019-04-28 07:54:51 +00:00
2020-12-29 12:03:46 +00:00
To set access rights for your bashbot installation to a reasonable default
run`sudo ./bashbot.sh init` after every update or change to your installation
2019-04-28 07:54:51 +00:00
directory.
2019-05-20 18:48:49 +00:00
## FAQ
2019-04-28 07:54:51 +00:00
### Is this Bot insecure?
Bashbot is not more (in)secure than a Bot written in another language. We have
2020-07-25 13:15:15 +00:00
done our best to make it as secure as possible. But YOU are responsible for the
bot commands you wrote and you should know about the risks ...
2019-04-28 07:54:51 +00:00
2020-07-28 07:14:57 +00:00
**Note:** Up to version 0.941 (mai/22/2020) telegram-bot-bash had a remote code
2020-07-25 13:15:15 +00:00
execution bug, please update if you use an older version!
2020-05-27 07:06:22 +00:00
2019-04-28 07:54:51 +00:00
### Why Bash and not the much better xyz?
2021-01-02 05:17:02 +00:00
Well, that's a damn good question... maybe because I'm a Unix admin from
the stone age. Nevertheless there are more reasons from my side:
2019-04-28 07:54:51 +00:00
- bashbot will run wherever bash and (gnu) sed is available, from
2021-01-02 05:17:02 +00:00
embedded Linux to mainframe
- easy to integrate with other shell scripts, e.g. for sending system message /
2019-04-28 07:54:51 +00:00
health status
- no need to install or learn a new programming language, library or framework
2020-07-25 13:15:15 +00:00
- no database, not event driven, not object oriented ...
### Can I have the single bashbot.sh file back?
At the beginning bashbot was simply the file`bashbot.sh` that you could copy
2019-05-20 18:48:49 +00:00
everywhere and run the bot. Now we have 'commands.sh', 'mycommands.sh',
'modules/*.sh' and much more.
Hey no problem, if you are finished with your cool bot,
run`dev/make-standalone.sh` to create a stripped down version of your bot
2019-05-20 18:48:49 +00:00
containing only
'bashbot.sh' and 'commands.sh'! For more information see [Create a stripped
down version of your Bot](doc/7_develop.md).
2019-05-20 18:48:49 +00:00
2019-05-24 18:30:01 +00:00
### Can I send messages from CLI and scripts?
Of course you can send messages from command line and scripts! Simply install
2020-12-29 12:03:46 +00:00
bashbot as [described here](#Your-really-first-bashbot-in-a-nutshell),
send the message '/start' to set yourself as botadmin and then stop the bot
with `./bashbot.sh stop`.
2019-05-24 18:30:01 +00:00
2020-12-29 12:03:46 +00:00
Bashbot provides some ready to use scripts for sending messages from command
line in `bin/` dir, e.g. `send_message.sh`.
2019-05-24 18:30:01 +00:00
```bash
2020-12-29 09:18:41 +00:00
bin/send_message.sh BOTADMIN "This is my first message send from CLI"
2019-05-24 18:30:01 +00:00
2020-12-29 09:18:41 +00:00
bin/send_message.sh --help
2019-05-24 18:30:01 +00:00
```
2020-12-29 09:18:41 +00:00
You can also source bashbot for use in your scripts, for more information see
2021-01-02 06:51:51 +00:00
[Expert Use](doc/4_expert.md).
2019-05-24 18:30:01 +00:00
2020-06-23 14:11:45 +00:00
### Blocked by telegram?
This may happen if too many or wrong requests are sent to api.telegram.org, e.g.
using a invalid token or invalid API calls.
2020-07-12 16:19:50 +00:00
If the block stay for longer time you can ask telegram service to unblock your
IP-Address.
2020-06-23 14:11:45 +00:00
2020-07-12 16:19:50 +00:00
You can check with curl or wget if you are blocked by Telegram:
2019-05-24 08:47:27 +00:00
```bash
curl -m 10 https://api.telegram.org/bot
#curl: (28) Connection timed out after 10001 milliseconds
wget -t 1 -T 10 https://api.telegram.org/bot
#Connecting to api.telegram.org (api.telegram.org)|46.38.243.234|:443...
failed: Connection timed out.
2020-12-14 13:00:23 +00:00
nc -w 2 api.telegram.org 443 || echo "your IP seems blocked by telegram"
#your IP seems blocked by telegram
2019-05-24 08:47:27 +00:00
```
2019-05-20 18:48:49 +00:00
2020-12-29 09:18:41 +00:00
Bashbot offers the option to recover from broken connections (blocked).
Therefore you can provide a function
named `bashbotBlockRecover()` in `mycommands.sh`, the function is called every
time when a broken connection is detected.
2020-07-12 11:52:03 +00:00
Possible actions are: Check if network is working, change IP-Address or simply
2020-07-25 13:15:15 +00:00
wait some time.
2020-12-29 09:18:41 +00:00
See `mycommnds.sh.dist` for an example.
2020-07-12 16:19:50 +00:00
2020-12-29 09:18:41 +00:00
---
2020-07-12 11:52:03 +00:00
@Gnadelwartz
2019-04-27 13:48:03 +00:00
## That's it all guys!
2019-04-09 11:41:38 +00:00
2019-04-28 07:54:51 +00:00
If you feel that there's something missing or if you found a bug, feel free to
submit a pull request!
2019-04-09 11:41:38 +00:00
2020-12-29 13:02:11 +00:00
#### $$VERSION$$ v1.21-dev-34-ga5307e3