SCSI Hot-Plugging With the cfgadm Command

This section describes various SCSI hot-plugging procedures that you can perform with the cfgadm command.

Note - The SCSI framework generally supports hot-plugging of SCSI devices. However, you should consult your
hardware documentation to confirm whether hot-plugging is supported for your SCSI devices.

These procedures use specific devices as examples to illustrate how to use the cfgadm command to hot-plug SCSI
components. The device information that you supply, and that the cfgadm command displays, depends on your
system configuration.
All of the procedures in this section require administrative privileges that are not generally granted to user accounts.
For more information, see How to Use Your Assigned Administrative Rights in Oracle Solaris Administration: Security
Services.

How to Display Information About SCSI Devices

The following procedure uses SCSI controllers c0 and c1 and the devices that are attached to them in the examples
of the type of device configuration information that you can display with the cfgadm command.

Note - If the SCSI device is not supported by the cfgadm command, the device does not display in
the cfgadm command output.

1.
2.

Become an administrator.
Display information about attachment points on the system.

3. # cfgadm -l
4. Ap_Id
5. c0
c1

Type
scsi-bus

Receptacle
connected

Occupant
configured

Condition
unknown

scsi-bus

connected

configured

unknown

In this example, c0 and c1 represent two SCSI controllers.

6.

Display information about a system's SCSI controllers and their attached devices.

7. # cfgadm -al
8. Ap_Id
9. c0
10.
c0::dsk/c0t0d0
11.
c0::rmt/0
12.
c1
13.
c1::dsk/c1t3d0
c1::dsk/c1t4d0

Type
Receptacle
Occupant
Condition
scsi-bus
connected
configured
unknown
disk
connected
configured
unknown
tape
connected
configured
unknown
scsi-bus
connected
configured
unknown
disk
connected
configured
unknown
unavailable

connected

unconfigured unknown

Note - The cfgadm -l commands displays information about SCSI HBAs but not SCSI devices. Use
the cfgadm -al command to display information about SCSI devices such as disk and tapes.

How to Unconfigure a SCSI Controller

The following procedure uses SCSI controller c1 in the example of unconfiguring a SCSI controller.
1.
2.

Become an administrator.
Unconfigure a SCSI controller.

# cfgadm -c unconfigure c1
3.

Verify that the SCSI controller is unconfigured.

4.
5.
6.
7.
8.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0

Type
scsi-bus
disk
tape

Receptacle
connected
connected
connected

Occupant
configured
configured
configured

c1

scsi-bus

connected

unconfigured unknown

Condition
unknown
unknown
unknown

Notice that the Occupant column for c1 specifies unconfigured, indicating that the SCSI bus has no
configured occupants.
If the unconfigure operation fails, see How to Resolve a Failed SCSI Unconfigure Operation.

How to Configure a SCSI Controller

The following procedure uses SCSI controller c1 in the example of configuring a SCSI controller.
1.
2.

Become an administrator.
Configure a SCSI controller.

# cfgadm -c configure c1
3.

Verify that the SCSI controller is configured.

4. # cfgadm -al
5. Ap_Id
6. c0
7. c0::dsk/c0t0d0
8. c0::rmt/0
9. c1
10.
c1::dsk/c1t3d0
c1::dsk/c1t4d0

Type
scsi-bus
disk
tape
scsi-bus
disk

Receptacle
Occupant
Condition
connected
configured
unknown
connected
configured
unknown
connected
configured
unknown
connected
configured
unknown
connected
configured
unknown

unavailable

connected

unconfigured unknown

The previous unconfigure procedure removed all devices on the SCSI bus. Now all the devices are configured
back into the system.

How to Configure a SCSI Device

The following procedure uses SCSI disk c1t4d0 in the example of configuring a SCSI device.
1.
2.

Become an administrator.
Identify the device to be configured.

3.
4.
5.
6.
7.
8.
9.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0

Type
scsi-bus
disk
tape
scsi-bus
disk

Receptacle
connected
connected
connected
connected
connected

Occupant
configured
configured
configured
configured
configured

