What is NfSen:
=============
NfSen is a graphical WEB based front end for the nfdump netflow tools.
See <http://nfdump.sourceforge.net>

With NfSen, you can:
- Display your netflow data from many sources: Flows, Packets and Bytes.
- Easily navigate through the netflow data.
- Process the netflow data within the specified time span.
- Create history as well as continuous profiles.
- Write your own plug-ins to process and disply netflow data on a regular interval.

NfSen allows you to keep all the convenient advantages of the command 
line using nfdump directly and gives you also a graphical overview over 
your netflow data.

A more detailed documentation is available in the doc directory. 

NfSen is distributed under the BSD license - see BSD-license.txt

The current version is nfsen v1.2

Installation:
-------------

1. Prerequisites:
- PHP and Perl:
  NfSen is written in PHP and Perl and should run on any *NIX system.
  At least Perl 5.6.0 and PHP > 4.1 is required.
- RRD tools
  NfSen requires the RRD tools v1.0.x or > 1.2.11, at least the RRDs Perl Module.
- nfdump tools
  Make sure you have version 1.2.1. It includes a bug fix in nfprofile 
  as well as in nfcapd for working with profiles. You can download nfdump
  from sourceforge nfdump.sourceforge.net.

NfSen v1.2 has a very flexible directory layout. To simplify matters, 
the default layout stores everything but the html pages under BASEDIR. 
However, you may configure NfSen to fit your local needs. 
See the nfsen-dist.conf config file. The netflow data is stored 
under PROFILEDATADIR ( BASEDIR/profiles by default ). So make sure you have 
enough disk space.

To update your current NfSen installation goto point 3.

2. First installation of NfSen:
If you have installed all prerequisites, change to the etc directory and
copy the NfSen config file nfsen-dist.conf to nfsen.conf. Edit nfsen.conf
according your needs and setup. Make sure you have set the right values
for the netflow sources. For any netflow source, make an entry in the 
%sources hash. The comments in nfsen.conf should guide you. When you 
are done, run the install.pl script in the distribution directory:

./install.pl etc/nfsen.conf

Running install.pl will:
- Create the NfSen environment with all required directories.
- Copy the php/html files into HTMLDIR.
- Create the live profile. 
- Prepares the RRD DBs for the live profile.

After the installation, you will find the nfsen.conf file in CONFDIR.

If you have existing netflow data from nfdump, follow these steps:
- cd PROFILEDATADIR/live
- Copy already existing data into the appropriate directory or make
  sure you have a softlink from the source directory to your flows.
- cd BINDIR and rebuild the profile live:
  ./nfsen -r live
Your live profile is now setup with existing data and you can verify your
profile: ./nfsen -l live.
Make sure to disable your current start/stop script, as NfSen will provide
it's own start/stop script to start all nfcapd processes, as well as the
nfsen-run background process. The nfdump cleanup script nfclean.pl isn't 
needed either, as expiring the netflow data is fully integrated into NfSen.

3. Update your current NfSen installation:

To upgrade your current NfSen installation:

   1. Change to the directory where you unpacked NfSen.
   2. If you upgrade from NfSen v1.1, add the missing directory config 
      statemants to your existing nfsen.conf file. To reflect the NfSen v.1.1 
      directory layout, add the following lines after the $HTMLDIR variable:

# Where to install the binaries
$BINDIR="${BASEDIR}/bin";
#
# Where to install the NfSen Perl modules
$LIBEXECDIR="${BASEDIR}/libexec";
#
# Where to install the config files
$CONFDIR="${BASEDIR}/etc";
#
# Var space for NfSen
$VARDIR="${BASEDIR}/var";
# 
# Where to install the docs
$DOCDIR="${HTMLDIR}/doc";
#
# The Profile stat directory, where all information and RRD DBs of the profile are stored
$PROFILESTATDIR="${BASEDIR}/profiles";
#
# The Profile directory, where all netflow data is stored
$PROFILEDATADIR="${BASEDIR}/profiles";
#
# Where go all the backend plugins
$BACKEND_PLUGINDIR="${BASEDIR}/libexeec";
#
# Where go all the frontend plugins
$FRONTEND_PLUGINDIR="${HTMLDIR}/plugins";


   3. If you feel ok with the current directory layout:
      Stop nfsen: BASEDIR/bin/nfsen.rc stop
      goto step 4.

      If you want to rearrage the directory layout:

      * Stop nfsen: BASEDIR/bin/nfsen.rc stop
      * Move/copy directories to the new desired location and change 
        the config to reflect the changes.
      * If you separate the profiles into PROFILESTATDIR and PROFILEDATADIR:
        Copy/move all *rrd *gif files as well as the profile.dat file 
        into the appropriate PROFILESTATDIR/<profilename>
        Copy/move the filter.txt/history_filter.txt file and all source 
        directories to the appropriate PROFILEDATADIR/<profilename>

        Example for profile 'port80':

        cd $BASEDIR/profiles/port80
        mv *rrd *gif profile.dat $PROFILESTATDIR/port80
        mv filter.txt <source1> <source2> ... $PROFILEDATADIR/port80 

		To ease this task, there is a helper script SplitProfiles.sh 
		in the helpers directory in the source tree. Edit the shell
		vars OLDPROFILES, PROFILESTATDIR and PROFILEDATADIR according
		your settings and run the script. It generates the required
		commands. Have a look at them and if you feel ok, pipe the
		output into a shell:

		./SplitProfiles.sh | sh

		or edit the command to fit your needs.

   4. Run:

       ./install.pl <path/to/your/existing/nfsen/etc/nfsen.conf>

   5. Start NfSen:

      BINDIR/nfsen.rc start

This will update your current NfSen installation without affecting your netflow data.
Any time you change anything in the directory layout, rerun the install.pl script and
reload nfsen:

      ./install.pl <path/to/your/nfsen/etc/nfsen.conf>
      BINDIR/nfsen reload

4.  NfSen is now ready to use. 
You may link the start/stop file BASEDIR/bin/nfsen.rc into your appropriate 
rc.d directory. Start NfSen:

BINDIR/nfsen.rc start

Point your web browser to nfsen.php. ( Typically http://yourserver/nfsen/nfsen.php )

NfSen - a rough overview
------------------------

Under the BASEDIR you'll find a few directories:

    BINDIR          contains all executables for NfSen:
                    nfsen        The command line tool to manage your profiles.
                    nfsen.rc     NfSen start/stop script.
                    nfsen-run    The NfSen background daemon.
                    other internally used scripts.
    LIBEXEC         contains various NfSen internal perl modules, as well as the
                    demo plugin demoplugin.pm.
    VARDIR          contains the directories:
                    run          Place for pid files.
                    filters      Directory for NfSen default filters.
    CONFDIR         contains the NfSen config files.
    PROFILESTATDIR  contains all profiles info data, RRD and gif files.
	PROFILEDATADIR  contains all netflow data.

When NfSen is started, a number of nfcapd processes are started, as well 
as the NfSen background daemon nfsen-run, which is responsible for the 
5 minutes periodic updates of NfSen.

What are Profiles?
------------------
Profiles are a specific view on your live netflow data. Every profile
has a profile filter assigned. For example you may be interested in
the port 80 traffic, therefore the filter would be 'tcp and port 80'.
The profile filter may be any filter which is accepted by nfdump.
This profile and all it's profile data is stored in it's own directory 
under BASEDIR/profiles/<profilename>. 

Continuous and history profiles:
A profile may be built from historic data for a certain period of time.
( for example yesterday between 3pm and 6pm ). This profile, when built,
remains static and does neither grow nor expires any data. It's a 
history profile.  History profiles are created from the life profile 
data in the past, and can start as long back as life data is available. 
The profile also ends in the past, at least up to the latest available data.

A continuous profile may start in the past and continues building while
new netflow data becomes available. Continuous profiles may grow in size,
but may also be automatically expired, depending on the disk space used
or by the maximum lifetime of the netflow data.

Profiles are maintained by the command line tool 'nfsen' or by the Web
front-end using the 'stat' tab. See nfsen -h more more information about
the 'nfsen' command line utility.

Working with NfSen.
-------------------
Working with NfSen should be mostly intuitive. See the more detailed 
documentation for more information.
