From 34628974f459b8abd15a17054eb174176653cf06 Mon Sep 17 00:00:00 2001 From: Graham Clark Date: Thu, 25 Feb 2021 23:08:38 -0500 Subject: [PATCH] Document the new column configuration --- CHANGELOG.md | 16 ++++++++++++++++ docs/FAQ.md | 10 +++++++++- docs/UserGuide.md | 27 ++++++++++++++++++++++++++- 3 files changed, 51 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cd5a5024..8acc1274 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## [Unreleased] + +### Added + + Termshark's columns can now be changed. Use the minibuffer `columns` command to show the current column + set. Columns can be added, removed or hidden from view. If your Wireshark config is available, termshark can + import your Wireshark column configuration. Custom columns can be chosen via a display filter expression. +- The packet structure view now provides a contextual menu with options to + - apply the filter representing the current level of structure as a custom column + - prepare or directly apply the same filter as a display filter + +### Changed + + Fixed a bug that caused "And" and "Or" conversation filters to be incorrect if the current display filter is + empty. + ## [2.2.0] - 2021-01-03 ### Added diff --git a/docs/FAQ.md b/docs/FAQ.md index 116fdaf0..53c435f6 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -288,7 +288,7 @@ The information is displayed in a table by conversation type. If the user has a tshark -r my.pcap -q -z conv,eth,http -z conv,ip,http -z conv,tcp,http ``` -Finally, termshark uses tshark in one more way - to generate the possible completions for prefixes of display filter terms. If you type `tcp.` in the filter widget, termshark will show a drop-down menu of possible completions. This is generated once at startup by running +Termshark also uses tshark to generate the possible completions for prefixes of display filter terms. If you type `tcp.` in the filter widget, termshark will show a drop-down menu of possible completions. This is generated once at startup by running ```bash tshark -G fields @@ -296,6 +296,14 @@ tshark -G fields then parsing the output into a nested collection of Go maps, and serializing it to `$XDG_CACHE_HOME/termshark/tsharkfieldsv2.gob.gz`. +Finally, termshark runs tshark to generate the list of all valid columns and their names. These are used to populate a dropdown menu showing valid column choices when the user configures their column set. Termshark runs + +```bash +tshark -G column-formats +``` + +and serializes this list to `$XDG_CACHE_HOME/termshark/tsharkcolumnsv2.gob.gz`. + Termshark also uses the `capinfos` binary to compute the information displayed via the menu "Analysis -> Capture file properties". `capinfos` is typically distributed with tshark. ## How can I make termshark run without root? diff --git a/docs/UserGuide.md b/docs/UserGuide.md index fce21ad0..bde3be52 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -22,6 +22,7 @@ Termshark provides a terminal-based user interface for analyzing packet captures - [Packet Capture Information](#packet-capture-information) - [Stream Reassembly](#stream-reassembly) - [Conversations](#conversations) + - [Columns](#columns) - [Command-Line](#command-line) - [Macros](#macros) - [Configuration](#configuration) @@ -225,7 +226,9 @@ Termshark's middle view shows the structure of the packet selected in the list v ![structure](/../gh-pages/images/structure.png?raw=true) -As you navigate the packet structure, different sections of the bottom view - a hex representation of the packet - will be highlighted. +As you navigate the packet structure, different sections of the bottom view - a hex representation of the packet - will be highlighted. The currently selected line in this view will display a small button at the right hand-side. This button opens a contextual menu from which you can add a custom column or apply a filter based on the current level of the packet structure. + +![pdmlmenu](/../gh-pages/images/termshark-pdml-menu.png?raw=true) ### Packet Hex View @@ -317,6 +320,25 @@ In the first pop-up menu, you can choose how to extend the current display filte ![convs3](/../gh-pages/images/convs3.png?raw=true) +### Columns + +Like Wireshark, you can configure the columns that termshark displays. To do this, choose "Edit Columns" from the main menu, or type `columns` from the command-line. + +![configcolumns](/../gh-pages/images/custom-columns.png?raw=true) + +From this dialog, you can: + +- Rearrange your current column set +- Hide columns or make them visible +- Delete and add columns +- Give each of your columns a custom name + +If termshark can find your Wireshark config, it also offers the option of importing your Wireshark column set. + +Use the drop-down menus to choose the column type. If you select a custom column, termshark will require you to provide a valid display filter +expression. Like Wireshark, the syntax of valid column expressions is a subset of those for display filters - essentially the disjunction (or) of +filter fields. Note that termshark follows Wireshark and currently allows you to enter *any* valid display filter expression. + ### Command-Line For fast navigation around the UI, termshark offers a vim-style command-line. To activate the command-line, hit the ':' key: @@ -327,6 +349,7 @@ Many of termshark's operations can be initiated from the command-line. After ope - **capinfo** - Show the current capture file properties (using the `capinfos` command) - **clear** - Clear the current pcap +- **columns** - Configure termshark's columns - **convs** - Open the conversations view - **filter** - Choose a display filter from those recently-used - **help** - Show one of several help dialogs @@ -534,6 +557,8 @@ Termshark reads options from a TOML configuration file saved in `$XDG_CONFIG_HOM - `capture-command` (string) - use this binary to capture packets, passing `-i`, `-w` and `-f` flags. - `color-tsharks` (string list) - a list of the paths of tshark binaries that termshark has confirmed support the `--color` flag. If you run termshark and the selected tshark binary is not in this list, termshark will check to see if it supports the `--color` flag. - `colors` (bool) - if true, and tshark supports the feature, termshark will colorize packets in its list view. +- `column-format` (string list) - a list of columns, each a group of three strings: field name, display name, and visibility. +- `column-format-bak` (string list) - the value of `column-format` prior to its last change; for restoring previous settings. - `conv-absolute-time` (bool) - if true, have tshark provide conversation data with a relative start time field. - `conv-resolve-names` (bool) - if true, have tshark provide conversation data with ethernet names resolved. - `conv-use-filter` (bool) - if true, have tshark provide conversation data limited to match the active display filter.