bsod-server-2.0.3

---------------------------------------------------------------------------
Copyright (c) 2004-2013 The University of Waikato, Hamilton, New Zealand.
All rights reserved.

This code has been developed by the University of Waikato WAND
research group. For further information please see http://www.wand.net.nz/.
---------------------------------------------------------------------------


This directory contains source code for bsod-server, one half of the bsod 
tool for the visualisation of network traffic captured from live interfaces 
or from offline traces. Get the other half, the bsod client from 
http://research.wand.net.nz/.

bsod was written to make use of the libtrace traffic processing library
also developed by the WAND research group. This means that it can 
understand and visualise live traffic capture from devices such as pcap
and DAG interfaces, as well as traces stored in erf and pcap formats.
The bsod server has been tested on and is known to run in Debian GNU/Linux.


It is licensed under the GNU General Public License (GPL) version 2. Please
see the included file GPL for details of this license.

Please read the included INSTALL file for information regarding the
installation of bsod, including required dependencies.

For further information, please contact the WAND group. See
http://www.wand.net.nz/ for details.




Configuring bsod server
----------------------------------
----------------------------------

The default configuration file is "/usr/local/bsod/etc/bsod_server.conf".
You can specify a different file by giving bsod server the command line 
option '-C /path/to/config/file'. Configuration options are pairs of the 
form:

<key> = <value>

A value can be one of three types - string, boolean or integer. All strings are 
enclosed in double quotes, while integers are simply a number. Booleans are
either true or false.

The configuration file can be reloaded on the fly by sending the bsod server
process a SIGUSR1.


KEY		VALUE TYPE
--------------------------
pidfile		string
background	integer
basedir		string
source		string
listenport	integer
client_wait	boolean
filter		string
colour_module	string
colourparam	string
rpos_module	string
rpos_param	string
lpos_module	string
lpos_param	string
dir_module	string
dirparam	string
loop		integer
shownondata	integer
showdata	integer
showcontrol	integer
showresets	integer
shownontcpudp	integer
darknet		boolean
blacklistdir 	string
rttest		boolean
sampling	integer
sendq		integer
left_image	string
right_image	string

option: pidfile		type: string
    The file that the process id (pid) of the bsod server should be written
    to when running.

option: background	type: integer
    Set this to 1 if the bsod server should run in the background (daemonise),
    otherwise set it to 0 to run in the foreground.

option: basedir		type: string
    The directory in which to find the relevant files for running the bsod
    server, including the shared libraries for dynamic loading of layout,
    colour, and direction evaluation schemes. Defaults to "/usr/local/bsod".

option: source		type: string
    A URI for libtrace describing the type and location of the data to be 
    visualised. 
    eg: rtclient:name-of-rt-server:port
	erf:/path/to/erf.trace
	pcap:/path/to/pcap.trace
	pcapint:eth0
    
option: listenport	type: integer
    The port that the server should listen to for incoming connections.
    This is the only config option that is not reparsed when the server is
    restarted via a SIGUSR1. Defaults to 32500.

option: client_wait	type: boolean
    If set to true, the server will not start reading from the input source
    until a client has successfully connected. Useful for replaying trace
    files.

option: filter		type: string
    BPF style filter to apply to the source URI. Works on any URI but is only
    tested on ethernets. Try the tcpdump man page for a handy explanation
    of BPF filters.

option: colour_module	type: string
option: colourparam	type: string
    Specify the shared library that should be loaded to supply the colour
    selection algorithms. Defaults to "plugins/colour/colours.so", which
    uses a port-based colour scheme. If your packet capture retains at least
    four bytes of packet payload, we recommend using the lpicolour module
    instead, as it can identify protocols much more accurately.

    The colourparam option can be used to pass parameters into a colour
    plugin. At present, no colour plugins utilise this option but they may in
    the future.

