Chapter 22 |
Command Line Interface |
Note - This feature may or may not be available on your system, depending on your licensing agreement.
The Sun Management Center Command Line Interface (CLI) provides an alternative method to the graphical user interface for monitoring and managing your system. The CLI also enables you to use the Sun Management Center server remotely.
The following topics are discussed in this chapter:
CLI functionality is similar to that provided in the GUI and provides many of the functions available through the GUI.
You can use the CLI to:
The CLI can be accessed from a user terminal session, using one of the following:
FIGURE 22-1 presents the Sun Management Center structure and the relationship of the CLI within the structure.
FIGURE 22-2 describes the software structure of the CLI. It contains four basic components:
CLI output is available only in text format. Features that require a GUI, such as physical view and graphing, are not available through the CLI.
Also, creation and viewing of groups and tasks are not supported in the CLI.
The following table describes characteristics of the CLI user environment
.
Two levels of user authorization are available:
The CLI is designed to support two interaction modes:
The parameter -b enables batch mode with a file option. Once the CLI is started, it will automatically execute the login command and prompt the user for login information. If the login is successful, the commands in the file will be executed one at a time. See "To Access the CLI in Solaris Environments".
Multiple-command or session mode is similar to the Sun Management Center GUI mode, in that it establishes a connection with the server before it is ready to provide service. Once a session is established, it can accept many service requests.
Session mode is more efficient in the networked environment when you apply multiple requests to a remote server. Session mode commences whenever the CLI is invoked without providing a specific operation on the command line. The exit status of the process indicates the success of the connection and authentication of the session, but does not attempt to indicate the success of individual operations.
Note - The Sun Management Center CLI can consider batch mode as one extreme case of session mode, in which there is only one command in the session. In this case, the exit status of the CLI indicates the success or failure of the operation performed.
To Access the CLI in Solaris Environments |
You can access the CLI in batch mode by typing the following command from
/opt/SUNWsymon/sbin:
./es-cli -b file
Note - The -b parameter indicates batch mode.
For multiple-command (or session) mode, type the following:
./es-cli parameters
Go to Step 1.
To Access the CLI in Microsoft Windows Environments |
After you have already installed the Sun Management Center console layer, double-click on es-cli in the CLI folder. A screen displays for CLI login.
1. | Type the login command. The login requires you to specify the host name and your login name. |
In the following example, seattle is the serverHost name, and joannm is the login name:
|
Your login name and password are the same as the name and password you enter on the Sun Management Center Login screen when using the Sun Management Center software GUI. |
2. | After the session is established, you can enter the desired commands:
|
The CLI commands are described in detail later in this chapter.
The CLI uses a set of reserved or predefined parameters in combination with the CLI commands to help you target the information you need. These parameters and corresponding values are listed in the following table:
TABLE 22-2 CLI Predefined Parameters and Values Parameter
Value
Optional Notes or Description
-b
This parameter is used to start the CLI in batch mode. It is ignored in session mode.
-h
When used as a parameter to a command, the help for the command is displayed. This parameter takes precedence over all other parameters. When -h is set, other parameters are ignored.
-l
This parameter has no effect on basic commands. This parameter is only used in extended commands to feed the result of the last extended command as an input to the current one. If this parameter is set, all other parameters will be ignored, and the parser will automatically feed the last extended output (including all parameters and results, if any) to the current extended command. Use this parameter sparingly in circumstances that warrant its necessity.
a
agent|agentList
agentList=agent[,agent]+
append
output file
The append parameter is used to append the results of a command to a file. If the file does not exist, it will be created. Use this parameter in conjunction with a command. Alternatively, set this parameter globally to append all subsequent output to a file. If the append and o parameters are both set, append takes precedence over o. Only results will be recorded. The command itself is not recorded. Use the log parameter to record command information.
columns
This parameter is used in extended commands to print only column(s) that correspond to the column name(s) specified in the value of this parameter. Multiple column names are delimited by a comma (","). for example:
columns="Alarm Id,Node URL,Target Host,Severity"
The values of this parameter are case-sensitive.f
plain|xml|html
Sets the output format to plain text, XML, or HTML. See "Format of CLI Output" for more information.
serverHost
server host
This parameter sets the server host for login. It is a global parameter that cannot be set after a login session is established.
height
number of lines
Number of lines displayed on a screen.
i
input file
This parameter is used to read an input file that contains various parameter settings into the current session. Each parameter setting should reside on a separate line. For example, an input file with three parameter settings would look as follows:
a=myagent:161
log
log file
This parameter is used to activate the recording of all CLI commands (including the time each command is entered) onto the specified log file. Once the parameter is set, all subsequent commands will be appended to the file. If the file does not exist, it will be created. Because the file is not overwritten, be sure a new file is created if you want a new set of records.
m
module|moduleList
module=moduleName[+moduleInstance]
moduleList=module[,module]+
more
on|off
If it is set to on, all subsequent outputs on the terminal will be displayed one screen at a time, which is defined by the height and width parameters. The default is off for batch mode and on for session mode.
o
output file
This parameter is used to write the results of a command to a file. If the file exists, it will be overwritten. Use this parameter in conjunction with the a command. Alternatively, set this parameter globally to write all subsequent output to a file. If append and o are both set, append takes precedence over o. Only results will be recorded. The command itself is not recorded. Use the log parameter to record command information.
serverPort
server port
This parameter is the server port for login. It is a global parameter that cannot be set after a login session is established. If it is not set, the default port of 2099 will be used.
t
topoObject
The topology object is the object managed in the topology agent. It can be a domain, a view group, or an entity. It is specified in the fully qualified name started from the domain, for example,
/domain/group/host.width
number of characters
Number of characters in one line displayed on a screen.
CLI operations support retrieval of information and manipulation of object attributes for topologies, modules, and alarms. The general format is:
> command [name=value]*
Parameters are a series of name-value pairs.
To Override Parameters |
Parameters passed on the command line are available throughout a session. The set command can be used to overwrite or store new parameters. For example:
./es-cli a=b > set a=b > set a=c > set x=y > set a=c x=y
The original values from the command line can be stored by entering reset. For example:
> reset a=b
The unset command can be used to remove a parameter from the current session. For example:
> set a=b c=d > unset a > set c=d
Specifying a parameter as part of an operation overrides the session parameter for the duration of that operation. When an explicit name value parameter is specified along with i=inputFile, the explicit name value overrides the value from the file. For example, if the file x contains:
a=b c=d
and you type:
> doSomething c=f i=x
then the doSomething command will see the value of c as f, and not d.
This applies also on the command line. For example:
./es-cli serverHost=bob i=serverFile
bob will override the value of of the host in the serverFile.
The CLI uses parameter lists to define all required parameters for a specific command. A parameter list is a list of name=value pairs, with values encapsulated in quotes (if they contain white space), with pairs separated by whitespace, and with no whitespace between the parameter name, the equals sign and the quoted value.
The following is an example of a parameter list:
m=kernel-reader moduleDesc="My Kernel Reader"
If a parameter has a list of values, they are separated by a comma (",") with no whitespace between each value. For example:
severity=DIS,DWN,ERR
The following name-value pairs are acceptable:
test1="This is just a test" test2=hello test3=hello,hi,aloha test4="hello,hi,aloha"
The following name-value pairs are not acceptable:
test1="How are you?","Who are you?" test2="Testing",1,2,3 test3="Hello test4=Hello"
Parameters can be entered during a session or read from a file. This file will contain key=value pairs separated by new lines. Values must be enclosed in quotes if they contain spaces. Use the i=fileName parameter to specify the location of the file.
This section describes the commands supported in the CLI. There are two types of commands:
Basic commands run in the foreground. You cannot run subsequent commands until you stop running a basic command.
Extended commands run in the background by default (unless the foreground parameter is set to on). Only one command can run in the background at any one time. Commands that run in the background do not produce any output to the screen to indicate its success or failure, errors encountered (if any), its progress, and so on. Use the print command to send output to the screen.
Note - When a command is running in the background, the login and logout commands are not allowed to run. These commands can interfere with the command that is running in the background.
The following table describes the basic CLI commands:
There are four types of extended commands available in the CLI:
There are seven extended commands for managing modules.
Examples for Using the Module Extended CLI Commands
If you want to find out which modules are loaded on a particular host, the command format is getLoadedModules a=agent. In this example, the agentHost name is seattle. You would type the following:
> getLoadedModules a=seattle
Next, suppose you wanted to load a module that is not currently loaded. The command format is loadModule a=agentHost:agentPort m=module. In this example, the agentHost name is still seattle and the agentPort is the default, 161. The module is the kernel reader module. You would type the following:
> loadModule a=seattle:161 m=kernel-reader
There are four extended commands for managing object attributes.
Examples for Using the Object Attribute Extended CLI Commands
In the following example to retrieve attributes, the agentHost name is haiku and the agentPort is 1161. The module is agent-stats, the managed object is totalstats, and the property is defined as size:
> getAttributes a=haiku:1161 m=agent-stats mgtObj=totalstats \ property=size
The following shows example parameters for deleting a row from a table (as specified in rowValues):
> delRow a=haiku:1161 \ m=filemon mgtObj=filemonstats/filemonTable/filemonEntry \ rowValues="name=test,desc=this,filename=/etc/passwd"
There are five extended commands for managing alarms.
Examples for Using the Alarms Extended CLI Commands
In the following example to retrieve alarms, the agentHost name is haiku and the alarms requested to be returned are specified as either ERR or DWN. The command getAlarms with no parameters would return all alarm information:
> getAlarms a=haiku severity=ERR,DWN
The following is an example parameter for deleting alarms with a specified notation:
> delAlarms note="by sysadm only"
Topology commands support the following parameter lists.
topoEntity_desc_list: specify a managed object information. It contains the following keywords:fullDesc=text
pollType=dummy|ping|snmp|ahost|amod|aprox
where agentPort is optional and is only used if url is not specified and the user does not want to use the default port.
topoEntity_filter_list: classify a group of managed objects under a certain conditionpollType=text
topoGroup_desc_list: specify a managed view group. It contains the following keywords:fullDesc=text
a=agent is a reserved parameter, where agent=agentHost[:agentPort].
There are seven extended commands for managing the topology.
Examples for Using the Topology Extended CLI Commands
In the following example, the command retrieves a list of managed topology objects under the default domain headquarters. The command would return a list of all groups and subgroups under the headquarters hierarchy:
> getTopoObject t=/headquarters
In the following example, the command creates a group under an existing domain named headquarters_test.
> createGroup t=/headquarters_test/build19 \ fullDesc="test headquarters domain" family=building-location
The output of a basic command is available only in plain text. The output of an extended command is available in three formats:
Use the f parameter to set the output to the intended format. Regardless of the format, an output will consist of a set of results. Each result contains a list of name=value pairs, with each pair occupying one row. Thus, each result may span multiple rows.
For retrieval commands, the name in the list of name=value pairs is the target attribute, or a managed object.
For set commands, each result will have the following format:
state=OK|Fail message=""
where state tells whether the command is successful, and message provides the details.
When an error is encountered, it should be generated in the following format:
state=Fail message=""
where message contains an error message.
When the f parameter is set to plain, the output format is set to plain text. To clearly delineate different results, each result begins and ends with a separator. The following example shows an output in plain text:
== <commandName>: Results 1/2 ======================= attribute1=value1 attribute2=value2 == <commandName>: Results 2/2 ======================= attribute1=value3 attribute2=value4 ====================================================
When the f parameter is set to xml, the output format is set to XML. In this format, each result is delineated by a Row tag. A set of results contains a list of Row tags.
Each Row contains a set of Property tags, which is a list of name=value pairs. Each Row has a Type attribute with either Data or Error as its value.
Data indicates that the set of Properties is information that has been retrieved, whereas Error indicates that the set of Properties is related to an error that has occurred. The following is an example of XML output:
<?xml version="1.0"?> <Table Command="<commandName>"> <Row Type="Data"> <Property Name="attribute1">value1</Property> <Property Name="attribute2">value2</Property> </Row> <Row Type="Data"> <Property Name="attribute1">value3</Property> <Property Name="attribute2">value4</Property> </Row> </Table>
When the f parameter is set to htm or html, the output format is set to HTML. In this format, the set of results is enclosed in a table. Each result takes up one row, with the top row comprising the column headings, that is, the name of each name=value pair.
The first column heading is Row, and lists the row number for each row. Subsequent rows have columns that contain values.
Each column in a subsequent row contains the value of a name=value pair in the corresponding result. Each result that is related to an error will be displayed in another table. If a column has no data, it is grayed out.
The following example shows an incomplete excerpt of HTML output:
<TABLE BORDER=1 CELLPADDING=5 CELLSPACING=0 BGCOLOR="#FFFFCC"> <TR VALIGN=TOP> <TD ALIGN=CENTER BGCOLOR=0><FONT COLOR=WHITE><B>Row</B></FONT></TD> <TD ALIGN=CENTER BGCOLOR=0><FONT COLOR=WHITE><B>attribute1</B></FONT></TD> <TD ALIGN=CENTER BGCOLOR=0><FONT COLOR=WHITE><B>attribute2</B></FONT></TD> </TR> <TR VALIGN=TOP> <TD ALIGN=CENTER>1</TD> <TD>value1</TD> <TD>value2</TD> </TR> <TR VALIGN=TOP> <TD ALIGN=CENTER>2</TD> <TD>value3</TD> <TD>value4</TD> </TR> </TABLE>
CLI commands (including the time a command is entered) are recorded in a log file. The log file has the following format:
DATE & TIME;duration or message;command and parameters
For example:
Wed Jan 26 10:18:20 EST 2000;== START OF THREAD ==;getAlarms Wed Jan 26 10:18:27 EST 2000;7 seconds;getAlarms
To Record CLI Commands in a Log File |
1. | Set the log parameter to a file name. For example:
|
Once the parameter is set, all subsequent commands are appended to the file. If the file does not exist, it will be created.
The file will not be overwritten, so make sure a new file is created if you want a new set of records.
2. | To stop recording, unset the log parameter. For example:
|
All commands and log files are available only in English. Command descriptions and help text, however, follow the Java internationalization guidelines for the following additional languages: