pyctd, the PYthon ConnTrack Daemon
==================================

 * Version : please run ``pyctd.py --version``
 * Contact : Pyctd Development Team <pyctd-dev AT inl.fr>
 * Website : http://software.inl.fr/trac/trac.cgi/wiki/pyctd

This program aims at serving Netfilter connection tracking through a
network via an XML-RPC server.

Presently, a frontend in PHP is available, see :
http://software.inl.fr/trac/trac.cgi/wiki/pyctd/frontends/php

License agreements
------------------

pyctd is a free software released under GNU General Public
License. Please see COPYING file for further informations.

Installation manual
-------------------

See INSTALL file.

Contribute
----------

Contributors are welcome. You may find some available tasks in TODO
file. If you want to implement one of them, please contact us, we
can create you a Trac account.


Security
========

Server security
---------------

XML-RPC server is based on the SimpleHTTPServer from Python's standard
library, so there is no waranty about security of this server. That's
why we strongly recommands to keep it listening to localhost only and
use Apache's mod_redirect to proxify it to the network. See
apache-site.template for an example.

Authentication security
-----------------------

If you applied what written above, you can configure Apache to manage
authentication. If done, you can give no ``mod_auth`` argument, but you
will still have to call the ``login`` procedure in order to get a
session ID. In that case arguments passed with ``login`` procedure has
no importance (so you can give no argument).

Otherwise, we strongly recommand you to give a ``mod_auth``
argument. This argument is a module containing an ``authenticate`` function
returning a boolean value and having the arguments passed with ``login``
remote procedure. A module ``auth_sha.py`` is provided with pyctd to
manage a password file encrypted with SHA hashing. To use it, you must
edit the script to set the module attribute ``PASSWD_FILE``. Then, you
have to add user/passwd by running the script itself::

  python auth_sha.py username passord

To remove access for a user/passwd, you just have to delete the
appropriate line in the passord file.

Available features
==================

"login" procedure
-----------------

  * prototype: ``login(mixed arguments) returns session ID : String;``

First procedure to call for authenticating the client. Arguments
depend on authentication backend. If using no modules, it does not
need any argument ; if using ``auth_sha.py``, it requires 2 arguments :
``login(username: String, password: String)``

The procedure returns a ``String`` which represents a session id to give
as a first argument in each future procedure calls. The created
session time out after 10 seconds.

"view" procedure
----------------

  * prototype: ``view(session_id: String) returns connection set : Struct;``

Gets a connections tracked by netfilter_conntrack.

"kill" procedure
----------------

  * prototype: ``kill(session_id: String, connection_ids: Array of Integer) returns nothing;``

Kills all connections identified by an element of
``connection_ids``. Connection IDs are given in the result of ``view``
procedure.

"change" procedure
------------------

  * prototype: ``change(session_id: String, field_name: String, connection_id: Integer, field_value: variable type) returns nothing;``

Changes a connection's field. Presently only 2 fields can be modified :

  * ``field_name="mark"``: Can be set to change the connmark of a
    connection. ``field_value`` must be an unsigned integer.

  * ``field_name="timeout"``: Can be set to change the timeout (in
    seconds) of a connection : timeout becomes fixed for this
    connection ; ``field_value`` must be an unsigned integer.
