doc/androiddump.pod

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