The chapter provides instructions for configuration devices in the Solaris environment.
This is a list of step-by-step instructions in this chapter.
For information about accessing devices, see Chapter 26, Accessing Devices (Overview).
Adding, removing, or replacing devices in the Solaris environment can be done while the system is still running, if the system components support hot plugging, or the system must be rebooted to reconfigure devices if the system components do not support hot plugging.
Adding a new peripheral device usually involves:
Shutting down the system
Connecting the device to the system
Rebooting the system
Use the procedure below to add the following devices to a system:
CD-ROM
Secondary disk drive
Tape drive
SBUS card
In some cases, you might have to add a third-party device driver to support the new device.
Become superuser.
Follow steps 2 and 3 of "How to Add a Device Driver" if you need to add a device driver to support the device.
Create the /reconfigure file.
# touch /reconfigure |
The /reconfigure file will cause the Solaris software to check for the presence of any newly installed devices the next time you turn on or boot your system.
Shut down the system.
# shutdown -i0 -g30 -y |
-i0 |
Brings the system to the 0 init state, which is the appropriate state for turning the system power off for adding and removing devices. |
-g30 |
Shuts the system down in 30 seconds. The default is 60 seconds. |
-y |
Continues the system shutdown without user intervention; otherwise, you are prompted to continue the shutdown process. |
Turn off power to the system after it is shut down.
On SPARC based Platforms ... |
On Intel based Platforms ... |
---|---|
It is safe to turn off power if the ok or > prompt is displayed. |
It is safe to turn off power if the type any key to continue prompt is displayed. |
Refer to the hardware installation guide that accompanies your system for the location of the power switch.
Turn off power to all external devices.
For location of power switches on any peripheral devices, refer to the hardware installation guides that accompany your peripheral devices.
Install the peripheral device, making sure the device you are adding has a different target number than the other devices on the system.
You often will find a small switch located at the back of the disk for this purpose.
Refer to the hardware installation guide that accompanies the peripheral device for information on installing and connecting the device.
Turn on the power to the system.
The system will boot to multiuser mode and the login prompt will be displayed.
Verify that the peripheral device has been added by attempting to access the device. See Chapter 26, Accessing Devices (Overview) for information on accessing the device.
This procedure assumes that the device has already been added to the system. If not, see "Adding a Peripheral Device to a System".
Become superuser.
Place the tape, diskette, or CD-ROM into the drive.
Install the driver.
# pkgadd -d device package-name |
-d device |
Identifies the device path name. |
package-name |
Identifies the package name that contains the device driver. |
Verify that the package has been added correctly by using the pkgchk command. The system prompt returns with no response if the package is installed correctly.
# pkgchk packagename # |
The following example installs and verifies a package called XYZdrv.
# pkgadd XYZdrv (licensing messages displayed) . . . Installing XYZ Company driver as <XYZdrv> . . . Installation of <XYZdrv> was successful. # pkgchk XYZdrv # |
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 disable them in some way without physically removing them from the system.
In this Solaris release, you can hot-plug SCSI devices on SPARC and IA based platforms and PCI adapter cards on IA based systems with the cfgadm command. 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 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. See cfgadm(1M) and "SCSI Hot Plugging With the cfgadm Command" for step-by-step instructions on hot-plugging SCSI components. See "IA: PCI Hot-Plugging With the cfgadm Command" for step-by-step instructions on hot-plugging PCI adapter cards on IA based systems.
Not all SCSI and PCI controllers support hot-plugging with the cfgadm command. For a list of PCI hardware that supports hot-plugging, please refer to the Solaris 8 (Intel Platform Edition) Hardware Compatibility List.
As part of Sun's high availability strategy, this feature is expected to be used in conjunction with additional layered products, such as alternate pathing or fail-over software, which 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 non-critical file systems, and then proceeding with the add or remove operations.
The cfgadm 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.
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. Refer to cfgadm(1M) for more information on ap_ids.
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 listed above is:
c0::st4
Refer to 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, and so on). Refer to cfgadm(1M) for more information on these generic states and operations.
The receptacle and occupant states for the SCSI HBA attachment points are:
Receptacle State |
Description |
Occupant State |
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 device attachment points are:
Receptacle State |
Description |
Occupant State |
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 are unknown unless there is special hardware to indicate otherwise. See the instructions below on displaying SCSI component configuration information.
A PCI adapter card hosting non-vital 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 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 network connection. This replacement requires additional layered software support to keep the network connection active.
A PCI adapter card can be added to the system as long as:
There are slots available.
The device driver supports hot-plugging for this adapter card.
See "IA: PCI Hot-Plugging With the cfgadm Command" for step-by-step instructions on adding or removing a PCI adapter card.
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 that you supply, and is displayed with the cfgadm command, depends on your system configuration.
SCSI controllers c0 and c1 and the devices attached to them provide examples of the type of device configuration information that can be displayed 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 info 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 examples, only SCSI attachment points are listed. The attachment points displayed on your system will depend on your system configuration.
SCSI controller c1 provides an example of unconfiguring a SCSI controller.
Become superuser.
Unconfigure a SCSI controller.
# cfgadm -c unconfigure c1 |
Verify 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 specifies unconfigured, indicating that the SCSI bus has no configured occupants.
SCSI controller c1 provides an example of configuring a SCSI controller.
Become superuser.
Configure a SCSI controller.
# cfgadm -c configure c1 |
Verify 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.
SCSI disk c1t4d0 provides 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 a specific SCSI device.
# cfgadm -c configure c1::dsk/c1t4d0 |
Verify 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 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.
Become superuser.
Verify the device is connected before disconnecting 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 a 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 may result in a system hang and could require a system reboot.
Verify 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 attached to it are disconnected from the system.
SCSI controller c1 provides an example of connecting a SCSI controller.
Become superuser.
Verify the device is disconnected before connecting 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 a SCSI controller.
# cfgadm -c connect c1 |
Verify 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 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.
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 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 |
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.
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 after the new device has been inserted.
Verify 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.
SCSI disk c1t4d0 provides 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 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 |
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.
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.
Type y at the Enter y if operation is complete or n to abort (yes/no)? prompt after the device has been replaced.
Verify 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 |
SCSI disk c1t4d0 provides 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 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 |
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.
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 after the device has been removed.
Verify 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 |
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 listed in the error message and try the cfgadm operation again.
The following section describes different hot-plugging operations and then provides step-by-step instructions for hot-plugging PCI adapter cards on IA based systems.
In the following examples, only PCI attachment points are listed, for brevity. The attachment points displayed on your system will depend on your system configuration.
The cfgadm(1M) command displays the status of PCI hot-pluggable devices and slots on a system.
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 # 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 that particular hot-pluggable slot, Slot 7, (physical identification of this slot). 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 present in the slot.
Become superuser.
Determine which slot the 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 this is an ethernet card, use ifconfig(1M) to bring down the interface and unplumb the interface.
Unconfigure the device.
# cfgadm -c unconfigure pci1:hpc0_slot3 |
Confirm 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 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 board.
Become superuser.
Identify the hot-pluggable slot and open latches.
Insert the adapter card into a hot-pluggable slot.
Determine which slot the adapter card is in once it is inserted and the latches are closed.
# 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 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 hot-pluggable adapter card.
# cfgadm -c configure pci1:hpc0_slot3 |
Verify the configuration of the 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 is a new device.
For example, if this is an ethernet card, use the ifconfig(1m) 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 cfgadm to check the current receptacle and occupant state and make sure the ap_id is correct.
cfgadm: Attachment point not found |
Specified attachment point was not found.
Check whether the attachment point is correct. Use cfgadm 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-plug operations. The prtconf(1M) command displays whether or not Solaris recognizes the hardware. After inserting hardware, use the prtconf command to verify that the hardware is recognized. After a configure operation, use the prtconf -D command to verify the driver is attached to the newly installed hardware device.