home | help 
SYMUX(8)		     System Manager's Manual			SYMUX(8)

NAME
     symux -- symon stream multiplexer

SYNOPSIS
     symux [-dltv] [-f filename]

DESCRIPTION
     symon(8)  is a lightweight system monitor that measures cpu, load, filesys-
     tem, interface, disk, memory, pf, pf queues, mbuf, proc and sensor  statis-
     tics every 5 seconds. This information is then spooled to symux for further
     processing.

     symon(8)  has been designed to inflict minimal performance and security im-
     pact on the system it monitors.  symux has performance impact  proportional
     to the amount of streams it needs to manage. Ideally symux should live on a
     different system and collect data from several symon(8) instances in a LAN.
     symux  stores the incoming streams in .rrd files and distributes the infor-
     mation to connected listeners. Listeners can connect to symux on a fifo and
     receive incoming symon(8) transmissions decoded into ascii.

     symux needs no specific privileges besides being able to  open  it's  ports
     and the rrd files. It should be run as nobody.

     The options:

     -d      Stop  symux  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.

     -f filename
	     Read configuration from filename instead of /etc/symux.conf.

     -l      List rrd files found in active configuration.

     -t      Test configuration file and exit.

     -v      Show version.

CONFIGURATION
     symux  obtains  configuration data from /etc/symux.conf.  The configuration
     file contains one mux stanza that defines on what	host  address  and  port
     symux  should listen to for incoming monitored data. There is a source sec-
     tion 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:

	   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" | "cpuiow" | "debug" | "df" | "flukso" |
			  "if" | "io" | "load" | "mbuf" | "mem" | "pf" |
			  "pfq" | "proc" | "sensor" | "smart"
	   version	= number
	   argument	= number | interfacename | diskname
	   datadir-stmt = "datadir" dirname
	   write-stmts	= write-stmt [write-stmts]
	   write-stmt	= "write" resource "in" filename

     Note that

     port    in the mux-stmt specifies the port-number for the udp port  (incom-
	     ing symon(8) traffic).

     version
	     is needed to distinguish between the same type of information (i.e.
	     io  ) coming from different versions of OpenBSD. If no version num-
	     ber is supplied, the latest will be assumed.

     datadir
	     will guess filenames for all accepted  streams.   write  statements
	     always take precendence over a datadir statement.

EXAMPLE
     Here is an example symux.conf that listens to udp port 2100 on lo0, and ac-
     cepts  cpu,  memory, pf, interfaces xl0/de0/lo0/wi0, disks wd[0-3]/cd[0-1],
     disk free blocks of three partition streams from a symon(8) on localhost.

	   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) }

	       datadir "/var/www/symon/rrds/localhost"
	   }

LISTENERS
     symux offers received symon(8) data to other programs via a fifo. An  exam-
     ple of a listener session:

	   nexus:~/project/symon$ cat /var/run/symux.fifo

	   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
	   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;

	   ^C

     The format is symon-version : symon-host-ip : stream-name : stream-argument
     : timestamp : data

     Data formats:

     cpu     Time  spent  in ( user, nice, system, interrupt, idle ). Total time
	     is 100, data is offered with precision 2.

     cpuiow  Time spent in ( user, nice, system, interrupt, idle, iowait ).  To-
	     tal time is 100, data is offered with precision 2.

     debug   Kernel  variables	debug0	to  debug19. ( debug0 : ... : debug19 ).
	     Values are 32 bit unsigned integers.

     df      Disk free statistics ( blocks : bfree : bavail : files  :	ffree  :
	     syncwrites : asyncwrites ). Values are 64 bit unsigned integers.

     load    Load  averages  for  the  last 1, 5, and 15 minutes ( load1, load5,
	     load15 ). Data is offered with prec ision 2 and a maximum of 655.

     if      Alias for if2. See below.

     if1     Pre OpenBSD  4.3  interface  counters  (  packets_in,  packets_out,
	     bytes_in,	bytes_out, multicasts_in, multicasts_out, errors_in, er-
	     rors_out, collisions, drops ). Values are 32 bit unsigned integers.

     if2     Interface counters ( ipackets, opackets, ibytes,  obytes,	imcasts,
	     omcasts,  ierrors,  oerrors, collisions, drops ). Values are 64 bit
	     unsigned integers.

     io      Alias for io2. See below.

     io1     Pre OpenBSD 3.5 io/disk counters  (  total_transfers,  total_seeks,
	     total_bytes ). Values are 64 bit unsigned integers.

     io2     Io/disk counters ( rxfer, wxfer, seeks, rbytes, wbytes). Values are
	     64 bit unsigned integers.

     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 ).

     mem     Alias for mem2. See below.

     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.

     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.

     pf      Packet filter statistics ( bytes_v4_in : bytes_v4_out : bytes_v6_in
	     : bytes_v6_out : packets_v4_in_pass :  packets_v4_in_drop	:  pack-
	     ets_v4_out_pass  : packets_v4_out_drop : packets_v6_in_pass : pack-
	     ets_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 : coun-
	     ters_short : counters_normalize : counters_memory ). Values are  64
	     bit unsigned integers.

     pfq     pf/altq queue statistics ( sent_bytes : sent_packets : drop_bytes :
	     drop_packets ). Values are 64 bit unsigned integers.

     proc    Process  statistics  ( number : uticks : sticks : iticks : cpusec :
	     cpupct : procsz : rsssz ).

     sensor  Single sensor measurement offered with 7.6 precision. Value depends
	     on sensor type.

     smart   SMART attributes ( read_error_rate:  reallocated_sectors:	spin_re-
	     tries:  air_flow_temp: temperature: reallocations: current_pending:
	     uncorrectables: soft_read_error_rate: g_sense_error_rate:	tempera-
	     ture2: free_fall_protection ). Values depend on drive model and may
	     change between models.

     flukso  Average  pwr  sensor  value  offered with 7.6 precision. Value is a
	     moving average and will depend on the number of  measurements  seen
	     in a particular symon interval.

SIGNALS
     SIGHUP  Causes  symux  to read /etc/symux.conf or the file specified by the
	     -f flag.  symux will keep the old configuration if  errors  occured
	     during parsing of the configuration file.

FILES
     /var/run/symux.pid
	     Contains the program id of the symux daemon.

     /var/run/symux.fifo
	     The named pipe / fifo that transmits an ascii version of the incom-
	     ing measurements.

     /etc/symux.conf
	     symux system wide configuration file.

LEGACY FORMATS
     symux supports symon(8) clients that send

     pre OpenBSD 3.5 disk statistics.
	     These  streams  should  be  identified  as  io1(<disk>)  instead of
	     io(<disk>) in /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.

     pre symon 2.78 mem/if statistics.
	     These  streams  should be identified as if1(<interface>) and mem1()
	     in /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.

     symux will output what version of information it is offered by symon(8)s on
     the network when started with the -d flag.

BUGS
     symux 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 symux to lockup while
     rrdupdate is updating the rrd file.  symux will be unresponsive during this
     process.

AUTHOR
     Willem Dijkstra <wpd@xs4all.nl>. Daniel Hartmeier helped to port to big-en-
     dian architectures. Matthew Gream helped to port symon to other  BSD  plat-
     forms.

     Port  contributors:  Marc	Balmer,  Tito  Dal Canton, Matthew Gream, Daniel
     Hartmeier, Lars Kotthoff,	Constantine  A.  Murenin,  J.  Martin  Petersen,
     Fredrik Soderblom, Harm Schotanus and Martin van der Werff.

SEE ALSO
     symon(8)

FreeBSD ports 15.quarterly	  April 4, 2012 			SYMUX(8)
home | help