c1::dsk/c1t4d0

unavailable

connected

unconfigured unknown

Condition
unknown
unknown
unknown
unknown
unknown

10. Configure the SCSI device.

# cfgadm -c configure c1::dsk/c1t4d0

11. Verify that the SCSI device is configured.

12.
13.
14.
15.
16.
17.
18.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0
c1::dsk/c1t4d0

Type
scsi-bus
disk
tape
scsi-bus
disk
disk

Receptacle
connected
connected
connected
connected
connected
connected

Occupant
configured
configured
configured
configured
configured

configured

Condition
unknown
unknown
unknown
unknown
unknown

unknown

How to Disconnect a SCSI Controller

Caution - Disconnecting a SCSI device must be done with caution, particularly when you
are dealing with controllers for disks that contain critical file systems such as root
(/), usr,var, and the swap partition. The dynamic reconfiguration software cannot detect
all cases where a system hang might result. Use this procedure with caution.
The following procedure uses SCSI controller c1 in the example of disconnecting a SCSI device.
1.
2.

Become an administrator.
Verify that the device is connected before you disconnect it.

3.
4.
5.
6.
7.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0

Type
scsi-bus
disk
tape

Receptacle
connected
connected
connected

Occupant
configured
configured
configured

Condition
unknown
unknown
unknown

8. c1
9. c1::dsk/c1t3d0
c1::dsk/c1t4d0

scsi-bus
disk

connected
connected

configured
configured

unknown
unknown

disk

connected

configured

unknown

10. Disconnect the SCSI controller.

11.
12.

# cfgadm -c disconnect c1
WARNING: Disconnecting critical partitions may cause system hang.
Continue (yes/no)? y

Caution - This command suspends all I/O activity on the SCSI bus until the cfgadm c connect command is used. The cfgadm command does some basic checking to
prevent critical partitions from being disconnected, but it cannot detect all cases.
Inappropriate use of this command can result in a system hang and could require a
system reboot.

13. Verify that the SCSI bus is disconnected.

14.
15.
16.
17.
18.
19.
20.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0
c1::dsk/c1t4d0

Type
scsi-bus
disk
tape
unavailable
unavailable
unavailable

Receptacle
connected
connected
connected
disconnected
disconnected

Occupant
configured
configured
configured
configured
configured

disconnected configured

Condition
unknown
unknown
unknown
unknown
unknown

unknown

The controller and all the devices that are attached to it are disconnected from the system.

SPARC: How to Connect a SCSI Controller

The following procedure uses SCSI controller c1 in the example of connecting a SCSI controller.
1.
2.

Become an administrator.
Verify that the device is disconnected before you connect it.

3.
4.
5.
6.
7.
8.
9.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0

Type
scsi-bus
disk
tape
unavailable
unavailable

Receptacle
connected
connected
connected
disconnected
disconnected

Occupant
configured
configured
configured
configured
configured

Condition
unknown
unknown
unknown
unknown
unknown

c1::dsk/c1t4d0

unavailable

disconnected configured

unknown

10. Connect the SCSI controller.

# cfgadm -c connect c1
11. Verify that the SCSI controller is connected.

12.
13.
14.
15.
16.
17.
18.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0
c1::dsk/c1t4d0

Type
scsi-bus
disk
tape
scsi-bus
disk
disk

Receptacle
connected
connected
connected
connected
connected
connected

Occupant
configured
configured
configured
configured
configured

configured

Condition
unknown
unknown
unknown
unknown
unknown

unknown

SPARC: How to Add a SCSI Device to a SCSI Bus

SCSI controller c1 is used in the example of how to add a SCSI device to a SCSI bus.

Note - When you add devices, you specify the Ap_Id of the SCSI HBA (controller) to which the device is attached,
not the Ap_Id of the device itself.

1.
2.

Become an administrator.
Identify the current SCSI configuration.

3.
4.
5.
6.
7.
8.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1

Type
scsi-bus
disk
tape
scsi-bus

Receptacle
connected
connected
connected
connected

