Table of Contents

Installation

You can install Hardware Sentry on the operating system of your choice as they are equally supported.

Note: Starting from v2.0.00, you can retrieve hardware information exposed by WMI from Linux and MacOs systems through the Windows Remote Management (WinRM) protocol.

Install

On Debian Linux

Download

From Sentry Software's Web site, download:

  • hws-debian-3.0.01-amd64.deb

Install

Once you have downloaded the Debian package, run the following dpkg command:

/ $ cd /usr/local
/usr/local $ sudo dpkg -i hws-debian-3.0.01-amd64.deb

When complete, the Hardware Sentry's files are deployed in /opt/hws and the Hardware Sentry Agent is started as a service.

Configure

You need to set up 2 configuration files in the installation directory (/opt/hws):

There are two configuration examples in the installation directory (/opt/hws):

  • ./otel/otel-config-example.yaml, a configuration example of the OpenTelemetry Collector.
  • ./config/hws-config-example.yaml, a configuration example of the Hardware Sentry Agent.

Before starting Hardware Sentry, make sure to configure ./otel/otel-config.yaml, since a restart of the Collector is required to take into account its changes.

Start

To start the Hardware Sentry service, run the command below:

systemctl start hws-agent

This will start Hardware Sentry with:

  • The default Hardware Sentry Agent configuration file: ./config/hws-config.yaml.
  • The default OpenTelemetry Collector configuration file: ./otel/otel-config.yaml.

You can start Hardware Sentry in an interactive terminal with an alternate Hardware Sentry Agent's configuration file with the command below:

/ $ cd /opt/hws/bin
/opt/hws/bin $ ./agent --config=<PATH>

Example:

/ $ cd /opt/hws/bin
/opt/hws/bin $ ./agent --config=config/my-hws-config.yaml

Stop

To stop the Hardware Sentry service, run the command below:

systemctl stop hws-agent

Uninstall

To uninstall Hardware Sentry, run the command below:

sudo dpkg -r hws

On Docker

Download

From Sentry Software's Web site, download:

  • hws-debian-3.0.01-docker.tar.gz

Install

First, unzip and untar the content of hws-debian-3.0.01-docker.tar.gz into a docker directory, like /docker. There is no need to create a specific subdirectory for hws as the archive already contains an hws directory.

/ $ cd /docker
/docker $ sudo tar xf /tmp/hws-debian-3.0.01-docker.tar.gz

Then, build the docker image using the following command:

/ $ cd /docker/hws
/docker/hws $ sudo docker build -t hws:latest .

Configure

You need to set up 2 configuration files in the docker image directory (hws):

There are two configuration examples in the docker image directory (hws):

  • ./otel/otel-config-example.yaml, a configuration example of the OpenTelemetry Collector.
  • ./config/hws-config-example.yaml, a configuration example of the Hardware Sentry Agent.

Before starting Hardware Sentry, make sure to configure ./lib/otel/otel-config.yaml, since a restart of the Collector is required to take into account its changes.

Start

You can start Hardware Sentry with the command below:

/ $ cd /docker/hws
/docker/hws $ sudo docker run --name=hws -p 8888:8888 -p 4317:4317 -p 13133:13133 hws:latest

This will start Hardware Sentry with:

  • The default Hardware Sentry Agent configuration file: ./lib/config/hws-config.yaml.
  • The default OpenTelemetry Collector configuration file: ./lib/otel/otel-config.yaml.

You can start Hardware Sentry with an alternate configuration file path with the command below:

/ $ cd /docker/hws
/docker/hws $ sudo docker run --name=hws -p 8888:8888 -p 4317:4317 -p 13133:13133 -v /docker/hws/lib/config:/opt/hws/lib/config hws:latest

See Ports and Firewalls for port details.

Docker Compose Example

You can start Hardware Sentry with docker-compose:

/docker/hws $ sudo docker-compose up -d --build

Example docker-compose.yaml

version: "2.1"
services:
  hws:
    build: .                                        # for image we will use ``image: sentrysoftware/hws:latest``
    container_name: hws
    ports:
      - 8888:8888                                   # OpenTelemetry Collector Exporter
      - 4317:4317                                   # OpenTelemetry Collector gRPC Receiver
      - 13133:13133                                 # OpenTelemetry Collector HealthCheck
    volumes:
      - ./lib/logs:/opt/hws/lib/logs                # Mount the volume ./lib/logs into /opt/hws/lib/logs in the container
      - ./lib/config:/opt/hws/lib/config            # Mount the volume ./lib/config into /opt/hws/lib/config in the container
      - ./lib/otel:/opt/hws/lib/otel                # Mount the volume ./lib/otel into /opt/hws/lib/otel in the container
    restart: unless-stopped

