Using PowerShell for NIC Configuration Tasks

Hi there! In this blog post we highlight some of the early work on NIC configuration using PowerShell from engaging with customers during our Windows Server 2012 engineering validation program.  Long before we reach RTM dedicated customers deploy in production, test and identify issues during the development phase to help us achieve a high quality release.  Ed Briggs a Principal Program Manager in the Customer Engineering team focused on Development and Low Latency computing will take you thru the details of NIC configuration using PowerShell.

Natalia Mackevicius
Group Program Manager, Partner and Customer Ecosystem Team

If you work with Network Interface cards (NIC) or manage systems, you will want to become familiar with the new Windows Server 2012 PowerShell Cmdlets that simplify many common NIC and Network configuration tasks. These Cmdlets make it easy to automate the configuration management multiple NICs on multiple servers.

In subsequent installments of this series, we'll be looking at Network latency and adjusting NIC parameters quite a bit, so becoming familiar with the basics is time well spent.

In this article I will demonstrate how to use PowerShell to perform NIC configuration tasks, including:

• Naming your NIC
• Getting and setting advanced NIC parameter settings
• Determining valid NIC parameters
• Resetting Parameters to Factory Default Values
• Using the -NoRestart flag to 'batch' changes
• Determining the NIC Driver Version

The reference documentation for these Cmdlets is available on-line at

http://technet.microsoft.com/en-us/library/jj134956

These commands can be used on your local machine, remote machines, or to configure an arbitrary number of NIC adapters on an arbitrary number of machines.

There are a large number of CmdLets covering virtually all aspects of network configuration, but I’m going to limit myself to performing some common NIC configuration tasks.

Naming Your NIC

If you have multiple NICs, remembering which is which can be difficult. The Consistent Device Naming (CDN) feature added in Windows 8 and Windows Server 2012 makes it easier for those who are concerned with network cabling to determine which physical network interface is which.

And with PowerShell, you can also give your NICs descriptive names which you can use for subsequent configuration tasks. This is particularly useful if you have multiple NICs or if you manage multiple servers.

Let's get a list of all the NICs on my machine. (abbreviated to fit on the page). The names below don't tell us very much about which NIC interface is used for:

PS > Get-NetAdapter

Let's rename the NICs to something easier to understand. In this example, I'll name the NICs to reflect their function.

PS> Rename-NetAdapter -Name "Wired Ethernet Connection 4" PublicInternet1

After a few more of these commands, we arrive at a much easier to understand display. Notice each NIC now has a descriptive name:

PS > Get-NetAdapter

Looking at this table, you can answer questions like "Why can't I reach the database?" It's disconnected. And you can fix this admittedly contrived example problem by enabling the back-up link - by name.

PS> Enable-NetAdapter BackupLink

Now that we have an easier way to refer to specific NIC interfaces, let’s move on to NIC configuration parameters.

Viewing and Setting Advanced NIC Parameters

With Windows Server 2012, PowerShell makes it easy to set and check the network parameters that previously had to be set using the Network Control Panel application. You can still use the control panel application of course, but PowerShell makes it possible to automate the process.

Let's try some practical examples. First well look at some NIC parameters, then see how to change them from PowerShell. To examine the NIC parameters for the PublicInternet1 NIC we can use.

To save a little typing, I'm going to abbreviate the NIC Name PublicIntenet1 as P*1. PowerShell will expand the wild-card for me.

PS C> Get-NetAdapterAdvancedProperty P*1

Let's increase the number of Receive Buffers to 2048. (Increasing the number of Receive Buffers (aka receive descriptors) increases the size of the buffering area used to hold arriving Ethernet frames. This buffering area resides in an area of system memory and is allocated from non-paged pool. On busy servers with lots of network traffic, increasing the number of buffers reduces the probability that an arriving frame will need to be discarded because there was no buffering available. The numeric value refers to the maximum number of Ethernet frames that can be buffered.)

PS> Set-NetAdapaterAdvancedProperty P*1 -DisplayName "Receive Buffers" -DisplayValue 2048.

Now let's check it.

PS> Get-NetAdapterAdvancedProperty P*1 -DisplayName "Receive Buffers"

This small example illustrates that by using the -DisplayName and -DisplayValue switches, we can set the NIC Advanced Configuration parameters from PowerShell.

This means it is also easy to automate the checking and setting of NIC parameters. For large installations, the parameters can be saved in a SQL-Server database, or in an XML file, or furnished by a Web Service, or simply in a comma separated variable (csv) file. Powershell makes it easy to access any of these.

Determining Valid NIC Parameter Values

Different kinds of NICs may have different parameter settings. How do you know what parameters values are valid for your NIC? You can use PowerShell to determine which values are valid for a particular parameter on a particular NIC. The values are supplied by the NIC Driver supplier and will reflect NIC specific capabilities.

