WilliamLam.com

How to Access vCloud Director Remote Console using vCloud & VMRC API

by // 17 Comments

If you are familiar with the vCloud Director UI and have used the virtual console for a virtual machine, you may have noticed it is serviced by the VMRC (Virtual Machine Remote Console) vCD browser plugin which is only accessible in the vCD UI. If you are building a custom provisioning portal, you may want to provide similar functionality in your own portal for your users to access their VMs.

You can do so by leveraging the vCloud API and the new VMRC API that was made available with the release of vCloud Director 1.5.

In addition to the VMRC API documentation, there is an sample VMRC API Reference Implementation that you can download and experiment with. When you extract the contents of the zip file, you will find an index.html and console.html web page and you can use this locally on your system or host it on a web server.

The index.html is the landing page that you will use to provide the vCloud VM's screen ticket using the vCloud API's AcquireTicket REST API method. The console.html will then load the VMRC for the requested VM assuming you provided a valid screen ticket.

Here are the four simple steps to access a vCloud VM's remote console using the vCloud REST API & VMRC API using curl:

Step 1 - Login

You will need a system that has curl installed and you will need an account in vCD that has access to some powered on VMs. In the example below, I will be logging into a regular organization and not the System organization. There are a few parameters you need to specify to login to vCD and obtain an authorization token. You will need to specify the following parameters and the URL to your vCloud Director instance which should be in the form of https://vcd-fqdn/api/sessions:

  • -i = Include headers
  • -k = Performs an "insecure" SSL connection
  • -H = Setting the header for the version of vCloud Director (1.5 in this example)
  • -u = User credentials in the format of [username@org:password]
  • -X = Request type

Note: For more details on the cURL flags, please refer to the cURL documentation.

curl -i -k -H "Accept:application/*+xml;version=1.5" -u coke-admin@Coke:vmware -X POST https://vcd.primp-industries.com/api/sessions

HTTP/1.1 200 OK
Date: Tue, 28 Feb 2012 22:20:54 GMT
x-vcloud-authorization: n/+ZglmIwJ2SbWlyz04XC5sHUDJqefU1mCMa9TFu9lk=
Set-Cookie: vcloud-token=n/+ZglmIwJ2SbWlyz04XC5sHUDJqefU1mCMa9TFu9lk=; Secure; Path=/
Content-Type: application/vnd.vmware.vcloud.session+xml;version=1.5
Date: Tue, 28 Feb 2012 22:20:55 GMT
Content-Length: 894


<?xml version="1.0" encoding="UTF-8"?>
<Session xmlns="http://www.vmware.com/vcloud/v1.5" user="coke-admin" org="Coke" type="application/vnd.vmware.vcloud.session+xml" href="https://vcd.primp-industries.com/api/session/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://172.30.0.139/api/v1.5/schema/master.xsd">
<Link rel="down" type="application/vnd.vmware.vcloud.orgList+xml" href="https://vcd.primp-industries.com/api/org/"/>
<Link rel="down" type="application/vnd.vmware.admin.vcloud+xml" href="https://vcd.primp-industries.com/api/admin/"/>
<Link rel="down" type="application/vnd.vmware.vcloud.query.queryList+xml" href="https://vcd.primp-industries.com/api/query"/>
<Link rel="entityResolver" type="application/vnd.vmware.vcloud.entity+xml" href="https://vcd.primp-industries.com/api/entity/"/>
</Session>

If you have successfully logged in, you should get an HTTP 200 response and get similar output as above. You will need to make note of your authorization token which is located on the third line that starts with "x-vcloud-authorization". This will be needed throughout the remainder of the session

Step 2 - Query All Powered On VMs

Using the new Query Service API in vCloud 1.5, we will locate all VMs within the vCD instance with the vm type. If you are logged in as a System Administrator and using the System Org, use the adminVM type instead. You can see the command is very similar to the one above but instead of specifying the credentials, we are using the authorization token from step 1. We are also including specific fields in the XML output for readability (VM name + vApp name), if you remove '&fields=name,containerName', you will see the other fields in the XML response. We also want to filter for only powered-on VMs, we can do this by adding '&filter=status==POWERED_ON'.

curl -i -k -H "Accept:application/*+xml;version=1.5" -H "x-vcloud-authorization: n/+ZglmIwJ2SbWlyz04XC5sHUDJqefU1mCMa9TFu9lk=" -X GET "https://vcd.primp-industries.com/api/query?type=vm&filter=status==POWERED_ON&fields=name,containerName"

