- Added config file option to enable/disable pluginsv0.1.2

- Switched from ConfigParser to RawConfigParser
- Renamed doc/README.txt to doc/DESIGN.txt
- Added tuned.conf man page
- Updated tuned man page
- Updated package descriptions (#487312)
- Added documentation for utils scripts (#487312)

13 files changed, 257 insertions, 26 deletions

diff --git a/Makefile b/Makefile
index 8788a76..c26a8d6 100644
--- a/Makefile
+++ b/Makefile
@@ -9,7 +9,7 @@ GITTAG = v$(VERSION)
 
 DIRS = doc contrib tuningplugins monitorplugins
 FILES = tuned tuned.spec Makefile tuned.py tuned.initscript tuned.conf
-FILES_doc = doc/README.txt doc/TIPS.txt doc/tuned.8
+FILES_doc = doc/DESIGN.txt doc/README.utils doc/TIPS.txt doc/tuned.8 doc/tuned.conf.5
 FILES_contrib = contrib/diskdevstat contrib/netdevstat
 FILES_tuningplugins = tuningplugins/disk.py tuningplugins/net.py tuningplugins/__init__.py
 FILES_monitorplugins = monitorplugins/disk.py monitorplugins/net.py monitorplugins/__init__.py
@@ -78,9 +78,11 @@ install:
 	mkdir -p $(DESTDIR)/etc/rc.d/init.d
 	install -m 0755 tuned.initscript $(DESTDIR)/etc/rc.d/init.d/tuned
 
-	# Install manpage
+	# Install manpages
 	mkdir -p $(DESTDIR)/usr/share/man/man8
 	install -m 0644 doc/tuned.8 $(DESTDIR)/usr/share/man/man8
+	mkdir -p $(DESTDIR)/usr/share/man/man5
+	install -m 0644 doc/tuned.conf.5 $(DESTDIR)/usr/share/man/man5
 
 changelog:
 	git-log > ChangeLog
diff --git a/README b/README
index 954d73c..1e3cb81 100644
--- a/README
+++ b/README
@@ -19,21 +19,51 @@ along with this program; if not, write to the Free Software
 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 
 
-SYNOPSIS
-       tuned [options]
+How to use
+----------
 
-DESCRIPTION
-       tuned is a dynamic adaptive system tuning daemon that tunes system settings dynamically depending on usage.
+After installing the package you simply need to start the tuned
+service either with system-config-services or from the
+commandline in a rootshell via:
 
-OPTIONS
-       -d, --daemon
-                   This options starts tuned as a daemon as opposed to in the foreground without forking at startup.
+  service tuned start
 
-       -c, --conffile="conffile"
-                   Specify the name and path of the configuration file, default is /etc/tuned.conf.
+You can also automatically start it during system startup by
+switching it on via chkconfig:
 
-BUGS
-       There are no known bugs.  To file bug reports, see AUTHORS below.
+  chkconfig tuned on
 
-AUTHOR
-       Written by Phil Knirsch <pknirsch@redhat.com>.
+After that the daemon will run automatically and monitor the
+usage of various system components. Based on that information
+components will then be put into lower or higher power saving
+modes to adapt to the current usage. Currently only ethernet
+network and and ATA harddisk devices are implemented.
+
+The config file /etc/tuned.conf contains several sections in
+INI style. There is always a "main" section which controls
+overall options of the daemon. Currently only 1 option
+is available:
+
+interval:  Interval for monitoring and tuning in seconds.
+           Default is 10.
+
+Each monitoring and tuning plugin has an own section then.
+Currently only 1 option for plugins is available:
+
+enabled: Enabled or disable the plugin. Default is True.
+         Any other value disables it.
+
+WARNING: At the moment there is a small incompatibility with
+tuned and NetworkManager which will results in connectivity
+loss if you are using tuned and your network devices are
+controlled by NetworkManager. This will be fixed in a future
+version of tuned and NetworkManager. At the moment there
+are two workarounds:
+
+1) Don't use NetworkManager for your Ethernet devices but
+configure them with system-config-network and enable the
+network service.
+2) Disabled the network tuning in tuned by editing
+/etc/tuned.conf and uncomment the
+# enabled=False
+line in the NetTuning section.
diff --git a/doc/README.txt b/doc/DESIGN.txt
index 40a1d9f..40a1d9f 100644
--- a/doc/README.txt
+++ b/doc/DESIGN.txt
diff --git a/doc/README.utils b/doc/README.utils
new file mode 100644
index 0000000..66f9937
--- /dev/null
+++ b/doc/README.utils
@@ -0,0 +1,94 @@
+Systemtap disk and network statistic monitoring tools
+=====================================================
+
+The netdevstat and diskdevstat are 2 systemtap tools that allow the user to
+collect detailed information about network and disk aktivity of all
+applications running on a system. These 2 tools were insipred by powertop,
+which shows the wakeups of applications per second.
+
+The basic idea is to collect statistic about the running applications in a
+form that allows a user to identify applications that behave power
+inefficient, meaning instead of doing fewer and bigger IO operations they
+do more and smaller ones. Current monitoring tools typically only show
+the transfer speeds which isn't very meaningful in that context.
+
+To run them you need to have systemtap and kernel-debuginfo installed.
+If both are installed a simple
+
+ netdevstat
+
+or
+
+ diskdevstat
+
+will start the scripts. There are no parameters or options for them. The
+output will look similar to top and/or powertop. Here a sample output of
+a longer diskdevstat run on a Fedora 10 system running KDE 4.2:
+
+
+  PID   UID DEV     WRITE_CNT WRITE_MIN WRITE_MAX WRITE_AVG    READ_CNT  READ_MIN  READ_MAX  READ_AVG COMMAND        
+ 2789  2903 sda1          854     0.000   120.000    39.836           0     0.000     0.000     0.000 plasma            
+15494     0 sda1            0     0.000     0.000     0.000         758     0.000     0.012     0.000 0logwatch         
+15520     0 sda1            0     0.000     0.000     0.000         140     0.000     0.009     0.000 perl              
+15549     0 sda1            0     0.000     0.000     0.000         140     0.000     0.009     0.000 perl              
+15585     0 sda1            0     0.000     0.000     0.000         108     0.001     0.002     0.000 perl              
+ 2573     0 sda1           63     0.033  3600.015   515.226           0     0.000     0.000     0.000 auditd            
+15429     0 sda1            0     0.000     0.000     0.000          62     0.009     0.009     0.000 crond             
+15379     0 sda1            0     0.000     0.000     0.000          62     0.008     0.008     0.000 crond             
+15473     0 sda1            0     0.000     0.000     0.000          62     0.008     0.008     0.000 crond             
+15415     0 sda1            0     0.000     0.000     0.000          62     0.008     0.008     0.000 crond             
+15433     0 sda1            0     0.000     0.000     0.000          62     0.008     0.008     0.000 crond             
+15425     0 sda1            0     0.000     0.000     0.000          62     0.007     0.007     0.000 crond             
+15375     0 sda1            0     0.000     0.000     0.000          62     0.008     0.008     0.000 crond             
+15477     0 sda1            0     0.000     0.000     0.000          62     0.007     0.007     0.000 crond             
+15469     0 sda1            0     0.000     0.000     0.000          62     0.007     0.007     0.000 crond             
+15419     0 sda1            0     0.000     0.000     0.000          62     0.008     0.008     0.000 crond             
+15481     0 sda1            0     0.000     0.000     0.000          61     0.000     0.001     0.000 crond             
+15355     0 sda1            0     0.000     0.000     0.000          37     0.000     0.014     0.001 laptop_mode       
+ 2153     0 sda1           26     0.003  3600.029  1290.730           0     0.000     0.000     0.000 rsyslogd          
+15575     0 sda1            0     0.000     0.000     0.000          16     0.000     0.000     0.000 cat               
+15581     0 sda1            0     0.000     0.000     0.000          12     0.001     0.002     0.000 perl              
+15582     0 sda1            0     0.000     0.000     0.000          12     0.001     0.002     0.000 perl              
+15579     0 sda1            0     0.000     0.000     0.000          12     0.000     0.001     0.000 perl              
+15580     0 sda1            0     0.000     0.000     0.000          12     0.001     0.001     0.000 perl              
+15354     0 sda1            0     0.000     0.000     0.000          12     0.000     0.170     0.014 sh                
+15584     0 sda1            0     0.000     0.000     0.000          12     0.001     0.002     0.000 perl              
+15548     0 sda1            0     0.000     0.000     0.000          12     0.001     0.014     0.001 perl              
+15577     0 sda1            0     0.000     0.000     0.000          12     0.001     0.003     0.000 perl              
+15519     0 sda1            0     0.000     0.000     0.000          12     0.001     0.005     0.000 perl              
+15578     0 sda1            0     0.000     0.000     0.000          12     0.001     0.001     0.000 perl              
+15583     0 sda1            0     0.000     0.000     0.000          12     0.001     0.001     0.000 perl              
+15547     0 sda1            0     0.000     0.000     0.000          11     0.000     0.002     0.000 perl              
+15576     0 sda1            0     0.000     0.000     0.000          11     0.001     0.001     0.000 perl              
+15518     0 sda1            0     0.000     0.000     0.000          11     0.000     0.001     0.000 perl              
+15354     0 sda1            0     0.000     0.000     0.000          10     0.053     0.053     0.005 lm_lid.sh         
+
+
+Here a quick explanation of each column:
+
+PID:       Process ID of the application
+UID:       User ID under which the applications is running
+DEV:       Device on which the IO took place
+WRITE_CNT: Total number of write operations
+WRITE_MIN: Lowest time in seconds for 2 consecutive writes
+WRITE_MAX: Largest time in seconds for 2 consecutive writes
+WRITE_AVG: Average time in seconds for 2 consecutive writes
+READ_CNT:  Total number of read operations
+READ_MIN:  Lowest time in seconds for 2 consecutive reads
+READ_MAX:  Largest time in seconds for 2 consecutive reads
+READ_AVG:  Average time in seconds for 2 consecutive reads
+COMMAND:   Name of the process
+
+In this example 3 very obvious applications stand out:
+
+  PID   UID DEV     WRITE_CNT WRITE_MIN WRITE_MAX WRITE_AVG    READ_CNT  READ_MIN  READ_MAX  READ_AVG COMMAND
+ 2789  2903 sda1          854     0.000   120.000    39.836           0     0.000     0.000     0.000 plasma
+ 2573     0 sda1           63     0.033  3600.015   515.226           0     0.000     0.000     0.000 auditd
+ 2153     0 sda1           26     0.003  3600.029  1290.730           0     0.000     0.000     0.000 rsyslogd
+
+Those are the 3 applications that have a WRITE_CNT > 0, meaning they performed
+some form of write during the measurement. Of those, plasma was the worst
+offender by a large amount. For one in total number of writes and of course
+the average time between writes was also the lowest. This would be the best
+candidate to investigate if you're concerned about power inefficient
+applications.
diff --git a/doc/tuned.8 b/doc/tuned.8
index 85b1209..abd1f6c 100644
--- a/doc/tuned.8
+++ b/doc/tuned.8
@@ -1,4 +1,4 @@
-.TH tuned 8 "25 Feb 2009"
+.TH "tuned" "8" "25 Feb 2009" "Phil Knirsch" "adaptive system tuning daemon"
 .SH NAME
 tuned \- dynamic adaptive system tuning daemon
 .SH SYNOPSIS
@@ -6,7 +6,10 @@ tuned \- dynamic adaptive system tuning daemon
 .SH DESCRIPTION
 \fBtuned\fR is a dynamic adaptive system tuning daemon
 that tunes system settings dynamically depending on
-usage.
+usage. It does so by monitoring the usage of several system components
+periodically. Based on that information components will then be put into
+lower or higher power saving modes to adapt to the current usage. Currently
+only ethernet network and ATA harddisk devices are implemented.
 .SH OPTIONS
 .TP 12
 .BI \-d "\fR, \fP" \--daemon
@@ -16,7 +19,19 @@ in the foreground without forking at startup.
 .BI \-c "\fR, \fP" \--conffile=" conffile"
 Specify the name and path of the configuration file, default is \fB/etc/tuned.conf\fR.
 .SH BUGS
-There are no known bugs.  To file bug reports, see \fBAUTHORS\fP below.
+If you are using tuned together with NetworkManager at the moment NetworkManager
+will completely stop and start a managed device when tuned switches power
+saving levels. This happens because the network device will loose it's physical
+link for a very short time when it performs a power saving switch and
+NetworkManager can not distinguish this from a connectivity loss. This will be
+resolved in future versions of tuned and NM where NM will gain the mechanism to
+switch speeds for network devices.
+.SH "FILES"
+.nf
+/etc/tuned.conf
+.SH "SEE ALSO"
+.LP
+tuned.conf(5)
 .SH AUTHOR
 Written by Phil Knirsch <pknirsch@redhat.com>.
 .SH REPORTING BUGS
