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
   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 interface {value=example1}{display=Example interface 1 for extcap}
  48 interface {value=example2}{display=Example interface 2 for extcap}
  49
  50 The value for each interface will be used in subsequent calls as the interface
  51 name IFACE.
  52
  53
  54 STEP2: the extcap is queried for valid DLTs (Data Link Types) for all the
  55 interfaces returned by the step 1.
  56
  57 extcapbin --extcap-dlts --extcap-interface IFACE
  58
  59 This call must print the valid DLTs for the interface specified. This call is
  60 made for all the interfaces and must return 0.
  61
  62 Example:
  63
  64 $ extcapbin --extcap-interface IFACE --extcap-dlts
  65 dlt {number=147}{name=USER1}{display=Demo Implementation for Extcap}
  66
  67 A binary or script, which neither provides an interface list or a DLT list will
  68 not show up in the extcap interfaces list.
  69
  70
  71 STEP3: the extcap is queried for the configuration options for an interface.
  72
  73 extcapbin --extcap-interface IFACE --extcap-config
  74
  75 Each interface can have custom options that are valid for this interface only.
  76 Those config options are specified on the command line when running the actual
  77 capture. To allow an end-user to specify certain options, such options may be
  78 provided using the extcap config argument.
  79
  80 To share which options are available for an interface, the extcap responds to
  81 the command --config, that shows all the available options (aka additional command
  82 line options).
  83
  84 Those options are automatically presented via a dialog to the user for the individual
  85 interface.
  86
  87 Example:
  88
  89 $ extcapbin --extcap-interface IFACE --extcap-config
  90 arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}{type=integer}{range=1,15}
  91 arg {number=1}{call=--message}{display=Message}{tooltip=Package message content}{type=string}
  92 arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag}
  93 arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}
  94 value {arg=3}{value=if1}{display=Remote1}{default=true}
  95 value {arg=3}{value=if2}{display=Remote2}{default=false}
  96
  97 Now the user can click on the options and change them. They are sent to the
  98 extcap when the capture is launched.
  99
 100 There are two kind of options available:
 101
 102 * file, integer, string, boolean, boolflag - are value based options and each expect a single value
 103   via the command-line call
 104 * selector, checkbox - are selections and can be presented multiple times in the command line. Both
 105   expect subsequent "value" items in the config list, with the corresponding argument selected via arg
 106
 107
 108 STEP4: the capture. Once the interfaces are listed and configuration is customized
 109 by the user, the capture is run.
 110
 111 extcapbin --extcap-interface IFACE [params] --capture [--extcap-capture-filter CFILTER] --fifo FIFO
 112
 113 To run the capture, the extcap must implement the --capture, --extcap-capture-filter
 114 and --fifo option.
 115 They are automatically added by wireshark that opens the fifo for reading. All
 116 the other options are automatically added to run the capture. The extcap interface
 117 is used like all other interfaces (meaning that capture on multiple interfaces, as
 118 well as stopping and restarting the capture is supported).
 119
 120
 121 ARGUMENTS
 122 ==========
 123 The extcap interface provides the possibility for generating a GUI dialog to
 124 set and adapt settings for the extcap binary.
 125
 126 All options must provide a number, by which they are identified. No NUMBER may be
 127 provided twice. Also all options must present the elements CALL and DISPLAY, where
 128 call provides the arguments name on the command-line and display the name in the GUI.
 129
 130 Additionally TOOLTIP may be provided, which will give the user an explanation within
 131 the GUI, about what to enter into this field.
 132
 133 These options do have types, for which the following types are being supported:
 134
 135  * INTEGER, UNSIGNED, LONG, DOUBLE - this provides a field for entering a numeric value
 136    of the given data type. A DEFAULT value may be provided, as well as a RANGE
 137
 138    arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}{type=integer}{range=1,15}{default=0}
 139
 140  * STRING - Let the user provide a string to the capture
 141
 142    arg {number=1}{call=--message}{display=Message}{tooltip=Package message content}{type=string}
 143
 144  * BOOLEAN,BOOLFLAG - this provides the possibility to set a true/false value.
 145    BOOLFLAG values will only appear in the command-line if set to true, otherwise they
 146    will not be added to the command-line call for the extcap interface
 147
 148    arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag}
 149
 150  * LOGFILE - Let the user provide a filepath to the capture. If FILE_MUSTEXIST is being provided,
 151    the GUI checks if the file exists
 152
 153    arg {number=3}{call=--logfile}{display=Logfile}{tooltip=A file for log messages}{type=fileselect}{file_mustexist=false}
 154
 155  * SELECTOR, RADIO, MULTICHECK - an optionfield, where the user may choose one or more options from.
 156    If PARENT is provided for the value items, the option fields for MULTICHECK and SELECTOR are being
 157    presented in a tree-like structure. SELECTOR and RADIO values must present a default value, which will
 158    be the value provided to the extcap binary for this argument
 159
 160    arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}
 161    value {arg=3}{value=if1}{display=Remote1}{default=true}
 162    value {arg=3}{value=if2}{display=Remote2}{default=false}
 163
 164
 165 DEVELOPMENT
 166 ===========
 167 To have extcap support, extcap must be enabled. Moreover the specific extcap must
 168 be compiled. Examples for autotools and cmake compiling the extcap plugin androiddump
 169 are provided within wireshark.
 170
 171 autotools: ./configure --with-extcap --enable-androiddump
 172 cmake: cmake -DENABLE_EXTCAP=ON -DBUILD_androiddump ..
 173
 174 Additionally there is an example python script available in doc/extcap_example.py.
 175
 176 When developing a new extcap, it must be created under extcap/ directory and
 177 added to the makefiles. Once compiled it will be under the extcap/ directory
 178 in the build dir.
 179
 180 If the current extcaps configuration is copied, the new extcap will need specific
 181 configuration flags like --enable-<newextcap> or -DBUILD_<newextcap>
 182
 183 Since this is a plugin, the developer must ensure that the extcap dir will be
 184 loaded. To see which dir is loaded, they must open HELP->ABOUT->FOLDER and look
 185 for "Extcap Path". If there is a system path (like /usr/local/lib/wireshark/extcap/)
 186 the extcaps in the build dir are not loaded. To load them, wireshark must be
 187 loaded with WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1. Now the "Extcap path" should
 188 point to the extcap dir under your build environment.