with ibm corp. · chapter 1. spectrum v irtualize restful api ..... . 1 chapter 2. api management...

IBM Spectrum Virtualize

Interfacing Using the RESTful API

IBM

NoteBefore using this information and the product it supports, read the information in “Notices” on page 785.

This edition applies to version 8, release 1, modification 3, and to all subsequent modifications until otherwiseindicated in new editions.

© Copyright IBM Corporation 2018.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Tables . . . . . . . . . . . . . . . ix

About this guide . . . . . . . . . . . xiAccessibility . . . . . . . . . . . . . . xiEmphasis . . . . . . . . . . . . . . . xiSyntax diagrams . . . . . . . . . . . . . xi

CLI special characters. . . . . . . . . . xiiiUsing wildcards in the CLI . . . . . . . . xiiiData types and value ranges . . . . . . . xivCLI commands and parameters . . . . . . xviiiCLI flags . . . . . . . . . . . . . . xixCLI messages. . . . . . . . . . . . . xxUnderstanding capacity indicators . . . . . . xxAttributes of the -filtervalue parameters . . . . xx

Chapter 1. Spectrum Virtualize RESTfulAPI . . . . . . . . . . . . . . . . . 1

Chapter 2. API management . . . . . . 9

Chapter 3. Using the CLI . . . . . . . 11Setting the clustered system time by using the CLI 11Setting cluster date and time . . . . . . . . 12Viewing and updating license settings by using theCLI . . . . . . . . . . . . . . . . . 12Displaying clustered system properties by using theCLI . . . . . . . . . . . . . . . . . 13Maintaining passwords using the CLI . . . . . 14Using the dump commands to work with directories 15Re-adding a repaired node to a clustered system byusing the CLI. . . . . . . . . . . . . . 16Displaying node properties by using the CLI . . . 20Discovering MDisks using the CLI . . . . . . 20Creating storage pools using the CLI . . . . . . 21Adding MDisks to storage pools using the CLI . . 24Setting a quorum disk using the CLI . . . . . . 25Modifying the amount of available memory forCopy Services, Volume Mirroring, and RAID arraysby using the CLI . . . . . . . . . . . . 26Creating volumes using the CLI . . . . . . . 28Adding a copy to a volume . . . . . . . . . 30Deleting a copy from a volume . . . . . . . . 31Configuring host objects . . . . . . . . . . 31Creating host mappings by using the CLI . . . . 32Creating FlashCopy mappings by using the CLI . . 33

Preparing and starting a FlashCopy mapping byusing the CLI. . . . . . . . . . . . . 34Stopping FlashCopy mappings by using the CLI 35Deleting a FlashCopy mapping using the CLI . . 35

Creating a FlashCopy consistency group and addingmappings using the CLI . . . . . . . . . . 36

Preparing and starting a FlashCopy consistencygroup using the CLI . . . . . . . . . . 37

Stopping a FlashCopy consistency group usingthe CLI . . . . . . . . . . . . . . . 38Deleting a FlashCopy consistency group usingthe CLI . . . . . . . . . . . . . . . 39

Creating Metro Mirror, Global Mirror, oractive-active relationships by using the CLI. . . . 40

Modifying Metro Mirror, Global Mirror, oractive-active relationships by using the CLI. . . 40Starting and stopping Metro Mirror, GlobalMirror, or active-active relationships by using theCLI . . . . . . . . . . . . . . . . 41Displaying the progress of Metro Mirror, GlobalMirror, or active-active relationships by using theCLI . . . . . . . . . . . . . . . . 41Switching Metro Mirror or Global Mirrorrelationships using the CLI . . . . . . . . 42Deleting Metro Mirror, Global Mirror, oractive-active relationships by using the CLI. . . 42

Creating Metro Mirror, Global Mirror, oractive-active consistency groups by using the CLI . 43

Modifying Metro Mirror, Global Mirror, oractive-active consistency groups by using the CLI 43Starting and stopping Metro Mirror, GlobalMirror, or active-active consistency-group copyprocesses by using the CLI . . . . . . . . 44Deleting Metro Mirror, Global Mirror, oractive-active consistency groups by using the CLI 44

Creating Metro Mirror and Global Mirrorpartnerships by using the CLI . . . . . . . . 45

Modifying Metro Mirror and Global Mirrorpartnerships using the CLI . . . . . . . . 46Starting and stopping Metro Mirror and GlobalMirror partnerships using the CLI . . . . . . 47Deleting Metro Mirror and Global Mirrorpartnerships using the CLI . . . . . . . . 47

Determining the WWNNs of a node using the CLI 47Listing node-dependent volumes using the CLI . . 48Determining the volume name from the deviceidentifier on the host . . . . . . . . . . . 49Determining the host that a volume maps . . . . 49Determining the relationship between volume andMDisks using the CLI . . . . . . . . . . . 50Determining the relationship between MDisks andcontroller LUNs using the CLI . . . . . . . . 50Increasing the size of your system by using the CLI 51

Adding a node to increase the size of the system 51Validating and repairing mirrored volume copies byusing the CLI. . . . . . . . . . . . . . 53Repairing a thin-provisioned volume using the CLI 55Recovering offline volumes using the CLI . . . . 55

Recovering a node and returning it to the systemby using the CLI . . . . . . . . . . . 56Recovering offline volumes using the CLI . . . 57Moving offline volumes to their original I/Ogroup using the CLI . . . . . . . . . . 58

Recording WWPN changes of replaced host HBAs 58

© Copyright IBM Corp. 2018 iii

Expanding volumes by using the CLI. . . . . . 59Expanding a volume that is mapped to an AIXhost . . . . . . . . . . . . . . . . 60Expanding a volume that is mapped to aMicrosoft Windows host by using the CLI . . . 60

Shrinking a volume using the CLI . . . . . . . 61Migrating extents using the CLI . . . . . . . 62Migrating volumes between pools using the CLI . . 63Moving a volume between I/O groups using theCLI . . . . . . . . . . . . . . . . . 65Creating an image-mode volume using the CLI . . 66Migrating data to an image mode volume using theCLI . . . . . . . . . . . . . . . . . 67Deleting a node from a system by using the CLI . . 67Completing the system maintenance procedure byusing the CLI. . . . . . . . . . . . . . 69Modifying system IP addresses using the CLI . . . 70Changing the system gateway address by using theCLI . . . . . . . . . . . . . . . . . 71Changing the relationship bandwidth for a systemby using the CLI . . . . . . . . . . . . 71Configuring the system for iSCSI hosts . . . . . 72

Configuring or modifying an iSCSI alias by usingthe CLI . . . . . . . . . . . . . . . 74Configuring the iSNS server address by using theCLI . . . . . . . . . . . . . . . . 74Configuring system iSCSI authentication byusing the CLI. . . . . . . . . . . . . 75

Configuring remote authentication service using theCLI . . . . . . . . . . . . . . . . . 75

Configuring remote authentication service withLightweight Directory Access Protocol (LDAP) byusing the CLI. . . . . . . . . . . . . 76

Changing user groups . . . . . . . . . . . 77Changing users . . . . . . . . . . . . . 77Managing SNMP notifications by using the CLI . . 78Setting up syslog notifications using the CLI . . . 79Setting up email event notifications and inventoryreports by using the CLI . . . . . . . . . . 80Setting up email servers by using the CLI . . . . 82Changing user passwords using the CLI. . . . . 82Changing the locale setting using the CLI . . . . 83Viewing the feature log using the CLI . . . . . 83Analyzing the error log using the CLI . . . . . 83Shutting down a system by using the CLI . . . . 84Updating the system automatically using the CLI . 84

Chapter 4. Array commands . . . . . 89charray . . . . . . . . . . . . . . . . 89charraymember . . . . . . . . . . . . . 90lsarray . . . . . . . . . . . . . . . . 93lsarrayinitprogress. . . . . . . . . . . . 100lsarraylba. . . . . . . . . . . . . . . 101lsarraymember . . . . . . . . . . . . . 103lsarraymembergoals . . . . . . . . . . . 106lsarraymemberprogress . . . . . . . . . . 109lsarrayrecommendation . . . . . . . . . . 111lsarraysyncprogress . . . . . . . . . . . 114lspotentialarraysize . . . . . . . . . . . 115mkarray . . . . . . . . . . . . . . . 117mkdistributedarray . . . . . . . . . . . 120

recoverarray . . . . . . . . . . . . . . 123recoverarraybycluster (Discontinued) . . . . . 123recoverarraybysystem . . . . . . . . . . 123rmarray . . . . . . . . . . . . . . . 124

Chapter 5. Audit log commands . . . 125catauditlog . . . . . . . . . . . . . . 125dumpauditlog . . . . . . . . . . . . . 126lsauditlogdumps (Deprecated) . . . . . . . . 128

Chapter 6. Backup and restorecommands . . . . . . . . . . . . 129svcconfig . . . . . . . . . . . . . . . 129backup . . . . . . . . . . . . . . . 130clear . . . . . . . . . . . . . . . . 131cron . . . . . . . . . . . . . . . . 132recover . . . . . . . . . . . . . . . 132restore. . . . . . . . . . . . . . . . 133

Chapter 7. Cloud commands . . . . . 137cfgcloudcallhome . . . . . . . . . . . . 137cfgcloudstorage . . . . . . . . . . . . 137querycloudstoragecandidate . . . . . . . . 138chcloudaccountawss3. . . . . . . . . . . 139chcloudaccountswift . . . . . . . . . . . 141lscloudaccount . . . . . . . . . . . . . 144lscloudaccountusage . . . . . . . . . . . 146lscloudaccountimportcandidate . . . . . . . 148mkcloudaccountawss3 . . . . . . . . . . 149mkcloudaccountswift . . . . . . . . . . . 150rmcloudaccount . . . . . . . . . . . . 152testcloudaccount . . . . . . . . . . . . 153

Chapter 8. Clustered systemcommands . . . . . . . . . . . . 155addnode (SAN Volume Controller only) . . . . . 155cfgportip . . . . . . . . . . . . . . 158chbanner . . . . . . . . . . . . . . . 165chcluster (Discontinued) . . . . . . . . . . 166chiogrp . . . . . . . . . . . . . . . 166chiscsiiqn (SAN Volume Controller only). . . . 170chiscsistorageport . . . . . . . . . . . . 171chnode . . . . . . . . . . . . . . . 173chnodebattery . . . . . . . . . . . . . 176chnodebootdrive . . . . . . . . . . . . 177chnodehw (SVC) / chnodecanisterhw (Storwizefamily products) . . . . . . . . . . . . 178chquorum . . . . . . . . . . . . . . 179chsecurity . . . . . . . . . . . . . . 181chsite . . . . . . . . . . . . . . . . 182chsra . . . . . . . . . . . . . . . . 183chsystem . . . . . . . . . . . . . . . 185chsystemcert . . . . . . . . . . . . . 193chsystemip . . . . . . . . . . . . . . 195chthrottle . . . . . . . . . . . . . . . 197cleardumps . . . . . . . . . . . . . . 198cpdumps . . . . . . . . . . . . . . . 200detectiscsistorageportcandidate . . . . . . 201dumpconfig (Discontinued). . . . . . . . . 203help . . . . . . . . . . . . . . . . 203

