test

N1 Grid Service Provisioning System 5.0 Command-Line Interface Reference Manual

Chapter 1 Using the Command-Line Interface

This chapter describes the command-line interface (CLI) for the N1 Grid 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:

This chapter covers the following topics:

CLI Command Structure

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.

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

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, use the -of argument. 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.


cr_cli -cmd hdb.h.add -of hostFile -u user-name
-p password -name myhost -tID NM:roxhost

After the command is run, hostFile contains output in detail format, which is the default output format for the hdb.h.add command.

Note that the -of argument must immediately follow the command specified by -cmd.

Reading Input From a File

To read in data from a file, identify the file by prefixing file: to the file name.

For example, you might want to store the session ID of the session you have just started and use it later to authenticate commands. First, save the RPC-serialized representation of the session ID to a file called session.


cr_cli -cmd udb.login -u user-name -p password -o serialized > session

Then, use the session ID in the session as input to another command.


cr_cli -cmd hdb.h.la -s file:session

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:

ProcedureHow 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

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

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:

[O]

The argument is optional.

[R]

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

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: