|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.
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:
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.
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:
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.
- % cd NETSITE_ROOT/bin/meta50/bin
% ./meta-admin [options] < 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 16-1 explains the command-line options that you can use to modify your administrative requests:
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).
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.
Table 16-2 describes the command-line options for controlling the output of the Meta-Admin Tool.
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.
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 admin-URL: http://admin:firstname.lastname@example.org: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" "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:
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 < admin_input.txt
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