1 LUXADM(1M) Maintenance Commands LUXADM(1M) 2 3 4 5 NAME 6 luxadm - administer Sun Fire 880 storage subsystem and FC_AL devices 7 8 SYNOPSIS 9 luxadm [options]... subcommand [options]... enclosure 10 [,dev] | pathname... 11 12 13 DESCRIPTION 14 The luxadm program is an administrative command that manages the SENA, 15 Sun Fire 880 internal storage subsystem, and individual Fiber Channel 16 Arbitrated Loop (FC_AL) devices. luxadm performs a variety of control 17 and query tasks depending on the command line arguments and options 18 used. 19 20 21 The command line must contain a subcommand. The command line may also 22 contain options, usually at least one enclosure name or pathname, and 23 other parameters depending on the subcommand. You need specify only as 24 many characters as are required to uniquely identify a subcommand. 25 26 27 Specify the device that a subcommand interacts with by entering a 28 pathname. For the SENA subsystem, a disk device or enclosure services 29 controller may instead be specified by entering the World Wide Name 30 (WWN) for the device or a port to the device. The device may also be 31 specified by entering the name of the SENA enclosure, and an optional 32 identifier for the particular device in the enclosure. The individual 33 FC_AL devices may be specified by entering the WWN for the device or a 34 port to the device. 35 36 Pathname 37 Specify the device or controller by either a complete physical pathname 38 or a complete logical pathname. 39 40 41 For SENA, a typical physical pathname for a device is: 42 43 /devices/sbus@1f,0/SUNW,socal@1,0/sf@0,0/ssd@w2200002037000f96, 44 0:a,raw 45 46 47 48 49 For all SENA IBs (Interface Boards) and Sun Fire 880 SES device 50 controllers on the system, a logical link to the physical paths is kept 51 in the directory /dev/es. An example of a logical link is /dev/es/ses0. 52 53 54 The WWN may be used in place of the pathname to select an FC_AL device, 55 SENA subsystem IB, or Sun Fire 880 internal storage subsystem. The WWN 56 is a unique 16 hexadecimal digit value that specifies either the port 57 used to access the device or the device itself. A typical WWN value is: 58 59 2200002037000f96 60 61 62 63 64 See NOTES for more information on the WWN formats. 65 66 67 For a disk in a Sun Fire 880 internal storage subsystem, a typical 68 physical pathname is: 69 70 /devices/pci@8,600000/SUNW,qlc@2/fp@0,0/ssd@w2100002037a6303c,0:a 71 72 73 74 75 and a typical logical pathname is: 76 77 /dev/rdsk/c2t8d0s2 78 79 80 81 82 For individual FC_AL devices, a typical physical pathname is: 83 84 /devices/sbus@3.0/SUNW,socal@d,10000/sf@0,0/ssd@w2200002037049fc3,0:a,raw 85 86 87 88 89 and a typical logical pathname is: 90 91 /dev/rdsk/c1t0d0s2 92 93 94 95 Enclosure 96 For SENA, a device may be identified by its enclosure name and 97 slotname: 98 box_name[,fslot_number] 99 box_name[,rslot_number] 100 101 102 box_name is the name of the SENA enclosure, as specified by the 103 enclosure_name subcommand. When used without the optional slot_number 104 parameter, the box_name identifies the SENA subsystem IB. 105 106 107 f or r specifies the front or rear slots in the SENA enclosure. 108 109 110 slot_number specifies the slot number of the device in the SENA 111 enclosure, 0-6 or 0-10. 112 113 114 For a Sun Fire 880 internal storage subsystem, a device may also be 115 identified by its enclosure name and slot name. However, there is only 116 one set of disks: 117 118 box_name[,sslot_number] 119 120 121 122 123 box_name is the name of the Sun Fire 880 enclosure, as specified by the 124 enclosure_name subcommand. When used without the optional slot_number 125 parameter, box_name identifies the Sun Fire 880 internal storage 126 subsystem enclosure services device. Use s to specify the disk slot 127 number in the Sun Fire 880 internal storage subsystem, 0 - 11. 128 129 130 See disks(1M) and devlinks(1M) for additional information on logical 131 names for disks and subsystems. 132 133 OPTIONS 134 The following options are supported by all subcommands: 135 136 -e 137 Expert mode. This option is not recommended for the novice user. 138 139 140 -v 141 Verbose mode. 142 143 144 145 Options that are specific to particular subcommands are described with 146 the subcommand in the USAGE section. 147 148 OPERANDS 149 The following operands are supported: 150 151 enclosure 152 153 The box_name of the SENA or Sun Fire 880 internal storage 154 subsystem. 155 156 157 fibre_channel_HBA_port 158 159 The path to the host controller port. A typical path is: 160 161 /devices/pci@8,600000/pci@1/SUNW,qlc@4/fp@0,0:devctl 162 163 164 165 166 pathname 167 168 The logical or physical path of a SENA IB, Sun Fire 880 internal 169 storage subsystem, or disk device. pathname can also be the WWN of 170 a SENA IB, SENA disk, or individual FC_AL device. 171 172 173 USAGE 174 Subcommands 175 display enclosure[,dev]...| pathname... 176 display -p pathname... 177 display -r enclosure[,dev]...| pathname... 178 display -v enclosure[,dev]...| pathname... 179 180 Displays enclosure or device specific data. 181 182 Subsystem data consists of enclosure environmental sense 183 information and status for all subsystem devices, including disks. 184 185 Disk data consists of inquiry, capacity, and configuration 186 information. 187 188 -p 189 Displays performance information for the device or subsystem 190 specified by pathname. This option only applies to subsystems 191 that accumulate performance information. 192 193 194 -r 195 Displays error information for the FC_AL device specified by 196 the pathname, or, if the path is a SENA, for all devices on 197 the loop. The -r option only applies to SENA subsystems and 198 individual FC_AL devices. 199 200 201 -v 202 Displays in verbose mode, including mode sense data. 203 204 205 206 download [ -s ] [ -f filename_path ] enclosure... 207 208 Download the prom image pointed to the SENA subsystem Interface 209 Board unit or the Sun Fire 880 internal storage subsystem specified 210 by the enclosure or pathname. 211 212 When the SENA's download is complete, the SENA will be reset and 213 the downloaded code executed. If no filename is specified, the 214 default prom image will be used. The default prom image for the 215 SENA is in the directory /usr/lib/locale/C/LC_MESSAGES and is named 216 ibfirmware 217 218 When the Sun Fire 880 internal storage subsystem's download is 219 complete, the subsystem resets and the downloaded code begins 220 execution. The default firmware image for the Sun Fire 880 internal 221 storage subsystem is in: /usr/platform/SUNW,Sun- 222 Fire-880/lib/images/int_fcbpl_fw. 223 224 -s 225 Save. The -s option is used to save the downloaded firmware 226 in the FEPROM. If -s is not specified, the downloaded 227 firmware will not be saved across power cycles. 228 229 The -s option does not apply to the Sun Fire 880 internal 230 storage subsystem as it always stores downloaded firmware in 231 the flash memory. 232 233 When using the -s option, the download subcommand modifies 234 the FEPROM on the subsystem and should be used with caution. 235 236 237 238 enclosure_name new_name enclosure | pathname 239 240 Change the enclosure name of the enclosure or enclosures specified 241 by the enclosure or pathname. The new name (new_name) must be 16 or 242 less characters. Only alphabetic or numeric characters are 243 acceptable. This subcommand applies only to the SENA and the Sun 244 Fire 880 internal storage subsystem. 245 246 247 failover primary | secondary pathname 248 249 Select which Sun Storage T3 storage array partner group controller 250 accesses a given logical volume. If primary is specified, the 251 logical volume is accessed through the primary controller. If 252 secondary is specified, the logical volume is accessed through the 253 secondary controller specified by pathname. 254 255 256 fcal_s_download [ -f fcode-file ] 257 258 Download the fcode contained in the file fcode-file into all the 259 FC100/S Sbus Cards. This command is interactive and expects user 260 confirmation before downloading the fcode. 261 262 Use fcal_s_download only in single-user mode. Using fcal_s_download 263 to update a host adapter while there is I/O activity through that 264 adapter will cause the adapter to reset. Newly updated FCode will 265 not be executed or visible until a system reboot. 266 267 -f fcode-file 268 When invoked without the -f option, the current 269 version of the fcode in each FC100/S Sbus card is 270 printed. 271 272 273 274 fcode_download -p 275 fcode_download -d dir-name 276 277 Locate the installed FC/S, FC100/S, FC100/P, or FC100/2P host bus 278 adapter cards and download the FCode files in dir-name to the 279 appropriate cards. The command determines the correct card for each 280 type of file, and is interactive. User confirmation is required 281 before downloading the FCode to each device. 282 283 Use fcode_download to load FCode only in single-user mode. Using 284 fcode_download to update a host adapter while there is I/O activity 285 through that adapter causes the adapter to reset. Newly updated 286 FCode will not be executed or visible until a system reboot. 287 288 -d dir-name 289 Download the FCode files contained in the directory 290 dir-name to the appropriate adapter cards. 291 292 293 -p 294 Prints the current version of FCode loaded on each 295 card. No download is performed. 296 297 298 299 inquiry enclosure[,dev ]... | pathname... 300 301 Display the inquiry information for the selected device specified 302 by the enclosure or pathname. 303 304 305 insert_device [ enclosure,dev... ] 306 307 Assist the user in the hot insertion of a new device or a chain of 308 new devices. Refer to NOTES for limitations on hotplug operations. 309 This subcommand applies only to the SENA, Sun Fire 880 internal 310 storage subsystem, and individual FC_AL drives. For the SENA, if 311 more than one enclosure has been specified, concurrent hot 312 insertions on multiple busses can be performed. With no arguments 313 to the subcommand, entire enclosures or individual FC_AL drives can 314 be inserted. For the SENA or the Sun Fire 880 internal storage 315 subsystem, this subcommand guides the user interactively through 316 the hot insertion steps of a new device or chain of devices. If a 317 list of disks was entered it will ask the user to verify the list 318 of devices to be inserted is correct, at which point the user can 319 continue or quit. It then interactively asks the user to insert the 320 disk(s) or enclosure(s) and then creates and displays the logical 321 pathnames for the devices. 322 323 324 led enclosure,dev...| pathname... 325 326 Display the current state of the LED associated with the disk 327 specified by the enclosure or pathname. This subcommand only 328 applies to subsystems that support this functionality. 329 330 331 led_blink enclosure,dev...| pathname... 332 333 Requests the subsystem to start blinking the LED associated with 334 the disk specified by the enclosure or pathname. This subcommand 335 only applies to subsystems that support this functionality. 336 337 338 led_off enclosure,dev...| pathname... 339 340 Requests the subsystem to disable (turn off) the LED associated 341 with the disk specified by the enclosure or pathname. On a SENA 342 subsystem, this may or may not cause the LED to turn off or stop 343 blinking depending on the state of the SENA subsystem. Refer to the 344 SENA Array Installation and Service Manual (p/n 802-7573). This 345 subcommand only applies to subsystems that support this 346 functionality. 347 348 349 led_on pathname... 350 351 Requests the subsystem to enable (turn on) the LED associated with 352 the disk specified by the pathname. This subcommand only applies to 353 subsystems that support this functionality. 354 355 356 power_off [ -F ] enclosure[,dev]... | pathname ... 357 358 When a SENA is addressed, this subcommand causes the SENA subsystem 359 to go into the power-save mode. The SENA drives are not available 360 when in the power-save mode. When a drive in a SENA is addressed 361 the drive is set to the drive off/unmated state. In the drive 362 off/unmated state, the drive is spun down (stopped) and in bypass 363 mode. This command does not apply to the Sun Fire 880 internal 364 storage subsystem. 365 366 -F 367 The force option only applies to the SENA. Instructs luxadm 368 to attempt to power off one or more devices even if those 369 devices are being used by this host (and are, therefore, 370 busy). 371 372 Warning: Powering off a device which has data that is 373 currently being used will cause unpredictable results. Users 374 should attempt to power off the device normally (without -F) 375 first, only resorting to this option when sure of the 376 consequences of overriding normal checks. 377 378 379 380 power_on enclosure[,dev].. 381 382 Causes the SENA subsystem to go out of the power-save mode, when 383 this subcommand is addressed to a SENA.. When this subcommand is 384 addressed to a drive the drive is set to its normal start-up state. 385 This command does not apply to the Sun Fire 880 internal storage 386 subsystem. 387 388 389 probe [ -p ] 390 391 Finds and displays information about all attached SENA subsystems, 392 Sun Fire 880 internal storage subsystems, and individual FC_AL 393 devices, including the logical pathname, the WWNs, and enclosure 394 names. This subcommand warns the user if it finds different SENAs 395 with the same enclosure names. 396 397 -p 398 Includes the physical pathname in the display. 399 400 401 402 qlgc_s_download [ -f fcode-file ] 403 404 Download the FCode contained in the file fcode-file into all the 405 FC100/P, FC100/2P PCI host adapter cards. This command is 406 interactive and expects user confirmation before downloading the 407 FCode to each device. Only use qlgc_s_download in single-user mode. 408 Using qlgc_s_download to update a host adapter while there is I/O 409 activity through that adapter will cause the adapter to reset. 410 Newly updated FCode will not be executed or visible until a system 411 reboot. 412 413 -f fcode-file 414 When invoked without the -f option, the current 415 version of the FCode in each FC100/P, FC100/2P PCI 416 card is printed. 417 418 419 420 release pathname 421 422 Release a reservation held on the specified disk. The pathname 423 should be the physical or logical pathname for the disk. 424 425 This subcommand is included for historical and diagnostic purposes 426 only. 427 428 429 remove_device [ -F ] enclosure[,dev]...| pathname... 430 431 Assists the user in hot removing a device or a chain of devices. 432 This subcommand can also be used to remove entire enclosures. This 433 subcommand applies to the SENA, Sun Fire 880 internal storage 434 subsystem, and individual FC_AL drives. Refer to NOTES for 435 limitations on hotplug operations. For the SENA, Sun Fire 880 436 internal storage subsystem, and individual FC_AL devices, this 437 subcommand guides the user through the hot removal of a device or 438 devices. During execution it will ask the user to verify the list 439 of devices to be removed is correct, at which point the user can 440 continue or quit. It then prepares the disk(s) or enclosure(s) for 441 removal and interactively asks the user to remove the disk(s) or 442 enclosure(s). 443 444 For Multi-Hosted disk, the steps taken are: 445 446 o Issue the luxadm remove_device command on the first 447 host. When prompted to continue, wait. 448 449 o Issue the luxadm remove_device command on the secondary 450 hosts. When prompted to continue, wait. 451 452 o Continue with the remove_device command on the first 453 host. Remove the device when prompted to do so. 454 455 o Complete the luxadm remove_device command on the 456 additional hosts. 457 458 -F 459 Instructs luxadm to attempt to hot plug one or more devices 460 even if those devices are being used by this host (and are, 461 therefore, busy or reserved), to force the hotplugging 462 operation. 463 464 Warning: Removal of a device which has data that is currently 465 being used will cause unpredictable results. Users should 466 attempt to hotplug normally (without -F) first, only 467 resorting to this option when sure of the consequences of 468 overriding normal hotplugging checks. 469 470 471 472 reserve pathname 473 474 Reserve the specified disk for exclusive use by the issuing host. 475 The pathname used should be the physical or logical pathname for 476 the disk. 477 478 This subcommand is included for historical and diagnostic purposes 479 only. 480 481 482 set_boot_dev [ -y ] pathname 483 484 Set the boot-device variable in the system PROM to the physical 485 device name specified by pathname, which can be a block special 486 device or the pathname of the directory on which the boot file 487 system is mounted. The command normally runs interactively 488 requesting confirmation for setting the default boot-device in the 489 PROM. The -y option can be used to run it non-interactively, in 490 which case no confirmation is requested or required. 491 492 493 start pathname 494 495 Spin up the specified disk(s) in a SENA. 496 497 498 stop pathname... 499 500 Spin down the specified disks in a SENA. 501 502 503 SENA, Sun Fire 880 Internal Storage Subsystem, and Individual FC_AL Drive 504 Expert Mode Subcommands 505 The following subcommands are for expert use only, and are applicable 506 only to the SENA, Sun Fire 880 internal storage subsystem, and fiber 507 channel loops. They should only be used by users that are knowledgeable 508 about the SENA subsystem and fiber channel loops. 509 510 511 If you specify a disk to an expert subcommand that operates on a bus, 512 the subcommand operates on the bus to which the specified disk is 513 attached. 514 515 -e bypass [-ab] enclosure,dev 516 -e bypass -f enclosure 517 518 Request the enclosure services controller to set the LRC (Loop 519 Redundancy Circuit) to the bypassed state for the port and device 520 specified. 521 522 This subcommand supports the following options: 523 524 -a 525 Bypass port a of the device specified. 526 527 528 -b 529 Bypass port b of the device specified. 530 531 532 533 -e dump_map fibre_channel_HBA_port 534 535 Display WWN data for a target device or host bus adapter on the 536 specified fibre channel port. If there are no target devices on the 537 specified port, an error is returned. 538 539 540 -e enable [-ab] enclosure,dev 541 -e enable -f enclosure 542 543 Request the enclosure services controller to set the LRC (Loop 544 Redundancy Circuit) to the enabled state for the port and device 545 specified. 546 547 This subcommand supports the following options: 548 549 -a 550 Enable port a of the device specified. 551 552 553 -b 554 Enable port b of the device specified. 555 556 557 558 -e forcelip enclosure[,dev] ... | pathname... 559 560 Force the link to reinitialize, using the Loop Initialization 561 Primitive (LIP) sequence. The enclosure or pathname can specify any 562 device on the loop. Use the pathname to specify a specific path for 563 multiple loop configurations. 564 565 This is an expert only command and should be used with caution. It 566 will reset all ports on the loop. 567 568 569 -e rdls enclosure[,dev] ... | pathname... 570 571 Read and display the link error status information for all 572 available devices on the loop that contains the device specified by 573 the enclosure or pathname. 574 575 576 Other Expert Mode Subcommands 577 See NOTES for limitations of these subcommands. They should only be 578 used by users that are knowledgeable about the systems they are 579 managing. 580 581 582 These commands do not apply to the Sun Fire 880 internal storage 583 subsystem. 584 585 -e bus_getstate pathname 586 Get and display the state of the specified 587 bus. 588 589 590 -e bus_quiesce pathname 591 Quiesce the specified bus. 592 593 594 -e bus_reset pathname 595 Reset the specified bus only. 596 597 598 -e bus_resetall pathname 599 Reset the specified bus and all devices. 600 601 602 -e bus_unquiesce pathname 603 Unquiesce the specified bus. the specified 604 device. 605 606 607 -e dev_getstate pathname 608 Get and display the state of the specified 609 device. 610 611 612 -e dev_reset pathname 613 Reset the specified device. 614 615 616 -e offline pathname 617 Take the specified device offline. 618 619 620 -e online pathname 621 Put the specified device online. 622 623 624 EXAMPLES 625 Example 1 Displaying the SENAs and Individual FC_AL Devices on a System 626 627 628 The following example finds and displays all of the SENAs and 629 individual FC_AL devices on a system: 630 631 632 example% luxadm probe 633 634 635 636 Example 2 Displaying a SENA or Sun Fire 880 Internal Storage Subsystem 637 638 639 The following example displays a SENA or Sun Fire 880 internal storage 640 subsystem: 641 642 643 example% luxadm display /dev/es/ses0 644 645 646 647 Example 3 Displaying Two Subsystems 648 649 650 The following example displays two subsystems using the enclosure 651 names: 652 653 654 example% luxadm display BOB system1 655 656 657 658 Example 4 Displaying Information about the First Disk 659 660 661 The following example displays information about the first disk in the 662 front of the enclosure named BOB. Use f to specify the front disks. Use 663 r to specify the rear disks. 664 665 666 example% luxadm display BOB,f0 667 668 669 670 Example 5 Displaying Information on a Sun Fire 880 Internal Storage 671 Subsystem 672 673 674 The Sun Fire 880 internal storage subsystem has only one set of disks. 675 In this case, use s to specify the slot: 676 677 678 example% luxadm display BOB,s0 679 680 681 682 Example 6 Displaying Information about a SENA disk, an Enclosure, or an 683 Individual FC_AL Drive 684 685 686 The following example displays information about a SENA disk, an 687 enclosure, or an individual FC_AL drive with the port WWN of 688 2200002037001246: 689 690 691 example% luxadm display 2200002037001246 692 693 694 695 Example 7 Using Unique Characters to Issue a Subcommand 696 697 698 The following example uses only as many characters as are required to 699 uniquely identify a subcommand: 700 701 702 example% luxadm disp BOB 703 704 705 706 Example 8 Displaying Error Information 707 708 709 The following example displays error information about the loop that 710 the enclosure BOB is on: 711 712 713 example% luxadm display -r BOB 714 715 716 717 Example 9 Downloading New Firmware into the Interface Board 718 719 720 The following example downloads new firmware into the Interface Board 721 in the enclosure named BOB (using the default path for the file to 722 download): 723 724 725 example% luxadm download -s BOB 726 727 728 729 Example 10 Displaying Information from the SCSI Inquiry Command 730 731 732 The following example displays information from the SCSI inquiry 733 command from all individual disks on the system, using only as many 734 characters as necessary to uniquely identify the inquiry subcommand: 735 736 737 example% luxadm inq /dev/rdsk/c?t?d?s2 738 739 740 741 Example 11 Hotplugging 742 743 744 The following example hotplugs a new drive into the first slot in the 745 front of the enclosure named BOB: 746 747 748 example% luxadm insert_device BOB,f0 749 750 751 752 753 The following example hotplugs a new drive into the first slot in the 754 Sun Fire 880 internal storage subsystem named SF880-1: 755 756 757 example% luxadm insert_device SF880-1,s0 758 759 760 761 Example 12 Running an Expert Subcommand 762 763 764 The following example runs an expert subcommand. The subcommand forces 765 a loop initialization on the loop that the enclosure BOB is on: 766 767 768 example% luxadm -e forcelip BOB 769 770 771 772 Example 13 Using the Expert Mode Hot Plugging Subcommands 773 774 775 An example of using the expert mode hot plugging subcommands to hot 776 remove a disk follows. See NOTES for hot plugging limitations. 777 778 779 780 The first step reserves the SCSI device so that it can't be accessed by 781 way of its second SCSI bus: 782 783 784 example# luxadm reserve /dev/rdsk/c1t8d0s2 785 786 787 788 Example 14 Taking the Disk to be Removed Offline 789 790 791 The next two steps take the disk to be removed offline then quiesce the 792 bus: 793 794 795 example# luxadm -e offline /dev/rdsk/c1t8d0s2 796 example# luxadm -e bus_quiesce /dev/rdsk/c1t8d0s2 797 798 799 800 Example 15 Unquiescing the Bus 801 802 803 The user then removes the disk and continues by unquiescing the bus, 804 putting the disk back online, then unreserving it: 805 806 807 example# luxadm -e bus_unquiesce /dev/rdsk/c1t8d0s2 808 example# luxadm -e online /dev/rdsk/c1t8d0s2 809 example# luxadm release /dev/rdsk/c1t8d0s2 810 811 812 813 ENVIRONMENT VARIABLES 814 See environ(5) for a description of the LANG environment variable that 815 affects the execution of luxadm. 816 817 EXIT STATUS 818 The following exit values are returned: 819 820 0 821 Successful completion. 822 823 824 -1 825 An error occurred. 826 827 828 FILES 829 /usr/lib/firmware/fc_s/fc_s_fcode 830 831 832 833 834 /usr/lib/locale/C/LC_MESSAGES/ibfirmware 835 836 837 838 839 SEE ALSO 840 devlinks(1M), disks(1M), attributes(5), environ(5), ses(7D) 841 842 NOTES 843 Currently, only some device drivers support hot plugging. If hot 844 plugging is attempted on a disk or bus where it is not supported, an 845 error message of the form: 846 847 luxadm: can't acquire "PATHNAME": No such file or directory 848 849 850 851 852 will be displayed. 853 854 855 You must be careful not to quiesce a bus that contains the root or the 856 /usr filesystems or any swap data. If you do quiesce such a bus a 857 deadlock can result, requiring a system reboot. 858 859 860 861 May 17, 2020 LUXADM(1M)