README.in

Overview
--------

There was once an AIRT home page at http://www.airt.nl.


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

It depends how you want to install the AIRT system. The easiest way is from
package, but if you read this, you likely want to do something more
elaborate.

For a typical development installation of AIRT (on a personal workstation),
make sure you have a working Apache with PHP and a working PostgreSQL database
server. Then cd to the source directory and type:

$ ./bootstrap

This creates a few scripts and files that the GNU Autoconf system needs. Now
type:

$ ./configure

This by default configures stuff to be dropped in the following places:

/usr/local/bin               CLI things: airt_import, airt_export...
/usr/local/etc/airt          config things: airt.cfg, importqueue.cfg...
/usr/local/lib/man           man pages: airt.1, airt_export.1...
/usr/local/share/airt/php    PHP files to be published on the www.
/usr/local/share/airt/lib    PHP (library) files not to be published on www.
/usr/local/share/doc/airt    Documentation files.

It does not actually drop stuff there. ./configure only creates a bunch of
files with the correct paths filled in, so that you now can type:

$ make

which generates even more files and leaves your source tree littered with
production versions of the code. But still there is nothing installed in the
list of directories above. To do this, you need:

$ make install

which you may also do from one of the lower directories. For example, if you
have modified something in the source/php directory, you only need to
execute "make install" in that directory, as all others have been unchanged.
Especially in the source/etc directory you will not often want to execute
"make install" as this overwrites your own live config files (in
/usr/local/etc/airt) with fresh versions with default values. If you do a
"make install" in the source directory itself, it will recurse down the
tree, so be careful with that given the etc directory.

bootstrap, configure, and make are "safe", they won't touch anything in your
live AIRT installation. "make install" is not safe, it will touch things in
your live AIRT installation, and usually you don't want etc to be touched.

You also need to install the following packages:

$ apt install php-mail php-mail-mime php-mail-mimedecode php-soap

Site customization
------------------

No two incident response teams are the same. AIRT offers a number of local
site customization hooks which can be used to taylor its behaviour for local
circumstances. The hooks that are presently provided are

* site specific ip address classification

  Depending on the setup of a site, simple classification of an IP address
  into a network might not be enough. AIRT offers customization by defining
  a function 

  function custom_categorize($ip, $networkid) {
        return $networkid;
  } 

  The function takes as input the IP address that needs to be categorized
  and the network id in which it is placed by AIRT's built-in categorization
  system. Return the network id in which you want the ip to be categorized.

* site specific ip address details

  After an IP address has been categorized into a network, additional
  detail can be provided by defining this function. Note that it is possible
  to see session variables in this function. A list of settable session
  variables can be found in the documentation tree.

  function search_info($ip, $networkid) {
      return;
  } // search_info

* hooks for "events"

  Use the customfunctions.plib list to add custom event handlers. Event
  handlers take the format

  addEventHandler($eventType, $handlerFunction)

  E.g. to add a local event handler for the creation of a new incident, add
  a line

  addEventHander("newincident", "local_NewIncident");

  Every time a new incident is created, the function local_NewIncident will
  be called, which may take one argument. The argument will contain a
  event-specific string.


Installation manual for packages
--------------------------------

