Using PowerShell for NIC Configuration Tasks

Using PowerShell for NIC Configuration Tasks

  • Comments 3
  • Likes

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

Name     InterfaceDescription ifIndex Status ...
Wired Ethernet Connec...6 Intel(R) Gigabit ET Dual Port Serv...#4 17 Up
Wired Ethernet Connec...5 Intel(R) Gigabit ET Dual Port Serv...#3 15 Up
Wired Ethernet Connec...4 Realtek PCIe GBE Family Controller 15 Disconnected
Wired Ethernet Connec...3 NetEffect(TM) Ethernet Server Cluste... 14 Up
Wired Ethernet Connec...2 Intel(R) Gigabit ET Dual Port Serv...#2 13 Up
Wired Ethernet Connection Intel(R) Gigabit ET Dual Port Server... 12 Disabled

 

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

Name   InterfaceDescription ifIndex Status ...
PublicInternet1 6 Intel(R) Gigabit ET Dual Port Serv...#4 17 Up
PublicInternet2 5 Intel(R) Gigabit ET Dual Port Serv...#3 15 Up
ManagementNetwork 4 Realtek PCIe GBE Family Controller 15 Up
DatabaseLink 3 NetEffect(TM) Ethernet Server Cluste... 14 Disconnected
ClusterNetwork 2 Intel(R) Gigabit ET Dual Port Serv...#2 13 Up
BackupLink 1 Intel(R) Gigabit ET Dual Port Server... 12 Disabled

 

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

Name DisplayName DisplayValue RegistryKeyword RegistrValue
         
PublicInternet1 Flow Control Tx Enabled *FlowControl {1}
PublicInternet1 Interrupt Moderation Enabled *InterruptMo... {1}
PublicInternet1 IPv4 Checksum Offload Rx & Tx Enabled *IPChecksumO... {3}
PublicInternet1 IPsec Offload Auth Header & ESP Enabled *IPsecOffloadV2 {3}
PublicInternet1 Jumbo Packet Disabled *JumboPacket {1514}
PublicInternet1 Large Send Offload V2 (IPv4) Enabled *LsoV2IPv4 {1}
PublicInternet1 Large Send Offload V2 (IPv6) Enabled *LsoV2IPv6 {1}
PublicInternet1 Max number of RSS Processors 8 *MaxRssProce... {8}
PublicInternet1 Preferred NUMA node System Default *NumaN odeId {65535}
PublicInternet1 Maximum Number of RSS Queues 2 Queues *NumRssQueues {2}
PublicInternet1 Priority & VLAN Priority & VLAN Enabled *PriorityVLA... {3}
PublicInternet1 Receive Buffers 512 *ReceiveBuffers {512}
PublicInternet1 Receive Side Scaling Disabled *RSS {0}
PublicInternet1 Speed & Duplex Auto Negotiation *SpeedDuplex {0}
PublicInternet1 SR-IOV Disabled *Sriov {0}
PublicInternet1 TCP Checksum Offload (IPv4) Rx & Tx Enabled *TCPChecksum... {3}
PublicInternet1 TCP Checksum Offload (IPv6) Rx & Tx Enabled *TCPChecksum... {3}
PublicInternet1 Transmit Buffers 2048 *TransmitBuf... {2048}
PublicInternet1 UDP Checksum Offload (IPv4) Rx & Tx Enabled *UDPChecksum... {3}
PublicInternet1 UDP Checksum Offload (IPv6) Rx & Tx Enabled *UDPChecksum... {3}
PublicInternet1 Virtual Machine Queues Disabled *VMQ {0}
PublicInternet1 Interrupt Moderation Rate Adaptive ITR {65535}
PublicInternet1 Log Link State Event Enabled LogLinkState... {51}
PublicInternet1 Gigabit Master Slave Mode Auto Detect MasterSlave {0}
PublicInternet1 Locally Administered Address -- NetworkAddress {--}
PublicInternet1 Wait for Link Auto Detect WaitAutoNegC... {2}

 

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"

Name DisplayName DisplayValue RegistryKeyword RegistryValue
         
PublicInternet1 Receive Buffers 2048 *ReceiveBuffers {2048}

 

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

