WilliamLam.com

How to generate specific support log bundles for vCenter & ESXi using vSphere API?

07.15.2014 by William Lam // 1 Comment

When an issue arises in your vSphere environment and you engage with VMware GSS, one of the first task you will mostly like be asked to perform is to generate a support log bundle and submit it. You can generate a support bundle using the vSphere Web/C# Client as seen in the screenshot below.

Last week I recieved a question from one of our development teams about generating support log bundles for both vCenter Server and ESXi hosts, but using the vSphere API instead of the UI. This functionality is available as part of the DiagnosticManager and the method you will want to call is GenerateLogBundles_Task() which allows you to specify which systems to collect support logs from. This by far is the easiest way if you just want to collect all logs and I will go into more detail in a bit on what I mean by this.

When invoking the GenerateLogBundles_Task(), support logs will be generated on each of the respective sub-systems which includes vCenter Server and the ESXi hosts. Once the log bundles have been created, the API will return a list of download URLs to the support log bundles. To demonstrate this functionality, I have created a sample vSphere SDK for Perl script called generateLogBundle.pl

The script assumes you want to collect ALL logs for both vCenter Server and ESXi hosts being managed by the given vCenter Server.

While working on the sample code, one thing I had noticed in the vSphere Web/C# Client is that you have the ability to select the specific logs to export.

I was looking through the vSphere API but I did not find a way to specify this level of granularity in the logs. I was of course curious and wondered if this was using some sort of private vSphere API (which I hoped was not the case). I decided to pull out one of my favorite tools when I get stuck with a question around the vSphere API which is Onyx. After manually generating the support log bundle and selecting a subset of the logs to export, I found out this process actually makes a call to a CGI script on the ESXi host called vm-support.cgi.

The list of available logs to export is generated by making a GET request to the following URL: https://[ESXI-HOSTNAME]/cgi-bin/vm-support.cgi?listmanifests=1

The output is an XML file that contains the manifest of the available logs to export in the log support bundle. To specify the specific logs to collect, you must provide the "id" property as seen in the screenshot above. In this example, I would like to collect the following: System:Base, VirtualMachines:GuestState, Storage:VSAN and VirtualMachines:diskinfo

To generate a support bundle from the ESXi host that contains the above, you will need to issue a GET request using the following URL: https://[ESXI-HOSTNAME]/cgi-bin/vm-support.cgi?manifests=System:Base VirtualMachines:GuestState Storage:VSAN VirtualMachines:diskinfo

This will instruct the ESXi host to generate the log bundle that contains the following manifest log files. To include others, you just need to append to the URL. You can easily test this out by pasting this URL into a web browser and providing your ESXi credentials and the logs will be available for download. Going back to my original observation, this is actually how vCenter Server provides the ability to export specific logs from each of the ESXi hosts when generating a support bundle.

If you would like to use the vSphere API to provide this same capability, you just need to leverage the AcquireGenericServiceTicket() API method which is available as part of the SessionManager and specify the URL for the support bundle. This will allow you to request a support log bundle from within vCenter Server without having to go directly to each of the ESXi hosts manually. You can see a very similar implementation of this API by taking a look at my How to efficiently transfer files to a datastore in vCenter using the vSphere API and specifically the efficent-upload-files-to-datastore.pl sample code.

Quick Tip - How to BSOD/Panic a Virtual Machine in ESXi?

07.14.2014 by William Lam // Leave a Comment

https://twitter.com/virtualdominic/status/488570929383890945

While catching up on my Twitter feed this morning, I saw an interesting question from Dominic Rivera. I remember a few years back I was troubleshooting an issue and required to panic a Virtual Machine, I did not recall the steps that GSS had walked me through but I figure if anyone would know, it would be my buddy Paudie who used to work in GSS. Sure enough, he had the answer which was using a nifty little tool on the ESXi Shell called vmdumper.

UPDATE: It turns out there is an even simpler thanks to Frank Buechsel who is also from GSS. Frank mentioned you can send an NMI request simply using either the vSphere Web/C# Client. In the vSphere Web Client, you just need to right click on the VM and go to All vCenter Actions->Export Systems Logs. To be able to perform this action, you will need the Global->Diagnostic privilege for the the given user.

Next, expand the menu and select Send_NMI_To_Guest option.

If you wish to perform this operation using the vSphere C# Client, you just need to select the VM and then at the top menu and click File->Export System Logs and you will have the option of sending the NMI request this way.

Using the vmdumper utility, you can create a BSOD (Blue Screen of Death) for a Windows or Kernel Panic for Linux Virtual Machines by sending an NMI (Non-Maskable Interrupt) request.

To send an NMI or any other request, you need to first identify the VM's World ID, this can be done using either ESXCLI or vmdumper utility itself.
Using ESXCLI:

esxcli vm process list | grep -A1 '^[VMNAME]'

