New-DbaFirewallRule

Want to see the source code for this command? Check out New-DbaFirewallRule on GitHub.
Want to see the Bill Of Health for this command? Check out New-DbaFirewallRule.

Synopsis

Creates a new inbound firewall rule for a SQL Server instance and adds the rule to the target computer.

Description

Creates a new inbound firewall rule for a SQL Server instance and adds the rule to the target computer.

This is basically a wrapper around New-NetFirewallRule executed at the target computer.
So this only works if New-NetFirewallRule works on the target computer.

Both DisplayName and Name are set to the same value, since DisplayName is required
but only Name uniquely defines the rule, thus avoiding duplicate rules with different settings.
The names and the group for all rules are fixed to be able to get them back with Get-DbaFirewallRule.

The functionality is currently limited. Help to extend the functionality is welcome.

As long as you can read this note here, there may be breaking changes in future versions.
So please review your scripts using this command after updating dbatools.

The firewall rule for the instance itself will have the following configuration (parameters for New-NetFirewallRule):

DisplayName = 'SQL Server default instance' or 'SQL Server instance <InstanceName>'  
Name        = 'SQL Server default instance' or 'SQL Server instance <InstanceName>'  
Group       = 'SQL Server'  
Enabled     = 'True'  
Direction   = 'Inbound'  
Protocol    = 'TCP'  
LocalPort   = '<Port>' (for instances with static port)  
Program     = '<Path ending with MSSQL\Binn\sqlservr.exe>' (for instances with dynamic port)  

The firewall rule for the SQL Server Browser will have the following configuration (parameters for New-NetFirewallRule):

DisplayName = 'SQL Server Browser'  
Name        = 'SQL Server Browser'  
Group       = 'SQL Server'  
Enabled     = 'True'  
Direction   = 'Inbound'  
Protocol    = 'UDP'  
LocalPort   = '1434'  

The firewall rule for the dedicated admin connection (DAC) will have the following configuration (parameters for New-NetFirewallRule):

DisplayName = 'SQL Server default instance (DAC)' or 'SQL Server instance <InstanceName> (DAC)'  
Name        = 'SQL Server default instance (DAC)' or 'SQL Server instance <InstanceName> (DAC)'  
Group       = 'SQL Server'  
Enabled     = 'True'  
Direction   = 'Inbound'  
Protocol    = 'TCP'  
LocalPort   = '<Port>' (typically 1434 for a default instance, but will be fetched from ERRORLOG)  

The firewall rule for the DAC will only be created if the DAC is configured for listening remotely.
Use Set-DbaSpConfigure -SqlInstance SRV1 -Name RemoteDacConnectionsEnabled -Value 1 to enable remote DAC before running this command.

Syntax

New-DbaFirewallRule
    [-SqlInstance] <DbaInstanceParameter[]>
    [[-Credential] <PSCredential>]
    [[-Type] <String[]>]
    [[-Configuration] <Hashtable>]
    [-Force]
    [-EnableException]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> New-DbaFirewallRule -SqlInstance SRV1, SRV1\TEST

Automatically configures the needed firewall rules for both the default instance and the instance named TEST on SRV1.

Example: 2

PS C:\> New-DbaFirewallRule -SqlInstance SRV1, SRV1\TEST -Configuration @{ Profile = 'Domain' }

Automatically configures the needed firewall rules for both the default instance and the instance named TEST on SRV1,
but configures the firewall rule for the domain profile only.

Example: 3

PS C:\> New-DbaFirewallRule -SqlInstance SRV1\TEST -Type Engine -Force -Confirm:$false

Creates or recreates the firewall rule for the instance TEST on SRV1. Does not prompt for confirmation.

Required Parameters

-SqlInstance

The target SQL Server instance or instances.

Optional Parameters

-Credential

Credential object used to connect to the Computer as a different user.

-Type

Creates firewall rules for the given type(s).
Valid values are:

• Engine - for the SQL Server instance
• Browser - for the SQL Server Browser
• DAC - for the dedicated admin connection (DAC)
  If this parameter is not used:
• The firewall rule for the SQL Server instance will be created.
• In case the instance is listening on a port other than 1433, also the firewall rule for the SQL Server Browser will be created if not already in place.
• In case the DAC is configured for listening remotely, also the firewall rule for the DAC will be created.
  

-Configuration

A hashtable with custom configuration parameters that are used when calling New-NetFirewallRule.
These will override the default settings.
Parameters Name, DisplayName and Group are not allowed here and will be silently ignored.
https://docs.microsoft.com/en-us/powershell/module/netsecurity/new-netfirewallrule

-Force

If the rule to be created already exists, a warning is displayed.
If this switch is enabled, the rule will be deleted and created again.

-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own try/catch.

-WhatIf

If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.

-Confirm

If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.