1cfgadm_scsi(1M)         System Administration Commands         cfgadm_scsi(1M)
2
3
4

NAME

6       cfgadm_scsi - SCSI hardware specific commands for cfgadm
7

SYNOPSIS

9       /usr/sbin/cfgadm [-f] [-y | -n] [-v] [-o hardware_option]
10            -c function ap_id...
11
12
13       /usr/sbin/cfgadm [-f] [-y | -n] [-v] [-o hardware_option]
14            -x hardware_function ap_id...
15
16
17       /usr/sbin/cfgadm [-v] [-a] [-s listing_option] [-o hardware_option]
18            [-l [ap_id | ap_type ... ]]
19
20
21       /usr/sbin/cfgadm [-v] [-o hardware_option] -t ap_id...
22
23
24       /usr/sbin/cfgadm [-v] [-o hardware_option] -h [ap_id]...
25
26

DESCRIPTION

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
34
35       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
44
45       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
48         c0::dsk/c0t0d0
49
50
51
52
53       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
63
64       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
68         # 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
74
75
76
77       To list SCSI devices in addition to SCSI controllers:
78
79         # cfgadm -al
80
81         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
91
92
93
94       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
98       empty           not applicable
99
100
101       disconnected    bus quiesced (I/O activity on bus is suspended)
102
103
104       connected       bus active
105
106
107       configured      one or more devices on the bus is configured
108
109
110       unconfigured    no device on the bus is configured
111
112
113
114       The corresponding states for individual SCSI devices are:
115
116       empty           not applicable
117
118
119       disconnected    bus to which the device is attached is quiesced
120
121
122       connected       bus to which device is attached is active
123
124
125       configured      device is configured
126
127
128       unconfigured    device is not configured
129
130

OPTIONS

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
137       -c function             The following generic commands are defined  for
138                               the SCSI hardware specific library:
139
140                               For SCSI controller attachment points, the fol‐
141                               lowing configuration  state  change  operations
142                               are supported:
143
144                               connect        Unquiesce the SCSI bus.
145
146
147                               disconnect     Quiesce  the  bus  (suspend  I/O
148                                              activity on bus).
149
150                                              Incorrect use  of  this  command
151                                              can  cause  the  system to hang.
152                                              See NOTES.
153
154
155                               configure      Configure new  devices  on  SCSI
156                                              bus.
157
158
159                               unconfigure    Unconfigure   all  devices  con‐
160                                              nected to bus.
161
162                               The following generic commands are defined  for
163                               SCSI devices:
164
165                               configure      configure a specific device
166
167
168                               unconfigure    unconfigure a specific device
169
170
171
172       -f                      When used with the disconnect command, forces a
173                               quiesce of the SCSI bus, if supported by  hard‐
174                               ware.
175
176                               Incorrect  use  of  this  command can cause the
177                               system to hang. See NOTES.
178
179
180       -h ap_id                SCSI specific help can be obtained by using the
181                               help option with any SCSI attachment point.
182
183
184       -o hardware_option      No  hardware  specific  options  are  currently
185                               defined.
186
187
188       -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
192
193       -t ap_id                No test commands are available at present.
194
195
196       -x hardware_function    Some of the following commands can only be used
197                               with  SCSI  controllers and some only with SCSI
198                               devices.
199
200                               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
205                               The  following  hardware specific functions are
206                               defined:
207
208                               insert_device controller_ap_id
209
210                                   Add a new device to  the  SCSI  controller,
211                                   controller_ap_id.
212
213                                   This  command  is  intended for interactive
214                                   use only.
215
216
217                               remove_device device_ap_id
218
219                                   Remove device device_ap_id.
220
221                                   This command is  intended  for  interactive
222                                   use only.
223
224
225                               replace_device device_ap_id
226
227                                   Remove  device  device_ap_id and replace it
228                                   with another device of the same kind.
229
230                                   This command is  intended  for  interactive
231                                   use only.
232
233
234                               reset_device device_ap_id
235
236                                   Reset device_ap_id.
237
238
239                               reset_bus controller_ap_id
240
241                                   Reset  bus  controller_ap_id without reset‐
242                                   ting any devices attached to the bus.
243
244
245                               reset_all controller_ap_id
246
247                                   Reset bus controller_ap_id and all  devices
248                                   on the bus.
249
250
251                               locator [=on|off] device_ap_id
252
253                                   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
258
259                               led[=LED,mode=on|off|blink] device_ap_id
260
261                                   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
266
267

