luxadm(1M) System Administration Commands luxadm(1M)NAMEluxadm - administer Sun Fire 880 storage subsystem and FC_AL devices
SYNOPSISluxadm [options]... subcommand [options]... enclosure
[,dev] | pathname...
DESCRIPTION
The luxadm program is an administrative command that manages the SENA,
Sun Fire 880 internal storage subsystem, and individual Fiber Channel
Arbitrated Loop (FC_AL) devices. luxadm performs a variety of control
and query tasks depending on the command line arguments and options
used.
The command line must contain a subcommand. The command line may also
contain options, usually at least one enclosure name or pathname, and
other parameters depending on the subcommand. You need specify only as
many characters as are required to uniquely identify a subcommand.
Specify the device that a subcommand interacts with by entering a path‐
name. For the SENA subsystem, a disk device or enclosure services con‐
troller may instead be specified by entering the World Wide Name (WWN)
for the device or a port to the device. The device may also be speci‐
fied by entering the name of the SENA enclosure, and an optional iden‐
tifier for the particular device in the enclosure. The individual FC_AL
devices may be specified by entering the WWN for the device or a port
to the device.
Pathname
Specify the device or controller by either a complete physical pathname
or a complete logical pathname.
For SENA, a typical physical pathname for a device is:
/devices/sbus@1f,0/SUNW,socal@1,0/sf@0,0/ssd@w2200002037000f96,
0:a,raw
For all SENA IBs (Interface Boards) and Sun Fire 880 SES device con‐
trollers on the system, a logical link to the physical paths is kept in
the directory /dev/es. An example of a logical link is /dev/es/ses0.
The WWN may be used in place of the pathname to select an FC_AL device,
SENA subsystem IB, or Sun Fire 880 internal storage subsystem. The WWN
is a unique 16 hexadecimal digit value that specifies either the port
used to access the device or the device itself. A typical WWN value is:
2200002037000f96
See NOTES for more information on the WWN formats.
For a disk in a Sun Fire 880 internal storage subsystem, a typical
physical pathname is:
/devices/pci@8,600000/SUNW,qlc@2/fp@0,0/ssd@w2100002037a6303c,0:a
and a typical logical pathname is:
/dev/rdsk/c2t8d0s2
For individual FC_AL devices, a typical physical pathname is:
/devices/sbus@3.0/SUNW,socal@d,10000/sf@0,0/ssd@w2200002037049fc3,0:a,raw
and a typical logical pathname is:
/dev/rdsk/c1t0d0s2
Enclosure
For SENA, a device may be identified by its enclosure name and slot‐
name:
box_name[,fslot_number]
box_name[,rslot_number]
box_name is the name of the SENA enclosure, as specified by the enclo‐
sure_name subcommand. When used without the optional slot_number param‐
eter, the box_name identifies the SENA subsystem IB.
f or r specifies the front or rear slots in the SENA enclosure.
slot_number specifies the slot number of the device in the SENA enclo‐
sure, 0-6 or 0-10.
For a Sun Fire 880 internal storage subsystem, a device may also be
identified by its enclosure name and slot name. However, there is only
one set of disks:
box_name[,sslot_number]
box_name is the name of the Sun Fire 880 enclosure, as specified by the
enclosure_name subcommand. When used without the optional slot_number
parameter, box_name identifies the Sun Fire 880 internal storage sub‐
system enclosure services device. Use s to specify the disk slot number
in the Sun Fire 880 internal storage subsystem, 0 - 11.
See disks(1M) and devlinks(1M) for additional information on logical
names for disks and subsystems.
OPTIONS
The following options are supported by all subcommands:
-e Expert mode. This option is not recommended for the novice user.
-v Verbose mode.
Options that are specific to particular subcommands are described with
the subcommand in the USAGE section.
OPERANDS
The following operands are supported:
enclosure
The box_name of the SENA or Sun Fire 880 internal storage subsys‐
tem.
fibre_channel_HBA_port
The path to the host controller port. A typical path is:
/devices/pci@8,600000/pci@1/SUNW,qlc@4/fp@0,0:devctl
pathname
The logical or physical path of a SENA IB, Sun Fire 880 internal
storage subsystem, or disk device. pathname can also be the WWN of
a SENA IB, SENA disk, or individual FC_AL device.
USAGE
Subcommands
display enclosure[,dev]...| pathname...
display -p pathname...
display -r enclosure[,dev]...| pathname...
display -v enclosure[,dev]...| pathname...
Displays enclosure or device specific data.
Subsystem data consists of enclosure environmental sense informa‐
tion and status for all subsystem devices, including disks.
Disk data consists of inquiry, capacity, and configuration informa‐
tion.
-p Displays performance information for the device or subsystem
specified by pathname. This option only applies to subsystems
that accumulate performance information.
-r Displays error information for the FC_AL device specified by
the pathname, or, if the path is a SENA, for all devices on
the loop. The -r option only applies to SENA subsystems and
individual FC_AL devices.
-v Displays in verbose mode, including mode sense data.
download [ -s ] [ -f filename_path ] enclosure...
Download the prom image pointed to the SENA subsystem Interface
Board unit or the Sun Fire 880 internal storage subsystem specified
by the enclosure or pathname.
When the SENA's download is complete, the SENA will be reset and
the downloaded code executed. If no filename is specified, the
default prom image will be used. The default prom image for the
SENA is in the directory usr/lib/locale/C/LC_MESSAGES and is named
ibfirmware
When the Sun Fire 880 internal storage subsystem's download is com‐
plete, the subsystem resets and the downloaded code begins execu‐
tion. The default firmware image for the Sun Fire 880 internal
storage subsystem is in: /usr/platform/SUNW,Sun-
Fire-880/lib/images/int_fcbpl_fw.
-s Save. The -s option is used to save the downloaded firmware
in the FEPROM. If -s is not specified, the downloaded
firmware will not be saved across power cycles.
The -s option does not apply to the Sun Fire 880 internal
storage subsystem as it always stores downloaded firmware in
the flash memory.
When using the -s option, the download subcommand modifies
the FEPROM on the subsystem and should be used with caution.
enclosure_name new_name enclosure | pathname
Change the enclosure name of the enclosure or enclosures specified
by the enclosure or pathname. The new name (new_name) must be 16 or
less characters. Only alphabetic or numeric characters are accept‐
able. This subcommand applies only to the SENA and the Sun Fire 880
internal storage subsystem.
failover primary | secondary pathname
Select which Sun Storage T3 storage array partner group controller
accesses a given logical volume. If primary is specified, the logi‐
cal volume is accessed through the primary controller. If secondary
is specified, the logical volume is accessed through the secondary
controller specified by pathname.
fcal_s_download [ -f fcode-file ]
Download the fcode contained in the file fcode-file into all the
FC100/S Sbus Cards. This command is interactive and expects user
confirmation before downloading the fcode.
Use fcal_s_download only in single-user mode. Using fcal_s_download
to update a host adapter while there is I/O activity through that
adapter will cause the adapter to reset. Newly updated FCode will
not be executed or visible until a system reboot.
-f fcode-file When invoked without the -f option, the current
version of the fcode in each FC100/S Sbus card is
printed.
fcode_download -p
fcode_download -d dir-name
Locate the installed FC/S, FC100/S, FC100/P, or FC100/2P host bus
adapter cards and download the FCode files in dir-name to the
appropriate cards. The command determines the correct card for each
type of file, and is interactive. User confirmation is required
before downloading the FCode to each device.
Use fcode_download to load FCode only in single-user mode. Using
fcode_download to update a host adapter while there is I/O activity
through that adapter causes the adapter to reset. Newly updated
FCode will not be executed or visible until a system reboot.
-d dir-name Download the FCode files contained in the directory
dir-name to the appropriate adapter cards.
-p Prints the current version of FCode loaded on each
card. No download is performed.
inquiry enclosure[,dev ]... | pathname...
Display the inquiry information for the selected device specified
by the enclosure or pathname.
insert_device [ enclosure,dev... ]
Assist the user in the hot insertion of a new device or a chain of
new devices. Refer to NOTES for limitations on hotplug operations.
This subcommand applies only to the SENA, Sun Fire 880 internal
storage subsystem, and individual FC_AL drives. For the SENA, if
more than one enclosure has been specified, concurrent hot inser‐
tions on multiple busses can be performed. With no arguments to the
subcommand, entire enclosures or individual FC_AL drives can be
inserted. For the SENA or the Sun Fire 880 internal storage subsys‐
tem, this subcommand guides the user interactively through the hot
insertion steps of a new device or chain of devices. If a list of
disks was entered it will ask the user to verify the list of
devices to be inserted is correct, at which point the user can con‐
tinue or quit. It then interactively asks the user to insert the
disk(s) or enclosure(s) and then creates and displays the logical
pathnames for the devices.
led enclosure,dev...| pathname...
Display the current state of the LED associated with the disk spec‐
ified by the enclosure or pathname. This subcommand only applies to
subsystems that support this functionality.
led_blink enclosure,dev...| pathname...
Requests the subsystem to start blinking the LED associated with
the disk specified by the enclosure or pathname. This subcommand
only applies to subsystems that support this functionality.
led_off enclosure,dev...| pathname...
Requests the subsystem to disable (turn off) the LED associated
with the disk specified by the enclosure or pathname. On a SENA
subsystem, this may or may not cause the LED to turn off or stop
blinking depending on the state of the SENA subsystem. Refer to the
SENA Array Installation and Service Manual (p/n 802-7573). This
subcommand only applies to subsystems that support this functional‐
ity.
led_on pathname...
Requests the subsystem to enable (turn on) the LED associated with
the disk specified by the pathname. This subcommand only applies to
subsystems that support this functionality.
power_off [ -F ] enclosure[,dev]... | pathname ...
When a SENA is addressed, this subcommand causes the SENA subsystem
to go into the power-save mode. The SENA drives are not available
when in the power-save mode. When a drive in a SENA is addressed
the drive is set to the drive off/unmated state. In the drive
off/unmated state, the drive is spun down (stopped) and in bypass
mode. This command does not apply to the Sun Fire 880 internal
storage subsystem.
-F The force option only applies to the SENA. Instructs luxadm
to attempt to power off one or more devices even if those
devices are being used by this host (and are, therefore,
busy).
Warning: Powering off a device which has data that is cur‐
rently being used will cause unpredictable results. Users
should attempt to power off the device normally (without -F)
first, only resorting to this option when sure of the conse‐
quences of overriding normal checks.
power_on enclosure[,dev]..
Causes the SENA subsystem to go out of the power-save mode, when
this subcommand is addressed to a SENA.. When this subcommand is
addressed to a drive the drive is set to its normal start-up state.
This command does not apply to the Sun Fire 880 internal storage
subsystem.
probe [ -p ]
Finds and displays information about all attached SENA subsystems,
Sun Fire 880 internal storage subsystems, and individual FC_AL
devices, including the logical pathname, the WWNs, and enclosure
names. This subcommand warns the user if it finds different SENAs
with the same enclosure names.
-p Includes the physical pathname in the display.
qlgc_s_download [ -f fcode-file ]
Download the FCode contained in the file fcode-file into all the
FC100/P, FC100/2P PCI host adapter cards. This command is interac‐
tive and expects user confirmation before downloading the FCode to
each device. Only use qlgc_s_download in single-user mode. Using
qlgc_s_download to update a host adapter while there is I/O activ‐
ity through that adapter will cause the adapter to reset. Newly
updated FCode will not be executed or visible until a system
reboot.
-f fcode-file When invoked without the -f option, the current
version of the FCode in each FC100/P, FC100/2P PCI
card is printed.
release pathname
Release a reservation held on the specified disk. The pathname
should be the physical or logical pathname for the disk.
This subcommand is included for historical and diagnostic purposes
only.
remove_device [ -F ] enclosure[,dev]...| pathname...
Assists the user in hot removing a device or a chain of devices.
This subcommand can also be used to remove entire enclosures. This
subcommand applies to the SENA, Sun Fire 880 internal storage sub‐
system, and individual FC_AL drives. Refer to NOTES for limitations
on hotplug operations. For the SENA, Sun Fire 880 internal storage
subsystem, and individual FC_AL devices, this subcommand guides the
user through the hot removal of a device or devices. During execu‐
tion it will ask the user to verify the list of devices to be
removed is correct, at which point the user can continue or quit.
It then prepares the disk(s) or enclosure(s) for removal and inter‐
actively asks the user to remove the disk(s) or enclosure(s).
For Multi-Hosted disk, the steps taken are:
o Issue the luxadm remove_device command on the first
host. When prompted to continue, wait.
o Issue the luxadm remove_device command on the secondary
hosts. When prompted to continue, wait.
o Continue with the remove_device command on the first
host. Remove the device when prompted to do so.
o Complete the luxadm remove_device command on the addi‐
tional hosts.
-F Instructs luxadm to attempt to hot plug one or more devices
even if those devices are being used by this host (and are,
therefore, busy or reserved), to force the hotplugging opera‐
tion.
Warning: Removal of a device which has data that is currently
being used will cause unpredictable results. Users should
attempt to hotplug normally (without -F) first, only resort‐
ing to this option when sure of the consequences of overrid‐
ing normal hotplugging checks.
reserve pathname
Reserve the specified disk for exclusive use by the issuing host.
The pathname used should be the physical or logical pathname for
the disk.
This subcommand is included for historical and diagnostic purposes
only.
set_boot_dev [ -y ] pathname
Set the boot-device variable in the system PROM to the physical
device name specified by pathname, which can be a block special
device or the pathname of the directory on which the boot file sys‐
tem is mounted. The command normally runs interactively requesting
confirmation for setting the default boot-device in the PROM. The
-y option can be used to run it non-interactively, in which case no
confirmation is requested or required.
start pathname
Spin up the specified disk(s) in a SENA.
stop pathname...
Spin down the specified disks in a SENA.
SENA, Sun Fire 880 Internal Storage Subsystem, and Individual FC_AL Drive
Expert Mode Subcommands
The following subcommands are for expert use only, and are applicable
only to the SENA, Sun Fire 880 internal storage subsystem, and fiber
channel loops. They should only be used by users that are knowledgeable
about the SENA subsystem and fiber channel loops.
If you specify a disk to an expert subcommand that operates on a bus,
the subcommand operates on the bus to which the specified disk is
attached.
-e bypass [-ab] enclosure,dev
-e bypass -f enclosure
Request the enclosure services controller to set the LRC (Loop
Redundancy Circuit) to the bypassed state for the port and device
specified.
This subcommand supports the following options:
-a Bypass port a of the device specified.
-b Bypass port b of the device specified.
-e dump_map fibre_channel_HBA_port
Display WWN data for a target device or host bus adapter on the
specified fibre channel port. If there are no target devices on the
specified port, an error is returned.
-e enable [-ab] enclosure,dev
-e enable -f enclosure
Request the enclosure services controller to set the LRC (Loop
Redundancy Circuit) to the enabled state for the port and device
specified.
This subcommand supports the following options:
-a Enable port a of the device specified.
-b Enable port b of the device specified.
-e forcelip enclosure[,dev] ... | pathname...
Force the link to reinitialize, using the Loop Initialization Prim‐
itive (LIP) sequence. The enclosure or pathname can specify any
device on the loop. Use the pathname to specify a specific path for
multiple loop configurations.
This is an expert only command and should be used with caution. It
will reset all ports on the loop.
-e rdls enclosure[,dev] ... | pathname...
Read and display the link error status information for all avail‐
able devices on the loop that contains the device specified by the
enclosure or pathname.
Other Expert Mode Subcommands
See NOTES for limitations of these subcommands. They should only be
used by users that are knowledgeable about the systems they are manag‐
ing.
These commands do not apply to the Sun Fire 880 internal storage sub‐
system.
-e bus_getstate pathname Get and display the state of the specified
bus.
-e bus_quiesce pathname Quiesce the specified bus.
-e bus_reset pathname Reset the specified bus only.
-e bus_resetall pathname Reset the specified bus and all devices.
-e bus_unquiesce pathname Unquiesce the specified bus. the specified
device.
-e dev_getstate pathname Get and display the state of the specified
device.
-e dev_reset pathname Reset the specified device.
-e offline pathname Take the specified device offline.
-e online pathname Put the specified device online.
EXAMPLES
Example 1 Displaying the SENAs and Individual FC_AL Devices on a System
The following example finds and displays all of the SENAs and individ‐
ual FC_AL devices on a system:
example% luxadm probe
Example 2 Displaying a SENA or Sun Fire 880 Internal Storage Subsystem
The following example displays a SENA or Sun Fire 880 internal storage
subsystem:
example% luxadm display /dev/es/ses0
Example 3 Displaying Two Subsystems
The following example displays two subsystems using the enclosure
names:
example% luxadm display BOB system1
Example 4 Displaying Information about the First Disk
The following example displays information about the first disk in the
front of the enclosure named BOB. Use f to specify the front disks. Use
r to specify the rear disks.
example% luxadm display BOB,f0
Example 5 Displaying Information on a Sun Fire 880 Internal Storage
Subsystem
The Sun Fire 880 internal storage subsystem has only one set of disks.
In this case, use s to specify the slot:
example% luxadm display BOB,s0
Example 6 Displaying Information about a SENA disk, an Enclosure, or an
Individual FC_AL Drive
The following example displays information about a SENA disk, an enclo‐
sure, or an individual FC_AL drive with the port WWN of
2200002037001246:
example% luxadm display 2200002037001246
Example 7 Using Unique Characters to Issue a Subcommand
The following example uses only as many characters as are required to
uniquely identify a subcommand:
example% luxadm disp BOB
Example 8 Displaying Error Information
The following example displays error information about the loop that
the enclosure BOB is on:
example% luxadm display -r BOB
Example 9 Downloading New Firmware into the Interface Board
The following example downloads new firmware into the Interface Board
in the enclosure named BOB (using the default path for the file to
download):
example% luxadm download -s BOB
Example 10 Displaying Information from the SCSI Inquiry Command
The following example displays information from the SCSI inquiry com‐
mand from all individual disks on the system, using only as many char‐
acters as necessary to uniquely identify the inquiry subcommand:
example% luxadm inq /dev/rdsk/c?t?d?s2
Example 11 Hotplugging
The following example hotplugs a new drive into the first slot in the
front of the enclosure named BOB:
example% luxadm insert_device BOB,f0
The following example hotplugs a new drive into the first slot in the
Sun Fire 880 internal storage subsystem named SF880-1:
example% luxadm insert_device SF880-1,s0
Example 12 Running an Expert Subcommand
The following example runs an expert subcommand. The subcommand forces
a loop initialization on the loop that the enclosure BOB is on:
example% luxadm-e forcelip BOB
Example 13 Using the Expert Mode Hot Plugging Subcommands
An example of using the expert mode hot plugging subcommands to hot
remove a disk follows. See NOTES for hot plugging limitations.
The first step reserves the SCSI device so that it can't be accessed by
way of its second SCSI bus:
example# luxadm reserve /dev/rdsk/c1t8d0s2
Example 14 Taking the Disk to be Removed Offline
The next two steps take the disk to be removed offline then quiesce the
bus:
example# luxadm-e offline /dev/rdsk/c1t8d0s2
example# luxadm-e bus_quiesce /dev/rdsk/c1t8d0s2
Example 15 Unquiescing the Bus
The user then removes the disk and continues by unquiescing the bus,
putting the disk back online, then unreserving it:
example# luxadm-e bus_unquiesce /dev/rdsk/c1t8d0s2
example# luxadm-e online /dev/rdsk/c1t8d0s2
example# luxadm release /dev/rdsk/c1t8d0s2
ENVIRONMENT VARIABLES
See environ(5) for a description of the LANG environment variable that
affects the execution of luxadm.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
−1 An error occurred.
FILES
usr/lib/firmware/fc_s/fc_s_fcode
usr/lib/locale/C/LC_MESSAGES/ibfirmware
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
usr/sbin
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │system/storage/luxadm │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOdevlinks(1M), disks(1M), attributes(5), environ(5), ses( 7D)
SENA Array Installation and Service Manual (p/n 802-7573).
RAID Manager 6.1 Installation and Support Guide Answerbook
RAID Manager 6.1 User's Guide Answerbook
NOTES
See the SENA Array Installation and Service Manual for additional
information on the SENA. Refer to Tutorial for SCSI use of IEEE Com‐
pany_ID, R. Snively, for additional information regarding the IEEE
extended WWN. See SEE ALSO. Currently, only some device drivers support
hot plugging. If hot plugging is attempted on a disk or bus where it is
not supported, an error message of the form:
luxadm: can't acquire "PATHNAME": No such file or directory
will be displayed.
You must be careful not to quiesce a bus that contains the root or the
/usr filesystems or any swap data. If you do quiesce such a bus a dead‐
lock can result, requiring a system reboot.
SunOS 5.11 24 Sep 2003 luxadm(1M)
