NOTE: This page is no longer being updated. To install the latest version of DSC Resource Kit, please use the PowerShell Gallery. If you need to report issues or would like to contribute to development, check out our GitHub Repositories.

Introduction

The xNetworking module is a part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit, which is a collection of DSC Resources produced by the PowerShell Team. This module contains the xFirewall, xIPAddress and xDnsServerAddress resources. These DSC Resources allow configuration of a node’s IP Address, DNS Server Address, and Firewall Rules.

All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service. The “x” in xNetworking stands for experimental, which means that these resources will be fix forward and monitored by the module owner(s).

Please leave comments, feature requests, and bug reports in the Q & A tab for this module.

If you would like to modify xNetworking module, feel free. When modifying, please update the module name, resource friendly name, and MOF class name (instructions below). As specified in the license, you may copy or modify this resource as long as they are used on the Windows Platform.

For more information about Windows PowerShell Desired State Configuration, check out the blog posts on the PowerShell Blog (this is a good starting point).  There are also great community resources, such as PowerShell.org , or PowerShell Magazine .  For more information on the DSC Resource Kit, check out this blog post.

Installation

To install xNetworking module

To confirm installation:

Requirements

This module requires the latest version of PowerShell (v4.0, which ships in Windows 8.1 or Windows Server 2012R2). To easily use PowerShell 4.0 on older operating systems, install WMF 4.0 .  Please read the installation instructions that are present on both the download page and the release notes for WMF 4.0.

Description

The xNetworking module contains the xIPAddress,  and  DSC Resources.  Instead of needing to know and remember the functionality and syntax for the IPAddress and DNS cmdlets, these DSC Resources allow you to easily configure and maintain your networking settings by writing simple configurations.  The xFirewall resource allows configuration of Firewall rules.

Details

xIPAddress resource has following properties:

xDnsServerAddress resource has following properties:

xFirewall resource has following properties:

  • Name:                    Name of the Firewall Rule
  • DisplayName:       Localized, user-facing name of the Firewall Rule being created
  • DisplayGroup:      Name of the Firewall Group where we want to put the Firewall Rules
  • Ensure:                   Ensure the presence/absence of the resource
  • Access:                   Permit or Block the supplied configuration
  • State:                      Enable or disable the supplied configuration
  •  Profile:                  Specifies one or more profiles to which the rule is assigned
  • Direction:              Direction of the connection
  • RemotePort:        Specific Port used for filter. Specified by port number, range, or keyword
  • LocalPort:             Local Port used for the filter
  • Protocol:                Specific Protocol for filter. Specified by name, number, or range
  • Description:          Documentation for the Rule
  • ApplicationPath:  Path and file name of the program for which the rule is applied
  • Service:                  Specifies the short name of a Windows service to which the firewall rule applies

Renaming Requirements

When making changes to these resources, we suggest the following practice:

  1. Update the following names by replacing MSFT with your company/community name and replacing the “x” with "c" (short for "Community") or another prefix of your choice:

    • Module Name (ex: xNetworking becomes cNetworking)
    • Resource Folder (ex: MSFT_xIPAddress becomes Contoso_cIPAddress)
    • Resource Name (ex: MSFT_xIPAddress becomes Contoso_cIPAddress)
    • Resource Friendly Name (ex: xIPAddress becomes cIPAddress)
    • MOF class name (ex: MSFT_xIPAddress becomes Contoso_cIPAddress)
    • Filename for the <resource>.schema.mof (ex: MSFT_xIPAddress.schema.mof becomes Contoso_cIPAddress.schema.mof)
  2. Update module and metadata information in the module manifest

  3. Update any configuration that use these resources

We reserve resource and module names without prefixes ("x" or "c") for future use (e.g. "MSFT_xIPAddress" or "IPAddress").  If the next version of Windows Server ships with a "IPAddress" resource, we don't want to break any configurations that use any community modifications.  Please keep a prefix such as "c" on all community modifications.

Example: Set IP Address on Ethernet NIC

This configuration will set IP Address with some typical values for network interface alias = Ethernet.


PowerShell
Edit|Remove
configuration Sample_xIPAddress_FixedValue 
{ 
    param 
    ( 
        [string[]]$NodeName = 'localhost' 
    ) 
 
    Import-DscResource -Module xNetworking 
 
    Node $NodeName 
    { 
        xIPAddress NewIPAddress 
        { 
            IPAddress      = "2001:4898:200:7:6c71:a102:ebd8:f482" 
            InterfaceAlias = "Ethernet" 
            SubnetMask     = 24 
            AddressFamily  = "IPV6" 
        } 
    } 
}
 

Example: Set IP Address with parameterized valuesspan>

This configuration will set IP Address along with default gateway on a network interface that is identified by its alias.


