Page tree
Skip to end of metadata
Go to start of metadata

Overview

VMware vSphere is a VMware's cloud computing virtualization platform. It is a package containing many components. The 2 main components are:

  • VMware vCenter Server: It is the central control point for data center services such as access control, performance monitoring and alarm management
  • VMware vSphere Client: It allows users to remotely connect to ESXi or vCenter Server

The LAM connects with the vCenter server and fetches events from it. The events generated in it are the actions performed on virtual machines present in it, or their status updates. The LAM after fetching the events, forwards it to Moogsoft AIOps.

Process Overview


  1. LAM reads the configuration from the vsphere_lam.conf file.
  2. LAM will connect with the vSphere Server using the given host name or IP Address.
  3. The response is received with event data in json format.
  4. The events are parsed and converted into normalized Moogsoft AIOps events.
  5. The normalized events are then published to MooMS bus.

vSphere LAM Configuration

The alarms received from vSphere are processed according to the configurations in the vsphere_lam.conf file. The processed alarms are published to Moogsoft AIOps.

The configuration file contains a JSON object. At the first layer of the object, the LAM has a parameter called config, and the object that follows config has all the necessary information to control the LAM.

The following sections are available for configuration in the vSphere LAM configuration file.

Monitor

The vSphere LAM takes the incidents from vSphere. The user can configure the parameters here to establish a connection with vSphere.

    config :
    {

        monitor:
        {

            name                      : "VSphere Lam Monitor",

            class                     : "CVSphereMonitor",

            host_name             	  : "localhost",
            
            user_name              	  : "userName",

            password              	  : "password",

            # encrypted_password   	  : "ieytOFRUdLpZx53nijEw0rOh07VEr8w9lBxdCc7229o=",

			vm_names                  : [],
            
			use_ssl                   : false,

			path_to_ssl_files         : "config",

            server_cert_filename      : "server.crt",

            use_client_authentication : false,

			client_key_filename       : "client.key",
            
			client_cert_filename      : "client.crt",
            
            polling_interval          : 10,

            max_retries               : 10, 

            retry_interval            : 60  
              
     },
  • name and class: These fields are reserved and should not be changed. The default values are VSphere Lam Monitor and CVsphereMonitor respectively
  • host_name: Enter the hostname or the IP address of the vCenter server. E.g. localhost
  • user_name and Password: Enter the username and password of the vCenter console
  • encrypted_password: If the encrypted password is to be used then enter the encrypted password in this field and comment the password field. At a time either password or the encrypted_password field is used. If both the fields are not commented then the field encrypted_password will be used by the vSphere LAM
  • vm_names: Enter the name of the Virtual Machine that you want to monitor in double quotes. You can enter multiple virtual machine names in double quotes separated by a comma. E.g ["vmname1", "vmname2"]. If nothing is mentioned here, then the LAM fetches the events from all the virtual machines
  • use_ssl: Enter true here, to enable SSL Communication. By default, it is set to false

  • path_to_ssl_files: Enter the path of the directory where all the certificates are stored, e.g. "/usr/local/vsphere_ssl"

  • server_cert_filename: Enter the server certificate name here. Use the certificate "rui.crt" here. The crt file should be present in the directory given in path_to_ssl_files field

  • use_client_authentication: Enter true here if you want client authentication, otherwise set it to false. By default, it is set to false. If it is set to true, then the values are to be entered in the client_key_filename and the client_cert_filename fields.

  • client_key_filename: Enter the name of the key file here, e.g. "rui.key".  The key file should be present in the directory given in path_to_ssl_files field.

  • client_cert_filename: Enter the name of the certificate file here, e.g. "rui.crt". The cert file should be present in the directory given in path_to_ssl_files field.

  • polling_interval: The polling time interval between the requests after which the event data is fetched from vSphere. The polling interval is entered in seconds

    The default value is set to 10 seconds, if 0 is entered in this field then the time interval is by default set to 10 seconds

  • max_retries: The maximum number of retry attempts to reconnect with the vSphere server in case of a connection failure

    The default value is set to 10, if 0 is entered in this field then the LAM by default takes the value 10 and will try at least 10 times to reconnect

    If all the number of retries are exhausted, then an alarm is sent to Moogsoft AIOps about the connection failure. For re-establishing the connection the LAM has to be restarted

  • retry_interval: The time interval between two successive retry attempts

    The default value is set to 60 seconds, if 0 is entered in this field then the time interval is by default set to 60 seconds

    The entry in the fields polling_interval, max_retries, retry_interval and max_events should be an integer, therefore enter the values in these fields without quotation marks

The LAM starts fetching the events from the current time. After that it saves the last poll time (in epoch format) in a state file. The state file is generated in the same folder where the config file is present e.g. $MOOGSOFT_HOME/config, and has the same name as the config file

It is recommended not to make any changes to the state file as this may lead to loss of alarms or events

Agent

Agent allows the user to define two parameters:

agent:
        {
                name    : "VMWare vSphere"
                #log    : "/var/log/moogsoft/vsphere_lam.log"
        },


The above example specifies:  

name: This is the agent name. The events sent to MooMS by the vSphere LAM are identified by the agent name in the log. In this example the agent name is VMWare vSphere

log: In this instance, the vSphere LAM will write its ingress contents in the file vsphere_lam.log located at /var/log/moogsoft/

HA Configuration

Refer the document HA Configuration of LAM

Mapping 

For events received in JSON format, a user can directly map the alarm/event fields of vSphere with moogsoft fields. In the case of an event received in text format, the event is first tokenised in the Variable section, and the tokenised event is then mapped here in the mapping section. The parameters of the received alarm/event are displayed in Moogsoft AIOps according to the mapping done here.

 mapping :
        {
            catchAll: "overflow",
			rules:
            [
                { name: "signature", rule:      "$ipAddress::$vm::$host::$eventType" },
                { name: "source_id", rule:      "$ipAddress" },
                { name: "external_id", rule:    "$chainId" },
                { name: "manager", rule:        "VMWare vSphere" },
                { name: "source", rule:         "$host" },
                { name: "class", rule:          "$eventType" },
                { name: "agent", rule:          "$LamInstanceName" },
                { name: "agent_location", rule: "$LamInstanceName" }, 
                { name: "type", rule:           "$eventType" },
                { name: "severity", rule:       "$severity",conversion:"sevConverter"},
                { name: "description", rule:    "$fullFormattedMessage" },
                { name: "agent_time", rule:     "$createdTime"} 
            ]
        },
        filter:
        {
            presend:"VSphereLam.js"
        }


The above example specifies the mapping of the vSphere alarm fields with the Moogsoft AIOps fields.

The signature field is used by the LAM to identify correlated alarms

The following table provides the alarm fields code and their respective names which can be used in the mapping section shown above:

An example of vSphere events:


Constants and Conversions

Constants and Conversions allow the user to convert formats of the received data defined users.

        constants:
        {
            severity:
            {
                "info"        	: 1,
                "Information"	: 1,
                "warning"       : 2,
                "Warning"       : 2,
                "error"         : 5    
            }
           
        },
        conversions:
        {
            sevConverter:
            {
                lookup: "severity",
                input:  "STRING",
                output: "INTEGER"
            },
            stringToInt:
            {
                input:      "STRING",
                output:     "INTEGER"
            },
         
            timeConverter:
            {
                timeFormat: "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
                input:      "STRING",
                output:     "INTEGER"
            }
        },


The above example specifies:

  • Severity and sevConverter: The severity field has a conversion defined as sevConverter in the Conversions section, this looks up the value of severity defined in the severity section of constants and returns back the mapped integer corresponding to the severity

  • stringToInt: It is used in a conversion, which forces the system to turn a string token into an integer value
  • timeConverter: It is used in conversion which forces the system to convert time. If epoc time is to be used, then timeFormat mentioned in timeConverter should be commented. Otherwise, the user should provide the timeFormat

Custom Info

The alarms/events are displayed in the Moogsoft AIOps, the data in the fields of the alarm or event mapped in the mapping section are shown in the respective columns of Moogsoft AIOps columns. The fields of alarms and events which are not mapped in the mapping section are displayed in the Custom Info field of the alarm. An example of Custom Info:

catchALL 

The attribute that is never referenced in a rule is collected and placed as a JSON object in a variable called overflow defined here and passed as part of the event.

mapping :
        {
            catchAll: "overflow",
			rules:
            [
                { name: "signature", rule:      "$ipAddress::$vm::$host::$eventType" },
                { name: "source_id", rule:      "$ipAddress" },
                { name: "external_id", rule:    "$chainId" },
                { name: "manager", rule:        "VMWare vSphere" },
                { name: "source", rule:         "$host" },
                { name: "class", rule:          "$eventType" },
                { name: "agent", rule:          "$LamInstanceName" },
                { name: "agent_location", rule: "$LamInstanceName" }, 
                { name: "type", rule:           "$eventType" },
                { name: "severity", rule:       "$severity",conversion:"sevConverter"},
                { name: "description", rule:    "$fullFormattedMessage" },
                { name: "agent_time", rule:     "$createdTime"} 
            ]
        },

The vSphere event field callCount is sent to vSphere LAM. Since it is not mapped to a field in the vsphere_lam.conf file it is placed in the overflow JSON object. The fields that are placed in the overflow variable can be viewed in the vSphere LAM log file or the custom info field of the event in Moogsoft AIOps GUI.

An example of an overflow JSON object created in the vSphere LAM log file:

"custom_info":"{\"overflow\":{\"callCount\":0,\"userAgent\":\"JAX-WS RI 2.2.9-b130926.1035 svn-revision#5f6196f2b90e9460065a4c2f4e30e065b245e51e\",\"sessionId\":\"5245abf2-1114-bfba-5087-3d326c8ab249\",\"loginTime\":1495695078882}}"
Quotes

Quotes

In some instances, the attribute strings are quoted. Our JSON parser ignores it, but the standard requires quoting for all strings, so Moogsoft recommends that user quote all strings. 

Comments

A user can comment out lines by appending them with a hash. 

Starting the vSphere LAM

To start the vSphere LAM enter the following command:

service vspherelamd start

To stop the vSphere LAM enter the following command:

service vspherelamd stop


To view the status of vSphere LAM, enter the following command:

service vspherelamd status


Command line attributes

The vsphere_lam is a command line executable that can be run as a service daemon, and takes four attributes, which can be viewed by typing:

 vsphere_lam --help

Option

Description

--config

Points to a pathname to find the configuration file for the LAM. This is where the entire configuration for the LAM is specified

--help

Displays all the command line options

--version

Displays the component’s version number

--log level

Specifies the level of debugging. By default, User gets everything. In common with all executables in MOOG, having it set at that level can result in a lot of output (many messages per event message processed).

In all production implementations, it is recommended that log level is set to WARN, which only informs user of matters of importance

Version Information

LAM Version

Tool Version

Tested?

Expected to Work

1.0

VMware vSphere Hypervisor (ESXi) 6.0 

VMware vSphere Hypervisor (ESXi) 6.5

Yes

Yes

1.1

VMware vSphere Hypervisor (ESXi) 6.0 

VMware vSphere Hypervisor (ESXi) 6.5

Yes

Yes

System Information

This LAM was tested on a system with the following configurations:

CPU2 core
RAM4 GB
Operating SystemCentOS Linux release 6.7

The system must at least have the above mentioned system requirements to run the LAM.



  • No labels