SPFarm

SPFarm

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
IsSingleInstance	Key	String	Specifies the resource is a single instance, the value must be 'Yes'	Yes
Ensure	Write	String	Present to create/join the farm. Absent is currently not supported	Present, Absent
FarmConfigDatabaseName	Required	String	Name of the configuration database
DatabaseServer	Required	String	Server that will host the configuration and admin content databases
FarmAccount	Required	PSCredential	The account to use as the main farm account
Passphrase	Required	PSCredential	The passphrase to use to allow servers to join this farm
AdminContentDatabaseName	Required	String	The name of the admin content database
RunCentralAdmin	Required	Boolean	Should the central admin site run on this specific server?
CentralAdministrationUrl	Write	String	Vanity URL for Central Administration
CentralAdministrationPort	Write	UInt32	What port will Central Admin be provisioned to - default is 9999
CentralAdministrationAuth	Write	String	The authentication provider of the CentralAdministration web application	NTLM, Kerberos
ServerRole	Write	String	SharePoint 2016 & 2019 only - the MinRole role to enroll this server as	Application, ApplicationWithSearch, Custom, DistributedCache, Search, SingleServerFarm, WebFrontEnd, WebFrontEndWithDistributedCache
DeveloperDashboard	Write	String	Specifies the state of the Developer Dashboard ('OnDemand' is SP2013 only)	Off, On, OnDemand
ApplicationCredentialKey	Write	PSCredential	Specifies the application credential key on the local server. Only supported for SP2019.
SkipRegisterAsDistributedCacheHost	Write	Boolean	Set to true to not register the server computer as a distributed cache host
UseSQLAuthentication	Write	Boolean	Should SQL Server authentication be used to connect to the database?
DatabaseCredentials	Write	PSCredential	If using SQL authentication, the SQL login to use to connect to the instance

Description

Type: Specific Requires CredSSP: No

This resource is used to create a new SharePoint farm and allow servers to join that farm. It will detect the presence of the configuration database on the SQL server as a first step, and if it does not exist then the farm will be created. If the database does exist, the server will join that configuration database. Once the config DB has been created, the resource will install local help collections, secure resources and activate features.

If the central admin site is to be running on the local server, the RunCentralAdmin property should be set to true. In the event that the central admin site has not been provisioned, this resource will first create it, otherwise it will simply start the central admin service instance on the local server.

The passphrase is passed as a Credential object.The username of this credential is ignored, only the value of the password is used as the farm passphrase.

The port of the Central Admin website can be set by using the CentralAdministrationPort property. If this is not defined, the site will be provisioned on port 9999 unless the CentralAdministrationUrl property is specified and begins with https, in which case it will default to port 443. The port number in CentralAdministrationPort and CentralAdministrationUrl must match if both parameters are specified. It is not recommended to include port number 80 and 443 in the CentralAdministrationUrl parameter. This will automatically follow the URL shceme http (80) and https (443) specified. CentralAdministrationPort is an optional parameter and can be omitted if the port is specified in CentralAdministrationUrl, or if default ports for http/https is used (no port is required to be specified). However, this setting will not impact existing deployments that already have Central Admin provisioned on another port. Also, when a farm is created, the current behavior is to not enroll the server as a cache server (which is the default behavior of SharePoint). This means you need to use SPDistributedCacheService on at least one server in the farm to designate it as a cache server.

CentralAdministrationAuth can be specified as "NTLM" or "KERBEROS". If not specified, it defaults to NTLM. If using Kerberos, make sure to have appropriate SPNs setup for Farm account and Central Administration URI.

To provision Central Admin on a vanity URL instead of the default http(s)://servername:port, use the CentralAdministrationUrl parameter. Central Admin will be provisioned as an SSL web application if this URL begins with HTTPS, and will default to port 443.

DeveloperDashboard can be specified as "On", "Off" and (only when using SharePoint 2013) to "OnDemand".

ApplicationCredentialKey is used to set the application credential key on the local server, which is used by certain features to encrypt and decrypt passwords. The application credential key will only be set during initial farm creation and when joining the farm. The ApplicationCredentialKey needs to be the same on each server in the farm. ApplicationCredentialKey is only supported for SharePoint 2019.

If SkipRegisterAsDistributedCacheHost is set to true, the server is not registered as a distributed cache host.

