VMware Import with Catalyst

Catalyst is SoftIron’s app provided to migrate from vSphere to VM Squared. Once connected to a VMware ESXi host or a vCenter, it can automatically import most virtual machines into VM Squared.

Enable ESXi access#

Before starting the Catalyst application, you must first enable SSH on your ESXi host and configure key-based authentication.

Start by logging into your ESXi deployment, then look under Host > Manage to confirm “TSM-SSH” is running. If not, follow the product’s instructions for enabling the service.

Once the SSH service reports as Running, we will use it to set up key-based access to the deployment, allowing secure downloads without exposing your system passwords to VM Squared.

Connect to your ESXi host and create a key by running /usr/lib/vmware/openssh/bin/ssh-keygen

Here is an example of the process.

[root@localhost:~] /usr/lib/vmware/openssh/bin/ssh-keygen 
Generating public/private rsa key pair.
Enter file in which to save the key (//.ssh/id_rsa): 
Created directory '//.ssh'.
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in //.ssh/id_rsa
Your public key has been saved in //.ssh/id_rsa.pub
The key fingerprint is:
SHA256:vzStRA7GPetktU1Rsgig/kL+pytbpbEpc+M9zb8Y84A root@localhost
The key's randomart image is:
+---[RSA 3072]----+
|        ...   . .|
|       .   . . + |
|      .     . o  |
|     . . .     . |
|      o S = . .  |
|     o o @ * +   |
|      = O Eo* .  |
|      .O Oo+o*   |
|      .o=+=...+. |
+----[SHA256]-----+

Now we must give the new key permission to log in remotely. Add it to the file /etc/ssh/keys-root/authorized_keys as outlined in the VMware KB using a command like the one below.

cat /.ssh/id_rsa.pub >> /etc/ssh/keys-root/authorized_keys

We will need the contents of both the public and the private key, to be used later in the process. Copy the files using scp, or copy the contents of /.ssh/id_rsa and /.ssh/id_rsa.pub and place them somewhere safe.

Enable rsync for Catalyst#

In order to upload VM disk images to your VM Squared dashboard, you will need to enable rsync using the keys you created in the previous step. Log into the VM Squared dashboard’s console using SSH, and paste the contents of the public key (id_rsa.pub) using the manage-catalyst-ssh-keys command. manage-catalyst-ssh-keys will prompt you to list, remove or add an SSH key. Input 3 to add an SSH key, and then paste the contents of the public key you generated in Enable ESXi access.

Here is an example of adding and then listing a public key to a VM Squared system named “Skipjack”.

Welcome to VMsquared!
Run "help" for supported commands

VMsquared:skipjack\dashboard> manage-catalyst-ssh-keys
0. Exit
1. List SSH keys
2. Remove SSH key
3. Add SSH key
Select an option: 3
Enter the SSH key you wish to add:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC8mNAQRUF2oNW6ugLdFNw1OBFoza/xzm8BaWHk3f6mp0JmoM4E9wGI9r3dNDRTvRT7rwp4uhWOjEZ+XaZQqbb7zIA6M3kAp9TeGoqInarHu/DUItz9C85Q89YID3J9dI6TzzL7yAAKXL8fkqmSCuuT98mrUKIsOJN/NKnB5ksjODFk1FNyiBI3u+o/5YcJ3CugXrhqnrYEd2zjmGd1C6oEls2LVIfF/97xdesTXpHnTw6m32F2+aqQJFf7iXQT4ycDcTtOU9eDyebX8m7FuFPeR95vqDNOSyJLv25NAYvXDg9oUjMnjBHjtrojRO6UcksUzhce2GWI1K0XP0HvjooaDog18soUHUUWeQiVZJxmbfgrhUdfmzn61dwtD9Ftl+rEdmTfvEsyef1oCPIsFLmhR9UZCbXZ1t42dEGofylVPF44g85gcFJcI06TsqJ1Bz4Yxctt/junw+e5HVmL/jiEepuS7Vrp5lKru017F6G4LuDCFTftc84X+dYOT9nwqe0= vagrant@robot
SSH key added successfully.
0. Exit
1. List SSH keys
2. Remove SSH key
3. Add SSH key
Select an option: 1
Listing SSH keys:
     1  ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC8mNAQRUF2oNW6ugLdFNw1OBFoza/xzm8BaWHk3f6mp0JmoM4E9wGI9r3dNDRTvRT7rwp4uhWOjEZ+XaZQqbb7zIA6M3kAp9TeGoqInarHu/DUItz9C85Q89YID3J9dI6TzzL7yAAKXL8fkqmSCuuT98mrUKIsOJN/NKnB5ksjODFk1FNyiBI3u+o/5YcJ3CugXrhqnrYEd2zjmGd1C6oEls2LVIfF/97xdesTXpHnTw6m32F2+aqQJFf7iXQT4ycDcTtOU9eDyebX8m7FuFPeR95vqDNOSyJLv25NAYvXDg9oUjMnjBHjtrojRO6UcksUzhce2GWI1K0XP0HvjooaDog18soUHUUWeQiVZJxmbfgrhUdfmzn61dwtD9Ftl+rEdmTfvEsyef1oCPIsFLmhR9UZCbXZ1t42dEGofylVPF44g85gcFJcI06TsqJ1Bz4Yxctt/junw+e5HVmL/jiEepuS7Vrp5lKru017F6G4LuDCFTftc84X+dYOT9nwqe0= vagrant@robot
0. Exit
1. List SSH keys
2. Remove SSH key
3. Add SSH key
Select an option: 0
Exiting...

Download Catalyst#

After setting up and logging into a VM Squared deployment, you can download the Catalyst App by going to Storage > Apps as shown below.

Find the Catalyst app in the list. Select it, then click the “Import into Datastore” button.

The Download App view should open. On the first screen, leave the app and Template names as Catalyst, then select Next.

Now choose the datastore where Catalyst will be installed. We strongly recommend using the default datastore.

After selecting a datastore, its name should appear below the Search field.

Select the Finish button, then the download will begin. After a few moments or a few minutes, depending on your connection speed, the Catalyst app will be available under Templates > VM Templates, ready to be deployed.

Deploying Catalyst#

Select the Catalyst template from VM Templates and click the Deploy button to begin setting up Catalyst.

When presented with the Configuration screen, pick a name and click Next.

User Inputs#

Catalyst will need some environment-specific information. Catalyst’s user inputs contain the information needed to connect to vCenter or ESXi.

User inputs are:

• ESXi_HOST — IP or DNS address of your ESXi host containing VMs to import.
• SOFTIRON_DASHBOARD — IP or DNS address of the VM Squared Web dashboard.
• MANIFOLD_API_USER — username of VM Squared user with permission to create images and templates
• MANIFOLD_API_TOKEN — password of VM Squared user
• CATALYST_PRIVATE_KEY — private key as created in Enable ESXi access

App Storage#

Select the Storage tab, then click the Edit button to configure how much space the app will be allowed once deployed.

Catalyst must have at least enough space to contain the largest VM you plan to migrate—plus 7 GB.

The Edit screen shows how much storage will be allotted to this VM once we spin it up.

Here we see that Catalyst can expect to have 8192 MB of storage at launch, which is 8 GB. If the largest VM we expect to migrate is 4 GB then we must reserve 11264 MB, which is 4 GB plus 7 GB.

App Networking#

Go to the Network tab then select Attach NIC. From there, you want to connect to a network from which both the VM Squared dashboard and your ESXi host will be accessible. If routing between the two is not possible, you can multi-home Catalyst by adding multiple NICs connected to different Virtual Networks.

Once you select Finish, the Template will deploy. Catalyst should be ready a few minutes later.

Once launched, Catalyst’s settings for the ESXi host should match what was provided during the app’s initial setup steps. These settings cannot be changed while Catalyst is running. If you suspect the ESXi connection details may need adjusting, then halt the VM and edit its template as needed before relaunching the app.

The Catalyst app is available through a browser or from the command line. The next two sections give directions for using either one.

Using Catalyst (in a browser)#

Once the Catalyst app has come up in VM Squared, it should be accessible by most modern web browsers as the app’s IP address.

Catalyst through a browser has two main views:: Convert and Status.

The Convert view displays the current dashboard and ESXi host.

Discover VMware VMs#

The main part of the Convert view shows a list of VMs available on the ESXi host, along with the status of each one. VMs that are not eligible for conversion will be shown disabled at the bottom of the list. The reason that the VM cannot be converted is shown to the right of the VM.

The most common reasons that a VM cannot be converted are: the VM is running, it contains snapshots of previous states—or it has already been converted. If a VM is running, it must be shut down outside of Catalyst using the current VM management system before its import can begin. If the VM has snapshots, they should be removed before its import can begin.

When all errors have been corrected, the VM will be available for migration. After making a change to a VM’s state, it may be necessary to refresh the Catalyst browser window in order to see the updated VM list and status.

Import VMware VMs#

To start the conversion of one or more VMs, select the checkbox beside each target VM and then select the “Start conversion” button shown in the previous screenshot, in the bottom left corner of the screen.

Once a conversion has begun, failed, or completed, the app’s view will automatically switch to show the updated Status.

Using Catalyst (from the console)#

Discover VMware VMs#

Connect to Catalyst on the console using the root account using the SSH Public Key associated with your user account in Glasshouse. Catalyst, like many Linux-based servers, does not allow password-based logins to the root account.

To discover available VMs, use the catalyst inventory command:

root@Catalyst:~# catalyst inventory
2024-05-03 14:59:56: Found 11 VM's on esxi-3.int.softiron.com
2024-05-03 14:59:56: Edit the following file to verify VM's to be converted:
2024-05-03 14:59:56: /root/esxi-3.int.softiron.com/vmx_list.txt

Edit the vmx_list.txt file, removing all lines except the VMs you want to migrate. These lines contain the filesystem addresses of your VMs on the ESXi host. Each filename should match its VM name in vCenter.

Import VMware VMs#

To begin importing copies of the VMs, call catalyst convert. Again, each original VM’s data will remain untouched. You are only making a copy of the original.

You can view the process status on the console, or look at more detailed information by following the output of catalyst.log which is located in the same directory as vmx_list.txt

# catalyst convert
2024-05-03 15:01:05: converting ubuntu1.vmx
2024-05-03 16:38:57: conversion complete
2024-05-03 16:38:57: converted output dir: /root/staging/esxi-3.int.softiron.com/root/staging/esxi-3.int.softiron.com/tmprk3hflkg/ubuntu1
2024-05-03 16:38:58: staging converted vmdata for ubuntu1
2024-05-03 16:39:39: staging complete
2024-05-03 16:39:39: creating image ubuntu1-sda on vmsquared-11.int.softiron.com
2024-05-03 16:39:40: image creation complete with id: 4
2024-05-03 16:39:40: setting image ubuntu1/ubuntu1-sda permissions in vmsquared-11.int.softiron.com
2024-05-03 16:39:40: setting image ubuntu1/ubuntu1-sda ownership in vmsquared-11.int.softiron.com
2024-05-03 16:40:21: parsing ubuntu1.vmx
2024-05-03 16:40:21: converting ubuntu1.tmpl
2024-05-03 16:40:21: template creation complete
2024-05-03 16:40:22: VM ubuntu1 complete

Once the import is complete you will have a VM Template created for each VMware VM with the same name, disk contents and network naming.

Start imported VMs#

After importing the VM go to VM Templates and click the Deploy button to start the imported VM.

Finishing Imports & Securing ESXi#

Once you’ve finished importing virtual machines from ESXi, we strongly recommend disabling the SSH service if it’s not typically needed. Since it does contain sensitive credentials, you may also consider terminating the Catalyst instance when not in use.