From: Victor Julien Date: Thu, 4 Oct 2012 12:59:58 +0000 (+0200) Subject: Clean up and update bundled docs X-Git-Tag: suricata-1.4beta2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=63c64ed2cc539194d5c8b15670d7dfd5167c7355;p=thirdparty%2Fsuricata.git Clean up and update bundled docs --- diff --git a/doc/AUTHORS b/doc/AUTHORS index 56a489f7cc..5d50fad25c 100644 --- a/doc/AUTHORS +++ b/doc/AUTHORS @@ -1,3 +1,6 @@ -Victor Julien -William Metcalf +Team: +http://suricata-ids.org/about/team/ + +All contributors: +https://www.ohloh.net/p/suricata-engine/contributors/summary diff --git a/doc/INSTALL b/doc/INSTALL index 886e34b9ec..cb7f513c3d 100644 --- a/doc/INSTALL +++ b/doc/INSTALL @@ -11,541 +11,4 @@ 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. - - 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. - - 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. - - 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. - - 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. - - 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 if you have libraries in a - nonstandard directory - LIBS libraries to pass to the linker, e.g. -l - CPPFLAGS C/C++/Objective C preprocessor flags, e.g. -I if - you have headers in a nonstandard directory - 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. - diff --git a/doc/NEWS b/doc/NEWS index e69de29bb2..e0de71b432 100644 --- a/doc/NEWS +++ b/doc/NEWS @@ -0,0 +1,2 @@ +http://suricata-ids.org/news/ + diff --git a/doc/TODO b/doc/TODO index 751a32bf7f..1b198e7795 100644 --- a/doc/TODO +++ b/doc/TODO @@ -1,26 +1,4 @@ -DETECTION ENGINE: -- implement flow as a prefilter -- implement protocol as a prefilter -- implement src ports as prefilters -- do a sort-insert for the temp address lists: sort it big to small to speed up later inserts: partly done -- deal with icmp & icmpv6 sigs -- ip only sigs only need to be checked once per flow direction, so put flags in packet to deal with that -- store a ptr to the rule group in the flow (the src,dst,sp,dp,proto will never change in a flow, so we can use that as a starting point) +Plenty, and you're welcome to help! -WU-MANBER: - -ADDRESSES: -- support [1.2.3.4,2.3.4.5] notation: unittest - -MAIN: -- move packet preallocation into it's own function -- create a cleanup function -- consider a api for per module init/deinit functions per packet, for example to clean up flowvars & http_uri - -THREADING -- Add pre-threading initialization API e.g. for Sig loading on Detect. -- Add post-threading deinitialization API - -CUSTOM LOGGING: -- idea: add a logging module that can be told to output things based on flowvars +http://suricata-ids.org/participate/