IBM Spectrum Virtualize for Public Cloud, IBM SpectrumVirtualize for SAN Volume Controller and Storwize Family

Command-Line Interface User's Guide

IBM

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

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

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

Contents

Tables . . . . . . . . . . . . . . . xi

About this guide . . . . . . . . . . xiiiWho should use this guide . . . . . . . . . xiiiAccessibility . . . . . . . . . . . . . . xiiiEmphasis . . . . . . . . . . . . . . . xiiiLibrary and related publications . . . . . . . xiiiSending comments . . . . . . . . . . . . xvSyntax diagrams. . . . . . . . . . . . . xv

Terminology . . . . . . . . . . . . xviiCLI special characters . . . . . . . . . xviiUsing wildcards in the CLI . . . . . . . xviiiData types and value ranges . . . . . . . xviiiCLI commands and parameters . . . . . . xxiiiCLI flags . . . . . . . . . . . . . xxiiiCLI messages . . . . . . . . . . . . xxivCLI deprecated and discontinued commands xxivUnderstanding capacity indicators . . . . . xxviAttributes of the -filtervalue parameters . . . xxvi

Chapter 1. Setting up an SSH client . . . 1Setting up an SSH client on a Windows host. . . . 2

Generating an SSH key pair using PuTTY . . . 2Configuring a PuTTY session for the CLI . . . . 3Connecting to the CLI using PuTTY . . . . . 4Starting a PuTTY session for the CLI . . . . . 5

Preparing the SSH client on an AIX or Linux host . . 6Generating an SSH key pair using OpenSSH. . . 7Connecting to the CLI using OpenSSH . . . . 7

Working with local and remote users . . . . . . 8UNIX commands available in interactive SSHsessions . . . . . . . . . . . . . . . . 8Copying the software update files by using PuTTYpscp or openssh scp . . . . . . . . . . . . 9

Chapter 2. 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 . . . . . . . 28

Adding 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 . . . . . . . . . . 37Stopping 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 . . . . . . . . . . . 50

© Copyright IBM Corp. 2003, 2018 iii

Determining 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 58Expanding volumes by using the CLI. . . . . . 59

Expanding 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 3. Array commands . . . . . 89charray . . . . . . . . . . . . . . . . 89charraymember . . . . . . . . . . . . . 90lsarray . . . . . . . . . . . . . . . . 93lsarrayinitprogress. . . . . . . . . . . . 100lsarraylba. . . . . . . . . . . . . . . 101lsarraymember . . . . . . . . . . . . . 103lsarraymembergoals . . . . . . . . . . . 106lsarraymemberprogress . . . . . . . . . . 109lsarrayrecommendation . . . . . . . . . . 111lsarraysyncprogress . . . . . . . . . . . 114lspotentialarraysize . . . . . . . . . . . 115mkarray . . . . . . . . . . . . . . . 117mkdistributedarray . . . . . . . . . . . 120recoverarray . . . . . . . . . . . . . . 123recoverarraybycluster (Discontinued) . . . . . 123recoverarraybysystem . . . . . . . . . . 123rmarray . . . . . . . . . . . . . . . 124

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

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

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

Chapter 7. Clustered systemcommands . . . . . . . . . . . . 155addnode (SAN Volume Controller only) . . . . . 155addiscsistorageport . . . . . . . . . . . 158cfgportip . . . . . . . . . . . . . . 160chbanner . . . . . . . . . . . . . . . 166chcluster (Discontinued) . . . . . . . . . . 168chiogrp . . . . . . . . . . . . . . . 168chiscsistorageport . . . . . . . . . . . . 172chiscsiportauth . . . . . . . . . . . . 174chnode . . . . . . . . . . . . . . . 175chnodebattery . . . . . . . . . . . . . 178

iv Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

chnodebootdrive . . . . . . . . . . . . 179chnodehw (SVC) / chnodecanisterhw (Storwizefamily products) . . . . . . . . . . . . 180chquorum . . . . . . . . . . . . . . 181chsecurity . . . . . . . . . . . . . . 183chsite . . . . . . . . . . . . . . . . 184chsra . . . . . . . . . . . . . . . . 185chsystem . . . . . . . . . . . . . . . 187chsystemcert . . . . . . . . . . . . . 195chsystemip . . . . . . . . . . . . . . 197chthrottle . . . . . . . . . . . . . . . 199cleardumps . . . . . . . . . . . . . . 200cpdumps . . . . . . . . . . . . . . . 202detectiscsistorageportcandidate . . . . . . 203dumpconfig (Discontinued). . . . . . . . . 205help . . . . . . . . . . . . . . . . 205lsclustercandidate (Discontinued) . . . . . . . 206lscluster (Discontinued) . . . . . . . . . . 206lsclusterip (Discontinued) . . . . . . . . . 206lsclusterstats (Discontinued) . . . . . . . . 206lsdiscoverystatus . . . . . . . . . . . . 206lsfabric . . . . . . . . . . . . . . . 207lsfcportcandidate . . . . . . . . . . . . 211lsiscsistorageport . . . . . . . . . . . . 212lsiscsistorageportcandidate . . . . . . . . . 215lsiscsiportauth . . . . . . . . . . . . 217lsiogrp . . . . . . . . . . . . . . . 218lshbaportcandidate (Deprecated) . . . . . . . 222lsiogrphost . . . . . . . . . . . . . . 222lsiogrpcandidate . . . . . . . . . . . . 223lsiostatsdumps (Deprecated) . . . . . . . . 224lsiotracedumps (Deprecated) . . . . . . . . 224lsnode (SVC) / lsnodecanister (Storwize familyproducts) . . . . . . . . . . . . . . . 224lsnodebattery . . . . . . . . . . . . . 229lsnodecandidate (SAN Volume Controller). . . . 232lsnodedependentvdisks (Deprecated) . . . . . 233lsnodehw (SVC) / lsnodecanisterhw (Storwizefamily products) . . . . . . . . . . . . 234lsnodestats (SVC) / lsnodecanisterstats (Storwizefamily products) . . . . . . . . . . . . 236lsnodevpd (SVC) / lsnodecanistervpd (Storwizefamily products) . . . . . . . . . . . . 244lsportusb . . . . . . . . . . . . . . . 253lsportip . . . . . . . . . . . . . . . 255lsportfc . . . . . . . . . . . . . . . 263lsportsas . . . . . . . . . . . . . . . 265lsquorum. . . . . . . . . . . . . . . 268lsroute. . . . . . . . . . . . . . . . 269lstimezones . . . . . . . . . . . . . . 270lssasportcandidate . . . . . . . . . . . . 271lssecurity . . . . . . . . . . . . . . 272lssite . . . . . . . . . . . . . . . . 274lssra . . . . . . . . . . . . . . . . 275lsthrottle . . . . . . . . . . . . . . . 278lssystem . . . . . . . . . . . . . . . 279lssystemcert . . . . . . . . . . . . . . 292lssystemip . . . . . . . . . . . . . . 294lssystemstats . . . . . . . . . . . . . 297lstargetportfc . . . . . . . . . . . . . 301(satask) mkcluster . . . . . . . . . . . . 303

