Skip to content

Commit

Permalink
Add some documentation on the new profile support
Browse files Browse the repository at this point in the history
  • Loading branch information
gcla committed Jul 3, 2022
1 parent 9b5a9ac commit 37ec8df
Showing 1 changed file with 33 additions and 4 deletions.
37 changes: 33 additions & 4 deletions docs/UserGuide.md
Original file line number Diff line number Diff line change
Expand Up @@ -494,17 +494,44 @@ https://user-images.githubusercontent.com/45680/122692277-0de7e180-d202-11eb-964

## Configuration

### Profiles

Termshark v2.4 introduces support for Wireshark-like profiles. A simple mental model for a profile called "work" is a separate toml file, stored as
`$XDG_CONFIG_HOME/termshark/profiles/work/termshark.toml`, whose settings take precedence over the default `termshark.toml` file. When a non-default
profile is active, termshark will display its name at the top of the user-interface. Configuration changes are saved to the currently-active
profile. These include typical termshark settings like dark-mode, columns and theme.

To create a profile, open the command line and type `profile create`. Termshark will open a dialog that lets you name your profile and, optionally,
"link" it to a Wireshark-profile.

![profilecreate](/../gh-pages/images/profilecreate.png?raw=true)

The effect of linking to a Wireshark profile "wshark" is that termshark will run tshark with the flags `-C wshark`. One useful effect of this is that
tshark will generate packet colors according to those configured for the "wshark" Wireshark profile. This allows Wireshark packet coloring rules to be
used flexibly in termshark; create a new termshark profile and link to the Wireshark profile with the colors configured the way you want. Once a
profile is created, you can unlink and re-link to a different Wireshark profile using the `profile unlink` and `profile link` commands respectively.

Once you have profiles configured, you can switch between them using the `profile use` command. Termshark may reload your current packet source if it
determines it needs to regenerate parts of the UI e.g. if packet colors or columns may be different. Note that if you create a new profile "new" while
currently using profile "old", the settings for "new" are initialized from "old" (the toml file is copied); but then further changes apply to profile
"new" only.

### Dark Mode

If termshark is too bright for your taste, try dark-mode. To enable, hit Esc to open the main menu and select "Toggle Dark Mode".

![darkmode](/../gh-pages/images/darkmode.png?raw=true)

Your choice is stored in the termshark [config file](UserGuide.md#config-file). Dark-mode is supported throughout the termshark user-interface.
Your choice is stored in the termshark [config file](UserGuide.md#config-file) for the currently active profile. Dark-mode is supported throughout the
termshark user-interface.

### Packet Colors

By 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.
By default, termshark will now display packets in the packet list view colored according to Wireshark's default 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.

### Themes

Expand Down Expand Up @@ -549,7 +576,7 @@ Termshark saves your selected theme against the terminal color mode, which can b
- 256-color
- truecolor i.e. 24-bit color

The theme is saved in `termshark.toml` under, respectively, the keys:
The theme is saved in the current profile's `termshark.toml` under, respectively, the keys:

- `main.theme-16`
- `main.theme-256`
Expand Down Expand Up @@ -614,7 +641,9 @@ widgets that will have focus when control returns to the container. Unselected m

### Config File

Termshark 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:
Termshark reads options from a TOML configuration file saved in `$XDG_CONFIG_HOME/termshark/termshark.toml` (e.g. `~/.config/termshark/termshark.toml`
on Linux) if you are using the default profile. If you are using a profile called "work", the settings are saved in
`$XDG_CONFIG_HOME/termshark/profiles/work/termshark.toml`. All options are saved under the `[main]` section. The available options are:

- `always-keep-pcap` (bool) - if true, and if termshark is run on a live packet source (`-i`), when termshark is asked to exit, it will not prompt the user to choose whether to keep or delete the capture.
- `auto-scroll` (bool) - if true, termshark will automatically scroll down when packets are read in a live-capture mode (e.g. `-i eth0`)
Expand Down

0 comments on commit 37ec8df

Please sign in to comment.