Installing IBM i Access Client Solutions using the Java Web Start method

Transcription

1 Front cover Installing IBM i Access Client Solutions using the Java Web Start method Ryan Cooper Tom Vernaillen Redpaper

2

3 Installing IBM i Access Client Solutions using the Java Web Start method This IBM Redpaper publication shows you how to set up an environment to host the IBM i Access Client Solutions software and serve it to users using the Java Web Start process. The example shown in this paper creates a new HTTP server to host a production and test environment of IBM i Access Client Solutions. When possible, IBM i command language (CL) commands are used in this example. However, some steps can be performed on your local computer to avoid complexity of the task. Examples used in this publication: The process of installing IBM i Access Client Solutions software using the Java Web Start process relies on having a Java client installed and your ability to make some custom changes to the Java configuration. As the authors of this paper discovered while creating this paper, the client installed version of Java and the configuration of it varies from one computer to the next. Because we cannot verify and test this process for every scenario, we provide examples that worked for us. The following topics are covered in this paper: Step 1: Creating the Java keystore and certificate Step 2: Creating the HTTP server on page 3 Step 3: Downloading and extracting IBM i Access Client Solutions on page 8 Step 4: Setting up the IBM i Access Client environment on page 9 Step 5: Customizing the AcsConfig.properties file on page 9 Step 6: Signing the JAR file on page 10 Step 7: Setting up the.jnlp file on page 11 Step 8: Authority settings on page 12 Step 9: Client considerations on page 13 Step 10: Testing the installation on page 14 For more information about IBM i Access Client Solutions, see the following websites: IBM i Access IBM i Access Client Solutions Copyright IBM Corp All rights reserved. ibm.com/redbooks 1

4 Step 1: Creating the Java keystore and certificate Creating the Java keystore is a simple process. However, some planning should be done before you proceed. You should answer the following questions before running the command to create the Java keystore. Tip: If your company has a department that manages certificates, have them review the questions presented in this section. Also, the IBM i integrated file system (IFS) directory used to create the Java keystore should be in a secure location. The IFS directory location for the Java keystore is /javakeystores. The keytool command is used to create the Java keystore and requires the following parameters: Name of the Java keystore Keystore password Certificate alias Certificate password Certificate validity period After the keytool command has been issued, you are prompted for the following information: What is your first and last name? What is the name of your organizational unit? What is the name of your organization? What is the name of your City or Locality? What is the name of your State or Province? What is the two-letter country code for this unit? In this example, the following values and answers are entered for the keytool command parameters and prompts: Name of the Java keystore: acsbundle Keystore password: storepassword Certificate alias: acsbundle Certificate password: certpassword Certificate validity period: 730 What is your first and last name? Ryan Cooper What is the name of your organizational unit? IT What is the name of your organization? Company Name What is the name of your City or Locality? Rochester What is the name of your State or Province? Minnesota What is the two-letter country code for this unit? US Start the Qshell environment by entering the STRQSH command. Enter the commands as shown in Example 1 on page 3. 2 Installing IBM i Access Client Solutions using the Java Web Start method

5 Example 1 Running the keytool command > mkdir /javakeystores > cd /javakeystores > keytool -genkeypair -alias acsbundle -keypass certpassword -validity 730 -keystore acsbundle -storepass storepassword What is your first and last name? [Unknown]: > Ryan Cooper What is the name of your organizational unit? [Unknown]: > IT What is the name of your organization? [Unknown]: > Company Name What is the name of your City or Locality? [Unknown]: > Rochester What is the name of your State or Province? [Unknown]: > Minnesota What is the two-letter country code for this unit? [Unknown]: > US Is CN=Ryan Cooper, OU=IT, O=Company Name, L=Rochester, ST=Minnesota, C=US cor rect? (type "yes" or "no") [no]: > yes$ Press F3 to exit Qshell. For more information about the keytool command, refer to your Java provider. For example: Step 2: Creating the HTTP server In this example, an Apache HTTP server is created to host the IBM i Access Client Solutions software. You can also use an existing web server. Before creating the new web server, check to ensure that the new port to be used is not currently in use. This can be done by using the NETSTAT *CNN command. The following information for creating a new web server is used in this example: Server Name: ACS Server Description: Access Client Solutions Install Server Server root: /www/acs Document root: /www/acs/htdocs IP address: All IP address Port: 8080 In this example, the server name is QUSERLAB and the domain is LOCAL. 3

6 Run the following steps to create an HTTP server: 1. Assuming the *ADMIN HTTP Server is already running, access the IBM Web Administration for i from a web browser: 2. From the IBM Web Administration for i window, select Create HTTP Server located under the Common Tasks and Wizards menu. 3. On the Create HTTP Server window (Figure 1), enter the Server name and description. In this example, the server is called ACS. Click Next. Figure 1 Create HTTP Server: Server name 4. Enter the Server root and click Next (Figure 2). Figure 2 Create HTTP Server: Server root 4 Installing IBM i Access Client Solutions using the Java Web Start method

7 5. Enter the Document root and click Next (Figure 3). Figure 3 Create HTTP Server: Document root 6. Select an IP address and enter the port number (Figure 4). Click Next. Figure 4 Create HTTP Server: IP address and port 5

8 7. Click Next until you get to the verify window as shown in Figure 5. Click Finish. Figure 5 Create HTTP Server: Review 8. After the Create HTTP Server wizard process has completed, add a MIME type map as shown in Figure 6 on page 7: a. Under the Server Properties menu, select Content Settings. b. On the Content Settings panel, add a MIME type map for.jnlp file extensions with a value of application/x-java-jnlp-file. c. Click Continue. d. Click Apply. 6 Installing IBM i Access Client Solutions using the Java Web Start method

9 Figure 6 Adding a MIME map for the.jnlp file extension 9. Start the web server. If the web server was already started, stop and restart the web server for this change to be applied. 10.Test access to the new web server by browsing to the following URL. If the web server is set up correctly, you see the sample home page shown in Figure 7: Figure 7 Web server sample home page 7

10 Step 3: Downloading and extracting IBM i Access Client Solutions Run the following steps to download and extract the latest version of IBM i Access Client Solutions: 1. Download the latest version of IBM i Access Client Solutions from the IBM i Access website: In this example, the IBMiAccess_v1r1.zip file has been downloaded to the following location on the local PC, which will then be FTP to the server: C:\Users\RyanC\Downloads\ Note: This file will be extracted on the server. Do not extract it on your computer now. 2. FTP the IBMiAccess_v1r1.zip file to the server by using the commands shown in Example 2. Example 2 FTPing the zip file to the server C:\Users\RyanC>ftp quserlab.local Connected to quserlab.local. 220-QTCP at QUSERLAB. 220 Connection will close if idle more than 5 minutes. User (quserlab.local:(none)): ryanc 331 Enter password. Password: 230 RYANC logged on. ftp> cd /tmp 250-NAMEFMT set to "/tmp" is current directory. ftp> bin 200 Representation type is binary IMAGE. ftp> put C:\Users\RyanC\Downloads\IBMiAccess_v1r1.zip 200 PORT subcommand request successful. 150 Sending file to /tmp/ibmiaccess_v1r1.zip 226 File transfer completed successfully. ftp: bytes sent in Seconds Kbytes/sec. ftp>bye 8 Installing IBM i Access Client Solutions using the Java Web Start method

11 Step 4: Setting up the IBM i Access Client environment In this example, production and test IBM i Access Client instances are created. This allows you to have a test environment for testing new releases and making custom changes to the default configuration. The production instance will be in the IFS location of /www/acs/htdocs/cur and the test instance will be in the IFS location of /www/acs/htdocs/test. Use the commands shown in Example 3 to create the IFS directories and then extract the zip file to each location. Example 3 Creating the production and test directories and extracting the zip file in each location MKDIR DIR('/www/acs/htdocs/cur') MKDIR DIR('/www/acs/htdocs/test') STRQSH cd /www/acs/htdocs/cur jar -xvf /tmp/ibmiaccess_v1r1.zip cd /www/acs/htdocs/test jar -xvf /tmp/ibmiaccess_v1r1.zip Step 5: Customizing the AcsConfig.properties file Changes can be made to the AcsConfig.properties file for each instance. To edit the file for the test instance, use the following EDTF command: EDTF STMF('/www/acs/htdocs/test/AcsConfig.properties') 9

