SharePoint 2010: PSConfig and PowerShell

The information in this article is based on BETA 2 of SharePoint 2010 - there may be differences with the RTM release.

Update 12/18/2009: I've updated the post to reflect BETA 2 changes and have considerably simplified the script removing all the dependencies on helper functions so that the core pieces required to build a basic farm are focused on rather than the complex elements to support tracing and error handling as I previously had it.

If you've ever done a scripted install of SharePoint 2007 then you are familiar with how to script the initial farm creation using psconfig.exe. Unfortunately psconfig is still with us in SharePoint 2010 but we do have some PowerShell cmdlets which replace all the psconfig commands.

Before we look at how to use PowerShell lets refresh our memories by looking at an install script for SharePoint 2007. I usually have two scripts, one for the first server and a second script for additional servers - here's the first script (I've omitted the variable declarations):

   1: ECHO %DATE% %TIME%:  Building configuration database

   2: psconfig -cmd configdb -create -server %SERVER_DB% -database %DB_CONFIG_NAME% -user %ACCT_SPFARM% -password %ACCT_SPFARM_PWD% -admincontentdatabase %DB_CENTRALADMINCONTENT_NAME% 

   3: if not errorlevel 0 goto errhnd

   4:  

   5: ECHO %DATE% %TIME%: Installing help content

   6: psconfig -cmd helpcollections -installall 

   7: if not errorlevel 0 goto errhnd

   8:  

   9: ECHO %DATE% %TIME%: Securing resources

  10: psconfig -cmd secureresources 

  11: if not errorlevel 0 goto errhnd

  12:  

  13: ECHO %DATE% %TIME%: Installing services

  14: psconfig -cmd services -install 

  15: if not errorlevel 0 goto errhnd

  16:  

  17: ECHO %DATE% %TIME%: Installing features

  18: psconfig -cmd installfeatures 

  19: if not errorlevel 0 goto errhnd

  20:  

  21: ECHO %DATE% %TIME%: Creating central admin site

  22: psconfig -cmd adminvs -provision -port %CENTRALADMIN_PORT% -windowsauthprovider enablekerberos 

  23: if not errorlevel 0 goto errhnd

  24:  

  25: ECHO %DATE% %TIME%: Adding application content to central admin site

  26: psconfig -cmd applicationcontent -install

  27: if not errorlevel 0 goto errhnd

  28:  

  29: goto end

  30:  

  31: :errhnd

  32:  

  33: echo An error occured - terminating script.

  34:  

  35: :end

And here's the second script (variable declarations omitted):

   1: ECHO %DATE% %TIME%: Connecting to farm

   2: psconfig -cmd configdb -connect -server %SERVER_DB% -database %DB_CONFIG_NAME% -user %ACCT_SPFARM% -password %ACCT_SPFARM_PWD%

   3: if not errorlevel 0 goto errhnd

   4:  

   5: ECHO %DATE% %TIME%: Installing services

   6: psconfig -cmd services install

   7: if not errorlevel 0 goto errhnd

   8:  

   9: ECHO %DATE% %TIME%: Installing features

  10: psconfig -cmd installfeatures

  11: if not errorlevel 0 goto errhnd

  12:  

  13: ECHO %DATE% %TIME%: Setting security on registry and file system

  14: psconfig -cmd secureresources

  15: if not errorlevel 0 goto errhnd

  16:  

  17: goto end

  18:  

  19: :errhnd

  20:  

  21: echo An error occured - terminating script.

  22:  

  23: :end

Obviously the two scripts are very similar with the main difference being the parameters passed to the configdb command and with fewer commands being called. So how would we do this using SharePoint 2010's PowerShell cmdlets? First lets list each psconfig command and what the PowerShell equivalent is:

PSConfig Command	PowerShell Cmdlet
configdb -create	New-SPConfigurationDatabase
configdb -connect	Connect-SPConfigurationDatabase
helpcollections -installall	Install-SPHelpCollection
secureresources	Initialize-SPResourceSecurity
services -install	Install-SPService
installfeatures	Install-SPFeature (provide the -AllExistingFeatures parameter)
adminvs -provision	New-SPCentralAdministration
applicationcontent -install	Install-SPApplicationContent