Occupant
configured
configured
configured
configured

Condition
unknown
unknown
unknown
unknown

c1::dsk/c1t3d0

disk

connected

configured

unknown

9.

Add the SCSI device to the SCSI bus.

a. Type the following cfgadm command.
For example:

# cfgadm -x insert_device c1
Adding device to SCSI HBA: /devices/sbus@1f,0/SUNW,fas@1,8800000
This operation will suspend activity on SCSI bus: c1
b.

Type y at the Continue (yes/no)? prompt to proceed.

c. Continue (yes/no)? y
d. SCSI bus quiesced successfully.
It is now safe to proceed with hotplug operation.
I/O activity on the SCSI bus is suspended while the hot-plug operation is in progress.
e.
f.

Connect the device and then power it on.

Type y at the Enter y if operation is complete or n to abort
(yes/no)? prompt.

Enter y if operation is complete or n to abort (yes/no)? y

10. Verify that the device has been added.

11.
12.
13.
14.
15.
16.
17.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0
c1::dsk/c1t4d0

Type
scsi-bus
disk
tape
scsi-bus
disk
disk

Receptacle
connected
connected
connected
connected
connected
connected

Occupant
configured
configured
configured
configured
configured

configured

Condition
unknown
unknown
unknown
unknown
unknown

unknown

A new disk has been added to controller c1.

SPARC: How to Replace an Identical Device on a SCSI

Controller
The following procedure uses SCSI disk c1t4d0 in the example of replacing an identical device on a SCSI
controller.
Review the following conditions when attempting to replace an identical device on a SCSI controller:

If you are replacing a mirrored or unmirrored boot device that is part of a ZFS root pool, see the following
reference:
http://www.oracle.com/technetwork/articles/servers-storage-admin/o11-091-sol-dis-recovery-489183.html

1.
2.

If the device is controlled by legacy volume management software, consult your volume management
documentation for the specific steps to replace a device. If you have an active Oracle support plan, see the
following references:

If you are using Solaris Volume Manager (SVM), see MOS document 1010753.1.

If you are using Veritas Volume Manager (VxVM), see MOS document 1003122.1, 1011782.1, and
1002285.1.

Become an administrator.
Identify the current SCSI configuration.

3. # cfgadm -al
4. Ap_Id

Type

Receptacle

Occupant

Condition

5.
6.
7.
8.
9.

c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0

scsi-bus
disk
tape
scsi-bus
disk

connected
connected
connected
connected
connected

configured
configured
configured
configured
configured

unknown
unknown
unknown
unknown
unknown

c1::dsk/c1t4d0

disk

connected

configured

unknown

10. Replace a device on the SCSI bus with another device of the same type.
a. Type the following cfgadm command.
For example:

# cfgadm -x replace_device c1::dsk/c1t4d0

Replacing SCSI device: /devices/sbus@1f,0/SUNW,fas@1,8800000/sd@4,0
This operation will suspend activity on SCSI bus: c1
b.

Type y at the Continue (yes/no)? prompt to proceed.

I/O activity on the SCSI bus is suspended while the hot-plug operation is in progress.

Continue (yes/no)? y
SCSI bus quiesced successfully.
It is now safe to proceed with hotplug operation.
c.
d.

Power off the device to be removed and remove it.

Add the replacement device. Then, power it on.
The replacement device should be of the same type and at the same address (target and LUN) as the
device to be removed.

e.

Type y at the Enter y if operation is complete or n to abort

(yes/no)? prompt.

Enter y if operation is complete or n to abort (yes/no)? y

11. Verify that the device has been replaced.

12.
13.
14.
15.
16.
17.
18.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0
c1::dsk/c1t4d0

Type
scsi-bus
disk
tape
scsi-bus
disk
disk

Receptacle
connected
connected
connected
connected
connected
connected

Occupant
configured
configured
configured
configured
configured

configured

SPARC: How to Remove a SCSI Device

Condition
unknown
unknown
unknown
unknown
unknown

unknown

The following procedure uses SCSI disk c1t4d0 in the example of removing a device on a SCSI controller.
1.
2.

