Netprobe User Guide

List of Supported Platforms

Please refer to the Geneos Compatibility Matrix for the list of supported platforms.

System Requirements

The type of information collected by the Netprobe is determined by the Plug-ins that are activated. For the majority of cases, the Netprobe needs to be installed onto the server to be monitored. For some Plug-ins the Netprobe can be installed onto any server that has access to the required information. E.g. for the MIBMON (SNMP MIB monitoring) Plug-in, the Netprobe can be installed onto any server.

Downloading and Installing (Solaris, Linux and AIX)

To download the Netprobe software, go to the ITRS website https://www.itrsgroup.com and log in using the client login field. If you do not already have a client login, then click on the "New User" link. Having logged in, select the "Downloads" client option. Then select the appropriate Netprobe download and save the downloaded file.

A single file with a name of the form <main body of name>.tar.gz is downloaded. This contains a number of files which have been tarred and zipped. They can be unpacked by using the commands:

gunzip <main body of name>.tar.gz
tar -xvf <main body of name>.tar

Once unpacked the tar file is no longer needed and can be removed.

If this is a new installation of the Netprobe, simply place the unpacked files in the directory from which Netprobe is to be launched.

If upgrading from an earlier version then stop the Netprobe, replace all of the files with those from the new version, and then restart the Netprobe.

Downloading and Installing (Windows)

For Windows there is a choice of two packages to download:

• an executable installer (named geneos-netprobe-*<version>*.windows-<platform>.setup.exe). This is an installer for the Windows Netprobe Package.

• a zip file (named geneos-netprobe-*<version>*.windows-<platform>.zip). This can only be used when upgrading a previous installation.

Note: <platform> is x86 for 32-bit and x64 for 64-bit.

Using a Shared Drive

It is possible to install a Netprobe on a shared drive and then run it on multiple nodes. However, there are a couple of things to be aware of if a Netprobe installation on a shared drive is going to be used by multiple nodes simultaneously:

1. If the Netprobes record their log output to file and they are writing their logs to the shared drive, then it is necessary to make sure that they each one is writing to a unique file. The Netprobes may crash if more than one Netprobe attempts to write to the same file. This is a problem that can be encountered, for example, if a shared script is being used to set up the environment and launch the Netprobe on a set of UNIX machines, and this script is setting LOG_FILENAME to the same file on the shared drive. In this example, one can work around the problem by changing the script to set it to something like

   setenv LOG_FILENAME netprobe.out.`hostname`

   This will generate a log file which includes the hostname as a suffix to the log file name, thus giving the Netprobe running on each machine a separate log file.

2. If the Message Tracker plug-in is being used, this writes a file in the Netprobe directory which ensures that no data is lost if the probe stops. If two Netprobe instances are using the same shared drive installation and both using Message Tracker plug-ins, there is the potential for these both to using the same name for this file and therefore overwrite each other's data. By default this file is called <Managed Entity Name>.<Sampler Name>.cache, but the name can be set by using the Message Tracker configuration setting persistenceFile.

   If multiple Netprobe instances are being run which use the same shared drive installation, more than one of which is running a Message Tracker sampler, it should therefore be ensured that each Message Tracker sampler has the persistenceFile setting defined and set to a name unique to that Netprobe and sampler.

Variables

The following variables fine-tune Netprobe operation or override the defaults. On non-Windows platforms these should be set as environment variables in the shell from which the Netprobe is launched. On Windows they should be set in the registry - see Setting Variables for Netprobe on Windows Platforms.

Where these variables are described as an equivalent of an advanced Gateway Setup File setting, more details on the Gateway Setup File setting can be found in Probes.

For Normal Netprobes, see Probe settings - Advanced tab.

For Floating Netprobes, see Floating Probe settings - Advanced tab

For Self-Announcing Netprobes, these settings cannot be defined in the Gateway Setup File - they have to be set by using the variable on the Netprobe.

Note: There are a number of other variables which can be set for debug or diagnostic purposes. These should only be used when requested or advised to do so by ITRS. These include DEBUG, GENERAL_DEBUG, GL_DEBUG, ISFS_SAMPLE_DEBUG, FKM_DEBUG, PROCESS_SAMPLE_DEBUG, SERVICE_SAMPLE_DEBUG, PROBE_MEM_TIME_INTERVAL, MAX_MEM_SIZE, DISABLE_MEM_PROTECTION and LEAK_MEMORY.

