Exploring the vSphere API with Managed Object Browser

 

 

The Managed Object Browser (MOB) is probably one tool many don’t even know exists or couldn’t be bothered using it. Regardless, it’s a good tool to know about as it provides valuable insight on how everything in vSphere land, well almost everything, is born as an object of sorts with a baggage full of properties and methods. Those of you acquainted with object driven languages like PowerShell or who are well versed with object-oriented programming, surely know what I’m talking about. For the uninitiated, an object is simply a software construct that has state (properties) and behavior (methods).

As an example, let’s take a virtual machine. The most trivial thing you can do with a VM is to power it on and off. Surely enough, all VMs in vSphere exist as objects and come with a property called PowerState which, as you’ve surely guessed, returns the power state of a VM; powered on, powered off or suspended. Other properties hold the VM’s name, the guest OS on it installed, the amount of RAM and number of CPUs allocated and so on and so forth.

To alter the behavior of a vm, we call a method, one of many intrinsic of a VM object. For instance, to power on a VM, a call to method PowerOnVM() is made which does just what the name suggests. All objects are exposed for consumption by the so called vSphere API and here’s where the MOB comes in handy. It allows us to visually explore the object hierarchy complete with methods and properties for each.

The VMware vSphere API reference is a good place to start at, for anyone wanting to learn more about vSphere objects, properties and methods.

UPDATE: Starting with vSphere 6.5, a Restful API is now included which can be explored via https://<vcenter-server-IP-or-FQDN>/apiexplorer.

 

The Managed Object Browser (MOB)

---

The MOB – nothing to do with organized crime and such – is accessible on both vCenter Server and ESXi hosts.

Note: Starting with vSphere 6, the MOB is disabled by default on ESXi, as part of a security hardening initiative. For some reason, it’s been left enabled on vCenter Server which essentially lets you do your thing on ESXi regardless. The reason why ESXi is now shipped with MOB disabled, is that it’s anything but a simple browser. In the wrong hands, it can cause some serious damage. Before diving in to enable it, make sure to weigh the pros and cons and ensure that everyone is on board with the idea. My take on this is to enable it only when required and disable it after use. Here’s how.

If you have vCenter Server installed, launch a browser and navigate to https://<vcenter-server-name-or-ip>/mob. The same link is used to access MOB on ESXi. Figures 1/2 is what you’ll see when accessing the MOB.

 

 

Enabling the MOB on vSphere 6.x

---

ESXi 6.x

As previously mentioned, the MOB is disabled by default in vSphere 6.x. To enable it, carry out the following procedure as you’ll find in the referenced KB article.

Using vSphere Client, log in the ESXi host and navigate to Configuration -> Software -> Advanced Settings. Expand the Config tree, drilling down to HostAgent and finally plugins. Select solo and tick the check-box to enable or disable the MOB.

 

vCenter Server 6.x

Even though MOB is enabled by default on vCenter Server, it still can be disabled and reenabled when required. Here’s how.

Note: The path given below is for vCenter Server 6.0 running on Windows Server 2012. For vCSA, the path is /etc/vmware-vpx/vpxd.cfg. Both paths given, may differ according to the vSphere version used.

• Remote desktop (rdp) to the vCenter Server Windows box
• Using explorer, navigate to C:\ProgramData\VMware\vCenterServer\cfg\vmware-vpx
• Edit the vpxd.cfg file and add the following line under <vpxd> to disable MOB.

<enableDebugBrowse>false</enableDebugBrowse>

To reenable MOB, simply change the value back to true.

• Restart the vCenter Server service.

 

With MOB disabled, the following error message is returned when trying to access it.

503 Service Unavailable (Failed to connect to endpoint: [N7Vmacore4Http20NamedPipeServiceSpecE:0x1f08b8d0] _serverNamespace = /mob _isRedirect = false _pipeName =/var/run/vmware/proxy-mob)

 

Using the MOB

---

