Geneos ["Geneos"]
["Geneos > Netprobe"]["Technical Reference"]

Netprobe variables

Overview

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, variables can either be set in the registry or set as environment variables. For more information, 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.

Variables

Name Use
DISCOVERY_DEBUG

Used in auto-discovery. Available only in Geneos 5.x Netprobes.

When enabled, JSON metadata is written on the Netprobe log in the form of the Netprobe XML setup, both raw and resolved.

For more information, see Auto-discovery in Introduction to Netprobe.

Default value: false

DISABLE_MEM_PROTECTION

If set to true, stops the Netprobe from restarting due to the limits imposed by MEM_PROTECTION_RATIO.

Default value: false

DLL_PATH

Available only in the Windows registry.

Specifies where the Netprobe looks for its resource libraries. This registry key is analogous to the LD_LIBRARY_PATH environment variable in Linux platforms.

DLL_PATH can be used as an alternative to PATH when upgrading live Netprobe implementations. When this key is set, then it overrides the PATH environment variable, and the PATH environment variable is ignored.

You can specify multiple paths on they key value. The values must be semicolon-delimited.

DLL_PATH requires you to restart the Netprobe service to take effect.

LOG_FILENAME

The Netprobe error and log file. If the filename is not defined, the errors and messages are sent to standard output. Ensure that the directory where the log file resides is writeable, so that the Netprobe can create and write to the file.

Note:

  • This parameter is ignored if the Netprobe executable is run with the -nolog' command-line option.
  • If the Netprobe software has been installed on a shared drive and is being run on more than one machine at the same time, see Log files in Install a Netprobe on a shared drive for important information regarding the setting of this variable.
  • A full path can be specified in this variable if you wish to place this log file in a specific directory. If only the name is specified, then it will be created in the directory where the Netprobe is running.

LOG_TIME_FORMAT

The log time format used to record the timestamp that begins each line of the log file.

Possible values:

  • (default) ISO-8601: 2019-09-25 09:18:28.871-0400
  • ISO-8601-UTC: 2019-09-25 13:18:28.871Z
  • LEGACY: <Wed Sep 25 09:18:28>

Caution: On Windows platforms, this variable can only be set as an environment variable and cannot be set in the registry.

MAX_LOG_FILE_SIZE_MB

The Netprobe error and log file can be set up to roll over to a new log file when it gets bigger than the MAX_LOG_FILE_SIZE_MB set.

The maximum value that can be set is 4096 MB, and the minimum is 1 MB. If the value is outside of these ranges or the input is invalid, then the default of 10 MB will be used. This is the equivalent of the advanced Gateway Setup File setting maxLogFileSize.

MAX_MEM_SIZE

Limits the Netprobe to a memory equal to the MAX_MEM_SIZE.

For example, if MAX_MEM_SIZE is 500 MiB, then the Netprobe restarts when its memory reaches 500 MiB.

By default, the Netprobe does not check if it reaches a certain memory limit.

Check is done every 30 seconds.

Default value: 0

Unit: mebibytes (MiB)

Maximum allowable value: 1024 MiB

MEM_PROTECTION_RATIO

Limits the Netprobe to a memory equal to its starting memory multiplied by the MEM_PROTECTION_RATIO.

Check is done every 10 minutes after a Netprobe starts or restarts.

For example, if the Netprobe starts with 50 MiB of memory and the MEM_PROTECTION_RATIO is 3, then the Netprobe restarts when its memory reaches 150 MiB.

Default value: 2

Allowable range: 2 - 5

LOG_ARCHIVE_SCRIPT

The log file generated by Netprobe will grow up to 1 MB. The Netprobe will then rename the file by adding a .old extension and will open a new log file. If the LOG_ARCHIVE_SCRIPT is set, then the Unix script defined by the environment variable will be called after the log file has been renamed. The script parses the name of the .old file as a parameter. This script can be used to archive the log files into an archive area. By default, the script is not called.

NET_PORT The TCP/IP port number that the Gateway uses to connect to Netprobes. To avoid confusion it is recommended that this setting is the same for all the Gateways and Netprobes. The default port number is 7036.
ENCODED_PASSWORD
ALLOW_ENCODED_PASSWORD_DOWNLOAD

These two variables are used to control the use of passwords in relation to Netprobe commands. For more information on using these variables, see Set passwords on Netprobe commands, which also explains the alternative method of setting the password via the Gateway Setup.

TRUSTED_GATEWAY_HOSTS
TRUSTED_GATEWAY_NAMES

The TRUSTED_GATEWAY_HOSTS and TRUSTED_GATEWAY_NAMES variables are comma-separated lists containing one or more trusted hostnames or IP addresses or names of Gateways. If set, the Netprobe will accept connection from any of these Gateways.

By default, these variables are set to +, which means that all connections are accepted. You are not required to set both variables, but if you do, then any connections must match TRUSTED_GATEWAY_HOSTS and TRUSTED_GATEWAY_NAMES.

If a connection fails to match, then a warning message is logged on the Netprobe, all connected Gateways, and Active Console Event Tickers.

