1include::../docbook/attributes.adoc[] 2= extcap(4) 3:doctype: manpage 4:stylesheet: ws.css 5:linkcss: 6:copycss: ../docbook/{stylesheet} 7 8== NAME 9 10extcap - The extcap interface 11 12== DESCRIPTION 13 14The extcap interface is a versatile plugin interface that allows external binaries 15to act as capture interfaces directly in Wireshark. It is used in scenarios, where 16the source of the capture is not a traditional capture model 17(live capture from an interface, from a pipe, from a file, etc). The typical 18example is connecting esoteric hardware of some kind to the main Wireshark application. 19 20Without extcap, a capture can always be achieved by directly writing to a capture file: 21 22 the-esoteric-binary --the-strange-flag --interface=stream1 --file dumpfile.pcap & 23 wireshark dumpfile.pcap 24 25but the extcap interface allows for such a connection to be easily established and 26configured using the Wireshark GUI. 27 28The extcap subsystem is made of multiple extcap binaries that are automatically 29called by the GUI in a row. In the following chapters we will refer to them as 30"the extcaps". 31 32Extcaps may be any binary or script within the extcap directory. Please note, that scripts 33need to be executable without prefacing a script interpreter before the call. 34 35WINDOWS USER: Because of restrictions directly calling the script may not always work. 36In such a case, a batch file may be provided, which then in turn executes the script. Please 37refer to doc/extcap_example.py for more information. 38 39When Wireshark launches an extcap, it automatically adds its installation path 40(c:\Program Files\Wireshark\) to the DLL search path so that the extcap library dependencies 41can be found (it is not designed to be launched by hand). This is done on purpose. There should 42only be extcap programs (executable, python scripts, ...) in the extcap folder to reduce the startup 43time and not have Wireshark trying to execute other file types. 44 45== GRAMMAR ELEMENTS 46 47Grammar elements: 48 49arg (options):: 50+ 51-- 52argument for CLI calling 53-- 54 55number:: 56+ 57-- 58Reference # of argument for other values, display order 59-- 60 61call:: 62+ 63-- 64Literal argument to call (--call=...) 65-- 66 67display:: 68+ 69-- 70Displayed name 71-- 72 73default:: 74+ 75-- 76Default value, in proper form for type 77-- 78 79range:: 80+ 81-- 82Range of valid values for UI checking (min,max) in proper form 83-- 84 85type:: 86+ 87-- 88Argument type for UI filtering for raw, or UI type for selector: 89 90 integer 91 unsigned 92 long (may include scientific / special notation) 93 float 94 selector (display selector table, all values as strings) 95 boolean (display checkbox) 96 radio (display group of radio buttons with provided values, all values as strings) 97 fileselect (display a dialog to select a file from the filesystem, value as string) 98 multicheck (display a textbox for selecting multiple options, values as strings) 99 password (display a textbox with masked text) 100 timestamp (display a calendar) 101-- 102 103value (options):: 104+ 105-- 106 Values for argument selection 107 arg Argument # this value applies to 108-- 109 110== EXAMPLES 111 112Example 1: 113 114 arg {number=0}{call=--channel}{display=Wi-Fi Channel}{type=integer}{required=true} 115 arg {number=1}{call=--chanflags}{display=Channel Flags}{type=radio} 116 arg {number=2}{call=--interface}{display=Interface}{type=selector} 117 value {arg=0}{range=1,11} 118 value {arg=1}{value=ht40p}{display=HT40+} 119 value {arg=1}{value=ht40m}{display=HT40-} 120 value {arg=1}{value=ht20}{display=HT20} 121 value {arg=2}{value=wlan0}{display=wlan0} 122 123Example 2: 124 125 arg {number=0}{call=--usbdevice}{USB Device}{type=selector} 126 value {arg=0}{call=/dev/sysfs/usb/foo/123}{display=Ubertooth One sn 1234} 127 value {arg=0}{call=/dev/sysfs/usb/foo/456}{display=Ubertooth One sn 8901} 128 129Example 3: 130 131 arg {number=0}{call=--usbdevice}{USB Device}{type=selector} 132 arg {number=1}{call=--server}{display=IP address for log server}{type=string}{validation=(?:\d{1,3}\.){3}\d{1,3}} 133 flag {failure=Permission denied opening Ubertooth device} 134 135Example 4: 136 arg {number=0}{call=--username}{display=Username}{type=string} 137 arg {number=1}{call=--password}{display=Password}{type=password} 138 139Example 5: 140 arg {number=0}{call=--start}{display=Start Time}{type=timestamp} 141 arg {number=1}{call=--end}{display=End Time}{type=timestamp} 142 143== Security awareness 144 145- Users running wireshark as root, we can't save you 146- Dumpcap retains suid/setgid and group+x permissions to allow users in wireshark group only 147- Third-party capture programs run w/ whatever privs they're installed with 148- If an attacker can write to a system binary directory, we're game over anyhow 149- Reference the folders tab in the wireshark->about information, to see from which directory extcap is being run 150 151== SEE ALSO 152 153xref:wireshark.html[wireshark](1), xref:tshark.html[tshark](1), xref:dumpcap.html[dumpcap](1), xref:androiddump.html[androiddump](1), xref:sshdump.html[sshdump](1), xref:randpktdump.html[randpktdump](1) 154 155== NOTES 156 157*Extcap* is feature of *Wireshark*. The latest version 158of *Wireshark* can be found at https://www.wireshark.org. 159 160HTML versions of the Wireshark project man pages are available at 161https://www.wireshark.org/docs/man-pages. 162