1 files changed, 157 insertions, 0 deletions
diff --git a/doc/extcap.adoc b/doc/extcap.adoc
new file mode 100644
index 0000000000..a0564a886e
--- /dev/null
+++ b/doc/extcap.adoc
@@ -0,0 +1,157 @@
+=begin man
+
+=encoding utf8
+
+=end man
+
+=head1 NAME
+
+extcap - The extcap interface
+
+=head1 DESCRIPTION
+
+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 application.
+
+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.
+
+When Wireshark launches an extcap, it automatically adds its installation path
+(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 (executable, python scripts, ...) in the extcap folder to reduce the startup
+time and not have Wireshark trying to execute other file types.
+
+
+=head1 GRAMMAR ELEMENTS
+
+Grammar elements:
+
+=over 4
+
+=item arg (options)
+
+argument for CLI calling
+
+=item number
+
+Reference # of argument for other values, display order
+
+=item call
+
+Literal argument to call (--call=...)
+
+=item display
+
+Displayed name
+
+=item default
+
+Default value, in proper form for type
+
+=item range
+
+Range of valid values for UI checking (min,max) in proper form
+
+=item type
+
+Argument type for UI filtering for raw, or UI type for selector:
+
+    integer
+    unsigned
+    long (may include scientific / special notation)
+    float
+    selector (display selector table, all values as strings)
+    boolean (display checkbox)
+    radio (display group of radio buttons with provided values, all values as strings)
+    fileselect (display a dialog to select a file from the filesystem, value as string)
+    multicheck (display a textbox for selecting multiple options, values as strings)
+    password (display a textbox with masked text)
+    timestamp (display a calendar)
+
+=item value (options)
+
+    Values for argument selection
+    arg     Argument # this value applies to
+
+=back
+
+=head1 EXAMPLES
+
+Example 1:
+
+    arg {number=0}{call=--channel}{display=Wi-Fi Channel}{type=integer}{required=true}
+    arg {number=1}{call=--chanflags}{display=Channel Flags}{type=radio}
+    arg {number=2}{call=--interface}{display=Interface}{type=selector}
+    value {arg=0}{range=1,11}
+    value {arg=1}{value=ht40p}{display=HT40+}
+    value {arg=1}{value=ht40m}{display=HT40-}
+    value {arg=1}{value=ht20}{display=HT20}
+    value {arg=2}{value=wlan0}{display=wlan0}
+
+Example 2:
+
+    arg {number=0}{call=--usbdevice}{USB Device}{type=selector}
+    value {arg=0}{call=/dev/sysfs/usb/foo/123}{display=Ubertooth One sn 1234}
+    value {arg=0}{call=/dev/sysfs/usb/foo/456}{display=Ubertooth One sn 8901}
+
+Example 3:
+
+    arg {number=0}{call=--usbdevice}{USB Device}{type=selector}
+    arg {number=1}{call=--server}{display=IP address for log server}{type=string}{validation=(?:\d{1,3}\.){3}\d{1,3}}
+    flag {failure=Permission denied opening Ubertooth device}
+
+Example 4:
+    arg {number=0}{call=--username}{display=Username}{type=string}
+    arg {number=1}{call=--password}{display=Password}{type=password}
+
+Example 5:
+    arg {number=0}{call=--start}{display=Start Time}{type=timestamp}
+    arg {number=1}{call=--end}{display=End Time}{type=timestamp}
+
+=head1 Security awareness
+
+=over 4
+
+=item - Users running wireshark as root, we can't save you
+
+=item - Dumpcap retains suid/setgid and group+x permissions to allow users in wireshark group only
+
+=item - Third-party capture programs run w/ whatever privs they're installed with
+
+=item - If an attacker can write to a system binary directory, we're game over anyhow
+
+=item - Reference the folders tab in the wireshark->about information, to see from which directory extcap is being run
+
+=back
+
+=head1 SEE ALSO
+
+wireshark(1), tshark(1), dumpcap(1), androiddump(1), sshdump(1), randpktdump(1)
+
+=head1 NOTES
+
+B<Extcap> is feature of B<Wireshark>.  The latest version
+of B<Wireshark> can be found at L<https://www.wireshark.org>.
+
+HTML versions of the Wireshark project man pages are available at:
+L<https://www.wireshark.org/docs/man-pages>.