diff --git a/README.html b/README.html index ad13d51..0b64fb6 100644 --- a/README.html +++ b/README.html @@ -287,15 +287,32 @@ Written by Drew (@topkecleon) and Kay M (@gnadelwartz).
To install and run bashbot you need access to a linux/unix command line. If you don't know how to get access to a linux/unix command line you should stop reading here :-(
-In addition you need a Telegram client and a mobile phone to register an account. If you don't want to register for Telegram you should stop reading here ;-)
-After you're registered to Telegram send a message to @botfather, create a new Telegram Bot token and write it down. You need the token to install the bot.
-Now open a terminal and check if bash is installed:
-which bash && echo "bash seems available..."
-Create a new directory, change to it: mkdir tbb; cd tbb
and download the latest '*.tar.gz' file from https://github.com/topkecleon/telegram-bot-bash/releases. This can be done with the commands:
wget -q https://github.com/$(wget -q https://github.com/topkecleon/telegram-bot-bash/releases/latest -O - | egrep '/.*/.*/.*tar.gz' -o)
Extract the '*.tar.gz' file and change to bashbot directory: tar -xzf *.tar.gz; cd telegram-bot-bash
, install bashbot: ./bashbot.sh init
and enter your bot token when asked. All other questions can be answered by hitting the <Return> key.
That's all, now you can start your bot with ./bashbot.sh start
and send him messages:
To install and run bashbot you need access to a linux/unix command line with bash, a Telegram client and a mobile phone with a Telegram account.
+First you need to create a new Telegram Bot token for your bot and write it down.
+Now open a linux/unix terminal with bash, create a new directory, change to it and install telegram-bot-bash:
+# 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)"
+
+# Extract the tar archive
+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.
Now open the Telegram App on your mobile phone and start a chatting with your bot (your bot's username is shown after 'Bot Name:'):
/start
You are Botadmin
@@ -328,19 +345,19 @@ It features background tasks and interactive chats, and can serve as an interfac
A powerful tool to improve your scripts is shellcheck
. You can use it online or install shellcheck locally. Shellcheck is used extensively in bashbot development to ensure a high code quality, e.g. it's not allowed to push changes without passing all shellcheck tests. In addition bashbot has a test suite to check if important functionality is working as expected.
Use printf whenever possible
If you're writing a script and it is taking external input (from the user as arguments or file system...), you shouldn't use echo to display it. Use printf whenever possible
-# very simple
- echo "text with variables. PWD=$PWD"
- printf '%s\n' "text with variables. PWD=$PWD"
- printf 'text with variables. PWD=%s\n' "$PWD"
- -> text with variables. PWD=/home/xxx
-
-# more advanced
- FLOAT="1.2346777892864" INTEGER="12345.123"
- echo "float=$FLOAT, integer=$INTEGER, PWD=$PWD"
- -> float=1.2346777892864, integer=12345.123, PWD=/home/xxx
-
-printf "text with variables. float=%.2f, integer=%d, PWD=%s\n" "$FLOAT" "$INTEGER" "$PWD"
- -> float=1.23, integer=12345, PWD=/home/xxx
+# very simple
+ echo "text with variables. PWD=$PWD"
+ printf '%s\n' "text with variables. PWD=$PWD"
+ printf 'text with variables. PWD=%s\n' "$PWD"
+ -> text with variables. PWD=/home/xxx
+
+# more advanced
+ FLOAT="1.2346777892864" INTEGER="12345.123"
+ echo "float=$FLOAT, integer=$INTEGER, PWD=$PWD"
+ -> float=1.2346777892864, integer=12345.123, PWD=/home/xxx
+
+printf "text with variables. float=%.2f, integer=%d, PWD=%s\n" "$FLOAT" "$INTEGER" "$PWD"
+ -> float=1.23, integer=12345, PWD=/home/xxx
Do not use #!/usr/bin/env bash
We stay with /bin/bash shebang, because it's more save from security perspective.
Use of a fixed path to the system provided bash makes it harder for attackers or users to place alternative versions of bash and avoids using a possibly broken, mangled or compromised bash executable.
@@ -370,40 +387,40 @@ It features background tasks and interactive chats, and can serve as an interfac
Can I send messages from CLI and scripts?
Of course, you can send messages from CLI and scripts, simply install bashbot as described here, send the message '/start' to set yourself as botadmin and stop the bot with ./bashbot.sh stop
.
Run the following commands in your bash shell or script while you are in the installation directory:
-# prepare bash / script to send commands
-export BASHBOT_HOME="$(pwd)"
-source ./bashbot.sh source
-
-# send me a test message
-send_message "$(getConfigKey "botadmin")" "test"
-
-# send me output of a system command
-send_message "$(getConfigKey "botadmin")" "$(df -h)"
+# prepare bash / script to send commands
+export BASHBOT_HOME="$(pwd)"
+source ./bashbot.sh source
+
+# send me a test message
+send_message "$(getConfigKey "botadmin")" "test"
+
+# send me output of a system command
+send_message "$(getConfigKey "botadmin")" "$(df -h)"
For more information see Expert Use
Blocked by telegram?
This may happen if to many or wrong requests are sent to api.telegram.org, e.g. using a invalid token or not existing API calls. If the block stay for longer time you can ask telegram service to unblock your IP-Adress.
You can check with curl or wget if you are blocked by Telegram:
-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.
-
-nc -w 2 api.telegram.org 443 || echo "your IP seems blocked by telegram"
-#your IP seems blocked by telegram
+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.
+
+nc -w 2 api.telegram.org 443 || echo "your IP seems blocked by telegram"
+#your IP seems blocked by telegram
Since Version 0.96 bashbot offers the option to recover from broken connections (aka blocked). Therefore you can provide a function named bashbotBlockRecover()
in mycommands.sh
. If the function exists it is called every time when a broken connection is detected.
Possible actions are: Check if network is working, change IP-Adress or simply wait some time.
If everything seems OK return 0 for retry or any non 0 value to give up.
-# called when bashbot sedn command failed because we can not connect to telegram
-# return 0 to retry, return non 0 to give up
-bashbotBlockRecover() {
-# place your commands to unblock here, e.g. change IP-Adess or simply wait
- sleep 60 && return 0 # may be temporary
- return 1
- }
+# called when bashbot sedn command failed because we can not connect to telegram
+# return 0 to retry, return non 0 to give up
+bashbotBlockRecover() {
+# place your commands to unblock here, e.g. change IP-Adess or simply wait
+ sleep 60 && return 0 # may be temporary
+ return 1
+ }
@Gnadelwartz
That's it all guys!
If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
-$$VERSION$$ v1.20-0-g2ab00a2
+$$VERSION$$ v1.21-dev-14-g3f8841b