nsc(1) - Linux man page

Name

nsc - colourized console-monitor for Nagios

Description

nsc allows you to monitor Nagios services without the expense or availability of a GUI .

Features

Support for Nagios 1.0, 1.1, 1.2 and 2.0b3
Realtime display of Nagios status
Uses colouring/highlighting for troubled items
Low-bandwidth fullscreen display works on any tty; if vi works, nsc probably does too
Displays all essential Nagios status info on a single screen
Clean & simple display & usage
Adjustable display layout
Requirements
nsc runs on Unix and look-alikes - I test on Linux, Solaris & FreeBSD
Read-access to Nagios status.log
Perl 5.x
Curses libraries installed (ncurses may be required)
Perl 'Curses' module, available from CPAN

Synopsis

nsc.pl [options] [statuslog]

If a statuslog isn't specified on the commandline, nsc will use the one from your ~/.nsc.conf.

Options

--term=

When using this option, the terminal type is changed:

nsc --term=vt220

This is the same thing as "env TERM=vt220 nsc".

-T Disables the terminal type replacement logic (described later in this document).

-h, --hosts=

If this option is given, nsc will filter out all hosts and services for hosts not matched by the --hosts list - this will only show items from the hosts calvin & hobbes:

nsc --hosts=calvin,hobbes

Wildcards are available using either "*" or "%":

nsc --hosts=*.myowndomain.com
nsc -h firewall,%proxy%,router%

Examples

To do a quick test-run, you can use the enclosed example status.log - run nsc as:

./nsc.pl nag1-status.log

This won't give you the live display from Nagios, of course. The example status.log's are in the /usr/share/doc/nsc* directory, if you installed from the rpm package.

Colours

The environment variable "TERM" is used to determine the terminals abilities. If the terminal type indicates that the terminal has colour-support, nsc will switch colours on. If the terminal capabilities are monochrome only, nsc uses underline, bold, etc. instead of colours.

If you see no colours in nsc, it is very likely that your $TERM variable indicates a monochrome terminaltype (like vt100). See below for how to get around this.

What colours?

Unfortunately, on Unix terminals, colours do not "just work". Monochrome mode works fine (when $TERM is about right), whereas nsc with enabled and properly working colours often requires a tweaked $TERM-setting.

The reasons for this are historic. Before personal computers, we had dumb terminals and most often, they had a green or amber monochrome display. This is what Unix terminal handling is geared towards, although today most of us have 16.7 million available colours at the desktop. So often we end up with a terminal type that won't do colours, usually due to settings on either the host OS or in the terminal application.

Getting colours working is usually just a matter of setting $TERM right - you may just need to start nsc a bit differently, for example:

nsc --term=xterm-color

Replacing terminal types

If you like your nsc to be in colours and are tired of fudging your $TERM value to get them, then nsc can be setup to replace the $TERM value with another terminal-type, if you tell it to do so in your .nsc.conf. For instance, if you add:

term.linux.vt220=xterm-color

.. then when you run nsc on Linux with TERM=vt220, nsc will replace vt220 with xterm-color instead. The operating system name is retrieved from 'uname -a' - nsc uses the first word and lowercases it, before looking for a replacement terminal type.

nsc knows about a number of terminal mappings - add others as needed to the .nsc.conf file.

Linux (Mandrake 9.1-10.2, RH9 ): Within putty/screen, "TERM=xterm-color" works well.
Solaris 9: "TERM=xterm-color" works, at least for putty/screen. CDE will likely work too with this setting.
FreeBSD 4.7: "TERM=vt340-color" works as advertised (putty/screen).
"works" as advertised" means that nsc will produce colour and that it looks right, specifically regarding producing an even-coloured background.
The above list is much shorter than what nsc actually will work with. So if you find new platform/terminal combos that just works, including colours, please send me info (nsc@gothix.biz) about it, so that I can incorporate the mappings in future nsc versions.
Colour configuration
Edit $HOME/.nsc.conf to change the colours. The default colours are commented out, so remove the '#' in front of any changed lines.
The "!normal" colour/attribute refers to the 'normal' colour/attribute and is just a shorthand to avoid specifying 'white on magenta' seven times.

Remote Nagios - Monitoring Nagios On Another Host

This allows you to run nsc on one host and monitor Nagios running on a different host. To make nsc access a remote status.log, just prefix the filename for the status.log with the remote hostname and a colon:

nsc my.host.net:/usr/local/nagios/var/status.log

This will use the remote filename from the commandline together with your existing settings from .nsc.conf. You can also set the remote filename in .nsc.conf (keyname 'nslog'). Another approach is to install various aliases in the shell:

