doc/README.extcap

   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 (live capture from an
   7 interface, from a pipe, from a file, etc). The typical example is connecting esoteric
   8 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
  23 scripts 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.
  27 Please 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}{help=Some help url}
  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
  52 the last one will be used) will be used for displaying the version information of
  53 the extcap 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 name
  56 IFACE.
  57
  58 Using the help argument, an interface may provide a generic help url for the extcap
  59 utility.
  60
  61 STEP2: the extcap is queried for valid DLTs (Data Link Types) for all the
  62 interfaces returned by the step 1.
  63
  64 extcapbin --extcap-dlts --extcap-interface IFACE
  65
  66 This call must print the valid DLTs for the interface specified. This call is
  67 made for all the interfaces and must return 0.
  68
  69 Example:
  70
  71 $ extcapbin --extcap-interface IFACE --extcap-dlts
  72 dlt {number=147}{name=USER1}{display=Demo Implementation for Extcap}
  73
  74 A binary or script, which neither provides an interface list or a DLT list will
  75 not show up in the extcap interfaces list.
  76
  77
  78 STEP3: the extcap is queried for the configuration options for an interface.
  79
  80 extcapbin --extcap-interface IFACE --extcap-config
  81
  82 Each interface can have custom options that are valid for this interface only.
  83 Those config options are specified on the command line when running the actual
  84 capture. To allow an end-user to specify certain options, such options may be
  85 provided using the extcap config argument.
  86
  87 To share which options are available for an interface, the extcap responds to
  88 the command --extcap-config, that shows all the available options (aka additional command
  89 line options).
  90
  91 Those options are automatically presented via a dialog to the user for the individual
  92 interface.
  93
  94 Example:
  95
  96 $ extcapbin --extcap-interface IFACE --extcap-config
  97 arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}{type=integer}{range=1,15}{required=true}
  98 arg {number=1}{call=--message}{display=Message}{tooltip=Package message content}{placeholder=Please enter a message here ...}{type=string}
  99 arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag}
 100 arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}
 101 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}
 102 value {arg=3}{value=if1}{display=Remote1}{default=true}
 103 value {arg=3}{value=if2}{display=Remote2}{default=false}
 104
 105 Now the user can click on the options and change them. They are sent to the
 106 extcap when the capture is launched.
 107
 108 There are two kind of options available:
 109
 110 * file, integer, string, boolean, boolflag - are value based options and each expect
 111   a single value via the command-line call
 112 * selector, checkbox - are selections and can be presented multiple times in the command
 113   line. Both expect subsequent "value" items in the config list, with the corresponding
 114   argument selected via arg
 115
 116
 117 STEP4: the capture. Once the interfaces are listed and configuration is customized
 118 by the user, the capture is run.
 119
 120 extcapbin --extcap-interface IFACE [params] --capture [--extcap-capture-filter CFILTER]
 121   --fifo FIFO
 122
 123 To run the capture, the extcap must implement the --capture, --extcap-capture-filter
 124 and --fifo option.
 125 They are automatically added by wireshark that opens the fifo for reading. All
 126 the other options are automatically added to run the capture. The extcap interface
 127 is used like all other interfaces (meaning that capture on multiple interfaces, as
 128 well as stopping and restarting the capture is supported).
 129
 130
 131 ARGUMENTS
 132 ==========
 133 The extcap interface provides the possibility for generating a GUI dialog to
 134 set and adapt settings for the extcap binary.
 135
 136 All options must provide a number, by which they are identified. No NUMBER may be
 137 provided twice. Also all options must present the elements CALL and DISPLAY, where
 138 call provides the arguments name on the command-line and display the name in the GUI.
 139
 140 Additionally TOOLTIP and PLACEHOLDER may be provided, which will give the user an
 141 explanation within the GUI, about what to enter into this field.
 142
 143 These options do have types, for which the following types are being supported:
 144
 145  * INTEGER, UNSIGNED, LONG, DOUBLE - this provides a field for entering a numeric value
 146    of the given data type. A DEFAULT value may be provided, as well as a RANGE
 147
 148    arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}
 149    {type=integer}{range=1,15}{default=0}
 150
 151  * STRING - Let the user provide a string to the capture
 152
 153    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}
 154
 155    - validation allows to provide a regular expression string, which is used to check
 156      the user input for validity beyond normal data type or range checks. Back-slashes
 157      must be escaped (as in \\b for \b)
 158
 159  * PASSWORD - Let the user provide a masked string to the capture. Password strings are
 160    not saved, when the extcap configuration is being saved
 161
 162    arg {number=0}{call=--password}{display=The user password}{tooltip=The password for the connection}{type=password}
 163
 164  * BOOLEAN,BOOLFLAG - this provides the possibility to set a true/false value.
 165    BOOLFLAG values will only appear in the command-line if set to true, otherwise they
 166    will not be added to the command-line call for the extcap interface
 167
 168    arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag}
 169
 170  * FILESELECT - Let the user provide a filepath to the capture. If MUSTEXIST is
 171    being provided, the GUI checks if the file exists.
 172
 173    arg {number=3}{call=--logfile}{display=Logfile}{tooltip=A file for log messages}{type=fileselect}{mustexist=false}
 174
 175  * SELECTOR, RADIO, MULTICHECK - an optionfield, where the user may choose one or
 176    more options from. If PARENT is provided for the value items, the option fields
 177    for MULTICHECK and SELECTOR are being presented in a tree-like structure. SELECTOR
 178    and RADIO values must present a default value, which will be the value provided to
 179    the extcap binary for this argument
 180
 181    arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}
 182    value {arg=3}{value=if1}{display=Remote1}{default=true}
 183    value {arg=3}{value=if2}{display=Remote2}{default=false}
 184
 185
 186 VALIDATION OF ARGUMENTS
 187 =======================
 188 Arguments may be set with "{required=true}" which enforces a value being provided, before
 189 a capture can be started using the extcap options dialog. This is not being checked, if
 190 the extcap is started via a simple double-click. The necessary fields are marked for the
 191 customer, to ensure a visibility for the end customer of the required argument.
 192
 193 Additionally text and number arguments may also be checked using a regular expression,
 194 which is provided using the validation attribute (see example above). The syntax for
 195 such a check is the same as for Qt RegExp classes. This feature is only active in the
 196 Qt version of Wireshark.
 197
 198
 199 TOOLBAR CONTROLS
 200 ================
 201 An extcap utility can provide configuration for controls to use in an interface toolbar.
 202 This controls are bidirectional and can be used to control the extcap utility while
 203 capturing.
 204
 205 This is useful in scenarios where configuration can be done based on findings in the
 206 capture process, setting temporary values or give other inputs without restarting the
 207 current capture.
 208
 209 Example:
 210
 211 $ extcapbin --extcap-interfaces
 212 extcap {version=1.0}{display=Example extcap interface}
 213 interface {value=example1}{display=Example interface 1 for extcap}
 214 interface {value=example2}{display=Example interface 2 for extcap}
 215 control {number=0}{type=string}{display=Message}{tooltip=Package message content. Must start with a capital letter.}{validation=[A-Z]+}{required=true}
 216 control {number=1}{type=selector}{display=Time delay}{tooltip=Time delay between packages}
 217 control {number=2}{type=boolean}{display=Verify}{default=true}{tooltip=Verify package content}
 218 control {number=3}{type=button}{display=Turn on}{tooltip=Turn on or off}
 219 control {number=4}{type=button}{role=logger}{display=Log}{tooltip=Show capture log}
 220 value {control=1}{value=1}{display=1 sec}
 221 value {control=1}{value=2}{display=2 sec}{default=true}
 222
 223 All controls will be presented as GUI elements in a toolbar specific to the extcap
 224 utility.  The extcap must not rely on using those controls (they are optional) because
 225 of other capturing tools not using GUI (e.g. tshark, tfshark).
 226
 227
 228 CONTROLS
 229 ========
 230 The controls are similar to the ARGUMENTS, but without the CALL element.  All controls
 231 may be given a default value at startup and most can be changed during capture, both
 232 by the extcap and the user (depending on the type of control).
 233
 234 All controls must provide a NUMBER, by which they are identified. No NUMBER may be
 235 provided twice. Also all options must present the elements TYPE and DISPLAY, where
 236 TYPE provides the type of control to add to the toolbar and DISPLAY the name in the GUI.
 237
 238 Additionally TOOLTIP and PLACEHOLDER may be provided, which will give the user an
 239 explanation within the GUI.
 240
 241 All controls, except from the logger, help and restore buttons, may be disabled
 242 (and enabled) in GUI by the extcap during capture. This can be because of set-once
 243 operations, or operations which takes some time to complete.
 244
 245 All control values which are changed by the user (not equal to the default value) will
 246 be sent to the extcap utility when starting a capture.  The extcap utility may choose
 247 to discard initial values and set new values, depending on implementation.
 248
 249 This TYPEs are defined as controls:
 250
 251  * BOOLEAN - This provides a checkbox with the possibility to set a true/false value.
 252
 253    The extcap utility can set a default value at startup, and can change (set) and receive
 254    value changes while capturing. When starting a capture the GUI will send the value if
 255    different from the default value.
 256
 257    The payload is one byte with binary value 0 or 1.
 258
 259    Valid Commands: Set value, Enable, Disable.
 260
 261  * BUTTON - This provides a button with different ROLEs:
 262
 263   ** CONTROL - This button will send a signal when pressed.
 264      This is the default if no role is configured.
 265      The button is only enabled when capturing.
 266
 267      The extcap utility can set the button text at startup, and can change (set) the
 268      button text and receive button press signals while capturing.  The button is
 269      disabled and the button text is restored to the default text when not capturing.
 270
 271      The payload is either the button text or empty (signal).
 272
 273      Valid Commands: Set value, Enable, Disable.
 274
 275   ** LOGGER - This provides a logger mechanism where the extcap utility can send log
 276      entries to be presented in a log window. This communication is unidirectional.
 277
 278      The payload is the log entry, and should be ended with a newline.
 279      Maximum length is 65535 bytes.
 280
 281      Valid Commands: Set log entry, Add log entry.
 282
 283      The Set command will clear the log before adding the entry.
 284
 285   ** HELP - This button opens the help page, if configured.
 286      This role has no controls and will not be used in communication.
 287
 288      Valid Commands: NONE.
 289
 290   ** RESTORE - This button will restore all control values to default.
 291      This role has no controls and will not be used in communication.
 292      The button is only enabled when not capturing.
 293
 294      Valid Commands: NONE.
 295
 296  * SELECTOR - This provides a combo box with fixed values which can be selected.
 297
 298    The extcap utility can set default values at startup, and add and remove values and
 299    receive change in value selection while capturing. When starting a capture the GUI
 300    will send the value if different from the default value.
 301
 302    The payload is a string with the value, and optionally a string with a display
 303    value if this is different from the value. This two string values are separated
 304    by a null character.
 305
 306    Valid Commands: Set selected value, Add value, Remove value, Enable, Disable.
 307
 308    If value is empty the Remove command will remove all entries.
 309
 310  * STRING - This provides a text edit line with the possibility to set a string or any
 311    value which can be represented in a string (integer, float, date, etc.).
 312
 313    The extcap utility can set a default string value at startup, and can change (set) and
 314    receive value changes while capturing. When starting a capture the GUI will send the
 315    value if different from the default value.
 316
 317    The payload is a string with the value. Maximum length is 32767 bytes.
 318
 319    Valid Commands: Set value, Enable, Disable.
 320
 321    The element VALIDATION allows to provide a regular expression string, which is used
 322    to check the user input for validity beyond normal data type or range checks.
 323    Back-slashes must be escaped (as in \\b for \b).
 324
 325
 326 MESSAGES
 327 ========
 328 In addition to the controls it's possible to send a single message from the extcap
 329 utility to the user.  This message can be put in the status bar or displayed in a
 330 information, warning or error dialog which must be accepted by the user.  This message
 331 does not use the NUMBER argument so this can have any value.
 332
 333
 334 CONTROL PROTOCOL
 335 ================
 336 The protocol used to communicate over the control pipes has a fixed size header of
 337 6 bytes and a payload with 0 - 65535 bytes.
 338
 339 Control packet:
 340
 341   +----+----+----+----+----+----+----+----+
 342   |     Sync Pipe Indication (1 byte)     |
 343   +----+----+----+----+----+----+----+----+
 344   |            Message Length             |
 345   |        (3 bytes network order)        |
 346   +----+----+----+----+----+----+----+----+
 347   |        Control Number (1 byte)        |
 348   +----+----+----+----+----+----+----+----+
 349   |           Command (1 byte)            |
 350   +----+----+----+----+----+----+----+----+
 351   |                Payload                |
 352   |           (0 - 65535 bytes)           |
 353   +----+----+----+----+----+----+----+----+
 354
 355  Sync Pipe Indication:
 356   The common sync pipe indication. This protocol uses the value 'T'.
 357
 358  Message Length:
 359   Payload length + 2 bytes for argument number and command.
 360
 361  Control Number:
 362    Unique number to identify the control.  This number also gives the order of
 363    the controls in the interface toolbar.
 364
 365  Command:                  Control type:
 366    0 = Initialized           none
 367    1 = Set                   boolean / button / logger / selector / string
 368    2 = Add                   logger / selector
 369    3 = Remove                selector
 370    4 = Enable                boolean / button / selector / string
 371    5 = Disable               boolean / button / selector / string
 372    6 = Statusbar message     none
 373    7 = Information message   none
 374    8 = Warning message       none
 375    9 = Error message         none
 376
 377  Payload Length:
 378    The length of the following payload.  Maximum length is 65535 bytes.
 379
 380 The Initialized command will be sent from the GUI to the extcap utility when all
 381 user changed control values are sent after starting a capture. This is an indication
 382 that the GUI is ready to receive control values.
 383
 384 The GUI will only send Initialized and Set commands.  The extcap utility shall not
 385 send the Initialized command.
 386
 387 Messages with unknown control number or command will be silently ignored.
 388
 389
 390 DEVELOPMENT
 391 ===========
 392 To have extcap support, extcap must be enabled. Moreover the specific extcap must
 393 be compiled. Examples for autotools and cmake compiling the extcap plugin androiddump
 394 are provided within wireshark. The extcap subsystem and the bundled extcaps are compiled
 395 by default.
 396
 397 autotools: ./configure --with-extcap --enable-androiddump
 398 cmake: cmake -DENABLE_EXTCAP=ON -DBUILD_androiddump ..
 399
 400 Additionally there is an example python script available in doc/extcap_example.py.
 401
 402 When developing a new extcap, it must be created under extcap/ directory and
 403 added to the makefiles. Once compiled it will be under the extcap/ directory
 404 in the build dir.
 405
 406 If the current extcaps configuration is copied, the new extcap will need specific
 407 configuration flags like --enable-<newextcap> or -DBUILD_<newextcap>
 408
 409 Since this is a plugin, the developer must ensure that the extcap dir will be
 410 loaded. To see which dir is loaded, they must open HELP->ABOUT->FOLDER and look
 411 for "Extcap Path". If there is a system path (like /usr/local/lib/wireshark/extcap/)
 412 the extcaps in the build dir are not loaded. To load them, wireshark must be
 413 loaded with WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1. Now the "Extcap path" should
 414 point to the extcap dir under your build environment.