vSphere PowerCLI Reference

Copy-VMGuestFile

Synopsis

Copies files and folders from and to the guest OS of the specified virtual machines using VMware Tools.

Syntax

Copy-VMGuestFile [-Source] <String[]> [-Destination] <String> -GuestToLocal [-Force] [-VM] <VirtualMachine[]> [-HostCredential <PSCredential>] [-HostUser <String>] [-HostPassword <SecureString>] [-GuestCredential <PSCredential>] [-GuestUser <String>] [-GuestPassword <SecureString>] [-ToolsWaitSecs <Int32>] [-Server <VIServer[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
Copy-VMGuestFile [-Source] <String[]> [-Destination] <String> -LocalToGuest [-Force] [-VM] <VirtualMachine[]> [-HostCredential <PSCredential>] [-HostUser <String>] [-HostPassword <SecureString>] [-GuestCredential <PSCredential>] [-GuestUser <String>] [-GuestPassword <SecureString>] [-ToolsWaitSecs <Int32>] [-Server <VIServer[]>] [-WhatIf] [-Confirm] [<CommonParameters>]

Related Commands

Online version

Detailed Description

Copies file and folders from and to the guest OS of the specified virtual machines using VMware Tools. If a file with the same name exists in the destination directory, it is overwritten. Use the GuestUser and GuestPassword, or GuestCredential parameters to authenticate when connecting to the VMware Tools. To authenticate with the host, use the HostUser and HostPassword, or HostCredential parameters. SSPI is not supported. This cmdlet supports only Windows XP 32 SP3, Windows Server 2003 32bit SP2, Windows Server 2003 64bit SP2, Windows 7 64 bit, Windows Server 2008 R2 64bit and Redhat Enterprise 5 operating systems.

To run this cmdlet against vCenter Server/ESX/ESXi versions earlier than 5.0, you need to meet the following requirements:
*You must run the cmdlet on the 32-bit version of Windows PowerShell.
*You must have access to the ESX that hosts the virtual machine over TCP port 902.
*For vCenter Server/ESX/ESXi versions earlier than 4.1, you need VirtualMachine.Interact.ConsoleInteract privilege. For vCenter Server/ESX/ESXi 4.1 and later, you need VirtualMachine.Interact.GuestControl privilege.

To run this cmdlet against vCenter Server/ESXi 5.0 and later, you need VirtualMachine.GuestOperations.Modify privilege.

Parameters

NameTypeDescriptionRequired?Pipeline InputDefault Value
SourceString[]Specify the file you want to copy. If the file is on a virtual machine, specify the absolute file path. Relative file paths are supported only when copying files from a local storage. Wildcards are allowed only at the end of the source path. If you are copying files from the guest operating system of a virtual machine to a local directory, the Source parameter supports wildcards only on vCenter Server 5.0 and later.truefalse
DestinationStringSpecify the destination path where you want to copy the file. If the destination points to a virtual machine, specify the absolute file path. Relative destination paths are supported only when copying files to a local storage.truefalse
VMVirtualMachine[]Specify the virtual machine where the file is located.truetrue (ByValue)
ConfirmSwitchParameterIf the value is $true, indicates that the cmdlet asks for confirmation before running. If the value is $false, the cmdlet runs without asking for user confirmation.falsefalse$true
ForceSwitchParameterIndicate that the non-existing directories in the specified destination path are automatically created.falsefalse
GuestCredentialPSCredentialSpecify a PSCredential object that contains credentials for authenticating with the guest OS where the file to be copied is located.falsefalse
GuestPasswordSecureStringSpecify the password you want to use for authenticating with the guest OS where the file to be copied is located.falsefalse
GuestToLocalSwitchParameterIndicate that you want to copy a file from the guest operating system of the virtual machine to a local directory.truefalse
GuestUserStringSpecify the user name you want to use for authenticating with the guest OS where the file to be copied is located.falsefalse
HostCredentialPSCredentialSpecify a PSCredential object that contains credentials for authenticating with the host where the file is to be copied. Do not use this parameter if the -HostUser and -HostPassword parameters are used. You need to specify host credentials only if the version of the vCenter Server or ESX you are authenticating with is earlier than 4.0, or the VIX version you have installed is earlier than 1.10.falsefalse
HostPasswordSecureStringSpecify the password you want to use for authenticating with the host where the file is to be copied. You need to specify host credentials only if the version of the vCenter Server or ESX you are authenticating with is earlier than 4.0, or the VIX version you have installed is earlier than 1.10.falsefalse
HostUserStringSpecify the user name you want to use for authenticating with the host where the file is to be copied. You need to specify host credentials only if the version of the vCenter Server or ESX you are authenticating with is earlier than 4.0, or the VIX version you have installed is earlier than 1.10.falsefalse
LocalToGuestSwitchParameterIndicate that you want to copy a file from a local directory to the guest operating system of the virtual machine.truefalse$true
ServerVIServer[]Specify the vSphere servers on which you want to run the cmdlet. If no value is given to this parameter, the command runs on the default servers. For more information about default servers, see the description of Connect-VIServer.falsefalse
ToolsWaitSecsInt32Specify the time in seconds to wait for a response from the VMware Tools. If a non-positive value is provided, the system waits infinitely long time.falsefalse20
WhatIfSwitchParameterIndicate that the cmdlet is run only to display the changes that would be made and actually no objects are modified.falsefalse

Return Type

Notes

Examples

-------------- Example 1 --------------

Copy-VMGuestFile -Source c:\text.txt -Destination c:\temp\ -VM VM -GuestToLocal -GuestUser user -GuestPassword pass2

Copies the text.txt file from the guest OS system to the local Temp directory.

-------------- Example 2 --------------

$vm = Get-VM -Name VM

Get-Item "c:\FolderToCopy\*.*" | Copy-VMGuestFile -Destination "c:\MyFolder" -VM $vm -LocalToGuest -GuestUser -GuestPassword pass2

Copies files from a local machine to a guest operating system.


Copyright © 1998 - 2012 VMware, Inc. All rights reserved.