suricata/doc/INSTALL

About
=====
Suricata is a multi-threaded intrusion detection/prevention engine.
engine available from the Open Information Security Foundation 
(http://www.openinfosecfoundation.org).

Suricata and the HTP library are licensed under the GPLv2. A copy of this
license is available in this tarball, or at:
http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt

Up to date installation guides are available online, at:
https://redmine.openinfosecfoundation.org/projects/suricata/wiki/Suricata_Installation

Build Requirements
==================
gcc
make
g++

If building from the git repository you will also need:
automake
autoconf
libtool
pkg-config

Library Requirements
====================
libpcre
libnet 1.1.x
libyaml
libpcap
libnetfilter-queue and libfnetlink (optional for use with 
  ./configure --enable-nfq)
libpthread  (should be part of most glibc's)
libpfring >= 4.0   (optional for use with ./configure --enable-pfring see INSTALL.PF_RING for install instructions)
libcap-ng (used for dropping privileges *linux only)
libz
htp


For Debian/Ubuntu Users
=======================

    sudo apt-get -y install libpcre3 libpcre3-dbg libpcre3-dev \
    build-essential autoconf automake libtool libpcap-dev libnet1-dev \
    libyaml-0-1 libyaml-dev zlib1g zlib1g-dev pkg-config

    #if using ubuntu-8.04 to use prebuilt yaml packages you need to
    uncomment the following two lines in your /etc/apt/sources.list to
    enable hardy-backports.
    #deb http://us.archive.ubuntu.com/ubuntu/ hardy-backports main
    restricted universe multiverse
    #deb-src http://us.archive.ubuntu.com/ubuntu/ hardy-backports main
    restricted universe multiverse

    #if building with IPS capabilities via ./configure --enable-nfq
    sudo apt-get -y install libnetfilter-queue-dev libnetfilter-queue1
    libnfnetlink-dev libnfnetlink0

    ### Libcap-ng Installation (needed for dropping privs)
    wget http://people.redhat.com/sgrubb/libcap-ng/libcap-ng-0.6.4.tar.gz
    tar -xzvf libcap-ng-0.6.4.tar.gz
    cd libcap-ng-0.6.4
    ./configure && make && sudo make install

    ### Suricata:
    wget http://www.openinfosecfoundation.org/download/suricata-current.tar.gz
    tar -xvzf suricata-current.tar.gz
    cd suricata.<version>
    
    If building from git sources:
    bash autogen.sh
    
    #else
    ./configure
    sudo mkdir /var/log/suricata/
    make
    make install



For Fedora Core Users
=====================

    sudo yum -y install libpcap libpcap-devel libnet libnet-devel pcre \
    pcre-devel gcc gcc-c++ automake autoconf libtool make libyaml \
    libyaml-devel zlib zlib-devel pkgconfig

    #if building with IPS capabilities via ./configure --enable-nfq
    sudo yum -y install libnfnetlink libnfnetlink-devel \
    libnetfilter_queue libnetfilter_queue-devel

    ### Libcap-ng Installation (needed for dropping privs)
    wget http://people.redhat.com/sgrubb/libcap-ng/libcap-ng-0.6.4.tar.gz
    tar -xzvf libcap-ng-0.6.4.tar.gz
    cd libcap-ng-0.6.4
    ./configure && make && sudo make install

    ### Suricata:
    #Retrieve and install Suricata
    wget http://www.openinfosecfoundation.org/download/suricata-current.tar.gz
    tar -xvzf suricata-current.tar.gz
    cd suricata.<version>
    
    If building from git sources:
    bash autogen.sh
    
    #else
    ./configure
    sudo mkdir /var/log/suricata/
    make
    make install



For CentOS5 Users
=================

    #You will be required to use the fedora EPEL repository for some 
    packages to enable this repo it is the same for i386 or x86_64
    sudo rpm -Uvh http://download.fedora.redhat.com/pub/epel/5/i386/epel-release-5-4.noarch.rpm

    sudo yum -y install libpcap libpcap-devel libnet libnet-devel pcre \
    pcre-devel gcc automake autoconf libtool make gcc-c++ libyaml \
    libyaml-devel zlib zlib-devel pkgconfig

    #if building with IPS capabilities via ./configure --enable-nfq there
    are no pre-built packages in CentOS base or EPEL for libnfnetlink and
    libnetfilter_queue.
    #If you wish you can use the rpms in the emerging threats CentOS 5
    repo.

    #i386
    sudo rpm -Uvh http://www.emergingthreats.net/emergingrepo/i386/libnetfilter_queue-0.0.15-1.i386.rpm \
    
    http://www.emergingthreats.net/emergingrepo/i386/libnetfilter_queue-devel-0.0.15-1.i386.rpm \
    http://www.emergingthreats.net/emergingrepo/i386/libnfnetlink-0.0.30-1.i386.rpm \
    http://www.emergingthreats.net/emergingrepo/i386/libnfnetlink-devel-0.0.30-1.i386.rpm
    
    #x86_64
    sudo rpm -Uvh http://www.emergingthreats.net/emergingrepo/x86_64/libnetfilter_queue-0.0.15-1.x86_64.rpm \
    http://www.emergingthreats.net/emergingrepo/x86_64/libnetfilter_queue-devel-0.0.15-1.x86_64.rpm \
    http://www.emergingthreats.net/emergingrepo/x86_64/libnfnetlink-0.0.30-1.x86_64.rpm \
    http://www.emergingthreats.net/emergingrepo/x86_64/libnfnetlink-devel-0.0.30-1.x86_64.rpm

    ### Libcap-ng Installation (needed for dropping privs)
    wget http://people.redhat.com/sgrubb/libcap-ng/libcap-ng-0.6.4.tar.gz
    tar -xzvf libcap-ng-0.6.4.tar.gz
    cd libcap-ng-0.6.4
    ./configure && make && sudo make install


    ### Suricata:
    #Retrieve and install Suricata
    wget http://www.openinfosecfoundation.org/download/suricata-current.tar.gz
    tar -xvzf suricata-current.tar.gz
    cd suricata.<version>
    
    If building from git sources:
    bash autogen.sh
    
    #else
    ./configure
    sudo mkdir /var/log/suricata/
    make
    make install



For Mac OS X Users
==================
    # The following instructions has been tested with Snow Leopard, 
    Mac OS X 10.6.1.
    # First of all you need an essential developmnet environment like 
    gcc/make. You can also download and install a set basic set of
    development tools Xcode from
    http://developer.apple.com/technology/xcode.html 
    # You need macports to fetch the depends
    # By default macports place the libraries at /opt/local/lib and
    /opt/local/include. The configuration should take care of this.

    port install autoconf automake gcc44 make libnet11 libpcap pcre \
    libyaml libtool pkgconfig
    export AC_PROG_LIBTOOL=$( which libtool )

    ### Suricata:
    #Retrieve and install Suricata
    wget http://www.openinfosecfoundation.org/download/suricata-current.tar.gz
    tar -xvzf suricata-current.tar.gz
    cd suricata.<version>
    
    If building from git sources:
    bash autogen.sh
    
    #else
    ./configure
    sudo mkdir /var/log/suricata/
    make
    make install


    #If autojunk, or ./configure fail, re export AC_PROG_LIBTOOL and try
    one more time.
    
    

For FreeBSD 8 Users
===================

    pkg_add -r autoconf262 automake19 gcc45 libyaml pcre libtool \
    libnet11 libpcap gmake pkg-config

    ### Suricata:
    #Retrieve and install Suricata
    wget http://www.openinfosecfoundation.org/download/suricata-current.tar.gz
    tar -xvzf suricata-current.tar.gz
    cd suricata.<version>
    
    If building from git sources:
    bash autogen.sh
    
    #else
    ./configure
    sudo mkdir /var/log/suricata/
    make
    make install
    
    
    #additionally FreeBSD 8 has support for zero-copy bpf in libpcap to
    try out this functionality issue the following command and then 
    start,restart the engine.
    
    sysctl net.bpf.zerocopy_enable=1

    #if you would like to build suricata on FreeBSD with IPS capabilities with IPFW via --enable-ipfw.
    You must do the following to enable ipfw and divert socket support before starting the engine
    with -d.

    #edit /etc/rc.conf and add or modify the following lines
    firewall_enable="YES"
    firewall_type="open"

    #edit /boot/loader.conf and add or modify the following lines
    ipfw_load="YES"
    ipfw_nat_load="YES"
    ipdivert_load="YES"
    dummynet_load="YES"
    libalias_load="YES"


Basic Installation
==================


   The details below contain general installation instructions and 
information.  

   As development on the Suricata engine progresses these instructions
will be updated.  

   As an open source project, it is important that you (the users) provide 
feedback that allows OISF to identify and address your needs rapidly.  
Therefore, if you identify any bugs or difficulties in the installation 
process, please forward detailed information to OISF using the following
email address:

bugreports@openinfosecfoundation.org

All submissions will be reviewed, prioritized and addressed for inclusion
in future releases of the Suricata engine and/or this document.


   The configure shell script attempts to determine correct values for
the various system-dependent variables used during the compile process.  
The values identified in this process are used to create a Makefile in 
each directory of the package.  One or more .h files may also be created 
at this time containing required system-dependent definitions.  The files
created are: 
- a shell script config.status, this script can be utilized in 
the future to recreate the current configuration 
- a config.cache file that saves the results of its tests to speed up 
reconfiguring
- and a config.log file that contains compiler output (useful mainly for 
debugging configure)


   If your configuration requires unique actions to compile the package
and/or you significantly modify the configure shell script, please
forward the details of your requirements and/or solution using the
following email address:

bugreports@openinfosecfoundation.org

All submissions will be addressed for inclusion in the next release.  


   If at some point config.cache contains results that are no longer 
required, the cache can be removed and/or edited to eliminate those
results.


   The file configure.in is used to create configure utilizing a 
program called autoconf.  The configure.in file is only required if
you need to change or regenerate configure using a newer version of
autoconf.


General Compile Instructions for this Package are:
==================================================


  1. cd to the directory containing the Suricata package source code and 
     enter ./configure to configure the package for your system.  If 
     using csh on an old version of System V, users might need to enter
     sh ./configure instead to prevent csh from trying to execute
     configure automatically.

     This process (running configure) will take some time.  While this 
     process runs, messages detailing the configuration progress (i.e.
     which features it is checking for, etc...) will be displayed on the
     screen.
 
  2. Type make to compile the package.

  3. Type make install to install the programs and any data files and
     documentation.

  4. The program binaries and object files can be removed from the
     source code directory by typing make clean.


Ruleset and Log File Details
============================


   Once the Suricata engine is compiled and installed, users must define
(or reference) the location that the ruleset is stored.  Suricata is 
compatible with standard Snort rulesets.  A sample standard configuration
file can be found in the Suricata base directory.  This file is called 
'suricata.yaml'.  In this file, configuration details are entered that set
the location for log files, log file and alert formats, and rule variable
definitions.

Network Variables are in the format of 

VARIABLE:"[X.Y.Z.A/NETMASK]"

For example:

The Variable HOME_NET (for a home network with the IP range 
192.168.0.0/16) would be represented as 

HOME_NET:"[192.168.0.0/16]" 


When setting a variable to the value of another variable, the variable 
referenced must be quoted.  For example to set the variable HTTP_SERVERS to HOME_NET, HTTP_SERVERS would be configured as:

HTTP_SERVERS:"$HOME_NET".



Compilers and Options
=====================

   
   Some systems may require unique or unusual options or linking in the 
compile process that the `configure' script is not able to identify
automatically. Users are able to enter initial values for configure
variables by setting them in the environment.  

For Example:
- a Bourne-compatible shell, would require a command line entry as 
displayed below:
     CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure

- systems that have the env program, will utilize the following command
line entry:
     env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure



Compiling For Multiple Architectures
====================================


   The Suricata engine package may be compiled for more than one kind of
computer simultaneously by placing the object files for each architecture
in their own directory.  


To do this, users must use a version of make that supports the `VPATH'
variable, such as GNU make. 

- cd to the directory where the object files and executables are to be
stored and run the `configure script.  configure automatically searches
for the source code in the directory that configure is stored in and in
‘..'.


   If a user is using a make that does not supports the VPATH variable, 
the package can only be compiled for one architecture at a time in the
source code directory.  After completing package installation for one
architecture, make distclean must be executed before reconfiguring for
another architecture.


Installation Names
==================


   By default, make install will install the package's files in
/usr/local/bin, /usr/local/man, etc...  An installation prefix other than
/usr/local can be configured by giving configure the option --prefix=PATH.

   Separate installation prefixes can be configured for 
architecture-specific files and architecture-independent files.  By
entering --exec-prefix=PATH into the configure, the package will use
PATH as the prefix for installing programs and libraries.  Documentation 
and other data files will still use the regular prefix.

   If supported by the package, users can configure programs to be 
installed with an extra prefix or suffix on their names by giving 
configure the option --program-prefix=PREFIX or --program-suffix=SUFFIX.


Configure Options
==================

./configure --help
`configure' configures this package to adapt to many kinds of systems.

Usage: ./configure [OPTION]... [VAR=VALUE]...

To assign environment variables (e.g., CC, CFLAGS...), specify them as
VAR=VALUE.  See below for descriptions of some of the useful variables.

Defaults for the options are specified in brackets.

Configuration:
  -h, --help              display this help and exit
      --help=short        display options specific to this package
      --help=recursive    display the short help of all the included
                          packages
  -V, --version           display version information and exit
  -q, --quiet, --silent   do not print `checking...' messages
      --cache-file=FILE   cache test results in FILE [disabled]
  -C, --config-cache      alias for `--cache-file=config.cache'
  -n, --no-create         do not create output files
      --srcdir=DIR        find the sources in DIR [configure dir or `..']

Installation directories:
  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                          [PREFIX]

By default, `make install' will install all the files in
`/usr/local/bin', `/usr/local/lib' etc.  You can specify
an installation prefix other than `/usr/local' using `--prefix',
for instance `--prefix=$HOME'.

For better control, use the options below.

Fine tuning of the installation directories:
  --bindir=DIR            user executables [EPREFIX/bin]
  --sbindir=DIR           system admin executables [EPREFIX/sbin]
  --libexecdir=DIR        program executables [EPREFIX/libexec]
  --sysconfdir=DIR        read-only single-machine data [PREFIX/etc]
  --sharedstatedir=DIR    modifiable architecture-independent data [PREFIX/com]
  --localstatedir=DIR     modifiable single-machine data [PREFIX/var]
  --libdir=DIR            object code libraries [EPREFIX/lib]
  --includedir=DIR        C header files [PREFIX/include]
  --oldincludedir=DIR     C header files for non-gcc [/usr/include]
  --datarootdir=DIR       read-only arch.-independent data root [PREFIX/share]
  --datadir=DIR           read-only architecture-independent data [DATAROOTDIR]
  --infodir=DIR           info documentation [DATAROOTDIR/info]
  --localedir=DIR         locale-dependent data [DATAROOTDIR/locale]
  --mandir=DIR            man documentation [DATAROOTDIR/man]
  --docdir=DIR            documentation root [DATAROOTDIR/doc/PACKAGE]
  --htmldir=DIR           html documentation [DOCDIR]
  --dvidir=DIR            dvi documentation [DOCDIR]
  --pdfdir=DIR            pdf documentation [DOCDIR]
  --psdir=DIR             ps documentation [DOCDIR]

Program names:
  --program-prefix=PREFIX            prepend PREFIX to installed program names
  --program-suffix=SUFFIX            append SUFFIX to installed program names
  --program-transform-name=PROGRAM   run sed PROGRAM on installed program names

System types:
  --build=BUILD     configure for building on BUILD [guessed]
  --host=HOST       cross-compile to build programs to run on HOST [BUILD]

Optional Features:
  --disable-option-checking  ignore unrecognized --enable/--with options
  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
  --disable-dependency-tracking  speeds up one-time build
  --enable-dependency-tracking   do not reject slow dependency extractors
  --enable-shared[=PKGS]  build shared libraries [default=yes]
  --enable-static[=PKGS]  build static libraries [default=yes]
  --enable-fast-install[=PKGS]
                          optimize for fast installation [default=yes]
  --disable-libtool-lock  avoid locking (might break parallel builds)
  --enable-gccprotect  Detect and use gcc hardening options
  --enable-nfqueue  Enable NFQUEUE support for inline IDP
  --enable-pfring  Enable Native PF_RING support
  --enable-unittests  Enable compilation of the unit tests
  --enable-debug  Enable debug output

Optional Packages:
  --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
  --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
  --with-pic              try to use only PIC/non-PIC objects [default=use
                          both]
  --with-gnu-ld           assume the C compiler uses GNU ld [default=no]
  --with-libpcre-includes=DIR  libpcre include directory
  --with-libpcre-libraries=DIR    libpcre library directory
  --with-libyaml-includes=DIR  libyaml include directory
  --with-libyaml-libraries=DIR    libyaml library directory
  --with-libpthread-includes=DIR  libpthread include directory
  --with-libpthread-libraries=DIR    libpthread library directory
  --with-libnfnetlink-includes=DIR  libnfnetlink include directory
  --with-libnfnetlink-libraries=DIR    libnfnetlink library directory
  --with-libnetfilter_queue-includes=DIR  libnetfilter_queue include directory
  --with-libnetfilter_queue-libraries=DIR    libnetfilter_queue
library directory
  --with-libnet-includes=DIR     libnet include directory
  --with-libnet-libraries=DIR    libnet library directory
  --with-libpfring-includes=DIR  libpfring include directory
  --with-libpfring-libraries=DIR    libpfring library directory
  --with-libpcap-includes=DIR  libpcap include directory
  --with-libpcap-libraries=DIR    libpcap library directory
  --with-libhtp-includes=DIR  libhtp include directory
  --with-libhtp-libraries=DIR    libhtp library directory

Some influential environment variables:
  CC          C compiler command
  CFLAGS      C compiler flags
  LDFLAGS     linker flags, e.g. -L<lib dir> if you have libraries in a
              nonstandard directory <lib dir>
  LIBS        libraries to pass to the linker, e.g. -l<library>
  CPPFLAGS    C/C++/Objective C preprocessor flags, e.g. -I<include dir> if
              you have headers in a nonstandard directory <include dir>
  CPP         C preprocessor

Use these variables to override the choices made by `configure' or to help
it to find libraries and programs with nonstandard names/locations.