7.1.3-Service-script.md

@@ -0,0 +1,23 @@
+# Service script (/etc/logwatch/scripts/services/backup)
+
+Logwatch calls any script with a name that **matches the service name**.  You'll notice that I just named everything *backup* to keep things simple.  You can change this to whatever you want, however.  If you changed the service name to *"mailcowbackup*.conf", for example, you would have to rename this script file to "*mailcowbackup*" with no extension.
+
+> Note: The script is a PERL file (note the shebang) but it can be written in any
+language.
+
+> Logwatch converts everything to lowercase, so keep that in mind when naming your log file and/or renaming any of these files!
+
+**In essence, Logwatch just spits out the log file(s) defined in the LogFile Group file as standard input (STDIN) for the script and then takes whatever is output (STDOUT) from the script to assemble into it's report.**
+
+## Detail levels
+
+The script supports four (4) detail levels as follows:
+
+- **Level 0: Summary output only**
+  - This will display an aggregate total of certain logged elements.  It will display the total number of overall successful script executions, total generated warnings and total errors encountered that stopped the normal execution of the script.  All totals are relative to the reporting period Logwatch is using (--range parameter). **This is the recommended reporting level.**  It does not take up much space and is quick to read.  If you notice warnings and/or errors, you should consult the full log.
+- **Levels 1-4 (all the same): Critical messages**
+  - This uses the data which is summarized by Level 0 but outputs the actual messages in the log file.  For example, you will see the actual text of the errors logged instead of just a total number of errors.  This level of reporting is useful when *initially* monitoring the script's operation since you can see the actual text of any generated warnings/errors.
+- **Level 5: Verbose (debugging) output**
+  - Like the previous level, this outputs the actual messages found in the log file.  However, it also includes *[INFO] tags* which contain logged operational messages such as created temporary directories, starting/stopping docker containers, whether the 503 page was copied, etc. This level of reporting is useful in diagnosing why errors are occurring or if you just want more insight into how the script works. **This level of output will make your Logwatch reports longer and consume more of your time to review. You should NOT use this level day-to-day.**
+- **Levels 6+ (all the same): Complete log file dump**
+  - Any number greater than 5 passed as a detail level will trigger the script to dump the entire log file out to Logwatch line-by-line.  This is useful only if you are debugging an issue and cannot get access to the actual raw log file itself.  The actual log file is colour-coded which makes it much easier to read for debugging purposes. **Use this detail level only when you need to see the entire log file and cannot otherwise access the log file.**