HTTP/1.1 200 OK
Date: Tue, 28 Feb 2012 22:22:09 GMT
Content-Type: application/*+xml;version=1.5
Date: Tue, 28 Feb 2012 22:22:09 GMT
Content-Length: 1356

<?xml version="1.0" encoding="UTF-8"?>
<QueryResultRecords xmlns="http://www.vmware.com/vcloud/v1.5" total="2" pageSize="25" page="1" name="vm" type="application/vnd.vmware.vcloud.query.records+xml" href="https://vcd.primp-industries.com/api/query?type=vm&page=1&pageSize=25&format=records&filter=status==POWERED_ON&fields=name,containerName" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://172.30.0.139/api/v1.5/schema/master.xsd">
<Link rel="alternate" type="application/vnd.vmware.vcloud.query.references+xml" href="https://vcd.primp-industries.com/api/query?type=vm&page=1&pageSize=25&format=references&filter=status==POWERED_ON&fields=name,containerName"/>
<Link rel="alternate" type="application/vnd.vmware.vcloud.query.idrecords+xml" href="https://vcd.primp-industries.com/api/query?type=vm&page=1&pageSize=25&format=idrecords&filter=status==POWERED_ON&fields=name,containerName"/>
<VMRecord name="WebServerVM" containerName="WebServer-Test-1" href="https://vcd.primp-industries.com/api/vApp/vm-25a4228e-1202-45a7-8f85-cafaeb1c3bc8"/>
<VMRecord name="ApplicationVM" containerName="AppTesting" href="https://vcd.primp-industries.com/api/vApp/vm-fadffc47-fa24-4ca0-9a90-f1048bc9f731"/>
</QueryResultRecords>

If the operation was successful, you should see a HTTP 200 response and list of VMs in your vCD instance. You will need to make a note of the VM's href property that you wish to obtain the remote console screen ticket for which is needed in the next step.

Step 3 - Obtain Screen Ticket for VM

Next we need to obtain the screen ticket using the AcquireTicket vCloud REST API method. You will need to perform a POST operation and using the href property from the previous step, append "/screen/action/acquireTicket". This link is only available IF the VM is powered-on and must be used within 30seconds or it will be considered invalid.

curl -i -k -H "Accept:application/*+xml;version=1.5" -H "x-vcloud-authorization: n/+ZglmIwJ2SbWlyz04XC5sHUDJqefU1mCMa9TFu9lk=" -X POST https://vcd.primp-industries.com/api/vApp/vm-25a4228e-1202-45a7-8f85-cafaeb1c3bc8/screen/action/acquireTicket

HTTP/1.1 200 OK Date: Tue, 28 Feb 2012 22:23:21 GMT Content-Type: application/vnd.vmware.vcloud.screenticket+xml;version=1.5 Date: Tue, 28 Feb 2012 22:23:21 GMT Content-Length: 895 <?xml version="1.0" encoding="UTF-8"?> <ScreenTicket xmlns="http://www.vmware.com/vcloud/v1.5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://172.30.0.139/api/v1.5/schema/master.xsd">mks://172.30.0.140/vm-180?ticket=cst-HtefHNvLNiLmfK1na3mx74rqmLmM%2FjhWu3UHHTFrRlnGZg%2FtgjfqwanE4HUvWgvaclaR5vRI3iJrOvJS4P%2Fq6vH%2FfU06v0kMJ4U1ngSCNnt2SmHpaazWp%2B7JPLMCPQz0f88bxnU3t2NIX3bn%2BrsIznRNaDkQeIEldti%2F7pWsH%2FWm1PGIAk%2Fh54IpBuaGmlwPtNjs40zGTLjSYzRtO9oII75jgWA%2F%2FVcRBXtIPgoQzL4GHpyS6PZ7vaTklxdjCUJklJnlAbpVjo7P5uUqzfhhFQa52GNxZK%2FCLS6nNJpVkmvV12J5aUwsWe3OXdecsckW%2By3VLdcKe9Fp8N44TEgGfqrjzvCsXOv5DbiChjrfhIBKlUhN2%2BHL2fHqbtrBbKvtteNERMl08cqExR7qyf4n1w%3D%3D-X6PBbcMUeRCaF5G6lkqOrrdPbjm%2FfLOj1Exk8w%3D%3D--tp-9B%3A2B%3A82%3A8D%3AA2%3AFD%3AF1%3A8F%3A42%3A20%3ABF%3A75%3AA9%3A4F%3AFA%3AA6%3AC4%3A09%3ACA%3A4F--</ScreenTicket>

Now we just need to take the screen ticket which starts with mks://..... and copy that over to our VMRC sample web page and hit the submit button. If everything was successful, you should see the a remote console popup up for the VM you had just requested the screen ticket from. You will also notice the IP Address in the screen ticket is not the same address as your vCloud Director Cell, it is actually the console proxy address if you were wondering why the IP is different.

So this is great, but you still need some interaction with the browser to actually submit the screen ticket request. What if we just wanted to provide a single URL that would automatically launch the remote console for a requested VM? You can definitely do so, but you will need to perform a URL encoding on the mks://... ticket and construct the proper URL.

Here is a simple shell script called vcloud-vAppRemoteConsole.sh that uses the same vCloud REST API calls as above and allows a user to select the vCloud VM to to retrieve a screen ticket and returns back a single URL to access the remote console of the VM.

The script requires three parameters: (username@organization, password and vcloud-host)

Here is an sample execution:

Once you have successfully logged in, you should see a list of VMs that are currently powered on (highlighted in blue). You will need to select a VM and provide the "href" property as input (highlighted in green). Then the AcquireTicket method will be called and the screen ticket is then encoded using a quick Perl one-liner. The encoded entry is then appended to the hosted URL of the VMRC sample https://air.primp-industries.com/vmrc/console.html? (you can replace the URL to fit your environment). The output of the script (highlighted in orange) is the URL you would then paste into a supported web browser and the remote console will automatically launch without any additional user input.

With the above knowledge, you can easily translate this using any of the vCloud SDKs (Java, .NET, PHP), vCO or the new vCloud Director cmdlets and provide console access to your vCloud VMs.

Note: For vSphere virtual machine remote console access instructions, please take a look at this article here.

Thank You For Voting!

by // 1 Comment

Eric Siebert of vSphere-Land.com just released the annual Top 25 Virtualization Blog results for 2012 this weekend and I am very proud and honored to announce that virtuallyGhetto has moved up from last year's #25 spot to now the #8 spot on the list! It was only a year ago that virtuallyGhetto first made it onto the Top 25 Virtualization Blog after only been around for 4 months. I am very humble to be among some of the smartest and most respected folks in the virtualization community!

New this year, in addition to the top virtualization blog post are the individual categories such as top storage, video, news, etc blogs. Of course scripting was one of the categories and though I did not get number 1, which went to my good friend/colleague Alan Renouf. I did win second place and following third went to Luc Dekens, another awesome scripter/friend in the scripting/automation community.

I wanted to take this time and thank all my readers and supporters from the blog, VMTN forums, twitter and email for voting for virtuallyGhetto! I am very happy to see that the topics/content that interests me also interest others and I really appreciate your support. I hope to continue to put out great and unique content in 2012 and beyond. Thank you again for all your support!

Lastly, I wanted to give shout out to some of the guys who made the top favorite new blogs: Barry Coombs, Josh Atwell, Andrew Mauro to just name a few and Jake Robinson (who did not make it to that list!?). Keep doing what you are doing and never give up, it will all payoff at the end!

Congrats to all the Top 25 virtualization bloggers! 2012 will be be another great year for bloggers!

Automating VMware Tools Upgrade Policy

by // 16 Comments

I received a question this week from a reader who was looking to change the VMware Tools upgrade policy for a few hundred virtual machines and wanted to know if it was possible to automate this. The answer is absolutely yes!

By default the VMware Tools upgrade policy is disabled and set to "manual" mode. If you want the vSphere platform to automatically check and upgrade VMware Tools upon a system power cycle, then you can enable it by going to Edit VM->Options->Tools->Check and upgrade Tools during power cycling.

To update this configuration, there is a property in the vSphere API called toolsUpgradePolicy which can accept two values: manual or upgradeAtPowerCycle.

Here is a vSphere SDK for Perl script updateVMToolsPolicy.pl that supports two types of operations: "list" and "update". The list operation will show you all VMs and their currently configured upgrade policy, by default they should be all manual unless you have changed it manually. The update operation will allow you to configure a list of VMs and policy you designate. This change can be done while the VM is running, you do not need to make any changes to the guestOS that is running.

Here is an example of the "list" operation:

If you want to take all the VMs that have "manual" policy and change them over to "upgradeAtPowerCycle", you can copy the output to a file and then use a find or UNIX/Linux grep command to search for entries that have the word "manual".

Here is the command you can use if you are on a UNIX/Linux system:

cat output | grep "manual" | awk -F '["|"]' '{print $2}'

Here is the command to get the first column which contains the VM display name:

cat output | grep "manual" | awk -F '["|"]' '{print $2}' > VMLIST

Lastly, you just need to take the previous command and redirect that to a file which will then be used in the "update" operation. You can also take the output and using an editor to get to the final output, use whatever you are comfortable with.

Here is an example of the commands listed above:

Now that we have the list of VMs we are interested in updating, we just need to select the policy and perform the "update" command. Here is an example:

So there you have it, you can now easily automate the the VMware Tools upgrade policy for any or all your VMs without having to edit each one manually.