mirror of
https://github.com/veeso/termscp.git
synced 2026-09-27 06:21:22 -07:00
docs(en): write configuration pages
This commit is contained in:
Christian Visintin
@@ -1 +1,50 @@
|
|||||||
# Configuration
|
# Configuration
|
||||||
|
|
||||||
|
termscp supports a number of user-defined parameters. termscp stores them in a
|
||||||
|
TOML file and a few directories, but you never edit these files by hand:
|
||||||
|
configuration is done entirely from the user interface.
|
||||||
|
|
||||||
|
To enter the configuration, press `<CTRL+C>` from the termscp home.
|
||||||
|
|
||||||
|
termscp requires these paths to be accessible:
|
||||||
|
|
||||||
|
- `$HOME/.config/termscp/` on Linux/BSD
|
||||||
|
- `$HOME/Library/Application Support/termscp` on macOS
|
||||||
|
- `FOLDERID_RoamingAppData\termscp\` on Windows
|
||||||
|
|
||||||
|
## Parameters
|
||||||
|
|
||||||
|
The following parameters can be configured:
|
||||||
|
|
||||||
|
- **Text Editor**: the text editor to use. By default termscp finds the default
|
||||||
|
editor for you; with this option you can force an editor to be used (e.g.
|
||||||
|
`vim`). GUI editors are also supported, unless they detach (`nohup`) from the
|
||||||
|
parent process.
|
||||||
|
- **Default Protocol**: the default value for the file transfer protocol to be
|
||||||
|
used in termscp. It applies to the login page and to the address CLI argument.
|
||||||
|
- **Show Hidden Files**: whether hidden files are displayed by default. You can
|
||||||
|
also toggle hidden files at runtime by pressing `A`.
|
||||||
|
- **Check for updates**: if set to `yes`, termscp queries the GitHub API to
|
||||||
|
check whether a new version of termscp is available.
|
||||||
|
- **Prompt when replacing existing files**: if set to `yes`, termscp prompts for
|
||||||
|
confirmation whenever a file transfer would replace an existing file on the
|
||||||
|
target host.
|
||||||
|
- **Group Dirs**: whether directories are grouped in the file explorers. If
|
||||||
|
`Display first` is selected, directories are sorted with the configured method
|
||||||
|
but displayed before files; with `Display last` they are displayed after
|
||||||
|
files.
|
||||||
|
- **Remote file formatter syntax**: syntax used to display file info for each
|
||||||
|
file in the remote explorer. See [File explorer format](explorer-format.md).
|
||||||
|
- **Local file formatter syntax**: syntax used to display file info for each file
|
||||||
|
in the local explorer. See [File explorer format](explorer-format.md).
|
||||||
|
- **Enable notifications**: if set to `Yes`, desktop notifications are displayed.
|
||||||
|
See [Notifications](notifications.md).
|
||||||
|
- **Notifications: minimum transfer size**: if the transfer size is greater than
|
||||||
|
or equal to the specified value, transfer notifications are displayed. The
|
||||||
|
accepted format is `{UNSIGNED} B/KB/MB/GB/TB/PB`.
|
||||||
|
- **SSH configuration path**: SSH configuration file to use when connecting to a
|
||||||
|
SCP/SFTP server. If left empty, no file is used. You can specify a path
|
||||||
|
starting with `~` to indicate the home directory (e.g. `~/.ssh/config`). The
|
||||||
|
attributes supported by termscp are listed at
|
||||||
|
[the ssh2-config exposed attributes](https://github.com/veeso/ssh2-config#exposed-attributes).
|
||||||
|
See also [SSH key storage](ssh-keys.md).
|
||||||
|
|||||||
@@ -1 +1,49 @@
|
|||||||
# File explorer format
|
# File explorer format
|
||||||
|
|
||||||
|
You can define a custom format for the file explorer through the configuration.
|
||||||
|
This is possible for both the local and the remote host, so you can use two
|
||||||
|
different syntaxes. The fields are named **File formatter syntax (local)** and
|
||||||
|
**File formatter syntax (remote)**, and they define how the file entries are
|
||||||
|
displayed in the file explorer.
|
||||||
|
|
||||||
|
## Syntax
|
||||||
|
|
||||||
|
The syntax for the formatter is the following:
|
||||||
|
|
||||||
|
```text
|
||||||
|
{KEY1}... {KEY2:LENGTH}... {KEY3:LENGTH:EXTRA} {KEYn}...
|
||||||
|
```
|
||||||
|
|
||||||
|
Each key in braces is replaced with the related attribute, while everything
|
||||||
|
outside braces is left unchanged.
|
||||||
|
|
||||||
|
- The key name is mandatory and must be one of the keys below.
|
||||||
|
- `LENGTH` describes the width reserved to display the field. Static attributes
|
||||||
|
do not support it (`GROUP`, `PEX`, `SIZE`, `USER`).
|
||||||
|
- `EXTRA` is supported only by some keys and provides an additional option. See
|
||||||
|
the keys below to check whether `EXTRA` is supported.
|
||||||
|
|
||||||
|
## Keys
|
||||||
|
|
||||||
|
These are the keys supported by the formatter:
|
||||||
|
|
||||||
|
| Key | Description |
|
||||||
|
| --------- | ------------------------------------------------------------------------------------------------ |
|
||||||
|
| `ATIME` | Last access time (default `%b %d %Y %H:%M`); `EXTRA` is the time format (e.g. `{ATIME:8:%H:%M}`) |
|
||||||
|
| `CTIME` | Creation time (default `%b %d %Y %H:%M`); `EXTRA` is the time format (e.g. `{CTIME:8:%H:%M}`) |
|
||||||
|
| `GROUP` | Owner group |
|
||||||
|
| `MTIME` | Last change time (default `%b %d %Y %H:%M`); `EXTRA` is the time format (e.g. `{MTIME:8:%H:%M}`) |
|
||||||
|
| `NAME` | File name (folders between root and first ancestors are elided if longer than `LENGTH`) |
|
||||||
|
| `PATH` | File absolute path (folders between root and first ancestors are elided if longer than `LENGTH`) |
|
||||||
|
| `PEX` | File permissions (UNIX format) |
|
||||||
|
| `SIZE` | File size (omitted for directories) |
|
||||||
|
| `SYMLINK` | Symlink target (if any, `-> {FILE_PATH}`) |
|
||||||
|
| `USER` | Owner user |
|
||||||
|
|
||||||
|
## Default format
|
||||||
|
|
||||||
|
If left empty, the default formatter syntax is used:
|
||||||
|
|
||||||
|
```text
|
||||||
|
{NAME:24} {PEX} {USER} {SIZE} {MTIME:17:%b %d %Y %H:%M}
|
||||||
|
```
|
||||||
|
|||||||
@@ -1 +1,28 @@
|
|||||||
# Logging
|
# Logging
|
||||||
|
|
||||||
|
termscp writes a log file for each session, located at:
|
||||||
|
|
||||||
|
- `$HOME/.cache/termscp/termscp.log` on Linux/BSD
|
||||||
|
- `$HOME/Library/Caches/termscp/termscp.log` on macOS
|
||||||
|
- `FOLDERID_LocalAppData\termscp\termscp.log` on Windows
|
||||||
|
|
||||||
|
The log is not rotated: it is truncated on each launch of termscp. If you want
|
||||||
|
to report an issue and attach the log file, save the log somewhere safe before
|
||||||
|
launching termscp again.
|
||||||
|
|
||||||
|
By default the log reports at the `INFO` level, so it is not very verbose.
|
||||||
|
|
||||||
|
## Reproducing an issue at TRACE level
|
||||||
|
|
||||||
|
To submit an issue, reproduce the problem with the log level set to `TRACE` by
|
||||||
|
launching termscp with the `-D` CLI option.
|
||||||
|
|
||||||
|
## Disabling logging
|
||||||
|
|
||||||
|
To turn logging off, start termscp with the `-q` or `--quiet` option. You can
|
||||||
|
alias termscp to make it persistent.
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
The log file does not contain any plaintext password. It exposes the same
|
||||||
|
information as the sibling `bookmarks` file.
|
||||||
|
|||||||
@@ -1 +1,23 @@
|
|||||||
# Notifications
|
# Notifications
|
||||||
|
|
||||||
|
termscp sends desktop notifications for the following events:
|
||||||
|
|
||||||
|
- **Transfer completed**: sent once a transfer has been successfully completed.
|
||||||
|
Displayed only if the total transfer size is at least the configured
|
||||||
|
`Notifications: minimum transfer size`.
|
||||||
|
- **Transfer failed**: sent once a transfer has failed due to an error.
|
||||||
|
Displayed only if the total transfer size is at least the configured
|
||||||
|
`Notifications: minimum transfer size`.
|
||||||
|
- **Update available**: sent whenever a new version of termscp is available.
|
||||||
|
- **Update installed**: sent whenever a new version of termscp has been
|
||||||
|
installed.
|
||||||
|
- **Update failed**: sent whenever the installation of an update fails.
|
||||||
|
|
||||||
|
## Disable notifications
|
||||||
|
|
||||||
|
To turn notifications off, enter setup and set `Enable notifications?` to `No`.
|
||||||
|
|
||||||
|
## Change the minimum transfer size
|
||||||
|
|
||||||
|
To change the threshold that gates transfer notifications, enter setup and set
|
||||||
|
`Notifications: minimum transfer size` to the value that suits you.
|
||||||
|
|||||||
@@ -1 +1,49 @@
|
|||||||
# Password security
|
# Password security
|
||||||
|
|
||||||
|
Bookmarks are saved in your configuration directory along with their passwords.
|
||||||
|
Passwords are not stored in plaintext: they are encrypted with AES.
|
||||||
|
|
||||||
|
The key used to encrypt passwords is stored, where possible, in the operating
|
||||||
|
system secret store:
|
||||||
|
|
||||||
|
- The Windows Vault on Windows
|
||||||
|
- The system keyring on Linux
|
||||||
|
- The Keychain on macOS
|
||||||
|
|
||||||
|
This is managed directly by your operating system.
|
||||||
|
|
||||||
|
On BSD and WSL there is no such secret store, so the encryption key is saved on
|
||||||
|
disk at `$HOME/.config/termscp`. The location protects the key with file
|
||||||
|
permissions so that it cannot be read by other users, but you should still avoid
|
||||||
|
saving passwords for servers exposed on the internet on these systems.
|
||||||
|
|
||||||
|
## Linux keyring
|
||||||
|
|
||||||
|
On Linux there might be no keyring installed on your system. The key storage
|
||||||
|
requires a service that exposes `org.freedesktop.secrets` on D-Bus, and only a
|
||||||
|
few services provide it:
|
||||||
|
|
||||||
|
- If you use GNOME as your desktop environment (e.g. Ubuntu users), the keyring
|
||||||
|
is already provided by `gnome-keyring` and everything should work out of the
|
||||||
|
box.
|
||||||
|
- For other desktop environments, you can use [KeepassXC](https://keepassxc.org/)
|
||||||
|
to obtain a keyring. It must be set up to work with termscp; see
|
||||||
|
[KeepassXC setup](#keepassxc-setup) below.
|
||||||
|
- If you do not want to install any of these services, termscp keeps working as
|
||||||
|
usual and falls back to saving the key in a file, as it does for BSD and WSL.
|
||||||
|
|
||||||
|
### KeepassXC setup
|
||||||
|
|
||||||
|
Follow these steps to set up KeepassXC for termscp:
|
||||||
|
|
||||||
|
1. Install KeepassXC.
|
||||||
|
2. Go to "Tools" > "Settings" in the toolbar.
|
||||||
|
3. Select "Secret service integration" and enable "Enable KeepassXC
|
||||||
|
freedesktop.org secret service integration".
|
||||||
|
4. Create a database, if you do not have one yet: from the toolbar, "Database" >
|
||||||
|
"New database".
|
||||||
|
5. From the toolbar, go to "Database" > "Database settings".
|
||||||
|
6. Select "Secret service integration" and enable "Expose entries under this
|
||||||
|
group".
|
||||||
|
7. Select the group where the termscp secret will be kept. Note that any other
|
||||||
|
application can read secrets exposed via D-Bus for that group.
|
||||||
|
|||||||
@@ -1 +1,25 @@
|
|||||||
# SSH key storage
|
# SSH key storage
|
||||||
|
|
||||||
|
Along with configuration, termscp provides an essential feature for SFTP/SCP
|
||||||
|
clients: the SSH key storage.
|
||||||
|
|
||||||
|
To access the SSH key storage, enter the configuration and move to the
|
||||||
|
`SSH Keys` tab.
|
||||||
|
|
||||||
|
## Manage keys
|
||||||
|
|
||||||
|
From the `SSH Keys` tab you can:
|
||||||
|
|
||||||
|
- **Add a new key**: press `<CTRL+N>`. You are prompted to provide the
|
||||||
|
hostname/IP address and the username associated with the key, then a text
|
||||||
|
editor opens: paste the **private** SSH key into the editor, save and quit.
|
||||||
|
- **Remove an existing key**: press `<DEL>` or `<CTRL+E>` on the key you want to
|
||||||
|
remove to delete it persistently from termscp.
|
||||||
|
- **Edit an existing key**: press `<ENTER>` on the key you want to edit to change
|
||||||
|
the private key.
|
||||||
|
|
||||||
|
## Password-protected keys
|
||||||
|
|
||||||
|
Password-protected private keys are supported. The password you provide for
|
||||||
|
authentication in termscp is valid both for username/password authentication and
|
||||||
|
for key authentication.
|
||||||
|
|||||||
@@ -1 +1,119 @@
|
|||||||
# Themes
|
# Themes
|
||||||
|
|
||||||
|
termscp lets you set the colors for several components in the application. There
|
||||||
|
are two ways to customize termscp:
|
||||||
|
|
||||||
|
- From the **configuration menu**
|
||||||
|
- Importing a **theme file**
|
||||||
|
|
||||||
|
## Customize from the configuration menu
|
||||||
|
|
||||||
|
To customize termscp from the configuration menu, enter the configuration from
|
||||||
|
the auth screen by pressing `<CTRL+C>`, then press `<TAB>` twice to reach the
|
||||||
|
`themes` panel. Move with `<UP>` and `<DOWN>` to select the style you want to
|
||||||
|
change, as shown in the gif below:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Import a theme file
|
||||||
|
|
||||||
|
You can also import theme files. You can take inspiration from, or directly use,
|
||||||
|
one of the themes bundled with termscp in the `themes/` directory of the
|
||||||
|
repository. Import a theme by running:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
termscp -t <theme_file>
|
||||||
|
```
|
||||||
|
|
||||||
|
This is also available as:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
termscp theme <theme_file>
|
||||||
|
```
|
||||||
|
|
||||||
|
If everything is fine, termscp confirms the theme has been imported.
|
||||||
|
|
||||||
|
## Color syntax
|
||||||
|
|
||||||
|
termscp accepts the following color formats:
|
||||||
|
|
||||||
|
- Explicit hexadecimal: `#rrggbb`
|
||||||
|
- RGB: `rgb(r, g, b)`
|
||||||
|
- [CSS color names](https://www.w3schools.com/cssref/css_colors.asp) (such as
|
||||||
|
`crimson`)
|
||||||
|
- The special keyword `Default`, which uses the situational default foreground
|
||||||
|
or background color (foreground for texts and lines, background otherwise)
|
||||||
|
|
||||||
|
## Recovering from a theme that won't load
|
||||||
|
|
||||||
|
After an update, a saved theme can fail to load. This happens when a new key is
|
||||||
|
added to themes: the previously saved theme no longer contains that key. There
|
||||||
|
are two quick fixes:
|
||||||
|
|
||||||
|
1. Re-import the official theme. After each release the official themes are
|
||||||
|
patched, so download the updated theme from the repository and re-import it:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
termscp -t <theme.toml>
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Edit your theme by hand. If you use a custom theme, edit the file and add the
|
||||||
|
missing key. The theme is located at `$CONFIG_DIR/termscp/theme.toml`, where
|
||||||
|
`$CONFIG_DIR` is:
|
||||||
|
|
||||||
|
- FreeBSD/Linux: `$HOME/.config/`
|
||||||
|
- macOS: `$HOME/Library/Application Support`
|
||||||
|
- Windows: `%appdata%`
|
||||||
|
|
||||||
|
Missing keys are reported in the CHANGELOG under `BREAKING CHANGES` for the
|
||||||
|
version you have just installed.
|
||||||
|
|
||||||
|
## Styles
|
||||||
|
|
||||||
|
The tables below describe each style field. Note that styles do **not** apply to
|
||||||
|
the configuration page, so it always remains usable in case you change something
|
||||||
|
by mistake.
|
||||||
|
|
||||||
|
### Authentication page
|
||||||
|
|
||||||
|
| Key | Description |
|
||||||
|
| ---------------- | ---------------------------------------- |
|
||||||
|
| `auth_address` | Color of the input field for IP address |
|
||||||
|
| `auth_bookmarks` | Color of the bookmarks panel |
|
||||||
|
| `auth_password` | Color of the input field for password |
|
||||||
|
| `auth_port` | Color of the input field for port number |
|
||||||
|
| `auth_protocol` | Color of the radio group for protocol |
|
||||||
|
| `auth_recents` | Color of the recents panel |
|
||||||
|
| `auth_username` | Color of the input field for username |
|
||||||
|
|
||||||
|
### Transfer page
|
||||||
|
|
||||||
|
| Key | Description |
|
||||||
|
| -------------------------------------- | ------------------------------------------------------------------------- |
|
||||||
|
| `transfer_local_explorer_background` | Background color of localhost explorer |
|
||||||
|
| `transfer_local_explorer_foreground` | Foreground color of localhost explorer |
|
||||||
|
| `transfer_local_explorer_highlighted` | Border and highlighted color for localhost explorer |
|
||||||
|
| `transfer_remote_explorer_background` | Background color of remote explorer |
|
||||||
|
| `transfer_remote_explorer_foreground` | Foreground color of remote explorer |
|
||||||
|
| `transfer_remote_explorer_highlighted` | Border and highlighted color for remote explorer |
|
||||||
|
| `transfer_log_background` | Background color for log panel |
|
||||||
|
| `transfer_log_window` | Window color for log panel |
|
||||||
|
| `transfer_progress_bar_partial` | Partial progress bar color |
|
||||||
|
| `transfer_progress_bar_total` | Total progress bar color |
|
||||||
|
| `transfer_status_hidden` | Color for status bar "hidden" label |
|
||||||
|
| `transfer_status_sorting` | Color for status bar "sorting" label; applies also to file sorting dialog |
|
||||||
|
| `transfer_status_sync_browsing` | Color for status bar "sync browsing" label |
|
||||||
|
|
||||||
|
### Misc
|
||||||
|
|
||||||
|
These styles apply to different parts of the application.
|
||||||
|
|
||||||
|
| Key | Description |
|
||||||
|
| ------------------- | ------------------------------------------- |
|
||||||
|
| `misc_error_dialog` | Color for error messages |
|
||||||
|
| `misc_info_dialog` | Color for info dialogs |
|
||||||
|
| `misc_input_dialog` | Color for input dialogs (such as copy file) |
|
||||||
|
| `misc_keys` | Color of text for key strokes |
|
||||||
|
| `misc_quit_dialog` | Color for quit dialogs |
|
||||||
|
| `misc_save_dialog` | Color for save dialogs |
|
||||||
|
| `misc_warn_dialog` | Color for warn dialogs |
|
||||||
|
|||||||
Reference in New Issue
Block a user