Confirm
29
edits
Changes
Created page with "This page describes how to use <code>[http://en.wikipedia.org/wiki/Netcat netcat]</code>, <code>[http://en.wikipedia.org/wiki/Tcpdump tcpdump]</code>, and <em>[http://www.wire..."
This page describes how to use <code>[http://en.wikipedia.org/wiki/Netcat netcat]</code>, <code>[http://en.wikipedia.org/wiki/Tcpdump tcpdump]</code>, and <em>[http://www.wireshark.org/ Wireshark]</em> to monitor network traffic to and from a real Firefox OS phone. (It may also work with the simulator, but that hasn't been tested.)
This has been tested on [http://www.ubuntu.com Ubuntu] 12.10 x64; if you work with a different platform, please update this page with your experiences.
This page is based on the AOSP instructions on [http://www.kandroid.org/online-pdk/guide/tcpdump.html debugging with tcpdump and other tools].
==Prerequisites==
===adb===
These instructions assume you have a working version of <code>adb</code> installed and on your path. <code>adb</code> is necessary to install some needed utilities, and also provides the communications channel between your phone and <em>Wireshark</em>. One way of getting a working copy of <code>adb</code> is to [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Building_and_installing_Firefox_OS build your own version of Firefox OS]; you can also get a prebuilt binary by following [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Firefox_OS_build_prerequisites#Install_adb these instructions].
===udev===
For <code>adb</code> to work, you also need to [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Firefox_OS_build_prerequisites#Configure_the_udev_rule_for_your_phone configure a udev rule for your phone].
==Getting and Installing the Tools==
===Wireshark===
Download and install the latest version of <em>Wireshark</em> through one of the following channels.
====Linux====
* If you are running <em>Ubuntu</em>, you can get the latest <em>Wireshark</em> bundle through the [http://apt.ubuntu.com/p/wireshark Ubuntu Software Centre].
* If you are running another Linux distro, there is very likely a <em>Wireshark</em> package available for you—check the appropriate documentation for your distro.
====Windows and Mac OS X====
* Prepackaged binaries are available [http://www.wireshark.org/download.html here]. Lucky you.
===Local netcat===
====Linux====
* If you are running <em>Ubuntu</em>, you probably already have a local version of <code>netcat</code> installed; if not, you can get it through the [http://apt.ubuntu.com/p/netcat Ubuntu Software Centre].
* If you are running another Linux distro, there is very likely a <code>netcat</code> package available for you—check the appropriate documentation for your distro.
====Windows and Mac OS X====
''TODO: add instructions on installing netcat to Mac OS X, if necessary; Windows is a whole other beast.''
===Remote tcpdump and netcat===
This step installs a pair of utilities onto your Firefox OS phone. Before proceeding, connect your phone to a USB port on your PC and confirm that <code>adb</code> can see your phone by typing:
<pre>
adb devices
</pre>
If your phone doesn't appear, double-check that you have followed [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Firefox_OS_build_prerequisites#Configure_the_udev_rule_for_your_phone these instructions] correctly.
====Getting and Installing====
# Download [https://wiki.mozilla.org/images/4/4d/Nc-tcpdump.zip this archive] containing prebuilt versions of <code>netcat</code> and <code>tcpdump</code> (<code>md5sum 6cf53b270177093326dd8760f5059278</code>);
# Extract the archive contents to a suitable temporary folder;
# Open your temporary folder in a terminal and run the following commands:
<pre>
adb remount
adb push tcpdump /system/xbin/tcpdump
adb shell chmod 0555 /system/xbin/tcpdump
adb push nc /system/xbin/nc
adb shell chmod 0555 /system/xbin/nc
</pre>
If you [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Installing_on_a_mobile_device#Flashing_your_phone reflash the gonk portion of your phone], you will need to repeat the above instructions to reinstall <code>netcat</code> and <code>tcpdump</code>.
====Adding to Your Flash Image====
You can add <code>netcat</code> and <code>tcpdump</code> to your build images permanently by copying them (and making sure their permissions are set to 0555) to the <code>out/target/product/$PRODUCT_NAME/system/xbin</code> subfolder of your B2G root directory, where <code>$PRODUCT_NAME</code> is the name of your phone (i.e. <code>otoro</code>, <code>unagi</code>, etc).
For example, for <code>otoro</code>:
<pre>
cp tcpdump out/target/product/otoro/system/xbin/
chmod 0555 out/target/product/otoro/system/xbin/tcpdump
cp nc out/target/product/otoro/system/xbin/
chmod 0555 out/target/product/otoro/system/xbin/nc
</pre>
Note that if you change your build to another platform, you will need to copy <code>nc</code> and <code>tcpdump</code> to the new <code>xbin</code> folder as well.
==Running Wireshark==
Open two terminals. In the first terminal, run:
<pre>
adb shell "tcpdump -n -s 0 -w - | nc -l -p 11233"
</pre>
In the second terminal, run:
<pre>
adb forward tcp:11233 tcp:11233 && nc 127.0.0.1 11233 | wireshark -k -S -i -
</pre>
The second command will launch Wireshark; if one or more interfaces is active, you should see all of the packets your phone is sending and receiving on those interfaces.
===Gotchas===
Restarting the running live capture in Wireshark (i.e. by clicking on the toolbar icon with the "back" arrow) seems to break the connection to the phone. When this happens, exit Wireshark and kill the <code>tcpdump</code> process (in the first terminal, above), then re-run the two commands again.
==TODO==
# Provide instructions on how to build <code>nc</code> and <code>tcpdump</code> from source.
This has been tested on [http://www.ubuntu.com Ubuntu] 12.10 x64; if you work with a different platform, please update this page with your experiences.
This page is based on the AOSP instructions on [http://www.kandroid.org/online-pdk/guide/tcpdump.html debugging with tcpdump and other tools].
==Prerequisites==
===adb===
These instructions assume you have a working version of <code>adb</code> installed and on your path. <code>adb</code> is necessary to install some needed utilities, and also provides the communications channel between your phone and <em>Wireshark</em>. One way of getting a working copy of <code>adb</code> is to [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Building_and_installing_Firefox_OS build your own version of Firefox OS]; you can also get a prebuilt binary by following [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Firefox_OS_build_prerequisites#Install_adb these instructions].
===udev===
For <code>adb</code> to work, you also need to [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Firefox_OS_build_prerequisites#Configure_the_udev_rule_for_your_phone configure a udev rule for your phone].
==Getting and Installing the Tools==
===Wireshark===
Download and install the latest version of <em>Wireshark</em> through one of the following channels.
====Linux====
* If you are running <em>Ubuntu</em>, you can get the latest <em>Wireshark</em> bundle through the [http://apt.ubuntu.com/p/wireshark Ubuntu Software Centre].
* If you are running another Linux distro, there is very likely a <em>Wireshark</em> package available for you—check the appropriate documentation for your distro.
====Windows and Mac OS X====
* Prepackaged binaries are available [http://www.wireshark.org/download.html here]. Lucky you.
===Local netcat===
====Linux====
* If you are running <em>Ubuntu</em>, you probably already have a local version of <code>netcat</code> installed; if not, you can get it through the [http://apt.ubuntu.com/p/netcat Ubuntu Software Centre].
* If you are running another Linux distro, there is very likely a <code>netcat</code> package available for you—check the appropriate documentation for your distro.
====Windows and Mac OS X====
''TODO: add instructions on installing netcat to Mac OS X, if necessary; Windows is a whole other beast.''
===Remote tcpdump and netcat===
This step installs a pair of utilities onto your Firefox OS phone. Before proceeding, connect your phone to a USB port on your PC and confirm that <code>adb</code> can see your phone by typing:
<pre>
adb devices
</pre>
If your phone doesn't appear, double-check that you have followed [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Firefox_OS_build_prerequisites#Configure_the_udev_rule_for_your_phone these instructions] correctly.
====Getting and Installing====
# Download [https://wiki.mozilla.org/images/4/4d/Nc-tcpdump.zip this archive] containing prebuilt versions of <code>netcat</code> and <code>tcpdump</code> (<code>md5sum 6cf53b270177093326dd8760f5059278</code>);
# Extract the archive contents to a suitable temporary folder;
# Open your temporary folder in a terminal and run the following commands:
<pre>
adb remount
adb push tcpdump /system/xbin/tcpdump
adb shell chmod 0555 /system/xbin/tcpdump
adb push nc /system/xbin/nc
adb shell chmod 0555 /system/xbin/nc
</pre>
If you [https://developer.mozilla.org/en-US/docs/Mozilla/Firefox_OS/Installing_on_a_mobile_device#Flashing_your_phone reflash the gonk portion of your phone], you will need to repeat the above instructions to reinstall <code>netcat</code> and <code>tcpdump</code>.
====Adding to Your Flash Image====
You can add <code>netcat</code> and <code>tcpdump</code> to your build images permanently by copying them (and making sure their permissions are set to 0555) to the <code>out/target/product/$PRODUCT_NAME/system/xbin</code> subfolder of your B2G root directory, where <code>$PRODUCT_NAME</code> is the name of your phone (i.e. <code>otoro</code>, <code>unagi</code>, etc).
For example, for <code>otoro</code>:
<pre>
cp tcpdump out/target/product/otoro/system/xbin/
chmod 0555 out/target/product/otoro/system/xbin/tcpdump
cp nc out/target/product/otoro/system/xbin/
chmod 0555 out/target/product/otoro/system/xbin/nc
</pre>
Note that if you change your build to another platform, you will need to copy <code>nc</code> and <code>tcpdump</code> to the new <code>xbin</code> folder as well.
==Running Wireshark==
Open two terminals. In the first terminal, run:
<pre>
adb shell "tcpdump -n -s 0 -w - | nc -l -p 11233"
</pre>
In the second terminal, run:
<pre>
adb forward tcp:11233 tcp:11233 && nc 127.0.0.1 11233 | wireshark -k -S -i -
</pre>
The second command will launch Wireshark; if one or more interfaces is active, you should see all of the packets your phone is sending and receiving on those interfaces.
===Gotchas===
Restarting the running live capture in Wireshark (i.e. by clicking on the toolbar icon with the "back" arrow) seems to break the connection to the phone. When this happens, exit Wireshark and kill the <code>tcpdump</code> process (in the first terminal, above), then re-run the two commands again.
==TODO==
# Provide instructions on how to build <code>nc</code> and <code>tcpdump</code> from source.
