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.