tmate

Installation

tmate is a fork of tmux. tmate and tmux can coexist on the same system.

brew install tmate

sudo apt-get install tmate

sudo dnf install tmate

sudo zypper install tmate

pkg install tmate

pkg_add tmate

emerge -a app-misc/tmate

pacman -S tmate

./autogen.sh && \
./configure  && \
make         && \
make install

Usage

• Once installed, simply launch tmate with tmate.
• Run tmate show-messages in your shell to see tmate's log messages, including the ssh connection string.
• tmate also allow you to share a read-only view of your terminal. The read-only connection string can be retrieved with tmate show-messages.
• tmate uses both ~/.tmux.conf and ~/.tmate.conf configuration files.
• Your mates will be using your tmux config and your key bindings.
• The terminal is forced to 256 colors and UTF-8, so you don't need to pass -2 as you may be used to do with tmux.

Running tmate as a daemon

You can run tmate in headless mode and retrieve the SSH connection strings as follows:

tmate -S /tmp/tmate.sock new-session -d               # Launch tmate in a headless mode
tmate -S /tmp/tmate.sock wait tmate-ready             # Blocks until the SSH connection is established
tmate -S /tmp/tmate.sock display -p '#{tmate_ssh}'    # Prints the SSH connection string
tmate -S /tmp/tmate.sock display -p '#{tmate_ssh_ro}' # Prints the read-only SSH connection string
tmate -S /tmp/tmate.sock display -p '#{tmate_web}'    # Prints the web connection string
tmate -S /tmp/tmate.sock display -p '#{tmate_web_ro}' # Prints the read-only web connection string

Note that it is important to specify a socket (e.g. /tmp/dev.sock) as tmate uses a random socket name by default.

You can think of tmate as a reverse ssh tunnel accessible from anywhere.

Host your own tmate server

The server sources are located at https://github.com/tmate-io/tmate-ssh-server.

You need a Linux distribution as tmate uses Linux-specific features.

tmate also depends on a couple of packages. On Ubuntu, the packages are:
git-core build-essential pkg-config libtool libevent-dev libncurses-dev zlib1g-dev automake libssh-dev cmake ruby

Once all the prerequisites are satisfied, you can install tmate-ssh-server with:

git clone https://github.com/tmate-io/tmate-ssh-server.git && cd tmate-ssh-server
./create_keys.sh # This will generate SSH keys, remember the keys fingerprints.
./autogen.sh && ./configure && make
sudo ./tmate-ssh-server

The usage of tmate-ssh-server is:

tmate-ssh-server [-k keys_dir] [-l logfile] [-p port] [-h host] [-v]

Once your server is running, you must configure the clients to use your custom server.
You may specify your custom options in the ~/.tmate.conf file. Here are the default options:

set -g tmate-server-host "ssh.tmate.io"
set -g tmate-server-port 22
set -g tmate-server-rsa-fingerprint   "SHA256:Hthk2T/M/Ivqfk1YYUn5ijC2Att3+UPzD7Rn72P5VWs"
set -g tmate-server-ecdsa-fingerprint "SHA256:8GmKHYHEJ6n0TEdciHeEGkKOigQfCFuBULdt6vZIhDc"
set -g tmate-identity ""              # Can be specified to use a different SSH key.

If you are interested in fault tolerance, you may setup the tmate-server-host host to resolve to multiple IPs.
The tmate client will try them all, and keep to the most responsive one.
ssh.tmate.io resolves to servers located in San Francisco, New York, London, and Singapore.

Technical Details

Figure 1 depicts the architecture diagram with the different components of the system. The following describes the connection process with its security considerations, the protocol used between the two tmux servers, and the roadmap of tmate.

Connection process

When launching tmate, an ssh connection is established to tmate.io (or your own server) in the background through libssh. The server ssh key signatures are specified upfront and are verified during the DH exchange to prevent man in the middle attacks. The client is authenticated with local ssh keys.

When a connection is established, a 150 bits session token is generated, then a tmux server is spawned in a jail with no file system, with its own PID namespace to isolate the server from other processes, and no user privileges. To allow this, all files required during the tmux server execution are opened before getting jailed. These measures are in place to limit the usefulness of possible exploits targeting the tmux server. The attacker would not be able to access other sessions, ensuring confidentiality.

When a mate connects to tmate.io (or your own server) with the ssh command, the tmux unix socket is looked up on the file system. On lookup failures, a random sleep is performed to prevent timing attacks, otherwise a tmux client is spawned and connected to the remote tmux server.

Figure 1: Simplified Architecture Diagram

Protocol

The local and remote tmux servers communicate with a protocol on top of msgpack, which is gzipped over ssh for network bandwidth efficiency as vim scrolling can generate massive amounts of data.

In order to keep the remote tmux server in sync with the local tmux server, PTY window pane's raw outputs are streamed individually as opposed to synchronizing the entire tmux window. Furthermore, window layouts, status bar changes, and copy mode state are also replicated. Finally, most of the tmux commands (like bind-key) are replicated. This ensures that the key bindings are the same on both side.

The remote client's keystrokes are parsed and the outcome is sent to the local tmux server. This includes tmux commands such as split-window, window pane keystrokes, or window size information.

This protocol ensure portability for future work such as a HTML5 client.

Future work

This project can take many interesting directions.
Here is what I have on the roadmap:

• Improve the headless experience. This is useful for managing a fleet of devices.
• Make the user experience top notch. Please submit bug reports when you see issues.
• Tolerate network failures. Dealing with reconnections and roaming (IP changes) similarly to what Mosh offers.
• Support for read-only clients. This would be easy to do by providing another session token, distinct from the read-write access one.
• Getting low latencies for everyone requires having nodes spread out all over the globe.
• HTML5 client with fullscreen support

Technical paper

A technical draft can be found here [PDF].

Get in touch

If you'd like to get in touch, here are your options:

• Submit bug reports on github: https://github.com/tmate-io/tmate/issues.
• Post a message on Google Groups: https://groups.google.com/group/tmate-io.
• Or send an email to tmate-io@googlegroups.com.
• You can also send me a personal email to tmate@viennot.com.

Enjoy,
Nico