INTEGRATION TOOLBOX. Installation Guide. for IBM Tivoli Storage Manager.

Transcription

1 INTEGRATION TOOLBOX for IBM Tivoli Storage Manager Installation Guide

2 INTEGRATION TOOLBOX for IBM Tivoli Storage Manager Version 1.0 Installation Guide Integration Toolbox for Tivoli Storage Manager Installation Guide ii

3 Integration Toolbox for IBM Tivoli Storage Manager Installation Guide Contents Introduction... 1 Components at a glance Installation planning Components Prerequisites Java API for IBM Tivoli Storage Manager RESTful API for IBM Tivoli Storage Manager with WebSphere Application Server RESTful API for IBM Tivoli Storage Manager with Glassfish Installing the Integration Toolbox for TSM Installing on Linux Installing on Windows Installing on AIX Post-installation steps Configuring logging Configuring environment variables Linux Windows AIX Verifying the installation Deploying the RESTful Web Service Deploying on WebSphere Resource Adapter Deploying the RAR file Creating the connection pool Web Service Adding shared libraries Configuring the classloader Deploying the WAR file Deploying on Glassfish Resource Adapter Deploying the RAR file Creating the resource adapter configuration Creating the connection pool Creating the connector resource Web Service Deploying the WAR file Starting and stopping the web service Verifying the installation Validating the installed environment Using the Toolbox for TSM command line examples Using REST services Trademarks Integration Toolbox for Tivoli Storage Manager Installation Guide iii

