Name

Description

$err = VMLoginInGuest($vmHandle,
                      $userName,
                      $password,
                      $options);

This function establishes a guest operating system authentication context that can be used with guest functions for the given virtual machine handle.

Parameters

vmHandle

Identifies a virtual machine. Call VMOpen() to create a virtual machine handle.

userName

The name of a user account on the guest operating system.

password

The password of the account identified by userName.

options

Must be 0.

Return Value

Remarks

• This function validates the account name and password in the guest OS. You must call this function before calling functions to perform operations on the guest operating system, such as VMRunProgramInGuest(). If you do not call any guest functions, you do not need to call VMLoginInGuest(). LoginInGuest().
• The following functions require that you call VMLoginInGuest().
  • VMRunProgramInGuest()
  • VMListProcessesInGuest()
  • VMKillProcessInGuest()
  • VMRunScriptInGuest()
  • VMOpenUrlInGuest()
  • VMCopyFileFromHostToGuest()
  • VMCopyFileFromGuestToHost()
  • VMDeleteFileInGuest()
  • VMFileExistsInGuest()
  • VMRenameFileInGuest()
  • VMCreateTempFileInGuest()
  • VMListDirectoryInGuest()
  • VMCreateDirectoryInGuest()
  • VMDeleteDirectoryInGuest()
  • VMDirectoryExistsInGuest()
  • VMWriteVariable() when writing a VIX_GUEST_ENVIRONMENT_VARIABLE value

• All guest operations for a particular VM handle will be done using the identity you provide to VMLoginInGuest(). As a result, guest operations will be restricted by file system priveleges in the guest OS that apply to the user specified in VMLoginInGuest(). For example, VMDeleteDirectoryInGuest(). may fail if the user named in VMLoginInGuest(). does not have access permissions to the directory in the guest OS.

• VMLoginInGuest() changes the behavior of Vix functions to use a user account. It does not log in a user into a console session on the guest operating system. As a result, you may not see the user logged in from within the guest operating system. Moreover, operations such as rebooting the guest do not clear the guest credentials.

• You must call VMLoginInGuest() for each VM handle that uses guest operations.

• The virtual machine must be powered on before calling this function.

• VMware Tools must be installed and running on the guest operating system before calling this function. You can call VMWaitForToolsInGuest() to wait for the tools to run.

• You can call VMLogoutFromGuest() to remove the user information from the VMHandle.

• You can always explicitly login in the guest by providing a username and password that is valid on the guest. Then you will execute all guest operations as that user. This is the default mechanism and is encouraged.

• Optionally, you may call VMLoginInGuest() with the constant defined by VIX_CONSOLE_USER_NAME in vix.h as the userName, and NULL for the password. If there is a user currently logged into the guest at the console (through the MKS) then all guest operations will be run as the console user. This is enabled by default and must be explicitly disabled by setting the "guest.commands.anonGuestCommandsRunAsConsoleUser" config value to false. If no user is logged in at the guest console, the call to VMLoginInGuest() will block and wait for a user to log in to the console.

Side Effects

Requirements

use VMWare::Vix::Simple;
use VMware::Vix::API::Constants;

Example

my $err = VIX_OK;
my $hostHandle = VIX_INVALID_HANDLE;
my $vmHandle = VIX_INVALID_HANDLE;

($err, $hostHandle) = HostConnect(VIX_API_VERSION,
                                  VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                                  undef, # hostName
                                  0, # hostPort
                                  undef, # userName
                                  undef, # password
                                  0, # options
                                  VIX_INVALID_HANDLE); # propertyListHandle

die "HostConnect() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;

($err, $vmHandle) = VMOpen($hostHandle,
                           "c:\\Virtual Machines\\vm1\\win2000.vmx");
die "VMOpen() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;
                       
$err = VMPowerOn($vmHandle,
                 0, # powerOnOptions
                 VIX_INVALID_HANDLE);  # propertyListHandle
die "VMPowerOn() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;


$err = VMWaitForToolsInGuest($vmHandle,
                             300); # timeoutInSeconds
die "VMWaitForToolsInGuest() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;

$err = VMLoginInGuest($vmHandle,
                      "vixuser", # userName
                      "secret", # password
                      0); # options
die "VMLoginInGuest() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;

$err = VMCopyFileFromGuestToHost($vmHandle, 
				 "c:\\guestDir\\helloworld.o",  # src name
				 "c:\\hostDir\\helloworld.o", # dest name
				 0, # options
				 VIX_INVALID_HANDLE); # propertyListHandle
die "VMCopyFileFromGuestToHost() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;

ReleaseHandle($vmHandle);
HostDisconnect($hostHandle);