Laptop Mode Tools README
------------------------

Author:  Bart Samwel (bart@samwel.tk, http://www.xs4all.nl/~bsamwel)


Installation
------------

To install, run ./install.sh. That's all there's to it. This will install
laptop mode, which will be enabled automatically when your laptop works
on batteries.  Debian users, please install the Debian package that can
be found on the home page and in the unstable repository!


Notes
-----

* To configure the laptop mode scripts, edit /etc/laptop-mode/laptop-mode.conf.

* The original laptop mode documentation that was distributed with the Linux
  kernel is included in this package as Documentation/laptop-mode.txt. It
  contains additional documentation, tips and tricks.


History
-------

 0.90   24 July 2004   * Initial release
 
 0.91   25 July 2004   * Add experimental APM support
 
 0.92   25 July 2004   * Add support for doing hdparm on multiple hard drives
                       * Various other fixes (thanks to Peter Ross)
		       
 0.93   28 July 2004   * Various small fixes.
                       * Enable laptop mode when booting on battery. (Tested
		         only on Debian, feedback on other distributions
			 wanted!)
			 
 0.94   29 July 2004   * Added Debian packaging support. If you use Debian,
                         please use the package provided on the
			 laptop-mode-tools website.
                       * Moved laptop_mode script to /usr/sbin/laptop_mode,
		         because it uses programs in /usr.
		       * Moved Debian-style config file to
		         /etc/laptop-mode/laptop-mode.conf
		         (/etc/default/laptop-mode is intended only for
			 init-scripts.)
		       * Wrote manual pages (not installed in non-Debian for
		         now.)

 0.95   31 July 2004   * Moved Debian support into a separate patch.
                       * Fixed bashism in /etc/init.d/laptop-mode
		       * Move all config files to
		         /etc/laptop-mode/laptop-mode.conf
		       * Add support for "always-on", using
		         LAPTOP_MODE_ALWAYS_ON=1 in config file.

 0.96   05 Aug 2004    * Installer was broken in 0.95.
                       * APM scripts now support LAPTOP_MODE_ALWAYS_ON as well (i.e. they didn't before :) )
		       * chkconfig support in the init script

 0.97   12 Aug 2004    * Fixed bug in APM script -- it was backwards. :)
                       * Fixed default setting for HD.

 0.98   18 Aug 2004    * Fixed bug in ACPI battery script -- missing discharge
 			 rate would lead to division by zero.
		       * Added "auto" option to /usr/sbin/laptop_mode script.
		         This autodetects the AC state and enables/disables
			 laptop mode accordingly, using either on_ac_power
			 (if available) or using the /proc/acpi and /proc/apm
			 values.
		       * Modified the APM and ACPI event scripts to simply call "laptop_mode auto".

 0.99   18 Aug 2004    * Fixed bug that broke DO_CPU in the config file.

 1.00    3 Sep 2004    * Use update-rc.d to install init scripts. Init scripts
			 are now installed in the default runlevels, not in
			 the bootup/sysinit scripts.
		       * Reduced dependence on location of certain binaries,
		         depend more on PATH.
		       * Optimize away double actions -- if laptop mode is
		         already in the requested state, the laptop_mode
			 script now does nothing instead of re-initializing
			 laptop mode to the state it was already in.
		       * Laptop mode is now enabled using the "master switch"
		         /etc/init.d/laptop-mode. If it has not been called
			 with parameter "start", then "laptop_mode start"
			 will not start laptop mode. (The file that is used
			 to control this is /var/run/laptop-mode-enabled.)
		       * Reduced default value for LM_SECONDS_BEFORE_SYNC to 
		         2 (was 5, but this saves more power).
		       * Reduced default value for MINIMUM_BATTERY_MINUTES to
		         7 (was 10).
		       * Reduced default value for BATT_HD to 1 (5 seconds),
		         was 4 (20 seconds).
		       * Reduced default value for DIRTY_BACKGROUND_RATIO to
		         1 (was 5).
		       * Increased default value for DIRTY_RATIO to 60 (was
		         40 previously).
		       * Default value for HD changed to "/dev/hda /dev/hdb
		         /dev/hdc /dev/hdd".
		       * Corrected documentation to state that READAHEAD is in
		         kilobytes, not in 512-byte sectors.
		       * Added option ACPI_WITHOUT_AC_EVENTS. Use this if your
		         ACPI doesn't generate AC events but does generate
			 battery events.
		       

1.01    3 Oct 2004     * Updated commented-out default values for configuration
                         parameters in config file, which were not all updated
			 correctly in the previous version.
		       * Updated the version number 0.100 in the release notes
		         to 1.00. Just goes to show how long I doubted on
			 whether to call it 1.00. :)
		       * Changed the way the config file is read. Formerly used
		         the construct ${VAR:-'value'} to set defaults, now I
			 simply set the values and then source the config file.
			 The immediate effect of this is that the surrounding
			 environment cannot influence the laptop mode anymore,
			 moving the app closer to being safe to use suid. Note
			 that it is NOT SAFE to run laptop_mode suid at this
			 moment, I haven't taken all necessary security
			 measures!
		       * The "hdparm -B" values are now configurable using the
		         (AC|BATT)_HDPARM_POWERMGMT options. The option
			 DO_HD_POWERMGMT can be set to 0 to disable the -B
			 behaviour altogether.
		       * The "hdparm -B" calls are now done BEFORE the -S
		         calls. This is because some HDs change the -S setting
			 as an effect of using the -B option.
		       * Use "chkconfig" when it is available to install the
		         rc.d-to-init.d links. (Until now only update-rc.d was
			 supported.)
		       * AC_HD is split into AC_HD_WITH_LM and AC_HD_WITHOUT_LM.
		         The former value is used when AC power is present but
			 laptop mode is still enabled (e.g. when the option
			 LAPTOP_MODE_ALWAYS_ON is enabled). The latter value
			 is used when AC power is present and laptop mode is
			 disabled. The AC_HDPARM_POWERMGMT option has been split
			 in the same way. The old option AC_HD is still
			 supported, if the config file specifies it then it
			 overrides both new config values.
		       * Ripped usage of on_ac_power out of the script and
		         included native support for pmud. This is because
			 on_ac_power is part of apmd, and doesn't support pmud
			 natively (except for the Debian version, which does
			 support pmud). I don't want to depend on having apmd
			 installed or on running on a Debian distro.

