Chapter 4 The N1 Service Provisioning System Software Command-Line Interface

This chapter describes the command line interface for the N1 Service Provisioning System software.

The command-line interface (CLI) allows you to submit commands to the Master Server from a shell prompt, a DOS prompt, or a script.

The CLI requires a Command Line Interface Client to be installed on the local machine. If you want to run access the CLI in its interactive mode, using the cr_clij tool, Jython must be installed on the local machine, as well. For details about system requirements and configurations, please see the N1 Service Provisioning System 4.1 Installation Guide.

The Command-Line Execution Client provides a command-line interface to the Master Server. The Command-Line Execution Client enables commands to be executed from the following interfaces.

• the Windows command line or a local shell such as bash

• shell scripts using sh or Perl

To execute these commands, the Command Line Execution Client establishes a secure connection to the Master Server through TCP/IP, SSL, or SSH.

The Command Line Execution Client uses the Jython programming language. Jython is a Java implementation of the high-level, dynamic, object-oriented language Python. You should install Jython on any system on which you plan to install the command line execution client. For more information about Jython and to download Jython, visit http://www.jython.org.

The CLI is a suite of tools for accessing the N1 Service Provisioning System software through non-HTML interfaces, such as a Windows prompt, a shell, or a script. CLI commands can be used in scripts to automate provisioning software operations, such as checking in files. They can also be used to access the Master Server from systems that lack a Web browser or an HTTP connection.

The CLI requires a Command Line Execution Client, which can be installed on any server that can make a network connection to the Master Server. The client parses the commands into native objects and sends them to the Master Server. Results of the commands are then translated by the client to a textual format and presented to users.

Login authentication is enforced on most commands in the CLI. Users authenticate themselves by specifying a user name and a password or a session ID with each command.

The Structure of CLI Commands

Whether invoked through cr_cli or cr_clij, all CLI commands use the following format:

subsystem.object.command
arguments

For example, the command for adding a host to the database is hdb.h.add. This command consists three elements that identify:

• a subsystem, in this case the host database (hdb)

• an object to operate on, in this case a host (h)

• a command or operation, in this case adding (add)

Invoking CLI Commands

There are two tools for invoking the Command Line Interface :

• cr_cli, which operates in single-line command mode, executing one command at a time

• cr_clij, which operates in interactive command mode using a Jython interpreter

Working with the CLI

Authentication by Username and Password or Session ID

All but a few of the commands in the command line interface require authentication by username and password or by session ID.

cr_cli -cmd [command] -u [user] -p [password]

You do not need a username and password to get help on any of the commands or to list all available commands.

For increased security, place the password in a file and pass the file to the command. You can then use the filesystem to restrict access to the file containing the password. Use the following method to securely enter commands that require authentication. For more information on this technique, see Passing Arguments to the CLI from a File.

Create a file with the password, and pass the file to the command.

cr_cli -cmd [command] -u [user] -p exp:[passwordfile] 

Listing the Commands

To list all the commands available, type:

cr_cli -cmd -l

To list all the commands with a command prefix, use the wildcard character * after the prefix. For example, the command below lists all the hdb commands:

cr_cli -cmd -l hdb.*

Getting Help with the CLI

To access the general help for the CLI, enter the command:

cr_cli -help

To see the help for a specific command, enter the command:

cr_cli –cmd <commandname> –h 

CLI Syntax

CLI syntax includes:

• An initial specification of the CLI tool to be used:

  • cr_cli (must be specified at the beginning of each command)

  • cr_clij (must be specified when the CLI is first invoked)

• A CLI command

• Any arguments required by the command

• Optionally, additional arguments

• Arguments used for authentication. Either:

  • The -u user and -p password arguments

  • The -s sessionID argument, which specifies the session ID of an authenticated user (see Passing Data to an Individual CLI Argument for an example using the -s option)

The following is an example of the general CLI syntax:

Selecting the Output Format of a CLI Command

Because you may want to use the output resulting from CLI commands in various ways, you can adjust the format a CLI command uses to return information. There are two types of CLI output formats:

• standard output formats that are available to all CLI commands

• optional, command-specific output formats

Standard Output Formats

The CLI supports the following output formats:

If you do not specify an output format, the command uses its default format for the output.

To discover the default output format for a given command, refer to the help information for that command by running the command with -h:

cr_cli –cmd <commandname> –h 

The default output format will be in asterisks at the bottom of the help.

Command-Specific Output Formats

You can also use the -h argument to discover command-specific output formats that are available for a command.Table 4–3 lists command-specific output formats

Specifying the Output Format

To specify the output format for a CLI command, use the -o argument and list it as the first argument to the command. For example, to select the string output format for the hdb.h.la command, you would run the command:

cr_cli -cmd hdb.h.la -o string -u [user] -p [password]

The output format you specify must appear after the command itself, but before any other arguments, as shown in this example.

Passing Output Data to a File

To pass the data resulting from a command to an external file, you can use the -of option. Use -of to provide a fully-specified file name into which the N1 Service Provisioning System software can put the data from the command you execute.

For example, to pass the data from creating a host named myhost to a file called hostFile, type:

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

