| Previous Contents DocHome |
| Directory Server Access Management Edition Programmer's Reference Guide |
Chapter 6 Using the Command Line Interface
This chapter describes how you can use the amadmin command line interface tool. It contains the following sections:
"Overview of the amadmin Command Line Interface Tool
"How the amadmin CLI Tool Works
"Guidelines for Loading Services into DSAME
"Guidelines on Performing Batch Updates to User Objects in Directory Server
Overview of the amadmin Command Line Interface Tool
This chapter describes the command-line interface (amadmin) available for iPlanet Directory Server Access Management Edition administration. The primary purpose of the amadmin tool is to help an administrator perform batch administrative tasks on the Directory Server, for example, create, register, and activate new services; and create, delete, and read (get) organizations, people containers, groups, roles, and users.The primary purposes of the amadmin CLI tool in this release are to:
Load service schema definitions in XML files. This lets DSAME administrators load their services into DSAME (and iPlanet Directory Server) in XML file format using the amadmin CLI tool, and then implement the service based on the schema. In this release of DSAME, you MUST load all services into DSAME (and Directory Server) by using the amadmin tool; you cannot load or import services through DSAME's Administration Console.
The amadmin CLI tool takes one or more XML files as input. Then it reads all the requests described in the XML file(s) and submits these requests to Directory Server through the DSAME SDK. Such requests include those for creating, getting and deleting various directory objects, as mentioned above.
To register a service through the amadmin CLI tool, you first define the service schema and configuration data in XML file(s), and then import the XML file(s) using the amadmin CLI tool.Perform batch operations (such as creating, deleting, and reading user objects in the Directory server, such as users, organizations, groups, people containers, roles, etc.) For example, if an administrator wants to create 1000 organizations, people containers, users, and groups, he/she can do this in one attempt by putting all the requests in one or multiple XML files for performing batch operations (such as <dsame_root>/samples/admin/cli/bulk-ops/
createRequests.xml and <dsame_root>/samples/admin/cli/bulk-ops/deleteRequests.xml files) and run the amadmin tool once. Otherwise, an administrator has to create these objects in Directory Server one at a time in DSAME Administration Console.There are two DTDs that the XML files should adhere to:
In this chapter, there are some sample XML files (one for loading a service, and one for performing a batch load operation such as a create requests operation to create some user objects in the DIT, two DTDs (an sms.dtd and an amAdmin.dtd), and how to load the service into DSAME. The sample XML files provided with this build are located in:
- sms.dtd—All the service XML files (for example, all the service XML files located in the <dsame_root>/SUNWam/web-apps/services/dtd directory) must adhere to the Service Management Services) sms.dtd file.
- amAdmin.dtd—All the XML files that perform batch updates to the Directory Information Tree (or DIT), which are located in the <dsame_root>/web-apps/services/amAdmin.dtd directory, must adhere to the document type definition rules defined in the amAdmin.dtd file.
The DTD files (sms.dtd and amAdmin.dtd) are located in:
They set up rules for how the XML files should be written, how an administrator would perform batch operations on the DIT, for example, adding new users and roles to the Directory server in batch mode. An administrator may want to perform a large number of operations on the DIT, and could use the sample XML files provided to perform creates, deletes, and gets on the Directory server.
- <dsame_root>/SUNWam/web-apps/services/dtd
Note When loading services and when performing batch updates on the Directory server, two different dtds are used; services use the sms.dtd; batch updates to the DIT use the amAdmin.dtd.
The amadmin CLI tool is not intended to be a replacement for Admin Console Tool, which has a GUI interface. The amadmin CLI tool does not support all the features that can be executed from DSAME's Admin Console. It is recommended that you use Admin Console GUI for any incremental administrative tasks while you use the amadmin CLI tool for any batch administrative tasks.
How the amadmin CLI Tool Works
The primary function of amadmin CLI tool comprises two different phases:
Service schema definition in XML and registration
To define the metadata (what type of attributes the service will have, how many attributes the service will have, what kind of policy attributes the service will have, what the attribute names are, etc.)
Data creation in Directory Server DIT (or populating the Directory Server DIT):
To actually create the DIT entries such as organization, group, people container, user, and role, the attributes defined in these entries will use the schema defined in the service XML file. For example, if an attribute A in the "user" entry is from some service X, the type (metadata/schema) of the attribute (string, boolean, integer, or some other attribute type) is determined using the schema defined in the service schema definition in the service XML file (for example, amAdminConsole.xml).
What you can use the amadmin tool for
The amadmin CLI tool provides a way for you to perform the following actions on the Directory server:
Import services.
File pathnames follow UNIX filesystem conventions. <dsame_root> refers to the installation directory where the Directory Server (iPlanet Directory Server) is installed, and is /usr/iplanet/servers by default.Create roles, users, organizations, groups, people containers, and services.
Delete roles, users, organizations, groups, people containers, and services.
Read (get) roles, users, organizations, groups, people containers, and services.
Read (get) roles, people containers, users.
Read (get) number of users for groups, people containers, roles.
Register a service for an existing organization.
Unregister a service from an existing organization.
Activate a service for an existing organization.
Deactivate a service from an existing organization.
Get registered service names from an existing organization.
Get activated service names from an existing organization.
Get the total number of registered and activated services for an existing organization.
<dsame_root> refers to the installation directory where DSAME services and agents are installed and is /opt/SUNWam by default.
Requirements to run amadmin CLI Tool
To perform batch updates on the Directory Server (DIT), you will need a sample XML file conforming to the DTD. This DTD is located in<dsame_root>/web-apps/services/dtd/amAdmin.dtd
To load services, you will need to use one of the sample XML files provided for defining service schema and configuration data, or you can use one of these to create your own service XML. Refer to the DTD provided for when loading services. This DTD is located in
<dsame_root>/web-apps/services/dtd/sms.dtd
The <dsame_root> by default is /opt/SUNWam. If you install DSAME using the default DSAME installation directory, this is where the DSAME build will be installed.
Installation/Setup
When DSAME 5.0 is installed, the amAdmin CLI tool also gets installed along with the server. The amserver is located in <dsame_root>/web-apps/services/WEB-INF/bin,
and the amAdmin CLI tool is installed in the <dsame_root>/web-apps/services/WEB-INF/bin directory. The amadmin CLI tool is a shell script wrapper around the actual Java class, which is the actual implementation of this CLI.
Syntax for using the amadmin Tool
The syntax for using the amadmin tool follows:
Note You must enter two hyphens (not one) exactly as shown in the command lines instructions in this section.
amadmin --runAsDN <dnname> --password <password>
[--locale <localename>] [--verbose|--debug]--data
xmlfile1 [xmlfile2 ...]
amadmin --runAsDN <dnname> --password <password> [--locale localename]
[--verbose|--debug]--schema xmlfile1 [xmlfile2 ...]
amadmin --runAsDN <dnname> --password <password> [--locale localename]
[--verbose|--debug]--deleteService <serviceName> [<serviceName2> ...]
amadmin --help
amadmin --version
Detailed descriptions of all the above-mentioned arguments is in the next sub-section.
Syntax Description for the amadmin Command Line Interface Tool
Following are syntax descriptions for the amadmin command:
or you can insert spaces between the different domain components of the DN, and double quote the entire DN:
- is a mandatory argument and its value is <dnname>. Replace <dnname> with your own DN. <dnname> is the DN of the authorized user who is running the amadmin. It is used to authenticate to the LDAP server. For example:
- --runAsDN uid=amAdmin,ou=People,o=iplanet.com,o=isp
--password' is a mandatory argument and its value is <password>. Replace <password> with your own password, which should correspond to the DN (Distinguished Name) name provided.
- --runAsDN "uid=amAdmin, ou=People, o=iplanet.com, o=isp"
--locale is an optional argument and its value is 'localename'. Replace 'localename' by your own 'localename'. This argument is used for the customization of the message language. If this argument is not provided then default is used. Default locale is 'en_US', which is US English.
--debug is an optional argument. When used, this option writes messages to the file amAdmin which is created under the /var/{BASE_DIR}/SUNWam/web-apps/services/debug directory. These messages are more detailed in technical terms. However, the messages written in the amAdmin file are not i18n-compliant.
--verbose is an optional argument. When used, this option does not print detailed information; instead, it prints the overall progress of the amadmin command on the screen. All the messages output on the command line are i18n- compliant.
--data option creates, deletes and reads the various directory objects such as roles, groups, organizations, and containers, which are detailed in the XML input files. The --data option also registers, unregisters, activates, and deactivates a service; and gets the number of activated and registered services, and registered and activated service names for an existing organization. You can specify multiple XML files or just specify one XML filename (such as createRequests.xml or deleteRequests.xml) for this option. You must provide either the --data or --schema option depending on whether you are performing batch updates to the DIT, or loading service schema and configuration data.
--schema option loads (imports) service schema and metadata (configuration data), which is detailed in the XML input files. When loading service schema information, you can also specify multiple XML filenames, in addition to a single XML filename (such as sampleMailService.xml). You must provide either the --data' or --schema option depending on whether you are performing batch updates to the DIT, or loading service schema and configuration data. <xmlfiles1> is not an argument. <xmlfiles1> is the name of a single XML filename or multiple XML filenames to be loaded or imported into the DSAME (and Directory server).
--deleteService argument is for deleting a service—its schema only. This service must have been imported previously by using the amadmin CLI tool's --schema option.
--serviceName1 is the ServiceName which is under the <ServiceName=...> tag of the serivce XML file.
--help displays the command syntax for the amadmin command.
--version argument displays the utility name, product name, product version and legal notice.
First step for any service in its lifecycle is to load its schema into DSAME.
The service should display in the available Services list in the Admin Console GUI under the User management page.At this point, no organization has yet registered for this service. So the second step would be to register the service for the organization so that the organization has access to (or can avail of) that service. For example, in a hosted environment, different orgs may purchase (register) different sets of services.
Registering and Unregistering a Service for an Organization
This section provides some information on registering and unregistering a service for an organization. After importing, or loading, service schema and configuration information into DSAME using the amadmin CLI tool, you must first register the service (using the registerRequests.xml file), then you must activate the service (using an activateRequests.xml). Similarly, when deactivating a service, you must first deactivate the service, then unregister the service, in that order.You use the amadmin CLI tool's -schema option to import (load) a service. After importing the service, the service is created in the "config" (configuration) area of the DIT for a particular organization.
Unregistering a service
Unregistering a service for a particular organization removes the COS definition of the service. This service must have been imported using the amadmin CLI for that particular organization.
Get Number Of Services
To get all services registered for an organization (all active and deactivated), use the getNumOfServices.xml file.
Guidelines for Loading Services into DSAME
This chapter provides an overview of service management in DSAME, and includes information on how to write service XML files per the DTD (sms.dtd). Also refer to the Readme.html file which is located in the following directory:<dsame_root>/samples/admin/cli
for more information on how to use the amadmin CLI tool to load services and perform batch updates to the DIT.
Make Sure you have the Necessary Files before Loading a Service
See Chapter 5 "Understanding DSAME XMLs and DTDs for information on the sample mail service files: sampleMailService.xml, sampleMailService.properties, and sampleMailService.ldif files.There is a sample mail service located in the <dsame_root>/samples/admin/cli/sampleMailService directory, along with an .ldif file and .properties file, which you can use to practice loading a service into DSAME. Following are brief descriptions of what you can do with these sample files:
sampleMailServiceSchema.ldif—The .ldif file contains the LDAP schema for the sampleMailService, which contains the necessary LDAP schema corresponding to the LDAP object classes and LDAP attribute names. You need to load the .ldif file for the service (such as sampleMailServiceSchema.ldif) into Directory Server using the ldapmodify command. If an administrator wanted to create a policy based on the sample policy schema defined in this file, for example, he or she would need to create the LDAP schema corresponding to the LDAP object classes and LDAP attribute names. For the sampleMailService, a sample .ldif file is provided in the <dsame_root>/samples/admin/cli/
sampleMailService directory.
In the sampleMailService.ldif file, the OIDs follow the standard convention of <attributename>-oid. When writing your own .ldif files to load the schema, you should use the read OIDs and get them registered before deploying DSAME. For more information about OIDs, or to request a prefix for your enterprise, send mail to the IANA (Internet Assigned Number Authority) at iana@iana.org or visit the IANA website at: http://www.iana.org/iana/.
sampleMailService.xml—You need to have a service xml file, which defines the necessary service schema and configuration data for your service per the rules defined in the sms.dtd file (for example, the sampleMailService.xml file already contains the necessary schema and configuration data). The service XML file (for example, sampleMailService.xml) defines attributes and object classes, among them i18Nkeys, also called localization keys, which map one for one to corresponding fields in the .properties files.
sampleMailService.properties—The sampleMailService.properties provides a sample .properties file, which defines the object class for the service profile, and the index keys that are defined in the service XML file (for example, i18nKey="a1" defines the localization key in the sampleMailService.xml file, which tells Admin Console to display that corresponding field on that service's page in Admin Console (in this case, it displays the field "Mail Status" on the Sample Mail Service Profile page in Admin Console).
- If writing a new service, you will need to update an existing schema and configuration data (in an XML file) with the necessary attributes and object classes. You can use this sampleMailService.xml as is, and load using amadmin.
- Note on sampleService.properties File
- The sampleMailService.properties file is used to display the sample services, attributes, etc. on the Admin Console when a user displays that service's page in the Admin Console.
- When a user or administrator brings up 'Service Management' in Admin Console, the Admin Console code looks for the sampleMailService.properties and gets the appropriate value for the key given and displays all information for that service on the Admin Console screen in the respective language specified.
- The path for this .properties file should be set correctly as described in "Specify pathname for sampleMailService.properties in jvm12.conf File".
Extend the Service Schema by Loading the .ldif File
Before creating any specific policies, you must extend the schema by using the ldapmodify command, which takes the .ldif file as input. (Also see the Directory server 5.0 documentation for information on updating schema.)Go to the install directory of Directory Server:
cd <DS_INSTALL_DIR>/shared/bin
By default, the "<userid to manage DS>" would be "cn=Directory Manager".
If the schema was created, the result of the previous command would be:
Modifying entry cn=schema To make sure that the schema has been created, use the ldapsearch command as shown below.
- If the schema was created, the result of the previous command would be:
Note The order in which you extend the schema (that is, run ldapmodify and ldapsearch) and then use the amAdmin CLI tool is not important. You can run the amAdmin CLI tool first, then load the schema.
However, after registering a service using the amadmin CLI tool, you should always run ldapmodify so that the objectclass of the service will be added to all the user entries. (See "Sample .ldif file that shows the objectclass of a service added to a user entry".) Or you can refer to the Directory server 5.0 documentation sections on extending schema for information.
Restart the Directory Server
Restart the Directory Server, which is located in the /<DS_INSTALL_DIR>/slapd-<hostname> directory.
Go to the directory where the Directory Server is installed:
Restart the Directory Server with:
- cd /<DS_INSTALL_DIR>/slapd-<hostname>
- ./restart-slapd
Specify pathname for sampleMailService.properties in jvm12.conf File
Next, modify the jvm12.conf file under the path <dsame_root>/servers/https-<fully-qualified-hostname>/config
Alternatively, you can copy the .properties file into the following directory:
- and add the following directory pathname:
- <dsame_root>/samples/admin/cli/sampleMailService
- to the entry jvm.classpath=
- All the .properties files should be located in the <dsame_root>/web-apps/services/WEB-INF/classes directory, by default.
- or
If you copy the .properties file to the classes directory, then you do not need to restart the Web and Directory servers (which is covered in "Start the Servers (Web and Directory Server )").
- <dsame_root>/web-apps/services/WEB-INF/classes
Start the Servers (Web and Directory Server )
Note This step is necessary only if changed the classpath (described in "Specify pathname for sampleMailService.properties in jvm12.conf File".)
Go to <dsame_root>/web-apps/services/WEB-INF/bin
Start the DSAME server in a terminal window:
- ./amserver start
Import the Service XML File(s)
Next, import the service's XML file, for example, "sampleMailService.xml".If the product has been installed in <dsame_root>/SUNWam, and Directory Server has been installed in <iDS_root_dir>, then after the product has been installed, follow the steps below to import the service XML file.
cd <dsame_root>/web-apps/services/WEB-INF/bin
./amadmin -runAsDN uid=amAdmin,ou=People,o=iplanet.com,o=isp -password passwordvalue -verbose -schema <dsame_root>/samples/admin/cli/sampleMailService/
sampleMailService.xml"
- After the sampleMailService.xml is loaded successfully, a message similar to the one below displays:
Register the Service
Next you must register the service. The preferred way to register a service is to go DSAME console and register the service. Or you could use a command similar to the following to register the sampleMailService (using the sampleMailService.xml).
Sample .ldif file that shows the objectclass of a service added to a user entry
You only need to perform this step if users already exist.If you create users after the service has been loaded, you can skip this step. (This step provides information on what to do if users already exist, and you must add the objectclass to the users. If users do not exist, and you create after you have loaded the service, then this is done automatically for you, and you do not have to add the objectclasses.
If you have to perform batch updates to user objects in the DIT, you can use the migration scripts provided in DSAME 5.0. These migration scripts are described in the iPlanet Directory Server Access Management Edition Installation and Configuration Guide.
Below shows some sample ldif that shows the objectclass of the service "iplanet-am-sample-mail-service" added to a user entry, specifically "shiva", after the schema has been extended. For example, you might create an .ldif file named xyz.ldif with the entries below:
Then run the ldapmodify command as shown here:
Add the sampleMailService to the Service Hierarchy
The Admin Console displays only DSAME-related services. If you are adding new (customized) services, then you must add them to the service hierarchy so you can view them on the Admin Console's Service Management page.
To display the sampleMailService in the Admin Console, you need to add the sampleMailService to the service hierarchy so that it will display under Other Configuration on the Service Management page. To do this, do the following steps:
Bring up the DSAME Admin Console by entering the URL into a web browser, for example,
After you have done all the above procedures (that is, modify the jvm12.conf file, import the service, then register and activate the service), you should be able to create templates through the Admin Console, and then add new roles and users, and assign policy attributes to them.
In Admin Console, select Service Management.
- http://sparkie10.red.iplanet.com:8080/console
- and logging into DSAME Admin Console as amadmin (as the top level administrator or Super-administrator).
Select the arrow for Administration under DSAME Configuration.
Scroll down to Service Hierarchy which is under Administration - Global.
Click Submit.
- other.configuration|sampleMailService
- into the textfield and click Add.
Go to the Service Management page, and view the sampleMailService and its profile on the ServiceManagement page.
Administration Service Attribute (iplanet-am-admin-console-service-hierarchy)
This section explains what the iplanet-am-admin-console-service-hierarchy attribute is used for. The part about DSAME services would be for DSAME developers or someone like an ISV who would adding an external or custom service that would be considered part of DSAME. A good example of this would be an authentication service. An authentication service is actually an addition to the services of DSAME, even though it is not shipped with DSAME. (This might also be referred to as an "external service", which means that it is not shipped as an internal service with DSAME, such as Logging, Session, and Naming services.)If the new service is something that is not an internal DSAME service (that is, shipped with DSAME), then it would go under Other services. An example of this would be something like a Calendar application or Mail service.
The first method could be used if someone loaded an XML service using amadmin and then needs to add it to the hierarchy. They would use the Admin Console to add their service to the hierarchy.
After making modifications to the amAdminConsole.xml, run
This is also an option as with any service. Customization engineers or administrators can make their modifications through the Admin Console or command line. Note that this is only for the default values. Other XML components like type, syntax, and i18n keys must be modified using the amadmin CLI tool. Typically, customization engineers and administrators will only do this during installation by using the amadmin CLI tool.
- amadmin -deleteService amAdminConsole
- amadmin -schema amAdminConsole.xml
There are two ways to have a new service shown in a hierarchical manner.
First (preferred) method
Go to the DSAME Admin Console, click on the Service Management view, click on Administration Service and look for the Service Hierarchy list. Update the list according to the format described in the section "Second Method (Alternative)".The second method allows you to import the service hierarchical information to Directory Server upon installation. The first method allows you to change the hierarchical information after you have imported, or loaded, the service into DSAME.
Second Method (Alternative)
This method is only applicable if you are installing DSAME for the first time. Only use this method if you have not changed the defaults for the Admin Console service (amAdminConsole.xml), or if you have reverted back to the installation defaults.Only use the first method if you know that you have not changed the amAdminConsole.xml service. The reason for this is because at installation time, defaults are loaded. Then the administrator can change some parameters for the service, which modifies the schema in the XML in the Directory server. Then if you were to reload this service, you would overwrite all those changes that had been made previously to the XML in the Directory server.
com/iplanet/dpro/admin/xml/amAdminConsole.xml
under the Configuration tag iplanet-am-admin-console-service-hierarchy attribute, if it is a DSAME service, it will be:
dsame.configuration|<serviceName>
<Value>dsame.configuration|iPlanetAMAdminConsoleService</Value>
If it is a DSAME authentication service, it will be
If it is a third party service (versus being an "internal DSAME server", such as Naming service, Session service, or Logging service), it will be:
- dsame.configuration|authentication|<serviceName>
- <Value>dsame.configuration|authentication|iPlanetAMAuthAnonymousService</Value>
For example:
- other.configuration|<serviceName>
<Value>other.configuration|XYZService</Value>
Assign Policies to the Sample Mail Service
The following steps give some information on how you would assign policies to a service after loading it into DSAME Admin Console.
Log in to the Admin Console as amadmin, if you are not already logged into Directory Server Admin Console.
Go to the Policy Management page for o=iplanet.com.
On the Properties page for the Sample Mail Service Profile, select the value of the priority to higher, and the mail quota to 8888.
Create the service in the o=iplanet.com organization.
Go to the User Management page for o=iplanet.com.
Assign user "user1" to the role of "role1".
Select roles, select role1, then select Services.
Click on Properties for the sampleMailService to create a template.
Go to the Policy Management page.
Go to the organization o=iplanet.com.
Click on the "sampleMailService" properties.
Create a policy template, and change the value of the priority to "highest" and the mail quota to 6666.
Do an ldapsearch for "user1". To do this, go to the directory /<DS_INSTALL_DIR>/shared/bin/ and run:
Check that the attributes of the "sampleMailService" are present and that the mail quota = 6666.
- ./ldapsearch -h localhost -p 389 -b "uid=user1,ou=People,o=iplanet.com,o=isp -D "cn=Directory Manager" -w password "(objectclass=*)"
View the Policy Profile for a Service that has been added to DSAME
This section gives a procedure on how to view the policy profile of an added service for an organization on the Admin Console's Policy Management page.
If you did not create Policy through the amadmin CLI tool, do the following:
After importing the service using amadmin, then creating user management objects amadmin, then registering and activating the service through amadmin:
Log into the DSAME Admin Console by entering the URL into a web browser, for example,
Click Policy Management.
- http://sparkie10.red.iplanet.com:8080/console
- and logging into DSAME Admin Console as amadmin (as the top level administrator or Super-administrator).
Choose the service from the choice box.
Type in the policy name and then select Create.
Make your changes to the policy template and click Submit, if needed.
- The policy template displays.
Choose the policy you have created and view its profile.
- Log in and then repeat Step 2 through Step 4.
If you created Policy through the amadmin CLI tool, do the following:
After importing the service using amadmin, then creating user management objects amadmin, then registering and activating the service through amadmin:
Log into the DSAME Admin Console by entering the URL into a web browser, for example,
Click Policy Management.
- http://sparkie10.red.iplanet.com:8080/console
- and logging into DSAME Admin Console as amadmin (as the top level administrator or Super-administrator).
View the Profile for an Added Service
This section gives information on how to view the profile for an added service for an organization in the Admin Console's User Management pageAfter importing, registering, and activating the service, log into the Admin Console.
Select User Management.
Select the organization for which the service is registered.
Click the service for which you want to view the profile.
Press Create to create the template.
- The message `There is no template for this service' displays.
Log in again and repeat steps Step 1 through Step 4.
- The dynamic attributes and the profile for the added service for that organization displays.
Guidelines on Performing Batch Updates to User Objects in Directory Server
This section provides an overview how you typically would perform batch updates on user objects (such as groups, users, roles, people containers, etc.) in the Directory Server. You can use the sample XML files provided in the following directory:<dsame_install_dir>/SUNWam/samples/admin/cli/bulk-ops/CreateRequests.xml
GetRequests.xml
Requests.xml
deleteOrgRequests.xml
deletePCRequests.xml
deleteGroupRequests.xml
registerRequests.xml
unregisterRequests.xml
activateRequests.xml
deactivateRequests.xml
getActivatedServices.xml
getRegisteredServices.xml
getNumOfServices.xml
Note Be aware that creations of roles, groups, and organizations is a time-intensive operation.
List of Sample XML Files for Performing Batch Updates to DIT
Sample XML input files for -data option are provided in the following directory:<dsame_root>/SUNWam/samples/admin/cli/bulk-ops/
The xml files and brief descriptions of their purpose follows:
createRequests.xml—Creates all the objects in the Directory Server.
getRequests.xml—Gets information about all objects (previously created by createRequests.xml).
deleteOrgRequests.xml—Deletes all objects (previously created by createRequests.xml) under the Organization.
deletePCRequests.xml—Deletes all objects (previously created by createRequests.xml) under the People Container.
deleteGroupRequests.xml—To delete all objects (created by createRequests.xml) under Group.
registerRequests.xml—Registers a service for an existing organization. This service must have been imported using the amadmin tool.
unregisterRequests.xml—Unregisters a service for an existing organization. This service must have been imported using the amadmin tool. (If a service has been registered, then activated, it must first be deactivated, then unregistered.)
activateRequests.xml—Activates a service for an existing organization. This service must have been previously imported and registered by using the amadmin tool.
deactivateRequests.xml—Deactivates a service for an existing organization. This service must have been imported and registered using the amadmin tool.
getActivatedServices.xml—Gets the list of activated service names for an organization.
getRegisteredServices.xml—Gets the list of registered service names for an organization.
getNumOfServices.xml—Gets the total number of registered and activated services for an existing organization.
Steps to Perform Batch Updates to DIT
Following is a list of high level steps and things to do when performing batch operations on Directory Server through DSAME's amadmin tool.
Define user objects in createRequests.xml File
First define the user objects you want to create in Directory Server in the createRequests.xml file, provided in the following directory:
- <dsame_root>/samples/admin/cli/bulk-ops
- The createRequests.xml file creates groups in the default mode (non-compliant DIT and schema).
Changes to make if the DSAME product is installed in Compliant mode (iPlanet DIT and schema mode)
There are now two modes for the product:
iPlanet DIT and schema mode (compliant)
Default mode (non-compliant)
- If you have installed in the "Compliant mode" (that is, iPlanet DIT and schema mode) you must modify the createRequests.xml file to create the groups under ou=Groups,o=sun.com. (Replace the actual organization name for sun.com, shown in this example.)
<DN>ContractorsGroup,ou=Groups,o=sun.com</DN>
<DN>EmployeesGroup,ou=Groups,o=sun.com</DN>
- iPlanet DIT and schema (Compliant) mode dictates that o=ISP be a child of the root suffix, which must be entered during the installation process. All orgs will then be created under o=ISP,<root suffix>.
- In default mode ,the 'ou=Groups' is not created. 'ou=Groups' is created only when running in the iPlanet DIT and schema (Compliant) mode. The createRequests.xml file in the samples/admin/cli/bulk-ops directory shows the sample XML format for creating groups in the default mode (that is, non-compliant mode).
- Therefore, you must modify all related 'o=isp' in the sample XML files as 'o=ISP,o=xyz', with 'xyz' being the root suffix entered by the administrator during installation of DSAME in iPlanet DIT and schema (compliant) mode.
Load the Batch Update Defined in the XML File into DSAME
To load an XML file that defines some batch operations such as creating, deleting, or getting (reading) user objects (such as organizations, people containers, roles, users, groups) in the DIT, run the amadmin command with the -data option.
Go to the following directory:
Run the following command:
- <dsame_root>/SUNWam/web-apps/services/WEB-INF/bin
- This directory contains the amadmin executable.
Verifying that the DIT has been Populated Correctly
If you want to verify that the DIT has been populated correctly in Directory Server , do the following steps:
Verification Caution
Typically, when you use amadmin to perform batch operations on Directory Server. Even without the additional verification, such operations may sometimes takes hours, and in extreme cases, even days.So you should be careful that the additional verification will only add additional hours or even days, depending on the amount of data.
Also, when you perform a verification, you should start the dump on the appropriate subtree instead of on the entire tree, which would take longer, and be unnecessary.
When performing a verification action, be aware that When amAdmin CLI tool is normally used, it is for batch operations. Even without the additional verification, such operations may sometimes takes hours and in extreme cases, even days.
Be careful that the additional verification operation will only add additional hours or even days, depending on the amount of data. Also, when you verify, you should start the dump on the appropriate subtree rather than the entire tree.
View the .ldif File to Ensure that the objects were created in the Directory server
View the .ldif file in <DS_INSTALL_DIR>/slapd-<hostname>/ldif directory to ensure that all the objects (described in createRequests.xml file) with their attributes and values were created. You can do this with any text editor or viewer.
Tips when running amadmin Tool
Following is some useful general information that involves using the amadmin CLI tool.
Using ldapmodify versus the DSAME amadmin Tool
Both ldapmodify and the amadmin CLI tool "eventually" end up using LDAP SDK/JDK to communicate with Directory server. So, in theory, whatever you can do with the amadmin CLI tool can be done with ldapmodify (not the other way round). Primarily, the benefits of CLI are ease-of-use, higher-level abstraction and XML-compliance. Other than creating users, it is not recommended that you use ldapmodify to create entries for DSAME.
Benefits of using CLI and XML Files
When creating certain higher-level DSAME abstractions (such as policies, service management), you do not have to learn or know how these abstractions are "implemented" or "mapped" to the DIT. Not all DSAME abstrations map 1-1 with Directory Server entries. For example, there may be more than one Directory Server entry manipulated as a result of some higher-level user operation. So users also don't have to know the "inter-dependencies" between different entries.The CLI tool will ease such tasks by avoiding any problems with inconsistent updates of Directory Server using ldapmodify. With ldapmodify, customers may have to know and list all the LDAP object classes and relevant LDAP attribute names. DSAME CLI hides most of the low-level details of LDAP by allowing the customer focus on tasks such as creating users, adding users to roles/groups, etc.
Most customers (developers) are more familiar with XML syntax than with the ldif syntax. For such customers who are comfortable with XML, they can continue to use XML instead of learning a new/one-more syntax. The availability of XML editors "sometimes" helps customers write XML files and validate the syntax right away.
How to Determine Attribute/Value Pairs to Provide in the XML Files
When creating user objects in the Directory, such as organizations and people containers, it may be difficult to determine what attribute/value pairs to give in the XML files. You can set or specify any attributes that are specified in the DSAME configuration file's CreationTemplates. (Currently, the DSAME configuration file is called ums.xml or umsCompliant.xml, and is located in <dsame_root>/SUNWam/config/ums.xml.) Every entry that DSAME creates must have a corresponding CreationTemplate, which instructs the User Management component of how to create that entry. It specifies what objectclasses and attributes are mandatory and optional and what default values should be set, if any.If a deployment engineer or customization developer wanted to add customized object classes to DSAME, they would need to modify the templates in the DSAME configuration file (ums.xml or umsCompliant.xml) so that both DSAME and Directory Server can read and recognize the new object classes and attributes. Then, to manage them from the DSAME Admin Console, these new object classes and attributes have to be defined and "modelled" in the XML format, then imported into DSAME using the procedures described in this chapter.
Which XML Files are Used for DSAME User Management
Any attribute/value pairs that Directory Server must know about, that is, read, store, or perform some operation on, must be defined in the ums.xml file. Any attribute/value pair that is to be displayed in DSAME Admin Console's User page must also be defined in the dpUser.xml file. The attribute/value pairs defined in the ums.xml file defines all the possible user objects that Directory server can create, read, and search on. For the attribute to be displayed in Admin Console, you must define those in the "user" subschema in the dpUser.xml file. Also, a corresponding .properties file must be created, with accurate i18nKey fields (called "localization keys" or "index keys") which point to actual field names to be displayed on that User server page in Admin Console.
Explanation on Defining GetUsers in amAdmin.dtd
This section provides information when performing batch updates to the DIT.To give an example and description of what DNsOnly=true|false means, for those objects that may have LDAP attributes, all 'get' operations follow the same design pattern which is given below:
If the element has an XML attribute 'DNsOnly' set to true or doesn't have that XML attribute, only the DNs of the corresponding DSAME objects shall be returned.
If DNsOnly="false", the entire object (with the LDAP attribute value pairs) shall be returned.
However, the behavior of DNsOnly is valid ONLY if there are no child elements (DNs) specified.
If the DNs are specified, the entire object shall always be returned.
Additionally, say if an administrator or user wanted to list two users, syntax for 'GetUsers' in amAdmin dtd is the following:
All Files Input with the amadmin Tool must be XML Files
You cannot use the amadmin CLI tool with anything other than XML input files. All requests (commands) to the amadmin tool are imported or fed into DSAME through XML input files. Thus the amadmin CLI tool is not involved in any operations that do NOT involve XML files. If an administrator wants to populate the DIT in Directory Server with user objects (create roles, groups, people containers, etc.), or perform batch reads (gets) or deletes on the Directory server DIT, then he or she must be able to write the necessary XML input files based on the amadmin data DTD or SMS schema DTD.
Using amadmin vs. DSAME's Admin Console
The primary purpose of the amadmin CLI tool is to enable administrators to perform batch operations possible for the case where users want to import a significant amount of data into the database. This is very time-consuming if Admin Console is used. You would have to perform each creation, deletion, or read operation one at a time.The amadmin tool only supports a subset of features that Admin Console supports.
You can only perform service registration (that includes importing service schema and configuration data through XML input files) through the amadmin tool.
This process may take hours if the number of users is large.
Service Registration XML DTD
For information on the service registration XML DTD, see Chapter 5 "Understanding DSAME XMLs and DTDs. It provides some information on the sms.dtd elements and attributes that DSAME uses, and describes how you would use the supported attributes types to create a custom service.When importing or loading any new or customized services to DSAME, you must write a service XML containing service schema and configuration data that corresponds to this DTD.
This DTD is located in the following directory:
<dsame_install_dir>/SUNWam/web-apps/services/dtd
Deleting a Service that has been Registered and Configured
If a service (having dynamic attributes) has been registered and configured in Admin Console for several organizations and roles, and it is in use, an administrator can delete this service. It can be deleted through Admin Console or by using the --deleteService option of amadmin tool.
You should not delete the DAI Service (ums.xml configuration file)
To modify the ums.xml configuration file after installation of DSAME, use the Directory server Console.DSAME does not support deleting the DAI service (ums.xml configuration file). The way to modify the DAI service (ums.xml) is either through LDAP (modifying an .ldif file directly) ro through the Directory Server Console. The reason that deleting and reloading this file through the amadmin CLI tool is not supported is that if the smallest error introduced into this file when making modifications may cause the DSAME platform to not initialize.
You may, however, delete the ums.xml configuration through the Directory Server Console (it's called DAI service) and then reimport the file using amadmin.
It is recommended that any modifications made to the ums.xml configuration file be done through the Directory Server Console, as this method is less error-prone than modifying the ums.xml file directly.
Basedn for DAI Service Tree
Following is the location and basedn for the DAI service tree in Directory Server:
- ou=DAI,ou=services,<install root suffix>
Location in Directory Server for User creation template for adding service object classes
Following is the location in Directory Server for the User creation template (for when adding service object classes):
- ou=BasicUser,ou=CreationTemplates,ou=templates,ou=1.0,ou=DAI,
ou=services,<install root suffix>
Location in Directory Server for Organization creation template for different org object classes and naming attributes
Following is the location in Directory Server for the Organization creation template (for when adding different organization objectclasses and naming attributes):
- ou=BasicOrganization,ou=CreationTemplates,ou=templates,ou=1.0,
ou=DAI,ou=services,<install root suffix>
Previous Contents DocHome
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.
Last Updated December 05, 2001