octoleo
/
telegram-bot-bash
mirror of https://github.com/octoleo/telegram-bot-bash.git
1
1
Fork 0
Code Issues Projects Releases Wiki Activity

doc: remove old stuff

This commit is contained in:
Kay Marquardt (Gnadelwartz) 2020-12-29 10:18:41 +01:00
parent 43f5536dcb
commit 13d15f453c
9 changed files with 252 additions and 371 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
README.html
View File

@ -327,7 +327,7 @@ This 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.</code></pre>
<p>For more Information on how to install, customize and use your new bot, read the <a href="#Documentation">Documentation</a></p>
<h3>Log files</h3>
<p>Since version 0.96 bashbot log commands received/send and connection errors. If you start bashbot in debug mode bash stdout, stderr and all send/received telegram message are logged also.</p>
<p>Bashbot actions are logged in BASHBOT.log, Telegram send/receive errors are logged to ERROR.log. Start bashbot in debug mode to get all messages send to / received from Telegram and error messages of bash commands also.</p>
<p>To enable debug mode start bashbot with debug as third argument: <code>bashbot start debug</code></p>
<pre><code>├── logs
│   ├── BASHBOT.log # log what your bot is doing ...
@ -340,28 +340,10 @@ It features background tasks and interactive chats, and can serve as an interfac
<p>Running a Telegram Bot means it is connected to the public and you never know what's send to your Bot.</p>
<p>Bash scripts in general are not designed to be bullet proof, so consider this Bot as a proof of concept. Bash programmers often struggle with 'quoting hell' and globbing, see <a href="https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells">Implications of wrong quoting</a></p>
<p>Whenever you are processing input from untrusted sources (messages, files, network) you must be as careful as possible, e.g. set IFS appropriate, disable globbing (set -f) and quote everything. In addition delete unused scripts and examples from your Bot, e.g. scripts 'notify', 'calc', 'question', and disable all not used commands.</p>
<p><strong>Note:</strong> Up to version v0.941 (mai/22/2020) telegram-bot-bash had a remote code execution (RCE) bug, please update if you use an older version! see <a href="https://github.com/topkecleon/telegram-bot-bash/issues/125">Issue #125</a></p>
<p>One of the most powerful features of unix shells is variable and command substitution using <code>${}</code> and <code>$()</code>, but as they are expanded in double quotes, this can lead to RCE and information disclosing bugs in complex scripts like bashbot. So it's more secure to escape or remove '$' in input from user, files or network.</p>
<p>A powerful tool to improve your scripts is <code>shellcheck</code>. You can <a href="https://www.shellcheck.net/">use it online</a> or <a href="https://github.com/koalaman/shellcheck#installing">install shellcheck locally</a>. 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 <a href="doc/7_develop.md">test suite</a> to check if important functionality is working as expected.</p>
<h3>Use printf whenever possible</h3>
<p>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. <a href="https://unix.stackexchange.com/a/6581">Use printf whenever possible</a></p>
<div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a> <span class="co"># very simple</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a> <span class="bu">echo</span> <span class="st">&quot;text with variables. PWD=</span><span class="va">$PWD</span><span class="st">&quot;</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a> <span class="bu">printf</span> <span class="st">&#39;%s\n&#39;</span> <span class="st">&quot;text with variables. PWD=</span><span class="va">$PWD</span><span class="st">&quot;</span></span>
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a> <span class="bu">printf</span> <span class="st">&#39;text with variables. PWD=%s\n&#39;</span> <span class="st">&quot;</span><span class="va">$PWD</span><span class="st">&quot;</span></span>
<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a> <span class="ex">-</span><span class="op">&gt;</span> text with variables. PWD=/home/xxx</span>
<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a> <span class="co"># more advanced</span></span>
<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a> <span class="va">FLOAT=</span><span class="st">&quot;1.2346777892864&quot;</span> <span class="va">INTEGER=</span><span class="st">&quot;12345.123&quot;</span></span>
<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a> <span class="bu">echo</span> <span class="st">&quot;float=</span><span class="va">$FLOAT</span><span class="st">, integer=</span><span class="va">$INTEGER</span><span class="st">, PWD=</span><span class="va">$PWD</span><span class="st">&quot;</span></span>
<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a> <span class="ex">-</span><span class="op">&gt;</span> float=1.2346777892864, integer=12345.123, PWD=/home/xxx</span>
<span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb4-12"><a href="#cb4-12" aria-hidden="true" tabindex="-1"></a> <span class="bu">printf</span> <span class="st">&quot;text with variables. float=%.2f, integer=%d, PWD=%s\n&quot;</span> <span class="st">&quot;</span><span class="va">$FLOAT</span><span class="st">&quot;</span> <span class="st">&quot;</span><span class="va">$INTEGER</span><span class="st">&quot;</span> <span class="st">&quot;</span><span class="va">$PWD</span><span class="st">&quot;</span></span>
<span id="cb4-13"><a href="#cb4-13" aria-hidden="true" tabindex="-1"></a> <span class="ex">-</span><span class="op">&gt;</span> float=1.23, integer=12345, PWD=/home/xxx</span></code></pre></div>
<h3>Do not use #!/usr/bin/env bash</h3>
<p><strong>We stay with /bin/bash shebang, because it's more save from security perspective.</strong></p>
<p>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.</p>
<p>If you are a BSD / MacOS user or must to use an other bash location, see <a href="doc/0_install.md">Install Bashbot</a></p>
<h3>Run your Bot as a restricted user</h3>
<p><strong>I recommend to run your bot as a user, with almost no access rights.</strong> All files your Bot have write access to are in danger to be overwritten/deleted if your bot is hacked. For the same reason every file your Bot can read is in danger to be disclosed. Restrict your Bots access rights to the absolute minimum.</p>
<p><strong>Never run your Bot as root, this is the most dangerous you can do!</strong> Usually the user 'nobody' has almost no rights on unix/linux systems. See <a href="doc/4_expert.md">Expert use</a> on how to run your Bot as an other user.</p>
@ -386,41 +368,28 @@ It features background tasks and interactive chats, and can serve as an interfac
<p>Hey no Problem, if you are finished with your cool bot run <code>dev/make-standalone.sh</code> to create a stripped down Version of your bot containing only 'bashbot.sh' and 'commands.sh'! For more information see <a href="doc/7_develop.md">Create a stripped down Version of your Bot</a></p>
<h3>Can I send messages from CLI and scripts?</h3>
<p>Of course, you can send messages from CLI and scripts, simply install bashbot as <a href="#Your-really-first-bashbot-in-a-nutshell">described here</a>, send the message '/start' to set yourself as botadmin and stop the bot with <code>./bashbot.sh stop</code>.</p>
<p>Run the following commands in your bash shell or script while you are in the installation directory:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="co"># prepare bash / script to send commands</span></span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="bu">export</span> <span class="va">BASHBOT_HOME=</span><span class="st">&quot;</span><span class="va">$(</span><span class="bu">pwd</span><span class="va">)</span><span class="st">&quot;</span></span>
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="bu">source</span> ./bashbot.sh source</span>
<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a><span class="co"># send me a test message</span></span>
<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a><span class="ex">send_message</span> <span class="st">&quot;</span><span class="va">$(</span><span class="ex">getConfigKey</span> <span class="st">&quot;botadmin&quot;</span><span class="va">)</span><span class="st">&quot;</span> <span class="st">&quot;test&quot;</span></span>
<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb5-8"><a href="#cb5-8" aria-hidden="true" tabindex="-1"></a><span class="co"># send me output of a system command</span></span>
<span id="cb5-9"><a href="#cb5-9" aria-hidden="true" tabindex="-1"></a><span class="ex">send_message</span> <span class="st">&quot;</span><span class="va">$(</span><span class="ex">getConfigKey</span> <span class="st">&quot;botadmin&quot;</span><span class="va">)</span><span class="st">&quot;</span> <span class="st">&quot;</span><span class="va">$(</span><span class="fu">df</span> <span class="at">-h</span><span class="va">)</span><span class="st">&quot;</span></span></code></pre></div>
<p>For more information see <a href="doc/8_custom.md">Expert Use</a></p>
<p>Bashbot provides some ready to use scripts ro send messages from command line in <code>bin/</code> dir, e.g. <code>send_message.sh</code>.</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/send_message.sh</span> BOTADMIN <span class="st">&quot;This is my first message send from CLI&quot;</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="ex">bin/send_message.sh</span> <span class="at">--help</span></span></code></pre></div>
<p>You can also source bashbot for use in your scripts, for more information see <a href="doc/8_custom.md">Expert Use</a></p>
<h3>Blocked by telegram?</h3>
<p>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.</p>
<p>You can check with curl or wget if you are blocked by Telegram:</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="ex">curl</span> <span class="at">-m</span> 10 https://api.telegram.org/bot</span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="co">#curl: (28) Connection timed out after 10001 milliseconds</span></span>
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a><span class="fu">wget</span> <span class="at">-t</span> 1 <span class="at">-T</span> 10 https://api.telegram.org/bot</span>
<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a><span class="co">#Connecting to api.telegram.org (api.telegram.org)|46.38.243.234|:443... failed: Connection timed out.</span></span>
<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a><span class="ex">nc</span> <span class="at">-w</span> 2 api.telegram.org 443 <span class="kw">||</span> <span class="bu">echo</span> <span class="st">&quot;your IP seems blocked by telegram&quot;</span></span>
<span id="cb6-8"><a href="#cb6-8" aria-hidden="true" tabindex="-1"></a><span class="co">#your IP seems blocked by telegram</span></span></code></pre></div>
<p>Since Version 0.96 bashbot offers the option to recover from broken connections (aka blocked). Therefore you can provide a function named <code>bashbotBlockRecover()</code> in <code>mycommands.sh</code>. If the function exists it is called every time when a broken connection is detected.</p>
<p>Possible actions are: Check if network is working, change IP-Adress or simply wait some time.</p>
<p>If everything seems OK return 0 for retry or any non 0 value to give up.</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="co"># called when bashbot sedn command failed because we can not connect to telegram</span></span>
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="co"># return 0 to retry, return non 0 to give up</span></span>
<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a><span class="fu">bashbotBlockRecover()</span> <span class="kw">{</span></span>
<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a> <span class="co"># place your commands to unblock here, e.g. change IP-Adess or simply wait</span></span>
<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a> <span class="fu">sleep</span> 60 <span class="kw">&amp;&amp;</span> <span class="cf">return</span> <span class="dv">0</span> <span class="co"># may be temporary</span></span>
<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a> <span class="cf">return</span> <span class="dv">1</span> </span>
<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a> <span class="er">}</span></span></code></pre></div>
<div class="sourceCode" id="cb5"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="ex">curl</span> <span class="at">-m</span> 10 https://api.telegram.org/bot</span>
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="co">#curl: (28) Connection timed out after 10001 milliseconds</span></span>
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a><span class="fu">wget</span> <span class="at">-t</span> 1 <span class="at">-T</span> 10 https://api.telegram.org/bot</span>
<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a><span class="co">#Connecting to api.telegram.org (api.telegram.org)|46.38.243.234|:443... failed: Connection timed out.</span></span>
<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a><span class="ex">nc</span> <span class="at">-w</span> 2 api.telegram.org 443 <span class="kw">||</span> <span class="bu">echo</span> <span class="st">&quot;your IP seems blocked by telegram&quot;</span></span>
<span id="cb5-8"><a href="#cb5-8" aria-hidden="true" tabindex="-1"></a><span class="co">#your IP seems blocked by telegram</span></span></code></pre></div>
<p>Bashbot offers the option to recover from broken connections (blocked). Therefore you can provide a function named <code>bashbotBlockRecover()</code> in <code>mycommands.sh</code>, the function is called every time when a broken connection is detected.</p>
<p>Possible actions are: Check if network is working, change IP-Adress or simply wait some time. See <code>mycommnds.sh.dist</code> for an example.</p>
<hr />
<p>@Gnadelwartz</p>
<h2>That's it all guys!</h2>
<p>If you feel that there's something missing or if you found a bug, feel free to submit a pull request!</p>
<h4>$$VERSION$$ v1.21-dev-15-ga1f7215</h4>
<h4>$$VERSION$$ v1.21-dev-28-g43f5536</h4>
</body>
</html>

