Level: Intermediate Neeraj Joshi (jneeraj@us.ibm.com), Advisory Software Engineer, IBM
David Kaminsky (dlk@us.ibm.com), Senior Software Engineer, IBM
11 Mar 2008 Get an introduction and overview of policy systems. Using the Apache Imperius as
an example, this article describes the SPL language and evaluation engine and shows you
how to install the SPL environment, write an SPL policy, and execute that policy using
the SPL engine. See how SPL can simplify mundane administrative tasks.
Introduction
It's February, and while the authors are located in the southern region of the United
States, it still gets pretty cold. A good cup of hot tea is just the recipe to recover from a cold day. You fill a kettle with water, place it on the stove, then wait for the water to heat. You check the kettle from time to time to see if the water has reached a boil. You're cold; time passes slowly. Eventually, the water is ready, and you can make your tea. Warm at last.
You might be thinking, "Lovely story, but what does this have to do with policy?"
Making tea isn't all that different from some of the mundane tasks required of systems administrators. Administrators must monitor systems, and when certain conditions arise (like the water boiling), take some action.
That's where policy-based management can help. A policy allows administrators to
express a set of conditions under which the policy is applicable and a set of decisions
that should result when the conditions are true. Such policies let administrators
replace mundane human tasks with automation--reducing the administrative burden.
Of course, not all administrative tasks are mundane; some require skill and careful
thought. The idea is to offload the mundane tasks from the administrator, leaving more time to focus on the complex, higher-value tasks.
In this article, you get an overview of policy systems and a description of the SPL
language and evaluation engine You'll also learn how SPL can simplify mundane administrative tasks. While the article discusses most of the background needed to use SPL, you should have some high-level familiarity with programming languages and systems management.
Policy languages
It is important to note up-front that there is astounding diversity in policy
languages. For that matter, there's little consensus on what comprises a policy language. Rather than attempting to enumerate policy language, or argue that SPL is the right or best policy language, this article simply stipulates that diversity exists, and that it describes just one of many types of language.
In that context, this article describes policies that are structured as "if-then" rules, where the "if" clause determines under what conditions the "then" clause should be actuated. For example, "if the data in a file system have changed by at least 10% since the last incremental backup, then perform an incremental backup." When such a policy is enforced automatically, instead of the administrator monitoring the "data changed" gauge and manually starting a backup, the policy system monitors the gauge and takes action when appropriate.
As described in more detail below, the "if" clauses can be quite complex. Modern policy languages support:
- Boolean algebra: AND, OR. NOT, and so on
- A wide set of arithmetic functions: plus, minus, multiply, and so on
- Collection operations: at least one of, all of, and so on
These operators combine information collected from the management environment to determine when the "then" clause should be executed.
The "then" clause causes the policy management system to take some action. For example, it might start a backup, change priority of running work, or simply notify an administrator.
The "then" clause is highly dependent on the management environment; that is, the actions the policy management system can take on the resource depend (almost) entirely on the function calls exposed by the environment. For example, if the environment system does not provide a call that initiates a backup or it doesn't permit priority changes, then such actions are not possible.
Management environments
Given their importance to policy management systems, it's worth briefly describing what
is meant by management environment. In short, a management environment is simply
a set of sensors and effectors that allow programmatic interaction with the resource exposing the environment --that is, the API.
The sensors are typically used in the "if" clause. For example, if the "if" clause
says "if the data in a file system have changed by at least 10% since the last
incremental backup," then either there must be a sensor that indicates what percentage
of the data has changed, or there must be enough information that such a value can be computed.
Effectors are typically used in the "then" clause. Using the same example, if the
policy requires that the system "start an incremental backup," then there must be an effector that can initiate the backup.
There are cases where sensors are used in the "then" clause. For example, a policy might state that the "then" clause should increase the priority of a process. If the environment doesn't provide an "increase" effector, but it does provide a "get priority" sensor, and a "set priority" effector, the policy can get the current priority, then set it to a higher value.
The structure of SPL
SPL is a policy language that can be bound to a wide variety of management
environments. It is worth noting that SPL is agnostic to the management environment;
the SPL doesn't care whether it is interacting with a Linux® server, a database, or
a Common Information Model (CIM)-based storage device. The structure of the policies is the same.
SPL policies are written within the scope of one or more anchor classes. The anchor classes encapsulate the state of the system that is being managed using policies. Based on the policy, the policy evaluator queries instances of these anchor classes to evaluate conditions and perform actions.
Listing 1 shows the general structure of an SPL policy.
Listing 1. SPL language syntax
Import Qualifier <namespace> Class <Class Name> : <instances>*;
Import ….
Strategy <strategy>
Policy (one or more)
{
Declaration {
<List of constant definition> (Optional)
<List of macro definitions> (Optional)
}
Condition { (Optional)
<If Condition> /* java-like boolean expression */
}
Decision { (Required)
<Then Decision> /* "small" workflow of action */
/* invocations */
}
} <priority>;
|
The major components of an SPL policy are:
- Import Statement: Declares the anchor classes and the instances of these classes that are referenced throughout the policy.
- Strategy Statement: Specifies arbitration strategy among multiple policies.
- Policy Statement: Declares the actual policy.
- Declaration Statement: Allows declaration of constants and functions (macros).
- Condition Statement: A Boolean expression that encapsulates the "if" portion of the
policy.
- Decision Statement: A sequence of actions that encapsulate the "then" part of the
policy.
- Priority: A numeric value used to determine relative importance among policies.
We illustrate the use of these constructs in the next section.
The structure of the SPL engine reflects the environment-agnostic design. In Figure 2, a typical management environment is shown on the left.
Figure 1: SPL engine architecture
The main components of the SPL engine are:
- The policy data store module, which interacts with the physical repository (policy repository) and cache to read and write policies.
- The policy parser, which converts a textual policy into an executable format.
- The policy cache, an in-memory storage allowing efficient policy reads and writes.
- The policy manager, which evaluates policies and coordinates the activities of the other policy engine components.
- The data collector, which interacts with the management environment, collecting the information needed to evaluate the policies.
- The actuator, which allows the policy engine to take action on the management environment.
- The Instrumentation Layers (CIMOM [Common Information Model Object Manager] or other layers) serve as the interface layer for the management environment, providing the data to the data collector and allowing the actuator to take action.
Note that the system is designed such that only the data collector and actuator components are aware of the user's environment; all other components are environment agnostic.
An example
of managing free space using SPL
In this section, you will use an example to demonstrate how SPL can simplify the management of computer systems.
Problem statement
No matter how disciplined you may be in keeping file systems clean, sooner or later,
you manage to fill them up with junk. That leads to the inevitable scurrying to find free space, and the unfortunate, yet common, "oh no" moment when you realize you deleted something you actually needed.
Solution
Instead of waiting until free space is critically low, you can author and execute an
SPL policy that periodically calculates the amount of free space in the file system.
When space is low, it uses the Windows® clean manager utility to selectively clean up dispensable data.
There are two key steps required to build a solution using SPL:
- Create an anchor class that encapsulates your operating environment state. For users
of the CIM, when SPL is running in a CIM environment, you can simply reuse some of the
CIM classes that exist within the CIMOM. A typical CIMOM ships with numerous classes that encapsulate the different IT artifacts in your system.
- Author the policy.
Creating the SPL anchor Java class
An anchor class needs to model the environment being managed through policies. In this scenario, you are managing the file system, and more specifically, cleaning it up when you are about to run out of space.
To create the anchor class, you must create a Java™ class that has (1) a method that
returns the current free space on your file system and (2) a method that can be invoked by the policy to initiate clean up. In this simple example, you need only two classes; in more realistic environments, the anchor class describing the management environment is far more rich.
Listing 2. Creating an SPL anchor Java class
Class WindowsComputerSystem {
float getFreeSpace();
void deleteFiles(String type);
}
|
It is important to note that there are no restrictions on the content of the anchor class or the methods in that class. (While the details of implementing such methods are beyond the scope of this article, you may use the sample code described later.)
Author the SPL policy
Apache Imperius , the incubator project for SPL hosted under the Apache umbrella,
comes with an Eclipse-based editor that can be used for authoring SPL policies. You
will need to refer to the "Apache Imperius SPL Editor Guide" (see Resources) for further details on how to build and configure the SPL editor if you want hands-on experience building the example policy.
Import the anchor class
The Import statement is the first statement within an SPL policy. It declares the anchor classes and one or more instances of them.
Listing 3. Importing the anchor class
Import Class
org.apache.imperius.javaspl.samples.windowscomputersystem.WindowsComputerSystem:system1; |
Here you are importing the WindowsComputerSystem as the anchor class and system1 as an instance of this class. Those classes have been defined elsewhere.
Specify the execution strategy
In some cases, multiple policies are grouped into policy groups, and the policy author
wants to control which get executed. Execution strategies allow the policy author to
control, based on stated priority, which policies in a group get executed. See
Resources to see a full list of execution strategies.
In this scenario you need all applicable policies to get executed so you include:
Strategy Execute_All_Applicable;
|
Declare constants
Declare the minimum and warning thresholds along with the e-mail addresses to where
alerts should be sent. Update the from and to constants with valid e-mail addresses.
Listing 4. Declaring constants
Declaration {
minimumFreeSpaceThreshold = 1 ;
warningFreeSpaceThreshold = 5 ;
from = "xxx@mail.com";
to = "yyy@mail.com";
}
|
Warning threshold reached policy
The first policy says "if the current free space on the file system is less than the
minimum threshold for free space then empty the recycle bin and notify the user via email".
Listing 5. Warning threshold reached policy
Policy {
Condition {
system1.freeSpace < minimumFreeSpaceThreshold
}
Decision {
system1.deleteFiles( "RecycleBin" ) -> SendMail(from,to,"Critical storage
situation","RecycleBin emptied")
}
}:1; // 1 specifies the priority of this policy. Higher number implies
// higher priority
|
Critical threshold reached policy
The second policy says "if the current free space on the file system is less than the
critical threshold for free space then clear the temporary Internet files and notify the user via email".
Because all policies will be executed as specified in the strategy, the warning
threshold policy will also evaluate to true as the free space is less than the warning threshold. As a result, the recycle bin will get emptied.
Listing 6. Critical threshold reached policy
Policy {
Condition {
system1.freeSpace < warningFreeSpaceThreshold
}
Decision {
system1.deleteFiles( "TemporaryInternetFiles" ) -> SendMail(from,to,"Critical storage
situation","TemporaryInternetFiles deleted")
}
}:1;
|
You can see the complete policy or, for your convenience, you can download the complete policy.
Executing the policy
Now that both the Anchor class and the SPL policy are authored, all that remains is to
deploy and execute the policy using the Apache Imperius policy engine. You will first
need to download and build the Apache Imperius code. For a link to the download site for
Apache Imperius, see Resources.
To execute the policy you must build a wrapper class that instantiates your anchor
class, instantiate the policy engine, deploy the policy, and, finally, execute the policy by passing the anchor instance.
Import the policy engine classes
Listing 7 shows the code needed to import the policy engine classes.
Listing 7. Importing the policy engine classes
import org.apache.imperius.javaspl.Java_SPLPolicyRuleProvider;
import org.apache.imperius.spl.parser.exceptions.SPLException;
|
Instantiate the anchor class and the policy engine
To instantiate the anchor class and the policy engine, use the code in Listing 8.
Listing 8. Instantiating the anchor class and policy
engine
WindowsComputerSystem system1 = new WindowsComputerSystem();
Java_SPLPolicyRuleProvider jspl = new Java_SPLPolicyRuleProvider();
|
Read the policy file from the file system
Listing 9 provides the code for reading the policy file from the file system.
Listing 9. Reading the policy from the file system
String aFile = policyToExecute + ".spl";
StringBuffer contents = new StringBuffer();
BufferedReader input = null;
try {
input = new BufferedReader( new FileReader(aFile) );
String line = null;
while (( line = input.readLine()) != null) {
contents.append(line);
contents.append(System.getProperty("line.separator"));
}
input.close();
} catch (FileNotFoundException ex) {
ex.printStackTrace();
} catch (IOException ex){
ex.printStackTrace();
}
boolean success = jspl.createPolicy("filesystempolicy", contents.toString());
|
Execute the policy
To execute the policy, use the code shown in Listing 10.
Listing 10. Executing the policy
Map objMap = new Hashtable();
objMap.put("system1", system1);
Object result = jspl.executePolicy(policyToExecute, objMap);
|
If the actual free space on your file system is less than the warning or critical
thresholds, you will see the Windows clean manager start and you will receive an e-mail
notice.
You can see the complete code for the policy engine
wrapper or, for your convenience, you can download the code.
The complete code is also available free on the Apache Imperius Web site (see
Resources).
All you need to do is:
- Download and build SPL source and samples.
- Follow the instructions under the samples/computersystem directory to execute the file
system sample.
Conclusion
Policy management systems provide a powerful tool for simplifying systems
administration. Apache Imperius, an open source policy system based on the SPL standard, provides a policy editor and evaluation environment that administrators can use to reduce the burden of mundane tasks. In this article, you learned how to install the SPL environment, write an SPL policy, and execute that policy using the SPL engine.
Download | Description | Name | Size | Download method |
|---|
| Code sample | ac-splsource.zip | 9KB | HTTP |
|---|
Resources
About the authors  | 
| | Neeraj Joshi is the lead developer in IBM Tivoli's Autonomic Computing Policy group. He has over 5 years of experience working in the areas of policy, problem determination, and security. He has a master's degree in Computer Science from North Carolina State University. |
| 
| | David Kaminsky is a Software Architect in the IBM autonomic computing group, where he focuses on policy-based management systems. Before working on autonomic computing, David worked on storage systems, portals, pervasive computing, and Java technology. David is an IBM Master Inventor, and has a Ph.D. in Computer Science from Yale University, where he studied parallel and distributed computing. Two commercial products resulting from his work are still sold today. |
Rate this page
| 