mkcluster (Deprecated) . . . . . . . . . . 304mkquorumapp . . . . . . . . . . . . . . 305mkthrottle . . . . . . . . . . . . . . 305ping . . . . . . . . . . . . . . . . 307rmiscsistorageport . . . . . . . . . . . . 308rmnode (SVC) / rmnodecanister (Storwize familyproducts) . . . . . . . . . . . . . . . 308rmportip . . . . . . . . . . . . . . . 311rmthrottle . . . . . . . . . . . . . . 312setclustertime (Discontinued) . . . . . . . . 312setsystemtime . . . . . . . . . . . . . 313setpwdreset . . . . . . . . . . . . . . 313settimezone . . . . . . . . . . . . . . 314showtimezone . . . . . . . . . . . . . 314startstats . . . . . . . . . . . . . . . 315stopstats (Deprecated) . . . . . . . . . . 317stopcluster (Discontinued) . . . . . . . . . 317stopsystem . . . . . . . . . . . . . . 317swapnode . . . . . . . . . . . . . . 318

Chapter 8. Clustered systemdiagnostic and service-aid commands 321applysoftware . . . . . . . . . . . . . 321caterrlog (Deprecated) . . . . . . . . . . 325caterrlogbyseqnum (Deprecated) . . . . . . . 325cherrstate (Deprecated) . . . . . . . . . . 325chdnsserver . . . . . . . . . . . . . . 325cheventlog . . . . . . . . . . . . . . 326chsyslogserver . . . . . . . . . . . . . 326clearerrlog . . . . . . . . . . . . . . 327cpfabricdumps (Discontinued) . . . . . . . . 328dumperrlog . . . . . . . . . . . . . . 328finderr . . . . . . . . . . . . . . . 329setevent (Discontinued) . . . . . . . . . . 329lscimomdumps (Deprecated) . . . . . . . . 329lscopystatus . . . . . . . . . . . . . . 329lsdumps . . . . . . . . . . . . . . . 330lsdnsserver . . . . . . . . . . . . . . 332lserrlogbyfcconsistgrp (Deprecated) . . . . . . 333lserrlogbyfcmap (Deprecated) . . . . . . . . 333lserrlogbyhost (Deprecated) . . . . . . . . 333lserrlogbyiogrp (Deprecated) . . . . . . . . 333lserrlogbymdisk (Deprecated) . . . . . . . . 333lserrlogbymdiskgrp (Deprecated) . . . . . . . 333lserrlogbynode (Deprecated) . . . . . . . . 333lserrlogbyrcconsistgrp (Deprecated) . . . . . . 333lserrlogbyrcrelationship (Deprecated) . . . . . 334lserrlogbyvdisk (Deprecated) . . . . . . . . 334lserrlogdumps (Deprecated) . . . . . . . . 334lsfeaturedumps (Deprecated) . . . . . . . . 334lseventlog . . . . . . . . . . . . . . 334lssyslogserver . . . . . . . . . . . . . 340lssoftwaredumps (Deprecated). . . . . . . . 341lssoftwareupgradestatus (Deprecated) . . . . . 341lssystemsupportcenter . . . . . . . . . . 341lsupdate . . . . . . . . . . . . . . . 343mkdnsserver . . . . . . . . . . . . . 346mksyslogserver . . . . . . . . . . . . . 347mksystemsupportcenter . . . . . . . . . . 348rmdnsserver . . . . . . . . . . . . . . 350rmsyslogserver . . . . . . . . . . . . . 350

Contents v

rmsystemsupportcenter . . . . . . . . . . 351setlocale . . . . . . . . . . . . . . . 352svqueryclock . . . . . . . . . . . . . 353writesernum. . . . . . . . . . . . . . 353

Chapter 9. Controller commands . . . 355chcontroller . . . . . . . . . . . . . . 355lscontroller . . . . . . . . . . . . . . 356lscontrollerdependentvdisks . . . . . . . . 360

Chapter 10. Drive commands . . . . 363applydrivesoftware . . . . . . . . . . . 363chdrive . . . . . . . . . . . . . . . 366lsdrive . . . . . . . . . . . . . . . 367lsdriveclass . . . . . . . . . . . . . 373lsdrivelba. . . . . . . . . . . . . . . 375lsdriveprogress . . . . . . . . . . . . . 376lsdriveupgradeprogress . . . . . . . . . . 378triggerdrivedump . . . . . . . . . . . . 380

Chapter 11. Email and eventnotification commands . . . . . . . 383chemail . . . . . . . . . . . . . . . 383chemailserver . . . . . . . . . . . . . 385chemailuser . . . . . . . . . . . . . . 386chsnmpserver . . . . . . . . . . . . . 387lsemailserver . . . . . . . . . . . . . 388lsemailuser . . . . . . . . . . . . . . 389lssnmpserver . . . . . . . . . . . . . 390mkemailserver . . . . . . . . . . . . . 391mkemailuser . . . . . . . . . . . . . 392mksnmpserver . . . . . . . . . . . . . 394rmemailserver . . . . . . . . . . . . . 395rmemailuser . . . . . . . . . . . . . . 395rmsnmpserver . . . . . . . . . . . . . 396sendinventoryemail . . . . . . . . . . . 396setemail (Discontinued) . . . . . . . . . . 397startemail. . . . . . . . . . . . . . . 397stopemail. . . . . . . . . . . . . . . 398testemail . . . . . . . . . . . . . . . 398

Chapter 12. Enclosure commands . . 401addcontrolenclosure . . . . . . . . . . . 401chenclosure . . . . . . . . . . . . . . 402chenclosurecanister . . . . . . . . . . . 402chenclosuredisplaypanel . . . . . . . . . . 404chenclosurepsu . . . . . . . . . . . . . 404chenclosuresem. . . . . . . . . . . . . 405chenclosureslot . . . . . . . . . . . . . 406(satask) chenclosurevpd (Deprecated) . . . . . 407lsenclosure . . . . . . . . . . . . . . 407lsenclosurebattery . . . . . . . . . . . . 410lscontrolenclosurecandidate (Storwize familyproducts only) . . . . . . . . . . . . . 413lsenclosurecanister. . . . . . . . . . . . 414lsenclosurechassis . . . . . . . . . . . . 417lsenclosuredisplaypanel . . . . . . . . . . 419lsenclosurefanmodule . . . . . . . . . . 420lsenclosurepsu . . . . . . . . . . . . . 422lsenclosuresem . . . . . . . . . . . . . 425

lsenclosureslot . . . . . . . . . . . . . 427lsenclosurestats . . . . . . . . . . . . . 430lssasfabric . . . . . . . . . . . . . . 433resetleds . . . . . . . . . . . . . . . 436triggerenclosuredump . . . . . . . . . . 436

Chapter 13. Encryption commands 439chencryption . . . . . . . . . . . . . 439chkeyserver . . . . . . . . . . . . . . 441chkeyserverisklm . . . . . . . . . . . . 442lsencryption . . . . . . . . . . . . . . 443lskeyserver . . . . . . . . . . . . . . 446lskeyserverisklm . . . . . . . . . . . . 447mkkeyserver . . . . . . . . . . . . . . 450rmkeyserver . . . . . . . . . . . . . . 451testkeyserver . . . . . . . . . . . . . 451

Chapter 14. Licensing andfeaturization commands. . . . . . . 453activatefeature . . . . . . . . . . . . . 453chlicense . . . . . . . . . . . . . . 454deactivatefeature . . . . . . . . . . . . 456lsfeature . . . . . . . . . . . . . . . 457lslicense . . . . . . . . . . . . . . . 459

