123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340 |
- .\" -*- nroff -*-
- .\"
- .\" Copyright (c) 2001-2007 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 December 11, 2007
- .Dt SYMUX 8
- .Os
- .Sh NAME
- .Nm symux
- .Nd symon stream multiplexer
- .Sh SYNOPSIS
- .Nm
- .Op Fl dltv
- .Op Fl f Ar filename
- .Pp
- .Sh DESCRIPTION
- .Xr symon 8
- is a lightweight system monitor that measures cpu, filesystem, interface, disk,
- memory, pf, pf queues, mbuf, proc and sensor statistics every 5 seconds. This
- information is then spooled to
- .Nm
- for further processing.
- .Pp
- .Xr symon 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 symon 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 symon 8
- transmissions decoded into ascii.
- .Lp
- .Nm
- needs no specific privileges 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 d
- Stop
- .Nm
- from becoming a daemon and show debug information on stdout. Use this setting
- to find hosts or specific statistics that do get sent, but are ignored due to
- configuration.
- .It Fl f Ar filename
- Read configuration from
- .Ar filename
- instead of
- .Pa /etc/symux.conf .
- .It Fl l
- List rrd files found in active configuration.
- .It Fl t
- Test configuration file and exit.
- .It Fl v
- Show version.
- .El
- .Sh CONFIGURATION
- .Nm
- obtains configuration data from
- .Pa /etc/symux.conf .
- The configuration file contains one mux stanza that defines on what host
- address 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. In the case that a
- source is of another address family than the mux stanza, i.e. source =
- ipv6 with mux = ipv4, a listen port of the sources' family is opened
- using the unspecified address. 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 | ip6addr | hostname
- port = [ "port" | "," ] portnumber
- source-stmt = "source" host "{"
- accept-stmts
- [ write-stmts ]
- [ datadir-stmt ] "}"
- accept-stmts = accept-stmt [accept-stmts]
- accept-stmt = "accept" "{" resources "}"
- resources = resource version ["(" argument ")"]
- [ ","|" " resources ]
- resource = "cpu" | "mem" | "if" | "io" | "pf" | "pfq" |
- "debug" | "proc" | "mbuf" | "sensor" | "df"
- version = "" | number
- argument = number | interfacename | diskname
- datadir-stmt = "datadir" dirname
- write-stmts = write-stmt [write-stmts]
- write-stmt = "write" resource "in" filename
- .fi
- .Pp
- Note that
- .Bl -tag -width Ds
- .It Va port
- in the
- .Va mux-stmt
- specifies the port-number for both the udp port (incoming
- .Xr symon 8
- traffic) and the tcp port for incoming listeners.
- .It Va version
- is needed to distinguish between the same type of information (i.e.
- .Va io
- ) coming from different versions of OpenBSD. If no version number is
- supplied, the latest will be assumed.
- .It Va datadir
- will guess filenames for all accepted streams.
- .Va write
- statements always take precendence over a
- .Va datadir
- statement.
- .El
- .Sh EXAMPLE
- Here is an example
- .Ar symux.conf
- that listens to udp port 2100 on lo0, and accepts cpu, memory, pf,
- interfaces xl0/de0/lo0/wi0, disks wd[0-3]/cd[0-1], disk free blocks
- of three partition streams from a
- .Xr symon 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, pf,
- if(xl0), if(de0),
- if(lo0), if(wi0),
- io(wd0), io(wd1), io(wd2),
- io(wd3), io(cd0), io(cd1),
- df(sd0a), df(sd0d), df(sd0e) }
- .Pp
- datadir "/var/www/symon/rrds/localhost"
- }
- .fi
- .Sh LISTENERS
- .Nm
- offers received
- .Xr symon 8
- data to other programs via tcp. An example of a listener session:
- .Pp
- .nf
- nexus:~/project/symon$ telnet 10.0.0.1 2100
- Trying 10.0.0.1...
- Connected to 10.0.0.1.
- Escape character is '^]'.
- .Pp
- 10.0.0.1;mem::1077662160:7630848:53850112:469417984:0:25600;cpu:0:
- 1077662160:0.00:0.00:0.30:0.20:99.50;io:wd0:1077662160:2074:12759:
- 0:30736384:131780608;
- 10.0.0.2;mbuf::1077658247:138:74:0:0:41:0:23:0:90:360:868352:25:0:
- 0:0;pf::1077658247:700930123:535398451:0:352:1107229:706391:119833
- 9:4:0:0:2:3:29:4109383:83291:83262:980325:0:1:6:0:0;mem::107765824
- 7:79155200:131956736:391430144:0:536739840;cpu:0:1077658247:0.50:0
- .00:0.00:0.90:98.60;proc:httpd:1077658247:9:216:172:8:3:0.00:14999
- 552:0;if:lo0:1077658247:147104:147104:45868177:45868177:0:0:0:0:0:
- 0;if:xl0:1077658247:284267:452077:150620236:273265863:372:89478:0:
- 0:0:0;if:de0:1077658247:1813721:1197722:729054136:568900227:101:2:
- 0:0:198:0;
- .Pp
- ^]
- telnet> close
- Connection closed.
- .fi
- .Lp
- The format is
- .Va symon-version
- :
- .Va symon-host-ip
- :
- .Va stream-name
- :
- .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 debug
- Kernel variables debug0 to debug19. ( debug0 : ... : debug19 ). Values are 32
- bit unsigned integers.
- .It df
- Disk free statistics ( blocks : bfree : bavail : files :
- ffree : synwrites : asyncwrites). Values are 64 bit unsigned integers.
- .It if
- Alias for if2. See below.
- .It if1
- Pre OpenBSD 4.3 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.
- .It if2
- Interface counters ( packets_in, packets_out, bytes_in, bytes_out,
- multicasts_in, multicasts_out, errors_in, errors_out, collisions, drops
- ). Values are 64 bit unsigned integers.
- .It io
- Alias for io2. See below.
- .It io1
- Pre OpenBSD 3.5 io/disk counters ( total_transfers, total_seeks, total_bytes
- ). Values are 64 bit unsigned integers.
- .It io2
- Io/disk counters ( total_rxfer, total_wxfer, total_seeks, total_rbytes,
- total_wbytes). Values are 64 bit unsigned integers.
- .It mbuf
- Mbuf statistics ( totmbufs : mt_data : mt_oobdata : mt_control :
- mt_header : mt_ftable : mt_soname : mt_soopts : pgused : pgtotal :
- totmem : totpct : m_drops : m_wait : m_drain ).
- .It mem
- Alias for mem2. See below.
- .It mem1
- Pre symon 2.78 memory counters ( real_active, real_total, free, swap_used,
- swap_total ). All values are in bytes rounded to page boundaries. Values are 32
- bit unsigned integers.
- .It mem2
- Memory in ( real_active, real_total, free, swap_used, swap_total ). All values
- are in bytes rounded to page boundaries. Values are 64 bit unsigned integers.
- .It pf
- Packet filter statistics ( bytes_v4_in : bytes_v4_out : bytes_v6_in :
- bytes_v6_out : packets_v4_in_pass : packets_v4_in_drop : packets_v4_out_pass :
- packets_v4_out_drop : packets_v6_in_pass : packets_v6_in_drop :
- packets_v6_out_pass : packets_v6_out_drop : states_entries : states_searches :
- states_inserts : states_removals : counters_match : counters_badoffset :
- counters_fragment : counters_short : counters_normalize : counters_memory
- ). Values are 64 bit unsigned integers.
- .It pfq
- pf/altq queue statistics ( sent_bytes : sent_packets : drop_bytes :
- drop_packets ). Values are 64 bit unsigned integers.
- .It proc
- Process statistics ( number : uticks : sticks : iticks : cpusec : cpupct :
- procsz : rsssz ).
- .It sensor
- Single sensor measurement offered with 7.6 precision. Value depends on sensor
- type.
- .El
- .Sh SIGNALS
- .Bl -tag -width Ds
- .It SIGHUP
- Causes
- .Nm
- to read
- .Pa /etc/symux.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/symux.pid
- Contains the program id of the
- .Nm
- daemon.
- .It Pa /etc/symux.conf
- .Nm
- system wide configuration file.
- .El
- .Sh LEGACY FORMATS
- .Nm
- supports symon(8) clients that send
- .Bl -tag -width Ds
- .It pre OpenBSD 3.5 disk statistics.
- These streams should be identified as io1(<disk>) instead of
- io(<disk>) in
- .Pa /etc/symux.conf.
- Also note that symon(8) measures io1 or io2 depending on whether it was
- compiled on a host that supports version 1 or 2. The rrd datastructures of
- these streams differ and there is no easy way to change an io1 rrd into an io2
- rrd.
- .It pre symon 2.78 mem/if statistics.
- These streams should be identified as if1(<interface>) and mem1() in
- .Pa /etc/symux.conf.
- symon versions 2.78 and up will always report if2 and mem2 statistics. The rrd
- files for the old and new probes are identical and need not be changed.
- .El
- .Nm
- will output what version of information it is offered by symon(8)s on
- the network when started with the
- .Va -d
- flag.
- .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>. \%Daniel \%Hartmeier helped to port to big-endian
- architectures. \%Matthew \%Gream helped to port symon to other BSD platforms.
- .Pp
- Port contributors: \%Marc \%Balmer, \%Matthew \%Gream, \%Daniel \%Hartmeier,
- \%Constantine A. \%Murenin, J. \%Martin \%Petersen, \%Fredrik \%Soderblom,
- \%Harm \%Schotanus and \%Martin van der \%Werff.
- .Sh SEE ALSO
- .Xr symon 8
|