mirror of
https://github.com/veeso/termscp.git
synced 2026-07-19 06:14:23 +02:00
docs(en): write configuration pages
This commit is contained in:
Christian Visintin
@@ -1 +1,50 @@
|
||||
# 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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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