1.02    3 Oct 2004     * Bugfix release. The calls to chkconfig in the installer
		         didn't work because the installer wrongfully detected
			 the presence of update-rc.d.

1.03   27 Oct 2004     * Add LM_WHEN_LID_CLOSED, to enable laptop mode when the
		         laptop's lid is closed. Only works on ACPI.
		       * Fixed incorrect default in a comment in the config
		         file.
		       * Fixed a bug in 1.01 which meant that laptop mode was
		         never enabled when using APM.

1.04    9 Nov 2004     * SEE ALSO sections in manpages updated to respect common
                         conventions.
		       * Mention path of laptop_mode script in manual page.
		       * Make AC detection work again on PMU (i.e. Mac) systems.
		       * Removed config file defaults. Simply define them in the
		         config file. They were a pain to maintain, and I had
			 to repeat them in several places (manual page, all
			 files in which the config was used), which was too
			 error-prone.
		       * Added support for syslog configuration switching
		         based on laptop mode and power state. See the new
			 config file and the accompanying manual page.
		       * Added support for forcing laptop mode start/stop
		         using second "force" option to /usr/sbin/laptop_mode.
		       * Added support for "/" in mount options. It was used
		         as a delimiter for the sed "s" command, and that
			 went wrong with loopback devices.
		       * Dropped the DocBook SGML sources for the manpages,
		         started working with pure nroff sources. The output
			 of docbook-to-man was crap recently, so I decided
			 to cut it out of the loop.

1.05	12 Apr 2005	* Detection of init.d or rc.d locations. Should make
			  things work better on Slackware.
			* Make things work if /proc/acpi/ac_adapter contains
			  no AC adapters.
			* Signal acpid to re-read its configuration after
			  installing.
			* Restore config file defaults, so that old config
			 files will keep working.
			* Made syslog daemon name configurable, so that you
			  can make it signal alternative syslog daemons.
			  (The signal to be sent still needs to be SIGHUP
			  though.)
			* Remove error output from "which" in the
			  install script. The result was handled gracefully
			  anyway, so why print the output?
			* New configuration setting REMOUNT_PARTITIONS.
			  Default is "", which means all partitions on the
			  drives listed in the HD option.
			* New configuration settings MINIMUM_BATTERY_CHARGE_MAH
			  and MINIMUM_BATTERY_CHARGE_MWH to specify the
			  minimum remaining charge in the battery for
			  laptop mode to remain enabled (in mAh and mWh,
			  respectively). This is intended
			  as a replacement for MINIMUM_BATTERY_MINUTES
			  for systems that don't specify a discharge rate.
			* When booting up on AC, laptop mode did not
			  set the correct syslog.conf, because it thought
			  "laptop mode is already disabled so I don't
			  need to do anything".
			* Added a manual page for lm-syslog-setup.
			* Attempt at support for pbbuttonsd and pmud. The
			  APM support files are no longer installed when
			  /proc/pmu exists (i.e. your system has PMU
			  support), because those interfere with the
			  native PMU support.
			* Lowered READAHEAD default from 8MB to 3MB. The
			  high readahead caused the system cache to be
			  flushed by too-large readaheads on other files.

1.06	28 Jul 2005	* Integration with pbbuttonsd that listens to the
			  user's power profile (thanks to Matthias Grimm).
			* "status" command for laptop_mode, displays all
			  kinds of useful stuff. Also supported by the
			  init script, as is standard in Fedora/RH.
			* Added option DO_WRITECACHE to enable laptop mode
			  tools control over write caching, and settings 
			  BATT_WRITECACHE, AC_WRITECACHE_WITH_LM and
			  AC_WRITECACHE_WITHOUT_LM to set the write caching
			  off or on depending on the power and laptop mode
			  state. This is ENABLED by default -- it always
			  sets write caching off when you are on laptop mode.
			* Support fstypes in fstab with fallbacks, e.g.
			  "ext3,ext2".
			* Allow REMOUNT_PARTITIONS to contain mount points
			  as well as devices.
			* Add "auto" keyword to REMOUNT_PARTITIONS, as a
			  way to indicate "all the default partitions".
			* Split CPU_MAXFREQ option into BATT_CPU_MAXFREQ,
			  AC_CPU_MAXFREQ_WITH_LM, AC_CPU_MAXFREQ_WITHOUT_LM.
			  (The CPU_MAXFREQ setting is now interpreted as
			  BATT_CPU_MAXFREQ.)
			* Support "fastest" in CPU_MAXFREQ options, for use
			  in AC_CPU_MAXFREQ_WITHOUT_LM.
			* Adjust syslog and HD settings even when basic
			  laptop mode status does not change. Previous
			  versions bailed out, but this meant that the
			  AC_*_WITH_LM versus BATT_* options were not
			  actually applied!
			* Add "--version" option for laptop_mode.
			* Added BIG FAT WARNING when root filesystem is
			  ext3 and doesn't support mount option. This
			  happens when the rootfs is mounted as ext2
			  at boot because of a missing ext3 module, and
			  there is no way to find out the actual rootfstype
			  later, so if you get this error you might be
			  running without journaling!
			* Support for multiple CPUs for frequency scaling
			  (in preparation for multicore laptop processors.)
			* Support /etc/default/laptop-mode, with option
			  ENABLE_LAPTOP_MODE="yes"/"no". This is for
			  backward compatibility with the Ubuntu "laptop-mode"
			  package.
			* Add VERBOSE configuration setting, for debugging
			  purposes.. Laptop mode tools will log everything 
			  it does when you enable this option.
			* Detect if a drive is not a CD/DVD player before
			  setting spindown timeouts on it. This gets rid
			  of "command not supported" errors in kernel
			  logs.
			* Include /dev/sda etc. in HD, because those are
			  the device names Linux gives to SATA drives.
			  
1.07	29 Jul 2005	* Fixed typo in 1.06 that broke basically everything.
			* Major cleanup of config. All the old settings should
			  keep working, but I recommend that you start with a
			  fresh config if you can, i.e., if you haven't got too
			  many personal changes.
			* Allow configuration of readahead when laptop mode is
			  disabled, using config variable NOLM_READAHEAD.

