1: .TH bmon 1 "Feb 27, 2005" "Bandwidth Monitor"
2: .SH NAME
3: bmon \- Portable bandwidth monitor and rate estimator
4: .SH SYNOPSIS
5: .B bmon
6: [
7: .B \-awSchV
8: ] [
9: .B \-i
10: .I <mod>
11: ] [
12: .B \-o
13: .I <mod>
14: ] [
15: .B \-I
16: .I <mod>
17: ] [
18: .B \-O
19: .I <mod>
20: ]
21: .br
22: .ti +5
23: [
24: .B \-f
25: .I <path>
26: ] [
27: .B \-p
28: .I <policy>
29: ] [
30: .B \-r
31: .I <float>
32: ] [
33: .B \-s
34: .I <float>
35: ]
36: .br
37: .ti +5
38: [
39: .B \-A
40: .I <attrs>
41: ] [
42: .B \-N
43: .I <ngraphs>
44: ] [
45: .B \-u
46: .I <uid>
47: ] [
48: .B \-g
49: .I <gid>
50: ]
51: .br
52: .ti +5
53: [
54: .B \-R
55: .I <float>
56: ] [
57: .B \-H
58: .I <float>
59: ] [
60: .B \-L
61: .I <lifetime>
62: ] [
63: .B \-t
64: .I <path>
65: ]
66: .PP
67:
68: .SH DESCRIPTION
69: bmon is a portable bandwidth monitor with multiple input
70: methods and output modes. A set of architecture specific
71: input modules provide the core with the listof interfaces
72: and their counters. The core stores this counters and
73: provides rate estimation including a history over the last
74: 60 seconds, minutes, hours and days to the output modules
75: which output them according to the configuration.
76:
77: The set of counters is dependant on the input module and
78: may vary. Secondary input and output modules may be used
79: to collect counter values from other nodes or to write
80: HTML statistics. This input/output architecture minimizes
81: the work needed to port it to other architectures or
82: generate specific statistics.
83:
84: .SH OPTIONS
85: .TP
86: .B \-i
87: Set primary \fIinput module\fR and its configuration. The
88: argument "list" will result in a list of available input
89: modules. See INPUT MODULES for more details.
90: .TP
91: .B \-o
92: Set primary \fIoutput module\fR and its configuration. The
93: argument "list" will result in a list of available output
94: modules. See OUTPUT MODULES for more details.
95: .TP
96: .B \-I
97: Set secondary \fIinput modules\fR and their configuration.
98: The argument "list" will result in a list of available
99: secondary input modules.
100: .TP
101: .B \-O
102: Set secondary \fIoutput modules\fR and their configuration.
103: The argument "list" will result in a list of available
104: secondary output modules.
105: .TP
106: .B \-f
107: Set alternative configuration \fIpath\fR.
108: .TP
109: .B \-p
110: Set interface acceptance policy. See INTERFACE SELECTION for
111: more details.
112: .TP
113: .B \-a
114: Include interfaces even if their status is down.
115: .TP
116: .B \-A
117: Set attribute acceptance policy for attributes you whish to
118: collect historical data for. Equivalent to INTERFACE
119: SELECTION but without support for wildcards. Set to "all"
120: to maintain a history for all attributes.
121: .TP
122: .B \-r
123: Set reading \fIinterval\fR in which the input module will be
124: called. The default for this is one second. Should be less or
125: equal than 1 or a factor of it. Values not equal to 1 will
126: result in additional rate calculation with the read interval
127: as its unit.
128: .TP
129: .B \-R
130: Set rate \fIinterval\fR, i.e. the time period taken into account for the
131: rate calculation. The default value is 30 seconds.
132: .TP
133: .B \-H
134: Set the \fIhearbeat\fR while reading, specifies the variance
135: of incomming updates still acceptable. A factor of 0.1 specifies
136: a accepted variance of 10% before and after the expected timestamp.
137: .TP
138: .B \-L
139: Set the \fIlifetime\fRlifetime of a item, i.e. the time that
140: can pass until a item is deleted if it does not receive any updates.
141: The default is 30 seconds.
142: .TP
143: .B \-t
144: Set \fIpath\fR to the itemtab file.
145: .TP
146: .B \-c
147: Enable the use of SI unit schema.
148: .TP
149: .B \-N
150: Set number of graphs to draw, does not work for all outputs
151: methods.
152: .TP
153: .B \-s
154: Set sleeping \fIinterval\fR between calls to output short
155: interval callbacks for interactive output modules. Changing
156: this can affect the variance of read intervals.
157: .TP
158: .B \-w
159: Enable signal driven output intervals. The output module will
160: only be invoked upon receiving of SIGUSR1. Use bmon \-S \- to
161: send the signal to a running bmon instance in signal driven mode.
162: .TP
163: .B \-S
164: Send SIGUSR1 to a running bmon instance. This arugment takes
165: either \fI-\fR which will result in invoking ps to find bmon
166: instances or a \fIpid\fR directly.
167: .TP
168: .B \-u
169: Change user ID to \fIuid\fR after initialization.
170: .TP
171: .B \-g
172: Change group ID to \fIgid\fR after initialization.
173: .TP
174: .B \-h
175: Prints a help text and exits.
176: .TP
177: .B \-V
178: Prints the version and exits.
179:
180: .SH INPUT MODULES
181:
182: Input modules provide the core with interface statistics.
183: Two kinds of modules exist, primary and secondary input
184: modules. Their main difference is usage, there may be only
185: one primary module running at the same time while the number
186: of secondary input modules is not limited.
187:
188: Every input module has a description, help text and list of
189: options available which can be seen by adding the option
190: "help" to the module options:
191: .TP
192: .RS
193: .NF
194: bmon \-i netlink:help
195: .FI
196: .RE
197:
198: See MODULE CONFIGURATION for more details.
199:
200:
201: .SH PRIMARY INPUT MODULES
202: .TP
203: \fBnetlink\fR (Linux)
204: Requires libnl and uses an rtnetlink to collect interface
205: statistics. This input module also provides statistics about
206: traffic control qdiscs and classes. It is the preferred
207: input module on Linux.
208:
209: .TP
210: \fBkstat\fR (SunOS)
211: Provides interface statistics on SunOS operating systems in
212: form of 32bit and 64bit counters. It is the preferred input
213: module on SunOS.
214:
215: .TP
216: \fBsysctl\fR (BSD, Darwin)
217: Provides interface statistics on BSD and Darwin operating
218: systems. Is is the preferred input module on any BSD
219: alike system.
220:
221: .TP
222: \fBproc\fR (Linux)
223: Provides interface statistics on Linux using the proc
224: filesystem (/proc/net/dev). It is one of the fallback
225: input modules on Linux and will work on nearly every
226: Linux kernel version.
227:
228: .TP
229: \fBsysfs\fR (Linux)
230: Provides interface statistics on Linux using the sys
231: filesystem (/sys/class/net/). It may be used together
232: with newer Linux kernel versions but has no real
233: advantage over the netlink input module. It caches
234: open file descriptors to speed it up and is used
235: as fallback method.
236:
237: .TP
238: \fBnetstat\fR (POSIX)
239: Provides limited interface statistics on almost any
240: POSIX operating system by invoking netstat \-i \-a. Only
241: use this as last hope.
242:
243: .TP
244: \fBdummy\fR (any)
245: The purpose of the dummy input module is for testing. It
246: generates in either a static or randomized form.
247:
248: .TP
249: \fBnulll\fR (any)
250: Does not provide any interface statistics and thus can be
251: used to disable local interface collection.
252:
253: .SH SECONDARY INPUT MODULES
254:
255: .TP
256: \fBdistribution\fR
257: Collects interface statistics from other nodes. It is the
258: counterpart of the secondary output module called distribution.
259: Its purpose is to distribute statistics in real time with
260: not too much bandwidth consumption itself. See DISTRIBUTION
261: for more details.
262:
263: .SH OUTPUT MODULES
264:
265: Output modules are feeded with rate estimations and graphs
266: from the core and print them out to the configured output
267: device. Two kinds of modules exist, primary and secondary
268: output modules. Their main difference is usage, there may be
269: only one primary module running at the same time while the number
270: of secondary output modules is not limited.
271:
272: Every output module has a description, help text and list of
273: options available which can be seen by adding the option
274: "help" to the module options:
275: .TP
276: .RS
277: .NF
278: bmon \-o ascii:help
279: .FI
280: .RE
281:
282: See MODULE CONFIGURATION for more details.
283:
284: .SH PRIMARY OUTPUT MODULES
285:
286: .TP
287: \fBascii\fR
288: The ascii output modules prints out the diagrams and
289: lists to standard output. The output format is highly
290: configurable and suits as vmstat alike tool for interface
291: statistics.
292:
293: .TP
294: \fBcurses\fR
295: Interactive curses user interface providing real time rate
296: estimations and graphs. The default view is a list of all
297: interfaces grouped per node. The graphical history diagram
298: and a list of detailed counters may be enabled/disable
299: during runtime. Press '?' while the UI is running to see
300: the quick reference.
301:
302: .TP
303: \fBformat\fR
304: Formatable ascii output for scripts. Calls a drawing function
305: for every item per node and outputs according to the specified
306: format string. The format string consists of text support various
307: escaping sequences and placeholders in the form of $(placeholder).
308:
309: .TP
310: \fBnull\fR
311: Disables primary output.
312:
313: .SH SECONDARY OUTPUT MODULES
314:
315: .TP
316: \fBhtml\fR
317: Writes all interface statistics and diagrams as HTML files including
318: a navigation menu for all nodes and their interfaces. The layout
319: can be easly changed by altering the stylesheet which will not be
320: overwritten.
321:
322: .TP
323: \fBdistribution\fR (any)
324: Distributes all statistics over the network using an UDP based
325: statistic distribution protocol. The default configuration will
326: use the multicast address all\-nodes but it may also be configured
327: so send to a unicast address.
328:
329: .TP
330: \fBrrd\fR (any)
331: Updates and creates RRD databases using librrd. Step, heartbeat
332: and archives can be freely configured.
333:
334: .TP
335: \fBaudio\fR (any)
336: Outputs the currently selected attribute rate as MIDI
337: sequence.
338:
339: .TP
340: \fBdb\fR (any)
341: Writes current rate estimations into a database for other tools
342: to pick up.
343:
344: .TP
345: \fBxml_event\fR (any)
346: Writes a continious stream of XML objects containing the
347: counters to a standard output or into a file.
348:
349: .TP
350: \fBxml_state\fR (any)
351: XML based state output, outputs counters as-is as XML
352: objects into a file. The file is overwritten in each
353: cycle and locked during this period.
354:
355: .SH MODULE CONFIGURATION
356:
357: ARGUMENT ::= modulename:OPTS[,modulename:OPTS[,...]]
358: .br
359: OPTS ::= OPTION[;OPTION[;...]]
360: .br
361: OPTION ::= type[=value]
362:
363: If you specify multiple primrary input or output modules the
364: first reported to be working module will be used.
365:
366: If you specify multiple secondary input or output modules all
367: of them will get invoked.
368:
369: .SH DISTRIBUTION
370:
371: Statistic distribution is a powerful method to spread the statistic
372: all over the network and make the available on every machine. The
373: advantage over web based statistic overviews and multi terminal
374: remote shell based solutions is its nearly realtime accuracy while
375: being lightweight and not polluting the network too much. The protocol
376: is UDP based and thus not reliable and optmized on size.
377:
378: See include/bmon/distribution.h for the protocol specification.
379:
380: .SH DIAGRAM TYPES
381:
382: You will find the following diagram types being used by all output
383: modules in some form:
384:
385: .TP
386: \fBlist\fR
387: A list of interfaces including their byte and packets rate (bps/pps).
388:
389: .TP
390: \fBgraphical history diagram \fR
391: A graph showing the history of a counter over the last 60 (read interval/
392: seconds/minutes/hours/days). The outer left column is the most recent
393: rate while the outer right column is the most outdated. The preferred
394: diagram to impress co\-workers.
395:
396: .TP
397: \fBdetailed\fR
398: Detailed counters such as error counters or other attributes assigned
399: to this interface. The list of attributes may very depending on the
400: input module and architecture of the host OS.
401:
402: .SH INTERFACE SELECTION
403:
404: SELECTION ::= NAME[,NAME[,...]]
405: .br
406: NAME ::= [!]interface
407:
408: The interface name may contain the character '*' which will act as a wildcard and represents any
409: number of any character type, i.e. eth*, h*0, ...
410:
411: .TP
412: Examples:
413: .RS
414: .NF
415: lo,eth0,eth1
416: .FI
417: .RE
418: .RS
419: .NF
420: eth*,!eth0
421: .FI
422: .RE
423:
424: .SH CONFIGURATION FILE
425:
426: Bmon will try and read configuration data from the following
427: files in the specified order: /etc/bmon.conf, $HOME/.bmonrc.
428:
429: None of the above files will be read if the path to the
430: configuration file was specified using the \-f option.
431:
432: Configuration possibilities:
433:
434: \fBinput\fR \fI<module configuration>\fR
435: .br
436: .ti +7
437: Specify primary input module (\-i), see INPUT MODULES.
438:
439: \fBsecondary_input\fR \fI<module configuration>\fR
440: .br
441: .ti +7
442: Specify secondary input modules (\-I), see INPUT MODULES.
443:
444: \fBoutput\fR \fI<module configuration>\fR
445: .br
446: .ti +7
447: Specify primary output module (\-o), see OUTPUT MODULES.
448:
449: \fBsecondary_output\fB \fI<module configuration>\fR
450: .br
451: .ti +7
452: Specify secondary output modules (\-O), see OUTPUT MODULES.
453:
454: \fBpolicy\fB \fI<policy>\fR
455: .br
456: .ti +7
457: Set interface acceptance policy (\-p), see INTERFACE SELECTION.
458:
459: \fBread_interval\fB \fI<interval>\fR
460: .br
461: .ti +7
462: Set reading interval in which the input module will be called
463: (-r).
464:
465: \fBsleep_time\fB \fI<interval>\fR
466: .br
467: .ti +7
468: Set sleeping interval between calls to output short interval
469: callbacks for interactive output modules. (\-s)
470:
471: \fBshow_all\fR
472: .br
473: .ti +7
474: Include interface even if their status is down. (\-a)
475:
476: \fBuse_si\fR
477: .br
478: .ti +7
479: Use SI metric system. (\-c)
480:
481: \fBnr_graphs\fR \fI<num>\fR
482: .br
483: .ti +7
484: Set number of graphs to draw, does not work for all outputs methods. (\-N)
485:
486: \fBitemtab\fR \fI<path>\fR
487: .br
488: .ti +7
489: Path to itemtab. (\-t)
490:
491: \fBheartbeat_factor\fR \fI<factor 0..1>\fR
492: .br
493: .ti +7
494: Set heartbeat factor
495:
496: \fBrate_interval\fR \fI<interval>\fR
497: .br
498: .ti +7
499: Set rate interval, i.e. the time period taken into account for the
500: rate calculation. (\-R)
501:
502: \fBlifetime\fR \fI<seconds>\fR
503: .br
504: .ti +7
505: Set lifetime of a item, i.e. the time that can pass until a
506: item is deleted if it does not receive any updates. (\-L)
507:
508: \fBinclude\fR \fI<file>\fR
509: .br
510: .ti +7
511: Include \fIfile\fR and read it as configuration file.
512:
513: \fBColor layouts\fR
514: .br
515: .ti +7
516: See COLOR LAYOUTS.
517:
518: \fBBindings\fR
519: .br
520: .ti +7
521: See BIND INTERFACE.
522:
523:
524: .SH COLOR LAYOUTS
525:
526: The layout is used to specify the look'n'feel of the curses
527: output module. The color "default" represents the terminal
528: color which can be used to keep the background transparent
529: for transparent terminals.
530:
531: .LP
532: .B Colors:
533: default, black, red, green, yellow, blue, magenta, cyan, white
534: .LP
535: .B Flags:
536: reverse
537: .LP
538: .B Layouts:
539: Default, Statusbar, Header, List, Selected,
540:
541: Prototype:
542: .br
543: .ti +7
544: \fBLayout\fR \fI<name>\fR \fI<foreground>\fR \fI<background>\fR \fI<flags>\fR
545:
546: Example:
547: .br
548: .ti +7
549: Layout Statusbar red black reverse
550:
551: Feel free to submit patches extending the configurability using layouts.
552:
553: .SH BIND INTERFACE
554:
555: The bind interface can be used to bind not yet assigned keys to
556: shell scripts. It currently works in the curses output module but
557: it might be ported to other output modules in the future. The interface
558: name of the currently selected interface is provided to the script
559: via the first argument.
560:
561: Prototype:
562: .br
563: .ti +7
564: \fBBind\fR \fI<key>\fR \fI<Executable>\fR
565:
566: Example:
567: .br
568: .ti +7
569: bind D /sbin/intf_down.sh
570:
571: .SH EXAMPLES
572:
573: To run bmon in curses mode monitoring the interfaces eth0
574: and eth1:
575: .RS
576: .NF
577: \fBbmon \-i eth0,eth1 \-o curses\fP
578: .FI
579: .RE
580:
581: To run bmon in acii mode printing the detailed diagram
582: with fixed y\-axis unit:
583: .RS
584: .NF
585: \fBbmon \-o 'ascii:diagram=detailed;ynit=kb'\fP
586: .FI
587: .RE
588:
589: To run bmon in signal driven mode drawing the graphical
590: diagram with customized drawing characters and fixed x
591: and y axis:
592: .RS
593: .NF
594: \fBbmon \-s \-o 'ascii:diagram=graph;fgchar=#;bgcar=_;xunit=min'\fP
595: .FI
596: .RE
597:
598: To run bmon with no primrary output (daemon) but
599: distribute the statistic over the network:
600: .RS
601: .NF
602: \fBbmon \-o null \-O distribution\fP
603: .FI
604: .RE
605:
606: To run bmon collecting local and remote statistics and
607: show it in curses mode:
608: .RS
609: .NF
610: \fBbmon \-I distribution:multicast \-o curses\fP
611: .FI
612: .RE
613:
614: To build a relay and collect remote statistic and send
615: them to a unicast address while ignoring while
616: the destination is unreachable:
617: .RS
618: .NF
619: \fBbmon \-i null \-I distribution:multicast \-o null \-O 'distribution:ip=10.0.0.1;errignore;forward'\fP
620: .FI
621: .RE
622:
623: To collect local statistics and those from the whole
624: network and generate a HTML page out of the those
625: statistics:
626: .RS
627: .NF
628: \fBbmon \-I distribution:multicast \-o null \-O html:path=/var/istats/\fP
629: .FI
630: .RE
631:
632: .SH KNOWN ISSUES
633: The curses output modules doesn't work properly on NetBSD < 2.0 because getch() cannot be set to be non\-blocking.
634:
635: sysctl input segfaults on sparc64 OpenBSD.
636:
637: .SH FILES
638: /etc/bmon.conf
639: .br
640: $HOME/.bmonrc
641:
642:
643: .SH SEE ALSO
644: ifconfig(8), kstat(1M), netlink(3)
645:
646: .SH AUTHOR
647: Thomas Graf <tgraf@suug.ch>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to bmon.1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bmon / man