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:

Overview of the Sun Management Center CLI

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:

Retrieve topology information (domain/group/entity).
Create topology objects (domain/group/entity).
Retrieve/manipulate managed object properties/attributes.
Load/unload module(s) on one or a set of Sun Management Center agents.
Enable/disable module(s) on one or a set of Sun Management Center agents.
Retrieve alarm information on one or a set of Sun Management Center agents.
Acknowledge or delete alarms on one or a set of Sun Management Center agents.
Set and run alarm actions on one or a set of Sun Management Center agents.

The CLI can be accessed from a user terminal session, using one of the following:

UNIX workstation, running Solaris 2.6 and higher
PC, running Windows98 or Windows NT

Relationship of the CLI to the System Structure

FIGURE 22-1 presents the Sun Management Center structure and the relationship of the CLI within the structure.

FIGURE 22-1 CLI in Sun Management Center System Structure

CLI Software Structure

FIGURE 22-2 describes the software structure of the CLI. It contains four basic components:

The Command IO component is used to parse the command line arguments and present the operational results, including errors, warnings, and exit status.
The Session Handler is used to set up a connection and maintain a session during the interaction.
The Operation Implementation layer implements the CLI operation functionality.
The Client API is used to implement all supported CLI operations.

FIGURE 22-2 CLI Software Structure

Constraints

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.

Assumptions and Dependencies

Functions supported in the CLI are a subset of the functions available in the GUI console.
The CLI provides comparable information to the output retrieved using the associated GUI functionality, but the information is formatted differently.
High-level operations can be performed by a single CLI command.

CLI User Interface

The following table describes characteristics of the CLI user environment

TABLE 22-1 Characteristics of the CLI User Environment
Characteristic
Description

Secured user access

You specify the host and port number on which the server is running, and provide a Sun Management Center login ID on the Sun Management Center server. You will be prompted to enter your password.

Independency

Commands in the CLI are independent. This means that no command's execution is required as a condition for execution of any other command.

Help

The CLI provides a help system that tells you the available commands, and explains how to use the commands.

Input

The CLI allows users to specify which operation is going to apply and where (scope and condition) to apply it. These specifications can be entered through the command line as parameters, or through an input file. Operations can be spread over several input lines, with a backslash at the end of a line signifying continuation on the following line.

Output

The CLI reports results as well as errors in a readable format.
Results can be output to a specified file, and should be formatted in such a way that it can be used as input to subsequent CLI commands. In batch mode, the CLI produces an exit status on termination that is indicative of the success of the operation.

.

**TABLE 22-1** Characteristics of the CLI User Environment
Characteristic	Description
Secured user access	You specify the host and port number on which the server is running, and provide a Sun Management Center login ID on the Sun Management Center server. You will be prompted to enter your password.
Independency	Commands in the CLI are independent. This means that no command's execution is required as a condition for execution of any other command.
Help	The CLI provides a help system that tells you the available commands, and explains how to use the commands.
Input	The CLI allows users to specify which operation is going to apply and where (scope and condition) to apply it. These specifications can be entered through the command line as parameters, or through an input file. Operations can be spread over several input lines, with a backslash at the end of a line signifying continuation on the following line.
Output	The CLI reports results as well as errors in a readable format. Results can be output to a specified file, and should be formatted in such a way that it can be used as input to subsequent CLI commands. In batch mode, the CLI produces an exit status on termination that is indicative of the success of the operation.

User Authorization

Two levels of user authorization are available:

General end users can retrieve monitored object properties.
Administrative users have the same privileges as general users, and can also set up or modify the managed system.

CLI Interaction Modes

The CLI is designed to support two interaction modes:

Batch mode: The CLI connects to the server, executes commands one at a time, and closes the connection.
Multiple-command or Session mode: The CLI establishes a connection with the server, then accepts all operations until it receives an explicit closing request. The session can include multiple operations.

Batch Mode

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

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.

Logging in to Sun Management Center Software

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

`./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.

`./es-cli` parameters

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.

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:


> `login serverHost=seattle` Login: `joannm`Password: >

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.

After the session is established, you can enter the desired commands:


> command

The CLI commands are described in detail later in this chapter.

CLI Command Parameters

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

agent=agentHost[:agentPort]
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:
more=off
serverHost=myserver
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.

**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`	`agent=agentHost[:agentPort]` `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: `more=off` `serverHost=myserver` `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.

Operation and Parameter Format

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.

`>` command`[name=value]*`

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.

`./es-cli a=b`> `set`a=b > `set a=c`> `set x=y`> `set`a=c x=y

`>` `reseta=b`

