TS3500CLI Instructions

8/9/2019 TS3500CLI Instructions

1/14

IBM System Storage TS3500Tape Library

Command Line Interface

The IBM TS3500 Tape Library Command Line Interface (CLI) program can be used to access the TS3500Tape Library from a CLI. This is in addition to the TS3500 Tape Library Web Specialist. The TS3500 CLIcan be downloaded from the web at the following URL:http://www-01.ibm.com/support/docview.wss?uid=ssg1S4000854.

The TS3500 CLI provides the ability to access library functions through a command line interface. Allview commands create a comma-separated value (csv) style output. The output is directed to thecommand prompt window by default, but can also be redirected to a file. To redirect the output to a file,you can add > output_filename to the end of the command.

In order to use the TS3500 CLI, the following prerequisites apply:

v The TS3500 Tape Library must be at a firmware level 8xxx (or higher).

v The Advanced Library Management System (ALMS) must be installed and enabled.

v Java 5.0 or later must be installed.

Cartridge movement using the TS3500 CLI is generally performed based on the current cartridge location:

1. Moving to storage

v If currently in storage, then use prestageDataCartridges only if library contains a High Density(HD) frame.

v If currently in a drive, then usemoveFromDrive.

v If currently in I/O with Virtual I/O disabled, then use moveFromIo.v If currently in I/O with Virtual I/O enabled, then use assignDataCartridges.

v If currently in a shuttle, then usemoveFromShuttle.

2. Moving to drive

v If currently in storage, then use moveToDrive.

v If currently in a drive, then usemoveFromDrive, followed bymoveToDrive.

v If currently in I/O with Virtual I/O disabled, then use moveFromIofollowed by moveToDrive.

v If currently in I/O with Virtual I/O enabled, then use assignDataCartridgesfollowed bymoveToDrive.

v If currently in a shuttle, then usemoveFromShuttle followed bymoveToDrive.

3. Moving to I/Ov If currently in storage, then use removeDataCartridges.

v If currently in a drive, then usemoveFromDrivefollowed by removeDataCartridges.

v If currently in I/O with Virtual I/O disabled, then use moveFromIofollowed byremoveDataCartridges.

v If currently in I/O with Virtual I/O enabled, then use removeDataCartridges.

v If currently in a shuttle, then usemoveFromShuttle followed byremoveDataCartridges.

Some move commands allow you to specify which cartridge to move by either its 8-character volumeserial (VOLSER) number or its current location in the library. By supporting moves by location, cartridgeswith an unknown VOLSER can be moved via the CLI.
http://www-01.ibm.com/support/docview.wss?uid=ssg1S4000854http://www-01.ibm.com/support/docview.wss?uid=ssg1S4000854http://www-01.ibm.com/support/docview.wss?uid=ssg1S4000854http://www-01.ibm.com/support/docview.wss?uid=ssg1S4000854


2/14

Moves from a storage slot location are supported by the following:

v assignDataCartridges

v bulkAssignDataCartridges

v bulkAssignDataCartridgesByLogicalLibrary

v destageDataCartridges

v moveToDrive

v prestageDataCartridges

v removeDataCartridges

Moves from an I/O slot location are supported by the following:

v moveFromIo

The format for storage locations is frame number, column number, row number (F,C,R) for a librarywithout an HD frame and F,C,R,T (tier number) for a library with an HD frame. The format for I/Olocations is F,R. As shown, the fields must be separated by commas without spaces. For example, for aremoveDataCartridges input file in an HD library, you could have the following:

F1,C2,R8,T0F2,C1,R25,T3F1,C1,R10,T1

For an assignDataCartridges input file in a non-HD library, the logical library testltolib is included:

F1,C2,R8, testltolibF2,C1,R25, testltolibZZZ000L4, testltolib

For amoveFromIocommand, you could have the following:

java -jar TS3500CLI.jar -a --moveFromIo F1,R4 -u -p

Supported Actions:

-assignDataCartridgesAssigns data cartridges to a logical library

-assignShuttleStationAssigns the shuttle station at the given frame to a logical library

-batch Performs actions specified within a file

-bulkAssignDataCartridgesAssigns multiple cartridges at the same time instead of one at a time

-bulkAssignDataCartridgesByLogicalLibraryGiving a logical library, assigns multiple cartridges at the same time instead of one at a time

-cleanDriveCleans a drive at the given location, designated by frame and row

-createCapRangesCreates a new Cartridge Assignment Policy (CAP)

