1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2001-2012 Willem Dijkstra 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" - Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" - Redistributions in binary form must reproduce the above 13.\" copyright notice, this list of conditions and the following 14.\" disclaimer in the documentation and/or other materials provided 15.\" with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 20.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 21.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 25.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 27.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 4, 2012 31.Dt SYMUX 8 32.Os 33.Sh NAME 34.Nm symux 35.Nd symon stream multiplexer 36.Sh SYNOPSIS 37.Nm 38.Op Fl dltv 39.Op Fl f Ar filename 40.Pp 41.Sh DESCRIPTION 42.Xr symon 8 43is a lightweight system monitor that measures cpu, load, filesystem, interface, disk, 44memory, pf, pf queues, mbuf, proc and sensor statistics every 5 seconds. This 45information is then spooled to 46.Nm 47for further processing. 48.Pp 49.Xr symon 8 50has been designed to inflict minimal performance and security impact on 51the system it monitors. 52.Nm 53has performance impact proportional to the amount of streams it needs to 54manage. Ideally 55.Nm 56should live on a different system and collect data from several 57.Xr symon 8 58instances in a LAN. 59.Nm 60stores the incoming streams in .rrd files and distributes the 61information to connected listeners. Listeners can connect to 62.Nm 63on a tcp port and receive incoming 64.Xr symon 8 65transmissions decoded into ascii. 66.Lp 67.Nm 68needs no specific privileges besides being able to open it's ports and 69the rrd files. It should be run as 70.Ar "nobody" . 71.Lp 72The options: 73.Bl -tag -width Ds 74.It Fl d 75Stop 76.Nm 77from becoming a daemon and show debug information on stdout. Use this setting 78to find hosts or specific statistics that do get sent, but are ignored due to 79configuration. 80.It Fl f Ar filename 81Read configuration from 82.Ar filename 83instead of 84.Pa /etc/symux.conf . 85.It Fl l 86List rrd files found in active configuration. 87.It Fl t 88Test configuration file and exit. 89.It Fl v 90Show version. 91.El 92.Sh CONFIGURATION 93.Nm 94obtains configuration data from 95.Pa /etc/symux.conf . 96The configuration file contains one mux stanza that defines on what host 97address and port 98.Nm 99should listen to for incoming monitored data. There is a source section 100for every host that is to be monitored. The source section defines what 101data to accept and where to write that data to. In the case that a 102source is of another address family than the mux stanza, i.e. source = 103ipv6 with mux = ipv4, a listen port of the sources' family is opened 104using the unspecified address. Whitespace, newlines and text behind '#' 105are ignored. The format in BNF: 106.Pp 107.Bd -literal -offset indent -compact 108stmt = mux-stmt | source-stmt 109mux-stmt = "mux" host [ port ] 110host = ip4addr | ip6addr | hostname 111port = [ "port" | "," ] portnumber 112source-stmt = "source" host "{" 113 accept-stmts 114 [ write-stmts ] 115 [ datadir-stmt ] "}" 116accept-stmts = accept-stmt [accept-stmts] 117accept-stmt = "accept" "{" resources "}" 118resources = resource [ version ] ["(" argument ")"] 119 [ ","|" " resources ] 120resource = "cpu" | "cpuiow" | "debug" | "df" | "flukso" | 121 "if" | "io" | "load" | "mbuf" | "mem" | "pf" | 122 "pfq" | "proc" | "sensor" | "smart" 123version = number 124argument = number | interfacename | diskname 125datadir-stmt = "datadir" dirname 126write-stmts = write-stmt [write-stmts] 127write-stmt = "write" resource "in" filename 128.Ed 129.Pp 130Note that 131.Bl -tag -width Ds 132.It Va port 133in the 134.Va mux-stmt 135specifies the port-number for both the udp port (incoming 136.Xr symon 8 137traffic) and the tcp port for incoming listeners. 138.It Va version 139is needed to distinguish between the same type of information (i.e. 140.Va io 141) coming from different versions of OpenBSD. If no version number is 142supplied, the latest will be assumed. 143.It Va datadir 144will guess filenames for all accepted streams. 145.Va write 146statements always take precendence over a 147.Va datadir 148statement. 149.El 150.Sh EXAMPLE 151Here is an example 152.Ar symux.conf 153that listens to udp port 2100 on lo0, and accepts cpu, memory, pf, 154interfaces xl0/de0/lo0/wi0, disks wd[0-3]/cd[0-1], disk free blocks 155of three partition streams from a 156.Xr symon 8 157on localhost. 158.Nm 159will also listen on tcp port 2100 for incoming listeners. 160.Pp 161.Bd -literal -offset indent -compact 162mux 127.0.0.1 2100 163source 127.0.0.1 { 164 accept { cpu(0), mem, pf, 165 if(xl0), if(de0), 166 if(lo0), if(wi0), 167 io(wd0), io(wd1), io(wd2), 168 io(wd3), io(cd0), io(cd1), 169 df(sd0a), df(sd0d), df(sd0e) } 170.Pp 171 datadir "/var/www/symon/rrds/localhost" 172} 173.Ed 174.Sh LISTENERS 175.Nm 176offers received 177.Xr symon 8 178data to other programs via tcp. An example of a listener session: 179.Pp 180.Bd -literal -offset indent -compact 181nexus:~/project/symon$ telnet 10.0.0.1 2100 182Trying 10.0.0.1... 183Connected to 10.0.0.1. 184Escape character is '^]'. 185.Pp 18610.0.0.1;mem::1077662160:7630848:53850112:469417984:0:25600;cpu:0: 1871077662160:0.00:0.00:0.30:0.20:99.50;io:wd0:1077662160:2074:12759: 1880:30736384:131780608; 18910.0.0.2;mbuf::1077658247:138:74:0:0:41:0:23:0:90:360:868352:25:0: 1900:0;pf::1077658247:700930123:535398451:0:352:1107229:706391:119833 1919:4:0:0:2:3:29:4109383:83291:83262:980325:0:1:6:0:0;mem::107765824 1927:79155200:131956736:391430144:0:536739840;cpu:0:1077658247:0.50:0 193\.00:0.00:0.90:98.60;proc:httpd:1077658247:9:216:172:8:3:0.00:14999 194552:0;if:lo0:1077658247:147104:147104:45868177:45868177:0:0:0:0:0: 1950;if:xl0:1077658247:284267:452077:150620236:273265863:372:89478:0: 1960:0:0;if:de0:1077658247:1813721:1197722:729054136:568900227:101:2: 1970:0:198:0; 198.Pp 199^] 200telnet> close 201Connection closed. 202.Ed 203.Lp 204The format is 205.Va symon-version 206: 207.Va symon-host-ip 208: 209.Va stream-name 210: 211.Va stream-argument 212: 213.Va timestamp 214: 215.Va data 216.Lp 217Data formats: 218.Bl -tag -width Ds 219.It cpu 220Time spent in ( user, nice, system, interrupt, idle ). Total time is 100, data 221is offered with precision 2. 222.It cpuiow 223Time spent in ( user, nice, system, interrupt, idle, iowait ). Total time is 224100, data is offered with precision 2. 225.It debug 226Kernel variables debug0 to debug19. ( debug0 : ... : debug19 ). Values are 32 227bit unsigned integers. 228.It df 229Disk free statistics ( blocks : bfree : bavail : files : 230ffree : syncwrites : asyncwrites ). Values are 64 bit unsigned integers. 231.It load 232Load averages for the last 1, 5, and 15 minutes ( load1, load5, load15 ). Data is offered with prec ision 2332 and a maximum of 655. 234.It if 235Alias for if2. See below. 236.It if1 237Pre OpenBSD 4.3 interface counters ( packets_in, packets_out, bytes_in, 238bytes_out, multicasts_in, multicasts_out, errors_in, errors_out, collisions, 239drops ). Values are 32 bit unsigned integers. 240.It if2 241Interface counters ( ipackets, opackets, ibytes, obytes, 242imcasts, omcasts, ierrors, oerrors, collisions, drops 243). Values are 64 bit unsigned integers. 244.It io 245Alias for io2. See below. 246.It io1 247Pre OpenBSD 3.5 io/disk counters ( total_transfers, total_seeks, total_bytes 248). Values are 64 bit unsigned integers. 249.It io2 250Io/disk counters ( rxfer, wxfer, seeks, rbytes, 251wbytes). Values are 64 bit unsigned integers. 252.It mbuf 253Mbuf statistics ( totmbufs : mt_data : mt_oobdata : mt_control : 254mt_header : mt_ftable : mt_soname : mt_soopts : pgused : pgtotal : 255totmem : totpct : m_drops : m_wait : m_drain ). 256.It mem 257Alias for mem2. See below. 258.It mem1 259Pre symon 2.78 memory counters ( real_active, real_total, free, swap_used, 260swap_total ). All values are in bytes rounded to page boundaries. Values are 32 261bit unsigned integers. 262.It mem2 263Memory in ( real_active, real_total, free, swap_used, swap_total ). All values 264are in bytes rounded to page boundaries. Values are 64 bit unsigned integers. 265.It pf 266Packet filter statistics ( bytes_v4_in : bytes_v4_out : bytes_v6_in : 267bytes_v6_out : packets_v4_in_pass : packets_v4_in_drop : packets_v4_out_pass : 268packets_v4_out_drop : packets_v6_in_pass : packets_v6_in_drop : 269packets_v6_out_pass : packets_v6_out_drop : states_entries : states_searches : 270states_inserts : states_removals : counters_match : counters_badoffset : 271counters_fragment : counters_short : counters_normalize : counters_memory 272). Values are 64 bit unsigned integers. 273.It pfq 274pf/altq queue statistics ( sent_bytes : sent_packets : drop_bytes : 275drop_packets ). Values are 64 bit unsigned integers. 276.It proc 277Process statistics ( number : uticks : sticks : iticks : cpusec : cpupct : 278procsz : rsssz ). 279.It sensor 280Single sensor measurement offered with 7.6 precision. Value depends on sensor 281type. 282.It smart 283SMART attributes ( read_error_rate: reallocated_sectors: spin_retries: 284air_flow_temp: temperature: reallocations: current_pending: uncorrectables: 285soft_read_error_rate: g_sense_error_rate: temperature2: free_fall_protection 286). Values depend on drive model and may change between models. 287.It flukso 288Average pwr sensor value offered with 7.6 precision. Value is a moving average 289and will depend on the number of measurements seen in a particular symon 290interval. 291.El 292.Sh SIGNALS 293.Bl -tag -width Ds 294.It SIGHUP 295Causes 296.Nm 297to read 298.Pa /etc/symux.conf 299or the file specified by the 300.Fl f 301flag. 302.Nm 303will keep the old configuration if errors occured during parsing of the 304configuration file. 305.El 306.Sh FILES 307.Bl -tag -width Ds 308.It Pa /var/run/symux.pid 309Contains the program id of the 310.Nm 311daemon. 312.It Pa /etc/symux.conf 313.Nm 314system wide configuration file. 315.El 316.Sh LEGACY FORMATS 317.Nm 318supports symon(8) clients that send 319.Bl -tag -width Ds 320.It pre OpenBSD 3.5 disk statistics. 321These streams should be identified as io1(<disk>) instead of 322io(<disk>) in 323.Pa /etc/symux.conf. 324Also note that symon(8) measures io1 or io2 depending on whether it was 325compiled on a host that supports version 1 or 2. The rrd datastructures of 326these streams differ and there is no easy way to change an io1 rrd into an io2 327rrd. 328.It pre symon 2.78 mem/if statistics. 329These streams should be identified as if1(<interface>) and mem1() in 330.Pa /etc/symux.conf. 331symon versions 2.78 and up will always report if2 and mem2 statistics. The rrd 332files for the old and new probes are identical and need not be changed. 333.El 334.Pp 335.Nm 336will output what version of information it is offered by symon(8)s on 337the network when started with the 338.Va -d 339flag. 340.Sh BUGS 341.Nm 342writes incoming data to rrd files "in process". An rrdupdate on a somewhat 343stale rrdfile -- with the last data from quite some time in the past -- is a 344very expensive operation. This can cause 345.Nm 346to lockup while rrdupdate is updating the rrd file. 347.Nm 348will be unresponsive during this process. 349.Sh AUTHOR 350Willem Dijkstra <wpd@xs4all.nl>. \%Daniel \%Hartmeier helped to port to big-endian 351architectures. \%Matthew \%Gream helped to port symon to other BSD platforms. 352.Pp 353Port contributors: \%Marc \%Balmer, \%Tito \%Dal \%Canton, \%Matthew 354\%Gream, \%Daniel \%Hartmeier, \%Lars \%Kotthoff, \%Constantine 355A. \%Murenin, J. \%Martin \%Petersen, \%Fredrik \%Soderblom, \%Harm 356\%Schotanus and \%Martin van der \%Werff. 357.Sh SEE ALSO 358.Xr symon 8 359