1.08    04 Aug 2005     * Fixed typo in lm_battery.sh and lm-syslog-setup that
                          caused infinite recursion.
                          
1.09    09 Aug 2005	* Fixed typo that caused CPU frequency scaling to no
			  longer work.
			* Support for controlling CPU throttling, using the
			  CONTROL_CPU_THROTTLING etc. options, similar to
			  the support for cpu frequency scaling.
			* When determining defaults for the commit and noatime
			  mount options for a filesystem, symbolic device links
			  and fstab entries using LABEL= are now supported:
			  fstab is no longer used. Instead, we save the relevant
			  mount options when laptop mode is enabled, and we
			  restore them when it is disabled.
			* Init script does not send output of laptop_mode to
			  /dev/null anymore, so you can see the output when
			  VERBOSE_OUTPUT is enabled.
			* Split the state reported by laptop_mode into two:
			  one is whether laptop mode processing is enabled at
			  all, and the other is whether it is currently active.
			* Support hd idle timeout settings in seconds instead
			  of in hdparm units, using HD_IDLE_TIMEOUT_SECONDS
			  instead of HD_IDLE_TIMEOUT. The old settings still
			  work.
			* Renamed ENABLE_LAPTOP_MODE_ALWAYS to
			  ENABLE_LAPTOP_MODE_ON_AC, and added
			  ENABLE_LAPTOP_MODE_ON_BATTERY. This allows you to
			  completely disable laptop mode, by setting all
			  ENABLE_ options to 0.
			* NOLM_MAX_LOST_WORK_SECONDS is removed, and replaced
			  by DEF_MAX_AGE. The setting didn't work as expected,
			  and wasn't supposed to.			
			  
1.10    14 Aug 2005	* Verbose output was on by default in earlier config
			  files.
			* Absence of AC adapters was interpreted as battery 
			  mode.
			* HD powermanagement default was incorrect for when
			  laptop mode was not active.

1.11	28 Oct 2005     * Cosmetic fix: "laptop_mode status" tried to get the
			  readahead setting for block devices that weren't,
			  causing error messages.
			* Fixed backward compatibility with VERBOSE
			  setting (now called VERBOSE_OUTPUT), because
			  Debian's init system may define this before calling
			  laptop_mode.
			* Cosmetic fix: sed would be run on
			  /var/run/laptop-mode-nolm-mount-opts when it didn't
			  yet exist, causing an error message.
			* Cosmetic fix: hdparm is not required, but it would
			  be called even if it wasn't installed. Now a
			  warning message is given instead, if any of the
			  hdparm-requiring options are enabled while hdparm
			  is not installed.
			* Changed default for CONTROL_HD_POWERMGMT to 0.
			  Some people have been experiencing system crashes
			  when their hard drives' powermgmt settings were
			  modified.
			* Cosmetic fix: updated config file to be 80-column
			  compliant.
			* Added ACPI-ONLY marker to every configuration
			  setting that only works on ACPI.
			* Instead of /var/run/laptop-mode-active, there is
			  now /var/run/laptop-mode-state, which contains
			  both the laptop mode and power state. This is used
			  to detect actual state changes, something which was
			  not possible before. If the state doesn't change,
			  then laptop_mode doesn't do anything.
			* Added support for controlling the CPU minimum
			  frequency, and frequency scaling governor. Thanks
			  to nokos for contributing this.
			* Added the ability to run start/stop scripts. Thanks
			  to Jan Polacek for the inspiration. You can put
			  links to init scripts (or any other scripts that
			  take "start" and "stop" commands) in the following
			  directories:
			    /etc/laptop-mode/nolm-ac-start
			    /etc/laptop-mode/nolm-ac-stop
			    /etc/laptop-mode/lm-ac-start
			    /etc/laptop-mode/lm-ac-stop
			    /etc/laptop-mode/batt-start
			    /etc/laptop-mode/batt-stop
			* Added the ability to adjust X-windows DPMS timing,
			  using CONTROL_DPMS_STANDBY. Thanks to Jan Polacek.
			* Fixes to useless output of hdparm when laptop mode
			  tries to determine if a drive is a CD-ROM. Thanks to
			  Jan Polacek.
			* New tool "lm-profiler", based on a contribution
			  by Jan Polacek. It provides a profile of your
			  system's disk usage and running network services,
			  and it can automatically disable network services
			  and other daemons when you are running on battery,
			  by placing links to the appropriate init scripts
			  in /etc/laptop-mode/batt-stop.
			
