Install Upwind Sensor on Hosts (VMs)

Overview

This topic describes how to install an Upwind Sensor on a Linux host (VM), such as an Amazon EC2 instance, Google Cloud Compute instance, Microsoft Azure VM, Oracle Compute instance or an on-premise VM.

note

This topic assumes the following criteria are met:

• You have already connected the cloud account where the Host is hosted to Upwind. If you haven't, please follow the Connect a Cloud Account page.

Step 1: Generate Client Credentials

note

This step is relevant only if you want to create new client credentials. If you already have client credentials, you can skip this step.

Assuming you have already connected your cloud account to Upwind, you will need to generate client credentials to allow the Upwind Sensor to communicate with the Upwind platform. The credentials can be generated as part of the host connection process.

Alternatively, you can generate it in the Upwind Console, under Client Credentials . After you have generated the client credentials, note down the UPWIND_CLIENT_ID and UPWIND_CLIENT_SECRET fields.

Note that once saved you will not be able to view the UPWIND_CLIENT_SECRET again, so make sure to save it in a secure location.

Step 2: Verify the Upwind Sensor Installation Script

Before installing the Upwind Sensor, validate the integrity of the sensor.sh installation script using SHA256 checksum provided by Upwind. This ensures that the script has not been tampered with.

tip

This step is optional, but we recommend doing this to verify the integrity of the installation script and ensure that the downloadable assets have not been altered or corrupted since they were published.

1. Generate the checksum. Read the script and pass it through the sha256sum utility to create the SHA256 checksum. Alternatively, you can download the file first and then run sha256sum on it.

   Command

   Execute the following command to generate the checksum:

   curl -fsSL https://get.upwind.io/sensor.sh | sha256sum

   Example output

   The command will output a checksum similar to the following:

   9eaea8877f984b2ff085b4936f82402be59c771f6a44b4aae6fee447022ca200  -

2. Compare with the provided checksum. Retrieve the official checksum from the accompanying .sha256 file and compare it with the generated checksum. If the checksums match, then it is safe to run the installation script. If the checksums do not match, do not run the installation script, and contact Upwind Support.

   Command

   Execute the following command to retrieve the official checksum:

   curl -fsSL https://get.upwind.io/sensor.sh.sha256

   Example output

   The official checksum will look like this:

   9eaea8877f984b2ff085b4936f82402be59c771f6a44b4aae6fee447022ca200

Step 3: Install Upwind Sensor

This describes the simplest way to install the Upwind Sensor on a host. For more advanced installation options and configurations, see the Configuration page.

note

Examples of advanced configurations include requiring a proxy server, turning off or configuring the Scanner, not allowing access to Instance Metadata Service (IMDS), and more...

Provide Client Credentials

There are two ways to provide your client credentials to the Sensor: as environment variables, or in the Sensor configuration file. For the Debian and RPM packages, export the credentials as environment variables so the download script can use them, and add them to the configuration file after you install the package, as described in those tabs under Run the Installer.

Environment Variables

Export the credentials from Step 1 on the host before running the installer. The install command below will pick them up automatically.

tip

The leading space before each export keeps the credentials out of shell history, but only when the shell is configured to ignore space-prefixed commands — HISTCONTROL=ignorespace (bash; default on most distros) or HIST_IGNORE_SPACE (zsh). If neither applies, use the Configuration File approach instead.

# Upwind Client Credentials
 export UPWIND_CLIENT_ID="<redacted>"
 export UPWIND_CLIENT_SECRET="<redacted>"

Configuration File

Create the Sensor configuration directory and add your credentials before running the automatic installer. Don't use this approach with the Debian or RPM package: they install their own copy of this file.

sudo mkdir -p /etc/upwind
sudo vi /etc/upwind/agent.yaml

# Upwind Agent Configuration
log-level: info
platform: host
auth-client-id: "<CLIENT_ID>"
auth-client-secret: "<CLIENT_SECRET>"

The file contains your client secret, so restrict it to root only:

sudo chmod 600 /etc/upwind/agent.yaml

Selecting your region

By default the Sensor connects to the US region. If your Upwind tenant is in another region, either export UPWIND_REGION="eu" (or "me") with the credentials, or set region in the Sensor configuration file (/etc/upwind/agent.yaml) before running the installer, for example region: "eu". Valid values are us, eu, and me; the default is us. The region key only applies to the automatic installer. The Debian and RPM packages need the regional endpoints in their configuration files instead, as described in those tabs. See Configuration for all available settings.

Run the Installer

Automatic (Recommended)

Standard

Execute the following command on the host to download and install the Upwind Sensor:

curl -fsSL https://get.upwind.io/sensor.sh | bash -s

BYOC

For a BYOC deployment, also export the cloud account details before running the installer:

# BYOC Configuration
 export UPWIND_AGENT_CLOUD_PROVIDER="byoc"
 export UPWIND_AGENT_CLOUD_ACCOUNT_ID="<ACCOUNT_ID>"
 export UPWIND_AGENT_ZONE="<LOCATION>"

Then execute the install command:

curl -fsSL https://get.upwind.io/sensor.sh | bash -s

Use the values of the BYOC account you created when connecting your BYOC account:

• <ACCOUNT_ID> is the Account ID of the BYOC account, which already starts with byoc-. Copy it from Inventory → Cloud accounts.
• <LOCATION> is the Location you picked for the data center, for example "United States". Keep the quotes, since it can contain spaces.

note

These three values can alternatively be placed in /etc/upwind/agent.yaml as cloud-provider, cloud-account-id, and zone — the same keys shown in the Debian and RPM tabs.

Debian

