This document describes how to install and setup the Nagios V-Shell or Visual
Shell for Nagios Core and Nagios XI installations.  


Target Audience
---------------

This document is intended for use by Nagios XI and Nagios Core Administrators, 
and assumes that Nagios Core is installed on the target system.    


Overview
--------

The Nagios V-Shell is a web interface written in PHP that is designed to render
as valid XHTML and be fully styled and formatted using CSS classes, while 
maintaining the power of Nagios Core for issuing system and node commands.  


Installation 
------------

Prerequisites:  

V-Shell requires apache and php 5.x already installed in the system, as well as php-cli if it's not already there. 

You will need to know the location of Apache configuration directory where your
nagios.conf file is located, as well as the htpasswd.users file that contains 
your Nagios Core authorizations.  These can be found using the following 
command: locate <filename>


V-Shell takes advantage of the Alternative PHP Cache system (APC), which is 
of particular importance if you are managing a large installation.  For 
information about APC and installation instructions see 
  http://php.net/manual/en/book.apc.php
  
  RHEL/CentOS/Fedora: yum install php-pecl-apc
  Ubuntu/Debian		: sudo apt-get install php-apc
  

To install:
Download and untar the latest V-Shell tarball from:
  http://assets.nagios.com/downloads/exchange/nagiosvshell/vshell.tar.gz

To download the latest code from Subversion
  https://nagios.svn.sourceforge.net/svnroot/nagios/nagiosvshell/trunk

(The defaults are appropriate for a Nagios install from SOURCE on CentOS / RHEL.)
If necessary, to modify your apache configuration, modify the contents of the
config/apache_vshell.conf file to match the directory structure of your distribution
and your installation of Nagios BEFORE running th install script.  Use a text
editor to modify this file as needed, then copy this file to the same directory
as your nagios.conf file.

Run the following with root permissions:

cd /tmp
wget http://assets.nagios.com/downloads/exchange/nagiosvshell/vshell.tar.gz
tar zxf vshell.tar.gz
cd vshell

Verify or Modify the following two lines in install.php to match your installation (lines 10-15)	
		define('TARGETDIR',"/usr/local/vshell");
		define('APACHECONF',"/etc/httpd/conf.d"); 	
	
chmod +x install.php	
./install.php  #located in the root vshell directory where the web files are stored 


After running this script, be sure to verify the location of the files specified in the /etc/vshell.conf file,
as well as the location of the htpasswd.users file that is specified by your apache configuration.
    
These will be required in order for V-Shell to run correctly.

For problems or support, use the V-Shell forum at the following address:
http://support.nagios.com/forum/viewforum.php?f=19


Configuration
--------------

*Important Notes*:
For custom configurations with Apache, changes may need to be made to the 
/etc/vshell.conf file, which contains variables for the V-shell URL, 
as well as the Nagios Core cgi's.  

V-Shell assumes that your Nagios Core installation can be accessed via 
http://<servername>/nagios.  If your configuration differs from this, make 
changes are appropriate to the /etc/vshell.conf file.  If errors occur after 
installation, verify that the constants point to the correct web URLS.  

You may need to update the location of htpasswd.users file in the apache configuration file.
For Ubuntu/Debian users on a nagios3 install this file will be at /etc/nagios3/htpasswd.users.

Default Apache Configuration Locations:
	RHEL/CentOS: /etc/httpd/conf.d/vshell.conf
	Ubuntu/Debian: /etc/apache2/conf.d/vshell.conf 
 

Future versions will include a separate config file and possibly a wizard to 
verify system configuration.  


Getting Started
---------------

Nagios V-Shell gets authorization information from the existing Nagios / Apache
access controll mechanisms (usually a htpasswd.users file), as well as the 
cgi.cfg file for Nagios Core.  Most permissions for Nagios Core should be 
reflected in the Nagios V-Shell as well.  To get started, log into your Nagios 
webserver at http://<yourserver>/vshell, and enter your Nagios Core 
authentication information. Nagios V-Shell requires a valid user defined in 
the /path/to/nagios/etc/cgi.cfg file in order to display information for hosts and services.
 NOTE: V-Shell needs a username from either an apache authentication method or the name 
need to be hard-coded into the index.php file.  See the code comments for the hard-coded option.  

V-Shell maintains most of the same features of Nagios Core, while utilizing 
a top menu bar for site navigation.  This is done to maximize space for table 
viewing for hosts and services.  

Nagios Core system commands, reports, and the Core interface can all be 
accessed by direct links from V-Shell. 


Internationalization
---------------------
V-Shell as of version 1.7 has implemented gettext support for internationalization.  
New language files can be created and stored according the following convention:
For English:
	vshell/locale/en_EN/LC_MESSAGES/en_EN.mo
	vshell/locale/en_EN/LC_MESSAGES/en_EN.po
	
The default language set can then be specified in the /etc/vshell.conf file:
	LANG = "en_EN"


Getting Help
------------------
For problems, feeback, or support, use the V-Shell forum at the following address:
http://support.nagios.com/forum/viewforum.php?f=19



Developer Notes:

We're looking for people who want to contribute to the V-Shell project, see the TODO file for more information.   
