Fortinet black logo

VMware vSphere v1.0.0

1.0.0
Copy Link
Copy Doc ID e8b7e7d0-f46d-49a5-a788-e4917580f67b:1

About the connector

VMware vSphere® uses virtualization to transform individual data centers into aggregated computing infrastructures that include CPU, storage, and networking resources. VMware vSphere manages these infrastructures as a unified operating environment and provides you with the tools to administer the data centers that participate in that environment. The VMware vSphere stack comprises of virtualization, management, and interface layers. The two core components of vSphere are ESXi and vCenter Server. ESXi is the virtualization platform where you create and run virtual machines and virtual instances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources.

This document provides information about the VMware vSphere connector, which facilitates automated interactions, with a VMware vSphere server using FortiSOAR™ playbooks. Add the VMware vSphere connector as a step in FortiSOAR™ playbooks and perform automated operations such as, starting and stopping a virtual machine, creating a snapshot of a virtual machine, and getting information about a specific virtual machine.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 4.11.0-1161

VMware vSphere Version Tested on: 5.5.0 and 6.5.0

Authored By: Fortinet

Certified: Yes

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-vmware-vsphere

For the detailed procedure to install a connector, click here.

Prerequisites to configuring the connector

  • You must have the IP address or FQDN of the VMware vSphere endpoint server to which you will connect and perform the automated operations and credentials to access that server.
  • You must also have an evaluation license that includes write access on the host.
  • To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, select the VMware vSphere connector, and click Configure to configure the following parameters:

Parameter Description
Server Address IP address or FQDN of the VMware vSphere endpoint server to which you will connect and perform the automated operations.
Username Username to access the VMware vSphere endpoint server to which you will connect and perform the automated operations.
Password Password to access the VMware vSphere endpoint server to which you will connect and perform the automated operations.
Port Port of the VMware vSphere server.
Defaults to 443.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

Function Description Annotation and Category
Create VM Creates a new Virtual Machine (VM) on VMware vSphere, based on the input parameters you have specified. create_vm
Miscellaneous
Start VM Powers on a stopped virtual machine (vm) based on the VM name that you have specified.
If the specified VM had been suspended, then this operation resumes execution from the point that the VM was suspended.
start_vm
Miscellaneous
Snapshot VM Creates a new snapshot of a VM, based on the VM name and snapshot name you have specified. snapshot_vm
Miscellaneous
Get Registered VMs List Retrieves a list of VMs that are registered on the VMware vSphere server. get_registered_vms_list
Miscellaneous
Get VM Information Retrieves details about a specified VM from the VMware vSphere server based on the VM name, IP address, UUID, instance UUID, or VM path you have specified. get_vm_information
Investigation
Suspend VM Suspends the execution on a VM based on the VM name that you have specified. suspend_vm
Miscellaneous
Revert VM Changes the execution state of a VM to the state of a specified snapshot, based on the VM name and snapshot name you have specified. revert_vm
Miscellaneous
Stop VM Powers off a VM based on the VM name that you have specified. stop_vm
Miscellaneous

operation: Create VM

Input parameters

Parameter Description
VM Name Name of the VM that you want to create on VMware vSphere.
Compatibility ESXi host versions that the VM machine run on.
You can choose one of the following compatibilities: ESXi 6.5 Virtual Machine or ESXi 5.5 Virtual Machine.
Hardware Version Virtual machine hardware version that is compatible with ESXi host version you have chosen.
If you select the ESXi 6.5 Virtual Machine option for the Compatibility field, then the associated hardware version is 13.
If you select the ESXi 5.5 Virtual Machine option for the Compatibility field, then the associated hardware version is 10.
Guest OS Family OS family on which you want to install the VM.
You can choose from the following options: Linux, Mac OS, Windows, or Others.
Guest OS Version Based on the OS family you have chosen to install the VM, select the appropriate OS version.
Data Storage Appropriate datastore in which you want to store the VM configuration and disk files.
CPU Number of CPU(s) available to the VM. You can specify a value between 1 to 40.
Memory Memory size of the VM in MB.
Disk Memory Disk size of the VM in GB.
Disk Type Disk type of the VM.
You can select from one of the following: Thin or Thick
Network Network adapter for the VM.
ISO File Path Datastore path of the ISO File of the VM.
For example, [Datastore] ubuntu-18.04-desktop-amd64.iso

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Create VM operation