Chapter 15. FlashCopy commands 463chfcconsistgrp . . . . . . . . . . . . . 463chfcmap . . . . . . . . . . . . . . . 463lsfcconsistgrp . . . . . . . . . . . . . 465lsfcmap . . . . . . . . . . . . . . . 468lsfcmapcandidate . . . . . . . . . . . . 471lsfcmapprogress . . . . . . . . . . . . 472lsfcmapdependentmaps . . . . . . . . . . 473lsrmvdiskdependentmaps . . . . . . . . . 474mkfcconsistgrp . . . . . . . . . . . . . 474mkfcmap . . . . . . . . . . . . . . . 475prestartfcconsistgrp . . . . . . . . . . . 478prestartfcmap . . . . . . . . . . . . . 480rmfcconsistgrp . . . . . . . . . . . . . 481rmfcmap . . . . . . . . . . . . . . . 481startfcconsistgrp . . . . . . . . . . . . 482startfcmap . . . . . . . . . . . . . . 484stopfcconsistgrp . . . . . . . . . . . . 485stopfcmap . . . . . . . . . . . . . . 486

Chapter 16. Host commands . . . . . 489addhostclustermember . . . . . . . . . . 489addhostiogrp . . . . . . . . . . . . . 490addhostport . . . . . . . . . . . . . . 490chhost . . . . . . . . . . . . . . . . 492chhostcluster . . . . . . . . . . . . . 494lshost . . . . . . . . . . . . . . . . 495lshostcluster . . . . . . . . . . . . . . 500lshostclustermember . . . . . . . . . . . 501lshostclustervolumemap . . . . . . . . . . 503lshostiogrp . . . . . . . . . . . . . . 504lsiscsiauth . . . . . . . . . . . . . . 505mkhost . . . . . . . . . . . . . . . 507mkhostcluster . . . . . . . . . . . . . 509mkvolumehostclustermap . . . . . . . . . 510

vi Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

rmhost . . . . . . . . . . . . . . . 511rmhostcluster . . . . . . . . . . . . . 512rmhostclustermember . . . . . . . . . . 513rmvolumehostclustermap . . . . . . . . . 514rmhostiogrp . . . . . . . . . . . . . . 515rmhostport . . . . . . . . . . . . . . 516

Chapter 17. Information commands 519ls2145dumps (Deprecated) . . . . . . . . . 519lsconfigdumps (Discontinued) . . . . . . . . 519lssshkeys (Discontinued) . . . . . . . . . 519

Chapter 18. Livedump commands . . 521cancellivedump. . . . . . . . . . . . . 521lslivedump . . . . . . . . . . . . . . 521preplivedump . . . . . . . . . . . . . 522triggerlivedump . . . . . . . . . . . . 522

Chapter 19. Managed disk commands 525addmdisk . . . . . . . . . . . . . . 525applymdisksoftware (Discontinued) . . . . . . 526chmdisk . . . . . . . . . . . . . . . 526detectmdisk . . . . . . . . . . . . . . 528dumpallmdiskbadblocks. . . . . . . . . . 530dumpmdiskbadblocks . . . . . . . . . . 531includemdisk . . . . . . . . . . . . . 532lsmdisk . . . . . . . . . . . . . . . 532lsmdiskdumps (Deprecated) . . . . . . . . 539lsmdisklba . . . . . . . . . . . . . . 539lsmdiskcandidate . . . . . . . . . . . . 540lsmdiskextent . . . . . . . . . . . . . 541lsmdiskmember . . . . . . . . . . . . . 543setquorum (Deprecated) . . . . . . . . . . 545triggermdiskdump (Discontinued) . . . . . . 545

Chapter 20. Copy Service commands 547chpartnership . . . . . . . . . . . . . 547chrcconsistgrp . . . . . . . . . . . . . 550chrcrelationship . . . . . . . . . . . . 552lspartnership . . . . . . . . . . . . . 556lspartnershipcandidate . . . . . . . . . . 560lsrcconsistgrp . . . . . . . . . . . . . 561lsrcrelationship . . . . . . . . . . . . . 564lsrcrelationshipcandidate . . . . . . . . 568lsrcrelationshipprogress . . . . . . . . . . 569mkfcpartnership . . . . . . . . . . . . 570mkippartnership . . . . . . . . . . . . 571mkpartnership (Discontinued) . . . . . . . . 573mkrcconsistgrp . . . . . . . . . . . . . 573mkrcrelationship . . . . . . . . . . . . 574rmpartnership . . . . . . . . . . . . . 578rmrcconsistgrp . . . . . . . . . . . . . 578rmrcrelationship . . . . . . . . . . . . 579startrcconsistgrp . . . . . . . . . . . . 580startrcrelationship . . . . . . . . . . . . 583stoprcconsistgrp . . . . . . . . . . . . 585stoprcrelationship . . . . . . . . . . . . 588switchrcconsistgrp. . . . . . . . . . . . 590switchrcrelationship . . . . . . . . . . . 591

Chapter 21. Migration commands . . . 593lsmigrate . . . . . . . . . . . . . . . 593migrateexts . . . . . . . . . . . . . . 594migratetoimage. . . . . . . . . . . . . 595migratevdisk . . . . . . . . . . . . . 597

Chapter 22. Service informationcommands . . . . . . . . . . . . 599sainfo host . . . . . . . . . . . . . . 599sainfo lsbootdrive . . . . . . . . . . . . 599sainfo lscmdstatus . . . . . . . . . . . . 601sainfo lsfiles . . . . . . . . . . . . . 603sainfo lshardware . . . . . . . . . . . . 604sainfo lsnodeip . . . . . . . . . . . . . 605sainfo lsservicenodes . . . . . . . . . . 606sainfo lsservicerecommendation . . . . . . . 607sainfo lsservicestatus . . . . . . . . . . 608sainfo traceroute . . . . . . . . . . . . 614

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

Chapter 24. Service mode informationcommands (Discontinued) . . . . . . 617ls2145dumps (Discontinued) . . . . . . . . 617lscimomdumps (Discontinued) . . . . . . . 617lsclustervpd (Discontinued). . . . . . . . . 617lserrlogdumps (Discontinued) . . . . . . . . 617lsfeaturedumps (Discontinued) . . . . . . . 617lsiostatsdumps (Discontinued) . . . . . . . . 617lsiotracedumps (Discontinued) . . . . . . . 617lsmdiskdumps (Discontinued) . . . . . . . . 617lssoftwaredumps (Discontinued) . . . . . . . 617

Chapter 25. Service task commands 619satask chbootdrive. . . . . . . . . . . . 619chnodeled . . . . . . . . . . . . . . 619satask chnodeip . . . . . . . . . . . . 621chserviceip . . . . . . . . . . . . . . 622satask chvpd . . . . . . . . . . . . . 624chwwnn . . . . . . . . . . . . . . . 626cpfiles . . . . . . . . . . . . . . . . 627satask downloadsoftware . . . . . . . . . 628dumpinternallog (Discontinued) . . . . . . . 630installsoftware . . . . . . . . . . . . . 630leavecluster . . . . . . . . . . . . . . 631metadata . . . . . . . . . . . . . . . 632satask overridequorum . . . . . . . . . . 633rescuenode . . . . . . . . . . . . . . 633resetpassword . . . . . . . . . . . . . 634restartservice . . . . . . . . . . . . . 634(satask) setlocale . . . . . . . . . . . . 635setpacedccu . . . . . . . . . . . . . . 636settempsshkey . . . . . . . . . . . . . 637satask snap . . . . . . . . . . . . . . 638

Contents vii

startservice . . . . . . . . . . . . . . 639stopnode . . . . . . . . . . . . . . . 639stopservice . . . . . . . . . . . . . . 640satask supportupload. . . . . . . . . . . 641t3recovery . . . . . . . . . . . . . . 643

