---------------------------------------------------------------------------

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.1 and 1.3.0
=============================================

*	New Client/Server Protocol
*	Server now allocates colours and protocol names
*	New menu (reachable via F1 or clicking on the Menu indicator)
*	Pointsprites support
*	Optimisations (both memory and cpu)
*	Toggle of individual protocols (via Menu)
*	Many Many Bug fixes
*	Right click on an endpoint reveals that endpoints IP address




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





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

Toggle HUD display:			H

Toggle wireframe mode:		R

Take screenshot:			M

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

