Rules can be used to make your configuration more dynamic.
One common example is to set one value for resource-stickiness during working hours, to prevent resources from being moved back to their most preferred location, and another on weekends when no-one is around to notice an outage.
</para>
<para>Another use of rules might be to assign machines to different processing groups (using a node attribute) based on time and to then use that attribute when creating location constraints.</para>
<para>
Each rule can contain a number of expressions, date-expressions and even other rules.
The results of the expressions are combined based on the rule's boolean-op field to determine if the rule ultimately evaluates to true or false.
What happens next depends on the context in which the rule is being used.
</para>
<table frame="all">
<title>Properties of a Rule</title>
<tgroup cols="2">
<thead>
<row>
<entry>Field</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>role</entry>
<entry>Limits the rule to only apply when the resource is in that role. Allowed values: <emphasis>Started</emphasis>, Slave, Master. NOTE: A rule with role="Master" can not determine the initial location of a clone instance. It will only affect which of the active instances will be promoted.</entry>
</row>
<row>
<entry>score</entry>
<entry>The score to apply if the rule evaluates to "true". Limited to use in rules that are part of location constraints.</entry>
</row>
<row>
<entry>score-attribute</entry>
<entry>The node attribute to look up and use as a score if the rule evaluates to "true". Limited to use in rules that are part of location constraints.</entry>
</row>
<row>
<entry>boolean-op</entry>
<entry>How to combine the result of multiple expression objects. Allowed values: <emphasis>and</emphasis>, or</entry>
</row>
</tbody>
</tgroup>
</table>
<section id="s-expression-attribute">
<title>Node Attribute Expressions</title>
<para>Expression objects are used to control a resource based on the attributes defined by a node or nodes.
In addition to any attributes added by the administrator, each node has a built-in node attribute called <literal>#uname</literal> that can also be used.</para>
<table frame="all">
<title>Properties of an Expression</title>
<tgroup cols="2">
<thead>
<row>
<entry>Field</entry>
<entry>Description</entry>
</row>
</thead><tbody><row>
<entry>value</entry>
<entry>User supplied value for comparison</entry>
</row>
<row>
<entry>attribute</entry>
<entry>The node attribute to test</entry>
</row>
<row>
<entry>type</entry>
<entry>Determines how the value(s) should be tested. Allowed values: integer, <emphasis>string</emphasis>, version</entry>
</row>
<row>
<entry>operation</entry>
<entry>
<para>The comparison to perform. Allowed values: </para>
<itemizedlist>
<listitem><para>lt,- True if the node attribute's value is less than value</para></listitem>
<listitem><para>gt - True if the node attribute's value is greater than value</para></listitem>
<listitem><para>lte- True if the node attribute's value is less than or equal to value</para></listitem>
<listitem><para>gte- True if the node attribute's value is greater than or equal to value</para></listitem>
<listitem><para>eq- True if the node attribute's value is equal to value</para></listitem>
<listitem><para>ne - True if the node attribute's value is not equal to value</para></listitem>
<listitem><para>defined- True if the node has an the named attribute</para></listitem>
<listitem><para>not_defined- True if the node does not have the named attribute</para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="s-expression-iso8601">
<title>Time/Date Based Expressions</title>
<para>
As the name suggests, date_expressions are used to control a resource or cluster option based on the current date/time.
They can contain an optional <literal>date_spec</literal> and/or <literal>duration</literal> object depending on the context.
</para>
<table frame="all">
<title>Properties of a Date Expression</title>
<tgroup cols="2">
<thead>
<row>
<entry>Field</entry>
<entry>Description</entry>
</row>
</thead><tbody><row>
<entry>start</entry>
<entry>A date/time conforming to the ISO8601 specification.</entry>
</row>
<row>
<entry>end</entry>
<entry>A date/time conforming to the ISO8601 specification. Can be inferred by supplying a value for start and a duration.</entry>
</row>
<row>
<entry>operation</entry>
<entry>
<para>Compares the current date/time with the start and/or end date, depending on the context. Allowed values: </para>
<itemizedlist>
<listitem><para>gt - True if the current date/time is after start</para></listitem>
<listitem><para>lt - True if the current date/time is before end</para></listitem>
<listitem><para>in-range - True if the current date/time is after start and before end</para></listitem>
<listitem><para>date-spec - performs a cron-like comparison between the contents of date_spec and now </para></listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</table>
<note><para>Because the comparisons (except for <literal>date_spec</literal>) include the time, the <literal>eq, neq, gte</literal> and <literal>lte</literal> operators have not been implemented.</para></note>
<section id="s-exprssion-date-spec">
<title>Date Specifications</title>
<para>
<literal>date_spec</literal> objects are used to create cron-like expressions relating to time.
Each field can contain a single number or a single range.
Instead of defaulting to zero, any field not supplied is ignored.
</para>
<para>
For example, <literal>monthdays="1"</literal> matches the first day of every month and <literal>hours="09-17"</literal> matches the hours between 9am and 5pm inclusive).
However at this time one cannot specify <literal>weekdays="1,2"</literal> or <literal>weekdays="1-2,5-6"</literal> since they contain multiple ranges.
Depending on demand, this may be implemented in a future release.
</para>
<table frame="all">
<title>Properties of a Date Spec</title>
<tgroup cols="2">
<thead>
<row>
<entry>Field</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>id</entry>
<entry>A unique name for the date</entry>
</row>
<row>
<entry>hours</entry>
<entry>Allowed values: 0-23</entry>
</row>
<row>
<entry>monthdays</entry>
<entry>Allowed values: 0-31 (depending on current month and year)</entry>
<entry>Allowed values: 1-366 (depending on the current year)</entry>
</row>
<row>
<entry>months</entry>
<entry>Allowed values: 1-12</entry>
</row>
<row>
<entry>weeks</entry>
<entry>Allowed values: 1-53 (depending on weekyear)</entry>
</row>
<row>
<entry>years</entry>
<entry>Year according the Gregorian calendar</entry>
</row>
<row>
<entry>weekyears</entry>
<entry>
<para>May differ from Gregorian years.</para>
<para>Eg. "2005-001 Ordinal" is also "2005-01-01 Gregorian" is also "2004-W53-6 Weekly" </para>
</entry>
</row>
<row>
<entry>moon</entry>
<entry>Allowed values: 0..7 (0 is new, 4 is full moon). Seriously, you can use this. This was implemented to demonstrate the ease with which new comparisons could be added.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section id="s-expression-duration">
<title>Durations</title>
<para>
Durations are used to calculate a value for end when one is not supplied to in_range operations.
They contain the same fields as <literal>date_spec</literal> objects but without the limitations (ie. you can have a duration of 19 days).
Like <literal>date_specs</literal>, any field not supplied is ignored.
</para>
<section>
<title>Sample Time Based Expressions</title>
<example>
<title>True if now is any time in the year 2005</title>
<para>The advantage of using the expanded form is that one can then add extra clauses to the rule, such as limiting the rule such that it only applies during certain times of the day or days of the week (this is discussed in subsequent sections).</para>
<para>
It also allows us to match on node properties other than its name.
If we rated each machine's CPU power such that the cluster had the following nodes section:
</para>
<example>
<title>A sample nodes section for use with score-attribute </title>
<title>Using <literal>score-attribute</literal> Instead of <literal>score</literal></title>
<para>
When using score-attribute instead of score, each node matched by the rule has its score adjusted differently, according to its value for the named node attribute.
Thus in the previous example, if a rule used <literal>score-attribute="cpu_mips"</literal>, c001n01 would have its preference to run the resource increased by 1234 whereas c001n02 would have its preference increased by 5678.
</para>
</section>
</section>
<section id="s-rules-resource-options">
<title>Using Rules to Control Resource Options</title>
<para>Often some cluster nodes will be different from their peers, sometimes these differences (the location of a binary or the names of network interfaces) require resources be configured differently depending on the machine they're hosted on.</para>
<para>By defining multiple <literal>instance_attributes</literal> objects for the resource and adding a rule to each, we can easily handle these special cases.</para>
<para>In the example below, mySpecialRsc will use eth1 and port 9999 when run on node1, eth2 and port 8888 on node2 and default to eth0 and port 9999 for all other nodes.</para>
<example>
<title>Defining different resource options based on the node name</title>
The order in which <literal>instance_attributes</literal> objects are evaluated is determined by their score (highest to lowest).
If not supplied, score defaults to zero and objects with an equal score are processed in listed order.
If the <literal>instance_attributes</literal> object does not have a <literal>rule</literal> or has a <literal>rule</literal> that evaluates to <literal>true</literal>, then for any parameter the resource does not yet have a value for, the resource will use the parameter values defined by the <literal>instance_attributes</literal> object.
</para>
</section>
<section id="s-rules-cluster-options">
<title>Using Rules to Control Cluster Options</title>
<para>Controlling cluster options is achieved in much the same manner as specifying different resource options on different nodes.</para>
<para>
The difference is that because they are cluster options, one cannot (or should not because they wont work) use attribute based expressions.
The following example illustrates how to set a different <literal>resource-stickiness</literal> value during and outside of work hours.
This allows resources to automatically move back to their most preferred hosts, but at a time that (in theory) does not interfere with business activities.
</para>
<example>
<title>Set resource-stickiness=INFINITY Mon-Fri between 9am and 6pm, and resource-stickiness=0 all other times</title>
<title>Ensuring Time Based Rules Take Effect</title>
<para>
A Pacemaker cluster is an event driven system.
As such, it wont recalculate the best place for resources to run in unless something (like a resource failure or configuration change) happens.
This can mean that a location constraint that only allows resource X to run between 9am and 5pm is not enforced.
</para>
<para>
If you rely on time based rules, it is essential that you set the <literal>cluster-recheck-interval</literal> option.
This tells the cluster to periodically recalculate the ideal state of the cluster.
For example, if you set <literal>cluster-recheck-interval=5m</literal>, then sometime between 9:00 and 9:05 the cluster would notice that it needs to start resource X, and between 17:00 and 17:05 it would realize it needed to be stopped.
</para>
<para>Note that the timing of the actual start and stop actions depends on what else needs to be performed first. </para>