Chapter 26. Service node informationcommands . . . . . . . . . . . . 645sninfo lsnodestatus . . . . . . . . . . . 645sninfo lsnonce . . . . . . . . . . . . . 646

Chapter 27. Service node taskcommands . . . . . . . . . . . . 647sntask chnode . . . . . . . . . . . . . 647sntask cleansnap . . . . . . . . . . . . 648sntask initnode . . . . . . . . . . . . . 649sntask rmnode . . . . . . . . . . . . . 650sntask snap . . . . . . . . . . . . . . 651sntask startnode . . . . . . . . . . . . 651sntask stopnode . . . . . . . . . . . . 652

Chapter 28. Storage pool commands 653chmdiskgrp . . . . . . . . . . . . . . 653lsfreeextents . . . . . . . . . . . . . . 655lsmdiskgrp . . . . . . . . . . . . . . 655mkmdiskgrp . . . . . . . . . . . . . . 665rmmdisk . . . . . . . . . . . . . . . 669rmmdiskgrp . . . . . . . . . . . . . . 671

Chapter 29. User managementcommands . . . . . . . . . . . . 673chauthservice . . . . . . . . . . . . . 673chcurrentuser . . . . . . . . . . . . . 675chldap. . . . . . . . . . . . . . . . 676chldapserver . . . . . . . . . . . . . 678chnaskey . . . . . . . . . . . . . . . 680chuser . . . . . . . . . . . . . . . . 681chusergrp . . . . . . . . . . . . . . 682lscurrentuser . . . . . . . . . . . . . 683lsldap . . . . . . . . . . . . . . . . 684lsldapserver . . . . . . . . . . . . . . 685lsuser . . . . . . . . . . . . . . . . 686lsusergrp . . . . . . . . . . . . . . . 688mkldapserver . . . . . . . . . . . . . 689mkuser . . . . . . . . . . . . . . . 690mkusergrp . . . . . . . . . . . . . . 692rmldapserver . . . . . . . . . . . . . 694rmuser . . . . . . . . . . . . . . . 695rmusergrp . . . . . . . . . . . . . . 695testldapserver . . . . . . . . . . . . . 696

Chapter 30. Volume commands. . . . 699addvolumecopy . . . . . . . . . . . . . 699addvdiskcopy . . . . . . . . . . . . . 702addvdiskaccess . . . . . . . . . . . . . 710analyzevdisk . . . . . . . . . . . . . 711analyzevdiskbysystem . . . . . . . . . . 712backupvolume . . . . . . . . . . . . . 713backupvolumegroup . . . . . . . . . . . 714

chvdisk . . . . . . . . . . . . . . . 715chvolumegroup. . . . . . . . . . . . . 720expandvdisksize . . . . . . . . . . . . 720lsdependentvdisks. . . . . . . . . . . . 723lshostvdiskmap. . . . . . . . . . . . . 724lsmetadatavdisk . . . . . . . . . . . . 726lsrepairsevdiskcopyprogress . . . . . . . . 727lsrepairvdiskcopyprogress . . . . . . . . . 729lssevdiskcopy . . . . . . . . . . . . . 731lsvdisk . . . . . . . . . . . . . . . 737lsvdiskaccess . . . . . . . . . . . . . 752lsvdiskanalysis . . . . . . . . . . . . . 754lsvdiskanalysisprogress . . . . . . . . . . 756lsvdiskcopy . . . . . . . . . . . . . . 758lsvdiskdependentmaps . . . . . . . . . . 765lsvdiskextent . . . . . . . . . . . . . 765lsvdiskfcmapcopies . . . . . . . . . . . 767lsvdiskfcmappings. . . . . . . . . . . . 768lsvdiskhostmap . . . . . . . . . . . . . 769lsvdisklba . . . . . . . . . . . . . . 770lsvdiskmember . . . . . . . . . . . . . 772lsvdiskprogress . . . . . . . . . . . . . 773lsvdisksyncprogress . . . . . . . . . . . 774lsvolumebackup . . . . . . . . . . . . 776lsvolumebackupgeneration . . . . . . . . . 778lsvolumebackupprogress . . . . . . . . . 780lsvolumegroup . . . . . . . . . . . . . 781lsvolumerestoreprogress . . . . . . . . . . 783mkmetadatavdisk . . . . . . . . . . . . 785mkvdisk . . . . . . . . . . . . . . . 786mkvdiskhostmap . . . . . . . . . . . . 797mkvolume . . . . . . . . . . . . . . . 799mkvolumegroup . . . . . . . . . . . . 803mkimagevolume . . . . . . . . . . . . . 804movevdisk . . . . . . . . . . . . . . 806recovervdisk. . . . . . . . . . . . . . 808recovervdiskbycluster (Discontinued) . . . . . 809recovervdiskbyiogrp . . . . . . . . . . . 809recovervdiskbysystem . . . . . . . . . . 809repairsevdiskcopy . . . . . . . . . . . . 810repairvdiskcopy . . . . . . . . . . . . 811restorevolume . . . . . . . . . . . . . 812rmvdisk . . . . . . . . . . . . . . . 813rmmetadatavdisk . . . . . . . . . . . . 817rmvdiskcopy . . . . . . . . . . . . . 817rmvdiskaccess . . . . . . . . . . . . . 818rmvdiskhostmap . . . . . . . . . . . . 819rmvolume . . . . . . . . . . . . . . 820rmvolumecopy . . . . . . . . . . . . . 821rmvolumegroup . . . . . . . . . . . . 823rmvolumebackupgeneration . . . . . . . . 823shrinkvdisksize . . . . . . . . . . . . 825splitvdiskcopy . . . . . . . . . . . . . 827

viii Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

Chapter 31. Command-line interfacemessages . . . . . . . . . . . . . 831

Appendix. Accessibility features forthe system . . . . . . . . . . . . 1019

Notices . . . . . . . . . . . . . 1021Trademarks . . . . . . . . . . . . . 1023

Index . . . . . . . . . . . . . . 1025

Contents ix

x Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

Tables

1. IBM websites for help, services, andinformation . . . . . . . . . . . . xiv

2. SAN Volume Controller library. . . . . . xiv3. IBM documentation and related websites xiv4. Syntax diagrams . . . . . . . . . . . xv5. Abbreviations . . . . . . . . . . . xvii6. Data types . . . . . . . . . . . . xix7. Capacity indicators . . . . . . . . . xxvi8. UNIX commands for interactive SSH sessions 89. Maximum volume capacity by extent size 23

10. Examples of memory required . . . . . . 2611. RAID level comparisons . . . . . . . . 2712. Volume copy resynchronization rates . . . . 2913. charraymember combination options . . . . 9214. Array output . . . . . . . . . . . . 9515. lsarrayinitprogress output . . . . . . . 10116. lsarraylba output . . . . . . . . . . 10217. lsarraymember output . . . . . . . . 10418. lsarraymembergoals output . . . . . . . 10719. lsarraymemberprogress output . . . . . . 11020. lsarrayrecommendation output. . . . . . 11221. lsarraysyncprogress output . . . . . . . 11522. lspotentialarraysize output . . . . . . . 11723. querycloudstoragecandidate output . . . . 13824. lscloudaccount output . . . . . . . . 14525. lscloudaccountusage output. . . . . . . 14726. lscloudaccountimportcandidate output 14927. Memory required for RAID arrays, Copy

