Blueye Layer 7 Sniffer

User Manual
Rel. 1.2.0

Corrado Federici
(corrado@blueye.it)

March 10 , 2008
Copyright Corrado Federici 2006-2011

Contents
1.Why

...................................................................................................................................................

4
2.WhatisBlueye?

................................................................................................................................

4
3.Buildingblocks

.................................................................................................................................

5
3.1.Snooper(SN)

...............................................................................................................................

5
3.2.PacketInjector(PI)

....................................................................................................................

7
3.3.SessionTracker(ST)

...................................................................................................................

8
3.4.Diagnostic(DG)

.......................................................................................................................

10
4.Configurationdetails

......................................................................................................................

11
4.1.snconf

........................................................................................................................................

11
4.1.1.interfname:
..........................................................................................................
11
..................

4.1.2.capdir:
.........................................................................................................................
12
............

4.1.3.capfilesize:
..................................................................................................
12
..........................

4.1.4.sessionhistory:
.................................................................................................................
12
......

4.1.5.sessionnumber:
....................................................................................................................
..12

4.1.6.sessionstorage:
................................................................................................
13
......................

4.1.7.sessiontimeout:
...................................................................................................................
13
...

4.1.8.sessiononedir:
.....................................................................................................................
13
...

4.1.9.sessionmindack:
....................................................................................................
14
................

4.1.10.patternmatchmethod:
............................................................................................
14
.............

4.1.11.bpf:
....................................................................................................................................
14
....

4.1.12.key:
...................................................................................................................
14
....................

4.1.13.noscreenmsg:
..........................................................................................
15
............................

4.1.14.affinitymask:
...................................................................................................
15
....................

4.1.15.enableipmsg:
...................................................................................................
16
....................

4.1.16.ipmsgid:
...........................................................................................................................
16
....

4.1.17.ipmsgaddress:
....................................................................................................................
..16

4.1.18.ipmsgport:
.......................................................................................................
16
....................

4.1.19.ipmsgbuddyaddress:
.........................................................................................
16
.................

4.1.20.ipmsgbuddyport:
..........................................................................................................
16
......

4.2.piconf

........................................................................................................................................

16
4.2.1.feid:
............................................................................................................
16
...........................

4.2.2.dbhost:
.......................................................................................................................
17
............

4.2.3.ftphost:
......................................................................................................
17
............................

4.2.4.user:
.................................................................................................................
17
.......................

4.2.5.password:
..........................................................................................................................
17
......

2

4.2.6.capdir:
.........................................................................................................................
17
............

4.2.7.deleteafterinjection:
..............................................................................................
17
...............

4.2.8.sessionmindack:
....................................................................................................
18
................

4.2.9.affinitymask:
....................................................................................................
18
.....................

4.3.stconf

........................................................................................................................................

18
4.3.1.dbhost:
.......................................................................................................................
18
............

4.3.2.user:
.................................................................................................................
18
.......................

4.3.3.password:
..........................................................................................................................
18
......

4.3.4.sessiondir:
.................................................................................................
18
...........................

4.3.5.sessionstorage:
................................................................................................
18
......................

4.3.6.key:
....................................................................................................................
18
.....................

4.3.7.deleteafterinspection:
..........................................................................................................
.
19
4.3.8.affinitymask:
....................................................................................................
19
.....................

4.3.9.sessionrebuilddelay:
....................................................................................
19
........................

4.3.10.sessiononedir:
...............................................................................................
19
.....................

4.3.11.mergedirtimestamps:
......................................................................................
19
...................

4.3.12.inspectudppkt:
.................................................................................................................
20
...

4.4.dgconf

.......................................................................................................................................

20
4.4.1.smtpsender:
......................................................................................................
20
.....................

4.4.2.smtprecipient:
.....................................................................................................................
20
...

4.4.3.fromsender:
........................................................................................................
20
...................

4.4.4.smtpserver:
..................................................................................................................
20
..........

4.4.5.logdir:
......................................................................................................................
20
..............

5.Architecture

....................................................................................................................................

20
6.Installation

......................................................................................................................................

21
6.1.Win32setup

..............................................................................................................................

21
6.2.Linux

.........................................................................................................................................

23
6.3.Sourcefiles

...............................................................................................................................

25
6.4.WiFicards

................................................................................................................................

25
7.Limitations

......................................................................................................................................

26
8.Directionsoffuturework

...............................................................................................................

26
9.TheBlueyeL7Group

....................................................................................................................

27

1.Why
The reader may wonder : So many sniffers available on earth. Did we need a
new one?. I hope so. At least me. Everything started when I first tried to
tackle the problem of chasing interesting signatures on high performance
Gigabit Ethernet links. When traffic reached the 100/150 Mbit/s threshold, the
classic approach of storing all packets in the file system for later analysis
showed all of its limits and every probe that I could use intolerably dropped
possibly precious information. I then had

some tests with Snort. A really

wonderful tool that inspired me a lot. But sometimes it could be unfit,

because maybe your task is monitoring regular traffic, that is easier to handle
than hostile one (for instance, packets do not get fragmented on purpose by
an attacker, but only when they are really too large to fit into routers
interfaces). From another point of view, the difficult part of your job could be
that you need to isolate only sessions that contain specific patterns and you
might need to rebuild them from start to end on very high speed network
segments. Things could be further complicated by the fact that all the packets
in a session could be spread over more than one link for load distribution
reasons, so all the pieces needed to be reassembled before inspection.
I then started to think about a solution that, without using special appliances
but off-the shelf computer hardware, could be efficient, portable, scalable and
could fit into many operative scenarios.
Blueye is dedicated to every network admin that cannot afford expensive
special equipment or has no time for inspecting tons of log files, but
nonetheless is in charge of monitor company backbone for security purposes.
It was conceived as a contribution to intellectual property defence and
definitely not for spying peoples activity or for illegal wiretapping.

2.What is Blueye?
Just a moment. First let me tell you what it is not. Blueye is not properly an
IDS, so if you may need to pinpoint a DoS attack outbreak, there are plenty of
tools that make it better (Snort being in pole position). However, if you ever
need to recover as much information as possible, maybe while trying to avoid
4

possible company's sensitive information leakage, when it flows in high speed

links and when capture is triggered by some relevant pattern, this software
could be for you. It happens that monitoring task is accomplished paying not
enough attention, because of its burden. Having a tool that contribute to
lower this load could be very useful. Blueye is a suite of applications that
work together to deliver complete tcp sessions that carry user defined
keywords in their payload and that's why we call it a Layer Seven Sniffer. The
final product of the process is a tcpdump formatted file, filled with session's
packets from start to end, that are guaranteed to be well sequenced,
unduplicated and reassembled even if they are split into ip fragments. These
files can then be viewed with your favourite network traffic analyzer such as
Ethereal. Beyond simplicity and performance, one of the design goals of the
project was portability and thus source code and binaries are natively
available for Windows and Linux platforms.
The suite has been designed to work with ip networks with Ethernet
encapsulation, but is also able to understand frames that bear MPLS or
802.1Q tags between MAC and IP layer. Starting from release 1.2, decoding of
802.11 packets for Linux boxes was introduced, so now you can monitor your
WiFi connections.

3.Building blocks
Blueye has three main components, each of which can be configured by mean
of its private ASCII file:

3.1.Snooper (SN)
Snooper is a pcap application that owns logic for capturing data and can
work in two modes:
a. Layer 7 mode: if the user defines at least one keyword in the
configuration file snconf, SN keeps track in memory of all captured
packets up to a configurable limit, beyond which a management
policy is enforced and entries are updated. When one of the keyword
is found in a frame , session history is rebuilt since the beginning and,
from then on, the stream is kept under observation until its natural
end or until it timeouts. Because of this RAM-only working mode, we
5

get a gorgeous speed improvement over classic method of storing

frames in the filesystem. Another clear advantage is that only
sessions that carry the keyword (or key phrase) in their payload are
saved to disk, with immediate benefits for available space and lower
time dedicated to analysis. The price to pay to enhanced speed is that
cache size is not unlimited of course and thus session history
reassembling is a best effort process. However, field tests say that SN
(very) most of the times is able to detect and completely reassemble
e.g. http or smtp sessions, mixed to noise tcp traffic having a rate
close to wire speed over Gigabit links (Linux pfring distribution, see
par. 6.2).
History cache is not mandatory. If user is not interested in it, streams
will be recorded starting only form the packet that contains the
keyword. This could be the case when one can expect to find patterns
at the very beginning of a stream.
Trading completeness of information for speed, it is also possible to
record only the frame that contains relevant patterns. This working
mode could be useful when a pattern is so meaningnful that it is worth
storing only the frame that carries it.
Starting from release 1.1.0, two probes can collaborate and behave
as if they were one. If enabled, a probe informs its buddy about
relevant events, such as when a new keyword is found, so both of
them can track the same session until its end and dump to disk only a
fraction of that section, that will be consolidated into one by mean of
. Thus, former session completeness requirement can be released
because packets that compose it could be spread over two physical
links. Another major improvement of rel 1.1.0 is the possibility of
flushing to disk a single udp packet that carries a keyword.
b. Layer 4 mode: with no keyword defined, Snooper becomes a regular
sniffer, so every frame belonging to every network protocol is written
to a log file of configurable size. Before this release, this less
performing work mode was the only possible in a distributed
environment, in which every probe could see only a subset of the
packets that composed an interesting session. Configured in this way,
6

SN allows anyway to withstand and dump to disk some hundredth of

megabit per second in the Linux pfring distro (see par. 6.2).
In both work modes is possible to define bpf kernel filters based on a
combination of ip addresses or tcp ports according to the famous pcap
syntax (www.tcpdump.org). In this case, only frames that match
selected criteria will be allowed to pass by pcap kernel driver and only
those will be delivered to Snooper.
After having configured snconf file (see chapter 4.1), you can launch the
application in a command shell by typing:
./blueye-sn [options]
With no command line options , SN will have a default behaviour, looking
for its configuration file and creating its operation log file in the local
directory.
Command line options:
-I

:shows a list of interfaces (win32 only)

-c conffilepath

:specifies the directory in which snconf is located

-l logfilepath

: specifies the directory in which log files will be

created
Examples:
./blueye-sn c ./etc
./blueye-sn c ./etc l /var/snlogs
Type blueye-sn --help for help.
As

bare

minimun,

you

must

configure

capture

interface

parameter of snconf file in order to run Snooper.

3.2.Packet Injector (PI)

If we strive to create a distributed monitoring architecture, for sure we
need a component that can feed a centralized workstation with all the
contributes coming from every field probe. Thats exactly the task of
Packet Injector. PI reads .cap files produced by Snooper and feeds a
central MYSQL database. Robustness and security features of MYSQL
technology need not to be remarked.

For space and bandwidth optimization , PI selects only tcp frames that
carry information (payload size is not null) or that delimit session
boundaries (SYN, FIN or RST flag set to one). Thus, when Snooper works
in L4, you will notice that the number of injected packets in database is
lesser than the total number of them present in the .cap file. You will see
an equal number only when Snooper works in L7 mode, because it uses
the same optimization (unless parameter session-mindack is unmasked:
see 4.19 and 4.2.8).
Another virtue of Packet Injector is sanity checking of the values present
in layer III and IV headers, so you can be positive that only valid tcp
packets are stored in the db.
PI is configured via text file piconf , to be discussed later.
After having configured piconf file (see chapter 4.2), you can launch the
application in a command shell by typing:
./blueye-pi [options]
With no command line options , PI will have a default behaviour, looking
for its configuration file and creating its operation log file in the local
directory.
Command line options:
-c conffilepath

:specifies tye directory in which piconf is located

-l logfilepath

: specifies tye directory in which log files will be created

Examples:
./blueye-pi c ./etc
./blueye-pi c ./etc l /var/pilogs
Type blueye-pi --help for help.
As bare minimun, you must configure front end identifier
parameter of piconf file in order to run Packet Injector.

3.3.Session Tracker (ST)

Session tracker has a rather sensitive task because is in charge of
extracting clean tcp sessions from the hell of packets that could be
8

present in the database. Furthermore, it must guarantee that frames are

in the correct order , unduplicated and reassembled even if they are split
into fragments. ST operations are regulated by a text file named (can you
guess?) stconf . If the user defines at least one keyword, after session is
reassembled from beginning to end, it is scanned for keyword
occurrence. In case of match, session is written to disk in the selected
folder as a .cap file , otherwise it is skipped. The same apply to single
udp packets if enbaled. With no keyword defined , all tcp streams or udp
packets are flushed to disk in the selected folder. Keyword searching
after reassembling all the pieces solves a possible boundary problem,
that can occur, if inspection is performed at frame scope only and key
phrase is split into more than one datagram. Sessions are grouped in
daily folders and stored in sub folders (named according to session
parameters) that contain a .cap raw file and a .L7 file (with random
names) with application layer info (both direction of communication,
much like Follow tcp stream function of Wireshark). A daily register was
added that reports more detailed info.
If not configured otherwise, all packets are not deleted from database,
but simply disabled. This guarantees that records can be always
inspected and that session rebuild process could be replayed in case of
need. Simply re-enable all records by issuing the following commands
when logged in the mysql console:
USE Blueye;

(select Blueye database)

UPDATE Packet SET Enabled=1;

(set Enabled field of all records to

one)
The drawback of keeping every record is that database size could grow
very significantly and thats why one can choose to delete every session
after it has been inspected.
After having configured stconf file (see chapter 4.3), you can launch the
application in a command shell by typing:
./blueye-st [options]

With no command line options , ST will have a default behaviour, looking

for its configuration file and creating its operation log file in the local
directory.
Command line options:
-c conffilepath

:specifies tye directory in which stconf is located

-l logfilepath

: specifies tye directory in which log files will be created

Examples:
./blueye-st c ./etc
./blueye-st c ./etc l /var/stlogs
Type blueye-st --help for help.

3.4.Diagnostic (DG)
When all the above stuff is in operation, log files are produced that
describe all the relevant events. If we need to setup a very small
monitoring system, maybe we want to be remotely informed about them.
Diagnostic is a very basic parser that scans each daily log file produced
by SN, PI, ST and emails some of its entries: every kind of error, program
startup and shutdown and key found events.
After having configured dgconf file (see chapter 4.4), you can launch the
application in a command shell by typing:
./blueye-dg [options]
With no command line options , DG will have a default behaviour, looking
for its configuration file in the local directory.
Command line options:
-c conffilepath

:specifies type directory in which stconf is located

Examples:
./blueye-dg c ./etc
Type blueye-dg --help for help.
At this point it should be clear that searching for patterns at the first stage of
the SN->PI->ST chain instead of the last, has complementary benefits in
terms of performance (capture in SN) and completeness of information
(search in ST).
10

Finally, you could ask: As L7 mode produces complete sessions from SYN to
FIN, when packets are not split over two physical links, why do I need to inject
them into the database?. Good question. In a local network scenario you
should not need it, but take into account that, for sake of speed, Snooper in
L7 mode cannot guarantee that frames are unduplicated or well sequenced as
Session Tracker does. In this context, you can rely on STs ability to act as a
washing machine, configuring it (with no keywords) to clean and reorder all
your interesting streams.
One final remark. STs speed mostly depends on database query
responsiveness, which can be greatly improved by optimization techniques.
Usage of indexes is a good candidate for this kind of task. This is not the
place to discuss table index creation, so please refer to Mysql doc about
optimization in general and CREATE INDEX statement syntax in particular.

4.Configuration details
What follows is a descriptions of all parameters of the configuration files.
Many parameters can be commented out with a pound sign # at the
beginning of each line, in which case a default value will be used. Notice that
parsing of configuration files will ignore blank spaces or tabs that you may
insert after colon with which parameter names end. Only for key statements
this spaces or tabs matter and are considered valid chars.

4.1.snconf

4.1.1.interf-name:
Name of the network interface that will snoop for packets. This
parameter is mandatory (there is no default value).
Example: (for Linux boxes)
Example: (for Linux boxes)
interf-name: eth0
Example: (for Windows boxes)
interf-name: \Device\NPF_{4DAF118C-ECC3-45CE-8E2DD649E02B7E40}.
11

In this case, you can get this lengthy string by running Snooper
with I switch, which prints out all network interfaces.
4.1.2.capdir:
Folder path in which .cap files will be stored. Default value is
current directory.
Example:
capdir: /var/caps (Linux)
capdir: c:\caps (Windows)
4.1.3.capfile-size:
When working in L4 mode, after having written log-size MB ,
Snooper will create a new log file. Min: 1 Max: 999 Default: 32
Example:
capfile-size: 64
4.1.4.session-history:
When working in L7 mode, this value determines the size of the
history cache in mega bytes. This container is the basket in which
Snooper will try to find packets (of same session) stored before the
one that contains the keyword. Please note that a bigger cache not
always gives better performances. Tcp session completeness may
increase, but also latency times could and the CPU may ignore new
incoming packets while busy in searching older ones. A value of
128/256 seems appropriate in many situations and a value of zero
will disable session history reconstruction.
Min: 0 Max: 999 Default: 256
Example:
session-history: 128
4.1.5.session-number:
When working in L7 mode, this value determines how many
interesting sessions at time must be handled. Interesting sessions
(for which at least one keyword matched) are kept in memory until
an ending mark is found or a timeout expires. Again this value
must be a trade off between performance and completeness and a
value from 4 to 16 could be appropriate if keywords are not very
trivial.
12

When this number in set to one, in case of keyword match session

history is rebuilt by a low priority thread letting the main one
always ready to read from network card .In case of heavy network
loads, this can avoid losing new incoming packets belonging to
that session. Tha bad news is that packet history is not updated till
session terminates (so you better keep low session timeouts).
Min: 1 Max: 99 Default: 4
Example:
session-number: 8
4.1.6.session-storage:
When working in L7 mode, this value determines the maximum
room available in memory for session growth. When a session is
active , after history is rebuilt, it is tracked until its end and every
packet is stored in this buffer. Dont worry about high values of this
parameters, because disk flush is accomplished via low priority
threads. A zero value will record only the packet where keyword
was found.
Min: 0 Max: 999 Default: 32
Example:
session-storage: 8
4.1.7.session-timeout:
When working in L7 mode, this value determines the maximum
number of seconds that Snooper will wait for an active session to
end, when no packet belonging to it is received. After this time
session is written to disk anyway.
Min: 1 Max: 999 Default: 30
Example:
sessiontimeout:5
4.1.8.session-onedir:
When working in L7 mode, an interesting session normally records
not only the stream where a keyword is found , but also the
opposite direction (e.g traffic from client to server and viceversa). If

13

one still needs to track a single direction this flag must be

unmasked. Default: disabled (both directions get logged)

4.1.9.session-mindack:
For performance reasons, when working in L7, Snooper discards
zero sized acknowledge packets, because they are not strictly
requested by ST at rebuild time. However, should your protocol
analyzer need them to better track a conversation between two
parties, you can unmask this flag. Default: disabled (ACK arent
logged)
4.1.10.pattern-match-method:
When working in L7 mode, this value determines the algorithm that
will be used for pattern matching. You can choose between WuMamber (WM) or Aho-Corasick (AK)
Possible values: WM, AK . Default: WM
Example:
patternmatchmethod:AK
4.1.11.bpf:
If the capture board doesnt provide this service and we need to
rely on filtering ability of the OS kernel, it is possible to define a
filter following the tcpdump syntax (see www.tcpdump.org).
If bpf statement is commented out, all traffic is allowed to pass.
Example:
bpf:tcpdstport25ortcpport80ortcpsrcport110
HerewedecidetocaptureSMTPtraffictoanymailserver,webservertrafficin
bothdirectionsandPOP3trafficfromanymailserver.
4.1.12.key:
Presence of at least one statement of this type determines L7 work
mode. Keywords can be simple tokens or phrases, written in ASCII
or expressed in hexadecimal form. This latter feature lets you
specify any language by entering raw mode coding. Key statement
14

shorter than 4 chars are ignored (they are considered too generic).
There is no limit but memory size to the number of key statements,
but remember that each of them must be sized 254 chars at most.
Syntax is case sensitive , unless a nocase statement is appended.
Example:
key:|546861747327416D6F7265|
key:jellyfisH
key:theBlueorcinus;nocase
key:tellmehowtogetridoftheoldboomerangasIwanttobuyanewone
Inthefirst,secondandfourthexamplepatternswillbesearchedexactlymatching
case,whileinthethirdBlueorcinuswillbesearchedregardlessofcase.
4.1.13.no-screenmsg:
WhenworkinginL7mode,ifthisstatementispresent,everyKEYFOUNDpost
startupmessagewillbesuppressedandtherewillbenoscreenprintoutwhena
keywordmatches.Iguessthatyoumayappreciatethisonlyinextremecases,in
whichCPUtimeissopreciousthatyoudonotwanttowasteitprintingtothe
standardoutput.Default:disabled(screenmessagesareallowed).

4.1.14.affinity-mask:
Inamultiprocessorsystem,affinityisdefinedasthepossibilityforaprocessto
chooseasubsetofavailableCPUs.Ingeneralthisbindingisautomaticallyperfomed
bythedispatcherunitoftheOS.Nevertheless,therearetimeswhenwewantto
manuallyassignadedicatedCPUtoaparticularrealtimeprocess.Anaffinitymask
isapatternofbitseachcorrespondingtoanavailableprocessor.Ifthebitisset
Snoopercanrunonthatprocessor,otherwiseitcannot.Validmaskhavenbits,
wherenis2or4.MostsignificantbitisforCPU0andsoontillleastsignificantbit
forCPUn1.Default:allbitstoone.
Example:Dualcoresystem:SnooperrunsonCPU1,butnotonCPU0
affinitymask:01
15

Example:Quadcoresystem:SnoopercanrunonCPU0orCPU3
affinitymask:1001

4.1.15.enable-ipmsg:
WhenworkinginL7mode,thisstatementenablescommunicationbetween two
probesthatbehaveasiftheywereone.Theonethatfindsanewkeywordinapacket
ordetectsanendofsessionmarkersendsamessagetotheotherthat,accordingly,
tracksthatsessionorflushesittodisk.Default:disabled(interprobemessagesare
notsent).
4.1.16.ipmsg-id:
Mandatory interprobe messaging identifier that distinguishes a
probe from its buddy. Min: 1 Max: 999
Example:
ipmsg-id: 1
4.1.17.ipmsg-address:
Mandatory ip address that receives interprobe messages.
4.1.18.ipmsg-port:
Udp port that listens to interprobe messages. Default:34543
4.1.19.ipmsg-buddy-address:
Mandatory ip address of buddy (to send interprobe messages to)
4.1.20.ipmsg-buddy-port:
Udp

port

of

buddy

that

listens

to

interprobe

messages.

Default:34543

4.2.piconf
4.2.1.fe-id:
Front end identifier. This parameter is used to distinguish from one
probe to another and it is inserted into records to understand
packet origin. It mandatory also in case of single probe
architecture. Min: 1 Max: 999
Example:
fe-id: 5
16

4.2.2.db-host:
NameoripaddressoftheremoteMYSQLdatabase
Example:
db-host:backend.company.it

