Using ptcli with ProtecTIER

Content

Introduction:

ProtecTIER includes a command line interface called ptcli that allows a user or administrator to perform some common operations. The ptcli requires an executable that can be found on the ProtecTIER nodes them selves at /opt/dtc/ptcli

and on the PT Mananger console (once installed) at : C:\Program Files\IBM\ProtecTIER Manager

(or where ever the PT Manager was installed, if you modified the defaults)

You can also find ptcli in the same directory that you installed the ptmanager, if you installed it on linux.

To test the ptcli.exe or ptcli command functionality, the simplest test is to run ptcli --help

Example:

(output from first screen of ptcli --help |more )

This output is also useful to use for showing the available commands along with the options and syntax.
You can also run it directly on a ProtecTIER node.

(output of the second screen of /opt/dtc/ptcli/ptcli --help |less)

Overview of the commands:

First, the ptcli command requires that you specify a login profile. - to create a login profile you can use the command ptcli -p filename

If you are running on a system that is not the node you do not need to specify the IP of the node because you are not yet actually connecting to the ProtecTIER system.

Example

Now all the other commands will require that you use this profile to login and perform the command.
Note: In the example above, ptadmin was used, and the "correct" ptadmin password is provided. The file contains an encrypted password that will be provided when the actual command is run. You can create a profile for any of the users that you have, ptoper, ptuser or ptadmin, but only the ptcli commands that are authorized will work. The ptadmin user can do all of the commands. I will specify which commands can be also used by ptuser or ptoper as they apply.

From the --help output we have a list of the 20 commands :

1. AddCartridges: Add cartridges
2. AddClusterMember: Add cluster member
3. AddLibrary: Create new library
4. CartridgeInfo: Prints information about specific cartridges in the library.
5. CreateRepository: Create repository
6. DriveModels: Prints information about the supported tape drive models.
7. InventoryFilter: This command queries the cartridges inventory snapshot
8. InventoryGetQueryFields: This command returns the fields available for the
specified query type.
9. InventoryMoveFile: Move a group of cartridges (expressed as a file).
10. InventoryMoveFilter: Move a group of cartridges (expressed as a filter).
11. InventoryRefresh: Refresh the cartridges inventory snapshot on the server.
12. InventoryStatistics: Display the latest information about the cartridges
inventory snapshot.
13. Libraries: Prints the list of libraries on the repository.
14. LibraryInfo: Prints information about a specific library in the repository.
15. LibraryTypes: Prints information about the supported library types.
16. NodeVtlStatistics: Prints the statistics history on the local host.
17. NumberOfCartridges: Prints the number of cartridges in the library.
18. RaidConfigurations: Prints information about the supported raid
configurations.
19. RepositoryStatistics: Prints the repository statistics.
20. ServerVersion: Prints the server version.

All of the Inventory commands (7-12) require that you have a Inventory Snapshot. Once the inventory snapshot is created, then all queries will be performed against that "state" until the snapshot is refreshed. So, if you create a snapshot, then the inventory is modified (very typical for a VTL that is use) the queries will not reflect any changes after that instant in time for the snapshot.

Be advised that the command "InventoryRefresh" can be load intensive so it is not recommended that it be run very often, or during critical times of use. This should be considered when automating ptcli, since it would be very dangerous to have a script inadvertently get in a loop that refreshes the snapshot.

You do not need to create or refresh the inventory snapshot unless you want to run the other inventory commands.

Sample commands:

Starting with the simplest of commands - 13.) Libraries

this is a good command to start with when learning ptcli and also when scripting, because you need the library name for many of the other commands. Since the library name could change, your script may want to be able to parse the library, or provide the name as a parameter.

Notice how the command Libraries does not use the "--" but all the other parameters do. --login --ip
Also notice in the successful output, the names of the libraries.
(also, the command underlined in red is typed all on one line, just wraps to the next line for the display)
Complete command used:
ptcli Libraries --login c:\work\technoteProfile.txt --ip 9.47.64.28

Another sample command - CartridgeInfo
This command requires some additional fields (shown in --help output)


The from and count are important if you have more then 1000 cartridges, since you will need to break the comand up into groups of 1000 for this display. My sample Library only has a few cartridges:

Notice that If you run this directly on the node, you do not need to provide the IP for the server.
Also notice that in this case, I created a profile for ptoper (underlined in green) Also notice that the count is only 4 so that it will fit the output on a single screen for this technote. Only barcode IC0000 has any data on it, (87GB)

Some of the commands will display information that is about the VTL emulation, and will not change, except when you install a new version of protecTIER - Examples DriveModels and LibraryTypes - ServerVersion and RaidTypes - Here I first ran LibraryTypes, and then using one of the results, I ran DriveModels, since DriveModels requires --libtype as a field

The commands : AddCartridges, AddClusterMember, AddLibrary, CreateRepository are commands that actually perform operations on the VTL and may require the system to be stopped, therefore it is not recommended that you use these commands except in rare cases where you have many ProtecTIER devices to configure and want them to all be the created the same by way of "scripting".
Also, these commands will cause the VTL or PTmanager to be taken offline, so it is strongly advised to not use the ptcli for them, unless the system is being implemented.
(note the following command below took about 5 minutes to return, and failed)


here we first failed because the profile was user "ptoper" and ptoper is not authorized to add a library.
Then we created the same profile again for the ptadmin user and the command but failed to add the library with the return code 3 and Description "InstallLibary: Covering the Error is out of the scope of this technote and since it is not recommended to do these types of operations with the ptcli, but rather use the GUI, we wont worry about the full exact syntax in this technote. Notice that I did not include any slots, import/export slots or drives with this command because according to the --help these options are optional.
Also notice that when you create the EXACT same library with 0 drives from the GUI it does warn you that it will take the system offline and failed with the same message :