iv Spectrum Virtualize: RESTful API

lsclustercandidate (Discontinued) . . . . . . . 204lscluster (Discontinued) . . . . . . . . . . 204lsclusterip (Discontinued) . . . . . . . . . 204lsclusterstats (Discontinued) . . . . . . . . 204lsdiscoverystatus . . . . . . . . . . . . 204lsfabric . . . . . . . . . . . . . . . 205lsfcportcandidate . . . . . . . . . . . . 209lsiscsistorageport . . . . . . . . . . . . 210lsiscsistorageportcandidate . . . . . . . . . 213lsiogrp . . . . . . . . . . . . . . . 215lshbaportcandidate (Deprecated) . . . . . . . 219lsiogrphost . . . . . . . . . . . . . . 219lsiogrpcandidate . . . . . . . . . . . . 220lsiostatsdumps (Deprecated) . . . . . . . . 221lsiotracedumps (Deprecated) . . . . . . . . 221lsnode (SVC) / lsnodecanister (Storwize familyproducts) . . . . . . . . . . . . . . . 221lsnodebattery . . . . . . . . . . . . . 226lsnodecandidate (SAN Volume Controller). . . . 229lsnodedependentvdisks (Deprecated) . . . . . 230lsnodehw (SVC) / lsnodecanisterhw (Storwizefamily products) . . . . . . . . . . . . 231lsnodestats (SVC) / lsnodecanisterstats (Storwizefamily products) . . . . . . . . . . . . 233lsnodevpd (SVC) / lsnodecanistervpd (Storwizefamily products) . . . . . . . . . . . . 241lsportusb . . . . . . . . . . . . . . . 250lsportip . . . . . . . . . . . . . . . 252lsportfc . . . . . . . . . . . . . . . 260lsportsas . . . . . . . . . . . . . . . 262lsquorum. . . . . . . . . . . . . . . 265lsroute. . . . . . . . . . . . . . . . 266lstimezones . . . . . . . . . . . . . . 267lssasportcandidate . . . . . . . . . . . . 268lssecurity . . . . . . . . . . . . . . 269lssite . . . . . . . . . . . . . . . . 271lssra . . . . . . . . . . . . . . . . 272lsthrottle . . . . . . . . . . . . . . . 275lssystem . . . . . . . . . . . . . . . 276lssystemcert . . . . . . . . . . . . . . 289lssystemip . . . . . . . . . . . . . . 291lssystemstats . . . . . . . . . . . . . 294lstargetportfc . . . . . . . . . . . . . 298(satask) mkcluster . . . . . . . . . . . . 300mkcluster (Deprecated) . . . . . . . . . . 301mkquorumapp . . . . . . . . . . . . . . 302mkthrottle . . . . . . . . . . . . . . 302ping . . . . . . . . . . . . . . . . 304rmiscsistorageport . . . . . . . . . . . . 305rmnode (SVC) / rmnodecanister (Storwize familyproducts) . . . . . . . . . . . . . . . 305rmportip . . . . . . . . . . . . . . . 308rmthrottle . . . . . . . . . . . . . . 309setclustertime (Discontinued) . . . . . . . . 309setsystemtime . . . . . . . . . . . . . 310setpwdreset . . . . . . . . . . . . . . 310settimezone . . . . . . . . . . . . . . 311showtimezone . . . . . . . . . . . . . 311startstats . . . . . . . . . . . . . . . 312stopstats (Deprecated) . . . . . . . . . . 314stopcluster (Discontinued) . . . . . . . . . 314

stopsystem . . . . . . . . . . . . . . 314swapnode . . . . . . . . . . . . . . 315

Chapter 9. Clustered systemdiagnostic and service-aid commands 317applysoftware . . . . . . . . . . . . . 317caterrlog (Deprecated) . . . . . . . . . . 321caterrlogbyseqnum (Deprecated) . . . . . . . 321cherrstate (Deprecated) . . . . . . . . . . 321chdnsserver . . . . . . . . . . . . . . 321cheventlog . . . . . . . . . . . . . . 322chsyslogserver . . . . . . . . . . . . . 322clearerrlog . . . . . . . . . . . . . . 323cpfabricdumps (Discontinued) . . . . . . . . 324dumperrlog . . . . . . . . . . . . . . 324finderr . . . . . . . . . . . . . . . 325setevent (Discontinued) . . . . . . . . . . 325lscimomdumps (Deprecated) . . . . . . . . 325lscopystatus . . . . . . . . . . . . . . 325lsdumps . . . . . . . . . . . . . . . 326lsdnsserver . . . . . . . . . . . . . . 328lserrlogbyfcconsistgrp (Deprecated) . . . . . . 329lserrlogbyfcmap (Deprecated) . . . . . . . . 329lserrlogbyhost (Deprecated) . . . . . . . . 329lserrlogbyiogrp (Deprecated) . . . . . . . . 329lserrlogbymdisk (Deprecated) . . . . . . . . 329lserrlogbymdiskgrp (Deprecated) . . . . . . . 329lserrlogbynode (Deprecated) . . . . . . . . 329lserrlogbyrcconsistgrp (Deprecated) . . . . . . 329lserrlogbyrcrelationship (Deprecated) . . . . . 330lserrlogbyvdisk (Deprecated) . . . . . . . . 330lserrlogdumps (Deprecated) . . . . . . . . 330lsfeaturedumps (Deprecated) . . . . . . . . 330lseventlog . . . . . . . . . . . . . . 330lssyslogserver . . . . . . . . . . . . . 336lssoftwaredumps (Deprecated). . . . . . . . 337lssoftwareupgradestatus (Deprecated) . . . . . 337lssystemsupportcenter . . . . . . . . . . 337lsupdate . . . . . . . . . . . . . . . 339mkdnsserver . . . . . . . . . . . . . 342mksyslogserver . . . . . . . . . . . . . 343mksystemsupportcenter . . . . . . . . . . 344rmdnsserver . . . . . . . . . . . . . . 346rmsyslogserver . . . . . . . . . . . . . 346rmsystemsupportcenter . . . . . . . . . . 347setlocale . . . . . . . . . . . . . . . 348svqueryclock . . . . . . . . . . . . . 349writesernum. . . . . . . . . . . . . . 349

Chapter 10. Controller commands . . 351chcontroller . . . . . . . . . . . . . . 351lscontroller . . . . . . . . . . . . . . 352lscontrollerdependentvdisks . . . . . . . . 356

Chapter 11. Drive commands. . . . . 359applydrivesoftware . . . . . . . . . . . 359chdrive . . . . . . . . . . . . . . . 362lsdrive . . . . . . . . . . . . . . . 363lsdriveclass . . . . . . . . . . . . . 369lsdrivelba. . . . . . . . . . . . . . . 371

Contents v

lsdriveprogress . . . . . . . . . . . . . 372lsdriveupgradeprogress . . . . . . . . . . 374triggerdrivedump . . . . . . . . . . . . 376

Chapter 12. Email and eventnotification commands . . . . . . . 379chemail . . . . . . . . . . . . . . . 379chemailserver . . . . . . . . . . . . . 381chemailuser . . . . . . . . . . . . . . 382chsnmpserver . . . . . . . . . . . . . 383lsemailserver . . . . . . . . . . . . . 384lsemailuser . . . . . . . . . . . . . . 385lssnmpserver . . . . . . . . . . . . . 386mkemailserver . . . . . . . . . . . . . 387mkemailuser . . . . . . . . . . . . . 388mksnmpserver . . . . . . . . . . . . . 390rmemailserver . . . . . . . . . . . . . 391rmemailuser . . . . . . . . . . . . . . 391rmsnmpserver . . . . . . . . . . . . . 392sendinventoryemail . . . . . . . . . . . 392setemail (Discontinued) . . . . . . . . . . 393startemail. . . . . . . . . . . . . . . 393stopemail. . . . . . . . . . . . . . . 394testemail . . . . . . . . . . . . . . . 394

Chapter 13. Enclosure commands . . 397addcontrolenclosure . . . . . . . . . . . 397chenclosure . . . . . . . . . . . . . . 398chenclosurecanister . . . . . . . . . . . 398chenclosuredisplaypanel . . . . . . . . . . 400chenclosuresem. . . . . . . . . . . . . 400chenclosureslot . . . . . . . . . . . . . 401(satask) chenclosurevpd (Deprecated) . . . . . 403lsenclosure . . . . . . . . . . . . . . 403lsenclosurebattery . . . . . . . . . . . . 406lscontrolenclosurecandidate (Storwize familyproducts only) . . . . . . . . . . . . . 408lsenclosurecanister. . . . . . . . . . . . 409lsenclosurechassis . . . . . . . . . . . . 412lsenclosuredisplaypanel . . . . . . . . . . 414lsenclosurefanmodule . . . . . . . . . . 415lsenclosurepsu . . . . . . . . . . . . . 417lsenclosuresem . . . . . . . . . . . . . 420lsenclosureslot . . . . . . . . . . . . . 422lsenclosurestats . . . . . . . . . . . . . 425lssasfabric . . . . . . . . . . . . . . 428resetleds . . . . . . . . . . . . . . . 431triggerenclosuredump . . . . . . . . . . 431

Chapter 14. Encryption commands 433chencryption . . . . . . . . . . . . . 433chkeyserver . . . . . . . . . . . . . . 435chkeyserverisklm . . . . . . . . . . . . 436lsencryption . . . . . . . . . . . . . . 437lskeyserver . . . . . . . . . . . . . . 440lskeyserverisklm . . . . . . . . . . . . 441mkkeyserver . . . . . . . . . . . . . . 444rmkeyserver . . . . . . . . . . . . . . 445testkeyserver . . . . . . . . . . . . . 445

Chapter 15. Licensing andfeaturization commands. . . . . . . 447activatefeature . . . . . . . . . . . . . 447chlicense . . . . . . . . . . . . . . 448deactivatefeature . . . . . . . . . . . . 450lsfeature . . . . . . . . . . . . . . . 451lslicense . . . . . . . . . . . . . . . 453

