Sun Java System Access Manager version 7 2005Q4

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 actual installation 
    properties and locations.
    
    * 
    INSTALL_DIR - /opt/SUNWam
    default installation directory for Access Manager
    
    * 
    DIR_INSTALL_DIR - /var/opt/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

    4.1 create roles, users, organizations, groups, people containers and
        services
    
    4.2 delete roles, users, organizations, groups, people containers and
        services
    
    4.3 display roles, users, organizations, groups, people containers and
	services profile
    
    4.4 get number of users for groups, people containers and roles
    
    4.5 import service scheme
    
    4.6 register a service in an organization
    
    4.7 unregister a service from an organization
    
    4.8 activate a service in an organization
    
    4.9 deactivate a service in an organization
    
    4.10 get name of registered services in an organization
    
    4.11 get name of activated services in an organization
    
    4.12 get the total number of registered and activated services in an
	 organization
    
    4.13 execute requests in multiple XML files together.
    
    4.14 perform Realm-related requests.
    
    4.15 perform Identity-related requests.
    



    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
    
    
    6.4 Realm and Identity requests
    The sample input xml files named R_*.xml correspond to
    Realm-related requests
    (com.sun.identity.sm.OrganizationConfigManager class).
    Those named I_*.xml correspond to Identity-related requests
    (com.sun.identity.idm.AMIdentityRepository and
    com.sun.identity.idm.AMIdentity classes).
    Consult the amAdmin.dtd for complete details for constructing these
    requests.
    

End of Sample

