forked from osmocom/wireshark
411 lines
18 KiB
Plaintext
411 lines
18 KiB
Plaintext
EXTCAP: DEVELOPER GUIDE
|
|
=======================
|
|
|
|
The extcap interface is a versatile plugin interface that allows external binaries
|
|
to act as capture interfaces directly in wireshark. It is used in scenarios, where
|
|
the source of the capture is not a traditional capture model (live capture from an
|
|
interface, from a pipe, from a file, etc). The typical example is connecting esoteric
|
|
hardware of some kind to the main wireshark app.
|
|
|
|
Without extcap, a capture can always be achieved by directly writing to a capture file:
|
|
|
|
the-esoteric-binary --the-strange-flag --interface=stream1 --file dumpfile.pcap &
|
|
wireshark dumpfile.pcap
|
|
|
|
but the extcap interface allows for such a connection to be easily established and
|
|
configured using the wireshark GUI.
|
|
|
|
The extcap subsystem is made of multiple extcap binaries that are automatically
|
|
called by the GUI in a row. In the following chapters we will refer to them as
|
|
"the extcaps".
|
|
|
|
Extcaps may be any binary or script within the extcap directory. Please note, that
|
|
scripts need to be executable without prefacing a script interpreter before the call.
|
|
|
|
WINDOWS USER: Because of restrictions directly calling the script may not always work.
|
|
In such a case, a batch file may be provided, which then in turn executes the script.
|
|
Please refer to doc/extcap_example.py for more information.
|
|
|
|
THE CAPTURE PROCESS
|
|
===================
|
|
The actual capture is run after a setup process that can be made manually by the
|
|
user or automatically by the GUI. All the steps performed are done for every extcap.
|
|
|
|
Let's go through those steps.
|
|
|
|
STEP1: the extcap is queried for its interfaces.
|
|
|
|
extcapbin --extcap-interfaces
|
|
|
|
This call must print the existing interfaces for this extcap and must return 0.
|
|
The output must conform to the grammar specified for extcap, and it is specified
|
|
in the doc/extcap.4 generated man page (in the build dir).
|
|
|
|
Example:
|
|
|
|
$ extcapbin --extcap-interfaces
|
|
extcap {version=1.0}{help=Some help url}
|
|
interface {value=example1}{display=Example interface 1 for extcap}
|
|
interface {value=example2}{display=Example interface 2 for extcap}
|
|
|
|
The version for the extcap sentence (which may exist as often as wanted, but only
|
|
the last one will be used) will be used for displaying the version information of
|
|
the extcap interface in the about dialog of Wireshark (Qt only).
|
|
|
|
The value for each interface will be used in subsequent calls as the interface name
|
|
IFACE.
|
|
|
|
Using the help argument, an interface may provide a generic help url for the extcap
|
|
utility.
|
|
|
|
STEP2: the extcap is queried for valid DLTs (Data Link Types) for all the
|
|
interfaces returned by the step 1.
|
|
|
|
extcapbin --extcap-dlts --extcap-interface IFACE
|
|
|
|
This call must print the valid DLTs for the interface specified. This call is
|
|
made for all the interfaces and must return 0.
|
|
|
|
Example:
|
|
|
|
$ extcapbin --extcap-interface IFACE --extcap-dlts
|
|
dlt {number=147}{name=USER1}{display=Demo Implementation for Extcap}
|
|
|
|
A binary or script, which neither provides an interface list or a DLT list will
|
|
not show up in the extcap interfaces list.
|
|
|
|
|
|
STEP3: the extcap is queried for the configuration options for an interface.
|
|
|
|
extcapbin --extcap-interface IFACE --extcap-config
|
|
|
|
Each interface can have custom options that are valid for this interface only.
|
|
Those config options are specified on the command line when running the actual
|
|
capture. To allow an end-user to specify certain options, such options may be
|
|
provided using the extcap config argument.
|
|
|
|
To share which options are available for an interface, the extcap responds to
|
|
the command --extcap-config, that shows all the available options (aka additional command
|
|
line options).
|
|
|
|
Those options are automatically presented via a dialog to the user for the individual
|
|
interface.
|
|
|
|
Example:
|
|
|
|
$ extcapbin --extcap-interface IFACE --extcap-config
|
|
arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}{type=integer}{range=1,15}{required=true}
|
|
arg {number=1}{call=--message}{display=Message}{tooltip=Package message content}{placeholder=Please enter a message here ...}{type=string}
|
|
arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag}
|
|
arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}
|
|
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}
|
|
value {arg=3}{value=if1}{display=Remote1}{default=true}
|
|
value {arg=3}{value=if2}{display=Remote2}{default=false}
|
|
|
|
Now the user can click on the options and change them. They are sent to the
|
|
extcap when the capture is launched.
|
|
|
|
There are two kind of options available:
|
|
|
|
* file, integer, string, boolean, boolflag - are value based options and each expect
|
|
a single value via the command-line call
|
|
* selector, checkbox - are selections and can be presented multiple times in the command
|
|
line. Both expect subsequent "value" items in the config list, with the corresponding
|
|
argument selected via arg
|
|
|
|
|
|
STEP4: the capture. Once the interfaces are listed and configuration is customized
|
|
by the user, the capture is run.
|
|
|
|
extcapbin --extcap-interface IFACE [params] --capture [--extcap-capture-filter CFILTER]
|
|
--fifo FIFO
|
|
|
|
To run the capture, the extcap must implement the --capture, --extcap-capture-filter
|
|
and --fifo option.
|
|
They are automatically added by wireshark that opens the fifo for reading. All
|
|
the other options are automatically added to run the capture. The extcap interface
|
|
is used like all other interfaces (meaning that capture on multiple interfaces, as
|
|
well as stopping and restarting the capture is supported).
|
|
|
|
|
|
ARGUMENTS
|
|
==========
|
|
The extcap interface provides the possibility for generating a GUI dialog to
|
|
set and adapt settings for the extcap binary.
|
|
|
|
All options must provide a number, by which they are identified. No NUMBER may be
|
|
provided twice. Also all options must present the elements CALL and DISPLAY, where
|
|
call provides the arguments name on the command-line and display the name in the GUI.
|
|
|
|
Additionally TOOLTIP and PLACEHOLDER may be provided, which will give the user an
|
|
explanation within the GUI, about what to enter into this field.
|
|
|
|
These options do have types, for which the following types are being supported:
|
|
|
|
* INTEGER, UNSIGNED, LONG, DOUBLE - this provides a field for entering a numeric value
|
|
of the given data type. A DEFAULT value may be provided, as well as a RANGE
|
|
|
|
arg {number=0}{call=--delay}{display=Time delay}{tooltip=Time delay between packages}
|
|
{type=integer}{range=1,15}{default=0}
|
|
|
|
* STRING - Let the user provide a string to the capture
|
|
|
|
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}
|
|
|
|
- validation allows to provide a regular expression string, which is used to check
|
|
the user input for validity beyond normal data type or range checks. Back-slashes
|
|
must be escaped (as in \\b for \b)
|
|
|
|
* PASSWORD - Let the user provide a masked string to the capture. Password strings are
|
|
not saved, when the extcap configuration is being saved
|
|
|
|
arg {number=0}{call=--password}{display=The user password}{tooltip=The password for the connection}{type=password}
|
|
|
|
* BOOLEAN,BOOLFLAG - this provides the possibility to set a true/false value.
|
|
BOOLFLAG values will only appear in the command-line if set to true, otherwise they
|
|
will not be added to the command-line call for the extcap interface
|
|
|
|
arg {number=2}{call=--verify}{display=Verify}{tooltip=Verify package content}{type=boolflag}
|
|
|
|
* FILESELECT - Let the user provide a filepath to the capture. If MUSTEXIST is
|
|
being provided, the GUI checks if the file exists.
|
|
|
|
arg {number=3}{call=--logfile}{display=Logfile}{tooltip=A file for log messages}{type=fileselect}{mustexist=false}
|
|
|
|
* SELECTOR, RADIO, MULTICHECK - an optionfield, where the user may choose one or
|
|
more options from. If PARENT is provided for the value items, the option fields
|
|
for MULTICHECK and SELECTOR are being presented in a tree-like structure. SELECTOR
|
|
and RADIO values must present a default value, which will be the value provided to
|
|
the extcap binary for this argument
|
|
|
|
arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}
|
|
value {arg=3}{value=if1}{display=Remote1}{default=true}
|
|
value {arg=3}{value=if2}{display=Remote2}{default=false}
|
|
|
|
|
|
VALIDATION OF ARGUMENTS
|
|
=======================
|
|
Arguments may be set with "{required=true}" which enforces a value being provided, before
|
|
a capture can be started using the extcap options dialog. This is not being checked, if
|
|
the extcap is started via a simple double-click. The necessary fields are marked for the
|
|
customer, to ensure a visibility for the end customer of the required argument.
|
|
|
|
Additionally text and number arguments may also be checked using a regular expression,
|
|
which is provided using the validation attribute (see example above). The syntax for
|
|
such a check is the same as for Qt RegExp classes. This feature is only active in the
|
|
Qt version of Wireshark.
|
|
|
|
|
|
TOOLBAR CONTROLS
|
|
================
|
|
An extcap utility can provide configuration for controls to use in an interface toolbar.
|
|
This controls are bidirectional and can be used to control the extcap utility while
|
|
capturing.
|
|
|
|
This is useful in scenarios where configuration can be done based on findings in the
|
|
capture process, setting temporary values or give other inputs without restarting the
|
|
current capture.
|
|
|
|
Example:
|
|
|
|
$ extcapbin --extcap-interfaces
|
|
extcap {version=1.0}{display=Example extcap interface}
|
|
interface {value=example1}{display=Example interface 1 for extcap}
|
|
interface {value=example2}{display=Example interface 2 for extcap}
|
|
control {number=0}{type=string}{display=Message}{tooltip=Package message content. Must start with a capital letter.}{validation=[A-Z]+}{required=true}
|
|
control {number=1}{type=selector}{display=Time delay}{tooltip=Time delay between packages}
|
|
control {number=2}{type=boolean}{display=Verify}{default=true}{tooltip=Verify package content}
|
|
control {number=3}{type=button}{display=Turn on}{tooltip=Turn on or off}
|
|
control {number=4}{type=button}{role=logger}{display=Log}{tooltip=Show capture log}
|
|
value {control=1}{value=1}{display=1 sec}
|
|
value {control=1}{value=2}{display=2 sec}{default=true}
|
|
|
|
All controls will be presented as GUI elements in a toolbar specific to the extcap
|
|
utility. The extcap must not rely on using those controls (they are optional) because
|
|
of other capturing tools not using GUI (e.g. tshark, tfshark).
|
|
|
|
|
|
CONTROLS
|
|
========
|
|
The controls are similar to the ARGUMENTS, but without the CALL element. All controls
|
|
may be given a default value at startup and most can be changed during capture, both
|
|
by the extcap and the user (depending on the type of control).
|
|
|
|
All controls must provide a NUMBER, by which they are identified. No NUMBER may be
|
|
provided twice. Also all options must present the elements TYPE and DISPLAY, where
|
|
TYPE provides the type of control to add to the toolbar and DISPLAY the name in the GUI.
|
|
|
|
Additionally TOOLTIP and PLACEHOLDER may be provided, which will give the user an
|
|
explanation within the GUI.
|
|
|
|
All controls, except from the logger, help and restore buttons, may be disabled
|
|
(and enabled) in GUI by the extcap during capture. This can be because of set-once
|
|
operations, or operations which takes some time to complete.
|
|
|
|
All control values which are changed by the user (not equal to the default value) will
|
|
be sent to the extcap utility when starting a capture. The extcap utility may choose
|
|
to discard initial values and set new values, depending on implementation.
|
|
|
|
This TYPEs are defined as controls:
|
|
|
|
* BOOLEAN - This provides a checkbox with the possibility to set a true/false value.
|
|
|
|
The extcap utility can set a default value at startup, and can change (set) and receive
|
|
value changes while capturing. When starting a capture the GUI will send the value if
|
|
different from the default value.
|
|
|
|
The payload is one byte with binary value 0 or 1.
|
|
|
|
Valid Commands: Set value, Enable, Disable.
|
|
|
|
* BUTTON - This provides a button with different ROLEs:
|
|
|
|
** CONTROL - This button will send a signal when pressed.
|
|
This is the default if no role is configured.
|
|
The button is only enabled when capturing.
|
|
|
|
The extcap utility can set the button text at startup, and can change (set) the
|
|
button text and receive button press signals while capturing. The button is
|
|
disabled and the button text is restored to the default text when not capturing.
|
|
|
|
The payload is either the button text or empty (signal).
|
|
|
|
Valid Commands: Set value, Enable, Disable.
|
|
|
|
** LOGGER - This provides a logger mechanism where the extcap utility can send log
|
|
entries to be presented in a log window. This communication is unidirectional.
|
|
|
|
The payload is the log entry, and should be ended with a newline.
|
|
Maximum length is 65535 bytes.
|
|
|
|
Valid Commands: Set log entry, Add log entry.
|
|
|
|
The Set command will clear the log before adding the entry.
|
|
|
|
** HELP - This button opens the help page, if configured.
|
|
This role has no controls and will not be used in communication.
|
|
|
|
Valid Commands: NONE.
|
|
|
|
** RESTORE - This button will restore all control values to default.
|
|
This role has no controls and will not be used in communication.
|
|
The button is only enabled when not capturing.
|
|
|
|
Valid Commands: NONE.
|
|
|
|
* SELECTOR - This provides a combo box with fixed values which can be selected.
|
|
|
|
The extcap utility can set default values at startup, and add and remove values and
|
|
receive change in value selection while capturing. When starting a capture the GUI
|
|
will send the value if different from the default value.
|
|
|
|
The payload is a string with the value, and optionally a string with a display
|
|
value if this is different from the value. This two string values are separated
|
|
by a null character.
|
|
|
|
Valid Commands: Set selected value, Add value, Remove value, Enable, Disable.
|
|
|
|
If value is empty the Remove command will remove all entries.
|
|
|
|
* STRING - This provides a text edit line with the possibility to set a string or any
|
|
value which can be represented in a string (integer, float, date, etc.).
|
|
|
|
The extcap utility can set a default string value at startup, and can change (set) and
|
|
receive value changes while capturing. When starting a capture the GUI will send the
|
|
value if different from the default value.
|
|
|
|
The payload is a string with the value. Maximum length is 32767 bytes.
|
|
|
|
Valid Commands: Set value, Enable, Disable.
|
|
|
|
The element VALIDATION allows to provide a regular expression string, which is used
|
|
to check the user input for validity beyond normal data type or range checks.
|
|
Back-slashes must be escaped (as in \\b for \b).
|
|
|
|
|
|
MESSAGES
|
|
========
|
|
In addition to the controls it's possible to send a single message from the extcap
|
|
utility to the user. This message can be put in the status bar or displayed in a
|
|
information, warning or error dialog which must be accepted by the user. This message
|
|
does not use the NUMBER argument so this can have any value.
|
|
|
|
|
|
CONTROL PROTOCOL
|
|
================
|
|
The protocol used to communicate over the control pipes has a fixed size header of
|
|
6 bytes and a payload with 0 - 65535 bytes.
|
|
|
|
Control packet:
|
|
|
|
+----+----+----+----+----+----+----+----+
|
|
| Sync Pipe Indication (1 byte) |
|
|
+----+----+----+----+----+----+----+----+
|
|
| Message Length |
|
|
| (3 bytes network order) |
|
|
+----+----+----+----+----+----+----+----+
|
|
| Control Number (1 byte) |
|
|
+----+----+----+----+----+----+----+----+
|
|
| Command (1 byte) |
|
|
+----+----+----+----+----+----+----+----+
|
|
| Payload |
|
|
| (0 - 65535 bytes) |
|
|
+----+----+----+----+----+----+----+----+
|
|
|
|
Sync Pipe Indication:
|
|
The common sync pipe indication. This protocol uses the value 'T'.
|
|
|
|
Message Length:
|
|
Payload length + 2 bytes for control number and command.
|
|
|
|
Control Number:
|
|
Unique number to identify the control. This number also gives the order of
|
|
the controls in the interface toolbar.
|
|
|
|
Command: Control type:
|
|
0 = Initialized none
|
|
1 = Set boolean / button / logger / selector / string
|
|
2 = Add logger / selector
|
|
3 = Remove selector
|
|
4 = Enable boolean / button / selector / string
|
|
5 = Disable boolean / button / selector / string
|
|
6 = Statusbar message none
|
|
7 = Information message none
|
|
8 = Warning message none
|
|
9 = Error message none
|
|
|
|
Payload Length:
|
|
The length of the following payload. Maximum length is 65535 bytes.
|
|
|
|
The Initialized command will be sent from the GUI to the extcap utility when all
|
|
user changed control values are sent after starting a capture. This is an indication
|
|
that the GUI is ready to receive control values.
|
|
|
|
The GUI will only send Initialized and Set commands. The extcap utility shall not
|
|
send the Initialized command.
|
|
|
|
Messages with unknown control number or command will be silently ignored.
|
|
|
|
|
|
DEVELOPMENT
|
|
===========
|
|
To have extcap support, the specific extcap must be compiled. Examples for autotools and
|
|
cmake compiling the extcap plugin androiddump are provided within wireshark.
|
|
The extcap subsystem and the bundled extcaps are compiled by default.
|
|
|
|
Additionally there is an example python script available in doc/extcap_example.py.
|
|
|
|
When developing a new extcap, it must be created under extcap/ directory and
|
|
added to the makefiles. Once compiled it will be under the extcap/ directory
|
|
in the build dir.
|
|
|
|
If the current extcaps configuration is copied, the new extcap will need specific
|
|
configuration flags like --enable-<newextcap> or -DBUILD_<newextcap>
|
|
|
|
Since this is a plugin, the developer must ensure that the extcap dir will be
|
|
loaded. To see which dir is loaded, they must open HELP->ABOUT->FOLDER and look
|
|
for "Extcap Path". If there is a system path (like /usr/local/lib/wireshark/extcap/)
|
|
the extcaps in the build dir are not loaded. To load them, wireshark must be
|
|
loaded with WIRESHARK_RUN_FROM_BUILD_DIRECTORY=1. Now the "Extcap path" should
|
|
point to the extcap dir under your build environment.
|