Chapter 16. FlashCopy commands 457chfcconsistgrp . . . . . . . . . . . . . 457chfcmap . . . . . . . . . . . . . . . 457lsfcconsistgrp . . . . . . . . . . . . . 459lsfcmap . . . . . . . . . . . . . . . 462lsfcmapcandidate . . . . . . . . . . . . 465lsfcmapprogress . . . . . . . . . . . . 466lsfcmapdependentmaps . . . . . . . . . . 467lsrmvdiskdependentmaps . . . . . . . . . 468mkfcconsistgrp . . . . . . . . . . . . . 468mkfcmap . . . . . . . . . . . . . . . 469prestartfcconsistgrp . . . . . . . . . . . 472prestartfcmap . . . . . . . . . . . . . 474rmfcconsistgrp . . . . . . . . . . . . . 475rmfcmap . . . . . . . . . . . . . . . 475startfcconsistgrp . . . . . . . . . . . . 476startfcmap . . . . . . . . . . . . . . 478stopfcconsistgrp . . . . . . . . . . . . 479stopfcmap . . . . . . . . . . . . . . 480

Chapter 17. Host commands . . . . . 483addhostclustermember . . . . . . . . . . 483addhostiogrp . . . . . . . . . . . . . 484addhostport . . . . . . . . . . . . . . 484chhost . . . . . . . . . . . . . . . . 486lshost . . . . . . . . . . . . . . . . 488lshostcluster . . . . . . . . . . . . . . 492lshostclustermember . . . . . . . . . . . 494lshostclustervolumemap . . . . . . . . . . 495lshostiogrp . . . . . . . . . . . . . . 497lsiscsiauth . . . . . . . . . . . . . . 498mkhost . . . . . . . . . . . . . . . 500mkhostcluster . . . . . . . . . . . . . 502mkvolumehostclustermap . . . . . . . . . 503rmhost . . . . . . . . . . . . . . . 504rmhostcluster . . . . . . . . . . . . . 505rmhostclustermember . . . . . . . . . . 506rmvolumehostclustermap . . . . . . . . . 507rmhostiogrp . . . . . . . . . . . . . . 508rmhostport . . . . . . . . . . . . . . 509

Chapter 18. Information commands 511ls2145dumps (Deprecated) . . . . . . . . . 511lsconfigdumps (Discontinued) . . . . . . . . 511lssshkeys (Discontinued). . . . . . . . . . 511

Chapter 19. Livedump commands . . 513cancellivedump. . . . . . . . . . . . . 513lslivedump . . . . . . . . . . . . . . 513preplivedump . . . . . . . . . . . . . 514triggerlivedump . . . . . . . . . . . . 514

vi Spectrum Virtualize: RESTful API

Chapter 20. Managed disk commands 517addmdisk . . . . . . . . . . . . . . 517applymdisksoftware (Discontinued) . . . . . . 518chmdisk . . . . . . . . . . . . . . . 518detectmdisk . . . . . . . . . . . . . . 520dumpallmdiskbadblocks. . . . . . . . . . 522dumpmdiskbadblocks . . . . . . . . . . 523includemdisk . . . . . . . . . . . . . 524lsmdisk . . . . . . . . . . . . . . . 524lsmdiskdumps (Deprecated) . . . . . . . . 531lsmdisklba . . . . . . . . . . . . . . 531lsmdiskcandidate . . . . . . . . . . . . 532lsmdiskextent . . . . . . . . . . . . . 533lsmdiskmember . . . . . . . . . . . . . 535setquorum (Deprecated) . . . . . . . . . . 537triggermdiskdump (Discontinued) . . . . . . 537

Chapter 21. Copy Service commands 539chpartnership . . . . . . . . . . . . . 539chrcconsistgrp . . . . . . . . . . . . . 542chrcrelationship . . . . . . . . . . . . 544lspartnership . . . . . . . . . . . . . 548lspartnershipcandidate . . . . . . . . . . 552lsrcconsistgrp . . . . . . . . . . . . . 553lsrcrelationship . . . . . . . . . . . . . 556lsrcrelationshipcandidate . . . . . . . . 560lsrcrelationshipprogress . . . . . . . . . . 561mkfcpartnership . . . . . . . . . . . . 562mkippartnership . . . . . . . . . . . . 563mkpartnership (Discontinued) . . . . . . . . 565mkrcconsistgrp . . . . . . . . . . . . . 565mkrcrelationship . . . . . . . . . . . . 566rmpartnership . . . . . . . . . . . . . 570rmrcconsistgrp . . . . . . . . . . . . . 570rmrcrelationship . . . . . . . . . . . . 571startrcconsistgrp . . . . . . . . . . . . 572startrcrelationship . . . . . . . . . . . . 575stoprcconsistgrp . . . . . . . . . . . . 577stoprcrelationship . . . . . . . . . . . . 580switchrcconsistgrp. . . . . . . . . . . . 582switchrcrelationship . . . . . . . . . . . 583

Chapter 22. Migration commands . . . 585lsmigrate . . . . . . . . . . . . . . . 585migrateexts . . . . . . . . . . . . . . 586migratetoimage. . . . . . . . . . . . . 587migratevdisk . . . . . . . . . . . . . 589

Chapter 23. Service mode commands(Discontinued) . . . . . . . . . . . 591applysoftware (Discontinued) . . . . . . . . 591svcservicemodetask cleardumps (Discontinued) . . 591svcservicemodetask dumperrlog (Discontinued) 591exit (Discontinued) . . . . . . . . . . . 591

Chapter 24. Service mode informationcommands (Discontinued) . . . . . . 593ls2145dumps (Discontinued) . . . . . . . . 593lscimomdumps (Discontinued) . . . . . . . 593

lsclustervpd (Discontinued). . . . . . . . . 593lserrlogdumps (Discontinued) . . . . . . . . 593lsfeaturedumps (Discontinued) . . . . . . . 593lsiostatsdumps (Discontinued) . . . . . . . . 593lsiotracedumps (Discontinued) . . . . . . . 593lsmdiskdumps (Discontinued) . . . . . . . . 593lssoftwaredumps (Discontinued) . . . . . . . 593

Chapter 25. Storage pool commands 595chmdiskgrp . . . . . . . . . . . . . . 595lsfreeextents . . . . . . . . . . . . . . 597lsmdiskgrp . . . . . . . . . . . . . . 597mkmdiskgrp . . . . . . . . . . . . . . 607rmmdisk . . . . . . . . . . . . . . . 611rmmdiskgrp . . . . . . . . . . . . . . 613

Chapter 26. User managementcommands . . . . . . . . . . . . 615chauthservice . . . . . . . . . . . . . 615chcurrentuser . . . . . . . . . . . . . 617chldap. . . . . . . . . . . . . . . . 618chldapserver . . . . . . . . . . . . . 620chuser . . . . . . . . . . . . . . . . 622chusergrp . . . . . . . . . . . . . . 623lscurrentuser . . . . . . . . . . . . . 624lsldap . . . . . . . . . . . . . . . . 624lsldapserver . . . . . . . . . . . . . . 626lsuser . . . . . . . . . . . . . . . . 627lsusergrp . . . . . . . . . . . . . . . 629mkldapserver . . . . . . . . . . . . . 630mkuser . . . . . . . . . . . . . . . 631mkusergrp . . . . . . . . . . . . . . 632rmldapserver . . . . . . . . . . . . . 635rmuser . . . . . . . . . . . . . . . 636rmusergrp . . . . . . . . . . . . . . 636testldapserver . . . . . . . . . . . . . 637

Chapter 27. Volume commands. . . . 641addvolumecopy . . . . . . . . . . . . . 641addvdiskcopy . . . . . . . . . . . . . 644addvdiskaccess . . . . . . . . . . . . . 652analyzevdisk . . . . . . . . . . . . . 653analyzevdiskbysystem . . . . . . . . . . 654backupvolume . . . . . . . . . . . . . 655backupvolumegroup . . . . . . . . . . . 656chvdisk . . . . . . . . . . . . . . . 657chvolumegroup. . . . . . . . . . . . . 662expandvdisksize . . . . . . . . . . . . 662lsdependentvdisks. . . . . . . . . . . . 665lshostvdiskmap. . . . . . . . . . . . . 666lsmetadatavdisk . . . . . . . . . . . . 668lsrepairsevdiskcopyprogress . . . . . . . . 669lsrepairvdiskcopyprogress . . . . . . . . . 671lssevdiskcopy . . . . . . . . . . . . . 673lsvdisk . . . . . . . . . . . . . . . 679lsvdiskaccess . . . . . . . . . . . . . 694lsvdiskanalysis . . . . . . . . . . . . . 696lsvdiskanalysisprogress . . . . . . . . . . 698lsvdiskcopy . . . . . . . . . . . . . . 700lsvdiskdependentmaps . . . . . . . . . . 707

Contents vii

lsvdiskextent . . . . . . . . . . . . . 707lsvdiskfcmapcopies . . . . . . . . . . . 709lsvdiskfcmappings. . . . . . . . . . . . 710lsvdiskhostmap . . . . . . . . . . . . . 711lsvdisklba . . . . . . . . . . . . . . 712lsvdiskmember . . . . . . . . . . . . . 714lsvdiskprogress . . . . . . . . . . . . . 715lsvdisksyncprogress . . . . . . . . . . . 716lsvolumebackup . . . . . . . . . . . . 718lsvolumebackupgeneration . . . . . . . . . 720lsvolumebackupprogress . . . . . . . . . 722lsvolumegroup . . . . . . . . . . . . . 723lsvolumerestoreprogress . . . . . . . . . . 725mkmetadatavdisk . . . . . . . . . . . . 727mkvdisk . . . . . . . . . . . . . . . 728mkvdiskhostmap . . . . . . . . . . . . 739mkvolume . . . . . . . . . . . . . . . 741mkvolumegroup . . . . . . . . . . . . 745mkimagevolume . . . . . . . . . . . . . 746movevdisk . . . . . . . . . . . . . . 748recovervdisk. . . . . . . . . . . . . . 750recovervdiskbycluster (Discontinued) . . . . . 751recovervdiskbyiogrp . . . . . . . . . . . 751recovervdiskbysystem . . . . . . . . . . 751repairsevdiskcopy . . . . . . . . . . . . 752repairvdiskcopy . . . . . . . . . . . . 753restorevolume . . . . . . . . . . . . . 754rmvdisk . . . . . . . . . . . . . . . 755rmmetadatavdisk . . . . . . . . . . . . 759rmvdiskcopy . . . . . . . . . . . . . 759

