Chapter 15 Command-Line Administration

Meta-Directory provides a tool, the Meta-Admin tool, that lets you administer the Meta-Directory components from the command line. This tool, used in conjunction with the Meta-Admin protocol, lets you perform a number of administrative processes on a Meta-Directory component. This chapter provides instructions to help you use the Meta-Admin tool. This chapter contains the following sections:

Meta-Admin Tool

The Meta-Admin Tool is a command-line utility that you can use to administer any running Meta-Directory component. The Meta-Admin Tool communicates with the Meta-Directory components through HTTP POST requests. Your requests are routed through the Administration Server CGI scripts to the specified component.

You can specify the administrative tasks that you want to perform using an LDIF input file. The Meta-Admin Tool reads the input file and translates your commands into POST requests, which it sends to the appropriate CGI scripts.

In the input file you supply, each request you make must contain a set of parameters whose values describe the administration task you want to perform. In response to your requests, the CGI scripts return an HTTP document to the Meta-Admin Tool.

Reads requests (in LDIF format) from stdin.

Sends the requests to the Meta-Directory components, via the Administration Server CGI scripts.

Echoes the Meta-Directory component responses to stdout.

Outputs any error messages to stderr.

Returns, as an exit status, the number of requests that failed.

Meta-Admin Tool Syntax

The Meta-Admin Tool is a Perl script that is installed in the following location:

The script makes use of several Perl extension modules, including and the Meta_Admin module.

The tool uses nsPerl5.8.2, which is installed when you install the Meta-Directory software package. As a note, the Perl implementation must be set to “use Meta_Admin”.

On Solaris systems, you can execute the tool from either a shell or shell script. On Windows systems, you can execute the tool from either the Command Prompt window or from a batch file.

For example, on Solaris, you can issue the following commands from a command prompt to run the Meta-Admin Tool:

Here, it is assumed that NETSITE_ROOT is set to the directory root of your installed Meta-Directory package, options are any command-line options you want to specify, and input.ldif is the LDIF input you supply to the tool.

Launch the Windows Control Panel and choose System. In the System Properties window, go to the Advanced tab and click the Environment Variables button.

Update the PATH variable to include the path to nsperl.exe. It is usually located in the directory NETSITE_ROOT\lib\nsperl5.8.2.

Set NETSITE_ROOT to point to the installation directory of Meta-Directory.

Exit the Windows Control Panel.

Open a Windows Command Prompt and change to the installation directory of Meta-Directory using the following command:

c:\> cd NETSITE_ROOT/bin/meta50/bin

Invoke the Meta-Admin tool using the following command:

nsperl.exe meta-admin < input.ldif

Meta-Admin Tool Command-Line Options

The following two tables define the command-line options that you can use with the Meta-Admin Tool. Table 15-1 explains the command-line options that you can use to modify your administrative requests:

Table 15-1 Request-related options for the Meta-Admin Tool
Option	Description
-b URL	Resolves all relative (incomplete) admin-URL values relative to the specified base URL.
-p URL	Sets the proxy to be used for the requests. The program also loads proxy settings from the environment, unless the -p option is also used.
-P	Specifies that proxy settings are not loaded from the environment.
-t timeout	Sets the time-out value; that is, the amount of time to wait for a response from the remote server before failing. The default unit for the time-out value is seconds. You may append “m” or “h” to the time-out value to make it minutes or hours, respectively. The default time-out is 180 seconds (3 minutes).
-i time	Sets the If-Modified-since header in the request. If time is the name of a file, use the modification timestamp for this file. If time is not a file, it is parsed as a literal date. For recognized date formats, refer to the HTTP:DATE manpage.
-H header	Sends an HTTP header with each request. A server can be specified. For example: meta-admin -H ‘referrer: http://other.url’ -H ‘Host: your_host’ < ldif.input

Table 15-2 describes the command-line options for controlling the output of the Meta-Admin Tool.