Setting Variables for Netprobe on Windows Platforms

For Windows platforms, the Netprobe does not read the above variables from the environment variables. Instead, these values need to be set in the registry. The Windows Netprobe Installer will have created a set of registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\NetAgent\NetprobeNT* (if a non-default service name was specified when the Netprobe was installed, that name will replace "NetprobeNT" in this key name).

Use the utility regedt32.exe on the Windows platform (supplied as part of the operating system) to edit the values or add new name-value pairs in this set of registry keys.

Alternatively, it is possible to get or set Netprobe registry keys using the utilities na_getenv.exe and na_setenv.exe which are installed as part of the Windows Netprobe package.

See binary command line options for Windows and other platforms. For a complete list of command line options, see Command Line Options.

Location of Windows registry files for Netprobe

Go to the Registry Editor to locate the registry path of the Netprobe. The default registry path of Netprobe is:

HKEY_LOCAL_MACHINE \SOFTWARE : \system32\config\software

Starting the Netprobe

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\NetprobeNT*\ImagePath

The user may prefer to run the Netprobe from the command line rather than as a service. If the same port or Netprobe log are going to be used, then it is necessary to first stop the service. To launch the Netprobe from the command line, first change folder to the folder containing the Netprobe. Then run the executable, specifying any Command Line Options that are required.

Note: This must include the -cmd command line option, which indicates that the Netprobe is to be run in the foreground (i.e. from the command line) rather than as a service.

Whether running as a service or from the command line, any Variables that are required should be set in the registry - see Setting Variables for Netprobe on Windows Platforms.

Gateway Setup Settings for Netprobe

For Normal, Virtual, and Floating Netprobes, various properties related to the Netprobe need to be configured in the Gateway File. These settings determine the relationship of Gateway with the Netprobe. Some of these properties are also downloaded to the Netprobe when it connects to the Gateway, controlling the Netprobe's behaviour. For information on Netprobe configuration settings in the Gateway Setup File, see Probes.

For Self-Announcing Netprobes, the Netprobe itself does not need to be configured in the GatewaySetup File . However, there are settings which still need to be set in the Gateway Setup File. These settings control the Gateway's behaviour with respect to Self-Announcing Netprobes. For example, controlling whether the Gateway will accept Self-Announcing Netprobes at all and, if so, which ones. For more information on the Gateway Setup File settings which relate to Self-Announcing Netprobes, see Self-Announcing Netprobes Technical Reference.

Note: Certain plug-ins run on the Gateway, instead of an external Netprobe process. For more information on these plug-ins, see Gateway Plug-Ins.

Once a connection is established, the Gateway can determine the state of a Netprobe as follows:

• Down — the machine is up, but no active port is detected.
• Unreachable — the host is unreachable; alternatively, there is a detected Netprobe process, but it is unresponsive or has a port issue.

For more information about probe connection status, see samplers > sampler > plugin > Gateway-probeData in Gateway Plug-Ins.

Running Netprobe under Elevated Privileges in Linux

When the privileges of netprobe is raised (e.g. via setcap/setuid), the runtime loader of Linux (ld.so) will not be able to load the libraries from the <netprobe directory>/lib64, as it will ignore RPATH and LD_LIBRARY_PATH. This is the way ld.so has been designed.

In order for the libraries to be loaded, the path to the lib64 folder has to be added to the trusted paths of ld.so. This can be done by doing the steps below, as root user.

1. Create a conf file in /etc/ld.so.conf.d/. The conf file should contain the path to the lib64 folder inside your netprobe directory.

[root@localhost netprobe]# echo /home/inbound/binaries/netprobe/geneos-netprobe-4.0.0.linux-x64/netprobe/lib64/ > /etc/ld.so.conf.d/netprobe.linux_64.conf

2. Rebuild the ld runtime cache by executing ldconfig.

[root@localhost netprobe]# ldconfig

After these steps, the netprobe can be run using the desired user and can load the runtime libraries without issues.

Installer command line options

The installer command line options are available only to Windows platforms.

The /nopassword option will override /pass option but ENCODED_PASSWORD will still be set in the registry.

To set up a Self-Announcing or Floating Netprobe from the installer wizard, check the "Install as Self-Announcing or Floating Netprobe" checkbox from the "Configure Self-Announcing or Floating Netprobe" screen. Select a configuration file from that screen.

