nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 EXTCAP: DEVELOPER GUIDE
2 =======================
3  
4 The extcap interface is a versatile plugin interface that allows external binaries
5 to act as capture interfaces directly in wireshark. It is used in scenarios, where
6 the source of the capture is not a traditional capture model
7 (live capture from an interface, from a pipe, from a file, etc). The typical
8 example is connecting esoteric hardware of some kind to the main wireshark app.
9  
10 Without extcap, a capture can always be achieved by directly writing to a capture file:
11  
12 the-esoteric-binary --the-strange-flag --interface=stream1 --file dumpfile.pcap &
13 wireshark dumpfile.pcap
14  
15 but the extcap interface allows for such a connection to be easily established and
16 configured using the wireshark GUI.
17  
18 The extcap subsystem is made of multiple extcap binaries that are automatically
19 called by the GUI in a row. In the following chapters we will refer to them as
20 "the extcaps".
21  
22 Extcaps may be any binary or script within the extcap directory. Please note, that scripts
23 need to be executable without prefacing a script interpreter before the call.
24  
25 WINDOWS USER: Because of restrictions directly calling the script may not always work.
26 In such a case, a batch file may be provided, which then in turn executes the script. Please
27 refer to doc/extcap_example.py for more information.
28  
29 THE CAPTURE PROCESS
30 ===================
31 The actual capture is run after a setup process that can be made manually by the
32 user or automatically by the GUI. All the steps performed are done for every extcap.
33  
34 Let's go through those steps.
35  
36 STEP1: the extcap is queried for its interfaces.
37  
38 extcapbin --extcap-interfaces
39  
40 This call must print the existing interfaces for this extcap and must return 0.
41 The output must conform to the grammar specified for extcap, and it is specified
42 in the doc/extcap.4 generated man page (in the build dir).
43  
44 Example:
45  
46 $ extcapbin --extcap-interfaces
47 extcap {version=1.0}
48 interface {value=example1}{display=Example interface 1 for extcap}
49 interface {value=example2}{display=Example interface 2 for extcap}
50  
51 The version for the extcap sentence (which may exist as often as wanted, but only the
52 last one will be used) will be used for displaying the version information of the extcap
53 interface in the about dialog of Wireshark (Qt only).
54  
55 The value for each interface will be used in subsequent calls as the interface
56 name IFACE.
57  
58 STEP2: the extcap is queried for valid DLTs (Data Link Types) for all the
59 interfaces returned by the step 1.
60  
61 extcapbin --extcap-dlts --extcap-interface IFACE
62  
63 This call must print the valid DLTs for the interface specified. This call is
64 made for all the interfaces and must return 0.
65  
66 Example:
67  
68 $ extcapbin --extcap-interface IFACE --extcap-dlts
69 dlt {number=147}{name=USER1}{display=Demo Implementation for Extcap}
70  
71 A binary or script, which neither provides an interface list or a DLT list will
72 not show up in the extcap interfaces list.
73  
74  
75 STEP3: the extcap is queried for the configuration options for an interface.
76  
77 extcapbin --extcap-interface IFACE --extcap-config
78  
79 Each interface can have custom options that are valid for this interface only.
80 Those config options are specified on the command line when running the actual
81 capture. To allow an end-user to specify certain options, such options may be
82 provided using the extcap config argument.
83  
84 To share which options are available for an interface, the extcap responds to
85 the command --config, that shows all the available options (aka additional command
86 line options).
87  
88 Those options are automatically presented via a dialog to the user for the individual
89 interface.
90  
91 Example:
92  
93 $ extcapbin --extcap-interface IFACE --extcap-config
94 arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}{type=integer}{range=1,15}{required=true}
95 arg {number=1}{call=--message}{display=Message}{tooltip=Package message content}{type=string}
96 arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag}
97 arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}
98 arg {number=4}{call=--server}{display=IP address for log server}{type=string}{validation=\\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\b}
99 value {arg=3}{value=if1}{display=Remote1}{default=true}
100 value {arg=3}{value=if2}{display=Remote2}{default=false}
101  
102 Now the user can click on the options and change them. They are sent to the
103 extcap when the capture is launched.
104  
105 There are two kind of options available:
106  
107 * file, integer, string, boolean, boolflag - are value based options and each expect a single value
108 via the command-line call
109 * selector, checkbox - are selections and can be presented multiple times in the command line. Both
110 expect subsequent "value" items in the config list, with the corresponding argument selected via arg
111  
112  
113 STEP4: the capture. Once the interfaces are listed and configuration is customized
114 by the user, the capture is run.
115  
116 extcapbin --extcap-interface IFACE [params] --capture [--extcap-capture-filter CFILTER] --fifo FIFO
117  
118 To run the capture, the extcap must implement the --capture, --extcap-capture-filter
119 and --fifo option.
120 They are automatically added by wireshark that opens the fifo for reading. All
121 the other options are automatically added to run the capture. The extcap interface
122 is used like all other interfaces (meaning that capture on multiple interfaces, as
123 well as stopping and restarting the capture is supported).
124  
125  
126 ARGUMENTS
127 ==========
128 The extcap interface provides the possibility for generating a GUI dialog to
129 set and adapt settings for the extcap binary.
130  
131 All options must provide a number, by which they are identified. No NUMBER may be
132 provided twice. Also all options must present the elements CALL and DISPLAY, where
133 call provides the arguments name on the command-line and display the name in the GUI.
134  
135 Additionally TOOLTIP may be provided, which will give the user an explanation within
136 the GUI, about what to enter into this field.
137  
138 These options do have types, for which the following types are being supported:
139  
140 * INTEGER, UNSIGNED, LONG, DOUBLE - this provides a field for entering a numeric value
141 of the given data type. A DEFAULT value may be provided, as well as a RANGE
142  
143 arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}{type=integer}{range=1,15}{default=0}
144  
145 * STRING - Let the user provide a string to the capture
146  
147 arg {number=1}{call=--server}{display=IP Address}{tooltip=IP Address for log server}{type=string}{validation=\\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\b}
148  
149 - validation allows to provide a regular expression string, which is used to check
150 the user input for validity beyond normal data type or range checks. Back-slashes
151 must be escaped (as in \\b for \b)
152  
153 * PASSWORD - Let the user provide a masked string to the capture. Password strings are
154 not saved, when the extcap configuration is being saved
155  
156 arg {number=0}{call=--password}{display=The user password}{tooltip=The password for the connection}{type=password}
157  
158 * BOOLEAN,BOOLFLAG - this provides the possibility to set a true/false value.
159 BOOLFLAG values will only appear in the command-line if set to true, otherwise they
160 will not be added to the command-line call for the extcap interface
161  
162 arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag}
163  
164 * LOGFILE - Let the user provide a filepath to the capture. If FILE_MUSTEXIST is being provided,
165 the GUI checks if the file exists
166  
167 arg {number=3}{call=--logfile}{display=Logfile}{tooltip=A file for log messages}{type=fileselect}{file_mustexist=false}
168  
169 * SELECTOR, RADIO, MULTICHECK - an optionfield, where the user may choose one or more options from.
170 If PARENT is provided for the value items, the option fields for MULTICHECK and SELECTOR are being
171 presented in a tree-like structure. SELECTOR and RADIO values must present a default value, which will
172 be the value provided to the extcap binary for this argument
173  
174 arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}
175 value {arg=3}{value=if1}{display=Remote1}{default=true}
176 value {arg=3}{value=if2}{display=Remote2}{default=false}
177  
178  
179 VALIDATION OF ARGUMENTS
180 =======================
181 Arguments may be set with "{required=true}" which enforces a value being provided, before a capture can be started
182 using the extcap options dialog. This is not being checked, if the extcap is started via a simple double-click. The
183 necessary fields are marked for the customer, to ensure a visibility for the end customer of the required argument.
184  
185 Additionally text and number arguments may also be checked using a regular expression, which is provided using
186 the validation attribute (see example above). The syntax for such a check is the same as for Qt RegExp classes.
187 This feature is only active in the Qt version of Wireshark.
188  
189  
190 DEVELOPMENT
191 ===========
192 To have extcap support, extcap must be enabled. Moreover the specific extcap must
193 be compiled. Examples for autotools and cmake compiling the extcap plugin androiddump
194 are provided within wireshark.
195  
196 autotools: ./configure --with-extcap --enable-androiddump
197 cmake: cmake -DENABLE_EXTCAP=ON -DBUILD_androiddump ..
198  
199 Additionally there is an example python script available in doc/extcap_example.py.
200  
201 When developing a new extcap, it must be created under extcap/ directory and
202 added to the makefiles. Once compiled it will be under the extcap/ directory
203 in the build dir.
204  
205 If the current extcaps configuration is copied, the new extcap will need specific
206 configuration flags like --enable-<newextcap> or -DBUILD_<newextcap>
207  
208 Since this is a plugin, the developer must ensure that the extcap dir will be
209 loaded. To see which dir is loaded, they must open HELP->ABOUT->FOLDER and look
210 for "Extcap Path". If there is a system path (like /usr/local/lib/wireshark/extcap/)
211 the extcaps in the build dir are not loaded. To load them, wireshark must be
212 loaded with WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1. Now the "Extcap path" should
213 point to the extcap dir under your build environment.