diff --git a/doc/tuned.conf.5 b/doc/tuned.conf.5
new file mode 100644
index 0000000..fea5655
--- /dev/null
+++ b/doc/tuned.conf.5
@@ -0,0 +1,37 @@
+.TH "tuned.conf" "5" "26 Feb 2009" "Phil Knirsch" "tuned configuration file"
+.SH "NAME"
+.LP
+\fBtuned.conf\fR \- Configuration file for \fBtuned(8)\fR.
+.SH "DESCRIPTION"
+.LP
+The tuned configuration file is by default found at \fB/etc/tuned.conf\fR.
+.SH "PARAMETERS"
+.LP
+The tuned.conf file must always contain a [main] section. The main section
+defines general parameters for the daemon. Each plugin may have a
+section with plugin specific parameters.
+.SH "[main] OPTIONS"
+.LP
+The [main] section must exist for tuned. It contains the following
+options:
+
+.IP \fBinterval\fR
+Interval for monitoring and tuning in seconds. The default is 10.
+
+.SH "[plugin] OPTIONS"
+.LP
+Each plugin can have an individual section with the name of the plugin as
+the section name. All plugins support at least the following options:
+
+.IP \fBenabled\fR
+Enabled or disable the plugin. Default is True. Any other value disables it.
+.SH "FILES"
+.nf
+/etc/tuned.conf
+.SH "SEE ALSO"
+.LP
+tuned(8)
+.SH AUTHOR
+Written by Phil Knirsch <pknirsch@redhat.com>.
+.SH REPORTING BUGS
+Report bugs to <pknirsch@redhat.com>.
diff --git a/monitorplugins/disk.py b/monitorplugins/disk.py
index 6167c84..2b58220 100644
--- a/monitorplugins/disk.py
+++ b/monitorplugins/disk.py
@@ -21,6 +21,7 @@ import os
 class DiskMonitor:
 	def __init__(self):
 		self.devices = {}
