1# Termshark User Guide 2 3Termshark provides a terminal-based user interface for analyzing packet captures. 4 5## Table of Contents 6 7- [Table of Contents](#table-of-contents) 8- [Basic Usage](#basic-usage) 9- [Choose a Source](#choose-a-source) 10 - [Reading from an Interface](#reading-from-an-interface) 11 - [Read a pcap file](#read-a-pcap-file) 12 - [Changing Files](#changing-files) 13 - [Reading from a fifo or stdin](#reading-from-a-fifo-or-stdin) 14- [Using the TUI](#using-the-tui) 15 - [Filtering](#filtering) 16 - [Changing Views](#changing-views) 17 - [Packet List View](#packet-list-view) 18 - [Packet Structure View](#packet-structure-view) 19 - [Packet Hex View](#packet-hex-view) 20 - [Copy Mode](#copy-mode) 21 - [Packet Capture Information](#packet-capture-information) 22 - [Stream Reassembly](#stream-reassembly) 23 - [Conversations](#conversations) 24- [Configuration](#configuration) 25 - [Dark Mode](#dark-mode) 26 - [Packet Colors](#packet-colors) 27 - [Config File](#config-file) 28- [Troubleshooting](#troubleshooting) 29 30## Basic Usage 31 32Termshark is inspired by Wireshark, and depends on tshark for all its intelligence. Termshark is run from the command-line. You can see its options with 33 34```console 35$ termshark -h 36termshark v2.1.0 37 38A wireshark-inspired terminal user interface for tshark. Analyze network traffic interactively from your terminal. 39See https://termshark.io for more information. 40 41Usage: 42 termshark [FilterOrFile] 43 44Application Options: 45 -i=<interfaces> Interface(s) to read. 46 -r=<file> Pcap file to read. 47 -d=<layer type>==<selector>,<decode-as protocol> Specify dissection of layer type. 48 -D Print a list of the interfaces on which termshark can capture. 49 -Y=<displaY filter> Apply display filter. 50 -f=<capture filter> Apply capture filter. 51 -t=<timestamp format>[a|ad|adoy|d|dd|e|r|u|ud|udoy] Set the format of the packet timestamp printed in summary lines. 52 --tty=<tty> Display the UI on this terminal. 53 --pass-thru=[auto|true|false] Run tshark instead (auto => if stdout is not a tty). (default: auto) 54 --log-tty Log to the terminal. 55 -h, --help Show this help message. 56 -v, --version Show version information. 57 58Arguments: 59 FilterOrFile: Filter (capture for iface, display for pcap), or pcap file to read. 60 61If --pass-thru is true (or auto, and stdout is not a tty), tshark will be 62executed with the supplied command-line flags. You can provide 63tshark-specific flags and they will be passed through to tshark (-n, -d, -T, 64etc). For example: 65 66$ termshark -r file.pcap -T psml -n | less 67``` 68 69By default, termshark will launch an ncurses-like application in your terminal window, but if your standard output is not a tty, termshark will simply defer to tshark and pass its options through: 70 71```console 72$ termshark -r test.pcap | cat 73 1 0.000000 192.168.44.123 → 192.168.44.213 TFTP 77 Read Request, File: C:\IBMTCPIP\lccm.1, Transfer type: octet 74 2 0.000000 192.168.44.123 → 192.168.44.213 TFTP 77 Read Request, File: C:\IBMTCPIP\lccm.1, Transfer type: octet 75``` 76 77## Choose a Source 78 79### Reading from an Interface 80 81Launch termshark like this to read from an interface: 82 83```bash 84termshark -i eth0 85``` 86 87You can also apply a capture filter directly from the command-line: 88 89```bash 90termshark -i eth0 tcp 91``` 92 93Termshark will apply the capture filter as it reads, but the UI currently does not provide any indication of the capture filter that is in effect. 94 95Termshark supports reading from more than one interface at a time: 96 97```bash 98termshark -i eth0 -i eth1 99``` 100 101Once packets are detected, termshark's UI will launch and the packet views will update as packets are read: 102 103 104 105You can apply a display filter while the packet capture process is ongoing - termshark will dynamically apply the filter without restarting the capture. Press `ctrl-c` to stop the capture process. 106 107When you exit termshark, it will print a message with the location of the pcap file that was captured: 108 109```console 110$ termshark -i eth0 111Packets read from interface eth0 have been saved in /home/gcla/.cache/termshark/eth0-657695279.pcap 112``` 113 114### Read a pcap file 115 116Launch termshark like this to inspect a file: 117 118```bash 119termshark -r test.pcap 120``` 121 122You can also apply a display filter directly from the command-line: 123 124```bash 125termshark -r test.pcap icmp 126``` 127 128Note that when reading a file, the filter will be interpreted as a [display filter](https://wiki.wireshark.org/DisplayFilters). When reading from an interface, the filter is interpreted as a [capture filter](https://wiki.wireshark.org/CaptureFilters). This follows tshark's behavior. 129 130Termshark will launch in your terminal. From here, you can press `?` for help: 131 132 133 134#### Changing Files 135 136Termshark provides a "Recent" button which will open a menu with your most recently-loaded pcap files. Each invocation of termshark with the `-r` flag will add a pcap to the start of this list: 137 138 139 140### Reading from a fifo or stdin 141 142Termshark supports reading packets from a Unix fifo or from standard input - for example 143 144```bash 145tcpdump -i eth0 -w - icmp | termshark 146``` 147 148On some machines, packet capture commands might require sudo or root access. To facilitate this, termshark's UI will not launch until it detects that it has received some packet data on its input. This makes it easier for the user to type in his or her root password on the tty before termshark takes over: 149 150```console 151$ sudo tcpdump -i eth0 -w - icmp | termshark 152(The termshark UI will start when packets are detected...) 153[sudo] password for gcla: 154``` 155 156If the termshark UI is active in the terminal but you want to see something displayed there before termshark started, you can now issue a SIGTSTP signal (on Unix) and termshark will suspend itself and give up control of the terminal. In bash, this operation is usually bound to ctrl-z. 157 158```console 159$ termshark -r foo.pcap 160 161[1]+ Stopped termshark -r foo.pcap 162$ 163``` 164 165Type `fg` to resume termshark. Another option is to launch termshark in its own tty. You could do this using a split screen in tmux. In one pane, type 166 167```bash 168tty && sleep infinity 169``` 170 171If the output is e.g. `/dev/pts/10`, then you can launch termshark in the other tmux pane like this: 172 173```bash 174termshark -r foo.pcap --tty=/dev/pts/10 175``` 176 177Issue a sleep in the pane for `/dev/pts/10` so that no other process reads from the terminal while it is dedicated to termshark. 178 179## Using the TUI 180 181### Filtering 182 183Press `/` to focus on the display filter. Now you can type in a Wireshark display filter expression. The UI will update in real-time to display the validity of the current expression. If the expression is invalid, the filter widget will change color to red. As you type, termshark presents a drop-down menu with possible completions for the current term: 184 185 186 187When the filter widget is green, you can hit the "Apply" button to make its value take effect. Termshark will then reload the packets with the new display filter applied. 188 189 190 191### Changing Views 192 193Press `tab` to move between the three packet views. You can also use the mouse to move views by clicking with the left mouse button. When focus is in any of these three views, hit the `\` key to maximize that view: 194 195 196 197Press `\` to restore the original layout. Press `|` to move the hex view to the right-hand side: 198 199 200 201You can also press `<`,`>`,`+` and `-` to change the relative size of each view. 202 203### Packet List View 204 205Termshark's top-most view is a list of packets read from the capture (or interface). Termshark generates the data by running `tshark` on the input with the `-T psml` options, and parsing the resulting XML. Currently the columns displayed cannot be configured, and are the same as Wireshark's defaults. When the source is a pcap file, the list can be sorted by column by clicking the button next to each column header: 206 207 208 209You can hit `home` to jump to the top of the list or `end` to jump to the bottom. Sometimes, especially if running on a small terminal, the values in a column will be truncated (e.g. long IPv6 addresses). To see the full value, move the purple cursor over the value: 210 211 212 213### Packet Structure View 214 215Termshark's middle view shows the structure of the packet selected in the list view. You can expand and contract the structure using the `[+]` and `[-]` buttons, the 'enter' key, or the right and left cursor keys: 216 217 218 219As you navigate the packet structure, different sections of the bottom view - a hex representation of the packet - will be highlighted. 220 221### Packet Hex View 222 223Termshark's bottom view shows the bytes that the packet comprises. Like Wireshark, they are displayed in a hexdump-like format. As you move around the bytes, the middle (structure) view will update to show you where you are in the packet's structure. 224 225### Copy Mode 226 227Both the structure and hex view support "copy mode" a feature which lets you copy ranges of data from the currently selected packet. First, move focus to the part of the packet you wish to copy. Now hit the `c` key - a section of the packet will be highlighted in yellow: 228 229 230 231You can hit the `left` and `right` arrow keys to expand or contract the selected region. Now hit `ctrl-c` to copy. Termshark will display a dialog showing you the format in which you can copy the data: 232 233 234 235Select the format you want and hit `enter` (or click). Copy mode is available in the packet structure and packet hex views. 236 237This feature comes with a caveat! If you are connected to a remote machine e.g. via ssh, then you should use the `-X` flag to forward X11. On Linux, the default copy command is `xsel`. If you forward X11 with ssh, then the packet data will be copied to your desktop machine's clipboard. You can customize the copy command using termshark's [config file](UserGuide.md#config-file) e.g. 238 239```toml 240[main] 241 copy-command = ["xsel", "-i", "-p"] 242``` 243 244to instead set the primary selection. If forwarding X11 is not an option, you could instead upload the data (received via stdin) to a service like pastebin, and print the URL on stdout - termshark will display the copy command's output in a dialog when the command completes. See the [FAQ](FAQ.md). 245 246If you are running on OSX, termux (Android) or Windows, termshark assumes you are running locally and uses a platform-specific copy command. 247 248### Packet Capture Information 249 250To show a summary of the information represented in the current pcap file, go to the "Analysis" menu and choose "Capture file properties". Termshark generates this information using the `capinfos` binary which is distributed with `tshark`. 251 252 253 254### Stream Reassembly 255 256Termshark is able to present reassembled TCP and UDP streams in a similar manner to Wireshark. In the packet list view, select a TCP or UDP packet then go to the "Analysis" menu and choose "Reassemble stream": 257 258 259 260Termshark shows you: 261 262- A list of each client and server payload, in order, colored accordingly. 263- The number of client and server packets, and times the conversation switched sides. 264- A search box. 265- A button to display the entire conversation, only the client side, or only the server side. 266 267You can type a string in the search box and hit enter - or the Next button - to move through the matches. 268 269 270 271Select Regex to instead have termshark interpret your search string as a regular expression. Because termshark is written in Golang, the regular expression uses Golang's regex dialect. [regex101](https://regex101.com/) provides a nice online way to experiment with matches. A quick tip - if you want your match to [cross line endings](https://stackoverflow.com/a/58318036/784226), prefix your search with `(?s)`. 272 273You can choose how to view the reassembled data by using the buttons at the bottom of the screen - ASCII, hex or Wireshark's raw format. Termshark will remember your preferred format. 274 275 276 277Like Wireshark, you can filter the displayed data to show only the client-side or only the server-side of the conversation: 278 279 280 281You can use Copy Mode in stream reassembly too. Hit the `c` key to enter Copy Mode. The currently selected "chunk" will be highlighted. Hit `ctrl-c` to copy that data. By default, termshark will copy the data to your clipboard. Hit the left arrow key to widen the data copied to the entire conversation (or filtered by client or server if that is selected). 282 283 284 285Finally, clicking on a reassembled piece of the stream (enter or left mouse click) will cause termshark to select the underlying packet that contributed that payload. If you hit `q` to exit stream reassembly, termshark will set focus on the selected packet. 286 287### Conversations 288 289To display a table of conversations represented in the current pcap, go to the "Analysis" menu and choose "Conversations". Termshark uses `tshark` to generate a list of conversations by protocol. Currently, termshark supports displaying Ethernet, IPv4, IPv6, UDP and TCP. 290 291 292 293You have have termshark filter the packets displayed according to the current conversation selected. The "Prepare..." button will set termshark's display filter field, but *not* apply it, letting you futher edit it first. The "Apply..." button will set the display filter and apply it immediately. Navigate to the interesting conversation, then click either "Prepare..." or "Apply..." 294 295 296 297In the first pop-up menu, you can choose how to extend the current display filter, if there is in. In the second pop-up menu, you can choose whether to filter by the conversation bidirectionally, unidirectionally, or just using the source or destination. These menus mirror those used in Wireshark. When you hit enter, the filter will be adjusted. Hit 'q' to quit the conversations screen. 298 299 300 301## Configuration 302 303### Dark Mode 304 305If termshark is too bright for your taste, try dark-mode. To enable, hit Esc to open the main menu and select "Toggle Dark Mode". 306 307 308 309Your choice is stored in the termshark [config file](UserGuide.md#config-file). Dark-mode is supported throughout the termshark user-interface. 310 311### Packet Colors 312 313By default, termshark will now display packets in the packet list view colored according to Wireshark's color rules. With recent installations of Wireshark, you can find this file at `$XDG_CONFIG_HOME/wireshark/colorfilters`. Termshark doesn't provide a way to edit the colors - the colors are provided by `tshark`. You can read about Wireshark's support [here](https://www.wireshark.org/docs/wsug_html_chunked/ChCustColorizationSection.html). If you don't like the way this looks in termshark, you can turn it off using termshark's main menu. 314 315### Config File 316 317Termshark reads options from a TOML configuration file saved in `$XDG_CONFIG_HOME/termshark/termshark.toml` (e.g. `~/.config/termshark/termshark.toml` on Linux). All options are saved under the `[main]` section. The available options are: 318 319- `browse-command` (string list) - termshark will run this command with a URL e.g. when the user selects "FAQ" from the main menu. Any argument in the list that equals `$1` will be replaced by the URL prior to the command being run e.g. 320 321```toml 322[main] 323 browse-command = ["firefox", "$1"] 324``` 325 326- `capinfos` (string) - make termshark use this specific `capinfos` binary (for pcap properties). 327- `capture-command` (string) - use this binary to capture packets, passing `-i`, `-w` and `-f` flags. 328- `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. 329- `colors` (bool) - if true, and tshark supports the feature, termshark will colorize packets in its list view. 330- `conv-absolute-time` (bool) - if true, have tshark provide conversation data with a relative start time field. 331- `conv-resolve-names` (bool) - if true, have tshark provide conversation data with ethernet names resolved. 332- `conv-use-filter` (bool) - if true, have tshark provide conversation data limited to match the active display filter. 333- `conv-types` (string list) - a list of the conversation types termshark will query for and display in the conversations view. Currently limited to `eth`, `ip`, `ipv6`, `udp`, `tcp`. 334- `copy-command` (string) - the command termshark executes when the user hits ctrl-c in copy-mode. The default commands on each platform will copy the selected area to the clipboard. 335 336```toml 337[main] 338 copy-command = ["xsel", "-i", "-b"] 339``` 340 341- `copy-command-timeout` (int) - how long termshark will wait (in seconds) for the copy command to complete before reporting an error. 342- `dark-mode` (bool) - if true, termshark will run in dark-mode. 343- `disable-shark-fin` (bool) - if true then it's safe to go back in the water. 344- `dumpcap` (string) - make termshark use this specific `dumpcap` (used when reading from an interface). 345- `packet-colors` (bool) - if true (or missing), termshark will colorize packets according to Wireshark's rules. 346- `pcap-bundle-size` - (int) - load tshark PDML this many packets at a time. Termshark will lazily load PDML because it's a slow process and uses a lot of RAM. For example, if `pcap-bundle-size`=1000, then on first loading a pcap, termshark will load PDML for packets 1-1000. If you scroll past packet 500, termshark will optimistically load PDML for packets 1001-2000. A higher value will make termshark load more packets at a time; a value of 0 means load the entire pcap's worth of PDML. Termshark stores the data compressed in RAM, but expect approximately 10MB per 1000 packets loaded. If you have the memory, can wait a minute or two for the entire pcap to load, and e.g. plan to use the packet list header to sort the packets in various ways, setting `pcap-bundle-size` to 0 will provide the best experience. 347- `pcap-cache-size` - (int) - termshark loads packet PDML (structure) and pcap (bytes) data in bundles of `pcap-bundle-size`. This setting determines how many such bundles termshark will keep cached. The default is 32. 348- `pdml-args` (string list) - any extra parameters to pass to `tshark` when it is invoked to generate PDML. 349- `psml-args` (string list) - any extra parameters to pass to `tshark` when it is invoked to generate PSML. 350- `recent-files` (string list) - the pcap files shown when the user clicks the "recent" button in termshark. Newly viewed files are added to the beginning. 351- `recent-filters` (string list) - recently used Wireshark display filters. 352- `stream-cache-size` (int) - termshark caches the structures and UI used to display reassembled TCP and UDP streams. This allows for quickly redisplaying a stream that's been loaded before. This setting determines how many streams are cached. The default is 100. 353- `stream-view` (string - the default view when displaying a reassembled stream. Choose from "hex"/"ascii"/"raw". 354- `tail-command` (string) - make termshark use this specific `tail` command. This is used when reading from an interface in order to feed `dumpcap`-saved data to `tshark`. The default is `tail -f -c +0 <file>`. If you are running on Windows, the default is to use `termshark` itself with a special hidden `--tail` flag. But probably better to use Wireshark on Windows :-) 355- `term` (string) - termshark will use this as a replacement for the TERM environment variable. 356 357```toml 358[main] 359 term = "screen-256color" 360``` 361 362- `tshark` (string) - make termshark use this specific `tshark`. 363- `tshark-args` (string list) - these are added to each invocation of `tshark` made by termshark e.g. 364 365```toml 366[main] 367 tshark-args = ["-d","udp.port==2075,cflow]" 368``` 369 370- `ui-cache-size` - (int) - termshark will remember the state of widgets representing packets e.g. which parts are expanded in the structure view, and which byte is in focus in the hex view. This setting allows the user to override the number of widgets that are cached. The default is 1000. 371- `validated-tsharks` - (string list) - termshark saves the path of each `tshark` binary it invokes (in case the user upgrades the system `tshark`). If the selected (e.g. `PATH`) tshark binary has not been validated, termshark will check to ensure its version is compatible. tshark must be newer than v1.10.2 (from approximately 2013). 372 373## Troubleshooting 374 375If termshark is running slowly or otherwise misbehaving, you might be able to narrow the issue down by using the `--debug` flag. When you start termshark with `--debug`, three things happen: 376 3771. A web server runs with content available at [http://127.0.0.1:6060/debug/pprof](http://127.0.0.1:6060/debug/pprof) (or the remote IP). This is a Golang feature and provides a view of some low-level internals of the process such as running goroutines. 3782. On receipt of SIGUSR1, termshark will start a Golang CPU profile that runs for 20 seconds. 3793. On receipt of SIGUSR2, termshark will create a Golang memory/heap profile. 380 381Profiles are stored under `$XDG_CONFIG_CACHE/termshark` (e.g. `~/.cache/termshark/`). If you open a termshark issue on github, these profiles will be useful for debugging. 382 383For commonly asked questions, check out the [FAQ](/docs/FAQ.md). 384
