New-DbaFirewallRule

Synopsis

Creates Windows firewall rules for SQL Server instances to allow network connectivity

Description

Creates inbound Windows firewall rules for SQL Server instances, Browser service, and Dedicated Admin Connection (DAC) to allow network connectivity.
This automates the tedious post-installation task of configuring firewall access for SQL Server, eliminating the need to manually determine ports and create rules through Windows Firewall GUI or netsh commands.

By default, the function creates program-based firewall rules that target SQL Server executables (sqlservr.exe, sqlbrowser.exe).
This approach allows instances to work regardless of port configuration changes - named instances on different ports or default instances on non-standard ports are automatically allowed without needing to update firewall rules.
Alternatively, you can use -RuleType Port to create traditional port-based firewall rules.

This is a wrapper around New-NetFirewallRule executed remotely on the target computer via Invoke-Command2.
Both DisplayName and Name are set to the same value to ensure unique rule identification and prevent duplicates.
All rules use the “SQL Server” group for easy management 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.

With -RuleType Program (default), 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'  
Program     = '<Path ending with MSSQL\Binn\sqlservr.exe>'  

With -RuleType Port, 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>'  

With -RuleType Program (default), 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    = 'Any'  
Program     = '<Path ending with sqlbrowser.exe>'  

With -RuleType 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.

The firewall rule for database mirroring or Availability Groups will have the following configuration (parameters for New-NetFirewallRule):

DisplayName = 'SQL Server default instance (DatabaseMirroring)' or 'SQL Server instance <InstanceName> (DatabaseMirroring)'  
Name        = 'SQL Server default instance (DatabaseMirroring)' or 'SQL Server instance <InstanceName> (DatabaseMirroring)'  
Group       = 'SQL Server'  
Enabled     = 'True'  
Direction   = 'Inbound'  
Protocol    = 'TCP'  
LocalPort   = '5022' (can be overwritten by using the parameter Configuration)

Syntax

New-DbaFirewallRule
    [-SqlInstance] <DbaInstanceParameter[]>
    [[-Credential] <PSCredential>]
    [[-Type] <String[]>]
    [[-RuleType] <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.
By default, creates program-based rules targeting the SQL Server executables, allowing the instances to work regardless of port configuration changes.

Example: 2

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

Creates port-based firewall rules instead of the default program-based rules.
This creates traditional TCP/UDP port rules for the instances.

Example: 3

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: 4

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.

Example: 5

PS C:\> New-DbaFirewallRule -SqlInstance SQL01 -Type DatabaseMirroring

Creates the firewall rule for database mirroring or Availability Groups on the default instance on SQL01 using the default port 5022.

Example: 6

PS C:\> New-DbaFirewallRule -SqlInstance SQL02 -Type DatabaseMirroring -Configuration @{ LocalPort = '5023' }

Creates the firewall rule for database mirroring or Availability Groups on the default instance on SQL02 using the custom port 5023.

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

Specifies which firewall rule types to create for SQL Server network access.
Use this when you need to create specific rules instead of the automatic detection behavior.
Valid values are Engine (SQL Server instance), Browser (SQL Server Browser service), DAC (Dedicated Admin Connection) and DatabaseMirroring (database mirroring or Availability Groups). When omitted,
the function automatically creates Engine rules plus Browser rules for non-default ports and DAC rules when remote DAC is enabled.

-RuleType

Specifies how firewall rules identify SQL Server traffic - either by targeting the executable program or by targeting specific TCP/UDP ports.
Valid values are Program (targets sqlservr.exe and sqlbrowser.exe executables) and Port (targets TCP/UDP port numbers).
Defaults to Program, which allows instances to work regardless of port configuration changes (named instances on different ports, default instances on non-standard ports).
Use Port when you need traditional port-based rules or when Program-based rules cannot be created.
Note: DAC and DatabaseMirroring rules are always port-based regardless of this setting.

-Configuration

Provides custom settings to override the default firewall rule configuration when calling New-NetFirewallRule.
Use this when you need to restrict rules to specific network profiles (Domain, Private, Public) or modify other advanced firewall settings.
Common examples include @{Profile = ‘Domain’} to limit rules to domain networks only, or @{RemoteAddress = ‘192.168.1.0/24’} to restrict source IPs. The Name, DisplayName, and Group parameters are
reserved and will be ignored if specified.

-Force

Forces recreation of firewall rules that already exist by deleting and recreating them.
Use this when you need to update existing rules with new settings or when troubleshooting connectivity issues.
Without this switch, the function will warn you about existing rules and skip their creation.

-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.

Outputs

PSCustomObject

Returns one object per firewall rule created, providing comprehensive details about the rule configuration and creation status.

Default display properties (via Select-DefaultView):

• ComputerName: The name of the computer where the firewall rule was created
• InstanceName: The SQL Server instance name; $null for Browser rules
• SqlInstance: The full SQL Server instance name (computer\instance); $null for Browser rules
• DisplayName: The display name of the firewall rule (e.g., ‘SQL Server default instance’, ‘SQL Server Browser’)
• Type: The type of firewall rule created (Engine, Browser, DAC, DatabaseMirroring)
• Successful: Boolean indicating if the rule creation was successful
• Status: Human-readable status message describing the outcome (e.g., ‘The rule was successfully created.’, ‘The desired rule already exists. Use -Force to remove and recreate the rule.’)
• Protocol: The protocol type of the rule (TCP, UDP, or Any)
• LocalPort: The TCP/UDP port number for port-based rules; $null for Program-based rules
• Program: The executable program path for Program-based rules; $null for Port-based rules

*Additional properties available (using Select-Object ):

• Name: The internal name of the firewall rule (same as DisplayName)
• RuleConfig: Complete hashtable containing all New-NetFirewallRule parameters used to create the rule
• Details: PSCustomObject containing remote command execution details with properties:
• Successful: Boolean indicating overall success status
• CimInstance: The CIM instance object returned by New-NetFirewallRule
• Warning: Warning messages from rule creation (if any)
• Error: Error messages from rule creation (if any)
• Exception: Exception details if an error occurred (if any)