Become an administrator.
Identify the current SCSI configuration.

3.
4.
5.
6.
7.
8.
9.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0

Type
scsi-bus
disk
tape
scsi-bus
disk

Receptacle
connected
connected
connected
connected
connected

Occupant
configured
configured
configured
configured
configured

Condition
unknown
unknown
unknown
unknown
unknown

c1::dsk/c1t4d0

disk

connected

configured

unknown

10. Remove the SCSI device from the system.

a. Type the following cfgadm command.
For example:

# cfgadm -x remove_device c1::dsk/c1t4d0

Removing SCSI device: /devices/sbus@1f,0/SUNW,fas@1,8800000/sd@4,0
This operation will suspend activity on SCSI bus: c1
b.

Type y at the Continue (yes/no)? prompt to proceed.

c. Continue (yes/no)? y
d. SCSI bus quiesced successfully.
It is now safe to proceed with hotplug operation.
I/O activity on the SCSI bus is suspended while the hot-plug operation is in progress.
e.
f.

Power off the device to be removed and remove it.

Type y at the Enter y if operation is complete or n to abort
(yes/no)? prompt.

Enter y if operation is complete or n to abort (yes/no)? y

11.
12. Note - This step must be performed if you are removing a SCSI RAID device from a SCSI RAID array.
13.
14. Verify that the device has been removed from the system.

15.
16.
17.
18.
19.
20.

# cfgadm -al
Ap_Id
c0
c0::dsk/c0t0d0
c0::rmt/0
c1
c1::dsk/c1t3d0

Type
scsi-bus
disk
tape
scsi-bus
disk

Receptacle
connected
connected
connected
connected
connected

Occupant
configured
configured
configured
configured

configured

Condition
unknown
unknown
unknown
unknown

unknown

Troubleshooting SCSI Configuration Problems

This section provides error messages and possible solutions for troubleshooting SCSI configuration problems. For
more information on troubleshooting SCSI configuration problems, seecfgadm(1M).
Error Message

cfgadm: Component system is busy, try again: failed to offline:

device-path
Resource
Information
------------------ -------------------------/dev/dsk/c1t0d0s0
mounted filesystem "/file-system"
Cause
You attempted to remove or replace a device with a mounted file system.
Solution
Unmount the file system that is listed in the error message and retry the cfgadm operation.
Error Message

cfgadm: Component system is busy, try again: failed to offline:

device-path
Resource
Information
------------------ -------------------------/dev/dsk/device-name
swap area
Cause
If you use the cfgadm command to remove a system resource, such as a swap device or a dedicated
dump device, a similar error message is displayed if the system resource is still active.
Solution
Unconfigure the swap areas on the device that is specified and retry the cfgadm operation.
Error Message

cfgadm: Component system is busy, try again: failed to offline:

device-path
Resource
Information
------------------ -------------------------/dev/dsk/device-name
dump device (swap)
Cause
You attempted to remove or replace a dump device that is configured on a swap area.
Solution
Unconfigure the dump device that is configured on the swap area and retry the cfgadm operation.
Error Message

cfgadm: Component system is busy, try again: failed to offline:

device-path
Resource
Information
------------------ -------------------------/dev/dsk/device-name
dump device (dedicated)
Cause
You attempted to remove or replace a dedicated dump device.

Solution
Unconfigure the dedicate dump device and retry the cfgadm operation.

How to Resolve a Failed SCSI Unconfigure Operation

Use this procedure if one or more target devices are busy and the SCSI unconfigure operation fails. Otherwise, future
dynamic reconfiguration operations on this controller and target devices will fail with a dr in progress message.
1.
2.

Become an administrator.
Reconfigure the controller.

# cfgadm -c configure device-name

Hot-Plugging USB Devices With the cfgadm Command

You can add and remove a USB device from a running system without using the cfgadm command.
However, a USB device can also be logically hot-plugged without physically removing the device. This
scenario is convenient when you are working remotely and you need to disable or reset a non functioning
USB device. The cfgadm command also provides a way to display the USB device tree, including
manufacturer and product information.
The cfgadm command displays information about attachment points, which are locations in the system
where dynamic reconfiguration operations can occur. An attachment point consists of the following:

