NMCap: the easy way to Automate Capturing


OK, I’m not going to blow smoke up your Async port. I don’t mean to say that the NMCap is necessarily easy to use, though it’s not that hard. But any command line utility always has its quirks. Isn’t that why GUI was invented?

What NMCap does make easy, is automating how you get your captures. And presenting somebody with a script is always much easier. I don’t know how many folks have tried to walk a parent or friend through some simple procedure over the phone or email, but I’m sure you can understand how challenging it can be. “Double click faster Mom…no not there, on the thingy that looks like a spider monkey!”

NMCap is a tool that runs from the command line and allows you to set all kinds of options to control when it starts, when it stops, how it stops, what it captures, where it captures, in all kinds of variations. This allows you to script it so that when you want somebody to get a trace; you get exactly what you want.

NMCap is…

  • Low profile – If you want to take a trace without affecting the server performance, use NMCap with no filters.
  • Configurable – A host of options to allow you to start/stop traces with full control.
  • Scriptable – Since it’s just a command line utility, you can use it in your batch files.

How can I stop my trace when my process is finished?

The other application that NMCap makes easier is automation. You’ll often want to start or stop a trace under certain conditions. And while you can’t communicate with NMCap directly, you can tell it to start and stop when specific trace data occurs. This means that you can PING some address, for instance, and cause your trace to stop. This is the key behind automating a capture.

The Situation: You need to start a capture, run your test pass, and stop the capture.

So imagine your application is blah.exe. This task requires two different processes. One to run NMCap to take the trace and look for the stop criteria, The other process is for your test application. Our batch file looks like this.

start nmcap /network * /capture /file t.cap /stopwhen /frame (ipv4.address == ipconfig.localipv4address) AND (Ipv4.DestinationAddress == 1.2.3.4)

Sleep 5

Blah.exe

Ping 1.2.3.4

We start by running nmcap with the START command. This lets NMCap run as another process in another window (we could use /b to make it run in the same window if we choose).

The next set of parameters, “/network *” tells NMCap to capture on all NICs. You can alternatively select a specific network adapter by number. To list the number to adapter mappings, type “NMCap /DisplayNetworks”.

The “/capture /file t.cap” parameters describes where to store the information and what to use for our capture filter. In this case, we don’t have a capture filter. If we wanted to supply one, we could add a filter after the “/Capture” parameter.

The final portion “/stopwhen /frame …” determines how NMCap will stop. When used with the “/frame” parameter, this allows you to stop when a specific filter criteria is met. Once we see a frame that passes this filter, we stop the capture and exit NMCap. We look for a filter whose sending IP address matches the local IPv4 address AND the IPv4 destination address is 1.2.3.4.

The next line of the batch file simply waits a few seconds to make sure NMCap is up and ready to capture packets. Once 5 seconds pass, we call the application that we want to capture the traffic for. And then finally the PING that NMCap is waiting for to single it to stop capture.

It probably doesn’t matter if this address exists or not. At least on Windows machines, the PING goes out whether it’s valid or not. But you could also change the traffic you use to stop the trace. There is more than one way to generate traffic that you could trigger on.

The most basic of examples:

So let’s take a step back and give you the most simple of examples. The following captures on all network adapters and does no filtering.

NMCap /network * /capture /file test.cap

Now let’s take the above command and add a filter to it. I now want to get rid of any traffic on port 3389, since I know my Terminal Server session rides on that port and I don’t want to see any of that traffic in my trace.

NMCap /network * /capture “!(tcp.port == 3389)” /file test.cap

You can use any complex filter you want here. You can reference and protocol we have a parser for. No longer are you limited to using offsets in protocols, like you were with Netmon2.x.

Stopping and Starting

The default stopping criteria is to stop when the user hits Ctrl+C or Ctrl+Break. You can use the “/stopwhen /keypress x” or any other letter to make it stop when a specific single character is entered.

There are many stopping and starting events. You can just as easily have a network event start NMCap capturing. You can also start/stop after a given amount of time with the “/TimeAfter” parameter. In this case you supply a number and units, like “/TimeAfter 30 mintues”. Or instead of a time delta, you can specify and absolute time instead, for example “/Time 10:30:00 am 9/10/2006”. The format of the time depends on your locale settings.

Capture File Output, creating chained captures

When you specify the capture file name with the “/File” parameter, you tell NMcap what type of capture file you want by the extension you add to the file. If you use a “.cap” extension we save the data to a single capture file and limit the size to 20 Megs. But you can change the default size by adding a colon and the size after the file. For example, “/File t.cap:50M”, sets the max file size to 50Megs. Once we reach this limit we do continue to capture, but the file doesn’t grow anymore.

But if you want chained captures, you can use the “.chn” extension. Again you can specify the size of each chained file with the colon. When you use chained capture files, it names each by attaching parens with a number in between which tells you the sequence in the list of capture files. So for example, “/file t.chn:1M”, will create files t(1).chn and t(2).chn, and so on. Each capture file will be 1 Meg in size.

Cool NMCap trick, using another capture file as the input source

NMCap also allows you to accept a capture file as input. This can be useful for cleansing your traces before you use them. Or you could also parse traffic by different ports or by IP addresses. The following example takes all the traffic going to 10.0.0.1 in the trace test.cap, and puts the resulting traffic in c1.cap.

NMCap /InputCapture test.cap /capture Ipv4.Address == 10.0.0.1 /file c1.cap

Seeing more examples

NMCap with the “/examples” switch will show you some more examples that should help you understand how to use the various parameters. With the host of capturing options, you should be able to fulfill most of your capturing needs.

