Skip to main content

vSphere Connector

Overview​

The Xshield platform uses the tags associated with an asset to group them for building micro-segmentation policies. Typically, the assets derive these tags (also known as core tags) from the underlying operating system and optionally allow the user to configure custom tags for the assets.

In a virtual environment, these core (system) tags may not be available from the virtual operating systems. Additionally, writing custom tags for each assets may be cumbersome. An enterprise, using VMWare's vSphere ecosystem for Virtual Machine management, is likely to have already tagged these systems in that environment. The Xshield platform, rather than requiring to duplicate that effort, provides a mechanism to import these already defined tags in the vSphere environment on to the platform. This capability also allows the administrator to see the Xshield platform value immediately as the tagging allows the grouping to be performed immediately.

vSphere API customer credentials are required to import the tags on to the Xshield platform. Since, it may not be feasible for administrator to provide the credentials or provide access to the API from the cloud (where the Xshield platform is hosted), they instead can run a connector program inside their vSphere environment. This connector will use the API to fetch the tags from vSphere and then use the Xshield API to write the tags to assets on the platform.

ColorTokens provides a connector application to import the tags into the Xshield platform. This software must be installed and run in a virtual machine inside the customers data center. The application will need to be provided with the credentials for accessing the vSphere API as well as the Xshield API. More information about the connector is provided below.

Prerequisites​

vSphere​

  • An Ubuntu (20.x or later) virtual machine with 2 vCPUs, 512MB memory, and 2GB disk space to host the ColorTokens vSphere Connector.
  • Internet connectivity to download the vSphere Connector from the ColorTokens image repository.
  • Persistent Internet connectivity to Xshield for sending vSphere tags.

Xshield​

There are no prerequisites for enabling the integration in Xshield. Once the vSphere connector is successfully installed and running, the integration becomes active, and tags are fetched to Xshield.

Procedure​

vSphere Setup​

All commands listed below should be executed from the vSphere CLI.

Download and Install Connector​

version=$(curl -L -s https://sacolortokensdev.blob.core.windows.net/ct-tag-connector/stable.txt) \
&& wget "https://sacolortokensdev.blob.core.windows.net/ct-tag-connector/$version/packages/debian/x86_64/ct-tools-connector_$version.x86_64.deb" \
&& sudo dpkg -i ct-tools-connector_$version.x86_64.deb

Upon successful installation, the following files will be available under /opt/colortokens/connector:

/opt/colortokens/connector
├── config
│   ├── connector
│   │   ├── connectorConfig.yml
│   │   └── reconciliation.yml
│   ├── ct-platform
│   │   └── ctCred.yml
│   └── vSphere
│       └── vSphereConfig.yml
├── cron
│   └── connector.cron
├── exec
│   └── connector
├── logs
│   └── connector.log
└── setConfig

Set vSphere and Xshield Credentials​

sudo /opt/colortokens/connector/setConfig

This launches a menu-driven interface to configure the following:

  • vSphere credentials: protocol, username, password, datacenter name and hostname (OR the IP address of the vsphere host)
  • Xshield credentials: Xshield API Credentials & Domain URL To generate API credentials follow the steps in Xshield API key generation

Configure Attribute Mapping​

Typically, tagging is done in free-flow format and hence tag names may not be the same on two different platforms. The same applies to an integration between a customer's vSphere environment and the Xshield platform. The connector must be configured with the mapping of the tag names so that the value(s) associated with the tag is imported to the right tag on the Xshield platform.

Edit the reconciliation.yml file located at /opt/colortokens/connector/config/connector to enable tag mapping. Default mapping:

Reconciliation:
  identifier:
    ipaddress:
      - ipaddress
  mapping:
    owner:
      - u_owner
    environment:
      - u_environment
    application:
      - u_application
    role:
      - u_role
    location:
      - u_location

To change mapping:

nano /opt/colortokens/connector/config/connector/reconciliation.yml

Run the Connector​

sudo /opt/colortokens/connector/exec/connector

A log entry will be generated under Monitoring > Tabs confirming the integration activation.

Operational Commands​

Run Connector at Custom Interval​

View and edit the Cron job using:

sudo su
crontab -l  # List all cron jobs
crontab -e  # Edit cron interval

Examples:

0 0 * * *   /opt/colortokens/connector/exec/connector  # Daily execution
* * * * *   /opt/colortokens/connector/exec/connector  # Every minute execution
*/2 * * * * /opt/colortokens/connector/exec/connector  # Every 2 minutes execution

Uninstall Connector​

sudo dpkg --remove colortokens-connector

Debugging Connector Issues​

Log file location: /opt/colortokens/connector/logs/connector.log

To change log levels (Info, Debug, Error, Fatal), modify:

nano /opt/colortokens/connector/config/connector/connectorConfig.yml