--- title: "Run Collection Agent using the Netprobe" description: "" url: "https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/collection-agent/run-ca-using-netprobe/index.html" --- **Caution** Collection Agent and its plugins is no longer packaged with the Netprobe in Geneos 5.14.7 and the subsequent 5.x versions. If you want to run Collection Agent using the Netprobe, please upgrade to the current 6.x version of Geneos. ## Overview This page describes how to run the Collection Agent in managed mode on the same host as a Netprobe. The Netprobe starts, supervises, and restarts the Collection Agent according to Collection agent parameters you define in the Gateway Setup Editor. Use this path when the Netprobe and Collection Agent run on the same host (normal, floating, or self-announcing Netprobe). To run them on different hosts, see [Run Collection Agent as a standalone Java process](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/collection-agent/run-ca-standalone-java/index.html). **Caution** Make sure to read [Upgrading Collection Agent](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/collection-agent/upgrade-collection-agent/index.html), which outlines the breaking changes that may have an impact on your upgrade, before you upgrade to the latest version of Geneos and Collection Agent. For information on running the Collection Agent in an orchestrated environment, see [Data collection in an orchestrated environment](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/data-collection-in-orchestrated-environments/data-collection-in-orchestrated-env/index.html). **Note** Beginning Geneos 5.1, the Collection Agent is included in the Netprobe binaries for Windows and generic Linux platforms. ## Prerequisites ### System requirements The following requirements must be met on the machine where the Netprobe and Collection Agent are installed: - Linux operating system (CentOS, RHEL, or SUSE), or - Windows operating system ### Java requirements - Java 21 or higher. **Note** Starting with Geneos 7.1.0, the Collection Agent has been upgraded to version 5.x and requires Java 21 as the minimum supported version. - A minimum Java heap size of 512MB is recommended for Collection Agent. If the agent is performing garbage collection too frequently as the volume increases, a larger heap size should be allocated. - Once you have Java installed, configure the environment variables required by the Netprobe so that it can locate the required resource files. For guidance, see [Configure the Java environment](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/configure-the-java-environment/index.html). **Caution** Java installation and environment configuration is a common source of errors for users setting up Java-based components and plug-ins. You should read [Configure the Java environment](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/configure-the-java-environment/index.html) to help you understand your Java installation. ### Geneos components requirements - Geneos Netprobe version 5.1.0 or higher. Please read [Upgrading the Collection Agent](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/collection-agent/upgrade-collection-agent/index.html) for information on how to properly upgrade to the latest version of Collection Agent. - Ensure that your Gateway and Netprobe are running. **Caution** If you are using a Gateway version 5.2, then any Netprobe running in normal or floating mode must also be version 5.2. Otherwise, the Collection Agent will not start. ## Run the Collection Agent using the Netprobe To run the Collection Agent using the Netprobe, follow these steps: 1. In Gateway Setup Editor, click **Dynamic entities** > **Collection agent parameters**, and then click **New Collection agent parameters**. 2. Select `Managed` in the **Collection Agent** dropdown list. 3. Choose your preferred YAML type in the **Yaml** dropdown list and configure your Collection Agent parameters. ![Collection Agent parameters](https://docscdn.itrsgroup.com/geneos/images/netprobe/collectionagent/geneos-managed-ca-parameters-conf-7-4-0.png)
YAML type Configure your Collection Agent in
Bundled YAML

the collection_agent/collection-agent.yml packaged with the Netprobe binary.
Custom YAML the specified YAML file that can have any name. The file can be in any folder but if you are using a relative path, then it should be relative to the working directory.
Managed YAML the Gateway Setup Editor. For more information, see Managed Collection Agent in Dynamic Entities.
**Note** If you are starting the Collection Agent using the Netprobe, all the ports configured in the Gateway Setup Editor will automatically apply to the running Collection Agent. For the full YAML reference and section descriptions, see the [Collection Agent configuration reference](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/collection-agent/config-ref-ca/index.html). 4. Configure your plugins.
YAML type Configure your plugins by
Bundled YAML

adding the parameters of the desired plugins in the collection_agent/collection-agent.yml packaged with the Netprobe binary.
Custom YAML

