NagVis Extending

This section reviews NagVis Extending.

Add own Iconsets
Example

Your boss is coming in and telling you that a technician needs a map with more than
250 hosts clearly laid out. You think: Hey, thats not possible, with a full description
for every host! The font in the background image is not the problem, but the
std_small-iconset from NagVis is too big for such a request.
Solution

Build your own iconset.

What is an iconset?

A complete iconset consists of 11 files. These files are png images which are named
like this:
Filename

Description

<set>_ack.png

Acknowledged problem

<set>_error.png

Error while fetching status

<set>_unknown.png Unknown state

<set>_critical.png

Critical state

<set>_ok.png

Ok state

<set>_up.png

Up state (Host)

<set>_down.png

Down state (Host)

<set>_sack.png

Acknowledged problem (Service)

<set>_warning.png

Warning state

NagVis checks for the <set>_ok.png image to list the iconsets, meaning there has to
be a <set>_ok.png image to have a complete iconset which can be choosen in WUI.
Which Programme Should I Use To Create an iconset?

Almost every graphic art software has the ability to build PNG-files. In this example
Photoshop is used to create a smaller version of the std_small iconset called std_mini.

Iconset

Icon Size

Icon Map

std_small 1616 pixel

mini

99 pixel

Implementing the iconset

To implement the set in your NagVis installation, copy all files to the iconset folder. It is
in:
/usr/local/groundwork/nagvis/images/iconsets
The Test

Open one of your maps and add a new host-icon. You should now be able to select the
iconset:
std_mini

Add Own Shapes

You can add "stateless Icons" to your maps, we call them shapes. These icons are
completely like the other icons, they just have no state.
What is a Shape?

A shape is nothing else than a simple image. We recommend to use PNG as format for
the shapes.
Which Programme Should I Use To Create a Shape?

Almost every graphic art software has the ability to build PNG-files.
Implementing the Shape

The shapes are placed in:

/usr/local/groundwork/nagvis/images/shapes

Just copy them to this directory, then you can use them in your maps.
The Test

Open one of your maps and add a new shape-icon. You should now be able to select
your own shapes.
Language File Format
General Information

The GroundWork language settings are taken by default from your language settings in
"My Preferences". The language format are gettext language files. For details about
gettext see the official gettext page.
The language files are stored in the language specific subdirectories:

/usr/local/groundwork/nagvis/share/frontend/nagvis-js/locale

The english language file is:

en_US/LC_MESSAGES/nagvis.mo

The files with .po extension are the sources which have to be compiled to .mo files.
By default the following languages are supported in the current NagVis versions:

english
german
french
spanish
brazilian portugese

Any other language setting outside the above will default to English.
Build Your Own

Your language is not supported by NagVis? No problem! You can easily build your own
language file.
If you built a new language file or fixed sth. in existing language files you're welcome
to submit the file to us so we can implement it in the next NagVis release or publish it
on Nagvis.org.
Macros

There is support for replacing given strings with some other values.
An example for a macro is the string [USER]. This string will be replaced before
displaying in NagVis when the language entry supports it.
Default Macros

Default Macros are sth. like HTML-Tags which don't have to be defined by the user. At
the moment the following default macros are supported:
Macro Replaced by
[i]

<i>

[/i]

</i>

[b]

<b>

[/b]

</b>

Special Chars

Special chars like ,,,",',... have to be set as HTML-entities (e.g. &nbsp;)

Install Templates
You can add templates to customize the look of header- and hover-menus. You can get
some of these templates at the NagVis template download page.
The directory structure changed between the NagVis version several times. So
there may be compatibility problems between the versions.
Unpack Template

Unpack the NagVis template in a path of your choice.

tar xvzf NagVis-Template-<name>-<version>.tar.gz
Install NagVis-Template

Merge the NagVis-Template directory tree with your NagVis Folder:

Default:
/usr/local/groundwork/nagvis/share/userfiles/templates
cp -r nagvis /usr/local/groundwork/nagvis/share/userfiles/templates
Configure

Now you should be able to use the new template in NagVis. You only have to configure
the maps or objects to use the template.
Header-Templates

You can set the header template in the main configuration of NagVis or in the global
section of the map configuration. For details see NagVis Configuration.
Hover-Templates

You can set the hover template in the main configuration for all your maps, in the
global section of a map for all the objects on this map or in each object for having a
custom hover menu for special objects. For details see NagVis Configuration.
Custom Context Menu Actions
Introduction

The context menus basically are right-click menus on the status icons. You can
customize these menus by simply editing some template files. The template files are
simple html files including some macros which are replaced during render time in
NagVis.
The context menus give you the ability to improve your administrative workflow with
the monitoring information dramatically. Imagine you have a NagVis map as the
primary user interface to gather status information about your systems and even as a
base to control your systems. Imagine you can view status information from NagVis
and simply connect to the problematic systems by ssh or via terminal session by just
two clicks. It is also possible to store some default recover jobs in scripts or anything
else.

Take a look at this guide to get some ideas of the power of this new feature.
Quick How-To

This is a quick how-to to add a "connect by ssh" option to the NagVis hosts context
menu. Most of the changes have to be made on the client browsers to get it handle ssh
connections. In this guide I am using the firefox on Ubuntu. It is no problem to get this
work on other systems like Windows.
1. Read basics about context templates
2. Create custom context template
Just copy the default context template:
cd /usr/local/groundwork/nagvis
cp share/userfiles/templates/default.context.html
share/userfiles/templates/default-ssh.context.html

Now add a line to the host specific macro section like follows:
<li><a href="ssh://[address]">[lang_connect_by_ssh]</a></li>

The template is finished.

3. Configure host to use the new template
Set the option to use the new template called default-ssh:
context_menu=true
context_template=default-ssh

You can set this option in the global section of a map, in a host object or even a
template which is used in a host object.
4. Configure your client to handle ssh:// uris
In this case I configure firefox on Ubuntu Linux. This may differ on your system.
Open about:config in your firefox. Add some new options:
Name: network.protocol-handler.app.ssh
Type: String
Value: /usr/local/bin/ssh-connect-handler
Name: network.protocol-handler.expose.ssh
Type: Boolean
Value: true
Name: network.protocol-handler.external.ssh
Type: Boolean
Value: true
Name: network.protocol-handler.warn-external.ssh
Type: Boolean
Value: false

5. Create a handler script

Create the script at the given script path. In my case it is: /usr/local/bin/sshconnect-handler
#!/bin/bash
xterm -e ssh ${1#ssh:\/\/*}
You need to make this script executable.

chmod +x /usr/local/bin/ssh-connect-handler
6. Test handler script:
Just enter ssh://<test-host> in your browser address bar and press enter. If an
xterm with the ssh session opens everything is ok here.
7. Test context links:
Now open the map you configured the new context template usage. Then rightclick the host you configured and hit the menu entry "Connect by ssh". A
terminal window should open now.
Perspective

With this knowledge you are ready to configure NagVis to be the core of your daily
administrative and monitoring tasks. Be creative now!
We like you to give us some feedback on this feature and how you use it.