doc: remove old stuff part 2
This commit is contained in:
Kay Marquardt (Gnadelwartz)
parent
13d15f453c
commit
cf6f3eedd7
22
README.md
22
README.md
|
|
@ -118,7 +118,7 @@ For more Information on how to install, customize and use your new bot, read the
|
|||
|
||||
### Log files
|
||||
|
||||
Bashbot actions are logged in BASHBOT.log, Telegram send/receive errors are logged to ERROR.log.
|
||||
Bashbot actions are logged to `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,11 +141,11 @@ 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.
|
||||
|
||||
One of the most powerful features of unix shells is variable and command substitution using ```${}``` and ```$()```,
|
||||
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.
|
||||
|
||||
A powerful tool to improve your scripts is ```shellcheck```. You can [use it online](https://www.shellcheck.net/) or [install shellcheck locally](https://github.com/koalaman/shellcheck#installing). 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.
|
||||
A powerful tool to improve your scripts is`shellcheck`. You can [use it online](https://www.shellcheck.net/) or [install shellcheck locally](https://github.com/koalaman/shellcheck#installing). 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](doc/7_develop.md) to check if important functionality is working as expected.
|
||||
|
||||
### Use printf whenever possible
|
||||
|
|
@ -163,9 +163,9 @@ For the same reason every file your Bot can read is in danger to be disclosed. R
|
|||
### Secure your Bot installation
|
||||
**Your Bot configuration must no be readable from other users.** Everyone who can read your Bots token is able to act as your Bot and has access to all chats the Bot is in!
|
||||
|
||||
Everyone with read access to your Bot files can extract your Bots data. Especially your Bot config in ```config.jssh``` must be protected against other users. No one except you should have write access to the Bot files. The Bot should be restricted to have write access to ```count.jssh``` and ```data-bot-bash``` only, all other files must be write protected.
|
||||
Everyone with read access to your Bot files can extract your Bots data. Especially your Bot config in`config.jssh` must be protected against other users. No one except you should have write access to the Bot files. The Bot should be restricted to have write access to`count.jssh` and `data-bot-bash` only, all other files must be write protected.
|
||||
|
||||
To set access rights for your bashbot installation to a reasonable default run ```sudo ./bashbot.sh init``` after every update or change to your installation directory.
|
||||
To set access rights for your bashbot installation to a reasonable default run`sudo ./bashbot.sh init` after every update or change to your installation directory.
|
||||
|
||||
## FAQ
|
||||
|
||||
|
|
@ -183,16 +183,16 @@ Well, that's a damn good question ... may be because I'm an unix admin from ston
|
|||
- no database, not event driven, not object oriented ...
|
||||
|
||||
### Can I have the single bashbot.sh file back?
|
||||
At the beginning bashbot was simply the file ```bashbot.sh``` you can copy everywhere and run the bot. Now we have 'commands.sh', 'mycommands.sh', 'modules/*.sh' and much more.
|
||||
At the beginning bashbot was simply the file`bashbot.sh` you can copy everywhere and run the bot. Now we have 'commands.sh', 'mycommands.sh', 'modules/*.sh' and much more.
|
||||
|
||||
Hey no Problem, if you are finished with your cool bot run ```dev/make-standalone.sh``` to create a stripped down Version of your bot containing only
|
||||
Hey no Problem, if you are finished with your cool bot run`dev/make-standalone.sh` to create a stripped down Version of your bot containing only
|
||||
'bashbot.sh' and 'commands.sh'! For more information see [Create a stripped down Version of your Bot](doc/7_develop.md)
|
||||
|
||||
### Can I send messages from CLI and scripts?
|
||||
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```.
|
||||
Of course, you can send messages from command line 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 then stop the bot with `./bashbot.sh stop`.
|
||||
|
||||
Bashbot provides some ready to use scripts ro send messages from command line in `bin/` dir, e.g. `send_message.sh`.
|
||||
Bashbot provides some ready to use scripts for sending messages from command line in `bin/` dir, e.g. `send_message.sh`.
|
||||
|
||||
```bash
|
||||
bin/send_message.sh BOTADMIN "This is my first message send from CLI"
|
||||
|
|
@ -233,4 +233,4 @@ See `mycommnds.sh.dist` for an example.
|
|||
|
||||
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-28-g43f5536
|
||||
#### $$VERSION$$ v1.21-dev-29-g13d15f4
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -74,8 +74,8 @@ You must use the function `user_is_allowed`to check if a user has the capability
|
|||
### Interactive Chats
|
||||
Interactive chats are short running scripts, reading user input and echo data to the user.
|
||||
|
||||
To create a new interactive chat script copy 'scripts/interactive.sh.clean' to e.g. 'scripts/mynewinteractive.sh', make it executable
|
||||
and then use 'start_proc' function from your bot, it's possible to pass two arguments. You find more examples for interactive scripts in 'examples'
|
||||
To create a new interactive chat script copy `scripts/interactive.sh.clean` to e.g. `scripts/mynewinteractive.sh`, make it executable
|
||||
and then use `start_proc` function from your bot, it's possible to pass two arguments. You find more examples for interactive scripts in 'examples'
|
||||
|
||||
*usage*: start_proc chat_id script arg1 arg2
|
||||
|
||||
|
|
@ -83,7 +83,7 @@ and then use 'start_proc' function from your bot, it's possible to pass two argu
|
|||
|
||||
*usage*: check_prog chat_id
|
||||
|
||||
**Note:** From Version 0.96 on scripts must read user input from '$3' instead of stdin!
|
||||
**IMPORTANT:** Scripts must read user input from '$3' instead of stdin!
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
|
@ -105,8 +105,8 @@ echo -e "Your Message: ${test}\nbye!"
|
|||
|
||||
#### message formatting and keyboards
|
||||
|
||||
The output of the script will be processed by 'send_messages', so you can not only send text, but also keyboards, files, locations and more.
|
||||
Each newline in the output will start an new message to the user. To have line breaks in your message you must insert ' mynewlinestartshere ' or '\n' instead.
|
||||
The output of the script will be processed by `send_messages`, so you can not only send text, but also keyboards, files, locations and more.
|
||||
Each newline in the output will start an new message to the user. To have line breaks in your message you must insert `\n` instead.
|
||||
|
||||
To open up a keyboard in an interactive script, print out the keyboard layout in the following way:
|
||||
```bash
|
||||
|
|
@ -137,10 +137,9 @@ echo "Text that will appear in chat? mykeyboardstartshere [ \"Yep, sure\" , \"No
|
|||
```
|
||||
Please note that you can either send a location or a venue, not both. To send a venue add the mytitlestartshere and the myaddressstartshere keywords.
|
||||
|
||||
To insert a line break in your message you can insert ` mynewlinestartshere ` or `\n` in your echo command:
|
||||
To insert a line break in your message you can insert `\n` in your echo command:
|
||||
```bash
|
||||
echo "Text that will appear in one message mynewlinestartshere with this text on a new line"
|
||||
echo "Other text message\nwith a newline" # \n instead of mynewlinestartshere
|
||||
echo "Text that will appear in one message \nwith this text on a new line"
|
||||
```
|
||||
|
||||
In case you want extend a message already containing a location, a file, a keyboard etc.,
|
||||
|
|
@ -302,5 +301,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-28-g43f5536
|
||||
#### $$VERSION$$ v1.21-dev-29-g13d15f4
|
||||
|
||||
|
|
|
|||
|
|
@ -5,8 +5,8 @@
|
|||
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
|
||||
|
|
@ -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```, `b
|
|||
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
|
||||
|
|
@ -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.21-dev-28-g43f5536
|
||||
#### $$VERSION$$ v1.21-dev-29-g13d15f4
|
||||
|
||||
|
|
|
|||
|
|
@ -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```.
|
||||
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():
|
||||
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
|
||||
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).**
|
||||
|
|
@ -160,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.21-dev-28-g43f5536
|
||||
#### $$VERSION$$ v1.21-dev-29-g13d15f4
|
||||
|
||||
|
|
|
|||
|
|
@ -325,13 +325,13 @@ Your Bot will leave the chat.
|
|||
*alias:* _leave
|
||||
|
||||
```bash
|
||||
if _is_admin ; then
|
||||
if bot_is_admin ; then
|
||||
send_markdown_message "${CHAT[ID]}" "*LEAVING CHAT...*"
|
||||
leave_chat "${CHAT[ID]}"
|
||||
fi
|
||||
```
|
||||
|
||||
'See also [kick Chat Member](https://core.telegram.org/bots/api/#kickchatmember)*
|
||||
See also [kick Chat Member](https://core.telegram.org/bots/api/#kickchatmember)*
|
||||
|
||||
----
|
||||
|
||||
|
|
@ -572,13 +572,11 @@ fi
|
|||
----
|
||||
|
||||
##### send_interactive
|
||||
Form version 0.80 on forward_message is used to forward messages to interactive job. It replaces the old 'inproc' commands used for TMUX.
|
||||
Usually a message is automatically forwarded in 'commands.sh', but you can forward messages while processing also or send your own messages.
|
||||
`send_interactive` is used to forward messages to interactive jobs.
|
||||
Usually a message is automatically forwarded from within `commands.sh`, but you can send messages yourself.
|
||||
|
||||
*usage:* send_interactive "${CHAT[ID]}" "message"
|
||||
|
||||
*replaces:* incproc
|
||||
|
||||
----
|
||||
|
||||
### jsshDB
|
||||
|
|
@ -612,18 +610,17 @@ slow functions:
|
|||
|
||||
#### File naming and locking
|
||||
|
||||
A jssh fileDB consists of two files which must reside inside BASHBOT_ETC or BASHBOT_DATA.
|
||||
A jssh fileDB consists of two files which must reside inside `BASHBOT_ETC` or `BASHBOT_DATA`.
|
||||
|
||||
- `filename.jssh` is a text file containing the key/value data in json.sh format.
|
||||
- `filename.jssh.flock` is used for read/write locking with flock
|
||||
|
||||
Path names containing `..` or not located in BASHBOT_ETC or BASHBOT_DATA are refused by jsshDB functions with an error.
|
||||
Path names containing `..` or not located in `BASHBOT_ETC` or `BASHBOT_DATA` are refused by jsshDB functions with an error.
|
||||
|
||||
Since version 0.94 jsshDB functions support file locking with flock. Write/update operations are serialised with flock to wait until
|
||||
previous operations are finished, see "man flock" for information. To avoid deadlocks we use a timeout of 10s for write and 5s for read operations.
|
||||
jsshDB functions use file locking with flock, if flock is availible. Write/update operations are serialised to wait until
|
||||
previous operations are finished, see "man flock". To avoid deadlocks bashbot use a timeout of 10s for write and 5s for read operations.
|
||||
|
||||
Every jssh_*DB function exist as jssj_*DB_async also.
|
||||
In case flock is not availibe or you don't want locking, jssh_*DB_async functions without file locking will be used.
|
||||
For every `jssh_...DB` function a `jsshj_...DB_async` function exsist also. In case don't want locking, use `jssh_...DB_async` functions.
|
||||
|
||||
*Example:* for allowed file names:
|
||||
```bash
|
||||
|
|
@ -676,7 +673,7 @@ Something wrong with data-bot-bash/../../../somevalues
|
|||
```
|
||||
|
||||
##### jssh_writeDB
|
||||
Write content of an ARRAY into jsshDB file. ARRAY name must be declared with "declare -A ARRAY" before calling writeDB.
|
||||
Write content of an ARRAY into jsshDB file. ARRAY name must be declared with `declare -A ARRAY` before calling writeDB.
|
||||
"DB" file MUST exist or nothing is written.
|
||||
|
||||
Note: Existing content is overwritten.
|
||||
|
|
@ -712,7 +709,7 @@ cat "${DATADIR:-}/myvalues.jssh"
|
|||
```
|
||||
|
||||
##### jssh_printDB
|
||||
Print content of an ARRAY to STDOUT. ARRAY name must be declared with "declare -A ARRAY" before calling printDB..
|
||||
Print content of an ARRAY to STDOUT. ARRAY name must be declared with `declare -A ARRAY` before calling printDB..
|
||||
|
||||
*usage:* jssh_printDB "ARRAY"
|
||||
|
||||
|
|
@ -734,7 +731,7 @@ jssh_printDB READVALUES
|
|||
```
|
||||
|
||||
##### jssh_updateDB
|
||||
Update/Add content of an ARRAY into a jsshDB file. ARRAY name must be declared with "declare -A ARRAY" before calling updateDB.
|
||||
Update/Add content of an ARRAY into a jsshDB file. ARRAY name must be declared with `declare -A ARRAY` before calling updateDB.
|
||||
"DB" file MUST exist or nothing is written.
|
||||
|
||||
Note: Existing content not in ARRAY is kept in file.
|
||||
|
|
@ -769,7 +766,7 @@ cat "$DBfile"
|
|||
```
|
||||
|
||||
##### jssh_readDB
|
||||
Read content of a file in JSON.sh format into given ARRAY. ARRAY name must be declared with "declare -A ARRAY" upfront,
|
||||
Read content of a file in JSON.sh format into given ARRAY. ARRAY name must be declared with `declare -A ARRAY` upfront,
|
||||
|
||||
*usage:* jssh_readDB "ARRAY" "filename"
|
||||
|
||||
|
|
@ -875,8 +872,8 @@ https://linuxconfig.org/how-to-use-arrays-in-bash-script
|
|||
----
|
||||
|
||||
### Aliases - shortcuts for often used functions
|
||||
Aliases are handy shortcuts for using in 'mycommands.sh', they avoid error prone typing of "${CHAT[ID]}" "${USER[ID]}" as much as possible.
|
||||
Do not use them in bashbot.sh, modules and addons.
|
||||
Aliases are handy shortcuts for use in `mycommands.sh` *only*, they avoid error prone typing of "${CHAT[ID]}" "${USER[ID]}" as much as possible.
|
||||
Do not use them in other files e.g. `bashbot.sh`, modules, addons etc.
|
||||
|
||||
##### _is_botadmin
|
||||
|
||||
|
|
@ -974,7 +971,7 @@ Do not use them in bashbot.sh, modules and addons.
|
|||
### Helper functions
|
||||
|
||||
##### download
|
||||
Download the fiven URL and returns the final filename in TMPDIR. If the given filename exists,the filename is prefixed with a
|
||||
Download the given URL and returns the final filename in TMPDIR. If the given filename exists,the filename is prefixed with a
|
||||
random number. Filename is not allowed to contain '/' or '..'.
|
||||
|
||||
*usage:* download URL filename
|
||||
|
|
@ -1084,9 +1081,6 @@ killallproc
|
|||
##### get_file
|
||||
*usage:* url="$(get_file "${CHAT[ID]}" "message")"
|
||||
|
||||
##### send_text
|
||||
*usage:* send_text "${CHAT[ID]}" "message"
|
||||
|
||||
----
|
||||
|
||||
##### JsonDecode
|
||||
|
|
@ -1107,7 +1101,7 @@ Reads JSON from STDIN and Outputs found Value to STDOUT
|
|||
|
||||
##### Json2Array
|
||||
Read JSON.sh style data from STDIN and assign to given ARRAY
|
||||
ARRAY name must be declared with "declare -A ARRAY" before calling
|
||||
ARRAY name must be declared with `declare -A ARRAY` before calling
|
||||
|
||||
*usage:* Json2Array "ARRAY"
|
||||
|
||||
|
|
@ -1155,5 +1149,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-28-g43f5536
|
||||
#### $$VERSION$$ v1.21-dev-29-g13d15f4
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
# Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
|
||||
#
|
||||
# shellcheck disable=SC1117
|
||||
#### $$VERSION$$ v1.21-dev-20-ga4dce7b
|
||||
#### $$VERSION$$ v1.21-dev-29-g13d15f4
|
||||
|
||||
# will be automatically sourced from bashbot
|
||||
|
||||
|
|
@ -336,14 +336,14 @@ send_message() {
|
|||
sent=y
|
||||
fi
|
||||
if [ "$sent" != "y" ];then
|
||||
send_text "$1" "$text"
|
||||
send_text_mode "$1" "$text"
|
||||
fi
|
||||
|
||||
}
|
||||
|
||||
# $1 CHAT $2 message starting possibly with html_parse_mode or markdown_parse_mode
|
||||
# not working, fix or remove after 1.0!!
|
||||
send_text() {
|
||||
send_text_mode() {
|
||||
case "$2" in
|
||||
'html_parse_mode'*)
|
||||
send_html_message "$1" "${2//html_parse_mode}"
|
||||
|
|
|
|||
Loading…
Reference in New Issue