Overview

C H A P T E R 1

Overview

This chapter introduces the Sun StorEdge™ Command-Line Interface (Sun StorEdge CLI) and includes the following topics:

Supported Communication Modes

Accessing the Sun StorEdge CLI

Accessing the Man Page and Help

Interactive Command Mode

Single-Command Mode

Command Keywords

Device Names for Inband Communication

Device Names for Out-of-Band Communication

Disk Device Syntax

Logical Drive Syntax

Logical Volume Syntax

Device Capacity

Supported Communication Modes

The Sun StorEdge CLI provides the capability to monitor and configure Sun StorEdge 3000 family arrays from an operating system command-line interface using inband or out-of-band interfaces.

Note - All methods that involve accessing a local device require superuser privileges. Only when an IP address is specified on the command line can the user invoke the Sun StorEdge CLI without being root.

The management mode is determined based on the following:

If a host name or IP address is specified on the command line, it is used. This is out-of-band mode. For more details, see Device Names for Out-of-Band Communication.

If a local Fibre Channel (FC) or SCSI device is specified on the command line, it is used. This is inband mode. For more details, see Device Names for Inband Communication.

When no address or device is specified, a search of local devices is done. If only one device is found, it is automatically selected. If more then one device is found, a list of devices to select from is displayed. This is inband mode. For more details, see Device Names for Inband Communication.

If the user selects a local device and specifies the --oob option, the Sun StorEdge CLI retrieves the network address of the device using inband methods. However, from that point forward, out-of-band access is used.

Note - If the array’s IP address cannot be found, the --oob option does not switch to out-of-band mode. This prevents scripts from failing when the array’s IP address is not set.

Accessing the Sun StorEdge CLI

The Sun StorEdge CLI must be installed on the server attached to the array that you want to access. For instructions about installing the Sun StorEdge CLI, refer to the Sun StorEdge 3000 Family Software Installation Guide.

Note - If the same array is connected to multiple servers, it is possible to have the Sun StorEdge CLI running on each of these servers trying to manage and monitor the same array. Due to a restriction on monitoring commands sent to the array controller by only one server at a time, some monitoring commands might fail if sent simultaneously by multiple servers. This could cause inaccurate reporting or the processes to stop responding. To prevent this from happening, the CLI can be configured to enable and disable array monitoring on a server.

Note - You cannot use the Sun StorEdge CLI and Sun StorEdge Configuration Service at the same time to configure, monitor, or maintain an array.

To access the Sun StorEdge CLI, follow the appropriate procedure for your operating system.

The Sun StorEdge CLI start-up time depends on several factors:

the number of device files in /dev/es and /dev/rdsk

the I/O load that is presented to any devices on the system

the behavior of the SES driver

The SES driver exhibits undesirable behavior when the Sun StorEdge CLI attempts to open a device file corresponding to a non-existent SES device. This is similar to the way the format(1M) command startup time depends on the number of disk devices on the system and the I/O load presented to those devices.

Note - To prevent unauthorized access to administrative functions of the RAID controller, the Sun StorEdge CLI requires superuser or system administrator privileges for in-band access, and uses the controller password to authorize users of the out-of-band interface.

To Access the Sun StorEdge CLI from UNIX Operating Systems

To access the Sun StorEdge CLI from the Solaris operating system or Linux, HP-UX, or AIX operating systems, perform the following steps.

1. To access the Sun StorEdge CLI, log in as root on the server that is attached to the array.

2. Type:

# sccli (with options and commands as described in this guide)

Note - If you do not have /usr/sbin in your PATH environment variable, you can run the Sun StorEdge CLI as /usr/sbin/sccli.

To Access the Sun StorEdge CLI from the Microsoft Windows Operating System

To access the Sun StorEdge CLI, go to Start right arrow Programs Sun StorEdge CLI Family Command Line Interface. This launches the file: c:\program files\sun\sccli\sccli.bat. You can modify this file if you want to change the command-line options passed to the Sun StorEdge CLI.

