Chapter 9 The amadmin Command Line Tool

This chapter provides information on the amadmin command line tool and contains the following sections:

The amadmin Command Line Executable

The primary purposes of the command line executable amadmin is to load XML service files into the Directory Server and to perform batch administrative tasks on the DIT. amadmin can be found in IdentityServer_base/SUNWam/bin and is used to:

Load XML service files - Administrators load services into Identity Server that use the XML service file format defined in the sms.dtd. All services must be loaded using amadmin; they cannot be imported through the Identity Server console.



Note	XML service files are stored in the Directory Server as static blobs of XML data that is referenced by Identity Server. This information is not used by Directory Server which only understands LDAP.

Perform batch updates of identity objects to the DIT - Administrators can perform batch updates to the Directory Server DIT using the batch processing XML file format defined in the amadmin.dtd. For example, if an administrator wants to create 10 organizations, 1000 users, and 100 groups, it can be done in one attempt by putting the requests in one or more batch processing XML files and loading them using amadmin. More information on this can be found in the “Service Management” chapter in the Sun One Identity Server Programmer’s Guide.



Note	amadmin only supports a subset of features that the Identity Server console supports and is not intended as a replacement. It is recommended that the console be used for small administrative tasks while amadmin is used for larger administrative tasks.

The amadmin Syntax

There are a number of structural rules that must be followed in order to use amadmin. The generic syntaxes for using the tool are:

amadmin -h | --help

amadmin -n | --version



Note	Two hyphens must be entered exactly as shown in the syntax.

amadmin Options

--runasdn (-u)

--runasdn is used to authenticate the user to the LDAP server. The argument is a value equal to that of the Distinguished Name (DN) of the user authorized to run amadmin; for example

The DN can also be formatted by inserting spaces between the domain components and double quoting the entire DN such as: --runasdn "uid=amAdmin, ou=People, o=iplanet.com, o=isp".

--password (-w)

--password is a mandatory option and takes a value equal to that of the password of the DN specified with the --runasdn option.

--locale (-l)

--locale is an option that takes a value equal to that of the name of the locale. This option can be used for the customization of the message language. If not provided, the default locale, en_US, is used.

--continue (-c)

--continue is an option that will continue to process the XML files even if there are errors. For example, if there are three XML files to be loaded at the same time, and the first XML file fails, amadmin will continue to load the remaining files.

--session (-m)

--session (-m) is an option to manage the sessions, or to display the current sessions. When specifying --runasdn, it must be the same as the DN for the super user in AMConfig.properties, or just ID for the top-level admin user.

The following example will display all sessions for a particular service host name,:

amadmin -u uid=amadmin,ou=people,dc=iplanet,dc=com -v -w 12345678 -m http://sun.com:58080

amadmin -u uid=amadmin,ou=people,dc=iplanet,dc=com -v -w 12345678 -m http://sun.com:58080 username

You can terminate a session by entering the corresponding index number, or enter multiple index numbers (with spaces) to terminate multiple sessions.

The pattern may be a wildcard (*). If this pattern is using a wildcard (*), it has to be escaped with a meta character (\) from the shell.

--debug (-d)

--debug is an option that will write messages to the amadmin file created under the IdentityServer_base/var/opt/SUNWam/debug directory. These messages are technically-detailed but not i18n-compliant. To generate amadmin operation logs, when logging to database, the classpath for the database driver needs to be added manually. For example, add the following lines when logging to mysql in amadmin:

CLASSPATH=$CLASSPATH:/opt/IS61/SUNWam/lib/mysql-connector-java-3.0.6-st able-bin.jar

--verbose (-v)

--verbose is an option that prints to the screen the overall progress of the amadmin command. It does not print to a file the detailed information. Messages output to the command line are i18n- compliant.

--data (-t)

--data is an option that takes as its value the name of the batch processing XML file being imported. One or more XML files can be specified. This XML file can create, delete and read various directory objects as well as register and unregister services. For more information on what types of XML files can be passed to this option, see the “Servic Management” chapter in the Sun ONE Identity Server Programmer’s Guide.

--schema (-s)

--schema is an option that loads the attributes of an Identity Server service into the Directory Server. It takes as an argument an XML service file in which the service attributes are defined. This XML service file is based on the sms.dtd. One or more XML files can be specified.

--deleteservice (-r)

--serviceName


Note	Either the --data or --schema option must be specified, depending on whether configuring batch updates to the DIT, or loading service schema and configuration data.

--serviceName is an option that takes a value equal to the service name which is defined under the Service name=... tag of an XML service file. This portion is displayed in Code Example 9-1.

Code Example 9-1 Portion of sampleMailService.xml

...
<ServicesConfiguration>
<Service name="sampleMailService" version="1.0">
<Schema
serviceHierarchy="/other.configuration/sampleMailService"
i18nFileName="sampleMailService"
i18nKey="iplanet-am-sample-mail-service-description">
...

--help (-h)

--version (-n)

--version is an argument that displays the utility name, product name, product version and legal notice.

Creating Policies with amadmin

Policies can be administered through amadmin, however they cannot be modified using amadmin directly. To modify the policy, you must first delete the policy and the add the modified policy using amadmin.

To add policies using amadmin, the policy XML file must be developed following the policy.dtd. (policy.dtd is described in the Sun ONE Identity Server Customization and API Guide) Once the policy’s XML file is developed, you can use the following command to load it:

To add multiple policies simultaneously, place the policies in one XML file, as opposed to having one policy in each XML file. If you load policies with multiple XML files in quick succession, the internal policy index may become corrupted, and some policies may not participate in policy evaluation.

When creating policies through amadmin, ensure that the authentication module is registered with the organization while creating authentication scheme condition; that the corresponding LDAP objects (organizations, groups, roles and users) exist while creating Organization, LDAP groups’, LDAP roles’ and LDAP users’ subjects; that Identity Server roles exist while creating IdentityServerRoles subjects; and that the relevant organizations exist while creating sub organization or peer organization referrals.

Please note that in the text of Value elements in SubOrgReferral, PeerOrgReferral, Organization subject, IdentityServerRoles subject, LDAPGroups subject, LDAPRoles subject and LDAPUsers subject need to be the full DN.