README.md

   1 What is dabba?
   2 ==============
   3
   4 [![Build Status](https://secure.travis-ci.org/eroullit/dabba.png?branch=master)](http://travis-ci.org/eroullit/dabba)
   5
   6 dabba is a set of network tools written for Linux.
   7
   8 This is inspired on the Dabba Walla system present in Mumbai where
   9 meals are regrouped and dispatched throughout the city with a high
  10 efficiency rate, every day of the year.
  11
  12 The project has 4 main components:
  13 * `libdabba` - low-level zero-copy network library
  14 * `libdabba-rpc` - protobuf-based rpc library for dabbad and dabba
  15 * `dabbad` - multi-threaded task manager and RPC query processor
  16 * `dabba` - CLI 'à la git' to communicate with dabbad and submit tasks
  17
  18 Currently supported feature are listed in the [CODING] file.
  19
  20 Get the source!
  21 ===============
  22
  23 ```
  24 git clone git://github.com/eroullit/dabba.git
  25 ```
  26
  27 Contributions are welcome, [CODING] regroups all information about it.
  28
  29 Prerequisites
  30 =============
  31
  32 dabba needs these to compile and run properly:
  33 * Linux kernel >= 2.6.31
  34 * `build-essential`
  35 * `cmake`
  36 * `pthread`
  37 * `libnl-3-dev`
  38 * `libnl-genl-3-dev`
  39 * `libnl-route-3-dev`
  40 * `protobuf-c-compiler`
  41 * `libprotobuf-c0-dev`
  42 * `setcap` (within `libcap2-bin` package)
  43
  44 Recommended optional packages:
  45 * `python-yaml`
  46 * `doxygen`
  47
  48 Installation
  49 ============
  50
  51 To build out-of-tree:
  52 ```sh
  53 $ mkdir build && cd build && cmake .. && make
  54 ```
  55
  56 To install it after being built:
  57 ```sh
  58 $ sudo make install/strip
  59 ```
  60
  61 Capabilities
  62 ============
  63
  64 To configure dabba to run with a regular user account:
  65 ```sh
  66 $ sudo make setcap
  67 ```
  68
  69 Testing
  70 =======
  71
  72 Automatic tests are available. There are two kinds:
  73 * Read-only (which do not interfere with network interface settings)
  74 * Read-write (which modify network interface settings)
  75
  76 WARNING: Read-write tests might degrade or disable the
  77 interface connectivity while tests are running. Avoid to run
  78 then on production interfaces.
  79
  80 To run read-only automatic tests, make sure proper capabilities are granted and
  81 run in the build directory:
  82 ```sh
  83 $ ctest --output-on-failure
  84 ```
  85
  86 To run read-only automatic tests, make sure proper capabilities are granted,
  87 set the `TEST_DEV` variable with the interface name to modify
  88 and run in the build directory:
  89 ```sh
  90 $ TEST_DEV=eth0 ctest --output-on-failure
  91 ```
  92
  93 Getting started!
  94 ================
  95
  96 Start dabbad:
  97 ```sh
  98 $ dabbad --daemonize
  99 ```
 100
 101 As long as dabbad is running, captures tasks can be submitted:
 102 ```sh
 103 $ dabba capture start --interface eth0 --pcap /tmp/example.pcap
 104 ```
 105
 106 Running captures can be listed in YAML format:
 107 ```sh
 108 $ dabba capture get
 109 ---
 110   captures:
 111     - id: 3076324160
 112       rc: 0 # Success
 113       packet mmap size: 32768
 114       frame number: 16
 115       pcap: /tmp/example.pcap
 116       interface: eth0
 117 ```
 118
 119 Stopping the capture:
 120 ```sh
 121 $ dabba capture stop --id 3076324160
 122 ```
 123
 124 Copyright
 125 =========
 126
 127 Copyright (C) 2011-2012 Emmanuel Roullit <emmanuel.roullit@gmail.com>
 128
 129 This program is free software; you can redistribute it and/or modify
 130 it under the terms of the GNU General Public License as published by
 131 the Free Software Foundation; either version 2 of the License, or (at
 132 your option) any later version.
 133
 134 This program is distributed in the hope that it will be useful, but
 135 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 136 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 137 for more details.
 138
 139 You should have received a copy of the GNU General Public License along
 140 with this program; if not, write to the Free Software Foundation, Inc.,
 141 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
 142
 143 Contact
 144 =======
 145
 146 For questions:
 147     Send me a message to @eroullit on GitHub
 148
 149 For suggestions or bug reports:
 150     Feel free to open an issue on the [ticket system](https://github.com/eroullit/dabba/issues).
 151
 152 [CODING]: https://github.com/eroullit/dabba/blob/master/CODING