doc/user-manual.txt

   1
   2
   3
   4                                    bwmon
   5                                 User Manual
   6
   7
   8
   9 bwmon is a per-application bandwith monitoring framework written in Python. It
  10 can monitor generated traffic and bandwidth (traffic over time) per process or
  11 application (group of processes).
  12
  13 bwmon has two different means of monitoring: the Monitor which relies on data
  14 gathered from the /proc filesystem and and Pipe which accounts data passed
  15 through it.
  16
  17 Both monitoring types can be used standalone or be combined through the
  18 Aggregator. The Aggregator can group processes to applications and issue
  19 notifications if one process/application passes its configured threshold.
  20
  21
  22
  23    The Monitor
  24 =================
  25
  26 The Monitor is used for general-purpose traffic and bandwith monitoring. It
  27 uses data from the /proc filesystem, especially from /proc/net/ip_conntrack
  28 which is provided by the Kernel module ip_conntrack. If this file does not
  29 exist, try to run
  30
  31   sudo modprobe ip_conntrack
  32
  33
  34
  35 Using the Monitor
  36 ~~~~~~~~~~~~~~~~~
  37
  38 The Monitor can be used standalone by running
  39
  40   sudo python runmonitor.py [--no-lookback] [--bandwidth] [--ignore-local]
  41       [--include=<regex> [--include=<regex> ...] [--exclude=<regex> [...]]
  42
  43 When started without arguments, Monitor displays the accumulated traffic since
  44 monitoring for the process was started by ip_conntrack. However this timespan
  45 can vary between processes and can (currently) not be determined. To display
  46 only traffic generated after the start of the Monitor, use the --no-lookback
  47 switch.
  48
  49
  50 To display bandwith usage instead of accumulated traffic, you can use
  51 --bandwidth switch. Monitor will then calculate the bandwidth usage per second.
  52
  53
  54 By default Monitor also includes traffic via the loopback interface. By using
  55 the --ignore-local switch loopback traffic can be ignored.
  56
  57
  58 To select the processes that are monitored by Monitor you can use the --include
  59 and --exclude options to pass regular expressions. Both flags can be combined
  60 and each can be used multiple times.
  61
  62 When --include is used, only processes that match at least one of the "include"
  63 regular expressions are monitored. When --exclude is used, processes that match
  64 the "exclude" regular expressions are excluded. Exclude overrides include.
  65
  66
  67
  68    The Pipe
  69 ==============
  70
  71 The Pipe opens a local port and connects to a remote host. It them forwards and
  72 accounts all traffic passed through it.
  73
  74
  75
  76 Using the Pipe
  77 ~~~~~~~~~~~~~~
  78
  79 The Pipe is started with
  80
  81     python runpipe.py <port> <remote-host>
  82     python runpipe.py <local-port> <remote-host> <remote-port>
  83
  84
  85 When started with two arguments, Pipe opens <port> locally and establishes a
  86 connection to <remote-host> on the same port. When started with three
  87 arguments, different local and remote ports can be used.
  88
  89
  90
  91    The Aggregator
  92 ====================
  93
  94 The aggregator combines multiple instances of Monitor and Pipe to provide a
  95 consistant configuration and notification interface.
  96
  97 Multiple processes (even with traffic data coming from different monitors) can
  98 be grouped to applications. Notification thresholds can then be assigned to
  99 applications instead of simple processes.
 100
 101
 102
 103 Using the Aggregator
 104 ~~~~~~~~~~~~~~~~~~~~
 105
 106 The aggregator is started with
 107
 108     python runaggregator.py [--app-config=<file>] [--monitor-config=<file>]
 109         [--notification-config=<file>] [--auto-group]
 110
 111
 112 It then prints one line per application that has used bandwidth during the last
 113 interval (1 second). The output can be divided into three columns. The first
 114 containins the incoming and the second the bandwidth. The third columns is used
 115 to distinguish the processes and contains the commandline (for processes) or
 116 the application name (for grouped processes).
 117
 118
 119 Specifying Monitors
 120 ~~~~~~~~~~~~~~~~~~~
 121
 122 By default the Aggregator starts one Monitor and no Pipes. To override this
 123 behaviour, the switch --monitor-config can be used to specify a monitor
 124 configuration file.
 125
 126 The configuration file is expected to have the following format.
 127
 128 [Monitor Name]
 129 type=<monitor-type>
 130 <parameter>=<value>
 131
 132 Monitor Name is a description of the monitoring instance and is not processed
 133 by the Aggregator. The type can either be "monitor" or pipe. The available
 134 parameters depend on the type.
 135
 136
 137 Paramters for Monitors:
 138  * include
 139  * exclude
 140  * ignorelocal
 141
 142 The parameters correspond to the commandline switches of the standalone
 143 monitor. Only one include and exclude regular expression can be given per
 144 Monitor instance.
 145
 146
 147 Parameters for Pipes
 148  * port
 149  * newhost
 150  * newport
 151
 152 The parameters correspond to the commandline switches of the standalone pipe.
 153
 154 A sample configuration can be found in monitors.sample.cfg
 155
 156
 157
 158 Grouping Processes
 159 ~~~~~~~~~~~~~~~~~~
 160
 161 The Aggregator can aggregate the bandwidth usage for a group of processes. The
 162 grouping can either happen automatically or through a supplied configuration.
 163
 164 The switch --auto-group activates automatic grouping based on the basename of
 165 the processes. Grouping is tried for all processes without exceptions. If only
 166 some processes shall be grouped or different rules shall be applied, a
 167 configuration file can be specified with the --app-config switch.
 168
 169 The supplied configuration file is expected to have the following format:
 170
 171 [Application Name]
 172 shortname=regex
 173
 174 Where Application Name is the name under which the aggregated bandwidth of the
 175 matched processes will be shown. Each application section can have multiple
 176 rules labeled with a "shortname" each with a regular expression that is matched
 177 against the processes' commandline. The shortname is used to describe the rule
 178 and is not used by the Aggregator.
 179
 180 A sample configuration file can be found in group.sample.cfg
 181
 182
 183
 184 Notifications
 185 ~~~~~~~~~~~~~
 186
 187 The Aggregator can issue notifications if a process or application exceeds its
 188 configured bandwidth threshold. Aggregator does not use default thresholds and
 189 does therefor not issue notifications unless explicitly configured.
 190
 191 The configuration file is provided via the parameter --notification-config and
 192 is expected to have the following format.
 193
 194 [Application Name]
 195 process_filter=<regex>
 196 notification_threshold=<bandwidth in kB/s>
 197 interval=<average timestamp in s>
 198 notification_command=<cmd>
 199
 200 Application Name is a label that is used to describe the following entry and is
 201 not processed by the Aggregator.
 202
 203 process_filter specifies a regular expression that is used to limit the scope
 204 of the rule. The regular expression is matched against
 205 * the process commandline for processes that are not grouped
 206 * the application name for grouped processes
 207
 208 The rule is only valid for matching processes/groups.
 209
 210 Incoming and outgoing bandwidth thresholds are specified in kB/s.
 211
 212 Notifications are triggered if the average bandwidth over the given interval
 213 (in seconds) exceeds the configured threshold.
 214
 215 A triggered notification writes its information to stderr. If a
 216 notification_command is configured, the given program is started.
 217