= Motivation =

On the Launchpad Yellow squad we've been using Google hangouts to do
pair programming and it's been quite effective.  Unfortunately, sharing
a terminal or editor via the screen sharing mechanism has a few
drawbacks:

 * low-quality video means that only relatively large type is legible

 * laggy video means that the viewer is often waiting to see what the sender is doing/talking about

 * you can't see the person and the work at the same time

 * switching between viewing the work and the person is at the sender's discretion (instead of the viewer) and is not as light weight as would be desired

 * the viewer can not copy text from the shared screen

 * the remote person can only watch, no remote control is available

We've tried using screen to share sessions (see our how to at
https://dev.launchpad.net/yellow/UsingScreen) but the setup was
burdensome:

 * it meant opening up our development machines to ssh connections from the outside, a security concern for some

 * our machines are often on dynamic IPs, behind firewalls or routers and bridging those is irritating

 * it takes so long to set up a new pair that we are often discouraged from trying

We have also considered tmux and byobu but they have similar issues.

To address these issues I began building Termbeamer.

Pros:

 * any terminal size is usable

 * screen updates are nearly instantaneous

 * you can use this with any other communication system (skype, hangouts, mumble, etc.)

 * the viewer can copy text just as with any other terminal session

 * remote control: classical pair programming handoffs are possible

 * optional remote control: security worries are lessened relative to giving a remote user a local login

 * the connection is encrypted and doesn't require either viewer or host machines to be directly accessible from the Internet.

Cons:


 * the only transport currently available is XMPP which most people can use via Google Talk.  The connections are encrypted, but Google could eavesdrop if they were so inclined.

 * terminal sharing only, no graphical applications


= Development =

The Termbeamer project is hosted on Launchpad at
http://launchpad.net/termbeamer.

To get a develop environment set up, install the build dependencies,
check out the source and then run the buildout:

{{{
    % sudo apt-get build-dep termbeamer
    % bzr branch lp:termbeamer
    % python2 bootstrap.py
    % bin/buildout
}}}

You can then run the tests.

{{{
    % bin/test
}}}

Test coverage can be generated:

{{{
    % bin/test --cover=cover
}}}

Or a quick coverage check is available:

{{{
    % ./list-uncovered-source-files
}}}


= News =

2012-06-18: Sections describing development, remote control, and using
saved credentials added.


= Installation =

Termbeamer is packaged for Ubuntu and is available at
https://launchpad.net/~benji/+archive/termbeamer.

You can install it by running

{{{
    % sudo add-apt-repository ppa:benji/termbeamer
    % sudo apt-get update
    % sudo apt-get upgrade
    % sudo apt-get install termbeamer
}}}


== Setup ==

Termbeamer uses XMPP as its transport.  The most easily available XMPP
service is Google's "Talk" chat service.

To use Google Talk with Termbeamer open the GMail UI, search for the
user's name in the chat box and then click "Invite to chat" on the
resulting pop-up.  The other user should also log into Gmail and accept
the chat request.  This only has to be done once.

Note: many people have multiple Google accounts, be sure to authorize
the same accounts that will be used with Termbeamer.


=== Using with Google's two-factor authentication ===

Users of Google's two-factor authentication should create an application
password for Google Talk by following the instructions at
support.google.com/accounts/bin/answer.py?answer=185833.  The generated
password will be the one used when starting Termbeamer.


== Running ==

Once the accounts have been authorized, the server and client can be
started.  Either may be started first.


=== Starting the server ===

To start a terminal session and stream it to someone else, run this
command:

{{{
    % tb --xmpp-user=ME@gmail.com --xmpp-password=MY-PASSWORD --xmpp-send=OTHER-PERSON@gmail.com
}}}

A new window will appear running the user's default shell.  Anything
visible in this terminal will be sent to the other user.  The host and
viewer can be started at any time or restarted at any time without
restarting the other.

It is recommended that a terminal multiplexer like GNU Screen be started
once the new terminal is created to facilitate switching between
multiple shell sessions and editors.

The user hosting the terminal session (but not yet the user viewing the
session) can highlight a point on the screen by control-clicking.  The
clicked point will then be highlighted on the viewer's screen.


=== Starting the client ===

To start viewing someone elses terminal session, run this command:

{{{
    % tb --xmpp-user=ME@gmail.com --xmpp-password=MY-PASSWORD --xmpp-receive=OTHER-PERSON@gmail.com
}}}


=== Saving credentials ===

Typing credentials on the command line is tedious and potentially
insecure (shoulder surfing).  The user name and password can be saved to
disk and are read when not otherwise provided:

{{{
    % tb --create-auth-file --xmpp-user=ME@gmail.com --xmpp-password=MY-PASSWORD
}}}


=== Remote control ===

If the --remote-control switch is provided when starting the server, any
keystrokes typed into the client will be transmitted to the server and
treated as if the local user typed them.  This allows for pair
programming between the local and remote user.