For security, you can only set these variables in the start-up environment on the machine running the Netprobe. You cannot configure them as part of the Netprobe on the Gateway.

If you have set TRUSTED_GATEWAY_HOSTS, the Netprobe checks the source IP of any connections against the list of hostnames and IP addresses. If an explicit IP address fails to match, then the Netprobe will try a reverse DNS lookup of the source IP by checking if any hosts in the list match. If the previous check still fails, then the Netprobe will check each hostname in the list and check the first returned IP address. Hostnames with multiple A records may not be validated correctly.

If a connection is permitted after the TRUSTED_GATEWAY_HOSTS check, then the Netprobe will check the name that the Gateway supplies against TRUSTED_GATEWAY_NAMES. If there is no match, then the connection is dropped, and an error message is logged.

Note: On IBM AIX, there is a known limitation that only IP addresses are checked, and no hostnames are resolved.

TRUSTED_HTTP_HOSTS

The TRUSTED_HTTP_HOSTS variable is a comma-separated list containing one or more trusted hostnames or IP addresses of the HTTP hosts. If set, the Netprobe will accept connection from any of these hosts.

By default, this variable is set to +, which means that all connections are accepted.

If a connection fails to match, then a warning message is logged on the Netprobe, all connected Gateways, and Active Console Event Tickers.

For security, you can only set this variable in the start-up environment on the machine running the Netprobe. You cannot configure them as part of the Netprobe on the Gateway.

If you have set TRUSTED_HTTP_HOSTS, the Netprobe checks any connections against the list of hostnames and IP addresses. If an explicit IP address fails to match, then the Netprobe will try a reverse DNS lookup by checking if any hosts in the list match. If the previous check still fails, then the Netprobe will check each host in the list and check the first returned IP address.

Note: On IBM AIX, there is a known limitation that only IP addresses are checked, and no hostnames are resolved.

TRUSTED_DEBUG_HOSTS

The TRUSTED_DEBUG_HOSTS variable is a comma-separated list containing one or more trusted hostnames or IP addresses of the debug hosts. If set, the Netprobe will accept connection from any of these debug hosts.

By default, the trusted debug host is 127.0.0.1. If this variable is set to +, then any HTTP host is trusted.

If a connection fails to match, then a warning message is logged on the Netprobe. For example,

WARN: ORB Non-trusted host itrslp003 rejected. Trusting only (127.0.0.1) for HTTP Debug components.

For security, you can only set this variable in the start-up environment on the machine running the Netprobe. You cannot configure them as part of the Netprobe on the Gateway.

If you have set TRUSTED_DEBUG_HOSTS, the Netprobe checks any connections against the list of hostnames and IP addresses. If an explicit IP address fails to match, then the Netprobe will try a reverse DNS lookup by checking if any hosts in the list match. If the previous check still fails, then the Netprobe will check each host in the list and check the first returned IP address.

Note: On IBM AIX, there is a known limitation that only IP addresses are checked, and no hostnames are resolved.

PERMISSIONS
This variable can be used to control which RMS commands can be executed on the Netprobe. Possible values are:
  • RMSPUT to enable PUT
  • RMSGET to enable GET
  • RMSEXEC to enable EXEC

Permissions can be combined using a plus sign. So, for example, to enable PUT and EXEC, set PERMISSIONS to RMSPUT+RMSEXEC.

Alternatively, PERMISSIONS can be set to RMSALL to enable all.

This is the equivalent of the advanced Gateway Setup File setting permissions.

TRUSTED_API_HOSTS

The TRUSTED_API_HOSTS variable is a comma-separated list containing one or more trusted hostnames or IP addresses of the API hosts. If set, the Netprobe will accept connection from any of these API hosts.

By default, this variable is set to +, which means that all connections are accepted. For more information, see XML-RPC Instrumentation API.

If a connection fails to match, then a warning message is logged on the Netprobe, all connected Gateways, and Active Console Event Tickers.

For security, you can only set this variable in the start-up environment on the machine running the Netprobe. You cannot configure them as part of the Netprobe on the Gateway.

If you have setTRUSTED_API_HOSTS, the Netprobe checks any connections against the list of hostnames and IP addresses. If an explicit IP address fails to match, then the Netprobe will try a reverse DNS lookup by checking if any hosts in the list match. If the previous check still fails, then the Netprobe will check each host in the list and check the first returned IP address.

Note: On IBM AIX, there is a known limitation that only IP addresses are checked, and no hostnames are resolved.

This is the equivalent of the advanced Gateway Setup File setting trustedAPIHosts.

