Sun Java System Access Manager version 6 2005Q1
Sample
 

Main Page

amadmin - Command Line Interface


1. Description

amadmin is the command line tool for administering Access Manager. The primary intent of this tool is to aid in bulk administrative tasks, ie creating 1,000 organizations, people containers, users or 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 Administration 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 Access Manager'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.


2. Installation Properties

The following assumptions are made regarding the installation directories. You may need to change the examples to reflect your actuall installation properties and locations.

  • INSTALL_DIR - /opt/SUNWam
    default installation directory for Access Manager
  • DIR_INSTALL_DIR - /var/Sun/mps
    default install directory for Directory Server
  • Base DN - dc=sun,dc=com
  • amadmin location - <INSTALL_DIR>/bin/amadmin


3. Requirements

Services must follow the DTD found in <INSTALL_DIR>/dtd/sms.dtd. A sample XML file is available in <INSTALL_DIR>/samples/um/user/sampleMailService.xml

Bulk operations need to follow the DTD specifications defined in <INSTALL_DIR>/dtd/amAdmin.dtd. Sample operations can be found in <INSTALL_DIR>/samples/admin/cli/bulk-ops.


4. Main Usage 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.


5. Usage

 
    amadmin ARGUMENTS COMMANDS OPTIONS

    ARGUMENTS:
    Must specify either a user ID and password, or the version argument.
        -u <userdn>, --runasdn <userdn>
            Full DN of the user running the command
    
        -w <password>, --password <password>
        -f <filename>, --passwordfile <filename>
            Full DN of the user used to run the command
    
    COMMANDS:
    One of the following commands must be specified in each amadmin command issued.
        -t <filename>, --data <filename>
            Load the data from the specified filename.

        -s <filename>, --schema <filename>
            Load the schema from the spefied filename.
    
        -r <servicename>, --deleteservice <servicename>
            Deletes the service name from the system.
    
        -m <servername>, --session <servername>
            Manage the active sessions on the specified server.
            Example: -m http://server.east.company.com:8080
    
        -a <serviceName> <schemaType> <xmlfile>
        --addattributes <serviceName> <schemaType> <xmlfile>
            Adds a new attribute to the specified serviceName and
            schemaType(global, dynamic, organization, or user).
            The attribute schema being added is defined in the xmlfile.
    
        -g <filename>, --import <filename>
            Load the Liberty meta compliance XML into Directory Server.
            filename contains the meta information and should adhere to
            the Liberty meta specification and XSD.
    
        -e <entity name>, --entityname <entity name>
    
        -o <filename>, --export <filename>
            Export an entity to the specified filename. The --entityname
            parameter must be used to specify the entity name. May also
            specify --verifysig, --defaulturlprefix, or --metaalias.
    
        -n, --version
            Output the version of Access Manager currently installed.

    OPTIONS:
        -l <localename>, --locale <localename>
            Name of the locale to display the results.
    
        -v, --verbose
            Run in verbose mode. Results sent to standard output
    
        -d, --debug
            Run in debug mode. Results sent to the debug file.
    
        -c, --continue
            Continue processing the input if errors are encountered.

        -y, --verifysig
            Used in conjunction with the --import command.
            The imported xml file will run through an xml signature validator.

        -k <url>, --defaulturlprefix <url>
            Used in conjuction with  --import .
            Implies the imported EntityDescriptor is a local entity. A
            series of Access Manager specific attributes will automatically
            loaded in the directory server. defaulturlprefix is used to build
            one of the attribute.

        -q <meta alias name>, --metaalias <meta alias name>
            Used in conjunction with --import.
            Implies the imported EntityDescriptor is a local entity. A series
            of Access Manager specific attributes will be automatically loaded
            to directory server. metaAlias is one of the customizable
            attribute.
    
        -x, --xmlsig
            Used in conjunction with --export.
            If specifed, the exported doc will be signed.
    
    


6. Examples

Some of the examples require a dn for operations such as creating new objects. A base dn of dc=example,dc=com is used throughout the sample files and will need to be modified to match you base installation prior to running the samples. Failure to modify these values to match your installation will result in errors running the commands.

6.1 Import a service using --schema

A sample service, sampleMailService.xml, is provided and based on the SMS DTD. The service can be found in <INSTALL_DIR>/samples/um/user/sampleMailService.xml.

    cd <INSTALL_DIR>/bin
    amadmin --runasdn uid=amAdmin,ou=People,dc=example,dc=com
	--password passwordvalue
	--schema <INSTALL_DIR>/samples/um/user/sampleMailService.xml
    
To verify this service was imported into Directory Server, follow these steps.
    cd /var/Sun/mps/slapd-<hostname>
    db2ldif -s dc=example,dc=com
    
This displays name of the ldif file stored under the <DIR_INSTALL_DIR>/slapd-<hostname>/ldif directory.

View that file to ensure that all the attributes and values of the service were imported correctly.

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

6.2 Create new objects using the --data option

    cd <INSTALL_DIR>/bin
    amadmin --runasdn uid=amAdmin,ou=People,dc=example,dc=com
	--password passwordvalue
	--data "<INSTALL_DIR>/samples/admin/cli/bulk-ops/createRequests.xml
    

The following sample files are provided to demonstrate different functionality available through amadmin using the -t or --data options. The samples can be found in <INSTALL_DIR>/samples/admin/cli/bulk-ops.

  • 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.
  • orgUnRegisterServiceRequests.xml
    To unregister a service for an existing organization. This service must have been imported.
  • 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.

6.3 Delete a service using --deleteservice

The service being removed must have been previously imported using --schema option. The value expected for the service name, is the name of the service which is mentioned under <Service name=.. .> tag of the service XML file. For this example we will remove the sampleMailService loaded in 6.1.
    cd <INSTALL_DIR>/bin
    ./amadmin --runasdn uid=amAdmin,ou=People,dc=example,dc=com
	--password passwordvalue
	--verbose
	--deleteservice sampleMailService
    


End of Sample