Introducing the PowerShell Network Adapter Configuration module

For a Windows administrator, working with network adapters is a common task. A common approach many companies use is configuring servers with static IP addresses (IPv4) and clients using DHCP. The IP address is just one of many properties of a network adapter, as we also have properties like subnet mask, default gateway, DNS server search order and so on. Configuring these properties is usually performed during the initial setup of a computer, either manually or by a deployment mechanism.

The configuration of a network adapter is mostly static, however, from time to time some properties might need to be changed. In example the subnet on a network is expanded to meet new requirements, and thus the subnet mask property must be updated on computers not using DHCP. Another scenario is the setup of new DNS servers, with a decision not to keep the existing DNS servers` IP addresses. I recently faced the last scenario, where several hundred servers configured with static IP addresses needed to have their DNS configuration updated. Using Windows PowerShell the task can be automated, even if we need to perform the task on 10, 100 or 1000 servers. However, the more computers a script is run against, the more important it is to implement proper error handling and logging to keep track of which computers is updated.

The above task is just one of many potential tasks for configuring a network adapter. Since I was unable to find any existing PowerShell module/library for working with network adapters on Windows systems, I decided to create a project on Codeplex:

 

The PowerShell Network Adapter Configuration module

The PowerShell Network Adapter Configuration (PSNetAdapterConfig) module is a PowerShell module for working with network adapters on Windows-based computers. The module is using Windows Management Instrumentation (WMI) to retrieve and configure properties of network adapters.

The current release of the module makes use of the following WMI-classes:

The module currently contains 4 functions:

  • Get-DNSServerSearchOrder – get the DNS client settings for a network adapter (the property name is DNSServerSearchOrder)
  • Get-NetConnectionId – get the name of a network adapter (the property name is NetConnectionId)
  • Set-DNSServerSearchOrder – change the configured DNSServerSearchOrder. This function contains two parameter sets, one for replacing the current DNSServerSearchOrder property value, the other for adding/removing IP addresses from the current value
  • Set-NetConnectionId – change the name of a network adapter. In example, change the name from “Local Area Connection” to “Server VLAN 42”

I will add functions to the module when I find time, but I also hope that people in the community will contribute by either improving the existing functions, providing suggestions or creating new functions.

When downloading a PowerShell module from the internet (typically a zip-file), beginners often get into problems because they don`t know that the file first needs to be unblocked (Right-click the zip-file->Properties->Unblock). To overcome this challenge I created a Windows installer (MSI) file which is easy to install and does not need to be unblocked:

image

The default install path is %userprofile%DocumentsWindowsPowerShellModules, and the user have the option to override the module path.

The installer was created using Windows XML Installer (Wix), based on Chad Miller`s blog-post Building A PowerShell Module Installer.

When the module is installed, we can use Import-Module to import the module, and Get-Command to list the available commands:

image

As we can see there is also an alias for each of the commands (functions).

By using Get-Help we can see available parameters along with their descriptions, as well as several examples:

image

The functions supports both ValueFromPipeline and ValueFromPipelineByPropertyName, which means we can leverage the PowerShell pipeline. Have a look at example 3 on the above image to see how computers can be retrieved from Active Directory using Get-ADComputer, and then piped directly into the Set-DNSServerSearchOrder function.

The functions outputs PowerShell objects, which mean we can use regular PowerShell techniques to work with the data, in example converting the objects to HTML or CSV. I typically use Export-Csv to output the data to CSV-files which in turn can be converted to Excel spreadsheets:

image

 

The functions is using a try/catch construct, using the following logic:

  1. Ping the computer, if unsuccessful the property “Connectivity” on the output object is set to “Failed (ping”)
  2. Connect to the computer using WMI, if unsuccessful the property “Connectivity” on the output object is set to “Failed (ping”)
  3. The property “Connectivity” on the output object is set to “Successful” if step 1 and 2 succeeds
  4. Retrieve or change the applicable properties using WMI

When working with a large number of computers we can use Sort-Object in PowerShell to filter the output objects based on the Connectivity property, or the sorting functionality in Microsoft Excel if the output objects is piped to a CSV-file.

 

The final example I will show is using the Set-NetConnectionId function. On a test-computer we have a network adapter named “Local Area Connection 5”:

image

Using Set-ConnectionId we can specify the subnet for which network adapter to perform the change on (the above network adapter has an IP address of 192.168.56.10) and specify the new name of the network connection:

image

When the command has run we can see that the connection name for the adapter has changed:

image

One additional feature that might be included to this function is the ability to provide a hash-table with a mapping of subnets and NetConnectionIds, which will make it easy to create a consistent naming convention for network adapters.

As a final note, all functions has a Logfile parameter, allowing us to log error message to the specified file.

 

Requirements

  • Windows PowerShell 2.0
  • ICMP (ping) and WMI firewall openings from the computer running the module to the target computers
  • Administrator permissions on the target computers

To avoid the firewall requirements, a workaround is running the functions from a PowerShell script locally on target computers using a software distribution product like System Center Configuration Manager.
Another option is to run the functions over PowerShell remoting.

 

Download and feedback

The module is available for download on the Codeplex project site http://psnetadapterconfig.codeplex.com. Please use the Discussions and Issue Tracker sites on the project site to report bugs and feature requests.

 

Resources

The functions is too long to walkthrough in a blog-post, so I will direct you to the following resources to get started working with advanced functions and modules in PowerShell:

An Introduction to PowerShell Modules by Jonathan Medd.

An Example ScriptModule and Advanced Function by Don Jones.

Ten tips for better PowerShell functions by James O`Neill.

Maximize the reuse of your PowerShell by James O`Neill.

One thought on “Introducing the PowerShell Network Adapter Configuration module

  1. Pingback: Episode 168 – Randy Roffey on MP Studio and a Bonus Interview « PowerScripting Podcast

You must log in to post a comment.