+		self.enabled = True
 		dnames = os.listdir("/sys/block/")
 		for d in dnames:
 			try:
@@ -58,11 +59,15 @@ class DiskMonitor:
 
 	def init(self, config):
 		self.config = config
+		if self.config.has_option("DiskMonitor", "enabled"):
+			self.enabled = (self.config.get("DiskMonitor", "enabled") == "True")
 
 	def cleanup(self):
 		pass
 
 	def getLoad(self):
+		if not self.enabled:
+			return
 		self.__update__()
 		ret = {}
 		ret["DISK"] = {}
diff --git a/monitorplugins/net.py b/monitorplugins/net.py
index bf806f7..6051b5c 100644
--- a/monitorplugins/net.py
+++ b/monitorplugins/net.py
@@ -21,6 +21,7 @@ import os
 class NetMonitor:
 	def __init__(self):
 		self.devices = {}
+		self.enabled = True
 		devs = open("/proc/net/dev").readlines()
 		for l in devs:
 			l = l.replace(":", " ")
@@ -64,6 +65,8 @@ class NetMonitor:
 
 	def init(self, config):
 		self.config = config
+		if self.config.has_option("NetMonitor", "enabled"):
+                        self.enabled = (self.config.get("NetMonitor", "enabled") == "True")
 		interval = self.config.getint("main", "interval")
 		# Assume 1gbit interfaces for now. FIXME: Need clean way to figure out max interface speed
 		for d in self.devices.keys():
