symon/mon/monmux/monmux.8

.\"  -*- nroff -*-
.\"
.\" Copyright (c) 2001-2002 Willem Dijkstra
.\" All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 
.\"    - Redistributions of source code must retain the above copyright
.\"      notice, this list of conditions and the following disclaimer.
.\"    - Redistributions in binary form must reproduce the above
.\"      copyright notice, this list of conditions and the following
.\"      disclaimer in the documentation and/or other materials provided
.\"      with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\" 
.Dd April 5, 2002
.Dt MONMUX 8
.Os
.Sh NAME
.Nm monmux
.Nd mon stream multiplexer
.Sh SYNOPSIS
.Nm 
.Op Fl vd
.Op Fl f Ar filename
.Pp
.Sh DESCRIPTION
.Xr mon 8
is a lightweight system monitor that measures cpu, memory, interface and disk
statistics every 5 seconds. This information is then spooled to
.Nm
for further processing. 
.Pp
.Xr mon 8
has been designed to inflict minimal performance and security impact on the
system it monitors.
.Nm
has performance impact proportional to the amount of streams it needs to
manage. Ideally 
.Nm 
should live on a different system and collect data from several
.Xr mon 8
instances in a LAN.
.Nm 
stores the incoming streams in .rrd files and distributes the information to
connected listeners. Listeners can connect to
.Nm
on a tcp port and receive incoming 
.Xr mon 8
transmissions decoded into ascii.
.Lp
.Nm
needs no specific priviledges besides being able to open it's ports and the rrd files. It should be run as
.Ar "nobody" .
.Lp
The options:
.Bl -tag -width Ds
.It Fl v
Show version information.
.It Fl d
Stop 
.Nm
from becoming a daemon and show debug information on stdout.
.It Fl f Ar filename
Read configuration from 
.Ar filename
instead of 
.Pa /etc/monmux.conf .
.Sh CONFIGURATION
.Nm
obtains configuration data from 
.Pa /etc/monmux.conf .
The configuration file contains one mux stanza that defines on what interface and port
.Nm 
should listen to for incoming monitored data. There is a source section for
every host that is to be monitored. The source section defines what data to
accept and where to write that data to. Whitespace, newlines and text behind '#' are ignored. The format in BNF:
.Pp
.nf
stmt         = mux-stmt | source-stmt
mux-stmt     = "mux" host [ port ]
host         = ip4addr | hostname
port         = [ "port" | ":" | "," ] portnumber
source-stmt  = "source" host "{" accept-stmts write-stmts "}"
accept-stmts = accept-stmt [accept-stmts]
accept-stmt  = "accept" "{" resources "}"
resources    = resource ["(" argument ")"] [ ","|" " resources ]
resource     = "cpu" | "mem" | "if" | "io"
argument     = number | interfacename | diskname
write-stmts  = write-stmt [write-stmts]
write-stmt   = "write" resource "in" filename
.fi
.Pp
Note that 
.Va port 
in the 
.Va mux-stmt
specifies the port-number for both the udp port (incoming 
.Xr mon 8
traffic) and the tcp port for incoming listeners.

.Sh EXAMPLE
Here is an example 
.Ar monmux.conf
that listens to udp port 2100 on lo0, and accepts cpu, memory, interfaces
xl0/de0/lo0/wi0, disks wd[0-3]/cd[0-1] streams from a
.Xr mon 8
on localhost. 
.Nm
will also listen on tcp port 2100 for incoming listeners.
.Pp
.nf
mux 127.0.0.1:2100
source 127.0.0.1 {
    accept { cpu(0), mem, 
             if(xl0), if(de0),
             if(lo0), if(wi0), 
             io(wd0), io(wd1), io(wd2), 
             io(wd3), io(cd0), io(cd1) }

    write cpu(0)   in "/export/mon/localhost/cpu0.rrd"
    write mem      in "/export/mon/localhost/mem.rrd"

    write if(xl0)  in "/export/mon/localhost/if_xl0.rrd"
    write if(de0)  in "/export/mon/localhost/if_de0.rrd"
    write if(lo0)  in "/export/mon/localhost/if_lo0.rrd"
    write if(wi0)  in "/export/mon/localhost/if_wi0.rrd"

    write io(wd0)  in "/export/mon/localhost/io_wd0.rrd"
    write io(wd1)  in "/export/mon/localhost/io_wd1.rrd"
    write io(wd2)  in "/export/mon/localhost/io_wd2.rrd"
    write io(wd3)  in "/export/mon/localhost/io_wd3.rrd"

    write io(cd0)  in "/export/mon/localhost/io_cd0.rrd"
    write io(cd1)  in "/export/mon/localhost/io_cd1.rrd"
}
.fi
.Sh LISTENERS
.Nm
offers received 
.Xr mon 8 
data to other programs via tcp. An example of a listener session:
.Pp
.nf
hoard:~/project/mon$ telnet 127.0.0.1 2100
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.

127.0.0.1;io:cd1:1027452867:262:308:536576;io:cd0:1027452867
:0:0:0;io:wd3:1027452867:249140:249140:11797277696;io:wd2:10
27452867:4074001:4074001:64923271168;io:wd1:1027452867:43183
9:431839:11880622080;io:wd0:1027452867:10890717:10890717:125
382360064;if:lo0:1027452867:86952111:86952111:1164079422:116
4079422:0:0:0:0:0:0;if:de0:1027452867:117562055:90333984:405
8603563:1844391820:2588654:1:0:0:4013757:0;if:xl0:1027452867
:149845272:187785769:2494862812:739916810:43291:1:3:0:318440
7:0;mem::1027452867:26566656:68579328:323141632:3571712:1047
67488;cpu:0:1027452867:0.00:0.00:0.00:0.00:99.00;
^]

telnet> close
Connection closed.
.fi
.Lp
The format is 
.Va mon-version
:
.Va mon-host-ip
:
.Va io|if|cpu|mem
:
.Va stream-argument
:
.Va timestamp
:
.Va data
.Lp
Data formats:
.Bl -tag -width Ds
.It cpu
Time spent in (user, nice, system, interrupt, idle). Total time is 100, data is
offered with precision 2.
.It mem
Memory in (real active, real total, free, swap used, swap total). All values
are in bytes rounded of to page boundaries. Values are 32 bit unsigned integers
internally.
.It if
Interface counters (packets in, packets out, bytes in, bytes out, multicasts
in, multicasts out, errors in, errors out, collisions, drops). Values are 32
bit unsigned integers internally.
.It io
Io/disk counters (total transfers, total seeks, total bytes). Values are 64 bit
unsigned integers internally.
.El
.Sh SIGNALS
.Bl -tag -width Ds
.It SIGHUP
Causes
.Nm
to read 
.Pa /etc/monmux.conf 
or the file specified by the 
.Fl f 
flag.
.Nm
will keep the old configuration if errors occured during parsing of the
configuration file.
.El
.Sh FILES
.Bl -tag -width Ds
.It Pa /var/run/monmux.pid
Contains the program id of the
.Nm
daemon.
.It Pa /etc/monmux.conf
.Nm
system wide configuration file. 
.El
.Sh BUGS
.Nm 
writes incoming data to rrd files "in process". An rrdupdate on a somewhat
stale rrdfile -- with the last data from quite some time in the past -- is a
very expensive operation. This can cause
.Nm 
to lockup while rrdupdate is updating the rrd file.
.Nm
will be unresponsive during this process. 
.Sh AUTHOR
Willem Dijkstra <wpd@xs4all.nl>
.Sh SEE ALSO
.Xr mon 8