operation: Start VM

Input parameters

Parameter Description
VM Name Name of the VM that you want to power on.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Start VM operation

operation: Snapshot VM

Input parameters

Parameter Description
VM Name Name of the VM for which you want to take a snapshot.
Snapshot Name Name of the snapshot.
The name that you specify for the snapshot does not require to be unique for the specified VM.
Description (Optional) Description for the snapshot.
If you do not include a description, a default description might be added.
Memory Select this check box (set to true) if you want to include a dump of the internal state of the virtual machine (basically a memory dump) in the snapshot. Memory snapshots consume time and resources and thus take longer to create. If this checkbox is not selected (set to false) the power state of the snapshot is set to powered off. The capabilities_ parameter indicates whether or not the VM supports this operation.
By default, this is set to false.
Quiesce If this checkbox is selected (set to true) and the virtual machine is powered on when the virtual machine when the snapshot is taken, VMware Tools is used to quiesce the file system in the virtual machine. This assures that a disk snapshot represents a consistent state of the guest file systems. If the virtual machine is powered off or VMware Tools are not available, the quiesce flag is ignored.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Snapshot VM operation

operation: Get Registered VMs List

Input parameters

None.

Output

The JSON output contains the status of the action and the list and details of all the registered VMs on the VMware vSphere server.

Following image displays a sample output:

Sample output of the Get Registered VMs List operation

operation: Get VM Information

Input parameters

Parameter Description
Search By Search field based on which you want to search and retrieve for the details of a VM from the VMware vSphere server. You can choose one of the following options:
VM Name: Display name of the VM whose details you want to retrieve from the VMware vSphere server.
IP Address: Primary IP address assigned to the guest operating system.
UUID: 128-bit SMBIOS UUID of a VM represented as a hexadecimal string in "12345678-abcd-1234-cdef-123456789abc" format.
Instance UUID: VirtualCenter-specific 128-bit UUID of a VM, represented as a hexadecimal string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that might share the same SMBIOS UUID.
VM Path: Configuration file path of vMX.
Search Value Value of the field on which you want to perform the search, based on the field that you have selected in the Search By parameter.

Output

The JSON output contains the details of the VM retrieved from the VMware vSphere server, based on the search parameters you have specified.

Note:

There is one key under guest that specifies the status of vmware tools. If VM IP address does not get populated and is null in the Get VM Information step output, check the following keys:

  1. toolsStatus: toolsNotRunning
    when the VM IP address value is present, then the values of the key is:
    toolsStatus: toolsOk
  2. toolsRunningStatus: guestToolsNotRunning
    when the VM IP address value is present, then the values of the key is:
    toolsRunningStatus: guestToolsRunning

Check that the powerState of the VM is poweredOn and if yet the VM IP is null then check the toolsStatuskey of guest.

Following image displays a sample output:

Sample output of the Get VM Information operation

operation: Suspend VM

Input parameters

Parameter Description
VM Name Name of the VM whose execution you want to suspend.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Suspend VM operation

operation: Revert VM

Input parameters

Parameter Description
VM Name Name of the VM that you want to revert to a specified snapshot.
Snapshot Name Name of the snapshot to which you want to revert the specified VM.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Revert VM operation

operation: Stop VM

Input parameters

Parameter Description
VM Name Name of the VM that you want to power off.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Stop VM operation

Included playbooks

The Sample - VMware-vSphere - 1.0.0 playbook collection comes bundled with the VMware vSphere connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the VMware vSphere connector.

  • Create VM
  • Get List of VMs
  • Get VM Information
  • Revert VM
  • Snapshot VM
  • Start VM
  • Stop VM
  • Suspend VM

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

Previous
Next

About the connector

