Chapter 28 Dynamically Configuring Devices (Tasks)

This chapter provides instructions for dynamically configuring devices in the Solaris environment. You can add, remove, or replace devices in the Solaris environment while the system is still running, if the system components support hot-plugging. If the system components do not support hot-plugging, you can reboot the system to reconfigure the devices.

For information on the procedures associated with dynamically configuring devices, see the following:

• SCSI Hot-Plugging With the cfgadm Command (Task Map)

• PCI Hot-Plugging With the cfgadm Command (Task Map)

• Application Developer RCM Script (Task Map)

• System Administrator RCM Script (Task Map)

For information on hot-plugging USB devices with the cfgadm command, see Hot-Plugging USB Devices With the cfgadm Command.

For information about accessing devices, see Chapter 30, Accessing Devices (Overview).

Dynamic Reconfiguration and Hot-Plugging

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. This term also refers to the general ability to move system resources (both hardware and software) around in the system or to disable them in some way without physically removing them from the system.

You can hot-plug the following devices with the cfgadm command:

• USB devices on SPARC and x86 platforms

• SCSI devices on SPARC and x86 platforms

• PCI devices on x86 platforms

Features of the cfgadm command include the following:

• Displaying system component status

• Testing system components

• Changing component configurations

• Displaying configuration help messages

The benefit of using the cfgadm command to reconfigure systems 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 system components.

For step-by-step instructions on hot-plugging SCSI components, see cfgadm(1M) and SCSI Hot-Plugging With the cfgadm Command. For step-by-step instructions on hot-plugging PCI adapter cards on x86 based systems, see x86: PCI Hot-Plugging With the cfgadm Command.

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

As part of Sun's high availability strategy, dynamic reconfiguration is expected to be used in conjunction with additional layered products, such as alternate pathing or fail-over software. Both products provide fault tolerance in the event of a device failure.

Without any high availability software, you can replace a failed device by manually stopping the appropriate applications, unmounting noncritical file systems, and then proceeding with the add or remove operations.

For information about hot-plugging devices on your specific hardware configuration, such as enterprise-level systems, please refer to your hardware configuration documentation.

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 the following:

• An occupant, which represents a hardware component that can be configured into the system

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

Attachment points are represented by logical and physical attachment point IDs (Ap_Ids). The physical Ap_Id is the physical pathname of the attachment point. The logical Ap_Id is a user-friendly alternative for the physical Ap_Id. For more information on Ap_Ids, refer to cfgadm(1M).

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 the following:

fas1:scsi

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

HBA-logical-apid::device-identifier

In the following example, 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 /dev/rmt/1 tape device is the following:

c0::st4

For more information on SCSI Ap_Ids, refer to cfgadm_scsi(1M).

The cfgadm command represents all resources and dynamic reconfiguration operations in terms of a common set of states (such as configured, unconfigured) and operations (connect, configure, unconfigure, and so on). For more information on these common states and operations, see cfgadm(1M).

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

Receptacle and occupant states for SCSI device attachment points are as follows:

The state of SCSI attachment points is unknown unless there is special hardware to indicate otherwise. For instructions on displaying SCSI component information, see How to Display Information About SCSI Devices.

x86: Detaching PCI Adapter Cards

A PCI adapter card that is hosting nonvital system resources can be removed if the device driver supports hot-plugging. A PCI adapter card is not detachable if it is a vital system resource. For a PCI adapter card to be detachable the following conditions must be met:

• The device driver must support hot-plugging.

• Critical resources must be accessible through an alternate pathway.

For example, if a system has only one Ethernet card installed in it, the Ethernet card cannot be detached without losing the network connection. This detachment requires additional layered software support to keep the network connection active.

x86: Attaching PCI Adapter Cards

A PCI adapter card can be added to the system as long as the following conditions are met:

• There are slots available.

• The device driver supports hot-plugging for this adapter card.

For step-by-step instructions on adding or removing a PCI adapter card, see x86: PCI Hot-Plugging With the cfgadm Command.

SCSI Hot-Plugging With the cfgadm Command (Task Map)

