SysUsage v2.0 Installation and configuration instruction


REQUIREMENT:
------------

	You must have a moderm perl install. 5.6.0 or more is good.

	You need to install rrdtool. You can find it at:

		http://people.ee.ethz.ch/~oetiker/

	To use the RRDs perl module you must use the following command
	to compile the distrib:

		make site-perl-install

	You also need sar to collect statistics. Sar is part of the sysstat
	package. You can find it here :

		http://freshmeat.net/projects/sysstat/

	If you plan to use thresold warning report you must have Net::SMTP.
	It can always be found at CPAN/


INSTALLATION:
-------------

	Simply run the install perl program and answer to the question.

	By default it will copy the perl programs into /usr/local/sysusage/bin
	and the HTML output will be done to /usr/local/apache/htdocs/sysusage/.
	The configuration file is created as /usr/local/sysusage/etc/sysusage.cfg
	and all Bekerley DB databases generated with rrdtool are done under
	/usr/local/sysusage/rrdfiles

	Add this line into crontab to run monitoring each minutes:

		*/1 * * * * /usr/local/sysusage/bin/sysusage

	Add this other line into crontab to draw graph each 5 minutes:

		*/5 * * * * /usr/local/sysusage/bin/sysusagegraph

	If you have change the default installation path of the configuration file
	you need to use option -c with the path of the configuration file. Example:

		*/1 * * * * /bin/sysusage -c /etc/sysusage.cfg

	Same with sysusagegraph.


CONFIGURATION
-------------

	You can edit the configuration file sysusage.cfg by hand, here is the format
	of the file with all default value. In this file there is three section. The
	first one set the general parameters of the application, the second set the
	parameter used to send SMTP alert at threshold exceed and the last configure
	all type of system information you may want to monitor.

		[GENERAL]
		DEBUG     = 0
		DATA_DIR  = /usr/local/sysusage/rrdfiles
		PID_FILE  = /usr/local/sysusage/etc
		DEST_DIR  = /usr/local/apache/htdocs/sysusage
		SAR_BIN   = /usr/bin/sar
		UPTIME    = /usr/bin/uptime
		HOSTNAME  = /bin/hostname
		INTERVAL  = 60

		[ALARM]
		WARN_MODE   = 1
		ALARM_PROG  = /usr/local/sysusage/bin/sysusagewarn
		SMTP        = localhost
		FROM        = root@localhost
		TO          = root@localhost

		[MONITOR]
		load:threshold_max_value
		cpu:threshold_max_value
		wait:threshold_max_value
		mem:threshold_max_value
		swap:threshold_max_value
		share:threshold_max_value
		sock:threshold_max_value
		io:threshold_max_value
		file:threshold_max_value
		page:threshold_max_value
		pcrea:threshold_max_value
		pswap:threshold_max_value
		net:threshold_max_value
		err:threshold_max_value
		disk:threshold_max_value
		proc:proc_name:threshold_max_value:threshold_min_value
		queue:path_queue_dir:threshold_max_value

	Section GENERAL

		DEBUG	= 0|1
			This option is used to set debug mode. If set to 1 then
			sysusage and sysusagegraph just show what they do
			but don't create or send anything.

		DATA_DIR  = /path/to/rrdfiles
			This option is used to set te ouput directory for all
			RRDTOOL database.

		PID_FILE  = /path/to/piddir
			sysusage and sysusagegraph use a file to store the
			pid of the running process to prevent simultaneous run.

		DEST_DIR  = /path/to/html_output
			Set the path to the directory where all HTML and graph
			files should be created.

		SAR_BIN   = /path/to/sar_binary
			sysusage use sar, part of the sysstat distribution to
			grab system information so we need to know where it is.

		UPTIME    = /path/to/uptime_binary
			sysusagegraph report the current uptime of the system
			using the uptime command. Used to set the path to uptime	
			binary.

		HOSTNAME  = /path/to/hostname_binary
			All scripts of Sysusage distribution need to know the name
			of the host. They use command hostname for that.

		INTERVAL  = pull_interval_in_second
			All RRDTOOL input use the given interval in second to store
			monitored values. Graph construction also use this interval
			to render things properly. By default Sysusage use an interval
			of 60 seconds to have a better statistic report. You can change
			this but it's not recommanded. If you change this adjust your
			crontab to the samse value.
			
	Section ALARM

		WARN_MODE   = 0|1
			Used to disable/enable SMTP alert message during threshold
			exceed.

		ALARM_PROG  = /path/to/sysusagewarn
			Used to set the path to the external program responsible of
			alarm message sending. You can change it to your own, just
			take a look at the sysusagewarn usage to see what command
			line options are used by sysusage

		SMTP        = smtp.server.net
			Name or Ip address of the SMTP server to contact. Default is
			localhost.

		FROM        = sender@localhost
			Sender email addresse to use in the SMTP message.

		TO          = destination@localhost
			Destination email address where the alarm message will be sent.



	Section MONITOR

	This section has two different format the first one is used to specify
	most of the monitoring type:

		type:threshold_max:threshold_min

	'type'

		Type of system information you may want to monitor. It can takes
		14 differents values:

			load  => monitor load average
			cpu   => monitor cpu(s) total/system/user usage
			wait  => monitor cpu(s) iowait/idle/steal usage
			mem   => monitor memory usage
			swap  => monitor swap usage
			share => monitor /dev/shm usage
			sock  => monitor number of open socket
			io    => monitor I/O request and block usage
			page  => monitor I/O page usage
			pswap => monitor I/O page swap usage
			pcrea => monitor the number of process created per second
			file  => monitor the percentage of open file regarding file-max
			net   => monitor I/O network bytes on all network interfaces
			err   => monitor bad packet, drop and collision on all network interfaces
			disk  => monitor disk space usage

		Note: last version of sysstat doesn't report the percentage of open file, sysusage
		try to compute the percentage with /proc/sys/fs/file-max. If it doesn't exists it simply
		report the number of open file.

	'threshold_max'

		This is the maximum threshold value. Any value equal or superior of this
		one will generate SMTP alert if you have enable it.

	'threshold_min'

		This is the minimum threshold value. Any value equal or inferior of
		this one will generate SMTP alert if you have enable it. Min threshold
		should certainly only be used with proc monitoring type. If you set it
		to 0 then you will be warn if any of the monitored process are down.

	The second format is used to monitor running process and queue directory.
	It has the following format:

		type:target:threshold_max_value:threshold_max_value

	'type'

		Type of system information you may want to monitor. It can takes
		two differents values:

			proc  => monitor number of running process
			queue => monitor number of files in a directory

	'target'

		If type is proc this represent the name of the process to monitor.
		If type is queue this represent the path of the directory to monitor.

	'threshold_max'

		This is the maximum threshold value. Any value equal or superior will
		generate SMTP alert if you have enable it.

	'threshold_min'

		This is the minimum threshold value. Any value equal or inferior of
		this one will generate SMTP alert if you have enable it. Min threshold
		should certainly only be used with proc monitoring type. If you set it
		to 0 then you will be warn if any of the monitored process are down.

There's a special case for disk usage monitoring that allow exclusion of some
mount point.

       disk:ThresholdMax:exclusion

where exclusion is a semicolon (;) separated list of mount point to exclude
from monitoring.


That's all...

--
Gilles Darold
