SharePoint 2010 with Windows PowerShell Remoting Step by Step
With all the improvements in SharePoint 2010 for IT Professionals, I always put Windows PowerShell support as the number one. Maybe this has something to do with my past Linux/Unix background, but the main reason is, I’m a really really lazy person. If something can be put into automation, then why bother to click through it manually every time? Schedule it to run at certain time everyday can save me a lot of time. In the past SharePoint versions, STSADM is okay, but it’s limited and hard to play with. Although you can use Windows PowerShell to call object models directly, but that is too complex and indeed a developer stuff. Now, with SharePoint 2010 Windows PowerShell cmdlets, scripting can be really fun!
But someone asked me this question:
You are telling me scripting is great – but isn’t that just a server thing? I still need to open remote desktop on my laptop to connect to the server box and then do the shell stuff, can’t I have something like SSH? Just run my script remotely without opening my browser, remote desktop, only Windows PowerShell…
Definitely you can do it! Windows PowerShell v2 RTM on Server 2008/R2, which is also a requisite of SharePoint 2010, supports “remoting”. So you can manage SharePoint 2010 remotely with Windows PowerShell prompt on your local machine.
Let’s try it!
Enable Remoting support on SharePoint Server box
A few steps are necessary to setup Windows PowerShell Remoting for SharePoint.
Enable Windows PowerShell Remoting
Windows PowerShell Remoting needs to be enabled first by calling the following cmdlet in Windows PowerShell:
This command will do a quick configuration of Windows Remote Management (WinRM). A HTTP listener will be created by WinRM and firewall exceptions will be created automatically. If you get a Kerberos error, it could be possible that SPN for HTTP/yourservername is not there and you need to use setspn to add it. Most of the time you won’t have the issue.
You can test if the remoting is working by type Enter-PSSession –ComputerName localhost on the same server box.
However, there’re two extra requirements for SharePoint remoting. I just list them here, if you want further details, Zach Rosenfield, the Program Manager who owns SharePoint Windows PowerShell support, explained in his blog SharePoint PowerShell “Remoting” Requirements.
Increase memory limit for remote shell
Some of the SharePoint cmdlets could run for quite a long time and require a lot of memory. By default, a remote shell will be allocated 150 MB of memory, this may cause some of the command to fail, for example site collection creation. Use the following command to increase this limitation to 1000MB. This is only necessary if you need to run those commands on that server.
Set-Item WSMan:\localhost\Shell\MaxMemoryPerShellMB 1000
If this value is too low, then you may have error messages like:System.Management.Automation.RemoteException: Process is terminated due to StackOverflowException.
Setup CredSSP support
Credential Security Service Provider(CredSSP) authentication should be used if you need to do “double hop” with your credentials. It does not mean using other authentication methods you can’t run the cmdlets at all, depending on different security permission scenarios, they may or may not work. CredSSP is the best way to deal with the situation.
In some of the situation, even without CredSSP the cmdlets still work. For example, my current account is in Microsoft domain. The target server is in contoso.com domain. I used Negotiate authentication with a username and password to logon this server remotely, then created a new content database without any problem. You can test your environment to choose the best way – certain domain policy may prevent client machine from delegating credentials, which is required by CredSSP. But still, please use CredSSP in any case if possible.
To enable CredSSP on the server, use the following command:
Enable-WSManCredSSP –Role Server
You can use Get-WSManCredSSP to check if it is enabled.
Setup client machine for Remoting
Enable CredSSP support
To use CredSSP, you need to run the following command in Windows PowerShell, where * can be replaced with the server name you want to connect:
Enable-WSManCredSSP -Role client -DelegateComputer *
Use Get-WSManCredSSP to check if it is enabled correctly.
Create and enter a remote session of Windows PowerShell
If your current user on client machine has permission to the SharePoint farm and Windows PowerShell on the remote box, you can use Enter-PSSession to create and enter the remote session.
For example, connecting to sharepoint.contoso.com…
Enter-PSSession -ComputerName sharepoint.contoso.com
If it works, the command prompt will be changed to [sharepoint.contoso.com]: PS C:\Users\Administrator\>.
To connect to a machine with CredSSP and a different credential, you can use
Enter-PSSession -ComputerName sharepoint.contoso.com -Authentication CredSSP –Credential domain\username
This will pop up a dialogue for you to type in password. If you want this process to be fully automated, you can store the credential first into a file.
Store and use credentials for scripting
A credential in Windows PowerShell is a object which contains username (as plain text) and password (as secure string).
First, use the following command to covert password from keyboard input to a secure string in a text file.
Read-Host -AsSecureString | ConvertFrom-SecureString | out-file C:\crd-sharepoint.txt
When you need to create a credential object, read this password (the secure string) from the file and create the credential with the following command:
$pwd = Get-Content C:\crd-sharepoint.txt | ConvertTo-SecureString
then create the credential (replace myusername with your domain\username):
$crd = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList "myusername",$pwd
Then you will be able to use this credential in the command line without any dialogue.
Enter-PSSession -ComputerName sharepoint.contoso.com -Authentication CredSSP -Credential $crd
Load SharePoint Windows PowerShell Snap-in
Unlike SharePoint Management Shell, You need to load this snap-in manually to use the cmdlets for SharePoint.
Then everything will work.
Zach Rosenfield’s Blog
Zach’s blog is my favorite. The following articles are highly recommended to read…
SharePoint 2010 PowerShell Permissions Explained
Remote Install of SharePoint (with SPModule)
Webcast - Getting Started: Windows PowerShell for SharePoint 2010 Administrators, by Todd Kindt on TechNet
Technical Reference: Windows PowerShell for SharePoint Server 2010
CHM references for download. Please note there’ll be some changes in the cmdlets between beta and RTM.
Ask them on TechNet Forum! If we got enough questions we may even open a separate section for Windows PowerShell!