...

The power management policy consists of a set of rules, and variables that can be used as arguments in these rules. Policy can currently be loaded from a text file, the DB, or added a rule or variable at a time over DBus. All policy, regardless of origin, is ultimately made persistent by storing it in the DB. 

Rule Structure

A rule consists of a name, a set of conditions, a set of actions, and optionally a set of undo actions. When all conditions become true, the rule becomes active, and its actions are executed in order. When any condition becomes untrue, the rule becomes inactive, and its undo actions (if any) are executed in order.

Name

Each rule is uniquely identified by its name. This name may be used to later modify or remove a rule.  A name may consist of letters, numbers, and underscores.

Name uniqueness is strictly enforced; attempts to add a rule with the same name as a currently loaded rule will fail.

Conditions

A rule’s conditions are a set of Boolean functions that determine when a rule is active. A condition either checks the state of the system or listens for an event. Each condition is individually simple, but more complex rules can be built out of multiple conditions. Multiple conditions are logically ANDed together; therefore, all conditions must be true for a rule to be active. Conditions may be preceded with an exclamation point (!) to invert their return value. If a logical OR is required, consider splitting the conditions into multiple rules with the same actions.

...

See the Arguments section for specific details on arguments.

Actions

A rule’s actions dictate what a rule will do when it changes from inactive to active. Actions, as their name implies, perform some sort of task, such as pausing a VM or printing a message to the system log. Each action in the list is performed, one at a time, in the order that they are written in the rule’s set of actions.

Much like conditions, each action has a defined prototype determining what arguments it takes. Unlike conditions, however, actions do not evaluate to any particular value; therefore, actions and conditions are in no way interchangeable. Actions, like conditions, also consist of a name followed by a set of parentheses that may contain arguments according to a prototype. When arguments are present, they are separated by spaces. Actions themselves are also separated by spaces.

Undo Actions

Undo actions are performed when a rule changes from active to inactive, but otherwise, the same conventions apply as in the action section. Undo actions may consist of any set of actions. Undo actions are optional, and may be omitted entirely.

Arguments

Arguments are pieces of data provided to conditions and actions. Each argument has a type, which is inferred by the parser. XCPMD currently supports four argument types: 

...

There is no type-punning; an integer cannot be substituted for a float, even if their values are equivalent.

Example Rule:

The following example shows a simple rule with each section separated by pipes (|):

...

• The rule’s name is rule1. 
• It will become active while it is both on battery power, and battery 0 has less than 30% capacity remaining. When either of these conditions become false, the rule will be inactive.
• When the rule changes from inactive to active, it will print the string “Pausing VM!” to the system log, then pause the VM named “ubuntu.” 
• When the rule changes from active to inactive, it will unpause the VM named “ubuntu.”

Variables

XCPMD also supports variables. Variables are, essentially, arguments whose values can arbitrarily substituted for other values of the same type, serving as an argument to one or more conditions and/or actions. Unlike constant arguments, the value of variables may change even while the daemon is running.

...

• All variables must have unique names.
• Names may contain only letters, numbers, and underscores (_).
• A variable must be defined before it can be used in a rule.
• They are strictly typed, like all arguments. A variable’s type must match the action/condition prototype in order to be used as an argument to that action/condition.
• Once defined, their type may not change, unless they are deleted and re-added.
• Variables may not be deleted if they are still in use by any rule.

Configuring Policy

XCPMD supports three interfaces for configuring policy: text files, DBus, and direct DB modification.

Text Files

Text files provide an easy way to encapsulate policy and deploy to many machines. Their syntax is simple and straightforward. Each policy file is broken into two sections, variables and rules, which are separated by a single line containing only an equals sign (=).

...

To trigger loading policy from a text file, use the DBus call load_policy_from_file.

Sample Policy File

#begin variables section
ubuntu_uuid(“12345678-1234-1234-1234-123456789012”)
battery_low(20)
battery_critical(7)
=
#begin rules section
screen_off     | whileLidClosed() | runScript(“/home/user/blank_screen.sh”) | runScript(“/home/user/unblank_screen.sh”)
low_batt_alert| whileBattLessThan(0, $battery_low) | logString(“Battery low!”)
pause_ubuntu  | whileBattLessThan(0, $battery_critical) | pauseVmUuid($ubuntu_uuid) | resumeVmUuid($ubuntu_uuid)

DBus Interface

XCPMD’s DBus interface allows the user to control and query different aspects of policy. This is the interface that any UI tools would use to modify policy in XCPMD. The following calls are currently available:

...

All DB entries are stored and retrieved as key-value pairs, with both key and value being strings. XCPMD parses the strings retrieved from the DB in the same way as other interfaces, so the same rules apply with respect to argument and variable type inference. In particular, ensure that string-type arguments and variables are wrapped in double quotes--using backslash (\) as an escape character may be necessary, depending on your shell.

Parse Errors

If the parser is unable to fully parse a rule, it will attempt to salvage as much as it can. An unparseable or invalid condition or action will be discarded, and provided that the rule has at least one remaining condition and at least one remaining action, it will continue to be loaded.

...

• The rule’s name must be unique
• At least one valid condition:
  • Condition type is known
  • Arguments provided match prototype
  • All variables are defined
• At least one valid action:
  • Action type is known
  • Arguments provided match prototype
  • All variables are defined

Available conditions

Available actions

...

Backend Architecture

Policy Structure

...