Search Results for: Invoke-VMScript

How to remotely run appliancesh & other shell commands on VCSA w/o requiring SSH?

02.25.2016 by William Lam // 13 Comments

In vSphere 6.0 Update 1, the vCenter Server Appliance (VCSA) has received a significant enhancement to its Virtual Machine Management Interface also known as VAMI for short. As the name suggests, this interface provides basic configuration, monitoring and management capabilities for the Virtual Appliance which can be consumed through either a UI using a web browser or from the appliancesh CLI running within the VCSA Shell.

When talking to customers, they love the fact that the VCSA is harden out of the box and things like SSH are disabled by default. However, one challenge today is that if you need to access the appliancesh interface, SSH still must be enabled or direct console access would be required which is not ideal from an automation as well as from a security standpoint. Although things like SNMP can be configured on the VCSA to help alleviate some of these challenges, it does not solve the problem of having programmatic and remote management access.

VMware Engineering is aware of this request and is working on exposing the VAMI capabilities as an API in a future release of vSphere. In the mean time, not all hope is lost and there is still a solution which does not require you to give up security to be able to operate and manage your VCSA. We can do so by leveraging one of my all time favorite features of the vSphere Platform which is the Guest Operations API which allows you perform guest operations (running commands, transferring files, etc) directly within the guestOS as if you were logged in. Valid guest credentials are still required and once authenticated, the operations are then proxied through VMware Tools. Networking is not even required which makes this a really handy feature for troubleshooting and can even extend into application level provisioning using a single API. I can not stress enough on how cool and underutilized this feature is and it still comes as a surprise when I tell customers that this is actually possible.

Customers can consume the Guest Operations API by consuming it through one of our many supported vSphere SDKs as I have shown here or you can also consume it through PowerCLI using the Invoke-VMSCript cmdlet. To demonstrate the power of the Guest Operations API with the VCSA, I will completely disable all remote access to the VCSA which includes Local Login, Bash Shell and SSH as shown in the screenshot below.

Here is an example of running a simple "echo" command using the vSphere SDK for Perl:

Note: You will notice that there is no output and that is because the standard output must be re-directed to a file and then downloaded back to your client. The PowerCLI's Invoke-VMScript does handle this for you and will return any standand output to the console. For more complex commands, I would recommend creating a script that contains the command and just running the script itself which you can then log locally or into a file.

Here is an example of running the "appliancesh" command using the Invoke-VMScript cmdlet:

Invoke-VMScript -ScriptText "echo 'VMware1!' | appliancesh help pi list
" -vm VCSA-No-SSH -GuestUser root -GuestPassword VMware1!

Here is an example of running the "cmsso-util" command using the Invoke-VMScript cmdlet:

Invoke-VMScript -ScriptText "export VMWARE_VAPI_HOME=/usr/lib/vmware-vapi
export VMWARE_RUN_FIRSTBOOTS=/bin/run-firstboot-scripts
export VMWARE_DATA_DIR=/storage
export VMWARE_INSTALL_PARAMETER=/bin/install-parameter
export VMWARE_LOG_DIR=/var/log
export VMWARE_OPENSSL_BIN=/usr/bin/openssl
export VMWARE_TOMCAT=/opt/vmware/vfabric-tc-server-standard/tomcat-7.0.55.A.RELEASE
export VMWARE_RUNTIME_DATA_DIR=/var
export VMWARE_PYTHON_PATH=/usr/lib/vmware/site-packages
export VMWARE_TMP_DIR=/var/tmp/vmware
export VMWARE_PERFCHARTS_COMPONENT=perfcharts
export VMWARE_PYTHON_MODULES_HOME=/usr/lib/vmware/site-packages/cis
export VMWARE_JAVA_WRAPPER=/bin/heapsize_wrapper.sh
export VMWARE_COMMON_JARS=/usr/lib/vmware/common-jars
export VMWARE_TCROOT=/opt/vmware/vfabric-tc-server-standard
export VMWARE_PYTHON_BIN=/opt/vmware/bin/python
export VMWARE_CLOUDVM_RAM_SIZE=/usr/sbin/cloudvm-ram-size
export VMWARE_VAPI_CFG_DIR=/etc/vmware/vmware-vapi
export VMWARE_CFG_DIR=/etc/vmware
cmsso-util --help
" -vm VCSA-No-SSH -GuestUser root -GuestPassword VMware1!

