VCP Plugin Installation Guide

Installation Procedure Overview

• If you're installing the plugin for the first time, follow the instructions in the New OVA Installation section below.
• If you're upgrading from version 1.0.0 or later using an offline upgrade bundle, follow the instructions in the Upgrading from Version 1.0.0 or Later section below.
• If you're upgrading online from version 1.2.0 or later, follow the instructions in the Online Upgrade from Version 1.2.0 or Later section below.
• If you're upgrading from a version prior to 1.0.0, contact the Lightbits Support team for detailed instructions.

OVA Installation Instructions

Prerequisites

1. vSphere client.
2. ESXi version 7.0 U3 and above, a Datastore of minimum size 24 GiB. 8.x and above versions are supported as well.
3. A static IPv4 IP or DHCP server for the plugin virtual machine.
4. Lightbits VMware Plugin OVA file (lightbits_vsphere_plugin.ova).

New OVA Installation

1. Open vSphere Client. Navigate to the Inventory view. Right-click on the ESXi host to run the plugin virtual machine. Select Deploy OVF Template.
2. Select the OVA file provided by Lightbits and click Next.
3. Specify the virtual machine name. This can be the default name, or you can enter a new name. Click Next.
4. Select the ESXi host where you want to deploy the plugin.
5. In the Configuration page, select DHCP if you want the plugin to be assigned an IP address via DHCP, or Static IP if you want to provide the IP address, gateway, and DNS servers manually.
6. Select the Datastore where the plugin's local storage will be stored.
7. Select the network to be exposed to the plugin. This network should have connectivity to Lightbits clusters and to the vSphere Client.
8. In the Customize Template screen, provide public SSH keys and/or a default login password. If you do not provide either one, you will not be able to log in to the plugin VM, if needed.
9. If you've selected Static IP configuration, fill in all three fields in the Network Customization category.
10. Click Finish to begin the OVA deployment.
11. Let the OVF deployment complete. When the green checkmark appears, power the Plugin VM.
12. When the installation is complete, the VM's console includes a congratulatory message. Note that this will take a few minutes to appear.
13. By default, the OVA will not be restarted in case the ESXi host is restarted.

To enable auto-restart:

1. Using the vSphere client, navigate to the Inventory view, and choose ESXi hosting the plugin virtual machine.
2. Select Configure > Virtual Machines > VM Startup/Shutdown > Edit... > Manual Startup.
3. Find and select the OVA VM, and then select Move To > Automatic.
4. Click Automatic.
5. Select the OVA VM again, and click Edit....
6. Under Startup Settings, select Use specified settings, and select Continue immediately if VMWare Tools starts.
7. Click OK and then OK again.
8. The IP address of the plugin is shown in the Summary page for the VM in the vSphere Client. The Admin portal will be available on port 443.

Logging into the Admin Portal

Use a web browser and navigate to port 443 to log in to the Admin portal. Use the following default credentials:

Username: admin

Password: lightbits

Upon first successful login, you will be required to change the password to a new one. The new password must be at least 8 characters long, and include uppercase and lowercase letters, numerals, and punctuation characters.

Registering the VCP to vCenter

After successfully logging in to the Admin portal, follow these instructions to register the plugin to a vCenter:

1. Click Register New Server.
2. Type in the vCenter IP or FQDN, username, and password.
3. Click Register.
4. Verify that the registration completed successfully, by looking for the word Yes under Registered in the table.

Registering Your First Cluster

1. Browse to vCenter and log in if needed. Click Shortcuts on the navigation tree on the left, and then click the Lightbits icon.
2. Right-click Lightbits Clusters on the plugin's navigation tree, and select New Cluster.
3. Follow the instructions given by the wizard.

Upgrading from Version 1.0.0 or Later

