SharePoint 2010 Cmdlets for Administration

As I mentioned in a previous article, SharePoint Server 2010 comes with 531 sharepoint-specific PowerShell cmdlets — little commands for sharepoint management — built in to the SharePoint 2010 Management Shell. Now, let’s take a quick survey of some of these cmdlets as well as some tips on how you can get up-to-speed with managing SharePoint with PowerShell.

Like all PowerShell cmdlets, these little SharePoint specific management tools are named with a verb-hypen-noun style. With these 531 cmdlets, there are 197 unique nouns, or different aspects of SharePoint that can be managed, and 38 unique verbs, or ways in which these parts of SharePoint may be administered. Certainly, it is not necessary to learn or memorize all of these cmdlets, but recommended that you focus on the areas of SharePoint you need to manage. Cmdlets such as Publish-SPServiceApplication and Ping-SPEnterpriseSearchContentService are some of the more esoteric.

If you start with just four verbs—get, set, new, and remove—you have 405 of the 531 cmdlets covered, and can focus on which aspects of SharePoint (nouns) you need to manage. Obviously, the remaining 126 cmdlets are used for something, but if they’re not applicable to your daily management needs, you could likely save learning about them until later.

As an example of learning related cmdlets, SharePoint’s dependence on SQL databases services as a good starting point. The generic noun to refer to these is SPDatabase, as used in the Get-SPDatabase cmdlet, while the other nouns are specific to a particular kind of SharePoint database, namely: SPConfigurationDatabase, SPContentDatabase, SPEnterpriseSearchCrawlDatabase, SPEnterpriseSearchPropertyDatabase, SPSingleSignOnDatabase, and SPStateServiceDatabase. Not all verbs work with all of these different types of databases (nouns). Although the most common verbs are Get, Set, New, and Remove, there is no Get nor Set cmdlet for either SPConfigurationDatabase or SPSingleSignOnDatabase.

In fact, while SPConfigurationDatabase has New and Remove cmdlets, yet no Set and Get, it also has Connect, Disconnect, and Backup cmdlets. Each kind if SharePoint database, like many other managed objects, has particular operations which make logical sense to meet their unique characteristics and management needs. The specific characteristics of the SPConfigurationDatabase and its cmdlets relate to the association of a SharePoint configuration database with a farm. The Connect-SPConfigurationDatabase cmdlet associates the current server with the specified configuration database, and therefore the farm. To move a server from one farm to another, first use the Disconnect-SPConfigurationDatabase to dissociate the server from its current farm, then use Connect-SPConfigurationDatbase cmdlet to associate the server with its new farm.

For example, to move the current server from the FINANCE farm to the MARKETING farm, use the following:

