===============================================================================
 Content
 Version: $Id$
===============================================================================

1. how to install sources

2. sources bundled with serverstats
  2.1. apache
  2.2. disk
  2.3. external
  2.4. memory
  2.5. users
  2.6. cpu
  2.7. load
  2.8. mysql
  2.9. traffic
  2.10. traffic_proc
  2.11. ping
  2.12. ping_http
  
3. additional sources

4. how to configure a graph 

===============================================================================
 1. how to install sources
===============================================================================

If you want to install a source, there must be a source class in sources/
directory of serverstats. serverstats comes with a brunch of sources (see "2.
sources bundled with serverstats"), but only a few of them work without any
configuration. Those simple sources/graphs can be found in config.sample/.
Simply by copying config.sample/ to config/ you will get some nice graphs,
usually without an further configuration (beside the update.php cronjob).

But if you want to use more advanced sources, you have to change the
serverstats configuration.

If you want to use one of the bundled sources, you only have to add a line in
config/sources.php:

  $config[<sourcemodulname>]['module'] = new <sourcemodulname>([parameters]);

<sourcemodulname> is the name of the source, e.g. "disk" for sources/disk.php.

[parameters] is sometimes needed, sometimes not, depending on the specific
source. That's what chapter 2 ("sources bundled with serverstats") is for, it
describes the parameters which can/must be provided.

Available [parameters] can also be found in __construct() methode from
sources/<sourcemodulname>.php. Here you can find out which [parameter] is
mandatory and which is optional.

An example line from sources/disk.php:

  public function __construct($disk, $withpartitions = false,
      $sector_size = 512, $path_stat = '/proc/diskstats')

here $disk is a mandatory [parameter] (e.g. 'hda'), all the other [parameters]
have default values like $path_stat = '/proc/diskstats' which don't need to be
changed if the default is OK. So the line in config/sources.php for the disk
source could look like this:

  $config['disk']['module'] = new disk('hda');

If you have a "sector size" of 1024 and not the default 512, you have to pass
something like that: 

  $config['disk']['module'] = new disk('hdb', false, 1024);

If a parameter has no default value, it must be provided in config/sources.php.

If you want to use an additional source, not one of the bundled ones, you have
to install the source class in the sources/ directory and add a corresponding
line in config/sources.php:

  $config[<sourcemodulname>]['module'] = new <sourcemodulname>([parameters]);

For information about the correct settings for <sourcemodulname> and
[parameters] ask the author of the source, or have a look at 
sources/<sourcemodulname>.php again (as described above for bundled sources).

See chapter 3. ("additional sources") for further information. 

===============================================================================
 2. sources bundled with serverstats
===============================================================================

Here we provide information, on how to install specific sources, which are
bundled with serverstats. You can find the sources in  sources/ directory of
the serverstats archive.

"Parameters" describes all available parameters for config/sources.php:

  $config[<sourcemodulname>]['module'] = new <sourcemodulname>([parameters]);

"Datasources" describes the available datasources ('ds') which can be displayed
by a graph, see doc/graph-config.txt for details.

"Additional configuration" provides information for sources, which don't work
by configuring serverstats only, but needs external software to read the data.

===============================================================================
 2.1. apache
===============================================================================

Reads the statistics created by apache. This is done by accessing
"http://localhost/server-status?auto" by default.

Parameters:
$url: URL to fetch Apache-Stats
	Format: URL-String
	Default: "http://localhost/server-status?auto"
$show: List of Variables that should be saved
	Format:
		array(
			APACHE_NAME1 => DS_NAME1,
			APACHE_NAME2 => DS_NAME2,
			APACHE_NAME3 => DS_NAME3,
			...
		)
	Default:
		array(
			'Total Accesses' => 'requests',
			'Total kBytes' => 'kilobytes',
			'BytesPerReq' => 'bytesperreq',
			'CPULoad' => 'cpuload',
			'BusyWorkers' => 'busyprocs',
			'IdleWorkers' => 'idleprocs'
		)
$psshow: List of Variables that should be saves in per-second-values
	Format:
		array(
			DS_NAME1 => PS_DS_NAME1,
			DS_NAME2 => PS_DS_NAME2,
			DS_NAME3 => PS_DS_NAME3,
			...
		)
	Default:
		array(
			'requests' => 'requestsps',
			'kilobytes' => 'kilobytesps'
		)

Additional configuration:
Apache must generate the statsitics, this can be activated by adding the
following configuration to httpd.conf:
---------8<-----------------------------------------------
<Location /server-status>
	SetHandler server-status
	Order deny,allow
	Deny from all
	Allow from 127.0.0.1
</Location>
ExtendedStatus On
----------------------------------------------->8---------

Datasources:
As defined above.
(Default: requests, kilobytes, bytesperreq, cpuload, busyprocs, idleprocs,
requestsps, kilobytesps)

===============================================================================
 2.2. disk
===============================================================================

Reads the disk-statistics from /proc/diskstats (kernel 2.6) and saves the
read/written bytes. Optional all Partitions can be logged, too.

Parameters:
$disk: Name of disk that should be monitored (example: 'hda')
	Format: String
$withpartitions: Decide wether you want to log the partitions
	Format: boolean
	Default: false
$sector_size: Size of the Sectors of your disk
	Format: integer
	Default: 512
$path_stat: Filename to the needed /proc/-file
	Format: String
	Default: '/proc/diskstats'

Datasources:
	read: Bytes read
	write: Bytes written
	readps: Bytes read per second
	writeps: Bytes written per second
	partX_read, partX_write, partX_readps, partX_writeps:
		Same for partitions

===============================================================================
 2.3. external
===============================================================================

Runs an external script and reads the data provided by the script. Format to
fetch the data is similar to cacti.

Parameters:
$command: Command that should be executed

Additional Methods:
addDatasourceDefinition(...):
	Parameters:
		$name: Name of the Variable outputted by the command
		$type = 'GAUGE': See rrdtool manual
		$heartbeat = null
		$min = 'U'
		$max = 'U'

Datasources:
Depends on command.

===============================================================================
 2.4. memory
===============================================================================

Reads /proc/meminfo and logs selected variables from the file.

Parameters:
$show: List of Variables that should be saved
	Default:
		array(
			'MemTotal',
			'MemFree',
			'Cached',
			'SwapCached',
			'SwapTotal',
			'SwapFree'
		)
	Format:
		array(
			NAME1,
			NAME2,
			NAME3,
			...
		)
$meminfofile: Filename to the needed /proc/-file
	Format: String
	Default: '/proc/meminfo'

Datasources:
As defined above.
(Default: MemTotal, MemFree, Cached, SwapCached, SwapTotal, SwapFree)

===============================================================================
 2.5. users
===============================================================================

Runs 'users' and logs the number of users logged in.

Parameters:
$usersbin: Path to the user-binary
	Format: String
	Default: '/usr/bin/users'

Datasources:
	users: Number of users logged in

===============================================================================
 2.6. cpu
===============================================================================

Reads /proc/stat and caclulate the usage of the CPU.
(sys: XX%, user: XX%, idle: XX%, nice: XX%)

Parameters:
$path_stat: Path to the needed /proc/-file
	Format: String
	Default: '/proc/stat'

Datasources:
	cpu_user: Userprocesses in percent
	cpu_nice: Niced processes in percent
	cpu_system: Systemprocesses in percent
	cpu_idle: CPU-idle in percent
	cpuX_user, cpuX_nice, cpuX_system, cpuX_idle:
		Same for multiple processors

===============================================================================
 2.7. load
===============================================================================

Reads /proc/loadavg and logs the load of the system.

Parameters:
$loadavgfile: Path to the needed /proc/-file
	Format: String
	Default: '/proc/loadavg'

Datasources:
	1min: load, 1min average
	5min: load, 5min average
	15min: load, 15min average
	running: number of running tasks
	tasks: number of tasks

===============================================================================
 2.8. mysql
===============================================================================

Logs into a mysql-server and fetches some statistics.

Parameters:
$user: MySQL-User
	Format: String
	Default: 'status'
$password: MySQL-Password
	Format: String
	Default: ''
$host: MySQL-Host
	Format: String
	Default: 'localhost'

Datasources:
	questions: Number of questions 
	questionsps: Number of questions per second
	processcount: Current count of "SHOW PROCESSLIST"

===============================================================================
 2.9. traffic
===============================================================================

Uses an external script and some iptables-rules to log the traffic.

Additional configuration:
	iptables-rules:
		Create iptables-rules similar to the sample in
		sources/traffic/iptables.sample. Every port/daemon you want to
		log needs his own chain. If you want to have seperate logs for
		incoming and outgoing traffic you have to use different chains
		for that, too.
	traffic.sh:
		This script runs 'iptables -nvxL' to fetch the current
		trafficcounters from iptables. It iterates through an list of
		chains (CHAINLIST) and writes a file with the current counter
		for each chain. The files are stored in LOGPATH, this path
		should be set according to the example in the script.
		The script must be run as a cronjob by root to save the values.

Parameters:
$chain: Name of the chain
	Format: String
$logdir: Path where traffic.sh stores the logs
	Format: String
	Default: SOURCEPATH . 'traffic'
		(SOURCEPATH is autoset to the path where the sources are stored)

Datasources:
	traffic: Trafficcounter
	bps: Bytes per second

===============================================================================
 2.10. traffic_proc
===============================================================================

Uses '/proc/net/dev' to log the traffic (Bytes, Packets)
  no additional config like iptables or snmp needed.

Parameters:
$ifs: network interface
	Format: String
	Default: 'eth0'
$procfile: Path to the needed /proc/-file 
	Format: String
	Default: '/proc/net/dev'
	
Datasources:
	rbytes: Downloaded Bytes
	rpackets: Downloaded Packets
	tbytes: Uploaded Bytes
	tpackets: Uploaded Packets
	
The datasources for graph.php config ('ds') have to be assembled by the $ifs
and the "Datasources", e.g.:

  'ds' => 'eth0_rbytes',

===============================================================================
 2.11. ping
===============================================================================

Uses 'ping' to ping some server.

Parameters:
$host: Host, that should be pinged
	Format: String
$ping_opts: Options passed to ping
	change it for other UNIX-systems than linux, should tell ping to have
	a timeout of one second and to only send one ping
	Format: String
	Default: '-c 1 -W 1'
$ping_exec: Path to ping
	Format: String
	Default: '/bin/ping'
	
Datasources:
	time: Time in ms
	

===============================================================================
 2.12. ping_http
===============================================================================

Connects to a HTTP-server and measures the time a request takes.

Parameters:
$host: HTTP-server
	Format: String
$port: Port of the HTTP-daemon
	Format: integer
	Default: 80
$path: Remote path that should be requested
	Format: String
	Default: '/'
$command: HTTP-command
	Format: String (only 'HEAD' or 'GET')
	Default: 'HEAD'
$timeout: Timeout in seconds
	Format: integer
	Default: 1
	
Datasources:
	time: ping-time in ms
	open: delay to open the connection
	send: delay to send the request
	receive: delay to receive the respons
	close: delay to close the connection
	
===============================================================================
 3. additional sources
===============================================================================

Additional sources, provided by users of serverstats can be found (and 
submitted) here:

http://serverstats.berlios.de/sources.html

===============================================================================
4. how to configure a graph 
===============================================================================

Have a look at doc/graph-config.txt