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