Michael Torrie's Personal Wiki

On several occasions I've wished for a way to share a terminal in a manner similar to vncviewer's –listen mode. shareterm is a set of scripts that use tmux and socat to do just that. This has several advantages over other methods of sharing a terminal including using ssh:

• remote host operator needs no login information
• minimal software requirements
  • server (remote host receiving the terminal session) needs only python, socat, openssl, an ssl key and cert
  • client (local host sending the terminal session) needs only bash, socat, openssl, tmux, and an optional certificate authority file.
• Host sharing the terminal can be behind a firewall on a private network
• Access to the shared terminal and the computers being worked on can be controlled and monitored by a local admin.

Before I created these scripts, if I needed to assist someone in managing their linux machine I either had to grant them access to one of my computers, or have them grant me access to their computer. In many cases this is not always desirable. On several occasions I've seen folks on IRC tell others who are having problems, “Just give me a login and I'll come in and fix it for you.” Hopefully no one has beent that gullible. But with shareterm, someone could assist another in a more secure manner without any passwords or logins being shared. Any passwords that are needed can be entered by the local user who is sharing the terminal with the remote user. And since everything is running locally and only the “image” of the terminal is being shared, no passwords are ever transmitted, encrypted or otherwise, across the wire.

shareterm works by creating a tmux session, and then connecting the local user's terminal to that session while simultaneously using socat to create a local pty, connecting it to the tmux session, and then connecting the pty to a remote host over an SSL socket. Ahead of time on the remote host, the shareterm-listen.py program is run which uses socat to listen for incoming SSL connections on a port and then connect them to the terminal socat was running in.

This works pretty well but has a couple of downsides and caveats.

• both people connected to the shared tmux session have to have the same terminal type
• the socat pty always defaults to 80×24, so that constrains the size of the shared terminal
• the listening socket on the remote host rarely closes cleanly

Using shareterm is very simple, although you will need an SSL key and certificate (I use xca to generate and manage keys). On the remote host you need to have socat installed, then just run the shareterm-listen.py script:

shareterm-listen.py --key /path/to/key --cert /path/to/cert -p <port number>

The script will then wait for a successful SSL connection on that port, then it will connect the socket directly to the terminal you ran the script in. As noted above, make sure the terminal is at least 80×24, as that's what the size of the terminal being shared will be.

On the machine you want to share a terminal from, just run the shareterm.sh script (provided you are using a self-signed key and don't want to verify it):

shareterm.sh -v <remotehost> <remoteport>

If you have a public CA certificate that was used to sign the SSL key used by shareterm-listen.py, then you would leave off the -v flag and use the CA cert:

shareterm.sh -c /path/to/cacert.crt <remotehost> <remoteport>

Here are the scripts, licensed under the GNU GPLv2:

shareterm-listen.py ( view)

shareterm.sh ( view)