You can also specify the Self-Announcing or Floating Netprobe configuration file through installer command-line switch. To do this, start a new Administrator command-line window and run geneos-netprobe-<version>.windows-<platform>.setup.exe.windows-x64.setup.exe /setup=<setup xml filename>, where <setup xml filename> specifies the full path to the Self-Announcing or Floating Netprobe configuration file:

geneos-netprobe-*<version>*.windows-<platform>.setup.exeExample: geneos-netprobe-*<version>*.windows-<platform>.setup.exe. 

For more information, see Self-Announce Settings .

To setup a secure Netprobe from the installer wizard, check the "Run probe in Secure Mode" checkbox from the "Configure Netprobe Secure Connections" screen. Select a PEM file that contains both the secure key and the secure certificate that the probe will use. This can also be done on the command line by using the /ssl-certificate flag. The flag followed by the name of the PEM file to use.

The certificate chain that is used to verify the certificates presented to the Netprobe can also be set either by using the wizard and setting the file on the "Configure Netprobe Secure Chain" page, or by using the /ssl-certificate-chain command flag. In both cases a file containing the certificates with which the presented certificates have been signed must be provided.

If you're doing a silent mode install using either /silent or /verysilent option then the /setup= switch should be used if a the probe is to run as a Self-Announcing or Floating Netprobe. The /ssl-certificate= flag should be used if the Netprobe is to run in a secure mode and only accept secure (TLS) connections from the gateway. The /ssl-certificate-chain= switch should be used if the Netprobe is to validate the gateway certificates prior to allowing the gateway to connect to the probe. If any of the files specified do not exist then the installer will fail silently and an 'Install Failed' line will be logged in the setup log. You can specify the log file with the /log=<log file> switch in the installer.

On completion, the Netprobe will have been installed and started running as a service. The relevant registry settings will also have been set up.

Note: If the Windows Win Apps Plug-in is to be run on a Windows 2008 Server, then it is necessary to alter the properties of the service to "Allow service to interact with desktop". See the Windows Win Apps plug-in documentation for further information.

Restricting Gateway Hosts

In order to provide an extra level of security, it is possible to configure a Netprobe to only accept connections from a nominated 'trusted' list of Gateway hosts.

This is done by setting the TRUSTED_GATEWAY_HOSTS variable, either as an environment variable on UNIX or in the registry on Windows (see Setting Variables for Netprobe on Windows Platforms). The variable should be set to the names of the trusted hosts, separated by commas.

TRUSTED_GATEWAY_HOSTS may contain a host alias as defined in /etc/hosts file. If TRUSTED_GATEWAY_HOSTS is set to "+", then any Gateway is trusted - this is equivalent to not setting the TRUSTED_GATEWAY_HOSTS variable.

Non-trusted hosts attempting to connect will cause a warning message to be logged on the Netprobe and to all connected Gateway and ActiveConsole Event Tickers.

For security reasons the TRUSTED_GATEWAY_HOSTS setting can only be set as a variable on the machine running the Netprobe - it is not possible to set it as part of the probe configuration on the Gateway.

Note: Only one Gateway should attempt to connect to each Netprobe. If multiple Gateways connect to a single Netprobe, only the first connection attempt will get a successful connection. The succeeding connection attempts will be rejected.

A similar setting TRUSTED_GATEWAY_NAMES can be configured to restrict Gateways connecting to Netprobe in the same manner as TRUSTED_GATEWAY_HOSTS above. This setting checks the Gateway name rather than the host.

Restricting HTTP Hosts

It is also possible to configure a Netprobe to only accept HTTP connections from a nominated 'trusted' list of HTTP hosts.

This is done by setting the TRUSTED_HTTP_HOSTS variable, either as an environment variable on UNIX or in the registry on Windows (see Setting Variables for Netprobe on Windows Platforms). The variable should be set to the names of the trusted hosts, separated by commas.

TRUSTED_HTTP_HOSTS may contain a host alias as defined in /etc/hosts file. If TRUSTED_HTTP_HOSTS is set to "+", then any HTTP host is trusted - this is equivalent to not setting the TRUSTED_HTTP_HOSTS variable.

Non-trusted hosts attempting to connect via HTTP will cause a warning message to be logged on the Netprobe and to all connected Gateway and ActiveConsole Event Tickers.

Setting Passwords on Netprobe Commands