DisplayName DisplayValue ValidDisplayValues
----------- ------------ ------------------
Flow Control Tx Enabled {Disabled, Tx Enabled, Rx Enabled...
Interrupt Moderation Enabled {Disabled, Enabled}
IPv4 Checksum Offload Rx & Tx Enabled {Disabled, Tx Enabled, Rx Enabled,..
IPsec Offload Auth Header & ESP Enabled {Disabled, Auth Header Enabled, ...
Jumbo Packet Disabled {Disabled, 4088 Bytes, 9014 Bytes}
Large Send Offload V2 (IPv4) Enabled {Disabled, Enabled}
Large Send Offload V2 (IPv6) Enabled {Disabled, Enabled}
Max number of RSS Processors 8 {1, 2, 4, 8}
Preferred NUMA node System Default {System Default, Node 0, Node 1, N..
Maximum Number of RSS Queues 2 Queues {1 Queue, 2 Queues, 4 Queues, 8...
Priority & VLAN Priority & VLAN Enabled {Priority & VLAN Disabled, Priority
Receive Buffers 2048  
Receive Side Scaling Disabled {Disabled, Enabled}
Speed & Duplex Auto Negotiation {Auto Negotiation, 10 Mbps Half Dup.
SR-IOV Disabled {Disabled, Enabled}
TCP Checksum Offload (IPv4) Rx & Tx Enabled {Disabled, Tx Enabled, Rx Enabled..
TCP Checksum Offload (IPv6) Rx & Tx Enabled {Disabled, Tx Enabled, Rx Enabled,
Transmit Buffers 2048  
UDP Checksum Offload (IPv4) Rx & Tx Enabled {Disabled, Tx Enabled, Rx Enabled,
UDP Checksum Offload (IPv6) Rx & Tx Enabled {Disabled, Tx Enabled, Rx Enabled,
Virtual Machine Queues Disabled {Disabled, Enabled}
Interrupt Moderation Rate Adaptive {Adaptive, Extreme, High, Medium...}
Log Link State Event Enabled {Enabled, Disabled}
Gigabit Master Slave Mode Auto Detect {Auto Detect, Force Master Mode, ..
Locally Administered Address    
Wait for Link Auto Detect {Off, On, Auto Detect}

 

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

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

 

DisplayName : Flow Control
ValidDisplayValues : {Disabled, Tx Enabled, Rx Enabled, Rx & Tx Enabled}

'

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*

 

DisplayName : Receive Buffers
NumericParameterBaseValue : 10
NumericParameterMaxValue : 2048
NumericParameterMinValue : 80
NumericParameterStepValue : 8
   
DisplayName : Transmit Buffers
NumericParameterBaseValue : 10
NumericParameterMaxValue : 2048
NumericParameterMinValue : 80
NumericParameterStepValue : 8

 

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*

DisplayName : Maximum RSS Processor Number
NumericParameterBaseValue : 10
NumericParameterMaxValue : 63
NumericParameterMinValue : 0
NumericParameterStepValue : 1

 

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

DisplayName : RSS Base Processor Number
NumericParameterBaseValue : 10
NumericParameterMaxValue : 63
NumericParameterMinValue : 0
NumericParameterStepValue : 1

 

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*

DriverVersion : 12.1.77.0
DriverInformation : Driver Date 2012-07-10 Version 12.1.77.0 NDIS 6.30
DriverFileName : e1q63x64.sys
DriverDate : 2012-07-10
DriverDateData : 129863520000000000
DriverDescription : Intel(R) Gigabit ET Dual Port Server Adapter
DriverMajorNdisVersion : 6
DriverMinorNdisVersion : 30
DriverName : \SystemRoot\system32\DRIVERS\e1q63x64.sys
DriverProvider : Intel

 

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

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Accessing the database by enabling the BackupLink adapter just doesn't seem right. :) I presume the idea is to enable the DatabaseLink.

  • Hi Sam,

    Thanks for the feedback.

    It was a contrived example to show the potential usefulness of naming in some circumstances. Imagine that that the backup link is a link that is redundant to the database links (which has failed).   Then, enabling the backup links is the right thing to do.

    If on the other hand, as you suggest , you could re-enable the database link instead.

    In either case, Powershell has made it a bit easier than trying to do this with the network control panel application.  The real power comes when you can perform comparison and configuraiton tasks on large number of NICs installed in many machines.