Sun Java System Identity Server 2004Q2
Sample
 

Main Page

Command Line Interface, amadmin

Table of Contents

  1. Convention
  2. Requirements
  3. Installation/Setup
  4. Brief Description of amadmin
  5. Main Usage of amadmin
  6. How to use
  7. Examples

 

1. Convention

This Readme file provides some information on how to use the amadmin CLI tool.

{iDS_INSTALL_DIR} refers to the installation directory where the Sun Java System Directory Server is installed. Default installation directory is /var/Sun/mps on Solaris and C:\SunONE\SunONEIS\DServers on Windows2000.

{BASE_DIR} refers to the installation directory where the Identity Server is installed. Default installation directory is /opt on Solaris and C:\SunONE\SunONEIS on Windows2000.

 

2. Requirements

To load services, you need a sample XML file conforming to a service DTD.   This is located in {BASE_DIR}/SUNWam/dtd/sms.dtd on Solaris; and <install-root>\dtd\sms.dtd on Windows2000.

A sample service XML file is located in {BASE_DIR}/SUNWam/samples/um/user/sampleMailService.xml on Solaris; and <install-root>\samples\um\user\sampleMailService.xml on Windows2000.

To perform bulk update operations to the DIT, you need to use one or more of the bulk operations XML files that conform to a bulk operations DTD.  This DTD is located in {BASE_DIR}/SUNWam/dtd/amAdmin.dtd on Solaris; and <install-root>\dtd\amAdmin.dtd on Windows2000.

Sample bulk operations XML files are located in {BASE_DIR}/SUNWam/samples/admin/cli/bulk-ops directory on Solaris; and <install-root>\samples\admin\cli\bulk-ops on Windows2000.

 

3. Installation/Setup

When Identity Server 2004Q2 is installed, the Command line tool, amadmin is located in {BASE_DIR}/SUNWam/bin directory on Solaris; and <install-root>\bin directory on Windows2000.

amadmin is a shell script wrapper around a Java class which implements this tool.

 

4. Brief Description of amadmin

amadmin is a command line tool for administering the Identity Server. The primary intent of this tool is to aid bulk administrative tasks. For instance, create 1,000 organizations, people containers, users and groups, with a single command. To perform bulk operation, we need to put all the requests in a single XML file and execute it using amadmin. Otherwise, you have to create these objects in Directory Server by using the Admin Console 1,000 times.

One of the two primary features of the amadmin is to register service schema and service configuration data. Service schema registration is accomplished using service schema XML input files. These XML files must conform to a SMS schema DTD.

The other key features is to create, delete and modify Identity Server's objects such organization, user, group, role, etc. For these operation, amadmin takes an XML file, reads all the requests specified in the XML file and processes these requests accordingly.

amadmin is not intended to replace for Administration Console which is a Web based user interface. It is recommended that we use the Administration Console for any incremental administrative operations. And, we use amadmin for bulk administrative operations.

 

5. Main Usages of amadmin

  1. create roles, users, organizations, groups, people containers and services
  2. delete roles, users, organizations, groups, people containers and services
  3. display roles, users, organizations, groups, people containers and services profile
  4. get number of users for groups, people containers and roles
  5. import service scheme
  6. register a service in an organization
  7. unregister a service from an organization
  8. activate a service in an organization
  9. deactivate a service in an organization
  10. get name of registered services in an organization
  11. get name of activated services in an organization
  12. get the total number of registered and activated services in an organization
  13. execute requests in multiple XML files together.

 

6. How to Use