12 Figure 8 shows disabling the KEYMAN, OPCONSOLE, HWCONSOLE, and L1CPLUGIN options by removing the comment (#) from the beginning of the line. After making changes, press F3 to save and exit the AcsConfig.properties file. Edit File: /www/acs/htdocs/test/acsconfig.properties Record : 88 of 117 by 8 Column : 1 89 by 74 Control : CMD # Example 2: com.ibm.iaccess.excludecomps=keyman,opconsole,hwconsole,l1cplugin # # Help text for the product normally displays in the configured desktop bro # In some cases, interaction with the browser does not work properly. For # or for when displaying the help text outside the configured browser is de # following property to false: # com.ibm.iaccess.javaawtdesktopallowed=false # Setting the property com.ibm.iaccess.datacache=true will reduce working s # and will significantly reduce startup times when the product jar file is # (e.g network share). # com.ibm.iaccess.datacache=true F2=Save F3=Save/Exit F12=Exit F15=Services F16=Repeat find F17=Repeat change F19=Left F20=Right Figure 8 Editing the AcsConfig.properties file Step 6: Signing the JAR file The acsbundle.jar file that was extracted as part of the IBMiAccess_v1r1.zip file is required to be signed. More information about this requirement can be found in the documentation from your Java provider. One source for this can be found on the following website: The signing process uses the information from the Step 1: Creating the Java keystore and certificate on page 2 task. Run the commands listed in Example 4 on page 11 by using the jarsigner command to sign the JAR files, where: jarsigner -keystore /javakeystores/acsbundle is the IFS location to the Java keystore -storepass storepassword is the password to the Java keystore -keypass certpassword is the password to the certificate alias -signedjar Sacsbundle.jar is the resulting signed JAR file acsbundle.jar is the original JAR file to be signed acsbundle is the certificate alias name Note: If you made any changes to the values in the Step 1: Creating the Java keystore and certificate on page 2 task, update those values in the commands shown in Example 4 on page Installing IBM i Access Client Solutions using the Java Web Start method

13 Example 4 Signing the JAR files used for Java Web Start STRQSH cd /www/acs/htdocs/cur jarsigner -keystore /javakeystores/acsbundle -storepass storepassword -keypass certpassword -signedjar Sacsbundle.jar acsbundle.jar acsbundle cd /www/acs/htdocs/test jarsigner -keystore /javakeystores/acsbundle -storepass storepassword -keypass certpassword -signedjar Sacsbundle.jar acsbundle.jar acsbundle More information about the jarsigner process can be found on the following website: Step 7: Setting up the.jnlp file You now need to create two Java Network Launch Protocol (.jnlp) files, one in each instance location. It is this.jnlp file that is called in the client web browser. Think of this file as a link between the client browser and the IBM i Access Client Solution program. Note: The syntax and usage of this protocol are subject to change between different client Java versions. To avoid some conversion problems, it is suggested to copy and paste the text shown in Example 5 into a notepad file and save it as acslaunch.jnlp and then save it again as acslaunch_test.jnlp. Then, FTP the files to the appropriate IFS locations. In Example 5, make the following changes: Line 2: Replace with your web server name and port number. Line 4: Change the title and version number as you prefer. Line 5: Replace Company Name with your company name. Save the file as acslaunch.jnlp. Repeat the process for the test instance: Line 2: Replace /cur with /test. This allows access to the test instance of Access Client Solutions. Line 4: Change the title and version number as you prefer. Save the file as acslaunch_test.jnlp. Example 5 Editing the acslaunch.jnlp file <?xml version="1.0" encoding="utf-8"?> <jnlp spec="1.0" codebase=" <information> <title>ibm i Access Client Solutions (Production Version 1.1)</title> <vendor>company Name</vendor> <offline-allowed/> </information> <resources> <jar href="sacsbundle.jar"/> 11

14 <j2se version="1.6+" href=" max-heap-size="1g" java-vm-args="-djava.security.manager=none"/> </resources> <application-desc main-class="com.ibm.iaccess.launch.acslaunchpad"/> <security> <all-permissions/> </security> </jnlp> Figure 9 is provided as a reference to show the exact syntax and layout of the.jnlp files for both instances. Notice there is no line wrap at line 10. After you have saved both files to your computer, transfer them to the following locations: acslaunch.jnlp should be transferred to /www/acs/htdocs/cur/acslaunch.jnlp acslaunch_test.jnlp should be transferred to /www/acs/htdocs/test/acslaunch_test.jnlp More information about the Java Network Launch Protocol can be found from your Java provider. One source for this can be found on the following website: Figure 9 Example of the acslaunch.jnlp files Step 8: Authority settings Ensure the correct file permission exists for user QTMHHTTP. The QTMHHTTP user should have read and execute permission to the document root sub directories /cur and /test. The same profile should have read authority to all files within these locations. Run the commands shown in Example 6 on page 13 to ensure that the permissions are set correctly. 12 Installing IBM i Access Client Solutions using the Java Web Start method

15 Example 6 Setting the correct directory and file permissions for user QTMHHTTP CHGAUT OBJ('/www/acs/htdocs/cur') USER(QTMHHTTP) DTAAUT(*R) SUBTREE(*ALL) CHGAUT OBJ('/www/acs/htdocs/test') USER(QTMHHTTP) DTAAUT(*R) SUBTREE(*ALL) CHGAUT OBJ('/www/acs/htdocs/cur') USER(QTMHHTTP) DTAAUT(*RX) CHGAUT OBJ('/www/acs/htdocs/test') USER(QTMHHTTP) DTAAUT(*RX) Step 9: Client considerations One key advantage of using the Java Web Start method to deploy IBM i Access Client Solutions in your organization is that the user systems need minimal, if any, setup. However, with all the security changes that have been made to protect user systems, the following tasks might need to be performed on each user system: A version of Java must be installed. Your web server address might need to be added to the Exception Site List in the Java Control Panel. The.jnlp file extension should be associated with the Java Web Start Launcher. Run the following steps to manage your Exception Site List on a Microsoft Windows 7 system: 1. Click Start. 2. Type in configure java and then select Configure Java from the search list. 3. On the Java Control Panel window, click the Security tab and then click Edit Site List. 4. On the Exception Site List window, add your web server URL as shown in Figure 10. Click Continue, then OK and OK again to close the Java Control Panel window. Figure 10 Java Exception Site list 13

16 Run the following steps to check the file association of.jnlp files on a Microsoft Windows 7 system: 1. Click Start. 2. Type in associated and select Change the file type associated with a file extension from the search list. 3. Select.jnlp from the list and if required set the current default to Java Web Start Launcher. Step 10: Testing the installation To test the installation of your IBM i Access Client instances, open your web browser and go to your test instance. For this example, the URL would be the following: If you get a security warning asking Do you want to run this application, as shown in Figure 11, everything worked as planned. Select the I accept the risk and want to run this application check box and click Run. Figure 11 Security Warning message Note: The first time each client system launches the website to load IBM i Access Client Solutions, the file structure is downloaded and stored in a cached Java location. This results in a longer initial start time. Care must also be taken for locations with slow or limited Internet access. Subsequent visits to the website only downloads files that have been changed since the last visit. 14 Installing IBM i Access Client Solutions using the Java Web Start method

17 References The following list of useful resources related to this topic are also helpful: IBM i Access JAR files revealed Setting Up the Web Site IBM i Access Client Solutions: Accessing IBM i has never been easier Authors This paper was produced by a team of specialists from around the world working at the IBM International Technical Support Organization (ITSO), Rochester Center. Ryan Cooper is an IBM Power Systems Engineer for Sirius Computer Solutions, which is headquartered in San Antonio, TX. He works in the Managed Services practice of the company, where Sirius provides system management and technical support for customers running various platforms, including IBM i running on IBM Power Systems. He also assisted IBM in the development of Power Systems certification tests as a subject matter expert (SME). Tom Vernaillen is a Senior IT Specialist in IBM Belgium. His areas of expertise include IBM i problem determination, network connectivity, and communications, including TCP/IP. He has participated in previous ITSO residencies, preparing technical overview presentation material and writing TCP/IP communications-related IBM Redbooks publications for IBM i. He is an Enhanced Technical Support remote Account Advocate for several IBM Power Systems customers. Thanks to the following people for their contributions to this project: Debbie Landon Ann Lund IBM International Technical Support Organization, Rochester Center 15

18 Now you can become a published author, too! Here s an opportunity to spotlight your skills, grow your career, and become a published author all at the same time! Join an ITSO residency project and help write a book in your area of expertise, while honing your experience using leading-edge technologies. Your efforts will help to increase product acceptance and customer satisfaction, as you expand your network of technical contacts and relationships. Residencies run from two to six weeks in length, and you can participate either in person or as a remote resident working from your home base. Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html Stay connected to IBM Redbooks Find us on Facebook: Follow us on Twitter: Look for us on LinkedIn: Explore new Redbooks publications, residencies, and workshops with the IBM Redbooks weekly newsletter: Stay current on recent Redbooks publications with RSS Feeds: 16 Installing IBM i Access Client Solutions using the Java Web Start method

19 Notices This information was developed for products and services offered in the US. This material might be available from IBM in other languages. However, you may be required to own a copy of the product or product version in that language in order to access it. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive, MD-NC119, Armonk, NY , US INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk. IBM may use or distribute any of the information you provide in any way it believes appropriate without incurring any obligation to you. The performance data and client examples cited are presented for illustrative purposes only. Actual performance results may vary depending on specific configurations and operating conditions. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to actual people or business enterprises is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs. Copyright IBM Corp All rights reserved. 17

20 Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol ( or ), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: Redbooks (logo) IBM Power Systems Redbooks Redpaper The following terms are trademarks of other companies: Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java, and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. Other company, product, or service names may be trademarks or service marks of others. 18 Installing IBM i Access Client Solutions using the Java Web Start method

21

22 Back cover REDP ISBN X Printed in U.S.A. ibm.com/redbooks