Disconnect-SPConfigurationDatabase
Connect-SPConfigurationDatabase -DatabaseServer clarityPRIMARYSERVER `
-DatabaseName SharePoint_Config

Another cmdlet associated with SPConfigurationDatabase is Backup-SPConfigurationDatabase, which backs up the specified configuration database, essentially backing up the farm configuration associated with that configuration database. A shared folder is specified as the backup destination. The content databases would be backed up independently, for example using the Backup-SPFarm cmdlet.

The configuration database for a farm is a tangible aspect of the management of a SharePoint deployment, yet its relationship to the SharePoint servers within a farm is not often reconfigured on a daily basis, yet when you add or remove servers to the farm. We’ve chosen this fairly static aspect of a SharePoint Server 2010 deployment as a starting point for further discussion. The SharePoint 2010 Management Shell can provide a wealth of opportunities for day-to-day administration automation, as perhaps we’ll address in future articles.

SharePoint 2010 Management Shell

Web-based administration via a web browser enables secure, remote, flexible administration of many services. SharePoint Server 2010, unlike many other Microsoft products is not managed with a Microsoft Management Console (MMC) snap-in, but with such a web interface.

It might seem that this management motif has it all. A farm of servers may be managed from a phone, tablet, or regular computer via a web browser from virtually anywhere in the world. When you upgrade your servers, the web management component(s) are upgraded at each managed server without a need to change anything on the management (browser) side.

Why would you want any other kind of management interface? Seriously. Think about it. Click, tap, or touch your way through the interface, and when necessary, type a few names or values in a dialog before hitting the (web-based) “make it so” (OK) button. What could be more efficient? Well, telepathy maybe, but we’ll work on that and maybe discuss it sometime in the future. For now, the web-based Graphical User Interface (GUI) is still state of the art, thirteen years after webmin’s initial release.

But there is another way. Yes, that’s right, Windows PowerShell. Are you thinking “doesn’t that involve a lot of typing?” Are you worried that it’s hard to learn? Maybe. But you can effectively manage parts of SharePoint via PowerShell without knowing all of the possible management tools.

SharePoint Server 2010 comes with 531 sharepoint-specific cmdlets — little commands for sharepoint management. But that’s not all. When it is necessary to dive under the hood and check or adjust something in the Internet Information Services (IIS) underpinnings or other Windows Server configuration, including networking or Active Directory Domain Services (AD DS), hundreds more PowerShell cmdlets and functions await your beck and call.

But why? Why would you choose to use PowerShell when you already have the web administration interface? Automation. Reproducibility. Engineering. The same reasons we typically use PowerShell for many tasks. Let’s go back to an earlier concern you might have had: do you have to be a touch-typist to be allowed entry into the “PowerShell club?” No. Being a decent typist doesn’t hurt with PowerShell. Typing is required sometimes, as with the GUI, but in some cases, just once. There are several aspects of the SharePoint Management Shell that can be used to make administration easier. A few of these are remote administration, pipelines, scriptability, and good old fashioned copy-and–paste (or select-and-execute really).

PowerShell Logon Scripts Revisited

Just about a year ago, I posted an article here about using Windows PowerShell for logon scripts. <http://microsoftblog.globalknowledge.com/2009/09/14/power-to-the-people-windows-powershell-logon-scripts/>

As noted in that post, to start you off, I presented a “Basic” example (and I’m not referring to VisualBasic script here) in quoting a Microsoft example. Also in that post were several other tips such as “the scripts must be accessible at a path visible to the client” and (although I could have been more clear in my choice of words by adding “if”) “unqualified, therefore in the local folder – that PowerShell script will run at the same location as the VBscript.” In other words, I intentionally drew the dots yet didn’t connect them for you. But now I think it’s time that I spell it out and be more clear. Here’s a recent request from someone regarding last years post:

“Unfortunately, that sample is as useless as every time people quote it. It seems to be the standard accepted non-functional answer. The problem: c:scriptslogon.ps1
[…] The location of the logon script is never a mapped drive. It’s something like: %userdomain%sysvoldomain.comPolicies{AAD5280F-A3B7-4F65-B15B-27E6F92BA431}UserScriptsLogon.
So, the .vbs script mentioned is not going to know where it is and presumably the .ps1 script will be in the same location. Now please, it would be great if you could show us how one could actually run a logon script using powershell.” (ellipsis mine)

Indeed, I think that’s a great idea. Thanks for asking. Let’s start with one slight modification of that earlier example, and then go with the even more beautifully straightforward answer to the question without any fancy explicit paths.

Let’s treat the following as a proof of concept on which we’ll improve once you have it working in a test environment. Success with simple examples is often good prior to getting into realistic solutions. I hope this helps. If you have assigned the following VBscript as a logon script via Group Policy, it will reveal several things.

’ logon.vbs – brief example
set objShell = CreateObject( “Wscript.Shell” )
objShell.run( “powershell.exe -noexit c:scriptslogon.ps1” )

Before getting into what running that can reveal, let us consider a change from my earlier post. Assume that the contents of this c:scriptslogon.ps1 is as follows:

“Hello, world!”
“Thus is redirected at $(get-date)” >logon.$($(get-date).ticks).txt

What do you get when you run it? Two things. First, due to the -noexit parameter used when logon.vbs launches logon.ps1, the shell window stays open and reveals the current path to be that of the folder with the logon.vbs script. In other words, this is typically a UNC file sharing path into the GPO’s UserScriptsLogon folder. For example, for a certain GPO in the domain sp.wernerconsulting.com the path is:

sp.wernerconsulting.comSysVolsp.wernerconsulting.comPolicies{C7872F8D-79E0-4770-BCC4-8A4B6E1A6C33}UserScriptsLogon

Secondly, even though the logon.ps1 ran from the c:scripts folder, its current location is also in the GPO’s UserScriptsLogon folder. For example, the file created when the script runs is stored in that folder (if you have permissions to it).

So why does that basic example use the local path c:scriptslogon.ps1? Signing. If the PowerShell execution policy is set to RemoteSigned, the script will not run from the remote UNC path, even if you are testing this locally on a domain controller. For instance, if we changed logon.vbs to simply use either a relative path .locallogon.ps1 or implicitly local path locallogon.ps1 as follows, we would get a PSSecurityException “cannot be loaded … is not digitally signed. The script will not execute on the system.”

’ logon.vbs – same path example
set objShell = CreateObject( “Wscript.Shell” )
objShell.run( “powershell.exe -noexit locallogon.ps1” )

So we see in reality the .vbs script does intrinsically know where it is running and can easily launch a PowerShell script residing in the same location. Again, my older post included suggestions regarding not using -noexit yet including other parameters. But which remedy would you choose for the execution policy issue? We have several choices.

Option 1. Code sign the script file(s) used as logon scripts and use the “same path example” shown above for the .vbs glue. Alternately, another UNC path could be used beside that of the GPO’s subfolder, however the code signing would still be necessary.

Option 2. Adjust the execution policy. This approach also requires adjustment of the options used to run the script.

Option 3. Adjust the trusted locations relative to the code signing and execution policy.

Option 4. Use a local path for the script file repository and use the “basic example” referenced earlier as the .vbs glue. Note that Group Policy Preferences may be used to create the local script repository and populate it. Alternately, the script repository could be deployed using Group Policy software deployment. Note that in this is a local path rather than a mapped drive.

There are several other options, as well as permutations, details, rationale, ramifications, and possibilities for PowerShell logon script execution. I hope this helps. Please let me know of any further questions.

SharePoint 2010 Ribbonized Central Administration

In two earlier articles, we looked at the ribbon interface for end users and content managers, then site administrators. Certainly, since the ribbon interfaces were introduced in Microsoft Office 2007 applications, there has been a fair amount of time to refine concept and focus the functionality ands design of ribbon interfaces for systems administration. Now let’s look at some of the ways in which SharePoint 2010’s central administration has been designed to effectively utilize the ribbon style interface for ma management of SharePoint farms.

Central Administration in SharePoint Server 2010 includes a top-level list of categories both in a list on the left-hand side of the window, and as an icon, title, and list of tasks view reminiscent of the Windows Control Panel. There is no ribbon interface in the Browse view at this level, only a bar at the top sporting the Site Actions menu, Up button, Browse tab (selected by default), and Page tab. We’ll get back to the Page tab in a moment. First, here’s the list of top-level categories in Central Administration:
• Application Management
• System Settings
• Monitoring
• Backup and Restore
• Security
• Upgrade and Migration
• General Application Settings
• Configuration Wizards

Before delving into any of these exciting categories, let’s first see what ribbon controls we have right at the top level. Note that the Browse tab is selected by default. When pull (e.g. click or tap) on the Page tab, the content editing ribbon with Edit, Manage, Share & Track, Approval, Workflow, and Page Actions sections appears in place of the SharePoint 2010 Central Administration title bar. The buttons and menus under each section of this ribbon are Edit (Edit Page), Manage (Edit Properties, Versions, Permissions, Delete Page), Share & Track (E-mail a Link, Alert Me), Approval (Approve, Reject), Workflow (Workflows), and Page Actions (Edit Mobile Page, Make Homepage, Title Bar Properties). But we’re not here to focus on that since this is an example of a content ribbon.

In order to see the true Central Administration ribbon in action, let’s choose an example category and management task. The Application Management category’s Manage web applications task is a good example. To navigate there, one way is to hit the Application Management link on the left, then choose the “Manage web applications” link under the Web Applications subcategory in the center of the administration window. A more direct approach is to simply choose the “Manage web application” link under the Application Management category in the middle pane right from the top level of Central Administration. These two approaches are possible for this particular example because “Manage web applications” happens to be one of those chosen tasks listed at the top level category view.

Now, after you’ve selected the Manage web applications task, the Web Applications tab (next to Browse) should show a list of your SharePoint farm’s current web applications showing the Name, URL, and Port of each. At a minimum, in a test environment, you should have a basic content site (e.g. SharePoint – 80) and Central Administration (e.g. SharePoint Central Administration v4). Above this list is the ribbon with Contribute, Manage, Security, and Policy sections. If you have not selected an application from the list below the ribbon, your only option initially is likely the “New” button in the Contribute section.

Once you have selected a web application from the list, the other actions may be enabled, depending on your permissions. The buttons in the Web Applications ribbon are, per section, Contribute (New, Extend, Delete), Manage (General Settings, Manage Features, Managed Paths, Service Connections), Security (Authentication, Self-Service Site Creation), Blocked File Types, User Permissions, Web Part Security), and Policy (User Policy, Anonymous Policy, and Permission Policy). The densely well organized elegance of this interface is a significant advantage over SharePoint 2007’s Central Administration while supporting administration of many new features.

The ribbon’s menus, buttons, and other controls are context-sensitive – the options present change based on the management task you’ve selected. For example, the Service Applications ribbon offers different sections and buttons than the Web Applications ribbon. Once you get used to SharePoint 2010 Central Administration’s navigation and the ribbon interface, I hope that you will soon forget the relatively cumbersome old SharePoint 2007 Central Administration interface, no matter how fluent and comfortable you had been with it.

Exchange Server 2010 SP1: Mailbox Export and Import

With Exchange Server 2010 SP1 in the wild now, many organizations who are still hosting their messaging services with Exchange Server 2003 or 2007 or other platforms are finally looking to upgrade to Exchange Server 2010, but with this latest service pack included with the upgrade. True, many other companies have already migrated to Exchange Server 2010, yet the new wave includes those others that typically wait for the first service pack of operating systems and other services.

Most often, Exchange Server 2010 SP1 will be hosted on Windows Server 2008 R2 which released around the time as E2010 debuted in November 2009.

Features such as role-based modularity, management with PowerShell, and unified messaging which debuted with Exchange 2007 are seemingly old hat to some people, having released over three and a half years ago. However, organizations who are already running E2007 or even E2010 without the recent service pack still have numerous new features to look forward to, while those still using E2003 or other technologies are in for a humongous wealth of new features.

Let’s focus on some changes which come with E2010 SP1 related to export and import of mailbox data. Some of these changes are associated with changes to the processing of mailbox moves. The Microsoft Exchange Mailbox Replication service (MRS) facilitates the heavy lifting, but it is Exchange Management Shell (EMS) cmdlets which are used to drive the process.

Two cmdlets, New-MailboxExportRequest and New-MailboxImportRequest are used to initiate migration of messages to or from a .PST data file and from or to an Exchange mailbox. Let’s consider the export direction first. New-MailboxExportRequest can set up the export of either a primary mailbox or a mailbox archive. In its simplest form, this cmdlet takes a mailbox identifier and a .PST file path, for example:

New-MailboxExportRequest -Mailbox brad.werner@sp.wernerconsulting.com `
-FilePath sp.wernerconsulting.compst-rootwbrad-werner.pst