The user can configure commands in their Gateway which will be executed by the machine running one of the Netprobes to which it is connected. Because there are clearly some security implications in permitting one machine to run a command on a different machine, this functionality is by default password controlled, i.e. the user will be prompted for a password when running such a command. There are several options open when setting this up.

Using Transport Layer Security (TLS) 

Geneos components can communicate using Transport Layer Security (TLS) as well as TCP/IP. This is configured using command line options for a listening gateway and using the xml setup file for Floating and Self-Announcing Netprobes. See Secure Communications.

Floating Netprobes

In Floating mode, a Netprobe and Managed Entity will already be configured on the Gateway but without connection details. On starting, the Netprobe will inform the Gateway of its hostname and its listen port, and the Gateway will then connect as normal. This allows a Netprobe to automatically follow an application that migrates between servers.

Self-Announcing Netprobes

For a Self-Announcing Netprobe, no Netprobe or Managed Entity need be configured on the Gateway. Instead the Netprobe Setup File specifies both the Probe name and Managed Entity name along with one or more type names that correspond to types in the Gateway Setup File. This allows Netprobes to start up on any hosts and immediately be configured with default monitoring.

In addition, the Netprobe Setup File can specify zero or more Managed Entity Attribute name-value pairs. These can be used by ActiveConsole for searching and sorting purposes. Attributes are typically used with the logical mode of the ActiveConsole State Tree.

Netprobe Setup File can also set user defined variables that will be set on the created Managed Entity. Managed Entities can contain any number of variables. The variables section is not parsed by the probe, it is passed to the gateway to be checked. All variable types that can be entered on in the gateway setup are accepted except for activeTime and any passwords.

Load Balancing

In Self-Announcing mode, the Netprobe Setup File must specify one or more Gateways to announce to.

When more than one Gateway is specified, the following occurs:

1. The Netprobe attempts to contact each Gateway.
2. The Gateways respond, indicating if they are willing to accept the Netprobe. Each Gateway provides its score, indicating how highly loaded it is. See Score.
3. The Netprobe picks the least loaded Gateway to announce to, and listens for a connection in the normal way.
4. If there is a tie, the Netprobe picks the first of the least loaded Gateways, in the order specified in the Netprobe Setup File.

Score

Self-announcing Netprobes use the Gateway score to determine what Gateway to connect to.

Each Netprobe gives an individual score which represents the load it puts on a Gateway. The Gateway score is the total of the scores from every Netprobe on a Gateway. The score is a measure of how loaded a Gateway is. Currently, the score is the number of samplers configured on a Netprobe.

You can use the Probe Data plugin to see the score from each Netprobe. See Probe data.

Rebalance self-announcing Netprobes

You can redistribute SANs across your Gateways using the Rebalance Self-Announcing Netprobes command. This command removes SANs from a Gateway to either reach a target number of SANs or to reach a target Gateway score.

You may want to use this command to redistribute SANs to a recently restored Gateway from other Gateways across your cluster.

See Gateway Commands.

Disable listening

There are two ways to configure self-announcing Netprobes not to listen for incoming connections on their configured port:

• Use the command line argument -listenipwith the value none.
• Set the environment variable LISTEN_IP to none.

Either method does not remove the configured port from the Netprobe, and the port is still used by Gateway to identify its connection with the Netprobe.

Netprobe Setup File

<netprobe executable> -extract npschema <filename>

<probeName><hostname/><data>_</data><port/></probeName>

<var name="var_ActiveTime"> 
	<activeTime>
		<activeTime ref="ABC"> </activeTime>
	</activeTime>
</var>

Example Netprobe Setup Configurations

Self-Announcing

<?xml version="1.0" encoding="ISO-8859-1"?>
<netprobe
        compatibility="1"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/GA2011.2-110303/netprobe.xsd">
        <selfAnnounce>
                <enabled>true</enabled>
                <retryInterval>60</retryInterval>
                <requireReverseConnection>false</requireReverseConnection>
                <probeName>myProbe</probeName>
                <managedEntities>
	                <managedEntity>
	                        <name>myEntity</name>
	                        <attributes>
	                                <attribute name="COUNTRY">USA</attribute>
	                                <attribute name="CITY">CHICAGO</attribute>
	                                <attribute name="ENVIRONMENT">PROD</attribute>
	                        </attributes>
	                        <variables>
	                                <var name="var_string">
	                                        <string>selfProbe</string>
	                                </var>
	                                <var name="var_double">
	                                        <double>10.1</double>
	                                </var>
	                        </variables>
	                        <types>
	                                <type>Linux</type>
	                                <type>Fidessa</type>
	                                <type>ProdShare</type>
	                        </types>
	                </managedEntity>
                </managedEntities>			
                <gateways>
                        <gateway>
                                <hostname>chimx165</hostname>
                                <port>17101</port>
                                <secure>true</secure>
                        </gateway>
                        <gateway>
                                <hostname>chimx165</hostname>
                                <port>17102</port>
                        </gateway>
                        <gateway>
                                <hostname>chimx165</hostname>
                                <port>17103</port>
                                <secure>false</secure>
                        </gateway>
                </gateways>
        </selfAnnounce>
