created: 2012/07/30 14:16:01

Just a modest list of ssoadm (the command line tool for OpenAM administration). Note: As with other cheat sheets, this one remains a perpetual work in progress. The ssoadm command is extremely useful. It should be installed with every OpenAM depoyment.

OpenAM Cheat Sheet

Getting Help

The utility has its own help function:

ssoadm --help

Its use is also discussed in the OpenAM Command Line Reference on the OpenAM Wiki.

Installing the SSO Admin Tools

See my article on the OpenAM Tools for how I do it.

Getting and Setting Attribute Values

See Attributes and the ssoadm command, for important tips on how to get and set attribute values with ssoadm.

List the servers in an OpenAM environment

ssoadm list-servers 
-u amadmin 
-f $HOME/etc/pwd.txt

In this and the examples to follow "-u" is the ID of the admin user and "-f" in the full path to the pwd.txt file you created above.

List all Web Agents for a realm

ssoadm list-agents 
-u amadmin 
-f $HOME/etc/pwd.txt 
-t WebAgent 
-e testrealm

Here "-t" is for the type of agent, and "-e" is the name of the realm. The output will show the actual configuration directory dn of the realm.

List the configuration of a server

ssoadm list-server-cfg 
-u amadmin 
-f $HOME/etc/pwd.txt 
-s http://test1.example.com:8081/openam

Here the "-s" stands for "server", the value being the base url where your OpenAM node can be accessed.

List cookie domains

ssoadm get-attr-defs 
-u amadmin 
-f $HOME/etc/pwd.txt 
-s iPlanetAMPlatformService 
-t global 
-a "iplanet-am-platform-cookie-domains"

How I got here: The OpenAM Reference says that the cookie domain list is stored in the iplanet-am-platform-cookie-domains attribute. That attribute is defined in the amPlatform.xml schema file as part of the iPlanetAMPlatformService. Because cookie domains are configured under the "Configure" tab in the gui console, it is a global attribute.

Change the default cookie domain

ssoadm set-attr-defs 
-u amadmin 
-f $HOME/etc/pwd.txt 
-s iPlanetAMPlatformService 
-t global 
-a "iplanet-am-platform-cookie-domains=.newdom.com"

List the user datastores in a realm

ssoadm list-datastores 
-u amadmin 
-f $HOME/etc/pwd.txt 
-e /tesrealm

The "-e" parameter specifies the realm. The default "root" realm is "/". Example uses the "/testrealm" sub-realm.

Get the config for a datastore

ssoadm show-datastore 
-u amadmin 
-f $HOME/etc/pwd.txt 
-e /testrealm 
-m OpenDS 
>/tmp/opends-cfg.txt

Here "-m" is the name of the datastore as returned by the "list-datastores" command,

Update a datastore config

ssoadm update-datastore 
-u amadmin 
-f $HOME/etc/pwd.txt 
-e /testrealm 
-m OpenDS 
-D $HOME/data/additional-cfg.txt

"-D" points to a text file containing parameters to add or overwrite a datastore's configuration. For example, to add the attributes "departmentnumber", "o" and "ou" to the list of user attributes a datastore is configured for, you will need to create a text file that includes all of the values currently existing for:

sun-idrepo-ldapv3-config-user-attributes

and then add those new values thus:

sun-idrepo-ldapv3-config-user-attributes=departmentnumber
sun-idrepo-ldapv3-config-user-attributes=o
sun-idrepo-ldapv3-config-user-attributes=ou

Note that when updating an existing datastore configuration you should not include the

sun-idrepo-ldapv3-config-authpw

attribute unless you really want to change that password value (used to bind with the target directory server). By default this attribute is included in any config dump and is set to asterisks ("*****") for security -- which will result in your password being reset to all asterisks if you don't remove the line.

Create a datastore

This is most useful for when you want to "clone" a datastore configuration from one OpenAM server to another or even between realms.

ssoadm create-datastore 
-u amadmin 
-f $HOME/etc/pwd.txt 
-e /testrealm 
-m OpenDS 
-t LDAPv3ForOpenDS 
-D $HOME/data/ldap1-cfg.txt

The "-t" or "--datatype" parameter is mandatory in creating datastores. You can get the types supported by the server with:

ssoadm list-datastore-types 
-u amadmin 
-f $HOME/etc/pwd.txt

Output will look something like this:

Supported Datastore Types:
Description                              Type
---------------------------------------- ---------------
Database Repository (Early Access)       Database       
Active Directory                         LDAPv3ForAD    
Tivoli Directory Server                  LDAPv3ForTivoli
Sun DS with OpenAM schema                LDAPv3ForAMDS  
OpenDS                                   LDAPv3ForOpenDS
Active Directory Application Mode (ADAM) LDAPv3ForADAM  

If you use the output of the "show-datastore" command for an existing datastore as input for a new one, you'll want to change the value for:

sun-idrepo-ldapv3-config-authpw=******

... to the password of the admin user entry that will bind to the directory server for OpenAM. By default this is represented by a line of asterisks, which will definitely cause a bind failure. The value can be clear text. It will get encoded SHA when committed to the server configuration.

List Web Agents in a realm

Example given is for Web Agents in the /testrealm realm.

ssoadm list-agents 
-e /testrealm 
-t WebAgent 
-u amadmin 
-f $HOME/etc/pwd.txt

Show a Web Agent config

ssoadm show-agent 
-e /testrealm 
-b testagent-01 
-u amadmin 
-f $HOME/etc/pwd.txt 
>/tmp/testagent-cfg-01

Here "-b" is where you specify the name of the agent as shown by the list-agents command. There is an "-o" parameter for output files but I usually just use a redirect.

Create a Web Agent

Best done using an input file, usually from an existing agent configuration. Be sure to add this attribute/value pair to the end of your input file -- it is required for creating an agent object:

userpassword=agentpassword

The "agentpassword" string being the password used to authorize the remote agent's registration with the server. This parameter is left out of the output from the "show-agent" command.

ssoadm create-agent 
-e /testrealm 
-t WebAgent 
-b testagent-02 
-u amadmin 
-f $HOME/etc/pwd.txt 
-D /tmp/testagent-cfg-01

Notice I've used the output of an existing agent config for my input here (after inserting the userpassword attribute and value).

Update a Web Agent

Making changes to agent configurations using ssoadm can reduce errors commonly committed when using a gui. It can also come in handy when syncing agent configurations in a multi-agent environment. Begin by exporting the existing agent configuration (or configuration for the agent you want to sync with) using the "ssoadm show-agent" command as described above.

ssoadm update-agent 
-e /testrealm 
-b testagent-02 
-u amadmin 
-f $HOME/etc/pwd.txt 
-D /tmp/testagent-cfg-02

Check the resulting configuration in both the gui and at the command line (by doing another "ssoadm show-agent") to make sure none of the attribute values were munged, and correct as necessary. Pay particular attention to those attributes having multiple values.

Comparing Agent Configurations

In comparing web agent configurations it is always a good idea to first sort the results from the show-agent command, since attributes and their values are normally ordered randomly. You can do that like this:

sort testagent-cfg-01.txt >testagent-cfg-01.txt~

Copyright 2004-2019 Phil Lembo