Summary: Ed Wilson, Microsoft Scripting Guy, talks about getting started with packet sniffing in Windows PowerShell.
Microsoft Scripting Guy, Ed Wilson, is here. One of the way cool things that happened with Windows 8.1 and Windows Server 2012 R2 was the ability to do network traces with Windows PowerShell. I have found network tracing extremely useful and helpful in troubleshooting and diagnostics ever since I wrote my book, Network Monitoring and Analysis: A Protocol Approach to Troubleshooting.
In the past, I have used batch files, automated the NetMon API, and done all kinds of crazy things to try to automate capturing network traces and analyzing the data. Although the Network Event Packet Capture cmdlets have been around for at least a year, I have not written very much about them. The thing is that even though it is basic Windows PowerShell, it still takes a bit of time to figure out how to get started. This is because there are 27 cmdlets in the NetEventPacketCapture module:
PS C:\> (gcm -Module NetEventPacketCapture | measure).count
27
Here are the 27 cmdlets (functions):
PS C:\> gcm -Module NetEventPacketCapture | select name
Name
—-
Add-NetEventNetworkAdapter
Add-NetEventPacketCaptureProvider
Add-NetEventProvider
Add-NetEventVmNetworkAdapter
Add-NetEventVmSwitch
Add-NetEventWFPCaptureProvider
Get-NetEventNetworkAdapter
Get-NetEventPacketCaptureProvider
Get-NetEventProvider
Get-NetEventSession
Get-NetEventVmNetworkAdapter
Get-NetEventVmSwitch
Get-NetEventWFPCaptureProvider
New-NetEventSession
Remove-NetEventNetworkAdapter
Remove-NetEventPacketCaptureProvider
Remove-NetEventProvider
Remove-NetEventSession
Remove-NetEventVmNetworkAdapter
Remove-NetEventVmSwitch
Remove-NetEventWFPCaptureProvider
Set-NetEventPacketCaptureProvider
Set-NetEventProvider
Set-NetEventSession
Set-NetEventWFPCaptureProvider
Start-NetEventSession
Stop-NetEventSession
TechNet does a good job at describing the cmdlets, but there is also a pretty good chance that it will be rather cumbersome to figure out how to get started. I mean, how do I do a basic network trace? How is that trace viewed? How do I filter that trace to find useful information? These are the sorts of things that I would need if I were going to do a network trace using Windows PowerShell. So, let’s get started.
Using an ETL log
This makes sense. With a gigabyte Ethernet (or greater), there are lots of packets flying by on the wire. Many of them are encrypted, and I can learn nearly nothing by watching network packets fly past. Well, nearly nothing. I can, of course, tell if my laptop is seeing anything on the wire—but that is basically the same as looking to see if the light blinks on my network card.
As I have mentioned before, ETL logging is an extremely high performance logging interface that is capable of writing hundreds of events a second— just the thing if I want to do a network trace. And guess what? Windows PowerShell already has a cmdlet that will read ETL logs—the Get-WinEvent cmdlet. So I don’t need anything else to be able to read my traces.
Six basic steps to perform a network trace
There are six basic steps required to perform a network trace:
- Add a new network event session with New-NetEventSession.
- Add a network event provider to the session with New-NetEventProvider.
- Start the session with Start-NetEventSession.
- Get information about the session with Get-NetEventSession.
- Stop the network event session with Stop-NetEventSession.
- Remove the network event session with Remove-NetEventSession.
Step-by-step walkthrough
Now I will go through the six steps that are used to create a new network event tracing session.
Create a new session
The first thing I need to do is to create a new network event session. To do this, I use the New-NetEventSession cmdlet and specify a name for the session. Here is an example of this command:
New-NetEventSession -Name “Session1”
When I run this command, I receive information such as where the log file will be and the size of file:
PS C:\> New-NetEventSession -Name “Session1”
Name : Session1
CaptureMode : SaveToFile
LocalFilePath : C:\Windows\system32\config\systemprofile\AppData\Local\NetEvent
Trace.etl
MaxFileSize : 250 MB
TraceBufferSize : 0 KB
MaxNumberOfBuffers : 0
SessionStatus : NotRunning
Add a provider
The second thing I need to do is to add a provider to the network event session. To do this, I need to know two things:
- The name of the session (in my case, session1)
- The name of a provider
I can use the Get-EtwTraceProvider cmdlet; but unfortunately, it only lists GUIDs and not much more information. So I can use the Logman.exe to query for providers:
logman query providers
This command brings back pages of providers, so I can either scroll through it or use Select-String to help me find what I need. That is right. I can pipe the output from the executable directly to Select-String. This is shown here:
PS C:\Windows\system32> logman query providers | select-string tcp
Microsoft-Windows-TCPIP {2F07E2EE-15DB-40F1-90EF-9D7BA282188A}
Microsoft-Windows-Tcpip-SQM-Provider {C8F7689F-3692-4D66-B0C0-9536D21082C9}
TCPIP Service Trace {EB004A05-9B1A-11D4-9123-0050047759BC}
I want to use the Microsoft-Windows-TCPIP provider, and my command is shown here:
PS C:\> Add-NetEventProvider -Name “Microsoft-Windows-TCPIP” -SessionName “Session1”
Name : Microsoft-Windows-TCPIP
SessionName : Session1
Level : 4
MatchAnyKeyword : 0xFFFFFFFFFFFFFFFF
MatchAllKeyword : 0x0
Start the session
Now I need to start the network trace session. I use the Start-NetEventSession cmdlet and specify my session name. Note that nothing returns from the following command:
PS C:\> Start-NetEventSession -Name “Session1”
Get the session
I want to get information about my session. To do this, I use the Get-NetEventSession cmdlet:
PS C:\> Get-NetEventSession
Name : Session1
CaptureMode : SaveToFile
LocalFilePath : C:\Windows\system32\config\systemprofile\AppData\Local\NetEvent
Trace.etl
MaxFileSize : 250 MB
TraceBufferSize : 64 KB
MaxNumberOfBuffers : 38
SessionStatus : Running
The Get-NetEventSession cmdlet tells me the location of the log file, so I probably want to store that and avoid a bit of typing. This is shown here:
$s = Get-NetEventSession
Stop the session
Now it is time to stop the network trace session. To do this, I use Stop-NetEventSession and specify my session number. This command does not return any information:
PS C:\> Stop-NetEventSession -Name session1
PS C:\>
Remove the session
The last thing I need to do is to remove the session that I stopped. To do this, I use the Remove-NetEventSession cmdlet. It does not return any information either, so I use the Get-NetEventSession cmdlet to ensure that it did remove the session:
PS C:\> Remove-NetEventSession
PS C:\> Get-NetEventSession
PS C:\>
Now you know how to use Windows PowerShell to get started making network traces. Join me tomorrow when I will talk about parsing the captured ETL log data.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy
It would be helpful to include descriptions of what is (roughly) happening. For instance, if I issue `Start-NetEventSession`, is this the point at which packets are being captured and saved to the file that you see when you run `Get-NetEventSession`? Stopping the trace is done with `Stop-NetEventSession` and I presume that means that no more packets are written to the file. However, what does `Remove-NetEventSession` do? What happens if you don't...