SCSI Hot-Plugging Features (cfgadm)

The cfgadm command is updated in the Solaris 7 8/99 software release to provide SCSI hot-plugging for supported SCSI controllers. This information supplements information on managing devices found in "Managing Devices" in System Administration Guide, Volume I.

Hot-plugging is the ability to physically add, remove, or replace system components while the system is running. Dynamic reconfiguration refers to the ability to hot-plug system components and also the general ability to move system resources--both hardware and software--around in the system, or to disable them without removing them from the system.

Features of the cfgadm command include:

• Displaying system component status

• Testing system components

• Changing component configurations

• Displaying configuration help messages

The benefit of using the cfgadm command to reconfigure SCSI components is that you can add, remove, or replace components while the system is running. An added benefit is that the cfgadm command guides you through the steps needed to add, remove, or replace SCSI components. See the man page cfgadm(1M) and "SCSI Hot-Plugging With the cfgadm Command" for step-by-step instructions on hot-plugging SCSI components.

---

Note -

Not all SCSI controllers support hot-plugging with the cfgadm command.

---

Attachment Points

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:

• An occupant, which represents a hardware resource that may be configured into the system, and

• A receptacle, which is the location that accepts the occupant resource

Attachment points are named by logical and physical attachment point IDs (ap_id). The physical ap_id is the physical pathname of the attachment point. The logical ap_id is a user-friendly name that represents the physical attachment point pathname. Refer to cfgadm(1M) for more information on ap_id.

The logical ap_id for a SCSI host bus adapter (HBA), or SCSI controller, is usually represented by the controller number, such as c0.

In cases where no controller number has been assigned to a SCSI HBA, then an internally-generated unique identifier is provided. An example of a unique identifier for a SCSI controller is:

fas1:scsi

The logical ap_id for a SCSI device usually looks like this:

HBA-logical-apid::device-identifier

In the example below, c0 is the logical ap_id for the SCSI HBA:

c0::dsk/c0t3d0

The device identifier is typically derived from the logical device name for the device in the /dev directory. For example, a tape device with logical device name, /dev/rmt/1, has the following logical ap_id:

c0::rmt/1

If a logical ap_id of a SCSI device cannot be derived from the logical name in the /dev directory, then an internally-generated unique identifier is provided. An example of an identifier for the tape device /dev/rmt/1 is:

c0::st4

Refer to the man page cfgadm_scsi(1M) for more information on SCSI ap_ids.

The cfgadm command represents all resources and dynamic reconfiguration operations in terms of a common set of states (such as configured, unconfigured) and set of operations (connect, configure, unconfigure). Refer to the man page cfgadm(1M) for more information on these generic states and operations.

The receptacle and occupant states for the SCSI HBA attachment points are:

Receptacle	Description	Occupant	Description
empty	N/A to SCSI HBA	configured	One or more devices configured on the bus
disconnected	Bus quiesced	unconfigured	No devices configured
connected	Bus active

Receptacle and occupant state mappings for SCSI devices are:

Receptacle	Description	Occupant	Description
empty	N/A to SCSI devices	configured	Device is configured
disconnected	Bus quiesced	unconfigured	Device is not configured
connected	Bus active

The condition of SCSI attachment points is "unknown" unless there is special hardware to indicate otherwise. See "How to Display Configuration Information for All Devices" for instructions on displaying SCSI component configuration information.

SCSI Hot-Plugging With the cfgadm Command

The following section describes various SCSI hot-plugging tasks with the cfgadm command.

The procedures in this section use specific devices as examples to illustrate how to use the cfgadm command to hot plug SCSI components. The device information you supply, and that is displayed with the cfgadm command, will depend on your system configuration.

How to Display Configuration Information for All Devices

SCSI controllers c0 and c1 and the devices attached to them are examples of the type of device configuration information that can be displayed with the cfgadm command.

---

Note -

If the SCSI device is not supported by the cfgadm command, it will not display in the cfgadm command output.

---

1. Become superuser.

2. Display information about attachment points on the system.

   # cfgadm -l Ap_Id Receptacle Occupant Condition ac0:bank0 connected configured ok ac0:bank1 connected configured ok c0 connected configured unknown c1 connected configured unknown sysctrl0:slot0 connected configured ok sysctrl0:slot1 connected configured ok

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

   The other ap_ids such as ac0:bank1 and sysctrl0:slot0 in the command output represent other types of system components.

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

   # cfgadm -al Ap_Id Receptacle Occupant Condition ac0:bank0 connected configured ok ac0:bank1 connected configured ok c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected configured unknown c2 connected unconfigured unknown sysctrl0:slot0 connected configured ok sysctrl0:slot1 connected configured ok

   Notice that SCSI HBAs are displayed in the cfgadm -l output but not SCSI devices. The cfgadm -al command displays information about SCSI devices such as disks and tapes.

How to Unconfigure a SCSI Controller

SCSI controller c1 provides an example of unconfiguring a SCSI controller.

Only SCSI attachment points are listed. The attachment points displayed on your system will depend on your system configuration.

1. Become superuser.

2. Unconfigure a SCSI controller.

   # cfgadm -c unconfigure c1

3. Verify the SCSI controller is unconfigured.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected unconfigured unknown

   Notice that the Occupant column specifies unconfigured for c1, indicating that the SCSI bus has no configured occupants.

How to Configure a SCSI Controller

SCSI controller c1 provides an example of configuring a SCSI controller.

Only SCSI attachment points are listed. The attachment points displayed on your system will depend on your system configuration.

1. Become superuser.

2. Configure a SCSI controller.

   # cfgadm -c configure c1

3. Verify the SCSI controller is configured.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected configured 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

SCSI disk c1t4d0 provides an example of configuring a SCSI device.

Only SCSI attachment points are listed. The attachment points displayed on your system will depend on your system configuration.

1. Become superuser.

2. Identify the device to be configured.

   cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected unconfigured unknown

3. Configure a specific SCSI device.

   # cfgadm -c configure c1::dsk/c1t4d0

4. Verify the SCSI device is configured.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected configured unknown

How to Disconnect a SCSI Controller

Disconnecting a SCSI device must be done with caution, particularly when dealing with controllers for disks containing critical file systems such as root /, usr, var, and the swap partition. The dynamic reconfiguration software cannot detect all cases where a system hang may result. Use this command with caution.

SCSI controller c1 provides an example of disconnecting a SCSI device.

1. Become superuser.

2. Verify the device is connected before disconnecting it.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected configured unknown

3. Disconnect a SCSI controller.

   # 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 may result in a system hang and could require a system reboot.

   ---

4. Verify the SCSI bus is disconnected.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 disconnected configured unknown c1::dsk/c1t10d0 disconnected configured unknown c1::dsk/c1t4d0 disconnected configured unknown

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

How to Connect a SCSI Controller

SCSI controller c1 provides an example of connecting a SCSI controller.

Only SCSI attachment points are listed. The attachment points displayed on your system will depend on your system configuration.

1. Become superuser.

2. Verify the device is disconnected before connecting it.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 disconnected configured unknown c1::dsk/c1t10d0 disconnected configured unknown c1::dsk/c1t4d0 disconnected configured unknown

3. Connect a SCSI controller.

   # cfgadm -c connect c1

4. Verify the SCSI controller is connected.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected configured unknown

How to Add a SCSI Device to a SCSI Bus

SCSI controller c1 provides an example of adding a SCSI device to a SCSI bus.

Only SCSI attachment points are listed. The attachment points displayed on your system will depend on your system configuration.

---

Note -

When adding devices, the ap_id of the SCSI HBA (controller) to which the device is attached is specified, not the ap_id of the device itself.

---

1. Become superuser.

2. Identify the current SCSI configuration.

   # cfgadm -al ap_id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown

3. Add a SCSI device to a SCSI bus.

   # 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 Continue (yes/no)? y SCSI bus quiesced successfully. It is now safe to proceed with hotplug operation. Enter y if operation is complete or n to abort (yes/no)? y

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

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

   2. Connect the device and then power it on.

   3. Type y at the Enter y if operation is complete or n to abort (yes/no)? prompt after the new device has been inserted.

4. Verify the device has been added.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected configured unknown

   A new disk has been added to controller c1.

How to Replace an Identical Device on a SCSI Controller

SCSI disk c1t4d0 provides an example replacing an identical device on a SCSI controller.

Only SCSI attachment points are listed. The attachment points displayed on your system will depend on your system configuration.

1. Become superuser.

2. Identify the current SCSI configuration.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected configured unknown

3. Replace a device on the SCSI bus with another device of the same type.

   # 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 Continue (yes/no)? y SCSI bus quiesced successfully. It is now safe to proceed with hotplug operation. Enter y if operation is complete or n to abort (yes/no)? y

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

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

   2. Power off the device to be removed and remove it. Add the replacement device, which should be of the same type and at the same address (target and lun) as the device to be removed. Then power it on.

   3. Type y at the Enter y if operation is complete or n to abort (yes/no)? prompt after the device has been replaced.

4. Verify the device has been replaced.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected configured unknown

How to Remove a SCSI Device

SCSI disk c1t4d0 provides an example of removing a device on a SCSI controller.

Only SCSI attachment points are listed. The attachment points displayed on your system will depend on your system configuration.

1. Become superuser.

2. Identify the current SCSI configuration.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown c1::dsk/c1t4d0 connected configured unknown

3. Remove a SCSI device from the system.

   # 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 Continue (yes/no)? y SCSI bus quiesced successfully. It is now safe to proceed with hotplug operation. Enter y if operation is complete or n to abort (yes/no)? y

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

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

   2. Power off the device to be removed and remove it.

   3. Type y at the Enter y if operation is complete or n to abort (yes/no)? prompt after the device has been removed.

4. Verify the device has been removed from the system.

   # cfgadm -al Ap_Id Receptacle Occupant Condition c0 connected configured unknown c0::dsk/c0t0d0 connected configured unknown c0::rmt/0 connected configured unknown c1 connected configured unknown c1::dsk/c1t10d0 connected configured unknown