---
title: "AWS Plugin in AWS Marketplace"
description: ""
url: "https://docs.itrsgroup.com/docs/geneos/collection/aws-cloudwatch/6.6.0/user-guide/aws-marketplace/index.html"
---
## Overview

You can easily deploy a Netprobe with AWS plugin by launching an EC2 instance based on the published ITRS's pre-configured AMI. The running EC2 instance will have a running Netprobe with AWS plugin on port `7036`, and optionally, you can run the Gateway on port `7039` that connects to the probe on the virtual machine.

Use this deployment option for the following reasons:

* To deploy the AWS plugin through the AWS Marketplace with built-in dynamic entity mapping to minimise Gateway configuration.
* To set up the plugin with minimal configuration. See [Supported Geneos deployment in ITRS Geneos AMI](https://docs.itrsgroup.com/docs/geneos/collection/aws-cloudwatch/6.6.0/user-guide/aws-marketplace/index.html#supported-geneos-deployment-in-itrs-geneos-ami).

To view the versions of Geneos components that are included in the AMI, see [Packaged binaries](https://docs.itrsgroup.com/docs/geneos/collection/aws-cloudwatch/6.6.0/user-guide/aws-marketplace/index.html#packaged-binaries).

## Launch ITRS Geneos EC2 instance

Ensure that your AWS account has the necessary credentials in order to access the application. For more information, see [AWS environment](https://docs.itrsgroup.com/docs/geneos/collection/aws-cloudwatch/6.6.0/user-guide/aws/index.html#aws-environment).

To launch the ITRS Geneos EC2 instance in AWS Marketplace:

1. Navigate to [AWS EC2 > Instances](https://console.aws.amazon.com/ec2), and then click **Launch instances**.
2. Search for **ITRS Geneos** under the **AWS Marketplace** category, and then click **Select**.
    - Provide all the required information in the selected AMI, such as the instance type, IAM role, storage, tags, and security group.
    
**Note**

  You can configure the remaining required fields depending on your machine requirements. This configuration only requires you to follow the settings below when configuring your AMI. 

3. In the **Configure Instance > IAM role**, select the role that has the appropriate [IAM role permissions](https://docs.itrsgroup.com/docs/geneos/collection/aws-cloudwatch/6.6.0/user-guide/aws-marketplace/index.html#iamrole-permissions). By default, the value of this field is set to **None** and if not changed, the plugin may not work as expected.
4. In the **Configure Instance > Advanced Details > User data**, add the script below. This will run the Gateway in demo mode. For other deployment scenarios, you can refer to the [Supported scenarios for deploying your AMI](https://docs.itrsgroup.com/docs/geneos/collection/aws-cloudwatch/6.6.0/user-guide/aws-marketplace/index.html#supported-geneos-deployment-in-itrs-geneos-ami).
    ```
    #cloud-config
    runcmd:
    - bash /opt/geneos/set-aws-parameters.sh --awsRegions us-east-1 --gatewayArgs "-demo"
    ```
    In this example, the AMI will run the Collection Agent, Netprobe, and Gateway because the `--gatewayArgs "-demo"` was used in the parameters script. The Gateway will run in demo mode that does not require licencing. This set up only requires minimal configuration.
    ![](https://docscdn.itrsgroup.com/geneos-aws-cloudwatch/images/aws-configure-instance-details.png)
5. Once the configuration for the AMI is completed, review the information, and then click **Launch**.
    - AWS will validate all the requirements that you submitted to create your AMI. Once successful, a message similar to this will appear:
    ![](https://docscdn.itrsgroup.com/geneos-aws-cloudwatch/images/aws-marketplace-ami-success.png)
6. View and launch your newly created instance. Wait until the **Instance state** changes from **Pending** to **Running**.
    ![](https://docscdn.itrsgroup.com/geneos-aws-cloudwatch/images/aws-marketplace-ami-running.png)
7. Open **Active Console Settings > Connections**, and then add the hostname or the **Public IPv4 address** of your AMI instance.

This displays the monitored AWS services. To view more AWS services and their corresponding sample dataviews, see [AWS CloudWatch Plugin services](https://docs.itrsgroup.com/docs/geneos/collection/aws-cloudwatch/6.6.0/user-guide/aws-services/index.html#overview).

![](https://docscdn.itrsgroup.com/geneos-aws-cloudwatch/images/aws-marketplace-dataview.png)

## Supported Geneos deployment in ITRS Geneos AMI

This section provides you the list of scenarios that you can choose from to deploy the ITRS Geneos EC2 instance through the AWS Marketplace.

The sample scripts in the scenarios described below require an environment variable, `${AWS_DEFAULT_REGION}`. You need to export this environment variable before proceeding. To do so, run:

```sh
export AWS_DEFAULT_REGION=<aws region>
```

### Run with specific services

In this mode, the EC2 instance will run the Collection Agent, Netprobe, and Gateway. The services that will be monitored are defined by the parameter `--enabledServices`.

Run this script in the ITRS Geneos EC2 instance:

```bash
#!/bin/bash

bash /opt/geneos/set-aws-parameters.sh \
--awsRegions ${AWS_DEFAULT_REGION} \
--gatewayArgs "-demo" \
--enabledServices "AWS/EC2,AWS/EBS,AWS/Billing"
```

### Run Gateway connecting to an existing Licence Daemon

In this mode, the EC2 instance will run the Collection Agent, Netprobe, and Gateway. The Gateway must be connected to an existing LICD that requires normal licencing. Then, you can connect Active Console to the Gateway using the public IP address of your EC2 instance on port `7039`.

Run this script in the ITRS Geneos EC2 instance:

```bash
#!/bin/bash

bash /opt/geneos/set-aws-parameters.sh \
--awsRegions ${AWS_DEFAULT_REGION} \
--gatewayArgs "-licd-host <host> -licd-port <port>"
```

### Run Geneos with TLS

You can also run the Geneos stack over secure TLS communication in your ITRS Geneos EC2 instance.

1. Upload your certificates to any file storage you prefer that will be accessible over the internet.
2. Launch an EC2 instance based on the ITRS Geneos AMI.
3. Run this script in the  **EC2 instance > User Data**:

```bash
#!/bin/bash

export AWS_DEFAULT_REGION="us-east-1"
# The following export lines can be removed if the AWS credentials are already available in the machine via AWS config or export file.
export AWS_ACCESS_KEY_ID="ABCDEFGHIJKLMNOPQRST"
export AWS_SECRET_ACCESS_KEY="abcdefGH1i2j3klm4NopqrSttu567VwxYz8+zY90"

# Download gateway certificates (You may download from any file storage you prefer via curl, wget or any similar tools)
aws s3 cp s3://<S3 object path>/gateway.crt /opt/certs/gateway.crt
aws s3 cp s3://<S3 object path>/gateway.key /opt/certs/gateway.key
aws s3 cp s3://<S3 object path>/trust-gw.pem /opt/certs/trust-gw.pem

# Download netprobe certificates (You may download from any file storage you prefer via curl, wget or any similar tools)
aws s3 cp s3://<S3 object path>/netprobe.crt /opt/certs/netprobe.crt
aws s3 cp s3://<S3 object path>/netprobe.key /opt/certs/netprobe.key
aws s3 cp s3://<S3 object path>/trust-np.pem /opt/certs/trust-np.pem

bash /opt/geneos/set-aws-parameters.sh \
--awsRegions ${AWS_DEFAULT_REGION} \
--gatewayArgs "-demo -ssl-certificate /opt/certs/gateway.crt -ssl-certificate-key /opt/certs/gateway.key -ssl-certificate-chain /opt/certs/trust-gw.pem" \
--netprobeArgs "-secure -ssl-certificate /opt/certs/netprobe.crt -ssl-certificate-key /opt/certs/netprobe.key -ssl-certificate-chain /opt/certs/trust-np.pem"

# If SAN, include the following parameter to set-aws-parameters.sh script.
# --san "gwSecure=true"
```

### Run Self-announcing Netprobe connecting to an external Gateway

In this mode, the EC2 instance will run the Collection Agent and Self-announcing Netprobe in normal mode. This requires you to configure the Gateway to connect to the Self-announcing Netprobe on port `7036`. Your security group must be configured to allow access through this port.


**Note**

  The Self-announcing Netprobe requires a reverse connection. You must configure your external Gateway accordingly. 


Run this script in the ITRS Geneos EC2 instance:

```bash
#!/bin/bash

bash /opt/geneos/set-aws-parameters.sh \
--awsRegions ${AWS_DEFAULT_REGION} \
--san "gwHost=ec2-99-999-99-99.compute-1.amazonaws.com;gwPort=7039"
```

## Update ITRS Geneos EC2 instance using parameters

You can follow any of the options below to manage your AWS monitoring stack (Gateway, Netprobe, and Collection Agent).

* Update your AWS plugin in the **Dynamic Entities** > **Collectors** section of your Gateway Setup Editor. For more information, see [Collectors in Dynamic Entities](https://docs.itrsgroup.com/docs/geneos/current/processing/configuration/dynamic_entities/index.html#collectors).
* Use the following bash script:
    ```bash
    bash /opt/geneos/set-aws-parameters.sh --awsRegions us-east-1 --gatewayArgs "-demo"
    ```
* Update a running ITRS Geneos EC2 instance using the same script. To do this remotely, you can execute `set-aws-parameters.sh` through SSH:
    ```sh
    ssh -i "C2_AWS_PLUGIN_AMI_KEY_PAIR.pem" ubuntu@ec2-34-219-189-228.us-west-2.compute.amazonaws.com "bash /opt/geneos/set-aws-parameters.sh --awsRegions us-west-2 --gatewayArgs \"-demo\" --san"
    ```
Here is the list of parameters that you can use for the `set-aws-parameters.sh` configuration:

| Option | Description |
|--------|-------------|
| `awsRegions` | Comma-separated list of AWS regions from which services will be monitored.
Mandatory: Yes |
| `--collectionInterval` | Interval (in milliseconds) between publications. This defaults to five minutes for `aws` and six hours for `aws-billing`.
Sample usage: `--collectionInterval "aws=300000;aws-billing=21600000"` |
| `--enabledServices` | Comma-separated list of AWS services that will be monitored. By default, all services are monitored.
Sample usage: `--enabledServices "AWS/EC2,AWS/EBS""` |
| `--gatewayArgs` | Starts the Gateway installed in the VM using the command line options provided.
Sample usage: `--gatewayArgs "-licd-host localhost -licd-port 7041"`|
| `--netprobeArgs`| Starts the Netprobe installed in the VM using the command line options provided.
Sample usage: `--netprobeArgs "-secure -ssl-certificate ./np.pem -ssl-certificate-chain ./rootCA.pem"` |
| `--loggerLevel` | Sets the logger level of the plugin.
Possible values: `trace`, `debug`, `info`, `warn`, `error`
Default value: `info` |
| `--san` | Runs the Netprobe as a Self-announcing Netprobe. The options are defined by adding key-value pairs separated semicolon.
Sample usage: `--san "gwHost=localhost;gwPort=7039;gwSecure=true"` Options:- `probeName` — name of the Self-announcing Netprobe. The default value is `aws-monitoring-<hostname>`.
- `healthPort` — Collection Agent port that the Netprobe communicates with for health checks. The default value is `9136`.
- `reporterPort` — the port the Netprobe should listen on to communicate with the Collection Agent using the `TcpReporter`. The default value is `9137`.
- `mappingType` — mapping type used to generate Dynamic Entities for this Netprobe. The default value is `CA Managed AWS Metrics`.
- `caParams` — Collection Agent parameters used to start the Collection Agent of this Netprobe. The default value is `aws-collection-agent-params`.
- `gwHost` — Gateway hostname where this Netprobe will connect to.
- `gwPort` — Gateway port where this Netprobe will connect to.
- `gwSecure` — whether the Gateway where this Netprobe will connect to is secured. The allowable values are either `true` or `false`. When no option is defined, the probe will run as a Self-announcing Netprobe using the current values defined. |
| `-h` \ `--help` | Shows the help text. |

### IAM role permissions

When launching the ITRS Geneos EC2 instance, ensure to set the [IAM role](https://console.aws.amazon.com/iam/home) to a role that has the following permissions:

* [Required AWS plugin permissions in Plugin services](https://docs.itrsgroup.com/docs/geneos/collection/aws-cloudwatch/6.6.0/user-guide/aws-services/index.html#required-aws-plugin-permissions).
* `s3:PutObject` to upload diagnostic files.
* STS and IAM permissions to assume IAM roles:

  * `sts:AssumeRole`
  * `sts:DecodeAuthorizationMessage`
  * `iam:PassRole`
  * `iam:ListInstanceProfiles`

## Packaged configuration files

The pre-configured AMI created by ITRS contains the following:

* Gateway, Netprobe, Collection Agent, and AWS plugin inside `/geneos` with the following configuration files:

  * `san.xml` setup file for running the Netprobe in self-announce mode.
  * `collection_agent/collection-agent.yml` configured with `AwsCollector` and `AwsBillingCollector`. All AWS services are monitored by default.
  * `collection_agent/logback.xml` logging configuration of the Collection Agent.
  * `gateway.setup.xml` configured to connect the Netprobe running locally and listening on port `7036`.
  * `mappings.xml` contains the AWS monitoring mappings.
* Helper scripts:

  * `/opt/geneos/set-aws-parameters.sh` main monitoring management script.
  * `/opt/geneos/get-diagnostics.sh` uploads Geneos logs to a specified AWS S3 bucket.
  * `/opt/geneos/set-logger-info.sh` updates the logging level of the Collection Agent.
  * `/opt/geneos/add-enabled-services.py` configures the AWS services to monitor for the `AwsCollector`.
  * `/opt/geneos/update-collection-interval.py` configures the collection interval of the configured collectors.
* Service files:

  * `/usr/bin/start-netprobe.sh` Netprobe startup script called by `netprobe.service`.
  * `/lib/systemd/system/netprobe.service` systemd service file.
  * `/usr/bin/start-gateway.sh` Gateway startup script called by `gateway.service`.
  * `/lib/systemd/system/gateway.service` systemd service file.

## Packaged binaries

The pre-configured AMI created by ITRS contains the latest versions of the following Geneos components:

* Geneos Gateway
* Geneos Netprobe
* Collection Agent
* AWS plugin

## Troubleshooting

### Check the Gateway and Netprobe service status

You can run the following commands to check the state of the Gateway and Netprobe in your EC2 instance.

1. Connect to your ITRS Geneos EC2 instance through SSH.
2. Run these commands to check if the Gateway and the Netprobe are running.
    ```
    # Check the status of Netprobe
    systemctl status netprobe

    # Check the status of Gateway
    systemctl status gateway
    ```
3. Run this command to restart the Gateway and Netprobe if they failed during the startup.
    ```
    # Restart the Netprobe
    systemctl restart netprobe

    # Restart the Gateway
    systemctl restart gateway
    ```
### Get the diagnostic files

1. Navigate to [Amazon S3](https://s3.console.aws.amazon.com/s3/home) and create an S3 bucket to store the logs.
2. Execute the following command in your EC2 instance. You can do this remotely through SSH.

```
/opt/geneos/get-diagnostics.sh --awsRegions <AWS_DEFAULT_REGION> --awsS3Bucket <AWS_S3_BUCKET>
```

4. Download files from S3: `s3://<AWS_S3_BUCKET>/geneos-logs.<YYYYMMDD>-<HHmmss>.tar.gz`.


**Note**

  The parameter `--awsS3Bucket` is optional. If you exclude `--awsS3Bucket`, the S3 upload is skipped but the logs will still be available in the instance path `/opt/geneos/logs`. 