An occupant, which represents a hardware resource, such as a USB device, that might be
configured into the system

A receptacle, which is the location that accepts the occupant, such as a USB port

Attachment points are represented by logical and physical attachment point IDs (Ap_Ids). The
physical Ap_Id is the physical path name of the attachment point. The logical Ap_Id is a user-friendly
alternative for the physical Ap_Id. For more information on Ap_Ids, see cfgadm_usb(1M).
The cfgadm command provides the following USB device status information.

Receptacle State
Description
The device is not physically connected.
empty/unconfigured
disconnected/unconfigured The device is logically disconnected and unavailable, even though
the device could still be physically connected.
The device is logically connected, but unavailable. The device is
connected/unconfigured
visible in prtconf output.

connected/configured

The device is connected and available.

The following sections describe how to hot-plug a USB device through the software with
the cfgadm command. All of the sample USB device information in these sections has been truncated to
focus on relevant information.

How to Display USB Bus Information (cfgadm)

For examples of using the prtconf command to display USB configuration information, see How to
Display USB Device Information.
1. Display USB bus information.
For example:
% cfgadm
Ap_Id
usb0/4.5
usb0/4.5.1
usb0/4.5.2
usb0/4.5.3
usb0/4.5.4
usb0/4.5.5
usb0/4.5.6
usb0/4.5.7

Type
usb-hub
usb-device
usb-printer
usb-mouse
usb-device
usb-storage
usb-communi
unknown

Receptacle
connected
connected
connected
connected
connected
connected
connected
empty

Occupant
configured
configured
configured
configured
configured
configured
configured
unconfigured

Condition
ok
ok
ok
ok
ok
ok
ok
ok

In the preceding example, usb0/4.5.1 identifies a device connected to port 1 of the second-level
external hub, which is connected to port 5 of first-level external hub, which is connected to the first
USB controller's root hub, port 4.
2. Display specific USB device information.
For example:
% cfgadm -l -s "cols=ap_id:info"
Ap_Id
Information
usb0/4.5.1 Mfg: Inside Out Networks Product: Edgeport/421 NConfigs: 1
Config: 0 : ...
usb0/4.5.2 Mfg: <undef> Product: <undef>
NConfigs: 1 Config: 0 ...
usb0/4.5.3 Mfg: Mitsumi Product: Apple USB Mouse NConfigs: 1
Config: 0 ...
usb0/4.5.4 Mfg: NMB Product: NMB USB KB/PS2 M NConfigs: 1 Config: 0
usb0/4.5.5 Mfg: Hagiwara Sys-Com Product: SmartMedia R/W NConfigs: 1
Config: 0 : ...
usb0/4.5.6 Mfg: 3Com Inc. Product: U.S.Robotics 56000 Voice USB Modem
NConfigs: 2 ...
usb0/4.5.7

How to Unconfigure a USB Device

You can unconfigure a USB device that is still physically connected to the system. However, a driver will
never attach to the device. Note that a USB device remains in the prtconf output even after that device
is unconfigured.
1. Become superuser.
2. Unconfigure the USB device.
For example:
# cfgadm -c unconfigure usb0/4.7
Unconfigure the device: /devices/pci@8,700000/usb@5,3/hub@4:4.7
This operation will suspend activity on the USB device
Continue (yes/no)? y
3. Verify that the device is unconfigured.
For example:
# cfgadm
Ap_Id
usb0/4.5
usb0/4.5.1
usb0/4.5.2
usb0/4.5.3
usb0/4.5.4
usb0/4.5.5
usb0/4.5.6
usb0/4.5.7
usb0/4.6
usb0/4.7

Type
usb-hub
usb-device
usb-printer
usb-mouse
usb-device
usb-storage
usb-communi
unknown
usb-storage
usb-storage

Receptacle
connected
connected
connected
connected
connected
connected
connected
empty
connected
connected

