asif/CloudflareDDNS
1
0
Fork 0
Code Issues Pull Requests Releases 2 Activity

Proofreading

Browse Source
This commit is contained in:
Asif Bacchus 2018-09-27 19:25:23 -06:00
parent 689f11beba
commit a901fc7ea2
1 changed files with 37 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
etc/logwatch/README.md
View File

@ -1,8 +1,8 @@
# Using Logwatch to monitor Cloudflare DDNS updater script <!-- omit in toc --> # Using Logwatch to monitor Cloudflare DDNS updater script <!-- omit in toc -->
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 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 reports. The correct (general) directory structure has been created in this git
archive already. Below are the details of each file. archive already. Below are the details of each file.
@ -13,7 +13,7 @@ ## Contents <!-- omit in toc -->
- [Archive location and name format](#archive-location-and-name-format) - [Archive location and name format](#archive-location-and-name-format)
- [External script for timestamp processing](#external-script-for-timestamp-processing) - [External script for timestamp processing](#external-script-for-timestamp-processing)
- [Service definition file (/etc/logwatch/conf/services/cfddns.conf)](#service-definition-file-etclogwatchconfservicescfddnsconf) - [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) - [Report title](#report-title)
- [Service script (/etc/logwatch/scripts/services/cfddns)](#service-script-etclogwatchscriptsservicescfddns) - [Service script (/etc/logwatch/scripts/services/cfddns)](#service-script-etclogwatchscriptsservicescfddns)
- [Detail levels](#detail-levels) - [Detail levels](#detail-levels)
@ -27,18 +27,16 @@ ## LogFile Group file (/etc/logwatch/conf/logfiles/cfddns.conf)
### Log file location ### Log file location
This file is commented so you can update it as necessary for your environment Update this as needed to point to the location and name of the log file
(i.e. you've changed the name of the log file generated by the script via the -l generated by the updater script. Remember, by default, the log file is created
parameter). in the same directory as the script itself.
```Ini ```Ini
LogFile = /path/to/your/cfddns.log LogFile = /path/to/your/cfddns.log
... ...
``` ```
Update this needed to point to the location and name of the log file generated Best practices suggest you use the *-l*
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*
flag to change this location to something like */var/log/cfddns.log*, for flag to change this location to something like */var/log/cfddns.log*, for
example. In that case, the entry would look like: example. In that case, the entry would look like:
@ -50,7 +48,7 @@ ### Log file location
### Archive location and name format ### Archive location and name format
If you want Logwatch to process old (archived) log files generated by something 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 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 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 recommended location (*/var/log/*) and are using *Logrotate* with compression
@ -72,8 +70,9 @@ ### Archive location and name format
### External script for timestamp processing ### External script for timestamp processing
Since the log file uses a non-standard (according to Logwatch) method of 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 datestamping, a custom filter had to be created. See the
this document for more information. [relevant](#timestamp-processing-script-etclogwatchscriptssharedsqfullstampanywhere)
section of this document for more information.
The script file is called with an *\** before the filename. The script file is called with an *\** before the filename.
@ -89,8 +88,8 @@ ### External script for timestamp processing
## Service definition file (/etc/logwatch/conf/services/cfddns.conf) ## Service definition file (/etc/logwatch/conf/services/cfddns.conf)
### LogFile group definition ### LogFile Group file definition
The service file needs to know what group of log file it is responsible for 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*: processing. This MUST match the name of your *LogFile Group file*:
```Ini ```Ini
@ -118,11 +117,12 @@ ## Service script (/etc/logwatch/scripts/services/cfddns)
notice that I just named everything *cfddns* to keep things simple. You can 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 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*.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 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 file as standard input (STDIN) for the script and then takes whatever is output
assembles that into it's report. (STDOUT) from the script to assemble into it's report.
### Detail levels ### Detail levels
@ -131,10 +131,12 @@ ### Detail levels
- **Level 0: Summary output only** - **Level 0: Summary output only**
- This will display an aggregate total of certain logged elements. It will - This will display an aggregate total of certain logged elements. It will
display the total number of hostnames (A and AAAA) that are already display the total number of hostnames (A and AAAA) that are already
up-to-date, those that needed updated, those successfully updated and the up-to-date, those that needed updating, those successfully updated and
total number of errors (or any type) encountered by the script. All the total number of errors (of any type) encountered by the script. All
totals are relative to the reporting period Logwatch is using (--range 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 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 match the number of needed updates and no errors logged, then things are
working properly. If you notice errors, you should consult the full working properly. If you notice errors, you should consult the full
@ -151,7 +153,9 @@ ### Detail levels
messages such as the detected IP address and the specific names of any messages such as the detected IP address and the specific names of any
hostnames not found in your Cloudflare account, etc. This level of hostnames not found in your Cloudflare account, etc. This level of
reporting is useful in diagnosing why errors are occurring or if you just 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 make your Logwatch reports longer and consume more of your time to
review. You should not use this level day-to-day.** review. You should not use this level day-to-day.**
- **Levels 6+: Complete log file dump** - **Levels 6+: Complete log file dump**
@ -159,7 +163,9 @@ ### Detail levels
script to dump the entire log file out to Logwatch line-by-line. This is 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 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 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.** to see the entire log file and cannot otherwise access the log file.**
## Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere) ## Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere)
@ -167,15 +173,15 @@ ## Timestamp processing script (/etc/logwatch/scripts/shared/sqfullstampanywhere
This is basically a modified version of the '*applyeurodate*' script that comes 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 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 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 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**' file. There are two lines you need to modify to suit your new '**stamp**'
variable. variable.
### The time format specification ### The time format specification
SearchDate is the variable used in the PERL script to do exactly what it says, '*$SearchDate*' is the variable used in the PERL script to do exactly what it
search for the date stamp. I have it set up to look for the format 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 '*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. anything here, we're just defining the format of the date/time stamp.
@ -187,7 +193,7 @@ ### The time format specification
If you changed the '**stamp**' variable so it was formatted as '*month/day/year 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** 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 ```Perl
... ...
@ -242,13 +248,13 @@ ## Testing
names for everything): names for everything):
```Bash ```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 logwatch --service cfddns --output stdout --format text --range all --detail 0
# Minimal detail yesterday only # Minimal detail, yesterday only
logwatch --service cfddns --output stdout --format text --range yesterday --detail 1 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 logwatch --service cfddns --output stdout --format text --range today --detail 5
``` ```
@ -256,5 +262,5 @@ ## Final thoughts
That's it! I'm a horrible PERL programmer so if anyone can optimize/improve the 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 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 :-) monitoring :-)