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
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.