SA CLI methods

End-users access SA through the SA Client. At times, advanced users need to access SA in a command-line environment to perform bulk operations or repetitive tasks on multiple servers. In SA, the command-line environment consists of the Global Shell (OGSH), Global File System (OGFS), and SA Command-Line Interface (CLI) methods.

To perform SA operations from the command line, you invoke the SA CLI methods from within an OGSH session. An SA CLI method is an executable in the OGFS that corresponds to a method in the SA API. When you run an SA CLI method, the underlying API method is invoked.

To understand this section, you should be familiar with the OGSH and the OGFS. For more information, see the OGSH in the Server Automation Using Guide on the HPE SSO portal.

For information on the oupload and odownload commands, see the OCLI 1.0 in the Server Automation Using Guide on the HPE SSO portal.

Method invocation

As shown in the following figure, when you invoke an SA CLI method in an OGSH session, the following operations occur:

1. The OGSH parses the command and parameters you entered to determine the API method.
2. The OGSH invokes the underlying API method.
3. An authorization check verifies that the user has permission to perform this operation. SA then performs the operation.
4. The API method passes the results back to the SA CLI method.
5. The SA CLI method writes the return value to the stdout of the OGSH session. If an exception was thrown, the SA CLI method returns a non-zero status.

Overview of an SA CLI method invocation

Security

SA CLI methods use the same authentication and authorization mechanisms as the SA Client. When you start an OGSH session, SA authenticates your SA user. When you run an SA CLI method, authorization is performed. To run an SA CLI method successfully, your SA user must belong to a group that has the required permissions. For more information on security, see the Server Automation Administer section on the HPE SSO portal.

Mapping between API and SA CLI methods

The OGFS represents SA objects as directory structures, object attributes as text files, and API methods as executables. These executables are the SA CLI methods. Every SA CLI method matches an underlying API method. The method name, parameters, and return value are the same for both types of methods.

For example, the setCustomer API method has the following Java signature:

public void setCustomer(ServerRef self,

                       CustomerRef customer)...

In the OGFS, the corresponding SA CLI method has the following syntax:

setCustomer self:i=server-id customer:i=customer-id

Note that the parameter names, self and customer, are the same in both languages. (The :i notations are called format specifiers, which are discussed later in this section.) In this example, the return type is void, so the SA CLI method does not write the result to the stdout. For information on how SA CLI methods return strings that represent objects, see Return values .

Differences between SA CLI methods and Unix commands

Although you can run both Unix commands and SA CLI methods in the OGSH, SA CLI methods differ in several ways:

• Unlike many Unix commands, SA CLI methods do not read data from stdin. Therefore, you cannot insert an SA CLI method within a group of commands connected by pipes (|). (However, SA CLI methods do write to stdout.)
• Most Unix commands accept parameters as flags and values (for example,
  ls -l /usr). With SA CLI methods, command-line parameters are name-value pairs, joined by equal signs.
• Unix commands are text based: They accept and return data as strings. In contrast, SA CLI methods can accept and return complex objects.
• With SA CLI methods, you can specify the format of the parameter and return values. Unix commands do not have an equivalent feature.