-createRoleModifyAnyCreates or modifies a role to have modify any permissions

-createRoleViewOnlyCreates or modifies a role to have view only permissions

2


3/14

-deleteCapRangesDeletes all existing CAP ranges

-destageDataCartridgesDestages cartridges based on a list of VOLSERs or locations in a file

-downloadLogsDownloads library logs specified by log type

-libraryFirmwareUpdateUpdates the library firmware

-moveFromAllDrivesDemounts all full drives

-moveFromDriveDemounts a cartridge from a specific drive, designated by frame and row

-moveFromIoMoves the specified cartridge from the I/O station into a storage slot

-moveFromShuttleMoves a cartridge from a shuttle station specified by either VOLSER or frame number

-moveToDriveMounts a cartridge to a specific drive

-powerCycleDrivePower cycle the drive at the given location, designated by frame and row

-prestageDataCartridgesPrestages cartridges to cache based on a list of VOLSERs or locations in a file

-removeDataCartridgesRemoves the data cartridges (cartridges moved to the I/O station)

-removeExpiredCleaningCartridgesRemoves all expired cleaning cartridges

-resetNodeCardsResets all specified node cards

-setLibraryTimeSets the Library date and time to that of the CLI host

-setMaxSocketExceptionRetriesSets the maximum number of Socket Exception retry attempts

-setShuttleBeaconLightBlinkSets the shuttle station beacon light-emitting diode (LED) to blink at the given frame

-setShuttleBeaconLightOffSets the shuttle station beacon LED off at the given frame

-setShuttleBeaconLightOnSets the shuttle station beacon LED on at the given frame

-setShuttleStationOfflineSets the shuttle station offline at the given frame

-setShuttleStationOnlineSets the shuttle station online at the given frame

-shuttleCarFirmwareUpdateUpdates the shuttle car firmware

3


4/14

-shuttleDiscoverConnectionsRuns discover connections at the given shuttle frame

-shuttleDistributeConnectionsRuns distribute connections at the given shuttle frame

-unassignShuttleStationUnassigns the shuttle station at the given frame

-versionDisplays version information about the TS3500 CLI

-viewAccessorViews the accessor status and usage statistics

-viewAvailableLibraryLogsViews all downloadable library logs

-viewBepRangesViews the encryption policy ranges

-viewCapRangesViews all Cartridge Assignment Policy ranges in the physical library

-viewCleaningCartridgesViews all cleaning cartridges

-viewDataCartridgesViews all data cartridges

-viewDriveDetailsViews detailed information about a drive at the given frame and row

-viewDriveSummaryViews the drive summary

-viewDriveVPDViews the drive VPD information

-viewFibreChannelViews the Fibre Channel settings

-viewIoStationViews the I/O station

-viewLibraryVPDViews the library VPD information

-viewLogicalLibrariesViews the logical library settings

-viewLogicalLibraryDetailsViews the detailed information about a given logical library

-viewNodeCardsViews the node card information

-viewRolePermissionsView the role permissions

-viewRolesView the roles and their permissions

-viewShuttleStationsViews the shuttle station settings

4


5/14

-viewSystemSummaryViews the physical library system summary

-viewSystemSummaryDetailsView physical library system summary for the specified frame

Command Parameters:

The following CLI parameters are supported:

-? Shows help

- : -Action (REQUIRED)

-a Tape library DNS name or IP address (REQUIRED)

-d Turns on extra debug tracing and stores in localTS3500CLI.log file (used for problemdetermination)

-f Specified frame #

-h Shows help

-k , Full path and file name of keystore holding the public/private key pair used withSSL. (REQUIRED if Secure Socket Layer [SSL] is enabled.)

-ll Specified logical library

-p Tape library password (used only if Web Security is enabled)

-r Drive row number

-s , Keystore password used with SSL (REQUIRED if SSL is enabled.)

-setMaxSocketExceptionRetries, Sets the limit of socket exception retries before failing the action (default isunlimited retries)

-t Sets timeout value in milliseconds (default is to never timeout, which may cause CLI to appear to

hang)-u Tape Library User ID (used only if Web Security is enabled)

-v or verboseThe default mode for the CLI is quiet." In quiet mode, progress messages are not included in theoutput. When the v or --verboseparameter is added, the progress messages are included in theoutput. When using the CLI with scripting, you probably do not want the progress messagesincluded in the output.

-w The last two characters of the drive world wide node name (WWNN) to specify the drive(instead of using-f and -r)

SSL Access:

Like the TS3500 Tape Library Web Specialist, the TS3500 CLI can be used with or without SSL enabled onthe TS3500 Tape Library. Refer to the TS3500 Tape Library Information Center at the following URL forinstructions on enabling SSL on the tape library: http://publib.boulder.ibm.com/infocenter/ts3500tl/v1r0/index.jsp.

TS3500 Web Specialist: When accessing the TS3500 with SSL enabled, the only change necessary ischanging the URL of the library from http to https. The TS3500 Tape Library's certificate used with SSL isstored in the browser. The web server in the TS3500 has the private key.

5
http://publib.boulder.ibm.com/infocenter/ts3500tl/v1r0/index.jsphttp://publib.boulder.ibm.com/infocenter/ts3500tl/v1r0/index.jsphttp://publib.boulder.ibm.com/infocenter/ts3500tl/v1r0/index.jsphttp://publib.boulder.ibm.com/infocenter/ts3500tl/v1r0/index.jsp


6/14

TS3500 CLI: When accessing the library with SSL enabled, the TS3500 Tape Library's certificate firstneeds to be exported from the browser and imported to a keystore. If there are multiple TS3500 TapeLibraries, this process needs to be done for every SSL-enabled library that will be accessed via the CLI.This can be done using the free IBM Java tool, Keytool. Keytool can be found at the following URL:http://www.ibm.com/developerworks/java/jdk/security/50/secguides/keytoolDocs/KeyToolUserGuide-150.html.

1. Enable SSL by using the TS3500 Tape Library Web Specialist. From the specialist, go to Access >Secure Socket Layer.

2. Using a browser, go to that SSL-enabled TS3500 Tape Library. This loads the library's certificate intothe browser.

3. View the certificate and export it to a file. In Mozilla Firefox this is done by performing the followingsteps:

a. Go to Tools > Options > Advanced > View Certificates.

b. Under the Server column, select the row with your library's IP address.

c. Click Export.

d. Leave file type as X.509 Certificate (PEM) and clickSave.

Note: On some versions of some browsers the Export option is not available. In this situation,

perform the following steps to view the certificate and export it to a file instead:a. Click on the IP address just to the left of the URL.

b. Click More Information.

c. Click View Certificate.

d. Select the Detail tab.

e. Click Export.

f. Leave file type as X.509 Certificate (PEM) and clickSave.

4. Import the certificate into a keystore. Using Keytool enter the following:keytool -import -file -keystore -storepass -alias.

5. Two additional parameters,-k and -s need to be added to the CLIcommand. The is the full path and filename of the keystore created with Keytool. The is the keystore's password.

Command Format:

assignDataCartridges

java -jar TS3500CLI.jar -a --assignDataCartridges -u -p

For the assignDataCartridges action, the input file would take the following format:

volser or location #1, Logical Library namevolser or location #2, Logical Library name

For example, if you wanted to assign four cartridges to the logical library named testltolib, you couldcreate a text file named volsers.txt containing the following lines:

ZZZ000L4, testltolibZZZ001L4, testltolibF1,C2,R8,T0, testltolibZZZ002L4, testltolib

6
http://www.ibm.com/developerworks/java/jdk/security/50/secguides/keytoolDocs/KeyToolUserGuide-150.htmlhttp://www.ibm.com/developerworks/java/jdk/security/50/secguides/keytoolDocs/KeyToolUserGuide-150.htmlhttp://www.ibm.com/developerworks/java/jdk/security/50/secguides/keytoolDocs/KeyToolUserGuide-150.htmlhttp://www.ibm.com/developerworks/java/jdk/security/50/secguides/keytoolDocs/KeyToolUserGuide-150.html


7/14

The following command would be used:

C:\$User\Applications\TS3500_CLI\>java -jar TS3500CLI.jar -a --assignDataCartridges c:\$User\Applications\TS3500_CLI\volsers.txt -u -p

TheassignDataCartridges action assigns one single cartridge at a time. The advantage is that you get toknow the actual status result of each individual cartridge. The disadvantage is that it takes longer than

bulkAssignDataCartridges.

With bulkAssignDataCartridges, a group of cartridges is assigned at one time based on the cartridgesthat it finds per bucket and range as it walks through each frame and their buckets and ranges. Theadvantage is that it is faster and even indicates which cartridges were assigned (but only when there areno failures). The disadvantage is that if there is an error, the CLI does not indicate which ones failed,only that they failed.

assignShuttleStation

java -jar TS3500CLI.jar -a --assignShuttleStation -f -ll -u -p