VMware vSphere® uses virtualization to transform individual data centers into aggregated computing infrastructures that include CPU, storage, and networking resources. VMware vSphere manages these infrastructures as a unified operating environment and provides you with the tools to administer the data centers that participate in that environment. The VMware vSphere stack comprises of virtualization, management, and interface layers. The two core components of vSphere are ESXi and vCenter Server. ESXi is the virtualization platform where you create and run virtual machines and virtual instances. vCenter Server is the service through which you manage multiple hosts connected in a network and pool host resources.

This document provides information about the VMware vSphere connector, which facilitates automated interactions, with a VMware vSphere server using FortiSOAR™ playbooks. Add the VMware vSphere connector as a step in FortiSOAR™ playbooks and perform automated operations such as, starting and stopping a virtual machine, creating a snapshot of a virtual machine, and getting information about a specific virtual machine.

Version information

Connector Version: 1.0.0

FortiSOAR™ Version Tested on: 4.11.0-1161

VMware vSphere Version Tested on: 5.5.0 and 6.5.0

Authored By: Fortinet

Certified: Yes

Installing the connector

All connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and use the yum command to install connectors:

yum install cyops-connector-vmware-vsphere

For the detailed procedure to install a connector, click here.

Prerequisites to configuring the connector

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Connectors page, select the VMware vSphere connector, and click Configure to configure the following parameters:

Parameter Description
Server Address IP address or FQDN of the VMware vSphere endpoint server to which you will connect and perform the automated operations.
Username Username to access the VMware vSphere endpoint server to which you will connect and perform the automated operations.
Password Password to access the VMware vSphere endpoint server to which you will connect and perform the automated operations.
Port Port of the VMware vSphere server.
Defaults to 443.
Verify SSL Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True.

Actions supported by the connector

The following automated operations can be included in playbooks, and you can also use the annotations to access operations from FortiSOAR™ release 4.10.0 onwards:

Function Description Annotation and Category
Create VM Creates a new Virtual Machine (VM) on VMware vSphere, based on the input parameters you have specified. create_vm
Miscellaneous
Start VM Powers on a stopped virtual machine (vm) based on the VM name that you have specified.
If the specified VM had been suspended, then this operation resumes execution from the point that the VM was suspended.
start_vm
Miscellaneous
Snapshot VM Creates a new snapshot of a VM, based on the VM name and snapshot name you have specified. snapshot_vm
Miscellaneous
Get Registered VMs List Retrieves a list of VMs that are registered on the VMware vSphere server. get_registered_vms_list
Miscellaneous
Get VM Information Retrieves details about a specified VM from the VMware vSphere server based on the VM name, IP address, UUID, instance UUID, or VM path you have specified. get_vm_information
Investigation
Suspend VM Suspends the execution on a VM based on the VM name that you have specified. suspend_vm
Miscellaneous
Revert VM Changes the execution state of a VM to the state of a specified snapshot, based on the VM name and snapshot name you have specified. revert_vm
Miscellaneous
Stop VM Powers off a VM based on the VM name that you have specified. stop_vm
Miscellaneous

operation: Create VM

Input parameters

Parameter Description
VM Name Name of the VM that you want to create on VMware vSphere.
Compatibility ESXi host versions that the VM machine run on.
You can choose one of the following compatibilities: ESXi 6.5 Virtual Machine or ESXi 5.5 Virtual Machine.
Hardware Version Virtual machine hardware version that is compatible with ESXi host version you have chosen.
If you select the ESXi 6.5 Virtual Machine option for the Compatibility field, then the associated hardware version is 13.
If you select the ESXi 5.5 Virtual Machine option for the Compatibility field, then the associated hardware version is 10.
Guest OS Family OS family on which you want to install the VM.
You can choose from the following options: Linux, Mac OS, Windows, or Others.
Guest OS Version Based on the OS family you have chosen to install the VM, select the appropriate OS version.
Data Storage Appropriate datastore in which you want to store the VM configuration and disk files.
CPU Number of CPU(s) available to the VM. You can specify a value between 1 to 40.
Memory Memory size of the VM in MB.
Disk Memory Disk size of the VM in GB.
Disk Type Disk type of the VM.
You can select from one of the following: Thin or Thick
Network Network adapter for the VM.
ISO File Path Datastore path of the ISO File of the VM.
For example, [Datastore] ubuntu-18.04-desktop-amd64.iso

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Create VM operation

