Redpaper

Front cover

Installing IBM i Access Client Solutions using theJava Web Start method

Ryan Cooper

Tom Vernaillen

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.

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

http://www.ibm.com/systems/power/software/i/access/solutions.html

� IBM i Access Client Solutions

http://www.ibm.com/developerworks/ibmi/library/i-access_client_solutions

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.

© Copyright IBM Corp. 2016. All rights reserved. ibm.com/redbooks 1

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.

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.

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.

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

Example 1 Running the keytool command

> mkdir /javakeystores> cd /javakeystores> keytool -genkeypair -alias acsbundle -keypass certpassword -validity 730 -keystore acsbundle -storepass storepasswordWhat 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:

https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html

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

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:

http://quserlab.local:2001/HTTPAdmin

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

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

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

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:

http://quserlab.local:8080

Figure 7 Web server sample home page

7

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:

http://www.ibm.com/systems/power/software/i/access/solutions.html

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\

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.localConnected to quserlab.local.220-QTCP at QUSERLAB.220 Connection will close if idle more than 5 minutes.User (quserlab.local:(none)): ryanc331 Enter password.Password:230 RYANC logged on.

ftp> cd /tmp250-NAMEFMT set to 1.250 "/tmp" is current directory.

ftp> bin200 Representation type is binary IMAGE.

ftp> put C:\Users\RyanC\Downloads\IBMiAccess_v1r1.zip200 PORT subcommand request successful.150 Sending file to /tmp/IBMiAccess_v1r1.zip226 File transfer completed successfully.ftp: 64063324 bytes sent in 129.33Seconds 495.35Kbytes/sec.

ftp>bye

Note: This file will be extracted on the server. Do not extract it on your computer now.

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

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')STRQSHcd /www/acs/htdocs/curjar -xvf /tmp/IBMiAccess_v1r1.zipcd /www/acs/htdocs/testjar -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

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.

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:

https://docs.oracle.com/cd/E19501-01/819-3659/gcjlg/index.html

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

Edit File: /www/acs/htdocs/test/AcsConfig.properties Record : 88 of 117 by 8 Column : 1 89 by 74 Control : CMD ....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+ # 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

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 11.

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

Example 4 Signing the JAR files used for Java Web Start

STRQSHcd /www/acs/htdocs/curjarsigner -keystore /javakeystores/acsbundle -storepass storepassword -keypass certpassword -signedjar Sacsbundle.jar acsbundle.jar acsbundle

cd /www/acs/htdocs/testjarsigner -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:

http://www.ibm.com/developerworks/library/j-jar

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.

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 “http://quserlab.local:8080/cur” 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="http://quserlab.local:8080/cur"><information><title>IBM i Access Client Solutions (Production Version 1.1)</title><vendor>Company Name</vendor><offline-allowed/></information><resources><jar href="Sacsbundle.jar"/>

Note: The syntax and usage of this protocol are subject to change between different client Java versions.

11

<j2se version="1.6+" href="http://java.sun.com/products/autodl/j2se" 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:

https://docs.oracle.com/javase/tutorial/deployment/deploymentInDepth/jnlp.html

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

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

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:

http://quserlab.local:8080/test/acslaunch_test.jnlp

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

References

The following list of useful resources related to this topic are also helpful:

� IBM i Access

http://www.ibm.com/systems/power/software/i/access/solutions.html

� JAR files revealed

http://www.ibm.com/developerworks/library/j-jar

� Setting Up the Web Site

http://docs.oracle.com/javase/1.5.0/docs/guide/javaws/developersguide/setup.html

� IBM i Access Client Solutions: Accessing IBM i has never been easier

http://www.ibm.com/developerworks/ibmi/library/i-access_client_solutions

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.

Thanks to the following people for their contributions to this project:

Debbie LandonAnn LundIBM International Technical Support Organization, 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.

15

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:

http://www.facebook.com/IBMRedbooks

� Follow us on Twitter:

https://twitter.com/ibmredbooks

� Look for us on LinkedIn:

http://www.linkedin.com/groups?home=&gid=2130806

� Explore new Redbooks publications, residencies, and workshops with the IBM Redbooks weekly newsletter:

https://www.redbooks.ibm.com/Redbooks.nsf/subscribe?OpenForm

� Stay current on recent Redbooks publications with RSS Feeds:

http://www.redbooks.ibm.com/rss.html

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

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 10504-1785, 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. 2016. All rights reserved. 17

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 http://www.ibm.com/legal/copytrade.shtml

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

ibm.com/redbooks

Printed in U.S.A.

Back cover

ISBN 073845494X

REDP-5304-00

®