Get-NetFirewallHyperVRule

Module:

NetSecurity

Retrieves Hyper-V firewall rules from the target computer.

Syntax

Get-NetFirewallHyperVRule
   [-All]
   [-PolicyStore <string>]
   [-CimSession <CimSession[]>]
   [-ThrottleLimit <int>]
   [-AsJob]
   [<CommonParameters>]

Get-NetFirewallHyperVRule
   [-Name] <string[]>
   [-PolicyStore <string>]
   [-CimSession <CimSession[]>]
   [-ThrottleLimit <int>]
   [-AsJob] 
   [<CommonParameters>]

Get-NetFirewallHyperVRule
   -DisplayName <string[]>
   [-PolicyStore <string>]
   [-CimSession <CimSession[]>]
   [-ThrottleLimit <int>]
   [-AsJob] 
   [<CommonParameters>]

Get-NetFirewallHyperVRule
   [-Direction {Inbound | Outbound}]
   [-VMCreatorId <string[]>]
   [-Protocol <string[]>]
   [-Action {NotConfigured | Allow | Block}]
   [-Enabled {True | False}]
   [-EnforcementStatus {Unknown | OK | PartiallyEnforced | NoApplicablePorts | ParsingError | Error}]
   [-PolicyStoreSourceType {None | Local | GroupPolicy | Dynamic | Generated | Hardcoded | MDM | HostFirewallLocal | HostFirewallGroupPolicy | HostFirewallDynamic | HostFirewallMDM}]
   [-PolicyStore <string>]
   [-CimSession <CimSession[]>]
   [-ThrottleLimit <int>]
   [-AsJob]
   [<CommonParameters>]

Description

The Get-NetFirewallHyperVRule cmdlet returns the instances of the Hyper-V firewall rules that match the search parameters of the user. See the New-NetFirewallHyperVrule cmdlet for more information.

This cmdlet returns one or more Hyper-V firewall rules by specifying the Name parameter, the DisplayName parameter, or rule properties. The queried rules can be placed into variables and piped to other cmdlets for further modifications.

In addition to the rule parameters, a read-only field called 'PortStatuses' will be enumerated. A Hyper-V firewall rule is applied to individual Hyper-V firewall ports based on the rule parameters. This output displays all Hyper-V ports that this rule is currently applied to.

Examples

EXAMPLE 1

PS C:\> Get-NetFirewallHyperVRule -PolicyStore ActiveStore

This example retrieves all the Hyper-V firewall rules in the active store, which is a collection of all the policy stores that apply to the computer. Running this cmdlet without specifying the policy store retrieves the persistent store.

EXAMPLE 2

PS C:\> Get-NetFirewallHyperVRule -EnforcementStatus OK

This example retrieves all the Hyper-V firewall rules with EnforcementStatus OK, which means that the rule is active and being enforced.

EXAMPLE 3

PS C:\> Get-NetFirewallHyperVRule -Name 'MyRuleId'

This example retrieves the Hyper-V firewall rule with the Name 'MyRuleId'

Parameters

-Action

Specifies that matching Hyper-V firewall rules of the indicated action are retrieved. The acceptable values for this parameter are: Allow or Block.

• Allow: Network packets that match all criteria specified in this rule are permitted through the firewall. This is the default value.
• Block: Network packets that match all criteria specified in this rule are dropped by the firewall.

Type:	Action
Accepted values:	NotConfigured, Allow, Block
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-AsJob

Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CimSession

Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a New-CimSession or Get-CimSession cmdlet. The default is the current session on the local computer.

Type:	CimSession[]
Aliases:	Session
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Direction

Specifies that matching Hyper-V firewall rules of the indicated direction are retrieved. This parameter specifies which direction of traffic to match with this rule. The acceptable values for this parameter are: Inbound or Outbound.

Type:	Direction
Accepted values:	Inbound, Outbound
Position:	Named
Default value:	Inbound
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-DisplayName

Specifies that only matching Hyper-V firewall rules of the indicated display name are retrieved. Wildcard characters are accepted.

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Enabled