PROCESS_LIST_COMMAND A probe-wide setting which affects all PROCESSES plug-ins for legacy Netprobes. This setting specifies a command to obtain process details for a legacy Netprobe. The default varies according to target operating system, but is typically "ps -ef". This is the equivalent of the advanced Gateway Setup File setting processListCommand.
WIDE_ PROCESS_LIST_COMMAND A probe-wide setting which affects all PROCESSES plug-ins running on a Solaris Netprobe. This setting specifies the command to obtain the full process name for processes with names longer than 75 characters. The default is "/usr/ucb/ps -axww". This is the equivalent of the advanced Gateway Setup File setting wideProcessListCommand.
CACHE_PROCESS_NAMES A Boolean value specifying whether to cache process names on Linux. This should be set to "false" if process names can change during execution. The default is "true". This is the equivalent of the advanced Gateway Setup File setting cacheProcessNames.
HEARTBEAT_INTERVAL When Netprobe does not receive any communication from a connected component within this number of seconds, it sends a heartbeat message to the component. Netprobe will then expect a reply within the number of seconds specified by the CONNECT_WAIT setting (see below). If the reply is not received within this time, the connection is terminated and re-established. The value supplied is in seconds, within the range 1 to 300, and defaults to 70. This is the equivalent of the advanced Gateway Setup File setting heartbeatInterval.
CONNECT_WAIT The time to wait for a connection to be established. The value supplied is in seconds, within the range 1 to 300, and defaults to 15. This is the equivalent of the advanced Gateway Setup File setting connectWait.
MAX_DATABASE_CONNECTIONS This sets the maximum amount of connections that a Netprobe can make to any database e.g. if managed_entity_1 belonging to probe_1 uses 3 SQL-TOOLKIT plug-ins, 1 Sybase plug-in and 1 Oracle plug-in and managed_entity_2 belonging to probe_1 uses the same, then they will have used 10 database connections in total. If probe_1 is using the default value then this means no more database connections could be made. The default is 10. This is the equivalent of the advanced Gateway Setup File setting maxDatabaseConnections.
PUBLISH_SCHEMA Set this variable to "false" to disable publishing of the schema file. This is the equivalent of starting the Netprobe with the -noschema Netprobe Command-line Options.
REJECT_TIMEOUT_INTERVAL Time for which a "bad" connection from a Gateway should be blocked before allowing it to retry.
MAIN_BUFFER_MAX

The maximum amount of outgoing comms data to store for the whole process. The value is in MB and in the range 25 to 250 inclusive. The default is 60.

Caution: On Windows platforms, this variable can only be set as an environment variable and cannot be set in the registry.

CONNECTION_BUFFER_MAX

The maximum amount of outgoing comms data to store for a single connection. The value is in MB and in the range 5 to 50 inclusive. The default is 30.

Caution: On Windows platforms, this variable can only be set as an environment variable and cannot be set in the registry.

FLUSH_DNS_PERIOD

The time to cache the result of a DNS lookup (this variable is more used in relation with Gateway, but can be used with Netprobe as well). The value is in seconds and is a positive integer amount. The default is 0, i.e. no flush.

Caution: On Windows platforms, this variable can only be set as an environment variable and cannot be set in the registry.

DISABLE_CORE_DUMP Set this variable to "true" to disable the creation of core dump files if Netprobe crashes. The default is "false".
LISTEN_IP Sets a specific IP address where the Netprobe will listen to incoming connections.

This argument can be used to force Self-Announcing Netprobes not to listen for incoming connections. See Disable listening in Manage Self-Announcing Netprobes.
CA_HEALTHCHECK_INTERVAL

Time in seconds between pings from the Netprobe to a managed Collection Agent.

Default value: 20

Note: This only applies to a managed Collection Agent not running in detached mode. For more information, see Detached mode in Collection Agent setup.

CA_MAX_HEALTHCHECK_ATTEMPTS

Maximum number of attempts that the Netprobe makes to contact a managed Collection Agent.

Default value: 3

Note: This only applies to a managed Collection Agent not running in detached mode. For more information, see Detached mode in Collection Agent setup.

CA_HEALTHCHECK_TIMEOUT

Time in seconds that the Netprobe waits for a response from the Collection Agent during a health check.

Default value: 5

Note: This only applies to a managed Collection Agent not running in detached mode. For more information, see Detached mode in Collection Agent setup.

CA_MAX_RESTARTS

Maximum number of attempts that the Netprobe makes to restart an unresponsive managed Collection Agent.

If the Netprobe fails to communicate with the managed Collection Agent after the maximum number of attempts, then the Netprobe stops monitoring the managed Collection Agent.

Default value: 3

Note: This only applies to a managed Collection Agent not running in detached mode. For more information, see Detached mode in Collection Agent setup.

   

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, and DISABLE_MEM_PROTECTION.

Setting variables for Netprobe on Windows platforms

On Windows platforms, variables can either be set in the registry or set as a Windows environment variable. Variables set in the registry take precedence over Windows environment variables. The Windows Netprobe installer creates 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, then that name replaces NetprobeNT in this key name.

Use the Registry Editor on Windows 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.

Utility Use Example
na_getenv.exe Extracts the value of a Netprobe registry key Using a default Netprobe installation (i.e. where the service name is "NetprobeNT"), the command na_getenv.exe NetprobeNT NET_PORT will return the default port value of 7036.
na_setenv.exe Sets the value of a Netprobe registry key Again using a default Netprobe installation, the command na_setenv.exe NetprobeNT NET_PORT 12345 will change the listen port for the service NetprobeNT to port 12345.

For a complete list of command-line options, see Netprobe 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
OS Bit Platform Registry Path
64-bit HKEY_LOCAL_MACHINE \SOFTWARE\NetAgent\