Common Tasks ：Virtual Machine Guest Operations

Virtual Machine Guest Operations

This section discusses several operations that provide access to the guest operating system.

VMware Tools

All functions that execute in a guest operating system require VMware Tools to be installed and running. See Installing VMware Tools in a Virtual Machine for information on installing VMware Tools.

Authentication

All functions that modify a file system in the guest operating system or that execute code in a guest operating system require the client to authenticate as a user account known to the guest. The following list shows the functions that require client authentication.

•  VixVM_CopyFileFromHostToGuest()
•  VixVM_CopyFileFromGuestToHost()
•  VixVM_CreateDirectoryInGuest()
•  VixVM_CreateTempFileInGuest()
•  VixVM_DeleteDirectoryInGuest()
•  VixVM_DeleteFileInGuest()
•  VixVM_DirectoryExistsInGuest()
•  VixVM_FileExistsInGuest()
•  VixVM_KillProcessInGuest()
•  VixVM_ListDirectoryInGuest()
•  VixVM_ListProcessesInGuest()
•  VixVM_OpenUrlInGuest()
•  VixVM_RenameFileInGuest()
•  VixVM_RunProgramInGuest()
•  VixVM_RunScriptInGuest()

A client uses VixVM_LoginInGuest() to authenticate with the guest operating system. Once authenticated, the client may continue to perform guest operations until one of the following takes place:

• The client calls VixVM_LogoutFromGuest().
• The client terminates, which ends the session.
• The client attempts to authenticate a second time, and the second attempt fails.
• The virtual machine shuts down.

If a virtual machine is suspended while a client is authenticated with the guest operating system, the client may resume guest operations after resuming virtual machine execution. However, this is true only as long as the client continues running while the virtual machine is suspended.

To authenticate with the guest operating system:

1. Connect to the host on which the virtual machine is located. See Connecting to a Host.
2. Get a handle to the virtual machine. See Getting a Handle to a Virtual Machine.
3. Power on the virtual machine and wait for VMware Tools to become active. See Starting or Resuming a Virtual Machine.
4. Use the virtual machine handle, the user name, and the user password, to call VixVM_LoginInGuest().

   Example 3-10.

   C code below. Click here for Perl. Click here for COM.

VixError err = VIX_OK;
VixHandle jobHandle = VIX_INVALID_HANDLE;
 
// Authenticate with guest operating system.
jobHandle = VixVM_LoginInGuest(vmHandle,
                               "Administrator", // userName
                               "secret", // password
                               0, // options
                               NULL, // callbackProc
                               NULL); // clientData
err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
 
Vix_ReleaseHandle(jobHandle);
jobHandle = VIX_INVALID_HANDLE;

The Console User

You may sometimes choose to provide a predefined string in place of an actual user name when callingVixVM_LoginInGuest(). The Vix header file provides the define VIX_CONSOLE_USER_NAME as a substitute for an actual user name. You need to use this substitute for authentication with a Windows guest operating system if you plan to launch a graphical user interface in the guest.

Before calling VixVM_LoginInGuest() with VIX_CONSOLE_USER_NAME, you need to be sure that a user is currently logged in to the guest operating system. The user must log in through a graphical console connection to the virtual machine.

VixVM_LoginInGuest() establishes credentials for API operations but does not do an actual login to the guest.

Using VIX_CONSOLE_USER_NAME is similar to making a second console connection to a virtual machine. When a user has logged in through one console connection, a second connection to the same virtual machine shares the display with the first connection and takes advantage of the first user's login account.

VIX_CONSOLE_USER_NAME is needed prior to calling these functions:

•  VixVM_OpenUrlInGuest()
•  VixVM_RunProgramInGuest()

The password for VIX_CONSOLE_USER_NAME is always NULL.

1. Example 3-11.

   C code below.  Click here for Perl.  Click here for COM.

VixError err = VIX_OK;
VixHandle jobHandle = VIX_INVALID_HANDLE;
 
// Authenticate with guest operating system.
jobHandle = VixVM_LoginInGuest(vmHandle,
                               CONSOLE_USER_NAME, // Use console ID
                               NULL, // no password needed
                               0, // options
                               NULL, // callbackProc
                               NULL); // clientData
err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
// Handle the error...
goto abort;
}
Vix_ReleaseHandle(jobHandle);
jobHandle = VIX_INVALID_HANDLE;