Over the holiday break I was cleaning out some of my old notes and I came across the subject of capturing virtual machine screenshots in vSphere. This topic comes up from time to time when talking to customers and the methods to accomplish this task may not always be clear. Capturing screenshots of a virtual machine is a capability provided by the vSphere platform and it is actually leveraged by several VMware features and products such as:
vSphere HA – A screenshot is taken of the virtual machine console during a restart
vCloud Director – Screenshots are periodically taken for thumbnails displayed in the vCD UI
vCloud Connector – Screenshots are periodically taken for thumbnails displayed in the vCC UI
Customers and partners may also be interesting in leveraging this feature for their own custom portals or solutions and there is more than one way to accomplish this task.
Though this topic has been briefly discussed before in the past by Steve Jin in this article, I think it is still a worthwhile topic to re-visit as the solution is still not very well known. There are two methods for capturing a virtual machine screenshot within vSphere without having to rely on traditional screen capture utilities:
Using the vSphere API
Using an HTTP Handler in vSphere
Option 1:
The first option is using the CreateScreenshot_Task vSphere API method for a virtual machine. This will capture a screenshot of a running virtual machine and store the PNG file in the datastore of the virtual machines working directory and the path to the download can be retrieved from the task object. The file name will contain the display name of the virtual machine along with an numeric value which is incremented for each additional snapshot (e.g. MyVM-screenshot-0.png). You can use call this API method connecting to either a vCenter Server or directly to an ESXi host, but to download the screenshot, you must connect directly to the ESXi host.
To retrieve the screenshot you will need to connect to an ESXi host with access to the specific datastore and download the file using a simple HTTP GET on the datastore URL of the filename. I wrote an example vSphere SDK for Perl script awhile back called takeVMScreenshots.pl which demonstrates this by simply specifying the name of a virtual machine. Ensure the user has “VirtualMachine.Interact.CreateScreenshot” privilege as noted in the API reference guide.
Note: Each time the method is called, a new screenshot is taken and stored in the virtual machine’s working directory. Remember to either delete or periodically clean up these files else you could consume unnecessary amount of storage for these screenshots.
Option 2:
The second option is to use a lesser known method via an HTTP handler that has been around since the vSphere 2.5 API. This method allows you to quickly generate and retrieve a virtual machine screenshot by specifying a URL containing the virtual machine’s MoRef ID (Managed Object Reference). There is a slight mention of this method in the Host Capability properties called scaledScreenshotSupported and screenshotSupported. The way this works is you generate a URL that contains either the vCenter Server or ESXi hostname or IP Address and apend /screen?id=X where X is the MoRef ID of the virtual machine. Here is an example URL:
https://10.24.145.65/screen?id=vm-162
To quickly demonstrate how this works, you can paste the URL into a web browser and after you authenticate, you will see screenshot that has been taken for your virtual machine. Ensure the user has “VirtualMachine.Interact.ConsoleInteract“privilege as noted in the API reference guide. In addition, there are a few other parameters that you can specify as part of the screenshot request:
w = the pixel width of the scaled image h = the pixel height of the scaled image x0 = the left side of the bounding box to select the image y0 = the top side of the bounding box to select the image x1 = the right side of the bounding box to select the image y1 = the bottom of the bounding box to select the image
Here is an example screenshot for a virtual machine screenshot requested with 800×600 setting (https://10.24.145.65/screen?id=vm-162&h=600&w=800):
Here is an example screenshot of the same virtual machine but requesting the additional parameters within the screenshot request (https://10.24.145.65/screen?id=vm-162&h=600&w=800&x0=200&y0=75&x1=480&y1=200):
The really nice thing about option #2 is you can easily generate and retrieve a virtual machine screenshot all in one step without having to directly go to the ESXi host to download the screenshot. The other nice thing is you can perform this operation by connecting to either a vCenter Server or directly to an ESXi host, this can be very useful when everything is centrally managed by vCenter Server.
Get notification of new blog postings and more by following lamw on Twitter: @lamw
Here is an example screenshot of the same virtual machine but requesting the additional parameters within the screenshot request (https://10.24.145.65/screen?id=vm-162&h=600&w=800&x0=200&y0=75&x1=480&y1=200):
The really nice thing about option #2 is you can easily generate and retrieve a virtual machine screenshot all in one step without having to directly go to the ESXi host to download the screenshot. The other nice thing is you can perform this operation by connecting to either a vCenter Server or directly to an ESXi host, this can be very useful when everything is centrally managed by vCenter Server.
