Chapter 20 Using the Command-Line Interface

The Sun Management Center command-line interface (CLI) is a lightweight, character-driven console alternative to the Java and web console graphical interfaces for monitoring and managing your system.

The following topics are discussed in this chapter:

• Overview of the Sun Management Center CLI

• CLI Parameters

• CLI Commands

• CLI Output

• CLI Procedures

Overview of the Sun Management Center CLI

The Sun Management Center command-line interface (CLI) is a character-driven console application for monitoring and managing your system. The CLI offers several useful features:

• Low overhead – Although the CLI provides most of the functionality of the Java Console and web console, the CLI does not require bitmapped graphics. The CLI therefore can run on simple data terminal equipment over low-bandwidth connections. However, features that require a GUI, such as physical views or graphing, are unavailable through the CLI.

• Batch mode processing – The CLI supports a basic scripting functionality that enables the CLI to take command input from a file in batch mode.

• Configurable output format – You can configure the format of CLI output. The plain-text output is compatible with other text-based tools. For extended commands, you can specify output in XML and HTML.

• Help – Online help for CLI commands is available from within the CLI.

You can use the CLI to perform the following tasks:

• Create topology objects such as domains, groups, and entities, and retrieve topology information about these objects.

• Retrieve and manipulate managed object properties or attributes.

• Load, unload, enable, and disable modules on Sun Management Center agents.

• Set and run alarm actions, retrieve alarm information, and acknowledge or delete alarms on Sun Management Center agents.

(On Solaris and Linux) You can automatically log in to the console using the parameters file. If the parameters file contains user name and password, the permission for that file must be 400. Otherwise, automatic login through CLI is not possible.

System Requirements

You can access the CLI from a user terminal session on one of the following system configurations:

• UNIX® workstation running the Solaris 7, Solaris 8, Solaris 9, or Solaris 10 version of the Solaris Operating System.

• UNIX workstation running Red Hat, SuSE/JDS Linux kernel version 2.4 and 2.6.

• PC running Windows 2000, Windows XP, or Windows NT

CLI Interaction Modes

The CLI supports the following two interaction modes:

• Session mode – Session mode is interactive. Once you log in to the Sun Management Center server, you can enter commands and receive output until you explicitly log out of the server.

• Batch mode – The CLI connects to the server and executes the commands contained in filename, where filename is the name of a file that contains CLI commands. CLI can be run in batch mode as a non-root user.

Configuring CLI Batch Mode

CLI batch mode can be configured by modifying the cli.properties file located at /opt/SUNWsymon/cli. This file contains nine configurable parameters.

Table 20–1 describes the configurable parameters.

CLI Command and Parameter Overview

This section provides an overview of CLI commands and parameters.

CLI Command Overview

CLI commands can be divided into two types: basic commands and extended commands.

• Basic commands are commands that modify the environment in which other CLI commands are executed. You use basic commands to set parameter values, define command aliases, check command status, or log in and log out of the server. Basic commands always execute in the foreground.

• Extended commands are commands that interrogate or modify the topology of managed objects, their properties, and their attributes. You use extended commands to perform several functions:

  • Locate managed objects in the managed object topology

  • Enable or disable modules

  • Acknowledge or delete alarms

  By default, extended commands run in the background. You can configure extended commands to run in the foreground.

In session mode, commands execute in either the foreground or the background.

• Foreground – Commands that execute in the foreground run to completion. These commands send their output directly to the screen unless otherwise redirected. Only one command at a time can run in the foreground. Basic commands can only run in the foreground. Extended commands run in the background by default, but can be configured to run in the foreground.

• Background – Commands that execute in the background run asynchronously and by default send no output or diagnostic messages to the screen. Output is buffered and can be displayed later by explicit request. Unlike the UNIX shells, only one extended command can run in the background at a time. While this command is running in the background, any number of basic commands can run in the foreground. By default, extended commands run in the background, although you can specify that extended commands run in the foreground. Basic commands cannot run in the background.

The CLI also supports aliases. You can define a shorthand term or pseudonym for a more complicated command and its parameters. User-defined aliases persist across different CLI sessions.

CLI Parameter Overview

CLI parameters are name-value pairs: each parameter has a name and a value. Some parameters are built-in to the CLI. Their names and the significance of their values are predefined within the CLI. You can define other parameters, also known as variables. Some parameters are global in scope. Global parameters affect the execution of all CLI commands that are run in a particular session. Other parameters are specific to a certain command or group of commands.

Input and Output Capabilities

The CLI provides several capabilities for input and output.

• Input

  • In session mode, the CLI accepts commands interactively from the keyboard.

  • In batch mode, the CLI executes commands that are contained in a CLI command file whose name is specified on the shell command line.

• Output

  • For basic commands, output appears on the screen by default.

  • For extended commands, output is buffered in the background by default until you request that output.

  • The output of both basic and extended commands can be redirected to a file that you specify.

  • Commands and parameters can be saved in a log file that can later be used as input to the CLI in batch mode.

    ---

    Note –

    To use a log file as input to the CLI in batch mode, you must edit the file. Remove the time stamps and any messages that appear before the actual commands and parameters in the log file.

    ---

• Format

  • You can specify the number of lines for the output display.

  • For multi-column output, you can specify which columns to display.

  • In addition to plain-text output, for some commands you can specify XML and HTML output.

CLI Command Help

