From aeb4671d28f73ef945f6b65b9575c4692c4ae945 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@unibe.ch>
Date: Fri, 14 Mar 2025 14:23:30 +0100
Subject: [PATCH] update docs
---
docs/10_Introduction.md | 8 -
docs/30_Usage.md | 74 ++------
docs/40_Configuration.md | 223 ++++++++++++++++++++++++
docs/{40_Embed.md => 50_Embed.md} | 20 +--
docs/{50_Security.md => 70_Security.md} | 0
docs/{60_Build.md => 80_Build.md} | 4 +-
6 files changed, 240 insertions(+), 89 deletions(-)
create mode 100644 docs/40_Configuration.md
rename docs/{40_Embed.md => 50_Embed.md} (81%)
rename docs/{50_Security.md => 70_Security.md} (100%)
rename docs/{60_Build.md => 80_Build.md} (89%)
diff --git a/docs/10_Introduction.md b/docs/10_Introduction.md
index 02063a1..0af944a 100644
--- a/docs/10_Introduction.md
+++ b/docs/10_Introduction.md
@@ -24,11 +24,3 @@ With command line parameter `--ini=<INIFILE>` it processes the checks that are d
* A binary for your platform must be available for download or must be built. Linux x86_64 is the 1st target platform
* no other requirements/ dependencies
-
-### To built a new binary
-
-* git
-* wget
-* PHP 8 cli client (no special modules needed)
-
-Tested on Linux only so far.
diff --git a/docs/30_Usage.md b/docs/30_Usage.md
index dff2097..d485a16 100644
--- a/docs/30_Usage.md
+++ b/docs/30_Usage.md
@@ -3,7 +3,7 @@
```text
./amcli -h
- IML Appmonitor as CLI client 0.4
+ IML Appmonitor as CLI client 0.5
This client performs appmonitor checks and puts the results as JSON to stdout.
It contains all checks that are available in the PHP appmonitor client.
@@ -31,12 +31,15 @@ You find example snippets in the source code of this project in tests/config/.
🔷 OPTIONS:
- -h, --help Print this help and exit
- -i, --ini Set an INI File to parse
- -l, --list list available checks and exit
- -m, --modules list available Php modules in this binary and exit
- -v, --verbose Enable verbose output (written to STDERR)
- -V, --version Show version and exit
+ -h, --help Print this help and exit
+
+ -i, --ini Set an INI File to parse
+ -v, --verbose Enable verbose output (written to STDERR)
+
+ -b, --buildinfos show build information and exit
+ -l, --list list available checks and exit
+ -m, --modules list available Php modules in this binary and exit
+ -V, --version Show version and exit
👉 EXAMPLES:
@@ -57,61 +60,10 @@ To execute it use the `--ini` parameter and reference the file (as absolute path
`[<PATH>]amcli --ini=<FILENAME>`
-## Define checks
-
-The infomation for the checks is structured in sections.
-
-* `[meta]` - defines the meta information for the web application, its hostname and more. This section is optional but I am naerly sure you want to override the defaults
-* `[notifications]` - define application specific receivers that get a message from appmonitor server on status change of this app.
-* `[<OTHER>]` - define one check per section.
-
-First an example:
-
-```ini
-[meta]
-host = "www.example.com"
-website = "Company website"
-ttl = 300
-tags[]="monitoring"
-
-[notifications]
-email[]="support@example.com"
-email[]="webmaster@example.com"
-
-slack["#support-channel"]="https://hooks.slack.com/services/XXXXXX/YYYYYY/ZZZZZ"
-
-; -----------------------------------------------------------------------
-; CHECKS
-; -----------------------------------------------------------------------
-
-["hello plugin"]
-description="I sust wanna say hello"
-function="hello"
-params[message]="Here is ${USER}"
-```
-
-### Types of values
-
-The binary uses the php function `parse_ini_file` - see 🌠<https://www.php.net/manual/en/function.parse-ini-file.php>.
-
-* The **section** is in brackets eg. `[<SECTION>]`
-* In each section is a set of keys and values, separated by `=`
-* **keys** (variable):
-
- * a string with letters, digits, underscore
- * Use multiple `<VARNAME>[]` to create an an array with list items
- * `<VARNAME>[<KEY>]` is used for slack notifications and one of the possible options for [check] -> params
-
-* **values**
-
- * numbers of integer, float (no quoting)
- * strings in single quotes or double quotes
- * Specialty: In [check] -> params you can use JSON syntax: It is aquoted string using single quotes `'`. The JSON key and value must be quoted with double quotes.
- * Environment variables or PHP configuration values can be embedded using `${<VARMAME>}`; it works with unquoted value or double quoted strings but not inside single quotes (or JSON).
-
-The values for each check are check specific. Have a look to the origin docs for each check - see 📗 <https://os-docs.iml.unibe.ch/appmonitor/PHP_client/Plugins/Checks/index.html>.
+Recommendations:
-To have a minimal working example have a the folder `tests/configs` or here 🌠<https://git-repo.iml.unibe.ch/iml-open-source/appmonitor-cli-client/-/tree/main/tests/configs?>. These ini files do NOT contain all supported keys.
+* The output is JSON in a single line. You can use `jq` to beautify it, eg `[<PATH>]amcli --ini=<FILENAME> | jq`
+* If the bahaviuor seems to be unwanted use `-v` to enable verbose mode. You get more debug output during the execution, showing parsed ini file and more. `[<PATH>]amcli --ini=<FILENAME> -v`
## Exitcodes
diff --git a/docs/40_Configuration.md b/docs/40_Configuration.md
new file mode 100644
index 0000000..89c7669
--- /dev/null
+++ b/docs/40_Configuration.md
@@ -0,0 +1,223 @@
+## How to check an app?
+
+To read about the PHP client have a look to the introdction
+<https://os-docs.iml.unibe.ch/appmonitor/Client/Introduction.html>
+
+The binary is compiled PHP code containing the classes to perform checks.
+
+To use the checks inside that binary the must be defined in an ini file.
+
+It contains:
+
+* meta information for the app
+* all checks
+
+The output is a JSON. The structure is described on 📗 <https://os-docs.iml.unibe.ch/appmonitor/Client/Description_of_response.html>.
+
+### Introduction
+
+The infomation for the checks is structured in sections.
+
+* `[meta]` - defines the meta information for the web application, its hostname and more. This section is optional but I am naerly sure you want to override the defaults
+* `[notifications]` - define application specific receivers that get a message from appmonitor server on status change of this app.
+* `[<OTHER>]` - all other section except meta and ntifications are checks. Define one check per section.
+
+First an example:
+
+```ini
+[meta]
+host = "www.example.com"
+website = "Company website"
+ttl = 300
+tags[]="monitoring"
+
+[notifications]
+email[]="support@example.com"
+email[]="webmaster@example.com"
+
+slack["#support-channel"]="https://hooks.slack.com/services/XXXXXX/YYYYYY/ZZZZZ"
+
+; -----------------------------------------------------------------------
+; CHECKS
+; -----------------------------------------------------------------------
+
+["hello plugin"]
+description="I sust wanna say hello"
+function="hello"
+params[message]="Here is ${USER}"
+```
+
+### Types of values
+
+The binary uses the php function `parse_ini_file` - see 🌠<https://www.php.net/manual/en/function.parse-ini-file.php>.
+
+* The **section** is in brackets eg. `[<SECTION>]`
+* In each section is a set of keys and values, separated by `=`
+* **keys** (variable):
+
+ * a string with letters, digits, underscore
+ * Use multiple `<VARNAME>[]` to create an an array with list items
+ * `<VARNAME>[<KEY>]` is used for slack notifications and one of the possible options for [check] -> params
+
+* **values**
+
+ * numbers of integer, float (no quoting)
+ * strings in single quotes or double quotes
+ * Specialty: In [check] -> params you can use JSON syntax: It is aquoted string using single quotes `'`. The JSON key and value must be quoted with double quotes.
+ * Environment variables or PHP configuration values can be embedded using `${<VARMAME>}`; it works with unquoted value or double quoted strings but not inside single quotes (or JSON).
+
+The values for each check are check specific. Have a look to the origin docs for each check - see 📗 <https://os-docs.iml.unibe.ch/appmonitor/PHP_client/Plugins/Checks/index.html>.
+
+To have a minimal working example have a the folder `tests/configs` or here 🌠<https://git-repo.iml.unibe.ch/iml-open-source/appmonitor-cli-client/-/tree/main/tests/configs?>. These ini files do NOT contain all supported keys.
+
+### Meta information
+
+#### Section [meta]
+
+| key | type | description
+| -- | -- | --
+| host | string | hostname where the app is running. example: "www.example.com"; default: automatic detection
+| website🔸 | string | Name of the app, eg. "Company website";
+| ttl | int | Ttl value in seconds. Tis cycle will be used by the appmonitor server to refresh the information
+| tags | array | array of tags (optional) You can send tags to describe kind of tool, department/ developer team, whatever. In the server webgui you will see a list of all tags of all monitors and can filter them
+
+🔸 required
+
+👉 Example:
+
+```ini
+[meta]
+host = "www.example.com"
+website = "Company website"
+ttl = 300
+tags[]="monitoring"
+```
+
+#### Section [notifications]
+
+You can define application specific receivers on status changes.
+This section is optional.
+
+Currently supported are
+
+* email addresses
+* Slack channels
+
+| key | type | description
+| -- | -- | --
+| email | array | array of email receivers
+| slack | hash | key-value list with a readable label for the target channel and the Slack webhook url
+
+👉 Example:
+
+```ini
+[notifications]
+email[]="support@example.com"
+email[]="webmaster@example.com"
+
+slack["#support-channel"]="https://hooks.slack.com/services/XXXXXX/YYYYYY/ZZZZZ"
+```
+
+### Check sections
+
+#### Transform PHP hash to ini
+
+All other sections except "meta" and "notifications" are checks. Define one check per section.
+
+All available checks are described here: 📗 <https://os-docs.iml.unibe.ch/appmonitor/PHP_client/Plugins/Checks/index.html>.
+
+Each section corresponds to a call of a single check.
+
+Conventions to describe a check in an ini section instead of using `$oMonitor->addCheck(<hash>)` snippets:
+
+* "name" - is the section name
+* "description" - use key "description" (1:1)
+* section "check" - this keyword is missed in ini files. Its subkeys are are taken 1 as keys
+ * check->function - use "function"
+ * check->params - use "params" as a hash
+
+Let's have a look to an example: this is the PHP code for the **Diskfree** check <https://os-docs.iml.unibe.ch/appmonitor/PHP_client/Plugins/Checks/diskfree.html>:
+
+👉 Example:
+
+```php
+$oMonitor->addCheck(
+ [
+ "name" => "Check free diskspace in /tmp",
+ "description" => "The file storage have some space left",
+ "check" => [
+ "function" => "Diskfree",
+ "params" => [
+ "directory" => "[directory]",
+ "warning" => [size],
+ "critical" => [size],
+ ],
+ ],
+ ]
+);
+```
+
+The same described in ini format:
+
+```ini
+["Free disk space /tmp"]
+description="The file storage have some space left"
+function="Diskfree"
+params[directory]="/tmp"
+params[warning]="1GB"
+params[critical]="500MB"
+```
+
+#### Dynamic values
+
+OK, the ini file has keys and values.
+If have environment variables (maybe by an earliear loaded .env file) then you can use them by adding a dollar sign in front.
+
+👉 Example:
+
+If you have this variable in the environment before starting amcli:
+
+```txt
+API_URL="https://www.example.com/api/v1/"
+```
+
+it can be expanded if your ini contains `$API_URL`:
+
+```txt
+["Http content"]
+description="Check if API is online"
+function="HttpContent"
+params[url]: "$API_URL"
+```
+
+#### JSON
+
+The params are written as a hash. It works as long the value is string/ integer/ bool value.
+
+It does not work on an array or hash. But there is a specialty (that is not part of the ini format): if the given value is a string then you can write a JSON.
+
+* use single quotes for the string
+* use double quotes for quoting key and value
+* multiline strings are posiible - and recommended for better readability
+
+👉 Example:
+
+When using the JSON format of
+
+```ini
+params[directory]="/tmp"
+params[warning]="1GB"
+params[critical]="500MB"
+```
+
+it looks like this:
+
+```ini
+params='{
+ "directory": "/tmp",
+ "warning": "1GB",
+ "critical": "500MB"
+}'
+```
+
+âš ï¸ Keep in mind that within JSON you cannot expand variables.
diff --git a/docs/40_Embed.md b/docs/50_Embed.md
similarity index 81%
rename from docs/40_Embed.md
rename to docs/50_Embed.md
index 34bad85..b09fb4e 100644
--- a/docs/40_Embed.md
+++ b/docs/50_Embed.md
@@ -8,7 +8,7 @@ To embed the cli tool into your web application you need to
* if it is `0` then the excution was successful - we have a result. You can send the JSON after setting the content type as http response header
* if it is `> 0` the response is no JSON syntax. You should send the output that the error is seen in the appm nitor server.
-Don't forget to protect the ini file and the monitoring request. See page Security.
+âš ï¸ Don't forget to protect the ini file and the monitoring request. See page Security.
## PHP
@@ -31,27 +31,9 @@ if ($iRc == 0) {
echo implode("\n", $aOut);
```
-To test it:
-
-(1)
-
-Start PHP webserver
-
-```txt
-$ cd examples
-$ php -S localhost:9000
-[Fri Mar 7 09:01:52 2025] PHP 8.4.4 Development Server (http://localhost:9000) started
-```
-
-
-(2)
-
-In a webbrowser open <http://localhost:9000/embed_example.php>
-
## Cronjob
You can setup a cronjob starting every minute. Its output you can write into a json file that is accessible by the webservice.
-You can
(1)
diff --git a/docs/50_Security.md b/docs/70_Security.md
similarity index 100%
rename from docs/50_Security.md
rename to docs/70_Security.md
diff --git a/docs/60_Build.md b/docs/80_Build.md
similarity index 89%
rename from docs/60_Build.md
rename to docs/80_Build.md
index 0e28515..e58afd0 100644
--- a/docs/60_Build.md
+++ b/docs/80_Build.md
@@ -1,5 +1,7 @@
## Requirements
+### Linux
+
To update and test the command line tool you need
* git
@@ -81,7 +83,7 @@ You need to re-run install.php + build.php if
* there is a newer appmonitor client version
* you compile with a newer php version
-* you change the set of included php modules.
+* you change the set of included php modules. For database access are included sqlite, mysql and postgres. For other database types supported by PHP you need to add the module in inc_vars.php `$php_libs="..."` and recompile the binary: `php installer.php && php build.php;`.
The build.php (without install.php) needs to be executed if the src/amcli.php was changed.
--
GitLab