SCSI Hot-Plugging With the cfgadm Command

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

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.

How to Display Information About SCSI Devices

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

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

1. Become superuser.

2. Display information about attachment points on the system.

   # cfgadm -l Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c1 scsi-bus connected configured unknown

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

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

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 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.

   ---

In the following procedures, only SCSI attachment points are listed. The attachment points that are displayed on your system depend on your system configuration.

How to Unconfigure a SCSI Controller

The following procedure uses SCSI controller c1 as an example of unconfiguring a SCSI controller.

1. Become superuser.

2. Unconfigure a SCSI controller.

   # cfgadm -c unconfigure c1

3. Verify that the SCSI controller is unconfigured.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected unconfigured 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 as an example of configuring a SCSI controller.

1. Become superuser.

2. Configure a SCSI controller.

   # cfgadm -c configure c1

3. Verify that the SCSI controller is configured.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 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 as an example of configuring a SCSI device.

1. Become superuser.

2. Identify the device to be configured.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 unavailable connected unconfigured unknown

3. Configure the SCSI device.

   # cfgadm -c configure c1::dsk/c1t4d0

4. Verify that the SCSI device is configured.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

How to Disconnect a SCSI Controller

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 as an example of disconnecting a SCSI device.

1. Become superuser.

2. Verify that the device is connected before you disconnect it.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

3. Disconnect the 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 can result in a system hang and could require a system reboot.

   ---

4. Verify that the SCSI bus is disconnected.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 unavailable disconnected configured unknown c1::dsk/c1t10d0 unavailable disconnected configured unknown c1::dsk/c1t4d0 unavailable disconnected configured unknown

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

How to Connect a SCSI Controller

The following procedure uses SCSI controller c1 as an example of connecting a SCSI controller.

1. Become superuser.

2. Verify that the device is disconnected before you connect it.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 unavailable disconnected configured unknown c1::dsk/c1t10d0 unavailable disconnected configured unknown c1::dsk/c1t4d0 unavailable disconnected configured unknown

3. Connect the SCSI controller.

   # cfgadm -c connect c1

4. Verify that the SCSI controller is connected.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

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

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

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. Become superuser.

2. Identify the current SCSI configuration.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown

3. Add the SCSI device to the 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

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

      Continue (yes/no)? y 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.

   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.

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

4. Verify that the device has been added.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured 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 as an example of replacing an identical device on a SCSI controller.

1. Become superuser.

2. Identify the current SCSI configuration.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk 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

   1. 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.

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

   3. 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

   4. 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

4. Verify that the device has been replaced.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

SPARC: How to Remove a SCSI Device

The following procedure uses SCSI disk c1t4d0 as an example of removing a device on a SCSI controller.

1. Become superuser.

2. Identify the current SCSI configuration.

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown c1::dsk/c1t4d0 disk connected configured unknown

3. Remove the 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

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

      Continue (yes/no)? y 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.

   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.

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

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

   # cfgadm -al Ap_Id Type Receptacle Occupant Condition c0 scsi-bus connected configured unknown c0::dsk/c0t0d0 disk connected configured unknown c0::rmt/0 tape connected configured unknown c1 scsi-bus connected configured unknown c1::dsk/c1t3d0 disk connected configured unknown

SPARC: 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, see cfgadm(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.

If you use the cfgadm command to remove a system resource, such as a swap device or a dedicated dump device, an error messages similar to the following is displayed if the system resource is still active.

Error Message

cfgadm: Component system is busy, try again: failed to offline: device path Resource Information ------------------ -------------------------- /dev/dsk/device-name swap area

Cause

You attempted to remove or replace one or more configured swap areas.

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. Become superuser, if not done already.

2. Type the following command to reconfigure the controller.

   # cfgadm -c configure device-name

PCI Hot-Plugging With the cfgadm Command (Task Map)

x86: PCI Hot-Plugging With the cfgadm Command

This section provides step-by-step instructions for hot-plugging PCI adapter cards on x86 based systems.

In the examples, only PCI attachment points are listed, for brevity. The attachment points that are displayed on your system depend on your system configuration.

x86: How to Display PCI Slot Configuration Information

The cfgadmin command displays the status of PCI hot-pluggable devices and slots on a system. For more information, see cfgadm(1M).

1. Become superuser.

2. Display PCI slot configuration information.

   # cfgadm Ap_Id Type Receptacle Occupant Condition pci1:hpc0_slot0 unknown empty unconfigured unknown pci1:hpc0_slot1 unknown empty unconfigured unknown pci1:hpc0_slot2 unknown empty unconfigured unknown pci1:hpc0_slot3 ethernet/hp connected configured ok pci1:hpc0_slot4 unknown empty unconfigured unknown

   Display specific PCI device information.

   # cfgadm -s "cols=ap_id:type:info" pci Ap_Id Type Information pci1:hpc0_slot0 unknown Slot 7 pci1:hpc0_slot1 unknown Slot 8 pci1:hpc0_slot2 unknown Slot 9 pci1:hpc0_slot3 ethernet/hp Slot 10 pci1:hpc0_slot4 unknown Slot 11

The logical Ap_Id, pci1:hpc0_slot0, is the logical Ap_Id for hot-pluggable slot, Slot 7. The component hpc0 indicates the hot-pluggable adapter card for this slot, and pci1 indicates the PCI bus instance. The Type field indicates the type of PCI adapter card that is present in the slot.

x86: How to Remove a PCI Adapter Card

1. Become superuser.

2. Determine which slot the PCI adapter card is in.

   # cfgadm Ap_Id Type Receptacle Occupant Condition pci1:hpc0_slot0 unknown empty unconfigured unknown pci1:hpc0_slot1 unknown empty unconfigured unknown pci1:hpc0_slot2 unknown empty unconfigured unknown pci1:hpc0_slot3 ethernet/hp connected configured ok pci1:hpc0_slot4 unknown empty unconfigured unknown

3. Stop the application that has the device open.

   For example, if the device is an Ethernet card, use the ifconfig command to bring down the interface and unplumb the interface.

4. Unconfigure the device.

   # cfgadm -c unconfigure pci1:hpc0_slot3

5. Confirm that the device has been unconfigured.

   # cfgadm Ap_Id Type Receptacle Occupant Condition pci1:hpc0_slot0 unknown empty unconfigured unknown pci1:hpc0_slot1 unknown empty unconfigured unknown pci1:hpc0_slot2 unknown empty unconfigured unknown pci1:hpc0_slot3 ethernet/hp connected unconfigured unknown pci1:hpc0_slot4 unknown empty unconfigured unknown

6. Disconnect the power to the slot.

   # cfgadm -c disconnect pci1:hpc0_slot3

7. Confirm that the device has been disconnected.

   # cfgadm Ap_Id Type Receptacle Occupant Condition pci1:hpc0_slot0 unknown empty unconfigured unknown pci1:hpc0_slot1 unknown empty unconfigured unknown pci1:hpc0_slot2 unknown empty unconfigured unknown pci1:hpc0_slot3 ethernet/hp disconnected unconfigured unknown pci1:hpc0_slot4 unknown empty unconfigured unknown

8. Open the slot latches and remove the PCI adapter card.

x86: How to Add a PCI Adapter Card

1. Become superuser.

2. Identify the hot-pluggable slot and open latches.

3. Insert the PCI adapter card into a hot-pluggable slot.

4. Determine which slot the PCI adapter card is in once it is inserted. Close the latches.

   # cfgadm Ap_Id Type Receptacle Occupant Condition pci1:hpc0_slot0 unknown empty unconfigured unknown pci1:hpc0_slot1 unknown empty unconfigured unknown pci1:hpc0_slot2 unknown empty unconfigured unknown pci1:hpc0_slot3 ethernet/hp disconnected unconfigured unknown pci1:hpc0_slot4 unknown empty unconfigured unknown

5. Connect the power to the slot.

   # cfgadm -c connect pci1:hpc0_slot3

6. Confirm that the slot is connected.

   # cfgadm Ap_Id Type Receptacle Occupant Condition pci1:hpc0_slot0 unknown empty unconfigured unknown pci1:hpc0_slot1 unknown empty unconfigured unknown pci1:hpc0_slot2 unknown empty unconfigured unknown pci1:hpc0_slot3 ethernet/hp connected unconfigured unknown pci1:hpc0_slot4 unknown empty unconfigured unknown

7. Configure the PCI adapter card.

   # cfgadm -c configure pci1:hpc0_slot3

8. Verify the configuration of the PCI adapter card in the slot.

   # cfgadm Ap_Id Type Receptacle Occupant Condition pci1:hpc0_slot0 unknown empty unconfigured unknown pci1:hpc0_slot1 unknown empty unconfigured unknown pci1:hpc0_slot2 unknown empty unconfigured unknown pci1:hpc0_slot3 ethernet/hp connected configured unknown pci1:hpc0_slot4 unknown empty unconfigured unknown

9. Configure any supporting software if this device is a new device.

   For example, if this device is an Ethernet card, use the ifconfig command to set up the interface.

x86: Troubleshooting PCI Configuration Problems

Error Message

cfgadm: Configuration operation invalid: invalid transition

Cause

An invalid transition was attempted.

Solution

Check whether the cfgadm -c command was issued appropriately. Use the cfgadm command to check the current receptacle and occupant state and to make sure that the Ap_Id is correct.

Error Message

cfgadm: Attachment point not found

Cause

The specified attachment point was not found.

Solution

Check whether the attachment point is correct. Use the cfgadm command to display a list of available attachment points. Also check the physical path to see if the attachment point is still there.

In addition to the cfgadm command, several other commands are helpful during hot-pluggable operations. The prtconf command displays whether Solaris recognizes the hardware. After adding hardware, use the prtconf command to verify that the hardware is recognized. After a configure operation, use the prtconf -D command to verify that the driver is attached to the newly installed hardware device.

Reconfiguration Coordination Manager (RCM) Script Overview

The Reconfiguration Coordination Manager (RCM) is the framework that manages the dynamic removal of system components. By using RCM, you can register and release system resources in an orderly manner.

You can use the new RCM script feature to write your own scripts to shut down your applications, or to cleanly release the devices from your applications during dynamic reconfiguration. The RCM framework launches a script automatically in response to a reconfiguration request, if the request impacts the resources that are registered by the script.

You can also release resources from applications manually before you could dynamically remove the resource. Or, you could use the cfgadm command with the -f option to force a reconfiguration operation, but this option might leave your applications in an unknown state. Also, the manual release of resources from applications commonly causes errors.

The RCM script feature simplifies and better controls the dynamic reconfiguration process. By creating an RCM script, you can do the following:

• Automatically release a device when you dynamically remove a device. This process also closes the device if the device is opened by an application.

• Run site-specific tasks when you dynamically remove a device from the system.

What Is an RCM Script?

An RCM script is as follows:

• An executable shell script (Perl, sh, csh, or ksh) or binary program that the RCM daemon runs. Perl is the recommended language.

• A script that runs in its own address space by using the user ID of the script file owner.

• A script that is run by the RCM daemon when you use the cfgadm command to dynamically reconfigure a system resource.

What Can an RCM Script Do?

You can use an RCM script to release a device from an application when you dynamically remove a device. If the device is currently open, the RCM script also closes the device.

For example, an RCM script for a tape backup application can inform the tape backup application to close the tape drive or shut down the tape backup application.

How Does the RCM Script Process Work?

You can invoke a script as follows:

$ script-name command [args ...]

A script performs the following basic steps:

1. Takes the RCM command from command-line arguments.

2. Executes the command.

3. Writes the results to stdout as name-value pairs.

4. Exits with the appropriate exit status.

The RCM daemon runs one instance of a script at a time. For example, if a script is running, the RCM daemon does not run the same script until the first script exits.

RCM Script Commands

You must include the following RCM commands in an RCM script:

• scriptinfo - Gathers script information

• register - Registers interest in resources

• resourceinfo - Gathers resource information

You might include some or all of the following RCM commands:

• queryremove - Queries whether the resource can be released

• preremove - Releases the resource

• postremove - Provides post-resource removal notification

• undoremove - Undoes the actions done in preremove

For a complete description of these RCM commands, see rcmscript(4).

RCM Script Processing Environment

When you dynamically remove a device, the RCM daemon runs the following:

• The script's register command to gather the list of resources (device names) that are identified in the script.

• The script's queryremove/preremove commands prior to removing the resource if the script's registered resources are affected by the dynamic remove operation.

• The script's postremove command if the remove operation succeeds. However, if the remove operation fails, the RCM daemon runs the script's undoremove command.

RCM Script Tasks

The following sections describe the RCM script tasks for application developers and system administrators.

Application Developer RCM Script (Task Map)

The following task map describes the tasks for an application developer who is creating an RCM script.

System Administrator RCM Script (Task Map)

The following task map describes the tasks for a system administrator who is creating an RCM script to do site customization.

Naming an RCM Script

A script must be named as vendor,service where the following applies:

Installing or Removing an RCM Script

You must be superuser (root) to install or remove an RCM script. Use this table to determine where you should install your RCM script.

How to Install an RCM Script

1. Become superuser.

2. Copy the script to the appropriate directory as described in Table 28–1.

   For example:

   # cp SUNW,sample.pl /usr/lib/rcm/scripts

3. Change the user ID and the group ID of the script to the desired values.

   # chown user:group /usr/lib/rcm/scripts/SUNW,sample.pl

4. Send SIGHUP to the RCM daemon.

   # pkill -HUP -x -u root rcm_daemon

How to Remove an RCM Script

1. Become superuser.

2. Remove the script from the RCM script directory.

   For example:

   # rm /usr/lib/rcm/scripts/SUNW,sample.pl

3. Send SIGHUP to the RCM daemon.

   # pkill -HUP -x -u root rcm_daemon

How to Test an RCM Script

1. Set environment variables, such as RCM_ENV_FORCE, in the command-line shell before running your script.

   For example, in the Korn shell, use the following:

   $ export RCM_ENV_FORCE=TRUE

2. Test the script by running the script commands manually from the command line.

   For example:

   $ script-name scriptinfo $ script-name register $ script-name preremove resource-name $ script-name postremove resource-name

3. Make sure each RCM script command in your script prints appropriate output to stdout.

4. Install the script in the appropriate script directory.

   For more information, see How to Install an RCM Script.

5. Test the script by initiating a dynamic remove operation:

   For example, assume your script registers the device, /dev/dsk/c1t0d0s0. Try these commands.

   $ cfgadm -c unconfigure c1::dsk/c1t0d0 $ cfgadm -f -c unconfigure c1::dsk/c1t0d0 $ cfgadm -c configure c1::dsk/c1t0d0

   ---

   Caution –

   Make sure that you are familiar with these commands because they can alter the state of the system and can cause system failures.

   ---

Tape Backup RCM Script Example

This example illustrates how to use an RCM script for tape backups.

What the Tape Backup RCM Script Does

The tape backup RCM script performs the following steps:

1. Sets up a dispatch table of RCM commands.

2. Calls the dispatch routine that corresponds to the specified RCM command and exits with status 2 for unimplemented RCM commands.

3. Sets up the scriptinfo section:

   rcm_script_func_info=Tape backup appl script for DR

4. Registers all tape drives in the system by printing all tape drive device names to stdout.

   rcm_resource_name=/dev/rmt/$f

   If an error occurs, prints the error information to stdout.

   rcm_failure_reason=$errmsg

5. Sets up the resource information for the tape device.

   rcm_resource_usage_info=Backup Tape Unit Number $unit

6. Sets up the preremove information by checking if the backup application is using the device. If the backup application is not using the device, the dynamic reconfiguration operation continues. If the backup application is using the device, the script checks RCM_ENV_FORCE. If RCM_ENV_FORCE is set to FALSE, the script denies the dynamic reconfiguration operation and prints the following message:

   rcm_failure_reason=tape backup in progress pid=...

   If RCM_ENV_FORCE is set to TRUE, the backup application is stopped, and the reconfiguration operation proceeds.

Outcomes of the Tape Backup Reconfiguration Scenarios

Here are the various outcomes if you use the cfgadm command to remove a tape device without the RCM script.

• If you use the cfgadm command and the backup application is not using the tape device, the operation succeeds.

• If you use the cfgadm command and the backup application is using the tape device, the operation fails.

Here are the various outcomes if you use the cfgadm command to remove a tape device with the RCM script.

• If you use the cfgadm command and the backup application is not using the tape device, the operation succeeds.

• If you use the cfgadm command without the -f option and the backup application is using the tape device, the operation fails with an error message similar to the following:

  tape backup in progress pid=...

• If you use the cfgadm -f command and the backup application is using the tape device, the script stops the backup application and the cfgadm operation succeeds.

Example—Tape Backup RCM Script

#! /usr/bin/perl -w
   #
   # A sample site customization RCM script.
   #
   # When RCM_ENV_FORCE is FALSE this script indicates to RCM that it cannot
   # release the tape drive when the tape drive is being used for backup.
   #
   # When RCM_ENV_FORCE is TRUE this script allows DR removing a tape drive
   # when the tape drive is being used for backup by killing the tape
   # backup application.
   #
    
    use strict;
    
    my ($cmd, %dispatch);
    $cmd = shift(@ARGV);
# dispatch table for RCM commands
    %dispatch = (
            "scriptinfo"    =>      \&do_scriptinfo,
            "register"      =>      \&do_register,
            "resourceinfo"  =>      \&do_resourceinfo,
            "queryremove"   =>      \&do_preremove,
            "preremove"     =>      \&do_preremove
    );
    
    
    if (defined($dispatch{$cmd})) {
            &{$dispatch{$cmd}};
    } else {
            exit (2);
    }
    
    sub do_scriptinfo
    {
            print "rcm_script_version=1\n";
            print "rcm_script_func_info=Tape backup appl script for DR\n";
            exit (0);
    }
    
    sub do_register
{
            my ($dir, $f, $errmsg);
    
            $dir = opendir(RMT, "/dev/rmt");
            if (!$dir) {
                 $errmsg = "Unable to open /dev/rmt directory: $!";
                 print "rcm_failure_reason=$errmsg\n";
                 exit (1);
            }
    
            while ($f = readdir(RMT)) {
                # ignore hidden files and multiple names for the same device
                if (($f !~ /^\./) && ($f =~ /^[0-9]+$/)) {
                        print "rcm_resource_name=/dev/rmt/$f\n";
                    }
                    
            }
    
            closedir(RMT);
            exit (0);
    }
sub do_resourceinfo
    {
      my ($rsrc, $unit);
    
      $rsrc = shift(@ARGV);
      if ($rsrc =~ /^\/dev\/rmt\/([0-9]+)$/) {
           $unit = $1;
           print "rcm_resource_usage_info=Backup Tape Unit Number $unit\n";
           exit (0);
       } else {
           print "rcm_failure_reason=Unknown tape device!\n";
            exit (1);
        }
    }
    
    sub do_preremove
    {
            my ($rsrc);
    
            $rsrc = shift(@ARGV);
    
            # check if backup application is using this resource
            #if (the backup application is not running on $rsrc) {
                    # allow the DR to continue
            #        exit (0);
            #}
            #
            # If RCM_ENV_FORCE is FALSE deny the operation.
            # If RCM_ENV_FORCE is TRUE kill the backup application in order
            # to allow the DR operation to proceed
            #
            if ($ENV{RCM_ENV_FORCE} eq 'TRUE') {
                 if ($cmd eq 'preremove') {
                         # kill the tape backup application
                 }
                 exit (0);
            } else {
               #
               # indicate that the tape drive can not be released
               # since the device is being used for backup by the
               # tape backup application
               #
               print "rcm_failure_reason=tape backup in progress pid=...\n"
;
               exit (3);
            }
    }