1. Fetch the VCP upgrade bundle from Lightbits: lb-vcp-vXXX-offline.tgz.
2. Log in to the Admin portal.
3. You will need to create a database backup before you can start the upgrade procedure. Click Backup & Restore on the left navigation tree, then click Backup and Create Backup. A file containing a backup of the VCP database will be generated, and the download will start automatically. Save this file in a safe place.
4. In the Admin portal, click Upgrade from the left navigation tree.
5. Click Browse and navigate to the VCP upgrade bundle (from step 1).
6. When the upload has completed, the Upgrade button will be enabled. Click it.
7. You may be prompted to provide the SSH credentials of the VM user running the VCP.

8. Click Upgrade to start the upgrade procedure. A large spinner will be shown while the upgrade is still ongoing.
9. When finished, Upgraded successfully is displayed. Click OK to reload the Admin portal.

Online Upgrade from Version 1.2.0 or Later

1. Log in to the Admin portal.
2. Click Appliance Settings on the left navigation tree.
3. If your OVA is behind a corporate firewall and/or you need to use a proxy in order to access the internet, click Edit on the top of the screen (next to HTTPS Proxy), and fill in the proxy details.
4. Click Edit next to Online Repository, and key in the details of the online repository. Contact the Lightbits Support team to get these details.
5. Click Test and verify that a green checkmark is shown, to indicate that the URL is correct and reachable.
6. You will need to create a database backup before you can start the upgrade procedure. Click Backup & Restore on the left navigation tree, then click Backup and Create Backup. A file containing a backup of the VCP database will be generated, and the download will start automatically. Save this file in a safe place.
7. In the Admin portal, click Upgrade from the left navigation tree.
8. Verify that Online Repository is selected.
9. Verify that Available Version shows the version that you want to upgrade to.
10. Click Upgrade to start the upgrade.
11. You may be prompted to provide the SSH credentials of the VM user running the VCP; however, note that the default OVA installation should not require you to key in any credentials.
12. Click Upgrade to start the upgrade procedure. A large spinner will be shown while the upgrade is still ongoing.
13. When finished, Upgraded successfully is displayed. Click OK to reload the Admin portal.

Unregistering the VCP from vCenter

The VCP can be unregistered from the vSphere client (vCenter).

Do the following:

1. Use a web browser and navigate to port 443 to log in to the Admin portal.
2. Select the correct VCenter.
3. Click Unregister.

Troubleshooting

Collecting VCP Logs

VCP logs are stored in two locations. You can observe and collect these logs if needed for analysis, or send them over to the Support team for further debugging, if requested.

The plugin and admin portal logs are stored in the $HOME/lightos_logs directory. You can configure this to use a different location by editing docker-compose.yml.

VCP container logs can be viewed by executing:

docker-compose logs

To get the logs of a specific container, use:

docker-compose logs vsphere-plugin

Enabling VCP Debug Logs

You might be asked by the Support team to temporarily enable additional logging for the product. An easy way to do this would be to create or edit the docker-compose.override.yml file (in the same folder as docker-compose.yml), with the following content:

version: "3.7"

services:

  vsphere-plugin:

    environment:

      LOGGING_LEVEL_COM_LIGHTBITS: DEBUG

Execute the following command to restart the plugin, with additional logging:

./start-lightbits-plugin.sh

Forgot Password

If you forget your admin portal password, run the following command to revert it to the factory default lightbits:

docker-compose exec mongodb mongosh --authenticationDatabase admin -u admin -p light lightos --eval 'db.vcp_user.update({ username: "admin" }, {$set: { password: "$2a$10$qH76RHaCahun1GD02Z8T6OMiAWzTGJ72BOu5COeEanD3gH.vhebmG", passwordChangeRequired: true } });'

Then log in to the admin portal and change the default password when requested.

Failure to Upgrade

In case of upgrade failure, try to reconnect to the Admin portal in either ports 8080 or 433.

If the VCP is non-recoverable, you should be able to rebuild the OVA and apply the backup file you have created shortly before starting the upgrade.

An automated backup file is also created on the OVA during an upgrade, for use in case you do not have access to the backup you have created. This file is called recovery_backup.bin and you should be able to find it in the OVA $HOME directory - or in the directory where the docker-compose.yml file was deployed.