NOTE: When using SharePoint 2016 and later and enabling the Developer Dashboard, please make sure you also provision the Usage and Health service application to make sure the Developer Dashboard works properly.

NOTE2: Since v4.4 the resource supports the use of precreated databases.

Examples

Example 1

This example shows how a basic SharePoint farm can be created. The database server and names are specified, and the accounts to run the setup as, the farm account and the passphrase are all passed in to the configuration to be applied. By default the central admin site in this example is provisioned to port 9999 using NTLM authentication.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $FarmAccount,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $SetupAccount,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $Passphrase
    )

    Import-DscResource -ModuleName SharePointDsc

    node localhost
    {
        SPFarm SharePointFarm
        {
            IsSingleInstance         = "Yes"
            DatabaseServer           = "SQL.contoso.local\SQLINSTANCE"
            FarmConfigDatabaseName   = "SP_Config"
            AdminContentDatabaseName = "SP_AdminContent"
            Passphrase               = $Passphrase
            FarmAccount              = $FarmAccount
            RunCentralAdmin          = $true
            PsDscRunAsCredential     = $SetupAccount
        }
    }
}

Example 2

This example shows how a basic SharePoint farm can be created. The database server and names are specified, and the accounts to run the setup as, the farm account and the passphrase are all passed in to the configuration to be applied. Here the port for the central admin site to run on, as well as the authentication mode for the site are also specified.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $FarmAccount,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $SetupAccount,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $Passphrase
    )

    Import-DscResource -ModuleName SharePointDsc

    node localhost
    {
        SPFarm SharePointFarm
        {
            IsSingleInstance          = "Yes"
            DatabaseServer            = "SQL.contoso.local\SQLINSTANCE"
            FarmConfigDatabaseName    = "SP_Config"
            AdminContentDatabaseName  = "SP_AdminContent"
            CentralAdministrationPort = 5000
            CentralAdministrationAuth = "Kerberos"
            Passphrase                = $Passphrase
            FarmAccount               = $FarmAccount
            RunCentralAdmin           = $true
            PsDscRunAsCredential      = $SetupAccount
        }
    }
}

Example 3

This example shows how a basic SharePoint farm can be created. The database server and names are specified, and the accounts to run the setup as, the farm account and the passphrase are all passed in to the configuration to be applied. By default the central admin site in this example is provisioned to port 9999 using NTLM authentication. In this example we also see the server role defined as "Application" which tells SharePoint 2016/2019 the role to apply to this server as soon as the farm is created. This property is not supported for SharePoint 2013 and so this specific example would fail if used against that verison.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $FarmAccount,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $SetupAccount,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $Passphrase
    )

    Import-DscResource -ModuleName SharePointDsc

    node localhost
    {
        SPFarm SharePointFarm
        {
            IsSingleInstance         = "Yes"
            DatabaseServer           = "SQL.contoso.local\SQLINSTANCE"
            FarmConfigDatabaseName   = "SP_Config"
            AdminContentDatabaseName = "SP_AdminContent"
            ServerRole               = "Application"
            Passphrase               = $Passphrase
            FarmAccount              = $FarmAccount
            RunCentralAdmin          = $true
            PsDscRunAsCredential     = $SetupAccount
        }
    }
}

Example 4

This example shows how a basic SharePoint farm can be created. The database server and names are specified, and the accounts to run the setup as, the farm account and the passphrase are all passed in to the configuration to be applied. The application credential key is also specified. This configuration is only supported with SharePoint 2019. By default the central admin site in this example is provisioned to port 9999 using NTLM authentication.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [PSCredential]
        $FarmAccount,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $SetupAccount,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $Passphrase,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $ApplicationCredentialKey
    )

    Import-DscResource -ModuleName SharePointDsc

    node localhost
    {
        SPFarm SharePointFarm
        {
            IsSingleInstance         = "Yes"
            DatabaseServer           = "SQL.contoso.local\SQLINSTANCE"
            FarmConfigDatabaseName   = "SP_Config"
            AdminContentDatabaseName = "SP_AdminContent"
            Passphrase               = $Passphrase
            FarmAccount              = $FarmAccount
            ApplicationCredentialKey = $ApplicationCredentialKey
            RunCentralAdmin          = $true
            PsDscRunAsCredential     = $SetupAccount
        }
    }
}