Summary of my remote tmux and ssh configuration to benefit from the iterm2-tmux integration, with ssh authentication socket refreshing

00-ssh-tmux-iterm.md

Configuration to use remote tmux over ssh in iterm

This is a compilation of information I found in different postings on the net.

All manual invocation

Basic remote tmux session

tmux can be invoked in command mode using tmux -CC. The simplest way to get a remote tmux session into a window of iterm is to invoke it on the remote host

   local> ssh rmhost
   #...
   rmhost> tmux -CC

This will open a new tmux session in a new iterm window.

Invoke tmux as the command to ssh

To run tmux as the remote command argument to ssh, it need a pseudo-terminal attached. This means invoking ssh with the -t flag:

   local> ssh rmhost -t tmux -CC

Naming the remote session to be able to re-attach

If you want to re-attach to a remote session, you have to know its name. The easisest way to is to create a session with a well known name and re-attach to that session later. For that, we invoke tmux with the command new -A -s tmux-main. The session name is set using the -s flag, the -A flag specifies that new behaves like attach if the session exists. The command is now

   local> ssh rmhost -t tmux -CC new -A -s tmux-main

Setting up a host configuration

The final command we put together above is a much on the fingers if you use it a lot. The solution is either to set up a shell alias or a special Host configuration in your ~./.ssh/config file, as shown below in ssh--config. If you do that, the command to invoke becomes

   local> ssh tmhost

You might want to set up two shorthands, one for normal ssh accesses and one for ssh with tmux.

Automatic ssh-agent socket handling and renewal

The socket of the ssh agent to access the unlocked keys changes with every ssh login. You loose access to your ssh keys when you re-attach to your tmux session. To avoid this, we can link the current authentication socket to a well-known name. We use ~/.ssh/ssh-auth-sock. This link can be set and updated in ~/.ssh/rc, see the ssh--rc example below. To use this name, set the SSH_AUTH_SOCK environment variable in your ~/.tmux.conf file, see the tmux.conf example below.

NB Your global sshd configuration might prohibit the use of the ~/.ssh/rc file. This is controlled by the administrator of the remote host.

NB The ~/.ssh/ssh-auth-sock gets set if it doesn't point to a valid socket. This means it might not point to the authentication socket of the ssh session running your tmux session if you have an earlier, regular ssh session open. If that is the case, the socket connection will be lost the moment you log out from that session.

ssh--config

# This is a fragment of ~/.ssh/config (local)

# regular ssh shorthand for remote host
Host rmhost
HostName remote.host.some.where             ### fix host name
### more ssh options here are needed

# ssh shorthand for remote host with tmux invocation 
Host tmhost
HostName remote.host.some.where             ### fix host name
ForwardAgent yes
RemoteCommand tmux -CC new -A -s tmux-main
RequestTTY yes
### more ssh options here are needed

ssh--rc

#! /bin/bash
# This is ~/.ssh/rc (remote)

# for X11 forwarding - needed, since the rc files hides default behaviour
if read proto cookie && [ -n "$DISPLAY" ]; then
    if [ `echo $DISPLAY | cut -c1-10` = 'localhost:' ]; then
        # X11UseLocalhost=yes
        echo add unix:`echo $DISPLAY | cut -c11-` $proto $cookie
    else
        # X11UseLocalhost=no
        echo add $DISPLAY $proto $cookie
    fi | xauth -q -
fi

# Setup standard ssh socket link
if [ ! -S $HOME/.ssh/ssh_auth_sock -a -S "$SSH_AUTH_SOCK" ]; then
    ln -sf $SSH_AUTH_SOCK ~/.ssh/ssh_auth_sock
fi

tmux.conf

# This is ~/.tmux.conf (remote)
set -g update-environment "DISPLAY SSH_ASKPASS SSH_AGENT_PID SSH_CONNECTION WINDOWID XAUTHORITY"
set-environment -g 'SSH_AUTH_SOCK' $HOME/.ssh/ssh_auth_sock
set -g set-titles on
# not all distros have a tmux terminal type
#set -g default-terminal tmux
set -g default-terminal xterm-color