---------------------------------------------------------------------------
Copyright (c) 2004 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 is the source release of the bsod client software. To download
the bsod server, see http://research.wand.net.nz/. To use
this software you must have access to a machine running the bsod server.

The bsod client is based on the BuNg 3d engine written by Sam Jansen and
Jesse Baker. See http://www.wand.net.nz/~stj2/bung/ for more information
and read the BUNG_LICENSE included with this release.


Changes to the client between 1.2.0 and 1.2.2
==============================================

*	IMPORTANT: Config file format changed from lua to being similar
	to bsod_server.
*	IMPORTANT: New dependancies:
	*	libconfig
	*	devil
*	Stripped out a lot of unused code (eg XML Config file parser)
*	Moved to external dependancies (removed everything from external/)
*	Removed the dependancy on lua.
*	Removed the dependancy on SCons.

Changes to the client between 1.2.0 and 1.2.1
==============================================

*	Now checks the version of the server to help prevent server/client
	mismatch.

Changes to the client between 1.1.0 and 1.2.0
==============================================

*	Vastly better performance when a lot of flows are created and destroyed 
	in a short period of time.
*	Performance improvements across the board.
*	Several new options to play with in the config file (see below).
*	Added help page (press F1 while the client is running).
*	P2P ports have their own colour now (for common ports only).
*	Particles are jittered in low framerate situations making the 
	visualization look more pleasing.
*	New particle alpha map (looks nicer and creates dots, not squares, when 
	particles are piled on top of each other).
*	Added the ability to toggle between all traffic and darknet traffic, 
	allowing you to see scans and other "garbage" traffic more easily.


Using the bsod client:
----------------------------------
----------------------------------


What you see:
----------------------------------

The bsod client displays the packets that the server receives as particles
moving through the space of the visualisation. The plane on the left hand
side represents the local address space (however the server determines that)
and the plane on the right is the remote address space (everywhere else).
Each IP address corresponds to a fixed point on one of these planes, and the
packets they send travel from the location of the source address to the
location of the destination address.

Depending on information available to the server, packets can be drawn at
different speeds, some faster, others slower. This is based off the estimated
round trip time between the source and destination machines - packets sent
between those that are close together will spend less time in the network,
and so they spend less time in the visualisation.

The colours used in the display represent different types of traffic, with
the decisions on which colours to use and which traffic to single out with
unique colours being fairly arbitrary (but based on what was commonly seen
at our capture point). The colours can be changed by replacing the colour
plugin the server uses, but the default colours based around port and
protocol are:

http:			blue
https:			light blue
smtp/pop/imap:	red
ftp:			green
dns:			yellow
ssh/telnet:		grey
windows:		orange
irc:			khaki brown
ntp:			matte green
vpn:			bright green
p2p:			toxic green (common p2p ports are processed but due to the 
				large port ranges used by modern p2p apps it is impossible to 
				mark all p2p traffic)

icmp:		teal
other tcp:	purple
other udp:	brown
unknown:	pink


Configuration file:
----------------------------------

After unzipping the archive and before running the bsod executable, you
must edit the configuration file to reflect where the bsod server is being
run. The config file is written in the lua scripting language, and contains
pairs of the form <key> = <value>. All values are either reals, integers or 
double quote enclosed strings. Comments can be added with a double hyphen 
(--), and any text after that point to the end of the line will be ignored.

Tweaking some of these options can yield large performance increases and make
visualizations of large amounts of traffic more readable. The default values
are optimal for the University of Waikato capture, for other networks these 
values should be changed appropiately.


option: network_host	type: string
Specify the host running the bsod server that will provide data to this 
client. Takes a string of the form "host:port". The server must be running
and connected to its data source before the client connects to the server.

option:	start_location	type: {real, real, real}
start_location is a triple specifying the X, Y and Z coordinates that the
camera should initially be positioned at. Pressing the 'H' key while the
client is running will display the current location, which can be useful
for getting the coordinates of the position you would like to have the
camera start at.

option:	pitch			type: real
Specify the pitch the camera should have when at its initial position.
Pressing the 'H' key while the client is running will display the current 
pitch, which can be useful for setting the pitch you would like to have the 
camera start at.

option:	heading			type: real
Specify the heading the camera should have when at its initial position.
Pressing the 'H' key while the client is running will display the current 
heading, which can be useful for setting the heading you would like to have 
the camera start at.


option: display			type: string
Specify the renderer that should be used when drawing the bsod client.
Currently only opengl is supported and so this option should always have 
the value "opengl".


