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 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
- create roles, users, organizations, groups, people containers and
services
- delete roles, users, organizations, groups, people containers and
services
- display roles, users, organizations, groups, people containers and
services profile
- get number of users for groups, people containers and roles
- import service scheme
- register a service in an organization
- unregister a service from an organization
- activate a service in an organization
- deactivate a service in an organization
- get name of registered services in an organization
- get name of activated services in an organization
- get the total number of registered and activated services in an
organization
- execute requests in multiple XML files together.
- perform Realm-related requests.
- 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.
|