@@ -73,6 +76,8 @@ class NetMonitor:
 		pass
 
 	def getLoad(self):
+		if not self.enabled:
+			return
 		self.__update__()
 		ret = {}
 		ret["NET"] = {}
diff --git a/tuned.conf b/tuned.conf
index 793d81e..96f8b89 100644
--- a/tuned.conf
+++ b/tuned.conf
@@ -4,24 +4,36 @@
 
 [main]
 # Interval for monitoring and tuning. Default is 10s.
-interval=10
+# interval=10
 
 #
 # Disk monitoring section
 #
 [DiskMonitor]
+# Enabled or disable the plugin. Default is True. Any other value
+# disables it.
+# enabled=False
 
 #
 # Disk tuning section
 #
 [DiskTuning]
+# Enabled or disable the plugin. Default is True. Any other value
+# disables it.
+# enabled=False
 
 #
 # Net monitoring section
 #
 [NetMonitor]
+# Enabled or disable the plugin. Default is True. Any other value
+# disables it.
+# enabled=False
 
 #
 # Net tuning section
 #
 [NetTuning]
+# Enabled or disable the plugin. Default is True. Any other value
+# disables it.
+# enabled=False
diff --git a/tuned.py b/tuned.py
index 773359a..cf12152 100644
--- a/tuned.py
+++ b/tuned.py
@@ -38,7 +38,7 @@ class Tuned:
 			store.append(_plugin)
 
 	def init(self, path, cfgfile):
-		self.config = ConfigParser.ConfigParser()
+		self.config = ConfigParser.RawConfigParser()
 		self.config.read(cfgfile)
 		if self.config.has_option("main", "interval"):
 			self.interval = self.config.getint("main", "interval")
diff --git a/tuned.spec b/tuned.spec
index d8b8728..72cda35 100644
--- a/tuned.spec
+++ b/tuned.spec
@@ -1,6 +1,6 @@
 Summary: A dynamic adaptive system tuning daemon
 Name: tuned
-Version: 0.1.1
+Version: 0.1.2
 Release: 1%{?dist}
 License: GPLv2+
 Group: System Environment/Daemons
@@ -21,15 +21,22 @@ BuildArch: noarch
 
 %description
 The tuned package contains a daemon that tunes system settings dynamically.
+It does so by monitoring the usage of several system components periodically.
+Based on that information components will then be put into lower or higher
+power saving modes to adapt to the current usage. Currently only ethernet
+network and ATA harddisk devices are implemented.
 
 %package utils
-Summary: Disk and net monitoring systemtap scripts
+Summary: Disk and net statistic monitoring systemtap scripts
 Requires: systemtap kernel-debuginfo
 Group: Applications/System
 
 %description utils
 The tuned-utils package contains several systemtap scripts to allow detailed
-manual monitoring of the system.
+manual monitoring of the system. Instead of the typical IO/sec it collects
+minimal, maximal and average time between operations to be able to
+identify applications that behave power inefficient (many small operations
+instead of fewer large ones).
 
 %prep
 %setup -q
