Main Page
Command Line Interface, amadmin
Table of Contents
- Convention
- Requirements
- Installation/Setup
- Brief Description of
amadmin
- Main Usage of
amadmin
- How to use
- 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
- 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.
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.
- cd
{BASE_DIR}/SUNWam/bin
./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.
- cd
/var/Sun/mps/slapd-<hostname>
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.
- cd
<install-root>\bin
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.
- cd
C:\SunONE\SunONEIS\DServers\slapd-<hostname>
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
- cd
{BASE_DIR}/SUNWam/bin
./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
- cd
<install-root>\bin
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.
- cd
{BASE_DIR}/SUNWam/bin
./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.
- cd
<install-root>\bin
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
- cd
{BASE_DIR}/SUNWam/bin
./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
- cd
<install-root>\bin
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
|