Export UPWIND_CLIENT_ID and UPWIND_CLIENT_SECRET as shown in the Environment Variables tab of Provide Client Credentials. The download script uses them to authenticate.

note

The download script supports Upwind tenants in the US region only. If your tenant is in another region, contact Upwind Support to get the package.

Download and install the package:

curl -fsSL https://get.upwind.io/scripts/get-package.sh | bash -s deb
sudo dpkg -i ./upwind-agent_*.deb

The script downloads the latest stable release for the host's architecture into the current directory. To install a specific release, also export UPWIND_SENSOR_VERSION="v<VERSION>".

The deb package installs a template /etc/upwind/agent.yaml. Edit that file after installing the package, not before. If the file already exists when you install the package, the install stops to ask which version to keep, and fails when it runs without a terminal.

sudo vi /etc/upwind/agent.yaml

# Upwind Agent Configuration
log-level: info
platform: host
auth-client-id: "<CLIENT_ID>"
auth-client-secret: "<CLIENT_SECRET>"
enable-scans: true

The deb package enables and starts the Scanner timer, and enable-scans: true makes the hostconfig service keep it enabled. To install without the Scanner, set enable-scans: false instead, skip the upwind-agent-scanner.timer lines below, and run sudo systemctl disable --now upwind-agent-scanner.timer. Refer to Disabling the Scanner.

The file contains your client secret, so restrict it to root only:

sudo chmod 600 /etc/upwind/agent.yaml

If your Upwind tenant is not in the US region, add the regional endpoints to /etc/upwind/agent.yaml, and create /etc/upwind/agent-hostconfig.yaml with the same two lines for the hostconfig service. Replace <REGION> with eu or me:

api-host: https://agent.<REGION>.upwind.io
auth-endpoint: https://oauth.<REGION>.upwind.io/oauth/token

For a BYOC deployment, add the cloud account details to both /etc/upwind/agent.yaml and /etc/upwind/agent-hostconfig.yaml:

cloud-provider: byoc
cloud-account-id: "<ACCOUNT_ID>"
zone: "<LOCATION>"

Use the Account ID, which already starts with byoc-, and the Location of the BYOC account you created when connecting your BYOC account. Copy the Account ID from Inventory → Cloud accounts.

Start the Sensor service:

sudo systemctl enable upwind-agent.service
sudo systemctl start upwind-agent.service
sudo systemctl enable upwind-agent-hostconfig.service
sudo systemctl start upwind-agent-hostconfig.service
sudo systemctl enable upwind-agent-scanner.timer
sudo systemctl start upwind-agent-scanner.timer

RPM

Export UPWIND_CLIENT_ID and UPWIND_CLIENT_SECRET as shown in the Environment Variables tab of Provide Client Credentials. The download script uses them to authenticate.

note

The download script supports Upwind tenants in the US region only. If your tenant is in another region, contact Upwind Support to get the package.

Download and install the package:

curl -fsSL https://get.upwind.io/scripts/get-package.sh | bash -s rpm
sudo rpm -i ./upwind-agent-*.rpm

The script downloads the latest stable release for the host's architecture into the current directory. To install a specific release, also export UPWIND_SENSOR_VERSION="v<VERSION>".

The RPM package installs a template /etc/upwind/agent.yaml. Edit that file after installing the package, not before. If the file already exists when you install the package, the install replaces it with the template and moves your file to /etc/upwind/agent.yaml.rpmorig.

sudo vi /etc/upwind/agent.yaml

# Upwind Agent Configuration
log-level: info
platform: host
auth-client-id: "<CLIENT_ID>"
auth-client-secret: "<CLIENT_SECRET>"
enable-scans: true

The RPM package enables and starts the Scanner timer, and enable-scans: true makes the hostconfig service keep it enabled. To install without the Scanner, set enable-scans: false instead, skip the upwind-agent-scanner.timer lines below, and run sudo systemctl disable --now upwind-agent-scanner.timer. Refer to Disabling the Scanner.

The file contains your client secret, so restrict it to root only:

sudo chmod 600 /etc/upwind/agent.yaml

If your Upwind tenant is not in the US region, add the regional endpoints to /etc/upwind/agent.yaml, and create /etc/upwind/agent-hostconfig.yaml with the same two lines for the hostconfig service. Replace <REGION> with eu or me:

api-host: https://agent.<REGION>.upwind.io
auth-endpoint: https://oauth.<REGION>.upwind.io/oauth/token

For a BYOC deployment, add the cloud account details to both /etc/upwind/agent.yaml and /etc/upwind/agent-hostconfig.yaml:

cloud-provider: byoc
cloud-account-id: "<ACCOUNT_ID>"
zone: "<LOCATION>"

Use the Account ID, which already starts with byoc-, and the Location of the BYOC account you created when connecting your BYOC account. Copy the Account ID from Inventory → Cloud accounts.

Start the Sensor service:

sudo systemctl enable upwind-agent.service
sudo systemctl start upwind-agent.service
sudo systemctl enable upwind-agent-hostconfig.service
sudo systemctl start upwind-agent-hostconfig.service
sudo systemctl enable upwind-agent-scanner.timer
sudo systemctl start upwind-agent-scanner.timer

info

It is possible to deploy the Upwind Sensor on a host using the cloud deployment tools, such as Azure Run Command, AWS Systems Manager, or Google Cloud Patch Manager. For more information, see the Cloud Deployment Tools page.

Step 4: Validate the Installation

It is recommended to validate that the Upwind Sensor is running correctly on the host.

Run the following command to check the Sensor status:

sudo systemctl status upwind-agent

The output should show that the Upwind Sensor is active and running.

Troubleshooting

Read the Troubleshooting guide for more information on how to troubleshoot the Upwind Sensor installation.