Now that we know what PowerShell cmdlets to use lets rework our install script. Instead of using a batch file for variables I'm going to use an XML file which can be read in and parsed as needed. I'm also going to make it so that you can run the same script from any server and just specify a switch parameter indicating whether or not you are connecting to an existing farm or not.

Let's first take a look at the XML that we'll use to manage our settings - we'll store this in a file called FarmConfigurations.xml:

<Farm FarmAccount="sp2010\spfarm" 
      ConfigDB="SharePoint_ConfigDB" 
      AdminContentDB="SharePoint_Content_Admin"
      DatabaseServer="spsql1" 
      Passphrase="Pa$$w0rd">
    <CentralAdmin Port="1234" AuthProvider="NTLM">
        <Servers>
            <Server Name="spsvr1" />
        </Servers>
    </CentralAdmin>
</Farm>

In this XML I'm storing the core farm settings in the <Farm /> element which includes attributes for the farm account to use as well as the database server and names for the configuration and central admin content database. I then have a <CentralAdmin /> element which contains the servers that the Central Admin site should be installed on along with the port and authentication provider to use.

So now that we have our configuration settings all we need now is the core script to actually create our farm. I named this script BuildFarm.ps1 but you can name it whatever you want:

function Install-SharePointFarm([bool]$connectToExisting, 
    [string]$settingsFile = "FarmConfigurations.xml") {
    
    [xml]$config = Get-Content $settingsFile

    $farmAcct = Get-Credential $config.Farm.FarmAccount

    $configDb = $config.Farm.ConfigDB
    $adminContentDb = $config.Farm.adminContentDb
    $server = $config.Farm.DatabaseServer
    if ($config.Farm.Passphrase.Length -gt 0) {
        $passphrase = (ConvertTo-SecureString $config.Farm.Passphrase `
            -AsPlainText -force)
    } else {
        Write-Warning "Using the Farm Admin's password for a passphrase"
        $passphrase = $farmAcct.Password
    }
    
    #Only build the farm if we don't currently have a farm created
    if (([Microsoft.SharePoint.Administration.SPFarm]::Local) -eq $null) {
        if ($connectToExisting) {
            #Connecting to farm
            Connect-SPConfigurationDatabase -DatabaseName $configDb `
                -DatabaseServer $server -Passphrase $passphrase
        } else {
            #Creating new farm
            New-SPConfigurationDatabase -DatabaseName $configDb `
                -DatabaseServer $server `
                -AdministrationContentDatabaseName $adminContentDb `
                -Passphrase $passphrase -FarmCredentials $farmAcct
        }
        #Verifying farm creation
        $spfarm = Get-SPFarm -ErrorAction SilentlyContinue -ErrorVariable err
        if ($spfarm -eq $null -or $err) {
            throw "Unable to verify farm creation."
        }
        
        #ACLing SharePoint Resources
        Initialize-SPResourceSecurity

        #Installing Services
        Install-SPService
        
        #Installing Features
        Install-SPFeature -AllExistingFeatures
    } else {
        Write-Warning "Farm already exists. Skipping creation."
    }
    
    $installSCA = (($config.Farm.CentralAdmin.Servers.Server | `
        where {$_.Name -eq $env:computername}) -ne $null)
    $url = "http://$($env:computername):$($config.Farm.CentralAdmin.Port)"
    $sca=[Microsoft.SharePoint.Administration.SPWebApplication]::Lookup($url)
    if ($installSCA -and $sca -eq $null) {
        #Provisioning Central Administration
        New-SPCentralAdministration -Port $config.Farm.CentralAdmin.Port `
            -WindowsAuthProvider $config.Farm.CentralAdmin.AuthProvider
       
        #Installing Help
        Install-SPHelpCollection -All

        #Installing Application Content
        Install-SPApplicationContent
    }
} 

Notice that the script takes a parameter which allows you to specify whether you are connecting to an existing farm. We can call the script using the following syntax (replace $false with $true if connecting to an existing farm):

PS C:\> . .\buildfarm.ps1
PS C:\> Install-SharePointFarm $false "FarmConfigurations.xml"

In a series of upcoming post I'll be building on what I created here by demonstrating how to create web applications and how to start each of the services that are included, including the extremely complex search service (gone are the days of a single line setup for search - we now have a dozen or so cmdlets that have to be run to get search started).