rmvdiskaccess . . . . . . . . . . . . . 760rmvdiskhostmap . . . . . . . . . . . . 761rmvolume . . . . . . . . . . . . . . 762rmvolumecopy . . . . . . . . . . . . . 763rmvolumegroup . . . . . . . . . . . . 765rmvolumebackupgeneration . . . . . . . . 765shrinkvdisksize . . . . . . . . . . . . 767splitvdiskcopy . . . . . . . . . . . . . 769

Appendix A. Helpful resources andpublications . . . . . . . . . . . . 773

Appendix B. Terminology . . . . . . 775

Appendix C. HTTP error messages 777

Appendix D. Usage examples in Perl 779

Appendix E. Usage examples in CURL 781

Appendix F. Accessibility features forthe system . . . . . . . . . . . . 783

Notices . . . . . . . . . . . . . . 785Trademarks . . . . . . . . . . . . . . 787

Index . . . . . . . . . . . . . . . 789

viii Spectrum Virtualize: RESTful API

Tables

1. Syntax diagrams . . . . . . . . . . . xii2. Data types . . . . . . . . . . . . xiv3. Capacity indicators . . . . . . . . . . xx4. POST method, authentication requirements, and

whether to run on the configuration node . . . 25. Supported RESTful API commands for

Spectrum Virtualize software . . . . . . . 36. Maximum volume capacity by extent size 237. Examples of memory required . . . . . . 268. RAID level comparisons . . . . . . . . 279. Volume copy resynchronization rates . . . . 29

10. charraymember combination options . . . . 9211. Array output . . . . . . . . . . . . 9512. lsarrayinitprogress output . . . . . . . 10113. lsarraylba output . . . . . . . . . . 10214. lsarraymember output . . . . . . . . 10415. lsarraymembergoals output . . . . . . . 10716. lsarraymemberprogress output . . . . . . 11017. lsarrayrecommendation output. . . . . . 11218. lsarraysyncprogress output . . . . . . . 11519. lspotentialarraysize output . . . . . . . 11720. querycloudstoragecandidate output . . . . 13821. lscloudaccount output . . . . . . . . 14522. lscloudaccountusage output. . . . . . . 14723. lscloudaccountimportcandidate output 14924. Memory required for RAID arrays, Copy

Services, and volume mirroring . . . . . 16825. RAID level comparisons . . . . . . . . 16926. Number of extents reserved by extent size 18027. IP address list formats . . . . . . . . 19728. lsfcportcandidate output . . . . . . . . 20929. lsiscsistorageport output . . . . . . . . 21130. lsiscsistorageportcandidate output . . . . 21431. lsnode or lsnodecanister attribute values 22232. lsnodebattery attribute values . . . . . . 22733. lsnodecandidate outputs . . . . . . . . 23034. Attribute values for lsnodehw and

lsnodecanisterhw . . . . . . . . . . 23135. Attribute values for lsnodestats or

lsnodecanister . . . . . . . . . . . 23436. Stat_name field values . . . . . . . . 23637. Attribute values for lsnodevpd and

lsnodecanistervpd . . . . . . . . . . 24238. lsportusb output . . . . . . . . . . 25039. lsportip output . . . . . . . . . . . 25440. lsportfc output . . . . . . . . . . . 26141. lsportsas output. . . . . . . . . . . 26342. lsquorum output . . . . . . . . . . 26543. lssasportcandidate output . . . . . . . 26944. lssecurity attribute values . . . . . . . 27045. lssite attribute values . . . . . . . . . 27246. lssra output . . . . . . . . . . . . 27347. lsthrottle output. . . . . . . . . . . 27648. lssystem output . . . . . . . . . . 27749. lssystemcert output . . . . . . . . . 29050. lssystemip output . . . . . . . . . . 292

