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 Sun ONE 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:

NETSITE_ROOT/bin/mdComponent/admin/bin

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.

---

Caution

Do not directly invoke the create and remove scripts provided by the protocol; these requests must be used in conjunction with other system calls built into the Meta Directory console. Using these scripts directly will put the Meta-Directory system into an unstable state from which the Meta-Directory console cannot recover.

---

This appendix describes the protocol itself; for a description on how to use the protocol with the Meta-Admin Tool, see "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.
• Task attributes contain the details of the request which you are making. These are the attributes that you use to tailor your administrative requests.

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.

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:

• Server URL
• Configuration Details
• Authentication Details

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=sunone.com,
  o=NetscapeRoot

Here, 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)]]

For example:

mdsAuthenticationDetails: simple "cn=Manager" "secret12"
mdsAuthenticationDetails: simple_base64 asdlALKJj8== 8AkBcUwHlMM=

A zero-length value signifies the absence of an authentication attribute.

Meta-Admin Protocol Requests

Meta-Directory version 5.0SP1 supports the following Meta-Admin protocol requests through the Meta-Admin Tool:

• start
• stop
• status
• statistics

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 "Command-Line Administration."

start

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:

Response	Description
NMC_Status: 0	Success response.
NMC_Status: 1 NMC_ErrInfo: SCM status NO_SUCH_SERVICE	Failure response.
NMC_Status: 2 NMC_ErrInfo: already started	The client should assume the agent is started, unless the response indicates a failure.

stop

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	Success response.
NMC_Status: 2 NMC_ErrInfo: already stopped	The client should assume the agent is stopped, unless the response indicates a failure.

read/status

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: up	The server is up.
NMC_Status: 0 status: down	The server is down.
NMC_Status: 1 NMC_ErrInfo: errno ENOMEM	Status is unknown, if the request fails.

read/statistics

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 ...	Successful response.
NMC_Status: 1 NMC_ErrInfo: errno ENOMEM	Status and statistics are unknown, if the request fails.

Protocol Responses

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:

name: value\n

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:

NMC_name: value

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: Unknown

NMC_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_ERROR

NMC_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.