That leaves only 16. NodeVtlStatistics, 17. NumberOfCartridges and 19. RepositoryStatistics

Note, that I was logged into the GUI for the above error and ptcli as ptadmin returned this :

After logging out of the GUI, the same ptcli command works - You can use the force flag, but it will disconnect whoever is logged in as ptadmin.

Notice the command specifies 1 hour, so you get 2 samples of 30 minutes of stats.
Then the fields show are the key fields for looking at the Front End Performance. (in this case the system is idle, so the out put has all 0's - If you give 24 hours, you will get 48 samples (like circled in yellow)

The samples indicate that the sample is 30 seconds, and taken at the time/date listed in sample date. So these may not include the full amount of data averaged over that time, but should allow a variety of values over a period of time. For more detailed statisics, the GUI offers the Long Term Statistics collection.

The remaining commands are the Inventory commands, and as mentioned require a snapshot of the inventory to be created. That is then used for any Inventory Queries. The Inventory command are probably most useful for the ptcli, but may not be very good for scripts since they will allow you to query and move cartrides from shelf to library, but it is likely something you would only perform in special circumstances. However there are some valid queries that can be used for reporting uses.

The typical flow for a inventory command is:
1.) Create snapshot
2.) Query the snapshot and save output to a file
3.) Use the output of a file for a move operation or as our report.

There are three types of queries, (querytype) : all, replica or origin. - based on which query type you choose, each has a list of possible queries. These can be displayed with InventoryGetQueryFields - Here I have listed the content of all 3 types :
Information that is common to all cartridge - "all":
/opt/dtc/ptcli/ptcli InventoryGetQueryFields --querytype all --login /work/technoteProfile.txt
<field name="cart_unique_id"/>
<field name="barcode"/>
<field name="nominal_size_in_bytes"/>
<field name="last_access_time"/>
<field name="media_type"/>
<field name="readonly"/>
<field name="principality_grid_id"/>
<field name="principality_repository_id"/>
<field name="container_name"/>

Information that is common only to cartridges that are on this cluster initially(spoke) "origin":

/opt/dtc/ptcli/ptcli InventoryGetQueryFields --querytype origin --login /work/technoteProfile.txt
<field name="cart_unique_id"/>
<field name="barcode"/>
<field name="nominal_size_in_bytes"/>
<field name="last_access_time"/>
<field name="media_type"/>
<field name="readonly"/>
<field name="principality_grid_id"/>
<field name="principality_repository_id"/>
<field name="container_name"/>
<field name="destination_repository_id"/>
<field name="destination_grid_id"/>
<field name="last_replication_time"/>
<field name="last_sync_time"/>
<field name="replicated_size"/>
<field name="backlog_size"/>

Information that is comononly to tapes that are replicated to this Cluster(hub) : replica:

/opt/dtc/ptcli/ptcli InventoryGetQueryFields --querytype replica --login /work/technoteProfile.txt
<field name="cart_unique_id"/>
<field name="barcode"/>
<field name="nominal_size_in_bytes"/>
<field name="last_access_time"/>
<field name="media_type"/>
<field name="readonly"/>
<field name="principality_grid_id"/>
<field name="principality_repository_id"/>
<field name="container_name"/>
<field name="last_update_time"/>
<field name="source_repository_id_for_last_sync_point"/>
<field name="source_grid_id_for_last_sync_point"/>
<field name="source_time_for_last_sync_point"/>
<field name="destination_time_for_last_sync_point"/>
<field name="in_sync"/>

Then, once you have the querytype and queryfields you can create the query command based on what you are interested in. In this example, I will query for all tapes that are "in_sync" on the hub.

Notice here, that since we are "querying" the DR cluster, we have to provide the IP for it, and we also had a message again that said I was logged into the GUI, so we ran with "--force" - but then it reminded us that we need to do an InventoryRefresh (red box) The Green is the inventory refresh command (require ptadmin)

Then notice I didnt use --force, and the command succeeded, but notice, that I did not give a 'output file' so, all the display shows is the number of cartridges that matched our query (21). so, this means, 21 cartridges are 'in_sync'

But if we want the list of files we need to specify the output file :

and we get the output file save in /work

(which then can be loaded into excel)


(in this case we only have 1 tape that has actually been used replicated)

Review the list of queryfields, you can use the inventoryfilter to limit your csv file to only certain cartridges. You also can limit the cartridge list by using the query type. The output file for each type "all", "origin" and replica determine what fields will be displayed.

Date Example:
/opt/dtc/ptcli/ptcli InventoryFilter --force --login /tmp/profile1 --querytype all --query "last_access_time < datetime('2012-02-27 08:23:00') " --output /tmp/cartlist_out.csv

Scripting Example:

Scripting isnt directly supported by IBM warranty or How To support, but the individual commands you may use are supported. So the creation and complexity and robustness of your script is entirely up to the author of the script. Usually the simpler you make a script the easier it will be to adapt it to a changing environment and changing levels of code. (in case new function is added etc)

A very simple script may have the goal to create 3 "report" type output at the same instant in time, and generate the report every day. The reports would include all tapes that are empty , all tapes that have backlog that needs to be replicated and modified in the last 24 hours.

the 3 main queries we would use are :

querytype origin query backlog_size>0

querytype origin query nominal_size_in_bytes=0

querytype origin query "last_replication_time > datetime('2011-12-27 08:23:00') "