After you log in, the topmost object you’ll see listed is called ServiceInstance along with its properties and methods. This is shown in Fig.2 above where a connection is made to a vCenter Server.

To start with, click on the content property and have a look at what’s under the hood.

 

On the next screen (Fig. 6), clicking on the about property returns the build number and version details of the vCenter Server currently connected to.

 

In keeping with the powerstate property example mentioned at the start, let’s drill down the object hierarchy to expose the powerstate property for a virtual machine. In Figure 7, I collated together a series of MOB screens (numerically labelled) as I navigate down the object hierarchy until I hit the required property. If you happen to have an open MOB session, you can replicate the steps as follows;

First, click on Home to go back to the ServiceInstance object screen. Click on content. At this point I should point out that some property values are in fact objects that can be further expanded to reveal other properties. It may be a bit confusing at first but you’ll get used to it especially when you start to use PowerShell and PowerCLI.

1 – Under the Name column, locate rootFolder and click its corresponding value, this being a Data Center Folder object.

2 – Click on the data center object exposed by the childEntity property in the last column. The data center name is displayed as you’d see it listed in a vSphere client.

3 – Locate the vmFolder property and click on its value to expose the virtual machine objects residing under it.

4 – Among other things, you should see a list of VMs listed for the property name childEntity. In Fig. 7, I’ve clicked on vm-405. This value is the so called MoRef ID, a unique object identifier in this case corresponding to a VM called 1GB. You won’t see this value listed in vSphere, this being a use-case example why MOB might be useful.

5 – Next, locate the runtime property. This holds an object as a value of type VirtualMachineRuntimeInfo, which exposes the property powerState which is what I’m after.

6 – Finally, we locate the running state of the VM as recorded by the property powerState value poweredOn. This should match the VM state reported in a vSphere client as per the example given.

 

One benefit derived from using MOB is the thorough view it gives you about an object’s properties and methods. This comes in handy, for instance, when scripting with PowerCLI. If you have PowerCLI installed, open up a console and run the commands listed next.

First, let’s connect to or instantiate the ServerContent object, this being a vCenter Server.

Connect-VIServer -server <vcenter-IP-or-FQDN>

Next, use get-vm to list the virtual machine object corresponding to the VM called 1GB. As is often the case, we store the object as a variable so we can reuse it later.

$vm = get-vm -name 1GB

Next, pipe the $vm variable into the get-member cmdlet. This returns a list of properties and methods associated with the virtual machine object.

$vm | get-member

 

Looking closely at the list of properties in Fig. 8, you can see a property called PowerState. To retrieve its value we simply run;

$vm.PowerState

 

However, the last command is simply a shortcut, nonetheless more than welcome. If we had to do this the MOB-way (steps 4-6), we’d call this property using this instead;

$vm.ExtensionData.runtime.powerstate

 

To MOB or not to MOB …

---

As I mentioned previously, the browser bit in MOB is somewhat of a misnomer since you can freely invoke methods and change configuration settings. While access to the MOB is password protected, bear in mind that this is the only security mechanism protecting you against malicious users who just need an internet browser to access it. Remember to use complex passwords, especially for your root user accounts, and to limit network access to both ESXi hosts and vCenter Server.

In the video below, I go over some of the stuff you can do with the MOB. This includes locating an object’s property, creating folders, powering off a VM and, heck why not, even deleting one. Here it goes.

 

Summary

---

In this post, we learned how the MOB gives you insight about the various objects, properties and methods constituting a vSphere deployment. If you write PowerCLI scripts, you’ll find that the MOB is a handy tool to master especially when you need to uncover new objects. By simply navigating the object hierarchy using any internet browser, you can drill down to the required property and set value if any.

Caution must be exercised when using the MOB, since contrary to belief, it is not a read-only tool. As we’ve seen, it allows you to change settings and run methods. If an attacker manages to compromise your setup, a wipe-out of your infrastructure is a few clicks away which is why, starting with vSphere 6.0, MOB is disabled by default on ESXi.

[the_ad id=”4738″][the_ad id=”4796″]