Maynard, Chris
2014-05-31 16:20:36 UTC
Attached is a proof-of-concept Windows batch file, which serves as a front-end for dumpcap.exe. It supports triggered capturing and with the help of the external command-line mailsend tool, it supports event notifications via e-mail as well. For additional flexibility, it also provides hooks for running your own arbitrary commands in addition to (or in lieu of) e-mail notifications. The attached batch file has been renamed as a .txt file since many mail servers reject .bat files.
Why might you want a front-end for dumpcap.exe?
Forgetting about event notification and triggering for the moment, the batch file allows you to enter and save many dumpcap capture parameters, such as the capture interface, the capture filter (which might be quite complex), etc. By saving these settings in separate configuration files, you can maintain a repository of potentially useful, reusable settings. Once you figure out your complicated capture filter, for example, you need not ever have to derive it again. You can also share these settings with colleagues by sending them your configuration file. With perhaps a few minor tweaks to the configuration, they can more easily and more quickly start capturing using proven and pre-tested settings.
So what about event notification and triggered captures?
These are features that people have inquired about in the past, either through Bugzilla, the Wireshark Ask Q&A site, or via the Wireshark mailing lists. Let me be clear in that this batch file does not address the concerns and desires of all inquiries. I believe it helps to address a number of them though, and *may* help others to fill the gap where this batch file falls short. There are almost certainly better long-term solutions than this, but you might find it at least somewhat useful in the interim.
I want to try it; how do I get started?
First, download the attached batch file, renaming it as dumpcap.bat. To experiment with event notification, you will need to download mailsend v1.17b14 (or later) from https://code.google.com/p/mailsend/ and save it in the same directory as the batch file; however, you must rename it to mailsend.exe. If you want to be able to attach small capture files to your e-mails, in some cases the batch file relies on handle.exe from sysinternals, so I recommend that you download handle.exe v3.51 from http://technet.microsoft.com/en-us/sysinternals/bb896655.aspx and also save it in the same directory as the batch file. Depending on your capture settings, you may need to run the command prompt as administrator in order to be able to attach certain capture files, such as temporary files or files created as part of a ringbuffer.
I want to try it; how does it work?
There are 4 basic modes of operation; choose the one that best fits what you're trying to accomplish:
1. Dumpcap only: Use this mode if you're not necessarily interested in separate event notifications or triggered captures. Perhaps you only want to take advantage of the stored configuration settings so you don't have to keep re-typing complicated capture filters. Or maybe you want a basic notification of when the main capturing stops, for example after a certain number of packets have been captured and dumpcap terminates itself.
2. Dumpcap+Event: This mode would be used if you wanted to capture arbitrary traffic, but you also wanted to know when a specific capture event occurred and possibly take some action once it did. Besides sending you a notification, you might want to terminate the main capturing, perhaps after a slight delay so you could continue capturing for some time period following the capture event of interest. If you've ever been looking for a needle in a haystack and had to leave dumpcap running for long periods of time waiting for that needle, this mode might be useful to you.
3. Trigger: This mode would be used when you want to start capturing traffic following a particular capture event of interest. It should be noted however that the current implementation is such that the capture event itself won't be included in the resulting capture file, since main capturing won't be initiated until after the event occurs. To me, this makes the Trigger mode less useful, but it might serve someone's purpose.
4. Event only: The batch file currently does not support all dumpcap options. Of particular note, it doesn't support capturing from multiple interfaces or specifying a different capture filter, snaplen, etc. for each of the different interfaces you might be interested in capturing packets from. If you have special capturing needs, but are still interested in capture event notifications, you can always launch your own dumpcap instance, and then run the batch file in "Event only" mode. In this mode, no main dumpcap capturing will be initiated either before or after the event, as presumably, you've already started it. If you wish, you can still terminate that capturing following the event however.
Run "dumpcap.bat -h" for some additional help, and read the batch file itself as there's more information included there as well.
- Chris
Digests:
dumpcap.txt: 102,998 bytes
MD5(dumpcap.txt)= 2ee016a55e545b43082e63c611c7aad7
SHA1(dumpcap.txt)= 7cb14aff6f9a48803a5a46ff9de4fdb408720283
RIPEMD160(dumpcap.txt)= 9481bb71da59f72a7cdae506b79c2ae861009205
--
CONFIDENTIALITY NOTICE: The information contained in this email message is intended only for use of the intended recipient. If the reader of this message is not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this communication in error, please immediately delete it from your system and notify the sender by replying to this email. Â Thank you.
Why might you want a front-end for dumpcap.exe?
Forgetting about event notification and triggering for the moment, the batch file allows you to enter and save many dumpcap capture parameters, such as the capture interface, the capture filter (which might be quite complex), etc. By saving these settings in separate configuration files, you can maintain a repository of potentially useful, reusable settings. Once you figure out your complicated capture filter, for example, you need not ever have to derive it again. You can also share these settings with colleagues by sending them your configuration file. With perhaps a few minor tweaks to the configuration, they can more easily and more quickly start capturing using proven and pre-tested settings.
So what about event notification and triggered captures?
These are features that people have inquired about in the past, either through Bugzilla, the Wireshark Ask Q&A site, or via the Wireshark mailing lists. Let me be clear in that this batch file does not address the concerns and desires of all inquiries. I believe it helps to address a number of them though, and *may* help others to fill the gap where this batch file falls short. There are almost certainly better long-term solutions than this, but you might find it at least somewhat useful in the interim.
I want to try it; how do I get started?
First, download the attached batch file, renaming it as dumpcap.bat. To experiment with event notification, you will need to download mailsend v1.17b14 (or later) from https://code.google.com/p/mailsend/ and save it in the same directory as the batch file; however, you must rename it to mailsend.exe. If you want to be able to attach small capture files to your e-mails, in some cases the batch file relies on handle.exe from sysinternals, so I recommend that you download handle.exe v3.51 from http://technet.microsoft.com/en-us/sysinternals/bb896655.aspx and also save it in the same directory as the batch file. Depending on your capture settings, you may need to run the command prompt as administrator in order to be able to attach certain capture files, such as temporary files or files created as part of a ringbuffer.
I want to try it; how does it work?
There are 4 basic modes of operation; choose the one that best fits what you're trying to accomplish:
1. Dumpcap only: Use this mode if you're not necessarily interested in separate event notifications or triggered captures. Perhaps you only want to take advantage of the stored configuration settings so you don't have to keep re-typing complicated capture filters. Or maybe you want a basic notification of when the main capturing stops, for example after a certain number of packets have been captured and dumpcap terminates itself.
2. Dumpcap+Event: This mode would be used if you wanted to capture arbitrary traffic, but you also wanted to know when a specific capture event occurred and possibly take some action once it did. Besides sending you a notification, you might want to terminate the main capturing, perhaps after a slight delay so you could continue capturing for some time period following the capture event of interest. If you've ever been looking for a needle in a haystack and had to leave dumpcap running for long periods of time waiting for that needle, this mode might be useful to you.
3. Trigger: This mode would be used when you want to start capturing traffic following a particular capture event of interest. It should be noted however that the current implementation is such that the capture event itself won't be included in the resulting capture file, since main capturing won't be initiated until after the event occurs. To me, this makes the Trigger mode less useful, but it might serve someone's purpose.
4. Event only: The batch file currently does not support all dumpcap options. Of particular note, it doesn't support capturing from multiple interfaces or specifying a different capture filter, snaplen, etc. for each of the different interfaces you might be interested in capturing packets from. If you have special capturing needs, but are still interested in capture event notifications, you can always launch your own dumpcap instance, and then run the batch file in "Event only" mode. In this mode, no main dumpcap capturing will be initiated either before or after the event, as presumably, you've already started it. If you wish, you can still terminate that capturing following the event however.
Run "dumpcap.bat -h" for some additional help, and read the batch file itself as there's more information included there as well.
- Chris
Digests:
dumpcap.txt: 102,998 bytes
MD5(dumpcap.txt)= 2ee016a55e545b43082e63c611c7aad7
SHA1(dumpcap.txt)= 7cb14aff6f9a48803a5a46ff9de4fdb408720283
RIPEMD160(dumpcap.txt)= 9481bb71da59f72a7cdae506b79c2ae861009205
--
CONFIDENTIALITY NOTICE: The information contained in this email message is intended only for use of the intended recipient. If the reader of this message is not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this communication in error, please immediately delete it from your system and notify the sender by replying to this email. Â Thank you.