Similar to my vCloud Director article, you can also provide access to the remote console of a virtual machine in a vSphere environment to your end users. This can be accomplished by leveraging both the vSphere and VMRC (Virtual Machine Remote Console) APIs and can be useful if you are building a custom portal for users to access their virtual machines. To use the VMRC API, you can download the latest VMRC 5.1 SDK which provides the following:

The VMRC SDK allows you to use a Web-based application to connect to a vCenter- or vCloud Director-managed virtual machine and access that virtual machine’s console in a browser window. You can interact with the virtual machine console input and screen. You can also use the VMRC SDK to manage virtual and physical device connections on a vCenter-managed virtual machine. 

The VMRC SDK includes documentation to the API as well as a sample webpage implementing some basic functionality of the VMRC API. I recently received a question on how to get started with the sample as it was not completely intuitive and thought I take you through the required steps to get the sample working.

Step 1 - Download the VMRC 5.1 SDK and extract the contents to your local desktop.

Step 2 - Open the vmrc-embed-example.html using a web browser located in the docs folder.

Note: In my example, I uploaded both the javascript and html file to a web server and accessed the sample by connecting to the server instead of running it locally on my desktop. This was to show how users could access the custom portal using the VMRC SDK.

Step 3 - At the top of the page where it says "VMRC Modes", make "MKS" is selected in the drop down box and click on the "+" icon to add. Then go ahead and click on the "Start" button to start a VMRC instance and ensure you see a success message on the right hand side of the console box.

Step 4 - To authenticate to VMRC, you will need a session ticket which will be obtained through the use of the vSphere API using the acquireCloneTicket() method provided by the SessionManager managed object. In this example, we will be using the vSphere MOB to quickly retrieve our session ticket, but in a real implementation, you would programamtically retrieve the session ticket along with few othe pieces of information to connect to the VMRC. Open up a new tab in your web browser and connect to the following URL:

https://reflex.primp-industries.com/mob/?moid=SessionManager&method=acquireCloneTicket

Note: Make sure you substitute in your vCenter Server IP Address/Hostname

Once you have authenticated, go ahead and click on the "Invoke Method" which should generate a session ticket:

Step 5 - Copy the session ticket string and go back to our VMRC sample page. We will now need to fill out the following sections before we can access the remote console of a virtual machine:

  • Hostname (IP Address/Hostname of your vCenter Server)
  • Allow SSL Validation Errors (Check this if you are using self signed SSL certificates)
  • Ticket (Paste the session ticket from the previous step here)
  • VM ID (This is the MoRef ID of the VM you wish to connect to the remote console)

Once you have filled out the minimum required fields, go ahead and click on the "Connect" button and if everything was successful, you should now see the remote console of the virtual machine you selected.

