Previous     Contents     Index     Next     
iPlanet Meta-Directory Configuration and Administration Guide

Chapter 16   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 is used in conjunction with the Meta-Admin protocol, which lets you perform the following administrative processes on a Meta-Directory component:

  • Start a specified component.

  • Stop a specified component.

  • Get the status of a specified component.

  • Get the statistics of a specified component.

The 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 or HTTPS POST requests. Your requests are routed through the Administration Server CGI scripts to the specified component.

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

In the LDIF input you supply, each request you make contains 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. The tool translates these responses into success and error messages.

When you run it, the Meta-Admin Tool does the following:

  1. Reads requests (in LDIF format) from stdin.

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

  3. Echoes the Meta-Directory component responses to stdout.

  4. Outputs any error messages to stderr.

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

The 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.005_03, 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 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, you can issue the following commands from a command prompt to run the Meta-Admin Tool:

% cd NETSITE_ROOT/bin/meta50/bin
% ./meta-admin [options] < input.ldif

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.

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 16-1 explains the command-line options that you can use to modify your administrative requests:

Table 16-1    Request-related options for the Meta-Admin Tool  



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



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:

    -H `referrer: http://other.url'
    -H `Host:
your_host' < ldif.input

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

Table 16-2    Options that control the output for the Meta-Admin Tool 

Output Options



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.  


Prints the request method and absolute URL as requests are made.  


Prints the request headers in addition to request method and absolute URL.  


Prints response status code. This option is always on for HEAD requests.  


Prints response status chain showing redirect and authorization requests handled by the library.  


Prints response headers. This option is always on for HEAD requests.  


Specifies that the content of a response not be printed.  


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.



Prints the version number of the program and quits.  


Prints the usage message and quits.  


Provides extra debugging output.  

Meta-Admin Tool Input

To administer the Meta-Directory components using the Meta-Admin Tool, you create an LDIF file which contains the commands for the administrative tasks you want to perform. You 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 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 LDIF format, you structure your administrative requests, where each request has attributes and values that conform to the Meta-Admin protocol.

Note You 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 Appendix B, "The Meta-Admin Protocol."

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.

You could use example script below 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.

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

configuration: LDAP://
authenticationDetails: simple "cn=Directory Manager" "iplanet"
#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:

meta-admin < admin_input.txt

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.

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 16-2    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.

For details on the responses you receive, review Appendix B, "The Meta-Admin Protocol." In particular, see the section titled "Protocol Responses."

Previous     Contents     Index     Next     
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated April 08, 2002