Previous Contents Index Next |
iPlanet Meta-Directory Configuration and Administration Guide |
Appendix B The Meta-Admin Protocol
The Meta-Admin protocol offers a repertoire of request commands that you can use to administer a Meta-Directory component, such as the join engine or any instantiated connectors.Clients that use the Meta-Admin protocol (such as the Meta-Admin Tool) communicate with Meta-Directory components by sending requests through iPlanet Administration Server. Requests to the Administrative Server are formatted as HTTP or HTTPS POST requests. In response to each request, the Administrative Server calls a CGI program to carry out the task. A set of CGI programs support each installed Meta-Directory component. The CGI programs can be located using the following directory structure:
Here, mdComponent is a directory housing an individual Meta-Directory component. The CGI programs located in these directories are Perl scripts that are interpreted by the copy of nsperl.exe that's located in the same admin/bin directory.
- NETSITE_ROOT/bin/mdComponent/admin/bin
This appendix describes the protocol itself; for a description on how to use the protocol with the Meta-Admin Tool, see Chapter 16 "Command-Line Administration."
The Protocol Requests
Each request in the protocol makes use of a set of attributes that supply the details needed to carry out the administrative task. You describe each administrative request by supplying the necessary attribute values needed by the request. All character values in the protocol are represented in UTF-8 format.Attributes can be grouped into two categories:
Session attributes set up the communication between the Administration Server and the component that you are administering with the request.
Before you can make a request, you must set up the request by supplying the configuration and authentication information for the component you are administering. You do this using the three session attributes: admin-URL, Configuration, and authenticationDetails. These attributes define the information needed to establish communication with the Meta-Directory component, and must be defined for each request you make.Task attributes contain the details of the request which you are making. These are the attributes that you use to tailor your administrative requests.
Once you supply the session information, you can specify the details of your individual administrative tasks using the task attributes defined in the Meta-Admin protocol. While some request do not require any task attributes, some take optional values, while others require that you supply a value (or set of values) in order for the request command to succeed.
Session Attributes
Before an administrative request can be carried out by a Meta-Directory component, you must specify the component you want to administer and the associated authentication details so you can access that component. Specifically, you must specify values for the following session attributes:While these details do not need to be specified with every request, they must be specified, at minimum, in the first request. Once the component and authentication details are supplied, they become default values that subsequent requests can use. If needed, you can specify specific component and authentication values for any request you make; the last one ones specified always become the default.
The Server URL Attribute
Before any administrative tasks can be performed, you must set up the connection with the Administration Server that administers the component taking action. You specify the Administration Server using the admin-URL attribute.The first record of the LDIF file must contain a valid admin-URL attribute. After it is specified, the URL attribute is optional for the remaining records in the input file; if the admin-URL attribute is omitted from a request, the URL of the preceding request is assumed.
You can use the following attributes in the record to specify individual parts of the URL:
admin-username is used for basic authentication.
admin-password is used for basic authentication.
admin-host specifies the Administration Server's host name or IP address.
admin-port specifies the Administration Server's TCP port number.
admin-path specifies the part of the URL following host:port/.
The Configuration and Authentication Attributes
You must define the values of the configuration and autheniticationDetails attributes for each LDIF request you make. While these two attributes do not constitute an administrative task by themselves, they contain information needed by the component before it will respond to an administrative request.configuration - The configuration attribute identifies the LDAP URL of the Meta-Directory component's own configuration entry (under cn=System). This attribute takes a single required value.
For example, consider the following configuration value:
configuration: dn: cn=join-engine, cn=Meta-Directories, cn=System,
ou=5, ou=Meta-Directory, ou=Global Preferences, ou=iplanet.com,
o=NetscapeRootHere, the first cn value is the name of the component and the second value is the type of the component (cn=connectors). The third, fourth, fifth, sixth, and eighth values of this dn are all hardcoded for this release and you must not modify them from this example. The seventh value is the admin domain, which you must supply.
authenticationDetails - The protocol requires an authenticationDetails value to access the LDAP server identified by the configuration attribute. At minimum, the request should provide a copy of the mdsAuthenticationDetails attribute of the configuration Data Server.
This attribute takes one or more values, with each value having the same format as an mdsAuthenticationDetails attribute value, as follows:
mdsAuthenticationDetails: simple ["username" ["password"]] |
simple_base64 [base64(username) [base64(password)]]mdsAuthenticationDetails: simple "cn=Manager" "secret12"
mdsAuthenticationDetails: simple_base64 asdlALKJj8== 8AkBcUwHlMM=A zero-length value signifies the absence of an authentication attribute.
Meta-Directory version 5.0SP1 supports the following Meta-Admin protocol requests through the Meta-Admin Tool:
The reference section below contains descriptions of the attributes that you need to supply for each task in the protocol. In addition, typical responses are shown are shown for each request.
For an example of how to use these request commands with the Meta-Admin Tool, refer to Chapter 16 "Command-Line Administration."
This request starts the server specified in the URL attribute.
Attributes
This request does not require any attributes.
Responses
This request can generate the following responses:
This request stops the server specified in the URL attribute.
Attributes
This request does not require any attributes.
Responses
This request can generate the following responses:
Response
Description
NMC_Status: 0 NMC_Status: 2
NMC_ErrInfo: already stoppedThe client should assume the agent is stopped, unless the response indicates a failure.
This request informs you whether or not a particular server is up or down. Specify the server in question using the URL attribute.
Attributes
This request does not require any attributes.
Responses
This request can generate the following responses:
Response
Description
NMC_Status: 0
status: upNMC_Status: 0
status: downNMC_Status: 1
NMC_ErrInfo: errno ENOMEM
This request reads and returns a component's status and statistics values. Specify the component using the URL attribute.
On Solaris systems, this request might take some time before returning.
Attributes
This request does not require any attributes.
Responses
This request can generate the following responses:
Response
Description
NMC_Status: 0
status: up
Total Changes: 2478
Total Changes to MV: 253
Total Changes to CVs: 996
...NMC_Status: 1
NMC_ErrInfo: errno ENOMEM
After processing your administrative task, the CGI program will issue a response through an HTTP text document. The client of the protocol (such as the Meta-Admin Tool) can interpret these responses, and output an associated message.
Technically, the client of the protocol should assume a request was successful, even if the if the response only indicates success in the HTTP header (and contains no document) or if it returns a document that contains an NMC_Status value other than 0. If the request returns data, it will be returned in the form of attribute name-value pairs, which have the following format:
While certain requests might return progress indicators, not all requests will do so. Although a request might be quiet, you should assume that your request is being processed until you receive a complete response.
Error Responses
If your request causes an error (for example, if the request has an invalid configure parameter), the response will report the failure or warning using the Mission Control NMC_ name-value pair format, as follows:For example, if you send a request to the Meta-Admin Tool whose attributes are not part of the Meta-Admin protocol, the tool could respond with the following:
NMC_Status: 1
NMC_ErrType: INCORRECT_USAGE
NMC_ErrInfo: unknown attribute <attribute_name_1>
NMC_ErrInfo: unknown attribute <attribute_name_2>
NMC_ErrInfo: unknown attribute <attribute_name_3>
The protocol has a predefined a set of indicators which it can use when sending back the results of your administrative tasks. These are defined as follows:
NMC_Status: Indicates the return status of the administrative CGI. The values returned can be any one of the following:
0: Success
1: Failure
2: Warning
3: UnknownNMC_ErrType: The text describes the error type. The values returned can be any one of the following:
FILE_ERROR
MEMORY_ERROR
SYSTEM_ERROR
INCORRECT_USAGE
ELEM_MISSING
REGISTRY_DATABASE_ERROR
NETWORK_ERROR
GENERAL_FAILURE
WARNING
APP_ERRORNMC_ErrInfo: Contains a brief text description of the error.
NMC_ErrDetail: Contains a detailed text description of the error.
NMC_Description: Contains a brief text description of the result. This result code can be used when NMC_Status equals 0 or 3.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated April 08, 2002