Quick Notes:
============

This is a developer release! Do not use in productive environment.
nfdump version snapshot-20070306 or later is required! Do not use 
any other nfdump snapshot!
As of nfdump snapshot-20070306, nfprofile is no longer built by default.
Make sure you have nfdump configured with option --enable-nfprofile

Upgrade is supported only for NfSen v1.2.x. Any NfSen 1.1.x installations should
be upgrdaed in a first step to NfSen 1.2.4.


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 stable version is nfsen v1.2.4
This is a developer snapshot nfsen-snapshot-20070312

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 with PHP socket extension.
- RRD tools
  NfSen requires the RRD tools v1.0.x or > 1.2.11, at least the RRDs Perl Module.
- nfdump tools
  Versions snapshot-20070306 is required! Do not use any other nfdump snapshot!
  Make sure you have nfdump configured with option --enable-nfprofile
  You can download nfdump from sourceforge nfdump.sourceforge.net.

NfSen 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 nfdump start/stop script, as NfSen will provide
it's own start/stop script to start all relevant nfcapd processes, as well as the
nfsend daemon process. The nfdump cleanup script nfclean.pl isn't 
needed any longer, as expiring the netflow data is fully integrated into NfSen.

3. Update your current NfSen installation:
Upgrade is supported only for NfSen v1.2.x. Any NfSen 1.1.x installations should
be upgrdaed in a first step to NfSen 1.2.4.
If you upgrade from any previous NfSen installation, make sure you have
upgraded nfdump to snapshot 20070110 according to this README file. 

To upgrade your current NfSen installation:

   1.  Stop old nfsen, due to nfprofile incompatibilities.
	   ./nfsen.rc stop
   2.  Upgrade nfdump to snapshot-20070306.
	   This update is required!

   3.  Upgrade NfSen:

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

	   This will update your current NfSen installation. and 
       you're done.

       Note: As of snapshot 20060325, NfSen changed the RRD DB layout to enable
       'on the fly' add/delete of netflow sources. This requires to convert all
       RRD DBs from all profiles from old style to new style layout. This is done
       automatically at installation time but will take some time to complete. 
       Do *NOT* interrupt the conversion process at any time or your nfsen 
       installation will be corrupted. Once you upgraded you can not downgrade 
       NfSen to an older version, without copying back the backup files.
       Before upgrading you may backup the original profile stat data:
           cd helpers
           ./mk_backup.sh /path/to/your/profilestatdir /path/to/backupdir
       
   4. If you have plugins installed, check the README.plugins file
      If you have PortTracker installed, you need to update to the PortTracker
      version included in the contrib directory. You need not to rebuild your current
      db files, just rebuild nftrack and replace the plugin files. See the INSTALL
      file.

   5. Start NfSen:

      BINDIR/nfsen.rc start

When updating to a newer snapshot ( > snapshot-20070110 ) the normal update procedure will do:

      ./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 )

Notes on sub directory hierarchy support:
-----------------------------------------
As of snapshot 20060728 nfsen supports the sub directory hierarchy of nfdump. When installing
or upgrading NfSen, the layout is set to '0' ( see nfcapd(1) ), which means no layout. If you
want to make use of any sub hierarchy layout, add '$SUBDIRLAYOUT = <num>;' to the nfsen.conf
file. See nfsen-dist.conf for more information. After changing the layout, run RebuildHierarchy.pl
in $BINDIR to reorganize the data files to the new layout. Changing the layout is possible at 
any other time later on. However, you must run RebuildHierarchy.pl after changing $SUBDIRLAYOUT 
the config file.

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.
                    nfsend       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 nfsend, 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.