EXAMPLES

269       Example 1 Configuring a Disk
270
271
272       The following command configures a disk attached to controller c0:
273
274
275         # cfgadm -c configure c0::dsk/c0t3d0
276
277
278
279       Example 2 Unconfiguring a Disk
280
281
282       The following command unconfigures a disk attached to controller c0:
283
284
285         # cfgadm -c unconfigure c0::dsk/c0t3d0
286
287
288
289       Example 3 Adding a New Device
290
291
292       The following command adds a new device to controller c0:
293
294
295         # cfgadm -x insert_device c0
296
297
298
299
300       The system responds with the following:
301
302
303         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
307
308
309
310       Enter:
311
312
313         y
314
315
316
317
318       The system responds with the following:
319
320
321         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
325
326
327
328       Enter:
329
330
331         y
332
333
334
335       Example 4 Replacing a Device
336
337
338       The following command replaces a device attached to controller c0:
339
340
341         # cfgadm -x replace_device c0::dsk/c0t3d0
342
343
344
345
346       The system responds with the following:
347
348
349         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
353
354
355
356       Enter:
357
358
359         y
360
361
362
363
364       The system responds with the following:
365
366
367         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
371
372
373
374       Enter:
375
376
377         y
378
379
380
381       Example 5 Encountering a Mounted File System While Unconfiguring a Disk
382
383
384       The  following  command  illustrates encountering a mounted file system
385       while unconfiguring a disk:
386
387
388         # cfgadm -c unconfigure c1::dsk/c1t0d0
389
390
391
392
393       The system responds with the following:
394
395
396         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
402
403
404       Example 6 Display the Value of the Locator for a Disk
405
406
407       The following command displays the value of the  locator  for  a  disk.
408       This example is specific to the SPARC Enterprise Server family:
409
410
411         # cfgadm -x locator c0::dsk/c0t6d0
412
413
414
415
416       The system responds with the following:
417
418
419         Disk                    Led
420         c0t6d0                  locator=on
421
422
423
424       Example 7 Set the Value of the Locator for a Disk
425
426
427       The  following  command  sets the value of the locator for a disk. This
428       example is specific to the SPARC Enterprise Server family:
429
430
431         # cfgadm -x locator=off c0::dsk/c0t6d0
432
433
434
435
436       The system does not print anything in response.
437
438

FILES

440       /usr/lib/cfgadm/scsi.so.1
441
442           hardware-specific library for generic SCSI hot-plugging
443
444
445       /usr/platform/SPARC-Enterprise/lib/cfgadm/scsi.so.1
446
447           platform-specific library for generic SCSI hot-plugging
448
449

ATTRIBUTES

451       See attributes(5) for descriptions of the following attributes:
452
453
454
455
456       ┌─────────────────────────────┬─────────────────────────────┐
457       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
458       ├─────────────────────────────┼─────────────────────────────┤
459       │Availability                 │SUNWcsl                      │
460       └─────────────────────────────┴─────────────────────────────┘
461

SEE ALSO

463       cfgadm(1M),   luxadm(1M),    config_admin(3CFGADM),    libcfgadm(3LIB),
464       attributes(5)
465

NOTES

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
473
474       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
483
484       Hotplugging operations are not supported by all SCSI controllers.
485

WARNINGS

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.
491
492
493
494SunOS 5.11                        6 Jun 2006                   cfgadm_scsi(1M)
Impressum