Configuration and Operations

3.1 Overview

This document provides step-by-step instructions on how to configure and run NetVigil on your production environment. It is assumed that the software package has been extracted and installed into a specific directory on your server(s) as described in Chapter 2, "Installation and Upgrade Guide". In this document, NETVIGIL_HOME refers to the top level directory where the package has been extracted and will be running from.

3.2 Installing A New License Key

NetVigil components rely on a license key to indicate which features are available, and also to impose time restrictions (if any) on when the application "expires". It may be necessary to install a new license key, for example, when a permanent license key is provided by Fidelia at the end of a trial period, or when the key format changes between different versions of the application. Once a new key has been delivered, here are the steps you need to take to install the new key:

To install a new license key:
Save/copy the downloaded file as NETVIGIL_HOME/etc/licenseKey.xml. On Linux/Solaris platforms this is /usr/local/netvigil by default, and on Windows platforms this directory is \Program Files\Fidelia NetVigil.
Make sure to replace the contents of the existing licenseKey.xml with this new file.
Restart NetVigil using NETVIGIL_HOME/etc/netvigil.init restart on Linux/Solaris platforms, or Start | Programs | Fidelia NetVigil | Start Fidelia NetVigil on Windows platforms.

3.3 Starting/Stopping NetVigil

On Linux/Solaris platforms, different components of NetVigil are started and stopped using the NETVIGIL_HOME/etc/netvigil.init script. This script should be called from /etc/rc.local or other startup directory appropriate to your operating system with a parameter of start so that NetVigil components start automatically when the system reboots. Before the script can be used, you will need to edit the script and uncomment the components you would run on that particular machine. For example, if you are running the web application and DGE monitor components on the same host, netvigil.init should be edited like this:

PROVDB="N"
BVEAPI="N"
WEBAPP="Y"
DGE="Y" 

On Windows, various services are created. To start all services at once, select Start | Programs | Fidelia NetVigil | Start Fidelia NetVigil.

To control the startup behavior of individual components, use Service Control Manager which is accessible via Control Panel | Administrative Tools | Services. All the NetVigil service names are prefixed with NetVigil. If you wish to have the web application and DGE component to start up when the system reboots, edit the properties of the corresponding service (as well as for NetVigil Provisioning Database and NetVigil Aggregated Database) and set the Startup Type to Automatic.

Although under normal circumstances you would run the netvigil.init script or menu items from Program Files, each component of NetVigil system has its own startup script in-case you would like to start/stop any of the components individually. These scripts are located under the NETVIGIL_HOME/etc directory on Linux/Solaris platforms. On the Windows platform, use net start <service_name> and net stop <service_name>. The scripts are named:

Script Name	Windows Service	Description
provdb.init	nvprovdb	provisioning server/database (poet)
dgedb.init	nvdgedb	DGE/monitor database (mysql)
monitor.init	nvmonitor	DGE/monitors
webapp.init	nvwebapp	web interface
bveapi.init	nvbveapi	BVE API server

Each of these scripts accepts the parameters start and stop which will start and stop the respective component.

3.3.1 Starting the system

The provisioning database should always be started first since all other components will request configuration information from the provisioning database. The DGE database and monitors should follow since they will provide information on the status of all configured devices and tests. The web application should be started next. The BVE socket server can be started at any point after the provisioning database has been started. The netvigil.init script on Linux/Solaris platforms will take care of maintaining this order.

% /etc/init.d/netvigil.init start 

On Windows platforms, select Start | Programs | Fidelia NetVigil | Start Fidelia NetVigil to start the entire application.

3.3.2 Stopping the system

When shutting down the system, the components should be shutdown one by one in the opposite order they were started. On Linux/Solaris:

% /etc/init.d/netvigil.init stop 

and on Windows, Start | Programs | Fidelia NetVigil | Stop Fidelia NetVigil.

If you want to stop the components of NetVigil that read configuration files (to re-read these config files), then you can also use

% /etc/init.d/netvigil.init stopcore 

This will not stop the various databases or the messaging bus.

Note: If you have recently stopped the provisioning database, it may take a few seconds until you can start the database again while it shuts down completely. The startup scripts will let you know if the Poet database was unable to start up properly and you should try again after a few seconds.

3.3.3 Verifying proper operation

On Linux/Solaris platforms, using the status parameter with the netvigil.init script will display the status of the different components. Example:

% ./netvigil.init status 
messaging server (openjms) ... running
provisioning database (poet) ... running
bve (socket) server api ... running
dge (monitor) components ... running
dge/jms database (mysql) ... running
application server (tomcat) ... running
virtual frame buffer (xvfb) ... running 

Alternatively, you can use status parameter with other startup scripts to check the status of individual components/software. This option is only available on Linux/Solaris platforms.

On Windows platform, you can check the status of individual components using the Service Control Manager where the Status column should indicate Started when a particular component is running. You can also execute net start | more from a command prompt to get a list of running services. NetVigil components are prefixed with "NetVigil".

3.4 Configuration Files

NetVigil system utilizes several configuration files to obtain information about different components and system parameters. Before starting the application, you need to make sure that the default values match your local network and server configurations in the following files:

3.4.1 Application installation path

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/netvigil.env	Provisioning database, Web application, Monitor	Linux, Solaris

This file contains environment variables that specify the location of different supporting software needed to run NetVigil. INSTALL_DIR should be set to the installation directory, NETVIGIL_HOME (as described above). All other variables should be left unchanged unless specified otherwise by Fidelia support.

3.4.2 BVE Config Database host/location

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/netvigil.xml	Web application, Monitor	Linux, Solaris, Windows

This file is used by the monitors that are part of the DGE component and web interface to identify the provisioning database. If the DGE or web component is running on the same server as the provisioning database, there is no need to change this file. Otherwise edit the following line:

<provisioning
name="provisioning"
host="localhost"
[...] 

localhost should be changed to the fully qualified domain name (fqdn) or ip address of the server where the provisioning database is going to be located. The user and password parameters should not be changed.

3.4.3 Logging configuration

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/log4j.conf	Provisioning database, Web application, Monitor	Linux, Solaris, Windows

Different components of NetVigil provide useful diagnostic and/or informative log messages, and you can control how much information is logged by editing this file. Change LOGLEVEL to one of the following to fine tune the level of details you would like:

Log message detail levels

LOGLEVEL	Level of Detail
INFO	Informational messages that highlight the progress of the application at coarse-grained level
WARN	Designates potentially harmful situations
ERROR	Designates error events that might still allow the application to continue running
FATAL	Designates very severe error events that will presumably lead the application to abort
DEBUG	Additional detailed information that is useful for debugging an application. Do not enable debug messages unless asked to do so by Fidelia technical support.

By default, messages are only logged into NetVigil's own log files stored in the directory specified by $LOGDIR variable. If you would like to send the logs to a Unix syslog host, either at a central location, or on same host(s), uncomment the following section:

#log4j.appender.SYSLOG = org.apache.log4j.net.SyslogAppender
#log4j.appender.SYSLOG.SyslogHost = localhost
#log4j.appender.SYSLOG.facility = 
org.apache.log4j.net.SyslogAppender.LOG_LOCAL7 

