add docs; update readme

README.md

@@ -8,9 +8,11 @@ use it as systemd watcher daemon.
 It uses stat for wide compatibility but can enable inotifywatch to
 check a file change by an event.
 
-licence: Free software GNU GPL 3.0
+Institute for Medical Education; University of Bern
 
-Source: https://git-repo.iml.unibe.ch/iml-open-source/onfilechange
+📄 Source: <https://git-repo.iml.unibe.ch/iml-open-source/onfilechange> \
+📜 License: GNU GPL 3.0 \
+📖 Docs: <https://os-docs.iml.unibe.ch/onfilechange/>
 
 ## Why?
 
@@ -19,96 +21,8 @@ You can use it to trigger actions that are not allowed by another user.
 Scenario:
 
 A web developer has access with a non privileged user to maintain an
-application ... and on an update you want to allow him to restart the
-web service without sudo permissions.
+application ... and on an update you want to allow him to restart the web service without sudo permissions.
 
 Start the onfilechange to watch a defined file as root:
 
 `onfilechange.sh -f /var/www/touch2restart_httpd -c "systemctl restart httpd"`
-
-## Installation
-
-* Copy the bash script somewhere you like.
-* set  execute permissions `chmod 0755 onfilechange.sh`
-
-## Usage
-
-start `./onfilechange.sh -h` to get the help
-
-```
-______________________________________________________________________________
-
-  T R I G G E R    C O M M A N D    O N    A    F I L E C H A N G E
-______________________________________________________________________________
-                                                                         v1.04
-
-INFO: stat command detected
-HELP:
-        This script checks the change of a given file and triggers
-        a command if it changes
-
-PRAMETERS:
-        -c [command]
-            command to execute on a file change
-        -f [filename(s)]
-            filenames to watch; separate multiple files with space and put all in quotes
-        -h
-            show this help
-        -i
-            force inotifywait command
-        -s
-                force stat command (default mode)
-        -v
-            verbose mode; enable showing debug output
-        -w [integer]
-            for stat mode: wait time in seconds betweeen each test or on missing file; default: 5 sec
-
-EXAMPLES:
-        onfilechange.sh -f /home/me/touchfile.txt -c "ls -l" 
-            watch touchfile.txt and make a file listing on change
-
-        onfilechange.sh -f "/home/me/touchfile.txt home/me/touchfile2.txt" -c "ls -l" 
-            watch touchfile.txt and touchfile2.txt
-
-        onfilechange.sh -f /home/me/touchfile.txt -s -w 10 -c "echo hello" 
-            watch touchfile.txt every 10 sec with stat and show "hello" on a change
-```
-
-## Test on command line
-
-To make a test on commandline touch a testfile `touch /tmp/mytestfile`.
-The start the script with enabled debugging (-d) in a 2nd terminal:
-
-`/usr/local/bin/onfilechange.sh -v -f "/tmp/mytestfile" -c 'echo "hello"'`
-
-Each time you touch the testfile it should show "hello".
-
-## Use as systemd service
-
-With running the script as a service can be helpful if you administrate servers and habe developer teams with limited access. Instead of giving sudo permissions you can watch a touchfile to execute something specific as root, i.e. restart Apache httpd. In the real world this file would be touched during an automated deploy process.
-
-Below is just an example service watching a dummy file in /tmp directory.
-
-In `/etc/systemd/system/` create a service config file **onfilechange-demo.service**
-
-```
-[Unit]
-Description=Onfilechange demo
-Wants=multi-user.target
-
-[Service]
-ExecStart=/usr/local/bin/onfilechange.sh -f "/tmp/mytestfile" -c 'systemctl restart apache2'
-Restart=on-failure
-RestartSec=5s
-SyslogIdentifier=onfilechange
-User=root
-Group=root
-Type=simple
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Check if the service exists `systemctl status onfilechange-demo`. If so you can start and stop it with `systemctl [start|stop] onfilechange-demo`
-
-To start the service on reboot you additionally need to enable it: `systemctl enable onfilechange-demo`.
\ No newline at end of file

docs/10_Installation.md

+# Installation
+
+# Manual installation
+
+In short a manual way:
+
+* Copy the bash script somewhere you like.
+* set  execute permissions `chmod 0755 onfilechange.sh`
+
+# Use git
+
+If you have git and want to update the files with a simple git pull
+you can do it that way.
+
+## Get the files
+
+```shell
+cd /opt
+git clone https://gitlab.iml.unibe.ch/iml-open-source/onfilechange.git
+```
+
+## Make script available anywhere
+
+To have a single file in /usr/local/bin you can create a softlink
+
+```shell
+cd /usr/local/bin
+ln -s /opt/onfilechange/onfilechange
+```
+
+## Update
+
+To start an update you can use
+
+```shell
+cd /opt/onfilechange/
+git pull
+```

docs/20_Usage.md

+# Usage
+
+Start `./onfilechange.sh -h` to get the help
+
+```txt
+______________________________________________________________________________
+
+  T R I G G E R    C O M M A N D    O N    A    F I L E C H A N G E
+______________________________________________________________________________
+                                                                         v1.04
+
+INFO: stat command detected
+HELP:
+        This script checks the change of a given file and triggers
+        a command if it changes
+
+PRAMETERS:
+        -c [command]
+            command to execute on a file change
+        -f [filename(s)]
+            filenames to watch; separate multiple files with space and put all in quotes
+        -h
+            show this help
+        -i
+            force inotifywait command
+        -s
+                force stat command (default mode)
+        -v
+            verbose mode; enable showing debug output
+        -w [integer]
+            for stat mode: wait time in seconds betweeen each test or on missing file; default: 5 sec
+
+EXAMPLES:
+        onfilechange.sh -f /home/me/touchfile.txt -c "ls -l" 
+            watch touchfile.txt and make a file listing on change
+
+        onfilechange.sh -f "/home/me/touchfile.txt home/me/touchfile2.txt" -c "ls -l" 
+            watch touchfile.txt and touchfile2.txt
+
+        onfilechange.sh -f /home/me/touchfile.txt -s -w 10 -c "echo hello" 
+            watch touchfile.txt every 10 sec with stat and show "hello" on a change
+```
+
+# Test on command line
+
+To make a test on commandline touch a testfile `touch /tmp/mytestfile`.
+The start the script with enabled debugging (-d) in a 2nd terminal:
+
+`/usr/local/bin/onfilechange.sh -v -f "/tmp/mytestfile" -c 'echo "hello"'`
+
+Each time you touch the testfile in another terminal window it should show "hello".

docs/30_Service.md

+
+# Use as systemd service
+
+With running the script as a service can be helpful if you administrate servers and habe developer teams with limited access. Instead of giving sudo permissions you can watch a touchfile to execute something specific as root, i.e. restart Apache httpd. In the real world this file would be touched during an automated deploy process.
+
+Below is just an example service watching a dummy file in /tmp directory.
+
+In `/etc/systemd/system/` create a service config file **onfilechange-demo.service**
+
+```txt
+[Unit]
+Description=Onfilechange demo
+Wants=multi-user.target
+
+[Service]
+ExecStart=/usr/local/bin/onfilechange.sh -f "/tmp/mytestfile" -c 'systemctl restart apache2'
+Restart=on-failure
+RestartSec=5s
+SyslogIdentifier=onfilechange
+User=root
+Group=root
+Type=simple
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Check if the service exists `systemctl status onfilechange-demo`. If so you can start and stop it with `systemctl [start|stop] onfilechange-demo`
+
+To start the service on reboot you additionally need to enable it: `systemctl enable onfilechange-demo`.
\ No newline at end of file

