Programming Guides › Programming Guide for Perl › Perl Scripting Overview

Perl Scripting Overview

This section contains the following topics:

About the SiteMinder Command Line Interface

Installation Path

Where to Run Your Scripts

CLI Example: Create a Policy Store Object

CLI Example: View and Set Individual Properties

Location of Sample Scripts

Related Documentation

About the SiteMinder Command Line Interface

The SiteMinder Command Line Interface (CLI) lets you perform tasks by running custom Perl scripts from the command line.

The scripting interface contains the following APIs:

• Agent API—Lets you test whether access control of protected resources is behaving according to policy definitions.
• Policy Management API—Lets you design and administer policy stores.

The Command Line Interface provides:

• A quick and light-weight alternative to the Administrative UI.
• An efficient way to perform Policy Server design and administrative tasks over multiple policy stores.
• The ability to migrate individual objects between policy stores.

The Command Line Interface lets you perform most, but not all, of the policy store operations you can perform through the Administrative UI.

More Information:

Command Line Interface Restrictions

Installation Path

By default, the SiteMinder Command Line Interface is installed in the following location:

<sm-ps-root>/CLI

<sm-ps-root> is the root directory where you installed your Policy Server software.

Perl Location

A complete version of Perl is installed along with the Policy Server. When you run scripts against the Command Line Interface, you should use the Perl interpreter that is installed with the Policy Server rather than any other Perl interpreter that might be on your system.

The installation program installs Perl in the following default location:

<sm-ps-root>/CLI/bin

If you have another version of Perl installed on your system, make sure that the Perl location shown above comes before any other Perl location in your system’s PATH environment variable.

Where to Run Your Scripts

The Perl Agent and Policy Management APIs can be used on the following machines:

• Agent API—On the machine where a Policy Server is installed. The Agent API can access the local Policy Server or a remote Policy Server.
• Policy Management API—On the machine where a Policy Server is installed.

To run a script against these APIs, use the following command line syntax:

perl scriptname

Note: A script built with the Policy Management API must run as the same user who installed the Policy Server (for example, smuser on UNIX platforms).

CLI Example: Create a Policy Store Object

Suppose you are an administrator for the domain engineering. You want to create the realm documentation in that domain. Using the Administrative UI, you might take the following steps:

1. Log into the SiteMinder Administration software.
2. Right-click the domain engineering where you are adding the realm.
3. Click Create Realm and provide the following configuration information for the fields on the Resource tab:
   • Name: documentation
   • Description: Source files for manuals
   • Agent: agent1
   • Resource Filter: /mysite/docs/*
   • Authentication Scheme: Basic

   You are accepting all other defaults for the realm (including resource protection, which is enabled by default).

4. Click OK to confirm the creation of the new realm.

If you write a script to perform the same operation, it might look like this:

#Initialize the Policy Management API
use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();

print "Step 1. Log in the admin and create an API session.\n";
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

print "Step 2. Select the domain for the new realm.\n";
$domain=$session‑>GetDomain("engineering");

#Get the realm’s agent and authorization scheme info.\n";
$agent=$session‑>GetAgent("agent1");
$authscheme=$session‑>GetAuthScheme("Basic");
print "Step 3. Create and configure the realm.\n";
$realm=$domain‑>CreateRealm("documentation",
                            $agent,
                            $authscheme,
                            "Source files for manuals",
                            "/mysite/docs/*" );

print "Step 4. Confirm the creation of the realm.\n";
if ($realm == undef) {
         print "Realm creation failed.\n";
   }
   else {
         print "Realm creation succeeded.\n";
}

Note: Generally, policy store object names are case-sensitive. In the above example, the Basic authentication scheme and the engineering domain are case-sensitive. Further, agent names are always written to the policy store in lowercase. Existing agents must be referenced in lowercase in your scripts.

CLI Example: View and Set Individual Properties

Policy Management API objects (such as PolicyMgtRealm) provide a number of get/set methods that let you view and modify individual properties of objects in the policy store. You use these get/set methods to view and edit an object’s properties just as you would use the property fields in the Administrative UI.

The following script modifies the resource filter property:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");
$domain=$session‑>GetDomain("engineering");

$realm=$domain‑>GetRealm("documentation");
if($realm‑>ResourceFilter() eq "/mysite/docs/*") {
      $filter=$realm‑>ResourceFilter("/mysite/docs/*.doc");
}
if ($filter eq undef) {
      print "Error changing resource filter.\n";
   }
   else {
      print "Resource filter changed to: " . $filter . "\n";
}

Note the following general rules:

• When you pass an argument into a method, the method behaves as a setter method—for example:

  $realm‑>ResourceFilter("/mysite/docs/*.doc");
  

• When no argument is given, the method behaves as a getter method—for example:

  $filter=$realm‑>ResourceFilter();
  

• With get and set methods, the existing or new property value is returned.

Location of Sample Scripts

Sample scripts are installed in the following default location:

<sm-ps-root>/CA/siteminder/CLI/examples

Before using a sample script, be sure to change the values of the site-specific variables (such as administrator’s credentials and user-store location) that are defined at the beginning of the script.

Related Documentation

You can find additional information about Policy Server and agent operations in the following SiteMinder documents:

• CA SiteMinder Policy Server Configuration Guide
• CA SiteMinder Policy Server Administration Guide
• CA SiteMinder Web Agent Configuration Guide

Object Dependencies Poster

The poster Scripting Interface for Perl: Object Dependencies is included with SiteMinder. The poster illustrates the Perl objects that you need to create or retrieve before you can manipulate dependent objects. Each object is shown with all of its methods.