51. lssystemstats attribute values . . . . . . 29552. Stat_name field values . . . . . . . . 29653. lstargetportfc output . . . . . . . . . 29954. lsdnsserver output . . . . . . . . . . 32855. lseventlog output . . . . . . . . . . 33256. lssyslogserver output . . . . . . . . . 33757. lssystemsupportcenter output . . . . . . 33858. lscontroller output . . . . . . . . . . 35459. lsdrive output . . . . . . . . . . . 36560. lsdriveclass output . . . . . . . . . 37061. lsdrivelba output . . . . . . . . . . 37262. lsenclosure output . . . . . . . . . . 40463. lsenclosurebattery outputs . . . . . . . 40764. lscontrolenclosurecandidate attribute values 40965. lsenclosurecanister output . . . . . . . 41066. lsenclosurechassis outputs . . . . . . . 41367. lsenclosuredisplaypanel output . . . . . 41568. lsenclosurefanmodule attribute values 41669. lsenclosurepsu output. . . . . . . . . 41870. lsenclosuresem output . . . . . . . . 42171. lsenclosureslot output . . . . . . . . . 42372. lsenclosurestats outputs . . . . . . . . 42773. Stat_name field values . . . . . . . . 42874. lssasfabric output . . . . . . . . . . 43075. lsencryption output . . . . . . . . . 43876. ~`lskeyserver output . . . . . . . . . 44077. lskeyserverisklm output . . . . . . . . 44278. lsfeature outputs . . . . . . . . . . 45279. lslicense output . . . . . . . . . . . 45480. Relationship between the rate, data rate, and

grains per second values . . . . . . . . 45981. Relationship between the rate, data rate, and

grains per second values . . . . . . . . 47282. lshost output. . . . . . . . . . . . 49183. lshostcluster output . . . . . . . . . 49384. lshostclustermember output . . . . . . 49485. lshostclustervolumemap output . . . . . 49686. lsiscsiauth output . . . . . . . . . . 49987. lslivedump outputs . . . . . . . . . 51488. MDisk output . . . . . . . . . . . 52689. lsmdisklba command output . . . . . . 53290. lspartnership attribute values . . . . . . 54991. lsrcconsistgrp command output values 55492. lsrcrelationship command attributes and

values . . . . . . . . . . . . . . 55893. stoprcconsistgrp consistency group states 57994. stoprcrelationship consistency group states 58195. Parameter differences for child pools and

parent pools . . . . . . . . . . . . 59696. Easy Tier settings for storage pools and

volumes . . . . . . . . . . . . . 60097. Parameter differences for child pools and

storage pools. . . . . . . . . . . . 60998. lsldap attribute values . . . . . . . . 62599. lsldapserver attribute values . . . . . . 627

100. testldapserver attribute values . . . . . . 638

© Copyright IBM Corp. 2018 ix

101. Storage pool Easy Tier settings . . . . . . 648102. Relationship between the syncrate value and

the data copied per second . . . . . . . 651103. Relationship between the syncrate value and

the data copied per second . . . . . . . 661104. lsmetadatavdisk output . . . . . . . . 669105. Easy Tier status values . . . . . . . . 685106. lsvdiskanalysis output . . . . . . . . 697107. lsvdiskanalysisprogress output . . . . . . 699108. Easy Tier setting for storage pools and

volumes . . . . . . . . . . . . . 703

109. lsvdisklba command output scenarios 713110. lsvolumebackup output . . . . . . . . 719111. lsvolumebackupgeneration output . . . . 721112. lsvolumebackupprogress output . . . . . 723113. lsvolumegroup output . . . . . . . . 724114. lsvolumerestoreprogress output . . . . . 726115. Easy Tier settings for storage pools and

volumes . . . . . . . . . . . . . 734116. Relationship between the syncrate value and

the data copied per second . . . . . . . 737117. Abbreviations . . . . . . . . . . . 775

x Spectrum Virtualize: RESTful API

About this guide

This publication provides information that helps you configure and use the IBM Spectrum Virtualize™ forSAN Volume Controller and Storwize® Family.

AccessibilityIBM® strives to provide products with usable access for everyone, regardless of age or ability.

This product uses standard Windows navigation keys.

For more information, see the accessibility features topic in the “Reference” section.

EmphasisDifferent typefaces are used in this guide to show emphasis.

The following typefaces are used to show emphasis.

Emphasis Meaning

Boldface Text in boldface represents menu items.

Bold monospace Text in bold monospace represents command names.

Italics Text in italics is used to emphasize a word. In commandsyntax, it is used for variables for which you supplyactual values, such as a default directory or the name ofa system.

Monospace Text in monospace identifies the data or commands thatyou type, samples of command output, examples ofprogram code or messages from the system, or names ofcommand flags, parameters, arguments, and name-valuepairs.

Syntax diagramsA syntax diagram uses symbols to represent the elements of a command and to specify the rules forusing these elements.

Table 1 on page xii explains how to read the syntax diagrams that represent the command-line interface(CLI) commands. In doing so, it defines the symbols that represent the CLI command elements.

© Copyright IBM Corp. 2018 xi

Table 1. Syntax diagrams

Element Syntax Description

Main path line >>>() () () The main path line begins on the leftwith double arrowheads: >>. Themain path line ends on the rightwith two arrowheads facing eachother: >

Read the diagrams from left-to-right,top-to-bottom, following the mainpath line.

Keyword►► esscli ►◄

Represents the name of a command,flag, parameter, or argument. Akeyword is not in italics. Spell akeyword exactly as it is shown inthe syntax diagram.

Required keywords►► a AccessFile

u Useridp Password

►◄Indicate the parameters orarguments that you must specify forthe command. Required keywordsmust be written on the main pathline. Required keywords that cannotbe used together are stackedvertically.

Optional keywords►►

h-help?

►◄Indicate the parameters orarguments that you can choose tospecify for the command. Optionalkeywords must be written below themain path line. Mutually exclusiveoptional keywords are stackedvertically.

Default value

►►FCP

protocol = FICON ►◄

The default value must be writtenabove the main path line.

Repeatable keywordor value ►► newports = ALL

PortId1,PortId2,...►◄

Represents a parameter or argumentthat you can specify more than once.A repeatable keyword or value isrepresented by an arrow returning tothe left above the keyword or value.

Variable►► AccessFile ►◄

Represents the value that you needto supply for a parameter orargument, such as a file name, username, or password. Variables are initalics.

Space separator►► u Userid p Password ►◄

Adds a blank space on the mainpath line to separate keywords,parameters, arguments, or variablesfrom each other.

xii Spectrum Virtualize: RESTful API

Table 1. Syntax diagrams (continued)

Element Syntax Description

Quotation markdelimiters ►► d " ess = EssId host = ►

► 'Host Name' profile = ProfileName ►

► " ►◄

Indicates the start and end of aparameter or argument that containsmultiple values. Enclose one or morename-value pairs in a set of doublequotation marks for a particularparameter or argument. If the valueof a parameter or name-value paircontains a blank or white space,enclose the entire value in a set ofsingle quotation marks.

Equalsign operator►► " ess = EssId profile = ►

► ProfileName " ►◄

Separates a name from its value in aname-value pair.

Syntax fragment►► Fragment Name ►◄

Fragment name:

( fragment details )

Breaks up syntax diagrams that aretoo long, too complex, or repetitious.The fragment name is inserted in themain diagram, and the actualfragment is shown below the maindiagram.

CLI special charactersThe following special characters are used in the command-line interface (CLI) command examples.

minus (-) signFlags are prefixed with a - (minus) sign. Flags define the action of a command or modify theoperation of a command. You can use multiple flags, followed by parameters, when you issue acommand. The - character cannot be used as the first character of an object name.

vertical bar (|)A vertical bar signifies that you choose only one value. For example, [ a | b ] in bracketsindicates that you can choose a, b, or nothing. Similarly, { a | b } in braces indicates that youmust choose either a or b.

delimiters (: or , or !)Delimiters are used to delimit items listed after issuing an information command.v Colon (:) is used to delimit items in a list in a command (for example mkhost -name myhost

-hbawwpn AA22000011112222:AA22000011112223).v Comma (,) is used to delimit items in a list in a command if item values can contain a colon.v Exclamation mark (!) is used to delimit items in a command if the item values can contain a

colon or comma. Exclamation points generally do not show up in example output and are agood delimiter to use.

Using wildcards in the CLIYou can use wildcards in the system command-line interface (CLI).

The CLI supports the use of the asterisk character (*) as a wildcard within the arguments of certainparameters. There are some behavioral issues that must be considered when using wildcards in order toprevent unexpected results. These behavioral issues and the ways to avoid them are as follows:1. Running the command while logged onto the node.

About this guide xiii

The shell will attempt to interpret any of the special characters if they are not escaped (preceded witha backslash character). Wildcards will be expanded into a list of files if any files exist that match thewildcards. If no matching files exist, the wildcard is passed to the system command untouched.To prevent expansion, issue the following command in one of its formats:

cleardumps -prefix '/dumps/*.txt' with single quotation marks(’’), or

cleardumps -prefix /dumps/\*.txt using a backslash (\), or

cleardumps -prefix "/dumps/*.txt" with double quotation marks("").

2. Running the command through Secure Shell (SSH), for example from a host.This method is slightly more complicated because the host shell processes the command line before itis passed through SSH to the shell on the clustered system (system). This means an extra layer ofprotection is required around the wildcard as the host shell will strip off any protecting quotes, and ifthe wildcard is exposed to the system shell, this will result in the wildcard being expanded in thesystem shell.To prevent expansion, issue the following command in one of its formats:

cleardumps "'/dumps/*.txt'" with single quotation marks (’’)inside of double quotation marks (""), or

cleardumps '/dumps/\*.txt' using a backslash (\) inside ofsingle quotation marks (’’), or

cleardumps '"/dumps/*.txt"' with double quotation marks ("")inside of single quotation marks (’’).

Data types and value rangesThe maximum length of any single parameter entered into the command line is 2176 bytes.

Note: When creating a new object, the clustered system (system) assigns a default -type name if one isnot specified. The default -type name consists of the object prefix and the lowest available integerstarting from 0 (except for nodes starting from 1); for example, vdisk23; the default -type name must beunique.

Table 2 lists the data types and the value ranges for each.

Table 2. Data types

Data types Value ranges

filename_arg This is a (optionally fully qualified) file name, containing a maximum of 169characters. Valid characters are:

v . (period; the field must not start with, end with, or contain two consecutiveperiods)

v / (forward slash)v - (hyphen)v _ (underscore)v a–z (lowercase letters, A through Z)v A–Z (uppercase letters, A through Z)v 0–9 (numerals 0 through 9)

xiv Spectrum Virtualize: RESTful API

Table 2. Data types (continued)


directory_or_file_filter Specifies a directory, file name filter, or both, within the specified directory. Validdirectory values are:

v /dumpsv /dumps/auditv /dumps/configsv /dumps/elogsv /dumps/featurev /dumps/iostatsv /dumps/iotracev /dumps/software

The file name filter can be any valid file name, containing a maximum of 128characters, with or without the “*” (wildcard), and appended to the end of adirectory value. Valid characters are:

v * (asterisk/wildcard)v . (the field must not start with, end with, or contain two consecutive periods)v /v -v _v a–zv A–Zv 0–9

filename_prefix The prefix of a file name, containing a maximum of 128 characters. Valid charactersare:

v -v _v a–zv A–Zv 0–9

name_arg Names can be specified or changed using the create and modify functions. The viewcommands provide the name and ID of an object.Note: The system name is set when the system is created.

The first character of a name_arg must be nonnumeric. The first character of an objectname cannot be a – (dash) because the CLI (command-line interface) interprets it asbeing the next parameter.

Valid characters are:

v . (a period - the field must not start with, end with, or contain two consecutiveperiods)

v /v -v _v spacev a through zv A through Zv 0 through 9

About this guide xv



password This is a user-defined password containing a maximum of 15 characters. Validcharacters are:

v - (cannot be used as the first character)v _v a–zv A–Zv 0–9

serial_number The format of this number conforms to IBM standard C-S 1-1121-018 1999-06 SerialNumbering for IBM products. The serial number is 7 digits, the first two of whichdefine the manufacturing location, leaving 5 digits for the product.

The standard defines a way to extend the serial number using letters in the place ofnumbers in the 5-digit field.

ip_address_arg The argument follows the standard rules for dotted decimal notation.

The following Internet Protocol 4 (IPv4) and Internet Protocol 6 (IPv6) addressformats are supported:

IPv4 (no port set, SAN Volume Controller uses default)1.2.3.4

IPv4 with specific port1.2.3.4:22

Full IPv6, default port1234:1234:0001:0123:1234:1234:1234:1234

Full IPv6, default port, leading zeros suppressed1234:1234:1:123:1234:1234:1234:1234

Full IPv6 with port[2002:914:fc12:848:209:6bff:fe8c:4ff6]:23

Zero-compressed IPv6, default port2002::4ff6

Zero-compressed IPv6 with port[2002::4ff6]:23

dns_name This is the dotted domain name for the system subnet (for example,yourcompany.com).

hostname The host name assigned to the system. This name can be different from the systemname, and is modifiable.

A combination of the host name and the dns_name is used to access the system, forexample: https://hostname.yourcompany.com

capacity_value The capacity expressed within a range of 512 bytes to 2 petabytes (PB).Tip: Specify the capacity as megabytes (MB), kilobytes (KB), gigabytes (GB), or PB.When using MB, specify the value in multiples of 512 bytes. A capacity of 0 is validfor a striped or sequential volume. The smallest number of supported bytes is 512.

node_id A node ID differs from other IDs in that it is a unique ID assigned when a node isused to create a system, or when a node is added to a system. A node_id value isnever reused in a system.

Node IDs are internally represented as 64-bit numbers, and like other IDs, cannot bemodified by user commands.

xvi Spectrum Virtualize: RESTful API



xxx_id All objects are referred to by unique integer IDs, assigned by the system when theobjects are created. All IDs are represented internally as 32-bit integers; node IDs arean exception.

IDs in the following ranges identify the various types of objects:

v node_id: A positive decimal integer greater than or equal to 1v mdisk_grp_id: 0–127v io_grp_id: 0–3 (See Note.)v mdisk_id: 0–4095v vdisk_id: 0–8191v copy_id: 0–1v host_id: 0–1023v flash_const_grp_id: 0–255v remote_const_grp_id: 0–255v fcmap_id: 0–4095v rcrel_id: 0–8191v controller_id: 0–63

Note: The io_group 4 exists but is used only in certain error recovery procedures.

These IDs, like node IDs, cannot be modified by user commands.Note: IDs are assigned at run time by the system and cannot be relied upon to bethe same after; for example, the configuration restoration. Use object names inpreference to IDs when working with objects.

xxx_list A colon-delimited list of values of type xxx.

wwpn_arg The Fibre Channel worldwide port name (WWPN), expressed as a 64-bithexadecimal number and consisting of the characters 0–9, a–f, and A–F; for example:1A2B30C67AFFE47B.Note: Entering WWPN 0 in the command string causes a command failure.

panel_name This is a string of up to six characters corresponding to the number on the printedlabel below the display on the front panel of a node in the system.

sequence_number A 32-bit unsigned integer, expressed in decimal format.

csi_num_arg A 32-bit unsigned integer, expressed in decimal format.

percentage_arg An 8-bit unsigned integer, expressed in decimal 0–100 format.

extent_arg A 32-bit unsigned integer, expressed in decimal format.

num_extents_arg A 32-bit unsigned integer, expressed in decimal format.

threads_arg An 8-bit unsigned integer, expressed in decimal format. Valid values are 1, 2, 3, or 4.

velocity_arg The fabric speed in gigabytes per second (GBps). Valid values are 1 or 2.

timezone_arg The ID as detailed in the output of the lstimezones command.

timeout_arg The command timeout period. An integer from 0 to 600 (seconds).

stats_time_arg The frequency at which statistics are gathered. Valid values are 1 to 60 minutes inincrements of 1 minute.

About this guide xvii



directory_arg Specifies a directory, file name filter, or both, within the specified directory. Validdirectory values are:

v /dumpsv /dumps/auditv /dumps/cimomv /dumps/configsv /dumps/elogsv /dumps/featurev /dumps/iostatsv /dumps/iotracev /home/admin/upgrade

The file name filter can be any valid file name, containing a maximum of 128characters, with or without the wildcard (*, an asterisk), and appended to the end ofa directory value. Valid characters are:

v *v . (the field must not start with, end with, or contain two consecutive periods)v /v -v _v a–zv A–Zv 0–9

locale_arg The system locale setting. Valid values are:

v 0 en_US: US English (default)v 1 zh_CN: Simplified Chinesev 2 zh_TW: Traditional Chinesev 3 ja_JP: Japanesev 4 fr_FR: Frenchv 5 de_DE: Germanv 6 it_IT: Italianv 7 es_ES: Spanish

key_arg A user-defined identifier for a secure shell (SSH) key, containing a maximum of 30characters.

user_arg Specifies the user: admin or service.

copy_rate A numeric value of 0–100.

copy_type Specifies the Mirror copy type: Metro or Global.

The maximum number of values entered into a colon-separated list is 128; exceeding this maximumnumber returns an error.

CLI commands and parametersCommand-line interface (CLI) commands and parameters are represented in the syntax diagram.

The system command-line interface offers command line completion for command entry. Command linecompletion allows you to type in the first few characters of a command and press the Tab key to fill in

xviii Spectrum Virtualize: RESTful API

the rest of the command name. If there are multiple commands that start with the same characters, then alist of possible commands is returned. You can type in more characters until the command name isunambiguous.

CLI parameters can be entered in any order except in the following situations:v When a command name is specified, the first argument given must be the action that you want to be

performed.v Where you are specifying a command against a specific object, the object ID or name must be the last

argument in the line.

A valid parameter meets the following requirements:v Parameters can be entered in any order.v If a parameter has an associated argument, the argument must always follow the parameter.v A parameter must start with a '-'; otherwise, it is assumed to be an argument.v The maximum length of any single parameter that can be entered into the CLI is 128 bytes.v An argument can contain multiple data items. The maximum number of data items that you can enter

into such a list is 128. For a component list, separate the individual items by a colon.v Any parameter with an argument can be entered as -parameter=argument.v Entering -param= means the argument is an empty string, equivalent to -param.v The symbol '--' is valid as the next to last entry on the command line. It specifies that the next entry is

the target object name or ID, even if it begins with a hyphen.chuser -usergrp=-usergrp -- -password

v The symbol '--' is valid as the final word on the command line.

Examples that are validmkuser -name fred -usergrp 0 -password bucketsmkuser -name fred -usergrp 0 -password=bucketsmkuser -name=-barney -usergrp=0 -password=buckets

chuser -usergrp 1 fredchuser -usergrp 1 -- fredchuser -usergrp 1 -- -barney

Examples that are invalidchuser -usergrp 1 fred --chuser -usergrp 1 -- fred --chuser -- -usergrp 1 fredchuser -usergrp 1 -barney

CLI flagsThe following flags are common to all command-line interface (CLI) commands.

-? or -hPrint help text. For example, issuing lssystem -h provides a list of the actions available with thelssystem command.

-nomsgWhen used, this flag prevents the display of the successfully created output. For example, ifyou issue the following command:

mkmdiskgrp -ext 16

it displays:

MDisk Group, id [6], successfully created

About this guide xix

However, if the -nomsg parameter is added, for example:

mkmdiskgrp -ext 16 -nomsg

the following information is displayed:

6

This parameter can be entered for any command, but is only acted upon by those commands thatgenerate the successfully created outputs. All other commands ignore this parameter.

CLI messagesEnsure that you are familiar with the command-line interface (CLI) messages.

When some commands complete successfully, textual output is normally provided. However, somecommands do not provide any output. The phrase No feedback is used to indicate that no output isprovided. If the command does not complete successfully, an error is generated. For example, if thecommand has failed as a result of the cluster being unstable, the following output is provided:v CMMVC5786E The action failed because the cluster is not in a stable state.

The Knowledge Center has a description of each message you might see.

Understanding capacity indicatorsThe system uses base-2 (binary numeral) as capacity indicators for volumes, drives, and other systemobjects. The management GUI and the command-line interface (CLI) use different abbreviations toindicate capacity.

The following table displays the differences in how capacity indicators are displayed in the managementGUI and the CLI.

Table 3. Capacity indicators. This table displays the differences in how capacity indicators are displayed in themanagement GUI and the CLI.

Metric GUI Abbreviation CLI Abbreviation Value

kibibyte KiB KB 1024

mebibyte MiB MB 1,048,576

gibibyte GiB GB 1,073,741,824

tebibyte TiB TB 1,099,511,627,776

pebibyte PiB PB 1,125,899,906,842,624

exbibyte EiB EB 1,152,921,504,606,846,976

zebibyte ZiB ZB 1,180,591,620,717,411,303,424

yobibyte YiB YB 1,208,925,819,614,629,174,706,176

Attributes of the -filtervalue parametersThe -filtervalue parameter filters a view that is based on specific attribute values that relate to eachobject type. You can combine multiple filters to create specific searches, for example, -filtervaluename=fred:status=online. The help (-filtervalue) specifies the attributes that are available for eachobject type.

The -filtervalue parameter must be specified with attrib=value. The -filtervalue? and -filtervalueparameters cannot be specified together.

xx Spectrum Virtualize: RESTful API

https://www.ibm.com/support/knowledgecenter/STVLF4

Note: The qualifier characters less than () must be enclosed within double quotationmarks (""). For example, -filtervalue vdisk_count ""1. It is also valid to includethe entire expression within double quotation marks. For example, -filtervalue "vdisk_count

xxii Spectrum Virtualize: RESTful API

Chapter 1. Spectrum Virtualize RESTful API

The Spectrum Virtualize Representational State Transfer (REST) model Application Programming Interface(API) consists of command targets that are used to retrieve system information and to create, modify, anddelete system resources. These command targets allow command parameters to pass through unedited tothe Spectrum Virtualize command line interface, which handles parsing parameter specifications forvalidity and error reporting. Use Hypertext Transfer Protocol Secure (HTTPS) to successfullycommunicate with the RESTful API server.

The RESTful API server does not consider transport security (such as SSL), but instead assumes thatrequests are initiated from a local, secured server. The HTTPS protocol provides privacy through dataencryption. The RESTful API provides more security by requiring command authentication, whichpersists for two hours of activity, or 30 minutes of inactivity, whichever occurs first.

Uniform Resource Locators (URLs) target different node objects on the system. The HTTPS POST methodacts on command targets that are specified in the URL. For more information, see “RESTful APIcommand targets and characteristics” on page 2. To make changes or view information about differentobjects on the system, you must create and send a request to the system. You are required to providecertain elements for the RESTful API server to receive and translate the request into a command, asdescribed in the next section.

Making an HTTPS request

To interact with the system by using the RESTful API, make an HTTPS command request with a validconfiguration node URL destination. Include the 7443 port and the keyword rest. Use the following URLformat for all requests:https://system_node_ip:7443/rest/command

Where:v system_node_ip is the system IP address, which is the address that is taken by the configuration node of

the system.v The port number is always 7443 for the Spectrum Virtualize RESTful API.v rest is a keyword.v command is the target command object (such as auth or lseventlog with any parameters).

The command specification follows this format:command_name,method="POST",headers={’parameter_name’: ’parameter_value’,’parameter_name’: ’parameter_value’,...}

Why we use POST exclusively: All of the Spectrum Virtualize RESTful API command targets are namedafter Spectrum Virtualize commands, with names that already reflect Create, Read, Update, and Deleteactions. MK commands make (create) resources, LS commands list (read) resources, CH commandschange (update) resources, and RM commands remove (delete) resources. Using HTTP methods on top ofsuch commands is redundant.

All commands, including LS commands, accept at least one named parameter. Because the SpectrumVirtualize RESTful API is POST method only, it implements a convention of appending positionalparameters to the URI, and packing named parameters into the request body as JavaScript ObjectNotation (JSON) strings.

Why we do not use GET: Most HTTP servers reject GET requests with body data. To support GETwould mean appending named parameters to the URI as a query string. Do not include such arbitrary

© Copyright IBM Corp. 2018 1

data in a query string. A valid URI cannot contain whitespace and other reserved characters that mightbe present in the data. Therefore, you must URL-encode named parameter data before you append it tothe URI. In addition to that inconvenience, the key-value structure of named parameter data must beconveyed in some way. The query string would likely be a URL-encoded JSON object. Supporting theGET method means that parameter data represented in your programming language of choice must passthrough two separate encoders before the data is sent as part of an HTTP request.

The more elegant method for the command targets was to adopt POST exclusively.

As mentioned, in addition to the URL and the name of the command target, other information is requiredin the request line and in the body of the HTTP request that regards the action to take on the specifiedobject. In the request line, include the POST HTTP method. Include any required parameters (such asRAID level or IP address) in the body of the request.

Provide any required parameters as valid JSON in the HTTP body, such as shown in the followingexample:{’X-Auth-Username’: ’superuser’}

The request is routed to port 7443 on the specified destination (which must be the configuration node ofthe system), where the request is received by the RESTful API server. The server runs the command,collects any resulting output, then creates an HTTP response like the following example:HTTP/1.1 200 OKServer: lighttpd/1.4.31Date: dateContent-type: application/json; charset=UTF-8Content-length: content_lengthConnection: close{“attribute”: “value”}

To view API command targets and their characteristics, see “RESTful API command targets andcharacteristics.” To see an example of how to get started, see “Getting started” on page 4. SeeAppendix C, “HTTP error messages,” on page 777 for a complete list of HTTP error codes that you mightencounter.

RESTful API command targets and characteristics

Table 4 stresses the POST method for all commands, including /auth. It also shows that you must use theauthentication token that is returned by the /auth command target to authenticate every other commandyou run. Except for the /auth command target, you run commands against the system IP address so thatthey are run by the configuration node.

Table 4. POST method, authentication requirements, and whether to run on the configuration node

Command targets Method Authentication requiredRun in ConfigurationNode / Cluster

/auth POST No No

All other command targets POST Yes Yes

Table 5 on page 3 shows the command target names of commonly used commands for this release of theRESTful API. Following convention, the svcinfo and svctask executable commands are defaults and donot require listing within your RESTful API command targets.

Descriptions of the command targets and their parameters, and descriptions of other less frequently usedcommands are available in the CLI command section of the product documentation.

2 Spectrum Virtualize: RESTful API

Table 5. Supported RESTful API commands for Spectrum Virtualize software

Command targets

/addhostclustermember /addhostiogrp /addhostport

/addvdiskaccess /addvdiskcopy /addvolumecopy

/auth /chhost /chnode

/chnodecanister /chrcconsistgrp /chrcrelationship

/chvdisk /expandvdisksize /lscurrentuser

/lseventlog /lsfcconsistgrp /lsfcmap

/lsfcmapcandidate /lsfcmapdependentmaps /lsfcmapprogress

/lshost /lshostcluster /lshostclustermember

/lshostclustervolumemap /lshostiogrp /lshostvdiskmap

/lsiogrp /lsiogrphost /lsmdiskgrp

/lsnode /lsnodecanister /lsnodehw

/lsnodecanisterhw /lsnodecanisterstats /lsnodecanistervpd

/lsnodehw /lsnodestats /lsnodevpd

/lspartnership /lsrcrelationshipprogress /lssystem

/lssystemip /lssystemstats /lsvdisk

/lsvdiskaccess /lsvdiskcopy /lsvdiskfcmapcopies

/lsvdiskfcmappings /lsvdiskhostmap /lsvdisksyncprogress

/mkfcconsistgrp /mkfcmap /mkfcpartnership

/mkhost /mkhostcluster /mkrcconsistgrp

/mkrcrelationship /mkvdisk /mkvdiskhostmap

/mkvolume /mkvolumehostclustermap /movevdisk

/prestartfcconsistgrp /prestartfcmap /rmfcmap

/rmhost /rmhostcluster /rmhostclustermember

/rmhostiogrp /rmhostport /rmvdisk

/rmvdiskaccess /rmvdiskcopy /rmvdiskhostmap

/rmvolume /rmvolumecopy /rmvolumehostclustermap

/startfcmap /startrcconsistgrp /startrcrelationship

/stopfcconsistgrp /stopfcmap /stoprcconsistgrp

/stoprcrelationship

Authentication overview

Aside from data encryption, the HTTPS server requires authentication of a valid user name and passwordfor each API session. Use two authentication header fields to specify your credentials: X-Auth-Usernameand X-Auth-Password.

Initial authentication requires that you POST the authentication target (/auth) with the user name andpassword. The RESTful API server returns a hexadecimal token. A single session lasts a maximum of twoactive hours or thirty inactive minutes, whichever occurs first. When your session ends due to inactivity,or if you reach the maximum time that is allotted, error code 403 indicates the loss of authorization. Usethe /auth command target to reauthenticate with the user name and password.

Chapter 1. Spectrum Virtualize RESTful API 3

For example, the following command passes the authentication command to target node IP 192.168.10.109at port 7443:https://192.168.10.109:7443/rest/auth, method="POST",

headers={’X-Auth-Username’: ’superuser’, ’X-Auth-Password’: ’passw0rd’}

The HTTP request that was sent to the API server looks like:POST /auth HTTPS/HTTPS_versionHost: https://192.168.10.109:7443Content-type: application/json; charset=UTF-8Content-length: message_sizeX-Auth-Token: 58cfd6acb1676e1cba78b7cb5a9a081d11d1d1cfeb0078083ef225d9c59bf4df

{“attribute”: “value”,“attribute”: “value”}

Where:v The first line is the request line with the POST method, API target, protocol (HTTPS), and protocol

version (1.1).v The second line is the host header, directing the HTTP request to the correct port (7443) and IP address

on the system.v The third line is the content type header that specifies the content type (application/json;

charset=UTF-8).v The fourth line is the content length header with the message size.v The fifth line is the authentication token header, with the authentication token.v A space is left between the headers and the body of the request. Any parameters appear in JSON on

the seventh line.

The successful auth command returns a token similar to the following example:{"token": "58cfd6acb1676e1cba78b7cb5a9a081d11d1d1cfeb0078083ef225d9c59bf4df"}

Command target parameters

Command targets interact with different parts of the system. After you target a specific node in thesystem (usually a configuration node), target an object within that node. See Table 5 on page 3 forcommand targets and see the CLI commands section of this product documentation for individualcommand descriptions of parameters that you can specify.

Getting started

The following Python 3 example shows how to complete initial setup to start interacting with the systemand running commands. For examples in other languages, see Appendix D, “Usage examples in Perl,” onpage 779 and Appendix E, “Usage examples in CURL,” on page 781.import sslimport jsonimport pprint

import urllib.requestimport urllib.errorimport urllib.parse

no_verify = ssl.create_default_context()no_verify.check_hostname = Falseno_verify.verify_mode = ssl.CERT_NONE

if getattr(ssl, ’_https_verify_certificates’, None):ssl._https_verify_certificates(False)


class HostString(str):"""

Comment: Special subclass of string, for storing arbitrary host-relatedattributes (such as auth tokens) without losing any string behavior

"""def __new__(cls, *args, **kwds):

return super(HostString, cls).__new__(cls, *args, **kwds)

class RESTUtil(object):show_default=Falsedefault_headers = {}port = 80

def __init__(self, show=None, catch=True):self.hosts = {}self.curr_host = Noneself.catch=catchself.show_default=show if show != None else self.show_default

@propertydef host(self):

return self.curr_host

@host.setterdef host(self, hostname):

"""Comment: Retrieve the HostString object of a known host from its

host name or string definition. Even if the host definitionis provided, we still need to key into self.hosts in case theclient classes are storing things on their HostString objects.

"""try:

if hostname in self.hosts:self.curr_host = self.hosts[hostname]

else:self.curr_host = [h for h in self.hosts.values() if h == hostname][0]

return self.curr_hostexcept IndexError:

raise KeyError("Unrecognized host/name %s" % hostname)

def add_host(self, hostdef, hostname=None):hostname = hostname if hostname is None else hostdefself.hosts[hostname] = HostString(hostdef)if self.curr_host == None:

self.curr_host = self.hosts[hostname]return hostname

def command(self, protocol, postfix, method=’POST’, headers=None, show=None, **cmd_kwds):"""

Comment: A fairly generic RESTful API request builder.See subclasses for examples of use.

"""if show == None:

show = self.show_defaultheaders = {} if headers == None else headersurl = ’%s://%s:%s/%s’ % (

protocol,self.curr_host,self.port,postfix

)request = urllib.request.Request(

url,headers =dict(self.default_headers, **headers),data=bytes(json.dumps(cmd_kwds), encoding="utf-8") if cmd_kwds else None)

request.get_method = lambda: methodif show:


self.request_pprint(request)try:

cmd_out = urllib.request.urlopen(request, context=no_verify).read().decode(’utf-8’)except urllib.error.HTTPError as e:

self.exception_pprint(e)if not self.catch:

raise Exception("RESTful API command failed.")return

try:cmd_out = json.loads(cmd_out)

except ValueError:pass

if show:print("\nCommand Output:")pprint.pprint(cmd_out)print("")

return cmd_out

@staticmethoddef request_pprint(request):

"""Comment: Request info print function

(for self.command with show=True)"""print(request.get_method(), request.get_full_url(), ’HTTP/1.1’)print(’Host:’, request.host)for key, value in request.headers.items():

print(key.upper() + ’:’, str(value))if request.data != None:

print()pprint.pprint(request.data)

@staticmethoddef exception_pprint(http_error):

"""Comment: HTTPError info print function

"""print(http_error.code, ’--’, http_error.reason)print(http_error.fp.read())print("")

class SVCREST(RESTUtil):"""

Comment: RESTful wrapper for the SVC CLI"""

def __init__(self, host, *args, **kwds):self.debug = kwds.pop(’debug’, False)super().__init__(*args, **kwds)self.add_host(host)

@propertydef default_headers(self):

return {’X-Auth-Token’: getattr(self.curr_host, ’token’, ’badtoken’),’Content-Type’: ’application/json’}

@propertydef port(self):

return getattr(self, ’_port’, None) or (’7665’ if self.debug else ’7443’)

@propertydef protocol(self):

return getattr(self, ’_protocol’, None) or (’http’ if self.debug else ’https’)

def command(self, cmd, *args, method="POST", headers=None, show=None, **cmd_kwds):postfix = ’/’.join(

[’rest’] + [cmd] + [urllib.parse.quote(str(a)) for a in args]


)return super().command(

self.protocol,postfix,method=method,headers=headers,show=show,**cmd_kwds

)

def authenticate(self, username=’superuser’, password=’passw0rd’, show=None):cmd_out = self.command(

’auth’, show=show, method="POST", headers={’X-Auth-Username’: username, ’X-Auth-Password’: password})if cmd_out:

self.curr_host.token = cmd_out[’token’]"""

Comment: First, set your cluster ipaddress.It’s assumed superuser/passw0rd (6 lines above) is the crednetial.After the authenticate call, you can issue any command in

s.command(’’) that is an svcinfo or svctask cmmand)"""

s = SVCREST(’192.168.10.109’)s.authenticate()print(s.command(’lssystem’))


Chapter 2. API management

To authenticate, use the Superuser ID and the authentication (auth) target.

Authentication

Use the authentication command target (auth) to authenticate using the POST method. In this process,you provide a username and password through the X-Auth-Username and X-AuthPassword headerfields. The beginning of the session is the only instance where you must enter the username andpassword. Upon successfully entering the username and password, an authentication token is displayed.This token is a 32-digit, hexadecimal code that you include in future commands using the X-Auth-Tokenheader. The X-Auth-Token header in combination with the authentication token replaces the usernameand password for each action. The token is good for one session, but after two hours of activity or thirtyminutes of inactivity, the session times out. Repeat authentication for another token. For information onsystem authentication, see “Authentication overview” on page 3.


Chapter 3. Using the CLI

The command-line interface (CLI) is a collection of commands that you can use to manage the clusteredsystem (system).

Overview

The CLI commands use the Secure Shell (SSH) connection between the SSH client software on the hostsystem and the SSH server on the system.

Note: Before you can use the CLI, you must create a system.

To use the CLI from a client system, complete the following steps:v Install and set up SSH client software on each system that you plan to use to access the CLI.v Authenticate to the system by using a password.v Use an SSH public key if you require command line access without entering a password. Then, store

the SSH public key for each SSH client on the system.

Note: After the first SSH public key is stored, you can add SSH public keys by using either themanagement GUI or the CLI.

Use the CLI commands to change or create arrays, drives, enclosures, storage pools, and volumes. Youcan also use the CLI commands to specify encryption or security settings or work with systems.

For example, use the CLI commands to:v Set up the system, its nodes, and the I/O groups.v Set up and maintain canisters and enclosures.v Analyze error logs event logs (logs).v Set up and maintain managed disks (MDisk) and storage pools.v Set up and maintain client public SSH keys on the system.v Set up and maintain volumes.v Setup logical host objects.v Map volumes to hosts.v Navigate from managed hosts to volumes and MDisks (and the reverse direction up the chain).v Set up and start Copy Services functions:

– For FlashCopy® and FlashCopy consistency groups– For Synchronous Metro Mirror and Metro Mirror consistency groups and relationships– For Asynchronous Global Mirror and Global Mirror consistency groups and relationships– For active-active consistency groups and relationships

v Setup licensing or featurization settings.

CLI commands generally give feedback whether or not the command ran. Check the audit log or eventlog (for configuration events, for example) after you specify a command to verify successful completion.You can also check the I/O group of the volume that you change.

Setting the clustered system time by using the CLIYou can use the command-line interface (CLI) to set the clustered system (system) time.


About this task

To set the system time:

Procedure1. Issue the showtimezone CLI command to display the current time-zone settings for the system. The

time zone and the associated time-zone ID are displayed.2. Issue the lstimezones CLI command to list the time zones that are available on the system. A list of

valid time-zone settings are displayed. Each time zone is assigned an ID. The time zone and theassociated ID are indicated in the list.

3. Issue the following CLI command to set the time zone for the system.settimezone -timezone time_zone_setting

where 031809142005time_zone_setting is the new time zone ID that you chose from the list of timezones that are available on the system.

4. Issue the following CLI command to set the time for the system:setsystemtime -time 031809142005

where 031809142005 is the new time that you want to set for the system. You must use theMMDDHHmmYYYY format to set the time for the system.

Setting cluster date and timeYou can set the date and time for a system cluster from the System Date and Time Settings panel.

Before you begin

This task assumes that you have already launched the management GUI.

About this task

You can set the System Date and time manually, or by specifying an NTP server:

Procedure1. Click Manage Systems > Set System Time in the portfolio. The System Date and Time Settings panel

is displayed.2. To use NTP to manage the clustered system date and time, enter an Internet Protocol Version 4 (IPv4)

address and click Set NTP Server.

Note: If you are using a remote authentication service to authenticate users to the system, then boththe system and the remote service should use the same NTP server. Consistent time settings betweenthe two systems ensure interactive performance of the management GUI and correct assignments foruser roles.

3. To set the clustered system date and time manually, continue with the following steps.4. Type your changes into the Date, Month, Year, Hours, and Minutes fields and select a new time zone

from the Time Zone list.5. Select Update cluster time and date, Update cluster time zone, or both.6. Click Update to submit the update request to the clustered system.

Viewing and updating license settings by using the CLIYou can use the command-line interface (CLI) to view and update your license settings.


About this task

Your system provides two license options: Physical Disk Licensing and Capacity Licensing. To view andupdate your system license settings:

Procedure1. Issue the lslicense CLI command to view the current license settings for the clustered system

(system).2. Issue the chlicense CLI command to change the licensed settings of the system.

Attention:

v License settings are entered when the system is first created; do not update the settings unless youchange your license.

v To select Physical Disk Licensing, run the chlicense command with one or more of thephysical_disks, physical_flash, and physical_remote parameters.

v To select Capacity Licensing, run the chlicense command with one or more of the -flash, -remote,and -virtualization parameters. If the physical disks value is nonzero, these parameters cannot beset.

Displaying clustered system properties by using the CLIYou can use the command-line interface (CLI) to display the properties for a clustered system (system).

About this task

These actions help you display your system property information.

Procedure

Issue the lssystem command to display the properties for a system.The following command is an example of the lssystem command you can issue:lssystem -delim : build1

where build1 is the name of the system.

Chapter 3. Using the CLI 13

Resultsid:000002007A00A0FEname:build1location:localpartnership:bandwidth:total_mdisk_capacity:90.7GBspace_in_mdisk_grps:90.7GBspace_allocated_to_vdisks:14.99GBtotal_free_space:75.7GBstatistics_status:onstatistics_frequency:15required_memory:0cluster_locale:en_UStime_zone:522 UTCcode_level:6.1.0.0 (build 47.3.1009031000)FC_port_speed:2Gbconsole_IP:9.71.46.186:443id_alias:000002007A00A0FEgm_link_tolerance:300gm_inter_cluster_delay_simulation:0gm_intra_cluster_delay_simulation:0email_reply:email_contact:email_contact_primary:email_contact_alternate:email_contact_location:email_state:stoppedinventory_mail_interval:0total_vdiskcopy_capacity:15.71GBtotal_used_capacity:13.78GBtotal_overallocation:17total_vdisk_capacity:11.72GBcluster_ntp_IP_address:cluster_isns_IP_address:iscsi_auth_method:noneiscsi_chap_secret:auth_service_configured:noauth_service_enabled:noauth_service_url:auth_service_user_name:auth_service_pwd_set:noauth_service_cert_set:norelationship_bandwidth_limit:25gm_max_host_delay:5tier:generic_ssdtier_capacity:0.00MBtier_free_capacity:0.00MBtier:generic_hddtier_capacity:90.67GBtier_free_capacity:75.34GBemail_contact2:email_contact2_primary:email_contact2_alternate:total_allocated_extent_capacity:16.12GB

Maintaining passwords using the CLIYou can use the command-line interface (CLI) to view and change the status of the password resetfeature for the system.

The superuser password can be reset to its default value of passw0rd by using the technician port on SANVolume Controller 2145-DH8 nodes or the front panel on earlier models of the system. To meet varyingsecurity requirements, this functionality can be enabled or disabled by using the CLI.

Complete the following steps to view and change the status of the password reset feature:


1. Issue the setpwdreset CLI command to view and change the status of the password reset feature forthe system.

2. Record the system superuser password because you cannot access the system without it.

The system superuser password can be reset by using a USB key. To meet varying security requirements,this functionality can be enabled or disabled by using the CLI. Complete the following steps to view andchange the status of the password reset feature:1. Issue the setpwdreset CLI command to view and change the status of the password reset feature for

the system.2. Record the system superuser password because you cannot access the system without it.

Using the dump commands to work with directoriesThe lsdumps command returns a list of dumps in a particular directory.

Dumps are contained in the following directory structure:v /dumpsv /dumps/auditv /dumps/cimomv /dumps/elogsv /dumps/featurev /dumps/iostatsv /dumps/iotracev /dumps/mdiskv /home/admin/updatev /dumps/drivev /dumps/enclosure

Use the lsdumps command with the optional prefix parameter to specify a directory. If you do notspecify a directory, /dumps is used as the default. Use the optional node_id_or_name parameter to specifythe node to list the available dumps. If you do not specify a node, the available dumps on theconfiguration node are listed.

Use the cpdumps command to copy dump files from a nonconfiguration node to the configuration node.You can use this command to retrieve dumps that were saved to an older configuration node. You canretrieve files and put them on the configuration node to be copied.

Use the cleardumps command to delete dump directories on a specified node. You can clear specific filesor groups of files based on the use of a wildcard (an asterisk, *). You can delete files on a single directoryor all of the dump directories (by specifying the /dumps variable).

An audit log tracks the action commands that are issued through an SSH session or from themanagement GUI. To list a specified number of the most recently audited commands, issue thecatauditlog command. To dump the contents of the audit log to a file on the current configuration node,issue the dumpauditlog command. This command also clears the contents of the audit log.

Dumps contained in the /dumps/cimom directory are created by the CIMOM (Common Information ModelObject Manager) that runs on the clustered system (system). These files are produced during normaloperations of the CIMOM.

Dumps that are contained in the /dumps/elogs directory are dumps of the contents of the error and eventlog at the time that the dump was taken. An error or event log dump is created by using the dumperrlog

Chapter 3. Using the CLI 15

command. The command dumps the contents of the error or event log to the /dumps/elogs directory. Ifno file name prefix is supplied, the default errlog_ is used. The full default file name iserrlog_NNNNNN_YYMMDD_HHMMSS, where NNNNNN is the node front panel name. If the commandis used with the -prefix parameter, the prefix value is used instead of errlog.

Dumps that are contained in the /dumps/iostats directory are dumps of the per-node I/O statistics fordisks on the system. An I/O statistics dump is created by using the startstats command. As part of thiscommand, you can specify a time interval for the statistics to be written to the file; the default is 15minutes. Every time the time interval is encountered, the I/O statistics that were collected are written toa file in the /dumps/iostats directory. The file names that are used for storing I/O statistics dumps areNm_stats_NNNNNN_YYMMDD_HHMMSS, Nv_stats_NNNNNN_YYMMDD_HHMMSS,Nn_stats_NNNNNN_YYMMDD_HHMMSS, and Nd_stats_NNNNNN_YYMMDD_HHMMSS, whereNNNNNN is the node name for the MDisk, volume, node, or drive.

Dumps that are contained in the /dumps/iotrace directory are dumps of I/O trace data. The type of datathat is traced depends on the options that are specified by the settrace command. The collection of theI/O trace data is started by using the starttrace command. The I/O trace data collection is stoppedwhen the stoptrace command is used. It is when the trace is stopped that the data is written to the file.The file name is prefix_NNNNNN_YYMMDD_HHMMSS, where prefix is the value that is entered for thefilename parameter in the settrace command, and NNNNNN is the node name.

Dumps that are contained in the /dumps/mdisk directory are copies of flash drive MDisk internal logs.These dumps are created using the triggerdrivedump command. The file name ismdiskdump_NNNNNN_MMMM_YYMMDD_HHMMSS, where NNNNNN is the name of the node that contains theMDisk, and MMMM is the decimal ID of the MDisk.

Software update packages are contained in the /home/admin/upgrade directory. These directories exist onevery node in the system.

Dumps of support data from a disk drive are contained in the /dumps/drive directory. This data can helpto identify problems with the drive, and does not contain any data that applications might have writtento the drive.

Dumps from an enclosure or enclosures are contained in the /dumps/enclosure directory.

Dumps that are contained in the /dumps directory result from application abends. Such dumps are writtento the /dumps directory. The default file names are dump.NNNNNN.YYMMDD.HHMMSS, where NNNNNNis the node front panel name. In addition to the dump file, there might be some trace files written to thisdirectory that are named NNNNNN.trc.

Because files can only be copied from the current configuration node (by using secure copy), you canissue the cpdumps command to copy the files from a nonconfiguration node to the current configurationnode.

Re-adding a repaired node to a clustered system by using the CLIYou can use the command-line interface (CLI) to re-add a failed node back into a clustered system after itwas repaired.

Before you begin

Before you add a node to a clustered system, you must make sure that the switchd\ zoning is configuredsuch that the node that is being added is in the same zone as all other nodes in the clustered system. Ifyou are replacing a node and the switch is zoned by worldwide port name (WWPN) rather than byswitch port, make sure that the switch is configured such that the node that is being added is in the sameVSAN/zone.


Attention:

1. If you are re-adding a node to the SAN, ensure that you are adding the node to the same I/O groupfrom which it was removed. Failure to select the correct I/O group can result in data corruption. Youmust use the information that was recorded when the node was originally added to the clusteredsystem. If you do not have access to this information, call the IBM Support Center to add the nodeback into the clustered system without corrupting the data.

2. The LUNs that are presented to the ports on the new node must be the same as the LUNs that arepresented to the nodes that currently exist in the clustered system. You must ensure that the LUNs arethe same before you add the new node to the clustered system.

3. LUN masking for each LUN must be identical on all nodes in a clustered system. You must ensurethat the LUN masking for each LUN is identical before you add the new node to the clusteredsystem.

4. You must ensure that the model type of the new node is supported by the SAN Volume Controllersoftware level that is installed on the clustered system. If the model type is not supported by the SANVolume Controller software level, update the clustered system to a software level that supports themodel type of the new node. See the following website for the latest supported software levels:www.ibm.com/support

About this task

Special procedures when you add a node to a clustered system

Applications on the host systems direct I/O operations to file systems or logical volumes that aremapped by the operating system to virtual paths (vpaths), which are pseudo disk objects that aresupported by the Subsystem Device Driver (SDD). SDD maintains an association between a vpath and aSAN Volume Controller volume. This association uses an identifier (UID) whic

with ibm corp. · chapter 1. spectrum v irtualize restful api ..... . 1 chapter 2. api management...

Documents