900b69a33e
1. add mount/unmount command 2. add sniffer command, supporting options 3. make pcap a component
124 lines
5.1 KiB
Markdown
124 lines
5.1 KiB
Markdown
# Simple Sniffer Example
|
||
|
||
(See the README.md file in the upper level 'examples' directory for more information about examples.)
|
||
|
||
## Overview
|
||
|
||
This example demonstrates basic usage of wifi sniffer mode by saving packets into SD card with pcap format. Go to wikipedia for more information about [pcap](https://en.wikipedia.org/wiki/Pcap).
|
||
|
||
This example is based on esp-idf's console component. For more information about console you should read this [guide](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/console.html).
|
||
|
||
## How to use example
|
||
|
||
### Hardware Required
|
||
|
||
To run this example, you should have one ESP32 dev board integrated with a SD card slot (e.g ESP32-WROVER Kit) or just connect ESP32-DevKitC to a SD card breakout board.
|
||
|
||
### Configure the project
|
||
|
||
Enter `make menuconfig` if you are using GNU Make based build system or enter `idf.py menuconfig` if you are using CMake based build system. Then go into `Example Configuration` menu.
|
||
|
||
- Check `Store command history in flash` if you want to save command history into flash (recommend).
|
||
- Set the mount point in your filesystem, for example, `/sdcard` if you want to store pcap file into SD card.
|
||
- Set the length of sniffer work queue.
|
||
- Set the stack size of the sniffer task.
|
||
- Set the priority of the sniffer task.
|
||
- Set the max number of packets to store in a single pcap file. The number of packets usually will be very large, so we just truncate them into multiple files. You should set a threshold value here.
|
||
|
||
### Build and Flash
|
||
|
||
Enter `make -j4 flash monitor` if you are using GNU Make based build system or enter `idf.py build flash monitor` if you' are using CMake based build system.
|
||
|
||
(To exit the serial monitor, type ``Ctrl-]``.)
|
||
|
||
See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
|
||
|
||
## Example Output
|
||
|
||
### `sniffer` Command Usage
|
||
|
||
> sniffer [-f <file>][-i ] [-F <mgmt|data|ctrl|misc|mpdu|ampdu>]... [-c <channel>][--stop]
|
||
> Capture specific packet and store in pcap format
|
||
> -f, --file=<file> name of the file storing the packets in pcap format
|
||
> -i, --interface=<wlan> which interface to capture packet
|
||
> -F, --filter=<mgmt|data|ctrl|misc|mpdu|ampdu> filter parameters
|
||
> -c, --channel=<channel> communication channel to use
|
||
> --stop stop running sniffer
|
||
|
||
The `sniffer` command support some important options as follow:
|
||
|
||
* `-f`: Specify the name of file who will store the packets, default value is `sniffer`, and the resulting file name will be like “snifferX.pcap”, here ‘X’ shows the file’s order.
|
||
* `-i`: Specify the interface to sniffer packets, currently only support `wlan`
|
||
* `-c` :Specify the channel to sniffer packet
|
||
* `-F`: Specify the filter condition, currently only support following filter conditions, you can select any number of them
|
||
* mgmt: Management packets
|
||
* data: Data packets
|
||
* ctrl: Control packets
|
||
* misc: Other packets
|
||
* mpdu: MPDU packets
|
||
* ampdu: AMPDU packets
|
||
* `--stop`: Stop sniffer job
|
||
|
||
### Mount SD Card
|
||
|
||
```bash
|
||
=======================================================
|
||
| Steps to sniffer WiFi packets |
|
||
| |
|
||
| 1. Enter 'help' to check all commands' usage |
|
||
| 2. Enter 'mount <device>' to mount filesystem |
|
||
| 3. Enter 'sniffer' to start capture packets |
|
||
| 4. Enter 'unmount <device>' to unmount filesystem |
|
||
| |
|
||
=======================================================
|
||
|
||
esp32> mount sd
|
||
I (158912) example: Initializing SD card
|
||
I (158912) example: Using SDMMC peripheral
|
||
I (158912) gpio: GPIO[13]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0
|
||
Name: SA16G
|
||
Type: SDHC/SDXC
|
||
Speed: 20 MHz
|
||
Size: 14832MB
|
||
```
|
||
|
||
### Start Sniffer
|
||
|
||
```bash
|
||
esp32> sniffer -f sniffer-example -i wlan -c 2
|
||
I (36200) cmd_sniffer: Start WiFi Promicuous Mode
|
||
I (36270) phy: phy_version: 4000, b6198fa, Sep 3 2018, 15:11:06, 0, 0
|
||
I (36270) wifi: ic_enable_sniffer
|
||
I (36290) pcap: Store packets to file: /sdcard/sniffer-example0.pcap
|
||
I (103810) pcap: Close Pcap file OK
|
||
I (103830) pcap: Store packets to file: /sdcard/sniffer-example1.pcap
|
||
I (177300) pcap: Close Pcap file OK
|
||
I (177320) pcap: Store packets to file: /sdcard/sniffer-example2.pcap
|
||
esp32> sniffer --stop
|
||
I (212250) wifi: ic_disable_sniffer
|
||
I (212250) wifi: flush txq
|
||
I (212250) wifi: stop sw txq
|
||
I (212260) wifi: lmac stop hw txq
|
||
I (212340) pcap: Close Pcap file OK
|
||
I (212340) cmd_sniffer: Sniffer Stopped
|
||
```
|
||
|
||
### Unmount SD Card
|
||
|
||
```bash
|
||
esp32> unmount sd
|
||
I (248800) example: Card unmounted
|
||
```
|
||
|
||
### Open PCap File in Wireshark
|
||
|
||
|
||
|
||
## Troubleshooting
|
||
|
||
- Make sure you have pluged in your SD card and mount it into filesystem before doing sniffer work or you will get error message like “Create file /sdcard/sniffer0.pcap failed”.
|
||
- To protect the SD card, we recommand you to execute command `unmount sd` before you plug out your SD card.
|
||
|
||
|
||
|
||
(For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you as soon as possible.) |