README for version 1.3 - Introduction The "Network Services Monitoring Framework" (NSMF) is an open source host and network services monitoring tool. Think of it as a lightweight "Nagios" (http://www.nagios.org/), if you will. Many people who do not have the time to get Nagios working or require its many features have found NSMF sufficiently featured for their needs. Look for updates on http://www.bogus.net/~torh/. There is a mailing list at http://bearclaw.bogus.net:8081/mailman/listinfo/nsmf-discussion for chatter about bugs, new features, likes, dislikes and so forth. At present, there is no nsmf-plugins list, but this might be a consideration if enough talk warrants it. NSMF is copyright (c) 2006 Tor Houghton. Consider this release having a GNU GPLv2 licence. For more information, read http://www.gnu.org/copyleft. Skip to "Quickstart" if you don't want to read the propaganda. - Features Simple design - one engine, one configuration file with support for plugins written in any programming language (current release uses ones written in Perl). Overall status is provided as a web page with support for changes to service status by SMTP mail. GSM SMS support is being worked on. It's free. If it is not free enough for you, let me know. - Requirements The NSMF daemon requires Perl to function. Many UNIX distributions will ship with a reasonably recent version of Perl by default. NSMF was developed on Mac OS X and OpenBSD 3.x respectively. Some of the plugins require OpenSSL, but again, many UNIX variants these days will ship with this by default. You can test a plugin by invoking it manually, e.g.: bash$ cd bash$ plugins/https.pl www.example.com - Plugins The current plugin set includes: ftp.pl - FTP service test http.pl - HTTP service https.pl - HTTPS service (requires openssl) icmp.pl - simple ICMP echo nessus.pl - Nessus (requires openssl) openvpn.pl - OpenVPN (requires openssl) smtp.pl - SMTP smtptls.pl - SMTP/TLS ssh.pl - SSH tcp.pl - arbitrary TCP port (open/closed) - Quickstart 1) Untar the archive to a directory and user of your choice. Avoid installing and running NSMF as root; it does not require elevated privileges. The archive should contain this file, a default configuration file, the NSMF daemon and two directories: img/ and plugins/. 2) Create the web page document root (e.g. /var/www/htdocs/nsmf). By default, NSMF uses /tmp. 3) Change the 'html_path' in the configuration file (nsmf_hosts.txt) to reflect your choice of documentroot. E.g.: html_path = /var/www/htdocs/nsmf 4) Copy the img/ directory (and its contents) to the path reflected by the html_path variable in the configuration file. If you do not do this, there won't be any shiny lights in your web report. 5) Change the 'smtp_server', 'admin_email' and 'notify_group' variables to reflect your site configuration. If you do not want or need SMTP mail notification, remove (or comment out) any of the above mail configuration variables. E.g.: smtp_server = smtp.example.com admin_email = nsmfadmin@example.com notify_group = david@example.com If you have more than one person you wish to provide email notification to, comma separate them. E.g.: notify_group = david@example.com,darcy@example.com 6) Decide which servers and services need monitoring. It is not necessary to include the icmp.pl plugin (especially for those hosts behind a filtering firewall). E.g.: ; does the router respond to ping? router.example.com { plugin ISUP icmp.pl } ; are the smtp and smtptls services running? smtp.example.com { plugin ISUP icmp.pl plugin ISUP smtp.pl plugin ISUP smtptls.pl } ; does the login server answer to SSH on port 222? login.example.com { plugin ISUP icmp.pl plugin ISUP ssh.pl:222 } 7) Start the NSMF daemon. E.g.: bash$ ./nsmfd.pl 8) Point your browser to the reporting page (http://www.example.com/nsmf/ or file:///tmp/index.html if you did not change the default html_path). - Configuration There is one configuration file (per running NSMF process). The default file, nsmf_hosts.txt, contains many of the configuration options in use, and how to use them. Comments are distinguished by a semi-colon (';') and permitted on a line of their own. E.g.: ; a legal comment www { ; an illegal comment } Most variables in global mode may be used in 'local' or 'host' mode and overrides the global setting for that host - this means that you can have different notify_group settings for different hosts, for example. One notable exception to this rule is the 'html_path' variable (to provide per-host reporting, separate NSMF processes are currently required). E.g.: notify_group = admin@example.com,wwwadmin@example.com ; only send notifies to francine for test.example.com test.example.com { notify_group = francine@example.com } ; admin & wwwadmin get notifies for www.example.com www.example.com { } Two timer variables are used; 'report_interval', which is used to determine how often the reporting is done (HTML/SMTP) and 'sample_period', which is used to determine how often to check a service. The report_interval variable may not be used locally (this may change if enough people drive through a per-host html_path), but 'sample_period' can. Both sample_period and report_interval are given as seconds: E.g.: ; set report_interval to 3m report_interval = 180 ; set sample_period to 1m sample_period = 60 ; check services on test.example.com every 5 seconds test.example.com { sample_period = 5 } Email notification (which appear to be originating from 'NSMF Daemon') requires three (3) configuration parameters to be set; smtp_server,admin_email and notify_group - if any of these are absent, email notification will not be enabled. E.g.: smtp_server = localhost admin_email = nobody@bogus.net notify_group = foo@bar.com,admin@test.bogus.net,www@test.net Each server entity is defined in a bracketed fashion as shown in the above examples (and below). E.g.: hostname { = plugin } The parameter 'hostname' may be the fully qualified domain name, or a symbolic name. If a symbolic name is used, however, it is imperative that the 'address' parameter is defined for this host. 'address' must be a value that can either be resolved by the resolver library or an IP address. E.g.: DNS { address = dns.example.com } TEST { address = 172.16.32.128 } The 'plugin' parameter takes two options; a 'type' and the actual filename used in the plugins/ directory. Currently only one type is supported ('ISUP'). Many plugins support an optional parameter (future versions may support many parameters if required). The 'tcp.pl' plugin, for example, which does a simple 3 way handshake on an arbitrary TCP port, is used as follows: server.example.com { plugin ISUP tcp.pl:80 plugin ISUP tcp.pl:6667 } - Running NSMF Once the configuration file has been edited to support your setup, you can do one of two things. If you edited the default file (nsmf_hosts.txt), you could start NSMF by invoking it without any parameters: bash$ ./nsmfd.pl Or, if you have created the configuration file elsewhere, use the '-c' command line switch to direct the NSMF daemon to it: bash$ ./nsmfd.pl -c /etc/nsmf/nsmf.conf The '-n' switch will instruct NSMF to hide the host names/addresses (as defined through the use of the address keyword) in the HTML output. Issue a '-h' parameter for help and more options for executing the NSMF daemon. - Parameter overview The following shows the recognised parameters, their scope and default values (if any). Name Scope Type Default address local hostname, ip address - admin_email local, global single email address - html_path global directory /tmp notify_group local, global email address(es) - plugin local ISUP - report_interval global seconds 180 sample_period local, global seconds 60 smtp_server local, global hostname, ip address - - Writing plugins Plugins can be written in whatever language you are familiar with. Essentially they are all stand-alone pieces of code that provide output in a common format. Currently, a plugin may only be of type "ISUP" (e.g. it may only provide a "boolean" result). Future versions of NSMF may contain other types, for use with traffic graphing, for example. The current version of NSMF expects the ISUP plugin to provide output in the following format: TYPE:RESULT[,INFO] TYPE may be any string except "NOEXEC" which is reserved for use when the plugin has suffered a 'hard error' (e.g. an executable isn't found, for example). Currently the 'TYPE' field is normally the protocol tested ('SSH' for the ssh plugin, say). RESULT should be 0 (failure, service could not be reached) or 1 (success, service operational). INFO may be included in the output if clarification of the result is needed for the reporting. One example of this is the output from the 'tcp' plugin, where it is also useful to know which port has been probed: TCP:1,80 The plugin format is not set in stone, but appears to suffice for now. - To do / future work Alerting; change the way alerting works - currently, alerting (via email/SMS) only occurs during the reporting phase (for consistency), not as a result of a sample. Daemon mode; or is backgrounding the task good enough? SMS support; the SMS gateway engine has been written, but requires some testing and integration work (all work done using a Nokia GSM data card). A day job, family and many other interests limits the time and effort I can put into this (options for its development can be discussed! :-). Plugins; new plugins are always welcome (especially plugins that work at the application layer). Some of the plugins in this release also require more work in that they do basic availability testing (and relying on third party tools). Graphics; any aspiring artists out there? The reporting page looks fairly drab. Documentation; more documentation (and probably the way it is written)! Historic data; enabling and making use of the historical data feature (e.g. for use checking against an SLA for statistics purposes). Web-based interface; enabling configuration through a browser-based interface.