For theassignShuttleStationaction, both the -f frame and -ll logical library arguments are required.The shuttle station must be offline when being assigned or unassigned. To operate command on allshuttle stations in one action, specify all for the shuttle frame number.

batch

java -jar TS3500CLI.jar -a --batch -u -p

For the batch action, the input file would take the following format:

-action #1

-action #2

bulkAssignDataCartridges

java -jar TS3500CLI.jar -a --bulkAssignDataCartridges -u -p

For thebulkAssignDataCartridges action, the input file would take the following format:


For example. if you wanted to assign four cartridges to the logical library named testltolib, you could

create a text file named volsers.txt containing the following lines:

ZZZ000L4, testltolibZZZ001L4, testltolibF1,C2,R8,T0, testltolibF2,C1,R25,T3, testltolib


7


8/14

C:\$User\Applications\TS3500_CLI\>java -jar TS3500CLI.jar -a --bulkAssignDataCartridges c:\$User\Applications\TS3500_CLI\volsers.txt -u -p

bulkAssignDataCartridgesByLogicalLibrary

java -jar TS3500CLI.jar -a --bulkAssignDataCartridges -ll -u -p

For the bulkAssignDataCartridgesByLogicalLibrary action, only cartridges that are already assigned tothe specified source logical library will be searched and then assigned to their new logical library,specified in the input file. This method is faster than bulkAssignDataCartridges if you only needcartridges from one logical library. For this action, the input file would take the following format:


cleanDrive

java -jar TS3500CLI.jar -a --cleanDrive -f -r -u -p

createCapRanges

java -jar TS3500CLI.jar -a --createCapRanges -u -p

The input file has the following format:

Cartridge Assignment Policy volser range #1, Logical Library nameCartridge Assignment Policy volser range #2, Logical Library name

For example, if you wanted to create three Cartridge Assignment Policies and associate them with thelogical library named testltolib, you could create a text file named cap.txtcontaining:

ZZZ000-ZZZ999, testltolibYYY111-YYY888, testltolibXXX222-XXX666, testltolib


C:\$User\Applications\TS3500_CLI\>java -jar TS3500WebInterfaceCLI_v1.0_20100128.jar -a --createCapRanges C:\$User\Applications\TS3500_CLI\cap.txt -u -p

createRoleModifyAny

java -jar TS3500CLI.jar -a --createRoleModifyAny -u -p

createRoleViewOnly

java -jar TS3500CLI.jar -a --createRoleViewOnly -u -p

deleteCapRanges

8


9/14

java -jar TS3500CLI.jar -a --deleteCapRanges -u -p

destageDataCartridges

java -jar TS3500CLI.jar -a --destageDataCartridges -u -p

The input file has the following format:

volser or location #1volser or location #2

downloadLogs

java -jar TS3500CLI.jar -a --downloadLogs -u -p

Multiple log types must be separated by commas without spaces. An optional argument -f will download only that frame's logs for the specified log type(s). To get both accessors' logs forthat type when specifying a frame number, use frame 1.

libraryFirmwareUpdate

java -jar TS3500CLI.jar -a --libraryFirmwareUpdate -u -p

The TS3500 Tape Library firmware can be downloaded from IBM Fix Central at the following URL:http://www.ibm.com/support/fixcentral.

moveFromAllDrives

java -jar TS3500CLI.jar -a --moveFromAllDrives -u -p

moveFromDrive

java -jar TS3500CLI.jar -a --moveFromDrive -f -r -u -p

Eitherf and r, or w, can be used to designate which tape drive. The f and r options supply theframe and row location of the drive. The woption is the last 2 characters of the drive's WWNN. ThemoveFromDriveaction will first attempt to move back to the home slot and if home slot is full, it willmove to first empty storage slot.

moveFromIo

java -jar TS3500CLI.jar -a --moveFromIo -u -p

VIO must be disabled for moveFromIo to work.

moveFromShuttle

9
http://www.ibm.com/support/fixcentralhttp://www.ibm.com/support/fixcentral


10/14

java -jar TS3500CLI.jar -a --moveFromShuttle


11/14

java -jar TS3500CLI.jar -a --setLibraryTime -u -p

Sets the library date and time to that of the server on which the CLI is running.

setShuttleBeaconLightBlink

java -jar TS3500CLI.jar -a --setShuttleBeaconLightBlink -f -u -p

To operate the command on all shuttle stations in one action, specify all for the shuttle frame numberas shown in the following example:

java -jar TS3500CLI.jar -a --setShuttleBeaconLightBlink -fALL -u -p

setShuttleBeaconLightOff

java -jar TS3500CLI.jar -a --setShuttleBeaconLightOff -f -u -p

To operate the command on all shuttle stations in one action, specify all for the shuttle frame number.

setShuttleBeaconLightOn

java -jar TS3500CLI.jar -a --setShuttleBeaconLightOn -f -u -p


setShuttleStationOffline

java -jar TS3500CLI.jar -a --setShuttleStationOffline -f -u -p


setShuttleStationOnline

java -jar TS3500CLI.jar -a --setShuttleStationOnline -f -u -p


shuttleCarFirmwareUpdate

java -jar TS3500CLI.jar -a --shuttleCarFirmwareUpdate -f -u -p

The shuttle car must be present in the library at the specified frame.

shuttleDiscoverConnections

java -jar TS3500CLI.jar -a --shuttleDiscoverConnections -f -u -p

11


12/14

shuttleDistributeConnections

java -jar TS3500CLI.jar -a --shuttleDistributeConnections -f -u -p

unassignShuttleStation

java -jar TS3500CLI.jar -a --unassignShuttleStation -f -u -p

For the unassignShuttleStation action, the shuttle station must be offline. To operate the command on allshuttle stations in one action, specify all for the shuttle frame number.

-version

java -jar TS3500CLI.jar --version

-viewAccessor

java -jar TS3500CLI.jar -a --viewAccessor -u -p

-viewAvailableLibraryLogs

java -jar TS3500CLI.jar -a --viewAvailableLibraryLogs -u -p

Displays the Download Library Logs page. Does not display available Shuttle Car logs. To see whichshuttle cars are present, use viewShuttleStations.

-viewBepRanges

java -jar TS3500CLI.jar -a --viewBepRanges -u -p

-viewCapRanges

java -jar TS3500CLI.jar -a --viewCapRanges -u -p

viewCleaningCartridges

java -jar TS3500CLI.jar -a --viewCleaningCartridges -u -p

viewDataCartridges

To run the viewDataCartridges action, enter the following command:

java -jar TS3500CLI.jar -a --viewDataCartridges -u -p

Response time is dependent on the firmware level. There was a performance improvement added infirmware levels B560 and later. On a 2200 slot, 2000 cartridge, TS3500 Tape Library running a firmwarelevel prior to B560, the command took about .17 seconds per cartridge, or stated another way, about 268

12


13/14

cartridges per minute. With B560 or later, the response time is improved. The command has no impact onlibrary mount performance or tape drive throughput performance.

Note: In firmware level prior to B560, in order to ensure there are no missing or duplicate data cartridgesin the response, viewDataCartridges must be used while the library is idle (not performingcartridge movement). If viewDataCartridges cannot be run while the library is idle, then it isrecommended that the user perform the action twice consecutively and then remove all duplicates

from the resulting combined responses.

viewDriveDetails

java -jar TS3500CLI.jar -a --viewDriveDetails -f -r -u -p

viewDriveSummary

java -jar TS3500CLI.jar -a --viewDriveSummary -u -p

viewDriveVPD

java -jar TS3500CLI.jar -a --viewDriveVPD -u -p

viewFibreChannel

java -jar TS3500CLI.jar -a --viewFibreChannel -u -p

viewIoStation

java -jar TS3500CLI.jar -a --viewIoStation -u -p

viewLibraryVPD

java -jar TS3500CLI.jar -a --viewLibraryVPD -u -p

viewLogicalLibraries

java -jar TS3500CLI.jar -a --viewLogicalLibraries -u -p

viewLogicalLibraryDetails

java -jar TS3500CLI.jar -a --viewLogicalLibraryDetails -u -p

viewNodeCards

java -jar TS3500CLI.jar -a --viewNodeCards -u -p

viewRolePermissions

13


14/14

java -jar TS3500CLI.jar -a --viewRolePermissions -u -p

viewRoles

java -jar TS3500CLI.jar -a --viewRoles -u -p

viewShuttleStations

java -jar TS3500CLI.jar -a --viewShuttleStations -u -p

viewSystemSummary

java -jar TS3500CLI.jar -a --viewSystemSummary -u -p

viewSystemSummaryDetails

java -jar TS3500CLI.jar -a --viewSystemSummaryDetails -u -p

IBM is a trademark or registered trademarks of International Business Machines in the US and/or other countries.

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

TS3500CLI Instructions

Documents

Transcript of TS3500CLI Instructions