docs/_index.md

+# onfilechange
+
+A Shell script that watches a given file or multiple files. 
+If one of the watched file changes then a given command will be exxecuted.
+It loops permanently; you need to stop it by Ctrl + C and/ or can
+use it as systemd watcher daemon.
+
+It uses stat for wide compatibility but can enable inotifywatch to
+check a file change by an event.
+
+Institute for Medical Education; University of Bern
+
+📄 Source: <https://git-repo.iml.unibe.ch/iml-open-source/onfilechange> \
+📜 License: GNU GPL 3.0 \
+📖 Docs: <https://os-docs.iml.unibe.ch/onfilechange/>
+
+## Why?
+
+You can use it to trigger actions that are not allowed by another user.
+
+Scenario:
+
+A web developer has access with a non privileged user to maintain an
+application ... and on an update you want to allow him to restart the web service without sudo permissions.
+
+Start the onfilechange to watch a defined file as root:
+
+`onfilechange.sh -f /var/www/touch2restart_httpd -c "systemctl restart httpd"`

docs/config.json

+{
+    "title": "onfilechange",
+    "author": "Axel Hahn",
+    "tagline": "Trigger an action if a file changes",
+    "ignore": {
+        "files": ["30_PHP-client/Plugins/Checks/_skeleton.md"],
+        "folders": ["99_Not_Ready"]
+    },
+    "html": {
+        "auto_toc": true,
+        "auto_landing": false,
+        "date_modified": false,
+        "jump_buttons": true,
+        "edit_on_github_": "iml-it/__PROJECT__/tree/master/docs",
+        "edit_on_": {
+            "name": "Gitlab",
+            "basepath": "https://git-repo.iml.unibe.ch/iml-open-source/__PROJECT__/tree/master/docs"
+        },
+        "links": {
+            "Git Repo": "__GITURL__"
+        },
+        "theme": "daux-blue",
+        "search": false
+    }
+}
\ No newline at end of file

docs/style.css

