List VCHs and Obtain Their IDs

You can obtain a list of the virtual container hosts (VCHs) that are running in vCenter Server or on an ESXi host by using the vic-machine ls command.

The vic-machine ls command lists VCHs with their IDs, names, and versions. The vic-machine ls command does not include any options in addition to the common options described in Common vic-machine Options.


You have deployed a VCH. If you have not deployed a VCH, vic-machine ls returns an empty list.


  1. On the system on which you run vic-machine, navigate to the directory that contains the vic-machine utility.
  2. Run the vic-machine ls command.

    • To obtain a list of all VCHs that are running on an ESXi host or vCenter Server instance, you must provide the address of the target ESXi host or vCenter Server.
    • You must specify the username and optionally the password, either in the --target option or separately in the --user and --password options.
    • If your vSphere environment uses untrusted, self-signed certificates, you must also specify the thumbprint of the vCenter Server instance or ESXi host in the --thumbprint option. To obtain the thumbprint of the vCenter Server or ESXi host certificate, run vic-machine without the specifying the --thumbprint option. The listing of the VCHs fails, but the resulting error message includes the required certificate thumbprint. You can copy the thumbprint from the error message and run vic-machine again, including the --thumbprint option.

      NOTE: If you obtain the thumbprint by other means, use upper-case letters and colon delimitation in the thumbprint. Do not use space delimitation.

    $ vic-machine-operating_system ls
    --target esxi_host_address
    --user root
    --password esxi_host_password
    --thumbprint certificate_thumbprint
    $ vic-machine-operating_system ls
    --target vcenter_server_username:password@vcenter_server_address
    --thumbprint certificate_thumbprint


The vic-machine ls command lists the VCHs that are running on the ESXi host or vCenter Server instance that you specified.

vm-101     path     vch_1   version     Upgradeable to version
vm-102     path     vch_2   version     Up to date
vm-n       path     vch_n   version     Up to date
  • The IDs are the vSphere Managed Object References, or morefs, for the VCH endpoint VMs. You can use VCH IDs when you run the vic-machine inspect, debug, upgrade, and delete commands. Using VCH IDs reduces the number of options that you need to specify when you run those commands.
  • The PATH value depends on where the VCH is deployed:

    • ESXi host that is not managed by vCenter Server:
    • Standalone host that is managed by vCenter Server:
    • vCenter Server cluster:


      If VCHs are deployed in resource pools on hosts or clusters, the resource pool names appear after Resources in the path. You can use the information in PATH in the --compute-resource option of vic-machine commands.

  • The VERSION value shows the version of vic-machine that was used to create the VCH. It includes the release version, the build number and the short Git commit checksum, in the format vch_version-vch_build-git_commit.

  • The UPGRADE STATUS reflects whether the current version of vic-machine that you are using is the same as the one that you used to deploy a VCH. If the version or build number of the VCH does not match that of vic-machine, UPGRADE STATUS is Upgradeable to vch_version-vch_build-git_commit.

results matching ""

    No results matching ""