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 free software released under GNU General Public
License v2. 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, filters: Struct, order_by: String, order_dir: String, start: Integer, length: Integer) returns connection set: Struct;``

Gets a connections tracked by netfilter_conntrack. filters is a Struct having
variable attributes ;
each attribute name represents a connection field name, and its value is the
value to filter to ; the type of the value is various in function of the
connection field.

 :Integers: mark, timeout, orig_l4proto, orig_ipv4_src, orig_ipv4_dst, orig_port_src, orig_port_dst
 :String: id

"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.

Note: if you want the connection not to be created again just at the next packet
received, you should add the following iptable rule (optionally, same thing in
INPUT and OUTPUT chains)::

  iptables -A FORWARD -p tcp -m state --state NEW ! --syn -j DROP

"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 32-bit 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 32-bit unsigned integer.

"refresh" procedure
------------------

  * prototype: ``refresh(session_id: String) returns nothing;``

Refresh the connection tracking table.

"set_autorefresh" procedure
------------------

  * prototype: ``set_autorefresh(session_id: String, refresh: Integer) returns nothing;``

Enable or disable the auto refreshing of the connection tracking table.

