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:
Bash example for traditional capture with 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, so long as it
will execute directly. On UN*X systems, please note that this means the scripts
need to be executable (chmod +x some.py) and start with an appropriate "shebang"
line (for example, #!/usr/bin/env python3).
On Windows systems, the file extension must be present in the PATHEXT environment
variable, and the default file association must be set properly so that the
executable or script will be run or interpreted, rather than being opened in an editor.
You may also create a batch file that is executable by default and which in turn
executes a script via its interpreter.
Please refer to Section 8.2.1.4.1, “Execute A Script-based Extcap On Windows” for more information.
When Wireshark launches an extcap, it automatically adds its installation path (normally C:\Program Files\Wireshark\) to the DLL search path so that the extcap library dependencies can be found (it is not designed to be launched by hand). This is done on purpose. There should only be extcap programs (executables, Python scripts, etc.) in the extcap folder to reduce the startup time and not have Wireshark trying to execute other file types.
The actual capture is run after a setup process that can be done manually by the user or automatically by the GUI. All the steps performed are done for every extcap.
Let’s go through those steps.
In the first step 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).
Wireshark 2.9 and later also pass --extcap-version=x.x, which provides the calling Wireshark’s major and minor version.
This can be used to change behavior depending on the Wireshark version in question.
Example call for interface query.
$ extcap_example.py --extcap-interfaces --extcap-version=5.0
extcap {version=1.0}{help=Some help url}
interface {value=example1}{display=Example interface 1 for extcap}
interface {value=example2}{control=3}{display=Example interface 2 for extcap}
The version for the extcap sentence (which may exist as many times as is needed, 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.
Using the help argument, an interface may provide a generic help URL for the extcap utility.
The value for each interface will be used in subsequent calls as the interface name <iface>.
The control argument is used to indicate support for the control pipes.
The value is an integer treated as a bitfield where 1 indicates support for
toolbar control messages, 2 indicates support
for quit messages, and 3 indicates support for both. The control argument can
appear in the line for an individual interface, or it can appear in the extcap
sentence; in the latter case it is used as the default value for all interfaces.
The display argument is displayed to the user as an interface description in places such as the interface list in Wireshark.
Next, the extcap binary is queried for all valid DLTs for all the interfaces returned by step 1.
$ extcap_example.py --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 for the DLT query.
$ extcap_example.py --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.
The extcap binary is next asked for the configuration of each specific interface
$ extcap_example.py --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, which shows all the available options (aka additional command line options).
Those options are used to build a configuration dialog for the interface.
Example for interface options.
$ extcap_example.py --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 several kind of options available:
|
File |
A path to a file displayed as a text entry and file selector. |
|
Flag |
A boolean value displayed as a checkbox. boolflag for instance expects the option to be present resulting in the corresponding entry set to true or false. |
|
Selection |
A set of fixed values displayed as a combobox, radio group, or selection list. Selections can be presented multiple times in the command line. Subsequent value items must be provided in the config list. |
|
Timestamp |
A time value displayed as a date/time editor. |
|
Value |
A text or numeric value displayed as an entry box. Values are passed as a single value via the command-line call. |
Once the interfaces are listed and configuration is customized by the user the capture can be started.
$ extcap_example.py --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 options.
They are automatically added by Wireshark, which 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).
Windows will run batch scripts directly, but other scripting languages require extra effort. Even PowerShell scripts (".ps1") There are two options: allowing Windows to run files with that script’s extension directly, or creating a wrapper script in a supported language which calls the script via its appropriate interpreter.
Running a script directly has the advantage of faster startup and only having
to distribute one script file cross-plaform.
It requires that the script extension both be associated with the interpreter and
be in the PATHEXT environment variable. These Windows settings must be set for
any host machine running the extcap, which may make it more difficult to distribute
the script in a multiuser environment. Even PowerShell scripts (.ps1), while in
PATHEXT by default, are by default associated with Notepad by Windows as a defense
against accidentally double-clicking on malicious scripts.
Taking Python as an another example, the official Python Windows installer
by default
associates the .py and .pyw extensions with the Python interpreter (though other
programs, like IDEs or other code editors, may associate themselves and replace the
interpreter), but does not add the extensions to PATHEXT.
These can be changed via the normal Windows settings mechanisms.
A Batch wrapper script has the advance of working out of the box on Windows installs, but has the disadvantage of slower startup and requiring distributing an extra file for Windows users. For example, in order to run a Python-based extcap, you can create scriptname.bat inside your extcap folder with the following content:
@echo off C:\Windows\py.exe %~dpn0.py %*
%~dpn0 expands to the concatenation of the drive letter, the path, and the
file name (without extension) of the invoked batch file.
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. All options must present the elements call and display, with call specifying the argument’s name on the command line and display specifying the name in the GUI.
Additionally tooltip and placeholder may be provided, which will give the user information 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 |
This provides a field for entering a text value. 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}
|
|
password |
Lets the user provide a masked string to the capture. Password strings are not saved with other capture settings. 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 |
Lets the user provide a file path. If mustexist=true is provided, the GUI shows the user a dialog for selecting a file. When mustexist=false is used, the GUI shows the user a file dialog for saving a file. arg {number=3}{call=--logfile}{display=Logfile}{tooltip=A file for log messages}{type=fileselect}{mustexist=false}
|
|
selector, editselector, radio, multicheck |
Option fields where the user may choose from one or more options. If parent is provided for the value items, the option fields for multicheck and selector are 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. editselector option fields let the user select from a list of items or enter a custom value. 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}
|
A selector may be reloaded from the configuration dialog of the extcap application within Wireshark. With the reload argument (defaults to false), the entry can be marked as reloadable.
arg {number=3}{call=--remote}{display=Remote Channel}{tooltip=Remote Channel Selector}{type=selector}{reload=true}{placeholder=Load interfaces...}
After this has been defined, the user will get a button displayed in the configuration dialog for this extcap application, with the text "Load interfaces…" in this case, and a generic "Reload" text if no text has been provided.
The extcap utility is then called again with all filled out arguments and the additional parameter --extcap-reload-option <option_name>. It is expected to return a value section for this option, as it would during normal configuration. The provided option list is then presented as the selection, a previous selected option will be reselected if applicable.
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.
An extcap utility can provide configuration for controls to use in an interface toolbar. These 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 of interface definition with toolbar controls.
$ extcap_example.py --extcap-interfaces
extcap {version=1.0}{display=Example extcap interface}
interface {value=example1}{display=Example interface 1 for extcap}
interface {value=example2}{control=3}{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 a GUI (e.g. tshark, tfshark).
An interface that supports controls should include a {control=1} or {control=3}
entry in the interface line, but for backwards compatibility, support for the control
pipe and "T" messages is assumed if controls are listed.
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. All options must present the elements type and display, where type provides the type of control to add to the toolbar and display providing the name in the GUI.
Additionally tooltip and placeholder may be provided, which will give the user information about what to enter into this field.
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.
These types are defined as controls:
|
boolean |
This provides a checkbox which lets the user 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:
|
|
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 for control: 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). |
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.
If support for control pipes is provided in the --extcap-interfaces output, then
the main application will create the control pipes (FIFOs or named pipes, depending
upon the OS) and pass the names as part of the capture start command via the
options --extcap-control-in <in-fifo> and --extcap-control-out <out-fifo>.
These are from the perspective of the extcap binary; --extcap-control-in is where
the extcap binary will receive QUIT or TOOLBAR_CONTROL messages, and --extcap-control-out
is where it is expected to send TOOLBAR_CONTROL messages.
The QUIT messages only require unidirectional information, so if the extcap
indicates support for QUIT messages only ({control=2}), then only the
control in pipe argument will be included in the command line.
The protocol used to communicate over the control pipes is the same as that used for communicating between the main application and dumpcap, with only two message types used. It has a fixed size header of 4 bytes, and an optional payload which is limited to 65537 bytes when communicating with the extcaps.
Table 8.1. Control packet:
|
|
|
Sync Pipe Indication. The common sync pipe indication. For communicating with the extcaps, the values "T" for toolbar control messages and "Q" for quit messages are supported.
Message Length. Message Payload length
Message Payload. The payload. Note that while there are 3 bytes reserved for the Message Length field, 512000 is the largest value supported by the main application, and messages used to communicate with the extcaps specifically are limited to 65537 bytes (two bytes for fixed toolbar control header plus up to 65535 bytes of payload).
QUIT messages ("Q" indicator) have an optional payload that may be ignored; if received, the extcap should gracefully shutdown.
TOOLBAR_CONTROL messages ("T" indicator) have a fixed size header of 2 bytes and a payload with 0 - 65535 bytes. Note that the message length in the common header will include the 2 bytes for the toolbar control header and thus be 2 - 65537.
Table 8.2. Toolbar Control message payload:
|
|
|
Control Number. Unique number to identify the control. This number also gives the order of the controls in the interface toolbar. For commands that do not address a specific control and apply to the entire application (0 and 6-9 below) this is ignored.
Table 8.3. Commands and application for controls
| Command Byte | Command Name | 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 |
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 an unknown command or with commands that require a control number but an unknown control number will be silently ignored.