Sun ONE Meta-Directory 5.1 Configuration and Administration Guide |
Chapter 19 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:
- 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:
NETSITE_ROOT/bin/meta50/bin
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.ldifHere, 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 19-1 explains the command-line options that you can use to modify your administrative requests:
Table 19-2 describes the command-line options for controlling the output of the Meta-Admin Tool.
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 "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 the example script in code sample 19-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 appropriate component.
Code below shows how you can perform a Refresh operation on the Meta View. The refresh operation is permitted only for the Join Engine.
admin-URL: http://admin:admin@cherokee.india:6667
configuration: LDAP://cherokee.india.sun.com:6006/
cn%join50-engine%cn%Meta-Directories%cn%System
%ou%5%ou%Meta-Directory
%2Cou%3DGlobal%Preferences%ou%india%o%NetscapeRoot
authenticationDetails: simple "cn=Directory Manager" "sunone"
admin-path: join50-engine/Tasks/request
op: refresh MV
# op: refresh CV
cv: CV5
mv: MV
The new Java based connectors (ie, the Novell Directory and Lotus Notes connectors) dont support simple authentication. You need to perform a base64 encode of the username and password, as shown in code below:
admin-URL: http://admin:admin@cherokee.india:6667
configuration: ldap://cherokee:6006/cn%3dndc-CV,%20
cn%3dConnectors,cn%3dSystem,%20ou%3d5,%20ou%3dMeta-Directory,
%20ou%3dGlobal%20Preferences,%20ou%3dindia,%20o%3dNetscapeRoot
authenticationDetails: simple_base64
Y249ZGlyZWN0b3J5IG1hbmFnZXI= bmV0c2NhcGU=
admin-path: ndc50-CV1/Tasks/start
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:
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 "The Meta-Admin Protocol." In particular, see the section titled "Protocol Responses."