In this example, the mailbox is identified using the SMTP address <brad.werner@sp.wernerconsulting.com>. Alternately, either the alias or display name for the mailbox could have been specified. If the -IsArchive parameter had also been included in the New-MailboxExportRequest then the user’s archive would have been used instead of their primary mailbox.

Next, the file path is indicated, which should be in UNC file sharing format rather than a local path. This requirement is due to the nature of the export operation. The Mailbox Replication service that actually performs the export operation is hosted on an Exchange server with running the Client Access Server role. The New-MailboxExportRequest could be submitted (this cmdlet run) from a workstation with the management tools, or any Exchange server within the organization. Not only must this path be visible to the replication service, but Read+Write permissions should be granted at both the NTFS and SMB/CIFS share levels so that members of the Exchange Trusted Subsystem group have access.

Other parameters of note are the -IncludeFolders and -ExcludeFolders parameters, each which allow the specification of lists of folders to include or not include in the export. Because each export may not include all folders for a particular mailbox, it could be useful to perform several separate export operations on the same mailbox, generating separate .PST files from distinct sets of folders from the mailbox.

If you have submitted several unique export requests simultaneously, care must be taken to ensure that their request identifiers are indeed unique as well. If you do not explicitly supply a request identifier in the request, New-MailboxExportRequest will provide one using the default naming scheme like “brad.wernerMailboxExport0” in which the alias is used before the backslash, and sequential numbers zero through nine are appended after the literal string MailboxExport. Thus, up to ten unique request IDs can be provided per mailbox by New-MailboxExportRequest. In order to explicitly supply an identifier, simply use the -Name parameter in the request. The supplied name is used in place of the default MailboxExportn after the alias and backslash, thus -Name Xyzzy would result in a request identifier of brad.wernerXyzzy.

The New-MailboxImportRequest cmdlet can be used in similar fashion, with the flow of mailbox data going in reverse. With the import, the data comes from the .PST file and is brought into the Exchange mailbox.

Naturally, Get-, Set-, Suspend-, Resume-, and Remove- verbs can be used for MailboxImportRequest and MailboxExportRequest nouns as well by virtue of ten more corresponding cmdlets. Exchange 2010 SP1 also supports two related statistics cmdlets: Get-MailboxExportRequestStatistics and Get-MailboxImportRequestStatistics which be used to track activity of a particular request, activity related to a particular database, or requests hosted by a particular server running the Mailbox Replication service (MRS).

The mailbox import/export functionality hosted by the Mailbox Replication service on client access server(s), without the need to have Outlook installed to perform the transfers is one of many great features of Exchange Server 2010 SP1.