integration toolboxtoolboxfortsm.com/toolbox4tsm_installguide.pdf · integration toolbox for tivoli...

Installation Guide

www.toolboxfortsm.com

INTEGRATION TOOLBOX

for IBM® Tivoli® Storage Manager

Integration Toolbox for Tivoli Storage Manager – Installation Guide ii

INTEGRATION TOOLBOXfor IBM® Tivoli® Storage Manager

Version 1.0Installation Guide

Integration Toolbox for Tivoli Storage Manager – Installation Guide iii

Integration Toolbox for IBM Tivoli Storage Manager

Installation Guide

ContentsIntroduction ...................................................................................................................................... 1Components at a glance ................................................................................................................... 1

1. Installation planning ...................................................................................................................... 2 1.1. Components ........................................................................................................................... 2 1.2. Prerequisites .......................................................................................................................... 2 1.2.1. Java API for IBM Tivoli Storage Manager......................................................................... 2 1.2.2. RESTful API for IBM Tivoli Storage Manager with WebSphere Application Server ......... 2 1.2.3. RESTful API for IBM Tivoli Storage Manager with Glassfish ............................................ 3

2. Installing the Integration Toolbox for TSM .................................................................................... 4 2.1. Installing on Linux .................................................................................................................. 4 2.2. Installing on Windows ............................................................................................................ 4 2.3. Installing on AIX ..................................................................................................................... 4

3. Post-installation steps ................................................................................................................... 5 3.1. Configuring logging ................................................................................................................ 5 3.2. Configuring environment variables ........................................................................................ 5 3.2.1. Linux ................................................................................................................................ 5 3.2.2. Windows ......................................................................................................................... 5 3.2.3. AIX ................................................................................................................................... 5 3.3. Verifying the installation ........................................................................................................ 5

4. Deploying the RESTful Web Service .............................................................................................. 6 4.1. Deploying on WebSphere ...................................................................................................... 6 4.1.1. Resource Adapter ............................................................................................................ 6 4.1.1.1. Deploying the RAR file.............................................................................................. 6 4.1.1.2. Creating the connection pool ................................................................................... 8 4.1.2. Web Service .................................................................................................................. 11 4.1.2.1. Adding shared libraries .......................................................................................... 11 4.1.2.2. Configuring the classloader .................................................................................... 13 4.1.2.3. Deploying the WAR file .......................................................................................... 17 4.2. Deploying on Glassfish ......................................................................................................... 23 4.2.1. Resource Adapter .......................................................................................................... 23 4.2.1.1. Deploying the RAR file............................................................................................ 23 4.2.1.2. Creating the resource adapter configuration ......................................................... 24 4.2.1.3. Creating the connection pool ................................................................................. 25 4.2.1.4. Creating the connector resource ........................................................................... 27 4.2.2. Web Service .................................................................................................................. 28 4.2.2.1. Deploying the WAR file .......................................................................................... 28 4.2.2.2. Starting and stopping the web service ................................................................... 29 4.2.3. Verifying the installation ............................................................................................... 29

5. Validating the installed environment .......................................................................................... 30 5.1. Using the Toolbox for TSM command line examples ........................................................... 30 5.2. Using REST services .............................................................................................................. 30

6. Trademarks ................................................................................................................................. 31

Integration Toolbox for Tivoli Storage Manager – Installation Guide 1

IntroductionIt is a daunting task for every company to store, access and share millions of documents—especially generated on a daily basis—in a reliable and efficient way.For Java™ based business applications our, Integration Toolbox for IBM® Tivoli® Storage Manager (TSM) product provides an effortless way to take advantage of storing documents or other data in existing TSM environments using a high level Java API. SOA environments can use our JAX-RS compliant Web Services for TSM feature without having to write a single line of code.

