Annotation of embedaddon/bmon/man/bmon.1, revision 1.1
1.1 ! misho 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