Chapter 1 Using the Command-Line Interface

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.2 Installation Guide.

  The Jython programming language is a Java^TM 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:

• CLI Command Structure

• CLI Input and Output

• Output Formats of CLI Commands

• Running the Command-Line Interface

• Getting Command-Line Help

CLI Command Structure

The cr_cli command has the following syntax:

cr_cli -cmd command common-arguments authentication-arguments [ other-arguments ]

Note that the common-arguments must be used in the position shown above , before the authentication arguments and other-arguments. The following table lists the common-arguments supported by all commands.

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.

-cmd command

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.

authentication-arguments

Most of the CLI commands require authentication, however, you do not need to authenticate to get help or to list the available commands.

-u user-name

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.

-p password

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.

-s session-ID

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.

other-arguments

Arguments and values that are associated with command.

The cr_cli command returns 0 on success and 1 on failure.

Example 1–1 Using the CLI

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

Using NM: to Perform ID Substitution

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.

CLI Input and Output

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.

Redirecting Output to a File

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.

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 store the session id to a file , you can pass a serialized version of the session object directly to another command by using the ser: prefix. In the example below, the serialized session object obtained by using udb.login command with the with the -o serialized argument, is available in sessionStr .

cr_cli -cmd hdb.h.la -s ser:sessionStr

Reading CLI Arguments From a File

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

Output Formats of CLI Commands

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:

raw

Produces an internal string representation of the result that depends on the command.

string

Produces brief output.

serialized

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.

sink

Discards output.

On UNIX systems, output is redirected to /dev/null.

detail

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

Converting the Output Format

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>

Running the Command-Line Interface

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.

How to Run the Single-Command CLI

Step

From a server where the CLI Client is installed, type the command.

./cr_cli -cmd subsystem.object.command -u user -p password

How to Run the CLI Jython Interpreter

Steps

1. From a server where the CLI Client and Jython are installed, start the CLI Jython Interpreter.

   ./cr_clij

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

   ---

   Note –

   Only the execStr and execRaw calls are supported for SPS scripts with Jython. The returned objects from execRaw can only be used as parameters for other execRaw calls. If you attempt to use an object returned from an execRaw call as a parameter to an execStr call, the call fails. You can use the toString() method of the object to construct the string to feed to the execStr call.

   ---

Getting Command-Line Help

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:

Optional

The argument is optional.

Required

The argument is required.

[O/R]

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 Optional: 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 Required notation to identify required arguments. Required arguments are shown without any notation.

Listing the CLI Commands

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