NMCap: the easy way to Automate Capturing

NMCap: the easy way to Automate Capturing

  • Comments 18
  • Likes

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.

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • 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

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

    Paul

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

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

    Paul

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

  • 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

  • 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

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

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

  • 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

  • Hello again,

    Do you have a library for all command and parameters?

    Thanks,

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

    Thanks,

    Paul

  • 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,

  • 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

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