Thursday May 08, 2008

Federated Access Manager: famadm Command Line Utility

I recently updated my last entry, More About Configuring Policy Agent 3.0, saying that I would add an entry about the famadm utility. Yeah, so, that's what I'm doing now.

Much of this info comes from engineering folks: Dennis Seah, Hua Cui,  and Sean Brydon.

As I mentioned in the update to my previous entry, info about setting up the famadm command line utility is provided on this Wiki page. Sean added that info, and while it has a Policy Agent 3.0 slant to it, much of the beginning steps that he describes relates to FAM 8, too, at least instructions describing how to make the famadm utility available.

Normal Software Development:

OpenSSO is changing constantly, of course. Some changes even affect the famadm utility. Therefore, from  build 4 to 5 (build 5 isn't out as of yet), a few differences will exist. For example, access to agents has changed in the FAM Console. In build 4, you access agents from the Configuration tab. In build 5, you access agents the way it was done in Access Manager: In the Access Control tab, you select a realm. Then you can access agents. How does this relate to the famadm utility? In build 4, when issuing famadm to create or configure an agent, it was not required to list an agent's realm. Now it is required. You can use -e or --realm for the realm argument, as such:

famadm  update-agent --realm
famadm  update-agent

Simple Example: 

Here's the famadm command with the list-servers subcommand: 

famadm list-servers 

With the required options, this command lists all server instances. Here is some usage info for this command:


famadm list-servers

Issued from the directory containing the famadm utility, the command might look like either of the following two examples:

[root@localhost]# ./famadm list-servers --adminid amadmin --password-file /tmp/testpwd

[root@localhost]# ./famadm list-servers -u amadmin -f /tmp/testpwd

A More-Involved Example:

What Dennis pointed out to me was that you can enter the subcommand name of the famadm command, such as update-agent. To which, the response will be a list of options. First, here's a complete command issued from the directory containing the famadm utility:

[root@localhost]# ./famadm update-agent -e testRealm1 -b testAgent1 -u amadmin -f /tmp/testpwd -a "com.sun.identity.agents.config.locale=en_US"

Now, in the box below is the famadm command with the update-agent subcommand, also issued from the directory containing the famadm utility (notice that the options for this subcommand are provided and explained).

[root@localhost]# ./famadm update-agent
Incorrect option(s), famadm  update-agent

famadm update-agent --options [--global-options]
    Update agent configuration.

famadm update-agent

Global Options:
    --locale, -l
        Name of the locale to display the results.
    --debug, -d
        Run in debug mode. Results sent to the debug file.
    --verbose, -v
        Run in verbose mode. Results sent to standard output.

    --realm, -e
        Name of realm.
    --agentname, -b
        Name of agent.
    --adminid, -u
        Administrator ID of running the command.
    --password-file, -f
        File name that contains password of administrator.
    --set, -s
        Set this flag to overwrite properties values.
    --attributevalues, -a
        properties e.g. homeaddress=here.
    --datafile, -D
        Name of file that contains properties.

Let's focus on the following usage info: 

 famadm update-agent

We can tell  that the update-agent subcommand requires the following arguments:

realm, agentname, adminid, password-file

The options bounded by square brackets are optional. However, you need to use either --attributevalues or --datafile to provide an attribute name and the corresponding value.

The following is an example of how to set the locale for a web agent by storing the property name and value in a data file:

[root@localhost]# ./famadm update-agent -e testRealm1 -b testAgent1 -u amadmin -f /tmp/pwd -D /tmp/testproperty

where the testproperty datafile contains the following text:

Updated 05/09/08 - I got some comments from developer Charles Wesley about this blog entry. I concluded that I should add one more section to it. Therefore, I've added the following section about wildcards:

Wildcards and Attribute Values: A Word of Caution

When issuing the famadm command, if you include attribute values that contain wildcards (e.g. '\*'), then the  associated attribute name/value pair should be enclosed in double quotes to avoid substitution by the shell. This applies when you use the -a (or --attributevalues)argument. This isn't necessary when you list the attributes in a data file and access them with the -D argument. The following example demonstrates the use of double quotes while setting a J2EE attribute (Not Enforced URIs).

[root@localhost]# ./famadm update-agent -e testRealm1 -b testAgent1 -u amadmin -f /tmp/testpwd -a "com.sun.identity.agents.config.notenforced.uri

Sunday May 04, 2008

More About Configuring Policy Agent 3.0

Michael blogged about Policy Agent 3.0 property configuration in the following entry:

Policy Agent Configuration with Agent 99

I have a few things I can share in this area:

This is all relatively new stuff; some stuff I mention is yet to be finalized. So um, uh, set your expectations accordingly.

Image of the Policy Agent 3.0 Local and Centralized Configuration Options

Since I just happened to take a snapshot of the Federated Access Manager (FAM) Console of the creation of an agent profile, I thought I'd share the image:

Agent Profile

Looking at the image above, you can see that you have the option while creating the profile to set the configuration to local or centralized. 

FAM Command-Line Interface (CLI) Examples

There's a lot you can do with the CLI to configure agents. Here, I'm just focusing on configuring the agent properties.  By the way, to create the agent, the command starts as follows:famadm create-agent. However, The examples below are for updating an agent after it's created.

Updated 05/05/08 - I found that the examples that were here yesterday were inaccurate. The new examples below should be correct. I'll add an entry about using the command line to configure agents. There's already some good info on it here:

Example 1: Below is an example of how to use the CLI to change the Agent Locale.

./famadm update-agent -e testRealm1 -b testAgent1 -u amadmin -f /tmp/testpwd -a "com.sun.identity.agents.config.locale=en_US"

Example 2: Below is an example of how to use the CLI to change the FAM Login URL

./famadm update-agent -e testRealm1 -b testAgent1 -u amadmin -f /tmp/testpwd -a "com.sun.identity.agents.config.login.url="

Policy Agent 3.0 Properties: Labels, Names, and Double Secret Other Stuff

Policy Agent developer Sean Brydon said to me, "Why don't you put together a wiki page that lists all the 3.0 agent properties so people can add details whenever they want?" I'm putting  that sentence in quotes as if that's what he said word for word. And though I don't remember what he actually said, I think it's safe to say that that's not exactly what he said. I'm just seeing if he's going to sue me for misquoting him. So, I'm testing just how "open" this OpenSSO thing is.

Anyway, whatever he actually said, he must have been pretty convincing because I've been working on that wiki page. Do you want to see it? Well, even if you don't, here's the link: 

I'll keep working on it. I don't know when you'll look at it, if at all (I mean, after all, I don't even know who you are) but if it's around early May, 2008, there's probably lots that can still be done.

The End

P.S. While I am a big fan of Get Smart, I have nothing to say about Agent 99 at this time. Sorry about that Chief.


What does this box do?


« April 2014