rubanetra/README.txt

###########################
# Compiling the project   #
###########################
In order to compile this project the following prerequisites must be fulfilled:
    -   Java Development Kit v1.8 must be installed
        (see http://www.oracle.com/technetwork/java/javase/downloads or http://openjdk.java.net/ )
    -   Apache Maven must be installed (see https://maven.apache.org/, version 3.2.3 was used during development).

The compilation process will not execute the provided test cases by default, nevertheless this behaviour
may be changed but additional prerequisites must be fulfilled first, please refer to the README file located in the test
resources directory (usually 'src/test/resources/').

Afterwards, within the projects top level directory (containing the file 'pom.xml') execute:
    $   mvn clean install

This will create the new directory 'target', containing:
    - "rubanetra-0.0.6-distribution.zip"
        This archive represents the final binary project files, including default configuration files ('./conf/'
        and dependencies ('./lib/').
        Use/unpack this archive to install the project on the target machine, however, please refer to the runtime
        requirements listed below first. Ultimately, this archive should contain:
            * "rubanetra-0.0.6.jar"
                The compiled project binary.
            * "rubanetra-0.0.6-(test-)sources.jar"
                This archive contains the projects (test-)source code, including generated (test-)sources
                and default configuration files.
            * "rubanetra-0.0.6-javadoc.jar"
                This archive contains the projects Java documentation.
            * the directory 'lib', which contains all compiled third-party java-dependencies.
            * the directory 'conf', which contains modifiable project specific configuration files.
    - "rubanetra-0.0.6-package.zip"
        This archive contains all sources needed to compile the project from scratch using maven.
        It does not contain any binary dependencies.

#######################
# Running the project #
#######################
In order to run this project it must be ensured that
    -   jNetPcap/libpcap/WinPcap (platform dependent) native libraries are accessible via Java classpath.
    -   the main configuration file (defaults to './conf/rubanetra.conf') is available/accessible and adjusted accordingly.
        The path to this file may alternatively be provided via command line argument '-c').
    -   the Drools configuration folder (defaults to './conf/META-INF') is available/accessible and adjusted accordingly.
        Note that for the current version 0.0.6, the actual Drools configuration folder must be
        named 'META-INF' and contain the file 'kmodule.xml', which represents the Drools knowledge base configuration
        and is looked up/compiled by Drools during runtime. This allows to adjust the Knowledge-Base,
        i.e. rule modifications/additions/deletions before each invocation without the need to compile a separate JAR.
    -   the SLF4J-logback logging configuration file (defaults to './conf/logback.xml') is available/accessible and
        adjusted accordingly.
    -   the project was successfully compiled and Maven was able to resolve all dependencies.
Additionally, it is recommended to compile the Rubanetra binding for the plaso project (http://plaso.kiddaland.net/) as
well, which is currently available at http://gitlab.swerk.priv.at/stefan/plaso-rubanetra.
For compilation instructions please follow the "Developers Guide - How to build plaso from scratch" chapter
at https://github.com/log2timeline/plaso/wiki/Developers-Guide.

The frontend main method for the project may then be invoked from the terminal by executing:
    $   java -jar rubanetra-0.0.6.jar
To provide the native libraries via '/usr/lib':
    $   java -cp /usr/lib -jar rubanetra-0.0.6.jar
To provide a custom configuration directory (e.g. '/etc/rubanetra/conf') and
native libraries via '/usr/lib'(substitute ':' with the underlying system path separator):
    $   java -cp "/etc/rubanetra/conf:/usr/lib" -jar rubanetra-0.0.6.jar

################
# Dependencies #
################
This project utilizes jNetPcap (http://jnetpcap.com/) and therefore libpcap/WinPcap as PCAP-library.
Please follow the installation instructions of the jNetPcap-library (project was compiled with version 1.4.r1425-1d),
especially the native library section and adjust the Java-Classpath accordingly.
As an alternative the required native file classpath may be included in the final jar-Archive manifest by adjusting
the projects 'pom.xml' property section (i.e. 'library.directory' and 'native.lib.classpath' properties) first
and recompiling afterwards.

For a list of all utilized (including transitive) third party libraries refer to file 'THIRD-PARTY.txt'.

########
# Bugs #
########
Please report bugs concerning this project to:
    http://gitlab.swerk.priv.at/stefan/rubanetra/issues

##################################
# Version control / project home #
##################################
The latest version of this project may be obtained via git:
    git clone http://gitlab.swerk.priv.at/stefan/rubanetra.git
or by pointing a browser to:
    http://gitlab.swerk.priv.at/stefan/rubanetra

#########
# Hints #
#########
If a runtime exception like the following
    java.lang.UnsatisfiedLinkError: com.slytechs.library.NativeLibrary.dlopen(Ljava/lang/String;)
is encountered, the JNetPcap-library (Java) was unable to locate the native library in the classpath, i.e.
either the JNetPcap native binding or libpcap is missing (see above).

Special note for Ubuntu 12.04: The package 'libpcap-dev' must be installed.