Healthbeat 8.1.4 – Linux 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 Linux:

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

Pre-requisites

• A sudo user with elevated privilege or a superuser access is required to create startup scripts during installation.
  

  cp (AGENT_HOME)/etc/init.d/healthbeat /etc/init.d/healthbeat

  cp (AGENT_HOME)/lib/systemd/system/healthbeat.service /lib/systemd/system/healthbeat.service

  sudo systemctl enable healthbeat or sudo update-rc.d healthbeat

• To remove/disable the startup script during agent uninstallation.
  

  sudo systemctl disable healthbeat

  rm /etc/init.d/healthbeat

  rm /lib/systemd/system/healthbeat.service

• The agent does not need any superuser privileges for running, it can run as a normal user.
• Firewalls, if any, should allow the outgoing TCP port of the vuSmartMaps data collector/shipper from the node on which this agent is installed.
• To enable a non-privileged user (non root or  non sudo) to stop and start the service using systemctl or service commands, the following entries can be added to  /etc/sudoers.
  
  (USERNAME) ALL=NOPASSWD:/usr/bin/systemctl stop healthbeat, /usr/bin/systemctl start healthbeat, /usr/bin/systemctl reload healthbeat , /usr/bin/systemctl restart healthbeat, /usr/bin/systemctl status healthbeat, /usr/bin/systemctl disable healthbeat,  /bin/cp healthbeat.service /lib/systemd/system/, /bin/cp healthbeat /etc/init.d/, /sbin/service healthbeat stop, /sbin/service healthbeat start, /sbin/service healthbeat restart, /sbin/service healthbeat status, /sbin/service healthbeat force-reload, /bin/rm /lib/systemd/system/healthbeat.service, /bin/rm /etc/init.d/healthbeat

Note: (USERNAME) is the placeholder for the non root user running the agent.

Supported OS

• Ubuntu – 16.04, 18.04, 20.04
• RHEL – 7.x and above
• CentOS – 7.x and above

Installation

1. Extract the package and run the Healthbeat installation script.
   
   bash ./install_healthbeat.sh

   This will run through the installation wizard.

2. Choose the installation option:
   
   1. Select “1” to install the agent for the first time
   2. Select “2” to upgrade the agent. The upgrade option will only update the binaries and leave the configurations intact.
3. Enter to accept the default directory. If you want the agent to be installed elsewhere, please specify the directory path.
   Example,
   

   /home/$USER – The installation will create Healthbeat directory inside /home/$USER/

   /home/$USER/agents  – The agents directory should exist in the system.

   Installation will create Healthbeat directory

   /home/$USER/agents/healthbeat/

4. The installation will ask to provide superuser / sudo access to create init.d/systemd services for the startup on system reboot.
   
   Enter [y] to accept this and provide the superuser / sudo username and password to proceed with.
   
   If you don’t have superuser / sudo access enter ‘n’ and skip the above steps. But, you have to run these steps manually with sudo access.

Configuration

1. The configuration file is available at the following location
   
   (AGENT_HOME)/etc/healthbeat/healthbeat.yml
2. During the installation, 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.
3. The configuration will update the following attributes:

• • Shipper/Target IP – The remote vuSmartMaps system where the data is to be sent.
  • 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:
    • Kafka

• • • beats

• • Port – The remote listening port on the vuSmartMaps data collector/shipper.

• • Interval – The frequency of data collection. Default is 5 min.

• • Topic – The Kafka topic name in case, 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)/etc/healthbeat/healthbeat.yml

   and

   (AGENT_HOME)/etc/healthbeat/modules.d/system.yml
2. The (AGENT_HOME)/etc/healthbeat/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 Kafka output can be enabled by uncommenting the “output.kafka” setting. Specify the remote kafka collector IP and port in the “host:” field.
   

   For example
   hosts: [“192.168.10.1:9092”]
   Specify the ‘topic’ name in the “topic:” field
   topic: ‘healthbeat-server‘

   

   Following are the configurations in the Kafka output block.

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

   output.kafka:

   #initial brokers for reading cluster metadata

   hosts: [“192.168.10.1:9092”]

   ###message topic selection + partitioning

   #topic: ‘{KAFKA_TOPIC}’

   topic: ‘healthbeat-server’  # This is the topic name

   required_acks: 1

   compression: gzip

   max_message_bytes: 100000

   channel_buffer_size: 100000

   #key: ‘%{[message_key]}’

   #—————————————————————————–

4. The logstash/beat output can be enabled by uncommenting the “output.logstash” setting. Specify the remote beats collector IP and port in the “host:” field. For example hosts: [“192.168.10.1:5040]
   

   
   Following are the configurations in the logstash output block.

   #—————————– Logstash output ——————————–

   output.logstash:

   # The Logstash hosts

   hosts: [“localhost:5040”]

   #ssl.enable: true

   #ssl.verification_mode: none

   # 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”

   #——————————————————————————-

5. The period option in (AGENT_HOME)/etc/healthbeat/modules.d/system.yml should be used to change the frequency at which the health metrics are collected.
   period: 300s
   This collects the system health metrics every 5 minutes and sends them to the vuSmartMaps collector.
6. By default, the system module is enabled. The additional modules like heartbeat, urlbeat, tracepath, apache2 can be enabled based on the requirement by running the below commands:
   
   (AGENTS_HOME)/usr/share/healthbeat/bin/enable_module.sh enable heartbeat

• This will create heartbeat.yml file under  (AGENT_HOME)/etc/heartbeat/modules.d/
• You can add the heartbeat targets in the hosts in heartbeat.yml
• 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

Enabling services at startup manually

1. Login with sudo user and run the below commands
   
   Sudo
   (AGENTS_HOME)/healthbeat/usr/share/healthbeat/bin/enable_healthbeat_service.sh
2. Once the systemd or service commands are enabled you can start and stop the agent using the below command:
   
   systemctl start healthbeat
   systemctl stop healthbeat
   systemctl status healthbeat

   (OR)

   service healthbeat start
   service healthbeat stop
   service healthbeat status

   
   Note: Please refer to the ‘Prerequisite’ ‘To enable a non-privileged user (non root or  non sudo) to stop and start the service using systemctl or service commands’
   

   If services are not enabled then you can manually start/stop the Healthbeat using the below commands:

   (AGENTS_HOME)/usr/share/healthbeat/bin/healthbeat.sh start
   (AGENTS_HOME)/usr/share/healthbeat/bin/healthbeat.sh stop
   (AGENTS_HOME)/usr/share/healthbeat/bin/healthbeat.sh status

   
   Note:

1. • Use the above command to start/stop the agent if you have not enabled the systemd/service commands.
   • Also if you have started the service using systemctl/service then you have to stop the agent using systemctl/service commands.

Logging

How to Run for Local Testing?

Uninstall

To uninstall navigate to agent installation path

For example: if Healthbeat is installed under /home/agent/healthbeat