alias nsc1='nsc my.host.net:/usr/local/nagios/var/status.log'
alias nsc2='nsc nagios.host2.com:/var/opt/nagios/var/status.log'

You will get the best results with the remote Nagios feature, if you ensure that the involved hosts have their clocks synchronized (using NTP or similar).

The remote copy interval may be changed in .nsc.conf - the default is 60 seconds and it may overridden with the keyword 'remote.copy_interval'.

Configuration

When nsc is accessing a remote status.log, it copies it to the local host once a minute and then displays it as usual.

The default remote.copy_cmd setup requires that:

- You have rsync(1) installed
- You have ssh installed (OpenSSH or similar)
- You can login to the Nagios host using ssh without specifying a password

If these conditions are met, then you are ready to go - just run nsc:

nsc remote.host.org:/path/to/nagios/status.log

If you want to access the remote status.log by other means than rsync/ssh, edit ~/.nsc.conf and specify a different remote.copy_cmd. This command should work for a pure ssh-/scp-setup with no rsync:

remote.copy_cmd=scp -q -p -C %H:%F %D >%L 2>&1

%-tokens available are:

%H => Hostname
%F => Remote filename
%D => Local destination filename
%L => Logfile for output from the copy command.

In case of difficulties, try out the copy command in the shell - to test the above scp setup, use something like:

scp -q -p -C my.host.net:/usr/local/nagios/var/status.log /tmp

You should get no output, no errors and /tmp/status.log should now be identical to the file on the remote host. The return value should also be zero, check it with 'echo $?' after executing the copy command. If the scp command works and you have rsync installed, then the default remote copy setup with rsync should work as well.

If problems arise, check the logfile from the copy operation:

ls -lt /tmp/status* │ head -10

Looking at the logfile needs to be done whilst nsc is running as it removes the logfile, when cleaning up on exit.

The above examples are based on ssh access to the Nagios host, but you can almost as easily use http and wget(1) to retrieve a remote Nagios status.log - or any other script or program that can retrieve a plain file from another host.

Various

Mapping external commands to keys

This is done with 'usercmd_X' in your ~/.nsc.conf - see .nsc.conf for an example (top). For example, to edit and reload the Nagios services.cfg file with the 'V' key from within nsc, add this to .nsc.conf:

usercmd_V=$VISUAL /usr/local/nagios/etc/services.cfg; /etc/init.d/nagios reload

Sorting

The 'h' key turns toggles sorting by hostname on/off. While on, sorting will be done by hostname, status and service. If off, sorting is done by status, hostname and service.

Any of the above may be reversed with 'r' :-)

Auto-roller

The "auto-roller" is the logic that automatically pages nsc through the services monitored by Nagios and it is controlled by these parameters in .nsc.conf:

roll_wait: 'roll_wait' is the number of seconds to wait since last keypress until rolling starts.
roll: 'roll' is the time in seconds between shown pages - if this is set to -1, then rolling will be disabled.

Files

~/.nsc.conf is used to store per-user settings.

Various other (Nagios) files are also used - you may edit ~/.nsc.conf as needed to reflect proper placement of these files.

Environment

Several environment-variables are used, but only ' HOME ' is required.

EDITOR: The text editor (program) to be used for editing files, such as hosts.cfg. Defaults to 'vi'.
VISUAL: VISUAL is used in preference to ' EDITOR ' if set (visual editor).
PAGER: For viewing files, such as status.log, defaults to 'more'.
HOME: Where nsc expects to find your .nsc.conf.

License

nsc and its accompanying modules distributed under the Perl Artistic License, perlartistic - this means that it is free to use for everybody.

If you include nsc with a Linux distribution or create a package for it for another platform, you should let me know. Obviously, I'm interested in how nsc is doing and where it goes, so please do drop me a mail at input@gothix.biz with a couple of words on what you are doing - thanks.

Versions prior to v0.80 (april, 2005) were distributed under the GNU General Public License and those versions may be used as per the GPL license.

SUPPORT, DOWNLOADS, HOMEPAGE

Downloads are available via <http://www.freshmeat.net> - project name 'nsc':

L<http://freshmeat.net/projects/nsc/>

Beta-versions are available through the nsc homepage:

L<http://nsc-gothix.sourceforge.net/>

There is a mailing-list available hosted by Yahoo Groups:

L<http://groups.yahoo.com/group/nsc-users/>

Send mail to <nsc-users-subscribe(at)yahoogroups.com> to join.

I will be posting annoucements of new versions to the mailing list (also regarding beta-versions) and everybody else should feel free to use the group for anything nsc'ish. If you need help using nsc, please write to the nsc-users list/group instead of writing me directly.

Author

Written by Stig H. Jacobsen <nsc(at)gothix.biz>

Please use the mailing list (see above) for nsc support. Thanks!