Let's see all the parameters and their permissible values for the PublicInternet1 NIC and format the display as a table using 'ft' (format table).

PS> Get-NetAdapterAdvancedProperty P*1 | ft DisplayName, DisplayValue, ValidDisplayValues

For example, let’s see what values are possible for Flow Control:

PS> Get-NetAdapterAdvancedProperty P*1 -DisplayName *flow* | fl DisplayName, ValidDisplayValues

'

Here we see the only permissible values for the "Flow Control" parameter are:

{Disabled, Tx Enabled, Rx Enabled, Rx & Tx Enabled}

and we could use those to set the flow control to "Rx & Tx" Enabled as follows:

PS> Set-NetAdapterAdvancedProperty P*1 -DisplayName "Flow Control"-DisplayValue "Rx & Tx Enabled"

Determining Valid Numeric Parameters

Some parameters accept range of numeric values. For these values, you can determine the valid values by examining the NumericaParameterBaseValue, NumericParameterMaxValue, NumericParameterMinValue, and NumericParametersStepValue.

As an example, let's see the permissible settings for Transmit Buffers and Receive Buffers on this particular NIC.

PS> Get-NetAdapterAdvancedProperty P*1 -DisplayName *Buffers | fl DisplayName, NumericP*

As another example, we can check the Receive Side Scaling (RSS) Maximum RSS Processor Number and

RSS Base Processor Number. (notice that by specifying the first and last letter of these names and an asterisk, (i.e. M*r and R*r) PowerShell will expand the property names automatically)

PS > Get-NetAdapterAdvancedProperty P*1 -DisplayName M*r | fl DisplayName, NumericP*

PS > Get-NetAdapterAdvancedProperty P*1 -DisplayName R*r | fl DisplayName, NumericP*

Resetting a Parameter to the Default Value

If you want to reset an advanced parameter back to the factory default value, you can use the Reset-NetAdapterAdvancedProperty CmdLet. In the following example, we set the Interrupt Moderation parameter to the factory default:

PS> Reset-NetAdapterAdvancedProperty P*1 –DisplayName “Interrupt Moderation”

If you want to reset all the advanced parameters back to default value, you can use a wild card

PS> Reset-NetAdapterAdvancedProperty P*1 –DisplayName *

Batching Commands

PowerShell provides a neat new feature which can batch multiple parameter changes into a single operation. This reduces the number of Network link 'bounces' during configuration and speeds up the configuration dramatically.

When you change a NIC parameter, the NIC driver needs to be restarted for the change to be applied. If you are used to using control panel, you may have noticed that when you make a change the affected network interface goes down briefly while the driver is restarted. This is especially noticeable if you are using a remote terminal session and reset the NIC you are using for the connection. This will temporarily interrupt your remote terminal session. Although the link will be restored, this is annoying, particularly if you need to do this repeatedly when using the network control panel to change NIC setting. But not with PowerShell.

If you are making multiple changes, PowerShell allows you to batch multiple changes and have them all applied with a single restart by using the -NoRestart flag.

For example, suppose I have four parameters I want to set. I append -NoRestart to all the CmdLet invocations except the last.

Set-NetAdapterAdvancedProperty $eth -DisplayName name1 -DisplayValue val1 -NoRestart

Set-NetAdapterAdvancedProperty $eth -DisplayName name2 -DisplayValue val2 -NoRestart

Set-NetAdapterAdvancedProperty $eth -DisplayName name3 -DisplayValue val3 -NoRestart

Set-NetAdapterAdvancedProperty $eth -DisplayName name4 -DisplayValue val4

The NIC will be restarted on when the last CmdLet runs, and will apply all the previous settings at one time. There will be only one link bounce.

Alternatively, you can explicitly restart the NIC by invoking

Restart-NetAdapter (NIC Name)

That's useful if your configuration script is a loop. Each CmdLet in the loop would include -NoRestart. Finally, when the loop completes, issue an explicit restart to apply all the changes. Restarting the NIC disables and re-enables the NIC, applying pending parameter changes in the process.

Determining the NIC Driver VersionA common operations task is checking the version of all the NICs and drivers on a server. This is easy to do with PowerShell by examining the NetAdapter properties. In the following example, we use a wild card to display all the driver related properties in a list format:

PS> Get-NetAdapter P*1 | fl Dri*

Summary

We’ve only scratched the surface of what is possible with PowerShell in the realm of NIC configuration, I hope you’ve found this helpful. If you work with NICs much, I think you’ll quickly find this capability is indispensible.

Ed Briggs
Principal Program Manager
Partner and Customer Engineering team