Configuration and Operations

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 Stop/Start Fidelia NetVigil from Start | Programs | 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:

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.

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:

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 
provisioning database (poet) is running
dge monitors are running
dge database (mysql) is running
application server (jakarta tomcat) is running
virtual frame buffer (xvfb) is 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:

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.

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:

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.

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.

3.4.7 DGE Identity

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

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

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:

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:

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

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:

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:

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

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:

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:

3.4.13 Web User Interface Appearance


Configuration File	Affected Components	Affected Operating Systems
`NETVIGIL_HOME/tomcat/webapps/ROOT/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.


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

This is similar to the above mentioned stylesheet, except this governs how the administrative sections of the web interface will look.

3.5 Provisioning Devices and Tests

You can provision individual devices and tests through NetVigil's web interface, or you can do it in bulk via the Device AutoDiscovery tool (which uses the BVE API).

3.5.1 Device and Test AutoDiscovery

NetVigil includes a network discovery tool that will scan the network (according to restrictions set by you) for IP devices that can be monitored, and given a number of possible SNMP community strings, the discovery engine will attempt to discover which one of these devices are SNMP capable and their type. Finally the engine creates an import file that is suitable for the batch provisioning tool (described in Section 3.5.2, "Manual Batch Creation of Devices and Tests" on page 3-14) which will create the devices and tests in the system.

Configuration Files

The discovery engine is comprised of two configuration files. The first file ("subnet" file) contains a list of IP networks in CIDR format. This is a plain text file with one network entry on each line in the following general format:

This indicates that the network discovery engine should limit its search to two class-C networks listed (192.168.123.0 w/mask 255.255.255.0 and 10.20.8.0 w/mask 255.255.248.0).

The second configuration (or community ID) file contains a list of SNMP community strings, one on each line, that the discovery engine should try against discovered devices. The engine will perform a single SNMP query with each community string (or until a match is found) and mark the device SNMP capable if a valid response is received.

Running Your First Discovery

NetVigil has a "wrapper" tool that takes care of performing the network discovery, starting the BVE API server, and use the batch provisioning tool to provision the discovered devices, along with various ICMP, SNMP and port tests on those devices. This will enable you to quickly populate the system with devices on your network and start monitoring them.

To run the initial discovery:

Edit NETVIGIL_HOME/utils/probe_subnets.txt and enter the local IP networks/subnets that you wish to probe.

Edit NETVIGIL_HOME/utils/probe_community.txt and enter the SNMP community strings used for your SNMP capable devices.

Devices will be imported into the default Department and location (localuser and Default Location respectively). If you wish to change them, please edit NETVIGIL_HOME/utils/runNetworkDiscover.sh (runNetworkDiscover.cmd on Windows) and change the values towards the top.

Start the discovery:

On linux/solaris:

				su
				NETVIGIL_HOME/utils/runNetworkDiscover.sh 

 On windows:

Start | Programs | Fidelia NetVigil | Run Network Discovery

Discovery Without Provisioning

If you wish to only discover the devices, but not immediately provision them into the NetVigil provisioning database, you can run the discovery tool manually instead of using the "wrapper" tool. This way you can inspect the contents of import file and make changes/remove existing entries before using the batch provisioning tool. This will also enable you to specify different login and location names for the batch provisioning tool.

To run the discovery tool, open a shell/command prompt and use the following commands:

su
cd NETVIGIL_HOME/utils
./probeNetwork.pl --subnets probe_subnets.txt \
		--community probe_community.txt --resolvedns \
		--output import_file.txt

cd NETVIGIL_HOME\utils
probeNetwork.pl --subnets probe_subnets.txt ^
		--community probe_community.txt --resolvedns ^
		--output import_file.txt

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 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

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

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.

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

3.6 Monitoring Log Files

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:

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

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:

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

3.8 Maintenance Tasks

3.8.1 Database backup/restoration

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 2-11.) 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:

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

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.8.2 Upgrading DGE Hardware

As the load on a DGE increases, it may be necessary to perform upgrades to the capacity of the hardware to increase the physical limits of the machine. If the upgrade involves addition of resources (memory, disk space, etc.) to the same machine, no special steps need to be performed. However, an upgrade may involve replacing the entire machine with a more powerful one. It may also be necessary to add a new DGE as a replacement for a failed machine. In either case, only the database and configuration files need to be copied over (although you may choose to copy the contents of the NETVIGIL_HOME) to the new machine. If you have a latest backup of the NETVIGIL_HOME/database, you can simply copy the archive to the new machine, and extract it under NETVIGIL_HOME. Refer to the section on database backup/restoration for additional details.

3.9 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.9.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.9.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.9.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 application	any	dge database lookup
tcp	incoming	7655	any	any	dge status 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.10 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:

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.

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

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.