The file hostFile will contain the host information in detail format (the default formatter for the hdb.h.add command).

The -of option must occur right after the command name, before any other arguments.

Passing Data to an Individual CLI Argument

To pass data to the CLI from an external file, you can use the file: option. For instance, you may want to store the session ID of the session you have just started and then use it to authenticate commands.

To save the session ID to a file called session, type:

cr_cli -cmd udb.login -u [user] -p [password] > session 

Then, to pass the session ID to another command, type:

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

Converting the Output Format

To convert the output format of a command that you have passed to a file, you can use the reformat.util command.

The util.reformat command reads in data from the output file you specify and reformats it using the output format you choose.

For example, if you have 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] 
-p [password] -name myhost -tID NM:roxhost > hostFile

you can give util.reformat the output of the previous command and tell it to use the detail format by passing it hostFile using the file: option as described in Passing Data to an Individual CLI Argument:

cr_cli -cmd util.reformat -u [user] -p [password] 
-o hdb.detail -self file:hostFile

which will return:

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>

Passing Arguments to the CLI from a File

To pass an argument to the CLI from an input file, you can use the Expand option. To do this, you create a file into which you enter the information you want to pass to the CLI. Each argument and its value must be listed on a separate line. Arguments must be listed in the order in which the command requires them. To pass these arguments to the command, call the command and make the exp: argument the first argument.

For example, here are two files (file1.txt and file2.txt) that can be used in conjunction with the exp: option:

file1.txt:

hdb.h.la
-u
[user]
exp: file2.txt

file2.txt:

-p
[password]

To execute them, type:

cr_cli -cmd exp:file1.txt

The first file will call the second file and execute the command.

Descriptions and Multi-word Names

To specify a description or any other qualifier that includes a space, you must enclose the string in quotes, such as:

“This is a multi-word description.”

You can also escape every space with a backslash (\) if you prefer.

ID Substitution Using NM:

Most of the objects that you create have ID numbers associated with them. This ID number is a unique identifier for an entity, such as a user account or a component, in the repository.

ID numbers are useful because they are unique, but they can be cumbersome to enter as the argument to a command. To use names rather than ID numbers, you can use the tag NM: to introduce the name of an object on a command line..

Table 4–6 provides a complete listing of all supported NM: mappings.

To use the object name rather than the full ID number, use the following syntax to represent an object ID in any CLI command:

NM:<host|user|user group name|host type name|etc.>

with no spaces.

You can also use the NM: syntax to identify components and plans. You may optionally specify a version number in addition to the name itself:

plan = NM:<plan name>[:<version>]

For example:

NM:simplePlan
NM:simplePlan:1.0

If you do not specify a version number, the N1 Service Provisioning System software uses the latest version of the component or plan.

Showing and Hiding Objects

Because the objects you store in the repository are deeply interconnected, it is not possible to delete objects. You can choose to hide objects that you are not currently using to keep your work space uncluttered.

Hiding an object does not make it inactive or unusable. For example, if a resource is referenced by a component and the resource is hidden, the next build of the component will still reference the resource. The resource is not deactivated or removed; it is simply hidden from view.

You can specify whether or not to show or hide the following objects.

• Hosts

• Host types

• Host sets

• Host searches

• Users

• Plans

• Components

Working with CLI Commands

The commands available through the CLI can be grouped into several major categories:

Required Arguments and Optional Arguments

This command descriptions in this manual and the description of each command available through its help flag use the following notation to describe required arguments and optional arguments for commands.

For example, the help information for the hdb.h.add command lists the following arguments:

-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 the host name (-name) and the host type ID (-tID), in addition to the arguments required to authenticate the user or the session. However, if the host type of the new host requires host attributes to be specified, then the -attr argument must be used as well.

As the example above shows, the help information for command does not use the notation [R] to identify required arguments. Arguments that are required are simply listed without [O] or [O/R]. See the -name argument above for an example.

The cr_cli Tool

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; the user is not interactively prompted for the next input parameter. Operating in this mode, the Command Line Execution Client does not maintain a command history.

Here's an example of a CLI command executed with the cr_cli tool. This command adds a host of type prodserver to the host database. The user running this command, rbarnes, supplies his password to authenticate himself to the Master Server.

cr_cli –cmd hdb.h.add -user
rbarnes -p XyZ572 -name webb1 –desc `web server 1' –tID
prodserver

cr_cli commands can be stored in a file and be called from a shell script. This is useful for repetitive tasks such as running execution plans, comparisons, or populating hosts.

The cr_clij Tool

The interactive command line mode uses the Jython interpreter as its shell. Operating in this mode, the CLI offers you these advantages:

• You don't have to type an entire command on a single line. You can simply enter a command name and then enter the command arguments that cr_clij prompts you for.

• You can take advantage of the command history stored by the shell.

• You can call N1 Service Provisioning System software commands from within a Jython script.

• You can create more powerful scripts for more complex, repetitive operations.

Jython Scripts

To call commands from within a Jython script, include the following code at the beginning of the 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.

CLI Input Types

Table 4–6 describes the syntax of each type of input argument that may be passed to a CLI command.