Healthbeat 8.1.4 – Windows Readme

Introduction

Healthbeat is an agent to capture health metrics of the system and the supported applications on Linux and Windows platforms. The following system health metrics are collected on Windows:

• cpu
• core
• diskio
• filesystems
• fsstat
• memory
• network
• process

Pre-requisites

PowerShell with admin access.

Supported OS

• Windows (64-bit) – 8.1, 10, 11
• Windows Server – 2016, 2019, 2022

Installation

1. Extract the contents of the vuHealthbeat_814_windows_x86_64.zip file into any folder of your choice.
2. Open a PowerShell prompt as an Administrator (right-click the PowerShell icon and select Run As Administrator).
3. From the PowerShell prompt, go to the extracted vuHealthbeat_814_windows_x86_64 folder and run the following commands to install Healthbeat as a Windows service.
   
   \install-service-healthbeat.ps1

   
   Note:
   If you get a script execution error while running the installer, rerun using an unrestricted execution policy:

   PowerShell.exe -ExecutionPolicy UnRestricted -File  .\install-service-healthbeat.ps1

   (OR)

   Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass .\install-service-healthbeat.ps1
4. Select an installation option:
   
   1. Fresh installation : To install the Healthbeat service for the first time
   2. Upgrade an existing installation : To upgrade the agent binaries
   3. Exit : To exit the installation wizards
5. Enter the directory where you want to install the Healthbeat agent. The default value is the (User Home).Press enter to accept the default. Else, if you want to specify the installation directory explicitly, please provide the path.
   
   Example,

   C:\Users\USER\  – The installation script will create Healthbeat directory inside C:\Users\USER
   

   C:\Users\USER\agents – The installation script will create Healthbeat directory inside C:\Users\USER\agents
   

   If the directory exists, press enter or y to continue installation on the same directory, or else you can exit wizards by pressing n.

Configuration

1. The installer will optionally assist in configuring the agent. It is recommended to use the option for creating the config files automatically. Else, the configuration needs to be done manually using the configuration yml file.
2. The configuration will update the following attributes:
   
   1. INTERVAL – The frequency of data collection. Default is 5 min.
   2. OUTPUT METHOD – The collection method used to ship the collected metrics to the remote vuSmartMaps data collector/shipper. The default is Kafka. We support two options:
      
      1. kafka
      2. beats
   3. Collector/Shipper IP  –  The remote vuSmartMaps data collector/shipper where the collected metrics should be sent.
   4. PORT   – The remote listening port on the vuSmartMaps data collector/shipper.
   5. TOPIC  – The kafka topic name in case, if the output method is chosen as kafka.

Note: A general assumption is agents are installed with the knowledge of the exact collection method and listening port setup at the vuSmartMaps end. If this information is not yet known, contact Vunet support.

How to Configure the Agent manually?

1. The configuration files controlling the functioning of the agent are
   
   (AGENT_HOME)\healthbeat.yml

   and

   (AGENT_HOME)\modules.d\(modules).yml
2. The (AGENT_HOME)\healthbeat.yml file mainly contains the modules directory path from where the individual module configuration needs to be fetched and the configuration for the output method to send the collected data.
3. The logstash output can be enabled by uncommenting the “output.logstash” setting.
   
   Following are the configurations in the logstash output block.
   

   #—————————– Logstash output ——————————–
   output.logstash:
   # The Logstash hosts
   hosts: [“127.0.0.1:5040”]

   # Optional SSL. By default it is off.
   # List of root certificates for HTTPS server verifications
   #ssl.certificate_authorities: [“/etc/pki/root/ca.pem”]

   # Certificate for SSL client authentication
   #ssl.certificate: “/etc/pki/client/cert.pem”

   # Client Certificate Key
   #ssl.key: “/etc/pki/client/cert.key”

4. The kafka output can be enabled by uncommenting the “output.kafka” setting. Following are the configurations in the kafka output block.
   

   #—————————– Kafka output ——————————–

   output.kafka:

   #initial brokers for reading cluster metadata

   hosts: [“127.0.0.1:9092”]

   ###message topic selection + partitioning

   topic: ‘healthbeat’

   required_acks: 1

   compression: gzip

   max_message_bytes: 100000

   channel_buffer_size: 100000

