This chapter describes the command-line interface (CLI) for the Sun N1 Service Provisioning System software, which enables you to submit commands to the master server from another server. You can run the CLI from a shell prompt, a DOS prompt, or a script. You can also use the CLI as an alternative to the browser interface to access the master server. Before you can use the CLI, you must first install the Command-Line Interface Client on the local server.
The CLI can be run in these two modes:
Single-line – This mode requires that you type complete commands and does not prompt you for missing information.
Interactive – This mode initiates a login session in which you can run one or more commands. When you initiate a login session in this way, you only need to authenticate once. This mode depends on the Jython programming language already being installed on the server. See the Sun N1 Service Provisioning System 5.1 Installation Guide.
The Jython programming language is a JavaTM implementation of the object-oriented Python language. You must install Jython on any system on which you plan to install the Command-Line Interface Client, see http://www.jython.org.
This chapter covers the following topics:
The cr_cli command has the following syntax:
cr_cli -cmd command authentication-arguments [ other-arguments ] |
Note that most commands must use the authentication arguments: either -u and -p, or -s. To determine whether a command requires the authentication arguments, see the description of the command. Also, the authentication arguments do not have a fixed position on the command line, but they must appear after the -cmd, -h, -o, and -of arguments.
Name of the command to run.
All CLI commands use the following format:
subsystem.object.command |
For example, the command for adding a host to the database is hdb.h.add.
subsystem is the name of the subsystem, such as hdb for the host database commands.
object is the object that the command affects, such as h for a host.
command is the action that the command performs, such as add that adds a host to the database.
Most of the CLI commands require authentication, however, you do not need to authenticate to get help or to list the available commands.
User name to use for authentication. To authenticate, you must also specify a password for the specified user.
As an alternative to supplying the user name and password, you can specify a session ID.
Password that is used to authenticate the user specified by -u.
A password that you specify on the command line is not secure, as it can appear in process lists and in a shell's command-line history. So, to keep your password secure, store your user name and password in a file on the local file system and refer to that file as input to your command. See the first example in Example 1–1. Make sure that the user owns the file and that the file is only readable by that user.
Session ID that is used to authenticate a session.
For information about how to get the session ID and use it for authentication, see Reading Input From a File.
As an alternative to supplying the session ID, you can specify a user name and password by using the -u and -p arguments.
Arguments and values that are associated with command.
The cr_cli command returns 0 on success and 1 on failure.
The following are some examples of the provisioning software's CLI:
This example shows how to read the user name and password from a file to authenticate the command. The file, .terrypw, contains the user name and password for Terry in the following format:
-u terry -p securepasswd |
To authenticate the hdb.h.lo command, Terry runs the following command:
cr_cli -cmd hdb.h.lo -exp:.terrypw |
Store the file on a local file system and use the file permissions to restrict access to the file. For more information, see Reading CLI Arguments From a File.
This example shows how user, terry, retrieves information about the host, barolo7. This command supplies the password directly on the command line.
cr_cli -cmd hdb.h.lo -ID NM:barolo7 -u terry -p password |
Note that specifying the password in this way is insecure.
This example shows how to pass arguments that include spaces by enclosing the string in quotes. In this example, user terry modifies the description of the component named myWebServer:
cr_cli -cmd cdb.c.mod -comp myWebServer -desc "Version 3.7 of My Web Server" -u terry -p 123xyz |
On UNIX® systems, you can escape each space with a backslash character (\).
cr_cli -cmd cdb.c.mod -comp myWebServer -u terry -p 123xyz -desc Version\ 3.7\ of\ My\ Web\ Server |
Most of the objects that you create are associated with ID numbers. An ID number is a unique identifier for an object in the repository, such as a user account or a component.
While ID numbers are useful, they can be cumbersome to use. To use names rather than ID numbers, introduce the name of an object by using the NM: notation.
For a complete list of the supported NM: mappings, see Appendix A, Input Types.
For example, the following syntax is used to represent object IDs, such as hosts, user names, user group names, and host type names:
NM:host NM:user-name NM:user-group-name NM:host-type-name |
You can also use the NM: syntax to identify components and plans by name and optional version number:
NM:plan-name[:version] |
The following are some sample uses of this notation:
NM:simplePlan NM:simplePlan:1.0 NM:/foo/bar/simplePlan:1.1 |
If a version number is not specified, the provisioning software uses the latest version.
The following sections describe how to use files as input to the CLI and how to use files to store output from the CLI commands.
To redirect command output to a file, you can either use the -of argument or use a shell redirect. The argument to the -of argument is a full path to a file.
For example, this command writes the output to a file called hostFile. Note that the -of argument must immediately follow the command specified by -cmd.
cr_cli -cmd hdb.h.add -of hostFile -u user-name -p password -name myhost -tID NM:system#crhost |
After the command is run, hostFile contains output in detail format, which is the default output format for the hdb.h.add command.
Another example of redirecting output to a file involves using a stored session ID to authenticate commands. First, save the RPC-serialized representation of the session ID to a file called session. You can redirect this output to a file using either method.
Create a file using a shell redirect
cr_cli -cmd udb.login -o serialized -u user-name -p password > session |
Create a file using the -of argument
cr_cli -cmd udb.login -o serialized -of session -u user-name -p password |
Once you have stored your session ID in a file, you can use the file as input to another command. See Reading Input From a File.
To pass data from a file to a command, identify the file by adding the prefix file: to the file name.
For example, if you have stored a session ID in a file and want to use the file to authenticate the hdb.h.la command, use the file as input to the command.
cr_cli -cmd hdb.h.la -s file:session |
If you did not create the session with the -o serialized argument, you can pass a serialized version of the file to another command by using the ser: prefix.
cr_cli -cmd hdb.h.la -s ser:session |
To read a CLI argument from an input file, identify the input file by prefixing exp: to the file name. First, create a file that contains the information you want to pass to the CLI. Note that each argument must be listed on a separate line and must appear in the order required by the command.
Then, have the command get the arguments from the file.
For example, these files, file1.txt and file2.txt, can be used in conjunction with exp: to specify command arguments.
file1.txt contains the following:
hdb.h.la -u user-name exp:file2.txt |
file2.txt contains the following:
-p password |
To execute the command that is described by these files, type the following:
cr_cli -cmd exp:file1.txt |
You can adjust the output format a CLI command. To specify the output format for a CLI command, the -o argument must immediately follow the command you specified by -cmd.
For example, to specify the string output format for the hdb.h.la command, type the following:
cr_cli -cmd hdb.h.la -o string -u user-name -p password |
These are the standard output formats that are available to all CLI commands:
Produces an internal string representation of the result that depends on the command.
Produces brief output.
Produces XML serialized text output.
Use this argument when you want to pass information to another script. Do not depend on the structure of this format, as it could change.
Discards output.
On UNIX systems, output is redirected to /dev/null.
Shows detailed information. Note that this format is not available for all commands.
If you do not specify an output format, the command uses its default output format. To see the default output format for a command, run the following:
cr_cli -cmd command -h |
Use the reformat.util command to convert the output format of a command that has been written to a file. The reformat.util command reads data from the specified output file and reformats it by using the specified output format.
For example, you created a host and stored the output from the hdb.h.add command in serialized format in a file named hostFile:
cr_cli -cmd hdb.h.add -o serialized -u user-name -p password -name myhost -tID NM:roxhost > hostFile |
Use the util.reformat command to reformat the output to be the hdb.detail format.
cr_cli -cmd util.reformat -o hdb.detail -u user-name -p password -self file:hostFile |
The previous command results in the following output:
ID: 010010000204-1027365659275-00170-1199101891 Name: myhost Description: Virtual: false Hidden: false Type ID: 010010001024-0000000000000-00001-0000000004 Attributes: <Table is empty> Applications: <Table is empty> |
To execute one CLI command at a time, use the cr_cli tool. This tool invokes the CLI in single-line command mode.
Single-line command mode accepts one command at a time as input. Each command submitted must be complete, you are not interactively prompted for the next input parameter. When operating in this mode, the Command Line Execution Client does not maintain a command history.
cr_cli commands can be stored in a file and called from a shell script. This feature is useful for repetitive tasks such as running execution plans, comparisons, or populating hosts.
The interactive command-line mode uses the Jython interpreter as its shell. When operating in this mode, the CLI offers you these advantages:
You can take advantage of the command history that is stored by the shell.
You can call the provisioning software commands from a Jython script.
You can create more powerful scripts for complex, repetitive operations.
From a server where the CLI Client is installed, type the command.
./cr_cli -cmd subsystem.object.command -u user -p password |
From a server where the CLI Client and Jython are installed, start the CLI Jython Interpreter.
./cr_clij |
Include the following code at the beginning of your script.
from clui import * app=PyCLUI() app.execStr(CLI command) App.close() |
The assignment app=PyCLUI() calls the CLI. The App.close() call deletes the instance of this Jython class.
To get general help about the CLI, type the following:
cr_cli -help |
To get help for a specific command, type the following:
cr_cli -cmd command -h |
The command descriptions use the following notation to indicate whether an argument is required or optional:
The argument is optional.
The argument is required.
The argument is usually optional, but might be required in some cases.
In such situations, the help indicates when the argument is required.
The following is the help information for the hdb.h.add command:
-u [O/R]: The user username for authentication: String -p [O/R]: The user password for authentication: String -s [O/R]: The session ID for authentication: SessionID -name: The host name: String -desc [O]: The host description: String -tID: The ID of the host type: HostTypeID -attr [O/R]: The host attributes; required if the host type requires them: Hashtable |
In this example, the only required arguments are -name, -tID, and the authentication arguments: either -u and -p, or -s. If the host type of the new host requires that host attributes be specified, the -attr argument is also required.
Note that help you get by using the -h does not use the [R] notation to identify required arguments. Required arguments are shown without any notation.
To list all of the available commands, type the following:
cr_cli -cmd -l |
To list all of the commands that have the same command prefix, use the wildcard character * after the prefix. You might need to escape the * with a backslash (\) or by enclosing it in double quotes. For example, the following command lists all of the hdb commands:
cr_cli -cmd -l "hdb.*" |
The CLI commands are grouped in the following categories:
cat – Categories
cdb – Component database
cfg – Configuration generator
cmp – Comparison engine
fdb – Folder repository
hdb – Host repository
net – Network operations
pdb – Plan repository
pe – Plan execution
plg – Plug-in repository
rule – Rules for notifications
udb – User repository
util – Miscellaneous utilities