Table 15-2 Options that control the output for the Meta-Admin Tool
Output Options	Description
-a	Sets the output mode to ASCII text and outputs a blank line between responses. If this option is not supplied, response content is output in binary mode with nothing added.
-u	Prints the request method and absolute URL as requests are made.
-U	Prints the request headers in addition to request method and absolute URL.
-s	Prints response status code. This option is always on for HEAD requests.
-S	Prints response status chain showing redirect and authorization requests handled by the library.
-e	Prints response headers. This option is always on for HEAD requests.
-d	Specifies that the content of a response not be printed.
-o	Processes HTML content in various ways before outputting it. If the content type of the response is not HTML, then this option has no effect. The legal format values are: text, ps, links, html, and dump. text specfies that the HTML output be formatted as plain latin1 text. ps specifies that the HTML output be formatted as Postscript. links outputs all links found in the HTML document. Relative links are expanded to absolute links. html reformats the HTML code. dump format dumps the HTML syntax tree.
-v	Prints the version number of the program and quits.
-h	Prints the usage message and quits.
-x	Provides extra debugging output.

Meta-Admin Tool Input

To administer the Meta-Directory components using the Meta-Admin Tool, you must create an LDIF file, which contains the commands for the administrative tasks you want to perform.

The LDIF file contains a sequence of attribute-value pairs. That is, each line of the input stream typically contains a parameter name, a colon, and the parameter’s value. Each input record in the LDIF file describes a request for a single administrative task. Using the LDIF format, you can structure your administrative requests, where each request has attributes and values that conform to the Meta-Admin protocol.

You can then invoke the Meta-Admin Tool, passing to it as input the LDIF file you’ve created. The tool reads the LDIF file and sends requests to the appropriate components as dictated by the request records in your file.

The input file can contain a single request or it can contain a sequence of requests; however, any input following the first empty line is ignored.


Note	You can use the attributes and values defined in the Meta-Admin protocol to structure the request commands that you input into the Meta-Admin Tool. For complete details on the Meta-Admin protocol and its use, refer to the section Meta-Admin Protocol.

You could use the example script in Code Example 15-1 to start a component, stop the component, read component statistics, and so on. The example has several administration request, each commented out with a hash mark in the original. To perform a desired task, just remove the hash marks next to the commands you want to perform and run the script through the Meta-Admin Tool. These tasks can be performed on any connector and the join engine. Just make sure that the URL in the configuration line points to the configuration directory. Also ensure that the admin-URL has the correct login credentials of the Admin user as shown in the following example.

Code Example 15-1 Sample Meta-Admin Tool input script


admin-URL: http://admin:admin@resturants.madisonparc.com:5000
configuration: LDAP://config.admin-domain.com:5001/
cn%3Djoin50-engine%2Ccn%3DMeta-Directories%2Ccn%3DSystem%2C
ou%3D5%2Cou%3DMeta-Directory%2Cou%3DGlobal%20Preferences%2C
ou%3Dadmin.domain%2Co%3DNetscapeRoot
authenticationDetails: simple “cn=Directory Manager” “sunone”
#
#admin-path: join50-engine/Tasks/start
#
#admin-path: join50-engine/Tasks/stop
#
#admin-path: join50-engine/Tasks/read/status
#
#admin-path: join50-engine/Tasks/read/statistics
#

If this script were saved with the file name admin_input.txt, you could run the script with the Meta-Admin Tool using the following command:

Using the Meta-Admin protocol, you can create a custom client that you can use to perform a predetermined set of administration tasks. To note an example, the Meta-Directory Console is a client of this protocol.

Input Files for Supported Tasks

In this section, you will find sample files that you can use for performing various tasks using the Meta-Admin Tool. These tasks can broadly be categorized as:

Join Engine Operations

Connector Operations

Join Engine Operations

Using the Meta-Admin Tool, you can perform the following operations on the join engine. Each of the following sections provides you a sample LDIF file that can be used to perform the operation.

Starting a Join Engine

You can use the following sample file to start a join engine. Only, make sure that the admin-URL, admin-path, authenticationDetails and configuration details are modified suitably to fit your environment.

Code Example 15-2 Sample LDIF file to start a join engine

SuiteSpotUser: root

admin-URL: http://admin:password@sina.eng.example.com:adminport

admin-path: join50-engine/Tasks/start

authenticationDetails: simple "cn=Directory Manager" password

configuration: LDAP://sina.eng.example.com:1389/cn%3Djoin-engine%2Ccn%3DMeta-

Directories%2Ccn%3DSystem%2Cou%3D5%2Cou%3DMeta-Directory%2Cou%

3DGlobal%20Preferences%2Cou%3Deng.example.com%2Co%3DnetscapeRoot

Stopping a Join Engine

The following sample LDIF file can help you stop a join engine. Make sure that the admin-URL and admin-path are modified suitably to fit your environment.

Enabling Participating Views

This file can help you enable the participating connector view to flow data. In the sample file, CV2 is the Connector View and MV2 is the Meta View. You should substitute these with the actual MV_ID and CV_ID in your environment.

Refreshing Data in the Join Engine

You can refresh the data in a participating view by traversing the Connector View to synchronise the Meta View with the contents of the participating view. In the following sample file, CV2 is the Connector View and MV2 is the Meta View. You should substitute these with the actual MV_ID and CV_ID in your environment.

You can also refresh the participating view by traversing the Meta View to synchronise the participating view with the Meta View contents. In the following sample, CV2 is the participating view and MV2 is the Meta View.

Refreshing Unlinked Entries in the Meta View

This file helps refresh all those entries in the participating view that are not linked to the entries in Meta View, or in other words do not have the mdsLinkToMV attribute. In the sample file, CV2 is the Connector View and MV2 is the Meta View. You should substitute these with the actual MV_ID and CV_ID in your environment.

Refreshing Unlinked Entries in the Connector View

This file helps refresh all those entries in the participating view that are not linked to the entries in the Connector View. In the sample file, CV2 is the Connector View and MV2 is the Meta View. You should substitute these with the actual MV_ID and CV_ID in your environment.

Disabling Participating Views

This file helps disable the selected participating connector view from flowing data. In the sample file, CV2 is the Connector View and MV2 is the Meta View. You should substitute these with the actual MV_ID and CV_ID in your environment.

Refreshing Groups

This operation helps specify the search criteria with which the Join Engine will do a refresh. You can use the following sample file to refresh data by traversing a Connector View. In the sample file, CV2 is the Connector View and MV2 is the Meta View. You should substitute these with the actual MV_ID and CV_ID in your environment.

To refresh data by traversing a Meta View, use the following LDIF file. Ensure that you substitute CV2 and MV2 with the actual MV_ID and CV_ID in your environment.

Validating Links

This operation traverses the Connector View and checks for invalid links and attempts to rejoin the entire data join. In the sample file, CV2 is the Connector View and MV2 is the Meta View. You should substitute these with the actual MV_ID and CV_ID in your environment.

To validate links by traversing a Meta View, you can use the same file. However, change the op code from CV to MV.

Breaking Links

You can use the following LDIF file to break all the links between the Connector View and the Meta View. It removes the mdsLinkTo information on entries in the Connector View and the Meta View.

Get Status

You can use the following LDIF file to find out if the components are ‘up’ or ‘down’.

Get Statistics

You can use the following LDIF file to get useful statistics about the Join Engine operations. These statistics include the number of add, modify, and delete operations done to the various views.

Connector Operations

Java-based Connectors

UTC-based Connectors

Java-based Connectors

Using the Meta-Admin tool, you can do the following operations on a Java-based Connector. The following sections provide sample LDIF files that you can use to perform the tasks.

Starting a Connector

Stopping a Connector

Refreshing a Connector

Starting a Connector

Code Example 15-16

SuiteSpotUser: root

admin-URL: http://admin:password@sina.eng.example.com:10010

admin-path: ndc50-cv-nds/Tasks/start

authenticationDetails: simple_base64 Y249RGlyZWN0b3J5IE1hbmFnZXI= cGFzc3dvcmQ=

configuration: LDAP://sina.eng.example.com:1389/cn%3Dndc-cv-nds%2Ccn%3DConnectors%2Ccn%3DSystem% 2Cou%3D5%2Cou%3DMeta-Directory%2Cou%3DGlobal%20Preferences%2Cou%3Deng.examp le.com%2Co%3DnetscapeRoot

Ensure that you substitute admin-URL with the admin-URL of your environment and cv-nds in the admin-path with the name of your Novell Connector.

The new Java-based connectors (ie, the Novell Directory and Lotus Notes connectors) do not support simple authentication. Hence, the authentication details provided in the LDIF file need to be Base64 encoded. It can be generated using the b64.pl script shown below:

Code Example 15-17 The b64.pl script

use MIME::Base64;

if ( "$ARGV[0]" eq "-e" ){

printf ("%s", encode_base64(eval "'$ARGV[1]'"));

}