68
README.md
View File

@ -118,8 +118,8 @@ For more Information on how to install, customize and use your new bot, read the
### Log files
Since version 0.96 bashbot log commands received/send and connection errors. If you start bashbot in debug mode
bash stdout, stderr and all send/received telegram message are logged also.
Bashbot actions are logged in BASHBOT.log, Telegram send/receive errors are logged to ERROR.log.
Start bashbot in debug mode to get all messages send to / received from Telegram and error messages of bash commands also.
To enable debug mode start bashbot with debug as third argument: `bashbot start debug`
@ -141,9 +141,6 @@ Bash scripts in general are not designed to be bullet proof, so consider this Bo
Whenever you are processing input from untrusted sources (messages, files, network) you must be as careful as possible, e.g. set IFS appropriate, disable globbing (set -f) and quote everything. In addition delete unused scripts and examples from your Bot, e.g. scripts 'notify', 'calc', 'question', and disable all not used commands.
**Note:** Up to version v0.941 (mai/22/2020) telegram-bot-bash had a remote code execution (RCE) bug, please update if you use an older version!
see [Issue #125](https://github.com/topkecleon/telegram-bot-bash/issues/125)
One of the most powerful features of unix shells is variable and command substitution using ```${}``` and ```$()```,
but as they are expanded in double quotes, this can lead to RCE and information disclosing bugs in complex scripts like bashbot.
So it's more secure to escape or remove '$' in input from user, files or network.
@ -156,31 +153,6 @@ In addition bashbot has a [test suite](doc/7_develop.md) to check if important f
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](https://unix.stackexchange.com/a/6581)
```bash
# 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.
If you are a BSD / MacOS user or must to use an other bash location, see [Install Bashbot](doc/0_install.md)
### Run your Bot as a restricted user
**I recommend to run your bot as a user, with almost no access rights.**
All files your Bot have write access to are in danger to be overwritten/deleted if your bot is hacked.
@ -220,20 +192,15 @@ Hey no Problem, if you are finished with your cool bot run ```dev/make-standalon
Of course, you can send messages from CLI and scripts, simply install bashbot as [described here](#Your-really-first-bashbot-in-a-nutshell),
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:
Bashbot provides some ready to use scripts ro send messages from command line in `bin/` dir, e.g. `send_message.sh`.
```bash
# prepare bash / script to send commands
export BASHBOT_HOME="$(pwd)"
source ./bashbot.sh source
bin/send_message.sh BOTADMIN "This is my first message send from CLI"
# send me a test message
send_message "$(getConfigKey "botadmin")" "test"
# send me output of a system command
send_message "$(getConfigKey "botadmin")" "$(df -h)"
bin/send_message.sh --help
```
For more information see [Expert Use](doc/8_custom.md)
You can also source bashbot for use in your scripts, for more information see [Expert Use](doc/8_custom.md)
### Blocked by telegram?
@ -252,24 +219,13 @@ 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.
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.
Possible actions are: Check if network is working, change IP-Adress or simply wait some time.
See `mycommnds.sh.dist` for an example.
If everything seems OK return 0 for retry or any non 0 value to give up.
```bash
# 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
@ -277,4 +233,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.21-dev-15-ga1f7215
#### $$VERSION$$ v1.21-dev-28-g43f5536

84
README.txt
View File

@ -143,9 +143,10 @@ the [Documentation](#Documentation)
### Log files
Since version 0.96 bashbot log commands received/send and connection errors. If
you start bashbot in debug mode
bash stdout, stderr and all send/received telegram message are logged also.
Bashbot actions are logged in BASHBOT.log, Telegram send/receive errors are
logged to ERROR.log.
Start bashbot in debug mode to get all messages send to / received from
Telegram and error messages of bash commands also.
To enable debug mode start bashbot with debug as third argument: `bashbot start
debug`
@ -178,10 +179,6 @@ globbing (set -f) and quote everything. In addition delete unused scripts and
examples from your Bot, e.g. scripts 'notify', 'calc', 'question', and disable
all not used commands.
**Note:** Up to version v0.941 (mai/22/2020) telegram-bot-bash had a remote
code execution (RCE) bug, please update if you use an older version!
see [Issue #125](https://github.com/topkecleon/telegram-bot-bash/issues/125)
One of the most powerful features of unix shells is variable and command
substitution using ```${}``` and ```$()```,
but as they are expanded in double quotes, this can lead to RCE and information
@ -204,35 +201,6 @@ arguments or file system...),
you shouldn't use echo to display it. [Use printf whenever
possible](https://unix.stackexchange.com/a/6581)
```bash
# 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.
If you are a BSD / MacOS user or must to use an other bash location, see
[Install Bashbot](doc/0_install.md)
### Run your Bot as a restricted user
**I recommend to run your bot as a user, with almost no access rights.**
All files your Bot have write access to are in danger to be overwritten/deleted
@ -297,21 +265,17 @@ as [described here](#Your-really-first-bashbot-in-a-nutshell),
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:
Bashbot provides some ready to use scripts ro send messages from command line
in `bin/` dir, e.g. `send_message.sh`.
```bash
# prepare bash / script to send commands
export BASHBOT_HOME="$(pwd)"
source ./bashbot.sh source
bin/send_message.sh BOTADMIN "This is my first message send from CLI"
# send me a test message
send_message "$(getConfigKey "botadmin")" "test"
# send me output of a system command
send_message "$(getConfigKey "botadmin")" "$(df -h)"
bin/send_message.sh --help
```
For more information see [Expert Use](doc/8_custom.md)
You can also source bashbot for use in your scripts, for more information see
[Expert Use](doc/8_custom.md)
### Blocked by telegram?
@ -333,28 +297,16 @@ 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.
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.
Possible actions are: Check if network is working, change IP-Adress or simply
wait some time.
See `mycommnds.sh.dist` for an example.
If everything seems OK return 0 for retry or any non 0 value to give up.
```bash
# 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
@ -363,4 +315,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.21-dev-15-ga1f7215
#### $$VERSION$$ v1.21-dev-28-g43f5536

201
doc/2_usage.md
View File

@ -1,14 +1,15 @@
#### [Home](../README.md)
## Getting Started
The Bots standard commands are in the commands dispatcher ```commands.sh```, Do not edit this file! Add your commands and functions to ```mycommands.sh```. In 'mycommands.sh.dist' you find examples how to add own commands and overwrite existing ones. See [Best practices](5_practice.md) for more information.
The Bots default commands are in `commands.sh`. Do not edit this file! Instead copy `mycommands.sh.clean` to `mycommands.sh` and place you commands there.
Have a look at `mycommands.sh.dist` for examples on how to write commands or overwrite existing ones. See [Best practices](5_practice.md) for more information.
Once you're done with editing start the Bot with ```./bashbot.sh start```. To stop the Bot run ```./bashbot.sh stop```
Once you're done with editing run the Bot with `./bashbot.sh start`. To stop running the Bot use `./bashbot.sh stop`
If something doesn't work as expected, debug with ```./bashbot.sh startbot DEBUG &```, where DEBUG can be 'debug', 'xdebug' or 'xdebugx'.
If something doesn't work as expected, debug with `./bashbot.sh startbot DEBUG &`, where DEBUG can be 'debug', 'xdebug' or 'xdebugx'.
See [Bashbot Development](7_develop.md) for more information.
To use the functions provided in this script in other scripts simply source bashbot: ```source bashbot.sh source```. see [Expert Use](8_expert.md#Expert-use)
To use the functions provided in this script in other scripts simply source bashbot: `source bashbot.sh source`. see [Expert Use](8_expert.md#Expert-use)
Have FUN!
@ -143,60 +144,60 @@ Evertime a Message is received, you can read incoming data using the following v
These Variables are always present in regular messages:
* ```${MESSAGE}```: Current message text
* ```${MESSAGE[ID]}```: ID of current message
* ```$USER```: This array contains the First name, last name, username and user id of the sender of the current message.
* ```${USER[ID]}```: User id
* ```${USER[FIRST_NAME]}```: User's first name
* ```${USER[LAST_NAME]}```: User's last name
* ```${USER[USERNAME]}```: Username
* ```$CHAT```: This array contains the First name, last name, username, title and user id of the chat of the current message.
* ```${CHAT[ID]}```: Chat id
* ```${CHAT[FIRST_NAME]}```: Chat's first name
* ```${CHAT[LAST_NAME]}```: Chat's last name
* ```${CHAT[USERNAME]}```: Username
* ```${CHAT[TITLE]}```: Title
* ```${CHAT[TYPE]}```: Type
* ```${CHAT[ALL_MEMBERS_ARE_ADMINISTRATORS]}```: All members are administrators (true if true)
* `${MESSAGE}`: Current message text
* `${MESSAGE[ID]}`: ID of current message
* `$USER`: This array contains the First name, last name, username and user id of the sender of the current message.
* `${USER[ID]}`: User id
* `${USER[FIRST_NAME]}`: User's first name
* `${USER[LAST_NAME]}`: User's last name
* `${USER[USERNAME]}`: Username
* `$CHAT`: This array contains the First name, last name, username, title and user id of the chat of the current message.
* `${CHAT[ID]}`: Chat id
* `${CHAT[FIRST_NAME]}`: Chat's first name
* `${CHAT[LAST_NAME]}`: Chat's last name
* `${CHAT[USERNAME]}`: Username
* `${CHAT[TITLE]}`: Title
* `${CHAT[TYPE]}`: Type
* `${CHAT[ALL_MEMBERS_ARE_ADMINISTRATORS]}`: All members are administrators (true if true)
The following variables are set if the message contains optional parts:
* ```$REPLYTO```: Original message which was replied to
* ```$REPLYTO```: This array contains the First name, last name, username and user id of the ORIGINAL sender of the message REPLIED to.
* ```${REPLYTO[ID]}```: ID of message which was replied to
* ```${REPLYTO[UID]}```: Original user's id
* ```${REPLYTO[FIRST_NAME]}```: Original user's first name
* ```${REPLYTO[LAST_NAME]}```: Original user's' last name
* ```${REPLYTO[USERNAME]}```: Original user's username
* ```$FORWARD```: This array contains the First name, last name, username and user id of the ORIGINAL sender of the FORWARDED message.
* ```${FORWARD[ID]}```: Same as MESSAGE[ID] if message is forwarded
* ```${FORWARD[UID]}```: Original user's id
* ```${FORWARD[FIRST_NAME]}```: Original user's first name
* ```${FORWARD[LAST_NAME]}```: Original user's' last name
* ```${FORWARD[USERNAME]}```: Original user's username
* ```$CAPTION```: Picture, Audio, Video, File Captions
* ```$URLS```: This array contains documents, audio files, voice recordings and stickers as URL.
* ```${URLS[AUDIO]}```: Audio files
* ```${URLS[VIDEO]}```: Videos
* ```${URLS[PHOTO]}```: Photos (maximum quality)
* ```${URLS[VOICE]}```: Voice recordings
* ```${URLS[STICKER]}```: Stickers
* ```${URLS[DOCUMENT]}```: Any other file
* ```$CONTACT```: This array contains info about contacts sent in a chat.
* ```${CONTACT[ID]}```: User id
* ```${CONTACT[NUMBER]}```: Phone number
* ```${CONTACT[FIRST_NAME]}```: First name
* ```${CONTACT[LAST_NAME]}```: Last name
* ```${CONTACT[VCARD]}```: User's complete Vcard
* ```$LOCATION```: This array contains info about locations sent in a chat.
* ```${LOCATION[LONGITUDE]}```: Longitude
* ```${LOCATION[LATITUDE]}```: Latitude
* ```$VENUE```: This array contains info about venue (a place) sent in a chat.
* ```${VENUE[TITLE]}```: Name of the place
* ```${VENUE[ADDRESS]}```: Address of the place
* ```${VENUE[LONGITUDE]}```: Longitude
* ```${VENUE[LATITUDE]}```: Latitude
* ```${VENUE[FOURSQUARE]}```: Fouresquare ID
* `$REPLYTO`: Original message which was replied to
* `$REPLYTO`: This array contains the First name, last name, username and user id of the ORIGINAL sender of the message REPLIED to.
* `${REPLYTO[ID]}`: ID of message which was replied to
* `${REPLYTO[UID]}`: Original user's id
* `${REPLYTO[FIRST_NAME]}`: Original user's first name
* `${REPLYTO[LAST_NAME]}`: Original user's' last name
* `${REPLYTO[USERNAME]}`: Original user's username
* `$FORWARD`: This array contains the First name, last name, username and user id of the ORIGINAL sender of the FORWARDED message.
* `${FORWARD[ID]}`: Same as MESSAGE[ID] if message is forwarded
* `${FORWARD[UID]}`: Original user's id
* `${FORWARD[FIRST_NAME]}`: Original user's first name
* `${FORWARD[LAST_NAME]}`: Original user's' last name
* `${FORWARD[USERNAME]}`: Original user's username
* `$CAPTION`: Picture, Audio, Video, File Captions
* `$URLS`: This array contains documents, audio files, voice recordings and stickers as URL.
* `${URLS[AUDIO]}`: Audio files
* `${URLS[VIDEO]}`: Videos
* `${URLS[PHOTO]}`: Photos (maximum quality)
* `${URLS[VOICE]}`: Voice recordings
* `${URLS[STICKER]}`: Stickers
* `${URLS[DOCUMENT]}`: Any other file
* `$CONTACT`: This array contains info about contacts sent in a chat.
* `${CONTACT[ID]}`: User id
* `${CONTACT[NUMBER]}`: Phone number
* `${CONTACT[FIRST_NAME]}`: First name
* `${CONTACT[LAST_NAME]}`: Last name
* `${CONTACT[VCARD]}`: User's complete Vcard
* `$LOCATION`: This array contains info about locations sent in a chat.
* `${LOCATION[LONGITUDE]}`: Longitude
* `${LOCATION[LATITUDE]}`: Latitude
* `$VENUE`: This array contains info about venue (a place) sent in a chat.
* `${VENUE[TITLE]}`: Name of the place
* `${VENUE[ADDRESS]}`: Address of the place
* `${VENUE[LONGITUDE]}`: Longitude
* `${VENUE[LATITUDE]}`: Latitude
* `${VENUE[FOURSQUARE]}`: Fouresquare ID
### Service Messages
@ -207,34 +208,34 @@ client, e.g. new users.
If a service message is received bashbot sets MESSAGE to the service message type as a command,
e.g. if a new user joins a chat MESSAGE is set to "/_new_chat_user".
* ```$SERVICE```: This array contains info about received service messages.
* ```${SERVICE}```: "yes" if service message is received
* ```${SERVICE[NEWMEMBER]}}```: New user's id
* ```${MESSAGE}```: /_new_chat_member ID NAME
* ```${NEWMEMBER[ID]}```: New user's id
* ```${NEWMEMBER[FIRST_NAME]}```: New user's first name
* ```${NEWMEMBER[LAST_NAME]}```: New user's last name
* ```${NEWMEMBER[USERNAME]}```: New user's username
* ```${NEWMEMBER[ISBOT]}```: New user is a bot
* ```${SERVICE[LEFTMEMBER]}```: Id of user left
* ```${MESSAGE}```: /_left_chat_member ID NAME
* ```${LEFTMEMBER[ID]}```: Left user's id
* ```${LEFTMEMBER[FIRST_NAME]}```: Left user's first name
* ```${LEFTMEMBER[LAST_NAME]}```: Left user's last name
* ```${LEFTMEMBER[USERNAME]}```: Left user's username
* ```${LEFTMEMBER[ISBOT]}```: Left user is a bot
* ```${SERVICE[NEWTITLE]}```: Text of new title
* ```${MESSAGE}```: /_new_chat_title SENDER TEXT
* ```${SERVICE[NEWPHOTO]}```: New Chat Picture
* ```${MESSAGE}```: /_new_chat_picture SENDER URL
* ```${SERVICE[PINNED]}```: Pinned MESSAGE ID
* ```${MESSAGE}```: /_new_pinned_message SENDER ID
* ```${PINNED[ID]}```: Id of pinned message
* ```${PINNED[MESSAGE]}```: Message text of pinned message
* ```${SERVICE[MIGRATE]}```: Old and new group id
* ```${MESSAGE}```: /_migrate_group MIGRATE_FROM MIGRATE_TO
* ```${MIGRATE[FROM]}```: Old group id
* ```${MIGRATE[TO]}```: New group id
* `$SERVICE`: This array contains info about received service messages.
* `${SERVICE}`: "yes" if service message is received
* `${SERVICE[NEWMEMBER]}}`: New user's id
* `${MESSAGE}`: /_new_chat_member ID NAME
* `${NEWMEMBER[ID]}`: New user's id
* `${NEWMEMBER[FIRST_NAME]}`: New user's first name
* `${NEWMEMBER[LAST_NAME]}`: New user's last name
* `${NEWMEMBER[USERNAME]}`: New user's username
* `${NEWMEMBER[ISBOT]}`: New user is a bot
* `${SERVICE[LEFTMEMBER]}`: Id of user left
* `${MESSAGE}`: /_left_chat_member ID NAME
* `${LEFTMEMBER[ID]}`: Left user's id
* `${LEFTMEMBER[FIRST_NAME]}`: Left user's first name
* `${LEFTMEMBER[LAST_NAME]}`: Left user's last name
* `${LEFTMEMBER[USERNAME]}`: Left user's username
* `${LEFTMEMBER[ISBOT]}`: Left user is a bot
* `${SERVICE[NEWTITLE]}`: Text of new title
* `${MESSAGE}`: /_new_chat_title SENDER TEXT
* `${SERVICE[NEWPHOTO]}`: New Chat Picture
* `${MESSAGE}`: /_new_chat_picture SENDER URL
* `${SERVICE[PINNED]}`: Pinned MESSAGE ID
* `${MESSAGE}`: /_new_pinned_message SENDER ID
* `${PINNED[ID]}`: Id of pinned message
* `${PINNED[MESSAGE]}`: Message text of pinned message
* `${SERVICE[MIGRATE]}`: Old and new group id
* `${MESSAGE}`: /_migrate_group MIGRATE_FROM MIGRATE_TO
* `${MIGRATE[FROM]}`: Old group id
* `${MIGRATE[TO]}`: New group id
@ -243,12 +244,12 @@ e.g. if a new user joins a chat MESSAGE is set to "/_new_chat_user".
Inline query messages are small, non regular messages used for interaction with the user,
they contain the following variables only:
* ```${iQUERY}```: Current inline query
* ```$iQUERY```: This array contains the ID, First name, last name, username and user id of the sender of the current inline query.
* ```${iQUERY[ID]}```: Inline query ID
* ```${iQUERY[USER_ID]}```: User's id
* ```${iQUERY[FIRST_NAME]}```: User's first name
* ```${iQUERY[LAST_NAME]}```: User's last name
* `${iQUERY}`: Current inline query
* `$iQUERY`: This array contains the ID, First name, last name, username and user id of the sender of the current inline query.
* `${iQUERY[ID]}`: Inline query ID
* `${iQUERY[USER_ID]}`: User's id
* `${iQUERY[FIRST_NAME]}`: User's first name
* `${iQUERY[LAST_NAME]}`: User's last name
### Send Message Results
@ -256,15 +257,15 @@ they contain the following variables only:
BOTSENT is set on every send_xxx action and only valid until next send action. For more on message results see.
[Advanced Usage](3_advanced.md)
* ```$BOTSENT```: This array contains the parsed results from the last transmission to telegram.
* ```${BOTSENT[OK]}```: contains the string ```true```: after a successful transmission
* ```${BOTSENT[ID]}```: Message ID of sent message, image, file etc., if OK is true
* `$BOTSENT`: This array contains the parsed results from the last transmission to telegram.
* `${BOTSENT[OK]}`: contains the string `true`: after a successful transmission
* `${BOTSENT[ID]}`: Message ID of sent message, image, file etc., if OK is true
## Usage of bashbot functions
#### sending messages
To send messages use the ```send_xxx_message``` functions.
To send messages use the `send_xxx_message`functions.
To insert line brakes in a message place `\n` in the text.
To send regular text without any markdown use:
@ -280,7 +281,7 @@ To send text with html:
send_html_message "${CHAT[ID]}" "lol <b>bold</b>"
```
To forward messages use the ```forward``` function:
To forward messages use the `forward`function:
```bash
forward "${CHAT[ID]}" "from_chat_id" "message_id"
```
@ -313,24 +314,24 @@ send_message "${CHAT[ID]}" "lol" "safe"
#### Send files, locations, keyboards.
To send images, videos, voice files, photos etc. use the ```send_photo``` function (remember to change the safety Regex @ line 14 of command.sh to allow sending files only from certain directories):
To send images, videos, voice files, photos etc. use the `send_photo`function (remember to change the safety Regex @ line 14 of command.sh to allow sending files only from certain directories):
```bash
send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool"
```
To send custom keyboards use the ```send_keyboard``` function:
To send custom keyboards use the `send_keyboard`function:
```bash
send_keyboard "${CHAT[ID]}" "Text that will appear in chat?" '[ "Yep" , "No" ]' # note the single quotes!
send_keyboard "${CHAT[ID]}" "Text that will appear in chat?" "[ \\"Yep\\" , \\"No\\" ]" # within double quotes you must escape the inside double quots
```
To send locations use the ```send_location``` function:
To send locations use the `send_location`function:
```bash
send_location "${CHAT[ID]}" "Latitude" "Longitude"
```
To send venues use the ```send_venue``` function:
To send venues use the `send_venue`function:
```bash
send_venue "${CHAT[ID]}" "Latitude" "Longitude" "Title" "Address" "optional foursquare id"
```
To send a chat action use the ```send_action``` function.
To send a chat action use the `send_action`function.
Allowed values: typing for text messages, upload_photo for photos, record_video or upload_video for videos, record_audio or upload_audio for audio files, upload_document for general files, find_location for locations.
```bash
send_action "${CHAT[ID]}" "action"
@ -340,5 +341,5 @@ send_action "${CHAT[ID]}" "action"
#### [Prev Create Bot](1_firstbot.md)
#### [Next Advanced Usage](3_advanced.md)
#### $$VERSION$$ v1.20-0-g2ab00a2
#### $$VERSION$$ v1.21-dev-28-g43f5536

36
doc/3_advanced.md
View File

@ -2,7 +2,7 @@
## Advanced Features
### Access control
Bashbot offers functions to check what Telegram capabilities like 'chat admin' or 'chat creator' the given user has:
Bashbot offers functions to check what Telegram capabilities like `chat admin` or `chat creator` the given user has:
```bash
# return true if user is admin/owner of the bot
@ -21,7 +21,7 @@ user_is_admin "${CHAT[ID]}" "${USER[ID]}" && send_markdown_message "${CHAT[ID]}"
```
In addition you can check individual capabilities of users as you must define in the file ```./botacl```:
In addition you can check individual capabilities of users as you must define in the file `./botacl`:
```bash
# file: botacl
@ -54,7 +54,7 @@ ALL:*:*
```
You must use the function ```user_is_allowed``` to check if a user has the capability to do something. Example: Check if user has capability to start bot.
You must use the function `user_is_allowed`to check if a user has the capability to do something. Example: Check if user has capability to start bot.
```bash
case "$MESSAGE" in
@ -143,8 +143,8 @@ echo "Text that will appear in one message mynewlinestartshere with this text
echo "Other text message\nwith a newline" # \n instead of mynewlinestartshere
```
New in v0.7: In case you must extend a message already containing a location, a file, a keyboard etc.,
with additionial text simply add ``` mytextstartshere additional text``` at the end of the string:
In case you want extend a message already containing a location, a file, a keyboard etc.,
with an additionial text simply add ` mytextstartshere additional text`at the end of the string:
```bash
out="Text that will appear mylatstartshere 45 mylongstartshere 45"
[[ "$out" != *'in chat'* ]] && out="$out mytextstartshere in chat."
@ -183,14 +183,14 @@ If you want to kill all background jobs permanently run:
./bashbot.sh killback
```
Note: Background jobs run independent from main bot and continue running until your script exits or you stop it. Background jobs will continue running if your Bot is stopped and must be terminated separately e.g. by ```bashbot.sh killback```
Note: Background jobs run independent from main bot and continue running until your script exits or you stop it. Background jobs will continue running if your Bot is stopped and must be terminated separately e.g. by `bashbot.sh killback`
### Inline queries
**Inline queries** allow users to send commands to your bot from every chat without going to a private chat. An inline query is started if the user type the bots name, e.g. @myBot. Everything after @myBot is immediately send to the bot.
In order to enable **inline mode**, send `/setinline` command to [@BotFather](https://telegram.me/botfather) and provide the placeholder text that the user will see in the input field after typing your bot’s name.
The following commands allows you to send ansers to *inline queries*. To enable bashbot to process inline queries set ```INLINE="1"``` in 'mycommands.sh'.
The following commands allows you to send ansers to *inline queries*. To enable bashbot to process inline queries set `INLINE="1"`in 'mycommands.sh'.
To send messages or links through an *inline query*:
```bash
@ -246,19 +246,19 @@ is received.
**Note**: the values of the variables contains always the result of the LAST transmission to telegram,
every send action will overwrite them!
* ```$BOTSENT```: This array contains the parsed results from the last transmission to telegram.
* ```${BOTSENT[OK]}```: contains the string ```true```: after a successful transmission
* ```${BOTSENT[ID]}```: Message ID if OK is true
* ```${BOTSENT[ERROR]}```: Error code if an error occurred
* ```${BOTSENT[DESC]}```: Description text for error
* ```${BOTSENT[RETRY]}```: Seconds to wait if telegram requests throtteling.
* ```$res```: temporary variable containing the full transmission result, may be overwritten by any bashbot function.
* `$BOTSENT`: This array contains the parsed results from the last transmission to telegram.
* `${BOTSENT[OK]}`: contains the string `true`: after a successful transmission
* `${BOTSENT[ID]}`: Message ID if OK is true
* `${BOTSENT[ERROR]}`: Error code if an error occurred
* `${BOTSENT[DESC]}`: Description text for error
* `${BOTSENT[RETRY]}`: Seconds to wait if telegram requests throtteling.
* `$res`: temporary variable containing the full transmission result, may be overwritten by any bashbot function.
By default you don't have to care about retry, as bashbot resend the message after the requested time automatically.
Only if the retry fails also an error is returned. The downside is that send_message functions will wait until resend is done.
If you want to disable automatic error processing and handle all errors manually (or don't care)
set ```BASHBOT_RETRY``` to any no zero value.
set `BASHBOT_RETRY`to any no zero value.
[Telegram Bot API error codes](https://github.com/TelegramBotAPI/errors)
@ -266,9 +266,9 @@ set ```BASHBOT_RETRY``` to any no zero value.
#### Detect bot blocked
If the we can't connect to telegram, e.g. blocked from telegram server but also any other reason,
bashbot set ```BOTSENT[ERROR]``` to ```999```.
bashbot set `BOTSENT[ERROR]`to `999`.
To get a notification on every connection problem create a function named ```bashbotBlockRecover``` and handle blocks there.
To get a notification on every connection problem create a function named `bashbotBlockRecover`and handle blocks there.
If the function returns true (0 or no value) bashbot will retry once and then return to the calling function.
In case you return any non 0 value bashbot will return to the calling function without retry.
@ -302,5 +302,5 @@ Note: If you disable automatic retry, se above, you disable also connection prob
#### [Prev Getting started](2_usage.md)
#### [Next Expert Use](4_expert.md)
#### $$VERSION$$ v1.21-dev-19-gb5e4f53
#### $$VERSION$$ v1.21-dev-28-g43f5536

42
doc/4_expert.md
View File

@ -5,17 +5,17 @@
UTF-8 is a variable length encoding of Unicode. UTF-8 is recommended as the default encoding in JSON, XML and HTML, also Telegram make use of it.
The first 128 characters are regular ASCII, so it's a superset of and compatible with ASCII environments. The next 1,920 characters need
two bytes for encoding and covers almost all ```Latin``` alphabets, also ```Greek```, ```Cyrillic```,
```Hebrew```, ```Arabic``` and more. See [Wikipedia](https://en.wikipedia.org/wiki/UTF-8) for more details.
two bytes for encoding and covers almost all `Latin` alphabets, also `Greek```, `Cyrillic```,
```Hebrew```, `Arabic` and more. See [Wikipedia](https://en.wikipedia.org/wiki/UTF-8) for more details.
#### Setting up your Environment
In general ```bash``` and ```GNU``` utitities are UTF-8 aware if you to setup your environment
In general `bash` and `GNU` utitities are UTF-8 aware if you to setup your environment
and your scripts accordingly:
1. Your Terminal and Editor must support UTF-8:
Set Terminal and Editor locale to UTF-8, eg. in ```Settings/Configuration``` select UTF-8 (Unicode) as Charset.
Set Terminal and Editor locale to UTF-8, eg. in `Settings/Configuration` select UTF-8 (Unicode) as Charset.
2. Set ```Shell``` environment to UTF-8 in your ```.profile``` and your scripts. The usual settings are:
2. Set `Shell` environment to UTF-8 in your `.profile` and your scripts. The usual settings are:
```bash
export 'LC_ALL=C.UTF-8'
@ -35,15 +35,15 @@ export 'LANGUAGE=den_US.UTF-8'
```
3. make sure your bot scripts use the correct settings, eg. include the lines above at the beginning of your scripts
To display all available locales on your system run ```locale -a | more```. [Gentoo Wiki](https://wiki.gentoo.org/wiki/UTF-8)
To display all available locales on your system run `locale -a | more`. [Gentoo Wiki](https://wiki.gentoo.org/wiki/UTF-8)
#### Bashbot UTF-8 Support
Bashbot handles all messages transparently, regardless of the charset in use. The only exception is when converting from JSON data to strings.
Telegram use JSON to send / receive data. JSON encodes strings as follow: Characters not ASCII *(>127)* are escaped as sequences of ```\uxxxx``` to be regular ASCII. In addition multibyte characters, *e.g. Emoticons or Arabic characters*, are send in double byte UTF-16 notation.
The Emoticons ``` 😁 😘 ❤️ 😊 👍 ``` are encoded as: ``` \uD83D\uDE01 \uD83D\uDE18 \u2764\uFE0F \uD83D\uDE0A \uD83D\uDC4D ```
Telegram use JSON to send / receive data. JSON encodes strings as follow: Characters not ASCII *(>127)* are escaped as sequences of `\uxxxx` to be regular ASCII. In addition multibyte characters, *e.g. Emoticons or Arabic characters*, are send in double byte UTF-16 notation.
The Emoticons ` 😁 😘 ❤️ 😊 👍 ` are encoded as: ` \uD83D\uDE01 \uD83D\uDE18 \u2764\uFE0F \uD83D\uDE0A \uD83D\uDC4D `
**This "mixed" JSON encoding needs special handling and can not decoded from** ```echo -e``` or ```printf '%s\\n'```
**This "mixed" JSON encoding needs special handling and can not decoded from** `echo -e` or `printf '%s\\n'`
Bbashbot uses an internal, pure bash implementation which is well tested now, even there may some corner cases*.
@ -56,7 +56,7 @@ Setup the environment for the user you want to run bashbot and enter desired use
sudo ./bashbot.sh init
```
Edit the file ```bashbot.rc``` and change the following lines to fit your configuration:
Edit the file `bashbot.rc` and change the following lines to fit your configuration:
```bash
#######################
# Configuration Section
@ -79,7 +79,7 @@ From now on use 'bashbot.rc' to manage your bot:
```bash
sudo ./bashbot.rc start
```
Type ```ps -ef | grep bashbot``` to verify your Bot is running as the desired user.
Type `ps -ef | grep bashbot` to verify your Bot is running as the desired user.
If your Bot is started by 'bashbot.rc', you must use 'bashbot.rc' also to manage your Bot! The following commands are available:
```bash
@ -90,15 +90,15 @@ sudo ./bashbot.rc suspendback
sudo ./bashbot.rc resumeback
sudo ./bashbot.rc killback
```
To change back the environment to your user-ID run ```sudo ./bashbot.sh init``` again and enter your user name.
To change back the environment to your user-ID run `sudo ./bashbot.sh init` again and enter your user name.
To use bashbot as a system service include a working ```bashbot.rc``` in your init system (systemd, /etc/init.d).
To use bashbot as a system service include a working `bashbot.rc` in your init system (systemd, /etc/init.d).
### Schedule bashbot from Cron
An example crontab is provided in ```examples/bashbot.cron```.
An example crontab is provided in `examples/bashbot.cron`.
- If you are running bashbot with your user-ID, copy the examples lines to your crontab and remove username ```nobody```.
- if you run bashbot as an other user or a system service edit ```examples/bashbot.cron``` to fit your needs and replace username```nobody``` with the username you want to run bashbot. copy the modified file to ```/etc/cron.d/bashbot```
- If you are running bashbot with your user-ID, copy the examples lines to your crontab and remove username `nobody`.
- if you run bashbot as an other user or a system service edit `examples/bashbot.cron` to fit your needs and replace username `nobody` with the username you want to run bashbot. copy the modified file to `/etc/cron.d/bashbot`
### Use bashbot from CLI and scripts
@ -169,7 +169,7 @@ echo $COMMANDS $MODULEDIR $BOTACL $TMPDIR $COUNTFILE
/usr/local/telegram-bot-bash/botacl /usr/local/telegram-bot-bash/data-bot-bash
/usr/local/telegram-bot-bash/count
```
`
After sourcing you can use bashbot functions to send Messages, Locations, Pictures etc. to any Telegram
User or Chat you are in. See [Send Messages](2_usage.md#sending-messages).
@ -209,7 +209,7 @@ If you want to have other locations for config, data etc, define and export the
**Note: all specified directories and files must exist or running 'bashbot.sh' will fail.**
##### BASHBOT_ETC
Location of the files ```commands.sh```, ```mycommands.sh```, ```botconfig.jssh```, ```botacl``` ...
Location of the files `commands.sh```, `mycommands.sh```, `botconfig.jssh```, `botacl` ...
```bash
unset BASHBOT_ETC # keep in telegram-bot-bash (default)
export BASHBOT_ETC "" # keep in telegram-bot-bash
@ -223,7 +223,7 @@ Location of the files ```commands.sh```, ```mycommands.sh```, ```botconfig.jssh`
e.g. /etc/bashbot
##### BASHBOT_VAR
Location of runtime data ```data-bot-bash```, ```count.jssh```
Location of runtime data `data-bot-bash```, `count.jssh`
```bash
unset BASHBOT_VAR # keep in telegram-bot-bash (default)
export BASHBOT_VAR "" # keep in telegram-bot-bash
@ -296,7 +296,7 @@ set BASHBOT_CURL to point to it.
```
##### BASHBOT_WGET
Bashbot uses ```curl``` to communicate with telegram server. if ```curl``` is not available ```wget``` is used.
Bashbot uses `curl` to communicate with telegram server. if `curl` is not available `wget` is used.
If 'BASHBOT_WGET' is set to any value (not undefined or not empty) wget is used even is curl is available.
```bash
unset BASHBOT_WGET # use curl (default)
@ -378,5 +378,5 @@ for every poll until the maximum of BASHBOT_SLEEP ms.
#### [Prev Advanced Use](3_advanced.md)
#### [Next Best Practice](5_practice.md)
#### $$VERSION$$ v1.20-0-g2ab00a2
#### $$VERSION$$ v1.21-dev-28-g43f5536

20
doc/5_practice.md
View File

@ -10,9 +10,9 @@ In addition you should know about [BotFather, the one bot to rule them all](http
If you don't have a github account, it may time to [setup a free account now](https://github.com/pricing)
### Add commands to mycommands.sh only
Do not change ```bashbot.sh``` and ```commands.sh```, instead place your commands in to ```mycommands.sh```.
To start with a clean/minimal bot copy ```mycommands.sh.clean``` to ```mycommands.sh``` and start editing
the message strings and place commands in the```case ... esac``` block of the function mycommands():
Do not change `bashbot.sh` and `commands.sh```, instead place your commands in to `mycommands.sh```.
To start with a clean/minimal bot copy `mycommands.sh.clean` to `mycommands.sh` and start editing
the message strings and place commands in the```case ... esac` block of the function mycommands():
```bash
# file: mycommands.sh
# your additional bashbot commands
@ -39,13 +39,13 @@ mycommands() {
### DIsable, replace and extend global commands
Global bashbot command processing, e.g. /start, /info etc. is disabled if you return a non zero value from ```mycommands.sh```,
Global bashbot command processing, e.g. /start, /info etc. is disabled if you return a non zero value from `mycommands.sh```,
see /start example below.
To replace a global bashbot command add the same command to ```mycommands.sh``` and place ```return 1``` at the end of
To replace a global bashbot command add the same command to `mycommands.sh` and place `return 1` at the end of
the case block, see /kickme example below.
If a command is available as a global command and in ```mycommands.sh```, plus you return a zero value (nothing or 0)
If a command is available as a global command and in `mycommands.sh```, plus you return a zero value (nothing or 0)
both command sections are processed. Thus you can extend global commands with additional actions, see /info example below
**Learn more about [Bot commands](https://core.telegram.org/bots#commands).**
@ -75,7 +75,7 @@ both command sections are processed. Thus you can extend global commands with ad
### Separate logic from commands
If a command need more than 2-3 lines of code, you should use a function to separate logic from command. Place your functions in ```mycommands.sh``` and call the from your command. Example:
If a command need more than 2-3 lines of code, you should use a function to separate logic from command. Place your functions in `mycommands.sh` and call the from your command. Example:
```bash
# file: mycommands.sh
# your additional bashbot commands
@ -133,7 +133,9 @@ Line 17:
^-- SC2116: Useless echo? Instead of 'cmd $(echo foo)', just use 'cmd foo'.
```
As you can see my ```mybotcommands.inc.sh``` contains an useless echo command in 'TEXT=' assignment and can be replaced by ```TEXT="${TEXT}${WORD}"```
As you can see my `mybotcommands.inc.sh` contains an useless echo command in 'TEXT=' assignment and can be replaced by `TEXT="${TEXT}${WORD}"`
```bash
$ shellcheck -x examples/notify
OK
@ -158,5 +160,5 @@ The second warning is about an unused variable, this is true because in our exam
#### [Prev Best Practice](5_practice.md)
#### [Next Functions Reference](6_reference.md)
#### $$VERSION$$ v1.20-0-g2ab00a2
#### $$VERSION$$ v1.21-dev-28-g43f5536

30
doc/6_reference.md
View File

@ -6,11 +6,11 @@
To insert line brakes in a message or caption you can place `\n` in the text.
##### send_action
```send_action``` shows users what your bot is currently doing.
`send_action` shows users what your bot is currently doing.
*usage:* send_action "${CHAT[ID]}" "action"
*"action":* ```typing```, ```upload_photo```, ```record_video```, ```upload_video```, ```record_audio```, ```upload_audio```, ```upload_document```, ```find_location```.
*"action":* `typing`, `upload_photo`, `record_video`, `upload_video`, `record_audio`, `upload_audio`, `upload_document`, `find_location`.
*alias:* _action "action"
@ -21,7 +21,7 @@ send_action "${CHAT[ID]}" "record_audio"
```
##### send_normal_message
```send_normal_message``` sends text only messages to the given chat.
`send_normal_message` sends text only messages to the given chat.
*usage:* send_normal_message "${CHAT[ID]}" "message"
@ -34,7 +34,7 @@ send_normal_message "${CHAT[ID]}" "this is a text message"
##### send_markdownv2_message
```send_markdownv2_message``` sends markdown v2 style messages to the given chat.
`send_markdownv2_message` sends markdown v2 style messages to the given chat.
Telegram supports a new [Markdown V2 Style](https://core.telegram.org/bots/api#markdownv2-style) which
has more formatting codes and is more robust, but incompatible with old telegram markdown style.
@ -48,7 +48,7 @@ send_markdownv2_message "${CHAT[ID]}" "*bold* __underlined__ [text](link)"
##### send_markdown_message
```send_markdown_message``` sends markdown style messages to the given chat.
`send_markdown_message` sends markdown style messages to the given chat.
This is the old, legacy Telegram markdown style, retained for backward compatibility.
It supports a [reduced set of Markdown](https://core.telegram.org/bots/api#markdown-style) only
@ -64,7 +64,7 @@ send_markdown_message "${CHAT[ID]}" "*bold* _italic_ [text](link)"
##### send_html_message
```send_html_message``` sends HTML style messages to the given chat.
`send_html_message` sends HTML style messages to the given chat.
Telegram supports a [reduced set of HTML](https://core.telegram.org/bots/api#html-style) only
*usage:* send_html_message "${CHAT[ID]}" "html message"
@ -78,7 +78,7 @@ send_normal_message "${CHAT[ID]}" "<b>bold</b> <i>italic><i> <em>italic>/em> <a
```
##### forward_message
```forward_mesage``` forwards a message to the given chat.
`forward_mesage` forwards a message to the given chat.
*usage:* forward_message "chat_to" "chat_from" "${MESSAGE[ID]}"
@ -100,7 +100,7 @@ See also [deleteMessage limitations](https://core.telegram.org/bots/api#deleteme
----
##### send_message
```send_message``` sends any type of message to the given chat. Type of output is steered by keywords within the message.
`send_message` sends any type of message to the given chat. Type of output is steered by keywords within the message.
The main use case for send_message is to process the output of interactive chats and background jobs. **For regular Bot commands I recommend using of the dedicated send_xxx_message() functions from above.**
@ -214,7 +214,7 @@ specify URL buttons, no Text Buttons and the Buttons must be an Array of Buttons
The inline buttons must be specified as a JSON string in the following format:
```[ {"text":"text1", "url":"url1"}, ... {"text":"textN", "url":"urlN"} ]```
`[ {"text":"text1", "url":"url1"}, ... {"text":"textN", "url":"urlN"} ]```
Each button consists of a pair of text and URL values, sourrounded by '{ }', multiple buttons are separated by '**,**' and everything is wrapped in '[ ]'.
@ -245,7 +245,7 @@ To replace a message you must know the message id of the the original message. T
`BOTSENT[ID]` after sending the original message.
##### edit_normal_message
```edit_normal_message``` replace a message with a text message in the given chat.
`edit_normal_message` replace a message with a text message in the given chat.
*usage:* edit_normal_message "${CHAT[ID]}" "MESSAGE-ID" "message"
@ -258,7 +258,7 @@ edit_normal_message "${CHAT[ID]}" "${saved-id}" "this is another text"
```
##### edit_markdownv2_message
```edit_markdownv2_message``` replace a message with a markdown v2 message in the given chat.
`edit_markdownv2_message` replace a message with a markdown v2 message in the given chat.
*usage:* edit_markdownv2_message "${CHAT[ID]}" "MESSAGE-ID" "message"
@ -271,7 +271,7 @@ edit_markdownv2_message "${CHAT[ID]}" "${saved-id}" "this is __markdown__ *V2* t
```
##### edit_markdown_message
```edit_markdown_message``` replace a message with a markdown message in the given chat.
`edit_markdown_message` replace a message with a markdown message in the given chat.
*usage:* edit_markdown_message "${CHAT[ID]}" "MESSAGE-ID" "message"
@ -284,7 +284,7 @@ edit_markdown_message "${CHAT[ID]}" "${saved-id}" "this is *markdown* text"
```
##### edit_html_message
```edit_html_message``` replace a message with a html message in the given chat.
`edit_html_message` replace a message with a html message in the given chat.
*usage:* edit_html_message "${CHAT[ID]}" "MESSAGE-ID" "message"
@ -475,7 +475,7 @@ Background functions and interactive jobs extends the bot functionality to not o
chats and send messages based on time or other external events.
##### start_proc
```startproc``` starts a script, the output of the script is sent to the user or chat, user input will be sent back to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats)
`startproc` starts a script, the output of the script is sent to the user or chat, user input will be sent back to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats)
*usage:* start_proc "${CHAT[ID]}" "script"
@ -1155,5 +1155,5 @@ The name of your bot is available as bash variable "$ME", there is no need to ca
#### [Prev Best Practice](5_practice.md)
#### [Next Notes for Developers](7_develop.md)
#### $$VERSION$$ v1.21-dev-17-g8c9298d
#### $$VERSION$$ v1.21-dev-28-g43f5536

75
doc/7_develop.md
View File

@ -7,7 +7,7 @@ If you want to provide fixes or new features [fork bashbot on github](https://he
### Debugging Bashbot
Usually all bashbot output is discarded.
If you want to get error messages (and more) start bashbot ```./bashbot.sh startbot debug```.
If you want to get error messages (and more) start bashbot `./bashbot.sh startbot debug`.
you can the change the level of verbosity of the debug argument:
```
@ -29,18 +29,18 @@ Logging of telegram update poll is disabled by default, also in `debug` mode. To
set `BASHBOT_UPDATELOG` to an empty value (not unset) `export BASHBOT_UPDATELOG=""`
### Modules and Addons
**Modules** resides in ```modules/*.sh``` and are colletions of optional bashbot functions grouped by functionality. Main reason for creating modules was
**Modules** resides in `modules/*.sh` and are colletions of optional bashbot functions grouped by functionality. Main reason for creating modules was
to keep 'bashbot.sh' small, while extending functionality. In addition not every function is needed by all bots, so you can
disable modules, e.g. by rename the respective module file to 'module.sh.off'.
Modules must use only functions provided by 'bashbot.sh' or the module itself and should not depend on other modules or addons.
The only mandatory module is 'module/sendMessage.sh'.
If a not mandatory module is used in 'bashbot.sh' or 'commands.sh', the use of ```_is_function``` or
```_execute_if_function``` is mandatory to catch absence of the module.
If a not mandatory module is used in 'bashbot.sh' or 'commands.sh', the use of `_is_function` or
`_execute_if_function` is mandatory to catch absence of the module.
**Addons** resides in ```addons/*.sh.dist``` and are not enabled by default. To activate an addon rename it to end with '.sh', e.g. by
```cp addons/example.sh.dist addons/example.sh```.
**Addons** resides in `addons/*.sh.dist` and are not enabled by default. To activate an addon rename it to end with '.sh', e.g. by
`cp addons/example.sh.dist addons/example.sh`.
Addons must register themself to BASHBOT_EVENTS at startup, e.g. to call a function every time a message is received.
Addons works similar as 'commands.sh' and 'mycommands.sh' but are much more flexible on when functions/commands are triggered.
@ -65,16 +65,16 @@ Note: For the same reason event function MUST return immediately! Time consuming
An RECEIVE event is executed when a Message is received, same iQuery / Message variables are available as in commands.sh
* BASHBOT_EVENT_INLINE an inline query is received
* `BASHBOT_EVENT_INLINE` an inline query is received
* BASHBOT_EVENT_MESSAGE any of the following message types is received
* BASHBOT_EVENT_TEXT a message containing text is received
* BASHBOT_EVENT_CMD a message containing a command is received (starts with /)
* BASHBOT_EVENT_REPLYTO a reply to a message is received
* BASHBOT_EVENT_FORWARD a forwarded message is received
* BASHBOT_EVENT_CONTACT a contact is received
* BASHBOT_EVENT_LOCATION a location or a venue is received
* BASHBOT_EVENT_FILE a file is received
* BASHBOT_EVENT_MESSAGE` any of the following message types is received
* `BASHBOT_EVENT_TEXT` a message containing text is received
* `BASHBOT_EVENT_CMD` a message containing a command is received (starts with /)
* `BASHBOT_EVENT_REPLYTO` a reply to a message is received
* `BASHBOT_EVENT_FORWARD` a forwarded message is received
* `BASHBOT_EVENT_CONTACT` a contact is received
* `BASHBOT_EVENT_LOCATION` a location or a venue is received
* `BASHBOT_EVENT_FILE` a file is received
*usage*: BASHBOT_EVENT_xxx[ "unique-name" ]="callback"
@ -84,6 +84,7 @@ An RECEIVE event is executed when a Message is received, same iQuery / Message v
and "unique-name" is the name provided when registering the event.
*Example:* Register a function to echo to any Text sent to the bot
```bash
# register callback:
BASHBOT_EVENT_TEXT["example_1"]="example_echo"
@ -102,7 +103,7 @@ example_echo() {
An SEND event is executed when a Message is send to telegram.
* BASHBOT_EVENT_SEND is executed if data is send or uploaded to Telegram server
* `BASHBOT_EVENT_SEND` is executed if data is send or uploaded to Telegram server
In contrast to other events, BASHBOT_EVENT_SEND is executed in a sub shell, so there is no need to spawn
a background process for longer running commands and changes to variables are not persistent!
@ -132,13 +133,13 @@ example_log(){
Important: Bashbot timer tick is disabled by default and must be enabled by setting BASHBOT_START_TIMER to any value not zero.
* BASHBOT_EVENT_TIMER executed every minute and can be used in 3 variants: oneshot, once a minute, every X minutes.
* `BASHBOT_EVENT_TIMER` is executed every minute and can be used in 3 variants: oneshot, once a minute, every X minutes.
Registering to BASHBOT_EVENT_TIMER works similar as for message events, but you must add a timing argument to the name.
EVENT_TIMER is triggered every 60s and waits until the current running command is finished, so it's not exactly every
minute, but once a minute.
Every time EVENT_TIMER is triggered the variable "EVENT_TIMER" is increased. each callback is executed if ```EVENT_TIMER % time``` is '0' (true).
Every time EVENT_TIMER is triggered the variable "EVENT_TIMER" is increased. each callback is executed if `EVENT_TIMER % time` is '0' (true).
This means if you register an every 5 minutes callback first execution may < 5 Minutes, all subsequent executions are once every 5. Minute.
*usage:* BASHBOT_EVENT_TIMER[ "name" , "time" ], where time is:
@ -148,7 +149,7 @@ This means if you register an every 5 minutes callback first execution may < 5 M
* x execute every x minutes
* -x execute once WITHIN the next x Minutes (next 10 Minutes since start "event")
Note: If you want exact "in x minutes" use "EVENT_TIMER plus x" as time: ```-(EVENT_TIMER + x)```
Note: If you want exact "in x minutes" use "EVENT_TIMER plus x" as time: `-(EVENT_TIMER + x)`
*Example:*
```bash
@ -185,7 +186,7 @@ Let's create a stripped down version:
- delete not needed commands and functions from `mycommands.sh`
- run `dev/make-standalone.sh` to create a a stripped down version of your bot
Now have a look at the directory 'standalone', here you find the files 'bashbot.sh' and 'commands.sh' containing everything to run your bot.
Now have a look at the directory `standalone`, here you find the files `bashbot.sh` and `commands.sh` containing everything to run your bot.
[Download make-standalone.sh](https://github.com/topkecleon/telegram-bot-bash/blob/master/dev/make-standalone.sh) from github.
### Setup your develop environment
@ -206,10 +207,10 @@ sudo apt-get -t buster-backports install git shellcheck pandoc codespell curl
A typical bashbot develop loop looks as follow:
1. start developing - *change, copy, edit bashbot files ...*
2. after changing a bash sript: ```shellcheck -x script.sh```
3. ```dev/all-tests.sh``` - *in case if errors back to 2.*
4. ```dev/git-add.sh``` - *check for changed files, update version string, run git add*
5. ```git commit -m "COMMIT MESSAGE"; git push```
2. after changing a bash sript: `shellcheck -x script.sh`
3. `dev/all-tests.sh` - *in case if errors back to 2.*
4. `dev/git-add.sh` - *check for changed files, update version string, run git add*
5. `git commit -m "COMMIT MESSAGE"; git push`
**If you setup your dev environment with hooks and use the scripts above, versioning, adding and testing is done automatically.**
@ -263,23 +264,23 @@ For more examples see [Pure bash bible](https://github.com/dylanaraps/pure-bash-
#### Prepare a new version
After some development it may time to create a new version for the users. a new version can be in sub version upgrade, e.g. for fixes and smaller additions or
a new release version for new features. To mark a new version use ```git tag NEWVERSION``` and run ```dev/version.sh``` to update all version strings.
a new release version for new features. To mark a new version use `git tag NEWVERSION` and run `dev/version.sh` to update all version strings.
Usually I start with pre versions and when everything looks good I push out a release candidate (rc) and finally the new version.
```
v0.x-devx -> v0.x-prex -> v0.x-rc -> v0.x ... 0.x+1-dev ...
```
If you release a new Version run ```dev/make-distribution.sh``` to create the zip and tar.gz archives in the dist directory and attach them to the github release. Do not forget to delete directory dist afterwards.
If you release a new Version run `dev/make-distribution.sh` to create the zip and tar.gz archives in the dist directory and attach them to the github release. Do not forget to delete directory dist afterwards.
#### Versioning
Bashbot is tagged with version numbers. If you start a new development cycle you can tag your fork with a version higher than the current version.
E.g. if you fork 'v0.60' the next develop version should tagged as ```git tag "v0.61-dev"``` for fixes or ```git tag "v0.70-dev"``` for new features.
E.g. if you fork 'v0.60' the next develop version should tagged as `git tag "v0.61-dev"` for fixes or `git tag "v0.70-dev"` for new features.
To get the current version name of your develepment fork run ```git describe --tags```. The output looks like ```v0.70-dev-6-g3fb7796``` where your version tag is followed by the number of commits since you tag your branch and followed by the latest commit hash. see also [comments in version.sh](../dev/version.sh)
To get the current version name of your develepment fork run `git describe --tags`. The output looks like `v0.70-dev-6-g3fb7796` where your version tag is followed by the number of commits since you tag your branch and followed by the latest commit hash. see also [comments in version.sh](../dev/version.sh)
To update the Version Number in files run ```dev/version.sh files```, it will update the line '#### $$VERSION$$ ###' in all files to the current version name.
To update the Version Number in files run `dev/version.sh files`, it will update the line '#### $$VERSION$$ ###' in all files to the current version name.
To update version in all files run 'dev/version.sh' without parameter.
@ -287,27 +288,27 @@ To update version in all files run 'dev/version.sh' without parameter.
For a shell script running as a service it's important to be paranoid about quoting, globbing and other common problems. So it's a must to run shellchek on all shell scripts before you commit a change. this is automated by a git hook activated in Setup step 6.
To run shellcheck for a single script run ```shellcheck -x script.sh```, to check all schripts run ```dev/hooks/pre-commit.sh```.
To run shellcheck for a single script run `shellcheck -x script.sh`, to check all schripts run `dev/hooks/pre-commit.sh`.
### bashbot test suite
Starting with version 0.70 bashbot has a test suite. To start testsuite run ```dev/all-tests.sh```. all-tests.sh will return 'SUCCESS' only if all tests pass.
Starting with version 0.70 bashbot has a test suite. To start testsuite run `dev/all-tests.sh`. all-tests.sh will return 'SUCCESS' only if all tests pass.
#### enabling / disabling tests
All tests are placed in the directory ```test```. To disable a test remove the execute flag from the '*-test.sh' script, to (re)enable a test make the script executable again.
All tests are placed in the directory `test`. To disable a test remove the execute flag from the '*-test.sh' script, to (re)enable a test make the script executable again.
#### creating new tests
To create a new test run ```test/ADD-test-new.sh``` and answer the questions, it will create the usually needed files and dirs:
To create a new test run `test/ADD-test-new.sh` and answer the questions, it will create the usually needed files and dirs:
Each test consists of a script script named after ```p-name-test.sh``` *(where p is test pass 'a-z' and name the name
of your test)* and an optional dir ```p-name-test/``` *(script name minus '.sh')* for additional files.
Each test consists of a script script named after `p-name-test.sh` *(where p is test pass 'a-z' and name the name
of your test)* and an optional dir `p-name-test/` *(script name minus '.sh')* for additional files.
Tests with no dependency to other tests will run in pass 'a', tests which need an initialized bashbot environment must run in pass 'd' or later.
A temporary test environment is created when 'ALL-tests.sh' starts and deleted after all tests are finished.
The file ```ALL-tests.inc.sh``` must be included from all tests and provide the test environment as shell variables:
The file `ALL-tests.inc.sh` must be included from all tests and provide the test environment as shell variables:
```bash
# Test Environment
TESTME="$(basename "$0")"
@ -354,5 +355,5 @@ fi
#### [Prev Function Reference](6_reference.md)
#### $$VERSION$$ v1.21-dev-17-g8c9298d
#### $$VERSION$$ v1.21-dev-28-g43f5536