4 Introduction It 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 ( If you have any questions, please contact us via info@toolboxfortsm.com. Components at a glance The 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. J2EE RESTful API for TSM REST (JAX-RS 2.0) Resource Adapter Standalone Java Application Toolbox (Java API for TSM) TSM Client TSM Server Integration Toolbox for Tivoli Storage Manager Installation Guide 1

5 1. Installation planning 1.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 Java API for IBM Tivoli Storage Manager Operating System Java JDK TSM Client API Red 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, Ultimate Windows 8 Core, Pro, Enterprise Windows Server 2008 Standard Edition x32 and x64 Windows Server 2008 Datacenter Edition x32 and x64 Windows Server 2008 Enterprise Edition x32 and x64 Windows Server 2008 R2 Standard Edition Windows Server 2008 R2 Data center Edition Windows Server 2008 R2 Enterprise Edition Java Development Kit 6 or higher Tivoli Storage Manager Client API 6.4 or higher IBM AIX 6.1 IBM AIX 7.1 Java Development Kit 6 or higher Tivoli Storage Manager Client API 6.4 or higher RESTful API for IBM Tivoli Storage Manager with WebSphere Application Server Operating System Application Server Java JRE TSM Client API Red Hat Enterprise Linux (RHEL) 5 Client Update 6 Red Hat Enterprise Linux (RHEL) 5 Server Update 6 WebSphere Application Server Base Edition or higher WebSphere Application Java Runtime Environment 7 or higher Tivoli Storage Manager Client API 6.4 or higher Red Hat Enterprise Linux (RHEL) Server Network Deployment Client 6 Base or higher Red Hat Enterprise Linux (RHEL) Server 6 Base Windows 7 Professional, Enterprise, Ultimate Windows 8 Core, Pro, Enterprise Windows Server 2008 Standard Edition x32 and x64 Windows Server 2008 Datacenter Edition x32 and x64 Windows 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 or higher WebSphere Application Server Network Deployment or higher Java Runtime Environment 7 or higher Tivoli Storage Manager Client API 6.4 or higher Integration Toolbox for Tivoli Storage Manager Installation Guide 2

6 Operating System Application Server Java JRE TSM Client API AIX 6.1 TL5 or higher WebSphere Application Java Runtime Tivoli Storage AIX 7.1 TL1 or higher Server Base Edition or higher Environment 7 or higher Manager Client API 6.4 or higher AIX 6.1 TL0 SP4 or higher AIX 7.1 TL1 SP2 or higher WebSphere Application Server Network Deployment or higher Java Runtime Environment 7 or higher RESTful API for IBM Tivoli Storage Manager with Glassfish Tivoli Storage Manager Client API 6.4 or higher Operating System Application Server Java JRE TSM Client API Red Hat Enterprise Linux 5 (64 bit) GlassFish 4.0 or higher Java Runtime Tivoli Storage Red Hat Enterprise Linux 6 (64 bit) Environment 7 or higher Manager Client API 6.4 or higher Windows 7 Professional, Enterprise, Ultimate Windows 8 Core, Pro, Enterprise Windows Server 2008 Standard Edition x32 and x64 Windows Server 2008 Datacenter Edition x32 and x64 Windows 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 GlassFish 4.0 or higher GlassFish 4.0 or higher Java Runtime Environment 7 or higher Java Runtime Environment 7 or higher Tivoli Storage Manager Client API 6.4 or higher Tivoli Storage Manager Client API 6.4 or higher Integration Toolbox for Tivoli Storage Manager Installation Guide 3

7 2. Installing the Integration Toolbox for TSM 2.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 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" NOTE: The package is installed to the C:\Program Files\toolbox-for-tsm directory by default. For the silent installation to work, you will need User Account Control (UAC) turned off.! 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 4

8 3. Post-installation steps 3.1. Configuring logging 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.! 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. 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 overwrite them without warning.! NOTE: If these environment variables are already set, the script will overwrite them without warning.! 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 Linux Execute 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 Windows Execute 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 AIX Execute 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 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 5

9 4. Deploying the RESTful Web Service The 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 Deploying on WebSphere Resource Adapter The 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 Deploying therar file 1. 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 6

10 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 7

11 5. Click Save to save the changes Creating the connection pool 1. Click on the newly created resource adapter. 2. Under Additional Properties choose J2C connection factories. 3. On the next page click on New. Integration Toolbox for Tivoli Storage Manager Installation Guide 8

12 4. Fill in the required fields (use ToolboxConnectionPool as Name for example). Specify the JNDI name (eis/tsmconnectionfactory for example) then click OK. Integration Toolbox for Tivoli Storage Manager Installation Guide 9

13 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 10

14 6. To apply the changes click OK then save the changes by clicking Save Web Service Adding shared libraries The 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 Integration Toolbox for Tivoli Storage Manager Installation Guide 11

15 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 12

16 4. Click Save to save the changes Configuring the classloader 1. Navigate to Servers -> Server Types -> WebSphere application servers and choose your server. Integration Toolbox for Tivoli Storage Manager Installation Guide 13

17 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 14

18 4. From the Class loader order drop down list choose Class loaded with local class loader first (parent last). 5. Click Save to save the changes. Integration Toolbox for Tivoli Storage Manager Installation Guide 15

19 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 16

20 9. Click Save to save the changes and restart the application server for the changes to take effect Deploying the WAR file 1. 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 17

21 4. On the Select Installation Options panel choose Next. Integration Toolbox for Tivoli Storage Manager Installation Guide 18

22 5. On the Map modules to servers panel click Next. NOTE: This must be the same as the name set during the con fi guration of the connection pool.! 6. On the Map resource references to resource panel specify the Target Resource JNDI Name (eis/ tsmconnectionfactory for example) then click Next. Integration Toolbox for Tivoli Storage Manager Installation Guide 19

23 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 20

24 9. On the Metadata for modules panel click Next. Integration Toolbox for Tivoli Storage Manager Installation Guide 21

25 10. On the Summary panel you can review the installation options. If everything is set correctly, click Finish. Integration Toolbox for Tivoli Storage Manager Installation Guide 22

26 4.2. Deploying on Glassfish Resource Adapter The 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 Deploying the RAR file 1. 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 23

27 4. Locate the tsmra.rar file (default location: <installation location>/rest/tsmra.rar) then click OK Creating the resource adapter configuration 1. Navigate to the Resources -> Resource Adapter Config menu then click New. Integration Toolbox for Tivoli Storage Manager Installation Guide 24

28 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 Creating the connection pool 1. 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 25

29 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 26

30 Creating the connector resource 1. 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 27

31 Web Service 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 28

32 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 Verifying the installation To 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 " filespace" If successful, you should see the newly created filespace in the returned list. Integration Toolbox for Tivoli Storage Manager Installation Guide 29

33 NOTE: The directory of java, javac and jar programs must be in the PATH.! 5. Validating the installed environment 5.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 ( If you have any questions, please contact us via info@toolboxfortsm.com 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" " backupobject/backupfs/highlevel/lowlevel" Listing all backed up objects with a given name: curl -X GET -i " backupobject/backupfs/highlevel/lowlevel/versions" Downloading a file (restoring a backed up object): curl -X GET -O " backupobject/backupfs/highlevel/lowlevel" Updating a backed up object: curl -X POST -i " backupobject/backupfs/highlevel/lowlevel?owner=owner&information=info&m anagement-class=toolbox_mgmt_bcg&estimated-size=123456" Deleting a backed up object: curl -X DELETE -i " toolboxfortsm/backupobject/backupfs/highlevel/lowlevel" You can also use a web browser to test GET requests. To restore an object navigate to the URL backupobject/backupfs/highlevel/lowlevel. To get the list of backup objects with a given name navigate to the URL com:9080/toolboxfortsm/backupobject/backupfs/highlevel/lowlevel/versions. Integration Toolbox for Tivoli Storage Manager Installation Guide 30

34 6. Trademarks IBM, 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. Integration Toolbox for Tivoli Storage Manager Installation Guide 31

35 INTEGRATION TOOLBOX for IBM Tivoli Storage Manager Version 1.0 Installation Guide