diff --git a/docs/en-US/configuration/configuration.md b/docs/en-US/configuration/configuration.md index a025a48..9131878 100644 --- a/docs/en-US/configuration/configuration.md +++ b/docs/en-US/configuration/configuration.md @@ -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 `` 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). diff --git a/docs/en-US/configuration/explorer-format.md b/docs/en-US/configuration/explorer-format.md index ef7e5c5..3f28ad7 100644 --- a/docs/en-US/configuration/explorer-format.md +++ b/docs/en-US/configuration/explorer-format.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} +``` diff --git a/docs/en-US/configuration/logging.md b/docs/en-US/configuration/logging.md index b921bbe..199608e 100644 --- a/docs/en-US/configuration/logging.md +++ b/docs/en-US/configuration/logging.md @@ -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. diff --git a/docs/en-US/configuration/notifications.md b/docs/en-US/configuration/notifications.md index 6aac42f..2badc17 100644 --- a/docs/en-US/configuration/notifications.md +++ b/docs/en-US/configuration/notifications.md @@ -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. diff --git a/docs/en-US/configuration/password-security.md b/docs/en-US/configuration/password-security.md index 6cd7529..d5f6d8d 100644 --- a/docs/en-US/configuration/password-security.md +++ b/docs/en-US/configuration/password-security.md @@ -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. diff --git a/docs/en-US/configuration/ssh-keys.md b/docs/en-US/configuration/ssh-keys.md index 7181e39..2019c2e 100644 --- a/docs/en-US/configuration/ssh-keys.md +++ b/docs/en-US/configuration/ssh-keys.md @@ -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 ``. 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 `` or `` on the key you want to + remove to delete it persistently from termscp. +- **Edit an existing key**: press `` 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. diff --git a/docs/en-US/configuration/themes.md b/docs/en-US/configuration/themes.md index 537c6e2..cdadf8c 100644 --- a/docs/en-US/configuration/themes.md +++ b/docs/en-US/configuration/themes.md @@ -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 ``, then press `` twice to reach the +`themes` panel. Move with `` and `` to select the style you want to +change, as shown in the gif below: + +![Themes](https://github.com/veeso/termscp/blob/main/assets/images/themes.gif?raw=true) + +## 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 +``` + +This is also available as: + +```sh +termscp theme +``` + +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 + ``` + +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 |