1. Configuring AIRT after installation

    After installing AIRT, a few actions need to be taken.

    Step 1. Create the database referred to in the configuration file. This
    would typically be achieved by changing to the postgres user and giving
    the following commands

        postgres:~% createdb airt
        CREATE DATABASE

    Step 2. Create the database user that is referred to in the configuration
    file. For example,

        postgres:~% createuser airt --no-createdb --no-adduser -P
        CREATE USER

  You will be prompted for a password for the AIRT user. Keep this password
  somewhere handy, as you will need it again.

    Step 3. Edit @ETCDIR@/airt/airt.cfg and set the 
    variables apropriately. Note that the configuration file is a
    regular PHP program, and any PHP construct can be used in it. For example,
    it is possible to move the database password out of the main configuration
    file and move it to its own file by using PHP's require_once operator.

    Step 4 (preferred). Make sure that the airt user has access to the
    database. Edit pg_ident.conf and add a map

    airt-users   www-data   airt

    Also, in pg_hba.conf, make sure that the airt-users have access to the
    database.

    local  airt   airt    ident airt-users

    Step 4 (alternative). If you do not wish to use ident maps, you need to
    use username/password authentication. Since the password will be available
    in plain text in your filesystem, you will need to take precautions.

    Make sure the airt user has access to the database. Edit
    pg_hba.conf. On most systems, that file can be found in /etc/postgresql,
    but your milage may vary.

    Keep in mind that the order of access control rules in pg_hba.conf is
    important. Add the following line after the line which grants the postgres
    user access to all databases:

        local   airt        airt       password

    Step 5. As root, signal postgres to reload the configuration. On most
    installations, this may be achieved by a command similar to 
    /etc/init.d/postgresql restart, however you may have chosen a different
    setup. 

    Debian administrators may use the command:

        root:~# invoke-rc.d postgresql reload

    Step 6. Initialise the database.

    Dont worry if the script outputs ERRORs in the the beginning; this is due
    to the fact that it tries to drop sequences and tables that may not exist
    yet.

    Having psql and gunzip in your PATH, do:

    postgres:~% gunzip -c @AIRT_DOCDIR@/database/airtschema.sql.gz \
            |psql airt airt


    Step 7. Bootstrap the database.

    postgres:~% psql airt airt < \
        @AIRT_DOCDIR@/database/airtbootstrap.sql 

    Step 8. Configure your web server. If you are using Apache, the easiest
    way to do this is to add a symbolic link in your configuration directory
    and include that file.

    Debian administrators can achieve the same by adding a symbolic link
    in /etc/apache/conf.d (or /etc/apache2/conf.d) which leads to
    @ETCDIR@/airt/airt-apache.conf

    Step 9. Confirm that the configuration file is correct. Apache
    administrators do

        root:~# apachectl configtest

    (or apache2ctl, or apache-sslctl, etc)

    Step 10. If everything checks out, reload the apache configuration and you
    should be done. If apache is already running, do

        root:~# /etc/init.d/apache reload

    else do

        root:~# /etc/init.d/apache start

    Step 11. Change the admin password. Point your browser at the machine that
    hosts the application, typically:
    http://your.host.com/airt/
    (mind the trailing slash) and log in with user admin, password admin. On
    the main menu, click Edit settings > Edit users. Then, on the line with
    the admin user, click edit and set a (different) password.


AIRT deinstallation manual for packages
---------------------------------------

Uninstalling AIRT consists of the following steps:

    Step 1: Remove PHP files; generally this may be achieved by 

        root:~# rm -rf /usr/share/airt

    Depending on your packacing policy, this may differ. Debian administrators
    do

        root:~# apt-get remove --purge airt

    Step 2: Remove data files. Generally this may be achieved by

        root:~# rm -rf /var/lib/airt

    Debian administrators can skip this step, as it is taken care of by the
    --purge option to apt-get remove.

    Step 3: Remove the database. This may be achieved by

        postgres:~% psql template1
        Welcome to psql 7.4.6, the PostgreSQL interactive terminal.
        ...

        template1=# drop database airt;
        DROP database

    Step 4: Remove the database user. This may be achieved by

        template1=# drop user airt;
        DROP USER

    Step 5: Update pg_hba.conf. Remove the line which grants access to the
    airt database from pg_hba.conf and signal Postgresql to reload its
    configuration files.


AIRT upgrade manual for packages
--------------------------------

If you upgrade AIRT with a live database in place, the current package
system does *not* automatically perform a database schema upgrade yet. You
need to do this manually. However, we give you a tool to do this.

Each release contains a database schema file which can be used to compare
your current database to what it should be. This file is
@AIRT_DOCDIR@/database/airtschema.sql. At any time, your database should be
consistent with this schema file.

When relevant, a new release contains a database upgrade script to
facilitate your database upgrade. The upgrade scripts are named:
@AIRT_DOCDIR@/database/airtschema-from-PREVREL-to-CURRENTREL.sql
If you run the appropriate script against a database from PREVREL, you will
hopefully end up with a database for CURRENTREL. The development team has
tested these upgrade scripts, but as always it is wise to first make a
backup of your complete AIRT database before running anything out of the
ordinary against it.

Example upgrade session (first backup, then upgrade):

    postgres:~% pg_dump -f /var/tmp/airt-20050607.1.sql airt
    postgres:~% psql airt airt < \
        @AIRT_DOCDIR@/database/airtschema-from-20050607.1-to-20050610.1.sql

Should you see any warnings or errors, please review them carefully. In
many cases, there is no real problem, but for consistency reasons you should
try to fix the offending issues.


Digitally signing outgoing mail with GPG
----------------------------------------

AIRT is able to digitally sign messages using GPG. To enable the feature, edit
the configuration file and uncomment the line which defined the GPG_KEYID.
Replace the keyID with your own key, and set the GPG_HOMEDIR to a directory in
which a keyring can be found containing the key that must be used to signed
messages.

The GPG_HOMEDIR should point to a directory which is owned by www-data.www-data and has permission mode 700. The pubring.gpg and the secring.gpg files which must be present in that directory must be mode 500.

# EOF