DocsDeployment & Installation > On-Prem Deployment & Installation > Deployment on Existing Kubernetes Cluster

Healthbeat 8.1.4 – Linux Readme


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


  • 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

(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


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

    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.

    /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


  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.


  1. The configuration file is available at the following location
  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


  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: [“”]
    Specify the ‘topic’ name in the “topic:” field
    topic: ‘healthbeat-server

    Following are the configurations in the Kafka output block.

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


    #initial brokers for reading cluster metadata

    hosts: [“”]

    ###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: [“]

    Following are the configurations in the logstash output block.

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


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

ssl.certificate_authorities:[“(path-to-client-truststore (.pem))”]

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

ssl.certificate: “(path-to-client-certificate (.pem))”
ssl.key: “(path-to-client-key (.key))”
#If implementing only 1-way SSL
ssl.verification_mode: “none”

  • 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
  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


    service healthbeat start
    service healthbeat stop
    service healthbeat status

    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/ start
    (AGENTS_HOME)/usr/share/healthbeat/bin/ stop
    (AGENTS_HOME)/usr/share/healthbeat/bin/ status


    • 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.


How to Run for Local Testing?

(AGENTS_HOME)/usr/share/healthbeat/bin/healthbeat -e -v -c



To uninstall navigate to agent installation path


bash ./

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

cd /home/agent/healthbeat



Browse through our resources to learn how you can accelerate digital transformation within your organisation.

Quick Links