option: rpos_module	type: string
option: rpos_param	type: string
    Specify the shared library that should be loaded to supply the layout
    algorithms for the right hand side of the display. Defaults to 
    "plugins/position/radial.so", which fits the entire ipv4 address space 
    into a circle. Other options include "plugins/position/networkxxyy.so"
    (fits the entire ipv4 address space into a square), 
    "plugins/position/network16.so" (will treat addresses as belonging to the
    same /16 network, using only the last two octets of the address to lay
    them out into a square), and "plugins/position/multiplenet24.so" (will
    evenly spread a number of /24 networks out over a square).
    
    The rpos_param option can be used to pass parameters into a layout module.
    For instance, the multiplenet24 plugin accepts a maximum number of /24
    networks to layout on the plane.

option: lpos_module	type: string
option: lpos_param	type: string
    Specify the shared library that should be loaded to supply the layout
    algorithms for the left hand side of the display. Defaults to 
    "plugins/position/network16.so", which treats all addresses as belonging
    to the same /16 network. Using the last two octets of the address, it 
    will lay them out over the whole square side. Other options include 
    "plugins/position/networkxxyy.so" (fits the entire ipv4 address space 
    into a square), "plugins/position/radial.so" (will fit the ipv4 address 
    space into a circle, and "plugins/position/multiplenet24.so" (will
    evenly spread a number of /24 networks out over a square).

    The lpos_param option can be used to pass parameters into a layout module.
    For instance, the multiplenet24 plugin accepts a maximum number of /24
    networks to layout on the plane.

option: dir_module	type: string
option: dirparam	type: string
    Specify the shared library that should be loaded to determine which
    direction packets are travelling in. This defaults to 
    "plugins/direction/interface.so", which uses the interface field in
    the erf header to decide between incoming and outgoing traffic. If
    you are using a pcap based format instead of erf, you will want to
    use the module "plugins/direction/destmac.so". 
    
    The dirparam option is used to specify any additional parameters that
    may be required by the direction plugin. For example, the destmac
    plugin requires a path to a file containing the mac addresses of the
    external router interfaces. This can be done as follows:

	dir_module = "plugins/direction/destmac.so"
	dirparam = "/path/to/bsod/etc/mac_addrs"
    
    Whether the packet is destined to or coming from one of the mac 
    addresses listed in this file is used to determine which way it is 
    travelling. The mac addresses should be in the standard colon seperated 
    hex notation (eg 00:11:22:33:44:55), one address per line in the file.
    
option: loop		type: integer
    Only makes sense when running with offline traces. If set to 1, then 
    the visualisation will loop when it reaches the end of the trace file.
    If set to 0, then the server will exit when it reaches the end of the 
    file. Defaults to 0.

option: shownondata	type: integer
    If set to 1 the display will show packets that contain no TCP or UDP
    payload data. Set it to 0 to hide these packets. Only applies to TCP 
    and UDP packets. Defaults to 0.

option: showdata	type: integer
    If set to 1 the display will show packets that do contain TCP or UDP
    payload data. Set it to 0 to hide these packets. Only applies to TCP
    and UDP packets. Defaults to 1.

options: showcontrol	type: integer
    If set to 1 the display will show TCP control packets (syn, fin, rst).
    Set it to 0 to hide these packets. This only applies to TCP, and 
    overrides the showdata and shownondata options. Defaults to 1.

options: showresets	type: integer
    If set to 1 the display will show TCP reset packets. To hide these packets,
    set this AND showcontrol to 0. This only applies to TCP, and does not
    override the showcontrol option. Defaults to 1.

options: shownontcpudp	type: integer
    If set to 1 the display will show IP packets for transports other than
    TCP and UDP, e.g. ICMP, GRE, ESP. Set to 0 to hide these packets.
    Defaults to 1.

option: darknet		type: boolean
    Specifies whether BSOD should maintain a blacklist of inactive hosts to
    identify DarkNet traffic. This lightlist is stored in the directory
    defined using the blacklistdir option. Defaults to false.
     
option: blacklistdir	type: string
    Specifies the directory where the blacklist information should be stored.
    This is used so that it can be reloaded at a later date without having
    to be regenerated. Blacklist info can be used to show/hide 'legitimate'
    traffic. Defaults to blist/ based off the base directory.

option: rttest		type: boolean
    Specifies whether BSOD should estimate RTT for each flow so that it can
    adjust packet velocity to mimic the connection speed. Defaults to false.

option: sampling	type: integer
    Specifies a sampling rate for the input source. One in every N packets is
    processed and sent to the client, where N is the value of this option.
    If set to 0 (or 1), no sampling is performed. Defaults to 0.

option: sendq		type: integer
    Specifies the maximum amount of outstanding data (in bytes) allowed for 
    each BSOD client. If this is exceeded, the client is dropped. Defaults to
    10 MB, i.e. 10000000.

option: left_image	type: string
    Specifies the image file that should be transmitted to the client to 
    display on the left pane.

option: right_image	type: string
    Specifies the image file that should be transmitted to the client to 
    display on the right pane.



Troubleshooting bsod server
----------------------------------
----------------------------------
Note: if these suggestions do not help, email contact@wand.net.nz with
details of your problem and we will do our best to help you.


Problem:
Everything builds and runs fine, but when the client connects it doesn't
see any traffic

Solution:
The primary cause of this is using the wrong direction module in the server.
If you are using a DAG capture card or reading from erf traces, make sure
that the 'interface' module is used. If reading straight from a network
interface or a pcap trace, the 'destmac' direction module should be used,
and the mac_addrs config file should contain remote mac addresses.

Another cause is that the server is so busy reading packets from the input
source that it has no time to transmit packet records to the client. Try
filtering the traffic source to only display a subset of the traffic or 
increase the sampling rate.

Problem:
/usr/local/bsod/bin/bsod_server: error while loading shared libraries: libtrace.so.2: cannot open shared object file: No such file or directory

Solution:
This will happen if libtrace hasn't been completely set up. After installing
libtrace, you must configure your library search paths. One way to do this is
to add the directory where libtrace is installed to your LD_LIBRARY_PATH before
running the server. In bash, this can be done with the command:

export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/usr/local/lib"

Alternatively, you can (as root) add /usr/local/lib to your /etc/ld.so.conf 
and run ldconfig to update this system wide.


Problem: 
error: parse error

Solution:
This means there is an error in your config file. Check that all strings
are appropriately quoted at start and finish and that all options have 
arguments of the right types. Also note that the last line of the file
cannont be a comment - it must either be a configuration option or a blank
line.


Problem:
Couldn't load module /usr/local/bsod/plugins/colour/colours.so
bsod_server: bsod_server.cc:391: void load_modules(): Assertion `colourhandle' failed.

Solution:
This library is part of the bsod server and should be present. It is the first
one loaded by bsod and so is usually indicative of all the libraries being
in the wrong place. Check the path that the error message gives for where it 
is looking for the module, and make sure that it is correct. If bsod server 
has been installed somewhere else (or if 'make install' has not been run at 
all), then you will need to specify where to find the bsod server directory. 
In the configuration file you should set the 'basedir' option to point to the 
bsod server directory containing the plugins directory.


Problem:
Oi! You called trace_read_packet() with a NULL libtrace parameter!
bsod_server: trace.c:639: trace_read_packet: Assertion `libtrace' failed.
Aborted

Solution:
This means that the server failed to open the data source correctly. Check
that the 'source' option in the configuration file is set to the right path,
and that the URI is of the correct type.

Problem:
bsodserver: trace.c:233: trace_create: Assertion `uri && "Passing NULL to trace_create makes me a very sad program"' failed.
Aborted

Solution:
This is similar to the problem above - in this case, you've failed to specify
the 'source' option at all. This often occurs if you do not provide a config
file when running BSOD server or the config file that you specified does not
exist. Make sure the file exists and contains a valid 'source' config option.
