Rechercher une page de manuel

pbbuttonsd.cnf

Langue: en

Version: February 06, 2007 (openSuse - 09/10/07)

Section: 5 (Format de fichier)

Sommaire

NAME
DESCRIPTION
KEYCODE DEFINITIONS
GENERAL
MODULE POWERSAVE
MODULE DISPLAY
MODULE MIXER
MODULE MIXER OSS
MODULE MIXER ALSA
MODULE CDROM
MODULE PMAC
SEE ALSO
AUTHOR

NAME

pbbuttonsd.cnf - configuration file for pbbuttonsd >= 0.8.

DESCRIPTION

pbbuttonsd.cnf tells pbbuttonsd how the user wants it to work and is usually found as /etc/pbbuttons.cnf.

With Pbbuttonsd 0.8 the format of the configuratione file slightly changed. It uses now the keyfile format defined by the freedesktop organisation. It is very similar to the old format which was proprietary to pbbuttonsd but is not exactly the same. The main advantage of the new file format is that pbbuttonsd can now use code of the glib to pare it, instead doing everything by itself.

The file format could be found on http://freedesktop.org/Standards/desktop-entry-spec. A rough short form of the file formatcomes here.

An option looks always like this:

keyword=value

Empty lines and lines starting with a number-sign (#) will be ignored. Comments behind options are not allowed and lead to unwanted results.

The value contains the whole rest of the line including any white spaces. So quoting is not necessary and forbidden. Quoted strings will be read as quoted strings and may cause unwanted results. The quotation marks won't be filtered out.

It isn't necessary to define every option or a configfile at all because there are useful default's built into the program.

The config file is split up into sections to group options which belong together. The section headlines are corresponding to the pbbuttonsd modules and group the options. It os allowed to have two options with the same name as long as they are in different sections. Each module has a config file section. The available options depends on the modules functionality.

KEYCODE DEFINITIONS

Some of the options need key definitions. A key could be defined as follows.

The key definition could have multiple parts. The first is the keycode as it could be found in ..include/linux/input.h. This keycode at least must be given otherwise the built-in default value will be used.

The other parts are the optional modifiers that could be combined with the keycode to trigger the certain function. The shift, alt and ctrl modifier are supported. They are added to the keycode with a plus-sign (+). The sequence doesn't matter.

EXAMPLE: 225 + shift + ctrl
This means the key 225 has to be pressed together with shift and ctrl to trigger the function.

GENERAL

userallowed = username (default: none): Lets talk about security. PBButtonsd accepts messages through the kernel IPC-message protokoll without verification who sent the message. This doesn't seem to be a problem because IPC is only used locally and can't be accessed directly over network. Only those options which could be abused to get root rights were protected and could only be changed by the owner of pbbuttonsd's process.

This didn't satisfy some users so I implemented this option to give those users more control who should be allowed to send messages to pbbuttonsd. If this option is set only the named user (only one possible at the moment) is allowed to change pbbuttonsd's options via the IPC-interface. Messages from all other users (root included) will be rejected. Query the current configuration is further possible for all users.

To completely disable the possibility to change options via IPC name a user that doesn't exist. In this case no logged-in user is allowed to change options. Setting the option in the config file and 'kill -HUP <process-id>' would then be the only way to change options on the fly then.

autorescan = [yes | no] (default: yes): PBButtonsd uses the kernel input layer and its event devices to get input from the keyboards and mice. This layer support all types of input devices also those which will be connected or removed later during operation. Normally pbbuttonsd scans the event devices once at startup and uses all keyboards and mice found at that time but most people wanted to be able to plug-in or remove external input devices at any time.

With this option set to 'yes' pbbuttonsd would scan for new input devices on a regular time basis. Due to the continuous access to the /dev/input/event% device files, spin-down functions of hard disks might be influenced. If you have problems with this, you could disable this feature and trigger a rescan by hand when necessary.

CmdTimeout = time in seconds (default = 8): Pbbuttonsd is able to launch user defined scripts and it uses some external helper utilities. This scripts and utilities were started as separate processes with their own environment independent from pbbuttonsd's. During a helper process is active pbbuttonsd's process is blocked and waits for the child process to end. Without security mechanism this could lead into an knocked out pbbuttonsd due to a hanging script. To prevent such a situation pbbuttonsd has an eye on its child processes and if they consume too much time they will be killed by the parent process.

It was very difficult in the past to define a correct timeout value because of a huge amount of different scripts written and used by users. With this option the individual timeout value in seconds can be defined. Be careful with high values because an error in your script can block pbbuttonsd for a long time. The minimum value is 1 second. values below this will force a one second timeout.

MODULE POWERSAVE

This module does all the hardware independent power saving stuff.

onAC_Policy = policy (default: performance)
onBattery_Policy = policy (default: powersave) This options set the power management policies that should become active after power source has changed. following policies were supported:

'nochange'    current policy won't be changed

'powersave'   minimum power consumption

'custom'      user defined

'performance' maximum system performance

The pmcs script does all actions needed to activate the options according the selected power policy.

onAC_TimerAction = action (default: suspend-to-ram)
onBattery_TimerAction = action (default: suspend-to-ram) After some time without user action, so called idle time, the timer emits an event. Pbbuttonsd can connect an action to this event that would be executed when this event occours. Four actions are possible (see below). This option can independently configured for AC or battery power source.

none
Nothing will be done. If onXX_TimerAction was set to 'none' the timer event would be ignored.

suspend-to-ram
This action suspends the machine and conserves the memory content in RAM. This mode is also known as 'sleep' and works only if it is supported by the hardware.

suspend-to-disk
This action suspends the machine and save the memory content to hard disk. This mode is controlled by the kernel and is supported since kernel version 2.6. A backport for kernel 2.4 is also available.

This action works a little bit different to suspend-to-ram. If the event suspend-to-ram occours the PMCS script will be executed to perform preliminary jobs. Suspend-to-ram is then triggered by pbbuttonsd.

If the event suspend-to-disk occurs the PMCS script will also be executed but in contrast to suspend-to-ram it has also to initiate suspend mode after all preliminary jobs are done. Pbbuttonsd doesn't expect the script to return.

blankscreen
If this action was configured the screen would be switched off. The computer will continue to run. This could be helpful in some cases where for example the machine must be reachable over a network without anyone working with it directly.

This mode is the fallback action if suspend-to-ram is not supported by the hardware.

Attention: With a switched-off display you might not be able to see that the computer is still running but it continues to consume power. To give you a hint the computer will play a beep every 30 seconds as a reminder.

shutdown
This action triggers a machine shutdown. The PMCS script is called to initiate the shutdown. Usually this is done with the 'halt' command.

onAC_CoverAction = action (default: suspend-to-ram)
onBattery_CoverAction = action (default: suspend-to-ram)
This options define the action to perform if cover has been closed or opened. For possible actions and it's description please see onXX_TimerAction. It could independently configured for AC or battery power source.

This options will only work if pbbuttonsd was compiled without pmud support so that pbbuttonsd has control over the cover.

onAC_KeyAction = action (default: suspend-to-ram)
onBattery_KeyAction = action (default: suspend-to-ram)
This options define the action to perform after the sleepkey has been triggered. For possible actions and it's decription please see onXX_TimerAction. It could be independently configured for AC and battery power source.

onAC_SuspendTime = value (default: 3000 = 5 minutes)
onBattery_SuspendTime = value (default: 3000 = 5 minutes)
This option sets the idle time in 1/100 seconds after the machine should be put to sleep or the display should be switched off. It could independently controlled for AC or battery power source.

Set this value to 0 to disable sleep when idle.

onAC_DimTime = value (default: 600 = 1 minutes)
onBattery_DimTime = value (default: 600 = 1 minutes)
This option sets the idle time in 1/100 seconds after the display should be dimmed to minimum level. It could independently controlled for AC or battery power source.

Set this value to 0 to disable display dimming. The display brightness won't change automatically and keep its value for unlimited time.

SleepKey = key (default: 116): Key to trigger sleep mode or blank the screen, corresponding to the current configuration and the machine's abilities.
SleepKeyDelay = time in milliseconds (default: 0): This option sets the delay time used for an additional validity check of the sleep key to prevent unwillingly triggered sleeps due to small keyboards. The key must be pressed for longer than the given time period to trigger sleep. The value must be given in milliseconds, for example to set a delay time of 2 seconds set the delay time to 2000. If the given value is zero, sleep mode would be entered immediately.

This option might be dangerous if the power key is used to trigger sleep mode, because the power key has a second hard-wired meaning. If you press the power key for a long time, the machine will be switched off completely. This is an emergency feature of the Macintosh hardware. Therefore it could be very tricky to press the power key long enough to trigger sleep and release the key just before the hardware switched power off. Use this option with care.

BWL_First = minutes (default: 20)
BWL_Second = minutes (default: 10)
BWL_Last = minutes (default: 3)
This options set the battery warn levels in minutes. If the remaining time on battery falls below one of the above values the appropriate battery warning would be displayed (gtkpbbuttons or something similar must be running to see them).

If the time remaining reaches 'zero' the non-configurable battery warnlevel 4 is entered, which causes the machine to shutdown immediately. The clients will be noticed by a message about the coming shutdown.

Defining new warn levels be aware that you fulfill following conditions:
- BWL_First > BWL_Second > BWM_Last > 0
- the difference of two adjacent warnlevels must be greater than 6 minutes.

Violation of this conditions will result in an error message and fall back to default values.

EmergencyAction = [action] (default: sleep): If the battery is critically low the machine have to be set into a safe state. This could be done on different ways. Which way is the right for your system could be configured with this option. There are three actions possible:

sleep - The machine would be forced to sleep mode. This action gives security only for a short period because also in sleep mode the computer consumes power and continue to discharge the battery but slower. This gives you enough time to plug in the AC connector to recharge the battery and go on with your work.
This action could only be chosen if the machine supports sleep mode. If not this action defaults to signal.

signal - A SIGPWR signal would be sent to the INIT process. The further actions depend on your system configuration in /etc/inittab. Please check your installation to be sure the SIGPWR does what you want. Pbbuttonsd won't do anything else to prevent data losses due to battery voltage collapse.
Pbbuttons tried first to send the init process the signal with the new init request through /dev/initctl. If that fails it tried the old method through /etc/powerstatus. If that fails too and the machine supports sleep mode this action defaults to sleep, otherwise it defaults to command.

command - This is the former standard action in case of critically battery power. a command would be executed which usually shut down the computer safely. The script_pmcs (see below) will be called with argument 'emergency' in this case.

HeartbeatBeep = [yes | no] (default: yes): Pbbuttonsd can be configured to switch off the display instead of entering sleep mode even though the lid was closed. As configured in such a way the machine only to switch off its display after sleep timeout and continue running on full power. If in this situation also the hard disk spun down, no sign of computer's life would exist anymore and the machine looks like a switched off computer.

This may lead to unexpectedly drained batteries or needlessly long idle runs because the computer looks like already switched-off and you may then forget to switch it off really. Due to pbbuttonsd's smart power management functions nothing harmful can happen to the computer or to your valuable data. So this is a convenience option.

To have always a sign of life from the computer pbbuttonsd will play a beep every roundabout 30 seconds if the computer was still running with switched-off display. Someone will take the risk to get rid of this nice little beep (others called it annoying). For those this option was implemented. It will switch off the heartbeat beep if set to 'no'.

Usual cases when the heartbeat beep will occur are using your PowerBook with closed lid connected to an external keyboard and monitor or access your computer remotely via the network. In the second case the heartbeat beep will first occur with delay of the configured sleep timeout.

Script_PMCS = command (default: none): This option sets the script name that should be called at following events: change of power policy, change of power source, change of suspend state and if configured at low battery (emergency). For security reasons this script should only be readable by the user who runs pbbuttonsd (usually root) and not be writable at all.

Up to three '%s' could be placed in the command string. The first '%s' will be replaced with the action (see etc/power/README for action list), the second with the current powersource ('ac' or 'battery') and the third with an action depending option. (for example the action 'suspend' may get the option 'ram'. This means suspend-to-ram).

IBAM_DataDir = directory (default: /var/lib/ibam): This directory is used to store statistical data measured during battery charge and discharge time. This data is used by the new IBAM algorithm for reliable and accurate battery and charge time predictions.

This option would only be available if pbbuttonsd was compiled with IBAM support.

CPULoad_sleeplock = [yes | no] (default: no): With option enabled high CPU loads prevent the machine from entering sleep mode. Every second the current CPU load will be calculated and compared with a minimum level. Is the current CPU load below this level for a certain period of time the sleep lock will be opened and the machine is allowed to enter sleep mode. Jumps the CPU load over the border line the sleep lock will be closed immediately and the time measurement starts from the beginning.
CPULoad_min = percent (default: 20): With this Tag the minimum CPU load level could be set.
CPULoad_period = seconds (default: 20): With this option the period of low CPU load time in seconds could be set.
NETLoad_sleeplock = [yes | no] (default: no): With option enabled high net loads prevent the machine from entering sleep mode. Every second the current net load will be calculated and compared with a minimum level. Is the transfer rate in bytes per second below this level for a certain period of time the sleep lock will be opened and the machine is allowed to enter sleep mode. Jumps the net load over the border line the sleep lock will be closed immediately and the time measurement starts from the beginning.
NETLoad_min = traffic (default: 4096 Bytes/s): With this Tag the minimum transfer rate in bytes per second could be set.
NETLoad_period = seconds (default: 20): With this Tag the period of low net load time in seconds could be set.
NETLoad_device = netdevice (default: eth0): With this option the network device to observe could be defined. Up to now only one network device could be set and observed.

MODULE DISPLAY

This module controls the light sources inside the laptop. Mostly this is the LCD backlight but recent computers come with an additionally keyboard illumination which is also controlled by this module. The module works hardware independently.

LCD_Brightness = value (default: none): With this option the initial brightness level of the LCD backlight in percent could be set. This value becomes active during pbbuttonsds start up phase.

Was this option commented out, pbbuttonsd wouldn't change the LCD brightness during start up. The display stays as bright as it has been before pbbuttonsd was started. Comment this option out if you want this behaviour.

LCD_FadingSpeed = value (default: 0): PBButtonsd is able to dim and recover the display brightness smoothly. Set the value to zero, blending would be disabled. In this case PBButtonsd would work as used to.

With a value greater than null fading will be activated. Fill in the time a full dim (from lowest to highest brightness level or vica versa) should last. PBButtonsd will take into account that some backlight controllers are not as fine grained controlable as others and adjusts its internal timing to fulfill your request as best as possible.

The time value must be given in miliseconds (1/1000th of a second).

LCD_AutoAdjust = mode (default: linear)
KBD_AutoAdjust = mode (default: hysteresis)
Enable automatic LCD brightness and keyboard illumination adjustment and set the mode for the brightness contoller. the brightness level will be automatically adjusted depending on ambient light. Possible modes are:

off No automatic brightness adjustment

linear Linear dependency between ambient light and brightness level (see graph below)

hysteresis Brightness level toggles dependent on ambient light thresholds (see graph below).

      lêvel     2                 lêvel          2
       |         o------           |      +--<--o-----
       |        /                  |      |     |
       |       /                   |      |     |
       |------o                    |------o-->--+
       |       1                   |     1
       +------ambient-light->      +--------ambient-light->
             linear                      hysteresis

Point one and point two define the characteristic of the controller. Each point is an ambient light/brightness level pair. They could be defined with the AutoadjParm options (see description below). Both points must be given to make the controller work properly.

This option work only on laptops with an ambient light sensor as for eg. the 17" Aluminum PowerBook or the MacBook from Apple. If such a sensor isn't present this option will be ignored. Furthermore not every machine have an illuminated keyboard.

LCD_AutoAdjParm_onBattery = A1, L1, A2, L2 (default: 0%,1%,54%,100%)
LCD_AutoAdjParm_onAC = A1, L1, A2, L2 (default: 0%,1%,94%,100%)
KBD_AutoAdjParm_onBattery = A1, L1, A2, L2 (default: 0%,100%,28%,0%)
KBD_AutoAdjParm_onAC = A1, L1, A2, L2 (default: 0%,100%,28%,0%)
With this options the characteristic of the automatic brightness controller could be changed. Each option has four parameters which all four must be present to be accepted.

Each paramerterset consists out of two ambient light/brightness level pairs called a point (A=Ambient light, L=brightness Level). The meaning of this points depend on the operating mode that was set with AutoadjMode. All parameters must be given in percent (0-100%).

Linear mode
In linear mode the brightness level will be smoothly changed from L1 to L2. The ambient light values set the start- and endpoint of this brightness change. The brightness level will be kept stable if the abmient light is below A1 or above A2.

Hysteresis mode
In hysteresis mode the brigtness level toggles between L1 and L2. The ambient light values A1 and A2 define when this will happen. To prevent fast flickering the threshold changes depending on the curent brightness level. If the backlight is at L1 and the ambient lightbecomes brighter than A2 the brightness level will be switched to L2. If the ambient light level falls below A2 again the brightness level stick to L2. In order to switch the brightness level back to L1 the ambient light level must decrease below A1 (see sketch above).

The behaviour of the automatic brightness controller can be individually defined for the LCD backlight and the keyboard illumination and might also set differently dependent on the power source.

This options could be used to limit the working range of the automatic brightness controller in general or depending on the power source, which is very usefull most of the time. It might help to save energy when running on battery.

LCD_IllumUpKey = key (default: KEY_BRIGHTNESSUP): Use alternative key to increase LCD illumination level.

In conjunction with shift the brightness will be set to maximum level. This second function is statically bound to the modifier shift so that the key definition must not contain shift. It will be ignored, if mentioned.

LCD_IllumDownKey = key (default: KEY_BRIGHTNESSDOWN): Use alternative key to decrease LCD illumination level.

In conjunction with shift the brightness will be set to minimum level. This second function is statically bound to the modifier shift so that the key definition mustn't contain shift. It will be ignored, if mentioned.

KBD_Brightness = value (default: 0): With this option the initial brightness level of the keyboard illumination on percent could be set. The value becomes active during pbbuttonsds start up phase. Comment this option out if you don't want this behaviour.