elsif ( "$ARGV[0]" eq "-d" ) {

printf ("%s", decode_base64(eval "'$ARGV[1]'"));

} else {

printf("Encode or Decode using Base64\n");

printf("Encode: b64.pl -e 'string'\n");

printf("Decode: b64.pl -d 'encoded text'\n");

}

Code Example 15-18

# /$NETSITE_ROOT/lib/nsPerl5.8.2/nsperl b64.pl -e "cn=Directory Manager"

Y249RGlyZWN0b3J5IE1hbmFnZXI=

# /$NETSITE_ROOT/lib/nsPerl5.8.2/nsperl b64.pl -e password

cGFzc3dvcmQ=

# /$NETSITE_ROOT/lib/nsPerl5.8.2/nsperl b64.pl -d cGFzc3dvcmQ=

password

Stopping a Connector

Given here is a sample LDIF file that you can use to stop a connector. Ensure that you substitute admin-URL with the admin-URL of your environment and cv-nds in the admin-path with the name of your Novell Connector.

Refreshing a Connector

For Meta-Directory to decide which direction to flow data, say from EDS to CV or vice versa, a multi-valued attribute called mdsGeneralConfiguration needs to be set to an appropriate value in the configuration directory before starting the actual refresh operation. You can use the ldapmodify command to set the value of this attribute.

Create an LDIF file depending on which direction you want to flow data. You can use one of the following sample files.

The following sample file can be used to refresh data in CV with data from the EDS. Make sure to localize the values of the attributes cn and ou to suit your environment.

Code Example 15-20 Sample LDIF to modify the mdsGeneralConfiguration attribute to enable refresh to CV

dn: cn=1,cn=Tasks,cn=ndc-cv-nds,cn=Connectors,cn=System,ou=5,ou=Meta-Directory,ou =Global Preferences,ou=eng.example.com,o=netscapeRoot

changetype: modify

delete: mdsGeneralConfiguration

mdsGeneralConfiguration: TaskReSyncToCV=0

add: mdsGeneralConfiguration

mdsGeneralConfiguration: TaskReSyncToCV=1

If you want to refresh the EDS with data from the CV, you can use the following sample file. Make sure to localize the values of the attributes cn and ou to suit your environment.

Code Example 15-21 Sample LDIF file to modify the mdsGeneralConfiguration attribute to enable refresh to MV

dn: cn=1,cn=Tasks,cn=ndc-cv-nds,cn=Connectors,cn=System,ou=5,ou=Meta-Directory,ou =Global Preferences,ou=eng.example.com,o=netscapeRoot

changetype: modify

delete: mdsGeneralConfiguration

mdsGeneralConfiguration: TaskReSyncFromCV=0

add: mdsGeneralConfiguration

mdsGeneralConfiguration: TaskReSyncFromCV=1

Then, run the ldapmodify command with the sample LDIF files created in Code Example 15-20 or Code Example 15-21.

Code Example 15-22 ldapmodify command to refresh the CV or MV

ldapmodify -D "cn=Directory Manager" -w password -h sina.eng.example.com -p 1389 -f ldiffile

The ldapmodify command modifies the attribute mdsGeneralConfiguration as required.

Finally execute the input.ldif shown here.

Code Example 15-23

admin-URL: http://admin:password@sina.eng.example.com:10010

admin-path: ndc50-cv-nds/Tasks/request

op: refresh

UTC-based Connectors

The following sections present sample files that you can use to perform various operations on UTC-based connectors.

Starting a Connector

Stopping a Connector

Refreshing Connector

Starting a Connector

To start a UTC Connector, you can use the following sample LDIF file. Make sure that you replace the admin-URL, admin-path, authentication details and configuration details with the actual values used in your environment.

Stopping a Connector

To stop a UTC Connector, you can use the following sample LDIF file. Ensure that the admin-URL and admin-path values are localized to your environment.

Refreshing Connector

For Meta-Directory to decide which direction to flow data, say from an external directory (csv, nvp or ldif files) to CV or from CV to an external directory, a multi-valued attribute called mdsGeneralConfiguration needs to be set to an appropriate value in the configuration directory before starting the actual refresh operation. You can use the ldapmodify command to set the value of this attribute.

Create an LDIF file depending on which direction you want to flow data. You can use one of the following sample files. To refresh data in the CV with data from the EDS, create an LDIF file as shown below. Make sure to localize the values of the attributes cn and ou to suit your environment.

Code Example 15-24 Sample LDIF file to modify mdsGeneralConfiguration to refresh data in the CV