Services, and volume mirroring . . . . . 17028. RAID level comparisons . . . . . . . . 17029. Number of extents reserved by extent size 18230. IP address list formats . . . . . . . . 19931. lsfcportcandidate output . . . . . . . . 21132. lsiscsistorageport output . . . . . . . . 21333. lsiscsistorageportcandidate output . . . . 21634. lsiscsiportauth output . . . . . . . . 21835. lsnode or lsnodecanister attribute values 22536. lsnodebattery attribute values . . . . . . 23037. lsnodecandidate outputs . . . . . . . . 23338. Attribute values for lsnodehw and

lsnodecanisterhw . . . . . . . . . . 23439. Attribute values for lsnodestats or

lsnodecanister . . . . . . . . . . . 23740. Stat_name field values . . . . . . . . 23941. Attribute values for lsnodevpd and

lsnodecanistervpd . . . . . . . . . . 24542. lsportusb output . . . . . . . . . . 25343. lsportip output . . . . . . . . . . . 25744. lsportfc output . . . . . . . . . . . 26445. lsportsas output. . . . . . . . . . . 26646. lsquorum output . . . . . . . . . . 26847. lssasportcandidate output . . . . . . . 27248. lssecurity attribute values . . . . . . . 27349. lssite attribute values . . . . . . . . . 27550. lssra output . . . . . . . . . . . . 27651. lsthrottle output. . . . . . . . . . . 279