and change localhost to the fqdn or ip address of the host where you want the log messages to be sent. If you would like the messages to be sent as a facility other than local7, change LOG_LOCAL7 to LOG_<FACILITY> where <FACILITY> is one of the facilities listed in the Unix manual (man5) of syslogd.conf. Make sure to enter the facility name in upper case.

3.4.4 Test Definitions & Defaults

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/TestTypes.xml	Provisioning database, Web application	Linux, Solaris, Windows

This file contains information on default values for thresholds and display properties of various tests. When new tests are being provisioned, or existing test results are being displayed, information in this file dictates how to group similar tests together and what units to use to display test results. The file is in XML format and the format should be strictly maintained while making any changes. This information is used by the provisioning server/webapp when no thresholds have been setup using the admin interface on the web application. Once an admin user has assigned default thresholds for any Department, the information in this file is no longer used for populating default thresholds when tests are created for that particular Department.

Please refer to Chapter 21, "Plugin Actions" for details of the layout and applications of this file.

3.4.5 Web application external help

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/tomcat/webapps/ROOT/WEB-INF/web.xml	Web application	Linux, Solaris, Windows

NetVigil provides an easy way to add escalation information, procedures or any other information related to individual tests, or on a global basis on test type, device, or Department context. Each test item on the web application includes a HELP link, which when clicked on, shows any such information. This information is obtained by running an external script. Locate the section containing:

<param-name>help.script.path</param-name>  

This parameter identifies the location of this script. NetVigil includes a default script, located at NETVIGIL_HOME/utils/externalTestHelp.pl, which looks for such information in a directory hierarchy of specific layout.

If you would like to have a different script used for this feature, you can change the externalTestHelp.pl script name and path to specify the different script.

For the algorithm that is used to find test-specific information, see Section 8.4, "External Help" on page 8-125.

3.4.6 Web application external authentication

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/tomcat/webapps/ROOT/WEB-INF/web.xml	Web application	Linux, Solaris, Windows

The <param-name>externalLoginKey</param-name> section is used to configure the shared key for external authentication. NetVigil makes it easy to integrate the web application into an existing web portal or single-login system. Using the external authentication mechanism, you can bypass the initial authentication web page and go directly into the device summary page. This is accomplished by encoding user Department and login information in an md5 hash, using the shared key and passing into the authentication engine of the web application component. See the section "Web Portal Authentication" on page 309 for further details on setting this up.

Note: It is highly recommended that the <param-value>payday</param-value> section be edited and the default shared key be changed to something different and secure. A sample CGI script (NETVIGIL_HOME/utils/externalWebLogin.cgi) illustrating how to use the external authentication mechanism is provided with NetVigil.

3.4.7 DGE Identity

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/dge.xml	Monitor	Linux, Solaris, Windows

The following entry sets the name a DGE identifies itself with against the provisioning database:

<dge name="my_dge" user="emerald" password="null"/>  

The name my_dge should be changed to the name of the DGE you have (or are going to) setup. The name does not need to be an fqdn, only something meaningful. However, you will need to use the same name when creating DGE information in the provisioning database using the superuser interface. For example, if you plan to have a DGE with the name "dge01.central" with an fqdn of "dge01.central.mycompany.com", then my_dge should be replaced with dge01.central, and you must use the same DGE name when you create the DGE using the superuser interface. (For more information on creating DGEs, see Chapter 6, "DGE Management".)

3.4.8 DGE controller port/password

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/dge.xml	Monitor	Linux, Solaris, Windows

Each DGE process listens on a TCP/IP port for incoming connection requests and provides status on each of the monitors it supports. By default this port is set to 7655, but this can be configured by editing the following section:

<controller port="7655" password="fixme"/>  

If you change the port from 7655 to something different, make sure that no other application running on the machine is going to bind to that port. You should also change the password fixme to a different and more secure password. You will use this password to log into the status server.

3.4.9 EDF server port/password

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/dge.xml	Monitor, External Data Feed	Linux, Solaris, Windows

Each DGE process listens on a TCP/IP port for incoming connection requests and allows integration with external tools utilizing the External Data Feed API. By default this port is set to 7657, but this can be configured by editing the following section:

<edfMonitor>
<port>7657</port>
<connections>1</connections>
<timeout>120</timeout>
<userName>edfuser</userName>
<password>fixme</password>
</edfMonitor>  

If you change the port from 7657 to something different, make sure that no other application running on the machine is going to use that port. You should also change the password fixme to a different and more secure password. You will use this password along with the specified user name to log into the EDF server. The connections parameter configures the number of concurrent connections to the EDF server that should be allowed. If you expect to run a lot of external monitors that need to insert results into NetVigil, this number should be set to a suitably large number.

3.4.10 ISM server port/password/files

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/dge.xml	Monitor, External Data Feed	Linux, Solaris, Windows

The Input Stream Monitor (ISM) running on each DGE has the ability to "watch" one or more log files and scan for specific text patterns, raising the configured severity upon a match. Each such file needs to be listed in this file in the ISM configuration section. The following entry configures the DGE to scan /var/log/messages:

<ismMonitor>
[....]
<source>
		<url>file:///var/log/messages>/url>
</source>
</ismMonitor>  

Multiple files can be monitored by adding additional
<url> ... </url> parameters.

The ISM also listens to a TCP port for incoming connections and allows an external process to insert "messages" using the Input Stream MonitorAPI. By default this port is set to 7659, but this can be configured by editing the following section:

<ismMonitor>
<port>7659</port>
<connections>1</connections>
<timeout>120</timeout>
<userName>edfuser</userName>
<password>fixme</password>
<source>
<url<file:///var/log/messages>/url>
</source>
</ismMonitor> 

Similar to the EDF, this section controls the number of concurrent connections, port number, login username and password.

3.4.11 E-mail servers

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/netvigil.xml	Monitor, Report Server	Linux, Solaris, Windows

The DGE and Report Server components need to know which E-mail server(s) they should use to send notifications or reports via E-mail. Edit the following section:

<email-servers>
<host name="my_mail_server" priority="10"/>
</email-servers>  

