TUTORIAL

   1 $Id: TUTORIAL,v 1.3 2003-08-17 11:40:52 arjen Exp $
   2
   3         Tutorial for GnuCoMo
   4
   5
   6         What is GnuCoMo
   7
   8 The aim of the GnuCoMo (GNU COmputer MOnitoring) project is to build a
   9 set of applications that will help administrators to monitor networks as
  10 a whole for errors, attacks and security-breaches in a very user-friendly
  11 way. It is free (GPL) software, sources are available and you are free
  12 to modify it to suit your needs.
  13
  14 GnuCoMo collects system and application logfiles from the monitored
  15 systems (this can be computers, routers and other devices) and stores them
  16 in a database. This collected data is further interpreted and analyzed
  17 until reports and alerts are generated. Because GnuCoMo can combine data
  18 from multiple sources and longer timespans than common IDSs it is able
  19 to recognize attacks that previously remained undetected.
  20
  21 [TODO: current status]
  22
  23
  24         About this Document
  25
  26 This document aims to guide you through the installation of GnuCoMo on
  27 a Unix (Linux) workstation. When we have completed the installation this
  28 document will give a quick guided tour through the functionality GnuCoMo
  29 offers. The procedures described here aim at getting the GnuCoMo demo
  30 up and running as quickly as possible and may not be suited for your
  31 production environment. I assume you have some experience with installing
  32 software on your system.
  33
  34 This document is part of the Gnucomo package. Gnucomo is released under
  35 the Gnu General Public License, see the file COPYING.
  36
  37
  38         Reporting Bugs
  39
  40 If you think you have found a bug in GnuCoMo, this tutorial or the
  41 other GnuCoMo documentation, please report it by sending an e-mail to:
  42 bugs@gnucomo.org. Please include in your bug report:
  43  - the GnuCoMo version you've found the bug in
  44  - what you did to provoke the error
  45  - the output (or error message) you got
  46  - (if relevant) which output you expected
  47  - processor type and kernel version you use
  48  - the versions of the packages that gnucomo depends on
  49
  50 [TODO: Check with Brenno over e-mail adress]
  51
  52
  53         Installation
  54
  55 Most of the GnuCoMo installation can be done from an ordinary Unix
  56 account; when you need root rights you will be told so explicitly. It is
  57 however a good idea to create a gnucomo account.
  58
  59
  60         Getting the software
  61
  62 GnuCoMo can be downloaded from the GnuCoMo website
  63 http://www.gnucomo.org/. If you read this file you are likely to have a
  64 copy of GnuCoMo on your system. If you are serious about using GnuCoMo
  65 it would be a good idea to periodicly check the website for updates
  66 and bugfixes.
  67
  68 To be able to install and run GnuCoMo you'll need several other packages:
  69
  70 PostgreSQL
  71         PostgreSQL is the database we use for GnuCoMo. Most
  72         linux distributions provide ready to install packages for
  73         PostgreSQL. We need at least the postgresql, postgresql-server,
  74         postgresql-libs and postgresql-devel packages.
  75         If you want to compile PostgreSQL from source: go to the
  76         PostgreSQL homepage (http://www.postgresql.org/) and download
  77         the sources via one of the ftp sites. We need libpq++ support
  78         for GnuCoMo.
  79         Though we appreciate the performance improvements that the
  80         PostgreSQL 7.3 server provides, we recommend sticking to the
  81         PostgreSQL 7.2 client versions for now; at least until we've
  82         solved the problems with the libpq++ libraries and PostgreSQL 7.3.
  83
  84 libpqxx
  85         The C++ client interface for the PostgreSQL database server
  86         is a separate project, not distributed with PostgreSQL.
  87         This library replaces the old libpq++ library.
  88         The place to find libpqxx is
  89         http://gborg.postgresql.org/project/libpqxx/projdisplay.php
  90         Make sure you install libpqxx in a default library path or
  91         set your LB_LIBRARY_PATH environment variable to include
  92         the directory in which libpqxx is installed. The default
  93         for libpqxx is /usr/local/libpqxx/lib.
  94
  95 PHP
  96         PHP is used as programming language for gcm_deamon. If you
  97         have packages you would want to install at least the php and
  98         php-pgsql packages.
  99         You can get PHP sources and documentation from the PHP website:
 100         http://www.php.net/. If you're compiling yourself, don't forget
 101         to include PostgreSQL support.
 102
 103 libxml2
 104         We use XML for configuration that we can't (or don't want
 105         to) store in the database and for documentation in XMLDOC
 106         format. The libxml2 library usually comes with your linux
 107         system and you would want to install both the libxml2 and
 108         libxml2-devel packages.  The libxml2 sources can be downloaded
 109         via http://xmlsoft.org/downloads.html
 110
 111 AXE
 112         It's not likely that you'll find precompiled AXE packages on
 113         the net, so you'll have to compile from source. Get the AXE
 114         sources from http://www.andromeda.nl/projects/AXE/AXE.html;
 115         you'll need version 0.3 or better.
 116         Instructions on compiling and installing AXE are given later in
 117         this document.
 118
 119
 120 The following packages are optional and provide additional functionality
 121 to GnuCoMo:
 122
 123 GnuPG
 124         Recommended for encryption and signing of data that is transported
 125         over the network. Not used at this moment.
 126
 127 XMLDOC
 128         We use XMLDOC to process our documentation. Download
 129         and installation instructions can be found on
 130         http://www.andromeda.nl/projects/xmldoc/xmldoc.html
 131
 132 Apache
 133         [HELPME: basic instructions]
 134
 135 Python + tkinter
 136         A GUI based configuration tool named MalfisInter (mi) is being
 137         worked upon. This tool is programmed in Python and requires XML
 138         and TkInter support.
 139
 140
 141         Compiling
 142
 143 If you're lucky enough to find precompiled packages for your system and
 144 have root permissions to install them, things are easy for you; otherwise
 145 you would have to compile from source, which takes a bit more time if
 146 you allready have the standard developer tools (C and C++ compilers,
 147 make, (f)lex and yacc or bison) installed. You will need those tools
 148 for GnuCoMo anyway.
 149 Another essential utility is the bzip compressor package; you will need
 150 it to unpack the archives. bzip2 and bunzip2 come standard with Linux,
 151 but may not be available on older Unix distributions. Sources for bzip2
 152 can be found at http://sources.redhat.com/bzip2/.
 153 Most of the packages mentioned in this document come with detailed
 154 compilation and installation instructions and I recommend to read the
 155 README and INSTALL files before compiling and installing them.
 156
 157
 158         Compiling AXE
 159
 160 For compiling AXE you need the X-windows (X11) headers and
 161 libraries. Under Linux you might need to install the XFree86-devel
 162 package, but these headers are usualy available whenever the C compiler
 163 is installed (also on propriatary unixes).
 164 [TODO]
 165
 166
 167         Compiling GnuCoMo
 168
 169 [TODO]
 170
 171
 172         A few notes on PostgreSQL configuration
 173
 174         - PostgreSQL authentication
 175 [TODO]
 176
 177
 178         Creating the database
 179
 180         - start up postgres
 181         - login as postgres administrator and create a postgres user
 182         - createdb
 183         - create.sql
 184
 185
 186         Getting the web interface up and running
 187
 188 The web interface is convenient (optional?)
 189 [TODO]
 190
 191
 192         Performing a test run
 193
 194         - add object id
 195         - gcm_input
 196         - gcm_deamon
 197         - view results
 198
 199         Cleaning up
 200
 201         dropdb
 202         dropuser
 203
 204
 205         And now...
 206
 207 If you like GnuCoMo [TODO]
 208 Report success under Non-Linux [TODO]