diff --git a/etc/logwatch/README.md b/etc/logwatch/README.md index b002832..c1bf9d8 100644 --- a/etc/logwatch/README.md +++ b/etc/logwatch/README.md @@ -1,8 +1,8 @@ # Using Logwatch to monitor Cloudflare DDNS updater script -The Cloudflare DDNS update script's log file has been setup so that utilities +The Cloudflare DDNS update script's log file has been set up so that utilities like Logwatch can easily parse it. In order to make that happen, a LogFile -group file, service and script have to be created for Logwatch to generate +Group file, Service and Script have to be created for Logwatch to generate reports. The correct (general) directory structure has been created in this git archive already. Below are the details of each file. @@ -13,7 +13,7 @@ archive already. Below are the details of each file. - [Archive location and name format](#archive-location-and-name-format) - [External script for timestamp processing](#external-script-for-timestamp-processing) - [Service definition file (/etc/logwatch/conf/services/cfddns.conf)](#service-definition-file-etclogwatchconfservicescfddnsconf) - - [LogFile group definition](#logfile-group-definition) + - [LogFile Group file definition](#logfile-group-file-definition) - [Report title](#report-title) - [Service script (/etc/logwatch/scripts/services/cfddns)](#service-script-etclogwatchscriptsservicescfddns) - [Detail levels](#detail-levels) @@ -27,18 +27,16 @@ archive already. Below are the details of each file. ### Log file location -This file is commented so you can update it as necessary for your environment -(i.e. you've changed the name of the log file generated by the script via the -l -parameter). +Update this as needed to point to the location and name of the log file +generated by the updater script. Remember, by default, the log file is created +in the same directory as the script itself. ```Ini LogFile = /path/to/your/cfddns.log ... ``` -Update this needed to point to the location and name of the log file generated -by the updater script. Remember, by default, the log file is created in the -same directory as the script itself. Best practices suggest you use the *-l* +Best practices suggest you use the *-l* flag to change this location to something like */var/log/cfddns.log*, for example. In that case, the entry would look like: @@ -50,7 +48,7 @@ LogFile = /var/log/cfddns.log ### Archive location and name format If you want Logwatch to process old (archived) log files generated by something -like *Logrotate*, then you have to specify that location and file name format of +like *Logrotate*, then you have to specify the location and file name format of those files. I've included the generalized compressed format of such rotated files as the default in the script. Suppose you store your log files in the recommended location (*/var/log/*) and are using *Logrotate* with compression @@ -72,8 +70,9 @@ option in Logwatch to true. You can comment/delete this line if you wish.** ### External script for timestamp processing Since the log file uses a non-standard (according to Logwatch) method of -time-stamping, a custom filter had to be created. See the relevant section of -this document for more information. +datestamping, a custom filter had to be created. See the +[relevant](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere) +section of this document for more information. The script file is called with an *\** before the filename. @@ -89,8 +88,8 @@ so your filename should be all lowercase also. ## Service definition file (/etc/logwatch/conf/services/cfddns.conf) -### LogFile group definition -The service file needs to know what group of log file it is responsible for +### LogFile Group file definition +The service file needs to know what group of log files it is responsible for processing. This MUST match the name of your *LogFile Group file*: ```Ini @@ -118,11 +117,12 @@ Logwatch calls any script with a name that **matches the service name**. You'll notice that I just named everything *cfddns* to keep things simple. You can change this to whatever you want, however. If you changed the service name to *"cloudflare*.conf", for example, you would have to rename this script file to -"*cloudflare*" with no extension. Note: The script is a PERL file. +"*cloudflare*" with no extension. Note: The script is a PERL file (note the +shebang) but it can be written in any language. In essence, Logwatch just spits out the log file(s) defined in the LogFile Group -file as standard input (STDIN) and then takes whatever is output (STDOUT) and -assembles that into it's report. +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 @@ -131,10 +131,12 @@ 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 hostnames (A and AAAA) that are already - up-to-date, those that needed updated, those successfully updated and the - total number of errors (or any type) encountered by the script. All + up-to-date, those that needed updating, those successfully updated and + the total number of errors (of any type) encountered by the script. All totals are relative to the reporting period Logwatch is using (--range - parameter). **This is the recommended reporting level.** It does not + parameter). + + **This is the recommended reporting level.** It does not take up much space and is quick to read. If you see successful updates match the number of needed updates and no errors logged, then things are working properly. If you notice errors, you should consult the full @@ -151,7 +153,9 @@ The script supports four (4) detail levels as follows: messages such as the detected IP address and the specific names of any hostnames not found in your Cloudflare account, 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 + 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+: Complete log file dump** @@ -159,7 +163,9 @@ The script supports four (4) detail levels as follows: 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. **Use this detail level only when you need + 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.** ## Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere) @@ -167,15 +173,15 @@ The script supports four (4) detail levels as follows: This is basically a modified version of the '*applyeurodate*' script that comes with Logwatch. It had to be modified to search within [square brackets] and to accept characters coming before the stamp (i.e. ANSI colour codes). If you -change '**stamp**' variable in the updater script to update the timestamp to +change the '**stamp**' variable in the updater script to update the timestamp to your liking (which to totally fine!) then you'll probably have to update this file. There are two lines you need to modify to suit your new '**stamp**' variable. ### The time format specification -SearchDate is the variable used in the PERL script to do exactly what it says, -search for the date stamp. I have it set up to look for the format +'*$SearchDate*' is the variable used in the PERL script to do exactly what it +says, search for the date stamp. I have it set up to look for the format '*year-month-date hour:minute:second*'. Note, we don't care about brackets or anything here, we're just defining the format of the date/time stamp. @@ -187,7 +193,7 @@ $SearchDate = TimeFilter('%Y-%m-%d %H:%M:%S'); If you changed the '**stamp**' variable so it was formatted as '*month/day/year hour:minute*' (ex: '*[09/27/2018 18:38]*') then you'd update the **$SearchDate** -variable as follows: +variable as follows (note: no mention of the square brackets!): ```Perl ... @@ -242,13 +248,13 @@ locally on your screen with the following command (assuming you kept default names for everything): ```Bash -# Summary output entire duration of log file +# Summary output, entire duration of log file logwatch --service cfddns --output stdout --format text --range all --detail 0 -# Minimal detail yesterday only -logwatch --service cfddns --output stdout --format text --range yesterday --detail 1 +# Minimal detail, yesterday only +logwatch --service cfddns --output stdout --format text --range yesterday --detail 3 -# Verbose output today only +# Verbose output, today only logwatch --service cfddns --output stdout --format text --range today --detail 5 ``` @@ -256,5 +262,5 @@ logwatch --service cfddns --output stdout --format text --range today --detail 5 That's it! I'm a horrible PERL programmer so if anyone can optimize/improve the script file used for Logwatch then please do it! Otherwise, I hope this made -sense and helped you out integrating the updater script with Logwatch for easy +sense and helped you integrate the updater script with Logwatch for easy monitoring :-) \ No newline at end of file