Occupant
configured
configured
configured
configured
configured
configured
configured
unconfigured
configured
unconfigured

Condition
ok
ok
ok
ok
ok
ok
ok
ok
ok
ok

How to Configure a USB Device

1. Become superuser.
2. Configure a USB device.
For example:
# cfgadm -c configure usb0/4.7
3. Verify that the USB device is configured.
For example:
# cfgadm usb0/4.7
Ap_Id
usb0/4.7

Type
usb-storage

Receptacle
connected

Occupant
configured

Condition
ok

How to Logically Disconnect a USB Device

If you want to remove a USB device from the system and the prtconf output, but you are not physically
near the system, just logically disconnect the USB device. The device is still physically connected.
However, the device is logically disconnected, unusable, and not visible to the system.
1. Become superuser.
2. Disconnect a USB device.
For example:
# cfgadm -c disconnect -y usb0/4.7
3. Verify that the device is disconnected.
For example:
# cfgadm usb0/4.7
Ap_Id
usb0/4.7

Type
unknown

Receptacle
disconnected

Occupant
unconfigured

Condition
ok

How to Logically Connect a USB Device

Use this procedure to logically connect a USB device that was previously logically disconnected or
unconfigured.
1. Become superuser.
2. Connect a USB device.
For example:
# cfgadm -c configure usb0/4.7
3. Verify that the device is connected.
For example:
# cfgadm usb0/4.7
Ap_Id
usb0/4.7

Type
usb-storage

Receptacle
connected

Occupant
configured

Condition
ok

The device is now available and visible to the system.

How to Logically Disconnect a USB Device

Subtree

Use this procedure to disconnect a USB device subtree, which is the hierarchy (or tree) of devices below
a hub.
1. Become superuser.
2. Remove a USB device subtree.
For example:
# cfgadm -c disconnect -y usb0/4
3. Verify that the USB device subtree is disconnected.
For example:
# cfgadm usb0/4
Ap_Id
usb0/4

Type
unknown

Receptacle
Occupant
Condition
disconnected unconfigured ok

How to Reset a USB Device

If a USB device behaves erratically, use the cfgadm command to reset the device, which logically
removes and re-creates the device.
1. Become superuser.
2. Make sure that the device is not in use.
3. Reset the device.
For example:
# cfgadm -x usb_reset -y usb0/4.7
4. Verify that the device is connected.
For example:
# cfgadm usb0/4.7
Ap_Id
usb0/4.7

Type
usb-storage

Receptacle
connected

Occupant
configured

Condition
ok

How to Change the Default Configuration of a

Multi-Configuration USB Device
Keep the following in mind when working with multi-configuration USB devices:

A USB device configuration defines how a device presents itself to the operating system. This
method is different from system device configurations discussed in other cfgadmsections.

Some USB devices support multiple configurations, but only one configuration can be active at a
time.

Multi-configuration devices can be identified by examining the cfgadm -lv output. Nconfigs will
be greater than 1.

The default USB configuration is configuration 1. The current configuration is reflected in cfgadm lv output as Config.

Changes to the default configuration persist across reboots, hot-removes, and the reconfiguration of
the device, as long as the device is reconnected to the same port.

1. Make sure that the device is not in use.

2. Change the default USB configuration.
For example:
# cfgadm -x usb_config -o config=2 usb0/4
Setting the device: /devices/pci@1f,0/usb@c,3:4
to USB configuration 2
This operation will suspend activity on the USB device
Continue (yes/no)? yes
3. Verify that the device changed.
For example:
# cfgadm -lv usb0/4
Ap_Id Receptacle
Occupant
Condition Information When Type
Busy
Phys_Id
usb0/4 connected
unconfigured ok
Mfg: Sun 2000
Product: USB-B0B0 aka Robotech
With 6 EPPS High Clk Mode
NConfigs: 7 Config: 2 : EVAL Board Setup
unavailable
usb-device
n
/devices/pci@1f,0/usb@c,3:4
Note that Config: now shows 2.