Struct RTSharkBuilderReady

pub struct RTSharkBuilderReady<'a> { /* private fields */ }

RTSharkBuilderReady is an object used to run to create a RTShark instance. It is possible to use it to add more optional parameters before starting a TShark application.

Implementations

impl<'a> RTSharkBuilderReady<'a>

pub fn input_path(&self, path: &'a str) -> Self

Adds another input for tshark. It works only with live capture to read packets from multiple interfaces. Adding multiple pcap files will fail, since tshark will only read the last instance of “-r” option.

Example: Prepare an instance of TShark to read from multiple network interfaces

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("eth0")
    .input_path("eth1")
    .live_capture();

pub fn live_capture(&self) -> Self

Enables -i option of TShark.

This option must be set to use network interface or pipe for live packet capture. See input_path() option of RTSharkBuilder for more details.

pub fn capture_filter(&self, filter: &'a str) -> Self

Filter expression to be passed to libpcap to filter captured packets.

Warning: these capture filters cannot be specified when reading a capture file. There are enabled only when using live_capture(). This filter will be ignored if live_capture() is not set.

Packet capturing filter is performed with the pcap library. That library supports specifying a filter expression; packets that don’t match that filter are discarded. The syntax of a capture filter is defined by the pcap library. This syntax is different from the TShark filter syntax.

More information about libpcap filters here : https://www.tcpdump.org/manpages/pcap-filter.7.html

Example: Prepare an instance of TShark with packet capture filter.

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("eth0")
    .live_capture()
    .capture_filter("port 53");

pub fn display_filter(&self, filter: &'a str) -> Self

Expression applied on analyzed packet metadata to print and write only matching packets.

Cause the specified filter (which uses the syntax of read/display filters, rather than that of capture filters) to be applied before printing a decoded form of packets or writing packets to a file. Packets matching the filter are printed or written to file; packets that the matching packets depend upon (e.g., fragments), are not printed but are written to file; packets not matching the filter nor depended upon are discarded rather than being printed or written.

Example: Prepare an instance of TShark with display filter.

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap")
    .display_filter("udp.port == 53");

pub fn metadata_blacklist(&self, blacklist: &'a str) -> Self

Filter out (blacklist) a list of useless metadata names extracted by TShark, to prevent storing them in Packet structure and consume extra memory. Filtered Metadata will not be available in Packet’s Layer.

This method can be called multiple times to add more metadata in the blacklist.

Example: Prepare an instance of TShark with IP source and destination metadata filtered.

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap")
    .metadata_blacklist("ip.src")
    .metadata_blacklist("ip.dst");

pub fn metadata_whitelist(&self, whitelist: &'a str) -> Self

Filter out (whitelist) a list of needed metadata names to be extracted by TShark, to prevent it to extract and put everything in the PDML report. There is a huge performance gain for TShark if the whitelist is small. Filtered Metadata will not be available in Packet’s Layer.

This method can be called multiple times to add more metadata in the whitelist.

In whitelist mode, TShark PDML does not encapsulate fields in a ‘proto’ tag anymore so it is not possible to build all packet’s layers.

Example: Prepare an instance of TShark to print only IP source and destination metadata.

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap")
    .metadata_whitelist("ip.src")
    .metadata_whitelist("ip.dst");

pub fn env_path(&self, path: &'a str) -> Self

Replace the PATH environment variable. This is used to specify where to look for tshark executable.

Note that environment variable names are case-insensitive (but case-preserving) on Windows, and case-sensitive on all other platforms.

Example: Prepare an instance of TShark when binary is installed in a custom path

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap")
    .env_path("/opt/local/tshark/");

pub fn keylog_file(&self, path: &'a str) -> Self

Specify the key log file that enables decryption of TLS traffic.

The key log file is generated by the browser when SSLKEYLOGFILE environment variable is set. See https://wiki.wireshark.org/TLS#using-the-pre-master-secret for more details.

Note that you can embed the TLS key log file in a capture file:

editcap --inject-secrets tls,keys.txt in.pcap out-dsb.pcapng

pub fn option(&self, option: &'a str) -> Self

Set custom protocol’s option to tune the tshark decoding. This adds -o parameter to tshark command line.

This method can be called multiple times to add more options.

Example: Prepare an instance of TShark without ip defragmenting and custom inap args:

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap")
    .option("ip.defragment:false")
    .option("inap.ssn:146");

pub fn disable_protocol(&self, protocol: &'a str) -> Self

Provide protocol names that should be disabled in tshark decoding.

This method can be called multiple times to add more protocols.

Example: Prepare an instance of TShark where t30 and t38 protocols are not decoded:

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap")
    .disable_protocol("t30")
    .disable_protocol("t38");

pub fn enable_protocol(&self, protocol: &'a str) -> Self

Provide protocol names that should be enabled in tshark decoding.

This method can be called multiple times to add more protocols.

Example: Prepare an instance of TShark where only ethernet and ip are decoded:

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap")
    .disable_protocol("ALL")
    .enable_protocol("eth")
    .enable_protocol("ip");

pub fn output_path(&self, path: &'a str) -> Self

Write raw packet data to outfile or to the standard output if outfile is ‘-’. Note : this option provides raw packet data, not text.

Example: Prepare an instance of TShark to store raw packet data

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/in.pcap")
    .output_path("/tmp/out.pcap");

pub fn decode_as(&self, expr: &'a str) -> Self

Let TShark to decode as the protocol which specified in the expression.

This method can be called multiple times to add more expression in the decode_as list.

Example: The packet which has TCP port 8080 or 8081 is decoded as HTTP/2.

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap")
    .decode_as("tcp.port==8080,http2")
    .decode_as("tcp.port==8081,http2");

pub fn spawn(&self) -> Result<RTShark>

Starts a new TShark process given the provided parameters, mapped to a new RTShark instance. This function may fail if tshark binary is not in PATH or if there are some issues with input_path parameter : not found or no read permission… In other cases (output_path not writable, invalid syntax for pcap_filter or display_filter), TShark process will start but will stop a few moments later, leading to a EOF on rtshark.read function.

Example

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap");
let tshark: std::io::Result<rtshark::RTShark> = builder.spawn();

pub fn batch(&self) -> Result<()>

Starts a new TShark process given the provided parameters and runs it to completion. In contrast to RTSharkBuilderReady::spawn no programmatic access to individual packets is provided. This function may fail if tshark binary is not in PATH or if there are some issues with input_path parameter : not found or no read permission… In other cases (output_path not writable, invalid syntax for pcap_filter or display_filter), TShark process will fail and the stderr will be reported.

Example

let builder = rtshark::RTSharkBuilder::builder()
    .input_path("/tmp/my.pcap");
let _: Result<(), std::io::Error> = builder.batch();

Trait Implementations

impl<'a> Clone for RTSharkBuilderReady<'a>

fn clone(&self) -> RTSharkBuilderReady<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.