option: fullscreen		type: string
Set this to "yes" to run the bsod client in fullscreen mode, otherwise set
it to "no" to run it in a window.


option: width			type: integer
Specify the horizontal width (in pixels) that the bsod client should be
displayed at.


option: height			type: integer
Specify the vertical height (in pixels) that the bsod client should be 
displayed at. Lower the width and height to a value such as 640x480 to
get better performance at the expense of image quality.


option: bpp				type: integer
Specify the number of bits per pixel used for colour information.
Lowering this to 16 may improve performance on some graphics cards.


option: speed			type: real
Sets a modifier to the speed that packets will travel at. Increasing this 
will mean fewer packets on the screen at one time and therefore better
performance. This value should be greater than 0.


option: size			type: real
Sets a modifier to the size of particles. Set this to something smaller such
as 0.5 (1/2 size) to make particles smaller and improve performance. It will
also help making a very busy display (lots of traffic) easier to read.


option: jitter			type: string
This option should be set to "yes". It will jitter particles in low framerate
situations to avoid a banding effect that would otherwise happen and make the
visualization look better. Setting it to "no" will disable this; doing so is 
not recommended.


option: billboard		type: string
Can be "yes" or "no". For now this should be set to "no" as the feature is
not implemented.


option: particle		type: string
Sets the path and filename of the alpha texture to use for the particles.

option: matrix_mode		type: string
Just for fun, changes the images used as particles to be characters from
a Matrix style font. Set to "yes" to enable, "no" to disable.

option: do_gcc			type: string
Every 10 minuted a garbage collection will be performed to throw away old,
unused flows. This can mean a slight impact in performance when the garbage 
collector runs. Setting this option to "no" may be a good idea if you have 
a lot of memory and periodically restart the client anyway.





Controls
----------------------------------

Help:						F1
Pitch up/down:				mouse up/down, up arrow/down arrow
Heading left/right:			mouse left/right, left arrow/right arrow
Forward:					W
Back:						S
Strafe left:				A
Strafe right:				D
Cycle traffic types left:	,
Cycle traffic types right:	.
Toggle HUD display:			H
Toggle wireframe mode:		R
Take screenshot:			M
Toggle darknet modes:		/
Increase speed:				=
Decrease speed:				-
Quit:						Esc


The traffic types displayed on the client can be cycled using the ',' and '.'
keys. It defaults to showing all traffic received from the server, but by 
cycling it, specific traffic types can be shown in isolation. A small label
in the bottom left corner shows what traffic is currently being shown.
Depending on how the server is configured and where it is capturing data
from, not all traffic types will show anything useful.

The HUD display can be toggled between showing the current date/time and
the debug hud, which will show the current position, pitch and heading of 
the camera, as well as frame rate and the last few lines written to the log
file.

Screenshots will be saved in the bsod client directory as 
screenshot-TIMESTAMP-COUNT.png



BSOD recommended system specs:
==============================

The machine being used to develop BSOD has the following specs: 
AMD AthlonXP 1800+, 512MB RAM, nVidia GF4-MX. BSOD should run on nearly any 
system with an OpenGL compatible 3D card but running it on anything less than 
the above is not recommended unless you are only monitoring a very low 
traffic network. On about 8Mbps worth of traffic, our machine sits at a steady
40 frames per second.

If you are running BSOD on a large network take into account that having a 
large number of flows is CPU intensive while having a large number of packets 
is GPU intensive. I.e. if you see many flows with very low packet count 
(mostly scans and worm traffic) using a fast CPU will be more important than 
a fast graphics card. If you see fewer flows but with large amounts of 
packets on them (most normal traffic, especially p2p) a fast graphics card 
becomes more important. If you see a lot of flows with a lot of packets you 
will want to use the fastest computer money can buy (BSOD really starts to 
crawl on large traffic volume networks, we are currently looking at further 
optimizing it to work better when visualizing these networks). When it comes 
to graphics card performance fillrate is the bottleneck so this is something 
to look for (rather than vertex performance) when considering buying a 
graphics card specifically for BSOD.



Customisation
----------------------------------

You can change the images displayed at either side of the visualisation area
by replacing the images in the data directory of the bsod client. The side
that represents local address space (on the left hand side with default
camera positioning) uses the file data/left.png while the world address space
(on the right by default), uses the file data/right.png. Each particle 
travelling through the display space is drawn as the image data/particle.png.





vim: ts=4
