-
Home
- Getting Started
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
):
- ./otel/otel-config.yaml: to specify where the OpenTelemetry Collector should send the collected data
- ./config/hws-config.yaml: to specify the hosts to monitor and their credentials
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
):
- ./lib/otel/otel-config.yaml: to specify where the OpenTelemetry Collector should send the collected data
- ./lib/config/hws-config.yaml: to specify the hosts to monitor and their credentials
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
):
- ./otel/otel-config.yaml: to specify where the OpenTelemetry Collector should send the collected data
- ./config/hws-config.yaml: to specify the hosts to monitor and their credentials
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 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
):
- ./otel/otel-config.yaml: to specify where the OpenTelemetry Collector should send the collected data.
- ./config/hws-config.yaml: to specify the hosts to monitor and their credentials.
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:
-
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
- On Windows:
-
Make a backup copy of:
- the configuration files
otel-config.yaml
andhws-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
- the configuration files
-
Install the latest version of Hardware Sentry
-
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 Linuxand replace the files in destination.
-
-
Open and edit
otel-config.yaml
:-
In the
receivers
section, update the security file pathscert_file
andkey_file
inotlp: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 thehws_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 theloglevel
line and addverbosity
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 inbasicauth: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, removehws_agent
in the list ofextensions
: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.
-
-
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 |