`>` `seta=bc=d>` `unset a>` `setc=d`

`a=bc=d`

`>` `doSomething c=f i=x`

`./es-cli serverHost=bob i=serverFile`

Command-Specific Parameters

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.

m=kernel-reader moduleDesc="My Kernel Reader"

severity=DIS,DWN,ERR

test1="This is just a test" test2=hello test3=hello,hi,aloha test4="hello,hi,aloha"

test1="How are you?","Who are you?" test2="Testing",1,2,3 test3="Hello test4=Hello"

CLI Commands

This section describes the commands supported in the CLI. There are two types of commands:

Basic
Extended

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.

Basic CLI Commands

The following table describes the basic CLI commands:

TABLE 22-3 Basic Commands for the CLI
Command name
Description

alias

Lists all available pseudonyms or shorthand terms for commands.

clear

Removes all parameters from the current session.

exit

Logs out from the server and exits the CLI.

help

Lists all available CLI commands in alphabetical order with a brief description of each. Basic commands are listed first, followed by extended commands. (Also see the more command below.)

kill

Kills the command that is running in the background.

login

Logs in to a Sun Management Center server. This command prompts you for your user name and password. You must log in before performing commands with the Sun Management Center server or agents. Once you log in to a session, no other login will be allowed until you run the logout command.

logout

Terminates your connection to the Sun Management Center server.

more

Displays help on a specified command, including parameters, defaults, and procedures.

print

Prints the results of the last extended command in the specified format to the specified destination. If the parameter o is set, the printout is directed to a file and is not shown on the screen.
Note: This command is not saved in the command history.

quit

Logs out from the server and exits the session (same as the exit command).

reset

Resets all parameters to what was set from the command line. Any parameter that is set after the command line is left unchanged.

set

Store or display parameters in the current session. The parameter is available to all commands.

status

Shows the status of the command that is running in the background.

unalias

Removes a pseudonym or shorthand term for a command.

unset

Removes parameter settings from the current session. Note: This command is not saved in the command history.

**TABLE 22-3** Basic Commands for the CLI
Command name	Description
`alias`	Lists all available pseudonyms or shorthand terms for commands.
`clear`	Removes all parameters from the current session.
`exit`	Logs out from the server and exits the CLI.
`help`	Lists all available CLI commands in alphabetical order with a brief description of each. Basic commands are listed first, followed by extended commands. (Also see the `more` command below.)
`kill`	Kills the command that is running in the background.
`login`	Logs in to a Sun Management Center server. This command prompts you for your user name and password. You must log in before performing commands with the Sun Management Center server or agents. Once you log in to a session, no other login will be allowed until you run the `logout` command.
`logout`	Terminates your connection to the Sun Management Center server.
`more`	Displays help on a specified command, including parameters, defaults, and procedures.
`print`	Prints the results of the last extended command in the specified format to the specified destination. If the parameter `o` is set, the printout is directed to a file and is not shown on the screen. Note: This command is not saved in the command history.
`quit`	Logs out from the server and exits the session (same as the `exit` command).
`reset`	Resets all parameters to what was set from the command line. Any parameter that is set after the command line is left unchanged.
`set`	Store or display parameters in the current session. The parameter is available to all commands.
`status`	Shows the status of the command that is running in the background.
`unalias`	Removes a pseudonym or shorthand term for a command.
`unset`	Removes parameter settings from the current session. Note: This command is not saved in the command history.

Extended CLI Commands

There are four types of extended commands available in the CLI:

Module commands
Object attribute commands
Alarm commands
Topology commands

Module Extended Commands

There are seven extended commands for managing modules.

TABLE 22-4 Module Extended Commands in the CLI
Command name
Reserved Parameters
Description

disableModule

a=agent|agentList
m=module|moduleList

Disable a module or modules in an agent or agents.

enableModule

a=agent|agentList
m=module|moduleList

Enable a module or modules in an agent or agents.

getLoadedModules

a=agent|agentList

Get a list of loaded modules in an agent or agents.

getModule

a=agent|agentList
m=module

Get information for a particular module.

getModules

a=agent|agentList

Get a list of modules in an agent.

loadModule

a=agent|agentList
m=module|moduleList
moduleName=name
moduleDesc=description

Load a module in an agent or agents.

unloadModule

a=agent|agentList
m=module|moduleList

Unload one or more modules in an agent or agents.

