Reconfiguring vmreconfig

The Perl script, vmreconfig.pl, is designed to reconfigure a virtual machine (VM). You can read more about it here. The tool can be used to make changes to the state of the VM. For example, you want to turn off a VM’s guest network interface card (NIC). You would use the command vmreconfig.pl in conjunction with an XML file that contains the necessary options to turn off the NIC.

The command might look like:

vmreconfig.pl –username akutz –password mypassword –server vcms.lostcreations.local –filename vmgnicoff.xml


And the XML file might look like:

<?xml version="1.0"?>
<Reconfigure-Virtual-Machine>
  <Name>purple.lostcreations.local</Name>
  <Host>morning.lostcreations.local</Host>
  <Disconnect-Device>
        <Network-Adapter>
          <Name>VM Network</Name>
        </Network-Adapter>
  </Disconnect-Device>
  <PowerOn-Flag>
        <Network-Adapter>
          <Name>VM Network</Name>
          <PowerOn>False</PowerOn>
        </Network-Adapter>
  </PowerOn-Flag>
</Reconfigure-Virtual-Machine>

This is where the trouble begins. The are a few problems with vmreconfig.pl (and I suspect with the other VI Perl tools as well; I will be documenting their issues as I use them):

- Poor error messages
- Schema is poorly designed
- Incomplete Perl modules
- Documentation is misleading

Poor Error Messages

When you execute the above command here is the error you will receive


Error in ‘vmgnicoff.xml’:
Element ‘Reconfigure-Virtual-Machine’ [CT local]: The element content is not valid.


This doesn’t really tell us all that much, does it? This is common with the VI Perl scripts. After some digging we are able to figure out that this problem has something to do with the XML schema file.

Poorly Designed Schema

The vmreconfig.xsd XML schema document (XSD) file included with the VI Perl Toolkit is poorly designed. It requires that every element be present in the file even when not in use. If you were to open the XML file in an XML editor and link the provided schema file you get a warning that the “AddDevice” node is not present? Well, we are not trying to add a device, so why should we need it? It turns out that the schema file does not implement the “minOccurs” attribute on its node definitions (even though the Perl script can cope with the absence of these elements). The solution is to go through the schema file and add a “minOccurs=’0′” attribute to the appropriate locations. You can download a copy of the schema I’ve already marked up for this purpose here.

Now you can use the simpler, easier-to-read XML that is printed above.

Incomplete Perl Modules

However, the next time you run the command you will possibly receive yet another error:


Can’t locate object method “new” via package “XML::LibXML::XPathContext” (perhaps you forgot to load “XML::LibXML::XPathContext”?)


This error occurs because some OSs do not have the XPathContext Perl module installed by default. To install this module from CPAN simply type:


sudo cpan XML::LibXML::XPathContext


That solves that problem.

Misleading Documentation

The last issue you can run into is the VMware documentation itself. The online documentation for vmreconfig.pl clearly implies that the name that should be used with a network adapter is the name of the network it is associated with. The documentation uses the example “VM Network”. This is the default name of a port group created for use by VMs in ESX. In fact, if you use this name when attempting to make changes to a network device you will receive this message:


No reconfiguration performed as there is no device config spec created.


You must specify the name of the network adapter, not the network it belongs to.

In Summary

To make vmreconfig.pl turn off and disconnect a VMs network adapter download my updated vmreconfig.xsd schema file and use the following XML:

<?xml version="1.0"?>
<Reconfigure-Virtual-Machine>
  <Name>purple.lostcreations.local</Name>
  <Host>morning.lostcreations.local</Host>
  <Disconnect-Device>
        <Network-Adapter>
          <Name>Network Adapter 1</Name>
        </Network-Adapter>
  </Disconnect-Device>
  <PowerOn-Flag>
        <Network-Adapter>
          <Name>Network Adapter 1</Name>
          <PowerOn>False</PowerOn>
        </Network-Adapter>
  </PowerOn-Flag>
</Reconfigure-Virtual-Machine>

Hope this helps!