menuimage

Description

Usage

Example

Options

Conf_file

Conf_file_Example

Conf_line

Files_created

Further_information

License

Changelog

Download

Donation

My_Other_Sites

My_Programs

Comments

tiny-device-monitor v4.6.2 [22 Jul 2024] - by Dominic

Description

tiny-device-monitor.sh is a lightweight network monitoring program - see https://en.wikipedia.org/wiki/Network_monitoring, and runs under Linux. It's called 'tiny' because it's little, but sometimes the best things come in small packages!

It can be used for testing internet or intranet websites, mail servers, local or remote servers / computers, and peripherals such as printers, switches, wireless access points etc.

Based on the conf file you create (one line per device - example below), or the quoted conf_line on the command line, it checks a list of machines and/or webpages for a response i.e. that they are live. For a webpage, it uses wget to check that the response includes some specified key_text; otherwise, it uses ping or, if a port number is specified, nmap. It can also test for authenticated access to mail servers.

It can be run with -cq as a cron job at regular intervals, say every 5 minutes, and it will generate some text as a warning if any of the monitored devices go offline - cron can then send this to you as an email.

Usage

tiny-device-monitor.sh [options] [conf_file || conf_line]

Example

./tiny-device-monitor.sh -q

Options

-c report only a change in status i.e. from failure to success or vice-versa (to reset i.e. to generate a report the next time the same conf parameters are tested with -c regardless of status, delete the appropriate log file from /var/tmp)
-f force mode - test all sites, including subtests that would normally be excluded
-h see this help text and exit
-l see changelog and exit
-n suppress header and final text
-s with -c option, report a failure only if it is repeated a consecutive time
-v verbose text output
-q quiet - text output only for a failure or status change

Conf_file

conf_file (default is tiny-device-monitor.conf in same directory as the running instance of tiny-device-monitor.sh) contains text lines with 2-4 fields like this (where square brackets indicate optional text):

[+/-]address[:[U]port] reportname [key_text] [wget_options]

each line is evaluated for the first match below:
- if address begins with 'http' then it is a webpage test: wget is used to retrieve the page which is then tested for key_text (see below)
- if address is 'ditto' (without the single quotes) then the webpage downloaded for the most recent http test in this session is re-used as the source for this test - so you can perform multiple tests on the same webpage without having to download it repeatedly
- if address begins with 'auth:' then the rest of the address is tested as a mailserver offering STARTTLS and user authentication via AUTH PLAIN - the port must be specified after the address i.e. :25 or :587, field3 (key_text) specifies a valid username and field4 (wget_options) specifies a valid password (it is recommended but not required that you install swaks if you want to use auth: - faster and more reliable)
- if a port number is specified (format address:[U]portnumber), nmap is used (precede port number with U for UDP, otherwise TCP) - any key_text and wget_options will be ignored
- if none of the above apply, ping is used - any key_text and wget_options will be ignored
- if address is preceded by a plus or minus sign then it is a 'subtest', which is carried out only if the preceding non-subtest succeeded (+) or failed (-). Note that -f command-line option forces all subtests to be carried out regardless.

- reportname is the device's 'friendly' name i.e. that will appear in reports; any spaces in it must be escaped with \