For further information, visit our Getting started page (http://toolboxfortsm.com/index.html#getting-started). If you have any questions, please contact us via e-mail: [email protected].

Components at a glanceThe core of our application is Java API for TSM, aka Toolbox, which—using TSM client—provides the connection to the TSM server. This Toolbox is a Java library that can be embedded into different layers of enterprise applications and can also be used for creating standalone Java applications.RESTful API for TSM web application also builds upon Toolbox. Its two main components are a resource adapter and a web application which implements a JAX-RS 2.0 compliant webservice. Webservices used in SOA environment can easily connect to the TSM server using the web application. The resource adapter enables the configuration of this TSM connection, some of whose configuration parameters are the node name, password and the number of sessions.

J2EERESTful API for TSM

REST(JAX-RS 2.0)

ResourceAdapter

TSM Client

Toolbox(Java API for TSM)

TSM Server

Standalone Java

Application

‹›

‹›

‹›

‹›

‹›

mailto:[email protected]


1. Installation planning1.1. Components

The two installable components of Integration Toolbox for IBM Storage Manager are• Java API for IBM Tivoli Storage Manager• RESTful API for IBM Tivoli Storage Manager

1.2. Prerequisites

The following tables list the prerequisites and supported environments for Integration Toolbox for IBM Storage Manager

1.2.1. Java API for IBM Tivoli Storage ManagerOperating System Java JDK TSM Client APIRed Hat® Enterprise Linux® 5 (64 bit)Red Hat® Enterprise Linux® 6 (64 bit)

Java™ Development Kit 6 or higher

Tivoli Storage Manager Client API 6.4 or higher

Windows 7 Professional, Enterprise, UltimateWindows 8 Core, Pro, EnterpriseWindows Server 2008 Standard Edition x32 and x64Windows Server 2008 Datacenter Edition x32 and x64Windows Server 2008 Enterprise Edition x32 and x64Windows Server 2008 R2 Standard EditionWindows Server 2008 R2 Data center EditionWindows Server 2008 R2 Enterprise Edition



IBM AIX® 6.1 IBM AIX® 7.1



1.2.2. RESTful API for IBM Tivoli Storage Manager with WebSphere Application Server Operating System Application Server Java JRE TSM Client APIRed Hat Enterprise Linux (RHEL) 5 Client Update 6Red Hat Enterprise Linux (RHEL) 5 Server Update 6Red Hat Enterprise Linux (RHEL) Client 6 BaseRed Hat Enterprise Linux (RHEL) Server 6 Base

WebSphere Application Server Base Edition 8.5.5.0 or higher WebSphere Application Server Network Deployment 8.5.5.0 or higher

Java Runtime Environment 7 or higher


Windows 7 Professional, Enterprise, UltimateWindows 8 Core, Pro, EnterpriseWindows Server 2008 Standard Edition x32 and x64 Windows Server 2008 Datacenter Edition x32 and x64Windows Server 2008 Enterprise Edition x32 and x64 Windows Server 2008 R2 Standard Edition Windows Server 2008 R2 Datacenter Edition Windows Server 2008 R2 Enterprise Edition

WebSphere Application Server Base Edition 8.5.5.0 or higher WebSphere Application Server Network Deployment 8.5.5.0 or higher




Operating System Application Server Java JRE TSM Client APIAIX 6.1 TL5 or higherAIX 7.1 TL1 or higher

WebSphere Application Server Base Edition 8.5.5.0 or higher



AIX 6.1 TL0 SP4 or higherAIX 7.1 TL1 SP2 or higher

WebSphere Application Server Network Deployment 8.5.5.0 or higher



1.2.3. RESTful API for IBM Tivoli Storage Manager with GlassfishOperating System Application Server Java JRE TSM Client APIRed Hat® Enterprise Linux® 5 (64 bit)Red Hat® Enterprise Linux® 6 (64 bit)

GlassFish 4.0 or higher Java Runtime Environment 7 or higher


Windows 7 Professional, Enterprise, UltimateWindows 8 Core, Pro, EnterpriseWindows Server 2008 Standard Edition x32 and x64 Windows Server 2008 Datacenter Edition x32 and x64Windows Server 2008 Enterprise Edition x32 and x64 Windows Server 2008 R2 Standard Edition Windows Server 2008 R2 Datacenter Edition Windows Server 2008 R2 Enterprise Edition



IBM AIX® 6.1 IBM AIX® 7.1




2. Installing the Integration Toolbox for TSM2.1. Installing on Linux

Download the latest installation package. Change to the directory where you downloaded the package to and install the product by executing the following command:

rpm -i IntegrationToolboxForTSM.rpm

The package is installed to the /opt/toolbox-for-tsm directory by default.A symbolic link to libtoolboxfortsm.so is created under the /usr/lib64 directory.

2.2. Installing on Windows

Download the latest installation package. Install the product by double clicking the IntegrationToolboxForTSM.msi executable and follow the instructions.

Silent installation:Open a command prompt that has elevated privileges.

1. Press the Windows button and type ‘cmd’.2. Right click the Command Prompt icon to view the properties. 3. Click Run as administrator. 4. Click Continue in the permission window.

Execute the following command:

msiexec /i "IntegrationToolboxForTSM.msi" RebootYesNo="No" REBOOT="Suppress"

ALLUSERS=1 INSTALLDIR="C:\Program Files\toolbox-for-tsm" /qn /l*v "C:\log.txt"

The package is installed to the C:\Program Files\toolbox-for-tsm directory by default.

2.3. Installing on AIX

Download the latest installation package. Change to the directory where you downloaded the package to and install the product using the following command:

installp -acXYd . toolbox-for-tsm.api

The package is installed to the /opt/toolbox-for-tsm directory by default. A symbolic link to libtoolboxfortsm.a is created under the /usr/lib directory.

NOTE:For the silent installation to work, you will need User Account Control (UAC)

turned off.!


3. Post-installation steps3.1. Configuring logging

The Integration Toolbox for TSM uses log4j for logging.

If you don’t have a log4j.properties file then copy the one found in the <installation location>/api/config to your working directory and add it to the CLASSPATH of your Java program.

You can modify this file to change the output format of the log. By default the logger creates two files under the log directory. The internal.log file contains the low level API logs, and the toolbox.log contains the Java API logs. New log files are generated daily.

3.2. Configuring environment variables

Navigate to the installation location and change to the <installation location>/api directory. Run the following scripts to set the environment variables for your platform.

3.2.1. LinuxExecute setenv.sh. This script creates /etc/profile.d/toolbox.sh which sets the DSMI_DIR, DSMI_LOG and DSMI_CONFIG environment variables needed for Integration Toolbox for TSM on each subsequent login.

3.2.2. WindowsExecute setenv.bat. This script sets the DSMI_LOG and DSMI_CONFIG environment variables needed for Integration Toolbox for TSM both in the current command line window and in the system environment.

3.2.3. AIXExecute setenv.sh. This script creates /etc/profile.d/toolbox.sh which sets the DSMI_DIR, DSMI_LOG and DSMI_CONFIG environment variables needed for Integration Toolbox for TSM on each subsequent login.

3.3. Verifying the installation

To verify the installation see Section 5.1. Using the Toolbox for TSM command line examples and execute the ConnectDisconnect sample application.

NOTE:If you use an application with an existing log4j . properties file, the contents of the file from the installation package must be merged with

the existing one.!

NOTE: If these environment variables are already set, the script will

overwrite them without warning.!

NOTE:If these environment variables are already set, the script will


NOTE:If these environment variables are already set, the script will



4. Deploying the RESTful Web ServiceThe RESTful API component makes many TSM functions accessible using standard JAX-RS 2.0 web service calls. Among others, you can:

• backup and archive files;• restore and retrieve previously backed up and archived files;• query the archive and backup objects;• query filespaces;• manage the retention state of archive objects;• update object metadata.

4.1. Deploying on WebSphere

4.1.1. Resource AdapterThe tsmra.rar resource adapter is created to enable connection pooling on the application server. The number of active TSM connections can be easily configured on the application servers using the connection pool.

4.1.1.1. Deploying theRAR file1. Navigate to the Resources -> Resource Adapters -> Resource adapters menu.2. Select the scope (node) you want to use for the resource adapter then click Install RAR.


3. Locate the tsmra.rar file (default location: <installation location>/rest/tsmra.rar) then click Next.

4. Specify the name of the resource adapter (for example ToolboxResourceAdapter) and fill in the Native library path with <installation location>/api/lib then click OK.


5. Click Save to save the changes.

4.1.1.2. Creating the connection pool1. Click on the newly created resource adapter.2. Under Additional Properties choose J2C connection factories.3. On the next page click on New….


4. Fill in the required fields (use ToolboxConnectionPool as Name for example). Specify the JNDI name (eis/tsmConnectionFactory for example) then click OK.


5. Copy other properties such as the nodeName, password and serverName for the connection pool under Additional Properties -> Custom properties from the <installation location>/api/config/dsm.opt file. For example set the nodeName property to “TOOLBOX” and the password property to “PASSWORD” as seen in the samples.


6. To apply the changes click OK then save the changes by clicking Save.

4.1.2. Web Service4.1.2.1. Adding shared librariesThe web service requires additional libraries that have to be added to the application server.

1. Navigate to Environment -> Shared Libraries menu.2. Under the Scope section choose the appropriate Node and Server


3. Click on New… to create a new Shared Library. Fill in the required fields. Set the Name to Jersey and set the Classpath to <installation location>/rest/ext then click OK.



4.1.2.2. Configuring the classloader1. Navigate to Servers -> Server Types -> WebSphere application servers and choose your server.


2. Under Server Infrastructure expand the Java and Process Management section and click on Class loader.

3. Click on New… to create a new Class loader configuration.


4. From the Class loader order drop down list choose Class loaded with local class loader first (parent last).



6. Click on the newly created class loader configuration then click on Shared library references.

7. Click Add to add the previously created shared library.

8. From the Library Name drop down list choose Jersey then click OK.


9. Click Save to save the changes and restart the application server for the changes to take effect.

4.1.2.3. Deploying the WAR file1. Navigate to the Applications -> Application Types -> WebSphere enterprise applications menu.2. Select Remote file system and browse for the toolboxfortsm.war file (default location: <installation

location>/rest/toolboxfortsm.war) then click Next.

3. Choose the Fast Past method then click Next.


4. On the Select Installation Options panel choose Next.


5. On the Map modules to servers panel click Next.

6. On the Map resource references to resource panel specify the Target Resource JNDI Name (eis/tsmConnectionFactory for example) then click Next.

NOTE:This must be the same as the name set during the con fi guration of the connection

pool.!


7. On the Map Virtual hosts for Web modules panel click Next.

8. On the Map context roots for Web modules panel change Context Root to “/toolboxfortsm” then click Next.


9. On the Metadata for modules panel click Next.


10. On the Summary panel you can review the installation options. If everything is set correctly, click Finish.


4.2. Deploying on Glassfish

4.2.1. Resource AdapterThe tsmra.rar resource adapter is created to enable connection pooling on the application server. The number of active TSM connections can be easily configured on the application servers using the connection pool.

4.2.1.1. Deploying the RAR file1. Navigate to the Configurations -> server-config menu then click the Path Settings tab and fill in the

Native Library Path Suffix with <installation location>/api/lib then click Save.

2. Navigate to the server (Admin Server) menu then on the General tab click Restart.

3. Navigate to the Applications menu then click Deploy….


4. Locate the tsmra.rar file (default location: <installation location>/rest/tsmra.rar) then click OK.

4.2.1.2. Creating the resource adapter configuration1. Navigate to the Resources -> Resource Adapter Config menu then click New….


2. For the Resource Adapter Name choose tsmra from the drop down list.3. Change the Thread Pool ID field to a valid value from the list then click OK.

4.2.1.3. Creating the connection pool1. Navigate to the Resources -> Connectors -> Connector Connection Pools menu then click New….

2. Fill in the required fields (use ToolboxConnectionPool as Pool Name for example). As the Resource Adapter choose tsmra from the drop down list. As the Connection Definition choose ToolboxConnectionFactory then click Next.


3. On the next page change the Transaction Support field to NoTransaction. You may copy the nodeName, password and serverName properties for the connection pool under Additional Properties from the <installation location>/api/config/dsm.opt file. For example set the nodeName property to “TOOLBOX” and the password property to “PASSWORD” as seen in the samples. To save the configuration click Finish.


4.2.1.4. Creating the connector resource1. Navigate to the Resources -> Connectors -> Connector Resources menu then click New….

2. Fill in the required fields. Set the JNDI name to eis/tsmConnectionFactory. Choose the previously specified connection pool for the Pool Name then click OK.


4.2.2. Web Service4.2.2.1. Deploying the WAR file

1. Navigate to the Applications menu then click Deploy….

2. Browse for the the toolboxfortsm.war file (default location: <installation location>/rest/toolboxfortsm.war) then click OK.


4.2.2.2. Starting and stopping the web service• To start the application select the toolboxfortsm element from the list then click Enable. The application

status should change to enabled.• To stop the application select the toolboxfortsm element from the list then click Disable. The application

status should change to disabled.

4.2.3. Verifying the installationTo verify the deployment see Section 5.1. Using the Toolbox for TSM command line examples and execute the RegisterFilespace sample application with filespace name of your choice. Execute the following command using curl or navigate to the given URL in a web browser:

curl -X GET -i "http://toolboxserver.yourdomain.com:9080/toolboxfortsm/filespace"

If successful, you should see the newly created filespace in the returned list.


5. Validating the installed environment5.1. Using the Toolbox for TSM command line examples

The samples folder contains programs demonstrating the use of each API method.

To compile the samples on AIX and Linux execute the compile_samples.sh script. On Windows execute the compile_samples.bat script.

To prepare the TSM server execute the prepare_tsm_server.sh script on AIX and Linux and execute the prepare_tsm_server.bat script on Windows to register the nodes and define the management classes needed by the samples. The samples use the option files located under the api/config directory.To run a sample execute the run_sample.sh or run_sample.bat script with one of the sample programs. To run a specific sample add the program name in <directory>.<name> format as a parameter (for example

run_sample.sh query.QueryManagementClasses). Specify additional parameters when needed (for instance a filespace name when registering a new filespace).

For further information, visit our Getting started page (http://toolboxfortsm.com/index.html#getting-started). If you have any questions, please contact us via e-mail: [email protected].

5.2. Using REST services

To send, delete or update objects use the command line tool curl. (The hostname, port and contextroot parameters must be set to values according to your environment.)

• Uploading a file (backing up an object):curl -X PUT -i -H "Content-Type:application/octet-stream" --data-binary @image.jpg "http://toolboxserver.yourdomain.com:9080/toolboxfortsm/backupObject/BACKUPFS/HIGHLEVEL/LOWLEVEL"

• Listing all backed up objects with a given name:curl -X GET -i "http://toolboxserver.yourdomain.com:9080/toolboxfortsm/backupObject/BACKUPFS/HIGHLEVEL/LOWLEVEL/versions"

• Downloading a file (restoring a backed up object):curl -X GET -O "http://toolboxserver.yourdomain.com:9080/toolboxfortsm/backupObject/BACKUPFS/HIGHLEVEL/LOWLEVEL"

• Updating a backed up object:curl -X POST -i "http://toolboxserver.yourdomain.com:9080/toolboxfortsm/backupObject/BACKUPFS/HIGHLEVEL/LOWLEVEL?owner=owner&information=info&management-class=TOOLBOX_MGMT_BCG&estimated-size=123456"

• Deleting a backed up object:curl -X DELETE -i "http://toolboxserver.yourdomain.com:9080/toolboxfortsm/backupObject/BACKUPFS/HIGHLEVEL/LOWLEVEL"

You can also use a web browser to test GET requests.• To restore an object navigate to the URL http://toolboxserver.yourdomain.com:9080/toolboxfortsm/

backupObject/BACKUPFS/HIGHLEVEL/LOWLEVEL.• To get the list of backup objects with a given name navigate to the URL http://toolboxserver.yourdomain.

com:9080/toolboxfortsm/backupObject/BACKUPFS/HIGHLEVEL/LOWLEVEL/versions.

NOTE: The directory of java, javac and jar programs must be

in the PATH.!

mailto:[email protected]


6. TrademarksIBM, Tivoli, System Storage and AIX are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. The IBM logo and the IBM Premier Business Partner mark are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Red Hat Enterprise Linux is a registered trademark of Red Hat, Inc. in the U.S. and other countries. Linux is a registered trademark of Linus Torvalds. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Any other names contained herein may be trademarks of their respective owners. Apache and Apache log4j are trademarks of the Apache Software Foundation.

Version 1.0Installation Guide

INTEGRATION TOOLBOXfor IBM® Tivoli® Storage Manager

integration toolboxtoolboxfortsm.com/toolbox4tsm_installguide.pdf · integration toolbox for tivoli...

Documents