SYNOPSIS

sharkd [ -a|--api <socket> ] [ --foreground ] [ -C|--config-profile <configuration profile> ]

sharkd -

sharkd -h|--help

sharkd -v|--version

DESCRIPTION

Sharkd is a daemon variant of Wireshark that provides a JSON-based API for performing network protocol analysis. It uses the same dissection engine as Wireshark and TShark, enabling programmatic access to packet dissection, filtering, and analysis capabilities.

Sharkd can operate in two modes: console mode and daemon mode.

In console mode, sharkd reads reads JSON-RPC requests from standard input and writes responses to standard output. This mode is activated by passing - as the argument or by running sharkd without the -a option.

In daemon mode, sharkd listens on a Unix domain socket or TCP socket for incoming connections, forking a new session process for each client. This mode is activated by passing the -a option with a socket specification.

Requests and responses are encoded as JSON objects, one per line. See JSON-RPC METHODS below for a complete list of method calls.

For full details on the JSON-RPC API, see https://wiki.wireshark.org/Development/sharkd.

Warning
 Sharkd should not be exposed to untrusted users. Unfiltered access to sharkd could potentially result in information disclosure or arbitrary command execution.

OPTIONS

-a <socket>, --api <socket>

Listen on the specified socket for incoming client connections instead of reading from the console. When this option is used, sharkd runs as a daemon, forking a new session process for each client connection.

Supported socket types:

unix:path

Listen on a Unix domain socket at path. For example, unix:/tmp/sharkd.sock. On Linux, abstract sockets are supported by prefixing the name with @, for example unix:@sharkd. Unix domain sockets are not available on Windows.

tcp:address:port

Listen on a TCP socket bound to address on port. For example, tcp:127.0.0.1:4446. TCP sockets are only available on Windows builds by default for security reasons.

If no -a option is provided, or if sharkd - is used, sharkd will accept commands via the console (standard input).

--foreground

When running in daemon mode, do not detach from the controlling terminal. By default, sharkd forks into the background when a socket is specified with the -a option.

-C <configuration profile>, --config-profile <configuration profile>

Start with the specified configuration profile.

-h, --help

Print the version number and options and exit.

-v, --version

Print the full version information and exit.

DIAGNOSTIC OPTIONS

--log-level <level>

Set the active log level. Supported levels in lowest to highest order are "noisy", "debug", "info", "message", "warning", "critical", and "error". Messages at each level and higher will be printed, for example "warning" prints "warning", "critical", and "error" messages and "noisy" prints all messages. Levels are case insensitive.

--log-fatal <level>

Abort the program if any messages are logged at the specified level or higher. For example, "warning" aborts on any "warning", "critical", or "error" messages.

--log-domains <list>

Only print messages for the specified log domains, e.g. "GUI,Epan,sshdump". List of domains must be comma-separated. Can be negated with "!" as the first character (inverts the match).

--log-debug <list>

Force the specified domains to log at the "debug" level. List of domains must be comma-separated. Can be negated with "!" as the first character (inverts the match).

--log-noisy <list>

Force the specified domains to log at the "noisy" level. List of domains must be comma-separated. Can be negated with "!" as the first character (inverts the match).

--log-fatal-domains <list>

Abort the program if any messages are logged for the specified log domains. List of domains must be comma-separated.

--log-file <path>

Write log messages and stderr output to the specified file.

JSON-RPC METHODS

Sharkd accepts newline-delimited JSON-RPC requests. Each request must include a jsonrpc field set to "2.0", a method field, and an id field. The following methods are supported:

analyse

Analyse the loaded capture file and return summary information.

bye

Terminate the session.

check

Check or compile a display filter.

complete

Provide field name completion suggestions.

download

Download captured data or reassembled objects.

dumpconf

Dump current preference values.

field

Get information about a specific display filter field.

fields

List all available display filter fields.

follow

Follow a stream (TCP, UDP, HTTP, etc.).

frame

Get detailed information about a specific frame.

frames

Get a list of frames (packets) from the loaded capture file.

info

Get information about available dissectors, taps, and statistics.

intervals

Get frame interval data for the loaded capture file.

iograph

Get I/O graph data for the loaded capture file.

load

Load a capture file for analysis.

setcomment

Set a comment on a specific frame.

setconf

Set a Wireshark preference value.

status

Get the status of the currently loaded capture file.

tap

Run a tap on the loaded capture file.

EXAMPLES

To run sharkd in console mode:

sharkd -

To run sharkd as a daemon listening on a Unix domain socket:

sharkd -a unix:/tmp/sharkd.sock

To run sharkd as a daemon with a specific configuration profile:

sharkd -a unix:/tmp/sharkd.sock -C myprofile

To keep the daemon in the foreground for debugging:

sharkd -a unix:/tmp/sharkd.sock --foreground

An example console session, loading a file and getting its status:

$ echo '{"jsonrpc":"2.0","id":1,"method":"load","params":{"file":"/path/to/capture.pcapng"}}' | sharkd -
$ echo '{"jsonrpc":"2.0","id":2,"method":"status"}' | sharkd -

ENVIRONMENT VARIABLES

WIRESHARK_CONFIG_DIR

This environment variable overrides the location of personal configuration files. On UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX, it defaults to $XDG_CONFIG_HOME/wireshark (or, if that directory doesn’t exist but $HOME/.wireshark does exist, $HOME/.wireshark); this is typically $HOME/.config/wireshark. On Windows, it defaults to %APPDATA%\Wireshark (or, if %APPDATA% isn’t defined, %USERPROFILE%\Application Data\Wireshark). Available since Wireshark 3.0.

WIRESHARK_DEBUG_WMEM_OVERRIDE

Setting this environment variable forces the wmem framework to use the specified allocator backend for all allocations, regardless of which backend is normally specified by the code. This is mainly useful to developers when testing or debugging. See README.wmem in the source distribution for details.

WIRESHARK_RUN_FROM_BUILD_DIRECTORY

This environment variable causes the plugins and other data files to be loaded from the build directory (where the program was compiled) rather than from the standard locations. It has no effect when the program in question is running with root (or setuid) permissions on UNIX-compatible systems, such as Linux, macOS, \*BSD, Solaris, and AIX.

WIRESHARK_DATA_DIR

This environment variable causes the various data files to be loaded from a directory other than the standard locations. It has no effect when the program in question is running with root (or setuid) permissions on UNIX-compatible systems.

WIRESHARK_EXTCAP_DIR

This environment variable causes the various extcap programs and scripts to be run from a directory other than the standard locations. It has no effect when the program in question is running with root (or setuid) permissions on UNIX-compatible systems.

WIRESHARK_PLUGIN_DIR

This environment variable causes the various plugins to be loaded from a directory other than the standard locations. It has no effect when the program in question is running with root (or setuid) permissions on UNIX-compatible systems.

ERF_RECORDS_TO_CHECK

This environment variable controls the number of ERF records checked when deciding if a file really is in the ERF format. Setting this environment variable a number higher than the default (20) would make false positives less likely.

IPFIX_RECORDS_TO_CHECK

This environment variable controls the number of IPFIX records checked when deciding if a file really is in the IPFIX format. Setting this environment variable a number higher than the default (20) would make false positives less likely.

WIRESHARK_ABORT_ON_DISSECTOR_BUG

If this environment variable is set, TShark will call abort(3) when a dissector bug is encountered. abort(3) will cause the program to exit abnormally; if you are running TShark in a debugger, it should halt in the debugger and allow inspection of the process, and, if you are not running it in a debugger, it will, on some OSes, assuming your environment is configured correctly, generate a core dump file. This can be useful to developers attempting to troubleshoot a problem with a protocol dissector.

WIRESHARK_ABORT_ON_TOO_MANY_ITEMS

If this environment variable is set, TShark will call abort(3) if a dissector tries to add too many items to a tree (generally this is an indication of the dissector not breaking out of a loop soon enough). abort(3) will cause the program to exit abnormally; if you are running TShark in a debugger, it should halt in the debugger and allow inspection of the process, and, if you are not running it in a debugger, it will, on some OSes, assuming your environment is configured correctly, generate a core dump file. This can be useful to developers attempting to troubleshoot a problem with a protocol dissector.

WIRESHARK_LOG_LEVEL

This environment variable controls the verbosity of diagnostic messages to the console. From less verbose to most verbose levels can be critical, warning, message, info, debug or noisy. Levels above the current level are also active. Levels critical and error are always active.

WIRESHARK_LOG_FATAL

Sets the fatal log level. Fatal log levels cause the program to abort. This level can be set to Error, critical or warning. Error is always fatal and is the default.

WIRESHARK_LOG_DOMAINS

This environment variable selects which log domains are active. The filter is given as a case-insensitive comma separated list. If set only the included domains will be enabled. The default domain is always considered to be enabled. Domain filter lists can be preceded by '!' to invert the sense of the match.

WIRESHARK_LOG_DEBUG

List of domains with debug log level. This sets the level of the provided log domains and takes precedence over the active domains filter. If preceded by '!' this disables the debug level instead.

WIRESHARK_LOG_NOISY

Same as above but for noisy log level instead.

SEE ALSO

wireshark-filter(4), wireshark(1), editcap(1), pcap(3), dumpcap(1), text2pcap(1), mergecap(1), pcap-filter(7) or tcpdump(8)

NOTES

This is the manual page for Sharkd 4.6.6. Sharkd is part of the Wireshark distribution. The latest version of Wireshark can be found at https://www.wireshark.org.

HTML versions of the Wireshark project man pages are available at https://www.wireshark.org/docs/man-pages.

AUTHORS

Sharkd was written by Jakub Zawadzki. Sharkd uses the same packet dissection code that Wireshark does, as well as using many other modules from Wireshark; see the list of authors in the Wireshark man page for a list of authors of that code.