- key_text is used for webpages (i.e. with wget) and the retrieved data is tested to check that the key_text is present; the test is case-sensitive, and spaces in key_text (or in reportname) must be escaped with \, not with quotes ("). Any characters that would need to be escaped anyway will need to be double escaped with \\. Tests are performed using sed -n, prefixing '/' and suffixing '/p', so searching is sed regex-compatible. Negative tests can be performed by prefixing '!' to the test - in these cases outcome is deemed successful if the text is *not* found. You can perform more sophisticated (e.g. multiline) tests by starting key_text with /, and expecting output only if the test is successful, e.g. to search for the word 'Registered' in the line after 'sip.voicetrading.com', use this key_text: /sip\\.voicetrading\\.com/{N;/Registered/p}

- wget_options are additional options if any for wget e.g: --http-user=myusername --http-password=mypassword

- a blank line, or any text after (and including) a hash (#), is ignored

Conf_file Example

# seek key_test 'Forbidden' on my webserver (lan-facing)
http://127.0.0.1/ internal Forbidden
# seek key_text 'My Greatest Web Site' on my webserver (wan-facing)
# (note the escaping of spaces!)
http://my.wan.ip my\ wan\ ip My\ Greatest\ Web\ Site
# if wan-facing test fails, ping-test my router lan-facing
-192.168.1.2 my_router_lan_side
# test mailserver with username postmanpat and password BlacknWhiteCat
auth:remote.mailserver.tld:587 My\ Remote\ MX postmanpat BlacknWhiteCat
# check my local network printer
192.168.1.109:9100 My\ Printer

Conf_line

Instead of specifying a conf_file you can specify the parameters for a single test on the command line. It is strongly advised to enclose them in quotes - spaces in key_text must still be escaped. It is possible to have multiple tests if all the parameters are enclosed in quotes and a \n line separator is used between tests.

Files created

A permanent results log is maintained at /var/log/tiny-device-monitor.sh.log - the directory can be modified by setting $LOG.

Temporary files during the run are stored at (and, unless the run is aborted, deleted from) /tmp - this can be modified by setting $TMPDIR.
Files recording the most recent results are stored at /var/tmp/*-new.log and /var/tmp/*-old.log for use by the -c option test.

Note that other users on the same system may be able to read these files.

Further information

When checking a webpage, tiny-device-monitor.sh checks both the page output and any output from wget - including error text - for the presence of the key_text. The downside of this is that you must guard against using a keyword that might appear unexpectedly anywhere in wget's output, but the upside is that that you can also check for specific error words. In particular, for password-protected sites, you can look for keywords returned by the site upon unauthorized access. This can be quicker than passing through the authorization username and password and means you do not have to put this sensitive data in the conf_file. For example:

http://my.cctv.website.com MyCCTV 401\ Authorisation\ Required

instead of

http://my.cctv.website.com MyCCTV i-Catcher --user=fred --password=bloggs


Exit code 99 indicates one or more destination failures.

License

Copyright © 2024 Dominic Raferd. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Changelog

4.6 [30 Jan 2024]: add -n option
4.5 [27 Jan 2024]: much closer shellcheck compliance
4.4 [26 Nov 2023]: very minor bugfix to greps
4.3 [05 May 2022]: very minor change to final line of output
4.2 [19 May 2019]: fix long-standing bug in determining whether to run sub-tests
4.1 [18 May 2019]: fixes for negative/ditto tests
4.0 [19 Feb 2019]: add date and time to text reporting
3.9 [21 Jun 2018]: fix incorrect exit code in quiet mode
3.8 [11 Apr 2018]: add negative test option
3.7 [20 Mar 2018]: use swaks (if available) for auth: tests - faster, more reliable
3.6 [01 Mar 2018]: add graceful timeout for auth: tests
3.5 [09 Feb 2018]: add auth: testing option
3.4 [16 Oct 2017]: allow single conf line on command line
3.3 [23 Nov 2016]: remove ssh option that was added at 3.2
3.2 [15 Nov 2016]: nmap skips ping scan, prevents some false positives, add ssh option
3.1 [30 Sep 2016]: some log messages were going to a wrongly-named log file
3.0 [22 Sep 2016]: remove debug message that appeared in non-debug mode
2.9 [16 Jul 2016]: change names and locations of temporary/log files
2.8 [18 Nov 2015]: add 'ditto' option to allow multiple checks on a webpage, use sed -n for pattern matching and allow complex and/or multiline testing, use uniquely-named temporary files
2.7 [02 Sep 2015]: allow http redirects but require certificate checks
2.6 [14 Aug 2015]: port-based test (nmap) bugfixed
2.5 [13 Aug 2015]: subtest (+/-) options bugfixed
2.4 [14 Jul 2015]: -s option bugfixed
2.3 [01 Jul 2015]: add -s option
2.2 [18 May 2015]: tidy up a couple of temporary files after successful conclusion
2.1 [14 May 2015]: report nmap 'open|filtered' UDP ports 'Failed', not 'Found'
2.0 [16 Jul 2014]: remove '--open' switch from nmap so it works with older versions of nmap, add UDP port test option
1.9 [18 Mar 2014]: renamed from 'websites-live-checker' to 'tiny-device-monitor' which better reflects its purpose, help text updated
1.8 [27 Nov 2013]: make change-in-status testing a command-line option, add force subtesting option, add subtest conditional on success (+ or -) - note changes required to any prior conf files, help updated
1.7 [02 Sep 2013]: small improvement to output text
1.6 [15 May 2013]: improved output text
1.5 [14 May 2013]: small change to help and output text
1.4 [24 May 2012]: small improvement to output text
1.3 [14 May 2012]: small improvement to conditional testing
1.2 [01 May 2012]: add '+' conditional test
1.1 [08 Mar 2012]: improved help text
1.0 [21 Sep 2011]: now compatible with cygwin & for non-privileged user

Download tiny-device-monitor.sh

Donation

I have provided this software free gratis and for nothing. If you would like to thank me with a contribution, please let me know and I will send you a link. Thank you!

My Other Sites

My Programs

Here is a selection of some (other) programs I have written, most of which run under GNU/Linux from the command line (CLI), are freely available and can be obtained by clicking on the links. Dependencies are shown and while in most cases written and tested on an x86-based Linux server, they should run on a Raspberry Pi, and many can run under Windows using Windows Subsystem for Linux (WSL) or Cygwin. Email me if you have problems or questions, or if you think I could help with a programming requirement.

Backup Utilities

Debian/Ubuntu kernel and LVM Utilities

Miscellaneous Programs

Comments

This section is closed. If you have a question, please submit it by email, thank you.

No comments yet for '/programs/help/tiny-device-monitor.sh.php'