5. The logging block is towards the end of the configuration where log level, log path, and rotation policy can be specified.
   

   #================================ Logging =====================================
   # Set log level. The default log level is info.
   # Available log levels are: critical, error, warning, info, and debug
   logging.level: debug

   # At debug level, you can selectively enable logging only for some components.
   # To enable all selectors use [“*”]. Examples of other selectors are “beat”,
   # “publish”, “service”.
   #logging.selectors: [“*”]

   logging.to_files: true
   logging.files:
   path: C:\Users\USER\healthbeat\logs
   name: healthbeat
   keepfiles: 5
   permissions: 0644

6. The period option in (AGENT_HOME)\modules.d\system.yml should be used to change the frequency at which the health metrics are collected.
   
   period: 5m

   
   This collects the system health metrics every 5 minutes and sends them to the Shipper.

7. By default, the system module is being enabled. The additional modules like apache2, heartbeat, urlbeat, tracepath, etc can be enabled based on the requirement by running enabe_module.ps1 under
   
   (AGENT_HOME)\enable_module.ps1

   
   Note: If you get a script execution error while running the script, rerun using an unrestricted execution policy:

   PowerShell.exe -ExecutionPolicy UnRestricted -File  .\enable_module.ps1

   
   Example: The heartbeat module can be enabled by running the script as follows:

   (AGENT_HOME)\enable_module.sh enable heartbeat

   
   This will enable the heartbeat.yml file under (AGENT_HOME)\modules.d\
   
   After enabling the module, the functioning of the heartbeat can be controlled by modifying the yml file.
   

   After making changes to the configuration, the Healthbeat agent has to be restarted for it to take effect.

Encryption of Agent Communication

vuSmartMaps uses 9094 for TLS and 9092 for plaintext communication from agent to broker.

To use encrypted communication with Kafka broker, the following steps should be performed.

For one-way SSL encryption, i.e. server authentication by the client, only one property needs to be added to the outputs.kafka section, i.e. certificate_authorities. This refers to the Root CA of the certificate used by the broker. In default vuSmartMaps installation, the broker is set up with a certificate signed by custom Root CA and this CA certificate is pre-packaged with the agent truststore. However, in case of a requirement to use your organization certificates, they have to be used during the install time of kafka broker while deploying vuSmartMaps and should also be added to agent truststore manually post agent installation.

The certificate and key properties are required for client authentication. If client authentication is not required, no need to specify these properties.

• certificate_authorities – The list of root(CA) certificates for server verifications. If certificate_authorities is empty or not set, the trusted certificate authorities of the host system are used. Simple SSL encryption requires only 1-way authentication, i.e., server authentication. This is done by the CA which has signed and trusted the server’s public key (certificate).
• certificate – The path to the certificate for SSL client authentication. If the certificate is not specified, client authentication is not available.
• key – The client certificate key used for client authentication. This option is required if a certificate is specified.

The server may be running a valid CA signed certificate or a self-signed certificate depending on the installation. In case CA signed certificate being used by the server, the client trust store must have the CA root certificate of the signing authority on its trust store. If a self-signed certificate is used by the server, the server certificate itself should be added to the trust store of the client.

Please note the agent uses PEM format for certificate_authorities.

Managing Healthbeat Service

How to start, stop and get the status of the Healthbeat service

1. To start the Healthbeat service, use the command below
   
   net start healthbeat
2. To stop the Healthbeat service, use the command below
   
   net stop healthbeat
3. To get the status of the Healthbeat service, use the command below
   
   get-service healthbeat

Logging

1. Logging is done into the following file(AGENT_HOME)\logs\healthbeat-*.ndjson
   Log files are written as newline delimited JSON.
2. The logging level can be changed by modifying the “logging.level” block in (AGENT_HOME)\healtbeat.yml file

How to Run for Debugging?

Uninstall

To uninstall the Healthbeat service, run uninstall-service-healthbeat.ps1 script located at (AGENT_HOME)\healthbeat directory as follows:

Note: If you get a script execution error while running the uninstaller, rerun using an unrestricted execution policy: