README

   1                      dabba
   2
   3        Distributed network monitoring tools
   4
   5        Copyright (C) 2011 Emmanuel Roullit
   6
   7         https://github.com/eroullit/dabba
   8
   9 What is dabba?
  10 ==============
  11
  12 dabba is a set of network tools written for Linux.
  13
  14 Its main use is to gather or scatter actions on a network such as
  15 traffic capture, replay, generation or monitoring on a network.
  16
  17 This is inspired on the Dabba Walla system present in Mumbai where
  18 meals are regrouped and dispatched throughout the city with a
  19 high efficiency rate, every day of the year.
  20
  21 The project has 3 main components:
  22     - libdabba - low-level zero-copy network library
  23     - dabbad - multi-threaded task manager and IPC query processor
  24     - dabba - CLI 'à la git' to communicate with dabbad and submit tasks
  25
  26 What is libdabba's goal?
  27 ========================
  28
  29 libdabba's goal is to prepare a clear and simple API for future networking tools.
  30 It uses low-level zero-copy kernel features to bring traffic between the
  31 userspace and the kernelspace with very low overhead.
  32
  33 Right now, it provides functions to perform:
  34     - Multi-threaded traffic capture
  35     - PCAP file support
  36
  37 What is a zero-copy feature?
  38 ============================
  39
  40 Zero-copy packet rings are memory-mapped buffers common to kernelspace and
  41 userspace where packets can be directly read or written.
  42 This direct way of data access drastically reduces the processing overhead
  43 as packets are not hard-copied between spaces.
  44 When using a RX packet ring, received packets are quicker available
  45 to the userspace.
  46 When a TX packet ring is used, packets to transmit can be placed to
  47 medium within shorter time.
  48
  49 What is a PCAP file?
  50 ====================
  51
  52 A PCAP file is a file where previously recorded packets are saved.
  53 It can be then read to perform protocol analysis, reverse engineering
  54 or network debugging.
  55 dabba will stay independent of libpcap, but nevertheless offer PCAP file support
  56 to capture, replay and perform off-line analysis on recorded traffic.
  57
  58 Development
  59 ===========
  60
  61 There's a public Git repository at http://github.com/eroullit/dabba
  62 where you can check out the latest code base.
  63
  64 git clone git://github.com/eroullit/dabba.git
  65
  66 Coding conventions can be found in CODING.
  67
  68 Installation
  69 ============
  70
  71 You need to fulfill these prerequisites in order to build dabba:
  72         - Linux kernel >= 2.6.31
  73         - cmake
  74         - setcap (within libcap package)
  75
  76 The following are optional but recommended:
  77         - python-yaml
  78         - doxygen
  79
  80 To build out-of-tree:
  81         $ mkdir build
  82         $ cd build
  83         $ cmake ..
  84         $ make
  85         # make install/strip
  86
  87 Some unit tests need the following extra capabilities:
  88         - CAP_NET_ADMIN - To allow various network-related operations
  89         - CAP_NET_RAW - To allow use of RAW and PACKET sockets.
  90         - CAP_IPC_LOCK - To allow to lock than 64kB of mmap'ed memory
  91
  92 To grant them run in your build directory:
  93         # make setcap
  94
  95 When the code is compiled and capabilities are granted, unit tests
  96 can be executed by this command:
  97         $ ctest --output-on-failure
  98
  99 Packaging
 100 =========
 101
 102 RPM and DEB packages can be generated this way:
 103         # make package
 104
 105 It can be then installed with:
 106         # dpkg -i dabba*.deb
 107 or
 108         # rpm -i dabba*.rpm
 109
 110 Source code can be packaged with this command:
 111         $ make package_source
 112
 113
 114 Copyright
 115 =========
 116
 117 Copyright (C) 2012      Emmanuel Roullit <emmanuel.roullit@gmail.com>
 118
 119 This program is free software; you can redistribute it and/or modify
 120 it under the terms of the GNU General Public License as published by
 121 the Free Software Foundation; either version 2 of the License, or (at
 122 your option) any later version.
 123
 124 This program is distributed in the hope that it will be useful, but
 125 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 126 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 127 for more details.
 128
 129 You should have received a copy of the GNU General Public License along
 130 with this program; if not, write to the Free Software Foundation, Inc.,
 131 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
 132
 133 Contact
 134 =======
 135
 136 For questions:
 137     Send me a message to @eroullit on GitHub
 138
 139 For bugs:
 140     https://github.com/eroullit/dabba and open an issue.
 141