doc/man_pages/androiddump.adoc

   1 include::../attributes.adoc[]
   2 = androiddump(1)
   3 :doctype: manpage
   4 :stylesheet: ws.css
   5 :linkcss:
   6 :copycss: {css_dir}/{stylesheet}
   7
   8 == NAME
   9
  10 androiddump - Provide interfaces to capture from Android devices
  11
  12 == SYNOPSIS
  13
  14 [manarg]
  15 *androiddump*
  16 [ *--help* ]
  17 [ *--version* ]
  18 [ *--extcap-version* ]
  19 [ *--debug* ]
  20 [ *--extcap-interfaces* ]
  21 [ *--extcap-dlts* ]
  22 [ *--extcap-interface*=<interface> ]
  23 [ *--extcap-config* ]
  24 [ *--extcap-capture-filter*=<capture filter> ]
  25 [ *--capture* ]
  26 [ *--fifo*=<path to file or pipe> ]
  27 [ *--adb-server-ip*=<IP address> ]
  28 [ *--adb-server-tcp-port*=<TCP port> ]
  29 [ *--logcat-text*=<TRUE or FALSE> ]
  30 [ *--bt-server-tcp-port*=<TCP port> ]
  31 [ *--bt-forward-socket*=<TRUE or FALSE> ]
  32 [ *--bt-local-ip*=<IP address> ]
  33 [ *--bt-local-tcp-port*=<TCP port> ]
  34
  35 [manarg]
  36 *androiddump*
  37 *--extcap-interfaces*
  38 [ *--adb-server-ip*=<IP address> ]
  39 [ *--adb-server-tcp-port*=<TCP port> ]
  40
  41 [manarg]
  42 *androiddump*
  43 *--extcap-interface*=<interface>
  44 [ *--extcap-dlts* ]
  45
  46 [manarg]
  47 *androiddump*
  48 *--extcap-interface*=<interface>
  49 [ *--extcap-config* ]
  50
  51 [manarg]
  52 *androiddump*
  53 *--extcap-interface*=<interface>
  54 *--fifo*=<path to file or pipe>
  55 *--capture*
  56
  57 == DESCRIPTION
  58
  59 *Androiddump* is a extcap tool that provide interfaces to capture from
  60 an Android device. There are only two requirements:
  61
  62 1. You must have the Android SDK and add it to your PATH environment variable.
  63 PATH should contain directory with tools like "adb" and "android".
  64 Android SDK for various platform are available on:
  65 https://developer.android.com/sdk/index.html#Other
  66
  67 2. You must have permission to capture from the Android device.
  68 Some Android devices require on-screen authentication.
  69
  70 Supported interfaces:
  71
  72 1. Logcat Main (binary [++<=++Jelly Bean] or text)
  73 2. Logcat System (binary [++<=++Jelly Bean] or text)
  74 3. Logcat Events (binary [++<=++Jelly Bean] or text)
  75 4. Logcat Radio (binary [++<=++Jelly Bean] or text)
  76 5. Logcat Crash (text; from Lollipop)
  77 6. Bluetooth Hcidump [++<=++Jelly Bean]
  78 7. Bluetooth Bluedroid External Parser [Kitkat]
  79 8. Bluetooth BtsnoopNet [>=Lollipop]
  80 9. WiFi/Ethernet tcpdump [needs tcpdump on phone]
  81
  82 Please note that Androiddump will work also for FirefoxOS or other
  83 Android-based operating systems.
  84
  85 == OPTIONS
  86
  87 --help::
  88 Print program arguments.
  89
  90 --version::
  91 Print program version.
  92
  93 --extcap-version::
  94 Print extcapized version.
  95
  96 --debug::
  97 Print additional messages.
  98
  99 --extcap-interfaces::
 100 List available interfaces.
 101
 102 --extcap-interface=<interface>::
 103 Use specified interfaces.
 104
 105 --extcap-dlts::
 106 List DLTs of specified interface.
 107
 108 --extcap-config::
 109 List configuration options of specified interface.
 110
 111 --extcap-capture-filter=<capture filter>::
 112 The capture filter. It corresponds to the value provided via the *tshark -f*
 113 option, and the Capture Filter field next to the interfaces list in the
 114 Wireshark interface.
 115 +
 116 NOTE: This is only respected for Wifi/Ethernet (tcpdump) capturing, not for
 117 Bluetooth or logcat.
 118
 119 --capture::
 120 Start capturing from the specified interface and save it in the location
 121 specified with --fifo.
 122
 123 --fifo=<path to file or pipe>::
 124 Save captured packet to file or send it through pipe.
 125
 126 --adb-server-ip=<IP address>::
 127 Use other than default (127.0.0.1) ADB daemon's IP address.
 128
 129 --adb-server-tcp-port=<TCP port>::
 130 Use other than default (5037) ADB daemon's TCP port.
 131
 132 --logcat-text=<TRUE or FALSE>::
 133 +
 134 --
 135 If TRUE then use text logcat rather then binary. This option only has an
 136 effect on
 137 Logcat interfaces. This have no effect from Lollipop where is no binary Logcat
 138 available.
 139
 140 Defaults to FALSE.
 141 --
 142
 143 --bt-server-tcp-port=<TCP port>::
 144 +
 145 --
 146 Use other than default Bluetooth server TCP port on Android side.
 147 On Lollipop defaults is 8872, earlier 4330.
 148 --
 149
 150 --bt-forward-socket=<TRUE or FALSE>::
 151 +
 152 --
 153 If TRUE then socket from Android side is forwarded to host side.
 154
 155 Defaults to FALSE.
 156 --
 157
 158 --bt-local-ip=<IP address>::
 159 Use other than default (127.0.0.1) IP address on host side for forwarded socket.
 160
 161 --bt-local-tcp-port=<TCP port>::
 162 Specify port to be used on host side for forwarded socket.
 163
 164 == EXAMPLES
 165
 166 To see program arguments:
 167
 168     androiddump --help
 169
 170 To see program version:
 171
 172     androiddump --version
 173
 174 To see interfaces:
 175
 176     androiddump --extcap-interfaces
 177
 178 .Example output
 179 ----
 180 interface {display=Android Logcat Main unknown MSM7627A}{value=android-logcat-main-MSM7627A}
 181 interface {display=Android Logcat System unknown MSM7627A}{value=android-logcat-system-MSM7627A}
 182 interface {display=Android Logcat Radio unknown MSM7627A}{value=android-logcat-radio-MSM7627A}
 183 interface {display=Android Logcat Events unknown MSM7627A}{value=android-logcat-events-MSM7627A}
 184 interface {display=Android Bluetooth Hcidump unknown MSM7627A}{value=android-bluetooth-hcidump-MSM7627A}
 185 ----
 186
 187 Human-readable display name of interfaces contains interface type, one of:
 188
 189     android-logcat-main (Android Logcat Main)
 190     android-logcat-system (Android Logcat System)
 191     android-logcat-radio (Android Logcat Radio)
 192     android-logcat-events (Android Logcat Events)
 193     android-logcat-text-main (Android Logcat Main)
 194     android-logcat-text-system (Android Logcat System)
 195     android-logcat-text-radio (Android Logcat Radio)
 196     android-logcat-text-events (Android Logcat Events)
 197     android-logcat-text-crash (Android Logcat Crash)
 198     android-bluetooth-hcidump (Android Bluetooth Hcidump)
 199     android-bluetooth-external-parser (Android Bluetooth External Parser)
 200     android-bluetooth-btsnoop-net (Android Bluetooth Btsnoop Net)
 201     android-tcpdump (Android tcpdump)
 202
 203 For tcpdump this is followed by target network device name (like `eth0`).
 204
 205 Then Android Device's name if available, otherwise `unknown`.
 206
 207 Last part of it is DeviceID - the identificator of the device provided by Android SDK (see `adb devices`).
 208
 209 For example: `Android Logcat Main unknown MSM7627A`
 210
 211 - `Android Logcat Main` - user-friendly type of interface
 212 - `unknown` - name of Android Device
 213 - `MSM7627A` - device ID
 214
 215 To see interface DLTs:
 216
 217     androiddump --extcap-interface=android-bluetooth-hcidump-MSM7627A --extcap-dlts
 218
 219 .Example output
 220     dlt {number=99}{name=BluetoothH4}{display=Bluetooth HCI UART transport layer plus pseudo-header}
 221
 222 To see interface configuration options:
 223
 224     androiddump --extcap-interface=android-bluetooth-hcidump-MSM7627A --extcap-config
 225
 226 .Example output
 227     arg {number=0}{call=--adb-server-ip}{display=ADB Server IP Address}{type=string}{default=127.0.0.1}
 228     arg {number=1}{call=--adb-server-tcp-port}{display=ADB Server TCP Port}{type=integer}{range=0,65535}{default=5037}
 229
 230 To capture:
 231
 232     androiddump --extcap-interface=android-bluetooth-hcidump-MSM7627A --fifo=/tmp/bluetooth.pcapng --capture
 233
 234 NOTE: To stop capturing CTRL+C/kill/terminate the application.
 235
 236 == SEE ALSO
 237
 238 xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:extcap.html[extcap](4)
 239
 240 == NOTES
 241
 242 *Androiddump* is part of the *Wireshark* distribution.  The latest version
 243 of *Wireshark* can be found at https://www.wireshark.org.
 244
 245 HTML versions of the Wireshark project man pages are available at
 246 https://www.wireshark.org/docs/man-pages.
 247
 248 == AUTHORS
 249
 250 .Original Author
 251 [%hardbreaks]
 252 Michal Labedzki <michal.labedzki[AT]tieto.com>
 253
 254 .Contributors
 255 [%hardbreaks]
 256 Roland Knall <rknall[AT]gmail.com>