Download Installing IBM Access Client Solutions using the Java Web Start

Front cover
Installing IBM i Access Client
Solutions using the
Java Web Start method
Ryan Cooper
Tom Vernaillen
Redpaper
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
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
© 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.
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
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:
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\
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 1.
250 "/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: 64063324 bytes sent in 129.33Seconds 495.35Kbytes/sec.
ftp>bye
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')
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
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 :
Control :
1
89 by
74
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
F17=Repeat change F19=Left F20=Right
F16=Repeat find
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
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
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:
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.
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 “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"/>
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
CHGAUT
CHGAUT
CHGAUT
OBJ('/www/acs/htdocs/cur') USER(QTMHHTTP) DTAAUT(*R) SUBTREE(*ALL)
OBJ('/www/acs/htdocs/test') USER(QTMHHTTP) DTAAUT(*R) SUBTREE(*ALL)
OBJ('/www/acs/htdocs/cur') USER(QTMHHTTP) DTAAUT(*RX)
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.
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
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
Back cover
REDP-5304-00
ISBN 073845494X
Printed in U.S.A.
®
ibm.com/redbooks