SqlProtocol

SqlProtocol

Parameters

Parameter	Attribute	DataType	Description	Allowed Values
InstanceName	Key	String	Specifies the name of the SQL Server instance to enable the protocol for.
ProtocolName	Key	String	Specifies the name of network protocol to be configured.	SharedMemory, NamedPipes, TcpIp
ServerName	Write	String	Specifies the host name of the SQL Server to be configured. If the SQL Server belongs to a cluster or availability group specify the host name for the listener or cluster group. Default value is the current computer name.
Enabled	Write	Boolean	Specifies if the protocol should be enabled or disabled.
ListenOnAllIpAddresses	Write	Boolean	Specifies to listen on all IP addresses. Only used for the TCP/IP protocol, ignored for all other protocols.
KeepAlive	Write	SInt32	Specifies the keep alive duration in milliseconds. Only used for the TCP/IP protocol, ignored for all other protocols.
PipeName	Write	String	Specifies the name of the named pipe. Only used for the Named Pipes protocol, ignored for all other protocols.
SuppressRestart	Write	Boolean	If set to $true then the any attempt by the resource to restart the service is suppressed. The default value is $false.
RestartTimeout	Write	UInt16	Timeout value for restarting the SQL Server services. The default value is 120 seconds.
HasMultiIPAddresses	Read	Boolean	Returns $true or $false whether the instance has multiple IP addresses or not.

Description

The SqlProtocol DSC resource manages the SQL Server protocols for a SQL Server instance.

For more information about protocol properties look at the following articles:

• TCP/IP Properties (Protocols Tab).
• Shared Memory Properties.
• Named Pipes Properties.

Requirements

• Target machine must be running Windows Server 2012 or later.
• Target machine must be running SQL Server Database Engine 2012 or later.
• Target machine must have access to the SQLPS PowerShell module or the SqlServer PowerShell module.
• If a protocol is disabled that prevents the cmdlet Restart-SqlService from contacting the instance to evaluate if it is a cluster. If this is the case then the parameter SuppressRestart must be used to override the restart. It is the same if a protocol is enabled that was previously disabled and no other protocol allows connecting to the instance, then the parameter SuppressRestart must also be used.
• When connecting to a Failover Cluster where the account SYSTEM does not have access then the correct credential must be provided in the built-in parameter PSDscRunAsCredential. If not the following error can appear; An internal error occurred.
• When using the resource against an SQL Server 2022 instance, the module SqlServer v22.0.49-preview or newer must be installed.

Known issues

All issues are not listed here, see here for all open issues.

Examples

Example 1

This example will enable the TCP/IP protocol, set the protocol to listen on all IP addresses, and set the keep alive duration.

The resource will be run as the account provided in $SystemAdministratorAccount.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $SystemAdministratorAccount
    )

    Import-DscResource -ModuleName 'SqlServerDsc'

    node localhost
    {
        SqlProtocol 'ChangeTcpIpOnDefaultInstance'
        {
            InstanceName           = 'MSSQLSERVER'
            ProtocolName           = 'TcpIp'
            Enabled                = $true
            ListenOnAllIpAddresses = $false
            KeepAlive              = 20000

            PsDscRunAsCredential   = $SystemAdministratorAccount
        }
    }
}

Example 2

This example will enable the Named Pipes protocol and set the name of the pipe.

The resource will be run as the account provided in $SystemAdministratorAccount.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $SystemAdministratorAccount
    )

    Import-DscResource -ModuleName 'SqlServerDsc'

    node localhost
    {
        SqlProtocol 'ChangeTcpIpOnDefaultInstance'
        {
            InstanceName         = 'MSSQLSERVER'
            ProtocolName         = 'NamedPipes'
            Enabled              = $true
            PipeName             = '\\.\pipe\$$\TESTCLU01A\MSSQL$SQL2014\sql\query'

            PsDscRunAsCredential = $SystemAdministratorAccount
        }
    }
}

Example 3

This example will enable the Shared Memory protocol.

The resource will be run as the account provided in $SystemAdministratorAccount.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $SystemAdministratorAccount
    )

    Import-DscResource -ModuleName 'SqlServerDsc'

    node localhost
    {
        SqlProtocol 'ChangeTcpIpOnDefaultInstance'
        {
            InstanceName         = 'MSSQLSERVER'
            ProtocolName         = 'SharedMemory'
            Enabled              = $true

            PsDscRunAsCredential = $SystemAdministratorAccount
        }
    }
}

Example 4

This example will disable the TCP/IP protocol.

The resource will be run as the account provided in $SystemAdministratorAccount.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $SystemAdministratorAccount
    )

    Import-DscResource -ModuleName 'SqlServerDsc'

    node localhost
    {
        SqlProtocol 'ChangeTcpIpOnDefaultInstance'
        {
            InstanceName           = 'MSSQLSERVER'
            ProtocolName           = 'TcpIp'
            Enabled                = $false

            PsDscRunAsCredential   = $SystemAdministratorAccount
        }
    }
}

Example 5

This example will disable the Named Pipes protocol.

The resource will be run as the account provided in $SystemAdministratorAccount.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $SystemAdministratorAccount
    )

    Import-DscResource -ModuleName 'SqlServerDsc'

    node localhost
    {
        SqlProtocol 'ChangeTcpIpOnDefaultInstance'
        {
            InstanceName           = 'MSSQLSERVER'
            ProtocolName           = 'NamedPipes'
            Enabled                = $false

            PsDscRunAsCredential   = $SystemAdministratorAccount
        }
    }
}

Example 6

This example will disable the Shared Memory protocol.

The resource will be run as the account provided in $SystemAdministratorAccount.

Configuration Example
{
    param
    (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $SystemAdministratorAccount
    )

    Import-DscResource -ModuleName 'SqlServerDsc'

    node localhost
    {
        SqlProtocol 'ChangeTcpIpOnDefaultInstance'
        {
            InstanceName           = 'MSSQLSERVER'
            ProtocolName           = 'SharedMemory'
            Enabled                = $false

            PsDscRunAsCredential   = $SystemAdministratorAccount
        }
    }
}