# Installation instructions

This instructions are meant for a new installation. If you update your old NagVis installation we strongly recommend to make a backup of your NagVis Directory and merge the config files manually.

## STEP 0: Prepare System

Make sure your System fits the System requirements.

## STEP 1: Download NagVis

Get NagVis, the latest release can be found at www.nagvis.org.

## STEP 2: Unpack NagVis

    tar xvzf nagvis-1.5.x.tar.gz

## STEP 3: Move the unpacked NagVis directory

Place the NagVis directory tree somewhere on your system. For most case `/usr/local/nagvis` is the best place.

    mv nagvis /usr/local/nagvis

You should see the following directory listing:

    # ls -l /usr/local/nagvis
    etc
    LICENCE
    README
    share
    var

DON'T move any files or folders inside the NagVis directory (in fact you can move, but in this case you have to change/add some parameters and values in the main config file - if everything is left untouched it should run "out of the box" without changes in the configuration files)

## STEP 4: Configure NagVis

Move to new NagVis directory

    cd /usr/local/nagvis

An example main configuration file can be found in `etc/nagvis.ini.php-sample`. If you like to change some settings, copy this example to `etc/nagvis.ini.php`.

    cp etc/nagvis.ini.php-sample etc/nagvis.ini.php

Now you can edit this file with your favourite text editor - I use vi:

    vi etc/nagvis.ini.php

Most lines in the fresh copied `nagvis.ini.php` are commented out. If you want to set different settings, you can simply uncomment the line and change its value. For information about the possible values have a look at Main Config Format Description.

## STEP 5: Configure webserver

Since NagVis 1.5 it is necessary to configure the webserver to be able to use NagVis. You will find a sample configuration file in `etc/apache2-nagvis.conf-sample`.

Simply copy the file to the `conf.d` directory of your webserver. For example this is `/etc/apache2/conf.d</code.</p>`

    cp etc/apache2-nagvis.conf-sample /etc/apache2/conf.d/apache2-nagvis.conf

Now you need to open that file and edit it to fit your needs. It is important to replace the macros `@NAGVIS_WEB@` and `@NAGVIS_PATH@`.

In this example you need to replace `@NAGVIS_WEB@` with `/nagvis` and `@NAGVIS_PATH@` with `/usr/local/nagvis/share`.

## STEP 6: Permissions

This is very important for a neatly working installation. First check which unix user account is used to run your webserver (in my case it is `wwwrun`). If you don't know which user the webserver is running then have a look at the webserver configuration. In case of Apache you can do this by the following command:
Ubuntu

    grep -e 'USER' /etc/apache2/envvars

SuSE/RedHat/Debian

    grep -e '^User' /etc/apache2/*.conf

If your configuration file is located at another path you should correct this in the command above. Set the permissions to your NagVis directory (in my case the paths are like this):

    chown wwwrun:www /usr/local/nagvis -R
    chmod 664 /usr/local/nagvis/etc/nagvis.ini.php
    chmod 775 /usr/local/nagvis/etc/maps
    chmod 664 /usr/local/nagvis/etc/maps/*
    chmod 775 /usr/local/nagvis/etc/automaps
    chmod 664 /usr/local/nagvis/etc/automaps/*
    chmod 775 /usr/local/nagvis/share/userfiles/images/maps
    chmod 664 /usr/local/nagvis/share/userfiles/images/maps/*
    chmod 775 /usr/local/nagvis/var
    chmod 664 /usr/local/nagvis/var/*
    chmod 775 /usr/local/nagvis/var/tmpl/cache
    chmod 664 /usr/local/nagvis/var/tmpl/cache/*

It's possible to set even lower permissions on the files but for most setups the example should be fine. Only change them if you know what you are doing!

## STEP 7: The graphical config tool (WUI)

NagVis has an included web based config tool called WUI. If you want to use it use your browser to open the page:

    http://<nagiosserver>/<path-to-nagvis>/frontend/wui/index.php

(i.e. http://localhost/nagvis/frontend/index.php).
Hint: If you have some script or popup blockers, disable them for the WUI.

When you see the NagVis image, right click on it, then a context menu should open and now you can configure NagVis and create maps with the WUI.

The Config Tool DOES NOT display the current Nagios states of objects configured. It's only for configuring! To "use" your configured maps afterwards see STEP 8!

If this doesn't work for you or if you don't want to use the WUI, you can simply edit the map config files in the `etc/maps/` directory with your favourite text editor. For valid formats and values have a look at Map Config Format Description.

## STEP 8: View the maps

You should now be able to view your defined maps in your browser:

     http://<nagiosserver>/<path-to-nagvis>/frontend/nagvis-js/?mod=Map&show=<mapname>

(i.e. http://localhost/nagvis/frontend/nagvis-js/?mod=Map&show=europe).

Have fun and please report bugs!