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