From 656389182f069520c0670b109a4d07cfb7f0720c Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Sun, 14 Jun 2020 13:50:44 +0200 Subject: [PATCH] doc log files --- README.html | 64 +++++++++++++++++++++++++++++--------------------- README.md | 18 +++++++++++++- README.txt | 21 ++++++++++++++++- doc/2_usage.md | 4 ++-- 4 files changed, 76 insertions(+), 31 deletions(-) diff --git a/README.html b/README.html index 502abca..1afdc83 100644 --- a/README.html +++ b/README.html @@ -175,6 +175,16 @@ his is bashbot, the Telegram bot written entirely in bash. 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

+

Log files

+

Since version 0.96 bashbot log commands recieved (updates) and connection errors. If you start bashbot in debug mode bash stdout, stderr and all recieved telegram message updates are logged also.

+

To enable debug mode start bashbot with debug as third argument: bashbot start debug

+
├── logs 
+│   ├── ERROR.log        # connection errors from / to telegram API
+│   ├── UPDATE.log       # summary whats received from your bot
+│   │
+│   ├── DEBUG.log        # stdout/stderr of you bot (debug mode enabled)
+│   └── MESSAGE.log      # full text of all message updates received (debug mode enabled)
+

Security Considerations

Running a Telegram Bot means it is connected to the public and you never know whats send to your Bot.

@@ -184,18 +194,18 @@ 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 extensive in bashbot development to enshure 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 names from the 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"
-  -> text with variables. PWD=/home/xxx
-
-  # more advanced
-  FLOAT="1.2346777892864" INTEGER="12345.123"
-  echo "text with variabeles. float=$FLOAT, integer=$INTEGER, PWD=$PWD"
-  ->text with variables. float=1.2346777892864, integer=12345.123, PWD=/home/xxx
-
-  printf "text with variables. float=%.2f, integer=%d, PWD=%s\n" "" "$INTEGER" "$PWD"
-  ->text with variables. float=1.23, integer=12345, PWD=/home/xxx
+
  # very simple
+  echo "text with variables. PWD=$PWD"
+  printf '%s\n' "text with variables. PWD=$PWD"
+  -> text with variables. PWD=/home/xxx
+
+  # more advanced
+  FLOAT="1.2346777892864" INTEGER="12345.123"
+  echo "text with variabeles. float=$FLOAT, integer=$INTEGER, PWD=$PWD"
+  ->text with variables. float=1.2346777892864, integer=12345.123, PWD=/home/xxx
+
+  printf "text with variables. float=%.2f, integer=%d, PWD=%s\n" "" "$INTEGER" "$PWD"
+  ->text with variables. 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.

Using 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.

@@ -225,27 +235,27 @@ 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 messsage '/start' to set yourself as botadmin and stop the bot with ./bashbot.sh kill.

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 "$(cat "$BOTADMIN")" "test"
-
-# send me output of a system command
-send_message "$(<"$BOTADMIN")" "$(df -h)"
+
# prepare bash / script to send commands
+export BASHBOT_HOME="$(pwd)"
+source ./bashbot.sh source
+
+# send me a test message
+send_message "$(cat "$BOTADMIN")" "test"
+
+# send me output of a system command
+send_message "$(<"$BOTADMIN")" "$(df -h)"

For more information see Expert Use

Why do I get "EXPECTED value GOT EOF" on start?

May be your IP is blocked by telegram. You can test this by running curl or wget manually:

-
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.
+
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.

This may happen if to many wrong requests are sent to api.telegram.org, e.g. using a wrong token or not existing API calls. If you have a fixed IP you can ask telegram service to unblock your ip or change your IP. If you are running a socks or tor proxy on your server look for the BASHBOT_CURL_ARGS lines in 'mycommands.sh' as example.

@Gnadelwartz

That's it!

If you feel that there's something missing or if you found a bug, feel free to submit a pull request!

-

$$VERSION$$ v0.96-0-g3871ca9

+

$$VERSION$$ v0.98-dev-10-g74caa49

diff --git a/README.md b/README.md index 207d974..2ba8736 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,22 @@ It features background tasks and interactive chats, and can serve as an interfac ``` For more Information on how to install, customize and use your new bot, read the [Documentation](#Documentation) +### Log files + +Since version 0.96 bashbot log commands recieved (updates) and connection errors. If you start bashbot in debug mode +bash stdout, stderr and all recieved telegram message updates are logged also. + +To enable debug mode start bashbot with debug as third argument: `bashbot start debug` + +``` +├── logs +│   ├── ERROR.log # connection errors from / to telegram API +│   ├── UPDATE.log # summary whats received from your bot +│   │ +│   ├── DEBUG.log # stdout/stderr of you bot (debug mode enabled) +│   └── MESSAGE.log # full text of all message updates received (debug mode enabled) +``` + ---- ## Security Considerations @@ -219,4 +235,4 @@ This may happen if to many wrong requests are sent to api.telegram.org, e.g. usi If you feel that there's something missing or if you found a bug, feel free to submit a pull request! -#### $$VERSION$$ v0.96-0-g3871ca9 +#### $$VERSION$$ v0.98-dev-10-g74caa49 diff --git a/README.txt b/README.txt index b5f2360..0ac45cc 100644 --- a/README.txt +++ b/README.txt @@ -131,6 +131,25 @@ interface for CLI programs. For more Information on how to install, customize and use your new bot, read the [Documentation](#Documentation) +### Log files + +Since version 0.96 bashbot log commands recieved (updates) and connection +errors. If you start bashbot in debug mode +bash stdout, stderr and all recieved telegram message updates are logged also. + +To enable debug mode start bashbot with debug as third argument: `bashbot start +debug` + +``` +├── logs +│   ├── ERROR.log # connection errors from / to telegram API +│   ├── UPDATE.log # summary whats received from your bot +│   │ +│   ├── DEBUG.log # stdout/stderr of you bot (debug mode enabled) +│   └── MESSAGE.log # full text of all message updates received (debug +mode enabled) +``` + ---- ## Security Considerations @@ -305,4 +324,4 @@ in 'mycommands.sh' as example. If you feel that there's something missing or if you found a bug, feel free to submit a pull request! -#### $$VERSION$$ v0.96-0-g3871ca9 +#### $$VERSION$$ v0.98-dev-10-g74caa49 diff --git a/doc/2_usage.md b/doc/2_usage.md index 0bba689..e8fdb9d 100644 --- a/doc/2_usage.md +++ b/doc/2_usage.md @@ -32,7 +32,7 @@ Have FUN! ├── scripts # place your bashbot interactive and background scripts here │   └── interactive.sh.clean # interactive script template for new scripts │ -├── logs # here you'll find ERROR, DEBUG and MESSAGE.log +├── logs # here you'll find ERROR, UPDSTE, DEBUG and MESSAGE.log │ ├── modules # optional functions, sourced by commands.sh │   ├── aliases.sh # to disable modules rename them xxx.sh.off @@ -261,5 +261,5 @@ send_action "${CHAT[ID]}" "action" #### [Prev Create Bot](1_firstbot.md) #### [Next Advanced Usage](3_advanced.md) -#### $$VERSION$$ v0.98-dev-7-gca05095 +#### $$VERSION$$ v0.98-dev-10-g74caa49