It's easy to copy files with PowerShell Copy-Item via the command line. Once you specify the source and destination location, it just happens. Unfortunately, many administrators don't think about how this process occurs until it doesn't work.
Whether or not you think about this, all TCP network communication (such as SMB file copies) use network ports to make the bits transfer. For a file copy process to get a file from point A to point B, a port needs to be open all the way to the destination node. In the case of an SMB file copy, that port is 445. This is a common port that's usually open internally, except in some high-security situations or across a DMZ.
If you're in a high-security environment or need to transfer files from an internal network to a DMZ that might have various port restrictions, how can you ensure that your scripts are able to copy files to nodes all the time? One way to do so is to use PowerShell v5's Copy-Item cmdlet with the new –ToSession parameter.
This parameter was introduced with Windows Management Framework (WMF) v5 with the Copy-Item cmdlet. It provides a way to transfer files over the same link that you might use today to execute commands remotely on computers with cmdlets like Invoke-Command.
This process has a few different advantages, but included in the biggest benefits are the TCP ports used: 5985 (HTTP) and 5986 (HTTPS). These standard ports are typically open to manage remote nodes, sometimes even to a DMZ environment. By using Copy-Item –ToSession, an administrator can ensure files will always be copied to a remote computer regardless of whether or not SMB is blocked.
When you're using PowerShell Copy-Item via the traditional SMB method, you need to specify the Path and Destination parameters. If you'd like to copy a file called file1.txt inside of C:\Folder to a remote computer SERVER1 on its C:\, you could do this:
Copy-Item –Path C:\Folder1\file1.txt –Destination '\\SERVER1\c$'
Notice that you're using the UNC path of \\SERVER1\c$ here. This will be important in a minute.
But what if SMB is blocked for some reason or you're using Invoke-Command to run commands on SERVER1 anyway? You can leverage PowerShell remoting sessions to transfer the file over WinRM instead of SMB. In order to do this, you must establish a new remoting session and then pass the file over that session.
First, you should create a new PowerShell remoting session. To do this, you can use the New-PSSession cmdlet and assign the session to the $session variable.
$session = New-PSSession –ComputerName SERVER1
This will use Kerberos authentication to establish a new PowerShell remoting session, which is the most common method to use when in an Active Directory environment.
Next, you need to specify the ToSession parameter and a local path on the remote computer for the Destination parameter.
Copy-Item –Path C:\Folder1\file1.txt –Destination 'C:\' –ToSession $session
Notice that you're now using C:\ for the destination rather than a UNC path. This command will accomplish the exact same thing as your previous one, but it will use the session to encapsulate the file and transfer it via WinRM.
Don't forget to remove the session when you're done by using Remove-PSSession.
$session | Remove-PSSession
If you don't intend to reuse the session for anything else, you could also create the session and tear it down (all at the same time).
Copy-Item –Path C:\Folder1\file1.txt –Destination 'C:\' –ToSession (New-PSSession –ComputerName SERVER1)
That's all there is to it! The next time you find yourself in an environment where PowerShell remoting is allowed but SMB is restricted, or you're already using a remoting session for something else, you can pass the session to Copy-Item to get your file transferred easily from point A to point B. Don't stop here; read our eBook, "How to Automate Using PowerShell," for other PowerShell tricks.
Adam Bertram is a 20-year veteran of IT. He’s currently an automation engineer, blogger, independent consultant, freelance writer, author, and trainer. Adam focuses on DevOps, system management, and automation technologies as well as various cloud platforms. He is a Microsoft Cloud and Datacenter Management MVP and efficiency nerd that enjoys teaching others a better way to leverage automation.
Let our experts teach you how to use Sitefinity's best-in-class features to deliver compelling digital experiences.
Learn MoreSubscribe to get all the news, info and tutorials you need to build better business apps and sites
Progress collects the Personal Information set out in our Privacy Policy and the Supplemental Privacy notice for residents of California and other US States and uses it for the purposes stated in that policy.
You can also ask us not to share your Personal Information to third parties here: Do Not Sell or Share My Info
We see that you have already chosen to receive marketing materials from us. If you wish to change this at any time you may do so by clicking here.
Thank you for your continued interest in Progress. Based on either your previous activity on our websites or our ongoing relationship, we will keep you updated on our products, solutions, services, company news and events. If you decide that you want to be removed from our mailing lists at any time, you can change your contact preferences by clicking here.