4.2.3.ftp-host:
Name or ip address of the remote FTP server. As an alternative to
inject packets into a database, it is possible to upload captured
files to an ftp server for further processing by some kind of
application the user might already have. File transfer is
accomplished by a standard version of ncftpput by Mike Gleason
(http://www.NcFTP.com)
4.2.4.user:
4.2.5.password:
Database connection credentials. PI must log into a MYSQL db
before it can inject frames. Blueye table setup script will have
granted access to this user.
Example:
db-user:blueyeadmin
db-password:blueye
This couple can be used also as logon credentials of a remote ftp
server.
4.2.6.capdir:
Folder path from which .cap files will be read. Default value is
current directory.
Example:(see4.1.2)

4.2.7.delete-after-injection:
Ifthisstatementispresent,everycapturefileisdeletedfromthefilesystemafterall
packetsthatitcontainshavebeeninjetctedintothedatabase.Youmayappreciate
thisbehaviourwhenitsbettersavingdiskspacethankeepingalocalcopyoftraffic.
Default:disabled(capturefilesarenotdeleted).
17

4.2.8.session-mindack:
See4.1.9

4.2.9.affinity-mask:
See4.1.12

4.3.stconf
4.3.1.db-host:
4.3.2.user:
4.3.3.password:
Databaseconnectioncredentials.STmustlogintoaMYSQLdbbeforeitcanfetch
frames.
(see 4.2.2-4-5)

4.3.4.session-dir:
Folder path in which .cap files with rebuilt sessions will be stored.
Default value is current directory.
Example:
session-dir: /var/sessions (Linux)
session-dir: c:\sessions (Windows)
4.3.5.session-storage:
During session building , packet payloads are copied in a
temporary buffer for later inspection. This value determines the
size of this buffer.
Min: 1 Max: 999 Default: 128 MB
Example:
sessionstorage:64
4.3.6.key:
If at least one key statement is found, after session is reassembled
from beginning to end, it is searched for keyword occurrence . In
case of match only, session is written to disk in the capdir folder as
a tcpdump formatted .cap file. If no keyword is defined, all sessions
will be flushed to disk. (see 4.1.10 for syntax)
18

4.3.7.delete-after-inspection:
Ifthisstatementispresent,everysessionisdeletedfromthedatabaseafterithas
beeninspected.Thissavesspaceonyourharddisk,butofcoursepreventsyoufrom
replayingtherebuildingprocessincaseofneed..Default:disabled(recordsare
simplydisabledandnotdeleted).

4.3.8.affinity-mask:
See4.1.12

4.3.9.session-rebuild-delay:
AsSessionTrackerandPacketInjectorworksasynchronously,wemustavoidthat
rebuildprocessofalengthysessioncouldstartwhilepacketsarestillbeingwritten
tothedatabase.ThusitisnecessaryforSTtoprocessonlyagedpacketsthatwere
writtenatleastsessionrebuilddelaysecondsago. Min: 10 sec Max: 999 sec
Default: 10 sec

4.3.10.session-one-dir:
Startingfromrel.1.1.0,bothdirectionsofasessionsarerebuilt(e.g.fromserverto
clientandviceversa)andflushedinthesamefile.Incaseofneed,onecanchooseto
processonedirectionattimeandhavethemwrittenintwoseparate.capfiles.
Default:disabled.

4.3.11.merge-dir-timestamps:
Inthedefaultcase,thetwodirectionsofasessionareflushedtodiskoneafter
another,becausetheyarerebuiltoneindependentlyfromtheother.Byunmasking
thisparameter,however,onecanchoosetosortpacketsaccordingtotheirreal
timestamp(thetimetheywerecapturedbythenetworkcard).Thisway,youcansee
theconversationbetweentwopeersasitreallyhappened.Awordofcaution:
rearrangingpacketsisanextracomputationalburdenforthebackendandmaybeit
isuselessatthisstage,becauseyourprotocoldecoder(theprogramyouuseto
analyzeapplicationlayerinformation)isalreadyabletodoit.Default:disabled,
unlessbuiltinprotocoldecodersareenabled.
19

4.3.12.inspect-udp-pkt:
Udppacketsareonlyprocessedifthisflagisunmasked.Default:disabled

4.4.dgconf
4.4.1.smtp-sender:
Optional SMTP address of the sender, that is RFC 821s MAIL
FROM: field (es Probe-1@company.com)

4.4.2.smtp-recipient:
SMTP address of the receiving mailbox, that is RFC 821s RCPT TO:
field (es blueyemonitor@company.com)

4.4.3.from-sender:
Name of the sender , that is the From: field inside RFC 821s
DATA field (es Probe-1)

4.4.4.smtp-server:
Fully qualified domain name (es mx.company.com) or ip address of
the mail server.
4.4.5.log-dir:
Directory in which log files are located.
Mail messages are sent by the following command line SMTP clients:
email rel 2.5.1. (www.cleancode.org) for Linux and blat 2.6.1
(www.blat.net) for Windows.

5.Architecture
Blueyes software components fit in a simple front-end/backend architecture
that let you easily deploy a distributed monitoring system. Most of the times
every front end probe (FeP) will host one

SN and one PI agent. From a

physical point of view, every probe will be a two armed object, connected
from one side to the network segment under observation, via span (mirror)
port or passive tap. The other network card is used to transmit packets to a
backend server that hosts a central MYSQL database and a Session Tracker
component. It is also possible to deploy a solution with multi-homed Feps, in
20

which a couple of SN, PI agent will be running for every capturing card, but of
course this configuration is strongly dependent on FeP hardware and traffic
rate sent to the Snooper. In case of interprobe messages, one can decide to
reserve a an additional network card as a private communication channel or
use backend interface.
A third possible computational level is a workstation that runs network
analysis software (Analysis Console: AC ) fed by .cap files picked up from the
backend, but nothing forbids to install it on the backend if enough
computational resources are present.
The following picture displays a possible configuration with two Feps
connected to span ports of the corporate network :

In

the

simplest

cases,

we

can

deploy

an

all-in-one

configuration

(SN+PI+DB+ST+AC modules in the same workstation) or even setup a probe

with Snooper L7 with analysis software only (SN+AC modules in the same
workstation). In this latter case take into account the remarks at the end of
chapter 3.

6.Installation
6.1.Win32 setup
Wizard Blueye 1.2.0 Setup.exe will assist you during installation
process. After having accepted license condition, you will be able to
select all the components you need:
21

Snooper: will copy in the installation folder the files blueye-sn.exe

and snconf. Packet capture library (http://www.winpcap.org) for
Windows rel 4.0.2 or above is a prerequisite and, if not detected,
setup will ask the user for the permission to install it;

Packet Injector: will copy in the installation folder the files blueyepi.exe and piconf. Prerequisites are packet capture library for
Windows (as above) and libmySQL.dll client libray rel 5, necessary to
connect to MYSQL database. This dll will be copied too, provided that
Blueye Database Tables options is not selected, in which case it is
assumed that installation occurs in the database machine where this
library is already present (at most you will have to copy it from Mysql
installation folder to where Windows can find it, perhaps System32 or
Blueye local directory) . The package also includes ncftpput.exe rel
3.2.0 (see 4.2.3);

Session Tracker: will copy in the installation folder the files blueyest.exe and stconf. libmySQL.dll client libray is a prerequisite and the
same considerations as above apply;

Diagnostic: will copy in the installation folder the files blueye-dg.exe

and dgconf. The package also includes blat.exe rel 2.6.1 see (4.4);

Blueye Database Tables: you will choose this option after having
installed MySQL database version 5 (www.mysql.com) in the selected
host. Setup will copy and execute MySqlCmd-win32.bat that will
22

create the BLUEYE database, according to CreateBlueyeDB.txt, which

is a text file with a list of commands interpreted by Mysql
administration utility mysql. After having launched the script, user
must enter a root password to login to database.
-

After having created BLUEYE database, these following statement will

grant all privileges on it to a user called blueyeadmin having password
blueye:
GRANT ALL PRIVILEGES ON BLUEYE.* TO 'blueyeadmin' IDENTIFIED BY
'blueye'
After installation, by mean of mysql utility you can (and should)
always modify these credentials, but remember that they must match
the ones defined in the configuration files piconf and stconf (see 4.2.2
and 4.3.1) , otherwise PI and ST login will fail. Configured this way, the
GRANT statement allows connections from any host. If you want to
enforce a better control on which hosts connect to database, you can
issue

GRANT

command

specifying

(blueyeadmin'@'somehost')

(blueyeadmin'@'172.16.5.32')

or

for

instance

an
perhaps

hostname

ip
a

class

address
B

subnet

(blueyeadmin'@'172.16.'). See Mysql documentation about GRANT

and REVOKE syntax for more details.
Please note that Setup will not create any table if already present in
the database and Uninstall.exe utility will not delete any table.

6.2.Linux
Archive Blueye-1.2.0-Linux.tar.gz contains all the stuff if you need to
start immediately: binaries precompiled with gcc 4.1.1 on a Fedora Core
6 box running kernel 2.6.18-1 with glibc 2.5.3 and libstdc++ 4.1.1,
configuration files and db table generation script. Snooper comes in two
flavours:
-

blueye-sn for any Linux platform with vanilla kernels;

blueye-sn-ring which will work only on Linux boxes that have been
previously kernel patched with the PF_RING rel.3 package by Luca
23

Deri (every detail at: http://www.ntop.org/PF_RING.html ). As already

recalled, this is the best performing Snooper configuration that it is
worth to get acquainted with, if you need to face high speed links.
Tables will be created on database machine by manually executing
the script MySqlCmd-linux. Same considerations as above apply.
Prerequisites:
-

blueye-sn-ring requires:
o previous installation of library libpcap 0.9.4 or later;
o previous

kernel

pacthing

as

described

here:

http://www.ntop.org/PF_RING.html. From the userland point of

view, this binary comes statically linked with a patched version of
libpcap rel 0.9.4 (as PF_RING socket requires also modifications to
the capture library).
-

blueye-sn requires previous installation of library libpcap 0.9.4 or

later;

blueye-pi requires previous installation of:

o library libpcap 0.9.4 or later;
o MySQL client library package

rel 5. It could be a good idea to

download database source package (mysql-5.0.18.tar.gz or later

from www.mysql.com) and run ./configure without-server . Then
running make and make install will compile and install only client
libraries (not the server part). See INSTALL-SOURCE file in the
package for every detail;
o OpenSSL library rel 0.9.8 a or later;
o lsof utility, a list open files utility usually present out of the box;
o Ncftp package (www.ncftp.com), but only if you plan to upload to a
ftp server (rel 3.2.0 was successfully tested).
-

blueye-st requires previous installation of:

o MySQL client library package rel 5 as above;
o OpenSSL library rel 0.9.8 a or later.

blueye-dg

requires

previous

installation

of

email

(www.cleancode.org): rel 2.5.1 was successfully tested.

24

package

6.3.Source files
Blueye-1.2.0-src.tar.gz contains all the project with source, doc and
configuration files. Win32 master project blueye.vcproj was created
with Microsoft Visual C++ 2005 Express Edition (which is freely available
from MS site) with .NET framework 2.0. Core part of Platform SDK is
needed (download and burn a copy of Windows Server 2003 R2 platform
SDK iso from MS site) in order to install some include and library files and
VC configuration must be updated accordingly (Tools->Options->VC++
Directories: Include and Library files).
Linux

project

files

are

blueye-c.cbx,

PacketInjector.cbx

and

SessionTracker.cbx which were created with Borland C++ Builder X

Personal 1.0 (free of charge too): .mak exports of project files are also
available (to be used with make f utility to build the sources). For Linux,
same prerequisites as above apply.
Sorry, there is no configure-make-make install procedure for now.

6.4.WiFi cards
As previously recalled, Snooper and Packet Injector are able to decode
radio headers that WiFi cards drivers prepend to packets with Ethernet
802.3 encapsulation (Linux only):
-

Radiotap headers (www.radiotap.org) , used for instance by Linux

madwifi drivers for Atheros chipsets (madwifi.org);

Prism2 headers used by Intersil (or compatible) chipsets;

AVS headers.

See this page by Jean Tourrilhes for a whos who of wifi drivers and
devices

under

Linux:

http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Linux.Wireless.driv
ers.802.11ag.html#AtherosMADWiFi.
Tests were performed with Proxim Orinoco 11 a/b/g ComboCard
(cardbus interface, atheros chipset, madwifi drivers) and D-Link DWLG122 8012.11g (usb interface, Ralink chipset and rt73-k2wrlz-2.0.1
drivers). For example with D-Link DWL-G122 driver rt73-k2wrlz-2.0.1
installs a wifi interface as rausb0. Then the following shell commands
25

must be issued before starting a live capture with Snooper on radio

channel 8 and ip addess 10.10.10.10:
-

ifconfig rausb0 10.10.10.10 up

iwconfig rausb0 channel 8;

iwconfig rausb0 mode monitor;

Wireless Extensions set by Jean Tourrilhes (iwconfig, iwlist, iwpriv, ) is a

prerequisite.
When reading offline captures, Packet Injector will remove radio and
802.3 headers and add a Ethernet V2 header, as packets were captured
from a wired interface.

7.Limitations
At the moment, Blueye is able to rebuild tcp sessions or inspect single udp
packets. Therefore, other kinds of traffic should be filtered out by the network
card or by operative system bpf kernel filters, because they only represent a
useless burden.
Furthermore, Snooper in L7 mode is not able to deal with fragmented
packets. Should your network have an not negligible quota of fragmented
datagrams and you need to collect them, the only way is reverting to L4
mode. According to experience, this issue is not generally important in a
corporate network scenario, when compared to the performance increase that
you can achieve working in L7 mode.

8.Directions of future work

Future releases will (hopefully) address the following possible issues:

at the moment, Session Tracker uses a so called Default Decoder that

simply saves Application Layer data, without further processing. Next
releases could enable smarter plugins that will decode at least most
common protocols (http, pop3,smtp, ..);

If smarter decode will be introduced , there will be the need of a suitable

user interface to navigate thru results;

26

Blueye building blocks now get configured via simple text files. In the
future, configuration commands could be stored as database tables.

installation automation on Linux boxes via standard configure + make +

make install sequence;

Snooper cache search algorithm when working in L7 mode. Session history

reconstruction is quite fast, but future releases could tailor the way cache
is searched to traffic profile, allowing user choose which algorithm
achieves best performance;

Snooper working in L7 mode seems fit for resource constrained equipment

like handheld devices. Rebuilding source code for Linux Familiar or
Windows Mobile seems reasonable;

all of the bugs that users will report. |-) .

9.The Blueye L7 Group

Not many indeed:

Corrado Federici: Software architect (corrado@blueye.it)

Tony Di Bernardo: Linux kernel wizard and field test engineer

(tony@blueye.it)

Mauro Sedrani: Webmaster and field test engineer (mauro@blueye.it)

Francesco Comello: FreeBSD kernel wizard and field test engineer

(frank@blueye.it)

27