Comments (20)

  1. Anonymous says:

    This is great information.

    FYI, I had to turn off the "Enable local only" option on a capture to be able to capture packets that weren’t addressed to my PC.  My guess is that turning this off turns on promiscuous mode for the packet capture.  I briefly reviewed the Netmon3 user guide and I didn’t see anything on this.

    You might want to highlight this somewhere as this is a change from NM2 which I believe ran in promiscuous mode by default.

    We were spanning traffic through our Cisco network and I didn’t see the traffic by default using NM3, but did with other software and NM2.

    The capture only local traffic also shows up in two areas.  It shows up under options and also under the capture.  I had to uncheck this under capture for it to take effect.

    John

  2. Anonymous says:

    Thanks John.  I’ve sent a note to our team to try and document this in the release notes.

    Paul

  3. Anonymous says:

    Having worked in Product Support for many years, I’ve had many occasions where a specific Event Log error

  4. Anonymous says:

    Hello all Networking Blog readers.  My name is Brett Crane and I am an engineer with the Networking

  5. Anonymous says:

    Many times, the key to solving these errors is a network packet trace. The problem is that these errors

  6. Anonymous says:

    The port information is part of TCP not HTTP.  so waht you want is "/capture tcp.port == 1000".

    By default when you capture with NMCap, you only see traffic comming to your machine.  You actually have to add an option /DisableLocalOnly, to see traffic that’s not destine for you machine.

    Thanks,

    Paul

  7. Anonymous says:

    Hello,

    is there a way to read the data from the .cap file for example if i want to get HTTP Headers from captured frames

    Thanks.

  8. Anonymous says:

    Today, you’d have to use the UI and add a column for the HTTP header.  Then you could export that data from the UI by Cut & Pasting, for instance, into Excel.  Then you could extract that one column.

    In the next version, NM3.2, you’ll be able to use the NMAPI to extract that data programmatically.  

    Thanks,

    Paul

  9. Anonymous says:

    Hello again,

    Do you have a library for all command and parameters?

    Thanks,

  10. Anonymous says:

    I like the way the command line is.  For some reason I can not do a filter with more than one option example:

    Works in GUI

    IPv4.Address == 123.1.12.12 AND Protocolname=="DNS") OR (IPv4.Address == 123.2.12.12 AND Protocolname=="DNS"

    using nmcap

    It starts but never logs.  I have tried using Quotes fot the whole "filter" and () for the filter (filter) and get the same results.  

    If I just use /capture DNS I will get all DNS ok but I only want DNS traffic to the DNS server and to the SOA for Dynamic updates.

    nmcap /network * /capture IPv4.Address == 123.1.12.12 AND Protocolname=="DNS" OR IPv4.Address == 123.2.12.12 AND Protocolname=="DNS"  /file d:tempDNS-watch.cap:100m

    The issue I am tring to capture DNS traffic that this 2008 Domain Controler send/receives for any Dynamic update sent/reply from DNS and to the SOA. (the Primary and Secondary DNS servers on the interface are not).  I am running this on the DC.

    Is this possible ?

    Thanks again for any help

    Al

  11. Anonymous says:

    Hi,

    I am very sorry for disturbing you but i realy need a way to automate capturing, so i need to capture HTTP responses and requests on the port 1000 of my PC

    i tried with: /capture "http.port == 1000"

    it doesnt work

    it wil be ok if i could just specify the port 1000 without the http filter

    finaly is there any option for /network so i can limit the capture to my own PC without need to specify my IP address?

    Thanks,

  12. Anonymous says:

    I see you posted your question on our forums, which is great.  I’ve hopefully posted the answer there.

    http://social.technet.microsoft.com/Forums/en/netmon/thread/cb8ccec7-f468-40af-b807-ba6f41cf9f13

  13. Anonymous says:

    Ali, thanks for the corrections.  I’ve fixed the typos in the blog.

    Paul

  14. Anonymous says:

    One of our goals for the next version is to provide some kind of API so that you can capture, store, and analyze trace data using our engine.  As for a COM or .Net interface, we probably will try to provide a managed interface, but I can’t be sure if that will be provided at the same time.

    Thanks,

    Paul

  15. Anonymous says:

    The next version will also contain a NetmonSDK.CHM with information about all the API calls and examples.  

    Thanks,

    Paul

  16. Anonymous says:

    Hello,

    Do you have plans to provide more sophisticated automation interface. COM or .Net ?

    It would be handy. In fact relying on shell commands is not the way to go

    Regards

  17. Anonymous says:

    Hi,

    I like the ability to filter from the command line with "NMCap /InputCapture"

    I think there are a couple of typos there…the following seems to work :

    NMCap /InputCapture test.cap /capture Ipv4.Address ==10.0.0.1 /file c1.cap

    Ali.

  18. Anonymous says:

    @Shahid, NMCap mentioned in the article above is the command line to capture traffic with Network Monitor. Moving forward with Message Analyzer (http://blogs.technet.com/MessageAnalyzer), we have new
    powershell cmdlets that I discuss here: (http://blogs.technet.com/b/messageanalyzer/archive/2013/10/29/using-powershell-to-automate-tracing.aspx).

    Further more there are built-in ways to get a trace using the OS, like NetSh, TraceLog, LogMan, Event Viewer, and native PowerShell scripts. Though the availability of these depends on your OS.

  19. China says:

    晕,都是英文看不懂!!!

    Email:hanqiang_80@126.com

  20. Shahid +918858200060 says:

    Which of the following command line tools is used to capture network file by using network monitor? Thanks for giving answer