========
sshproxy
========

.. Generate an HTML page with "rst2html.py INSTALL > install.html"
.. rst2html.py is part of the docutils software suite.

.. contents:: **Index**
.. sectnum::


Prerequisites
=============

Here is the list of prerequisite software to run **sshproxy**. The versions are
the ones I develop with. It may work with earlier versions, but I can't
guaranty anything.

* `mysql <http://www.mysql.com/>`_ 4.1.14
* `openssh <http://www.openssh.com/>`_ 4.2_p1 (not necessary for the proxy
  alone)
* `python <http://www.python.org/>`_ 2.4.3

  - `pycrypto <http://www.amk.ca/python/code/crypto.html>`_ 2.0 (indirect
    dependency from paramiko)
  - `paramiko <http://www.lag.net/paramiko/>`_ 1.6 (1.7.1+ prefered)
  - `MySQLdb <http://sourceforge.net/projects/mysql-python/>`_ 1.2.0


Install the software
====================

Get the latest version of `sshproxy`_.

.. _`sshproxy`: http://penguin.fr/sshproxy/download.html

Untar the tarball in the directory of your choice::

    $ tar zxvf sshproxy-{version}.tar.gz

Now enter in the sshproxy-{version} directory.

Run the following command::

    # python setup.py install

Note: packages may be provided by your distribution. Please check it first as
it will probably be easier that way.

Setup for the mysql backend
===========================

If you don't intend to use MySQL as a backend, you can skip this section.

Before the first run, you have to initialize the MySQL database::

First create a database for **sshproxy**::
    
    $ mysqladmin create database sshproxy

Then create a user for the **sshproxy** database (be sure to change the
password)::

    $ mysql
    mysql> GRANT USAGE ON * . * TO 'sshproxy'@'localhost' IDENTIFIED BY 'CHANGE_ME' WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0 ;
    mysql> GRANT ALL ON `sshproxy` . * TO 'sshproxy'@'localhost';

Now let's create tables in the database::

    $ mysql sshproxy < misc/mysql_db.sql

You should now be good to go on the next section.

Configuration
=============

It is better to run **sshproxy** as it's own user. **sshproxy** can do it
when you launch it as root, with the --user option.

First create the sshproxy group and user::

    # groupadd sshproxy
    # useradd -g sshproxy -m -d /var/lib/sshproxy sshproxy

If you don't have a root access, you can still run sshproxy as your user,
just omit the --user (-u) option and adapt the --config-dir (-c) in the
next commands.

To configure **sshproxy** before a first run, you need to use the script *sshproxy-setup*::

    # sshproxy-setup -u sshproxy -c /etc/sshproxy

This will display a menu allowing you to tweek the configuration options::

    
    Configure sshproxy
    ==================
    
    Global options
    1. IP address or interface [any]
    2. Port [2242]
    3. Auto-add public key [no]
    4. Public key id string [sshproxy@penguin.fr]
    5. Cipher engine [blowfish]
    6. Blowfish secret passphrase [**********]
    
    Choose backends
    7. ACL database backend type [ini_db]
    8. Client database backend type [ini_db]
    9. Site backend type [ini_db]
    
    Configure backends
    10. File Backend
    
    Plugin options
    11. Select plugins
    
    
    0. Quit
    
    Please make a choice:

Default values should be OK for a first try, using the **ini_db** backend for
both three databases.

:Note: If you want to use the **mysql_db** backend, make sure you already
created the sshproxy database.

When you quit the menu, **sshproxy-setup** will create the necessary
configuration directories and files in */etc/sshproxy* (or *$HOME/.sshproxy*
if you didn't give the --config-dir (-c) option).

The main configuration file is sshproxy.ini. Here is a sample sshproxi.ini::

    [sshproxy]
    bindip =
    port = 2242
    plugin_dir = /usr/lib/sshproxy
    logger_conf = /usr/share/sshproxy/logger.conf
    log_dir = @log
    pkey_id = sshproxy@penguin.fr
    auto_add_key = no
    client_db = ini_db
    acl_db = ini_db
    site_db = ini_db
    plugin_list = ini_db
    cipher_type = blowfish

    [blowfish]
    secret = This should be a valid passphrase

    [client_db.ini]
    file = @client.db

    [acl_db.ini]
    file = @acl.db

    [site_db.ini]
    db_path = @site.db

In this file, there are several sections. The first one, **[sshproxy]** is
the main section, while all the other sections are provided by plugins or
different optional features of the program.

:Note: the **@** sign for a path is replaced by the absolute path to the
configuration directory, ie. */home/sshproxy/.sshproxy/* or */etc/sshproxy/*
on Gentoo default installation.


The next step is to create an admin client user that will be able to create
clients and sites, and edit ACL rules::

    # sshproxy-setup -u sshproxy -c /etc/sshproxy --add-admin admin
    Enter password:
    Enter password (verify):
    Admin admin added.
    #

Now, we're ready to start the proxy daemon **sshproxyd**.


Running the proxy
=================

Start sshproxy by executing the following command::

    # sshproxyd -u sshproxy -c /etc/sshproxy


You can make it start as a daemon with the --daemon option::

    # sshproxyd -u sshproxy -c /etc/sshproxy --daemon
    #


Administering the proxy
=======================

Now you may want to read the `documentation`_ for more information on how to
setup clients and sites. 

.. _`documentation`: http://penguin.fr/sshproxy/wiki/SshProxy/DocV0.5#administering-the-proxy


Mailing lists
=============

If you have any question, you can send it to the `users mailing list`_.
    
.. _`users mailing list`: mailto:sshproxy@penguin.fr

If you have patches, send them to the `development mailing list`_.

.. _`development mailing list`: mailto:sshproxy-dev@penguin.fr



-----------------------------------------------------------------------------

David Guerizec <david@guerizec.net>