You can also access the Sun StorEdge CLI from a command shell. In the shell window, type:

c:\program files\sun\sccli\sccli.exe

Accessing the Man Page and Help

Refer to the Sun StorEdge CLI man page and the Release Notes for the latest documentation updates.

To Access the Man Page from UNIX Operating Systems

For the Solaris operating system or Linux, HP-UX, or AIX operating systems, to access the man page, type:

# man sccli

To Access Help from the Microsoft Windows Operating System

To access help in Windows, go to Start right arrow Programs Sun StorEdge CLI Family Command Line Help.

Interactive Command Mode

The Sun StorEdge CLI supports single-command mode and interactive mode. In interactive mode no command is specified on the command line. Specifying the device name on the command line is optional. If the device name is omitted, the Sun StorEdge CLI searches for any locally attached Sun StorEdge 3000 family arrays. If one is found, it is selected automatically. If more than one device is found, a list of choices is displayed. If no device is found, the Sun StorEdge CLI exits with an error.

In interactive mode, specify the device on the command line. For instance, type:

# sccli 206.1.111.111
sccli: selected se3000://206.1.111.111:58632 [SUN StorEdge 3310 SN#000001]
sccli> show disks free
sccli: no free disks found

To choose from a list of available devices, do not specify a device on the command line. For instance, in Solaris, type:

# sccli
Available devices:
 
  1. /dev/rdsk/c1t0d0s2 [SUN StorEdge 3310 SN#000001] (Primary)
  2. /dev/rdsk/c6t40d0s2 [SUN StorEdge 3510 SN#003CE3] (Primary)
 
Please enter selection: 1
sccli> version
sccli version 2.0.0

Note - In interactive mode, special characters must be enclosed in single or double quotes, which are parsed and stripped off. For example, if you want to set your password to an empty string, specify an empty string by typing two quote characters with nothing in between, such as set password "".

Single-Command Mode

In single-command mode, the name of the target device and the command to execute are specified on the command line. The Sun StorEdge CLI executes the command and exits.

To start single-command mode, type:

# sccli option [device-name |host-name [:port]] command parameters

TABLE 1-1 Single-Command Syntax
Syntax	Description
device-name	Specify a native operating system device file name for a locally attached SCSI target.
host-name	Specify a controller name or the IP address for the host of the primary agent.
port	Specify a port number for the primary agent on the specified controller or IP address.

In single-command mode, type the entire command on the command line. For instance, in Solaris, type:

# sccli /dev/rdsk/c1t0d0s2 show events

In single-command mode in Windows, type:

c:\> sccli \\.\PhysicalDrive3 show events

When the Sun StorEdge CLI performs a single command, an exit code indicates the success or failure of the command. An exit code of 0 indicates success, and any non-zero code indicates the command failed.

Command Keywords

Sun StorEdge CLI commands are case-independent. Uppercase, lowercase, or mixed case parameters, commands, and options can be used. Options have a long form and a single-letter form. Options begin with a single dash “-” for single-letter form and with two dashes “--” for long form.

In most cases, you can abbreviate command keywords to the shortest unambiguous substring. For example, abbreviate the show disks command to sh d. Or, type show lds to execute the show logical-drive command. However, to avoid ambiguity, do not abbreviate the command name.

The general syntax for commands in single-command mode is:

# sccli option [device-name | host-name [:port]] command parameters

Except for the help, about, and version commands, all Sun StorEdge CLI commands require the specification of a device name.

The following table shows the parameters and options that are used with commands in the following chapters. TABLE 1-2 also shows the options that can be used to simplify script creation and retrieve information.

TABLE 1-2 Command Parameters and Options
Parameter or Option	Short Form	Description
ch.id.lun		A single-host LUN mapping for a logical unit on a host channel can be specified using 3 dotted decimals in this form, where `ch` is the physical host channel number, `id` is the SCSI ID of the logical unit, and `lun` is the logical unit number.
device		For more information, see Device Names for Inband Communication and Device Names for Out-of-Band Communication.
disk		Physical disk drives are specified as two decimal integers separated by a period. The first number is the physical channel number, and the second number is the SCSI target ID for the drive on that channel. For example, specify the disk with target ID 1 on channel 2 as `2.1`.
`--disk` disk	`-d` disk	LVD JBOD enclosure only. Selects the disk enclosure containing the specified disk. Specify a Solaris device name such as `sd31` or `c1t0d0`. This option is an alternative to specifying an enclosure services device such as `/dev/es/ses`n when selecting a JBOD enclosure. The `disk` option does not support split-bus JBOD enclosures.
disk-list		A list of disk specifiers, separated by commas. For example, `1.0, 1.1, 1.2`.
--help, --usage	`-`h	Displays a usage message and exits without processing any commands. This option can also be used as a command. For information about the `help` command, see help.
`inter-controller-link`	`icl`	The command abbreviation, `icl,` provides an alternative to typing the full command name.
ld-list		A comma-separated list of logical drive indexes, for example, `ld0,ld1,ld2`, or a list of logical drive identifiers. Note that these logical drive numbers do not necessarily correspond to the single-digit logical drive identifiers in the firmware menu interface. The Sun StorEdge CLI logical drive indexes might change when logical drives are deleted.
--list	-l	Displays a list of local or remote devices that the Sun StorEdge CLI manages, and exits without processing any commands. The output includes a file name or URL that can be used to access the device in subsequent commands and the SCSI inquiry data and serial number of the subsystem. If a network URL is specified on the command line, the output is limited to that device. If a local device file name or directory name is specified, the search is limited to matching devices. The output includes the device name, vendor, product ID, and serial number.
logical-drive	ld or lds	A logical drive can be represented by a logical drive index (a small decimal number distinguished by an ld prefix), or a logical drive identifier (an eight-digit hexadecimal number). For example, a logical drive might be identified both by its logical drive index `ld3` and its logical drive ID `71038221`. For additional information, see Logical Drive Syntax. Note that these logical drive numbers do not necessarily correspond to the single-digit logical drive identifiers in the firmware menu interface. The Sun StorEdge CLI logical drive indexes might change when logical drives are deleted.
logical-volume	lv or lvs	Logical volumes are specified using either a logical volume index, such as `lv12`, or an eight-digit hexadecimal logical volume ID. For additional information, see Logical Volume Syntax. Note that these logical volume numbers do not necessarily correspond to the single-digit logical volume identifiers in the firmware menu interface. The Sun StorEdge CLI logical volume indexes might change when logical volumes are deleted.
lun		Partitions of a logical drive or logical volume are made available to hosts by mapping each partition to a target ID and logical unit number on one or more channels of the array controller. Commands with a lun parameter accept the physical channel number, target ID, and logical unit as three decimal numbers separated by periods. For example, `4.1.2` represents physical channel 4, target ID 1, logical unit number 2.
lv-list		A comma-separated list of logical volume indexes, for example, `lv0,lv1,lv2`, or a list of logical volume identifiers. Note that these logical volume numbers do not necessarily correspond to the single-digit logical volume identifiers in the firmware menu interface. The Sun StorEdge CLI logical volume indexes might change when logical volumes are deleted.
--no	-n	Assumes a `no` response to any yes/no prompts. Use this option to prompt the user before running scripts.
--oob	-o	Accesses the selected device using out-of-band communication rather than using the SCSI or Fibre Channel host bus adapter (HBA) with which the array is connected to the host. This option accesses the device using a local HBA only briefly, to retrieve the array’s network address, and all subsequent access is done over the network. This can provide better performance when the array is processing large quantities of SCSI I/O. If the IP address for the array cannot be determined, inband communication is used instead.
partition		A logical drive or logical volume identifier with a suffix indicating a specific partition within the logical drive or volume, for example, `ld2-03` or `2CA48914-03`. The suffix is a hexadecimal number ranging from 0 to 7F.
--password password	-w password	Specifies the password assigned to the array controller. The user must supply the correct password when issuing potentially dangerous commands to the array over a network connection. For security reasons, it is preferable to supply this password using the Sun StorEdge CLI `password` command, or enter the password interactively when prompted for it. No password is required for commands which do not modify the state of the controller, or commands issued using the inband communication mode.
target-list		A comma-separated list of SCSI target ID numbers.
--version	-v	Displays the version number of the Sun StorEdge CLI and exits without processing any commands.
--yes	-y	Assumes a `yes` response to any `yes`/`no` prompts. Use this option to run scripts without prompting the user.

Device Names for Inband Communication

For inband communication, device names include one of the following:

Native SCSI or FC disk device file names

Native device file names with the directory names and partitions removed

For systems using the Solaris operating system, the device name is typically specified as:

/dev/rdsk/cXtYdZs2

In the preceding device name code:

X = controller number

Y = SCSI target number

Z = logical unit number

s2 = slice 2 of the (logical) disk. Usually, slice 2 is specified when identifying a disk for administrative purposes, but any slice number between 0 and 7 (if the slice exists) works.

An example of the device name in Solaris is:

/dev/rdsk/c2t0d0

To access a JBOD enclosure services device using Solaris, specify the device name as shown in the following example, or use the --disk option and specify the name of a disk device within the enclosure.

/dev/es/sesn

For Windows operating systems, the device name is specified using the Windows internal device name for the physical device, where N corresponds to the disk number displayed in the Disk Administrator.

\\.\PhysicalDriveN

For example:

PhysicalDrive3

Note - If no device is specified on the command line, and more than one array is connected to the host, a menu of devices is presented with one device file name for each array. If there is only one Sun StorEdge 3000 family array device connected to the host, that device is selected automatically.

Note - If inband management access has been disabled by Sun StorEdge CLI--the firmware application--or Sun StorEdge Configuration Service, and a user attempts to use inband management, the message “RAID controller not responding” displays when a command is run. If this occurs, use out-of-band management to access Sun StorEdge CLI. For details, see Device Names for Out-of-Band Communication.

Device Names for Out-of-Band Communication

To access a RAID array using its out-of-band network interface rather than using the SCSI or FC host bus adapter (HBA) with which the array is connected to the host, specify the --oob option. This option accesses the device using a local HBA only briefly, to retrieve the array’s network address, and all subsequent access is done over the network. Out-of-band communication is useful when heavy SCSI I/O makes inband access slow. It can also be used when the host has no path to the primary controller, but can still retrieve the IP address of the array from a logical unit number (LUN) mapped from the secondary controller.

Alternately, if the host on which the Sun StorEdge CLI is running is not connected to the array with a SCSI or FC HBA, a URL can be specified to indicate that the Sun StorEdge CLI should connect to the remote array over the network.

In out-of-band management, the device name is typically specified as a URL in the format:

[se3000://] hostname-or-address[:port]

TABLE 1-3 Out-of-Band Device Name Syntax
Syntax	Description
[se3000://]	Optionally, use this prefix to ensure that the string that follows is interpreted only as a host name and not as a device name.
hostname-or-address	Specify a host name or the IP address for the host of the primary agent.
port	Optionally, specify the TCP/IP port number to use. The default value, 58632, is the only supported value.

Disk Device Syntax

A physical disk attached to the array can be identified with any of the following:

TABLE 1-4 Disk Device Syntax
Syntax	Description
ch.id	Dotted-decimal format where `ch` is physical device channel and `id` is the SCSI ID of the device.
ch.m-n	Where `ch` is physical device channel and `m` to `n` represents a contiguous range of IDs on the same channel.
sdn or c<X>t<Y>d<Z>	JBOD LVD disks only. Specify a disk device using a Solaris or SPARC device name such as `sd31` or `c1t0d0` when a JBOD chassis is selected.

Logical Drive Syntax

Logical drives can be specified by one of the following alphanumeric strings:

an eight-digit hexadecimal logical drive identifier.

a logical drive index composed of the prefix “ld” followed by a temporary decimal ordinal number ranging from 0 to n-1, where n is the number of logical drives configured on the array.

Note - Logical drive indexes can change whenever a logical drive is deleted, while a logical drive identifier never changes over the life of the logical drive.

The logical drive index number referenced with each logical drive is dynamic; it might change when logical drives are created or deleted. The index number is used strictly as a placeholder that enables you to visually keep track of logical drives. For example, if four logical drives exist, and LD2 is deleted, the existing LD3 dynamically changes to LD2, and LD4 changes to LD3. Only the LD index number changes; all LUN mapping and data on the logical drives remains unchanged. Care must be taken not to assume that a logical drive keeps the same logical drive index after creating or deleting any logical drive or rebooting the array controller.

Caution - Any time logical drives are created or deleted, the numbering of logical drive indexes might change. After creating or deleting logical drives, issue a show logical-drivecommand to view an updated list of logical drive indexes. Or, use logical drive IDs, which do not change over the lifetime of the logical drive, rather than logical drive indexes.

Note - In contrast, in the firmware application, the LG number on the View and Edit Logical Drives menu is not dynamic. After a logical drive is deleted, you see an empty placeholder.

Some commands accept a list of logical drives, or LD-list. This list is constructed by concatenating one or more logical drive identifiers or indexes as shown in the following examples.

This example lists logical drives using the local drive identifier.

0043BF50,05CC1F19,025E42E1

This example lists logical drives using the index number.

ld0,ld1,ld2

Note - Do not include spaces before or after the commas when specifying a logical drive list.

Logical Volume Syntax

Logical volumes are specified by one of the following alphanumeric strings:

an eight-digit hexadecimal logical volume identifier.

a logical volume index composed of the prefix “lv” followed by a temporary decimal ordinal number ranging from 0 to n-1, where n is the number of logical volumes configured on the array.

Note - Logical volume indexes can change whenever a logical volume is deleted, while a logical volume identifier never changes over the life of the logical volume.

The logical volume index number referenced with each logical volume is dynamic; it might change when logical volumes are created or deleted. The index number is used strictly as a placeholder that enables you to visually keep track of logical volumes. For example, if four logical volumes exist, and LV2 is deleted, the existing LV3 dynamically changes to LV2, and LV4 changes to LV3. Only the LV index number changes; all LUN mapping and data on the logical volume remains unchanged. Care must be taken not to assume that a logical volume keeps the same logical volume index after creating or deleting any logical volume or rebooting the array controller.

A list of logical volumes identifiers or indexes can be specified by concatenating one or more logical drive identifiers or logical volume indexes, separating them with commas.

Caution - Any time logical volumes are created or deleted, the numbering of logical volume indexes might change. After creating or deleting logical volumes, issue a show logical-volumescommand to view an updated list of logical volume indexes. Or, use logical volume IDs, which do not change over the lifetime of the logical volume, rather than logical volume indexes.

Note - In contrast, in the firmware application, the LG number on the View and Edit Logical Drives menu is not dynamic. After a logical volume is deleted, you see an empty placeholder.

This example lists logical volumes using the local volume identifier.

52AD5DEB,472C1397,E2054317

This example lists logical volumes using the local volume index number.

lv0,lv1,lv2

Device Capacity

In the Sun StorEdge CLI, all device capacity is displayed in powers of 1024.

1 Kbyte = 1024 bytes

1 Mbyte = 1024 Kbyte = 1,048,576 bytes

1 Gbyte = 1024 Mbyte = 1,073,741,824 bytes

1 Tbyte = 1024 Gbyte = 1,099,511,627,776 bytes