1cfgadm_scsi(1M) System Administration Commands cfgadm_scsi(1M)
2
6 cfgadm_scsi - SCSI hardware specific commands for cfgadm
7
9 /usr/sbin/cfgadm [-f] [-y | -n] [-v] [-o hardware_option]
10 -c function ap_id...
11 /usr/sbin/cfgadm [-f] [-y | -n] [-v] [-o hardware_option]
14 -x hardware_function ap_id...
15 /usr/sbin/cfgadm [-v] [-a] [-s listing_option] [-o hardware_option]
18 [-l [ap_id | ap_type ... ]]
19 /usr/sbin/cfgadm [-v] [-o hardware_option] -t ap_id...
22 /usr/sbin/cfgadm [-v] [-o hardware_option] -h [ap_id]...
25
28 The SCSI hardware specific library /usr/lib/cfgadm/scsi.so.1 provides
29 the functionality for SCSI hot-plugging through the cfgadm(1M) command.
30 cfgadm operates on attachment points, which are locations in the system
31 where hardware resources can be dynamically reconfigured. Refer to
32 cfgadm(1M) for information regarding attachment points.
33 For SCSI hot-plugging, each SCSI controller is represented by an
36 attachment point in the device tree. In addition, each SCSI device is
37 represented by a dynamic attachment point. Attachment points are named
38 through ap_ids. Two types of ap_ids are defined: logical and physical.
39 The physical ap_id is based on the physical pathname, whereas the logi‐
40 cal ap_id is a shorter more user-friendly name. For SCSI controllers,
41 the logical ap_id is usually the corresponding disk controller number.
42 For example, a typical logical ap_id would be c0.
43 SCSI devices are named relative to the controller ap_id. Thus if a disk
46 device is attached to controller c0, its ap_id can be:
47 c0::dsk/c0t0d0
49 where dsk/c0t0d0 identifies the specific device. In general, the device
54 identifier is derived from the corresponding logical link for the
55 device in /dev. For example, a SCSI tape drive logical ap_id could be
56 c0::rmt/0. Here c0 is the logical ap_id for the SCSI controller and
57 rmt/0 is derived from the logical link for the tape drive in /dev/rmt.
58 If an identifier can not be derived from the link in /dev, a unique
59 identifier will be assigned to it. For example, if the tape device has
60 no link in /dev, it can be assigned an ap_id of the form c0::st3 where
61 st3 is a unique internally generated identifier.
62 A simple listing of attachment points in the system will include
65 attachment points at SCSI controllers but not SCSI devices. Use the -a
66 flag to the list option (-l) to list SCSI devices as well. For example:
67 # cfgadm -l
69 Ap_Id Type Receptacle Occupant Condition
70 c0 scsi-bus connected configured unknown
71 sysctrl0:slot0 cpu/mem connected configured ok
72 sysctrl0:slot1 sbus-upa connected configured ok
73 To list SCSI devices in addition to SCSI controllers:
78 # cfgadm -al
80 Ap_Id Type Receptacle Occupant Condition
82 c0 scsi-bus connected configured unknown
83 c0::dsk/c0t14d0 disk connected configured unknown
84 c0::dsk/c0t11d0 disk connected configured unknown
85 c0::dsk/c0t8d0 disk connected configured unknown
86 c0::dsk/c0t0d0 disk connected configured unknown
87 c0::rmt/0 tape connected configured unknown
88 sysctrl0:slot0 cpu/mem connected configured ok
89 sysctrl0:slot1 sbus-upa connected configured ok
90 Refer to cfgadm(1M) for more information regarding listing attachment
95 points. The receptacle and occupant state for attachment points at the
96 SCSI controller have the following meanings:
97 empty not applicable
99 disconnected bus quiesced (I/O activity on bus is suspended)
102 connected bus active
105 configured one or more devices on the bus is configured
108 unconfigured no device on the bus is configured
111 The corresponding states for individual SCSI devices are:
115 empty not applicable
117 disconnected bus to which the device is attached is quiesced
120 connected bus to which device is attached is active
123 configured device is configured
126 unconfigured device is not configured
129
132 cfgadm defines several types of operations besides listing (-l).These
133 operations include testing, (-t), invoking configuration state changes,
134 (-c), invoking hardware specific functions (-x), and obtaining configu‐
135 ration administration help messages (-h).
136 -c function The following generic commands are defined for
138 the SCSI hardware specific library:
139 For SCSI controller attachment points, the fol‐
141 lowing configuration state change operations
142 are supported:
143 connect Unquiesce the SCSI bus.
145 disconnect Quiesce the bus (suspend I/O
148 activity on bus).
149 Incorrect use of this command
151 can cause the system to hang.
152 See NOTES.
153 configure Configure new devices on SCSI
156 bus.
157 unconfigure Unconfigure all devices con‐
160 nected to bus.
161 The following generic commands are defined for
163 SCSI devices:
164 configure configure a specific device
166 unconfigure unconfigure a specific device
169 -f When used with the disconnect command, forces a
173 quiesce of the SCSI bus, if supported by hard‐
174 ware.
175 Incorrect use of this command can cause the
177 system to hang. See NOTES.
178 -h ap_id SCSI specific help can be obtained by using the
181 help option with any SCSI attachment point.
182 -o hardware_option No hardware specific options are currently
185 defined.
186 -s listing_option Attachment points of class scsi can be listed
189 by using the select sub-option. Refer to the
190 cfgadm(1M) man page for additional information.
191 -t ap_id No test commands are available at present.
194 -x hardware_function Some of the following commands can only be used
197 with SCSI controllers and some only with SCSI
198 devices.
199 In the following, controller_ap_id refers to an
201 ap_id for a SCSI controller, for example, c0.
202 device_ap_id refers to an ap_id for a SCSI
203 device, for example: c0::dsk/c0dt3d0.
204 The following hardware specific functions are
206 defined:
207 insert_device controller_ap_id
209 Add a new device to the SCSI controller,
211 controller_ap_id.
212 This command is intended for interactive
214 use only.
215 remove_device device_ap_id
218 Remove device device_ap_id.
220 This command is intended for interactive
222 use only.
223 replace_device device_ap_id
226 Remove device device_ap_id and replace it
228 with another device of the same kind.
229 This command is intended for interactive
231 use only.
232 reset_device device_ap_id
235 Reset device_ap_id.
237 reset_bus controller_ap_id
240 Reset bus controller_ap_id without reset‐
242 ting any devices attached to the bus.
243 reset_all controller_ap_id
246 Reset bus controller_ap_id and all devices
248 on the bus.
249 locator [=on|off] device_ap_id
252 Sets or gets the hard disk locator LED, if
254 it is provided by the platform. If the
255 [on|off] suboption is not set, the state of
256 the hard disk locator is printed.
257 led[=LED,mode=on|off|blink] device_ap_id
260 If no sub-arguments are set, this function
262 print a list of the current LED settings.
263 If sub-arguments are set, this function
264 sets the mode of a specific LED for a slot.
265
269 Example 1 Configuring a Disk
270 The following command configures a disk attached to controller c0:
273 # cfgadm -c configure c0::dsk/c0t3d0
276 Example 2 Unconfiguring a Disk
280 The following command unconfigures a disk attached to controller c0:
283 # cfgadm -c unconfigure c0::dsk/c0t3d0
286 Example 3 Adding a New Device
290 The following command adds a new device to controller c0:
293 # cfgadm -x insert_device c0
296 The system responds with the following:
301 Adding device to SCSI HBA: /devices/sbus@1f,0/SUNW,fas@e,8800000
304 This operation will suspend activity on SCSI bus c0
305 Continue (yes/no)?
306 Enter:
311 y
314 The system responds with the following:
319 SCSI bus quiesced successfully.
322 It is now safe to proceed with hotplug operation.
323 Enter y if operation is complete or n to abort (yes/no)?
324 Enter:
329 y
332 Example 4 Replacing a Device
336 The following command replaces a device attached to controller c0:
339 # cfgadm -x replace_device c0::dsk/c0t3d0
342 The system responds with the following:
347 Replacing SCSI device: /devices/sbus@1f,0/SUNW,fas@e,8800000/sd@3,0
350 This operation will suspend activity on SCSI bus: c0
351 Continue (yes/no)?
352 Enter:
357 y
360 The system responds with the following:
365 SCSI bus quiesced successfully.
368 It is now safe to proceed with hotplug operation.
369 Enter y if operation is complete or n to abort (yes/no)?
370 Enter:
375 y
378 Example 5 Encountering a Mounted File System While Unconfiguring a Disk
382 The following command illustrates encountering a mounted file system
385 while unconfiguring a disk:
386 # cfgadm -c unconfigure c1::dsk/c1t0d0
389 The system responds with the following:
394 cfgadm: Component system is busy, try again: failed to offline:
397 /devices/pci@1f,4000/scsi@3,1/sd@1,0
398 Resource Information
399 ------------------ --------------------------
400 /dev/dsk/c1t0d0s0 mounted filesystem "/mnt"
401 Example 6 Display the Value of the Locator for a Disk
405 The following command displays the value of the locator for a disk.
408 This example is specific to the SPARC Enterprise Server family:
409 # cfgadm -x locator c0::dsk/c0t6d0
412 The system responds with the following:
417 Disk Led
420 c0t6d0 locator=on
421 Example 7 Set the Value of the Locator for a Disk
425 The following command sets the value of the locator for a disk. This
428 example is specific to the SPARC Enterprise Server family:
429 # cfgadm -x locator=off c0::dsk/c0t6d0
432 The system does not print anything in response.
437
440 /usr/lib/cfgadm/scsi.so.1
441 hardware-specific library for generic SCSI hot-plugging
443 /usr/platform/SPARC-Enterprise/lib/cfgadm/scsi.so.1
446 platform-specific library for generic SCSI hot-plugging
448
451 See attributes(5) for descriptions of the following attributes:
452 ┌─────────────────────────────┬─────────────────────────────┐
457 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
458 ├─────────────────────────────┼─────────────────────────────┤
459 │Availability │SUNWcsl │
460 └─────────────────────────────┴─────────────────────────────┘
461
463 cfgadm(1M), luxadm(1M), config_admin(3CFGADM), libcfgadm(3LIB),
464 attributes(5)
465
467 The disconnect (quiesce) operation is not supported on controllers
468 which control disks containing critical partitions such as root (/),
469 /usr, swap, or /var. The disconnect operation should not be attempted
470 on such controllers. Incorrect usage can result in a system hang and
471 require a reboot.
472 When a controller is in the disconnected (quiesced) state, there is a
475 potential for deadlocks occurring in the system. The disconnect opera‐
476 tion should be used with caution. A controller should be kept in the
477 disconnected state for the minimum period of time required to accom‐
478 plish the DR operation. The disconnect command is provided only to
479 allow the replacement of the SCSI cables while the system is running.
480 It should not be used for any other purpose. The only fix for a dead‐
481 lock (if it occurs) is to reboot the system.
482 Hotplugging operations are not supported by all SCSI controllers.
485
487 The connectors on some SCSI devices do not conform to SCSI hotplug
488 specifications. Performing hotplug operations on such devices can cause
489 damage to the hardware on the SCSI bus. Refer to your hardware manual
490 for additional information.
491SunOS 5.11 6 Jun 2006 cfgadm_scsi(1M)