SYMUX(8)

NAME
symux - symon stream multiplexer

SYNOPSIS
symux [-dltv] [-f filename]

DESCRIPTION
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 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 information 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 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:

    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" | "time" |
                   "wg"
    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 (incoming 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 number 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 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.

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

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

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

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.

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

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_retries: air_flow_temp: temperature: reallocations: current_pending: uncorrectables: soft_read_error_rate: g_sense_error_rate: temperature2: free_fall_protection ). Values depend on drive model and may change between models.

time
    Micro seconds ( usec ) taken to do all symon measurements. This stream can be used by developers to validate new probe cpu time cost. Value is a 32 bit unsigned integer.

wg  WireGuard peer counters ( rxbytes : txbytes : lasthandshake ). rxbytes and txbytes are 64 bit unsigned integers. lasthandshake is a 32 bit unsigned integer.

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 incoming measurements.

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

LEGACY FORMATS
symux supports symon(8) clients that send

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-endian architectures. Matthew Gream helped to port symon to other BSD platforms.

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

SEE ALSO
symon(8)