From a1f7215aa476984bbc2d5668deb23f5d3d0afd76 Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Sun, 27 Dec 2020 16:22:38 +0100 Subject: [PATCH] update bashbot in a nutshell --- README.html | 111 ++++++++++++++++++++++++++++++---------------------- README.md | 46 +++++++++++++--------- README.txt | 68 +++++++++++++++++--------------- 3 files changed, 127 insertions(+), 98 deletions(-) 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).
  • Examples Dir

    • Your really first bashbot in a nutshell

    -

    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
    
 
 
diff --git a/README.md b/README.md
index 2adfa68..10eef2f 100644
--- a/README.md
+++ b/README.md
@@ -67,31 +67,39 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
 
 ### Your really first bashbot in a nutshell
 
-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 :-(
+To install and run bashbot you need access to a linux/unix command line with bash, a [Telegram client](https://telegram.org) and a mobile phone [with a Telegram account](https://telegramguide.com/create-a-telegram-account/).
 
-In addition you need a [Telegram client](https://telegram.org) and a mobile phone to [register an account](https://telegramguide.com/create-a-telegram-account/).
-If you don't want to register for Telegram you should stop reading here ;-)
+First you need to [create a new Telegram Bot token](doc/1_firstbot.md) for your bot and write it down.
 
-After you're registered to Telegram send a message to [@botfather](https://telegram.me/botfather),
-[create a new Telegram Bot token](doc/1_firstbot.md) and write it down. You need the token to install the bot.
+Now open a linux/unix terminal with bash, create a new directory, change to it and install telegram-bot-bash:
 
-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](https://github.com/topkecleon/telegram-bot-bash/releases). This can be done with the commands:
 ```bash
-wget -q https://github.com/$(wget -q https://github.com/topkecleon/telegram-bot-bash/releases/latest -O - | egrep '/.*/.*/.*tar.gz' -o)
+# 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 \ 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.
 ```
 
-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 \ key.
+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:'_):
 
-That's all, now you can start your bot with ```./bashbot.sh start``` and send him messages:
 ```
 /start
 
@@ -269,4 +277,4 @@ bashbotBlockRecover() {
 
 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
diff --git a/README.txt b/README.txt
index b0c3382..2acd5d3 100644
--- a/README.txt
+++ b/README.txt
@@ -81,44 +81,48 @@ available on www.github.com
 
 ### Your really first bashbot in a nutshell
 
-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 :-(
+To install and run bashbot you need access to a linux/unix command line with 
+bash, a [Telegram client](https://telegram.org) and a mobile phone [with a 
+Telegram account](https://telegramguide.com/create-a-telegram-account/).
 
-In addition you need a [Telegram client](https://telegram.org) and a mobile 
-phone to [register an 
-account](https://telegramguide.com/create-a-telegram-account/).
-If you don't want to register for Telegram you should stop reading here ;-)
+First you need to [create a new Telegram Bot token](doc/1_firstbot.md) for your 
+bot and write it down.
 
-After you're registered to Telegram send a message to 
-[@botfather](https://telegram.me/botfather),
-[create a new Telegram Bot token](doc/1_firstbot.md) and write it down. You 
-need the token to install the bot.
+Now open a linux/unix terminal with bash, create a new directory, change to it 
+and install telegram-bot-bash:
 
-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](https://github.com/to
-pkecleon/telegram-bot-bash/releases). This can be done with the commands:
 ```bash
-wget -q https://github.com/$(wget -q 
-https://github.com/topkecleon/telegram-bot-bash/releases/latest -O - | egrep 
-'/.*/.*/.*tar.gz' -o)
+# 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 \ 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.
 ```
 
-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 \ key.
+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:'_):
 
-That's all, now you can start your bot with ```./bashbot.sh start``` and send 
-him messages:
 ```
 /start
 
@@ -359,4 +363,4 @@ wait
 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