Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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

     symux -- symon stream multiplexer

     symux [-dltv] [-f filename]

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

     symon(8) has been designed	to inflict minimal performance and security
     impact on the system it monitors.	symux has performance impact propor-
     tional to the amount of streams it	needs to manage. Ideally symux should
     live on a different system	and collect data from several symon(8) in-
     stances in	a LAN.	symux stores the incoming streams in .rrd files	and
     distributes the information to connected listeners. Listeners can connect
     to	symux on a tcp port and	receive	incoming symon(8) transmissions	de-
     coded 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.

     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
     section for every host that is to be monitored. The source	section	de-
     fines 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 be-
     hind '#' 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	"{"
			  [ 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 both	the udp	port
	     (incoming symon(8)	traffic) and the tcp port for incoming listen-

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

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

     Here is an	example	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
     symon(8) on localhost.  symux will	also listen on tcp port	2100 for in-
     coming listeners.

	   mux 2100
	   source {
	       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"

     symux offers received symon(8) data to other programs via tcp. An example
     of	a listener session:

	   nexus:~/project/symon$ telnet 2100
	   Connected to
	   Escape character is '^]'.;mem::1077662160:7630848:53850112:469417984:0:25600;cpu:0:

	   telnet> close
	   Connection closed.

     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 ).
	     Total 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,
	     errors_out, collisions, drops ). Values are 32 bit	unsigned inte-

     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 : pack-
	     ets_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_bad-
	     offset : counters_fragment	: counters_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 de-
	     pends on sensor type.

     smart   SMART attributes (	read_error_rate: reallocated_sectors: spin_re-
	     tries: air_flow_temp: temperature:	reallocations: current_pend-
	     ing: uncorrectables: soft_read_error_rate:	g_sense_error_rate:
	     temperature2: 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.

     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.

	     Contains the program id of	the symux daemon.

	     symux system wide configuration file.

     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

     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.

     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.

     Willem Dijkstra <>. Daniel Hartmeier helped to port to big-
     endian architectures. Matthew Gream helped	to port	symon to other BSD

     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.


BSD				 April 4, 2012				   BSD


Want to link to this manual page? Use this URL:

home | help