Note: The reason the additional "export" commands are required is that certain commands may rely on certain environmental variables to be setup. In the case of the cmsso-util command, there are several VMware environmental variables it uses. I decided to just export them all but you can selectively figure out which ones are truly needed.

As you can see from the examples above, I was able to successfully run both shell commands as well as the appliancesh without requiring SSH and even local login! This methods works whether you are connected to vCenter Server or ESXi host from vSphere API perspective.

UPDATE (06/06/19) - Example joining the VCSA to Active Directory using domainjoin-cli

Invoke-VMScript -ScriptText "echo 'VMware1!' | /opt/likewise/bin/domainjoin-cli join vmware.corp administrator
" -vm VCSA -GuestUser root -GuestPassword VMware1!

Using PowerCLI to invoke Guest Operations API to a Nested ESXi VM

07.14.2015 by William Lam // 1 Comment

In my opinion, the Guest Operations API in vSphere is still one of the most powerful Virtual Machine capabilities that is available to vSphere Administrators and anyone else who integrates with the vSphere Platform. The Guest Operations API allows users to perform guest operations (running commands, transferring files, etc) directly within the guestOS as if you were logged in. Valid guest credentials are still required and once authenticated, the operations are then proxied through VMware Tools. Networking is not even required which makes this a handy feature for troubleshooting and can even extend into application level provisioning through a single API.

Obviously, I am a huge fan of this capability and have used it myself on more than one occasion. However, one limitation that I discovered awhile back when using the Guest Operations API with Nested ESXi VMs is that it threw some very strange memory related errors. It was only recently did I find out that there was a known issue with the VMware Tools for Nested ESXi, both the installable VIB and the pre-installed version in ESXi 6.0 on how the guest operations are executed. The good news is that for now, there is a simple workaround that can be applied when using the Guest Operations API.

You will need to add the following option, which runs the command under a specific resource group in the ESXi Shell:

'++group=host/vim/tmp'

Here is an example if I were to run the 'echo' command:

/bin/echo '++group=host/vim/tmp' "hello world"

A more interesting example would be to issue ESXCLI commands using the Guest Operations API, perhaps configuring the welcome message?

/bin/python '++group=host/vim/tmp' '/bin/esxcli.py system welcomemsg set -m "vGhetto Was Here"'

Notice, we need to pass in the resource group command to the "python" binary versus ESXCLI binary. The reason for this is that /bin/esxcli is really just a symlink to /bin/esxcli.py which is just a Python wrapper. The actual command being launched is the python interpreter and the arguments to the command is /bin/esxcli.py and the ESXCLI arguments itself.

For those who prefer to consume the Guest Operations API without having to directly use the vSphere API, you can use PowerCLI and use the Invoke-VMScript cmdlet. The problem with that is due to the way the cmdlet has been abstracted, the necessary underlying API details can not be accessed due to certain assumed defaults which can not be overridden or extended. This is a general problem that I have seen in more than one occasion where the abstraction is to make the consumption of the API simpler but in certain cases, it can also inhibit the use of the underlying API feature.

In this case, we will actually need to call into the vSphere API and using PowerCLI as an example, I have created a script called runGuestOpsInNestedESXiVM.ps1 which implements the specific Guest Operations APIs to issue commands to a Nested ESXi VM.

Here is an example of running the script and configuring the welcome message using ESXCLI:

What is the VMware VIX API and it's future?

11.21.2010 by William Lam // 4 Comments

Some recent twitter conversations about vSphere SDK improvements, specifically around VMware VIX API and few emails around the use cases was the motivation for this post.

