Self-announcing Netprobe

Overview

This topics walks you through the configuration and basic features of Self-announcing Netprobes (SANs).

Features

Disable listening

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

  • Use the command line option -listenip with the argument 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 Gatewayto identify its connection with the Netprobe.

Load balancing

In self-announcing mode, the Netprobe setup file must specify one or more Gateways to announce to.

When more than one Gatewayis specified, the following occurs:

  1. The Netprobe attempts to contact each Gateway.
  2. The Gateways respond, indicating if these are willing to accept the Netprobe. Each Gateway provides a metric indicating how highly loaded it is.
  3. The Netprobepicks the least loaded Gatewayto announce to, and listens for a connection in the normal way.
  4. If there is a tie, the Netprobepicks 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 plug-in to see the score from each Netprobe. For more information, see Probe data in Gateway Plug-Ins.

Rebalance Self-announcing Netprobes

You can redistribute SANs across your Gateways using the Gateway command for rebalancing Self-announcing Netprobes. This command removes SANs from a Gateway to either reach a target number of SANs or 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.

For more information, see Rebalance Self-Announcing Netprobes command in Gateway Commands.

Snooze and user assignment information on self-announcing probes

Self-announcing Netprobes store snooze and user assignment information in files in the Netprobedirectory. The files have the following filenames, where <probename> is the name of the SAN configured in the Netprobesetup file:

  • <probename>.snooze — contains snooze information.
  • <probename>.user_assignment — contains user assignment information.

Configuration 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 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 can fetch its setup file from a remote source.

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 true, enables the Self-announcing Netprobe mode.

If set to false after previously running a Self-announcing Netprobe, the Netprobe reverts to the normal mode.

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

selfAnnounce > requireReverseConnection  

When set to true, indicates that the Netprobe can only make a Netprobe-to-Gateway connection. This is useful when, for example, the Netprobe is behind a firewall.

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 disableSelfAnnouncing command for the Netprobe.

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 true, then the default value for this setting is true and it cannot be overridden. This is because Gateway-to-Netprobeare not supported secure Self-announcing Netprobe connections. If all the Gateways connected to are insecure, then the default value of this setting is false, but it can be set to true to ensure that all connections are Netprobe-to-Gateway.

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:

  • hostname — the server host name.
  • port — the Netprobe listen port.

To create a probe name in the format hostname port, where the correct values are automatically inserted for host name and port, the following should be specified in the xml:

<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 Self-announcing Netprobe, then the Self-announcing Netprobe starts a REST API HTTP server with the default port 7136.

Mandatory: No

Default: 7136

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:

  • The common name must be the REST API server host name associated with the SSL certificate.
  • As a best practice, use the same certificate authority (CA) as is used for other Netprobe certificates.
  • The certificate created is used by the REST API plug-in as well as the Netprobe to communicate with the Gateway. The Netprobe only uses the certificate if it is in secure mode.

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 -ssl-certificate and -ssl-certificate-key command-line parameters, respectively. For more information, see Netprobe Command-line Options.

If you do not configure this setting, but there exists a REST API sampler under the type specified in Self-announcing Netprobe, then the Self-announcing Netprobe starts a REST API HTTP server with the default port 7136.

Mandatory: No

selfAnnounce > collectionAgent  

Note: Beginning Geneos 5.1, the Collection Agent is included in the Netprobe binaries for Windows and generic Linux 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:

  • -Xms512M — allocates the initial heap size.
  • -Xmx512M — allocates the maximum heap size.
  • -Dlogback.configurationFile=collection_agent/logback.xml — specifies the file path to the Logback configuration for the Collection Agent logs.

If the Collection Agent cannot access logback.xml for any reason, then it writes to standard output (stdout) and standard error (stderr), and outputs the log file in the Netprobe's working directory.

Caution: This fallback behaviour is not supported on Windows.

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

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

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 start option.

For more information, see Detached mode in Run Collection Agent with Netprobe.

Default value: true

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 managedEntity sections.

You can only have one managed entity 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.

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

Connection rules

Reasons for rejection

Gateways may refuse to accept a Self-announcing Netprobe for a few reasons. For more information, see Rejection reasons.

Configuration conflicts

The Self-announcing Netprobe may encounter conflicts between its setup file and the Gateway setup file. For more information, see Configuration conflicts.

Disconnection behaviour

The Netprobe follows a set of rules when connecting to the Gateway. For more information, see Disconnect behaviours.

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.

For more information on Gateway hot standby behaviour, see Hot Standby.