1.20	25 Jan 2006     * Fixed a typo that broke the setting of the CPU
			  governor. Thanks to a *lot* of people for
			  submitting exactly the same patch. :-) And sorry
			  that I didn't get around to actually applying the
			  patches for so long. :-(
			* Adapted the "big fat warning" so that it gives more 
			  info on how to fix the problem.
			* Applied a patch by Chung-chieh Shan (aka Ken) that
			  is supposed to fix the feature that controls DPMS
			  standby settings. Everybody, please report back if 
			  this actually works, I have NOT tested this but as
			  it didn't work before either I'm not too worried
			  about breaking it. ;-)
			* Corrected a path that was shown in an error message
			  in /etc/acpi/actions/lm_battery.sh.
			* Fixed typo in config: Shoudl should've been should.
			* Changed the default for CONTROL_NOATIME to 0. Mutt
			  doesn't work if filesystems are mounted noatime, and 
			  the only thing it actually buys you is that the disk 
			  doesn't spin up if you haven't changed *anything* 
			  at all for a period of 10 minutes. The chances
			  of that happening are practically zero -- you might
			  as well have suspended your system during that time,
			  that would have saved more power, as you weren't
			  actually doing anything!
			* Fixed a problem that would cause the acpid log to
			  be destroyed every time it ran laptop_mode. As much
			  a bug in acpid as in laptop_mode, but anyway, it's
			  fixed now.
			* Modified lm-profiler so that block_dump is disabled
			  when profiling is interrupted.
			* Added support for controlling terminal blanking
			  settings: CONTROL_TERMINAL, and
			  BATT_TERMINAL_BLANK_MINUTES,
			  BATT_TERMINAL_POWERDOWN_MINUTES, etc. This feature
			  is disabled by default.
			* Changed the default for CONTROL_START_STOP to 1.
			  There are no scripts in the start/stop directories
			  initially anyway, and having to explicitly enable
			  this is problematic for any related programs that
			  want to use this feature.
			* Changed the default for CONTROL_HD_WRITECACHE to 0.
			  As several people pointed out, it's very dangerous
			  to turn on write caching without explicit
			  knowledge of the system's administrator.
			* Added support for auto-hibernation once a
			  configurable battery level is reached. The control
			  option is ENABLE_AUTO_HIBERNATION.
			* Added "sort", "mv" and "sleep" to the
			  default-ignored programs for lm-profiler, as they 
			  are used by lm-profiler itself.
			* Improved checking for media types, so that no
			  actions are taken on CD-ROM drives and the like.
			  This gets rid of the errors that a lot of people
			  have been seeing. Thanks to Andrey Borzenkov for
			  contributing the bulk of this change. This does
			  NOT yet use the new 2.6.16 kernel sysfs "media"
			  attribute, I'll add that when I have the time to
			  upgrade to 2.6.16 myself.
			* Support for SCSI drives and sdparm. The appropriate
			  command is automatically detected. For now, only
			  idle timeout setting is supported (SCSI setting SCT, 
			  Standby Condition Timer).
			* Improved the output of lm-profiler so that it
			  doesn't scroll a line every second.
			* As it turns out, noatime remounting was only done
			  on ext3, reiserfs and xfs filesystems. Fixed.
			* Removed LMTVERSION from the distribution. The version
			  number is now stored only in /usr/sbin/laptop_mode,
			  and extracted as needed using some grep/sed trickery.
			  This saves me from the mistake of changing one
			  but not the other.
			* Changed syslog.conf control so that when laptop mode
			  is disabled by the init script, the original 
			  syslog.conf is restored. While laptop mode is active,
			  it is saved as syslog.conf.no-lm. This fixes a
			  problem on some distros (most notably Debian) where
			  the laptop mode syslog.conf files were being deleted
			  on purging laptop-mode-tools, leaving the system in
			  a state without a syslog.conf. Now, the purging can
			  only take place when the laptop mode service has been
			  stopped, which means that the original syslog.conf
			  will be back in place before the purging is done.
			* When the laptop mode init script is stopped (i.e., 
			  laptop mode processing is completely disabled), the
			  start/stop program actions taken by laptop mode are
			  now completely undone. Previously, the computer would
			  be left in the state as if it were in nolm-ac mode
			  with laptop mode enabled.
			* Added "force" option to /usr/sbin/laptop_mode script.
			  This makes laptop mode reapply all settings even
			  though the new state is the same as the previous
			  state. This is useful when coming back from a state
			  that may have lost some hardware settings, such as
			  hibernation. (Note however that stopping the service
			  during hibernation has the same effect.) It is also
			  useful for implementing the "reload" command
			  on the init script.
			* Changed the implementation of the "reload" command
			  in the init script so that it does "laptop_mode
			  auto force" instead of "start". That works better.
			* Removed special support for "start" and "stop" from
			  the laptop_mode command. These options now all do
			  the same thing as "auto". This means that it has
			  become IMPOSSIBLE to do something like
			  "/usr/sbin/laptop_mode start" manually and expect
			  it to work. Laptop mode will always simply get into
			  the state that it detects that it needs to get
			  into.
			* Moved all special detection logic, such as "minimum
			  battery minutes" etc., into the main laptop_mode
			  file. Previously, an ill-timed "laptop_mode auto"
			  could re-enable laptop mode even after it had been
			  disabled using "laptop_mode stop" by the
			  lm_battery.sh script. 
			* From this version onward the "minimum battery 
			  minutes" only influences the things that can cause 
			  data-loss, i.e., most settings stay at maximum 
			  powersaving, only the HD keeps spun up when the 
			  system is low on power.
			* Minimum battery minutes now applies to ALL
			  batteries, i.e., it only kicks in when ALL of the
			  batteries are below the threshold.
			* Speed optimization: the laptop_mode script no
			  longer needs to call itself recursively in order
			  to read the configuration file.
			* AC state is now correctly applied when booting
			  up on AC. This wasn't done correctly in 1.11.
			* The installer now creates the batt-start/stop,
			  lm-ac-start/stop and nolm-ac-start/stop
			  subdirectories in /etc/laptop-mode.
			* Added a check for MAX_LOST_WORK_SECONDS > 85899
			  for kernel versions 2.6.13 and greater. These
			  kernels do some calculations on clock tick counts
			  and 2^31 / 250 = ~85899 is the maximum value for
			  any centisecs kernel setting that they can
			  handle, due to integer overflow issues. Note
			  that this restriction only applies to kernels
			  running on 32-bit architectures.
			* Prevented the output of the start-stop
			  scripts from interfering with the output of
			  the laptop_mode script.

1.21	26 Jan 2006     * The first, inevitable bugfix release after such
			  a large release.
			* Fixed installation problem with existing old
			  /var/run/laptop-mode-state.
			* Changed installer to stop existing laptop mode
			  service before installing.
			* Added check for 32-bit architecture to new
			  warning about maximum MAX_LOST_WORK_SECONDS.
			  (The warning does not apply to 64-bit
			  architectures.)
			* Fixed laptop_mode output when state unchanged.
			  The prefix "Laptop mode " was not printed.

1.22	28 Jan 2006     * The SECOND, inevitable bugfix release after such
			  a large release. :-)
			* Fixed typo in laptop_mode that broke terminal
			  powerdown control. (Blanking still worked though.)
			* Added checks on whether the kernel sysctl settings
			  were actually applied. "echo value > /proc/..."
			  does not show errors, so failure was silent
			  until now.
			* Removed warnings on MAX_LOST_WORK_SECONDS > 85899.
			  The real problem is in the kernel, I submitted
			  patches to fix that problem.


References
----------

The laptop mode tools website.

  http://www.xs4all.nl/~bsamwel/laptop_mode/tools

The laptop mode website.

  http://www.xs4all.nl/~bsamwel/laptop_mode