52. lssystem output . . . . . . . . . . 28053. lssystemcert output . . . . . . . . . 29354. lssystemip output . . . . . . . . . . 29555. lssystemstats attribute values . . . . . . 29856. Stat_name field values . . . . . . . . 29957. lstargetportfc output . . . . . . . . . 30258. lsdnsserver output . . . . . . . . . . 33259. lseventlog output . . . . . . . . . . 33660. lssyslogserver output . . . . . . . . . 34161. lssystemsupportcenter output . . . . . . 34262. lscontroller output . . . . . . . . . . 35863. lsdrive output . . . . . . . . . . . 36964. lsdriveclass output . . . . . . . . . 37465. lsdrivelba output . . . . . . . . . . 37666. lsenclosure output . . . . . . . . . . 40867. lsenclosurebattery outputs . . . . . . . 41268. lscontrolenclosurecandidate attribute values 41469. lsenclosurecanister output . . . . . . . 41570. lsenclosurechassis outputs . . . . . . . 41871. lsenclosuredisplaypanel output . . . . . 41972. lsenclosurefanmodule attribute values 42173. lsenclosurepsu output. . . . . . . . . 42374. lsenclosuresem output . . . . . . . . 42575. lsenclosureslot output . . . . . . . . . 42876. lsenclosurestats outputs . . . . . . . . 43177. Stat_name field values . . . . . . . . 43378. lssasfabric output . . . . . . . . . . 43479. lsencryption output . . . . . . . . . 44480. ~`lskeyserver output . . . . . . . . . 44681. lskeyserverisklm output . . . . . . . . 44882. lsfeature outputs . . . . . . . . . . 45883. lslicense output . . . . . . . . . . . 46084. Relationship between the rate, data rate, and

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

grains per second values . . . . . . . . 47886. lshost output. . . . . . . . . . . . 49887. lshostcluster output . . . . . . . . . 50088. lshostclustermember output . . . . . . 50289. lshostclustervolumemap output . . . . . 50390. lsiscsiauth output . . . . . . . . . . 50691. lslivedump outputs . . . . . . . . . 52292. MDisk output . . . . . . . . . . . 53493. lsmdisklba command output . . . . . . 54094. lspartnership attribute values . . . . . . 55795. lsrcconsistgrp command output values 56296. lsrcrelationship command attributes and

values . . . . . . . . . . . . . . 56697. stoprcconsistgrp consistency group states 58798. stoprcrelationship consistency group states 58999. lsbootdrive attribute values . . . . . . . 600

100. lscmdstatus output. . . . . . . . . . 602101. lshardware attribute values . . . . . . . 605102. sainfo lsnodeip output . . . . . . . . 606103. lsservicenodes outputs . . . . . . . . 607104. lsservicestatus output . . . . . . . . . 609

© Copyright IBM Corp. 2003, 2018 xi

105. sninfo lsnodestatus output . . . . . . . 646106. Parameter differences for child pools and

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

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

storage pools. . . . . . . . . . . . 667109. lsldap attribute values . . . . . . . . 684110. lsldapserver attribute values . . . . . . 686111. testldapserver attribute values . . . . . . 697112. Storage pool Easy Tier settings . . . . . . 706113. Relationship between the syncrate value and

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

the data copied per second . . . . . . . 719115. lsmetadatavdisk output . . . . . . . . 727

116. Easy Tier status values . . . . . . . . 743117. lsvdiskanalysis output . . . . . . . . 755118. lsvdiskanalysisprogress output . . . . . . 757119. Easy Tier setting for storage pools and

volumes . . . . . . . . . . . . . 761120. lsvdisklba command output scenarios 771121. lsvolumebackup output . . . . . . . . 777122. lsvolumebackupgeneration output . . . . 779123. lsvolumebackupprogress output . . . . . 781124. lsvolumegroup output . . . . . . . . 782125. lsvolumerestoreprogress output . . . . . 784126. Easy Tier settings for storage pools and

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

the data copied per second . . . . . . . 795128. Accepted IP address formats . . . . . . 976

xii Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

About this guide

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

Who should use this guideThis guide is intended for system administrators or others who install and use the SAN VolumeController or Storwize V7000.

Before you use the SAN Volume Controller , you should have an understanding of storage area networks(SANs), the storage requirements of your enterprise, and the capabilities of your storage units.

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.

Library and related publicationsProduct manuals, other publications, and websites that contain information that is related to your systemare available.

IBM Knowledge Center for SAN Volume Controller

The information collection in the IBM Knowledge Center contains all of the information that is requiredto install, configure, and manage the system. The information collection in the IBM Knowledge Center isupdated between product releases to provide the most current documentation. The information collectionis available at the following website:

© Copyright IBM Corp. 2003, 2018 xiii

http://www.ibm.com/support/knowledgecenter/STPVGU

SAN Volume Controller library

Table 1 lists websites where you can find help, services, and more information.

Table 1. IBM websites for help, services, and information

Website Address

Directory of worldwide contacts http://www.ibm.com/planetwide

Support for SAN Volume Controller (2145) www.ibm.com/support

Support for IBM System Storage® and IBM TotalStorage products www.ibm.com/support

Each PDF publication in theTable 2 library is available in the IBM Knowledge Center by clicking the titlein the “Link to PDF” column:

Table 2. SAN Volume Controller library

Title Description Link to PDF file

IBM SAN Volume Controller Model2145-SV1 Hardware Installation Guide

The guide provides the instructionsthat the IBM service representativeuses to install the hardware for SANVolume Controller model 2145-SV1.

Hardware Installation Guide [PDF]

IBM SAN Volume Controller HardwareMaintenance Guide

The guide provides the instructionsthat the IBM service representativeuses to service the SAN VolumeController hardware, including theremoval and replacement of parts.

Hardware Maintenance Guide [PDF]

IBM SAN Volume ControllerTroubleshooting Guide

The guide describes the features ofeach SAN Volume Controller model,explains how to use the front panelor service assistant GUI, andprovides maintenance analysisprocedures to help you diagnose andsolve problems with the SAN VolumeController .

Troubleshooting Guide [PDF]

IBM Spectrum Virtualize for PublicCloud, IBM Spectrum Virtualize forSAN Volume Controller and StorwizeFamily Command-Line Interface User'sGuide

The guide describes the commandsthat you can use from the SANVolume Controller command-lineinterface (CLI).

Command-Line Interface User'sGuide [PDF]

IBM Spectrum Virtualize REST API This document provides informationon the REST API and related CLIcommands.

IBM documentation and related websites

Table 3 lists websites that provide publications and other information about the SAN Volume Controlleror related products or technologies. The IBM Redbooks® publications provide positioning and valueguidance, installation and implementation experiences, solution scenarios, and step-by-step proceduresfor various products.

Table 3. IBM documentation and related websites

Website Address

IBM Publications Center ibm.com/shop/publications/order

xiv Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

http://www.ibm.com/support/knowledgecenter/STPVGUhttp://www.ibm.com/planetwidehttp://www.ibm.com/supporthttp://www.ibm.com/support/http://ibm.com/shop/publications/order

Table 3. IBM documentation and related websites (continued)

Website Address

IBM Redbooks publications www.redbooks.ibm.com/

Related accessibility information

To view a PDF file, you need Adobe Reader, which can be downloaded from the Adobe website:

www.adobe.com/support/downloads/main.html

Sending commentsYour feedback is important in helping to provide the most accurate and highest quality information.

Procedure

To submit any comments about this publication or any other IBM storage product documentation:

Send your comments by email to ibmkc@us.ibm.com. Be sure to include the following information:v Exact publication title and versionv Page, table, or illustration numbers that you are commenting onv A detailed description of any information that should be changed

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

Table 4 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.

Table 4. 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.

About this guide xv

http://www.redbooks.ibm.com/http://www.adobe.com/support/downloads/main.htmlmailto:ibmkc@us.ibm.com?subject=IBM%20Systems%20Storage%20publications

Table 4. Syntax diagrams (continued)

Element Syntax Description

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.

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.

xvi Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

TerminologyTerms that are most commonly used for the command-line interface (CLI) operations.

Table 5 shows the terms and offers a brief description.

Table 5. Abbreviations

Name Object type

Host Refers to a single host.

Host cluster Refers to a host cluster (which is part of a server thatshares a set of volumes).

Host object Refers to a list of worldwide port names WWPNs andiSCSI names.

Volume copy Referred to as vdiskcopy.

Thin-provisioned volume copy Referred to as sevdiskcopy.

Managed disk (MDisk) Referred to as MDisk.

MDisk group or storage pool Referred to as storage pool.

I/O group Referred to as iogrp.

Node, node canister, enclosure Refers to node or node canister or enclosure, dependingon the system.

Clustered system (system) or cluster Referred to as system.

VDisk or volume Referred to as volume.

Controller Refers to a controller that is part of a clustered system.

IBM FlashCopy® mapping Referred to as fcmap.

IBM FlashCopy consistency group Referred to as fcconsistgrp.

Metro Mirror or Global Mirror relationship Referred to as rcrelationship.

Metro Mirror or Global Mirror consistency group Referred to as rcconsistgrp.

HyperSwap® mirroring consistency group Referred to as hyperswap.

Unsupported/unknown object unknown

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.

About this guide xvii

v Exclamation mark (!) is used to delimit items in a command if the item values can contain acolon 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.

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 6 on page xix lists the data types and the value ranges for each.

xviii Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

Table 6. 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)

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

About this guide xix

Table 6. Data types (continued)

Data types Value ranges

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

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

xx Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

Table 6. Data types (continued)

Data types Value ranges

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.

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.

About this guide xxi

Table 6. Data types (continued)

Data types Value ranges

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.

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.

xxii Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

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 inthe 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.

About this guide xxiii

-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

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.

CLI deprecated and discontinued commandsSome command-line interface (CLI) commands are discontinued or deprecated and replaced with newcommands.

Command-line interface (CLI) commands can be discontinued or deprecated and replaced with newcommands that are more effective. This action can affect scripting, which is done to simplify tasks such asspecifying (repeated) commands.

A discontinued command is removed from the CLI and can no longer be used. In most instances, there isa replacement command for discontinued commands.

A deprecated command can still be used if the appropriate command prefix is specified (svctask orsvcinfo, for example). In most instances, there is a replacement command for deprecated commands.

The following commands are deprecated:v These commands are replaced by lseventlog:

– caterrlog– caterrlogbyseqnum– lserrlogbyfcconsistgrp– lserrlogbyfcmap– lserrlogbyhost– lserrlogbyiogrp– lserrlogbymdisk

xxiv Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

– lserrlogbymdiskgrp– lserrlogbynode– lserrlogbyrcconsistgrp– lserrlogbyrcrelationship– lserrlogbyvdisk

v These commands are replaced by lsdumps:– ls2145dumps– lsauditlogdumps– lserrlogdumps– lscimomdumps– lsfeaturedumps– lsiostatsdumps– lsiotracedumps– lsmdiskdumps– lssoftwaredumps

v lssoftwareupgradestatus is replaced by lsupdatev chenclosurevpd is replaced by chvpdv cherrstate is replaced by cheventlogv lsnodedependentvdisks is replaced by lsdependentvdisksv setquorum is replaced by chquorumv mkpartnership is replaced by mkippartnership and mkfcpartnershipv lshbaportcandidate is replaced by lssasportcandidate and lsfcportcandidate

The following commands are discontinued:v These commands are replaced by lsdumps:

– svcservicemodeinfo ls2145dumps– svcservicemodeinfo lsclustervpd– svcservicemodeinfo lserrlogdumps– svcservicemodeinfo lsfeaturedumps– svcservicemodeinfo lsiostatsdumps– svcservicemodeinfo lsiotracedumps– svcservicemodeinfo lsmdiskdumps– svcservicemodeinfo lssoftwaredumps

v These commands are replaced by the user management commands:– addsshkeys– lsauth– mkauth– rmsshkey– rmallsshkeys– rmauth

v applymdisksoftware is replaced by applydrivesoftwarev chcluster is replaced by chsystemv cpfabricdumps has no replacementv dumpconfig has no replacementv dumpinternallog has no replacement

About this guide xxv

v lscluster is replaced by lssystemv lsclustercandidate is replaced by lspartnershipcandidatev lsclusterip is replaced by lssystemv lsclusterstats is replaced by lssystemstatsv lsconfigdumps has no replacementv recoverarraybycluster is replaced by recoverarraybysystemv recoverdiskbycluster is replaced by recoverdiskbysystemv svcservicemodeinfo lsclustervpd is replaced by satask lsservicestatusv svcservicemodetask applysoftware is replaced by satask installsoftwarev svcservicemodetask cleardumps is replaced by cleardumpsv svcservicemodetask dumperrlog is replaced by dumperrlogv svcservicemodetask exit is replaced by stopservicev setclustertime is replaced by setsystemtimev stopcluster is replaced by stopsystemv triggermdiskdump is replaced by triggerdrivedumpv setevent is replaced by chsnmpserver, lssnmpserver, mksnmpserver, and rmsnmpserverv setemail is replaced by chemail, chemailserver, lsemailserver, mkemailserver, and rmemailserver

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 7. 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.

xxvi Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

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

xxviii Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

Chapter 1. Setting up an SSH client

Secure Shell (SSH) is a client/server network application. It is used as a communication vehicle betweenthe host system and the system command-line interface (CLI).

Overview

The system acts as the SSH server in this relationship. The SSH client provides a secure environment inwhich to connect to a remote computer. Authentication is completed by using a user name and password.If you require command-line access without entering a password, it uses the principles of public andprivate keys for authentication.

Authenticating SSH logins

Generate a Secure Shell (SSH) key pair to use the command-line interface (CLI). Additionally, when youuse the SSH to log in to the system, you must use the RSA-based private key authentication.

When you are using AIX® hosts, SSH logins are authenticated on the system by using the RSA-basedauthentication that is supported in the OpenSSH client that is available for AIX . This scheme is based onthe supplied password (or if you require command-line access without entering a password, thenpublic-key cryptography is used) by using an algorithm that is known commonly as RSA.

Note: The authentication process for host systems that are not AIX is similar.

With this scheme (as in similar OpenSSH systems on other host types), the encryption, and decryption isdone by using separate keys. This scheme means that it is not possible to derive the decryption key fromthe encryption key.

Because physical possession of the private key allows access to the system, the private key must be keptin a protected place, such as the .ssh directory on the AIX host, with restricted access permissions.

When SSH client (A) attempts to connect to SSH server (B), the SSH password (if you requirecommand-line access without entering a password, the key pair) authenticates the connection. The keyconsists of two halves: the public keys and private keys. The SSH client public key is put onto SSHServer (B) using some means outside of the SSH session. When SSH client (A) tries to connect, the privatekey on SSH client (A) is able to authenticate with its public half on SSH server (B).

The system supports up to 32 interactive SSH sessions on the management IP address simultaneously.

Note: After one hour, a fixed SSH interactive session times out, which means the SSH session isautomatically closed. This session timeout limit is not configurable.

To connect to the system, the SSH client requires a user login name and an SSH password (or if yourequire command-line access without entering a password, the key pair). Authenticate to the system byusing a management user name and password. When you use an SSH client to access a system, you mustuse your SVC_username and password. The system uses the password (and if not a password, the SSHkey pair) to authorize the user who is accessing the system.

You can connect to the system by using the same user name with which you log in to the system.

For Microsoft Windows hosts, PuTTY can be downloaded from the internet and used at no charge toprovide an SSH client.

© Copyright IBM Corp. 2003, 2018 1

You can connect to the system by using the same user name with which you log in to the system.

Setting up an SSH client on a Windows hostYou can prepare the SSH client on a Windows host.

The workstation for the system include the PuTTY client program, which is a Microsoft Windows SSHclient program. The PuTTY client program can be installed on your workstation in one of these ways:v If you purchased the workstation hardware option from IBM, the PuTTY client program has been

preinstalled on the hardware.v You can use the workstation software installation CD to install the PuTTY client program.v You can use the separate PuTTY client program-installation wizard, putty-version-installer.exe. You

can download the PuTTY client program from this website:Download Putty

Note: Before you install the PuTTY client program, ensure that your Windows system meets the systemrequirements.

You can connect to the system by using the same user name with which you log in to the system.

Generating an SSH key pair using PuTTYTo use the system command-line interface, you must generate a Secure Shell (SSH) key pair using PuTTY.

About this task

Generate SSH keys using the PuTTY key generator (PuTTYgen):

Procedure1. Start PuTTYgen by clicking Start > Programs > PuTTY > PuTTYgen. The PuTTY Key Generator

panel is displayed.2. Click SSH-2 RSA as the type of key to generate.

Note: Leave the number of bits in a generated key value at 1024.3. Click Generate and then move the cursor around the blank area of the Key section to generate the

random characters that create a unique key. When the key has been completely generated, theinformation about the new key is displayed in the Key section.Attention: Do not modify the Key fingerprint or the Key comment fields; this can cause your key tono longer be valid.

4. Optional: Enter a passphrase in the Key passphrase and Confirm passphrase fields. The passphraseencrypts the key on the disk; therefore, it is not possible to use the key without first entering thepassphrase.

5. Save the public key by:a. Click Save public key. You are prompted for the name and location of the public key.b. Type icat.pub as the name of the public key and specify the location where you want to save the

public key. For example, you can create a directory on your computer called keys to store both thepublic and private keys.

c. Click Save.6. Save the private key by:

a. Click Save private key. The PuTTYgen Warning panel is displayed.b. Click Yes to save the private key without a passphrase.

2 Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html

c. Type icat as the name of the private key, and specify the location where you want to save theprivate key. For example, you can create a directory on your computer called keys to store both thepublic and private keys. It is recommended that you save your public and private keys in thesame location.

d. Click Save.7. Close the PuTTY Key Generator window.

Configuring a PuTTY session for the CLIYou must configure a PuTTY session using the Secure Shell (SSH) password. If you require command lineaccess without entering a password, use the SSH key pair that you created for the command-lineinterface (CLI).

About this task

Attention: Do not run scripts that create child processes that run in the background and call systemcommands. This can cause the system to lose access to data and cause data to be lost.

Complete the following steps to configure a PuTTY session for the CLI:

Procedure1. Select Start > Programs > PuTTY > PuTTY. The PuTTY Configuration window opens.2. Click Session in the Category navigation tree. The Basic options for your PuTTY session are

displayed.3. Click SSH as the Protocol option.4. Click Only on clean exit as the Close window on exit option. This ensures that connection errors are

displayed.5. Click Connection > SSH in the Category navigation tree. The options controlling SSH connections

are displayed.6. Click 2 as the Preferred SSH protocol version.7. Click Connection > SSH > Auth in the Category navigation tree. The Options controller SSH

authentication are displayed.8. Click Browse or type the fully qualified file name and location of the SSH client and password. If no

password is used, the private key in the Private key file for authentication field.9. Click Connection > Data in the Category navigation tree.

10. Type the user name that you want to use on the system in the Auto-login username field.11. Click Session in the Category navigation tree. The Basic options for your PuTTY session are

displayed.12. In the Host Name (or IP Address) field, type the name or Internet Protocol (IP) address of one of the

system IP addresses or host names.13. Type 22 in the Port field. The system uses the standard SSH port.14. Type the name that you want to use to associate with this session in the Saved Sessions field. For

example, you can name the session “System 1”.15. Click Save.

Results

You have now configured a PuTTY session for the CLI.

Note: If you configured more than one IP address for the system, repeat the previous steps to createanother saved session for the second IP address. This can then be used if the first IP address isunavailable.

Chapter 1. Secure Shell 3

Connecting to the CLI using PuTTYEnsure that you are familiar with how to run the PuTTY and plink utilities.

Note: Windows users can download PuTTY from the following website: Download Putty.

The Secure Shell (SSH) protocol specifies that the first access to a new host server sends a challenge tothe SSH user to accept the SSH server public key or user password. Because this is the first time that youconnect to an SSH server, the server is not included in the SSH client list of known hosts. Therefore, thereis a fingerprint challenge, which asks if you accept the responsibility of connecting with this host. If youtype y, the host fingerprint and IP address are saved by the SSH client.

When you use PuTTY, you must also type y to accept this host fingerprint. However, the host fingerprintand IP address are stored in the registry for the user name that is logged on to Windows.

The SSH protocol also specifies that once the SSH server public key is accepted, another challenge ispresented if the fingerprint of an SSH server changes from the one previously accepted. In this case, youmust decide whether you want to accept this changed host fingerprint.

Note: The SSH server keys on the SAN Volume Controller are regenerated when a microcode load isperformed on the clustered system. As a result, a challenge is sent because the fingerprint of the SSHserver has changed.

All command-line interface (CLI) commands are run in an SSH session. You can run the commands inone of the following modes:v An interactive prompt modev A single-line command mode, which is entered one time to include all parameters.

Interactive mode

For interactive mode, you can use the PuTTY executable to open the SSH restricted shell.

The system supports up to 32 interactive SSH sessions on the management IP address simultaneously.

Note: After one hour, a fixed SSH interactive session times out, which means the SSH session isautomatically closed. This session timeout limit is not configurable.

The following is an example of the command that you can issue to start interactive mode:C:\support utils\putty @svcconsoleip

where support utils\putty is the location of your putty.exe file, is the IP address of yourmanagement GUI, and is the user name that you want to use.

If you were to issue the lsuser command, which lists the SSH client public keys that are stored on thesystem, the following output is displayed when ssh_key=yes:

IBM_2145:cluster0:superuser>lsuserid name password ssh_key remote usergrp_id usergrp_name0 superuser yes yes no 0 SecurityAdmin1 smith no yes no 4 Monitor2 jones no yes no 2 CopyOperator

You can type exit and press Enter to escape the interactive mode command.

The following is an example of the host fingerprint challenge when using plink in interactive mode:

4 Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html

C:\Program Files\IBM\svcconsole\cimom>plink superuser@9.43.225.208The server’s host key is not cached in the registry. Youhave no guarantee that the server is the computer youthink it is.The server’s key fingerprint is:ssh-rsa 1024 e4:c9:51:50:61:63:e9:cd:73:2a:60:6b:f0:be:25:bfIf you trust this host, enter "y" to add the key toPuTTY’s cache and carry on connecting.If you want to carry on connecting just once, withoutadding the key to the cache, enter "n".If you do not trust this host, press Return to abandon theconnection.Store key in cache? (y/n) yUsing user name "superuser".Authenticating with public key "imported-openssh-key"IBM_2145:your_cluster_name:superuser>

Single-line command

For single-line command mode, you can type the following all on one command line:

C:\Program Files\IBM\svcconsole\cimom>plink superuser@9.43.225.208 lsuser

Authenticating with public key "imported-openssh-key"id name password ssh_key remote usergrp_id usergrp_name0 superuser yes yes no 0 SecurityAdmin1 smith no yes no 4 Monitor2 jones no yes no 2 CopyOperator

Note: If you are submitting a CLI command with all parameters in single-line command mode, you arechallenged upon first appearance of the SSH server host fingerprint. Ensure that the SSH server hostfingerprint is accepted before you submit a batch script file.

The following is an example of the host fingerprint challenge when using plink in single-line commandmode:

C:\Program Files\IBM\svcconsole\cimom>plink superuser@9.43.225.208 lsuserThe server’s host key is not cached in the registry. You

have no guarantee that the server is the computer youthink it is.The server’s key fingerprint is:ssh-rsa 1024 e4:c9:51:50:61:63:e9:cd:73:2a:60:6b:f0:be:25:bfIf you trust this host, enter "y" to add the key toPuTTY’s cache and carry on connecting.If you want to carry on connecting just once, withoutadding the key to the cache, enter "n".If you do not trust this host, press Return to abandon theconnection.Store key in cache? (y/n) yAuthenticating with public key "imported-openssh-key"id name password ssh_key remote usergrp_id usergrp_name0 superuser yes yes no 0 SecurityAdmin1 smith no yes no 4 Monitor2 jones no yes no 2 CopyOperator

Starting a PuTTY session for the CLIYou must start a PuTTY session to connect to the command-line interface (CLI).

Chapter 1. Secure Shell 5

Before you begin

This task assumes that you have already configured and saved a PuTTY session using the Secure Shell(SSH) password. If you require command line access without entering a password, use the SSH key pairthat you created for the CLI.

About this task

Start a PuTTY session:

Procedure1. Select Start > Programs > PuTTY > PuTTY. The PuTTY Configuration window opens.2. Select the name of your saved PuTTY session and click Load.3. Click Open.

Note: If this is the first time that the PuTTY application is being used since you generated anduploaded the SSH password or key pair, a PuTTY Security Alert window is displayed. Click Yes toaccept the change and trust the new key.

4. Type the SVC_username in the login as field and press Enter.

Preparing the SSH client on an AIX or Linux hostYou can prepare the Secure Shell (SSH) client on an AIX or Linux host.

Before you begin

Ensure that you have an SSH client installed on your system:

IBM AIX operating systemsFor IBM AIX 5L™ for POWER, versions 5.1, 5.2, 5.3, and AIX version 6.1 for IBM POWERarchitecture, you can obtain the OpenSSH client from the bonus packs, but you also must obtainits prerequisite, OpenSSL, from the IBM AIX toolbox for Linux applications for IBM PowerSystems™. For AIX 4.3.3, you can obtain the software from the AIX toolbox for Linux applications.You can also obtain the AIX installation images from IBM developerWorks® at the followingwebsite:

oss.software.ibm.com/developerworks/projects/openssh

Linux operating systemsThe OpenSSH client is installed by default on most Linux distributions. If it is not installed onyour system, consult your Linux installation documentation or visit the following website:

www.openssh.org/portable.html

The OpenSSH client can run on a variety of additional operating systems. For more informationabout the openSSH client, visit the following website:

www.openssh.org/portable.html

About this task

Authentication to the system generally requires the use of a password, but if there is no password youcan use a key pair. Use these steps to set up an RSA key pair on the AIX or Linux host and the clusteredsystem:

6 Spectrum Virtualize for SAN Volume Controller and Storwize Family: Command-Line Interface User's Guide

http://oss.software.ibm.com/developerworks/projects/opensshhttp://www.openssh.org/portable.htmlhttp://www.openssh.org/portable.html

Results

To authenticate using an SSH key, use the following command:ssh -i full_path_to_key username@my_system

Where my_system is the name of the system IP, username@my_system is the user name that you also loginto the system with, and full_path_to_key is the full path to the key file that was generated in the previousstep. Authenticate to the system using a SVC_username and password. (If you require command-lineaccess without using a password, SSH keys can be used.) The system determines which user is logging infrom the key the user is using.

Note: You can omit -i full_path_to_key if you configure the SSH client to use the key file automatically.

If you use the Secure Shell (SSH) to log into the system, use the password defined for accessing the GUI.You can also use RSA-based private key authentication.

For more information, see “Connecting to the CLI using OpenSSH.”

Generating an SSH key pair using OpenSSHYou can generate an SSH key pair using OpenSSH.

About this task

Set up an RSA key pair on the AIX or Linux host and the clustered system:

Procedure1. Create an RSA key pair by issuing a command on the host that is similar to this command:

ssh-keygen -t rsa

You can also create a valid ECDSA key pair for authentication:ssh-keygen -t ecdsa

Tip: Issue the command from the $HOME/.ssh directory.This process generates two user named files. If you select the name key, the files are named key andkey.pub. Where key is the name of the private key and key.pub is the name of the public key.

2. Associate the public key with a user on the clustered system using the management GUI.

Connecting to the CLI using OpenSSHYou can connect to the command-line interface (CLI) using OpenSSH.

To connect to a clustered system using a SVC_username and SSH password, issue:ssh username@my_system

To use an SSH key, issue:-i full_path_to_key

Where my_system is the name of the system IP, full_path_to_key is the full path to the key file that wasgenerated in the previous step, and SVC_username is the user name that you want to usesystem.

Note: You can omit -i full_path_to_key if you configure the SSH client to use the key file automatically.For more SSH information, refer to the OpenSSH documentation.

Chapter 1. Secure Shell 7

Working with local and remote usersYou can create either a local or a remote user to access a system.

Before you begin

You can create two categories of users that access the system. These types are based on how the users areauthenticated to the system. Local users must provide the SVC_username and password, and if yourequire command line access without entering a password, a Secure Shell (SSH) key - or both. Local usersare authenticated through the authentication methods that ar