## trzsz-ssh ( tssh ) - an ssh client alternative that meets your needs
[](https://choosealicense.com/licenses/mit/)
[](https://github.com/trzsz/trzsz-ssh/releases)
[](https://trzsz.github.io/ssh)
[](https://trzsz.github.io/cn/ssh)
trzsz-ssh ( tssh ) is an ssh client designed as a drop-in replacement for the openssh client. It aims to provide complete compatibility with openssh, mirroring all its features, while also offering additional useful features not found in the openssh client.
trzsz-ssh ( tssh ) with [tsshd](https://github.com/trzsz/tsshd) also supports intermittent connectivity, allows roaming, and can be used on high-latency links such as cellular data connections, unstable Wi-Fi, etc.
### Why to do
- `tssh` login prompt supports searching and selecting the servers to log in to, if you can't remember them.
- `tssh` has built-in support for [trzsz](https://trzsz.github.io/) ( trz / tsz ), no longer need to open a new session to transfer files.
- `tssh` supports multiple selection and batch login, and supports executing the preset remote command.
- `tssh` supports remember password, supports automated interaction, improving your login efficiency.
- `tssh` instead of `trzsz ssh` on Windows, solves the issue of slow upload speed of `trz` on Windows.
- `tssh` with [tsshd](https://github.com/trzsz/tsshd) are similar to mosh, solved some of mosh's issues, such as SSH forwarding and ProxyJump.
### Installation
**_Here is how to install `trzsz-ssh (tssh)` on the client side (choose one):_**
- Install with scoop / winget / choco on Windows
scoop install tssh / winget install tssh / choco install tssh
```sh
scoop install tssh
```
```sh
winget install tssh
```
```sh
choco install tssh
```
- Install with Homebrew on MacOS
brew install trzsz-ssh
```sh
brew update
brew install trzsz-ssh
```
- Install with apt on Ubuntu
sudo apt install tssh
```sh
sudo apt update && sudo apt install software-properties-common
sudo add-apt-repository ppa:trzsz/ppa && sudo apt update
sudo apt install tssh
```
- Install with apt on Debian
sudo apt install tssh
```sh
sudo apt install curl gpg
curl -s 'https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x7074ce75da7cc691c1ae1a7c7e51d1ad956055ca' \
| gpg --dearmor -o /usr/share/keyrings/trzsz.gpg
echo 'deb [signed-by=/usr/share/keyrings/trzsz.gpg] https://ppa.launchpadcontent.net/trzsz/ppa/ubuntu jammy main' \
| sudo tee /etc/apt/sources.list.d/trzsz.list
sudo apt update
sudo apt install tssh
```
- Install with yum on Linux
sudo yum install tssh
- Install with [gemfury](https://gemfury.com/) repository.
```sh
echo '[trzsz]
name=Trzsz Repo
baseurl=https://yum.fury.io/trzsz/
enabled=1
gpgcheck=0' | sudo tee /etc/yum.repos.d/trzsz.repo
sudo yum install tssh
```
- Install with [wlnmp](https://www.wlnmp.com/install) repository. It's not necessary to configure the epel repository for tssh.
```sh
curl -fsSL "https://sh.wlnmp.com/wlnmp.sh" | bash
sudo yum install tssh
```
- Install with yay on ArchLinux
yay -S tssh
```sh
yay -Syu
yay -S tssh
```
- Install with Chromebrew on ChromeOS
crew install tssh
```sh
crew install tssh
```
- Install with Go ( Requires go 1.25 or later )
go install github.com/trzsz/trzsz-ssh/cmd/tssh@latest
```sh
go install github.com/trzsz/trzsz-ssh/cmd/tssh@latest
```
The binaries are usually located in ~/go/bin/ ( C:\Users\your_name\go\bin\ on Windows ).
- Build from source ( Requires go 1.25 or later )
sudo make install
```sh
git clone --depth 1 https://github.com/trzsz/trzsz-ssh.git
cd trzsz-ssh
make
sudo make install
```
- Download from the [GitHub Releases](https://github.com/trzsz/trzsz-ssh/releases) and install locally
download and install locally
```sh
sudo apt install /tmp/tssh_*.deb
sudo dpkg -i /tmp/tssh_*.deb
sudo dnf install /tmp/tssh_*.rpm
sudo yum install /tmp/tssh_*.rpm
sudo rpm -i /tmp/tssh_*.rpm
tar zxvf tssh_*.tar.gz && sudo cp tssh_*/tssh /usr/bin/
```
### Login Prompt
- Before use, you need to configure `~/.ssh/config` (for Windows, it is `C:\Users\xxx\.ssh\config`, replace `xxx` with your username).
- For how to configure `~/.ssh/config`, please refer to the documentation of [openssh](https://manpages.debian.org/bookworm/openssh-client/ssh_config.5.en.html) ( `Match` section is not supported yet ).
- Running `tssh` without arguments will open the login prompt. If there are arguments except destination will also open the login prompt.
- If the destination is part of the aliases in `~/.ssh/config`, and can't completely match an alias, the login prompt will also be opened.
- If `#!! HideHost yes` is configured, or the alias contains `*` or `?` wildcard characters, it will not be displayed in the login prompt.
- `tssh` supports shortcuts, supports search, and supports multi-selection when used in `tmux`, `iTerm2`, and `Windows Terminal`, etc.
| Action | Global shortcuts | Non search shortcuts | Shortcuts description |
| --------- | ------------------------------- | -------------------- | -------------------------- |
| Confirm | Enter | | Confirm and login |
| Quit/Exit | Ctrl+C Ctrl+Q | q Q | Cancel and quit |
| Move Prev | Ctrl+K Shift+Tab ↑ | k K | Move cursor up |
| Move Next | Ctrl+J Tab ↓ | j J | Move cursor down |
| Page Up | Ctrl+H Ctrl+U Ctrl+B PageUp ← | h H u U b B | Page up |
| Page Down | Ctrl+L Ctrl+D Ctrl+F PageDown → | l L d D f F | Page down |
| Goto Home | Home | g | Go to the first item |
| Goto End | End | G | Go to the last item |
| EraseKeys | Ctrl+E | e E | Erase search keywords |
| TglSearch | / | | Toggle search function |
| Tgl Help | ? | | Toggle help information |
| TglSelect | Ctrl+X Ctrl+Space Alt+Space | Space x X | Toggle selection |
| SelectAll | Ctrl+A | a A | Select all current items |
| SelectOpp | Ctrl+O | o O | Select the opposite items |
| Open Wins | Ctrl+W | w W | Batch login in new windows |
| Open Tabs | Ctrl+T | t T | Batch login in new tabs |
| Open Pane | Ctrl+P | p P | Batch login in new panes |
### Custom Theme
- `tssh` supports a few themes. Choose one by setting `PromptThemeLayout` in `$XDG_CONFIG_HOME/tssh/tssh.conf` ( or `~/.tssh.conf` ). Welcome to create more and better themes together.
- Each theme supports custom colors. Just configure the `PromptThemeColors` in `$XDG_CONFIG_HOME/tssh/tssh.conf` ( or `~/.tssh.conf` ) to override the default colors as you prefer.
- Please [❤️vote❤️](https://github.com/trzsz/trzsz-ssh/issues/75) for your favorite theme. The theme with the highest number of votes will be set as the default theme in the next version.
#### tiny theme
- Configure `PromptThemeLayout = tiny` in `$XDG_CONFIG_HOME/tssh/tssh.conf` ( or `~/.tssh.conf` ) to choose `tiny theme`.

- Configure `PromptThemeColors` in `$XDG_CONFIG_HOME/tssh/tssh.conf` ( or `~/.tssh.conf` ) and configure it in one line. `tiny theme` supports the following color items:
tiny theme colors and default values:
```json
{
"help_tips": "faint",
"shortcuts": "faint",
"label_icon": "blue",
"label_text": "default",
"cursor_icon": "green|bold",
"active_selected": "green|bold",
"active_alias": "cyan|bold",
"active_host": "magenta|bold",
"active_group": "blue|bold",
"inactive_selected": "green|bold",
"inactive_alias": "cyan",
"inactive_host": "magenta",
"inactive_group": "blue",
"details_title": "default",
"details_name": "faint",
"details_value": "default"
}
```
tiny theme color enumerations which can be concatenated with `|`:
```
default
black
red
green
yellow
blue
magenta
cyan
white
bgBlack
bgRed
bgGreen
bgYellow
bgBlue
bgMagenta
bgCyan
bgWhite
bold
faint
italic
underline
```
#### simple theme
- Configure `PromptThemeLayout = simple` in `$XDG_CONFIG_HOME/tssh/tssh.conf` ( or `~/.tssh.conf` ) to choose `simple theme`.

- The custom colors and default values of `simple theme` are exactly the same as the `tiny theme`.
#### table theme
- Configure `PromptThemeLayout = table` in `$XDG_CONFIG_HOME/tssh/tssh.conf` ( or `~/.tssh.conf` ) to choose `table theme`.

- Configure `PromptThemeColors` in `$XDG_CONFIG_HOME/tssh/tssh.conf` ( or `~/.tssh.conf` ) and configure it in one line. `table theme` supports the following color items:
table theme colors and default values:
```json
{
"help_tips": "faint",
"shortcuts": "faint",
"table_header": "10",
"default_alias": "6",
"default_host": "5",
"default_group": "4",
"selected_icon": "2",
"selected_alias": "14",
"selected_host": "13",
"selected_group": "12",
"default_border": "8",
"selected_border": "10",
"details_name": "4",
"details_value": "3",
"details_border": "8"
}
```
- For supported color enumerations, please refer to [lipgloss](https://github.com/charmbracelet/lipgloss#colors), except `help_tips` and `shortcuts` are the same as the `tiny theme`.
### Support trzsz
- [trzsz](https://trzsz.github.io/) needs to be installed on the server to use `trz / tsz` for uploading and downloading files. Choose either the [Go version](https://trzsz.github.io/go) ( ⭐ Recommended ), [Py version](https://trzsz.github.io/), or [Js version](https://trzsz.github.io/js).
- In the `~/.ssh/config` or `ExConfigPath` configuration file, configure `EnableDragFile` to `Yes` to enable the drag and drop to upload feature.
```
Host *
# If configured in ~/.ssh/config, add `#!!` prefix to be compatible with openssh.
EnableDragFile Yes
```
- If you want to overwrite the existing files when dragging files to upload, configure `DragFileUploadCommand` to `trz -y`:
```
Host xxx
# If configured in ~/.ssh/config, add `#!!` prefix to be compatible with openssh.
DragFileUploadCommand trz -y
```
- If you want to temporarily enable the drag and drop to upload feature, use `tssh --dragfile` to log in.
- In the `~/.ssh/config` or `ExConfigPath` configuration file, configure `EnableTrzsz` to `No` to disable the trzsz and zmodem feature.
```
Host no_trzsz_nor_zmodem
# If configured in ~/.ssh/config, add `#!!` prefix to be compatible with openssh.
EnableTrzsz No
```
- You can use the `--upload-file` argument to specify file or directory to upload directly in the command line, and you can specify the `trz` upload command arguments and save path after the server, such as:
```sh
tssh --upload-file /path/to/file1 --upload-file /path/to/dir2 xxx_server '~/.local/bin/trz -d /tmp/'
```
- You can use `tsz` in the command line to directly download files and directories to your local computer. You can also use the `--download-path` argument to specify the path for local saving, such as:
```sh
tssh -t --client --download-path /tmp/ xxx_server 'tsz -d /path/to/file1 /path/to/dir2'
```

### Support zmodem
- In the `~/.ssh/config` or `ExConfigPath` configuration file, configure `EnableZmodem` to `Yes` to enable the zmodem ( rz / sz ) feature.
```
Host *
# If configured in ~/.ssh/config, add `#!!` prefix to be compatible with openssh.
EnableZmodem Yes
```
- If you want to use `rz` to upload when dragging files, configure `DragFileUploadCommand` to `rz`:
```
Host xxx
# If configured in ~/.ssh/config, add `#!!` prefix to be compatible with openssh.
EnableDragFile Yes
DragFileUploadCommand rz
```
- Not only the server, but also the local computer needs to install `lrzsz`. For Windows, you can download from [lrzsz-win32](https://github.com/trzsz/lrzsz-win32/releases), unzip and add to `PATH` environment, or install it as follows:
```
scoop install lrzsz / choco install lrzsz / winget install lrzsz
```
- If you want to temporarily enable the zmodem ( rz / sz ) feature, use `tssh --zmodem` to log in.
- About the progress, the transferred and speed are not precise. It just indicating that the transfer is in progress.
- You can use the `--upload-file` argument to specify file to upload directly in the command line, and `cd` to the save path and specify the `rz` command with arguments after the server, such as:
```sh
tssh --upload-file /path/to/file1 --upload-file /path/to/file2 xxx_server 'cd /tmp/ && rz -yeb'
```
- You can use `sz` in the command line to directly download files to your local computer. You can also use the `--download-path` argument to specify the path for local saving, such as:
```sh
tssh -t --client --zmodem --download-path /tmp/ xxx_server 'sz /path/to/file1 /path/to/file2'
```
### Support scp sftp
- Using the `Remember Password` feature of `tssh`, you no longer need to manually enter your password. The same applies to `scp` and `sftp`.
- Using the `UDP Mode` feature of `tssh`, the SSH session uses an encrypted UDP channel for communication. The same applies to `scp` and `sftp`.
- As long as `scp` and `sftp` use the `-S` option to specify `tssh`, or configure an alias, you can use some of the features provided by `tssh`, such as:
```sh
sftp -S tssh xxx
scp -S tssh xxx @xxx:/tmp/
alias tscp='scp -S tssh'
alias tsftp='sftp -S tssh'
```
### Batch Login
- tssh supports selecting multiple servers in `iTerm2`( Requires [Python API](https://iterm2.com/python-api-auth.html), no need to `Allow all apps to connect` ),`tmux` and `Windows Terminal`, logging in to them in batches, and executing pre-specified commands in batches.
- Press `Space`, `x` or `Ctrl+X` to toggle select the current host. If it cann't be selected, it means that the current terminal is not supported yet. Please run `tmux` first.
- Press `a` or `Ctrl+A` to select all the hosts on the current page, `o` or `Ctrl+O` to select the opposite hosts on the current page, `d` or `l` move to next page.
- Press `p` or `Ctrl+P` will split panes for batch login, `w` or `Ctrl+W` will open new windows for batch login, `t` or `Ctrl+T` will open new tabs for batch login.
- Execute the `tssh` command without arguments, you can log in to servers in batches. And you can specify the commands to be executed in batches by `-o RemoteCommand`. And you can switch to an interactive shell after executing the specified command. `Windows Terminal` does not support semicolon `;`, you can use `|cat&&` instead. For example:
```sh
tssh -t -o RemoteCommand='ping -c3 trzsz.github.io ; bash -l'
tssh -t -o RemoteCommand="ping -c3 trzsz.github.io |cat&& bash -l"
```

### Group Labels
- If there are a lot of servers, `GroupLabels` can be used to quickly find the target server when searching by `/`.
- After press `/` and search for a group label, press `Enter` to lock it. You can search for another group label by pressing `/` again, and press `Enter` to lock it too.
- In non-search mode, press `E` to erase the current search group labels. In search mode, press `Ctrl + E` to have the same effect.
- Supports configuring multiple group labels separated by spaces in one `GroupLabels`. Supports configuring multiple `GroupLabels`.
- Supports configuring group labels on multiple Host nodes in the form of wildcard \*, and `tssh` will summarize all the group labels.
```
# The following testAA has group labels group1 group2 label3 label4 group5. Add `#!!` prefix to be compatible with openssh.
Host test*
#!! GroupLabels group1 group2
#!! GroupLabels label3
Host testAA
#!! GroupLabels label4 group5
```
### Automated Interaction
- Supports automated interaction feature similar to `expect`. After logging into the server, it automatically matches the server's output and then enters input accordingly.
```
Host auto
#!! ExpectCount 2 # Configures the number of automated interactions, default is 0 which means no automated interaction
#!! ExpectTimeout 30 # Configures the timeout for automated interaction (in seconds), default is 30 seconds
#!! ExpectPattern1 *assword # Configures the first automated interaction match expression
# Configures the first automated input (encrypted). It was encoded by `tssh --enc-secret`, `tssh` will send \r (enter) automatically
#!! ExpectSendPass1 d7983b4a8ac204bd073ed04741913befd4fbf813ad405d7404cb7d779536f8b87e71106d7780b2
#!! ExpectPattern2 hostname*$ # Configures the second automated interaction match expression
#!! ExpectSendText2 echo tssh expect\r # Configures the second automated input (plaintext), specify \r to send enter
# Choose either ExpectSendPass? or ExpectSendText? for each interaction; if both are configured, ExpectSendPass? has higher priority
```
- Before each `ExpectPattern?` match, one or multiple optional matches can be configured as follows:
```
Host case
#!! ExpectCount 1 # Configures the number of automated interactions, default is 0 which means no automated interaction
#!! ExpectPattern1 hostname*$ # Configures the first automated interaction match expression
#!! ExpectSendText1 ssh xxx\r # Configures the first automated input, can also use ExpectSendPass1 then configure with encrypted text
#!! ExpectCaseSendText1 yes/no y\r # Before matching ExpectPattern1, if encountering yes/no, then send y and enter
#!! ExpectCaseSendText1 y/n yes\r # Before matching ExpectPattern1, if encountering y/n, then send yes and enter
#!! ExpectCaseSendPass1 token d7... # Before matching ExpectPattern1, if encountering token, then decode d7... and send
```
- When the server's output is matched, generate the `totp` 2FA code, and send it:
```
Host totp
#!! ExpectCount 2 # Configures the number of automated interactions, default is 0 which means no automated interaction
#!! ExpectPattern1 token: # Configures the first automated interaction match expression
#!! ExpectSendTotp1 xxxxx # Configure the secret (plain text) of totp, generally obtained by scanning the QR code
#!! ExpectPattern2 token: # Configures the second automated interaction match expression
# The following ciphertext was generated by encoding the secret of totp with `tssh --enc-secret`.
#!! ExpectSendEncTotp2 821fe830270201c36cd1a869876a24453014ac2f1d2d3b056f3601ce9cc9a87023
```
- When the server's output is matched, execute the specified command to obtain the one-time password, and send it:
```
Host otp
#!! ExpectCount 2 # Configures the number of automated interactions, default is 0 which means no automated interaction
#!! ExpectPattern1 token: # Configures the first automated interaction match expression
#!! ExpectSendOtp1 oathtool --totp -b xxxxx # Configure the command line to obtain the one-time password
#!! ExpectPattern2 token: # Configures the second automated interaction match expression
# The following ciphertext was generated by encoding `oathtool --totp -b xxxxx` with `tssh --enc-secret`.
#!! ExpectSendEncOtp2 77b4ce85d087b39909e563efb165659b22b9ea700a537f1258bdf56ce6fdd6ea70bc7591ea5c01918537a65433133bc0bd5ed3e4
```
- Some servers may not support sending data continuously. For example, sending `1\r` requires a slight delay after `1` before sending `\r`. You can use `\|` to separate them.
```
Host sleep
#!! ExpectCount 2 # Configures the number of automated interactions, default is 0 which means no automated interaction
#!! ExpectSleepMS 100 # Number of milliseconds to sleep between separate inputs, default is 100ms
#!! ExpectPattern1 x> # Configures the first automated interaction match expression
#!! ExpectSendText1 1\|\r # Configures the first automated input, send 1, sleep 100ms, send \r.
#!! ExpectPattern2 y> # Configures the second automated interaction match expression
#!! ExpectSendText2 \|1\|\|\r # Configures the second automated input, sleep 100ms, send 1, sleep 200ms, send \r.
```
- Some servers may not support sending password continuously. Then you need to configure `ExpectPassSleep`, which is `no` by default, and can be configured as `each` or `enter`:
- Configuring `ExpectPassSleep each` will sleep for a short period of time for each character send, the default is 100 milliseconds, and you can configure `ExpectSleepMS` to adjust it.
- Configuring `ExpectPassSleep enter` will only sleep for a short period of time before `\r` send, the default is 100 milliseconds, and you can configure `ExpectSleepMS` to adjust it.
- If you don’t know how to configure `ExpectPattern2`, you can first configure `ExpectCount` to `2`, then use `tssh --debug` to log in, you will see the output captured by `expect`, and you can directly copy the last part of the output to configure `ExpectPattern2`. Replacing `2` with any other number will also work.
### Remember Password
- It is recommended to use public key authentication to log in. Please refer to openssh documentation.
- If you can only log in with a password, it is recommended to at least set the permissions of the configuration file:
```sh
chmod 700 ~/.ssh && chmod 600 ~/.ssh/password ~/.ssh/config
```
- The passwords configured below for `test1` and `test2` are `123456`, and the passwords for other aliases starting with `test` are `111111`:
```
# If configured in ~/.ssh/config, you can add `#!!` prefix to be compatible with openssh.
Host test1
# The following ciphertext was generated by encoding `123456` with `tssh --enc-secret`.
#!! encPassword 756b17766f45bdc44c37f811db9990b0880318d5f00f6531b15e068ef1fde2666550
# If configured in ~/.ssh/password, there is no need to consider whether it's compatible with openssh.
Host test2
# The following ciphertext was generated by encoding `123456` with `tssh --enc-secret`.
encPassword 051a2f0fdc7d0d40794b845967df4c2d05b5eb0f25339021dc4e02a9d7620070654b
# ~/.ssh/config and ~/.ssh/password support wildcards, and tssh will use the first matched value.
# Here we want test2 to use a different password from other test*, so we put test* behind test2.
Host test*
Password 111111 # supports plain text, but it is recommended to encrypt with `tssh --enc-secret`.
```
- If you are still prompted to enter password after remembering password, it may be need to [remember answers](#remember-answers). Try configuring `encQuestionAnswer1`:
```
Host test1
# The following ciphertext was generated by encoding `123456` with `tssh --enc-secret`.
#!! encQuestionAnswer1 756b17766f45bdc44c37f811db9990b0880318d5f00f6531b15e068ef1fde2666550
```
- - If `ControlMaster` multiplexing is enabled, or in older versions of the `Warp` terminal, you will need to use the `Automated Interaction` mentioned earlier to achieve remembering password. Please refer to the earlier `Automated Interaction` section, simply add a `Ctrl` prefix as follows:
```
Host ctrl
#!! CtrlExpectCount 1 # Configure the number of automated interactions, typically only requires entering the password once
#!! CtrlExpectPattern1 *assword # Configure the matching expression for the password prompt
#!! CtrlExpectSendPass1 d7983b... # Configure the password encoded by `tssh --enc-secret`
```
- Support remember `Passphrase` for private keys ( It's recommended to use `ssh-agent` ). Support configuring `Passphrase` together with `IdentityFile`. Support configuring `Passphrase` using private key filename instead of host alias. For example:
```
# Configuring Passphrase together with IdentityFile. Add `#!!` prefix to be compatible with openssh.
Host test1
IdentityFile /path/to/id_rsa
# The following ciphertext was generated by encoding `123456` with `tssh --enc-secret`.
#!! encPassphrase 6f419911555b0cdc84549ae791ef69f654118d734bb4351de7e83163726ef46d176a
# Configure the Passphrase corresponding to the private key ~/.ssh/id_ed25519 in ~/.ssh/config
# The wildcard * can be added to prevent the filename from appearing in the tssh server list.
Host id_ed25519*
# The following ciphertext was generated by encoding `111111` with `tssh --enc-secret`.
#!! encPassphrase 3a929328f2ab1be0ba3fccf29e8125f8e2dac6dab73c946605cf0bb8060b05f02a68
# If configured in ~/.ssh/password, the wildcard * is not required and will not appear in the server list.
Host id_rsa
Passphrase 111111 # supports plain text, but it is recommended to encrypt with `tssh --enc-secret`.
```
- Still ask for password after `Remember Password`? Maybe it's `keyboard interactive authentication`, please refer to `Remember Answers` below.
### Remember Answers
- In addition, there is a keyboard interactive authentication. The server returns some questions, and log in by providing the correct answers. Many custom one-time passwords are implemented by it.
- For those with one question and a fixed answer, just configure `QuestionAnswer1`. For those with multiple questions, the answer to each question can be configured by serial number, or by the hex code of the question.
- Login with `tssh --debug`, the hex code of the questions will be output, so that you will know how to configure with the hex code. For example:
```
# If configured in ~/.ssh/config, add `#!!` prefix to be compatible with openssh.
Host test1
# The following ciphertext was generated by encoding `TheAnswer1` with `tssh --enc-secret`.
encQuestionAnswer1 4f6b79d0e4e48fc56ee29c61bd19559a322cd07f7d27f2a7f33978671be1b522d549252b22ee
Host test2
# The following ciphertext was generated by encoding `TheAnswer1` with `tssh --enc-secret`.
encQuestionAnswer1 09d6936c104f7bbd62e3b4dc43d746496a368776b85d37b1ce8cecc2ace1b920af0ca5a1812b
QuestionAnswer2 TheAnswer2 # supports plain text, but it is recommended to encrypt with `tssh --enc-secret`.
QuestionAnswer3 TheAnswer3
Host test3
# The `6e616d653a20` is the hex code of `name: `, the `enc` prefix indicates that it's ciphertext.
# The following ciphertext was generated by encoding `my_name` with `tssh --enc-secret`.
enc6e616d653a20 775f2523ab747384e1661aba7779011cb754b73f2e947672c7fd109607b801d70902d1
636f64653a20 my_code # The `636f64653a20` is the hex code of `code: `, `my_code` is plain answer.
```
- For `totp` 2FA code, you can configure them as follows (configure by serial number or hex code of the question):
```
Host totp
TotpSecret1 xxxxx # Configure the secret (plain text) of totp by serial number
totp636f64653a20 xxxxx # Configure the secret of totp by the hex code of the question `code: ` that is `636f64653a20`
# The following ciphertext was generated by encoding the secret of totp with `tssh --enc-secret`. Add the `enc` prefix for configuration.
encTotpSecret2 8ba828bd54ff694bc8c4619f802b5bed73232e60a680bbac05ba5626269a81a00b
enctotp636f64653a20 8ba828bd54ff694bc8c4619f802b5bed73232e60a680bbac05ba5626269a81a00b
```
- For one-time password that can be obtained by the command line, you can configure them as follows (configure by serial number or hex code of the question):
```
Host otp
OtpCommand1 oathtool --totp -b xxxxx # Configure the command line to obtain the one-time password by serial number
otp636f64653a20 oathtool --totp -b xxxxx # Configure the command line by the hex code of the question `code: ` that is `636f64653a20`
# The following ciphertext was generated by encoding `oathtool --totp -b xxxxx` with `tssh --enc-secret`. Add the `enc` prefix for configuration.
encOtpCommand2 77b4ce85d087b39909e563efb165659b22b9ea700a537f1258bdf56ce6fdd6ea70bc7591ea5c01918537a65433133bc0bd5ed3e4
encotp636f64653a20 77b4ce85d087b39909e563efb165659b22b9ea700a537f1258bdf56ce6fdd6ea70bc7591ea5c01918537a65433133bc0bd5ed3e4
```
- You can write a program to obtain the one-time password. Specify the `%q` argument if you want to get the question. Just output the one-time password to stdout and exit with 0, and the debugging information can be output to stderr (you can see it when running `tssh --debug`). Configuration example (the serial number represents the number of questions, generally there is only one question, just configure `OtpCommand1`):
```
Host custom_otp_command
#!! OtpCommand1 /path/to/your_own_program %q
#!! OtpCommand2 python C:\your_python_code.py %q
```
- If `ControlMaster` multiplexing is enabled, or in older versions of the `Warp` terminal, you will need to use the `Automated Interaction` mentioned earlier to achieve remembering answers.
```
Host ctrl_totp
#!! CtrlExpectCount 1 # Configure the number of automated interactions
#!! CtrlExpectPattern1 code: # Configure the matching expression for the password prompt (totp 2FA)
#!! CtrlExpectSendTotp1 xxxxx # Configure the secret (plain text) of totp, generally obtained by scanning the QR code
#!! CtrlExpectSendEncTotp1 622ada31cf... # Or configure the encrypted secret of totp encoded using `tssh --enc-secret`
Host ctrl_otp
#!! CtrlExpectCount 1 # Configure the number of automated interactions
#!! CtrlExpectPattern1 token: # Configure the matching expression for the password prompt (one-time password)
#!! CtrlExpectSendOtp1 oathtool --totp -b xxxxx # Configure the command line to obtain the one-time password
#!! CtrlExpectSendEncOtp1 77b4ce85d0... # Or configure the encrypted command line encoded using `tssh --enc-secret`
```
### Custom Configuration
- The following custom configurations are supported in `$XDG_CONFIG_HOME/tssh/tssh.conf` ( or `~/.tssh.conf`, `C:\Users\your_name\.tssh.conf` on Windows):
```
# SSH configuration path, the default is ~/.ssh/config
ConfigPath = ~/.ssh/config
# Extended configuration path, the default is ~/.ssh/password
ExConfigPath = ~/.ssh/password
# The default path of the file dialog for trz uploading, the default is empty which opening the last path.
DefaultUploadPath = ~/Downloads
# The automatically save path for tsz downloading, the default is empty which poping up a folder dialog.
DefaultDownloadPath = ~/Downloads
# The global drag file upload command, note that the priority configured in ~/.ssh/config is higher.
DragFileUploadCommand = trz -y
# The trzsz progress bar will gradient from the first color to the second color. Don't include `#`.
ProgressColorPair = B14FFF 00FFA3
# When searching and selecting servers with tssh, the theme and colors.
PromptThemeLayout = simple
PromptThemeColors = {"active_host": "magenta|bold", "inactive_host": "magenta"}
# When searching and selecting servers with tssh, the number of records displayed on each page, the default is 10.
PromptPageSize = 10
# When searching and selecting servers with tssh, default is normal mode similar to vim. Configure to search mode as follows:
PromptDefaultMode = search
# When searching and selecting servers with tssh, the items displayed in details. The default is as follows:
PromptDetailItems = Alias Host Port User GroupLabels IdentityFile ProxyCommand ProxyJump RemoteCommand UdpMode TsshdPath
# When searching and selecting servers with tssh, you can customize the cursor and selected icon:
PromptCursorIcon = 🧨
PromptSelectedIcon = 🍺
# Auto set terminal title after login. It will not be reset after exiting. Please set PROMPT_COMMAND in local shell.
SetTerminalTitle = Yes
```
### Comments of Config
- The comments in the `tssh` configuration are basically the same as `openssh`, with some additional extended support, see the following table for details:
| Comments | openssh | tssh |
| :-------------------- | :----------: | :-----------: |
| Starting with `#` | Is a comment | Is a comment |
| Starting with `#!!` | Is a comment | Not a comment |
| `Key Value # Comment` | It depends | Is a comment |
| `Key=Value # Comment` | It depends | Not a comment |
- Configuration starting with `#` are always considered by `openssh` to be a comment; `tssh` considers configuration starting with `#!!` not to be a comment, and other configurations starting with `#` are comments.
- `Key Value # Comment` configuration (without `=` sign), `openssh` considers the content after `#` to be a comment in some cases, and considers it not to be a comment in some other cases; `tssh` always considers the content after `#` to be a comment.
- `Key=Value # Comment` configuration (with `=` sign), `openssh` considers the content after `#` to be a comment in some cases, and considers it not to be a comment in some other cases; `tssh` always considers the content after `#` not to be a comment.
### Wayland Integration
- In the `~/.ssh/config` or `ExConfigPath` configuration file, configure `EnableWaypipe` to `Yes` to enable the Wayland (waypipe) integration feature.
```
Host xxx
# If configured in ~/.ssh/config, add `#!!` prefix to be compatible with openssh.
EnableWaypipe Yes
```
- Once Wayland (waypipe) integration is enabled, there is no need to explicitly use the waypipe program any more, tssh will automatically run the waypipe program in the background.
- If the waypipe program cannot be found in the PATH on the client-side, you can specify the path to the waypipe program using the `WaypipeClientPath` configuration.
- If the waypipe program cannot be found in the PATH on the server-side, you can specify the path to the waypipe program using the `WaypipeServerPath` configuration.
- You can configure certain options for the waypipe program using `WaypipeClientOption` and `WaypipeServerOption` as needed. Note that you should not specify the options `-s`, `--socket`, `--login-shell`, `--display`, `client`, or `server`. Configuration example:
```
Host xxx
#!! EnableWaypipe Yes
#!! WaypipeClientPath /usr/bin/waypipe
#!! WaypipeServerPath /usr/bin/waypipe
#!! WaypipeClientOption -c lz4
#!! WaypipeServerOption -c lz4
```
### Clipboard Integration
- In the `~/.ssh/config` or `ExConfigPath` configuration file, configure `EnableOSC52` to `Yes` to enable the clipboard integration feature.
```
Host *
# If configured in ~/.ssh/config, add `#!!` prefix to be compatible with openssh.
EnableOSC52 Yes
```
- Clipboard integration allows remote servers to write to the local clipboard via OSC52 sequences.
- On Linux, clipboard integration requires `xclip` or `xsel` command to be installed.
### SSH Console
- The `tssh` console is similar to OpenSSH escape sequences, and is planned to provide more user-friendly and powerful SSH control features. Currently supported features include:
- Send the escape character '~' ( ~ : equivalent to typing `~`, can be used as a remedy after accidentally triggering the console).
- Suspend the current SSH process ( ^Z : equivalent to `Ctrl + Z`, but it applies to `tssh` itself, not the process on the remote server).
- Terminate the current SSH session ( . : equivalent to Exit / Kill, can be used to kill the `tssh` process when it freezes due to network issues or other reasons).
- The character between `(` and `:` are shortcuts, compatible with OpenSSH escape sequences. For example, typing `~.` quickly after a newline will quickly terminate the current SSH session.
- The escape character for entering the SSH console can be configured via the `EscapeChar` option (default is `~`). The argument should be a single character, ‘^’ followed by a letter, and it should not conflict with other shortcut keys.
- The `ConsoleEscapeTime` option configures how many seconds after pressing the `Enter` key should the `~` key be pressed to enter the SSH console. The default value is `1` second, which can be configured to `0` to disable the console feature:
```
Host xxx
#!! ConsoleEscapeTime 1
```
### Other Features
- Use `-f` to run in the background, you can add `--reconnect`, it will automatically reconnect when the background process exits.
- Run `tssh --enc-secret`, enter the password or answer, and you can get the ciphertext for configuration (the encryption result for the same password is different each time):
- The `remember password` and `remember answer` mentioned above can be configured as ciphertext by adding `enc` prefix to prevent screen snooping.
- If the password contains special characters such as `#`, you have to configure it with ciphertext.
```
Host server2
# If configured in ~/.ssh/config, add `#!!` prefix to be compatible with openssh.
encPassword de88c4dbdc95d85303682734e2397c4d8dd29bfff09ec53580f31dd40291fc8c7755
encQuestionAnswer1 93956f6e7e9f2aef3af7d6a61f7046dddf14aa4bbd9845dbb836fe3782b62ac0d89f
```
- Run `tssh --new-host` to easily add SSH configuration in the TUI interface, and you can log in immediately after completion.
- Run `tssh --install-trzsz` to install [trzsz](https://github.com/trzsz/trzsz-go) to the server automatically.
- It is installed to the `~/.local/bin/` directory by default. You can specify the installation directory through `--install-path /path/to/install`.
- If the `--install-path` installation directory contains `~/`, single quotes must be added, such as `--install-path '~/path'`.
- If obtaining the latest version of `trzsz` fails, you can specify it through `--trzsz-version x.x.x`.
- If downloading the `trzsz` installation package fails, you can download and specify it through `--trzsz-bin-path /path/to/trzsz.tar.gz`.
- Note: `--install-trzsz` does not support Windows server, and does not support jump server (unless using `ProxyJump`).
- Run `tssh --install-tsshd` to install [tsshd](https://github.com/trzsz/tsshd) to the server automatically.
- It is installed to the `~/.local/bin/` directory by default. You can specify the installation directory through `--install-path /path/to/install`.
- If the `--install-path` installation directory contains `~/`, single quotes must be added, such as `--install-path '~/path'`.
- If obtaining the latest version of `tsshd` fails, you can specify it through `--tsshd-version x.x.x`.
- If downloading the `tsshd` installation package fails, you can download and specify it through `--tsshd-bin-path /path/to/tsshd.tar.gz`.
- Note: `--install-tsshd` does not support Windows server, and does not support jump server (unless using `ProxyJump`).
- About changing the terminal title, it can be achieved without `tssh`. It only needs to be configured in the server's shell configuration file (such as `~/.bashrc`):
```sh
# Set fixed server title
PROMPT_COMMAND='echo -ne "\033]0;Fixed server title\007"'
# Dynamically changing title based on environment variables
PROMPT_COMMAND='echo -ne "\033]0;${USER}@${HOSTNAME}: ${PWD}\007"'
```
- If `SetTerminalTitle = Yes` is set in `$XDG_CONFIG_HOME/tssh/tssh.conf` ( or `~/.tssh.conf` ), the terminal title is automatically set after login, but `PROMPT_COMMAND` on the server overrides the title set by `tssh`.
- `tssh` does not reset to the original title after exiting, you need to set `PROMPT_COMMAND` in the local shell so that it overrides the title set by `tssh`.
- DNS SRV: Say you have a home network with multiple hosts, but you only have one external IP address. Set up SRV records as follows, and make similar configurations in `~/.ssh/config`:
```sh
$ dig +short _ssh._tcp.myhost.mydomain.com SRV
1 1 22029 gateway.mydomain.com.
```
```
Host xxx
#!! DnsSrvName myhost.mydomain.com
```
### UDP Mode
- Install [tsshd](https://github.com/trzsz/tsshd?tab=readme-ov-file#installation) on the server, use `tssh --udp xxx` to log in (latency-sensitive users can specify `--kcp` option), or configure as follows in `~/.ssh/config` to omit `--udp` or `--kcp` option:
```
Host xxx
#!! UdpMode Yes/QUIC/KCP
```
- The `tssh` plays the role of `ssh` on the client side, and the `tsshd` plays the role of `sshd` on the server side.
- The `tssh` will first login to the server normally as an ssh client, and then run a new `tsshd` process on the server.
- The `tsshd` process listens on a random udp port between 61001 and 61999 (can be customized by `TsshdPort`), and sends its port number and some secret keys back to the `tssh` process over the ssh channel. The ssh connection is then shut down, and the `tssh` process communicates with the `tsshd` process over udp.
### UDP Configurations
```
Host xxx
#!! UdpMode Yes
#!! TsshdPort 61001-61999
#!! TsshdPath ~/go/bin/tsshd
#!! UdpAliveTimeout 86400
#!! UdpHeartbeatTimeout 3
#!! UdpReconnectTimeout 15
#!! ShowNotificationOnTop yes
#!! ShowFullNotifications yes
#!! UdpProxyMode UDP
```
- `UdpMode`: `No` (the default: tssh works in TCP mode), `Yes` (default protocol: `QUIC`), `QUIC` ([QUIC](https://github.com/quic-go/quic-go) protocol: faster speed), `KCP` ([KCP](https://github.com/xtaci/kcp-go) protocol: lower latency).
- `TsshdPort`: Specifies the port range that tsshd listens on, default is [61001, 61999]. You can specify multiple discrete ports (e.g., `6022,7022`) or multiple discrete ranges (e.g., `8010-8020,9020-9030,10080`); tsshd will randomly choose an available port. You can also specify the port on the command line using `--tsshd-port`.
- `TsshdPath`: Specifies the path to the tsshd binary on the server, lookup in $PATH if not configured. You can also specify the path on the command line using `--tsshd-path`.
- `UdpAliveTimeout`: If the disconnection lasts longer than `UdpAliveTimeout` in seconds, tssh and tsshd will both exit, and no longer support reconnection. The default is 86400 seconds.
- `UdpHeartbeatTimeout`: If the disconnection lasts longer than `UdpHeartbeatTimeout` in seconds, tssh will try to reconnect to the server by a new path. The default is 3 seconds.
- `UdpReconnectTimeout`: If the disconnection lasts longer than `UdpReconnectTimeout` in seconds, tssh will display a notification indicating that the connection has been lost. The default is 15 seconds.
- `ShowNotificationOnTop`: Whether the connection loss notification is displayed on the top. The default is yes, which may overwrite some of the previous output. Set it to `No` to display notifications on the current line of the cursor.
- `ShowFullNotifications`: Whether to display the full notifications or a brief notification. The default is yes, which may output several lines to the screen. Set it to `No` will output only one line.
- `UdpProxyMode`: The default transport protocol is `UDP`. If `UDP` traffic is blocked by firewalls in your network environment, you can set it to `TCP` to work around the restriction, though this may introduce additional latency.
### Trouble shooting
- In older versions of the Warp terminal, the features like blocks requires renaming `tssh` to `ssh`. It is recommended to create a soft link (friendly for updates):
```
sudo ln -sv $(which tssh) /usr/local/bin/ssh
```
- After the soft link, `ssh -V` should output `trzsz ssh` plus the version number. If not, it means that the soft link is unsuccessful, or `openssh` has a higher priority in `PATH`, and you need to soft link to another path or adjust the priority of `PATH`.
- In order to make `tssh` search login also support the blocks feature, you need to create a `tssh` function in `~/.bash_profile` ( bash ) or `~/.zshrc` ( zsh ):
```sh
tssh() {
if [ $# -eq 0 ]; then
ssh FAKE_DEST_IN_WARP
else
ssh "$@"
fi
}
```
- The `--dragfile` argument may disable the Warp features, please refer to the previous section to configure `EnableDragFile` to enable the drag and drop to upload feature.
- In the Warp terminal, after dragging files and directories into the Warp terminal, the upload may not be triggered immediately. You need to press the `Enter` key once to make it upload.
- If you are using Windows7 or an older version of Windows10, and getting an error `enable virtual terminal failed`.
- Try using `tssh` in [Cygwin](https://www.cygwin.com/), [MSYS2](https://www.msys2.org/) or [Git Bash](https://www.atlassian.com/git/tutorials/git-bash).
- Since `v0.1.21`, the default Windows version no longer supports Windows7, you need to download the version with the `win7` keyword in [Releases](https://github.com/trzsz/trzsz-ssh/releases) to use.
- If the `tssh` specific configuration items are configured in `~/.ssh/config`, and openssh report an error `Bad configuration option`.
- You can add `#!!` prefix to the items, openssh will treat it as a comment, while `tssh` will treat it as one of the valid configurations.
### Contact
Feel free to email the author , or create an [issue](https://github.com/trzsz/trzsz-ssh/issues). Welcome to join the QQ group: 318578930.
### Sponsor
[❤️ Sponsor trzsz ❤️](https://github.com/trzsz), buy the author a drink 🍺 ? Thank you for your support!