Examples/Sniffer/Mainpage.dox

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \mainpage Simple packet sniffer reading and dumping raw network packets
  24
  25     \dontinclude Sniffer.cc
  26
  27     The Sniffer application is a simple command line network sniffer like \c tcpdump or \c
  28     tethereal. The application uses a packet socket to read Ethernet packets from the \c eth0
  29     interface and dumps the parsed packets out to the standard output.
  30
  31     To try out the example application, check out the library, go to the \c %Sniffer
  32     directory and execute
  33
  34     <pre>
  35     # scons -u
  36     # ./sniffer loop
  37     < Hit Ctrl-C when you've seen enough >
  38     # ./sniffer scheduler
  39     < Hit Ctrl-C when you've seen enough >
  40     </pre>
  41
  42     We will now look at the code which is found in \c Sniffer.cc in the \c %Sniffer directory. The
  43     code starts out by including the necessary headers
  44
  45     \skip // Custom includes
  46     \until #include <senf/Scheduler/Scheduler.hh>
  47
  48     The example includes two implementations, one using blocking calls and a while loop, the other
  49     using the senf::Scheduler for asynchronous event notification. They are implemented in
  50     \c loop_main() and \c scheduler_main(). They will be documented below. For now, we skip these
  51     implementations and go straight to the \c main() function
  52
  53     \skip int main(
  54     \until return 1;
  55     \until }
  56
  57     This routine simply interprets the first command line argument and dispatches to the required
  58     implementation.
  59
  60     Now lets go back and study each implementation in detail.
  61
  62     \dontinclude Sniffer.cc
  63
  64     \section example_loop A Blocking Implementation
  65
  66     This implementation is found in the \c loop_main function.
  67
  68     \skip loop_main
  69     \until try
  70
  71     We catch all exceptions in a \c try block. This is good for a deliverable binary. When debugging
  72     the application, it might be better to let the exception \c abort the execution so you can get a
  73     backtrace of the exception origin in the debugger.
  74
  75     We now create a packet socket and bind it to the interface given as second command line argument.
  76     A packet socket is a linux specific type of socket which returns ethernet packets directly from
  77     the network wire. By uncommenting the last line, you may switch the interface into promiscuous mode.
  78
  79     \until //
  80
  81     We will now read packets from the socket forever, that is until the user hits Ctrl-C
  82
  83     \skip while
  84     \until while
  85
  86     The next step is, to parse the data read from the socket as an Ethernet packet
  87
  88     \until sock.read
  89
  90     \doc the following section is obsolete!
  91
  92     Lets digest this line step by step: We declare a variable named \c packet as a smart pointer to
  93     an \c EthernetPacket instance. \c ptr is a typedef member of all Packet classes for the
  94     corresponding smart pointer type. We then initialize this pointer with a call to the static \c
  95     create member of the \c Packet class. This member takes the type of Packet to parse as a
  96     template argument. We pass \c EthernetPacket here. The function takes an iterator range as an
  97     argument, and we pass it the complete packet just read by giving the range \c begin() to \c
  98     end() of our just read \c data string.
  99
 100     The next step is to write out the packet to the standard output
 101
 102     \until \n\n
 103
 104     The \c dump call will write out a complete representation of the parsed packet data. The Packet
 105     library will \e not try to interpret payload data as long as no exact indication of the payload
 106     type is available (example: A UDP Payload is not parsed further unless you explicitly tell the
 107     library, how to parse it).  Tools like \c tethereal guess the payload type by checking port
 108     numbers and the payload data, however this is not advisable for a general purpose packet
 109     library.
 110
 111     The next line, \c hexdump, will write out the \e last packet component. Packets are managed as a
 112     chain of headers. The last header is normally a \c DataPacket holding the payload data.
 113
 114     That's it. We finish of by catching the exception and giving as much detail as possible if an
 115     exception is caught
 116
 117     \until ;
 118     \until }
 119     \until }
 120
 121     The \c prettyName function from the \c Utils library is used, to get a nice, printable
 122     representation of the \e dynamic type of the exception instance. It is an interface to the g++
 123     demangler. This is necessary since the \c name member of the C++ \c type_info instance is a
 124     mangled name in \c g++.
 125
 126     That's it for the simple blocking implementation.
 127
 128     \section example_scheduler Using the Scheduler
 129
 130     However, we have another one which uses the Scheduler. We do this as it will be most of the
 131     time: We define a class which manages reading the packets and dumping them out.
 132
 133     \until }
 134
 135     The class constructor binds the socket defined as a data member to the correct interface. To
 136     tell the scheduler to call us back whenever data is available on the socket, we add a
 137     senf::scheduler::FdEvent isntance to out class.
 138
 139     The senf::scheduler::FdEvent constructor takes several arguments:
 140     \li a string describing the event.
 141     \li the callback to call whenever the event occurs.  The callback is specified as a <a
 142         href="http://www.boost.org/doc/libs/release/doc/html/function.html">Boost.Function</a>
 143         object. We use the \c senf::membind helper from the Utils library to build such a
 144         function object. This helper takes an arbitrary class member and binds it to a specific
 145         instance.
 146     \li the handle or file descriptor to monitor.
 147     \li and the events to watch for.
 148
 149     \until }
 150
 151     The public \c run() member is called to run the sniffer.  Here we just forward the call to the
 152     scheduler. Calling the Schedulers \c process() method will start the event loop. This call does
 153     not return (ok, it does return in special cases if \c senf::scheduler::terminate() is called
 154     which does not apply here).
 155
 156     \until {
 157
 158     The \c dumpPacket() member is called by the scheduler whenever an event on the socket is
 159     encountered. The scheduler calls this function with a mask of the events which triggered the
 160     call.
 161
 162     \until };
 163
 164     The body is absolutely identical to the body of the \c while loop of the blocking
 165     implementation. However, the scheduler guarantees, that a read on the socket will not block if
 166     the socket is triggered to be readable (even if the socket is not set to non-blocking mode).
 167
 168     We now only need to provide the \c scheduler_main() function to run this code
 169
 170     \until 0;
 171     \until }
 172
 173     This function is straight forward. The exception handling is the same as in \c loop_main(). The
 174     code then just creates a \c Sniffer instance and calls it's \c run() member.
 175
 176     \see \ref senf_components \n
 177          \ref senf_build \n
 178          <a href="../../../../Socket/doc/html/index.html"><b>libSocket API reference</b></a> \n
 179          <a href="../../../../Packets/doc/html/index.html"><b>libPackets API reference</b></a> \n
 180          <a href="../../../../Utils/doc/html/index.html"><b>libUtils API reference</b></a>
 181  */
 182
 183 \f
 184 // Local Variables:
 185 // mode: c++
 186 // fill-column: 100
 187 // comment-column: 40
 188 // c-file-style: "senf"
 189 // indent-tabs-mode: nil
 190 // ispell-local-dictionary: "american"
 191 // compile-command: "scons -u doc"
 192 // mode: flyspell
 193 // mode: auto-fill
 194 // End: