From c5c337c55a0f9343c1cf2cbb93973d83bca526f7 Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@unibe.ch>
Date: Thu, 13 Mar 2025 17:07:14 +0100
Subject: [PATCH] update docs
---
docs/20_Installation.md | 23 ++++++++++++++++++---
docs/40_Embed.md | 23 +++++++++++++++++----
docs/50_Security.md | 33 +++++++++++++++++++++++++++++++
docs/{50_Build.md => 60_Build.md} | 8 +++++++-
4 files changed, 79 insertions(+), 8 deletions(-)
create mode 100644 docs/50_Security.md
rename docs/{50_Build.md => 60_Build.md} (93%)
diff --git a/docs/20_Installation.md b/docs/20_Installation.md
index 26c45c1..3200868 100644
--- a/docs/20_Installation.md
+++ b/docs/20_Installation.md
@@ -1,7 +1,24 @@
## Installation
-TODO: there is no uploaded binary yet.
+### Linux
-You need a local copy of the compiled single binary.
+Download the binary as root or with sudo
-It's not a must to put it into a folder that is covered by PATH variable.
+```txt
+sudo curl -o /usr/local/bin/amcli https://static.iml.unibe.ch/downloads/appmonitor_client/amcli_linux_x86_64
+# OR
+sudo wget -O /usr/local/bin/amcli https://static.iml.unibe.ch/downloads/appmonitor_client/amcli_linux_x86_64
+```
+
+Set executable permissions on the downloaded file
+
+```txt
+sudo chmod 0755 /usr/local/bin/amcli
+```
+
+Test amcli:
+
+```txt
+/usr/local/bin/amcli -V
+0.4
+```
diff --git a/docs/40_Embed.md b/docs/40_Embed.md
index 32786b9..34bad85 100644
--- a/docs/40_Embed.md
+++ b/docs/40_Embed.md
@@ -8,6 +8,8 @@ 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.
+
## PHP
This code snippet is for demonstration purposes only. A PHP web app should use the PHP client - see <https://os-docs.iml.unibe.ch/appmonitor/PHP_client/index.html>
@@ -15,10 +17,7 @@ This code snippet is for demonstration purposes only. A PHP web app should use t
```php
<?php
-$AMCLI = __DIR__ . '/../built_packages/amcli';
-$INI = __DIR__ . '/../src/simple.ini';
-
-$sCommand = "$AMCLI --ini='$INI'";
+$sCommand = "/usr/local/bin/amcli --ini=/var/www/www.example.com/checks.ini";
$aOut = [];
exec($sCommand, $aOut, $iRc);
@@ -44,6 +43,22 @@ $ 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)
+
+```txt
+* * * * * root /usr/local/bin/amcli --ini=/var/www/www.example.com/checks.ini > /var/www/www.example.com/public/appmonitor/appmonitor.json 2>/dev/null
+```
+
+(2)
+
+In the appmonitor server add the url to the generated static file for monitoring eg `https://www.example.com/appmonitor/appmonitor.json`.
diff --git a/docs/50_Security.md b/docs/50_Security.md
new file mode 100644
index 0000000..b461eef
--- /dev/null
+++ b/docs/50_Security.md
@@ -0,0 +1,33 @@
+## Security hints
+
+### Protect ini file
+
+The ini file can contain credentials for databases or api secrets if checks must test its acess.
+
+* If possible put them outside webroot or
+* protect its access with http, put it into a folder "protected" below webroot and deny the access
+
+Snippet for Apache httpd:
+
+```txt
+ <Location "/protected">
+ Require all denied
+ </Location>
+```
+
+### IP restriction
+
+The request to exec the `amcli` (or the generated static json file) should be protected. Maybe your output has no sensitive information but maybe it does on error. The monitoring request is not for the public.
+
+Dynamic requests depending on the kind of checks can run a bit longer and could be misused for DOS attacks.
+
+You can set an ip restriction to the ip address of your appmonitor server instance + localhost.
+
+Snippet for Apache httpd:
+
+```txt
+<location "/appmonitor">
+ Require ip 192.168.100.10
+ Require ip 127.0.0.1
+</Location>
+```
diff --git a/docs/50_Build.md b/docs/60_Build.md
similarity index 93%
rename from docs/50_Build.md
rename to docs/60_Build.md
index e6813f1..efe7e47 100644
--- a/docs/50_Build.md
+++ b/docs/60_Build.md
@@ -72,7 +72,7 @@ The build.php (without install.php) needs to be executed if the src/amcli.php wa
## Start over
-Remove the dirs
+You can manually remove the dirs
* built_packages
* build
@@ -83,3 +83,9 @@ Remove the dirs
* src/include_checks.php
Then start `./installer.php` and `./build.php`
+
+OR
+
+You can use the `-r` / `--reset` parameter when starting the installer.php:
+
+`./installer.php --reset`
--
GitLab