Synnefo » snf-ganeti

	doc/design-http-server.rst \

   design-http-server.rst

=========================================

Design for replacing Ganeti's HTTP server

=========================================

.. contents:: :depth: 4

.. _http-srv-shortcomings:

Current state and shortcomings

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

The :doc:`new design for import/export <design-impexp2>` depends on an

HTTP server. Ganeti includes a home-grown HTTP server based on Python's

``BaseHTTPServer``. While it served us well so far, it only implements

the very basics of the HTTP protocol. It is, for example, not structured

well enough to support chunked transfers (:rfc:`2616`, section 3.6.1),

which would have some advantages. In addition, it has not been designed

for sending large responses.

In the case of the node daemon the HTTP server can not easily be

separated from the actual backend code and therefore must run as "root".

The RAPI daemon does request parsing in the same process as talking to

the master daemon via LUXI.

Proposed changes

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

The proposal is to start using a full-fledged HTTP server in Ganeti and

to run Ganeti's code as `FastCGI <http://www.fastcgi.com/>`_

applications. Reasons:

- Simplify Ganeti's code by delegating the details of HTTP and SSL to

  another piece of software

- Run HTTP frontend and handler backend as separate processes and users

  (esp. useful for node daemon, but also import/export and Remote API)

- Allows implementation of :ref:`rpc-feedback`

Software choice

+++++++++++++++

Theoretically any server able of speaking FastCGI to a backend process

could be used. However, to keep the number of steps required for setting

up a new cluster at roughly the same level, the implementation will be

geared for one specific HTTP server at the beginning. Support for other

HTTP servers can still be implemented.

After a rough selection of available HTTP servers `lighttpd

<http://www.lighttpd.net/>`_ and `nginx <http://www.nginx.org/>`_ were

the most likely candidates. Both are `widely used`_ and tested.

.. _widely used: http://news.netcraft.com/archives/2011/01/12/

  january-2011-web-server-survey-4.html

Nginx' `original documentation <http://sysoev.ru/nginx/docs/>`_ is in

Russian, translations are `available in a Wiki

<http://wiki.nginx.org/>`_. Nginx does not support old-style CGI

programs.

The author found `lighttpd's documentation

<http://redmine.lighttpd.net/wiki/lighttpd>`_ easier to understand and

was able to configure a test server quickly. This, together with the

support for more technologies, made deciding easier.

With its use as a public-facing web server on a large number of websites

(and possibly more behind proxies), lighttpd should be a safe choice.

Unlike other webservers, such as the Apache HTTP Server, lighttpd's

codebase is of manageable size.

Initially the HTTP server would only be used for import/export

transfers, but its use can be expanded to the Remote API and node

daemon (see :ref:`rpc-feedback`).

To reduce the attack surface, an option will be provided to configure

services (e.g. import/export) to only listen on certain network

interfaces.

.. _rpc-feedback:

RPC feedback

++++++++++++

HTTP/1.1 supports chunked transfers (:rfc:`2616`, section 3.6.1). They

could be used to provide feedback from node daemons to the master,

similar to the feedback from jobs. A good use would be to provide

feedback to the user during long-running operations, e.g. downloading an

instance's data from another cluster.

.. _requirement: http://www.python.org/dev/peps/pep-0333/

  #buffering-and-streaming

WSGI 1.0 (:pep:`333`) includes the following `requirement`_:

  WSGI servers, gateways, and middleware **must not** delay the

  transmission of any block; they **must** either fully transmit the

  block to the client, or guarantee that they will continue transmission

  even while the application is producing its next block

This behaviour was confirmed to work with lighttpd and the

:ref:`flup <http-software-req>` library. FastCGI by itself has no such

guarantee; webservers with buffering might require artificial padding to

force the message to be transmitted.

The node daemon can send JSON-encoded messages back to the master daemon

by separating them using a predefined character (see :ref:`LUXI

<luxi>`). The final message contains the method's result. pycURL passes

each received chunk to the callback set as ``CURLOPT_WRITEFUNCTION``.

Once a message is complete, the master daemon can pass it to a callback

function inside the job, which then decides on what to do (e.g. forward

it as job feedback to the user).

A more detailed design may have to be written before deciding whether to

implement RPC feedback.

.. _http-software-req:

Software requirements

+++++++++++++++++++++

- lighttpd 1.4.24 or above built with OpenSSL support (earlier versions

  `don't support SSL client certificates

  <http://redmine.lighttpd.net/issues/1288>`_)

- `flup <http://trac.saddi.com/flup>`_ for FastCGI

Lighttpd SSL configuration

++++++++++++++++++++++++++

.. highlight:: lighttpd

The following sample shows how to configure SSL with client certificates

in Lighttpd::

  $SERVER["socket"] == ":443" {

    ssl.engine = "enable"

    ssl.pemfile = "server.pem"

    ssl.ca-file = "ca.pem"

    ssl.use-sslv2  = "disable"

    ssl.cipher-list = "HIGH:-DES:-3DES:-EXPORT:-ADH"

    ssl.verifyclient.activate = "enable"

    ssl.verifyclient.enforce = "enable"

    ssl.verifyclient.exportcert = "enable"

    ssl.verifyclient.username = "SSL_CLIENT_S_DN_CN"

  }

.. vim: set textwidth=72 :

.. Local Variables:

.. mode: rst

.. fill-column: 72

.. End: