Ezine 186 – Grappling with PowerShell’s Remoting

Ezine 186 – Grappling with PowerShell 2.0 Remoting

Normally Microsoft products are so easy to install that you don’t need any instructions.  However, PowerShell v 2.0 with ‘Remoting’ is an exception; in fact, creating remote sessions is so difficult for beginners that I have devoted a whole article to achieve this single mission.

Remoting in Microsoft PowerShell v 2.0

This Week’s Secret

Remoting is PowerShell v 2.0’s jewel in the crown.  The ability to run the wonderful PowerShell commands against another machine transforms what you can achieve by typing away at your command-line.  Now for the bad news, getting starting with remoting is hard.  Most of the articles about PowerShell’s remote capabilities are written by experts, people who are not only comfortable with command line syntax, but also, in a previous life, have probably written a shell program from scratch.

This Week’s Mission

My Mission is solely to get you started with remoting.  Firstly, set aside any thoughts of safe procedures; on each test machine logon locally as THE administrator, then disable the firewalls on each test computer.  Furthermore, before you launch either PowerShell or the cmd DOS box, right-click and select ‘Run as administrator’, that way if a command does not work it won’t be due to lack of security rights.  Once you gain success with remoting commands, then naturally revert to normal security and start turning on firewalls, and logging on with normal accounts. 

The crucial concept for this mission is to get PowerShell remoting working is that we need an additional shell program called WinRm.  If you have used a command line program such as NetSh then the concepts involved in configuring WinRm will be vaguely familiar.  I got my copy of WinRm from Microsoft Connect, I recommend registering with this site because you never know when you are going to need some its vast library of software.  Also be sure to install the same version of WinRm and PowerShell v 2.0 on both test machines.  Incidentally, that in itself can be a major challenge if you have to uninstall a previous version, but in the mean time you have applied a service pack. 

Two Types of PowerShell Remoting

It’s time to point out that there are two varieties of Microsoft PowerShell remoting; the more sophisticated variation employs cmdlets containing the word PSSession, check what’s available with this cmdlet:
get-Command -noun PSSession.

But there is also a more basic form of remoting which merely extends local commands by appending the -computerName parameter; the result is that your instructions run against another named machine on the network.  For example:
get-Process -computerName machine2.

For a list of cmdlets that support this simple remote behaviour try:
get-command | where { $_.parameters.keys -contains "ComputerName"}

For the full list you need to add: -and $_.parameters.keys -notContains "Session"

Get Started with Basic Remoting

I strongly recommend that you gain confidence by starting with the basic form of remoting, my reasoning is that it does not require you configuring the tricky WinRm shell.   My thinking is that when you are learning anything new, not just PowerShell, there is nothing like success to encourage exploring the boundaries of what is possible.  Thus once you have mastered a PowerShell technique on the local computer it’s only natural try to run the same command on a remote machine. 

get-services   (Local Machine)
get-Services -computerName machine2  (You should get a list of services from your second test computer.)

Guy Recommends: Tools4ever’s UMRAUMRA The User Management Resource Administrator

Tired of writing scripts? The User Management Resource Administrator solution by Tools4ever offers an alternative to time-consuming manual processes.

It features 100% auto provisioning, Helpdesk Delegation, Connectors to more than 130 systems/applications, Workflow Management, Self Service and many other benefits. Click on the link for more information onUMRA.

WinRm – The Pre-requisite for PowerShell Remoting

Even with all the components installed correctly, (PowerShell v 2.0 CTP3, .Net Framework and WinRm), remoting still won’t work until you run this cmdlet from within PowerShell (not DOS):

Note that unlike PSSession commands, this function only has one ‘S’ PSRemoting.  Actually, the underling cmdlet is Enable-PSSessionConfiguration.

The two commonest traps with WinRm are, trying to configure this command from inside PowerShell, when you should be at the cmd (DOS box) command line.  In particular the ‘set’ verb works with cmd but not with PowerShell.  The second trap is remembering to right-click and ‘Run as administrator’.  The error messages do give tiny clues to the underlying problem, but they don’t give many ideas for a solution.  This is why I recommend investigating the WinRm syntax, I would start with
winrm help -?

Having noted the verbs, ‘get’, ‘set’ and ‘enumerate’, I would try
winrm help config

Two more useful commands
winrm enumerate winrm/config/listener
winrm get winrm/config/client

Any problems, remember, you should be in the DOS box and not PowerShell.   Also, you did right-click and ‘Run as administrator’, didn’t you?  Naturally you have to run the same WinRm setup techniques on both the host machine and the test ‘victim’ machine.

Configuring TrustedHosts drove me mad, I suggest you try this command, especially noting the famous * wildcard:
winrm set winrm/config/client @{TrustedHosts="*"}  

Guy Recommends: The Free IP Address Tracker (IPAT) IP Tracker

Calculating IP Address ranges is a black art, which many network managers solve by creating custom Excel spreadsheets.  IPAT cracks this problem of allocating IP addresses in networks in two ways:

For Mr Organized there is a nifty subnet calculator, you enter the network address and the subnet mask, then IPAT works out the usable addresses and their ranges. 

For Mr Lazy IPAT discovers and then displays the IP addresses of existing computers. Download the Free IP Address Tracker

Basic PowerShell Remoting Commands

Once you have slaved away to setup PowerShell v 2.0’s remoting, then naturally you want to test the connections to the second machine, for example:

New-PSSession -computername testMachine2
Or simply:
Enter-PSSession -computername testMachine2

Other useful commands include:
Get-PSSession | remove-PSSession  (Deletes the session)

For the full list try: Get-command -noun pssession.  Also get-command -verb invoke

Once you reach the ‘Victim’ / client / second machine

With the remote pipeline in place, you are ready to run PowerShell commands as though you were at the keyboard of the second machine, indeed, this is the whole point of creating remote shells.  For example,

set-location c:\ | get-childitem

As my mission in this ezine is solely to get you started, now it’s up to you to think of PowerShell cmdlets to run on the remote computer.

Tip: If any of your remote commands don’t seem to work, test them on your local computer first.

Summary of Microsoft PowerShell v 2.0 Remoting

Paradoxically, once you realize a project is going to be complicated, the task becomes easy if you break it down into a series of bite-sized chunks.  Therefore, install the same version of PowerShell on both machines, abandon security and get WinRm working, now you are ready to test PowerShell 2.0’s wonderful remoting capabilities.

If you like this page then please share it with your friends


See more Microsoft PowerShell tutorials

PowerShell Tutorials  • Methods  • Cmdlets  • PS Snapin  • Profile.ps1  • Exchange 2007

Command & Expression Mode  • PowerShell pipeline (|)  • PowerShell ‘where‘  • PowerShell ‘Sort’

Windows PowerShell Modules  • Import-Module  • PowerShell Module Directory 

If you see an error of any kind, do let me know.  Please report any factual mistakes, grammatical errors or broken links.