On Red Hat Enterprise Linux

Download

From Sentry Software's Web site, download:

  • hws-rhel-3.0.01-1.x86_64.rpm

Install

Once you have downloaded the RPM package, run the following rpm command to install Hardware Sentry:

/ $ cd /usr/local
/usr/local $ sudo rpm -i hws-rhel-3.0.01-1.x86_64.rpm

When complete, the Hardware Sentry's files are deployed in /opt/hws and the Hardware Sentry Agent is started as a service.

Configure

You need to set up 2 configuration files in the installation directory (/opt/hws):

There are two configuration examples in the installation directory (/opt/hws):

  • ./otel/otel-config-example.yaml, a configuration example of the OpenTelemetry Collector.
  • ./config/hws-config-example.yaml, a configuration example of the Hardware Sentry Agent.

Before starting Hardware Sentry, make sure to configure ./otel/otel-config.yaml, since a restart of the Collector is required to take into account its changes.

Start

To start the Hardware Sentry service, run the command below:

systemctl start hws-agent

This will start Hardware Sentry with:

  • The default Hardware Sentry Agent configuration file: ./config/hws-config.yaml.
  • The default OpenTelemetry Collector configuration file: ./otel/otel-config.yaml.

You can start Hardware Sentry in an interactive terminal with an alternate Hardware Sentry Agent's configuration file with the command below:

/ $ cd /opt/hws/bin
/opt/hws/bin $ ./agent --config=<PATH>

Example:

/ $ cd /opt/hws/bin
/opt/hws/bin $ ./agent --config=config/my-hws-config.yaml

Stop

To stop the Hardware Sentry service, run the command below:

systemctl stop hws-agent

Uninstall

To uninstall Hardware Sentry, run the command below:

sudo rpm -e hws-3.0.01-1.x86_64

On Windows

Download

From Sentry Software's Web site, download:

  • hws-windows-3.0.01.msi

Install

Double-click the .msi file you previously downloaded. The Installation Wizard will automatically start and guide you through the installation process.

When complete, the Hardware Sentry's files are deployed to the destination folder (by default under C:\Program Files\hws) and the Hardware Sentry Agent is started as a service and appears in services.msc.

Hardware Sentry running as a service on Windows

Hardware Sentry operates using the configuration located in the ProgramData\hws directory (C:\ProgramData\hws).

Configure

You need to set up 2 configuration files in the ProgramData\hws directory (C:\ProgramData\hws):

There are two configuration examples in the installation directory (C:\Program Files\hws):

  • ./otel/otel-config-example.yaml, a configuration example of the OpenTelemetry Collector.
  • ./config/hws-config-example.yaml, a configuration example of the Hardware Sentry Agent.

Before starting Hardware Sentry, make sure to configure ./otel/otel-config.yaml, since a restart of the Collector is required to take into account its changes.

Start

To start the Hardware Sentry service, open services.msc and start the Hardware Sentry Agent service.

This will start Hardware Sentry with:

  • The default Hardware Sentry Agent configuration file: ./config/hws-config.yaml.
  • The default OpenTelemetry Collector configuration file: ./otel/otel-config.yaml.