PowerShell
Edit|Remove
configuration Sample_xIPAddress_Parameterized 
{ 
    param 
    ( 
 
        [string[]]$NodeName = 'localhost', 
 
        [Parameter(Mandatory)] 
        [string]$IPAddress, 
 
        [Parameter(Mandatory)] 
        [string]$InterfaceAlias, 
 
        [Parameter(Mandatory)] 
        [string]$DefaultGateway, 
 
        [int]$SubnetMask = 16, 
 
        [ValidateSet("IPv4","IPv6")] 
        [string]$AddressFamily = 'IPv4' 
    ) 
 
    Import-DscResource -Module xNetworking 
 
    Node $NodeName 
    { 
        xIPAddress NewIPAddress 
        { 
            IPAddress      = $IPAddress 
            InterfaceAlias = $InterfaceAlias 
            DefaultGateway = $DefaultGateway 
            SubnetMask     = $SubnetMask 
            AddressFamily  = $AddressFamily 
        } 
    } 
}
 

Example: Set DNS Server Address

This configuration will set DNS Server Address on a network interface that is identified by its alias. 


PowerShell
Edit|Remove
configuration Sample_xDnsServerAddress 
{ 
    param 
    ( 
        [string[]]$NodeName = 'localhost', 
 
        [Parameter(Mandatory)] 
        [string]$DnsServerAddress, 
 
        [Parameter(Mandatory)] 
        [string]$InterfaceAlias, 
 
        [ValidateSet("IPv4","IPv6")] 
        [string]$AddressFamily = 'IPv4' 
    ) 
 
    Import-DscResource -Module xNetworking 
 
    Node $NodeName 
    { 
        xDnsServerAddress DnsServerAddress 
        { 
            Address        = $DnsServerAddress 
            InterfaceAlias = $InterfaceAlias 
            AddressFamily  = $AddressFamily 
        } 
    } 
}

Example: Adding a Firewall Rule

This configuration will ensure that a firewall rule is present.
PowerShell
Edit|Remove
# DSC configuration for Firewall 
 
configuration Add_FirewallRule 
{ 
    param  
    ( 
        [string[]]$NodeName = 'localhost' 
    ) 
 
    Import-DSCResource -ModuleName xNetworking 
 
    Node $NodeName 
    { 
        xFirewall Firewall 
        { 
            Name                  = "MyAppFirewallRule"             
            ApplicationPath       = "c:\windows\system32\MyApp.exe" 
            Access                = "Allow" 
        } 
    } 
 }

Example: Add a Firewall Rule to an Existing Group

This configuration ensures that two Firewall rules are present on the target node, both within the same group.

PowerShell
Edit|Remove
# DSC configuration for Firewall 
 
 
configuration Add_FirewallRuleToExistingGroup 
{ 
    param  
    ( 
        [string[]]$NodeName = 'localhost' 
    ) 
 
    Import-DSCResource -ModuleName xNetworking 
 
    Node $NodeName 
    { 
        xFirewall Firewall 
        { 
            Name                  = "MyFirewallRule" 
            DisplayName           = "My Firewall Rule" 
            DisplayGroup          = "My Firewall Rule Group" 
            Access                = "Allow" 
        } 
 
        xFirewall Firewall1 
        { 
            Name                  = "MyFirewallRule1" 
            DisplayName           = "My Firewall Rule" 
            DisplayGroup          = "My Firewall Rule Group" 
            Ensure                = "Present" 
            Access                = "Allow" 
            State                 = "Enabled" 
            Profile               = ("Domain""Private") 
        } 
    } 
 }
 

Example: Disable Access to an Application

This example ensures that notebad.exe is blocked.
PowerShell
Edit|Remove
# DSC configuration for Firewall 
 
 
configuration Disable_AccessToApplication 
{ 
    param  
    ( 
        [string[]]$NodeName = 'localhost' 
    ) 
 
    Import-DSCResource -ModuleName xNetworking 
 
    Node $NodeName 
    { 
        xFirewall Firewall 
        { 
            Name                  = "NotePadFirewallRule" 
            DisplayName           = "Firewall Rule for Notepad.exe" 
            DisplayGroup          = "NotePad Firewall Rule Group" 
            Ensure                = "Present" 
            Access                = "Block" 
            Description           = "Firewall Rule for Notepad.exe"   
            ApplicationPath       = "c:\windows\system32\notepad.exe" 
        } 
    } 
 }
 

Example: Disable Access with additional parameters

This example will disable notepad.exe's outbound access.
PowerShell
Edit|Remove
# DSC configuration for Firewall 
 
configuration Sample_xFirewall 
{ 
    param  
    ( 
        [string[]]$NodeName = 'localhost' 
    ) 
 
    Import-DSCResource -ModuleName xNetworking 
 
    Node $NodeName 
    { 
        xFirewall Firewall 
        { 
            Name                  = "NotePadFirewallRule" 
            DisplayName           = "Firewall Rule for Notepad.exe" 
            DisplayGroup          = "NotePad Firewall Rule Group" 
            Ensure                = "Present" 
            Access                = "Allow" 
            State                 = "Enabled" 
            Profile               = ("Domain""Private") 
            Direction             = "OutBound" 
            RemotePort            = ("8080""8081") 
            LocalPort             = ("9080""9081")          
            Protocol              = "TCP" 
            Description           = "Firewall Rule for Notepad.exe"   
            ApplicationPath       = "c:\windows\system32\notepad.exe" 
            Service               =  "WinRM" 
        } 
    } 
 } 
 
Sample_xFirewall 
Start-DscConfiguration -Path Sample_xFirewall -Wait -Verbose -Force
 

Versions

1.0.0.0

2.0.0.0

2.1.0

2.1.1.1