README

   1                      dabba
   2
   3        Distributed network monitoring tools
   4
   5        Copyright (C) 2013 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 The MIT License (MIT)
 113
 114 Copyright (c) 2013 Emmanuel Roullit
 115
 116 Permission is hereby granted, free of charge, to any person obtaining a copy
 117 of this software and associated documentation files (the "Software"), to deal
 118 in the Software without restriction, including without limitation the rights
 119 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 120 copies of the Software, and to permit persons to whom the Software is
 121 furnished to do so, subject to the following conditions:
 122
 123 The above copyright notice and this permission notice shall be included in
 124 all copies or substantial portions of the Software.
 125
 126 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 127 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 128 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 129 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 130 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 131 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 132 THE SOFTWARE.
 133
 134 Contact
 135 =======
 136
 137 For questions:
 138     Send me a message to @eroullit on GitHub
 139
 140 For suggestions or bug reports:
 141     https://github.com/eroullit/dabba and feel free to open an issue.