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

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