+/*
+
+    patch css elements of daux.io blue theme
+    version 2022-05-13
+
+*/
+
+
+/* ---------- vars ---------- */ 
+
+:root{
+
+    /* background colors */
+    --bg:none;
+    --bg-body: #fff;
+    --bg-navlinkactive:#f4f4f4;
+    --bg-navlinkactive: linear-gradient(-90deg,rgba(0,0,0,0), rgba(40,60,80,0.05) 30%);
+    --bg-pre:#f8f8f8;
+    --bg-toc: #fff;
+
+    /* foreground colors */
+    --color: #234;
+    --navlinkactive:#f33;
+    --title: #aaa;
+
+    --link:#12a;
+    --toclink:rgba(40,60,80,0.8);
+
+    --h1: rgba(40,60,80,0.8);
+    --h1-bottom: 1px solid rgba(40,60,80,0.1);
+    --h2: #468;
+    --h3: #579;
+
+}
+
+/* ---------- tags ---------- */
+
+a.Brand::before {
+	background: rgb(255,0,51);
+	color: #fff;
+    font-family: arial;
+	font-weight: bold;
+	padding: 0.5em 0.3em;
+	content: 'IML';
+    margin-right: 0.4em;
+}
+
+body, *{color: var(--color);}
+body{background: var(--bg-body);}
+
+
+a{color: var(--link);}
+a:hover{opacity: 0.7;}
+
+h1>a{ color:var(--title);}
+_h1:nth-child(1){position: fixed; background: var(--bg); box-shadow: 0 0 1em #ccc; padding: 0 1em}
+h1:nth-child(1)>a{ color:var(--navlinkactive); }
+
+.s-content h1{color: var(--h1); font-size: 200%; font-weight:bold; margin-top: 2em; border-bottom: var(--h1-bottom);}
+.s-content h2{color: var(--h2); font-size: 160%; }
+.s-content h3{color: var(--h3); font-size: 140%; }
+.s-content h4{margin: 0; font-size: 100%; text-align: center; background-color: rgba(0,0,0,0.05);padding: 0.3em;}
+
+.s-content pre{
+    background: var(--bg-pre);
+}
+
+/* ---------- classes ---------- */
+
+.required{color:#a42;}
+.optional{color:#888;}
+
+
+/* ----- top left */
+.Brand,
+.Columns__left {
+	background: var(--bg);
+	border-right: 0px solid #e7e7e9;
+    color: var(--color);
+}
+.Brand{font-size: 200%;
+    background_: linear-gradient(-10deg,#fff 50%, #ddd);
+    background: var(--bg);
+}
+.Columns__right__content {
+	background: var(--bg);
+}
+
+/* ----- Navi left */
+
+.Nav a:hover{
+    background: none;
+    color: var(--navlinkactive) !important;
+}
+
+.Nav__item--active {
+    border-right_: 0.3em solid var(--navlinkactive);
+}
+.Nav__item--active > a{
+	background: var(--bg-navlinkactive);
+    color: var(--navlinkactive);
+}
+.Nav .Nav .Nav__item--active a {
+    color: var(--navlinkactive);
+}
+.Nav .Nav .Nav__item a {
+	opacity: 1;
+}
+.Nav__item--open > a {
+	background-color: var(--bg);
+}
+
+.Nav a[href*="__Welcome"]{
+    background: url("/icons/house.png") no-repeat 10px 4px ;
+    padding-left: 40px;
+}
+.Nav a[href*="__How_does_it_work"]{
+    background: url("/icons/light-bulb.png") no-repeat 10px 4px ;
+    padding-left: 40px;
+}
+
+
+
+
+/* ---------- classes ---------- */
+
+/* FIX smaller fnt size in tables */
+.s-content table {
+	font-size: 1em;
+}
+
+
+/* TOC */
+@media(min-width:1700px){
+    .TableOfContentsContainer{
+        position: fixed;
+        right: 2em;
+        top: 1em;
+    }
+}
+
+.TableOfContentsContainer{
+    border-top-left-radius: 1em;
+    background-color: var(--bg-toc);
+	border-left: 2px solid rgba(0,0,0,0.05);
+    padding: 0em;
+}
+.TableOfContentsContainer__content {
+
+	border: none;
+	font-size: 0.5em;
+
+}
+ul.TableOfContents ul{
+	list-style-type: none;
+    padding-left: 1em;
+}
+.TableOfContentsContainer a{ color:var(--toclink);}
+
+.TableOfContentsContainer__content > .TableOfContents > li + li {
+	border-top: none;
+}
+.TableOfContentsContainer__content > .TableOfContents > li {
+	border-bottom: 1px dashed #ddd;
+}
+
+/* pager - prev .. next */
+.s-content{
+    margin-bottom: 6em;
+}
+.Pager{
+    border-top: 1px dashed #aaa; margin: 0; padding: 1em;
+}
+.Pager a{
+    color:var(--navlinkactive);
+}