operation: Start VM

Input parameters

Parameter Description
VM Name Name of the VM that you want to power on.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Start VM operation

operation: Snapshot VM

Input parameters

Parameter Description
VM Name Name of the VM for which you want to take a snapshot.
Snapshot Name Name of the snapshot.
The name that you specify for the snapshot does not require to be unique for the specified VM.
Description (Optional) Description for the snapshot.
If you do not include a description, a default description might be added.
Memory Select this check box (set to true) if you want to include a dump of the internal state of the virtual machine (basically a memory dump) in the snapshot. Memory snapshots consume time and resources and thus take longer to create. If this checkbox is not selected (set to false) the power state of the snapshot is set to powered off. The capabilities_ parameter indicates whether or not the VM supports this operation.
By default, this is set to false.
Quiesce If this checkbox is selected (set to true) and the virtual machine is powered on when the virtual machine when the snapshot is taken, VMware Tools is used to quiesce the file system in the virtual machine. This assures that a disk snapshot represents a consistent state of the guest file systems. If the virtual machine is powered off or VMware Tools are not available, the quiesce flag is ignored.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Snapshot VM operation

operation: Get Registered VMs List

Input parameters

None.

Output

The JSON output contains the status of the action and the list and details of all the registered VMs on the VMware vSphere server.

Following image displays a sample output:

Sample output of the Get Registered VMs List operation

operation: Get VM Information

Input parameters

Parameter Description
Search By Search field based on which you want to search and retrieve for the details of a VM from the VMware vSphere server. You can choose one of the following options:
VM Name: Display name of the VM whose details you want to retrieve from the VMware vSphere server.
IP Address: Primary IP address assigned to the guest operating system.
UUID: 128-bit SMBIOS UUID of a VM represented as a hexadecimal string in "12345678-abcd-1234-cdef-123456789abc" format.
Instance UUID: VirtualCenter-specific 128-bit UUID of a VM, represented as a hexadecimal string. This identifier is used by VirtualCenter to uniquely identify all virtual machine instances, including those that might share the same SMBIOS UUID.
VM Path: Configuration file path of vMX.
Search Value Value of the field on which you want to perform the search, based on the field that you have selected in the Search By parameter.

Output

The JSON output contains the details of the VM retrieved from the VMware vSphere server, based on the search parameters you have specified.

Note:

There is one key under guest that specifies the status of vmware tools. If VM IP address does not get populated and is null in the Get VM Information step output, check the following keys:

  1. toolsStatus: toolsNotRunning
    when the VM IP address value is present, then the values of the key is:
    toolsStatus: toolsOk
  2. toolsRunningStatus: guestToolsNotRunning
    when the VM IP address value is present, then the values of the key is:
    toolsRunningStatus: guestToolsRunning

Check that the powerState of the VM is poweredOn and if yet the VM IP is null then check the toolsStatuskey of guest.

Following image displays a sample output:

Sample output of the Get VM Information operation

operation: Suspend VM

Input parameters

Parameter Description
VM Name Name of the VM whose execution you want to suspend.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Suspend VM operation

operation: Revert VM

Input parameters

Parameter Description
VM Name Name of the VM that you want to revert to a specified snapshot.
Snapshot Name Name of the snapshot to which you want to revert the specified VM.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Revert VM operation

operation: Stop VM

Input parameters

Parameter Description
VM Name Name of the VM that you want to power off.

Output

The JSON output contains the status and result of the operation, as shown in the following image that contains a sample output:

Sample output of the Stop VM operation

Included playbooks

The Sample - VMware-vSphere - 1.0.0 playbook collection comes bundled with the VMware vSphere connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the VMware vSphere connector.

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.

Previous
Next