dn: cn=1,cn=Tasks,cn=utc-cv-utc,cn=Connectors,cn=System,ou=5,ou=Meta-Directory,ou= Global Preferences,ou=eng.example.com,o=netscapeRoot

changetype: modify

delete: mdsGeneralConfiguration

mdsGeneralConfiguration: TaskReSyncToCV=0

add: mdsGeneralConfiguration

mdsGeneralConfiguration: TaskReSyncToCV=1

To refresh data in the EDS with data from the CV, you can use the following sample file. Make sure to localize the values of the attributes cn and ou to suit your environment.

Code Example 15-25 Sample LDIF file to modify mdsGeneralConfiguration to refresh data in the external directory

dn: cn=1,cn=Tasks,cn=utc-cv-utc,cn=Connectors,cn=System,ou=5,ou=Meta-Directory,ou= Global Preferences,ou=eng.example.com,o=netscapeRoot

changetype: modify

delete: mdsGeneralConfiguration

mdsGeneralConfiguration: TaskReSyncFromCV=0

add: mdsGeneralConfiguration

mdsGeneralConfiguration: TaskReSyncFromCV=1

where utc-cv-utc is the UTC Connector name

Run the ldapmodify command with the sample LDIF file shown in Code Example 15-24 or Code Example 15-25. This command modifies mdsGeneralConfiguration as required.

Code Example 15-26 ldapmodify command

ldapmodify -D "cn=Directory Manager" -w password -h sina.eng.example.com -p 1389 -f utc2cv.ldif

Create an LDIF file as shown in the example and run it with the Meta-Admin Tool.

Code Example 15-27

admin-URL: http://admin:password@sina.eng.example.com:10010

admin-path: utc50-cv-utc/Tasks/request

op: refresh CV

Meta-Admin Tool Responses

After successfully processing a request, the Meta-Admin Tool will output any data returned by the request. While the Meta-Admin Tool might display progress indicators as it performs your requested tasks, a request which is successfully processed will not necessarily return any special success message.

The following text is an example of what you might see returned from a statistics request:

Code Example 15-28 Meta-Admin Tool output from a statistics request


NMC_Status: 0
NMC_ErrInfo: connecting ...
NMC_ErrInfo: communicating ...
NMC_Description: <3d95f080c204e3af489@join50-engine>
NMC_Description: LOGIN WRITE
NMC_Description: OK
NMC_Description: STATUS
40 total number of changes
20 total number of CV to MV changes
20 total number of MV to CV changes
5 total number of CV to MV adds
0 total number of CV to MV add errors
15 total number of CV to MV modifies
0 total number of CV to MV modify errors
0 total number of CV to MV deletes
0 total number of CV to MV delete errors
0 total number of MV to CV adds
0 total number of MV to CV add errors
20 total number of MV to CV modifies
0 total number of MV to CV modify errors
0 total number of MV to CV deletes
0 total number of MV to CV delete errors
1 total number of ConnectorViews
1 total number of ConnectorViews running
1 total number of MetaViews
0 telnet-only mode
1 current manager associations
53 total number of manager associations
0 total number of manager login authentication failures
978976517 date/time of last startup (8 Jan 2001 09:55:17 -0000)
259 secs since last Meta-Directory activity
NMC_Description: OK
NMC_Description: LOGOUT

It is possible for you to make a request that results in an error message being returned by the Meta-Admin Tool. For example, if the Meta-Directory CGI software is absent or damaged, if the tool does not support the request you make, or if the client is not permitted to perform the requested action, you will receive an error message in response to your request.

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:

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.

Meta-Admin 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 can 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.

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

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.

configuration: dn: cn=join-engine, cn=Meta-Directories, cn=System,
ou=5, ou=Meta-Directory, ou=Global Preferences, ou=madisonparc.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)]]

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

Supported Requests

Meta-Directory, version 5.1.1, supports the following Meta-Admin protocol requests through the Meta-Admin Tool:

start

stop

status

statistics

request

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.

start

Attributes

Responses

stop

Attributes

Responses

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

Responses

read/statistics

This request reads and returns a component’s status and statistics values. Specify the component using the URL attribute.

Attributes

Responses

request

Attributes

Responses

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:

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:

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_Description: Contains a brief text description of the result. This result code can be used when NMC_Status equals 0 or 3.

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.

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.

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.


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.

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.