Change my_mail_server to the fqdn of your local E-mail server or the E-mail server that you use for sending outgoing E-mail. If you have more than one E-mail server, you may add additional servers with a different priority value. The NetVigil component responsible for sending mail will start with the E-mail server with the lowest priority, and if it is unable to reach that server, it will move onto the next server on the list until the notification has been sent out successfully. You should make sure that the E-mail server(s) is configured properly to allow NetVigil to relay E-mail to any E-mail address. (Please refer to your E-mail server's administration guide for instructions on how to accomplish this.)

3.4.12 Web server TCP/IP port

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/tomcat/conf/server.xml	Web application	Linux, Solaris, Windows

This is the configuration file for Jakarta Tomcat application server. If you would like to run the application on a different port other than the default of port 80, you need to locate the section:

<Connector 
className="org.apache.tomcat.service.PoolTcpConnector>  

and change the value of <Parameter name="port">.

3.4.13 Web User Interface Appearance

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/tomcat/webapps/ROOT/resources/css/stylesheet.css	Web application	Linux, Solaris, Windows

This is an HTML-standard compliant style sheet that is used by the NetVigil web interface. You can edit the definitions of different HTML components in this file to change the look and feel of the web interface to suit your needs. This stylesheet is used only on those sections of the interface that are visible to the user.

3.4.14 Customizing Device Tag Labels

Configuration File	Affected Components	Affected Operating Systems
NETVIGIL_HOME/etc/netvigil.xml	Web application	Linux, Solaris, Windows

NetVigil provides five customizable device tags, which you can define to meet your needs. For example, you can store information about where a device is located (city, state, building, room, rack) or what corporate group it belongs to (payroll, helpdesk, etc.) By default, these attributes are displayed with the labels Custom Attribute 1, Custom Attribute 2, etc. You can change these labels to more meaningful names by editing the following section:

<device-tags>
		<tag index="1" description="Custom Attribute 1"/>
		<tag index="2" description="Custom Attribute 2"/>
		<tag index="3" description="Custom Attribute 3"/>
		<tag index="4" description="Custom Attribute 4"/>
		<tag index="5" description="Custom Attribute 5"/>
</device-tags>  

Replace the description parameters with the labels that you want to see in the Web application. For example:

<device-tags>
		<tag index="1" description="City"/>
		<tag index="2" description="State"/>
		<tag index="3" description="Building"/>
		<tag index="4" description="Room"/>
		<tag index="5" description="Rack"/>
</device-tags>  

note: These definitions do not affect the way custom attributes are stored or used. They affect the display labels only for the tags.

3.5 Network and Topology Discovery

Today, enterprise networks are large, complex, and constantly changing. To help you keep track of the components of your infrastructure, NetVigil provides both network and topology discovery.

Network discovery, included in all NetVigil installations, enables you to automatically discover and provision new devices into NetVigil.

Layer 2 and 3 topology discovery, available when you purchase a NetVigil Topology license, discovers devices and maps the relationships between them. (You can also map relationships between devices manually by creating device dependencies as described in Section 8.3, "Device Dependency" on page 8-123.)

Topology discovery is run for one DGE Location at a time, by the least-loaded DGE in that location. This ensures that discovery is not blocked by firewalls, access lists, etc., since the DGE must have access to the devices that it is to monitor.

NOTE: You must log in as Superuser to run network or topology discovery.

3.5.1 Configuring Scope of Discovery

Discovery scope is the range of devices that are discovered by a single discovery operation. There are two ways to configure discovery scope:

Specify one or more IP address/subnet mask pairs, and discover devices on those subnets
Specify a seed router and a number of hops, and discover devices within the specified number of hops from the seed router (Topology license only). (A hop is the trip a data packet takes from one router or intermediate device to another within a network. If a packet travels from a source computer to a router to a second router to a destination computer, it has taken one hop.)

In addition, the final list of discovered devices is affected by the following:

Discovery location, the DGE location from which the discovery is run

The least-loaded DGE in the selected DGE Location performs discovery. Devices that are inaccessible to this DGE (due to ACLs, firewalls, etc.) are not discovered.

Discovery filter (Topology license only), which determines what kinds of devices appear in the final list

You can choose to include or exclude specific device types from the final list of discovered devices.

Example: Configuring Discovery Scope

Figure 3.1 shows a sample network that includes three subnets, each of which is connected to a router. All three subnets are part of the same DGE location, which contains only one DGE, in Subnet A.

Here are two sample discovery configurations and their results:

The Superuser configures discovery by specifying two IP Address/subnet pairs:

			198.168.2.0/255.255.255.0
			198.168.3.0/255.255.255.0 

Discovery finds all of the devices on Subnet B and Subnet C.

Superuser configures discovery by specifying the IP address of Router A, 192.168.1.14, and a maximum of two hops. The result is that devices in all three subnets are discovered, because Router B and Router C are both within two hops of Router A, and devices within the subnets that are connected to the routers fall within the discovery scope.

Sample network configuration for NetVigil discovery

To run Network or Topology Discovery:
Click SUPERUSER | discover.
If no discovery data exists, the Network Discovery page appears. Configure the following discovery options:

Network Discovery Configuration Parameters

Field	Purpose
Network Discovery Scope	Specify the subnet(s) on which you want to discover devices. For each subnet, enter an IP address and a subnet mask in dotted quad notation. To enter multiple IP address/subnet mask pairs, list each one on a separate line. You must specify at least one subnet/subnet mask pair. For additional information see Section 3.5.1, "Configuring Scope of Discovery" on page 3-36.
Discovery Location	Select the DGE Location for which you want to perform discovery. Discovery is performed by the DGE in this location that has the fewest configured tests.
Discovery Filter (Topology license only)	Optionally, to filter discovery results, select include or exclude, and the device types to be included or excluded.
SNMP Community Strings	To automatically discover SNMP tests that are supported by discovered devices, specify the SNMP community strings that are used in your network(s). Enter one community string per line. If no community string is entered, discovered devices are not tested for SNMP capabilities. To discover SNMP devices only, select Exclude devices that do not support SNMP. If this option is selected you must enter at least one SNMP Community string.
Advanced Options (Topology license only)
discover physical connectivity (topology) between devices	Select this to discover relationships between devices. If this option is selected, choose one of the following: update topology information for existing devices only If selected, NetVigil updates information about the relationships between provisioned devices, but does not discover new devices discover new devices and new/updated topology If selected, NetVigil discovers both devices and relationships between devices
start discovery from following "seed" router	Select this option to limit the scope of discovery to devices within a certain number of hops from the specified router. If selected, you must specify the seed router IP address and maximum number of hops. For additional information see Section 3.5.1, "Configuring Scope of Discovery" on page 3-36.

Click Run Discovery. While discovery is in progress, the Network Discovery Status page periodically refreshes the status display. Discovery may take several minutes to complete, up to several hours in large networks with tens of thousands of devices.
If devices are discovered, the Network Discovery Results page displays them, sorted by device type. (Devices with an unrecognized type are listed as Type: Unknown/Other.) To provision discovered devices, select the Departmentto which you want to assign the devices and the devices that you want to provision, and then click Continue.
The Discovery Topology page displays discovered devices in a hierarchy of expandable folders. If a device has multiple parents, it is listed under all of its parents.

Review your selections. If you are satisfied with them, click Provision Devices. After the operation is complete, the Network Discovery Status window displays a message indicating that the devices were successfully provisioned. For each provisioned device, NetVigil creates ICMP ping tests (packet loss and RTT).

NOTE: Devices that are already provisioned (with the same name) are not created again.

If you just want to update the topology (dependencies) for provisioned devices, then remember to set the option `Update topology for provisioned devices only' in the scope configuration as described above.

3.5.2 Manual Batch Creation of Devices and Tests

You can add devices and tests using the web interface. However, for bulk additions or changes, NetVigil includes tools to provision large numbers of devices into the provisioning database via the BVE API. The tool will also automatically discover available network interfaces, system resources, various application services, etc. on the devices, and using the default test threshold values, automatically create the tests in the system so that you can be up and running in a very short period of time.

Before using the bulk import tool (provisionDevices.pl), make sure that all necessary Departments and admin/end-user logins have been created. The import tool is meant to be used for importing devices for one Department at a time. For each such Department create a text file (e.g. network_devices.txt) and add device information (one device per line) in the following format:

device_name   device_address   device_type   snmp_community 

Where

device_name is either the FQDN or a descriptive name of the device.
device_address is the ip address of the device. This should be in dotted-quad (n.n.n.n) notation
device_type is one of
UNIX
NT
ROUTER
SWITCH
UNKNOWN (determine automatically)
snmp_community is the snmp community string of the device, if the device supports snmp. This information is used to automatically discover network and system resources.

Devices are imported for one logical location at a time also. So make sure to include devices in an import file that are meant to belong to the same Department and monitored from the same location. Once this import file is ready, use the provisionDevices.pl tool to proceed with the import. General syntax of the tool is:

NETVIGIL_HOME/utils/provisionDevices.pl --host=prov_host \
--user=login_id --password=login_password --file=import_file \
--location=location_name 

Where

prov_host is the fqdn/ip address of host where the BVE socket server is running. Usually you would provision devices from the same host, so this would be localhost.
login_id and login_password are the userid and corresponding password for an end-user, who is a member of the specific Department you want the newly provisioned devices to belong to.
import_file is the text file containing the device information as outlined above.
location_name is the name of the location as defined in the database. The default NetVigil installation is pre-configured with location name Default Location.

As the device is created and tests are discovered and added to the provisioning database, information will be printed.

Example: Batch Creation of Tests

reading contents of import file '/tmp/import.txt' ... 
connecting to provisioning host ...
succesfully logged in as user test with supplied password
creating new device 'my_test_host' (192.168.100.100)
attempting to perform auto-provisioning for 'port' tests ...
		created 'port' test for 'HTTP'
		created 'port' test for 'POP3'
		created 'port' test for 'HTTPS'
		created 'port' test for 'IMAP'
attempting to perform auto-provisioning for 'snmp' tests ...
		created 'snmp' test for 'hme0 Status'
		created 'snmp' test for 'hme0 Util In'
		created 'snmp' test for 'hme0 Util Out'
		created 'snmp' test for 'hme0 Err In'
		created 'snmp' test for 'hme0 Err Out'
		created 'ping' test for 'Packet Loss'
		created 'ping' test for 'Round Trip Time' 
data import complete in 0 days, 0:00:31 

Note: Tests are created based on thresholds and intervals defined in TestTypes.xml, so if you want to make changes to the defaults, make sure to edit this file before starting the import task.

3.6 Monitoring Log Files

NOTE: The syslog and text log file monitoring capability uses the Input Stream Monitor (ISM) API.

NetVigil has the ability to "watch" text log files for specific patterns and raise alarms when a match is found. Before a log file can be monitored, a NetVigil Administrator must configure the DGE to scan the file(s). This is accomplished by editing NETVIGIL_HOME/etc/dge.xml. The following entry configures the DGE to scan /var/log/messages:

<ismMonitor>
		[....]
		<source>   <!-- log files to monitor -->
			<url> file:///var/log/messages </url>
		</source>
</ismMonitor> 

Multiple files can be monitored by adding additional <url> ... </url> parameters.

Next you will need create a list of regular expressions to watch for and a Regular Expression test. These tasks, which can be performed by an End-User, are described in Section 14.3.1, "Monitoring Log Files for Patterns" on page 14-191.

3.7 Processing SNMP Traps

Various router/switch/network appliances and applications have the ability to send SNMP traps to indicate some event has transpired. NetVigil has the ability to accept such SNMP traps from devices it is monitoring and display the messages on-screen with appropriate (configured) severity. The SNMP traps are accepted by trap handlers running on servers that are running DGE components and compared against text pattern filters. If a match is found, the configured severity is assigned to the message and it is recorded into DGE database for archival/reporting purposes.

Also, in order for NetVigil to process SNMP traps, the device will need to be configured to send traps to the DGE where the device is provisioned. Please refer to the respective documentation of the device/application to find out how to configure trap destinations. The IP address of the DGE for a particular "location" can be obtained from your local NetVigil administrator.

3.7.1 Trap Handler Configuration

NetVigil SNMP trap handler is configured via configuration entry in NETVIGIL_HOME/etc/dge.xml. A typical configuration looks like:

<snmpTrapListener>
		<enabled>true</enabled>
		<port>162</port>
		<performHostnameLookup>false</performHostnameLookup>
</snmpTrapListener> 

By default, the trap handler is disabled, in case there is already an SNMP trap daemon running on the same host (typically the case on Windows and Solaris platforms). To enable the trap handler, set the enabled parameter to true (<enabled>true</enabled>) You can also choose to run the trap handler at an alternate (UDP) port other than the standard port 162 by modifying the port parameter. In that case, make sure to specify the alternate destination port number on remote devices that will send SNMP traps. Lastly, performHostnameLookup parameter controls whether the trap handler will attempt to resolve the host name of remote hosts when a trap is received. As slow DNS resolutions may impact performance, the default option disables this feature.

Once any of these values have been changed, the DGE will need to be restarted before the change is applied. At this point the trap handler should be ready to accept SNMP traps. If you do not require any advanced configurations, you may proceed to the following section that describes how to process received traps.

In certain cases, you may wish to "relay" the SNMP traps to another management station/application (e.g. a central event correlation engine). NetVigil allows you to relay all or select traps to one or more hosts:

<snmpTrapListener>
		<enabled>false</enabled>
		<port>162</port>
		<performHostnameLookup>false</performHostnameLookup> 
		<!-- forward fidelia traps to hostA -->
		<relay oid=".1.3.6.1.4.1.10844.*">
			<destination host="192.168.1.1" port="162"
				communityId="public"/>
		</relay>  
		<!-- forward all other to hostB and hostC -->
		<relay oid="default"> 
			<destination host="192.168.2.2" port="162"
				communityId="public"/> 
			<destination host="192.168.5.5" port="8162"
				communityId="secret"/> 
		</relay> 
</snmpTrapListener> 

In the above example, all enterprise traps for Fidelia Technology MIB with prefix .1.3.6.1.4.1.10844 is relayed to a management agent (specified in destination element) running on host 192.168.1.1, on UDP port 162. Note the use of the * as wildcard in the oid parameter. If you wish to forward only specific traps, you can use exact OID. The second relay configuration block has an oid value default, which has special meaning and covers any OID not explicitly specified in other relay blocks. The default oid is optional and if not specified, in the absence of a matching relay block, the trap will not be forwarded to any other host. In this case all traps are forwarded to two hosts, each with different port and community string.

The trap handler also allows SNMP traps to be passed to external scripts, which can further process them:

<snmpTrapListener>
		<enabled>false</enabled>
		<port>162</port>
		<performHostnameLookup>false</performHostnameLookup> 
		<!-- forward fidelia nodeDeleted traps to a script -->
		<trapHandle oid=".1.3.6.1.4.1.10844.1.1.255.2.1">
			<script>/usr/bin/nodeDeleted.pl</script>
		</trapHandle> 
</snmpTrapListener> 

The same rules for wildcard (*) and default OID as relay configuration applies to trapHandle configuration. Upon match, the specified script is executed and trap information is made available via standard input (STDIN) in the following format, one entry per line in sequential order:

remote_device host_name
remote_device ip_address
system.sysUpTime.0 uptime
snmpTrap.snmpTrapEnterpriseOID enterprise_oid
varbind_oid1 varbind_value1
varbind_oid2 varbind_value2
[...]
varbind_oidN varbind_valueN 

If DNS resolution is disabled, or DNS resolution failed, host_name will be same as ip_address. uptime represents number of seconds since remote agent was started or initialized.

3.7.2 Loading Enterprise MIBs for SNMP Traps

NetVigil monitors use OID values to poll for results and does not need MIB files. However, if you are using the SNMP trap handler, and wish to create severity mappings using OID name, you will need to load the MIB definition into the trap handler. To load a new SNMP MIB file, simply copy the MIB file to NETVIGIL_HOME/lib/mibs and run NETVIGIL_HOME/utils/loadSnmpMIBs.sh (NETVIGIL_HOME/utils/loadSnmpMIBs.cmd on Windows). On Windows, restart the DGE using

net stop nvmonitor
net start nvmonitor 

3.8 Windows monitoring using WMI

3.8.1 Overview

NetVigil can monitor Windows hosts using the native Windows Management Instrumentation (WMI), which is installed by default on all Windows 2000, XP and 2003 or later versions, and available as an add-on for Windows NT hosts.

NetVigil performs WMI monitoring using the NetVigil WMI Query Server (nvwmiqd). This server is automatically installed on Windows DGEs, however, to perform WMI monitoring from a Linux or Solaris DGE, you must install and configure a NetVigil WMI Query Server on a Windows system that can access the Windows hosts to be monitored.

3.8.2 Installing the NetVigil WMI Query Server

The WMI Query Server (nvwmiqd) should be installed on a Windows machine which has access to the windows hosts being monitored using NetBIOS. This service is automatically installed on Windows DGEs by default.

Step 1: Check System and Network Requirements

Hardware requirements

Install the NetVigil WMI Query Server on a system that meets or exceeds the following requirements:

Pentium III processor
512 MB RAM
10 MB free disk space

Software requirements

The NetVigil WMI Query Server system must meet the following software requirements:

Operating System: Windows 2000 with Service Pack 3 or Windows XP with Service Pack 1
Other software can run on the NetVigil WMI Query Server host, provided there are enough resources to allow both the software and the WMI Query Server to run efficiently.

Network Requirements

The WMI Query server system must be able to access the windows hosts being monitored using NetBIOS. Test this by typing NET VIEW \\remote_host at a Command Prompt.

Firewall requirements

When the DGE is running on a Linux/Solaris platform, it communicates with the WMI Query Server on TCP port 7667 by default. To specify a different port number, edit the configuration files on the probe and DGE as described in "The NetVigil WMI Query Server Configuration File" on page 48 and "Step 1: Enable any Linux/Solaris DGE for WMI" on page 50. If firewalls, access lists, etc. exist between the DGE and the WMI Query Server, the rules must be modified to allow incoming connections from the DGE to the WMI Query Server on the specified port. The rules should allow persistent connections (i.e., connections should not be forcibly timed out, even if there is no data flowing).

Access requirements

If the Windows hosts to be monitored is part of a domain, you will need the username and the corresponding password for a user who is part of the "Domain Administrator" group. The WMI Query Server will use this user's credentials to connect to the Windows hosts being monitored for retrieving the WMI performance information.
If the hosts are configured in one or more workgroups, and not part of a domain, then each host, including the host where the WMI Query Server is being installed, will need to have the same password for the "Administrator" user, or have another such common user which is part of the "Administrators" group

Step 2: Install the WMI Query Server Software

To install the NetVigil WMI Query Server:
Double-click the install file, wmiQDinstaller.exe. A copy of this installer is available on the NetVigil installation CDROM, or the Fidelia support web site (http://www.fidelia.com)
Read the Introduction, and then click Next to continue.
Optionally, in the Choose Install Folder window, specify the folder in which you want to install the WMI Query Server. Click Next to continue.
In the Remote Query Credentials window, enter the username and password that the WMI Query Server will use to access monitored Windows hosts. The username can include a domain name (e.g., ACMECORP\wmi_user). In the Password (Again) field, enter the password a second time for validation. If you do not enter a Remote Username and Remote Password, the WMI Query Server will use the username and password of its local system account.

Click Next to continue.

In the Pre-Installation Summary window, review the configuration options. If they are correct, click Install to continue.
After the installation completes, click Done to close the installer.

Relationship between DGEs, WMI Query Server, and monitored hosts

The NetVigil WMI Query Server Configuration File

After the NetVigil WMI Query Server is installed, either on a stand-alone server to be used with DGE on a Linux/Solaris server, or as part of the DGE on a Windows server, you can fine-tune it's configuration. The table below lists the configurable parameters in the configuration file nvwmiqd.ini. This file can be found in the WMI_Query_Server_Install_Dir\bin (stand-alone install), or NETVIGIL_HOME\etc. If the file, or any of the parameters are missing, default values are used by the server.

NOTE: The configuration file may contain parameters that are not listed here. Do not modify unlisted parameters unless advised to do so by Fidelia technical support.

Parameter	Description	Default Value
Port	TCP port on which NetVigil WMI Query Server listens for incoming connections from DGEs	7667
Username	User name that a DGE must use when logging in to NetVigil WMI Query Server	wmiuser
Password	Password that a DGE must use when logging in to NetVigil WMI Query Server	fixme
Server_Username	User name that the NetVigil WMI Query Server uses to connect to Windows hosts being monitored	n/a
Server_Password	Password that the NetVigil WMI Query Server uses to connect to the Windows hosts being monitored.	n/a

Example: Sample Configuration File (nvwmiqd.ini)

[ServerConfig] 
Port = 7667
Username = wmiuser
Password = fixme
Timeout = 100000
Threads = 4
Server_Username = ACMECORP\localuser
Server_Password = testpassword 

3.8.3 Configuring NetVigil for WMI Monitoring

If all your DGEs in a Location are not "WMI capable", then you should create a separate DGE Location for WMI-capable DGEs only (described in Section 6.2.1, "Adding Locations and DGEs via web" on page 6-105).This will avoid assigning any windows tests on a non-WMI capable DGE. A single WMI Query Server can handle upto 4 Unix DGEs simultaneously.

Step 1: Enable any Linux/Solaris DGE for WMI
If you want to use a Linux or Solaris DGE for WMI monitoring, install and configure the NetVigil WMI Query Server as described in Section 3.8.2, "Installing the NetVigil WMI Query Server" on page 3-46.
Configure one or more Unix DGE for WMI monitoring by setting the following parameters in $NETVIGIL_HOME/etc/dge.xml:

<wmiQueryServer>
		<host name="my_host_1" address="1.1.1.1" port="7667"
		username="wmiuser" password="wmipassword" />
</wmiQueryServer> 

Where:

host name	is a unique, descriptive name for the WMI Query Server host that this DGE uses for WMI monitoring (e.g., Denver_WMI_QueryHost).
address	is the IP address of the WMI Query Server host, in dotted quad notation. If the DGE is running on Windows, this will be set to 127.0.0.1
port	is the TCP port on the WMI Query Server to which the DGE connects. This must match the Port parameter in the nvwmiqd.ini file on the WMI Query Server.
username	is the username that the DGE uses to log in to the WMI Query Server. This must match the Username parameter in the nvwmiqd.ini file on the WMI Query Server.
password	is the password that the DGE uses to log in to the WMI Query Server. This must match the Password parameter in the nvwmiqd.ini file on the WMI Query Server.

Restart the DGE so that the changes can take effect.
Step 2: Setup common account on all Windows hosts
Make sure that every Windows host that will be monitored through WMI has a user login account for access by WMI Query Server. The DGE uses the same username/password to access all monitored WMI devices (see "The NetVigil WMI Query Server Configuration File" on page 48).
Step 3: Provision Hosts in NetVigil
Provision the Windows hosts that will be monitored using WMI as described in Section 14.1, "Managing Devices" on page 14-177. Make sure that the devices are added to a location where all the DGEs are `WMI Enabled' (have access to a NetVigil WMI Query Server).
Discover and provision WMI tests on the Windows hosts as described in Section 14.2, "Managing Standard Tests" on page 14-182.

3.8.4 Troubleshooting

This section lists problems that may arise with WMI monitoring, possible causes, and solutions.

Problem: "The DGE can't discover WMI tests for Windows hosts."
Ensure that the NetVigil WMI Query Server is running
Check the error log on the WMI Query server for errors.
Problem: "The DGE discovered WMI tests, but it can't monitor configured tests using WMI."
Ensure that the NetVigil WMI Query Server is running
Check the error log on the WMI Query server for any errors.
Problem: "Ever since I installed WMI, I'm getting test provisioning errors."
When you use NetVigil to discover tests, it may discover SNMP and WMI tests with the same name. However, if you try to create SNMP and WMI tests with the same, you will get provisioning errors. To keep names unique, use a naming convention to distinguish between SNMP and WMI tests. For example, start the names of all WMI tests with "wmi_".

3.9 Setting up Apache Monitor

The apache server will need to be compiled with mod_status support. By default this module is included in a build process, but you can verify this using the following commands:

(on Unix)
cd /path/to/apache
bin/httpd -l | grep mod_status 
(on Windows)
cd \path\to\apache
bin\httpd -l | findstr "mod_status" 

If the output shows "mod_status.c" then this module is included in the web server. You will need to enable this module in "httpd.conf". Refer to the documentation at http://httpd.apache.org/docs/mod/mod_status.html for instructions on how to enable and configure it. You will need to make sure that:

The URL for the module matches the URI specified for the NetVigil Apache monitor specified in the configuration file (described below).
"ExtendedStatus On" directive is applied
NetVigil hosts (WebApp, DGE) are included in teh "Allow" directive

For example, if the Web Application is running on host 192.168.100.5, and the DGE is on host with address 192.168.200.10, the module configuration in httpd.conf may look like:

<Location /server-status>
		SetHandler server-status
		ExtendedStatus On
		Order Deny,Allow
		Deny from all
		Allow from 192.168.100.5
		Allow from 192.168.200.10
</Location> 

Once the configuration has been enabled/modified, the httpd process will need to be restarted (http://httpd.apache.org/docs/stopping.html) to apply the changes.

Editing NetVigil Configuration

Once NetVigil has been installed, on each host (if running on a distributed configuration) edit "NETVIGIL_HOME/lib/ext/gp_apache/config.xml" and locate the following section:

<uri>
		<protocol>http</protocol>
		<port></port>
		<file>/server-status?auto</file>
</uri> 

The item of interest here is the URI specified within the <file>...</file> property. When a client access this URL, Apache server provides performance statistics that it stores in an internal database. The URL (/server-status) should match the URL specified in the configuration of the "mod_status" module (see below). If the server is configured to provide the performance stats via URL "/internal/stats/apache", then the configuration above would be changed to:

<uri>
		<protocol>http</protocol>
		<port></port>
		<file>/internal/stats/apache?auto</file>
</uri> 

Note that the "?auto" parameter should be left as-is. The remaining configuration items should not be altered in any way without specific instructions from Fidelia Support.

3.10 Alphanumeric Paging

NetVigil can send alphanumeric messages to a TAP/IXO pager using a modem attached to the DGE. Note that each DGE has one or more locally attached modems, which ensures maximum redundancy and fault tolerance in a distributed environment.

To configure NetVigil for alphanumeric paging:
Add modem configuration information to NETVIGIL_HOME/etc/netvigil.xml on the DGE that will send the paging notifications. See Section 3.10.1, "Modem Configuration" on page 3-54 for details.
On the same DGE, add paging central information for the paging service provider to NETVIGIL_HOME/etc/netvigil.xml as described in Section 3.10.2, "Paging Central Configuration" on page 3-55.
Create Action Profiles that use alphanumeric paging as described in Section 14.7, "Managing Action Profiles" on page 14-215, and assign them to tests that are run by this DGE.

3.10.1 Modem Configuration

You can have multiple modems attached to a DGE. For each modem that's attached to the DGE, add a modem-config section to the DGE's NETVIGIL_HOME/etc/netvigil.xml file. If multiple modems are configured, they are used in the order specified by their device priority parameters (the lower the number, the higher the priority). For each modem, set the following:

Parameter	Purpose
sender id	The phone number used to identify this modem when sending a page. You can set it to any phone number representing this DGE.
device priority	This modem's priority with respect to other modems attached to the DGE. The lower the value of this parameter, the higher the modem's priority. When sending a page, NetVigil uses the highest-priority modem that is available.
port	The port through which this modem communicates. For UNIX DGEs enter a port in the format /dev/ttySn where n is 0,1,2. For Windows DGEs use the format COMn where n is the number of the COM port.
speed	The modem's transmission speed, expressed in bits per second.
parity	The type of parity checking, if any, used by this modem. Possible values are even, odd, and none.
databits	The number of data bits transmitted in each series. Possible values are 7 and 8.
stopbits	The number of bits used to indicate the end of a byte. Possible values are 1, 1.5, and 2.

Sample netvigil.xml modem configuration

<modem-config> 
		<sender id="3035557777"/> 
		<device priority="10">
			<port>/dev/ttyS0</port>  <!-- /dev/ttyS or COMn -->
			<speed>9600</speed>      <!-- bps                -->
			<parity>none</parity>    <!-- none, odd, even    -->
			<databits>8</databits>   <!-- 8, 7               -->
			<stopbits>1</stopbits>   <!-- 1, 1.5, 2          -->
		</device> 
</modem-config> 

3.10.2 Paging Central Configuration

Every paging service provider has its own central number and modem pool configuration. For each paging service provider that will be used, add a paging-central child element to the alpha-pager element of the DGE's NETVIGIL_HOME/etc/netvigil.xml file. For each service provider, set the following:

Parameter	Purpose
name	A name that uniquely identifies this service provider to the DGE.
number	The number the DGE must dial to reach paging central, including any prefixes. You can find many paging central phone numbers at http://www.notepager.net/tap-phone-numbers.htm or similar sites.
speed	The highest speed supported by the service provider. Possible values are 0 (110bps), 2 (300bps), 4 (1200bps), 5 (2400bps), 6 (4800bps), and 7 (9600bps). Default value is 5.
parity	The type of parity checking, if any, supported by the service provider. Possible values are 0 (none), 1 (odd), 2 (even), 3 (mark), and 4 (space). Default value is 2.
databits	The number of data bits supported by the service provider. Possible values are 2 (7 bits) and 3 (8 bits). Default value is 2.
stopbits	The number of end-of-byte bits supported by the service provider. Possible values are 1, 1.5, and 2. Default value is 1.
flowcontrol	The type of handshaking supported by the service provider to prevent data loss during transmission. Possible values are 0 (none), 1 (XONXOFF), 2 (CTSRTS), and 3 (DSRDTR). Default value is 2.

The alpha-pager parent element also includes a sender id, which identifies the modem that is used to communicate with the specified paging central location(s), as well as one or more device priority child elements that specify what port is used.

Note that it is typical to have several <paging-central> definitions since your staff might have pagers (cell phones) from different vendors, and each vendor has their own phone number for paging. While creating action profiles, the vendor is specified using the pager-pin@pager-central-name syntax.

If the modem is not available or busy, pages are queued on the DGE. Undelivered pages older than 1 hour are ignored (these parameters can be controlled via the configuration in netvigil.xml also).

Sample netvigil.xml `paging central' configuration

				<alpha-pager> 
					<sender id="3035557777"/> 
					<device priority="10" port="/dev/ttyS0" />
					<device priority="20" port="/dev/ttyS2" /> 
					<paging-central name="attws">   <!-- name should be unique            -->
						<number>9998887777</number>   <!-- number to dial, including prefix -->
						<speed>5</speed>              <!-- 0=110bps, 2=300bps, 4=1200bps    -->
																		<!-- 5=2400bps, 6=4800bps, 7=9600bps  -->
						<parity>2</parity>            <!-- 0=none, 1=odd, 2=even, 3=mark    -->
																		<!-- 4=space                          -->
						<databits>2</databits>        <!-- 2=7bits, 3=8bits                 -->
						<stopbits>1</stopbits>
						<flowcontrol>1</flowcontrol>  <!-- 0=none, 1=xonxoff, 2=ctsrts      -->
																		<!-- 2=ctsdtr, 3=dsrdtr               -->
					</paging-central> 
					<paging-central name="nextel">   <!-- name should be unique            -->
						<number>3035551212</number>   <!-- number to dial, including prefix -->
						<speed>5</speed>              <!-- 0=110bps, 2=300bps, 4=1200bps    -->
																		<!-- 5=2400bps, 6=4800bps, 7=9600bps  -->
						<parity>0</parity>            <!-- 0=none, 1=odd, 2=even, 3=mark    -->
																		<!-- 4=space                          -->
						<databits>3</databits>        <!-- 2=7bits, 3=8bits                 -->
						<stopbits>1</stopbits>
						<flowcontrol>0</flowcontrol>  <!-- 0=none, 1=xonxoff, 2=ctsrts      -->
																		<!-- 3=dsrdtr               -->
					</paging-central> 
				</alpha-pager> 

3.11 SSL Support on Web Application

Since the NetVigil Web Application is pure HTML based, the GUI component can be accessed using both regular and secure (SSL) HTTP ptorocol. Use the following steps to setup SSL support in NetVigil (replace NETVIGIL_HOME with the correct installation directory name):

The application server (Jakarta Tomcat) used by NetVigil uses a JKS format keystore. NetVigil by default ships with a keystore with self-signed certificate. If you are not ready to install a valid key yet, you can skip to step 9. Otherwise, first rename or move the existing keystore under NETVIGIL_HOME/etc/netvigil.keystore
Create a private/public (RSA) key pair using the following command:

NETVIGIL_HOME/jdk/bin/keytool -genkey -keyalg RSA -storepass 
changeit -alias tomcat -keystore 
NETVIGIL_HOME/etc/netvigil.keystore 

Answer the questions, making sure to specify the fully-qualified domain name when asked for first/last name. Do not use comma (,) in any of the answers as it will cause problems. When asked for key password for tomcat, press return/enter
Generate a Certificate Signing Request (CSR) using the following command:

NETVIGIL_HOME/jdk/bin/keytool -certreq -storepass changeit -
alias tomcat -keystore NETVIGIL_HOME/etc/netvigil.keystore -
file my_new_key.csr 

You will need to send the CSR (my_new_key.csr) to a valid certificate authority (CA) such as Verisign or Thawte. Usually the CA will send you a signed certificate via email
Save the certificate in my_new_cert.pem and make sure that the certificate begins with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----. All other text above/below the specified section should be deleted
Import the new certificate into a new keystore using:

NETVIGIL_HOME/jdk/bin/keytool -import -v -trustcacerts -alias 
tomcat -storepass changeit -file my_new_cert.pem -keystore 
NETVIGIL_HOME/etc/netvigil.keystore 

When asked "Trust this certificate?", answer yes and The certificate will be installed into the keystore.

Verify that the certificate has been imported correctly using:

NETVIGIL_HOME/jdk/bin/keytool -list -v -storepass changeit -
keystore NETVIGIL_HOME/etc/netvigil.keystore 

Edit NETVIGIL_HOME/tomcat/conf/server.xml using a text editor (eg. vi, wordpad) and locate the following section (for NetVigil version 3.4.2 or earlier):

<Connector 
className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter name="handler"
value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
<Parameter name="port" value="443"/>
<Parameter name="socketFactory"
value="org.apache.tomcat.net.SSLSocketFactory" />
<Parameter name="keystore"
value="NETVIGIL_HOME/etc/netvigil.keystore" />
<Parameter name="keypass" value="changeit"/>
</Connector> 

On NetVigil 3.6 or later, the following section should be located:

<Connector 
className="org.apache.coyote.tomcat4.CoyoteConnector"
port="443" minProcessors="20" maxProcessors="80"
enableLookups="false" acceptCount="100" debug="0" 
scheme="https" secure="true" useURIValidationHack="false" 
disableUploadTimeout="true"> 
<Factory 
className="org.apache.coyote.tomcat4.CoyoteServerSocketFactory"
clientAuth="false" protocol="TLS" keystorePass="chageit"
keystoreFile="/usr/local/netvigil/etc/netvigil.keystore"/>
</Connector> 

which should be commented out by default. Remove the comment (<!-- .. -->) and make sure that the keystore, keypass and port parameters are set correctly

Save the file and restart the Web Application (if already running). On Linux/Solaris platform this is accomplished using NETVIGIL_HOME/etc/webapp.init restart. On Windows platform use Start -> Programs -> Fidelia NetVigil -> Individual Components -> Stop/Start Web Application
Wait 15-30 seconds for the Web Application to initialize and use your web browser to connect to https://your_netvigil_host/ and you should see the NetVigil login page

3.12 Maintenance Tasks

3.12.1 Database backup/restoration

Note: This section applies to Linux and Solaris platforms only.

The provisioning server utilizes Poet ObjectServer database while DGE components use MySQL, Oracle, etc. These databases need to be backed up periodically as a safety measure, as it will allow you to fall back to the last backed up version in the event of a database corruption. In normal operating mode, the Poet database may have objects in memory and writing data to the database files randomly. It is not recommended that the database files be backed up while Poet is writing to the databases. NetVigil comes with a script called NETVIGIL_HOME/utils/tasks/01d_50_db_backup.sh that should be used to backup the database in proper manner. The script sends special signals to the Poet database to flush all in-memory objects to disk and allows an external backup program to copy the database files. Once the backup operation has been completed, the script sends signal to Poet to resume normal operation. While the backup operation is in progress, Poet will continue to operate normally and cache all write transactions.

NETVIGIL_HOME/utils/tasks/01d_50_db_backup.sh should be run from the netvigil cron job (NETVIGIL_HOME/utils/runPeriodicTasks.pl) nightly. (For additional information about NetVigil cron jobs, see "Scheduled tasks (cron jobs)" on page 22.) By default this script will create a tar-gzipped archive in the /var/backup directory with names of the form netvigil-mm-dd-yy,hh-mm.tar.gz. If you would like to create these files somewhere else, edit the 01d_50_db_backup.sh script to specify the destination by changing the backupPath variable. (Whether you use the default or some other location, make sure that there is sufficient disk space for the backup files.)

To manually backup the provisioning database:

		% cd NETVIGIL_HOME 
		utils/tasks/01d_50_db_backup.sh 

In order to restore a copy of the provisioning database, simply uncompress and un-tar the archive into the NETVIGIL_HOME directory. Make sure what you do not have the application running while restoring a database.

To restore a copy of the provisioning database:

		% /etc/init.d/netvigil stop 
		% cd NETVIGIL_HOME 
		% cd database 
		% mv provisioning provisioning.OLD 
		% cd .. 
		% gunzip -c /var/backup/netvigil-mm-dd-yy,hh-mm.tar.gz | tar 
xvf - database 
		% /etc/init.d/netvigil start 

Backing up the DGE database:

		bin/mysqldump --defaults-file=NETVIGIL_HOME/etc/mysql.conf --
opt aggregateddatadb > /var/backup/backup-db.sql 

To restore the DGE database:

		% /etc/init.d/netvigil.init stop 
		% cd /tmp 
		% gunzip -c /var/backup/netvigil-mm-dd-yy,hh-mm.tar.gz | tar 
xvf - aggregateddatadb.sql 
		% cd NETVIGIL_HOME 
		% cd database 
		% mv aggregateddatadb aggregateddatadb.OLD 
		% cd ../mysql/bin 
		% mysql --defaults-file=../../etc/mysql.conf aggregateddatadb 
< /tmp/aggregateddatadb.sql 
		% rm /tmp/aggregateddatadb.sql 
		% /etc/init.d/netvigil.init start 

3.13 Operating NetVigil Behind Firewalls

If any component of NetVigil is going to be installed behind a firewall, depending on the existing policies, some changes may be necessary to the rules to accommodate the requirements. In the following requirements, "remote" host implies a host that is outside of the firewall while a "local" host is a device on the secure side of the firewall. Also, note that the requirements are not applicable for cases where the two hosts in question are on the same side of the firewall (i.e. packets are not crossing the firewall).

3.13.1 Requirements for the BVE Provisioning Database

The provisioning server stores all device, test, action, threshold, authentication and other provisioning information. This information is retrieved on-demand by both the web server(s) and DGEs. This is accomplished by creating connections to the database server on specific TCP ports running on the provisioning host. The following firewall rules will need to be applied for a provisioning server which is behind a firewall:

Firewall rules for a provisioning server that is behind a firewall

protocol	direction	local port	remote host	remote port	reason
tcp	incoming	7651	any	any	NetVigil provisioning database
tcp	incoming	7653	any	any	NetVigil messaging protocol #1
tcp	incoming	7654	any	any	NetVigil messaging protocol #2
tcp	incoming	7661	any	any	NetVigil BVE (provisioning) API server
udp	incoming	162	any	any	snmp traps
tcp	outgoing	any	any DGE	7657	external data feed API server
tcp	outgoing	any	any DGE	7659	input stream monitor
udp	outgoing	any	dns servers	53	dns queries for name resolution

3.13.2 Requirements for Web Server(s)

The web server(s) provides an interface for displaying all collected information as well as reports generated from those information. If a location is served by more than one web server, we will be installing a load balancer to distribute the load and the load balancer will need the same firewall rule changes as the web servers themselves. The load balancer might have additional firewall specific requirements. The following firewall rules will need to be applied for web server(s) which is behind a firewall:

Firewall rules for a web server that is behind a firewall

protocol	direction	local port	remote host	remote port	reason
tcp	incoming	80	any	any	any access to web application
tcp	incoming	443	any	any	any access to web application over ssl
udp	outgoing	any	dns servers	53	dns queries for name resolution

3.13.3 Requirements for DGE (monitors)

The DGEs perform actual monitoring of all provisioned devices and store the data on a local database. The web server(s) will need access to this stored data on-demand for report generation. The provisioning server also needs access to the data to fulfill requests made via the BVE socket API. Since the DGE perform monitoring tasks, it will need outbound access via a multitude of ports and protocols. The following firewall rules will need to be applied for a DGE server which is behind a firewall:

Firewall rules for a DGE that is behind a firewall

protocol	direction	local port	remote host	remote port	reason
tcp	incoming	7657	any	any	external data feed API server
tcp	outgoing	7659	any	any	input stream monitor
tcp	incoming	7663	web app	any	dge database lookup
tcp	incoming	7655	any	any	dge status server
tcp	outgoing	any	WMI query server	7667	dge connection to WMI query server
tcp	incoming	20	any	any	ftp servers create incoming connection on port 20 in response to connections on port 21
icmp	outgoing	any	any	"echo"	packet loss, round trip time tests
udp	outgoing	any	any	161	snmp queries
udp	outgoing	any	any	53	dns queries, tests
udp	outgoing	any	any	123	ntp service tests
udp	outgoing	any	any	1645	radius service tests
tcp	outgoing	any	any	21	ftp service tests
tcp	outgoing	any	any	25	smtp service tests, alerts via E-mail
tcp	outgoing	any	any	80	http service tests
tcp	outgoing	any	any	110	pop3 service tests
tcp	outgoing	any	any	143	imap service tests
tcp	outgoing	any	any	389	ldap service tests
tcp	outgoing	any	any	443	http over ssl service tests
tcp	outgoing	any	any	993	pop3 over ssl service tests
tcp	outgoing	any	any	995	imap over ssl service tests

3.14 NetVigil Operation in NAT Networks

NAT (Network Address Translation) devices usually translate connections between a public network and a private address space. There are several issues to consider while monitoring in a NAT network:

NAT Port Translation

In this NAT method, one or more public IP address are mapped to one or more private IP addresses by manipulation of the source port. It is difficult to permit an external monitoring server to query an internal host unless such translation is set up.

Firewalls Disable Queries from public network

Several NAT and firewall devices (such as the PIX firewall) disable SNMP queries from their public interfaces.

Dynamic NAT

For non-server type devices (such as user systems), they usually get a dynamic IP address instead of a fixed address. These devices cannot be queried since the IP address is changing all the time.

NetVigil can be deployed in a NAT environment as long as there is a way to query the device being monitored. If the DGE is co-located near the private LAN, then an ethernet interface from the DGE can be attached to the NAT network directly.

NetVigil can be deployed in an environment with similar private addresses, as long as each of these networks has its own DGE. The provisioning database does NOT reference devices by IP addresses, so many devices can exist in the system with the same IP address. Each device is allocated to a DGE, so as long as the respective DGE can access the private (or NAT) network, the devices on these networks can be monitored by NetVigil.