adding the parameters of the desired plugins in the specified YAML file in Step 3.
Managed YAML adding the parameters in the Dynamic Entities > Collectors section in the Gateway Setup Editor. For more configuration information, see Collectors in Dynamic Entities.
**Note**  If you need to set up a plugin that is not included in the package, download it from the [ITRS Downloads](https://resources.itrsgroup.com/) and add it to `collection_agent/plugins` or the appropriate Collection Agent plugins directory. **Tip** Watch this [Collection Agent demo](https://app.storylane.io/share/wvjkgxnq6cbu) to see how to configure the Collection Agent to run using the Netprobe. https://app.storylane.io/demo/wvjkgxnq6cbu ### Self-Announcing Netprobe For Self-Announcing Netprobes, you can start the Collection Agent by adding the following configuration in the `selfAnnounce` settings in the Netprobe setup file: ``` CollectionAgentParams DynamicEntitiesMapping ``` For more information, see [Self-announce settings in Netprobe setup](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/netprobe-setup/index.html#self-announce-settings). **Note**  You still have to [Create Dynamic Entities](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/collection-agent/collection-agent-setup/index.html#create-dynamic-entities) and make sure of the following: - The value inside the `collectionAgentParameters` tag in the XML above is the name of your **Collection agent parameters** in Gateway Setup Editor. - The value inside the `mappingType` tag in the XML above is the name of your **Mapping type** in Gateway Setup Editor. ### Secure Collection Agent To use a secure connection between a Netprobe (normal, floating, or self-announcing modes) and Collection Agent, enable TLS using the secure command line option. Additionally, set the relevant SSL files on the command line. For more information, see [Netprobe Command-line Options](https://docs.itrsgroup.com/docs/geneos/current/collection/netprobe/configuration/netprobe-command-line-options/index.html). **Note** Secure Collection Agent does not support Bundled YAML. Use Managed YAML or Custom YAML instead. ## Create Dynamic Entities Netprobes receive datapoints from Collection Agents. Each datapoint can have a different set of dimensions, attributes, and properties. You should create mappings to construct a Geneos hierarchy from datapoints. This Geneos hierarchy determines how data is displayed in your Active Console. You should also create a mapping type, which allows you to easily deploy the same configuration on multiple probes. 1. Open Gateway Setup Editor. 2. Click **Dynamic entities** > **Mapping**, and then click **New Mapping**. 3. Enter a mapping name in the **Name** field. 4. In Options, choose **custom** or **builtin**. For more information, see [Dynamic entities > Mapping > Options in Dynamic Entities](https://docs.itrsgroup.com/docs/geneos/7.11.0/processing/configuration/dynamic_entities/index.html#mapping-options). **Note**  A built-in **Collection Agent V3** mapping is packaged with the Netprobe, which automatically sets up the default mappings needed to display the Collection Agent self-monitoring metrics. Using this mapping requires [setting the `HOSTNAME` as an environment variable](#collection-agent-self-monitoring-metrics) to ensure that it returns valid metrics. ![](https://docscdn.itrsgroup.com/geneos/images/gateway/gse-images/dynamic-mapping-conf-6-1.png) 5. Click **Dynamic entities** > **Mapping types**, and then click **New Mapping type**. 6. If you configured a managed Collection Agent with a managed YAML type in the previous steps, then in the **Collectors** field, click **Add new** to add the name of the collectors you created in [Run Collection Agent using Netprobe](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/collection-agent/run-ca-using-netprobe/index.html). 7. In the **Mappings** field, click **Add new** to add the name of the mapping created in Step 4. ![Mapping type](https://docscdn.itrsgroup.com/geneos/images/gateway/gse-images/dynamic-mapping-type-6-0.png) 8. To monitor the logs collected by the Collection Agent plugin, you can add an FKM plugin sampler in the **Samplers** field. The FKM plugin consumes these logs as streams. To configure your FKM plugin to monitor these streams, see [files > file > source > stream in configuration](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/fkm-config/index.html#files--file--source--stream). ## Add Dynamic Entities in your Netprobe 1. Open Gateway Setup Editor. 2. In **Probes**, select your Netprobe and go to the **Dynamic Entities** tab. 3. Choose a mapping type in the **Mapping type** dropdown list. 4. Choose a collection agent parameter in the **Collection agent parameters** dropdown list. ![Collection agent parameters](https://docscdn.itrsgroup.com/geneos/images/gateway/gse-images/probe-dynamic-entities-6-0.png) **Note** If mappings are defined in both the Mapping type and in the Collector, then the Netprobe will apply the mappings defined in the Mapping type first then the mappings defined in the Collectors. ## Collection Agent self-monitoring metrics If you started the Collection Agent with the built-in **Collection Agent V3** mapping, then the Collection Agent self-monitoring metrics are displayed in your Active Console. ![](https://docscdn.itrsgroup.com/geneos/images/netprobe/collectionagent/ca-collection-agent-view.png) **Note** The `HOSTNAME` must be set as an environment variable to ensure that the built-in **Collection Agent V3** mapping returns valid metrics. - On Debian-based systems such as Ubuntu, the `HOSTNAME` variable is typically set as a shell variable. Therefore, you must explicitly export it as an environment variable before running the Netprobe. - On RHEL-based systems, `HOSTNAME` is usually already set as an environment variable by default. ### Setting the HOSTNAME as an environment variable There are two ways to set `HOSTNAME` as an environment variable: - Option 1: Export `HOSTNAME` using the command: ```command export HOSTNAME ``` Then verify that it has been set using: ```command printenv HOSTNAME ``` Example: ```command root@infanta:~/netprobe# echo $HOSTNAME infanta.mnl.itrsgroup.com root@infanta:~/netprobe# printenv HOSTNAME root@infanta:~/netprobe# export HOSTNAME root@infanta:~/netprobe# printenv HOSTNAME infanta.mnl.itrsgroup.com root@infanta:~/netprobe# echo $HOSTNAME infanta.mnl.itrsgroup.com root@infanta:~/netprobe# ./netprobe.linux_64 -port 25565 ``` - Option 2: Set a `HOSTNAME` when starting the Netprobe using the command: ```command HOSTNAME=./netprobe.linux_64 ``` Example: ```command root@infanta:~/netprobe# printenv HOSTNAME root@infanta:~/netprobe# echo $HOSTNAME infanta.mnl.itrsgroup.com root@infanta:~/netprobe# HOSTNAME=infanta.mnl.itrsgroup.com ./netprobe.linux_64 -port 25565 ``` ## Dynamic Entities Health The Dynamic Entities Health plugin monitors the performance of Collection Agent and Netprobe communication. It tracks the state of all metrics received by a Netprobe from the Collection Agent, and all dynamic entities associated with a Netprobe. For guidance on how to set up the Dynamic Entities Health sampler, see [Dynamic Entities Health](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/dynamic-entities-health/index.html). ## Connection and lifecycle When run with the Netprobe, Collection Agent runs as a Java process alongside the Netprobe process. ### Common failure modes The Collection Agent will not start in the following scenarios: - `JAVA_HOME` is not set in the Netprobe's environment. For more information, see [Configure the Java environment](https://docs.itrsgroup.com/docs/geneos/7.11.0/collection/netprobe/configuration/configure-the-java-environment/index.html). - Collection Agent resource files are missing, or are not the same version packaged in the `collection_agent` directory: - `collection-agent--exec.jar` - `collection-agent.yml` - The following Collection Agent ports are not available: - Health port - Reporter port - StatsD UDP port is not available **Note**  The StatsD plugin uses the default which is specified in the `collection-agent.yml`. If two Netprobes are running with one Collection Agent, then the `Address bind already in use.` error message is displayed in the Collection Agent log file. ### Netprobe connection The following describes the behaviour of the Netprobe connection depending on the state of the Collection Agent: - Netprobe restarts the managed Collection Agent if the latter goes down, or cannot be detected after having been detected before. - Netprobe will attempt to restart an unreachable Collection Agent three times. If on the third time, the Netprobe still cannot detect the Collection Agent, then it no longer attempts to restart the Collection Agent. - If the Netprobe restarts, the managed Collection Agent is also restarted. **Note**  A Collection Agent started independently of the Netprobe is not managed by the Netprobe. ### Health checks The Netprobe periodically pings the managed Collection Agent through the defined health check port. The health checks are governed by the following variables: | Name | Description | |------|-------------| | CA_HEALTHCHECK_INTERVAL | Time to wait in seconds before performing another health check on the Collection Agent. Default value: `20` | | CA_MAX_HEALTHCHECK_ATTEMPTS | Maximum number of attempts that the Netprobe makes to contact a managed Collection Agent. Default value: `3` | | CA_HEALTHCHECK_TIMEOUT | Time in seconds that the Netprobe waits for a response from the Collection Agent during a health check. Default value: `5` | | 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` |