From 6e4ecc9898bc5b7d904e68ff7d8a7e56cd73c7ec Mon Sep 17 00:00:00 2001 From: "Hahn Axel (hahn)" <axel.hahn@unibe.ch> Date: Fri, 17 Jan 2025 13:50:15 +0100 Subject: [PATCH] update docs --- docs/10_Installation.md | 12 ++-- docs/20_Usage.md | 142 +++++++++++++++++++++++++++++++--------- docs/30_Service.md | 14 +++- docs/_index.md | 6 +- 4 files changed, 133 insertions(+), 41 deletions(-) diff --git a/docs/10_Installation.md b/docs/10_Installation.md index 87785ce..5e4b21a 100644 --- a/docs/10_Installation.md +++ b/docs/10_Installation.md @@ -1,25 +1,25 @@ -# Installation +## Installation -# Manual installation +### Manual installation In short a manual way: * Copy the bash script somewhere you like. * set execute permissions `chmod 0755 onfilechange.sh` -# Use git +### 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 +#### Get the files ```shell cd /opt git clone https://gitlab.iml.unibe.ch/iml-open-source/onfilechange.git ``` -## Make script available anywhere +#### Make script available anywhere To have a single file in /usr/local/bin you can create a softlink @@ -28,7 +28,7 @@ cd /usr/local/bin ln -s /opt/onfilechange/onfilechange ``` -## Update +#### Update script To start an update you can use diff --git a/docs/20_Usage.md b/docs/20_Usage.md index 0c2be67..0faae15 100644 --- a/docs/20_Usage.md +++ b/docs/20_Usage.md @@ -1,51 +1,133 @@ -# Usage +## 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 + 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.06 + -INFO: stat command detected HELP: - This script checks the change of a given file and triggers - a command if it changes + +onfilechange.sh checks the change of a given fileobjects and triggers +a command on file changes. +It can use stat or inotifywait to watch a file change. Default is stat because +it can be used for non existing files. + +SYNTAX: + + onfilechange.sh OPTIONS [FILE] [[... FILE N]] 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 + + -c|--command COMMAND + A command to execute on a file change + + -f|--file FILENAME + Filenames or directories to watch; separate multiple files with + space and put all in quotes + DEPRECATED: add all files to watch as parameters + + -h|--help + show this help + + -i|--inotifywait + force inotifywait command + + -s|--stat + force stat command (default mode) + + -v + verbose mode; enable showing debug output; it should be the first option + to see handling of other options + + -w|--wait SLEEPTIME + 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 -c "ls -l" /home/me/touchfile.txt + watch touchfile.txt and make a file listing on change + + onfilechange.sh -c "ls -l" "/home/me/touchfile.txt" "home/me/touchfile2.txt" + watch touchfile.txt and touchfile2.txt + + onfilechange.sh -s -w 10 -c "echo hello" /home/me/touchfile.txt + watch touchfile.txt every 10 sec with stat and show "hello" on a change - 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 +## 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"'` +`/usr/local/bin/onfilechange.sh -c 'echo Changes!'`"/tmp/mytestfile" + +``` +______________________________________________________________________________ + + 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.06 + + +--- summary +checking file(s): /tmp/mytestfile +with command [stat] +with a sleep time of [5] seconds +on change execute command [echo Changes!] + +............................................................................... + + + +>>>>> watched files +ls: cannot access '/tmp/mytestfile': No such file or directory +INFO: file '/tmp/mytestfile' (or one of them) does not exist yet + +>>>>> start +waiting for file changes ... +``` + +If you create the file in another terminal window `touch /tmp/mytestfile`then you get the reaction: + +```txt +>>>>> start +waiting for file changes ... +1c1 +< stat: cannot statx '/tmp/mytestfile': No such file or directory +--- +> regular empty file /tmp/mytestfile | perms: -rw-r--r--; user 1000 (axel) group 1000 (axel) | size: 0 byte | last modification 2025-01-17 13:39:02.543806368 +0100 +>>>>> Fri Jan 17 13:39:06 CET 2025 Executing echo Changes! ... +``` + +The given command will be executed and its output is visible. Then it waits again. + +```txt +Changes! +Command was successful. + +>>>>> waiting for the next change ... +``` + +## Tipps and tricks + +### Multiple files + +You cannot watch just a single file but multiple files too. Just add all of them at the and of the command line as parameters. + +`onfilechange.sh -c <command> <FILE_1> <FILE_2> <FILE:N>` + +The files are seperated by spaces. If they contain spaces or other special chars you need to quote them or mask the special characters. Both of these examples are equal: + +```txt +onfilechange.sh -c <command> "directory 1" "directory 2" +onfilechange.sh -c <command> directory\ 1 directory\ 2 +``` + +### Run permanently -Each time you touch the testfile in another terminal window it should show "hello". +If the file watcher should run always ans always start after reboot, then create a service. In the chapter Service is an example for systemd. diff --git a/docs/30_Service.md b/docs/30_Service.md index f7be693..79181f7 100644 --- a/docs/30_Service.md +++ b/docs/30_Service.md @@ -1,10 +1,11 @@ - -# Use as systemd service +## 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. +### Create the service file + In `/etc/systemd/system/` create a service config file **onfilechange-demo.service** ```txt @@ -25,6 +26,13 @@ Type=simple WantedBy=multi-user.target ``` +**Remark**: +The example runs with root to restart a system service. Always limit the permission "User" an "Group" to that user that is needed for watching files and the command. + +### Test + 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 +### Startup on boot + +To start the service on reboot you additionally need to enable it: `systemctl enable onfilechange-demo`. diff --git a/docs/_index.md b/docs/_index.md index c735b0c..e2589db 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -1,7 +1,7 @@ # onfilechange -A Shell script that watches a given fileobject or multiple fileobjects (=files or directories). -If one of the watched fileobject changes then a given command will be exxecuted. +Watche a given fileobject or multiple fileobjects (=files or directories) and execute a command if it changes. + It loops permanently; you need to stop it by Ctrl + C and/ or can use it as systemd watcher daemon. @@ -26,3 +26,5 @@ application ... and on an update you want to allow him to restart the web servic Start the onfilechange to watch a defined file as root: `onfilechange.sh -f /var/www/touch2restart_httpd -c "systemctl restart httpd"` + +Or you can start a tool to process changed files in a watched directory: eg convert docs to PDF or videos. -- GitLab