@@ -59,20 +66,31 @@ fi
 
 %files
 %defattr(-,root,root,-)
-%doc AUTHORS ChangeLog COPYING INSTALL NEWS README doc/README.txt doc/TIPS.txt
+%doc AUTHORS ChangeLog COPYING INSTALL NEWS README doc/DESIGN.txt doc/TIPS.txt
 %{_initddir}/tuned
 %config(noreplace) %{_sysconfdir}/tuned.conf
 %{_sbindir}/tuned
 %{_datadir}/tuned
+%{_mandir}/man5/*
 %{_mandir}/man8/*
 
 %files utils
+%doc doc/README.utils
 %defattr(-,root,root,-)
 %{_sbindir}/netdevstat
 %{_sbindir}/diskdevstat
 
 
 %changelog
+* Thu Feb 26 2009 Phil Knirsch <pknirsch@redhat.com> - 0.1.2-1
+- Added config file option to enable/disable plugins
+- Switched from ConfigParser to RawConfigParser
+- Renamed doc/README.txt to doc/DESIGN.txt
+- Added tuned.conf man page
+- Updated tuned man page
+- Updated package descriptions (#487312)
+- Added documentation for utils scripts (#487312)
+
 * Wed Feb 25 2009 Phil Knirsch <pknirsch@redhat.com> - 0.1.1-1
 - Bump version
 - Added comment in empty __init__.py files
diff --git a/tuningplugins/disk.py b/tuningplugins/disk.py
index d255252..a97433a 100644
--- a/tuningplugins/disk.py
+++ b/tuningplugins/disk.py
@@ -21,6 +21,7 @@ import os, copy
 class DiskTuning:
 	def __init__(self):
 		self.devidle = {}
+		self.enabled = True
 
 	def __updateIdle__(self, dev, devload):
 		idle = self.devidle.setdefault(dev, {})
@@ -35,12 +36,17 @@ class DiskTuning:
 
 	def init(self, config):
 		self.config = config
+		if self.config.has_option("DiskTuning", "enabled"):
+                        self.enabled = (self.config.get("DiskTuning", "enabled") == "True")
 
 	def cleanup(self):
 		for dev in self.devidle.keys():
-			os.system("hdparm -S0 -B255 /dev/"+dev+" > /dev/null 2>&1")
+			if self.enabled and self.devidle[dev]["LEVEL"] > 0:
+				os.system("hdparm -S0 -B255 /dev/"+dev+" > /dev/null 2>&1")
 
 	def setTuning(self, load):
+		if not self.enabled:
+			return
 		disks = load.setdefault("DISK", {})
 		for dev in disks.keys():
 			devload = disks[dev]
diff --git a/tuningplugins/net.py b/tuningplugins/net.py
index 1ef11c6..ecb4c20 100644
--- a/tuningplugins/net.py
+++ b/tuningplugins/net.py
@@ -21,6 +21,7 @@ import os, copy
 class NetTuning:
 	def __init__(self):
 		self.devidle = {}
+		self.enabled = True
 
 	def __updateIdle__(self, dev, devload):
 		idle = self.devidle.setdefault(dev, {})
@@ -35,12 +36,18 @@ class NetTuning:
 
 	def init(self, config):
 		self.config = config
+		if self.config.has_option("NetTuning", "enabled"):
+                        self.enabled = (self.config.get("NetTuning", "enabled") == "True")
+
 
 	def cleanup(self):
 		for dev in self.devidle.keys():
-			os.system("ethtool -s "+dev+" advertise 0x03F")
+			if self.enabled and self.devidle[dev]["LEVEL"] > 0:
+				os.system("ethtool -s "+dev+" advertise 0x03F")
 
 	def setTuning(self, load):
+		if not self.enabled:
+			return
 		disks = load.setdefault("NET", {})
 		for dev in disks.keys():
 			devload = disks[dev]