**TABLE 22-4** Module Extended Commands in the CLI
Command name	Reserved Parameters	Description
`disableModule`	`a=agent\|agentList` `m=module\|moduleList`	Disable a module or modules in an agent or agents.
`enableModule`	`a=agent\|agentList` `m=module\|moduleList`	Enable a module or modules in an agent or agents.
`getLoadedModules`	`a=agent\|agentList`	Get a list of loaded modules in an agent or agents.
`getModule`	`a=agent\|agentList` `m=module`	Get information for a particular module.
`getModules`	`a=agent\|agentList`	Get a list of modules in an agent.
`loadModule`	`a=agent\|agentList` `m=module\|moduleList` `moduleName=name` `moduleDesc=description`	Load a module in an agent or agents.
`unloadModule`	`a=agent\|agentList` `m=module\|moduleList`	Unload one or more modules in an agent or agents.

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

> `getLoadedModules a=seattle`

> `loadModule a=seattle:161 m=kernel-reader`

Object Attribute Extended Commands

There are four extended commands for managing object attributes.

TABLE 22-5 Object Attribute Extended Commands in the CLI
Command name
Reserved Parameters
Description

addRow

a=agent[,agent]+
m=module
mgtObj=managed_object
property=property
propInst=property_instance
rowValues="name=value[,name=value]+"

Add a row in a table.

delRow

a=agent[,agent]+
m=module
mgtObj=managed_object
property=property
propInst=property_instance
rowValues="name=value[,name=value]+"

Delete a row in a table.

getAttributes

a=agent[,agent]+
m=module
mgtObj=managed_object
property=property
propInst=property_instance

Get certain attributes in an agent or a list of agents.

setAttributes

a=agent[,agent]+
m=module
mgtObj=managed_object
property=property
propInst=property_instance
attributes=""
values=""

Set certain attributes in an agent or a list of agents.

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"

Alarms Extended Commands

There are five extended commands for managing alarms.

TABLE 22-6 Alarms Extended Commands in the CLI
Command name
Reserved Parameters
Description

ackAlarms

a=agent|agentList
note=reason
m=module[+moduleInstance]
managed_object=managed_object
property=property
property_instance=property_instance
qualifier=qualifier
severity=ERR|WRN|INF|IRR|DWN|DIS|OFF
state=O|C|F
ack=A|N

Acknowledge alarms with an optional note (or reason) in an agent or a list of agents.

delAlarms

a=agent|agentList
note=reason
m=module[+moduleInstance]
managed_object=managed_object
property=property
property_instance=property_instance
qualifier=qualifier
severity=ERR|WRN|INF|IRR|DWN|DIS|OFF
state=O|C|F
ack=A|N

Delete alarms with an optional note (or reason) in an agent or a list of agents.

getAlarms

a=agent|agentList
m=module[+moduleInstance]
managed_object=managed_object
property=property
property_instance=property_instance
qualifier=qualifier
severity=ERR|WRN|INF|IRR|DWN|DIS|OFF
state=O|C|F
ack=A|N

Get alarm information of an agent or a set of agents.

runAlarmAction

a=agent|agentList

Run an alarm action manually in an agent or a list of agents.

setAlarmAction

a=agent|agentList
command=command

Set an alarm action (manual or delay) in an agent or a list of agents.

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"

Supported Parameter Lists for Topology Commands

Topology commands support the following parameter lists.

topoEntity_desc_list: specify a managed object information. It contains the following keywords:

fullDesc=text

family=text

topoType=text

topoCfg=text

isPolled=true|false

readInfo=text

writeInfo=text

targetHost=text

targetIp=text

agentPort=port

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 condition

pollType=text

arch=text

family=text

topoGroup_desc_list: specify a managed view group. It contains the following keywords:

fullDesc=text

family=text

a=agent is a reserved parameter, where agent=agentHost[:agentPort].

Topology Extended Commands

There are seven extended commands for managing the topology.

TABLE 22-7 Topology Extended Commands in the CLI
Command name
Reserved Parameters
Description

createEntity

t=topoObject topoEntity_desc_list

Create a managed entity. The topoEntity_desc_list is used to specify the entity properties. If the url or the agentPort is not specified, the default port of 161 is not used.

createGroup

t=topoObject, topoGroup_desc_list

Create a topology domain or group. If it is a domain, topoGroup_desc_list is ignored. If it is a topology group, topoGroup_desc_list must be provided.

delTopoObjects

t=topoObject

Delete a managed topology object in the managed topology hierarchy. All objects under the specified topology object are deleted as well.

getAgentPort

a=agent,t=topoObject

Return a port number that the Sun Management Center agent is running on the specified host in a topology domain. If there are multiple agents, a list of port numbers is returned. If t is not specified, the default domain is used.

getAllTopoObjects

