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:
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).
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.
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 State |
Description |
Occupant State |
Description |
---|---|---|---|
empty |
N/A for SCSI HBA |
configured |
One or more devices configured on the bus |
disconnected |
Bus quiesced |
unconfigured |
No devices configured |
connected |
Bus active |
|
|
Receptacle and occupant states for SCSI device attachment points are as follows:
Receptacle State |
Description |
Occupant State |
Description |
---|---|---|---|
empty |
N/A for SCSI devices |
configured |
Device is configured |
disconnected |
Bus quiesced |
unconfigured |
Device is not configured |
connected |
Bus active |
|
|
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.
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.
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.
Task |
Description |
For Instructions |
---|---|---|
1. Display information about SCSI devices |
Display information about SCSI controllers and devices. | |
2. Unconfigure a SCSI controller |
Unconfigure a SCSI controller. | |
3. Configure a SCSI controller |
Configure a SCSI controller that was previously unconfigured. | |
4. Configure a SCSI device |
Configure a specific SCSI device. | |
5. Disconnect a SCSI controller |
Disconnect a specific SCSI controller. | |
6. Connect a SCSI controller |
Connect a specific SCSI controller that was previously disconnected. | |
7. Add a SCSI device to a SCSI bus |
Add a specific SCSI device to a SCSI bus. | |
8. Replace an identical device on a SCSI controller |
Replace a device on the SCSI bus with another device of the same type. |
SPARC: How to Replace an Identical Device on a SCSI Controller |
9. Remove a SCSI device |
Remove a SCSI device from the system. | |
10. Troubleshooting SCSI configuration problems |
Resolve a failed SCSI unconfigure operation. |
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.
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.
Become superuser.
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.
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 |
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.
The following procedure uses SCSI controller c1 as an example of unconfiguring a SCSI controller.
Become superuser.
Unconfigure a SCSI controller.
# cfgadm -c unconfigure c1 |
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.
The following procedure uses SCSI controller c1 as an example of configuring a SCSI controller.
Become superuser.
Configure a SCSI controller.
# cfgadm -c configure c1 |
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.
The following procedure uses SCSI disk c1t4d0 as an example of configuring a SCSI device.
Become superuser.
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 |
Configure the SCSI device.
# cfgadm -c configure c1::dsk/c1t4d0 |
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 |
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.
Become superuser.
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 |
Disconnect the SCSI controller.
# cfgadm -c disconnect c1 WARNING: Disconnecting critical partitions may cause system hang. Continue (yes/no)? y |
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.
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.
The following procedure uses SCSI controller c1 as an example of connecting a SCSI controller.
Become superuser.
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 |
Connect the SCSI controller.
# cfgadm -c connect c1 |
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 |
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.
Become superuser.
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 |
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 |
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.
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 |
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.
The following procedure uses SCSI disk c1t4d0 as an example of replacing an identical device on a SCSI controller.
Become superuser.
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 |
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 |
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. |
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
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 |
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 |
The following procedure uses SCSI disk c1t4d0 as an example of removing a device on a SCSI controller.
Become superuser.
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 |
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 |
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.
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 |
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 |
This section provides error messages and possible solutions for troubleshooting SCSI configuration problems. For more information on troubleshooting SCSI configuration problems, see cfgadm(1M).
cfgadm: Component system is busy, try again: failed to offline: device path Resource Information ------------------ -------------------------- /dev/dsk/c1t0d0s0 mounted filesystem "/file-system" |
You attempted to remove or replace a device with a mounted file system.
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.
cfgadm: Component system is busy, try again: failed to offline: device path Resource Information ------------------ -------------------------- /dev/dsk/device-name swap area |
You attempted to remove or replace one or more configured swap areas.
Unconfigure the swap areas on the device that is specified and retry the cfgadm operation.
cfgadm: Component system is busy, try again: failed to offline: device path Resource Information ------------------ -------------------------- /dev/dsk/device-name dump device (swap) |
You attempted to remove or replace a dump device that is configured on a swap area.
Unconfigure the dump device that is configured on the swap area and retry the cfgadm operation.
cfgadm: Component system is busy, try again: failed to offline: device path Resource Information ------------------ -------------------------- /dev/dsk/device-name dump device (dedicated) |
You attempted to remove or replace a dedicated dump device.
Unconfigure the dedicate dump device and retry the cfgadm 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.
Become superuser, if not done already.
Type the following command to reconfigure the controller.
# cfgadm -c configure device-name |
Task |
Description |
For Instructions |
---|---|---|
1. Display PCI Slot Configuration Information |
Display the status of PCI hot-pluggable devices and slots on the system. | |
2. Remove a PCI adapter card |
Unconfigure the card, disconnect power from the slot, and remove the card from the system. | |
3. Add a PCI adapter card |
Insert the adapter card into a hot-pluggable slot, connect power to the slot, and configure the card. | |
4. Troubleshooting PCI configuration problems |
Identify error message and possible solutions to resolve PCI configuration problems. |
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.
The cfgadmin command displays the status of PCI hot-pluggable devices and slots on a system. For more information, see cfgadm(1M).
Become superuser.
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.
Become superuser.
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 |
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.
Unconfigure the device.
# cfgadm -c unconfigure pci1:hpc0_slot3 |
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 |
Disconnect the power to the slot.
# cfgadm -c disconnect pci1:hpc0_slot3 |
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 |
Open the slot latches and remove the PCI adapter card.
Become superuser.
Insert the PCI adapter card into a hot-pluggable slot.
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 |
Connect the power to the slot.
# cfgadm -c connect pci1:hpc0_slot3 |
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 |
Configure the PCI adapter card.
# cfgadm -c configure pci1:hpc0_slot3 |
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 |
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.
cfgadm: Configuration operation invalid: invalid transition |
An invalid transition was attempted.
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.
cfgadm: Attachment point not found |
The specified attachment point was not found.
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.
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.
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.
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.
You can invoke a script as follows:
$ script-name command [args ...] |
A script performs the following basic steps:
Takes the RCM command from command-line arguments.
Executes the command.
Writes the results to stdout as name-value pairs.
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.
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).
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.
The following sections describe the RCM script tasks for application developers and system administrators.
The following task map describes the tasks for an application developer who is creating an RCM script.
Task |
Description |
For Instructions |
---|---|---|
1. Identify resources your application uses |
Identify the resources (device names) your application uses that you could potentially dynamically remove. | |
2. Identify commands to release the resource |
Identify the commands for notifying the application to cleanly release the resource from the application. |
Application documentation |
3. Identify commands for post-removal of the resource |
Include the commands for notifying the application of the resource removal. | |
4. Identify commands if the resource removal fails |
Include the commands for notifying the application of the available resource. | |
5. Write the RCM script |
Write the RCM script based on the information identified in the previous tasks. | |
6. Install the RCM script |
Add the script to the appropriate script directory. | |
7. Test the RCM script |
Test the script by running the script commands manually and by initiating a dynamic reconfiguration operation. |
The following task map describes the tasks for a system administrator who is creating an RCM script to do site customization.
Task |
Description |
For Instructions |
---|---|---|
1. Identify resources to be dynamically removed |
Identify the resources (device names) to be potentially removed by using the cfgadm -l command. | |
2. Identify applications to be stopped |
Identify the commands for stopping the applications cleanly. |
Application documentation |
3. Identify commands for pre-removal and post-removal of the resource |
Identify the actions to be taken before and after the resource is removed. | |
4. Write the RCM script |
Write the RCM script based on the information identified in the previous tasks. | |
5. Install the RCM script |
Add the script to the appropriate script directory. | |
6. Test the RCM script |
Test the script by running the script commands manually and by initiating a dynamic reconfiguration operation. |
A script must be named as vendor,service where the following applies:
vendor |
Is the stock symbol of the vendor that provides the script, or any distinct name that identifies the vendor. |
service |
Is the name of the service that the script represents. |
You must be superuser (root) to install or remove an RCM script. Use this table to determine where you should install your RCM script.
Table 28–1 RCM Script Directories
Directory Location |
Script Type |
---|---|
/etc/rcm/scripts |
Scripts for specific systems |
/usr/platform/`uname -i`/lib/rcm/scripts |
Scripts for a specific hardware implementation |
/usr/platform/`uname -m`/lib/rcm/scripts |
Scripts for a specific hardware class |
/usr/lib/rcm/scripts |
Scripts for any hardware |
Become superuser.
Copy the script to the appropriate directory as described in Table 28–1.
For example:
# cp SUNW,sample.pl /usr/lib/rcm/scripts |
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 |
Send SIGHUP to the RCM daemon.
# pkill -HUP -x -u root rcm_daemon |
Become superuser.
Remove the script from the RCM script directory.
For example:
# rm /usr/lib/rcm/scripts/SUNW,sample.pl |
Send SIGHUP to the RCM daemon.
# pkill -HUP -x -u root rcm_daemon |
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 |
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 |
Make sure each RCM script command in your script prints appropriate output to stdout.
Install the script in the appropriate script directory.
For more information, see How to Install an RCM Script.
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 |
Make sure that you are familiar with these commands because they can alter the state of the system and can cause system failures.
This example illustrates how to use an RCM script for tape backups.
The tape backup RCM script performs the following steps:
Sets up a dispatch table of RCM commands.
Calls the dispatch routine that corresponds to the specified RCM command and exits with status 2 for unimplemented RCM commands.
Sets up the scriptinfo section:
rcm_script_func_info=Tape backup appl script for DR |
Registers all tape drives in the system by printing all tape drive device names to stdout.
rcm_resource_name=/dev/rmt/$f |
rcm_failure_reason=$errmsg |
Sets up the resource information for the tape device.
rcm_resource_usage_info=Backup Tape Unit Number $unit |
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.
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.
#! /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); } } |