=======================
Nulog v2 : Installation
=======================

Dependencies
------------

Nulog2 depends on the following modules:
    - twisted
    - nevow
    - matplotlib
    - gettext
    - soappy
    - mysqldb
    - cairo
    - python-ipy
    - python-numpy
    - python-docutils

On debian, Nulog2 dependencies can be resolved by running ::

    # aptitude install python2.4 python-twisted python-nevow python-matplotlib gettext \
            python-soappy python-mysqldb python-cairo python-ipy python-numpy python-docutils

SQL Schema
----------

To use NuLog2, you have to use ulogd with netfilter and optionnally NuFW, the authenticating firewall.

The following commands may have to be changed, depending on your MySQL version. They
are just provided as examples.

Create database for NuLog ::

    $ mysql -uroot -prootpassword mysql
    > CREATE DATABASE dbname;

You should also create a user for this database ::

    > GRANT ALL PRIVILEGES ON dbname.* TO user IDENTIFIED BY 'pass';

To create a ulog+nulog SQL schema, go in the /usr/share/doc/nulog/scripts/ directory and run this script ::

    $ cat ipv4.sql | mysql -uuser -ppass dbname

If you have an ipv6 network, and a netfilter version which supports ipt6_ULOG module, you
can run the ipv6.sql script instead of ipv4.sql. You will also need a compatible version of ulogd.

Configure iptables to create rules to log with ULOG.

To get performances, you can use triggers to copy data in other tables
(usersstats, offenders, tcp_ports and udp_ports).
You have to execute script/triggers.py script in your database to
create triggers ::

    $ ./triggers.py | mysql -uuser -ppass dbname

State of log packets
--------------------

There is no formal way to know, by reading the ulog table, if a packet is dropped or not. Nulog's behaviour
is to consider all logged packets were accepted, unless the following condition is met.

In the trigger procedure, Nulog parses the Log Prefix to find a word. If this
word is found, nulog considers the packet to be dropped, and displays it on that status.
If the occurence is not found in the log prefix of a packet, nulog considers the packet has been
accepted, and displays it as such.

It concerns only netfilter rules, while NuFW sets the 'state' column correctly (NuFW has its own INSERT procedures
into the ulog table).

The default word is 'DROP'. You can change it with the '--drop' parameter of the
script.

Installation
------------

To install Nulog2 on your system, run this command ::

    # ./setup.py install

You can build the documentation by running ::

    # make

Now we can configure our knack.

Nulog-core
----------

Enter the /etc/nulog/ directory, copy or rename default.core.conf to core.conf and edit it ::

    # Database configuration
    [DB]
    # Hostname
    host=localhost

    # Database to use
    db=ulog

    # Username
    user=nulog

    # Password
    password=pupuce

    # Type of database
    # - ulog: standard use of database, with ulog.mysql.sql
    # - triggers: get perfs if you use triggers.sql script
    type=triggers

    # IP version used in database
    ip=4

Nulog-web
---------

Now, copy default.nulog.conf to nulog.conf ::

    # Links
    [Links]
    url=http://localhost:8080/nulog/

    [Sessions]
    # Accept anonymous connections.
    anonymous=yes


Wrapper
-------

If you want to launch nulog2 in stand-alone mode,
copy or rename default.wrapper.conf to wrapper.conf and edit it ::

    # Nevow Server configuration
    [server]

    # HTTP server port
    port=8080

    # Directory of nulog datas
    vardir = /var/lib/nucentral/

    # Where wrapper will look for modules
    # Useless if it's a standard installation.
    # modulespath=../

    # List of modules.
    # Only modules with "yes" value will be loaded.
    [modules]
    nulog-core=yes
    nulog-web=yes
    auth=yes

User settings
~~~~~~~~~~~~~

You must launch *scripts/install_defconf.sh* to create user settings
directory, and to install default configuration::

	$ cd scripts/
	$ ./install_defconf.sh

Answer to questions and do not forget to put the path in wrapper.conf.

If you run Nulog in the stand alone mode, you can use user settings only
with a reverse proxy which will authentificate user. (see bellow)

Reverse-proxy
~~~~~~~~~~~~~

    If you want to use a reverse proxy to do an authentification
    on Nulog (because stand alone version doesn't support it, see NuCentral),
    you have to configure your HTTP Server to send a "Nulog_User" HTTP header which
    contains the username.

    Nulog will not check authentification, but will save user's settings in file
    (see 'vardir' variable in wrapper configuration).

    If you use Apache, you could have a configuration like this::

	<VirtualHost *>
		ServerName nulog

		ProxyPreserveHost Off
		ProxyPassReverse /nulog http://localhost:8080/nulog

		<Location /nulog>
			Allow from all

			AuthType Basic
			AuthName nulog
			AuthUserFile /etc/apache2/users
			AuthBasicProvider file
			Require valid-user


			RewriteEngine on
			RewriteCond %{LA-U:REMOTE_USER} (.+)
			RewriteRule /nulog(.*) http://localhost:8080/nulog$1 [P,E=RU:%1]
			RewriteRule /nulog(.*) http://localhost:8080/nulog$1 [P]
			RequestHeader set Nulog_User %{RU}e
			RequestHeader unset Authorization
		</Location>

	</VirtualHost>

Running Nulog
-------------

Now, launch wrapper with ::

    # nulog

To have debug informations, you can run it with ::

    # twistd -noy /usr/sbin/nulog.tac


Running without install
~~~~~~~~~~~~~~~~~~~~~~~

First, link scripts/default.conf in auth/ with this command ::

    $ cd auth
    $ ln -s ../scripts/default.conf default.conf

Note that if you DON'T use NuFW, you can link to scripts/no_users.conf
instead of default.conf, to not show user filtering logging accounts.

Then, to run it locally, simply run ::

    $ twistd -noy nulog.tac

Post-install
------------

Now you can go with your browser to http://localhost:8080/nulog/ (or other configured
server and port) and have fun!