</netprobe>

Floating

<?xml version="1.0" encoding="ISO-8859-1"?>
<netprobe
        compatibility="1"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="http://schema.itrsgroup.com/GA2011.2-110303/netprobe.xsd">
        <floatingProbe>
                <enabled>true</enabled>
                <retryInterval>60</retryInterval>
                <requireReverseConnection>false</requireReverseConnection>
                <probeName>myFloatingProbe</probeName>
                <gateways>
                        <gateway>
                                <hostname>chimx158</hostname>
                                <port>17101</port>
                                <secure>false</secure>
                        </gateway>
                </gateways>
        </floatingProbe>
</netprobe>

Gateway Setup

For references to Gateway Setup requirements when using Floating and Self-Announcing Netprobes, see Gateway Setup Settings for Netprobe.

Rejection Reasons

Potential Configuration Conflicts

Disconnection Behaviour

If a Gateway to self-announcing Netprobe (SAN) connection is disconnected, either due to network failure or one party dropping the connection for one of the reasons stated above, then the following rules apply:

Hot Standby Gateways

Where Hot Standby Gateway pairs are used, both should be specified in the Netprobe Setup File. A non-active Gateway will refuse to accept the Netprobe so there is no risk of the Netprobe choosing a secondary Gateway while the primary is still up.

Plug-In Whitelist

The Plug-In Whitelist is a list of plug-in names that determine is a plug-in can be used by the Netprobe for sampling. If a plug-in is not specified in the whitelist, then the sampler associated with the plug-in cannot perform sampling during runtime.

The whitelist is specified in the Netprobe Setup File.

Note: If no setup file is specified, or if the whitelist does not contain any valid plug-in names, then all plug-ins are allowed by default.

Plug-in names that can be used follow the ones specified in the Gateway Setup Editor.

Below is a screenshot of a disabled sampler:

Netprobe Setup File

Example Netprobe Setup Configurations for whitelist

Plug-in Whitelist (Enables CPU and TOP plug-ins)

<netprobe>
        <pluginWhiteList>
                <data>cpu</data>
                <data>top</data>
        </pluginWhiteList>
</netprobe>

Command Whitelist

The Command Whitelist is a list of shell commands that can be used by the Netprobe for sampling. If a shell command is not specified in the whitelist, then an error will be shown in the dataview.

Affected commands are configurable plug-in shell commands that are invoked by the plug-ins themselves, as well as user commands specified via the gateway setup editor and are invoked by the user in the active console.

The whitelist is specified in the Netprobe Setup File.

Note: If no setup file is specified, or if the whitelist does not contain any shell commands, then all shell commands are allowed by default.

The command white list makes use of regular expressions to specify the allowed commands. Syntax is based on Perl-Compatible Regular Expressions (PCRE).

When matching for exact strings, always terminate your regular expressions (b).

Below are screenshots of error messages:

Affected Plugins and Features

Below is the list of plug-ins and features that have user-configurable shell commands that are affected by the command whitelist:

Caution: In Toolkit plug-in, you can use the Advanced functionality to write the script to the server. Unless the Toolkit Advanced tab is secured by a Gateway hook validation, it is possible to workaround the restriction set in the command whitelist.

• cpu
• toolkit
• network
• processes
• gl-orderbook
• fidessa
• flm
• gl-lostorders
• informix
• ipc
• market-data-monitor
• net-ping
• tcp-links
• unix-users
• veritas-cluster-server

Netprobe Setup File

Example Netprobe Setup Configurations for whitelist

<netprobe>
        <commandWhiteList>
                <data>echo test\b</data>
                <data>^cat.*</data>
        </commandWhiteList>
</netprobe>