Home > Software Development, vSphere API > Announcing Guest Operating System Management API for vSphere

Announcing Guest Operating System Management API for vSphere

Having created a sample to run a program in guest operating system using GuestProgramManager, I started to write a similar one to show how to use the GuestFileManager. Compared with the GuestProgramManager, the GuestFileManager is much more complicated to use.

So I decided to take time to develop a high-level guest management API on top of the existing VI Java API. Besides the existing features offered by the vSphere API itself, I also added new features like uploading and downloading a whole directory (vSphere API itself only supports uploading and downloading a single file), uploading and downloading file to and from Java stream. The stream support is very important for an API, not much so for a command line tool.

Time to learn how to "Google" and manage your VMware and clouds in a fast and secure


The core of the guest opermanagement API for vSphere is two classes: GuestProgramDirector and GuestFileDirector, which corresponds to the GuestProgramManager and GuestFileManager. The names are consistent with the fact that a director is high level to a manager. :-)

The usage of the APIs is straight-forward. The methods, especially those in the GuestFileDirector, are pretty similar to what you do with conventional command lines. For example, the downloadFile method has the following signature. I think you can guess out how to use this method easily.

public void downloadFile(String filePathInGuest, String filePathLocal) throws IOException

I will explain more about each of the types with samples in future blogs. Here is the API for you to download.

Update: sample 1: run, kill, and list programs in guest operating system.

  1. Santhosh
    April 12th, 2012 at 06:45 | #1


    i have downloaded the API and copied your code to run, kill process.

    Its throwing a null pointer exception at line 30 of the GuestProcessDirector.java.

    What would be the error?

    I am new to Java. Please deal with this solution.

    GuestProcessDirector progDir = new GuestProcessDirector(vm, “Administrator”, “vijava”);

    The VM object , user name and password are valid here.

  2. Santhosh
    April 13th, 2012 at 04:52 | #2

    My vmware tools version is 8.3.2, build 257589….Should i upgrade?

  3. April 13th, 2012 at 15:25 | #3

    It should be newer. In my case, the version is 8.6.0 build 425873.

  4. Santhosh
    April 17th, 2012 at 02:52 | #4

    Can you share your ESX details? Can you please specify the minimum requirements ?

  5. Santhosh
    April 17th, 2012 at 14:48 | #5

    my ESX is 4.0

  6. Tyron
    October 17th, 2012 at 10:23 | #6

    Is there any particular reason why this API is not part of the VI Java API? Using the link provided here I am downloading five .class java files and was wondering whether there exists such files packaged in a jar. Thanks

  7. October 24th, 2012 at 17:56 | #7

    This is awesome. Can you put this in maven central?

  8. Mark Norman
    August 22nd, 2013 at 09:36 | #8

    can I get the source? I need to step through it to figure out a problem. thanks.

  9. ptpt52
    April 23rd, 2014 at 21:11 | #9

    Hi, I was trying to download files from the guest using the vSphere API from vmware.com
    I try the sample code to run but failed
    the code is from VMware-vSphere-SDK-5.1.0-774886.zip
    where samples/com/vmware/guest/DownloadGuestFile.java

    my guest os has installed the vmware-tools, but I notice that the sample code run just hung at waitting for guest.guestOperationsReady to be true
    but it is not,
    why the guest.guestOperationsReady is false? how shuold I configure my vcenter?
    the EXSi server is version 4.1
    and the vcenter is 5.x

    any help?

  10. April 23rd, 2014 at 22:55 | #10

    The guest operation from vSphere API was added in 5.0. If you are using ESXi 4.1, it’s not supported. Try it out with 5.x ESXi.

    Good luck!


  11. Simon
    July 7th, 2014 at 14:28 | #11

    Hi, I’m having problems when I try to run this sample, I’m working in eclipse, I included the .class files in my project and imported with no problem, however when I try to run it, I get this error: java.lang.NoClassDefFoundError: org/doublecloud/vi/vmware/guest/GuestProcessDirector

    I have no errors up until I run it, then the line:
    GuestProcessDirector progDir = new GuestProcessDirector(vm, “admin”, “pass”);
    Says that class can not be found.

  12. July 8th, 2014 at 18:44 | #12

    You need to include the jar that has the G.P.D in your classpath to run the sample.


  13. Evan
    July 14th, 2014 at 08:42 | #13

    Hi Steve,

    I am trying to change the linux password using the code below but it does not change the password and i get no errors. Any idea what I am doing wrong?


    GuestProgramSpec GPS = new GuestProgramSpec();
    GPS.Arguments = “echo -e \”evan\\nevan\” | passwd root”;
    GPS.ProgramPath = “/”;
    GuestProcessManager s = (GuestProcessManager)vc.GetView(GOM.ProcessManager, null);
    s.StartProgramInGuest(TempVM.MoRef, NPA, GPS);

  1. March 5th, 2012 at 01:32 | #1
  2. March 11th, 2012 at 01:35 | #2