t=topoObject, topoEntity_filter_list

Get a list of all managed objects in the managed topology hierarchy that satisfy a certain condition as specified in the entity_filter_list.

getDomains

Get information for all managed domains.

getTopoObject

t=topoObject, topoEntity_filter_list

Get managed topology objects. If the topology object is a domain or a group, it returns all group/entity objects directly under this domain or group. These objects satisfy a certain condition specified in the topoEntity_filter_list.

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

Format of CLI Output

The output of a basic command is available only in plain text. The output of an extended command is available in three formats:

Plain text
XML
HTML

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.

Plain Text

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

XML

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>

HTML

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 Log File

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

Set the log parameter to a file name. For example:


`set log=/var/opt/SUNWsymon/history.log`

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.

To stop recording, unset the log parameter. For example:


`unset log`

Internationalization and the CLI

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:

French
German
Italian
Japanese
Korean
Simplified Chinese
Spanish
Traditional Chinese

Command name	Reserved Parameters	Description
`addRow`	`a=agent[,agent]+` `m=module` `mgtObj=managed_object` `property=property` `propInst=property_instance` `rowValues="name=value[,name=value]+"`	Add a row in a table.
`delRow`	`a=agent[,agent]+` `m=module` `mgtObj=managed_object` `property=property` `propInst=property_instance` `rowValues="name=value[,name=value]+"`	Delete a row in a table.
`getAttributes`	`a=agent[,agent]+` `m=module` `mgtObj=managed_object` `property=property` `propInst=property_instance`	Get certain attributes in an agent or a list of agents.
`setAttributes`	`a=agent[,agent]+` `m=module` `mgtObj=managed_object` `property=property` `propInst=property_instance` `attributes=""` `values=""`	Set certain attributes in an agent or a list of agents.

Command name	Reserved Parameters	Description
`ackAlarms`	`a=agent\|agentList` `note=reason` `m=module[+moduleInstance]` `managed_object=managed_object` `property=property` `property_instance=property_instance` `qualifier=qualifier` `severity=ERR\|WRN\|INF\|IRR\|DWN\|DIS\|OFF` `state=O\|C\|F` `ack=A\|N`	Acknowledge alarms with an optional note (or reason) in an agent or a list of agents.
`delAlarms`	`a=agent\|agentList` `note=reason` `m=module[+moduleInstance]` `managed_object=managed_object` `property=property` `property_instance=property_instance` `qualifier=qualifier` `severity=ERR\|WRN\|INF\|IRR\|DWN\|DIS\|OFF` `state=O\|C\|F` `ack=A\|N`	Delete alarms with an optional note (or reason) in an agent or a list of agents.
`getAlarms`	`a=agent\|agentList` `m=module[+moduleInstance]` `managed_object=managed_object` `property=property` `property_instance=property_instance` `qualifier=qualifier` `severity=ERR\|WRN\|INF\|IRR\|DWN\|DIS\|OFF` `state=O\|C\|F` `ack=A\|N`	Get alarm information of an agent or a set of agents.
`runAlarmAction`	`a=agent\|agentList`	Run an alarm action manually in an agent or a list of agents.
`setAlarmAction`	`a=agent\|agentList` `command=command`	Set an alarm action (manual or delay) in an agent or a list of agents.

Command name	Reserved Parameters	Description
`createEntity`	`t=topoObject topoEntity_desc_list`	Create a managed entity. The `topoEntity_desc_list` is used to specify the entity properties. If the url or the `agentPort` is not specified, the default port of `161` is not used.
`createGroup`	`t=topoObject, topoGroup_desc_list`	Create a topology domain or group. If it is a domain, `topoGroup_desc_list` is ignored. If it is a topology group, `topoGroup_desc_list` must be provided.
`delTopoObjects`	`t=topoObject`	Delete a managed topology object in the managed topology hierarchy. All objects under the specified topology object are deleted as well.
`getAgentPort`	`a=agent,t=topoObject`	Return a port number that the Sun Management Center agent is running on the specified host in a topology domain. If there are multiple agents, a list of port numbers is returned. If `t` is not specified, the default domain is used.
`getAllTopoObjects`	`t=topoObject, topoEntity_filter_list`	Get a list of all managed objects in the managed topology hierarchy that satisfy a certain condition as specified in the `entity_filter_list`.
`getDomains`		Get information for all managed domains.
`getTopoObject`	`t=topoObject, topoEntity_filter_list`	Get managed topology objects. If the topology object is a domain or a group, it returns all group/entity objects directly under this domain or group. These objects satisfy a certain condition specified in the `topoEntity_filter_list`.