Name
VMLoginInGuest
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 or VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT.
Return Value
$err. The error code returned by the operation. For returned values, see Topics > Error Codes.
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 OS,
such as those below. Otherwise you do not need to call this function.
- This function does not load system environment variables.
VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT
should be used to be sure the function
VMOpenUrlInGuest
works correctly.
- The following functions require that you call VixVM_LoginInGuest():
- VixVM_RunProgramInGuest()
- VixVM_ListProcessesInGuest()
- VixVM_KillProcessInGuest()
- VixVM_RunScriptInGuest()
- VixVM_OpenUrlInGuest()
- VixVM_CopyFileFromHostToGuest()
- VixVM_CopyFileFromGuestToHost()
- VixVM_DeleteFileInGuest()
- VixVM_FileExistsInGuest()
- VixVM_RenameFileInGuest()
- VixVM_CreateTempFileInGuest()
- VixVM_ListDirectoryInGuest()
- VixVM_CreateDirectoryInGuest()
- VixVM_DeleteDirectoryInGuest()
- VixVM_DirectoryExistsInGuest()
- VixVM_WriteVariable() when writing a VIX_GUEST_ENVIRONMENT_VARIABLE value.
- VixVM_CaptureScreenImage()
- All guest operations for a particular VM handle are done using the identity
you provide to VixVM_LoginInGuest(). As a result, guest operations are restricted
by file system privileges in the guest OS that apply to the user specified
in VixVM_LoginInGuest(). For example, VixVM_DeleteDirectoryInGuest() might fail
if the user named in VixVM_LoginInGuest() does not have access permissions
to the directory in the guest OS.
- VixVM_LoginInGuest() changes the behavior of Vix functions to use a user account.
It does not log a user into a console session on the guest OS. As a result,
you might not see the user logged in from within the guest OS.
Moreover, operations such as rebooting the guest do not clear the guest credentials.
- You must call VixVM_LoginInGuest() 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 OS
before calling this function. You can call VixVM_WaitForToolsInGuest()
to wait for the tools to run.
- Once VixVM_LoginInGuest() has succeeded, the user session remains valid until
- VixVM_LogoutFromGuest() is called successfully,
- VixVM_LoginInGuest() is called successfully with different user credentials,
- the virtual machine handle's reference count reaches 0, or
- the client applications exits.
- 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
- VMCaptureScreenImage
- All guest operations for a particular VM handle are done using the identity
you provide to VMLoginInGuest(). As a result, guest operations are restricted
by file system privileges in the guest OS that apply to the user specified
in VMLoginInGuest(). For example, VMDeleteDirectoryInGuest() might 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 a user into a console session on the guest OS. As a result,
you might not see the user logged in from within the guest OS.
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 OS
before calling this function. You can call VMWaitForToolsInGuest()
to wait for the tools to run.
- Once VMLoginInGuest() has succeeded, the user session remains valid until
- VMLogoutFromGuest() is called successfully,
- VMLoginInGuest() is called successfully with different user credentials,
- the virtual machine handle's reference count reaches 0, or
- the client applications exits.
- To log in as a Windows Domain user, you should specify the 'userName' parameter
in the form "domain\username".
- The special login type VIX_CONSOLE_USER_NAME is no longer supported.
- This function does not respect access permissions on guest operating systems
Windows 95, Windows 98, and Windows ME, due to limitations of the
permissions model in those operating systems.
Side Effects
None.
Requirements
use VMware::Vix::Simple;
use VMware::Vix::API::Constants;
since VMware Server 1.0
Example
This example copies a compiled object file from a virtual machine to be
run on the host.
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;
$err = VMLogoutFromGuest($vmHandle);
die "VMLogoutFromGuest() failed, $err ", GetErrorText($err), "\n" if $err != VIX_OK;
ReleaseHandle($vmHandle);
HostDisconnect($hostHandle);