Using vmdumper:

vmdumper -l | grep [VMNAME]

In the example above, I have a VM called vcenter55-2 running Windows 2008 R2 and the World ID is 23100118. To send the NMI request, you will now run the following command:

vmdumper [WORLD-ID] nmi

If we now take a look at the VM Console, we will see that it successfully BSOD the Windows VM:

Here is a screenshot for sending an NMI request to a Linux VM. It seems the Linux system handles the NMI in a much more graceful manner and the system was still responsive 🙂

After learning about the vmdumper utility, I also performed a quick search online and found VMware KB 2005715 that provides some additional information. It looks like the KB only references ESXCLI as a way to locate the World ID, I will see if we can get the KB updated to also include vmdumper method of identifying the VM's World ID.

Does reinstalling ESXi with an existing VSAN Datastore wipe your data?

07.11.2014 by William Lam // 16 Comments

The quick answer is no, reinstalling ESXi on a host that contained VSAN data will not be touched or destroyed. This, of course, assumes you do not touch any of the disks that contains your VSAN data. To further assist administrators, you can also see which disks are claimed by VSAN during the the disk selection of a reinstall/upgrade of ESXi, so the proper disk is selected.

This to me is a very important fact and probably a very conscious design decision by the VSAN Engineers to ensure that you do not accidentally wipe your data because ESXi needed to be reinstalled. The topic has been one I have been wanting to write about for awhile but just never found the time. The reason I am bringing this up is that I saw an interesting tweet the other day from fellow VMware colleague, Geordy Korte who works over in the NSBU that had the following request:

NEED HELP: Anyone have any clue on how to recreate a #VSAN using esxcli and not wiping the data. My Vcenter is on the VSAN. RT PLZ

— Geordy Korte (@gekort) July 2, 2014

Geordy needed to reinstall ESXi but he did not want to lose any of the VSAN data residing on the disks within the ESXi host which also contained his vCenter Server among other Virtual Machines. Fortunately, reinstalling ESXi is a very safe operation and it will not touch any of the VSAN partitions. In fact, after the installation, if ESXi detects there are partitions that contains VSAN data, it will automatically claim the devices for you. You may have even seen this as part of the ESXi boot process:

Going back to Geordy's original question, how do you re-create the VSAN Datastore after reinstalling ESXi? Well, the process is actually pretty straight forward and is quite similar to how you bootstrap vCenter Server onto a VSAN Datastore. To demonstrate this process, I decided to take a fully functional 3-Node VSAN setup that contained a Virtual Machine and reinstall ESXi on all three nodes. I will now take you through the process of restoring the VSAN Datastore and at the end I will also talk about an alternative approach depending on the situation you might be in.

Step 1 - You can easily check whether you have an existing VSAN Disk Group by running the following ESXCLI command:

esxcli vsan storage list

Step 2 - You will need to enable VSAN traffic type for the VMkernel interface you wish to run VSAN on by running the following command and specifying the interface (this will need to be done on ALL ESXi hosts):

esxcli vsan network ipv4 add -i vmk0

Step 3 - You will need to re-create a new VSAN Cluster and you can do so by running the following command which will generate a UUID and create a VSAN Cluster from that:

esxcli vsan cluster join -u $(python -c 'import uuid; print(str(uuid.uuid4()))')

Step 4 - Once the VSAN Cluster has been created, you will need to make a note of the UUID that was generated so you can join the remaining ESXi hosts to the same VSAN Cluster. To do so, you will need to run the following command:

esxcli vsan cluster get

You will need to look for "Sub-Cluster UUID" property as seen in the screenshot above highlighted in green.

Step 5 - On the remainder ESXi hosts, you can now join the the VSAN Cluster using the following command and specifying the UUID from the previous step:

esxcli vsan cluster join -u [UUID]

Step 6 - Once all ESXi hosts have re-joined the VSAN Cluster, you can now go into the VSAN Datastore and re-register all the Virtual Machines using either the vSphere C# Client or from the CLI on the ESXI Shell.

As you can see from the screenshot above, I was able to recover my Virtual Machine and there was no data loss!

If you recall earlier, I also mentioned there was an alternative approach that you could take depending on the situation. If you need to deploy a new vCenter Server for what ever reason, you can easily restore your existing VSAN Cluster by simply creating a new VSAN Cluster in the new vCenter Server. You would then add each ESXi hosts to the VSAN Cluster and the VSAN Datastore and its contents will automatically be restored without any issues. Once you have your VSAN Datastore, you can then re-create the missing VM Storage Policies and re-apply them to the respective Virtual Machines.

In this article I have described two potential scenarios when working with VSAN and in both cases you can safely recover your data without any problems. This is one of the things I have come to appreciate about VSAN is the amount of engineering effort to make it super simple to use but also very resilient!