2004Q2 Syntax

  amadmin -u | --runasdn <dnname> -w | --password <password>
          -f | --passwordfile <passwordfile>
          [-l | --locale <localename>] [[-v | --verbose] |[-d | --debug]
          -t | --data <xmlfile1> [<xmlfile2> ...]
  amadmin --runasdn <dnname> -w | --password <password>
          -f | --passwordfile <passwordfile>
          [-l | --locale <localename>] [[-v | --verbose] |[-d | --debug]
          -s | --schema <xmlfile1> [<xmlfile2> ...]
  amadmin -u | --runasdn <dnname> -w | --password <password>
          -f | --passwordfile <passwordfile>
          [-l | --locale <localename>] [[-v | --verbose] | [-d | --debug]
          -r | --deleteservice <serviceName1> [<serviceName2> ...]
  amadmin --runasdn <dnname> -w | --password <password>
          -f | --passwordfile <passwordfile>
          [-l | --locale <localename>] [[-v | --verbose] |[-d | --debug]
          -m | --session <servername> <pattern>   amadmin -h | --help
  amadmin -n | --version
Detailed descriptions of the above-mentioned arguments is in the next sub-section. For examples of how to use it, refer to section 7.

2004Q2 Syntax Description

-u | --runasdn is a mandatory argument and its value is dnname. Replace dnname with your own distinguished name, DN. dnname is the DN of the authorized user running amadmin. It is used for authenticating to the LDAP server. For example,
-u | --runasdn uid=amAdmin,ou=People,dc=example,dc=com
and
-u | --runasdn "uid=amAdmin, ou=People, dc=example,dc=com"

 

-w | --password or -f | --passwordfile is a mandatory argument and its value is password. Replace password with a password corresponding to DN.

 

-l | --locale is an optional argument and its value is localename. Replace localename with a preferred locale. This argument is used for customizing the message language. Default value is en_US which is US English.

 

-d | --debug is an optional argument. When used, amadmin writes debug messages to a file amAdmin under /var/{BASE_DIR}/SUNWam/debug directory on Solaris; and <install-root>\debug directory on Windows2000. These messages provides more detailed of operations done using amadmin. This messages are not localized.

 

-v | --verbose is an optional argument. When used, this option does not print detailed information; instead it prints the overall progress of amadmin on the screen. These messages are localized.

 

-t | --data option creates, deletes and read the various directory objects like roles, groups, organizations and containers which is detailed in the XML input files. This option also registers, unregisters, activates, deactivates a service and gets the number of activated and registered services, and registered and activated service names for an existing organization. Multiple XML files can also be used for this option. You must provide either -t | --data or -s | --schema option depending on the need.

 

-s | --schema option loads and registers service schema and metadata, which is detailed in the XML input files. Multiple XML files can also be used for loading service schema information. You must provide either -t | --data or -s | --schema option depending on the need.

xmlfiles1 is not an argument. This is the name of XML files to be used.

 

-r | --deleteservice argument is use to delete a service (its schema and configuration data). This service must have been imported previously by using -s | --schema option. serviceName1 is the name of service to be deleted.

 

-m | --session argument is to manage the sessions i.e. to display the sessions currently login to the system; and to invalidate the sessions.

 

-h | --help argument to display the syntax usage.

 

-n | --version argument to display the utility name, product name, product version and legal notice.

 

7. Examples

7.1 Example for --schema option

Import the sampleMailService.xml as given below.

Solaris

Assume that Sun Java System Directory Server is installed in /var/Sun/mps. After installation, follow these steps.

  1. cd {BASE_DIR}/SUNWam/bin
  2. ./amadmin -u or --runasdn uid=amAdmin,ou=People,dc=example,dc=com --password passwordvalue or passwordfile passwordfilename -v or --verbose -s or --schema "{BASE_DIR}/SUNWam/samples/um/user/sampleMailService.xml"
To verify the DIT population in Sun Java System Directory Server after doing the above. follow these steps.
  1. cd /var/Sun/mps/slapd-<hostname>
  2. db2ldif -s dc=example,dc=com
This displays name of the ldif file stored under the /var/Sun/mps/slapd-<hostname>/ldif directory.

View that file to ensure that all the attributes and values (metadata) of the service got imported.

A sample XML input file for a sample service based on the SMS DTD can be found in {BASE_DIR}/SUNWam/samples/um/user/sampleMailService.xml.

WARNING: process may take hours if the number of users is large.

 

Windows2000

Follow these steps.

  1. cd <install-root>\bin
  2. amadmin -u or --runasdn uid=amAdmin,ou=People,dc=example,dc=com --password passwordvalue or passwordfile passwordfilename -v or --verbose -s or --schema "<install-root>\samples\um\user\sampleMailService.xml"
To verify the DIT population in Sun Java System Directory Server after doing the above. follow these steps.
  1. cd C:\SunONE\SunONEIS\DServers\slapd-<hostname>
  2. db2ldif -s dc=example,dc=com
This displays name of the ldif file stored under the C:\SunONE\SunONEIS\DServers\slapd-<hostname>\ldif directory.

View that file to ensure that all the attributes and values (metadata) of the service got imported.

A sample XML input file for a sample service based on the SMS DTD can be found in {BASE_DIR}/SUNWam/samples/um/user/sampleMailService.xml.

WARNING: process may take hours if the number of users is large.

 

7.2 Example for --data option

Solaris

Follow these steps

  1. cd {BASE_DIR}/SUNWam/bin
  2. ./amadmin -u or --runasdn uid=amAdmin,ou=People,dc=example,dc=com either --password passwordvalue or --passwordfile passwordfilename -v or --verbose -t or --data "{BASE_DIR}/SUNWam/samples/admin/cli/bulk-ops/createRequests.xml"

 

Windows2000

Follow these steps

  1. cd <install-root>\bin
  2. amadmin -u or --runasdn uid=amAdmin,ou=People,dc=example,dc=com either --password passwordvalue or --passwordfile passwordfilename -v or --verbose -t or --data "<install-root>\samples\admin\cli\bulk-ops\createRequests.xml"

Sample XML input files for -t or --data options are provided in the directory {BASE_DIR}/SUNWam/samples/admin/cli/bulk-ops/.

Some of the samples and their description given below, basically their intuitive names, represent the various requests

Note: If you have installed with different DIT, before running these samples modify the corresponding DNs to match the DIT installed

For example,

<CreateGroups>
    <DN>ContractorsGroup,ou=Groups,dc=example,dc=com</DN>
        <DN>EmployeesGroup,ou=Groups,dc=example,dc=com</DN>
</CreateGroups>

Default installation dictates that dc=example,dc=com be a child of the root suffix which is entered at install. All organizations are then created under dc=example,dc=com, <root suffix>.

So all the related dc=example,dc=com in the sample XML files need to be modified as dc=example,dc=com,dc=xyz, with xyz being the root suffix entered by the user during the installation of the Identity Server.

  • createRequests.xml
    To create all the objects in the Directory Server.

  • getRequests.xml

    To get info about all objects (created by createRequests.xml).
  • orgDeleteRequests.xml

    To delete all objects (created by createRequests.xml) under the organization.
  • pcDeleteRequests.xml

    To delete all objects(created by createRequests.xml) under the people container.
  • deleteGroupRequests.xml

    To delete all objects (created by createRequests.xml) under group.

  • orgRegisterServiceRequests.xml

    To register a service for an existing organization. This service must have been imported using amadmin

  • orgUnRegisterServiceRequests.xml
    To unregister a service for an existing organization. This service must have been imported using the amadmin.

  • orgGetRegisteredServiceRequests.xml
    To get the total number of registered and activated services for an existing organization.

  • serviceAddSubConfigurationRequests.xml
    To add the sub configuration for the given service
    Note : Before adding sub configuration, load the schema with GlobalConfiguration defined and replace corresponding serviceName and subConfigID in this sample
    file OR load serviceConfigurationRequests.xml before loading this sample

Verification Caution for this option: When amadmin is normally used, it is for bulk operations. 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 verify, you should start the dump of the appropriate sub tree rather than the entire tree.

 

7.3 Example for --deleteservice option

Solaris

Follow these steps.

  1. cd {BASE_DIR}/SUNWam/bin
  2. ./amadmin -u or --runasdn uid=amAdmin,ou=People,dc=example,dc=com either one of the -w or --password passwordvalue or -f or --passwordfile passwordfilename -v or --verbose -r or --deleteservice  serviceName

 

Windows2000

Follow these steps.

  1. cd <install-root>\bin
  2. amadmin -u or --runasdn uid=amAdmin,ou=People,dc=example,dc=com either --password passwordvalue or --passwordfile passwordfilename -v or --verbose -r or --deleteservice  serviceName

Note: This service must have been imported using amadmin. serviceName is the name of the service which is mentioned under <Service name=.. .> tag of the service XML file.

 

7.4 Example for --session option

Solaris

Follow these steps

  1. cd {BASE_DIR}/SUNWam/bin
  2. ./amadmin -u or --runasdn uid=amAdmin,ou=People,dc=example,dc=com either one of the -w or --password passwordvalue or -f or --passwordfile passwordfilename -v or --verbose -m or --session  http://hostname:port pattern

 

Windows2000

Follow these steps

  1. cd <install-root>\bin
  2. amadmin -u or --runasdn uid=amAdmin,ou=People,dc=example,dc=com either --password passwordvalue or --passwordfile passwordfilename -v or --verbose -m or --session  http://hostname:port pattern