README

   1 What is dabba?
   2 ====================
   3
   4 dabba is a set of network tools written in C for Linux.
   5
   6 Its main use is to gather or scatter actions on a network such as
   7 traffic capture, traffic replay or traffic generation on a network.
   8
   9 This is inspired on the Dabba Walla system present in Mumbai where
  10 meals are regrouped and dispatched throughout the city with a
  11 high efficency rate, every day of the year.
  12
  13 What is libdabba's goal?
  14 ====================
  15
  16 libdabba's goal is to prepare a clear and simple API for future networking tools.
  17
  18 Those then can be for high performance network tooling which
  19 focus on usability, robustness and functionality. Its aim is to support
  20 the daily work for networking engineers, developers, admins or Linux
  21 users by providing support with or in network monitoring, protocol
  22 analysis, reverse engineering, network debugging and penetration testing.
  23
  24
  25 What is a zero-copy * ring?
  26 ==========================
  27
  28 Zero-copy rings are memory-mapped ring buffers common to kernelspace and userspace where
  29 packets can be directly read or written.
  30 This direct way drastically reduces the processing overhead as packets are not hard-copied
  31 between spaces.
  32 When using a RX ring, received packets are quicker available to the userspace.
  33 When a TX ring is used, packets to transmit can be placed to medium within shorter time.
  34
  35 What is a PCAP file?
  36 ====================
  37
  38 A PCAP file is a file where previously recorded packets are saved.
  39 It can be then read to perform protocol analysis, reverse engineering or network debugging.
  40 dabba will stay independant of libpcap, but nevertheless offer PCAP file support
  41 to capture, replay and perform offline analysis on recorded traffic.
  42
  43 Some use cases and features
  44 ===========================
  45
  46 * Open source project and free licensing
  47 * Analyzing and debugging of network problems or protocol implementations
  48 * Reverse engineering of (proprietary) network protocols
  49 * Dumping, replaying and offline analysis of pcap traces
  50 * Integrated high performance capabilities
  51 * Focus on usability, robustness, security and functionality
  52
  53 Development
  54 ===========
  55
  56 There's a public Git repository at http://github.com/eroullit/dabba
  57 where you can check out the latest code base.
  58
  59 git clone git://github.com/eroullit/dabba.git
  60
  61 Coding conventions can be found in CODING.
  62
  63 Installalation
  64 ==============
  65
  66 You need to fulfill these prerequisites in order to build dabba:
  67         - Linux kernel >= 2.6.31
  68         - cmake
  69         - setcap (within libcap package)
  70
  71 To build out-of-tree:
  72         $ mkdir build
  73         $ cd build
  74         $ cmake ..
  75         $ make
  76         # make install
  77
  78 Some unit tests need the following extra capabilities:
  79         - CAP_NET_ADMIN - To allow various network-related operations
  80         - CAP_NET_RAW - To allow use of RAW and PACKET sockets.
  81         - CAP_IPC_LOCK - To allow to lock than 64kB of mmap'ed memory
  82
  83 To grant them run in your build directory:
  84         # make setcap
  85
  86 When the code is compiled and capabilities are granted, unit tests
  87 can be executed by this command:
  88         $ ctest --output-on-failure
  89
  90 Contact
  91 =======
  92
  93 For questions:
  94     Send me a message to @eroullit on GitHub
  95
  96 For bugs:
  97     https://github.com/eroullit/dabba and open an issue.
  98