| Alexander Afanasyev | 6fbb7b4 | 2015-08-10 11:53:49 -0700 | [diff] [blame^] | 1 | ndn-dissect-wireshark |
| 2 | ===================== |
| 3 | |
| 4 | A Wireshark dissector for [Named Data Networking (NDN) packets](http://named-data.net/doc/ndn-tlv/). |
| 5 | |
| 6 | The dissector is able to process and visualize structure of NDN packets encapsulated in |
| 7 | IPv4/IPv6 UDP packets with source of destination port 6363, IPv4/IPv6 TCP packets with |
| 8 | source or destination port 6363, IPv4/IPv6 TCP/HTTP WebSocket packets (any port). |
| 9 | |
| 10 | Note that when UDP packet is fragmented, only the first fragment is getting dissected. |
| 11 | For TCP packets, the dissector assumes that NDN packet starts at the packet boundary, |
| 12 | therefore some NDN packets will not be properly dissected. The same limitation applies to |
| 13 | WebSocket packets. |
| 14 | |
| 15 | Currently, the dissector does not support NDNLPv2 packets, Link, SelectedDelegation fields. |
| 16 | |
| 17 | ## Usage |
| 18 | |
| 19 | By default, the dissector script `ndn.lua` is installed into `/usr/local/share/ndn-dissect-wireshark`. |
| 20 | On some platforms, it may also be installed in `/usr/share/ndn-dissect-wireshark` or |
| 21 | `/opt/local/share/ndn-dissect-wireshark`. To enable the dissector for Wireshark session, |
| 22 | use `-X` command line option, specifying the full path to the `ndn.lua` script: |
| 23 | |
| 24 | wireshark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua |
| 25 | |
| 26 | Similarly, NDN packets dissector can be enabled when using `tshark`: |
| 27 | |
| 28 | tshark shark -X lua_script:/usr/local/share/ndn-dissect-wireshark/ndn.lua |
| 29 | |
| 30 | To enable NDN packets dissector for all future Wireshark sessions, you can create/edit |
| 31 | Wireshark's `init.lua` script, which located in `/usr/share/wireshark`, |
| 32 | `/usr/local/share/wireshark`, `/Applications/Wireshark.app/Contents/Resources/share/wireshark`, |
| 33 | or similar location depending on the platform and the way Wireshark is installed. The |
| 34 | `dofile` command should be added to the end of `init.lua` file: |
| 35 | |
| 36 | -- dofile("/full/path/to/ndn.lua") |
| 37 | dofile("/usr/local/share/ndn-dissect-wireshark/ndn.lua") |
| 38 | |
| 39 | For more detailed information about how to use Lua refer to [Lua wiki](https://wiki.wireshark.org/Lua). |
| 40 | |
| 41 | ## Known issues |
| 42 | |
| 43 | Due to security issues, customized lua scripts are not allowed to be loaded when Wireshark |
| 44 | is started with root privileges. There are two workarounds: |
| 45 | |
| 46 | - run Wireshark, `dumpcap`, or `tcpdump` with root privileges to capture traffic to a file, later |
| 47 | running Wireshark without root privileges and to analyze the captured traffic. |
| 48 | |
| 49 | - (beware of potential security implications) allow non-root users to capture packets: |
| 50 | |
| 51 | * On Linux platform, you can use `setcap` |
| 52 | |
| 53 | sudo setcap cap_net_raw,cap_net_admin=eip /full/path/to/wireshark |
| 54 | |
| 55 | You may need to install a package to use setcap (e.g., `sudo apt-get install libcap2-bin` on Ubuntu) |
| 56 | |
| 57 | * On Debian/Ubuntu Linux, capturing traffic with Wireshark by a non-root user can be enabled by adding |
| 58 | this user to the `wireshark` group. |
| 59 | |
| 60 | See [Wireshark Debian README](http://anonscm.debian.org/viewvc/collab-maint/ext-maint/wireshark/trunk/debian/README.Debian?view=markup) |
| 61 | for more details. |
| 62 | |
| 63 | * On OSX platform, `/dev/bpf*` devices need to be assigned proper permissions |
| 64 | |
| 65 | Automatically using ChmodBPF app |
| 66 | |
| 67 | curl https://bugs.wireshark.org/bugzilla/attachment.cgi?id=3373 -o ChmodBPF.tar.gz |
| 68 | tar zxvf ChmodBPF.tar.gz |
| 69 | open ChmodBPF/Install\ ChmodBPF.app |
| 70 | |
| 71 | or manually: |
| 72 | |
| 73 | sudo chgrp admin /dev/bpf* |
| 74 | sudo chmod g+rw /dev/bpf* |