working with launchpad behind an authenticating proxy

[Denys Duchier]

I have written up some documentation about what I did to make things
work for my students.  Perhaps this could be useful for other people.
Feel free to insert it wherever in the bzr documentation.  Maybe others
can contribute additional case studies.

--Denys

HOWTO: Behind Firewalls and Proxies
===================================

This section is a survival guide for people trying to use ``bzr`` from within
institutions that implement very restrictive network access policies.

Case 1: The University of NothingMuch
-------------------------------------

In the CS department, at the university of er... let's call it NothingMuch, to
protect the guilty, students are taught the principles and practice of VCS, and
are required to use them for their course work and projects.  In particular,
they learn ``bzr`` and are encouraged to use ``launchpad.net`` to host their
projects and practice collaborative development.

Unfortunately (from an ease-of-use perspective), like many institutions, the
university of NothingMuch has become increasingly paranoid about network
security: practically all ports are blocked and students are required to go
through an authenticating proxy for all connections to the web.

Here is how we managed to make the use bzr/launchpad reasonably transparent for
our students.  Students use machines, in the intranet, that are not NAT'ed.
Therefore, they cannot make direct connections to hosts in the internet: they
must go through a gateway/proxy.

Pushing to launchpad requires an ``ssh`` connection. ``ssh`` uses port 22,
which is blocked anyway for good reasons.  The first step is to create a
forwarding proxy for ``ssh``connections from the intranet to launchpad.  The CS
department has a gateway machine called MORDOR that can be accessed from the
student intranet and that can make outgoing ``ssh`` connections to the
internet.  We added the following command to ``/etc/rc.local`` on MORDOR::

  ssh -qNnf -L 2222:bazaar.launchpad.net:22 -oGatewayPorts=yes root at localhost

In this manner, whenever MORDOR boots, it creates a process that
forward-proxies all connections to MORDOR on port 2222 to bazaar.launchpad.net
on port 22.  For this to work, it is necessary (1) for MORDOR to run a ``ssh``
server, (2) for root to have setup cryptographic keys so that an ``ssh``
connection as root from MORDOR to itself requires no password.

We want that, when a student attempts to establish an ssh connection to
``bazaar.launchpad.net``, this goes transparently through MORDOR.  To achieve
this, on each student machine we added the following to
``/etc/ssh/ssh_config``, just before the ``Host *`` section::

  Host bazaar.launchpad.net
  HostName MORDOR
  Port 2222

Why is the forwarding proxy on MORDOR safe from the point of view of network
security?  (1) it only forwards to bazaar.launchpad.net, (2) launchpad does not
permit connections that run anything but the bzr server, (3) it also refuses to
forward ports.  In other words: it is not possible to use launchpad to setup a
security breaking tunnel.

When accessing launchpad, ``bzr`` also needs to make some ``xmlrpc`` requests
(https).  From the student intranet, these requests must go through the
university proxy ``proxy.nothingmuch.fr`` at port 3128.  To make things more
unpleasant, this is an authenticating proxy: whenever a connection is
established to the proxy, the student must provide a username and a password.
As a consequence, any invocation of ``bzr`` that must contact launchpad will
require the student to provide username and password one or more times (some
commands ask 3 times).  This makes the use of ``bzr`` very quickly unbearable.

The solution we have used is to include username and password in the values of
variables ``http_proxy`` and ``https_proxy``.  To make things even more
unpleasant, a student's username is his university email address, which
contains a ``@`` that needs to be encoded as ``%40``.   Let's suppose that
student Bilbo Baggins uses password ``gandalf``, then we instructed him to add
the following definitions to his ``~/.bash_profile``::

  proxyuser='bilbo.baggins%40nothingmuch.fr'
  proxypass=gandalf
  http_proxy=http://$proxyuser:$proxypass@proxy.nothingmuch.fr:3128/
  https_proxy=https://$proxyuser:$proxypass@proxy.nothingmuch.fr:3128/