I will provide a very high level of what the VMware VIX API is, since there is a awesome presentation by Matt LaMantia at TechExchange in VMworld 2010 SF that goes into more details about VIX (video below). The VIX API (Virtual Infrastructure eXtension) is an API that provides guest management operations inside of a virtual machine that maybe running on VMware vSphere, Fusion, Workstation or Player. These operations are executed on behalf of the vmware-tools service that must be running within the virtual machine and guest credentials are required prior to execution.

The current incarnation of the VIX API is a little odd because it provides guest management operations which is unique to the VIX API but it also provides virtual machine operations. These virtual machine operation overlaps with some of the functionality provided by the vSphere API which is used for managing your vSphere infrastructure. Part of this overlap was due to origins of VIX which started from Workstation on the desktop. I almost consider this VMware API sprawl 🙂

Currently if you want to automate your vSphere infrastructure and want hooks into your virtual machine and guestOSes you need to leverage both the vSphere API and VIX API. I have seen this cause some confusion in the communities. Users wanting to standardize on VIX API and realize that 80% of what they want to do is available in VIX but the portion requires the use of the vSphere APIs. Don't get me wrong, the functionality of VIX is very powerful. When I first learn in version 1.6.2 of VIX where it officially supported vSphere, a whole new set of possibilities just opened up for administrators and developers.

There are several ways of using the VIX API today. If you are using PowerCLI, there are actually a few cmdlets that directly integrate with VIX, which requires you to install the VIX client libraries local to your PowerCLI installation. One such cmdlet is the Invoke-VMScript and here are a few example use cases:

If you don't prefer the dark side 😉 and want to run something like the vSphere SDK for Perl, C or COM, the VIX client libraries also includes client side bindings to these languages. If you are a Java shop and want to leverage Steve Jin's VI Java there is also an open source project called VIX Java Toolkit that can be used. Here is an example use case with vSphere SDK for Perl:

http://www.virtuallyghetto.com/2010/07/automate-update-manager-operations.html

You can also just install the VIX client libraries which also includes a pre-compiled binary called vmrun that provides majority of the VIX operations all bundled into one utility. It also supports VMware vSphere, Workstation, Fusion and Player. Here is an example use case:

http://professionalvmware.com/2008/12/vmware-vix-changing-ips-of-a-guest-vm/

There is also a very interesting application called VGC (Virtual Guest Console) created by the VMware Lab guys also known as flings. This is a graphical interface similar to VMware Remote Console, but it is 1000x better and provides integration to all the VIX operations. The application allows you to view running processes in a guest, kill a particular process, deploy application to a guest, download/upload files and browse guest filesystem and much much more. I would highly recommend taking a look at this tool!

As you can see, the possibilities are endless! but you still have to use two separate APIs. I along with others in the community have asked for a consolidation of the VIX API and merging with the vSphere API, makes the most sense. I think our feedback has finally been heard and if you watch the presentation given by Matt, you will see that future of VIX API is exactly that, consolidatation with the vSphere API. Though we will not see it anytime soon until the next major release of vSphere dubbed vSphere.next (MN) and vSphere.next^2 (OP), it is a change I am looking forward to.

One other interesting thing to point out, during the first release of the VIX API that supported vSphere which was 1.6.2, there was a tiny bug that was identified regarding licensing. As you may or may not know, VMware requires that you have a "paid" license to be able to leverage the various APIs and CLIs for automation, configuration and management of your vSphere infrastructure. This is generally not an issue when dealing with vCenter or ESX, but with ESXi, you have option of a free license.

In the VIX 1.6.2 release, you actually have full VIX read and write operations against an ESXi host using the free license. This was of course fixed in subsequent releases and the trick only works with ESXi 4.0 or older. You will notice on the VIX landing page, there is no mention of the release notes for 1.6.2 release other than 1.7.1 superseding it. You however still can download 1.6.2 release under VIX 1.6 and you can still see the release notes if you search on VMware's site or on Google.

For more details about VIX and downloads, take a look at the following:

PPC15 Guest Operations Using VMware VIX APIs and Beyond:

Guest Operations using VMware VIX APIs and Beyond from heyitspablo on Vimeo.