You can start Hardware Sentry in an interactive terminal (using CMD.EXE or Windows Terminal with an alternate Hardware Sentry Agent's configuration file using the command below:

c:
cd "Program Files"
cd hws
agent --config="c:\ProgramData\hws\config\my-hws-config.yaml"

Uninstall

To uninstall Hardware Sentry, double-click the hws-windows-3.0.01.msi file and click Remove when prompted.

Migrate

If you are migrating from v2.0.00 or older, perform the actions below before installing the latest version of Hardware Sentry:

  1. Stop the service:

    • On Windows:
      • if you installed Hardware Sentry as a service, stop and remove the service
      • if you are running the collector in an interactive terminal, stop the hws-otel-collector.exe process
    • On Linux: stop hws-otel-collector

  2. Make a backup copy of:

    • the configuration files otel-config.yaml and hws-config.yaml stored by default in hws-otel-collector/config
    • the security keystore hws-encrypt.p12 stored by default in hws-otel-collector/security if you previously encrypted your passwords

  3. Install the latest version of Hardware Sentry

  4. Paste your backup copy of:

    • otel-config.yaml in C:\ProgramData\hws\otel for Windows, /opt/hws/otel for Linux

    • hws-config.yaml in C:\ProgramData\hws\config for Windows, /opt/hws/config for Linux

    • hws-keystore.p12 in C:\ProgramData\hws\security for Windows, /opt/hws/security for Linux

      and replace the files in destination.

  5. Open and edit otel-config.yaml:

    • In the receivers section, update the security file paths cert_file and key_file in otlp:protocols:grpc:tls as follows:

      receivers:
  # OTLP
  # Receives data via gRPC or HTTP using OTLP format. For additional information on the OTLP receiver:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
        tls:
          cert_file: ../security/otel.crt # updated security file path.
          key_file: ../security/otel.key # updated security file path.
        auth:
          authenticator: basicauth

      Note: The security file path is relative to the otelcol-contrib executable directory, i.e. C:\Program Files\hws\otel on Windows, /opt/hws/otel on Linux (C:\Program Files\hws\otel\..\security on Windows, /opt/hws/otel/../security on Linux).

    • In the extensions section, remove the hws_agent extension:

        extensions:

    # healthcheck
    # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension
    health_check:

    # zPages
    # https://github.com/open-telemetry/opentelemetry-collector/tree/main/extension/zpagesextension
    zpages:

    # Remove hwsagent extension
    # hws_agent: # Extension not supported starting from version 3.0.00

    • In the exporters section, remove the loglevel line and add verbosity as follows:

      # logging
# https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/loggingexporter
logging:
  verbosity: detailed

    • In the extensions section, update the security file path in basicauth:htpasswd:file as follows:

      extensions:

  # healthcheck
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension
  health_check:

  # zPages
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/extension/zpagesextension
  zpages:

  # basicauth
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/basicauthextension
  basicauth:
    htpasswd:
      file: ../security/.htpasswd # updated security file path

    • In the service section, remove hws_agent in the list of extensions:

      service:
  telemetry:
    logs:
      level: debug # Change to debug for more details
    metrics:
      address: localhost:8888
      level: basic
  extensions: [health_check, basicauth] # Removed hws_agent from this list
  # ...
  ```

    • If you specified an alternate configuration file using the extra_arg --config in version 2.0.00, you need to start Hardware Sentry in an interactive terminal using the command documented above for Debian Linux, Docker, Red Hat, and Windows.

  6. Restart Hardware Sentry.

Upgrade from v3.x to 3.0.01

Debian Linux

From Sentry Software's Web site, download:

  • hws-debian-3.0.01-amd64.deb

Run the following command to stop the hws-agent service:

systemctl stop hws-agent

If you are running the Hardware Sentry Agent in an interactive terminal or as background process, stop the /opt/hws/bin/agent processes.

Run the following dpkg command:

/ $ cd /usr/local
/usr/local $ sudo dpkg -i hws-debian-3.0.01-amd64.deb

If you are running the Hardware Sentry Agent in an interactive terminal or as background process, start the /opt/hws/bin/agent processes using the command documented above.

Red Hat Enterprise Linux

From Sentry Software's Web site, download:

  • hws-rhel-3.0.01-1.x86_64.rpm

Run the following command to stop the hws-agent service:

systemctl stop hws-agent

If you are running the Hardware Sentry Agent in an interactive terminal or as background process, stop the /opt/hws/bin/agent processes.

Run the following rpm command to upgrade Hardware Sentry:

/ $ cd /usr/local
/usr/local $ sudo rpm -U hws-rhel-3.0.01-1.x86_64.rpm

If you are running the Hardware Sentry Agent in an interactive terminal or as background process, start the /opt/hws/bin/agent processes using the command documented above.

Windows

From Sentry Software's Web site, download:

  • hws-windows-3.0.01.msi

Stop the Hardware Sentry Agent service.

If you are running the Hardware Sentry Agent in an interactive terminal or as background process, stop the agent processes (default:C:/Program Files/hws/agent.exe).

Double-click the .msi file you previously downloaded. The Installation Wizard will automatically start and guide you through the installation process.

If you are running the Hardware Sentry Agent in an interactive terminal or as background process, start the agent processes (default:C:/Program Files/hws/agent.exe) using the command documented above.

Post-install

Verify

Verify that Hardware Sentry is properly running as explained in the Health Check section.

Ports and Firewalls

Hardware Sentry opens several TCP ports for listening. None of these ports need to be open to the outside network, as they are used internally only.

Component Port Required
OpenTelemetry Collector OTLP gRPC Receiver TCP/4317 Used internally only
OpenTelemetry Collector HealthCheck TCP/13133 Optional, if you need to verify the status of the collector
OpenTelemetry Collector Exporter TCP/8888 Used internally only
Keywords:
install upgrade firewalls hardware observability opentelemetry otel sustainability
No results.