The CLI provides online help for each CLI command. CLI help is available from within the CLI. CLI help does not require a GUI. For each command, the help provides a synopsis of command usage and a list of the parameters associated with that command.

CLI Parameters

Most CLI parameters are name-value pairs: each parameter has a name and a value. A few parameters have names but no values. These parameters are known as flags.

Scope of Parameters

You can specify parameter values at several points in a CLI session:

• CLI startup – You can specify parameters at the command line when you start the CLI. Parameters that are specified at startup are global to the session. Global parameters retain their values unless overridden with the set command or removed from the current session with the unset command.

• CLI commands – You can specify parameters for individual CLI commands executed during a session. A value specified as part of a command temporarily overrides the value of a global parameter for the duration of that command.

• Input file – Parameter definitions can be stored in an external file and can be invoked at any time in a CLI session. Parameter values that are defined in an external file are overridden by global parameters and by individual command parameters.

Parameter Syntax

Parameters are specified as name=value pairs:

file=/home/examples/example1

where the parameter name is file and the parameter value is /home/examples/example1. There must be no whitespace between the equals sign (=) and the parameter name or parameter value. If the value contains whitespace such as a space or tab character, the value must be enclosed in double-quote characters (ASCII character 0x22):

moduleDesc="Local File Scanning"

Parameter values can be a list of comma-separated values. There must be no whitespace between the comma-separated values, as shown in the following example.

severity=DIS,DWN,ERR

A parameter list is a sequence of parameters separated by whitespace, as shown in the following example.

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

Examples of Acceptable and Unacceptable Parameter Syntax

The following parameters have acceptable syntax:

ok1="This is just a test"
ok2=hello
ok3=hello,hi,aloha
ok4="hello,hi,aloha"

The following parameters do not have acceptable syntax:

broken1="How are you?","Who are you?"
broken2="Testing",1,2,3
broken3="Hello
broken4=Hello"

Parameter Input File Format

Parameters can be stored in a file and read when needed. You can create as many parameter files as needed. Use the built-in i parameter to specify the name of the desired parameter input file.

Predefined Parameters and Flags

This section describes parameters that have predefined meanings within the CLI.

Several predefined parameters have single-letter names. Some examples include such as a, f, and o.

-b

When included at the command line when the CLI is started, this flag instructs the CLI to run in batch mode. This flag is ignored in session mode.

-h

When this flag is used as a parameter to a command in session mode, it instructs the CLI to display the help text for the command.

-l

When this flag is used as a parameter to an extended command in session mode, it instructs the CLI to retain the parameters from the last extended command while executing the current command. If the -l flag is specified, any additional parameters specified for the current command are ignored. This flag has no effect on basic commands. The following example illustrates usage of the -l flag:

> getLoadModules a=myHostName ... ... > getAlarms -l

When the getAlarms command is executed, the command uses the value of parameter a (myHostName) from the previously executed getLoadModules command.

a

The value of the a parameter is an agent, which is specified as the agent host and (optional) port number. If you specify the port number, separate the number from the host name by a colon (:). The general syntax is a=agentHost[:agentPort]. For example, to specify an agent running on host example_host and listening to port 12345, you would use the following syntax:

a=example_host:12345

The value of the a parameter can also be a comma-separated list of agent specifications: a=agent[,agent]*.

about

The about parameter is used with the help command. This parameter displays the version information for CLI.

append

The value of the append parameter is the name of a file to which the output of a command should be appended. If this file does not exist, the file is created. If you set the append parameter globally, all command output for that session is appended to the specified file. You can also set this parameter for a specific command, as shown in the following example.

append=/home/examples/cli_output

If both the append and o parameters are set, append takes precedence over o. Only command results are recorded in the specified file. The actual command is not recorded. Use the log parameter to record command information.

columns

The value of the columns parameter is the name of one or more columns of command output to be displayed by the print command. Column names are case sensitive. Multiple column names are separated by commas. The following example uses several column names.

columns="Alarm Id,Node URL,Target Host,Severity"

f

The value of the f parameter determines the format of command output. The current formats are plain and html. See Command Output Format for more information. To set the format to HTML, use the following syntax:

f=html

height

The value of the height parameter is the number of lines of command output to display on the screen. The following example sets the height to approximately the height of a standard terminal screen:

height=24

history

The value of the history parameter is the number of commands to be stored in the command history. The command history allows the user to view the previously executed commands. This parameter is used by the set command.

history=10

i

The value of the i parameter is the name of an input file that contains parameter definitions to be included in the current session. Within the input file, each parameter definition should be on a separate line. For example, assume that the following lines are in a /home/examples/myParams file:

more=off serverHost=myserver a=myagent:161

You could include these parameters in the current CLI session by using the following line:

i=/home/examples/myParams

log

The value of the log parameter is the name of a file that records all CLI commands and the time that the commands were executed. Note that the log file records only command names and time of execution. Command output is logged in files specified by the a or o parameters. Once the parameter is set, all subsequent commands are appended to the file. If this file does not exist, the file is created. Because the log file is not overwritten when logging is turned on, specify a different file if you want a different log. To turn logging off, use the unset command with the log parameter. The following example starts a log, then later stops the log.

> log=/home/examples/sunmc-log ... ... > unset log

logmode

The value of the logmode parameter can be detailed, command, or from n. The value of detailed stores detailed information of commands in the command log file. The value of command stores only the commands and the respective parameters in the command log file. The value of from n appends all the entries (starting from the n^th entry) in the command history to the command log file. The default value of the logmode parameter is detailed.

m

The value of the m parameter is the name of a Sun Management Center module. The value can also be a comma-separated list of modules.

m=kernel-reader

more

The value of the more parameter controls paging of command output on your display. Possible values are on and off. If more is set to on, all subsequent output to the terminal is displayed one screen at a time. The size of a screen is defined by the height and width parameters. Default values are off for batch mode and on for session mode.

more=on

ncols

The value of the ncols parameter is the maximum number of columns of command output to be displayed by the print command.

o

The value of the o parameter is the name of a file to which command output should be written. If this file exists, the file is overwritten. You can use the o parameter to capture the output of a particular command by specifying the o parameter to that command. You can also set the parameter globally using the set command to write all subsequent output to a file.

If both the append and o parameters are set, append takes precedence over o. Output is appended to the specified file. Only command output is written to the file. The actual command is not recorded. Use the log parameter to record command information. The following example defines a file into which command output is written.

o=/home/examples/sunmc-output

prompt

The value of the prompt parameter is used to set a different CLI prompt.

serverPort

The value of the serverPort parameter is the server port for login. This global parameter cannot be set after a login session is established. If this parameter is not set, the default port of 2099 is used.

style

The value of the style parameter determines the style of command output. The allowed values of this parameter are table, list, and <custom>. The table value displays the output in a tabular format. The list value displays the output in a list with the columns separated by a comma. The <custom> value ensures that the output is displayed in a user-defined format. Each column is represented by %a. The custom value can contain special characters such as :, \t, and \n.

t

The value of the t parameter is the name of an object that is managed in the topology agent. The object can be a domain, a view group, or an entity. The object name is the fully qualified name at the domain level, for example, /domain/group/host.

CLI Commands

See CLI Command and Parameter Overview for an overview of command types and concepts. For details about the parameters used by the basic CLI commands, refer to Predefined Parameters and Flags.

Basic CLI Commands

The following list describes the basic CLI commands.

alias

Description

The alias command creates an alias for frequently used commands or for commands that have complicated parameters. An alias cannot have the same name as an existing CLI command. Whitespace in an alias definition must be enclosed in double-quotes (", ASCII character 0x22).

When the user quits a CLI session, the aliases that the user has specified are stored in a file in the aliases directory. These aliases will be available when the user logs in to the CLI session.

Syntax

alias [<pseudonym>="command [parameters]"]

Examples

> alias assign=set > alias alarms="getAlarms severity=dwn"

If called without arguments, the alias command prints a list of defined aliases and their values. The following example shows the result of the alias command when the command is called without arguments.

> alias assign - set alarms - getAlarms severity=dwn

attrib

Description

The attrib command retrieves the attributes of a topological object.

Syntax

attrib [group=groupName [name=attribName] [-key]]

browse

Description

The browse command activates the browsing mode of the topology.

Syntax

browse

cd

Description

The cd command changes the current topological path. If no path is specified, the current path will be set to the default domain. If a number (n) is specified, the current path will be set to the n^th child path, as shown by the list command.

Syntax

cd [path|number]

clear

Description

The clear command removes all parameters that were set during the current session. However, this command will not remove parameters that were set from the command line. This command is similar to the unset command but does not require parameter names as arguments.

Syntax

clear

data

Description

The data command shows the details of a topological object. If a number (n) is specified, the path will be set to the n^th child path, as shown by the list command.

Syntax

data [path|number|-key]

end

Description

The end command deactivates the browsing mode of the topology.

Syntax

end

exit

Description

The exit command terminates your server connection and the CLI session.

Syntax

exit [-onError]

Parameter

onError

The onError parameter is used to terminate the CLI session if an exception occurs in the execution of the previous command. This parameter is used only in batch mode.

---

Note –

The exit command and the quit command are identical.

---

goto

Description

The goto command navigates to a topological path that matches the case-sensitive pattern. If more than one matching path is found, the user is asked to choose a path.

Syntax

goto <pattern>

help

Description

The help command displays information about CLI commands and their parameters. The help information is suitable for displaying on a terminal screen that is not bitmapped. When help is executed without an argument, the help displays an alphabetical list and a brief description of available CLI commands. Basic commands are listed first, followed by extended commands.

Syntax

help [-e][-h] [<command>|about|legal]

Parameters

-e, -h, command, about, and legal

-e displays the help text in extensive mode. The following format is also supported: <command> -e.

-h displays the help text in normal mode. The following format is also supported: <command> -h.

command displays information specific to that command.

about displays the version information about CLI.

legal displays the licensing terms of the CLI.

Example

The following example shows help for the getAlarms command.

> help getAlarms getAlarms [a=host[,host]+] [alarm_filter_list] - Get alarm information on an agent or a list of agents under a set of filter conditions. If no agent is provided, all alarms will be obtained. All the filter conditions are "ANDED" to provide the result. The filter conditions as specified in alarm_filter_list comprises: domain=domain and/or m=module[+instance] and/or managed_object=managed_object and/or property=property and/or property_instance=property_instance and/or qualifier=qualifier and/or severity=[DIS,DWN,ERR,OFF,INF,IRR,WRN] and/or state=[C,F,O] and/or ack=[A,N]

history

Description

The history command lists or executes the previously entered commands in the CLI session. When the history command is called without any argument and history was set earlier, all the previously entered commands will be listed. When the history command is called with a numerical argument and history was set earlier, the command that matches this argument will be executed.

Syntax

history [num]

kill

Description

The kill command terminates any commands that are running in the background.

Syntax

kill

list

Description

The list command lists the objects under a path. If a number (n) is specified, the path will be set to the n^th child path as shown by this command.

Syntax

list [path|number]

locate

Description

The locate command finds all the topological paths that match the specified pattern. The pattern is case sensitive.

Syntax

locate <pattern>

login

Description

The login command establishes a connection to a Sun Management Center server. You can specify the serverHost and, optionally, serverPort parameters as arguments. If no host is specified, you are prompted for a host. If no port is specified, 2099 is used. The login command also prompts you for your user name and password.

Syntax

login [serverHost=host] [serverPort=portNumber] [user=userName] [password=userPassword]

Parameters

serverHost, serverPort, user, and password

logout

Description

The logout command terminates your connection to the Sun Management Center server, but does not terminate the CLI session.

Syntax

logout

print

Description

The print command directs the output of the last extended command in the specified format to the specified destination. By default, print directs this output to the terminal screen in plain text format. If the parameters append or o are set, the output is directed to the file that is specified by those parameters. The output is not shown on the screen. if ncols is not specified, the default number of columns is set to 4.

---

Note –

The print command is not saved in the command history.

---

Syntax

print [f=plain|xml|html] [style=table|list|<custom>] [columns= columnList] [ncols=num] [o=outputFile | append=appendFile]

Parameters

f, style, columns, ncols, o, and append

quit

Description

The quit command disconnects from the server and terminates the CLI session.

---

Note –

There is no difference between the quit and the exit commands.

---

Syntax

quit

reset

Description

The reset command restores the values of all parameters that are specified at the command line to the values that were specified at the beginning of the CLI session. Parameters that were defined during the session but not at the command line remain unchanged. If a specific parameter name is supplied as an argument to reset and the parameter was specified at the command line, that parameter's value is restored to its original value. Otherwise, the parameter's value remains unchanged.

---

Note –

The reset command is not saved in the command history.

---

Syntax

reset [<parameter>]*

set

Description

The set command enables you to specify parameter values or to display parameter values. Parameters whose values are specified with the set command are global to the current session. Global commands are available to all commands during that session. If you execute set with no arguments , the value of all parameters that are defined during the current session are displayed. If you execute set with a parameter that is specified as an argument, the value of that parameter is displayed.

Syntax

set [<parameter>[=value]]* [height=num] [history=num] [log=file] [logmode=detailed|command|"from n"] [more=on|off] [prompt=prompt]

Example

The following example shows all three variations of this command.

> set height=10 > set height=10 > set height height=10

status

Description

The status command displays the status of any commands that are running in the background.

Syntax

status

unalias

Description

The unalias command removes the alias or a list of aliases that was specified as an argument.

Syntax

unalias [<pseudonym>]*

unset

Description

The unset command removes the specified parameter(s) from the current session.

Syntax

unset [<parameter>]*

---

Note –

The unset command is not saved in the command history.

---

where

Description

The where command displays the current topological path.

Syntax

where

Extended CLI Commands

Several types of extended commands that are available in the CLI are described in these sections:

• Module Extended Commands

• Object Attribute Extended Commands

• Alarm Extended Commands

• Topology Extended Commands

• Topology import and export commands in Import and Export CLI Interface

Module Extended Commands

Seven extended commands are available for managing modules.

Parameters for the Module Command

The following parameters can be used by the module commands. For details about the a and m parameters, refer to Predefined Parameters and Flags.

moduleName

The internationalized name of the module

moduleDesc

The text description of the module

moduleParams

The comma-separated list of module parameters

-default

The default settings of the module

Module Commands

disableModule

Description

The disableModule command disables a module or modules in an agent or agents.

Syntax

disableModule a=host[:port][,host[:port]]* m=module[+instance][,module[+instance]]*

Parameters

a and m

enableModule

Description

The enableModule command enables a module or modules in an agent or agents.

Syntax

enableModule a=host[:port][,host[:port]]* m=module[+instance][,module[+instance]]*

Parameters

a and m

getLoadedModules

Description

The getLoadedModules command obtains a list of loaded modules in an agent or agents.

Syntax

getLoadedModules a=host[:port][,host[:port]]*

Parameter

a

getModule

Description

The getModule command obtains information for a particular module in an agent or agents.

Syntax

getModule a=host[:port][,host[:port]]* m=module[+instance]

Parameters

a and m

getModules

Description

The getModules command obtains a list of all available modules in an agent or agents.

Syntax

getModules a=host[:port][,host[:port]]*

Parameter

a

loadModule

Description

The loadModule command loads a module in an agent or agents.

Syntax

loadModule a=host[:port][,host[:port]]* m=module[+instance] [moduleName= name] [moduleDesc=description] [moduleParams= key=value[,key=value]*] [-default]

Parameters

a, m, moduleName, moduleDesc, moduleParams, and -default.

unloadModule

Description

The unloadModule command unloads one or more modules in an agent or agents.

Syntax

unloadModule a=host[:port][,host[:port]]* m=module[+instance][,module[+instance]]*

Parameters

a and m

Module Command Examples

To determine which modules are loaded on a host whose agentHost name is seattle, you would type the following command at the CLI prompt:

> getLoadedModules a=seattle

To load the kernel-reader module on the host seattle at port 1776, you would type the following command:

> loadModule a=seattle:1776 m=kernel-reader

Object Attribute Extended Commands

There are four extended commands for managing object attributes and attribute values.

Parameters for the Object Attribute Command

The following parameters can be used by the object attribute commands. For details about the a and m parameters, refer to Predefined Parameters and Flags.

mgtObj

The value of the mgtObj parameter is the name of the managed object whose attributes and properties are being set or retrieved.

property

The value of the property parameter is the name of the property whose attributes and values are being set or retrieved.

propInst

The value of the propInst parameter is the name of the instance of the property whose attributes and values are being set or retrieved.

rowValues

The value of the rowValues parameter is a comma-separated list of name-value pairs. name is the name of a column in the row. value is the value in that column.

attribute

The value of the attribute parameter is a comma-separated list of attribute names that belong to the property whose attributes and values are being set or retrieved. When used with the setAttributes command, each attribute name in the attribute parameter must have a corresponding value in the value parameter.

value

The value of the value parameter is a comma-separated list of values that correspond to the attributes that are specified in the attribute parameter. When used with the setAttributes command, there must be a value for each attribute specified.

Object Attribute Commands

You can set and retrieve object attributes and attribute values with the following commands:

addRow

Description

The addRow command adds a row with the specified values to a table.

Syntax

addRow a=host[:port][,host[:port]]* m=module[+instance] mgtObj=managedObject [property=property] [propInst=propertyInstance] rowValues=name=value[,name=value]

Parameters

a, m, mgtObj, property, propInst, and rowValues.

delRow

Description

The delRow command deletes a row with the specified values from a table.

Syntax

delRow a=host[:port][,host[:port]]* m=module[+instance] mgtObj=managedObject [property=property] [propInst=propertyInstance] rowValues=name=value[,name=value]

Parameters

a, m, mgtObj, property, propInst, and rowValues.

getAttributes

Description

The getAttributes command retrieves the information for a property or retrieves specified attributes from an agent or a list of agents.

Syntax

getAttributes a=host[:port][,host[:port]]* m=module[+instance] mgtObj=managedObject property=property [propInst=propertyInstance] [attribute=attribute[,attribute]*]

Parameters

a, m, mgtObj, property, propInst, and attribute.

setAttributes

Description

The setAttributes command sets a property or sets values to the specified attributes in an agent or a list of agents. You can also reset the value of a specified attribute to null.

Syntax

setAttributes a=host[:port][,host[:port]]* m=module[+instance] mgtObj=managedObject property=property [propInst=propertyInstance] [attribute=attribute[,attribute]*] value=value[,value]*

Parameters

a, m, mgtObj, property, propInst, attribute, and value.

For each attribute specified in the attribute parameter, there must be a corresponding value in the value parameter.

Examples for the Object Attribute Command

The following command retrieves all attributes for the size property in the totalstats managed object in the agent-stats module at port 1161 on host haiku:

> getAttributes a=haiku:1161 m=agent-stats mgtObj=totalstats \
property=size

The following command sets the attribute alarmlimits.error-gt to the value of 2 in the size property specified in the previous example:

> setAttributes a=haiku:1161 m=agent-stats mgtObj=totalstats \
property=size attribute=alarmlimits.error-gt value=2

The following command deletes the row that is specified in rowValues from the managed object that is specified in mgtObj:

> delRow a=haiku:1161 \
m=filemon mgtObj=filemonstats/filemonTable/filemonEntry \
rowValues="name=test,desc=this,filename=/etc/passwd"

Alarm Extended Commands

There are five extended commands for managing alarms.

Alarm Command Parameters

The following parameters can be used by the extended commands for alarms. For details about the a and m parameters, refer to Predefined Parameters and Flags.

ack

The value of the ack parameter is a comma-separated list of values that indicate whether the alarms being managed have been acknowledged. Legal values for the ack parameter are ACK (Acknowledged) and NOACK (Not Acknowledged).

command

The value of the command parameter is the alarm action to be performed.

domain

The value of the domain parameter is the name of the Sun Management Center domain for which alarms are to be managed. If no domain is specified, the Default Domain is used.

mgtObj

The value of the mgtObj parameter is the name of the managed object for which alarms are to be managed.

note

The value of the note parameter is a text annotation for the command being run.

property

The value of the property parameter is the name of the property for which alarms are to be managed.

propInst

The value of the propInst parameter is the name of the specific property instance for which alarms are to be managed.

qualifier

The value of the qualifier parameter is the name of the qualifier that is associated with the managed property whose alarms are to be managed.

severity

The value of the severity parameter is a comma-separated list of severity values for the alarms being managed. The following values are allowed for the severity parameter:

• ERR — Error

• WRN — Warning

• INF — Informative

• IRR — Irrational

• DWN — Down

• DIS — Disabled

• OFF — Off

state

The value of the state parameter is a comma-separated list of state values for the alarms being managed. Legal values for the state parameter are Open, Closed, and Fixed.

Alarm Commands

You can examine alarm values and set alarm actions with the following commands:

ackAlarms

Description

The ackAlarms command acknowledges alarms in an agent or a list of agents.

Syntax

ackAlarms a=host[:port][,host[:port]]* [domain=domain] [m=module[+instance][mgtObj=managedObject [property=property [propInst=propertyInstance] [qualifier=qualifier]]]] [severity=DIS|DWN|ERR|INF|IRR|OFF|WRN] [state=OPEN|CLOSED|FIXED] [note=reason]

Parameters

a, domain, m, mgtObj, property, propInst, qualifier, severity, state, and note.

If no value is specified for the state parameter, state defaults to Open.

delAlarms

Description

The delAlarms command deletes alarms in an agent or a list of agents.

Syntax

delAlarms a=host[:port][,host[:port]]* [domain=domain] [m=module[+instance][mgtObj=managedObject [property=property [propInst=propertyInstance] [qualifier=qualifier]]]] [severity=DIS|DWN|ERR|INF|IRR|OFF|WRN] [state=OPEN|CLOSED|FIXED] [ack=ACK|NOACK] [note=reason]

Parameters

a, domain, m, mgtObj, property, propInst, qualifier, severity, state, ack, and note.

If no value is specified for the state parameter, state defaults to Closed.

getAlarms

Description

The getAlarms command retrieves alarm information for an agent or a set of agents.

Syntax

getAlarms a=host[:port][,host[:port]]* [domain=domain] [m=module[+instance][mgtObj=managedObject [property=property [propInst=propertyInstance] [qualifier=qualifier]]]] [severity=DIS|DWN|ERR|INF|IRR|OFF|WRN] [state=OPEN|CLOSED|FIXED] [ack=ACK|NOACK]

Parameters

a, domain, m, mgtObj, property, propInst, qualifier, severity, state, and ack.

If no parameters are specified, getAlarms returns all alarm information.

runAlarmAction

Description

The runAlarmAction command runs a manual or delayed alarm action for all alarms under a domain of an agent or a list of agents.

Syntax

runAlarmAction a=host[:port][,host[:port]]* [domain=domain] [m=module[+instance][mgtObj=managedObject [property=property [propInst=propertyInstance] [qualifier=qualifier]]]] [severity=DIS|DWN|ERR|INF|IRR|OFF|WRN] [state=OPEN|CLOSED|FIXED] [ack=ACK|NOACK]

Parameters

a, domain, m, mgtObj, property, propInst, qualifier, severity, state, and ack.

setAlarmAction

Description

The setAlarmAction command sets a manual or delayed alarm action for all alarms under a domain of an agent or a list of agents.

Syntax

setAlarmAction a=host[:port][,host[:port]]* command=command [domain=domain] [m=module[+instance][mgtObj=managedObject [property=property [propInst=propertyInstance] [qualifier=qualifier]]]] [severity=DIS|DWN|ERR|INF|IRR|OFF|WRN] [state=OPEN|CLOSED|FIXED] [ack=ACK|NOACK]

To set up email alerts for an alarm, the command format can either be

command="email.sh:<email-id>:<message>" or

command="email:<email-id>:<message>"

Parameters

a, command, domain, m, mgtObj, property, propInst, qualifier, severity, state, and ack.

Alarm Command Examples

The following command retrieves all alarms with severity of ERR or DWN from the host haiku:

> getAlarms a=haiku severity=ERR,DWN

Topology Extended Commands

There are nine extended commands for managing topology.

Topology Command Parameters

The following parameters can be used by the extended commands for topology. For details about the a and t parameters, refer to Predefined Parameters and Flags.

agentPort

The value of the agentPort parameter is the agent port number. If agentPort is not specified, the default value of 161 is used. The agentPort parameter is optional. This parameter is only specified if the url parameter is not specified and if you do not want the default port.

arch

The value of the arch parameter is the architecture of the topology object.

domain

The value of the domain parameter is the name of the Sun Management Center domain that you must specify for the setCurrentDomain command.

domainmode

The value of the domainmode parameter can be follow or ignore. If the value is follow, the import command imports both the group and domain information from the file to the specified target domain. If the value is ignore, the import command ignores the domain information.

family

The value of the family parameter is the object family of the topology object. If this is not specified, this will be automatically obtained.

filename

The value of the filename parameter is the name of the file. This parameter is used by export and import commands to export and import topology data.

fullDesc

The value of the fullDesc parameter is a text description of the entity or group being created.

isPolled

The value of the isPolled parameter can be true or false. If the value is true, the entity polls for status information according to the polling type (pollType). The default value is true.

mode

The value of the mode parameter can be append or overwrite. If the value is append, the export command adds the topology data to the end of the file. If the value is overwrite, the export command overwrites the file with the topology data.

nodemode

The value of the nodemode parameter can be replace or ignore. If there is a mismatch of data in the file and in the domain, the replace value replaces the data in the domain with data in the file. The ignore value ignores any mismatch of data.

pollType

The value of the pollType parameter is the type of polling for this entity. The following values are allowed for the pollType parameter:

• agroup – Identifies a group on which an active agent is installed and running

• ahost – Identifies a host on which an active agent is installed and running

• amod – Identifies a module that has an active agent

• aprox – Identifies an agent that is running an SNMP proxy module

• dummy – Identifies a device that is not monitored

• ping – Identifies a host to be monitored using the ICMP ping command

• snmp – Identifies a host to be monitored using the SNMP ping command

readInfo

The value of the readInfo parameter is the name of the SNMPv1 read community for SNMP polled objects.

targetHost

The value of the targetHost parameter is the name of the target host.

targetIp

The value of the targetIP parameter is the IP address of the target host.

topoCfg

The value of the topoCfg parameter is configuration information for the topological representation of a managed entity.

topoType

The value of the topoType parameter is the topological representation type of a managed entity.

url

The value of the url parameter is the URL of the entity to be polled. The value of the url parameter can be specified in the following formats:

ping://hostname
snmp://hostname:port/oid/#.#.#.#
snmp://hostname:port/[mod,sym]/path

validity

The value of the validity parameter is the duration (in days) you want the exported topology data to be valid. The value of the validity parameter can be Unlimited, 7, 15, 30, or 90.

writeInfo

The value of the writeInfo parameter is the name of the SNMPv1 write community for SNMP polled objects.

Topology Commands

There are nine extended commands for managing topology.

createEntity

Description

The createEntity command creates a managed entity.

Syntax

createEntity t=topoObject pollType=ahost|amod|aprox|dummy|ping|snmp [fullDesc=text] [targetHost=host] [agentPort=port] [targetIp=ip] [family=family] [isPolled=true|false] [topoType=text] [topoCfg=text] [readInfo=text] [writeInfo=text] [url=url]

Parameters

t, pollType, fullDesc, targetHost, agentPort, targetIp, family, isPolled, topoType, topoCfg, readInfo, writeInfo, and url.

If the url or agentPort parameters are specified, the default port of 161 is not used.

createGroup

Description

The createGroup command creates a topology domain or group.

Syntax

createGroup t=topoObject [family=base|building-view|campus-view|network-view|subnetwork-view] [fullDesc=desc]

Parameters

t, family, and fullDesc.

If the entity being created is a group, the family parameter is mandatory.

If the entity being created is a domain, the family and fullDesc parameters are ignored.

delTopoObject

Description

The delTopoObject command deletes a managed topology object in the managed topology hierarchy. All objects under the specified topology object are deleted as well.

Syntax

delTopoObject t=topoObject

Parameter

t

export

Description

The export command exports topology data in a domain or domains to a file.

Syntax

export filename=filename domain=domain|"All Domains" mode=append|overwrite validity=Unlimited|7|15|30|90 [comment=text]

Parameters

filename, domain, mode, validity, and comment.

getAgentPort

Description

The getAgentPort command returns a port number of the Sun Management Center agent running on the specified host in a topology domain. If there are multiple agents, a list of port numbers is returned.

Syntax

getAgentPort a=host[,host]* [t=topoObject]

Parameters

a and t.

If the t parameter is not specified, the default domain is used.

getAllTopoObjects

Description

The getAllTopoObjects command returns a list of all managed objects in the managed topology hierarchy that satisfy conditions specified by the arch, family, or pollType parameters.

Syntax

getAllTopoObjects t=topoObject [arch=os] [family=platform] [pollType=aview|ahost|amod|aprox|dummy|ping|snmp]

Parameters

t, arch, family, and pollType.

getCurrentDomain

Description

The getCurrentDomain command returns the name of the current domain.

Syntax

getCurrentDomain

Parameters

None

getDomains

Description

The getDomains command returns a list of all managed domains in the current server context.

Syntax

getDomains

Parameters

None

getTopoObject

Description

The getTopoObject command returns a list of managed topology objects directly under the topology object specified by parameter t that satisfy conditions specified by the arch, family, or pollType parameters.

Syntax

getTopoObject t=topoObject [arch=os] [family=platform] [pollType=aview|ahost|amod|aprox|dummy|ping|snmp]

Parameters

t, arch, family, and pollType.

import

Description

The export command imports topology data from a file to a domain.

Syntax

import filename=filename domainmode=follow|ignore nodemode=replace|ignore [domain=domain]

Parameters

filename, domainmode, nodemode, and domain.

setCurrentDomain

Description

The setCurrentDomain command sets the home domain to the value specified in the domain parameter.

Syntax

setCurrentDomain domain=domainName

Parameter

domain

Topology Command Examples

The following command returns a list of all Sun Management Center agent hosts on the sun4u family in group building12 in the menlo_park domain that are running SunOS 5.7 software:

> getTopoObject t=/menlo_park/building12 pollType=ahost \
arch="SunOS 5.7" family=sun4u

The following command creates a group that is named building19 under an existing domain that is named headquarters_test:

> createGroup t=/headquarters_test/building19 \
fullDesc="test headquarters domain" family=building-location

The following command creates a managed entity that is named myHost in the group building12 in the domain test_domain. The topology object is a host with the agent running in port 1161.

> createEntity t=/test_domain/building12/myHost \
fullDesc="my test host" family=ultra-2 topoType="" \
topoCfg="" isPolled=false pollType=ahost readInfo="" \
writeInfo="" targetHost=osftserv targetIp="" agentPort=1161

CLI Output

The CLI provides the following output options:

• Log command execution to a file

• Log command output to a file

• Control appearance of command output on the screen

• Specify output as plain text, XML, or HTML

All commands and log files are available only in English. However, command descriptions and help text follow the Java internationalization guidelines for languages other than English.

Command Output Format

The output of basic commands is available only in plain text. Refer to CLI Command and Parameter Overview for an explanation of basic and extended commands.

The output of extended commands is available in three formats:

• Plain text

• XML

• HTML

To specify the output format, set the f parameter to the value of the desired format. Currently supported values are plain, xml, and html.

You can define a logical screen size for command output by setting the height parameter to a desired value. You can set the more parameter to display output one screen at a time. See Predefined Parameters and Flags for an explanation of these parameters.

Example 20–1 Plain Text Command Output

The following example shows the partial output of the getLoadedModules command in plain text.

== getLoadedModules: Results 1/16 ===============================
Module Name=Dynamic Reconfiguration
Module Key=dr
Description=Dynamic Reconfiguration (Sunfire)
Agent Name=myhost-dev86
Agent Port=161
Version=2.0
== getLoadedModules: Results 2/16 ===============================
Module Name=Config-Reader(sun4u/sun4d)
Module Key=Config-Reader4u
Description=Config Reader (sun4u/sun4d)
Agent Name=myhost-dev86
Agent Port=161
Version=1.0
...
== getLoadedModules: Results 15/16 ==============================
Module Name=DNS Synthetic Transaction [dns]
Module Key=dnsST+dnstest
Description=DNS Synthetic Transaction
Agent Name=myhost-dev86
Agent Port=161
Version=1.0
================================================================

CLI Log File

To record CLI commands in a log file, set the log parameter to the name of the file in which to record the commands. To pass the log file to CLI in batch mode for execution, set the logmode parameter to detailed, command, or from n. For more details, see log and logmore in Predefined Parameters and Flags.

The log file has the following format:

DATE & TIME;duration or message;command and parameters

Example 20–2 Partial CLI Log File

The following example is an excerpt of the log of the command sequence from which the previous getLoadedModules command output was obtained.

Fri Dec 21 14:15:12 PST 2001;0 second;set o=\
/home/examples/output.3c23b455
Fri Dec 21 14:15:23 PST 2001;0 second;set f=plain
Fri Dec 21 14:15:45 PST 2001;0 second;set a=smtg-dev21
Fri Dec 21 14:16:08 PST 2001;== START OF THREAD ==;getLoadedModules
Fri Dec 21 14:16:08 PST 2001;2 seconds;getLoadedModules
Fri Dec 21 14:16:12 PST 2001;9 seconds;print
Fri Dec 21 14:21:28 PST 2001;== START OF THREAD ==;getAgentPort
Fri Dec 21 14:21:28 PST 2001;0 second;getAgentPort
Fri Dec 21 14:21:31 PST 2001;0 second;print
Fri Dec 21 14:22:01 PST 2001;0 second;exit

Accessing the CLI

es-cli

Description

The es-cli command is used to access the CLI.

Syntax

es-cli [-h] [-b <filename> -i <parameter-filename>] [-i <parameter-filename>]

For an explanation of the parameters to es-cli, see CLI Parameters.

---

Note –

If no option is specified, the CLI runs in session mode.

---

CLI Procedures

This section describes some common CLI procedures.

To Access the CLI in the Solaris or Linux Operating Environment

Before You Begin

If the console is not installed in the default /opt directory, the CLI application will not start. In this case, start the CLI application by either of the following ways:

• After installation, change the location of the add-ons in the cli.properties file to correctly point to the installed location.

• Create the /opt/SUNWsymon/cli/addons directory.

1. To begin an interactive session, type the command /opt/SUNWsymon/sbin/es-cli followed by any desired global parameters.

2. Type login in response to the CLI prompt (>).

3. Type the name of the host to which you wish to connect in response to the Host prompt.

4. Type your login name and password in response to the Login and Password prompts.

   The result of steps 1-4 resembles the following example:

   /opt/SUNWsymon/sbin/es-cli parameters > login Host: myhost Login: mylogin Password: mypassword Login is successful. >

   ---

   Tip –

   You can run the CLI in batch mode using a previously prepared file of CLI commands as input by using the following command: /opt/SUNWsymon/sbin/es-cli -b file.

   ---

To Access the CLI in Microsoft Windows Environments

1. After you have installed the Sun Management Center console layer, double-click es-cli in the CLI folder.

   The CLI screen is displayed.

2. Type the login command.

   The login process prompts you to specify the desired host name and your login name.

   In the following example, seattle is the host, and susan is the login name:

   > login Host: seattle Login: susan Password: >

To Access CLI Online Help

1. To obtain a list of all available CLI commands, type help at the CLI prompt.

2. To obtain a more detailed explanation of a particular command, type help followed by the name of the command.

   For example, to obtain additional help about the getLoadedModules command, you would type:

   > help getLoadedModules

To Control Command Output Screen Size

1. Define a screen size by setting the height parameter to the number of lines to display.

   For example, to define a screen 20 lines high, you would type:

   > set height=20

2. To enable output to be viewed one page at a time, set the more parameter to on.

   > set more=on

To Record CLI Commands in a Log File

1. Set the log parameter to the name of the file in which to record the commands.

   > set log=/home/examples/log.3c254030

   Once the log parameter is set, all subsequent commands are appended to the file. If this file does not exist, the file is created.

   The file is not overwritten, so make sure a new file is created if you want a new set of records.

2. To stop recording, use the unset command with the log parameter.

   > unset log

To Record Command Output in a File

To record command output in a file, set the o parameter to the name of the output file.

> set o=/home/examples/output.3c254030

To stop recording, use the unset command with the o parameter.

> unset o

To Terminate a CLI Session

To terminate a CLI session, type exit.

> exit