If you are currently using version 5.x.x, we advise you to upgrade to the latest version before the EOL date. You can find the latest documentation here.
Netprobe setup
Overview
After a Netprobe is installed and running on a machine, the next step is to set it up to connect to a Gateway. Depending on the mode that the Netprobe is running in, as well as its relationship with a Gateway, you can set up a Netprobe by itself or from the Gateway.
Gateway setup settings
For normal, floating, and virtual Netprobes, various properties related to the Netprobe need to be configured in the Gateway. 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. For information on Netprobe configuration settings in the Gateway Setup File, see Probes.
Floating Netprobes do not rely entirely on the Gateway setup, and have some limited setup options available. For more information, see Floating settings.
For Self-Announcing Netprobes, the Netprobe itself does not need to be configured in the Gateway. 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, the Gateway can control whether it accepts 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.
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.
Netprobe setup file
The Netprobe setup file is an XML document that follows the XML 1.0 specification. It is used primarily to enable the Netprobe to run in floating and self-announcing modes.
The contents of a valid XML document can be described by a set of rules called the schema. This schema is distributed with the Netprobe and can be used by any schema-aware XML editor to ensure that the setup file is well-formed and that the contents are valid.
For guidance in setting up a Netprobe running in normal mode, see How to create and configure a new standard probe in Probes.
Netprobe setup file contents
The Netprobe setup file has a single top-level
netprobe element under which it can have
either a selfAnnounce or floatingProbe element.
Self-announce settings
With Self-Announcing Netprobes, no Netprobe or Managed Entity is configured on the Gateway. Instead, you configure the Netprobe setup file to specify both the Netprobe and Managed Entity names, along with one or more type names that correspond to types in the Gateway setup file. This configuration 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 Active Console for searching and sorting purposes. Attributes are typically used with the logical mode of the Active Console State Tree.
Netprobe Setup File can also set user-defined
variables 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.
Consider the following setup file for a Self-Announcing Netprobe:
<?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>
| Element | Sub-element | Sub-element | Description |
|---|---|---|---|
| selfAnnounce |
Setup values for Self-Announcing Netprobemode. Mandatory: No |
||
| selfAnnounce > | enabled |
When set to If set to Mandatory: Yes |
|
| selfAnnounce > | retryInterval |
Specifies the time in seconds that the Netprobe waits after failing to find a suitable Gateway to announce to, or after the master connection drops, before restarting the polling process. Mandatory: No Default value: |
|
| selfAnnounce > | requireReverseConnection |
When set to By default, Self-Announcing Netprobes make Netprobe-to-Gateway connections where both components support it. This setting ensures that the Netprobe will not select a Gateway that does not support reverse connections, and will prevent the Gateway from publishing the The default value for this depends upon whether the Netprobeis configured to connect to a secure Gateway. If any of the Gateway connections have the secure flag set to Mandatory: No Default: Dependent on other settings |
|
| selfAnnounce > | probeName |
The name of the probe to create on the Gateway.
This name must not already be in use in the Gateway configuration, or be used by other . The probe name can be composed of any number of data elements containing raw text and special macro elements that resolve to installation-specific strings, such as hostname. This allows a single Setup File to be used for Self-Announcing Netprobes on many different servers. The following macro elements are supported:
To create a probe name in the format <probeName><hostname/><data>_</data><port/></probeName>
Mandatory: Yes |
|
| selfAnnounce > | probeName > | data > hostname |
Host name element of probe name. Mandatory: No |
| selfAnnounce > | probeName > | data > port |
Netprobe's listen port element of probe name. Mandatory: No |
| selfAnnounce > | restApiHttpPort |
Insecure port where content is ingested by the REST API plug-in. This port is used by all REST API samplers running on the probe. By default, the REST API plug-in listens only on this port. If you create a REST API sampler without configuring any listening port, then this default behaviour applies. If you configure both insecure and secure ports, then the REST API sampler listens on both ports concurrently. Caution: If you set the same value for both HTTP and HTTPS ports, then the Netprobe only starts the REST API HTTPS server. If the SSL certificate or key is invalid for the server, then the Netprobe does not start the HTTP server. Note: Updating the port causes all REST API samplers on the probe to reload. If you do not configure this setting, but there exists a REST API sampler under the type specified in Netprobe setup, then the Self-Announcing Netprobe starts a REST API HTTP server with the default port Mandatory: No Default: |
|
| selfAnnounce > | restApiHttpsPort |
Secure port where content is ingested by the REST API plug-in. This port is used by all REST API samplers running on the probe. This setting requires an SSL certificate and SSL certificate key. If you configure this port without configuring the insecure port, then the REST API sampler listens only on the secure port. If you configure both insecure and secure ports, then the REST API sampler listens on both ports concurrently. Caution: If you set the same value for both HTTP and HTTPS ports, then the Netprobe only starts the REST API HTTPS server. If the SSL certificate or key is invalid for the server, then the Netprobe does not start the HTTP server. When you use HTTPS for the REST API plug-in, follow these guidelines:
Note: Updating the port causes all REST API samplers on the probe to reload. Note: If this option is set, then the REST API plug-in uses the SSL certificate and SSL certificate key as specified in the If you do not configure this setting, but there exists a REST API sampler under the type specified in Netprobe setup, then the Self-Announcing Netprobe starts a REST API HTTP server with the default port Mandatory: No |
|
| selfAnnounce > | collectionAgent |
Note: Beginning Geneos 5.1, the Collection Agent is included in the Netprobe binaries for and generic platforms. List of collectionAgent options. Mandatory: No |
|
| selfAnnounce > | collectionAgent > | start |
If enabled, then the Netprobe runs an instance of the Collection Agent as a Java process. If you disable this option, then the Netprobe stops any running managed Collection Agent process. This applies whether or not the Collection Agent is running in detached mode. Mandatory: No |
| selfAnnounce > | collectionAgent > | jvmArgs |
Specifies additional JVM options for when the Collection Agent starts. By default, the Collection Agent runs with the following JVM options:
If the Collection Agent cannot access Caution: This fallback behaviour is not supported on . Mandatory: No |
| selfAnnounce > | collectionAgent > | healthPort |
Specifies the Collection Agent port that the Netprobe communicates with for health checks. For more information, see Health checks in Run Collection Agent with Netprobe. Default value: Mandatory: No |
| selfAnnounce > | collectionAgent > | reporterPort |
Specifies the Collection Agent port to be used for communicating with the Dynamic Managed Entities using the TcpReporter. Default value: Mandatory: No |
| selfAnnounce > | collectionAgent > | detached |
If enabled, then the managed Collection Agent keeps running even if the Netprobe stops. When detached mode is enabled, the managed Collection Agent only stops when you disable its For more information, see Detached mode in Run Collection Agent with Netprobe. Default value: |
| selfAnnounce > | dynamicEntities > | mappingType |
Specifies the mapping type used to generate Dynamic Managed Entities for this probe. A Self-Announcing Netprobe version 5.1.2 or later, that is configured with a Dynamic Entities Mapping type, will not connect to a Gateway version 5.0.x or earlier. A failed connection will be recorded in the Netprobe log, with a warning that the Gateway version is too old. For more information, see Dynamic Entities. Mandatory: No |
| selfAnnounce > | managedEntities |
List of You can have multiple Managed Entities on the setup file. |
|
| selfAnnounce > | managedEntities > | managedEntity |
Specifies the configuration details for the Managed Entity to be created on the Gateway. Mandatory: Yes |
| selfAnnounce > | managedEntities > | managedEntity > name |
The name of the Managed Entity to create on the Gateway. This name must not already be in use in the Gateway configuration or be used for other Self-Announcing Netprobes. The Managed Entity name is case sensitive. Mandatory: Yes |
| selfAnnounce > | managedEntities > | managedEntity > attributes |
A list of user defined attributes that will be applied to the created Managed Entity. Managed Entities can contain any number of attributes. Each attribute is specified as a name-value pair containing a textual value. These attributes can then be used for searching and sorting in ActiveConsole. A special Mandatory: No |
| selfAnnounce > | managedEntities > | managedEntity > variables |
A list of 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. Variables setting can be copied from XML Section of Gateway > ManagedEntity > Advanced tab > Var inGateway Setup Editor, or from Gateway setup file. Variables may be ignored by the Gateway. For more information, see Managed entity variables in Rejection reasons. Mandatory: No |
| selfAnnounce > | managedEntities > | managedEntity > types |
A list of referenced types that will be applied to the created Managed Entity. These types refer to the named types in the Gateway configuration. These types (and the associated samplers) will be loaded into the created Managed Entity when the Netprobe connects to a Gateway. Duplicate types will be ignored. Mandatory: No |
| selfAnnounce > | gateways |
A list of candidate Gateways that the Netprobesattempts to connect to. The order of the list determines which Gateway the Netprobe connects to if there is a tie. For more information, see Load balancing in Manage Self-Announcing Netprobes. Mandatory: Yes, at least one Gateway |
|
| selfAnnounce > | gateways | gateway > hostname |
The hostname of a candidate Gateway, to which the Netprobe will connect. Mandatory: Yes |
| selfAnnounce > | gateways | gateway > port |
The listen port of a candidate Gateway, to which the Netprobewill connect. Mandatory: Yes |
| selfAnnounce > | gateways | gateway > secure |
Flag to indicate if the probe should use a secure or an insecure protocol when connecting to the Gateway.
Mandatory: No
Default: False
|
| selfAnnounce > | encodedPassword |
A password encoded using the crypt command-line utility, which is then requested when you attempt to execute a Netprobe command. When defined, this setting takes precedence over passwords defined through environment variables. For more information, see Types of password offered by the Gateway and how to generate them in Secure Passwords. |
|
| selfAnnounce > | cyberArkApplicationID |
Name used to identify the CyberArk permissions for the Self-Announcing Netprobe. This determines which passwords can be requested, and must be configured in the CyberArk web interface. This setting is used for the CyberArk Local Credential Provider. If not defined, then the value defaults to |
|
| selfAnnounce > | cyberArkSdkPath |
Path to the Application Password SDK installed on the Netprobe host. The path must be fully specified and cannot embed any references to environment variables. This setting is used for the CyberArk Local Credential Provider. If not defined, then the value defaults to the following:
|
|
Advanced settings
You can also use some of the advanced settings of a standard Netprobe to configure a Self-Announcing Netprobe. To apply the advanced settings for Self-Announcing Netprobes, you can add them to the start-up script or set them as environment variables:
setenv <variable name> <value>
export <variable name>=<value>
| Advanced setting | Variable name |
|---|---|
| Max log file size | maxLogFileSize |
| Wide process list command | wideProcessListCommand |
| Cache process names | cacheProcessNames |
| Max database connections | maxDatabaseConnections |
| Case insensitive filenames (Unix based OS) | caseInsensitiveFilename |
| Command time out | commandTimeOut |
| Fkm lock file path | fkmLockFilePath |
| Max toolkit processes | maxToolkitProcesses |
For more information about these settings, see Probe settings - Advanced tab in Probes.
Floating settings
In floating mode, a Netprobe and Managed Entity are configured on the Gateway, but without connection details.
On starting, the Netprobe informs the Gateway of its host name and listen port. In turn, the Gateway connects to the Netprobe. This allows a Netprobe to automatically follow an application that migrates between servers.
Consider the following setup file for a floating Netprobe:
<?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>
| Element | Sub-element | Sub-element | Description |
|---|---|---|---|
| floatingProbe |
Setup values for the Floating Netprobe mode. Mandatory: No |
||
| floatingProbe > | enabled |
Enables or disables the Floating Netprobe mode. Mandatory: Yes |
|
| floatingProbe > | retryInterval |
Time in seconds that the Netprobe waits after failing to announce itself to a Gateway, or after the master connection is dropped, before restarting the announcing process.
Mandatory: No
Default value:
60 |
|
| floatingProbe > | requireReverseConnection |
When set to By default, floating Netprobes make Netprobe-to-Gateway connections where both components support it. This setting ensures that theNetprobe will not select a Gateway that does not support reverse connections. The default value for this depends upon whether the Netprobeis configured to connect to a secure Gateway. If any of the Gateway connections have the secure flag set to Mandatory: No Default: Dependent on other settings |
|
| floatingProbe > | probeName |
Specifies the name of this Netprobe. The probe
must already have been configured as a
Mandatory: Yes |
|
| floatingProbe > | gateways |
The Gateway or Gateways to which the floating Netprobe should connect. Up to two Gateways are allowed. If two are set then they must be a hot-standby pair. Mandatory: Yes, at least one Gateway must be configured. |
|
| floatingProbe > | gateways | gateway > hostname |
The host name of the Gateway to which the Netprobe should connect. Mandatory: Yes |
| floatingProbe > | gateways | gateway > port |
The listen port of the Gateway to which the Netprobe should connect. Mandatory: Yes |
| floatingProbe > | gateways | gateway > secure |
Flag to indicate if the probe should use a secure or an insecure protocol when connecting to the Gateway.
Mandatory: No
Default: false
|
OS environment variables
Beginning Geneos 5.3.x, the Netprobe setup file supports using macros to access environment variables available to the host platform.
The syntax for the new macro is [[$env:VARIABLE_NAME]].
The Netprobe evaluates environment variables only once during its lifecycle. That is, during a Netprobe process startup and restart.
If an environment variable cannot be determined, then the macro remains unresolved.
Environment variables abide by OS-specific rules, precedence, and profiles.
environment variables
On , you can use any available environment variables. For example, if the value of $SHELL in the environment is /bin/bash, then [[$env:SHELL]] resolves to /bin/bash in the Netprobe setup file.
variables are case-sensitive.
environment variables
On , you can use any user environment variable defined under Environment Variables in System Properties.
environment variables are case-insensitive.
If the Netprobe is run as a service, then it evaluates the environment variable macros using the environment values defined at startup.