Specifies that matching Hyper-V firewall rules of the indicated state are retrieved. This parameter specifies that the rule object is administratively enabled or administratively disabled. The acceptable values for this parameter are:

• True: Specifies the rule is currently enabled.
• False: Specifies the rule is currently disabled.

Note that the type of this parameter is not Boolean, therefore $true and $false variables are not acceptable values here. Use "True" and "False" text strings instead.

A disabled rule will not actively modify computer behavior, but the management construct still exists on the computer so it can be re-enabled.

Type:	Enabled
Accepted values:	True, False
Position:	Named
Default value:	True
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-EnforcementStatus

Specifies that firewall rules that match the indicated enforcement status are retrieved. This parameter specifies the overall status of the rule.

• OK: Specifies that the rule will work as specified.
• PartiallyEnforced: Specifies that one or more parts of the rule will not be enforced.
• NoApplicablePorts: Specifies that the rule is functioning as expected, but there are no ports applicable for this rule and therefore is not active.
• ParsingError: Specifies that the rule is corrupted and the computer is unable to use the rule at all.
• Error: Specifies that the computer is unable to use the rule at all.

Type:	PrimaryStatus[]
Accepted values:	Unknown, OK, Inactive, Error
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Name

Specifies that only matching Hyper-V firewall rules of the indicated name are retrieved. This name serves as the unique identifier for this rule. This parameter acts just like a file name, in that only one rule with a given name may exist in a policy store at a time.

Type:	String
Aliases:	ID
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PolicyStore

Targets the policy store from which to retrieve the rules. A policy store is a container for firewall policy. The acceptable values for this parameter are:

• PersistentStore: Sometimes called static rules, this store contains the persistent policy for the local computer. This policy is not from GPOs, and has been created manually or programmatically (during application installation) on the computer. Rules created in this store are attached to the ActiveStore and activated on the computer immediately.
• ActiveStore: This store contains the currently active policy, which is the sum of all policy stores that apply to the computer.
• SystemDefaults: This read-only store contains the default state of firewall rules.
• MDM: This store contains the rules configured via MDM.

By default, the PersistentStore is queried.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PolicyStoreSourceType

Specifies that Hyper-V firewall rules that match the indicated policy store source type are retrieved. This parameter value is automatically generated and should not be modified. The acceptable values for this parameter are:

• Local: The object originates from the local store.
• MDM: The object originates from the MDM store.
• Dynamic: The object originates from the dynamic store.
• HostFirewallLocal: This object originates from the host windows firewall local store.
• HostFirewallGroupPolicy: This object originates from the host windows firewall group policy store.
• HostFirewallMDM: This object originates from the host windows firewall MDM store.

By default, the Local store is queried.

Type:	PolicyStoreType[]
Accepted values:	None, Local, MDM
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Protocol

Specifies that only matching Hyper-V firewall rules with the indicated protocol are retrieved.

The acceptable values for this parameter are:

• Protocols by number: 0-255.
• Protocols by name: TCP, UDP, ICMPv4, or ICMPv6.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ThrottleLimit

Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If this parameter is omitted or a value of 0 is entered, Windows PowerShell calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer.

The throttle limit applies only to the current cmdlet, not to the session or to the computer.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-VMCreatorId

Specifies that only matching Hyper-V firewall rules with the specified VMCreatorId are retrieved. The format for this value is a GUID enclosed in brackets: '{9E288F02-CE00-4D9E-BE2B-14CE463B0298}'.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Inputs

None

Outputs

CimInstance

The Microsoft.Management.Infrastructure.CimInstance object is a wrapper class that displays Windows Management Instrumentation (WMI) objects. The path after the pound sign (#) provides the namespace and class name for the underlying WMI object.

Related Links

• New-NetFirewallHyperVRule
• Enable-NetFirewallHyperVRule
• Disable-NetFirewallHyperVRule
• Remove-NetFirewallHyperVRule
• Rename-NetFirewallHyperVRule
• Set-NetFirewallHyperVRule
• Get-NetfirewallHyperVPort
• Get-NetfirewallHyperVVMCreator