28 thoughts on “How to Access vSphere Remote Console Using vSphere & VMRC API

  1. William,

    Thanks for the inspiration and tools. Since you released the Perl ticket generator last year, and since the release of the VMRC SDK, I have been planning on putting it all together to make to make a web-based control center for limited access to do: snapshots, power-on, power-off, and console. Essentially, a limited set of tools that a person would need without having to open up vCenter.

    • np! I’m glad you’ve found the tools and articles to be useful. Perhaps when you’ve put everything together, you won’t mind sharing what you’ve built and maybe some lessons learn/tips for others that might be interesting in providing a similar solution. Thanks again for the comments

  2. great info William.
    And devides sharing working :)
    I want write proxy for console, becouse my vCenter is hidden behind a NAT.
    Did You try write console proxy like in vCloud Director?
    Or try use haproxy for this.

  3. Hi Willam,

    Is this tool able to show me a list of thin clients that are in use? We wat to create a connector to the server to look for clients that are available and show them on a screen.

    Willem Luijk

  4. @VMBLOG.pl

    Creating a proxy is not that difficult.

    1. Add your ESXi hosts, and vCenter, to your public DNS (split DNS). Meaning your external DNS would have publics IPs while internal DNS would have your private network IPs.
    2. Create a VM (or physical machine) with 2 NICs. One NIC to your backend network to access ESXi hosts and One NIC to public IPs used for ESXi and vCenter. vCenter and each ESXi host need a public IP and that public IP is on the proxy host and also what is entered into DNS. A request is made to the public IP and forwarded to the backend ESX host. So when you open a console and vCenter is telling vSphere Client to go to esx02.backend.network.yourdomain.com, external DNS knows that this is actually PU.B.L.IC IP and not 10.10.10.x

    3. Port forward each public IP to the proper backend private IP and port.

    I have this working with no issues.

    You can also do this with MIPs on a firewall, but I find it easier to generate tickets for customer use on an actual server. Ticket is requested, firewall ports are opened for 1 hour, and then the customer’s IP is removed without have to edit the configs on a hardware firewall.

    I’ll trade you a working console proxy for working PHP code that does a soap call for a ticket and generates the console window :)

  5. Hi William,
    I followed all steps as mentioned and I got the following success message on connect()

    onConnectionStateChange - connectionState: 2, host: xx.xxx.xx.xxx, datacenter: , vmId: vm-179, userRequested: true, reason: Connection successful.

    But couldn’t see the console, it was blank as before. what can be the reason? Also I tried to send other ‘SetFullscreen’ etc option from page and it throws following error
    setScreenSize call failed: undefined
    setFullscreen call failed: undefined
    sendCAD call failed: undefined

    I appreciate your help!
    Thanks

  6. Hey Vick886, i had the exact same problem. for me it was because i didnt hit the plus sign next to “MKS”.

  7. Hi“ I am currently having issues. I followed the exact same steps mentioned in this post and I am getting the following error:
    starting VMRC instance: modes: 2, messages: 1
    “startup returned “vmrc-ax-t-{9E36E306-0DC9-4D21-983E-AE1962CE249B}”
    connect succeeded
    onConnectionStateChange - connectionState: 1, host: vc51.democentral.ibm.com, datacenter: , vmId: vm-744, userRequested: true, reason: Cannot complete login due to an incorrect user name or password.”

    My current environment is:
    vCenter Server 5.1 (Windows R2 2008)
    VMRC 5.1 (Windows 7 Professional SP1 , also tried with XP)
    Internet Explorer 9
    vmrc-embed-example.html (example code provided by default)

  8. William, just saw your comment at the Forum.. So funny!!! Hey.. btw, it is an honor to get your help.
    You know“ I am such a rookie“ I was requesting the ticket as a user a created which is administrator of the system and vmware and was getting the previous errors. I requested the ticket again with the installation user and now connection was successful. Is it because of Single Sign On ??
    So“ is this the only way to establish a connection ? Because I tried connecting using the same user but I still get the SSL error.

    • Marco,

      No problem, glad you got it working. Your issue is not related to SSO, remember SSO is just a authentication broker. The actual permission validation is done on the vCenter Server itself and will highly depend on the privileges assigned to the user you’re using.

      If you take a look at the vSphere API Reference guide, you will see the required privileges for the method which is System.View, so make sure the user has that and it should work regardless of whether the account was used to install the OS or manage the virtual infrastructure

  9. Hi William,

    followed all the steps mentioned in your blog, not able to the get connection,

    starting VMRC instance: modes: 2, messages: 1
    startup returned “vmrc-ax-t-{7A162615-E8CA-4641-865C-7C2308B14F69}”
    connect succeeded
    onConnectionStateChange - connectionState: 1, host: xxxxxxxx:902, datacenter: , vmId: 42144feb-b91e-1ed0-c7b6-1ebc8b2492b5, userRequested: true, reason: A secure connection to the server could not be established

  10. Hi, I was wondering if someone could post some PHP code to get the AcquireCloneTicket dynamically.
    Thanks,
    George

  11. Hey chaps, great little tool William. I’m wondering, does this work against ESXi 5 or do you have to run it against vCenter?

    Thanks

  12. Hi, thanks for your greate article! I have connected to VM through mks with the vCenter ticket successfully.

    However, I don’t want to use a key that has accesses to all the VMs, and currently I’m using vCloud web console. So I’m wondering, how to use the api with vCD 5.1?

    There’s a note in the api document:

    NOTE When using VMRC with vCloud Director 5.1, only the host, ticket, and vmid parameters are
    supported when calling connect(). You must pass false for the allowSSLErrors parameter, and empty
    strings (““) for all other parameters in connect().
    The following is an example of how to call connect() when using VMRC with vCloud Director 5.1.
    connect(hostname, ““, false, ticket, ““, ““, vmid, ““, ““);

    But when I tried this way, I never got a success. I got the ticket through vCD api, below is an example:
    mks://xx.xx.xx.xx/vm-xxxxx?ticket=cst-JBQz57dOcsxDma%2Fo68GTgAXukQxoDMvAZen%2BlbUyV2ThJfdE9Wu41obtqfp3u2bx7g49zRAjsvIHHsQT%2FqX3ltHMBjchjOhD1fcwrD5h1dnyqc2XnyHOhblUwqjISo5oUosEyhWbiTpwzCHJr4LVoIfsyaYfesSozXMYvXLvUk8aPatjqDR1PAxosHTHF1Jgpc4B%2FPLpaPincE1KlGfETGstToBKac%2FpeA1vzakKz8jP8xMJLbStPicEeAp%2FGRr3Wo9bY5IuS5y53uhJ94u2rHXR%2B2Y9m%2FZTBk2eMFJOYlU2nyI4yYDPrWzVTj4H0qTZYVs7pe3Z6auFA4ohYHtb%2Fiz8rVJVKJWcbRG5l7hHleylHNt5RU%2BBHHVOPhd2TPTRh5cdusIfenTWjIPirQAYrkOIuKeXBHB7Nhe1Egp7eJSxUf88o03gmYWny5STG94N-sW1Hx5pO22nUviNC0UdAkCxtYMbrt1Q9OraL9g%3D%3D--tp-CF%3AC6%3A83%3AAC%3A5B%3AB8%3A40%3A5B%3A46%3A21%3A1F%3A8C%3AD3%3AAD%3A26%3A93%3AEB%3A63%3A06%3AB1--

    I have split it into “hostname” “vmid” and “ticket”, and used diffente methods to decode the ticket. And if I call
    connect(hostname, ““, false, ticket, ““, ““, vmid, ““, ““) I would get a security error, and if
    connect(hostname, ““, true, ticket, ““, ““, vmid, ““, ““) then a username/password error.

    Do you have any idea? Thanks in advance.

  13. I have just started playing with this tool. So far it seems like it will do what we want it to. We are trying to create a portal so that end users can connect remotely to guests running in isolated port groups. I had a question on setting up an id that we will use to access the acquireCloneTicket() method.

    What permissions does the id we will create need for this to work. I need to be able to get a ticket and also view the entire inventory of guests within a particular vCenter.

  14. Hello, Thanks for the article.

    Unfortunately I can’t seem to get the VMware Remote Console API Example to work. I’m trying to access the console of a VM off of a ESXi 5.1 under
    a VC 5.1.

    I’ve retrieved the ticket as an administrator and I’m supplying the following arguments:
    VC IP address
    Allow SSL Validation Errors checked
    Ticket
    VM ID:

    and I get the following error:
    onConnectionStateChange - connectionState: 1, host: 10.207.66.95, datacenter: , vmId: vm-270,
    userRequested: true, reason: Cannot complete login due to an incorrect user name or password.

    Any idea what I’m doing wrong here? Is there a problem with ESXi 5.1?

    Thanks,
    Abe

    • Please disregard previous post. It appears that it works after I grabbed the ticket the second time, pasted and connected. I assume there is probably a short lifetime assigned to the ticket.

      Thanks again for the great article.

      Regards,
      Abe

  15. Instead of AcquireCloneTicket() on the SessionManager Object, can the AcquireTicket() Method on the VirtualMachine work with vmrc as well? I see this as being more secure, because once the Ticket from the SessionManager is acquired, any VM can be accessed in vcenter.

  16. Hi,

    Can we use VMRC for launching the Esxi Host console also ? or is it only available for VM Console ?

    thanks

  17. Hi,

    Could anyone possibly help me on this one? Just for the record, I am not an IT newbie.

    The problem is when I open the virtual console in vsphere 5.1 client.

    At login, it accepts keyboard input for the username, no problem there.
    When I hit Return on my keyboard, it prompts for the password. Still within the console, I attempt to type out the password. Nada, zip, nothing happens. No keyboard output appears to display the password.

    Unless I hit Enter or Shift-Enter. Then I can enter the password and it appears on screen. But then I get “Incorrect login”. I know this is NOT true as I have the exact login details beside me. Why is this error coming up, has anyone had this same experience with failure to successfully enter the correct password within the console window?

    Any help could really be appreciated.

    Thanks,

    N.

  18. Hello William,

    I am trying to generate session ticket using perl SDK script. But I am getting error “Cannot complete login due to an incorrect user name or password”. I would be most appreciative if you can tell me why ticket generated with this scrip cannot be used with vmrc.

    here is my script:
    #!/usr/bin/perl
    $ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0;
    use strict;
    use warnings;
    use VMware::VIRuntime;
    use VMware::VILib;

    my $type = ‘vm’;
    my $name = ‘testvm’;
    my $url = ‘https://VCserver/sdk/webServer’;
    my $username =’user1′;
    my $password =’User@123′;

    Vim::login(service_url => $url, user_name => $username, password => $password);
    my $entity = Vim::find_entity_view(view_type => ‘VirtualMachine’, filter => {“name” => $name}, properties => ['name']);
    my $sessionMgr = Vim::get_view(mo_ref => Vim::get_service_content()->sessionManager);
    my $session = $sessionMgr->AcquireCloneTicket();
    print “Session ID: \t $session \n”;

    print “EntityName: ” . $entity->{‘name’} . “\t MoRefID: ” . $entity->{‘mo_ref’}->value . “\n\n”;
    Vim::logout();

Thanks for the comment!