Before using this information and the product it supports, read the information in Appendix E. Notices.
Document number: SC14-7266-00
This edition applies to Version 11 of IBM® Rational Host On-Demand (program number 5724-I20) and to all subsequent releases and modifications until otherwise indicated in new editions.
The Planning, Installing, and Configuring Host On-Demand guide helps you to plan for, install, and configure the Host On-Demand program. This book is written for administrators. It contains three major parts.
Planning for Host On-Demand gives you information about Host On-Demand for you to consider before installation and deployment. For example, which server platform will you use? Which deployment model will you use? How will you handle security?
Installing, upgrading, and uninstalling Host On-Demand offers step-by-step procedures based on each operating system.
Configuring Host On-Demand describes different configuration models to specify how session configuration information is defined and managed, how to dynamically modify session configuration information, how to customize new clients, and how to deploy Host On-Demand to your users.
After you install and configure Host On-Demand, use the online help to learn how to define sessions and perform other administrative tasks.
Planning, Installing, and Configuring Host On-Demand is also available on the DVD-ROM and the Host On-Demand Information Center on the Web at http://publib.boulder.ibm.com/infocenter/hodhelp/v11r0/index.jsp.
In addition to the Planning, Installing, and Configuring Host On-Demand guide, Host On-Demand also provides other sources of information to help you use the product. To access the documentation described here, go to the Host On-Demand Information Center on the Web at http://publib.boulder.ibm.com/infocenter/hodhelp/v11r0/index.jsp. Most of the documentation is also included on the Host On-Demand product or Toolkit DVD-ROMs.
![]() |
The MySupport feature enables you to personalize your support view and register to receive weekly e-mail notifications alerting you of new fix packs, downloads, and hot technical support information for IBM products. To register for MySupport, complete the instructions in this Technote. |
The following typographic conventions are used in Planning, Installing and Configuring Host On-Demand:
Convention | Meaning |
---|---|
Monospace | Indicates text you must enter at a command prompt and values you must use literally, such as commands, functions, and resource definition attributes and their values. Monospace also indicates screen text and code examples. |
Italics | Indicates variable values you must provide (for example, you supply the name of a file for file_name). Italics also indicates emphasis and the titles of books. |
Return | Refers to the key labeled with the word Return, the word Enter, or the left arrow. |
> | When used to describe a menu, shows a series of menu selections. For example, "Click File > New" means "From the File menu, click the New command." |
When used to describe a tree view,
shows a series of folder or object expansions. For example, "Expand
HODConfig Servlet > Sysplexes > Plex1 > J2EE Servers > BBOARS2"
means:
|
![]() |
This graphic is used to highlight notes to the reader. |
![]() |
This graphic is used to highlight tips for the reader. |
This section describes the terminology used throughout this book.
Note the following terms and their use in this document.
IBM Rational Host On-Demand provides cost effective and secure browser-based and non-browser-based host access to users in intranet-based and extranet-based environments. Host On-Demand is installed on a Web server, simplifying administrative management and deployment, and the Host On-Demand applet or application is downloaded to the client browser or workstation, providing user connectivity to critical host applications and data.
Host On-Demand supports emulation for common terminal types, communications protocols, communications gateways, and printers, including the following:
You can use the Java component-based Host Access Toolkit to create customized e-business applications. This Toolkit contains a rich set of Java libraries and application programming interfaces: Host Access Class Library (HACL), Host Access Beans for Java, and Java 2 Enterprise Edition (J2EE) connectors. Host On-Demand also includes Database On-Demand, which provides an interface for sending Structured Query Language (SQL) queries to IBM DB2 databases hosted on IBM System i5 systems.
The following figure and explanation show how a Host On-Demand system works. Host On-Demand is a client/server system. Host On-Demand clients are Java applets that are downloaded from the Web server to a Web browser on a remote computer.
Step 1. The user opens a browser and clicks a hyperlink.
Step 2. IBM Rational Host On-Demand applet downloads to the client workstation.
Step 3. When the applet is downloaded, IBM Rational Host On-Demand connects directly to any Telnet server to access host applications.
Session information is configured in the HTML file or Host On-Demand configuration server. For more information about the configuration server, see Planning for deployment.
Host On-Demand client applets can be run as download clients, Web Start clients, or cached clients. Download clients are downloaded from the Web server every time they are used. Cached client and Web Start clients are downloaded from the Web server and stored on the client computer. After the initial download, the cached client is loaded from the local machine. The cached client checks the Host On-Demand server for new versions of the client and automatically downloads the updated version.
Host On-Demand includes the following administrative components:
In addition, a number of predefined clients are also supplied with Host On-Demand to demonstrate Host On-Demand's client functions for users and administrators (for example, emulation, Database On-Demand, cached client removal, and problem determination utilities).
You can reduce maintenance costs and increase your return on investment by installing Host On-Demand on a Web server, eliminating the need to manage individual user desktops.
Since the applets reside on a server and are downloaded to Web browsers when needed, you no longer have to schedule maintenance and upgrades. Upgrade the software on the server and users can receive the upgrade the next time they access the client applet.
Administrators can centrally define and control all session configuration information available to their users, including connection options, security features, macro definitions, keyboard specifications, and color mappings. Furthermore, administrators have full control over which fields the user can or cannot modify, and can choose where user updates should be stored.
With Host On-Demand, the client applet contains the emulation functionality. With the emulator residing on the client, the middle-tier server, such as IBM Communications Server or a third-party SNA server, can be eliminated. Any performance and security issues introduced with this intermediary piece will also be removed. Once the applet is served to the client, it is easy to connect directly to any standard Telnet server that provides the best access to the required data. You can access many host sessions concurrently. By eliminating the need for a middle-tier server, Host On-Demand also minimizes capacity restrictions. To see how this works, refer to Figure 1.
The browser-based access of Host On-Demand gives you a simple way to centrally manage and deploy critical host applications and data. Host On-Demand uses the power of Java technology to open the doors to your host system whenever you need it, wherever you need it, directly from your browser. Just click on a hyperlink to launch the Host On-Demand Java applet. This Web-to-host connectivity solution provides secure Web-browser access to host applications and system data through Java-based emulation, so you can take existing host applications to the Web without programming. Because Host On-Demand is Java-based, its interface has the same look-and-feel across various types of operating environments.
Host On-Demand servers and clients are supported on a wide variety of platforms and can be used over any TCP/IP network. This gives you a great deal of flexibility in setting up your system and enables Host On-Demand to be deployed in your computing environment without having to purchase new hardware.
Host On-Demand is compatible with browsers that support Java 2 standards. In addition, some new features of Host On-Demand take advantage of capabilities offered only by Java 2.
Support for Internet Protocol Version 6 requires Java 1.4 or higher. However, Host On-Demand Version 11 supports Java 1.5 or higher.
An Internet Protocol is a protocol used to route data from its source to its destination through an Internet environment. An IP is an intermediary between higher protocol layers and the physical network.
Internet Protocol Version 6 is the replacement for Internet Protocol Version 4. Internal Protocol Version 6 expands the number of available IP addresses and makes improvements in routing and network configuration. Both Internet Protocol Version 6 and Internet Protocol Version 4 were designed by the Internet Engineering Task Force (IETF).
Most of the Internet currently uses Internet Protocol Version 4. Internet Protocol Version 6 is expected to replace Internet Protocol Version 4 over a period of years.
![]() |
The Host On-Demand server also supports Internet Protocol Version 6 for the Redirector. For more information, refer to Redirector support for IPv6. |
Host On-Demand is available in 23 languages, including double-byte character set (DBCS) languages. Support for the European currency symbol, as well as keyboard and code page support for many more languages such as Arabic, Hebrew and Thai, is also provided. All language versions are available on the same media, and multiple language versions can be accessed concurrently.
Using Transport Layer Security (TLS) version 1.0 and Secure Sockets Layer (SSL) Version 3.0, Host On-Demand extends secure host data access across intranets, extranets, and the Internet. Mobile workers access a secure Web site, receive authentication and establish communication with a secure enterprise host. With client and server certificate support, Host On-Demand can present a digital certificate (X.509, Version 3) to the Telnet server - such as IBM Communications Server for Windows NT Version 6 or later, or IBM Communications Server for z/OS - for authentication.
Host On-Demand can also be configured for use in environments that include firewalls. Firewall ports need to be opened for the functions defined in your Host On-Demand session definitions. For more information, refer to Using Host On-Demand with a firewall.
Host On-Demand includes a Deployment Wizard that enables you to create custom HTML files. These files enable you to tailor the content of the client and the function necessary to meet the needs of specific groups of users. For more information about the Deployment Wizard, refer to Configuring Host On-Demand emulator clients.
Host On-Demand includes the Java component-based Host Access Toolkit for creating customized e-business applications. This Toolkit contains a rich set of Java libraries and application programming interfaces, including the Host Access Class Library (HACL), Host Access Beans for Java, and Java 2 Enterprise Edition (J2EE) connectors.
HACL provides a non-visual API for interacting with back-end host machines running applications originally designed for human interaction. Host applications rely on readable character presentation, formatted fields, color-coding, and keyboard responses. HACL provides specialized classes for functionalities needed to mimic traditional interaction with a series of host screen presentations (green screens). HACL contains no GUI (visible component) classes. For example, a Java program could be running on a mainframe as a secondary application. The secondary application program interacts first with another mainframe running a CICS data application, and then with a client browser through dynamically generated HTML pages. The secondary application interprets client inputs into simulated terminal actions which are sent to the CICS machine using the HACL API. The response screens from the CICS machine are captured using HACL APIs, converted into dynamic HTML pages, and sent back to the client.
Host On-Demand J2EE Connector provides a set of Resource adapters that communicate to 3270, 5250, CICS, and VT hosts. These resource adapters are deployed to a conforming application server, such as IBM WebSphere Application Server. The users can write Web applications using the APIs provided in Host On-Demand J2EE Connector via WebSphere Studio Application Developer Integration Edition.
Programmable Host On-Demand is a set of Java APIs that allows developers to integrate various pieces of the Host On-Demand client code, such as terminals, menus, and toolbars, into their own custom Java applications and applets. The API gives the developer complete control over the Host On-Demand desktop (what the user sees) without starting with the Host Access Java Beans found in the Toolkit. The underlying Host On-Demand code handles all the "wiring" of the various components, including saving user preferences, such as macros, keyboard remappings, and color remappings, to the local file system for future use. The developer must only determine the layout of the Host On-Demand desktop. For more information, refer to the Programmable Host On-Demand Reference .
In addition to the application programming interfaces (APIs) provided with the Host Access Toolkit, Host On-Demand provides specialized public APIs that provide support for embedding host sessions in Web pages using JavaScript. These JavaScript-based APIs help application developers manage host sessions and text-based interactions with host sessions and are available through the Host On-Demand Session Manager. Refer to the Session Manager API Reference for more information.
Host On-Demand can run as a portlet on Portal Server, a component of WebSphere Portal. Portal Server has sophisticated desktop management and security features that offer administrators more control over user access rights and users control over the appearance and arrangement of the portal desktop.
Administrators can create customized Host On-Demand portlets quickly and easily using the Deployment Wizard and then load them directly into Portal Server.
Database On-Demand is included with Host On-Demand to provide access to DB2 information stored on IBM System i5 servers using a Java Database Connectivity (JDBC) driver. Database On-Demand is a Java applet that allows you to perform Structured Query Language (SQL) requests to IBM System i5 databases through a JDBC driver. Database On-Demand is a separate applet from the Host On-Demand applet and is started by a separate HTML file. You can also use the Data transfer support from within an emulator session to perform SQL requests if you need both terminal emulation and support for SQL queries.
For the most recent information about Host On-Demand Version 11, see the product readme file.
For up-to-date product information, go to the Host On-Demand Web site at http://www.ibm.com/software/webservers/hostondemand.
For the latest technical hints and tips for Host On-Demand, go to the Host On-Demand Hints and Tips site.
To subscribe to the Software Support Bulletin, go to http://www.ibm.com/software/network/support.
The following functions and enhancements have been added to Host On-Demand Version 11:
This feature provides users the opportunity to view or go through the screens which they have previously navigated, which is particularly important for Host On-Demand 3270 and 5250 sessions, which are screen-based. The screen history feature also allows the users to use any data from previously navigated screens on the current screen. For example, if you need data from the first screen and are currently in the 10th screen, you can navigate through the screen history and retrieve the data. You can select from two flavors of the Screen History feature: Traditional and Simple.
Host On-Demand Version 11 provides several new types of enhanced hot spot capabilities along with the option to make each hot spot 3D. URL hot spots is active by default, but you must activate the others (Mailto, Function/Number, Execute macro/script, and Point-and-Select Commands) before you can use them. You must use a mouse for hot spots because they provide a way of performing functions with a mouse rather than with keys.
This new feature provides users the capability to search text in their current display session. Under this new feature, users can enable the Search Text Panel from the View menu similar to menu items such as Keypad, Macro Manager, and the like. This panel contains a text field, Next and Previous buttons, Ignore Case and Wrap Search check boxes.
For Virtual Terminal sessions, this panel has an extra option, the Search History check box. Text found on the session screen will be highlighted using a yellow rectangle. This feature would be available for 3270, 5250 and Virtual Terminal Display sessions. However, Virtual Terminal sessions do not support fixed font sessions.
Host On-Demand Version 11 provides an option for quickly starting a new session from the current session. To start a new session using the Quick Connect feature, you have the option of copying the reference of the current icon object associated with the current session and cloning this object. Specifying the hostname is mandatory. You can select this feature for FTP sessions also.
The new scratch pad feature provides a text editor in the terminal window, which helps you write notes and get text from the terminal screen on demand. The Scratch Pad text editor provides an option to save its contents to a file. You have the option to send selected text from the terminal screen to the scratch pad.
In the latest release of Host On-Demand, the SSH server sends an SSH Banner message at any time after the authentication protocol starts and before authentication is successful. This message contains text to be displayed to the client user before a user attempts authentication. The SSH banner displays on the terminal screen. The ssh.properties dialog provides an option to enable or disable the banner.
With this new feature in Host On-Demand Version 11, administrators can add an image that will be displayed on the session screen as a watermark. The data on the screen displays in its configured settings (text colors, size, and the like). The watermark overlays the screen data in such a way that the user can continue on the terminal screen as usual. This allows an administrator to customize the display session by embedding a watermark in addition to enhancing the visual appeal. This feature also provides the user the option to select an image that will be used to display on the terminal in the client machine and change the opacity of the watermark so that the screen data remains clearly visible.
The Host On-Demand Container for Lotus Expeditor provides access to host applications from within a composite application. A host application is a series of screens that use landmark expressions to identify these screens. The Host On-Demand Container provides the means to publish and receive information from a region of the screen.
Host On-Demand, starting with Version 11 onward, supports the Deployment Wizard for Linux on all supported platforms of Linux flavors capable of displaying the user interface.
This new function allows the user to copy data from the session screen in the form of a table. The position of the fields on the screen determines the makeup of the table. Unlike the already available Copy as Table function in which the data is divided into columns based on the space and characters displaying on the screen, this enhancement separates data into columns based on the field positions on the display session.
The JIS2004 support can now be enabled by selecting the existing host code pages 1390 Japanese (Katakana Unicode Extended) and 1399 Japanese (Latin Unicode Extended).
Host On-Demand Version 11 offers the Copy SO/SI as space option into the Cut/Copy tab of the Edit window. The Copy SO/SI as space option would be available only in the 3270/5250 DBCS session and unavailable in the SBCS/VT session.
This new feature offers multiple captured screens for Print Screen in one page.
Host On-Demand Version 11 provides the option for the Host On-Demand Admin and/or Clients to enable/disable Contention Resolution for 3270 Enhanced Display Session.
Menu items in Host On-Demand Version 11 have been reordered based on groups and submenu items accordingly. For example, in the Edit menu, the Copy Append and Copy as Table, have been merged under the Copy Special sub-menu item. This reordered menu provides a more logical grouping of tasks for users.
For updates to this information, refer to the Readme.
For a complete list of z/OS requirements, see the Program Directory.
Server operating system |
Recent cumulative service is recommended. Refer to the IBM System i5 Support, Recommended fixes Web site for service information. Unicode support using Coded Character Set Identifiers (CCSIDs) requires V5R2 with the following PTFs:
|
Disk space | 363 MB for an English-only installation. Add 4 to 8 MB for each additional national language to be installed. |
Memory | 256 MB memory or more. Refer to the IBM System i5 Performance Capabilities Reference Web page for additional information about the impact of additional memory and Java performance |
Supported Web servers |
|
Supported Web Application Servers |
|
Java | Toolbox for Java
Java Developer's Kit Version 1.5 |
All other requirements | TCP/IP Connectivity Utilities for IBM System
i5
QShell Interpreter |
Server operating systems |
|
Disk space | 363 MB for an English-only installation. Add 4 to 8 MB for each additional national language to be installed. |
Supported Web servers |
|
Supported Web Application Servers |
|
Java | Installed with Host On-Demand |
Server operating system |
|
Disk space (installp image) | 363 MB for an English-only installation. Add 4 to 8 MB for each additional national language to be installed (including the additional security files). |
Supported Web servers |
|
Supported Web Application Servers |
|
C/C++ Runtime Libraries |
C/C++ runtime libraries are available for download at ftp://www7b.boulder.ibm.com/aix /fixes/byCompID/5765F5600/. |
Java | Installed with Host On-Demand |
Server operating system |
|
Disk space | 363 MB for an English-only installation. Add 4 to 8 MB for each additional national language to be installed. |
Supported Web servers |
|
Supported Web Application Servers |
|
Java | Installed with Host On-Demand |
Server operating system |
|
Disk space | 363 MB for an English-only installation. Add 4 to 8 MB for each additional national language to be installed. |
Supported Web servers |
|
Supported Web Application Servers |
|
Java | Installed with Host On-Demand |
Server operating systems |
|
Disk space | 363 MB for an English-only installation. Add 4 to 8 MB for each additional national language to be installed. |
Supported Web servers |
|
Supported Web Application Servers |
|
Java | Installed with Host On-Demand |
You must have the correct korn shell in order to run the Host On-Demand Service Manager. For Red Hat, install the pdksh rpm package on the Red Hat machine. For all other flavors of Linux, change the first line of your_install_directory/lib/samples/NCServiceManager/NCServiceManager-UNIX from #!/bin/ksh to #!/bin/sh, where your_install_directory is your Host On-Demand installation directory.
IBM Rational Host On-Demand Version 11 does not support OS/2.
The Host On-Demand server can optionally use the lightweight directory access protocol (LDAP) as a data store for user and group information. Host On-Demand supports the following LDAP servers:
For more information on IBM's LDAP Directory solution and to download a complimentary evaluation kit, go to http://www.software.ibm.com/network/directory/
For instructions on using LDAP with Host On-Demand, see Configuring Host On-Demand Server to use LDAP.
Host On-Demand supports the Rational Application Developer for WebSphere Software Version 7.0 and 7.5.
For updates to client requirements, refer to the Readme, readme.html.
Host On-Demand clients are supported on the following operating systems:
![]() |
Host On-Demand supports a local client on Windows 2000, Windows 2003, Windows Vista and Windows XP. |
For the most up-to-date list of supported Web browsers and Java 2 plug-ins, see the Readme and the Host On-Demand Web site.
The supported browsers run either a Host On-Demand local client (that is, a download client or cached client downloaded to the workstation from a Host On-Demand server, see Using Host On-Demand emulator clients) or a Host On-Demand locally installed client (see Using locally installed clients).
Host On-Demand supports the following Java 2-enabled browsers:
A Java-2 enabled browser requires a Java 2 plug-in. Supported Java 2 plug-ins include Sun, IBM, and HP Java 1.5.0 and above.
For more information about Java 2-enabled browsers and Java 2 plug-ins, refer to Planning for Java 2 on the client.
Host On-Demand provides access to host applications from a Web browser. The browser downloads the Host On-Demand Java applet from the Web server and then connects to any Telnet server to access host applications. The Host On-Demand applet needs configuration information to determine which host to connect to and other host session properties. This configuration information can be provided to the Host On-Demand applet from an HTML file that is used to launch Host On-Demand or by the Host On-Demand configuration server. The configuration server is a part of Host On-Demand that centrally stores session configuration information and user preferences by user and group IDs. Users then access session information and user preferences by contacting the configuration server. The configuration server is managed through the administration client. For information on configuring the Host On-Demand configuration server, see the online help.
You can create custom client HTML files using the Deployment Wizard. When creating these HTML files, you can choose from three different configuration models to specify how session configuration information and user preferences are defined and managed: the HTML-based model, the configuration server-based model, and the combined model.
These models are described below. For detailed information on each model and benefits and limitations to using each model, see the online help.
If you choose the HTML-based model, all host session configuration information is contained in the HTML file itself, and nothing more is needed to define host sessions. Therefore, you are not required to use the configuration server to specify sessions, which means you do not have to open up a port on your firewall. If you allow users to save changes to the host session configuration information, their changes are stored on the local file system where the browser is running.
This option of defining configuration information in the HTML files is only available in clients that are created using the Deployment Wizard.
In the configuration server-based model, host session information is maintained on the configuration server using the Administration client, and the information is defined using a user and group structure. By default, the configuration server stores its data directly on the Host On-Demand server machine, though it can be configured to use LDAP instead. Users access their configurations using either custom HTML files created in the Deployment Wizard or by using one of several HTML files that are provided as part of Host On-Demand. User IDs are defined in the configuration server, and in most cases the user needs to log on to the Host On-Demand server before viewing his sessions. If administrators allow users to save changes, user preferences are stored in the configuration server by user ID. Because their customizations are saved on the configuration server, this model may be the best choice if users need to access their sessions from multiple machines.
By default, the Web browser communicates directly to the configuration server. If you communicate through a firewall, you need to open the configuration server's port on the firewall. Alternatively, you can use the configuration servlet to eliminate the need to open the configuration server's port on the firewall. The Web browser connects to the configuration servlet over an HTTP or HTTPS connection and the configuration servlet then interacts with the configuration server. See Configuring the configuration servlet for more information about using the configuration servlet.
Host On-Demand supports a combined model, where the host session information is defined in the configuration server (like the configuration server-based model) and user updates are saved on the user's machine (like the HTML-based model). In addition, like the HTML-based model, users of the combined model do not need to log on to the Host On-Demand server to view their sessions.
Additionally, for client deployment considerations, you need to decide whether to use cached, download, or Web Start clients (see Using Host On-Demand emulator clients) and which version of Java to use (see Planning for Java 2 on the client).
This chapter provides detailed information related to running the Host On-Demand client on a Java 2-enabled browser.
The following improvements bring the Java 2 cached client up to the same level of user-friendliness and flexibility as the Java 1 cached client. With the Java 2 cached client, you can now do the following:
Almost all Host On-Demand Java 2 cached clients support these improvements. The Java Web Start client also supports these improvements.
The following types of Java 2 cached clients do not support the improvements to the Java 2 cached client:
Using a Java 2-enabled browser with a Java 2 plug-in, you can take advantage of the following advanced features offered by the Host On-Demand client. For more information on Java 2-enabled browsers, refer to Browsers and Java 2 plug-ins.
Host On-Demand Mac OS X emulator and database clients support Safari 1.0, Safari 2.0, Safari 3.2.2, Firefox, and the Mac version of Internet Explorer. Host On-Demand does not support the administration clients on Mac OS X. If your users use Safari 1.0, they should upgrade to JRE 1.4.1, available at http://www.apple.com. However, Host On-Demand Version 11 supports Java 1.5 or higher.
The Duplicate Key Support feature requires a Java Plug-in of 1.4.2 or newer on Macintosh clients. However, Host On-Demand Version 11 supports Java 1.5 or higher.
This section discusses a number of client limitations to be aware of with Java 2.
The following sections discuss the limitations in downloading a client with Java 2.
With the Java 2 download client, a user cannot download a Host On-Demand client component that is not in the original preload list. Consequently, you must specify all the components that your users might require in the preload list.
This limitation is caused by a conflict between the method used by a download client to download components not on the preload list and security restrictions imposed by the Java 2 plug-in.
With Java 2, the default download client HTML files (HOD_xx.html, where xx is the two-letter language suffix) do not contain the following client components:
IBM removed these less frequently used components from the preload list of the Java 2 default download HTML files to shorten download time. However, with the Java 2 download client, any component not in the preload list cannot be downloaded later.
If you want some or all of these components to be in the preload list, perform one of the following actions:
Mac OS X does not support the Java 2 cached client improvements described in Improvements to the cached client for Java 2. For more information, refer to Cached client support for Mac OS X (Java 2 clients only).
With a Java 2-enabled browser, the Host On-Demand client starts a little more slowly (5 to 15 seconds slower, depending on the workstation type). The delay is caused by the system loading the Java 2 plug-in.
Also, with a Java 2-enabled browser, a host session on the Host On-Demand client desktop can take a little longer to start.
If you are using a Sun Java 2 plug-in and Hindi characters are not displayed correctly, make sure your Sun JRE level is the latest.
If a user runs a customer-supplied applet (that is, an applet written by your company or a third party) with a session (such as 3270 Display) launched from a Java 2 Host On-Demand client, and if this applet requires any Java 2 permissions, then you must take one of the following actions to meet the security requirements of Java 2:
If you do not meet the security requirements of Java 2, the applet silently fails.
Restricted users do not have the authority to install the Java 2 plug-in. A user with administrative authority must install the Java 2 plug-in.
This section discusses issues involved in using Java 2-enabled browsers and Java 2 plug-ins.
A Java 2-enabled browser does not have a JVM included with it. It can display HTML files on its own, but it needs a separate Java 2 plug-in installed to launch a Java applet such as the Host On-Demand client. Examples of Java 2-enabled browsers are Firefox and Microsoft Internet Explorer with the Java 2 plug-in installed.
For a list of browsers and Java 2 plug-ins supported by Host On-Demand clients, refer to Supported browsers and Java 2 plug-ins.
Users with client workstations running Windows can download the IBM Java 2 plug-in from any Host On-Demand server. See Obtaining a Java 2 plug-in for your clients.
As vendors of Java 2 plug-ins such as Sun, IBM, and Hewlett-Packard publish new versions of their Java 2 plug-ins, and as IBM extends Host On-Demand to support these new versions, IBM will announce support of the new versions on the Host On-Demand Web site at: http://www.ibm.com/software/webservers/hostondemand.
When a Java 2 plug-in is properly installed and configured on a Windows client workstation, Microsoft Internet Explorer will function as a Java 2-enabled browser, depending on how Host On-Demand chooses to launch the client.
To run a Java applet on Firefox, you must install a Java 2 plug-in.
Consequently, Host On-Demand expects you to configure the Java 2 plug-in so that it is the default Java Runtime for Firefox. For instructions on how to check or change this setting, refer to the Setting the default Java Runtime for a Java 2-enabled browser topic in the online help.
Unlike Internet Explorer, the Firefox browser itself does not have a setting for changing the default JVM. You need only to verify that the Java 2 plug-in's setting is correct.
Not all Java plug-ins have this setting. If the plug-in does not provide a way to change this setting, then the default configuration is correct.
Starting with Host On-Demand Version 11, only Java 2 clients are supported.
On all supported platforms, the Host On-Demand server includes a downloadable install image of the IBM Java 2 plug-in for the Microsoft Windows platform. The plug-in is called the IBM 32-bit Runtime Environment for Java 2.
Consequently, any client running on a supported Windows platform can attach to a Host On-Demand server, download the install image, and install the IBM Java 2 JRE. For instructions see Downloading and installing the IBM Java 2 plug-in for the Microsoft Windows platform in the online help.
For the Sun Java 2 plug-ins, see the Sun Microsystems Web site at http://java.sun.com.
The Java Plug-in Control Panel is launched differently depending on the client platform and on the vendor of the plug-in. For more information, refer to Launching the Java 2 Plug-in Control Panel in the online help.
Whether you are implementing Host On-Demand purely within your corporate network, or you are using it to provide access to your host systems over the Internet, security is a concern. This chapter provides an overview of Host On-Demand security.
The TLS and SSL security protocols are very similar; in fact, TLS is based on the SSL protocol. TLS differs from SSL mainly in the initial handshake protocol for establishing client/server authentication and encryption. It is also more extensible than SSL. Although they cannot interoperate, TLS provides a mechanism by which a TLS 1.0 implementation can revert to SSL 3.0. For detailed information on TLS, see the description of The TLS Protocol Version 1.0 at http://www.ietf.org/rfc/rfc2246.txt.
The TLS protocol uses public-key and symmetric-key cryptographic technology. Public-key cryptography uses a pair of keys: a public key and a private key. Information encrypted with one key can be decrypted only with the other key. For example, information encrypted with the public key can be decrypted only with the private key. Each server's public key is published, and the private key is kept secret. To send a secure message to the server, the client encrypts the message by using the server's public key. When the server receives the message, it decrypts the message with its private key.
Symmetric-key cryptography uses the same key to encrypt and decrypt messages. The client randomly generates a symmetric key to be used for encrypting all session data. The key is then encrypted with the server's public key and sent to the server.
TLS provides three basic security services:
![]() |
You can also use secure HTTP (HTTPS) to ensure that a client's security information is not compromised as it is downloaded from a server. |
Security is controlled by digital certificates that act as electronic ID cards. The purpose of a certificate is to assure a program or a user that it is safe to allow the proposed connection and, if encryption is involved, to provide the necessary encryption/decryption keys. They are usually issued by Certificate Authorities (CAs), which are organizations that are trusted by the industry as a whole and whose business is the issuing of Internet certificates. A CA's certificate, which is also known as a root certificate, includes (among other things) the CA's signature and a validity period.
Encryption and authentication are performed by means of a pair of keys, one public, one private. The public key is embedded into a certificate, known as a site or server certificate. The certificate contains several items of information, including the name of the Certificate Authority (CA) that issued the certificate, the name and public key of the server or client, the CA's signature, and the date and serial number of the certificate. The private key is created when you create a self-signed certificate or a CA certificate request and is used to decrypt messages from clients.
A TLS or SSL session is established in the following sequence:
There are three areas where you can configure security for Host On-Demand: session security, Web server security, and configuration security.
Host On-Demand can use two protocols to provide security for emulator and FTP sessions.
Support is provided for the following:
For Host On-Demand, you can use a CA's certificate, but you can also create your own self-signed certificate, as described in the Using a self-signed certificate topic in the online help.
A graphical Certificate Management utility (available on Windows and AIX platforms) is provided to:
IKEYCMD is a tool, in addition to the Certificate Management utility, that you can use to manage keys, certificates, and certificate requests. IKEYCMD is functionally similar to Certificate Management and is meant to run from the command line without a graphical interface. For more information, refer to Appendix B. Using the IKEYCMD command-line interface.
To support TLS and SSL services, Host On-Demand uses four databases:
The CustomizedCAs.p12 file is a newer version of the CustomizedCAs.class file, which you may have created with an earlier release of Host On-Demand. The CustomizedCAs.class file supports Host On-Demand Version 7 and earlier clients, and is located in your publish directory by default. If you are running Windows or AIX, when you upgrade to version 10, the Host On-Demand installation automatically detects the CustomizedCAs.class file, creates the new CustomizedCAs.p12 file, and places it in the publish directory. Both files remain in your publish directory and are available to clients of different versions. If you have an separate user publish directory and not the default publish directory, the Host On-Demand installation will not be able to detect the CustomizedCAs.class file and you will need to run the migration tool manually on the command line. Refer to Migrating from CustomizedCAs.class to CustomizedCAs.p12 in "Upgrading from earlier versions of Host On-Demand" for more information.
If you create the CustomizedCAs.p12 file for the first time using the Host On-Demand Certificate Management utility (IKEYMAN), you will also want to have the older CustomizedCAs.class file in your publish directory so that older clients can still operate with the new server. Also, when you subsequently update the CustomizedCAs.p12 file, you will want to make sure these changes are picked up by the CustomizedCAs.class file. For Windows platforms, if these files are in the default publish directory, c:\Program Files\IBM\HostOnDemand\HOD, each time you open IKEYMAN to update the CustomizedCAs.p12 file and then close IKEYMAN, the CustomizedCAs.class file is automatically updated along with the CustomizedCAs.p12 file. If these files are not in the default publish directory, you need to manually run the reverse-migration tool from your publish directory using the following command. The command appears on three lines, but you should type it on one line.
..\hod_jre\jre\bin\java -cp ..\lib\sm.zip; com.ibm.eNetwork.HOD.convert.CVT2SSLIGHT CustomizedCAs.p12 hod CustomizedCAs.class
On AIX, for the CustomizedCAs.class file to pick up the changes you make to the CustomizedCAs.p12 file, you must run this reverse-migration tool manually from your publish directory using the following command. The command appears on three lines, but you should type it on one line.
../hod_jre/jre/bin/java -cp ../lib/sm.zip com.ibm.eNetwork.HOD.convert.CVT2SSLIGHT CustomizedCAs.p12 hod CustomizedCAs.class
The CustomizedCAs.class is a Java class file that contains the certificates of unknown CAs and self-signed certificates that are not in the WellKnownTrusted list. If you use a self-signed certificate or a certificate from an unknown authority (CA), you must update the CustomizedCAs.class file. However, note that you can no longer create or update the CustomizedCAs.class file using the Certificate Management utility on Windows or AIX platforms. In Host On-Demand Versions 9 or later, you can only create a newer version of this file called CustomizedCAs.p12. All clients still support the older format, however. For more information, refer to the description of CustomizedCAs.p12 above.
WellKnownTrustedCAs.class/WellKnownTrustedCAs.p12 and CustomizedCAs.p12 and/or CustomizedCAs.class must be present in the Host On-Demand publish directory. The Host On-Demand client uses these files to trust the server's certificate during the TLS or SSL handshake.
When you select the TLS or SSL protocol for the Host On-Demand client, a basic TLS or SSL session is established. During the TLS or SSL negotiation process, the server presents its certificate to the client. With basic TLS or SSL enablement, the certificate must be signed by an authority that the client trusts. The client checks WellKnownTrustedCAs.class/WellKnownTrustedCAs.p12 first, followed by the CustomizedCAs.p12 or the CustomizedCAs.class. The client rejects the session if it does not find the signer in these files. If the client finds the signer in these files, the session is established. This is basic Server Authentication. Host On-Demand allows you to configure a more enhanced form of Server Authentication in its client configuration. Refer to the following section for more information.
![]() |
Starting with Host On-Demand V9, Web Express Logon offers a type of logon automation that uses client-side certificates. This model is called certificate-based Web Express Logon and is significantly different than Certificate Express Logon. With Certificate Express Logon, client certificates are used to authenticate users to an Express Logon-enabled TN3270 server that is configured to automate the login process. With certificate-based Web Express Logon, however, client certificates are used to authenticate users to a Web server or a network security application, and the login process is automated by a plug-in and a macro. For more information, refer to the Web Express Logon Reference. |
The Telnet server must support TLS-based Telnet security (as described in the IETF Internet-Draft TLS-based Telnet Security, available at http://www.watersprings.org/pub/id/draft-ietf-tn3270e-telnet-tls-06.txt) for the Host On-Demand clients to use Telnet-negotiated security. The Communications Server for z/OS supports TLS-based Telnet security. Communications Server for z/OS documentation refers to Telnet-negotiated security as "negotiable SSL."
For more information regarding Telnet-negotiated security, see the Telnet-negotiated security overview in the online help. Refer to your Telnet server's documentation for more information about configuring TLS or SSL on the Telnet server, and refer to the Security topic in the online help for more information about configuring a client to connect to a secure Telnet server.
The FTP session's security properties are independent of the emulator session's security properties. For an integrated FTP session, you must configure FTP security information using the new Security tab in FTP session properties. If you configure an emulator session to be secure and the File Transfer Type is set to FTP, the FTP session will not be secured automatically. In this situation, the following message appears when you click the OK button: If a secure file transfer session is desired, configure the security information in File Transfer Defaults.
The TLS based secure FTP function is supported by z/OS V1R2 or later.
Refer to the following examples as situations where you might want to use session security:
You can configure your Web server to use TLS or SSL (HTTPS), so that the data stream from your Web server to your browser is encrypted. See your Web server documentation for more information about configuring your Web server for TLS or SSL. Once the client is loaded in a browser, however, it communicates directly with the host. You can configure Host On-Demand to provide TLS or SSL security to your host sessions. For more information, see Configuring TLS and SSL in the online help.
If you use the HTML model, your session configuration information will be encrypted if you use HTTPS. For all other models, you need to configure Host On-Demand to use the configuration servlet over HTTPS (after configuring your Web application server) to encrypt the session configuration instead of communicating directly with the configuration server. See Installing the configuration servlet in this guide for more information about installing the configuration servlet, and see configuring the configuration servlet in the online help for more information about configuring clients to use the configuration servlet.
The Secure Shell (SSH) is a set of protocols for implementing secure sessions over a non-secure network (such as a standard TCP/IP network). In order to use SSH, you must set up SSH server software on the host. Security features include the following:
Host On-Demand supports SSH as an option on the following session types:
The implementation of SSH in Host On-Demand is a subset of SSH Version 2. Host On-Demand also supports a subset of SSH Version 1.5 on VT Display Sessions. Host On-Demand does not support SSH Version 1.3. The following table summarizes this information:
Version of SSH | Supported by Host On-Demand |
---|---|
SSH Version 2.0 | Yes (subset) |
SSH Version 1.5 | Yes (subset, on VT Display sessions only) |
SSH Version 1.3 | no |
The following subsections describe for each protocol in SSH and the features that Host On-Demand supports, or the features that Host On-Demand does not support.
For the SSH Version 2 Transport Protocol, Host On-Demand supports the following algorithms. The same algorithms are supported for sending files (client to server) and receiving files (server to client).
Category | Algorithm supported |
---|---|
Compression: | none |
Encryption1: |
3des-cbc aes128-cbc |
Data Integrity: | hmac-sha1 |
Key Exchange: | diffie-hellman-group1-sha1 |
Public Key: | ssh-dss (same as DSA), ssh-rsa |
1 Host On-Demand always give priority to 3des-cbc over aes128-cbc. If you want to use aes128-cbc, 3des-cbc needs to be disabled on the server side. |
For the SSH Version 2 Authentication protocol Host On-Demand supports the following authentication methods:
Host On-Demand does not support the following features in the SSH Version 2 Connection protocol:
For the SSH Version 1.5 protocol, Host On-Demand supports following features:
The SSH Version 1.5 protocol is used on VT Display Sessions when the SSH server supports Version 1.5 protocol only. If the server supports both Version 1.5 and 2 protocols, the Version 2 protocol will be used.
For SSH support Host On-Demand requires the following configuration on the client workstation:
This section describes Host On-Demand's support of public-key, keyboard-interactive, and password authentications on the client when SSH Version 2 protocol is used. When SSH Version 1.5 protocol is used, password authentication is the only authentication method available.
Host On-Demand allows public-key, keyboard-interactive, and password authentication to be configured on the client at the same time. At run time, the following occurs:
The server configuration for public-key authentication differs depending on the vendor or source of the SSH support. Refer to the documentation for your SSH server software for information on how to configure the SSH server for the public-key authentication method.
Public key authentication for SSH requires that the server knows the public key of the client. Here is an overview of the method for generating this public key and making it available to the server with Host On-Demand. A detailed explanation of each step follows this overview:
The first step is to use the keytool utility in the JCE to generate a keystore containing a pair of keys for the client (a public key and a private key). To generate the keystore, invoke the keytool utility as follows:
keytool -genkey
For example, on a Windows platform you might type the following:
c:\program files\ibm\java14\jre\bin\keytool.exe -genkey
The keytool utility then prompts you for the following information:
When invoked with only the -genkey option, as above, the keytool utility generates the items listed below. These are the default values generated by the keytool utility and are also the default values expected by Host On-Demand configuration.
By default, the keytool utility generates this file in the directory named in the Java system property user.home. For example, for the Windows platform, the file would be generated in the following directory:
c:\Documents and Settings\username
where username is the user name.
To generate a keystore with a non-default filename, key alias, store password, and alias password, invoke the keytool utility with the following command. Note that the command appears in this document on two lines; however, you should type it all on one line.
keytool -genkey -keystore MyKeystoreFile -alias MyAlias -storepass MyKeystorePassword -keypass MyKeyPassword
Run the keytool utility with no options specified to see all the possible options.
The second step is to place the keystore file in the proper subdirectory on the client workstation. As mentioned above, the default file name is .keystore and the default subdirectory is the path stored in the user.home Java system property. In any case, you should use the same file name and path that you plan to specify in the session configuration.
The third step is to configure the Host On-Demand session parameters for SSH. As mentioned above two Host On-Demand session types support SSH:
You will need to specify the following information (or you can accept the default values):
For more information, refer to SSH configuration in the online help.
The fourth step is to run the Host On-Demand Export Public Key utility in order to export the public key to a plain-text file. This utility is not a stand-alone utility but rather is integrated with the session configuration. To run the utility, go to the SSH configuration panel in the session configuration, the same panel where you specified the path and file name for the keystore, and click Export Public Key. Follow the instructions to export the public key to a plain text file.
The fifth step is to transfer the plain text file to the host. You should use a secure method for transferring the plain text file to the host, such as one of the following:
To configure the client for public-key authentication, a keystore containing the client's public and private key information must be placed either:
The server configuration for keyboard-interactive authentication differs depending on the vendor or source of the SSH support. Refer to the documentation for your SSH server software for information on how to configure the SSH server for the keyboard-interactive authentication method.
You do not need to configure the client for keyboard-interactive authentication. The Host On-Demand client will look for whether or not keyboard-interactive authentication is configured on the server. If it is configured on the server, then Host On-Demand will prompt the user for keyboard input.
The server configuration for password authentication differs depending on the vendor or source of the SSH support. Refer to the documentation for your SSH server software for information on how to configure the SSH server for the password authentication method.
You do not need to configure the client for password authentication. The Host On-Demand client will look for the password in the session configuration information. If no password is found, then Host On-Demand will prompt the user for a password.
Both SSH and TLS/SSL provide secure sessions. The best protocol for you depends on the characteristics of the system that you support:
The Redirector is a service that runs on the Host On-Demand server and that allows a Host On-Demand client to communicate with a Telnet server by connecting to a Redirector port on the Host On-Demand server.
Normally, a Host On-Demand client:
However, when the Redirector is used, the Redirector acts as an intermediary between the client and the Telnet server. The client, instead of connecting directly to the Telnet server, connects to a Redirector port on the Host On-Demand server. The Redirector then sends to the Telnet server the data received from the client. When the Telnet server replies, the Redirector sends to the client the data received from the Telnet server. This process continues until the session ends.
If your Telnet server does not support TLS or SSL, and if you are running the Host On-Demand server on one of the operating systems on which the Redirector supports secure sessions (see Operating systems supported by the Redirector), then you can configure the Host On-Demand Redirector to provide TLS or SSL support.
![]() |
Many Telnet servers support TLS or SSL (for example, IBM Communications Servers on zSeries, IBM System i5, AIX, or NT). If your Telnet server supports TLS or SSL, we strongly recommend using your Telnet server. If your Telnet server does not support TLS or SSL, the Communications Server for AIX Redirector offers a more scalable alternative to the Host On-Demand Redirector. |
The Redirector acts as a transparent Telnet proxy that uses port remapping to connect the Host On-Demand server to other Telnet servers. Each defined server can configure a set of local-port numbers. Instead of connecting directly to the target Telnet server, a client connects to the Host On-Demand server and port number. The Redirector maps the local-port number to the host-port number of the target and makes a connection.
![]() |
The recommended solution for a Telnet proxy is to use Load Balancer, a feature of WebSphere Application Server's Edge Components, or a similar product that provides address translation as part of the overall firewall solution, instead of the Host On-Demand Redirector. |
Figure 5 illustrates how the Redirector sends the client data to the Telnet server and sends to the client the responding data from the Telnet server.
The Redirector can be configured in any one of the following four modes:
Before you use the Client-side, Server-side, or Both modes, you must create the HODServerKeyDb.kdb for the Redirector.
You can use the Pass-through mode when encryption by the Redirector is not necessary, either because the data stream does not need to be encrypted, or because the data stream is already encrypted between the client and the Telnet server. You must use the Pass-through mode if the Host On-Demand client is connecting through the Redirector to a host that requires client authentication or Express Logon.
Refer to Adding a host to the Redirector in the online help for more information.
For Redirector load capacity recommendations, refer to the Readme.
The Redirector now supports:
Not every Redirector mode is supported on every operating system. The next two subsections describe Redirector support in more detail. For more information on IPv4 and IPv6 see Support for Internet Protocol Version 6.
For operating systems that support IPv4 the Redirector supports the following:
Table 14 shows this information:
Operating system: | Pass-through: | Client-side: | Host-side: | Both: |
---|---|---|---|---|
Windows | Yes | Yes | Yes | Yes |
AIX | Yes | Yes | Yes | Yes |
Linux | Yes | Yes | Yes | Yes |
All other operating systems | Yes | No | No | No |
Table 15 shows the operating systems and the Redirector modes for which the Redirector supports Internet Protocol Version 6 (IPv6):
Operating system: | Pass-through: | Client-side: | Host-side: | Both: |
---|---|---|---|---|
Windows:
|
No | Yes | Yes | Yes |
Linux:
|
Yes | Yes | Yes | Yes |
AIX:
|
Yes | Yes | Yes | Yes |
If you are configuring Host On-Demand to go through a firewall, we recommend that the firewall administrator open only those ports required for the clients to function. Telnet ports allow TLS or SSL-encrypted session traffic.
If you are using the configuration server-based or combined models, the Host On-Demand configuration servlet allows Host On-Demand clients to communicate with the configuration server across either HTTP or HTTPS.
Host On-Demand clients connecting to a host system through open ports in the firewall should see Configuring firewall ports for details. Host On-Demand clients connecting to a host system through a Socks or HTTP proxy server should see Connecting to a host system through a proxy server for details.
If you are using the configuration server-based model or the combined model, your Host On-Demand clients will need to communicate with the configuration server. To allow this through a firewall, you will need to either open the Host On-Demand Service Manager port or use the Host On-Demand configuration servlet. The Service Manager listens on port 8999 by default. You can change this default to any other available port number. For details, refer to Changing the Service Manager port in the online help. The Host On-Demand configuration servlet allows Host On-Demand clients to communicate with the configuration server across either HTTP or HTTPS. Therefore, the Service Manager port does not need to be open on the firewall. (See Figure 4.) Refer to Installing the configuration servlet and Configuring the configuration servlet in the online help for details on using the configuration servlet.
If you are using the HTML-based model, there is no requirement for Host On-Demand clients to access the configuration server, and the Service Manager port does not need to be open on the firewall. The clients will still attempt to contact the configuration server for license counting but will fail silently if the Service Manager port is not open. If you want to prevent clients from making license counting requests, you can add a parameter Disable with a value of LUM in the Additional Parameters tree view on the Advanced Options window in the Deployment Wizard.
In addition to the Service Manager port, make sure the firewall administrator opens any ports that are being used for functions your clients use. For example, if you have a TLS or SSL session with the Redirector on port 5000, port 5000 must be open for Telnet traffic. The following table summarizes the ports that Host On-Demand can use.
Host On-Demand Function | Ports Used |
Display emulation (3270 and VT) and 3270 Printer emulation | 23 (Telnet), 80 (HTTP), or 443 (TLS or SSL) and 8999 (config server)3 |
5250 Display and Printer emulation | 23 (Telnet) or 992 1 (TLS or SSL) or 80 (HTTP) or 443 (TLS or SSL) and 8999 (config server) 3 |
3270 file transfer | 23 (Telnet), 80 (HTTP), or 443 (TLS or SSL) and 8999 (config server)3 |
5250 file transfer - savfile | 80 (HTTP), 8999 (config server)3, 21 (FTP)4, >1024 (FTP)4, 446 (drda)4, 449 (as-svrmap)4, 8470 (as-central)1 2 4, 8473 (as-file)1 4, 8475 (as-rmtcmd)1 4, and 8476 (as-signon)1 4 |
5250 file transfer - database | 80 (HTTP), 8999 (config server)3, 446 (drda)4, 449 (as-svrmap)4, 8470 (as-central)1 2 4, 8473 (as-file)1 4, 8475 (as-rmtcmd)1 4, and 8476 (as-signon)1 4 |
5250 file transfer - stream file | 80 (HTTP), 8999 (config server)1 2 4, 449 (as-svrmap)4, 8470 (as-central)1 2 4, 8473 (as-file)1 4, and 8476 (as-signon)1 4 |
FTP | 21 (FTP), 80 (HTTP), 8999 (config server)1 2 4, and >1024 (FTP)5 |
CICS | 2006 |
Database On-Demand | 80 (HTTP), 8999 (config server)3, 449 (as-svrmap)4, 8470 (as-central)1 2 4, 8471 (as-database)1 4, and 8476 (as-signon)1 4 |
License Use Management (LUM) | 8999 (config server) for default license use counting using the configuration server |
Host On-Demand clients | 23 (Telnet), 80 (HTTP), and 8999 (config server)3 |
Administration clients | 80 (HTTP) and 8999 (config server)3 |
SSH (the Secure Shell) | 22 |
Notes: | |
1 | You can change the port numbers with the command WRKSRVTBLE . The port numbers listed are the default values. |
2 | The port for as-central is used only if a codepage conversion table needs to be created dynamically (EBCDIC to/from Unicode). This is dependant on the JVM and the locale of the client. |
3 | You can change the config server port. Port 8999 is the default. |
4 | These ports do not need to be opened on the firewall if you are using IBM System i5 proxy server support. You will need to open the default proxy server port 3470. You can change this port. |
5 | In passive (PASV) mode, the FTP client initiates
both connections to the server, solving the problem of firewalls filtering
the incoming data port connection to the client from the server. When
opening a FTP connection, the client opens two random unprivileged
ports locally (N>1024 and N+1). The first port contacts the server
on port 21, but instead of then issuing a PORT command and allowing
the server to connect back to its data port, the client issues the
PASV command. As a result, the server then opens a random unprivileged
port (P>1024) and sends the PORT P command back to the client. The
client then initiates the connection from port N+1 to port P on the
server to transfer data.
From the server-side firewall's standpoint, to support passive mode FTP, you must open the following communications ports:
|
If you do not want to open port 8999 on the firewall, you can still allow users to access Host On-Demand. There are two options:
If you use the configuration server and it is separated from your Web browser by a firewall, you will either need to open the configuration server port on the firewall or run the Host On-Demand configuration servlet. The configuration servlet allows the browser to communicate with the configuration server across standard Web protocols, such as HTTP or HTTPS. (See Figure 4.)
Host On-Demand clients can use a proxy server to transparently access host systems from behind a firewall. Two types of proxy servers are supported:
Before you can connect to a host system through a proxy server, you must find out which protocol the proxy server supports. Decide whether you want to specify the proxy server settings through the Web browser or explicitly identify a proxy server for the session. If you decide to explicitly identify a proxy server, you must specify the protocol that the proxy server uses, the proxy server name and port number, and other information.
In general, if a Socks proxy server is available, configure Host On-Demand sessions to use it. Configure sessions to use an HTTP proxy server if that is the only type of proxy server supported at your site.
Many organizations use Socks proxy servers to protect computing resources behind a firewall. Socks is a protocol for TCP/IP-based network proxies. It allows applications on one side of a Socks proxy server to gain full access to hosts on the other side of the Socks proxy server without directly connecting to them. Proxy servers are generally used in conjunction with firewalls. Under the Socks protocol, a client that requests a connection to a host system through a firewall actually connects to a Socks proxy server. The Socks proxy server acts as an intermediary between the client and the host system. It authorizes communication requests, connects to the host on behalf of the client, and relays data between the two systems.
Host On-Demand supports both version 4 and version 5 of the Socks protocol.
The Java Virtual Machine (JVM) used in most Web browsers supports Socks version 4. A session can access either a Socks version 4 or version 5 proxy server, bypassing the proxy server settings in the Web browser. You can also have the session negotiate a Socks version 4 connection if the proxy server does not support version 5. For more information on Socks proxy server settings, refer to Proxy Server in the online help.
HTTP proxy servers handle HTTP requests through firewalls. They act as intermediaries between private local networks and the Internet. The HTTP proxy server is connected to both the local network and the Internet. Local users configure their browsers to pass HTTP requests through the HTTP proxy server by specifying the proxy server's IP address and TCP port number. The HTTP proxy server accepts these HTTP requests and forwards them to the actual Web servers specified by the URLs entered in the browser.
For Host On-Demand clients, HTTP proxy servers act as forwarding agents for connections to a host system. The HTTP proxy server opens a connection to the host system and sends data back and forth between the host system and the client. Although an HTTP proxy server usually closes a connection after servicing an HTTP request, Host On-Demand keeps the connection open for host traffic by using the HTTP Connect method (if it is enabled for the proxy server).
To have a session use a HTTP proxy server, you need to select HTTP proxy as the proxy type and specify the proxy server name and port number. For more information on HTTP proxy server settings, refer to Proxy Server in the online help.
If you have a network security application in place and you are using the configuration server-based model, you can select Web Express Logon in the Deployment Wizard to allow users to access hosts and host-based applications without providing an additional user ID and password. Entering the full URL of the Credential Mapper Server tells Host On-Demand where to locate the Credential Mapper Servlet, which processes the HTTPS request from the user, performs a lookup, and returns the user's credentials. The credentials are then used to perform a secure, automated Host On-Demand login.
If you use the configuration server-based model, you can configure your Host On-Demand users to be natively authenticated. This option allows users to log on to Host On-Demand using the same password as they would to log on to the operating system (Windows NT, AIX, or z/OS) where Host On-Demand is active. When a user logs on to Host On-Demand, their password is validated against the operating system password, rather than a separate Host On-Demand password. This gives the administrator a single point of control for password administration and the user a single password to remember.
Refer to Native Authentication in the online help for more information on enabling this option.
If your users are logged on to a Windows domain, this option (available with the configuration server-based model in the Deployment Wizard) automatically logs users on to Host On-Demand using their Windows user name. The Host On-Demand logon window does not appear and the Windows user name is used as the Host On-Demand user ID. If a Host On-Demand user ID does not already exist (matching the Windows user name), you can also choose to have a user ID automatically created in the specified Host On-Demand group.
Refer to Logon Type in the online help for more information about choosing how users access the Host On-Demand configuration server.
If you are in an environment that mandates or requires that your security components use Federal Information Processing Standards (FIPS)-certified components/modules, consider the following. For secure Telnet and FTP connections, Host On-Demand uses FIPS-compliant modules by default. If your environment requires you to connect to an IBM System i5 host for file transfer or data transfer, you must meet the following requirements:
When you have a secure connection to an IBM System i5 host and are accessing the file transfer capabilities, you will be asked to enter the path and the password for the JSSE Trust Store. If you are performing data transfer to an IBM System i5 host, you will also see additional fields for entering the path and password for the JSSE Trust Store.
Another way to enter the path and password is to use a Run Applet that is provided with Host On-Demand. To do this, take the following steps:
You only need to configure the JSSE Trust Store one time. It is a global setting that applies to all sessions. Once you have entered the values, they will persist until the browser is restarted.
In earlier versions of Host On-Demand, you could enable FIPS mode authentication through an HTML parameter. The current version of Host On-Demand provides a menu option to enable or disable the FIPS mode for each session. By default, FIPS mode is enabled for all the sessions.
Host On-Demand is provided in 23 languages. The session windows, configuration panels, help files, and the documentation have been translated. In addition, display, keyboard, and processing support is provided for Arabic, Hebrew, Thai, and Hindi. This support is fully explained in the online help.
All the translated versions are provided on the DVDs and on the zSeries tapes. When you install Host On-Demand on i5/OS, OS/400, Windows, AIX, Linux, Solaris, and HP-UX using the graphical installation program, you can choose which languages to install. On z/OS and Novell, all the languages are always installed.
![]() |
National language support is operating-system dependent, so the appropriate font and keyboard support for the language you want to use must be installed in the operating system. For example, if you want to use Korean as the host-session language but do not have the Korean font and keyboard support installed, you may not be able to display the correct characters. |
![]() |
DBCS cannot be used as the HTML file name. |
The languages into which Host On-Demand has been translated are listed below, along with the language suffixes you can use to load translated versions of the Host On-Demand clients. For example, IBM-supplied HTML pages have language extensions to identify different language installations and different language predefined HTML files, such as HOD_en.html for English.
Language | Language suffix |
Simplified Chinese | zh |
Traditional Chinese | zh_TW |
Czech | cs |
Danish | da |
Dutch | nl |
English | en |
Finnish | fi |
French | fr |
German | de |
Greek | el |
Hungarian | hu |
Italian | it |
Japanese | ja |
Korean | ko |
Norwegian | no |
Polish | pl |
Brazilian Portuguese | pt |
Portuguese | pt_PT |
Russian | ru |
Slovenian | sl |
Spanish | es |
Swedish | sv |
Turkish | tr |
Host On-Demand supports multiple code pages. You can specify these code pages on a session-by-session basis.
The code pages specified below are supported by the 3270 and 5250 emulators. You can select them in the Session Configuration window.
Country or region | Code page | Note |
Arabic Speaking | 420 | |
Austria | 273 | |
Austria (Euro) | 1141 | |
Belarus | 1025 | |
Belarus (Euro) | 1154 | |
Belgium | 037 | |
Belgium (Euro) | 1140 | |
Belgium (Old Code) | 274 | |
Bosnia/Herzegovina | 870 | |
Bosnia/Herzegovina (Euro) | 1153 | |
Brazil | 037 | |
Brazil (Euro) | 1140 | |
Brazil (Old) | 275 | |
Bulgaria | 1025 | |
Bulgaria (Euro) | 1154 | |
Canada | 037 | |
Canada (Euro) | 1140 | |
China (Simplified Chinese Extended) | 1388 | |
Croatia | 870 | |
Croatia (Euro) | 1153 | |
Czech Republic | 870 | |
Czech Republic (Euro) | 1153 | |
Denmark | 277 | |
Denmark (Euro) | 1142 | |
Estonia | 1122 | |
Estonia (Euro) | 1157 | |
Finland | 278 | |
Finland (Euro) | 1143 | |
France | 297 | |
France (Euro) | 1147 | |
FYR Macedonia | 1025 | |
FYR Macedonia (Euro) | 1154 | |
Germany | 273 | |
Germany (Euro) | 1141 | |
Greece | 875 | |
Hebrew (New Code) | 424 | |
Hebrew (Old Code) | 803 | |
Hindi | 1137 | 5250 display only |
Hungary | 870 | |
Hungary (Euro) | 1153 | |
Iceland | 871 | |
Iceland (Euro) | 1149 | |
Italy | 280 | |
Italy (Euro) | 1144 | |
Japan (Katakana) | 930 | |
Japan (Katakana Extended) | 930 | |
Japan (Katakana Unicode Extended) | 1390 | 3270 only |
Japan (Latin Extended) | 939 | |
Japan (Latin Unicode Extended) | 1399 | |
Kazakhstan (Euro) | 1166 | |
Korea (Euro) | 1364 | 3270 only |
Korea (Extended) | 933 | |
Latin America | 284 | |
Latin America (Euro) | 1145 | |
Latvia | 1112 | |
Latvia (Euro) | 1156 | |
Lithuania | 1112 | |
Lithuania (Euro) | 1156 | |
Multilingual | 500 | |
Multilingual ISO (Euro) | 924 | |
Multilingual (Euro) | 1148 | |
Netherlands | 037 | |
Netherlands (Euro) | 1140 | |
Norway | 277 | |
Norway (Euro) | 1142 | |
Open Edition | 1047 | |
Poland | 870 | |
Poland (Euro) | 1153 | |
Portugal | 037 | |
Portugal (Euro) | 1140 | |
Romania | 870 | |
Romania (Euro) | 1153 | |
Russia | 1025 | |
Russia (Euro) | 1154 | |
Serbia/Montenegro (Cyrillic) | 1025 | |
Serbia/Montenegro (Cyrillic; Euro) | 1154 | |
Slovakia | 870 | |
Slovakia (Euro) | 1153 | |
Slovenia | 870 | |
Slovenia (Euro) | 1153 | |
Spain | 284 | |
Spain (Euro) | 1145 | |
Sweden | 278 | |
Sweden (Euro) | 1143 | |
Taiwan (Traditional Chinese Extended) | 937 | |
Taiwan (Traditional Chinese Extended; Euro) | 1371 | |
Thai | 838 | |
Thai (Euro) | 1160 | |
Turkey | 1026 | |
Turkey (Euro) | 1155 | |
Ukraine | 1123 | |
Ukraine (Euro) | 1158 | |
United Kingdom | 285 | |
United Kingdom (Euro) | 1146 | |
United States | 037 | |
United States (Euro) | 1140 |
Notes:
Language | Code page |
Arabic | ASMO 708 and ASMO 449 |
British | 1101 |
DEC Greek | |
DEC Hebrew | |
DEC Multinational Replacement Character Set | 1100 |
DEC Technical | |
Dutch | 1102 |
Finnish | 1103 |
French | 1104 |
French Canadian | 1020 |
German | 1011 |
Hebrew NRCS | |
ISO Greek Supplemental (ISO Latin-7) | 813 |
ISO Hebrew Supplemental | |
ISO Latin-1 | 819 |
Italian | 1012 |
Norwegian/Danish | 1105 |
PC Danish/Norwegian | 865 |
PC International | 437 |
PC Multilingual | 850 |
PC Portugese | 860 |
PRC GBK | 936 |
PC Spanish | 220 |
Spanish | 1023 |
Swedish | 1106 |
Swiss | 1021 |
United States | 1100 |
Code page | Character set |
000 | Auto Detect (default) |
437 | Latin-1 |
813 | ISO Greek (8859_7) |
819 | ISO Latin 1 (8859_1) |
850 | Latin 1 |
852 | Latin 2 |
855 | Cyrillic |
856 | Hebrew |
857 | Latin 5 |
864 | Arabic |
866 | Cyrillic |
869 | Greek |
874 | Thai |
912 | ISO Latin 2 (8859_2) |
915 | ISO Cyrillic (8859_5) |
920 | ISO Latin 5 (8859_9) |
The JIS2004 support can now be enabled by selecting the existing host code pages 1390 Japanese (Katakana Unicode Extended) and 1399 Japanese (Latin Unicode Extended). The following features are supported:
Functions not included due to Unicode formats not currently supported in HOD:
For double-byte character set (DBCS) languages, you can use customized user-defined character (UDC) mapping in your session (3270, 5250, 3270 host print) instead of the default mapping. You can create a UDC translation table using the UDC mapping editor to store customized mapping for your session. For instructions for how to use the UDC mapping editor to change your character mapping, see Using the user-defined character (UDC) mapping editor in the online help.
See Unicode Support for i5/OS and OS/400.
This chapter discusses installing the following three Host On-Demand components:
![]() |
If you are upgrading to Host On-Demand Version 11 from a previous version, refer to Upgrading from earlier versions of Host On-Demand for migration scenarios and instructions on how to upgrade your system. |
Before installing the Host On-Demand server, ensure that you have the appropriate level of authority to access the directories and run the commands required for installation. For example:
When installing the Host On-Demand server, Host On-Demand will alert you if it does not recognize your operating system. In this case, you will have the option either to continue installing the product files or cancel the installation. If you decide to continue installing, the product files will be installed, but no automatic configuration will take place. This means the Web server will not be configured properly, and for Windows machines, no shortcuts or services will be created. For information about how to configure your Web server manually, refer to your Web server's documentation.
For a list of supported operating systems, refer to Requirements.
![]() |
Because Host On-Demand clients are served as Web pages, you must install the server component in the same environment as a Web server. |
For information regarding installation and accessibility, refer to Accessibility in the online help.
![]() |
If you are upgrading from a previous version of Host On-Demand, refer to Upgrading from earlier versions of Host On-Demand for information on backing up your customized HTML pages and other customized configuration files. |
For instructions about installing Host On-Demand on z/OS, refer to the Host On-Demand Program Directory supplied with the Host On-Demand product media.
For instructions on installing Host On-Demand on Linux for zSeries, refer to Installing on Windows, AIX, Linux, Solaris, and HP-UX.
There are three options for installing the Host On-Demand server on i5/OS and OS/400 systems:
To install on i5/OS and OS/400 in graphical mode, you must install remotely from a computer running Windows. The following steps guide you through the install:
hodinstallwin.exe -os400
Alternatively, you can use three more parameters to designate the exact server to which you are installing and log onto that server. For example:
hodinstallwin.exe -os400 myserver myuserid mypassword
Myserver is the TCP/IP address or host name for your IBM System i5 server. Myuserid and mypassword are a valid logon ID to that server.
![]() |
When migrating to Host On-Demand Version 11 from a previous version, the installation directory will remain the same. This is true for all platforms. |
Installing Host On-Demand in console mode suppresses the GUI wizard. Instead, the utility sends messages and text prompts directly to your console (or command line window). You make selections by pressing the Enter key or typing a number.
The silent mode is particularly useful for deploying multiple images of Host On-Demand server. The silent mode requires no interaction between you and the systems constituting your installation. You simply distribute a text-only response file supplying installation input.
The following steps apply to both console and silent installations on your IBM System i5 server:
For other installation options, refer to Appendix D. Native platform launcher command line options.
To run a remote console installation from a Windows machine, enter the following: hodinstallwin.exe -os400 -console.
To run a remote silent installation from a Windows machine, enter the following: hodinstallwin.exe -os400 myserver myuserid mypassword -silent -options c:\mydirectory\responseFile
There are three options for installing the Host On-Demand server on Windows, AIX, Linux, Solaris, and HP-UX systems:
![]() |
Even if you plan to install in console or silent mode, you should read through the steps for using the graphical interface. They document environment variables required for any installation mode. |
The following steps guide you through the graphical interface for installation on Windows, AIX, Linux, Solaris, and HP-UX:
![]() |
Attention Unix users: If you plan to install Host On-Demand by copying the DVD image on to your target machine, for example, in cases where your target machine does not have a DVD drive, you will need to manually recreate permissions. To do this, issue the following command at the root of your DVD image: chmod -R +x *. This command is valid for Linux, HP-UX, AIX, and Sun platforms. |
![]() |
Attention Unix users: Alternately, you can use setupunix.sh located in the root of the install image to install Host On-Demand on Unix-based systems (AIX, Linux, Solaris, and HP-UX). |
![]() |
When migrating to Host On-Demand Version 11 from a previous version, the installation directory will remain the same. This is true for all platforms. |
![]() |
|
Installing Host On-Demand in console mode suppresses the GUI wizard. Instead, the utility sends messages and text prompts directly to your console (or command line window). You make selections by pressing the Enter key or typing a number.
To use console mode, input your native platform launcher with the -console command line option. For example, on Windows:
hodinstallwin.exe -console
For other installation options, refer to Appendix D. Native platform launcher command line options.
The silent mode is particularly useful for deploying multiple images of Host On-Demand server. The silent mode requires no interaction between you and the systems constituting your installation. You simply distribute a text-only response file supplying installation input.
You can find a sample response file on the Host On-Demand DVD in hodinst\hodSampleResponse.txt. After modifying the file for your environment, enter the following command-line options (with your native platform launcher) to run a silent installation. For example, on Windows:
hodinstallwin.exe -silent -options c:\mydirectory\responseFile
where c:\mydirectory\responseFile is your response file's path name.
To create your own response file, enter the following options:
-options-record filename
where filename is the name of your response file.
For other installation options, refer to Appendix D. Native platform launcher command line options.
During the Host On-Demand installation, you can choose to have the configuration servlet installed and configured on i5/OS, OS/400, Windows, AIX, Linux, Solaris, and HP-UX for IBM WebSphere Application Server.
![]() |
All Web servers and servlet engines are configured differently. Check your Web server and servlet engine documentation for servlet configuration details on your operating system. |
Installing the configuration servlet is necessary only if both of the following statements are true for your Host On-Demand deployment:
By default, the Host On-Demand clients use port 8999 to access configuration information from the Service Manager. If any of your clients are outside the firewall, the firewall administrator needs to open port 8999 both internally and externally. However, you can avoid opening this port by customizing your clients to use the configuration servlet to access configuration information.
During Host On-Demand installation on Windows, AIX, Linux, Solaris, and HP-UX, the install utility searches your system for an instance of WebSphere Application Server. If it detects an instance, the install utility can automatically install and configure the configuration servlet on WebSphere Application Server Versions 5.1, 6.0, 6.1 and 7.0.
For platforms that do provide an installation program such as System z and others, you will need to manually install the configuration servlet. Refer to your WebSphere Application Server documentation for steps on installing enterprise applications. You can also go to http://www.ibm.com/software/webservers/ and navigate to the WebSphere Application Server support page, where you will find a link to your version's documentation.
The Host On-Demand configuration servlet EAR file, cfgservlet.ear, is located in the lib directory of your Host On-Demand installation.
![]() |
For WebSphere Application Server 5: After you save your deployment settings in the administrative console, you need to start the Host On-Demand configuration servlet in the Enterprise Applications window of WebSphere Application Server. Then go to the Environment window and select Update Web Server Plug-in. |
After the configuration servlet is installed, you must configure your clients to use the configuration servlet instead of directly accessing the Service Manager. You can use the Deployment Wizard to build customized HTML client pages. The wizard sets the applet parameters in the HTML based on your input, so you do not have to learn the syntax and valid parameter values. IBM recommends that you use the Deployment Wizard to set the ConfigServerURL parameter in the client HTML to HODConfig/HODConfig/hod.
For more information regarding configuration servlet parameters, configuration and examples, see Configuring the configuration servlet in the online help.
The Deployment Wizard is automatically installed as part of the Windows Host On-Demand server installation. It is also available separately for those customers who do not wish to install the entire Windows Host On-Demand server. The following Windows platforms are supported:
This separate Deployment Wizard can be installed in one of two ways:
The following two sections describe the installation process for each method.
![]() |
The Deployment Wizard installation image is approximately 68 MB. If you plan to download this installation image, particularly over a modem, prepare for a large download. |
To install and run the Deployment Wizard, do the following:
The Deployment Wizard image is shipped on all Host On-Demand server platforms, and it can be downloaded from the server and installed on any Windows machine.
To download the Deployment Wizard from a Host On-Demand server, do the following:
This chapter provides detailed information on how to properly upgrade your system from earlier versions of Host On-Demand. It discusses the steps involved in upgrading the following components of Host On-Demand:
When upgrading the Host On-Demand server, the following basic steps minimize migration risks, and provide a transparent upgrade experience for your users:
After the entire migration process, users select from sessions with the same definitions as before. All of their customizations (for example, macros and keyboard remaps) continue to work as before.
The following sections guide you through these basic steps, which vary according to your operating system and Host On-Demand version upgrade.
![]() |
Upgrading on Windows or AIX: If your customized files include CustomizedCAs.class files generated by IKEYMAN (the Certificate Management utility built into Host On-Demand), be aware that upgrading to Host On-Demand 11 involves automatic translation of those files into a different format: CustomizedCAs.p12. For more information, refer to Migrating from CustomizedCAs.class to CustomizedCAs.p12. |
IBM recommends different migration scenarios (including different file back-up methods), depending on your operating system and the Host On-Demand version from which you are upgrading to Host On-Demand 11.
Operating system | Previous version of Host On-Demand | Migration scenario |
---|---|---|
|
8 | Host On-Demand automatically migrates to the new version without formally uninstalling the previous version. Only the files that have changed are updated. Customized files remain intact. |
|
8.0.0 | You must manually uninstall Host On-Demand V8.0.0 before installing the newer version. If you attempt to install the newer version without uninstalling the older one first, Host On-Demand will warn you that the installation cannot continue until you uninstall the older version. Refer to Uninstalling the Host On-Demand server for more information. |
|
8.0.x (manufacturing refreshes) | Host On-Demand automatically migrates to the new version without formally uninstalling the previous version. Only the files that have changed are updated. Customized files remain intact. |
|
5-7 | Host On-Demand automatically uninstalls the previous version from your system and replaces it with Host On-Demand 11, leaving customized files intact. Refer to Installing on Windows, AIX, Linux, Solaris, and HP-UX. |
Windows or AIX | previous to 5 | Refer to Migrating on server operating systems with an uninstall program. |
i5/OS and OS/400 | 4-8 | Host On-Demand automatically uninstalls the previous version from your system and replaces it with Host On-Demand 11, leaving customized files intact. Refer to Installing on i5/OS and OS/400. |
Any other operating system without a native uninstall utility such as z/OS | does not apply | Refer to Migrating on server operating systems without an uninstall program. |
In Host On-Demand 7 and later, you can put custom HTML files (files generated from the Deployment Wizard), config.properties, and CustomizedCAs.class or CustomizedCAs.p12 files in a directory other than the Host On-Demand publish directory.
Creating a separate user publish directory makes it easier to apply Host On-Demand upgrades because installing a new version of Host On-Demand will not affect the new directory. It also keeps the Host On-Demand publish directory read-only because it provides a separate writeable location for deploying Deployment Wizard pages. Additionally, creating a separate user publish directory isolates customer generated files from those provided by Host On-Demand. Note that other user-modified files (such as customer applets and HACL programs) still need to run from the Host On-Demand publish directory.
Continue with step 2.
Continue with step 2.
The Deployment Wizard HTML files are installed in the directory /user_publish_dir/. Additional files like cfg0.cf and params.txt are installed in the /user_publish_dir/HODData/your_html directory.
Pass /user_alias/ * /user_publish_dir/ *
/hod_publish_dir_alias/config.properties
/user_publish_dir/config.properties
![]() |
On the zSeries platform, append the ascii extension, /user_publish_dir/config.properties.ascii. |
/hod_publish_dir_alias/CustomizedCAs.p12
/user_publish_dir/CustomizedCAs.p12
On server platforms that have an uninstall program (for example, Windows and AIX), the uninstall program assists in the upgrade process. The uninstall program does not uninstall any files that the installation program did not install initially; such as, CustomizedCAs.class, CustomizedCAs.p12, or customized HTML files. Also, there are no changes to the private directory during the uninstall of the previous release. Any customized files that you added for the previous release of Host On-Demand remain unchanged when you install the new version of Host On-Demand. Run the uninstall program to remove the old version and then install the new version of Host On-Demand.
Refer to Installing on Windows, AIX, Linux, Solaris, and HP-UX for installation instructions.
Take the following steps to migrate on server platforms without an uninstall program:
If you install Host On-Demand in a test environment before deploying to your production environment, complete the following steps to migrate Host On-Demand from one server to another (or from one HFS to a different HFS in a z/OS environment). First, install Host On-Demand on the new server. Then copy the private directory, any files added to the publish directory, such as CustomizedCAs.class, CustomizedCAs.p12, or customized HTML files, and the HODData directory from the test environment to the new server environment.
![]() |
If your current environment is not z/OS and you want to move to a z/OS environment, this migration requires some additional steps. You can copy the private directory and the CustomizedCAs.class and CustomizedCAs.p12 files over to the new server directly. However, you should use the DWUnzip utility to correctly install the customized HTML files and the HODData directory. |
Starting with Host On-Demand 8 or later, you can no longer create or update the CustomizedCAs.class file on Windows and AIX platforms. The Certificate Management utility (IKEYMAN) only allows you to create or update a newer version of this file called CustomizedCAs.p12. When you upgrade to Host On-Demand 8, the Host On-Demand installation automatically detects the CustomizedCAs.class file, creates the CustomizedCAs.p12 file, and places it in the publish directory. Both the CustomizedCAs.class and CustomizedCAs.p12 files remain in your publish directory and are available to clients of different versions.
If you have a separate user publish directory and not the default publish directory, you need to run the migration tool manually. From your publish directory, use the following command to run the migration tool and migrate the CustomizedCAs.class into the CustomizedCAs.p12 file:
..\hod_jre\jre\bin\java -cp ..\lib\ssliteV2.zip;..\lib\sm.zip com.ibm.eNetwork.HOD.convert.CVT2PKCS12 \user_directory_path\CustomizedCAs.class hod
![]() |
The command appears in this document on three lines; however, you should type it all on one line. |
Once you have migrated to the new CustomizedCAs.p12 file, you may need to make future updates. In order for these updates to appear in the CustomizedCAs.class file for older clients, you must run a reverse migration utility. For Windows platforms, this utility runs automatically each time you open and close the IKEYMAN tool. For AIX, you must manually run the utility from your publish directory using the following commands:
../hod_jre/jre/bin/java -cp ../lib/ssliteV2.zip;../lib/sm.zip com.ibm.eNetwork.HOD.convert.CVT2SSLIGHT CustomizedCAs.p12 hod CustomizedCAs.class
![]() |
Note that the second command appears in this document on three lines; however, you should type it all on one line. |
Unlike the CustomizedCAs.class, the CustomizedCAs.p12 requires a password by definition to open the file using the Certificate Management utility (IKEYMAN). If you create the CustomizedCAs.p12 file, use hod as the default password. If the Host On-Demand installation creates the CustomizedCAs.p12 file after detecting CustomizedCAs.class in your publish directory, it automatically configures the CustomizedCAs.p12 file with the hod password.
Download client users load the new Host On-Demand client code the first time they point their browsers to the download client HTML file after the Host On-Demand server has been updated to the new version of Host On-Demand. They will be able to use the new features of Host On-Demand right away.
The cached client and Web Start client code detects that there is a newer version available on the server. Depending on how you set the cached client upgrade controls, users could be delayed in upgrading to the newer version. They will not be able to take advantage of the new features until their client code gets upgraded, but they can continue to use the older cached client code until then.
![]() |
There are circumstances where the client upgrade takes place regardless of how you set the cached client upgrade. Host On-Demand provides html parameters you can use to help under these circumstances. See the Upgrade Options section of the Cached Client Settings topic of the online help. |
When you upgrade to a new release of Host On-Demand, it is not necessary to edit your existing Deployment Wizard files. Those files will continue to work as they always have. However, if you wish to take advantage of new features available in the Host On-Demand Deployment Wizard, you must edit your existing custom HTML files using the new Deployment Wizard.
Follow these steps to edit an existing HTML file:
![]() |
If your users have Java 2-enabled browsers, and you have custom HTML files that you created or last edited in Host On-Demand 6.0, IBM strongly encourages you to edit the HTML files with the new Deployment Wizard to receive the improved support for Java 2 environments. |
![]() |
If you are using the Cached Client or Web Start client and want to use the upgrade controls, do not add any additional components to the Preload Options when you edit the HTML file after an upgrade. See Cached Client Settings in the online help. |
Upgrading is the process of converting HTML files generated by an earlier version of Host On-Demand to a format that runs successfully on the Host On-Demand 11 client. Upgrading allows you to take advantage of the new features provided by the Host On-Demand 11 client.
The statements in the following sections apply to emulator clients only. Also, the statements in this section apply both to the emulator cached client and the emulator download client, unless the statement specifically mentions one or the other.
You do not have to migrate HTML files from Host On-Demand 7 or later to Host On-Demand 11.
Host On-Demand 7 or later have the same concept of client Java level as Host On-Demand 11. Consequently, whether the HTML file was created using the Deployment Wizard from Version 7 or later, the Host On-Demand 11 cached client runs the HTML file in the same way. For more information on client Java level, refer to Host On-Demand Java level.
Host On-Demand 6 does not have the concept of client Java level and provides limited Java 2 support. As a result, you must migrate some types of HTML files created with Host On-Demand 6.
If you want to run the HTML files created with the Host On-Demand 6 Deployment Wizard on Java 2-enabled browsers, then you must migrate the HTML files. To migrate these files, edit them with the Host On-Demand 11 Deployment Wizard.
If you created HTML files with the Host On-Demand 6 Deployment Wizard that your users run with Java 2-enabled browsers, these files allow your users to run Java 2-enabled browsers.
IBM recommends that you migrate these HTML files in order to take advantage of the advanced features available in the Java 2 version of Host On-Demand.
To migrate these files, edit them with the Host On-Demand 11 Deployment Wizard.
To remove Host On-Demand 11, follow the steps for your operating system.
For other uninstallation options, refer to Appendix D. Native platform launcher command line options.
Run your operating system's uninstall utility, with path name your_install_directory/uninst/, where your_install_directory is the directory where you installed Host On-Demand:
![]() |
Alternately, you can use your Windows Add/Remove Programs utility to uninstall Host On-Demand. |
You can run the utility in console mode by using the -console command line option. Otherwise, follow the uninstall wizard's GUI.
After installing Host On-Demand, you need to create HTML files and configure Host On-Demand sessions for your users.
![]() |
Host On-Demand provides a sample HTML file
of ready-to-use 3270, 5250, VT, and FTP emulator sessions pre-configured
with download client and Java auto-detection components. These sessions
use the HTML-based configuration model and are provided to allow you
to get Host On-Demand up and running and access your host systems
quickly. To use these emulator sessions, take the following steps:
|
The best way to create and set up your HTML files for Host On-Demand is to use the Deployment Wizard. The Deployment Wizard allows you to easily create custom HTML files that contain all of the Host On-Demand features tailored for your environment. The following is a list of some of the many features that can be configured using the Deployment Wizard:
![]() |
To use the Web Start client, you must use the Deployment Wizard. Predefined files for this client type are not provided. |
In addition to setting up your HTML files, you will need to define sessions for your users. If you are using the HTML-based model, then you configure your sessions in the Deployment Wizard at the same time that you create the HTML files. Otherwise, if you are using the configuration server-based model or the combined model, or using one of the predefined clients, you will need to create groups, users, and sessions in the configuration server using one of the administration clients.
There is a full range of options available to you when you are configuring your sessions, regardless of whether you need to use the Deployment Wizard or one of the administration clients:
The Deployment Wizard runs on a Windows platform. To start the Deployment Wizard, select one of the following ways:
The Deployment Wizard Welcome window appears.
The Deployment Wizard guides you through configuration choices and provides comprehensive help for the features. When you have finished selecting features, the Deployment Wizard creates the HTML and supporting files for you. These files need to be placed on the Host On-Demand server in a directory known to your Web server; usually, this directory is your Host On-Demand server's publish directory.
If your Host On-Demand server is on a Windows or IBM System i5 platform, you may be able to write your Deployment Wizard HTML and configuration files directly to your Host On-Demand server's publish directory. On the final screen of the Deployment Wizard, you can select where to write the generated files. You may select any local or network drive accessible by the machine where your Deployment Wizard is running. In this case, you would direct the Deployment Wizard output to a publish directory on the Host On-Demand server and specify an output format of HTML. Assuming that you have already defined your sessions, the HTML page is then ready to be accessed by your users.
Otherwise, if your Deployment Wizard cannot directly write to your Host On-Demand server, then you should select to have the Deployment Wizard generate a zip file for the output format. The Deployment Wizard will then produce a single zip file containing all of the HTML and supporting files. You will need to move the zip file to the Host On-Demand server and use DWunzip to explode the zip file into the desired publish directory. Assuming that you have already defined your sessions, the HTML page is then ready to be accessed by your users.
Host On-Demand supplies several predefined clients for administering Host On-Demand and creating new user accounts. Before accessing an emulator client or a Database On-Demand client that uses the configuration server-based or combined deployment models, you must add users and configure sessions for them with one of the administration or full administration clients.
To load an administration or new user client, do one of the following:
http://server_name/hod_alias/client_name.htmlwhere server_name is the host name or IP address of the Host On-Demand server, hod_alias is the alias (or path) of the publish directory, and client_name is the HTML file name of the administration or new user client. For example, you can download the cached version of the administration client from the Web server by specifying a URL such as the following:
http://host.yourcompany.com/hod/HODAdminCached.html
To log on as the administrator the first time after the initial installation:
Administration clients enable you to perform the following tasks for data stored on the configuration server:
Administration clients run on all Host On-Demand client platforms except the Macinstosh operating system. If you are creating HTML files in the Deployment Wizard using either the configuration server-based or combined models, you must configure sessions on the configuration server using an administration client. Refer to Basic Configuration Steps in the online help for more detailed information about configuring the Host On-Demand configuration server.
Host On-Demand supplies the following predefined administration and full administration clients:
![]() |
To bookmark the cached Administration client, you must manually create the bookmark. It must point to HODAdminCached.html, so that Host On-Demand can compare the cached version to the server version. This allows Host On-Demand to recognize and notify you that a newer version of the cached Administration client is available at the server. |
Directory Utility is a command-line Java application the administrator can use to manage user, group or session configuration information. This information is stored either in the Host On-Demand default data store, or in an LDAP directory. This utility is only useful in the environment where the Configuration Server-based model is in use. Directory Utility allows you to add, delete, or update large numbers of users, groups, or sessions in a batch mode environment instead of using the Administration client. Directory Utility reads an XML ASCII file that contains the following actions to be performed on users, groups, or sessions defined to the Configuration Server:
![]() |
Searches performed with the list action are either user-based (returning user-specific information) or group-based (returning group-specific information). LDAP environments, however, support only user-based searches. |
For more information, see Using the Directory Utility in the online help.
If the administrator has enabled Allow users to create accounts in the Users/Groups window, users can use the predefined new user clients to create new accounts. See the New User client topic in the online help for more information about this client.
The following new user clients are supplied with Host On-Demand:
This chapter discusses issues that you need to be aware of when configuring and using Host On-Demand terminal emulator clients.
![]() |
Host On-Demand provides a sample HTML file of ready-to-use 3270, 5250, VT, and FTP emulator sessions pre-configured with download client and Java auto-detection components. These sessions use the HTML-based configuration model and are provided to allow you to get Host On-Demand up and running and access your host systems quickly. For more information, refer to Configuring Host On-Demand emulator clients. |
To load a Host On-Demand emulator client, a user starts a Web browser and enters in the Address field the URL of a Host On-Demand HTML file. The Host On-Demand HTML file must be one of the following:
IBM recommends the first option. For more information on the Deployment Wizard, see the Deployment Wizard topic in the online help. For more information on the generic predefined HTML files, see Predefined emulator clients.
![]() |
If your emulator client is deployed with the configuration server-based or combined deployment model, you must add users and configure sessions with the administration client before you can use the emulator client. |
To launch HTML files generated by the Deployment Wizard, specify the full URL of the HTML file in your browser:
http://server_name/hod_alias/client_name.html
where server_name is the host name or IP address of the Host On-Demand server, hod_alias is the alias (or path) of the publish directory, and client_name is the HTML file name of the client. For example, if you created an HTML file in the Deployment Wizard called 3270sessions.html, you can load it by specifying a URL such as the following:
http://host.yourcompany.com/hod/3270sessions.html
To launch a predefined HTML file included with Host On-Demand, point your browser to HODMain_xx.html file, where xx is your two-letter language suffix, to view links to all the available predefined clients. HODMain_xx.html is located in the publish directory.
When you access a client, a security warning appears to notify you that Host On-Demand was created by International Business Machines. Users must grant Java security privileges for this session or any future sessions by clicking the appropriate buttons in order for Host On-Demand to work properly.
The types of Host On-Demand clients that you use depend on your computing environment and your personal preferences.
Cached clients and Web Start clients are stored locally and load faster than download clients (unless an updated version of the client is being downloaded from the Web server). You can use them equally well over network and dial-up connections. Cached clients and Web Start clients take up more local disk space than download clients, but on most machines this is not a problem.
The Web Start client allows users to run Host On-Demand sessions without a browser. Users start Host On-Demand sessions from the Java Web Start Application Manager. If a user closes the Host On-Demand desktop and there are active sessions running, the user is prompted to make sure he wants to close all sessions.
Download clients are generally used in LAN-connected environments because high-speed network connections reduce the time it takes to download them from the Web server. They are not recommended for use over low-speed dialup connections because they need to be downloaded every time they are used, which takes more time on dialup connections. The small disk footprint of download clients is especially well-suited for client machines that do not have a lot of local disk space, such as NetStation machines.
You can use cached, Web Start, and download clients in the same Host On-Demand environment. Refer to Removing the cached client for instructions on removing cached clients.
If you plan to use the Web Start client, you must use the Deployment Wizard to generate your HTML file. If you plan to use cached clients or download clients, IBM recommends that you create your own clients using the Deployment Wizard instead of using one of the predefined clients. Refer to Reducing client download size for more information.
A Host On-Demand cached client is any Host On-Demand client whose components have been cached (stored locally for quick access) on the hard disk of a user's workstation. When a user first runs a cached client, the Host On-Demand startup code downloads the Host On-Demand client components and stores them on the hard disk of the user's workstation. This is called installing the cached client.
When the user then runs the cached client, the Host On-Demand startup code downloads only a small startup applet from the server. The startup applet in turn starts the Host On-Demand client from the cached components on the hard disk.
By using the cached client, the user avoids having to wait for the Host On-Demand client components to be downloaded because they are already immediately available on the workstation's hard disk. In addition, the cached client is persistent across operating system restarts and browser reloads. Even though the cached client was originally intended for users with slow connectivity, such as dial-up phone lines, where downloading a large applet would take a long time, many customers have preferred using the cached client even for high-speed lines.
Like all Host On-Demand clients, the cached client is started (both the first time and subsequently) by specifying the URL of a Host On-Demand HTML file in the Address field of a supported Web browser. IBM recommends that you create your own HTML file using the Deployment Wizard. However, you can also use one of the generic, predefined cached client HTML files included with Host On-Demand.
The applet that starts the cached client also determines whether the version number of any of the Host On-Demand client components on the Host On-Demand server is newer than the version number of the corresponding downloaded components. If so, then the applet upgrades the cached client by downloading and caching the newer component from the server before launching the cached client.
The user can install multiple types of a cached client on the same workstation. For example, an emulator cached client, a Database On-Demand cached client, and an administration cached client could all be installed on one workstation. Also, with the Java 2 version of Host On-Demand, the user can install two versions of the same cached client: one with problem determination and one without problem determination.
You can install a cached client either from a Host On-Demand server or from a LAN drive or DVD drive.
Two types of information are stored on the user's workstation when a Java 2 cached client is installed:
These components are in the form of Java archive files (JAR).
This information includes data such as the URL of the Host On-Demand server and the version of each downloaded component.
Multiple versions of the Java 2 cached client can exist on the user's workstation because the Java 2 cached client startup code stores the cached client components in a different directory of the workstation's hard disk for each server from which the user has downloaded a cached client.
For the Java 2 cached client, all the client components that are downloaded from the same server are stored in the same directory on the user's hard disk. For example, if the user installs a Java 2 emulator client and a Java 2 Database On-Demand client from the same server, then the component files for both types of client are stored in the same directory.
For a few specialized types of Java 2 cached clients, the client components are stored in the Java 2 plug-in's sticky cache. These are the same cached client types that are listed in Limits of support.
To install the cached client from a Host On-Demand server:
![]() |
The installation progress window does not appear for a few types of Java 2 cached clients. These are the same Java 2 cached clients that are listed in Limits of support. |
You can now have some or all of your users initially download the cached client from a LAN drive or a DVD. To install the cached client, the user has to access the LAN drive or DVD only once. After the installation, the user connects to the Host On-Demand server in the usual way.
The advantages of this method are that the cached client components are installed on the user's workstation more quickly than they would be if they had to be downloaded from the Web server, and that the user is not placing an additional load on the Web server by downloading an entire set of cached client components.
This method is supported on most client platforms. However, several Java 2 cached clients do not support this feature. The Java 2 cached clients that do not support this feature are listed in Limits of support.
The HTML file cannot specify a separate user publish directory. (If you specified a Code Base in the Deployment Wizard, the HTML file cannot be used to install the cached client from a LAN or DVD drive.) Refer to the online help for more information about the separate user publish directory.
![]() |
If you are copying these files from a z/OS installation to a DVD image, note that you will have to remove the .ascii file extension from all HTML, PROPERTIES, JS, JNLP, and CSS files first. For example, a file named *.properties.ascii should be copied to the DVD as *properties. |
![]() |
If you are using a DVD for cached client installation, the DVD must be distributed with the same guidelines as the License Agreement and Export and Import regulations because it contains encryption technology. |
After the administrator has set up the LAN drive or DVD, the user must perform the following steps to install the cached client.
![]() |
For the Java 2 cached client, the system administrator can eliminate this step by adding the HTML parameter WebServerHostname to the HTML file. See HTML parameters in the online help. |
Type the path and name of the HTML file in the browser's address input field, such as:
f:/mypath/MyHOD.html
![]() |
For the Java 2 cached client, the system administrator can eliminate this step by adding the HTML parameter WebServerHostname to the HTML file. See HTML parameters in the online help. |
http://myServer/hod/MyHOD.htmlThe name of the HTML on the Host On-Demand server is the same as the name of the HTML file on the LAN or DVD.
After completing these steps, the Host On-Demand cached client starts in the usual way.
A general purpose removal method is discussed in the following sections.
Removing the cached client means erasing the information that was stored on the user's hard disk when the Java 2 cached client was installed.
A user running the Java 2 version of the cached client has a separate version of the cached client for each Host On-Demand server for which he downloaded a cached client. For more information, refer to Information installed for the cached client.
Removing the Java 2 cached client removes only the version of the Java 2 cached client that was downloaded from the server that the user visits when he does the removal. For example, if the user visits the server http://myHODServerA/hod/HODRemove.html for the server myHODServerA to remove the Java 2 cached client on the user's workstation, then only the Java 2 cached client that was downloaded from myHODServerA is removed.
Finally, for the Java 2 cached client, removing the cached client removes all the types of cached clients (such as emulation, Database On-Demand, and administration) associated with that installation.
Removing the Java 2 cached client from a workstation while attaching to server myHODServerA removes the emulation cached client, Database On-Demand cached client, and administration cached client that were previously downloaded from server myHODServerA. However, only the cached client components downloaded from that server are removed. Cached client components from other servers, if any, are not removed until the user connects to that server and performs a remove.
The general-purpose removal method removes the Java 2 cached client. Follow these steps:
Start a Java 2-enabled browser to remove a Java 2 cached client.
http://myServer/HOD/HODMain.html
![]() |
If you are removing a Java 2 cached client, you must connect to the same server from which you installed the Java 2 cached client to successfully remove it. For more information, refer to Before you begin. |
Remove Cached Client
There is also an alternate and more direct way of performing this general-purpose removal. Follow these steps:
http://myServer/HOD/HODRemove.htmlThis removes the cached client.
![]() |
If you are removing a Java 2 cached client, you must connect to the same server from which you installed the Java 2 cached client to successfully remove it. For more information, refer to Before you begin. |
Whichever general-purpose removal method you use, you will be prompted to clear the Java 2 plug-in's cache if you have removed the following Java 2 cached clients:
A window appears to notify you to clear the Java 2 plug-in's cache. For more information, refer to Using the Java 2 plug-in in the online help.
If multiple users share a single cached client, and one of these users removes the cached client, then the cached client is removed for all users. For information on sharing a single cached client, refer to Cached client support for Windows 2000, Windows 2003 and Windows XP.
The following sections detail issues and problems that might arise when cached client users access multiple Host On-Demand servers.
A Host On-Demand Java 2 cached client installs a separate copy of the cached client code for each Host On-Demand server that the user visits. Therefore there is no problem accessing servers at different service levels. With some versions of the plug-in, users may need to increase the size of their Java 2 cache if they are going to visit many Host On-Demand servers.
The following problems can occur with the Java 2 cached clients.
If you are using locally stored preferences, the custom HTML files you create must have names unique to your company, because the HTML file names differentiate between the locally stored preferences of different sites. Using generic names could cause preference conflicts for your users.
If you have problems managing cached client deployment on the Internet, go to http://www.ibm.com/software/webservers/hostondemand/support.html for more information.
On a multi-user Windows machine running either Windows 2000, Windows 2003 or Windows XP operating systems, users can download their own independent version of the cached client:
If the JavaScript API is enabled, the cached client cannot be shared for Mozilla Java 2 browsers due to a technical limitation.
Alternatively, you can add the following parameters using the HTML parameters selection of the Advanced Options window of the Deployment Wizard:
When the cached client is shared but you do not specify a directory, the cached client is installed in the default directory \Documents and Settings\All Users\IBMHOD. If you specify a directory, for example SharedCachedDirectory=c:\ibm, the Host On-Demand cached client appends IBMHOD\HODCC to this string, and the cached client is installed in this new location, for example, c:\ibm\IBMHOD\HODCC. An administrator or power user must either create the install directory manually or perform the first install of the shared cached client. In either case, the administrator or power user must change the security settings for this directory so that restricted users have Read, Modify, and Write access. The Administrator can either change the security settings and then download the cached client to the directory, or download the shared cached client to the directory and then change the security settings. If the security settings are not updated and a restricted user attempts to install the shared cached client, the user receives an error message that indicates there may be a problem with the file system, and the restricted user will not be able to use or update the cached client.
Once the administrator or power user changes the security settings, a restricted user can log on to Windows and can either install the shared cached client or use (or update) a previously installed version of the shared cached client. Other restricted users can log on to Windows and use the cached client without having to download it from the Host On-Demand server again. They can also upgrade the shared cached client, if necessary.
If you do not want restricted users to share the cached client, a separate instance of the cached client is downloaded to the user directory for each restricted user.
If an administrator or a power user downloads the previous version of the cached client, and you want to allow restricted users to access it, the administrator or a power user must use HODRemove.html to remove the previous version of the cached client, and then change the security settings to the shared cached client directory to Read, Modify, and Write for restricted users, as described above.
For information about removing a shared cached client, see Removing a cached client shared by multiple users.
Cached clients have the following limitations on Mac OS X:
![]() |
The Java 2 cached client improvements do not apply to the Mac OS X Java 2 cached client. For more information, refer to Limits of support. |
If you find that you cannot load the cached client, follow the troubleshooting suggestions provided below.
After upgrading your browser from Microsoft Internet Explorer 4 to Microsoft Internet Explorer 5.5, you might receive security exceptions in the Java console. When you install the Cached Client, several files are stored into the browser's directory structure. When you upgrade Internet Explorer from Version 4 to Version 5, the browser will no longer know about the CAB files that contain the Host On-Demand cached code. Since the browser cannot find the CAB files, it tries to use the class files directly from the server, causing security exceptions. To resolve this issue, you should upgrade your browser, remove Host On-Demand using HODRemove.html, and then reinstall the product using HODCached.html.
With the Mozilla and Firefox browser, if nothing happens when you try to install the cached client, or if the attempt to install the cached client fails, check the browser's settings. Make sure that Mozilla and Firefox are not set to suppress popup windows that appear on top of or under the Navigator window. This setting prevents the Host On-Demand cached client from being installed.
This location of this setting depends on the version of Mozilla:
After the cached client is installed, you can restore this setting to suppress popup windows. But if you need to install the entire cached client again or update to a newer version in the foreground, you must set Mozilla or Firefox again so that it does not suppress popup windows.
![]() |
The setting to suppress popup windows does not hinder the downloading of additional components that were not included in the initial download (preload list). |
The Java Web Start client allows users to start Host On-Demand without a browser. You must use the Deployment Wizard to generate a HTML file for the Web Start client. The HTML file generated by the Deployment Wizard points to a Java Network Launch Protocol (JNLP) file. The JNLP file defines a Java Application, including parameters passed to the application and the archives that contains class files used by the application. The JNLP file and the associated archives are stored on a Web server.
When a user points to the JNLP file, the browser launches the Web Start application on the client computer. It downloads the associated archives, checks to insure that the minimum required JRE is present (if specified), stores the archives on the user's machine, sets up icons to represent the application, and launches the application.
Users can start Host On-Demand sessions from the Java Web Start Application Manager. By using the Java Web Start Application Manager, Host On-Demand sessions do not depend on a browser. Therefore, closing a browser does not end a Host On-Demand session. If the user attempts to close the Host On-Demand desktop and there are active sessions running, the user is prompted to make sure he wants to close all sessions. If so, the sessions are terminated cleanly to prevent problems that occur when there are sessions running in the browser and the browser is abruptly closed.
After the initial launch of the application, you can either point the Web browser at the JNLP file again, or click the mouse on the icons created on the client machine. After Web Start is restarted, it checks the Web server for updates to the archives and downloads any updated files.
Java Web Start is bundled with JRE 1.4.0 or higher versions of the Java Runtime Environment. If you use JRE 1.3, then you should upgrade to JRE 1.4. For more information about Java Web Start, refer to http://www.javasoft.com. Host On-Demand Version 11 recommends Java 1.5 or higher.
The Host On-Demand Web Start client has the following requirements:
There are two ways to install the Web Start client. Typically, users install it from a Host On-Demand server over the network, either with or without using a Web browser. Alternatively, users can install it from a LAN or DVD drive, although this requires a small additional download over the network. Regardless of how users install the Web Start client, once it is installed and in the Java Web Start Application Manager, they can start it by clicking the appropriate icon in the Application Manager.
Users can install the Web Start client from the Host On-Demand server either with or without using a browser.
To install the Web Start client using a Web browser, users can perform the following steps:
The Web Start client begins installing immediately. A window shows the progress of the installation. The upper progress bar of this window shows the status of individual files as they download, while the lower progress bar shows the status of the overall installation.
For Windows users, distribute the JNLP file that was generated from the Deployment Wizard (for example, myhod.jnlp) to your end users. Once the file is distributed, users can type start myhod.jnlp to start the Web Start application and begin installing the Host On-Demand client. Since the file extension '.jnlp' will be registered to the Web Start application, the Web Start application will start, read the file, and download all the appropriate archive files from the Host On-Demand server that was specified in the Deployment Wizard-generated JNLP file. The Host On-Demand Web Start client will start when the download completes.
If you have not distributed the JNLP file to Windows users or your clients are running platforms other than Windows, users can still download the Web Start client without a Web browser by starting the Java Web Start Application Manager directly and pointing to the JNLP file on the Web server.
For Windows clients, users can perform the following steps:
For Linux clients, a user can type /javaws http://HODServer/HODAlias/myhod.jnlp to install and run the Host On-Demand session. A Host On-Demand icon appears in the Java Web Start Application Manager. Users can double-click this icon to launch Host On-Demand.
In order to reduce network traffic and minimize download times, some companies wish for users to install the Web Start client from a LAN or DVD. Since the Web Start client and the cached client share the same cached archives, users can install the majority of the Web Start client using the same installation procedure as the cached client. However, the Web Start client requires an additional component that must be installed directly from the Host On-Demand server over a network.
Installing the Web Start client involves two steps for the administrator followed by two steps for the end user.
First, the administrator should perform the following two steps:
Second, once you have published your HTML file, users should perform the following two steps:
The administrator must register the JNLP extension as a mimetype with the Web server so the browser knows to launch the Web Start application. For example, the following sections describe how to configure Apache HTTP Server, IBM HTTP Server, and Microsoft IIS.
To configure the Apache HTTP Server or IBM HTTP Server for Web Start, add the following line to mime.types:
AddType Application/x-java-jnlp-file .jnlp
To configure Microsoft IIS for Web Start, complete the following steps:
After the initial install of the Web Start client, if users point their browsers to the HTML file generated by the Deployment Wizard and updates are available on the Host On-Demand server, Host On-Demand prompts users to update. If users want to update, Java Web Start downloads the updated archive files and launches Host On-Demand. If users decline to upgrade, Host On-Demand prompts them again the next time they launch the HTML file.
If users request a function that is not installed on the Java Web Start client, Host On-Demand prompts them to install the additional components required for that function. If they choose to install the additional components, they must restart the Host On-Demand client to use them.
Windows Restricted Users with Java Web Start 1.0.1 should remove the JRE and Java Web Start and reinstall a newer JRE with Java Web Start 1.2.
Since the Web Start client runs outside of a browser, bookmarking is disabled since bookmarking is a browser feature. Administrators can create Web Start clients that give users the same look as running an embedded bookmarked session by doing the following:
If you want to use HTTPS with the Web Start client, the certificate authority used for your secure HTTP connection should come from a well known root authority. When you use Host On-Demand as an applet and use an HTTPS connection, you are given the opportunity to trust the certificate used for the HTTPS connection if the root authority is not known by the browser. Since Java Web Start runs as an application, this browser facility is not available. The Java Virtual Machine used by Java Web Start contains several root authorities that it trusts. If the certificate that comes from the HTTPS connection has a root authority of one of these authorities known by the JVM, the secure connection can be established. If you want to use a certificate authority other than ones known by the JVM by default, for example, a self-signed certificate, you must import the certificate into the keystore of the JVM for each of the clients accessing this Java Web Start client. This is required to establish the secure HTTP connection.
To remove the Web Start client, complete both of the following steps:
Unlike the cached client and Web Start client, the download client does not control how or when client components are downloaded to the workstation's hard disk. The download client leaves all caching decisions to the browser.
Use the download client if you meet both of the following requirements:
Launch the download client by downloading it from the Host On-Demand server into your browser window, as described in Loading emulator clients.
With Java 2 clients, you can successfully launch the download client after installing the cached client or Web Start client.
Several predefined emulator client HTML files are supplied with Host On-Demand. They are included to demonstrate the range of Host On-Demand client functionality and to serve as examples for creating customized HTML files in the Deployment Wizard. All of them use the Configuration server-based model. To load one of these clients, follow the instructions in Loading emulator clients.
![]() |
In general, it is recommended that you define your own customized HTML files with the Deployment Wizard instead of using the predefined client HTML files. |
The following predefined emulator client HTML files are provided by Host On-Demand:
![]() |
With a Java 2-enabled browser the predefined download client file HOD.html omits some infrequently used Host On-Demand components. For more information, including a list of excluded components and a description of workarounds, see HTML files do not contain some components. Accessing HOD.html with a Java 2 browser works with limited functions. |
In general, it is a good idea to keep the size of your Host On-Demand clients (whether download, Web Start, or cached clients) as small as possible. This speeds up their download time and conserves disk space on client machines.
The best way to minimize the size of your Host On-Demand clients is to create them by using the Deployment Wizard. The predefined clients supplied with Host On-Demand are typically larger than the custom clients created with the Deployment Wizard because they contain Host On-Demand's full range of client functionality. Clients created in the Deployment Wizard contain only the functions that you select to be pre-installed. In addition, Deployment Wizard clients are downloaded in compressed format. This further reduces their download size.
When you create a customized client with the Deployment Wizard, you can select only the functions that you know users are going to need on the Preload Options window in the Deployment Wizard. For instance, if your users are only going to need 3270 terminal and 3270 printer sessions, do not select any other session types when you are creating the client in the Deployment Wizard. Including support for unused session types increases the size of the client without improving its functionality.
If you click Auto Select on the Preload Options window, the Deployment Wizard selects the components you need based on your session configuration.
You can also choose not to download components for functions that are not frequently used. Unless you choose to disable that function in the Deployment Wizard, users will be prompted to download any necessary components when they use that function. If you need additional session types later, you don't necessarily have to create a new client type. You can add the new session types to the preload list on the Preload Options window instead.
![]() |
On Mac OS X, you cannot install additional components after the initial download. For more information, refer to Cached client support for Mac OS X (Java 2 clients only). |
Do not use debugging or problem determination in either Deployment Wizard-generated or predefined clients. This greatly increases the size of the client and can slow down a client's performance. Debugging and problem determination clients are not intended for general use. Use them only in conjunction with Host On-Demand technical support to diagnose and solve problems with your Host On-Demand system.
Customer-supplied Java classes and archives are Java class files and archive files that are not included either as part of the Host On-Demand client or as part of the Java 2 Runtime Environment. Examples of such files are Java classes or archives that you yourself have implemented or that you have obtained from third parties.
You would want to deploy such classes or archives for use with the emulator client in the following situations:
![]() |
For Java 2 limitations on running customer-supplied applets, see Limitations with customer-supplied applets and Java 2. |
Although several methods are available for deploying these files, each method works only under certain circumstances. The possible methods are:
The deployment method you choose depends on:
The three methods available for deploying customer-supplied Java archives and classes are described in the following sections. In addition, Hints and tips for archive files provides more information about using archive files.
You can use this method when you want to deploy Java 2 archives to a Host On-Demand server. This method works for the cached emulator client, the download emulator client, and for the Web Start client.
Java 2 archives must be Java 2 .JAR files.
The advantage of using the AdditionalArchives HTML parameter is that it causes your Java archives to be downloaded to the user's workstation automatically when one of your users connects with the cached client or download client HTML file on your Host On-Demand server.
The disadvantage of this method is that these Java archives or class files will be downloaded again every time a user connects to that HTML file regardless of whether you are using a cached client or downloaded client. The reason for downloading the archives every time your user connects is to ensure that the Host On-Demand client has the latest versions of your archives or class files. As a result, this method works best when the Java archives or class files are relatively few and relatively small, so that your users do not have to wait a long time for these files to be downloaded, and so that downloading these files to your users does not place a heavy load on your Web server.
To use this method, perform the following steps:
myCustomA,myCustomB,MyCustomC
For more information, see AdditionalArchives in the online help.
This method works in the following situation:
To use this method, place the archives in your Host On-Demand publish directory. The default publish directory is the subdirectory HOD in your Host On-Demand server's install directory, such as c:\Program Files\IBM\HostOnDemand\HOD\.
The following hints and tips might provide helpful information about using archive files:
The Database On-Demand client is a Java applet that allows an end user to build SQL statements and File Upload statements, to send these SQL statements and File Upload statements to a remote database server, and to retrieve the results of SQL queries (SQL Select statements) from the remote database server.
The user can communicate with a database server running on an IBM System i5 server or other platform, so long as the proper Java Database Connectivity (JDBC) driver is installed on the Database On-Demand client workstation. For more information refer to Obtaining and installing a JDBC driver in this manual.
Features of Database On-Demand include:
The Database On-Demand client is available only through one of three predefined client HTML files (see Database On-Demand predefined clients). You cannot use the Deployment Wizard to create a Database On-Demand client.
However, as an alternative to the Database On-Demand client, you can now use database functions in Host On-Demand emulation clients and in macros (see Database functions in Display Emulation clients and in macros).
For more information see Overview of database access in the Host On-Demand online help.
The Database On-Demand client exists in a Java 2 version. Therefore:
This Database On-Demand client can take advantage of the advanced capabilities of the Java 2 plug-in.
As an alternative to the Database On-Demand client, almost all of the functions that are available in the Database On-Demand client are now also available in the display emulation client, including the following session types:
You can also use SQL statements and File Upload statements in macros in display emulation client sessions (see the SQLQuery action and the File Upload action in the Macro Programming Guide).
For example, while you are connected to a remote host in a 3270 Display session, you can launch a macro that automatically reads data from the 3270 Display session window and writes the data into a table in a database that is located on another remote host. Similarly, you can launch a macro that automatically reads data from a table in a remote database and writes the data into the 3270 Display session window.
For more information see Overview of database access in the Host On-Demand online help.
To start a Database On-Demand client on the client workstation, use one of the following two methods:
http://server_name/hod_alias/client_name.htmlwhere server_name is the host name or IP address of the Host On-Demand server, hod_alias is the alias of the publish directory, and client_name is the name of the HTML file. For example, assuming that www.myHODServer.com is your Host On-Demand server and that hod is the alias of the publish directory, then the URL for the download version of the Database On-Demand client is:
http://www.myHODServer.com/hod/HODDatabase.html
http://server_name/hod_alias/HODMain_xx.htmlwhere server_name and hod_alias have the same meanings as above. In the name of the file HODMain_xx, the xx is a two-letter mnemonic for the language that you want to use. For example, for English, the file is named HODMain_en.html, and the full URL is (assuming the same server and alias as above):
http://www.myHODServer.com/hod/HODMain_en.html
The Database On-Demand client is available through any one of three predefined client HTML files. You cannot use the Deployment Wizard to create a Database On-Demand client HTML file. The predefined clients are described below.
This is the download client. "Download" means that all the client code is downloaded to the client workstation each time the end user starts the Database On-Demand client.
This is the cached client. "Cached" means that most of the client code is downloaded the first time the end user starts the Database On-Demand client and is stored on the client workstation. After the first download, the cached client starts much more quickly than the download client, because most of the client code is already available on the client workstation. The cached Database On-Demand client has many components in common with the cached Host On-Demand client.
![]() |
For the cached client, if your end user requires more than one code page, you need to add the name of the archive file (.jar file) for each additional code page to the preload list in the predefined HTML file. For a list of code page languages and corresponding file names, see Using multiple code pages with Database On-Demand. |
This is the cached client with extra problem determination code for logging session events and tracing.
![]() |
Use the problem determination client only if you are working with IBM Support to resolve a problem with your Host On-Demand installation. |
To configure Database On-Demand for users, follow these steps:
If you want to create predefined SQL statements and File Upload statements for users and groups, follow these steps:
To connect to a database server running on a remote host, the end user needs a Java Database Connectivity (JDBC) driver installed on the client workstation.
The Host On-Demand client and the Database On-Demand client already include a JDBC driver from the IBM AS/400 Toolbox for Java. This driver allows a client to access a DB2/400 database on a properly configured IBM System i5 or AS/400 host system. You do not need to register or deploy this driver.
If you need a different JDBC driver:
The end user selects a file type for an SQL statement or a File Upload statement on the Output tab of the SQL Wizard window or on the File tab of the File Upload window.
For information on file formats, see File formats for database access in the Host On-Demand online help.
If you wish to use multiple code pages with Database On-Demand, you must add jar or cab files to your HTML file. Only those code pages that correspond to the language of the HTML file are automatically loaded. For example, if you are running from a French computer, but you want to access a Dutch host, you must make these modifications.
Edit the CommonJars.js file. If you are using a download client, look for the line that starts "dbaDownloadJars =" and add the appropriate file names from the table below. Use jar file names, even if your clients will be using Internet Explorer (the names will be converted to cab file names later). If you are using a cached client, look for the line that starts "dbaCachedComps =" and add the appropriate component name from the table below.
The following table lists the supported Database On-Demand client code page languages, the corresponding .jar file names, and the cached component names:
Code page language | .JAR file name | Component name |
Arabic | hacpar.jar | HACPAR |
Czech, Hungarian, Polish, Slovenian | hacpce.jar | HACPCE |
Danish, Finnish, Dutch, Norwegian, Swedish | hacp1b.jar | HACP1B |
German, Spanish, French, Italian, Portuguese, Brazilian Portuguese | hacp1a.jar | HACP1A |
Greek | hacpgr.jar | HACPGR |
Hebrew | hacphe.jar | HACPHE |
Japanese | hacpja.jar | HACPJA |
Korean | hacpko.jar | HACPKO |
Russian | hacpru.jar | HACPRU |
Simplified Chinese | hacpzh.jar | HACPZH |
Thai | hacpth.jar | HACPTH |
Turkish | hacptr.jar | HACPTR |
Traditional Chinese | hacptw.jar | HACPTW |
Server macro libraries are available for HTML model pages only. They allow you to create and maintain a central repository of macros for users to access from their Host On-Demand sessions. These macros are not downloaded to the user's machine until they are needed. When you make changes to a server macro, users automatically get your updates the next time they access the macro.
Server macro libraries have several benefits:
Server macro libraries can reside on a Web server or on a shared network drive. For both types of libraries, you can control which macros are available to particular Host On-Demand sessions. If you use a Web-based macro library, you need to create a text file that identifies the specific macros that you want to be available for the session that you are configuring. If you use a shared drive-based macro library, then all the files in the specified directory will be available to the session. Users will not be allowed to write to a Web-based macro library, but they may update a shared drive-based macro library if they have write-access.
macro1.mac macro2.mac macro3.macBe sure to note the following rules:
When users open their sessions, they can use the Play Macro or Available Macros windows to see the macros specified in the list that you created for their session. These macros are available when users select Server library as their macro location. The Server library location is only available if you have configured the session to use a server macro library.
When users open their sessions, they can use the Play Macro or the Available Macros windows to see a list of the macros in the directory. These macros are available when users select Server library as their macro location. The Server library location is only available if you have configured the session to use a server macro library.
Host On-Demand sessions are defined by the administrator and retrieved by the Host On-Demand client when a user accesses a Host On-Demand HTML file. The session properties a user sees are fixed values and consist of a combination of the administrator's initial configuration and any user updates. However, there may be times when it would be useful with some HTML files, or with certain session properties, to dynamically set a value at the time that the HTML is accessed. This type of control allows you to set particular session property values based on information such as the IP address of the client or the time of day.
In order to dynamically set session properties at the time the HTML is accessed, the administrator must write a program that runs on the Web server and effectively modifies the HTML just before it is sent to the client. Even though the initial session properties are not defined in the HTML, Host On-Demand provides the capability to override many of the session properties in the HTML. These override values are always used by the client and take precedence over both the initial session properties setup by the administrator, as well as any updates for the property made by the user. The HTML override value is never stored, so the client will return to using prior settings for the property whenever the administrator removes the override. Also, the overridden property is locked so a user cannot change it.
There are many ways in which an administrator could write a program to dynamically set one or more session properties using the HTML overrides, such as using Java Server Pages (JSP), servlets, Perl, REXX, or Active Server Pages (ASP). This chapter takes you through a couple of examples that focus on common administrator issues. These examples are meant to demonstrate the syntax and technique of overriding particular properties. These mechanisms apply to whichever programming approach the administrator may choose.
The initial HTML file should be created using the Deployment Wizard, which will allow you to set up the features that are important to you, such as the size of the downloaded code and the functions available to your users. The following sections describe the HTML parameters you will need to include. However, keep in mind that the exact format required for these parameters will vary depending on the format of the HTML. Note that in Host On-Demand 7 and later, some of the HTML is generated using JavaScript, and HTML parameters are specified within a JavaScript array or using JavaScript document.write statements. Also, the format of the HTML varies according to the client (cached or download client) selected.
To set the code base when creating an HTML using the Deployment Wizard, do the following:
The HTML file is now located in the same directory with the Host On-Demand's archive files.
Code base refers to the installed Host On-Demand publish directory and not the directory where Deployment Wizard files are published. Although you can enter a fully qualified URL in the Code base field, we strongly recommend that you enter the relative path /hod/ for the default publish directory when modifying session properties dynamically. If you enter a fully qualified URL, any users who specify the host name in a different manner than you specified as the Code base will not be able to access the files, even if the DNS entries resolve to the same IP address.
![]() |
For more information about Code base and which files are created by the Deployment Wizard, refer to the Deployment Wizard chapter in the Host Access Client Package redbook on the IBM redbooks Web site at http://www.redbooks.ibm.com. |
Add a parameter to the HTML file called ConfigBase. Similar to defining /hod/ as the Codebase in Setting the Code base, the ConfigBase parameter is necessary because you will eventually deploy your JSP file to a location that is different than the default publish directory, and the Host On-Demand applet needs to know how to find the session configuration files located in the hostondemand/HOD/HODData directory. These files are created at the same time you save your Deployment Wizard HTML file to the publish directory. Unlike Codebase, the ConfigBase parameter requires a fully qualified URL. ConfigBase is a term that is specific to Host On-Demand.
![]() |
For more information, refer to Developing JavaServer Pages files with WebSphere extensions. |
There are several steps you must follow in order to dynamically set session properties (the examples shown later in this chapter will help clarify how some of these parameters should be specified):
The following table describes the session properties that can be overridden and gives the acceptable values for each parameter:
Parameter name | Description | Valid values |
---|---|---|
Host | Host name or IP address of the target server. Appears as "Destination address" on property panels. Applies to all session types. | Host name or IP address. |
HostBackup1 | Host name or IP address of the backup1 server. Appears as "Destination address" of backup1on property panels. Applies to all session types. | Host name or IP address. |
HostBackup2 | Host name or IP address of the backup2 server. Appears as "Destination address" of backup2on property panels. Applies to all session types. | Host name or IP address. |
Port | The port number on which the target server is listening. Appears as "Destination port" on property panels. Applies to all session types. | Any valid TCP/IP port number. |
PortBackup1 | The port number on which the backup1 server is listening. Appears as "Destination port" of backup1 on property panels. Applies to all session types. | Any valid TCP/IP port number. |
PortBackup2 | The port number on which the backup2 server is listening. Appears as "Destination port" of backup2 on property panels. Applies to all session types. | Any valid TCP/IP port number. |
CodePage | The codepage of the server to which the session will connect. Appears as "Host Code-Page" on property panels. Applies to all session types except FTP. | The numeric portion (for example, 037) of the supported host codepage listed in the session property panel. |
SessionID | The short name you want to assign to this session (appears in the OIA). It must be unique to this configuration. Appears as "Session ID" on property panels. Applies to all session types. | One character: A-Z. |
LUName | The name of the LU or LU Pool, defined at the target server, to which you want this session to connect. Appears as "LU or Pool Name" on property panels. Applies to 3270 Display and 3270 Printer session types. | The name of an LU or LU Pool. |
LUNameBackup1 | The name of the LU or LU Pool, defined at the backup1 server, to which you want this session to connect. Appears as "LU or Pool Name" of backup1 on property panels. Applies to 3270 Display and 3270 Printer session types. | The name of an LU or LU Pool. |
LUNameBackup2 | The name of the LU or LU Pool, defined at the backup2 server, to which you want this session to connect. Appears as "LU or Pool Name" of backup2 on property panels. Applies to 3270 Display and 3270 Printer session types. | The name of an LU or LU Pool. |
WorkstationID | The name of this workstation. Appears as "Workstation ID" on property panels. Applies to 5250 Display and 5250 Print session types. | A unique name for this workstation. |
ScreenSize | Defines the number of rows and columns on the screen. Appears as "Screen Size" on property panels. Applies to 3270 Display, 5250 Display, and VT Display session types. |
|
SLPScope | Service Location Protocol (SLP) Scope. Appears as "Scope" under "SLP Options" on property panels. Applies to 3270 Display, 3270 Printer, 5250 Display, and 5250 Printer session types. | Contact your administrator to get the correct value for this field. |
SLPAS400Name | Connects a session to a specific IBM System i5. Appears as "iSeries Name (SLP)" on property panels. Applies to 5250 Display and 5250 Printer session types. | The fully-qualified SNA CP name (for example, USIBMNM.RAS400B). |
SSLCertificateSource | The certificate can be kept in the client's browser or dedicated security device, such as a smart card; or, it can be kept in a local or network-accessed file. Appears as "Certificate Source" on property panels. Applies to 3270 Display, 3270 Printer, 5250 Display, 5250 Printer, and VT Display session types. | The value is SSL_CERTIFICATE_IN_CSP for a certificate in a browser or security device. The value is SSL_CERTIFICATE_IN_URL for a certificate in a URL or file. |
SSLCertificateURL | Specifies the default location of the client certificate. Appears as "URL or Path and Filename" in property panels. Applies to 3270 Display, 3270 Printer, 5250 Display, 5250 Printer, and VT Display session types. | The URL protocols you can use depend on the capabilities of your browser. Most browsers support HTTP, HTTPS, FTP, and FTPS. |
FTPUser | Specifies the user ID the session uses when connecting to the FTP server. Appears as "User ID" on property panels. Applies to FTP session types. | A valid user ID. |
FTPPassword | Specifies the password the session uses when connecting to the FTP server. Appears as "Password" on property panels. Applies to FTP session types. | A valid password. |
UseFTPAnonymousLogon | Enables the session to log in to an FTP server using anonymous as the user ID. Appears as "Anonymous Login" on property panels. Applies to FTP session types. | Yes or No. |
FTPEmailAddress | Specifies the e-mail address to use when connecting to the FTP server while using Anonymous Login. Appears as "E-mail Address" on property panels. Applies to FTP session types. | A valid e-mail address. |
PromptForDestinationAddress | Specifies whether to prompt the user for the destination address to use when connecting to the FTP server. Appears as "Destination Address" on property panels. Applies to FTP session types. | yes or no |
CICSInitialTransEnabled | Enables an initial transaction to be started when a CICS Gateway session is established. | true or false |
CICSInitialTrans | Specifies the name of the initial transaction to be started upon connection to a CICS host. Applies to CICS Gateway sessions only. The CICSInitialTransEnabled parameter must be set to true for the specified transaction to be started. | Valid transaction identifiers are strings of between 1 and 128 characters. The string identifies the initial transaction and any parameters to be run upon connection to the server. The first four characters, or the characters up to the first blank in the string are taken as the transaction. The remaining data is passed to the transaction on its invocation. |
Netname | The name of the terminal resource to be installed or reserved. If this field is blank, the selected terminal type is not predictable. Applies to CICS sessions only. | A valid terminal resource name. |
Any errors encountered in processing the HTML parameters are displayed in the Java Console.
Administrators may want to avoid specifying LU names directly in session definitions. This example shows a simple way of using the IP address of the client to look up an LU name listed in a text file and use it as an override value in a session.
This example is written using JSP. The Deployment Wizard was used to create an HTML file that contains two sessions named 3270 Display and 5250 Display. Note that in Host On-Demand 7 and later, some of the HTML is generated using JavaScript, and HTML parameters are specified within a JavaScript array or using JavaScript document.write statements. Also, the format of the HTML varies according to the client(cached or download client) selected.
This example uses a cached Java 2 page to start from with the needed changes for HTML overrides in bold. When the Deployment Wizard is used to generate a cached Java2 page it generates the following files:
A Macintosh client makes use of the Example_J2.html page.
A file (c:\luname.table) is read that contains IP address/LU name pairs. The IP address of the client is used to look up the proper LU name, which is overridden in the "3270 Display" session. See the comments in the example for more detail. The lines added to the Deployment Wizard output are displayed in bold.
<!doctype html public "-//W3C//DTD HTML 3.2 Final//EN"> <% // Read the luname.table file into a properties variable. // The luname.table file contains lines in the following format: // ipaddress=luname Properties lunames = new Properties(); lunames.load(new FileInputStream("c:\\luname.table")); %> <HTML> <HEAD> <META http-equiv="content-type" content="text/html; charset=UTF-8"> <!-- TITLE Begin --> <TITLE>Example1 page title</TITLE> <!-- TITLE End --> <!-- SUMMARY Begin --> <!-- Configuration Model What configuration model would you like to use? -HTML-based model Host Sessions -3270 Display -5250 Display Additional Options -Cached = Cached client -Java Type = java2 Disable Functions Preload Options -5250 Sessions = True -Change Session Properties = True -3270 Sessions = True Cached Client/Web Start Options Basic Options -Debug = False -Height (in pixels) = 250 -Width (in pixels) = 550 Upgrade Options -Percent of users who can upgrade by default = 100 -Prompt user (user decides foreground or background) Advanced Options HTML parameters -None Code base - /hod/ HTML templates -Default Problem determination -Debug = False User updates -Persist user updates? = True Appearance -Standard Host On-Demand Client Applet size -Autosize to browser Session Manager API -Enable Session Manager JavaScript API = False Server connection Language -Locale = Use the system Locale Maximum sessions - 26 --> <!-- SUMMARY End --> </HEAD> <BODY BACKGROUND="/hod/hodbkgnd.gif"> <CENTER> <IMG src="/hod/hodlogo.gif" ALT="hodlogo.gif"> <P> <SCRIPT LANGUAGE="JavaScript"> function writeAppletParameters() { return ""; } </SCRIPT> <SCRIPT LANGUAGE="JavaScript" SRC="/hod/HODVersion.js"></SCRIPT> <SCRIPT LANGUAGE="JavaScript" SRC="/hod/CommonJars.js"></SCRIPT> <SCRIPT LANGUAGE="JavaScript" SRC="/hod/CommonParms.js"></SCRIPT> <SCRIPT LANGUAGE="JavaScript" SRC="/hod/CommonJ2Parms.js"></SCRIPT> <SCRIPT LANGUAGE="JavaScript"> var db = parent.location; var hod_Locale = ''; var hod_AppName =''; var hod_AppHgt = '340'; var hod_AppWid = '550'; var hod_CodeBase = '/hod/'; var hod_Comps = 'HABASE;HODBASE;HODIMG;HACP;HAFNTIB;HAFNTAP;HA3270;HODCFG;HA5250'; var hod_Archs = 'habasen.jar,hodbasen.jar,hodimg.jar,hacp.jar,hafntib.jar,hafntap.jar, ha3270n.jar,hodcfgn.jar,ha5250n.jar'; var hod_URL = new String(window.location); var hod_DebugOn = false; // put cached client installation applet parameters here var hHod_AppletParams = new Array; hHod_AppletParams[0] = '<PARAM NAME="DebugCachedClient" VALUE="false">'; hHod_AppletParams[1] = '<PARAM NAME="ShowDocument" VALUE="_parent">'; hHod_AppletParams[2] = '<PARAM NAME="CachedClient" VALUE="true">'; hHod_AppletParams[3] = '<PARAM NAME="ParameterFile" VALUE="HODData\\Example1\\params.txt">'; hHod_AppletParams[4] = '<PARAM NAME="JavaScriptAPI" VALUE="false">'; hHod_AppletParams[5] = '<PARAM NAME="BookmarkPage" VALUE="Example1.html">'; // The next 2 lines are required in order to override session properties. // The first line turns on the processing for this function and does not // need to be modified. The second line identifies the sessions that you // want to change. In this example, there are 2 sessions identified // named: "3270 Display" and "5250 Display". hHod_AppletParams[6]='<PARAM NAME="EnableHTMLOverrides" VALUE="true">'; hHod_AppletParams[7]='<PARAM NAME="TargetedSessionList" VALUE="3270 Display,5250 Display">'; // The following line changes the LUName session parameter for the session named // "3270 Display". In this example, the LUName is being set to the value // contained in the c:\luname.table for the IP address of the client. // When you are initially testing your changes, you may want to use a constant // value to verify that the syntax is correct before you insert your // calculations. hHod_AppletParams[8]='<PARAM NAME="Luname" VALUE="3270 Display=<%=lunames.get(request.getRemoteAddr())%>">'; //hHod_AppletParams[x] = '<PARAM NAME="DebugCode" VALUE="65535">'; var pg = buildJ2Page(db); pg += writeAppletParameters(); pg += '</APPLET>'; if(hod_DebugOn) alert('J2 page complete, result = \n' + pg); document.write(pg); </SCRIPT> </CENTER> </BODY> </HTML>
Administrators may also want to use HTML forms to specify override values rather than calculating them. The following example displays a simple form for entry of a host name. The form posts to a JSP program which uses the host name specified in the form to override the host name in the 3270 Session.
This example is written using JSP. The Deployment Wizard was used to create an HTML file that contains two sessions named "3270 Display" and "5250 Display." Note that in Host On-Demand 7 and later, some of the HTML is generated using JavaScript, and HTML parameters are specified within a JavaScript array or using JavaScript document.write statements. Also, the format of the HTML varies according to the client (cached or download client) selected.
When using forms, the form data needs to be retained across requests to the program. This is because Host On-Demand HTML files reload themselves for Java detection and for bookmarking support when using configuration server-based model pages. If Java 1 is selected and bookmarking support is disabled if using the configuration server-based model, the page will not need to reload and there is no need to retain the form data. This example uses a JSP session to store the form data across reloads.
Here is a simple HTML form that allows for entry of a host name. The form posts to the JSP program (example2.jsp):
<form method="POST" action="hod/example2.jsp"> Hostname <input name="form.hostname"><br> <input type="submit"> </form>
Here is the modified output from the Deployment Wizard. See the comments in the example for more detail. The lines added to the Deployment Wizard output are displayed in bold.
<HTML> <% // Get a session or create if necessary and store the hostname // entered in the form in the session. HttpSession session = request.getSession(true); String hostname = request.getParameter("form.hostname"); if (hostname!=null) { session.putValue("session.hostname", hostname); } %> <!-- HOD WIZARD HTML --> <!-- Deployment Wizard Build : 8.0.0-B20030605 --> <HEAD> <META http-equiv="content-type" content="text/html; charset=UTF-8"> <TITLE>Example 2 page title</TITLE> <SCRIPT LANGUAGE="JavaScript" SRC="/hod/CommonJars.js"></SCRIPT> <SCRIPT LANGUAGE="JavaScript" SRC="/hod/HODJavaDetect.js"></SCRIPT> <SCRIPT LANGUAGE="JavaScript" SRC="/hod/CommonParms.js"></SCRIPT> <SCRIPT LANGUAGE="JavaScript"> //---- Start JavaScript variable declarations ----// var hod_Locale = ''; var hod_jsapi=false; var hod_AppName =''; var hod_AppHgt = '80%'; var hod_AppWid = '80%'; var hod_CodeBase = '/hod/'; var hod_FinalFile = 'z_example2.html'; var hod_JavaType = 'java2'; var hod_Obplet = ''; var hod_jars = 'habasen.jar,hodbasen.jar,hodimg.jar,hacp.jar,hodsignn.jar,ha3270n.jar, hodcfgn.jar,ha5250n.jar'; var hod_URL = new String(window.location); var hod_DebugOn = false; var hod_SearchArg = window.location.search.substring(1); var hod_AppletParams = new Array; hod_AppletParams[0] = '<PARAM NAME="ParameterFile" VALUE="HODData\\example2\\params.txt">'; hod_AppletParams[1] = '<PARAM NAME="ShowDocument" VALUE="_parent">'; hod_AppletParams[2] = '<PARAM NAME="JavaScriptAPI" VALUE="' + hod_jsapi + '">'; hod_AppletParams[3] = '<PARAM NAME="PreloadComponentList" VALUE="HABASE;HODBASE;HODIMG; HACP;HAFNTIB;HAFNTAP; HA3270;HODCFG;HA5250">'; // The next 2 lines are required in order to override session properties. // The first line turns on the processing for this function and does not // need to be modified. The second line identifies the sessions that you // want to change. In this example, there are 2 sessions identified // named: "3270 Display" and "5250 Display". // Be careful to increment the array index correctly. hod_AppletParams[4] = <PARAM NAME="EnableHTMLOverrides" VALUE="true">; hod_AppletParams[5] = <PARAM NAME="TargetedSessionList" VALUE="3270 Display,5250 Display">; // The following line changes the Host or Destination Address session parameter // for the session named "3270 Display". In this example, the Host is being set // to the value saved in the JSP session from the HTML form. // When you are initially testing your changes, you may want to use a constant // value to verify that the syntax is correct before you insert your // calculations. // Here we override the host for the 3270 session to the value saved in the // jsp session from the html form. hod_AppletParams[6] = <PARAM NAME="Host" VALUE="3270 Display=<%=session.getValue("session.hostname")%>">; //hod_AppletParams[x] = '<PARAM NAME="DebugCode" VALUE="65535">'; //---- End JavaScript variable declarations ----// function getHODMsg(msgNum) { return HODFrame.hodMsgs[msgNum]; } function getHODFrame() { return HODFrame; } var lang = detectLanguage(hod_Locale); document.writeln('<FRAMESET cols="*,10" border=0 FRAMEBORDER="0">'); document.writeln('<FRAME src="/hod/hoddetect_' + lang + '.html" name="HODFrame">'); document.writeln('</FRAMESET>'); </SCRIPT> </HEAD> </HTML>
This chapter describes how to set up separate read/write private and publish directories for configuring Host On-Demand on a zSeries system.
The purpose of this configuration scenario is to provide instructions for common zSeries configuration tasks.
See the product installation documentation (found in the Program Directory) for detailed instructions on setting up Host On-Demand on zSeries.
This chapter also provides details about removing the ASCII file extension from Host On-Demand files.
When Host On-Demand is installed, files in the /usr/lpp/HOD/hostondemand/private directory are updated in an execution environment, not just by manufacturing refresh releases. Because this directory is now updated during the Host On-Demand software's execution, it is recommended that you mount a separate (non-service) HFS. You can do this in one of the following ways:
ln -s /etc/HOD/private /usr/lpp/HOD/hostondemand/private
Customers running in a sysplex environment using SHARED HFS support can install the Host On-Demand SMP/E managed code in the VERSION HFS, which must be mounted with READ ONLY privileges in a SHARED HFS environment. Make the /private directory a system-specific HFS mounted with READ WRITE privileges, with a symbolic link pointing to the /usr/lpp/HOD/hostondemand/private directory.
If you are using LDAP and native authentication, manually copy the HODrapd and /keys directory to the system-specific /private directory.
When the system-specific /private directory is mounted, it overlays but does not destroy the master /private directory. When maintenance releases are applied, use the master /private directory. If these files were changed, copy them to the system-specific /private directory.
Files generated from the Deployment Wizard can be placed in a user-defined directory that is separate from the Host On-Demand publish directory. This makes it easier to apply future Host On-Demand upgrades. It also simplifies installing and maintaining Host On-Demand on z/OS systems where the SMP/E installed libraries must not contain user modifications (the file systems are mounted read-only). This solution keeps the Host On-Demand publish directory read only and provides a separate writeable location for deploying Deployment Wizard files.
For instructions on deploying Deployment Wizard files in a separate user publish directory and for information on other user-modified files that can be placed outside the publish directory, see Backing up files and directories.
Host On-Demand customers who use the zSeries platform might want to use the following two tools to remove the ASCII file extension from their Host On-Demand HTML, TXT, CSS, JS, PROPS, and PROPERTIES files. Typical customers who might benefit from these tools are those who serve Host On-Demand through IBM WebSphere Application Server.
The first tool is a shell script called hodAscii.sh, which can be found in the Host On-Demand product samples S390 directory, for example, usr/lpp/HOD/hostondemand/lib/samples/zSeriesCommandFiles. This script removes the ASCII file extension from all files that are included in the Host On-Demand publish directory and subdirectories. Note that you might need to update your Web server's Pass directives to reflect the changed file extensions. Optionally, this script can also remove the ASCII extension from Deployment Wizard files that are located in a separate user publish directory. The script has an undo feature that allows users to reappend the ASCII extension. Note that if Host On-Demand is installed in a path other than the default path, the hodAscii.sh script must be modified to reflect the correct installation path.
The second tool is an enhancement to the DWunzip-S390 utility, which can be found in the Host On-Demand product samples directory in DWunzipCommandFiles subdirectory. The DWunzip tool unzips a Deployment Wizard zip file, places the files into the appropriate directories, appends the ASCII file extensions, and sets files permissions and ownerships on the files and directories. The enhancement allows you to choose whether or not you want to append the ASCII extension to the files. You can set this option inside the DWunzip-S390 script with an environment variable called ADD_ASCII_EXTENSION.
When upgrading from a previous level of Host On-Demand, you will probably want to take into consideration previous customizations. Allocate a new HFS, then follow the installation procedure. Copy your existing private directory into the new HFS using the pax or tar command. Refer to Backing up the private directory.
The private directory can be backed up using either the pax command or the tar command. Assume the current private directory is for HOD V7:
After you install Host On-Demand on the IBM System i5 platform, configure the software as follows:
A menu is provided for starting and stopping the Host On-Demand Service Manager. To access the menu, type the following on the i5/OS or OS/400 command line:
GO HOD
The following commands can be used from the menu or the i5/OS or OS/400 command line.
To configure the Service Manager, choose option 1. You need *JOBCTL and *ALLOBJ authority to use this option. You can configure the following information:
There are multiple screens. You may need to page down to see the next screen.
To start the Host On-Demand Service Manager, choose option 2. You need *JOBCTL authority to use this option.
The Service Manager can be automatically started each time that the associated subsystem starts. One way to do this is to add the STRHODSVM command to the system startup program.
To determine whether the Service Manager is running, use the following command:
WRKJOB QHODSVM
To stop the Service Manager, choose option 3. You need *JOBCTL authority to use this option.
Use this option to view the current status of the Host On-Demand Service Manager.
Use this option to work with SSL certificates in one of the Host On-Demand keyrings. Refer to Planning for security for general information on SSL related sessions.
In the event that you need to contact the IBM Support Center for assistance, use this menu option to gather information about your Host On-Demand configuration.
Use this menu option to create a custom printer definition table for Host On-Demand 3270 printer sessions. A custom printer definition may be necessary if you have a special paper form or if the printer is not supported. Refer to Section 16.5 in the Host Access Client Package Redbook (SG24-6182-00) for additional information.
Use this menu option to start the Client Access Organizer for the workstation.
Use this menu option to run a command on your local workstation. You will need to start the Client Access Organizer for the workstation before using this menu option.
To use the Deployment Wizard to deploy screens to an IBM System i5-based Host On-Demand server, do the following:
The IBM System i5 servers can be configured to use certificates from a public signing agency or from a private certificate management system, like the IBM System i5 Digital Certificate Manager. Before you enable SSL, decide which type of certificate to use. Refer to the IBM System i5 Web site at http://publib.boulder.ibm.com/infocenter/iseries/v5r3/ic2924/index.htm for more information.
You must have the following programs installed to use SSL with IBM System i5:
The following list provides a high-level overview of the steps needed to install and configure Host On-Demand with SSL:
Visit http://publib.boulder.ibm.com/infocenter/iseries/v5r3/ic2924/index.htm and search on 'Telnet SSL' to learn the steps you need to take to enable Telnet with SSL. You will need to repeat the steps for each IBM System i5 system that you wish to use secure connections with.
If you are using self-signed certificates or certificates from a signing agency that is not in the well-known list, complete the following steps to configure a CustomizedCAs keyring:
server.name:portwhere server.name is the TCP/IP name of the target server (for example, my400.myco.com) and port is the port for the target server (for example, 992).
This command can take a few minutes to complete. If you are prompted for a password, press the Enter key. If this is the first certificate, a new CustomizedCAs object is created.
To view the contents of the CustomizedCAs keyring, do the following:
![]() |
If you have multiple IBM System i5 machines and would like to create a single certificate that all the machines can use, consider cross certification. Refer toIBM System i5 Wired Security: Protecting Data over the Network, OS/400 Version 5 Release 1DCM and Cryptographic Enhancements (SG24-6168) for additional information about cross certification. |
For additional security, consider SSL with client authentication to tightly control who can Telnet to your system over the Internet. For example, you can configure the Telnet server to only allow authentication if the client certificate was issued by your IBM System i5 (through Digital Certificate Manager).
The client certificates have a limited validity period (for example, 90 days). When the certificate expires, the user must perform the Client Certificate Download process in order to continue. This process requires a valid IBM System i5 user ID and password.
![]() |
Not all Telnet client software is capable of client authentication. When enabled, all SSL-enabled Telnet connections to the IBM System i5 require a user certificate. |
Refer to the IBM System i5 Web site at http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp for more information.
The OS/400 proxy can be configured to encrypt file transfer and Database On-Demand connections. To do this, the following additional software must be installed on each target IBM System i5:
You need to control authorization of the users to the files. To help you to meet the SSL legal responsibilities, you must change the authority of the directory that contains the SSL files to control user access to the files. In order to change the authority, do the following:
STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
Repeat the above steps for each target IBM System i5 server.
If any of the target connections is using self-signed certificates or certificates from a signing agency that is not on the well-known list, do the following:
server.name:portwhere server.name is the TCP/IP name of the target server (for example, my400.myco.com) and port is the port for the sign-on server (for example, 9476).
This command can take a few minutes to complete. If you are prompted for a password, press the Enter key. If this is the first certificate, a new KeyRing.class object is created.
The Host On-Demand server uses the Web server to download program objects to the browser. This information can be encrypted, but with a considerable performance impact. Refer to the redbook AS/400 HTTP Server Performance and Capacity Planning (SG24-5645) for more information.
The default port for secure web serving is 443. If that port is not enabled, port 80 is used. To enable secure web serving, perform the following steps:
STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
ENDTCPSVR SERVER(*HTTP) HTTPSVR(DEFAULT)
STRTCPSVR SERVER(*HTTP) HTTPSVR(DEFAULT)
For more information on a wide variety of IBM System i5 topics, see www.redbooks.ibm.com/tstudio.
In a 5250 Display session, Host On-Demand supports the display of Unicode data located in fields tagged with Coded Character Set Identifiers (CCSIDs). For more information see the following:
For host programming information, refer to the IBM System i5 Web site at http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp.
As an alternative to accessing Host On-Demand through an HTML file, users can access it through Portal Server, which is a component of WebSphere Portal. Portal Server provides a framework for plugging content extensions known as portlets into a Web site. Portlets are applications that run within Portal Server. They organize content from different sources (such as Web sites, e-mail, and business applications) and display it on a single HTML file in a browser window. The WAR files generated by the Deployment Wizard used to launch Host On-Demand sessions can be deployed as portlets, enabling users to access Host On-Demand through the portal interface. If you are planning to use Host On-Demand and Portal Server in conjunction with a firewall, refer to Using Host On-Demand with a firewall. Also, if you are planning to use security features of WebSphere Portal, such as the user's Portal ID or the Portal Server Credential Vault, refer to the Web Express Logon Reference.
Both Host On-Demand and Portal Server must be installed to run a Host On-Demand portlet.
Figure 8 shows how Host On-Demand works with Portal Server.
To use Host On-Demand with Portal Server, you need a Host On-Demand portlet. You can quickly and easily create your own custom portlets using the Deployment Wizard. See the Deployment Wizard online help for details about creating portlets. You can also download sample Host On-Demand portlets from the Host On-Demand Service Key site at http://www6.software.ibm.com/aim/home.html on the Host On-Demand manufacturing refresh page under Tools and Utilities.
After you create a custom portlet or obtain a sample one, you can import it directly into Portal Server just like any other portlet. Refer to the WebSphere Portal for Multiplatforms Web site at http://www.ibm.com/software/webservers/portal/library.html for more details.
The Portal environment supports full Host On-Demand functionality with the following limitations:
When using Host On-Demand with Portal Server, you may want to consider the following issues:
Now, the client's browser will request Host On-Demand files from the same host as the portal, but these requests will be internally rerouted by the Web server to the actual location of your Host On-Demand install.
![]() |
User preferences are stored in WebSphere Portal only if you have granted users the appropriate access to the portlet and the Web page that will access the portlet. WebSphere Portal V5 users must have Privileged User, Editor, Manager, or Administrator access. For more information about how to grant access to users, refer to WebSphere Portal documentation. |
![]() |
User preferences are stored in WebSphere Portal only if you have granted users the appropriate access to the portlet and the Web page that will access the portlet. WebSphere Portal V5 users must have Privileged User, Editor, Manager, or Administrator access. For more information about how to grant access to users, refer to WebSphere Portal documentation. |
Under certain circumstances, you may wish to modify the appearance or functionality of your Host On-Demand portlets. Here are some tips and guidelines to help you extend your portlets:
This chapter describes how to set up Host On-Demand for the IBM Workplace Client Technology (WCT).
WCT is the foundation for next-generation, network-centric computing. Built on the Eclipse rich client platform, it provides additional features for managing and deploying applications easily to end users. For more technical details of WCT, refer to "IBM Workplace Client Technology architecture" at http://www.ibm.com/developerworks/lotus/library/wct-architecture/
On WCT, all applications are packaged as Eclipse "features", which consist of "plugins" and "fragments". Eclipse features are usually installed from an "update site", which is a directory on a machine that is web-accessible.
In order to build the Host On-Demand plugin for WCT, Host On-Demand provides a Java applet called "Update Site Utility". The Update Site Utility converts Host On-Demand jar files into Eclipse plugins and fragments and places them in a new or an existing update site directory.
Procedures to install features from an update site are different depending on WCT platforms, such as Workplace Managed Client (WMC) or WebSphere Everyplace Deployment (WED). When WMC is used, extra configuration steps are required on its server counterpart, Workplace Collaboration Service (WCS). The Update Site Utility generates an XML file, which eases the configuration steps on WCS.
To create and deploy these Host On-Demand plugins to run in WCT, do the following:
For example, if you want to use the Java plugin that is shipped by Host On-Demand server for Linux, use export command to set the LD_LIBRARY_PATH environment variable as follows:
export LD_LIBRARY_PATH=/opt/ibm/HostOnDemand/hod_jre/jre/bin: $LD_LIBRARY_PATH
Host On-Demand plugin | Plugin itself. File name is given in the form: com.ibm.eNetwork.HOD.wct_(plugin version).jar |
Host On-Demand code fragment | Host On-Demand runtime code. File name is given in the form: com.ibm.eNetwork.HOD.wct.(function name)_(plugin version).jar |
Config fragment | Fragment that stores configuration information. File name is given in the form: com.ibm.eNetwork.HOD.wct.configs.(deployment wizard output file name)_(feature version).jar |
For information about installing the plugin on the client, refer to documents that come with your WCT platforms.
On WCT platform, HTML overrides cannot be used in order to dynamically set session properties because no HTML files are used for running the Host On-Demand plugin. If you need to have the similar functionality, do the following steps:
public String setHodHtmlFileName() public Properties getHodHtmlParameters()
Following is an example of such Java classes:
package com.ibm.eNetwork.HOD.wct.samples; import java.util.Properties; import com.ibm.eNetwork.HOD.wct.IHODConfigFactory; public class ConfigOverride implements IHODConfigFactory { /* (non-Javadoc) * @see com.ibm.eNetwork.HOD.wct.IHODConfigFactory#getHodHtmlFileName() */ public String getHodHtmlFileName() { return "hodwmc"; } /* (non-Javadoc) * @see com.ibm.eNetwork.HOD.wct.IHODConfigFactory#getHodHtmlParameters() */ public Properties getHodHtmlParameters() { Properties p = new Properties(); p.put("EnableHTMLOverrides", "true"); p.put("TargetedSessionList", "3270 Display"); p.put("host", "3270 Display=hostname"); return p; }
var showUserClass="true";
When you are using a separate user publishing directory other than the Host On-Demand publish directory, you need to specify the directory on Update Site Utility with the following procedure:
var showAlternatePublishDirectory ="true";
Following is the list of view IDs used by Host On-Demand plugin. You may need to know those IDs when you configure page layout on WCS manually.
ID | Description |
---|---|
com.ibm.eNetwork.HOD.wct.SessionsView | Configured Sessions |
com.ibm.eNetwork.HOD.wct.SessionLabelsView | Active Sessions |
com.ibm.eNetwork.HOD.wct.TerminalView | Terminal (Display, Printer, FTP, etc.) |
Following are limitations not mentioned above on using Host On-Demand in a WCT environment:
The Host On-Demand Server is used to manage configuration data for the configuration server-based and combined models. For the default operational mode of the Host On-Demand Server, this data is saved in a non-shared private data store. Some enterprise customers need to manage their configuration information between multiple Host On-Demand servers. If these customers use the non-shared private data store, then their administrators must manage the data for each Host On-Demand Server separately. A Lightweight Directory Access Protocol (LDAP) server directory provides the ability to share user and group configuration information over different instances of the Host On-Demand configuration server.
Using an LDAP directory server to manage and share your definitions across multiple Host On-Demand servers is an option that must be carefully planned and executed. Migration from the private data store, in particular, has implications on the configuration data. LDAP enables the customer to manage the configuration information by arranging users into a hierarchical tree of groups. If existing users are members of more than one group, then some information will be lost. Note that the configuration data in the private data store is not changed when a migration to LDAP occurs. Refer to implications of migrating to LDAP in the Host On-Demand online help for more detailed information.
![]() |
Users and groups that are already defined in LDAP for other purposes are not used by Host On-Demand. Users and groups for Host On-Demand must be defined separately by either migrating the configuration information from the private data store or by setting up the users and groups in Host On-Demand after enabling LDAP. |
![]() |
If you are using the IBM LDAP server on Windows and
AIX platforms, and you are creating a large number of users, make sure that
DB2 is configured with the proper value for APP_CTL_HEAP_SZ. While the value
for this variable is dependent on individual installations, setting APP_CTL_HEAP_SZ
to 512 is a good starting value.
To configure DB2 heap size in a Windows or AIX environment, issue these commands:
Also, be sure that STMTHEAP is large enough. The size for these parameters are dependent solely on individual customer configurations and the number of Host On-Demand users that are being migrated to LDAP. |
The Host On-Demand extensions to the LDAP directory schema are provided in several files that are located in the LDAP subdirectory of the publish directory (for example, your_install_directory\HOD\ldap, where your_install_directory is your Host On-Demand installation directory). These files contain extensions to the LDAP schema and are stored in the standard slapd format. The schema extensions must be in effect before Host On-Demand can store configuration information in an LDAP server. Contact your LDAP administrator to have these schema extensions installed.
Refer to the Program Directory for instructions on installing the schema extensions for the zSeries.
![]() |
Your LDAP administrator may have already installed these schema extensions for use by another IBM product. If so, skip these steps. If you are using the IBM Directory Server Version 3.1.1 or later, the schema is pre-installed, so you can skip these steps also. |
To install the Host On-Demand schema extensions on a Netscape LDAP Directory server:
Netscape.IBM.at Netscape.IBM.oc
userat "<Netscape LDAP config directory>/Netscape.IBM.at" useroc "<Netscape LDAP config directory>/Netscape.IBM.oc"
To install the Host On-Demand schema extensions on an IBM LDAP Directory server:
V2.1.IBM.at V2.1.IBM.oc
include /etc/V2.1.IBM.at
include /etc/V2.1.IBM.oc
![]() |
The Redirector configuration is not migrated to the directory server. |
![]() |
If you have a problem connecting to LDAP and migrating, try to connect to LDAP first. Then, after successfully connecting, try to migrate. |
When you are asked to authenticate with the LDAP directory for the first time, specify a user ID of "admin" and a password of "password". You can change this password after the first log on. Even though you might have changed your password for the private data store, that ID and password continues to be valid for the private data store only. For the LDAP directory, a separate user ID and password are required. To avoid confusion, you can change your LDAP directory password to be the same as your private data store password.
Changes made on this panel are effective immediately. Once you have switched to the LDAP server, subsequent user-related changes will be made only on the LDAP server, including administrative changes to groups, users, or sessions, and changes such as new passwords, macros, keyboard changes, etc., by either the administrator or a user.
The locally installed client installs to a local disk. The client applet is loaded directly into the default system browser, so there is no download from a server. The most common reason to configure a local client is for users who connect remotely over slow telephone lines, where download time can be an issue and connectivity is unpredictable. You can also use the locally installed client to test host access capabilities without installing the full Host On-Demand product.
Host On-Demand can be installed as a client on the following operating systems:
The locally-installed client requires approximately 320 MB of disk space.
To install the Host On-Demand local client on a Windows 2000, Windows 2003, or Windows XP workstation, you must be a member of the Administrators group.
At the end of installation, the Host On-Demand Service Manager is configured and started automatically. On Windows 2000, Windows 2003, and Windows XP, the Service Manager is installed as a Service.
To start Host On-Demand as a client, click Start > Programs > IBM Rational Host On-Demand > Host On-Demand.
To remove the local client, use Add/Remove Programs from the Control Panel. If InstallShield does not remove the hostondemand directory, you must remove it manually.
IKEYCMD is a command-line tool, in addition to the Host On-Demand Certificate Management Utility, that can be used to manage keys, certificates, and certificate requests. It is functionally similar to Certificate Management and is meant to be run from the command line without a graphical interface. It can be called from native shell scripts and programs to be used when applications prefer to add custom interfaces to certificate and key management tasks. It can create key database files for all of the types that the Certificate Management utility currently supports. It can create certificate requests, import CA-signed certificates and manage self-signed certificates. It is Java-based and is available only on Windows, AIX, Linux Intel and Linux zSeries platforms.
Use IKEYCMD for configuration tasks related to public-private key creation and management. You cannot use IKEYCMD for configuration options that update the server configuration file, httpd.conf. For options that update the server configuration file, you must use the IBM Administration Server.
Set up the environment variables to use the IKEYCMD command-line interface as follows:
For Windows platforms, do the following:
set PATH=c:\Program Files\IBM\HostOnDemand\hod_jre\jre\bin;%PATH%;
set CLASSPATH=c:\Program Files\IBM\GSK7\classes\cfwk.zip;C:\
Program Files\IBM\GSK7\classes\gsk7cls.jar;%CLASSPATH%;
For AIX platforms:
First ensure that your xlC files (which constitute the run-time library for the standard AIX C++ compiler) meet one of the following requirements:
Use the following command to confirm your version:
lslpp -ha "xlC.aix*.rte"
(If your xlC fileset is outdated and you start the Host On-Demand ServiceManager with Certificate Management active, errors occur.)
Next make the following specifications:
EXPORT PATH=/opt/IBM/HostOnDemand/hod_jre/jre/bin:$PATH
EXPORT CLASSPATH=/usr/local/ibm/gsk7/classes/cfwk.zip:/ usr/local/ibm/gsk7/classes/gsk7cls.jar:$CLASSPATH
Once you have completed these steps, IKEYCMD should run from any directory. To run an IKEYCMD command, use the following syntax:
java com.ibm.gsk.ikeyman.ikeycmd <command>
The syntax of the Java CLI is
java [-Dikeycmd.properties=<properties_file>]
com.ibm.gsk.ikeyman.ikeycmd <object> <action> [options]
where
Action is the specific action to be taken on the object, and options are the options, both required and optional, specified for the object and action pair.
![]() |
The object and action keywords are positional and must be specified in the selected order. However, options are not positional and can be specified in any order, provided that they are specified as an option and operand pair. |
IKEYCMD command-line interface tasks required for Host On-Demand are summarized in the following sections of this appendix:
A key database is a file that the server uses to store one or more key pairs and certificates. This is required to enable secure connections between the Host On-Demand server and clients. Before configuring SSL communication, you must create the HODServerKeyDb.kdb key database file in your_install_directory\bin for Windows and your_install_directory/bin for AIX. This file is not shipped with Host On-Demand, so you must create it after the first install.
For Windows platforms, for example, to create a new key database using the IKEYCMD command-line interface, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -keydb -create
-db your_install_directory\bin\HODServerKeyDb.kdb
-pw <password> -type cms -expire <days> -stash
where your_install_directory is your Host On-Demand installation directory.
Note the following descriptions:
When the -stash option is specified during the key database creation, the password is stashed in a file with the filename HODServerKeyDb.sth
Once the HODServerKeyDb.kdb file has been created, it holds all the security information needed by the Host On-Demand server. Any additions or changes are made to the existing HODServerKeyDb.kdb key database file.
![]() |
Whenever you create or make changes to the HODServerKeyDb.kdb file, you must stop and restart the Host On-Demand Service Manager. |
When you create a new key database, you specify a key database password. This password protects the private key. The private key is the only key that can sign documents or decrypt messages encrypted with the public key. Changing the key database password frequently is a good practice.
Use the following guidelines when specifying the password:
![]() |
Keep track of expiration dates for the password. If the password expires, a message is written to the error log. The server will start, but there will not be a secure network connection if the password has expired. |
To change the database password, do the following:
For Windows platforms, for example, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -keydb -changepw
-db your_install_directory\bin\HODServerKeyDb.kdb
-pw <password> -new_pw <new_password> -expire <days> -stash
where your_install_directory is your Host On-Demand installation directory.
Note the following descriptions:
To display a list of trusted CAs in the HODServerKeyDb.kdb key database, do the following:
For Windows platforms, for example, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -list CA
-db your_install_directory\bin\HODServerKeyDb.kdb
-pw <password> -type cms
where your_install_directory is your Host On-Demand installation directory.
By default, HODServerKeyDb.kdb comes with the CA certificates of the following well-known trusted CAs:
To create a public-private key pair and certificate request, do the following:
java com.ibm.gsk.ikeyman.ikeycmd -certreq -create
-db your_install_directory\bin\HODServerKeyDb.kdb
-pw <password> -size <1024 | 512> -dn <distinguished_name>
-file <filename> -label <label>where your_install_directory is your Host On-Demand installation directory.
Note the following descriptions:
"CN=weblinux.raleigh.ibm.com,O=ibm,OU=IBM HTTP Server,L=RTP,ST=NC,C=US"
a. View the contents of the certificate request file you created.
b. Make sure the key database recorded the certificate request:
java com.ibm.gsk.ikeyman.ikeycmd -certreq -list
-db <filename> -pw <password>
You should see the label listed that you just created.
Use this procedure to receive an electronically mailed certificate from a certificate authority (CA), designated as a trusted CA on your server. By default, the following CA certificates are stored in the HODServerKeyDb.kdb key database and marked as trusted CA certificates:
The Certificate Authority may send more than one certificate. In addition to the certificate for your server, the CA may also send additional Signing certificates or Intermediate CA Certificates. For example, Verisign includes an Intermediate CA Certificate when sending a Global Server ID certificate. Before receiving the server certificate, receive any additional Intermediate CA certificates. Follow the instructions in Storing a CA certificate to receive Intermediate CA Certificates.
![]() |
If the CA who issues your CA-signed certificate is not a trusted CA in the key database, you must first store the CA certificate and designate the CA as a trusted CA. Then you can receive your CA-signed certificate into the database. You cannot receive a CA-signed certificate from a CA who is not a trusted CA. For instructions, see Storing a CA certificate |
For Windows platforms, for example, to receive the CA-signed certificate into a key database, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -receive -file <filename>
-db your_install_directory\bin\HODServerKeyDb.kdb -pw <password>
-format <ascii | binary> -default_cert <yes | no>
where your_install_directory is your Host On-Demand installation directory.
Note the following descriptions:
For Windows platforms, for example, to store a certificate from a CA who is not a trusted CA, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -add
-db your_install_directory\bin\HODServerKeyDb.kdb
-pw <password> -label <label> -format <ascii | binary>
-trust <enable |disable> -file <file>
where your_install_directory is your Host On-Demand installation directory.
Note the following descriptions:
![]() |
You must stop and restart the Host On-Demand Service Manager after doing this. |
It usually takes two to three weeks to get a certificate from a well-known CA. While waiting for an issued certificate, use IKEYCMD to create a self-signed server certificate to enable SSL sessions between clients and the server. Use this procedure if you are acting as your own CA for a private Web network.
For Windows platforms, for example, to create a self-signed certificate, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -create
-db your_install_directory\bin\HODServerKeyDb.kdb
-pw <password> -size <1024 | 512> -dn <distinguished name>
-label <label> -default_cert <yes or no>
where your_install_directory is your Host On-Demand installation directory.
Note the following descriptions:
"CN=weblinux.raleigh.ibm.com,O=ibm,OU=IBM HTTP Server,L=RTP,ST=NC,C=US"
All the certificates in the HODServerKeyDb.kdb are available to the Host On-Demand server. However, in some of the configurations, one of these certificates must also be made available to the clients that access the server. In the cases where your server uses a certificate from an unknown CA, the root of that certificate must be made available to the client. If your server uses a self-signed certificate, then a copy of that certificate must be made available to the clients.
For Host On-Demand downloaded and cached clients, this is done by extracting the certificate to a temporary file and creating or updating a file named CustomizedCAs.p12, which should be present in the Host On-Demand publish directory.
To create the CustomizedCAs.p12 file for downloaded or cached clients, enter the following command:
java com.ibm.gsk.ikeyman -keydb -create -db
CustomizedCAs.p12 -pw hod -type pkcs12
The default password is hod.
First, extract the CA's root certificate or a self-signed certificate from the HODServerKeyDb.kdb key database file. To do this for Windows, for example, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -extract
-db your_install_directory\bin\HODServerKeyDb.kdb
-pw <password> -label <label> -target cert.arm -format ascii
where your_install_directory is your Host On-Demand installation directory.
Note the following descriptions:
Now, add this CA root certificate to the CustomizedCAs.p12 file. To add a CA root certificate or a self-signed certificate to the list of signers in CustomizedCAs.p12, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -add
-db CustomizedCAs.p12 -pw hod -label <label>
-file cert.arm -format ascii -trust <enable | disable>
For older clients, to add this CA root certificate to the CustomizedCAs.class file, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -add
-db CustomizedCAs.class -label <label>
-file cert.arm -format ascii -trust <enable | disable>
Note the following descriptions:
![]() |
Stop and restart the Host On-Demand Service Manager after completing this task. |
For older clients, you need to convert the CustomizedCAs.p12 file to CustomizedCAs.class file for download or cached clients by entering the following command. The command appears on three lines, but you should type it on one line.
..\hod_jre\jre\bin\java -cp ..\lib\sm.zip; com.ibm.eNetwork.HOD.convert.CVT2SSLIGHT CustomizedCAs.p12 hod CustomizedCAs.class
To export keys to another key database or to export keys to a PKCS12 file, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -export -db <filename>
-pw <password> -label <label> -type <cms | jks | jceks | pks12>
-target <filename> -target_pw <password>
-target_type <cms | jks | jceks | pkcs12> -encryption <strong | weak>
Note the following descriptions:
To import keys from another key database, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -import -db <filename>
-pw <password> -label <label> -type <cms | jks | jceks | pks12> -target
<filename> -target_pw <password> -target_type <cms | jks | jceks | pks12>
To import keys from a PKCS12 file,enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -import -file <filename>
-pw <password> -type pkcs12 -target <filename>
-target_pw <password> -target_type <cms | jks | jceks | pks12>
Note the following descriptions:
For Windows platforms, for example, to display the default key entry, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -cert -getdefault
-db your_install_directory\bin\HODServerKeyDb.kdb
-pw <password>
where your_install_directory is your Host On-Demand installation directory.
For a secure network connection, store the encrypted database password in a stash file. For Windows platforms, for example, to store the password while a database is created, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -keydb -create
-db your_install_directory\bin\HODServerKeyDb.kdb
-pw <password> -type cms -expire <days> -stash
where your_install_directory is your Host On-Demand installation directory.
For Windows platforms, for example, to store the password after a database has been created, enter the following command:
java com.ibm.gsk.ikeyman.ikeycmd -keydb -stashpw
-db your_install_directory\bin\HODServerKeyDb.kdb -pw <password>
where your_install_directory is your Host On-Demand installation directory.
A batch file, gsk7cmd, provides the same function of the "java com.ibm.gsk.ikeyman" command. For Windows platforms, for example, to store the password after a database has been created, you can also enter following command:
gsk7cmd -keydb -stashpw
-db your_install_directory\bin\HODServerKeyDb.kdb -pw <password>
where your_install_directory is your Host On-Demand installation directory.
The following table describes each action that can be performed on a specified object.
Object | Action | Description |
-keydb | -changepw | Change the password for a key database |
-convert | Convert the key database from one format to another | |
-create | Create a key database | |
-delete | Delete the key database | |
-stashpw | Stash the password of a key database into a file | |
-cert | -add | Add a CA certificate from a file into a key database |
-create | Create a self-signed certificate | |
-delete | Delete a CA certificate | |
details | List the detailed information for a specific certificate | |
-export | Export a personal certificate and its associated private key from a key database into a PKCS#12 file, or to another key database | |
-extract | Extract a certificate from a key database | |
-getdefault | Get the default personal certificate | |
-import | Import a certificate from a key database or PKCS#12 file | |
-list | List all certificates | |
-modify | Modify a certificate (NOTE: Currently, the only field that can be modified is the Certificate Trust field) | |
-receive | Receive a certificate from a file into a key database | |
-setdefault | Set the default personal certificate | |
-sign | Sign a certificate stored in a file with a certificate stored in a key database and store the resulting signed certificate in a file | |
-certreg | -create | Create a certificate request |
-delete | Delete a certificate request from a certificate request database | |
-details | List the detailed information of a specific certificate request | |
extract | Extract a certificate request from a certificate request database into a file | |
-list | List all certificate requests in the certificate request database | |
-recreate | Recreate a certificate request | |
-help | Display help information for the IKEYCMD command | |
-version | Display IKEYCMD version information |
The following table shows each option that can be present on the command line. The options are listed as a complete group; however, their use is dependent on the object and action specified on the command line.
Option | Description |
-db | Fully qualified path name of a key database |
-default_cert | Sets a certificate to be used as the default certificate for client authentication (yes or no). The default is no. |
-dn | X.500 distinguished name. Input as a quoted string of
the following format (only CN, O, and C are required):
"CN=Jane Doe,O=IBM,OU=Java Development,L=Endicott, ST=NY,ZIP=13760,C=country" |
-encryption | Strength of encryption used in certificate export command (strong or weak). The default is strong. |
-expire | Expiration time of either a certificate or a database password (in days). Defaults are 365 days for a certificate and 60 days for a database password. |
-file | File name of a certificate or certificate request (depending on specified object) |
-format | Format of a certificate (either ascii for Base64_encoded ASCII or binary for Binary DER data). The default is ascii. |
-label | Label attached to a certificate or certificate request |
-new_format | New format of key database |
-new_pw | New database password |
-old_format | Old format of key database |
-pw | Password for the key database or PKCS#12 file. See Creating a new key database. |
-size | Key size (512 or 1024). The default is 1024. |
-stash | Indicator to stash the key database password to a file. If specified, the password will be stashed in a file. |
-target | Destination file or database. |
-target_pw | Password for the key database if -target specifies a key database. See Creating a new key database. |
-target_type | Type of database specified by -target operand (see -type). |
-trust | Trust status of a CA certificate (enable or disable). The default is enable. |
-type | Type of database. Allowable values are cms (indicates a CMS key database), jce (indicates Sun's proprietary Java Cryptography Extension), jceks (indicates Sun's proprietary Java Cryptography Extension Key Store), or pkcs12 (indicates a PKCS#12 file). |
-x509version | Version of X.509 certificate to create (1, 2 or 3). The default is 3. |
The following is a list of each of the command line-invocations, with the optional parameters specified in italics.
For simplicity, the actual Java invocation, java com.ibm.gsk.ikeyman.ikeycmd, is omitted from each of the command invocations.
-keydb -changepw -db <filename> -pw <password> -new_pw <new_password> -stash -expire <days>
-keydb -convert -db <filename> -pw <password> -old_format <cms | webdb> -new_format <cms>
-keydb -create -db <filename> -pw <password> -type <cms | jks | jceks | pks12> -expire <days> -stash
-keydb -delete -db <filename> -pw <password>
-keydb -stashpw -db <filename> -pw <password>
-cert -add -db <filename> -pw <password> -label <label> -file <filename> -format <ascii | binary> -trust <enable | disable>
-cert -create -db <filename> -pw <password> -label <label> -dn <distinguished_name> -size <1024 | 512> -x509version <3 | 1 | 2> -default_cert <no | yes>
-cert -delete -db <filename> -pw <password> -label <label>
-cert -details -db <filename> -pw <password> -label <label>
-cert -export -db <filename> -pw <password> -label <label> -type <cms | jks | jceks | pks12> -target <filename> -target_pw <password> -target_type <cms | jks | jceks | pkcs12> -encryption <strong | weak>
-cert -extract -db <filename> -pw <password> -label <label> -target <filename> -format <ascii | binary>
-cert -getdefault -db <filename> -pw <password>
-cert -import -db <filename> -pw <password> -label <label> -type <cms | jks | jceks | pks12> -target <filename> -target_pw <password> -target_type <cms | jks | jceks | pks12>
-cert -import -file <filename> -type <pkcs12> -target <filename> -target_pw <password> -target_type <cms | jks | jceks | pks12>
-cert -list <all | personal | CA | site> -db <filename> -pw <password> -type <cms | jks | jceks | pks12>
-cert -modify -db <filename> -pw <password> -label <label> -trust <enable | disable>
-cert -receive -file <filename> -db <filename> -pw <password> -format <ascii | binary> -default _cert <no | yes>
-cert -setdefault -db <filename> -pw <password> -label <label>
-cert -sign -file <filename> -db <filename> -pw <password> -label <label> -target <filename> -format <ascii | binary> -expire <days>
-certreq -create -db <filename> -pw <password> -label <label> -dn <distinguished_name> -size <1024 | 512> -file <filename>
-certreq -delete -db <filename> -pw <password> -label <label>
-certreq -details -db <filename> -pw <password> -label <label>
-certreq -extract -db <filename> -pw <password> -label <label> -target <filename>
-certreq -list -db <filename> -pw <password>
-certreq -recreate -db <filename> -pw <password> -label <label> -target <filename>
-help
-version
In order to eliminate some of the typing on the Java CLI invocations, user properties can be specified in a properties file. The properties file can be specified on the Java command-line invocation via the -Dikeycmd.properties Java option. For Windows platforms, a sample properties file, ikminit_hod.properties, is supplied in your_install_directory\bin, where your_install_directory is your Host On-Demand installation directory. For AIX platforms, this file is supplied in your_install_directory/bin. These installation directories contain the default setting for Host On-Demand.
A graphical Certificate Management utility (available on Windows and AIX platforms) is provided to allow you to create certificate requests, receive and store certificates, and create self-signed certificates. The P12 Keyring utility is provided mainly for platforms that do not have the Certificate Management Utility to create a keyring database with root certificates of self-signed and unknown Certificate Authority certificates. However, it can be used on any Host On-Demand platform. This utility provides system administrators with an easy way to create and deploy an SSL keyring database.
The P12 Keyring utility is written in Java. It obtains a server certificate from a Telnet or an FTP server (or a Redirector) that is configured for SSL. An SSL connection is made to the specified server and SSL port. If the port is not provided, the well-known secure Telnet or FTP port is used. The server's certificate will be extracted and added to the specified p12 file.
Access to the keyring database is password-protected. A password prompt will be given before any of the commands are performed. If the specified keyring file does not exist, it will be created and the password will be stored in the file.
![]() |
The Host On-Demand SSL support requires the password to be hod. If you are adding a private certificate to the keyring database, another password prompt will be given for the second p12 file. |
P12Keyring p12FileName connect ipaddr[:port] [ftp] P12Keyring p12FileName add p12FileName2 P12Keyring p12FileName list
connect - establishes an SSL connection to the specified ipaddr and port. The port number and ftp keyword are optional. If the port number is not specified, the default secure Telnet port 443 or the default secure FTP port 990 will be used.
If the ftp keyword is specified, the connection is to be made to a secure FTP server that is configured for security. There are two types of security options for FTP servers:
If the ftp keyword is specified but the port number is not specified or it is 990, implicit security negotiations are performed. If the ftp keyword is specified and the port number is not 990, explicit security negotiations are done by issuing AUTH TLS command first.
add - adds a private client certificate to the specified keyring database.
list - displays a list of certificates stored in the specified keyring database.
Windows:
C:\your_install_dir\lib\P12Keyring c:\your_install_dir\HOD\CustomizedCAs connect myServer.raleigh.ibm.com:702 C:\your_install_dir\lib\P12Keyring c:\your_install_dir\HOD\CustomizedCAs connect myFTPServer.raleigh.ibm.com:5031 ftp
where your_install_dir is your Host On-Demand installation directory.
Unix:
cd your_install_directory/HOD Java -classpath .;your_install_dir/lib/sm.zip \ com.ibm.hod5sslight.tools.P12Keyring CustomizedCAs connect myServer.raleigh.ibm.com:702
where your_install_dir is your Host On-Demand installation directory.
When you enter the following command line options with your native platform launcher, the launcher passes them to the Host On-Demand install as installation parameters. Options that suppress the GUI wizard are marked accordingly.
Option | Purpose | Example usage |
---|---|---|
-console
(Suppresses the GUI wizard) |
Installs Host On-Demand in console mode. | hodinstallwin.exe -console |
-log #!filename
where # echoes the display to standard output and !filename is the name of the log file. If you specify ! without a file name, the default log file name is used. |
Generates an installation file log with the name specified. | hodinstallwin.exe -log #!\mydirectory\logfile |
-options filename | Installs Host On-Demand with command line options that set specified properties for the installation. | hodinstallwin.exe -silent -options c:\mydirectory\responseFile |
-options-record filename | Generates an options text file recording your responses to the Host On-Demand install wizard, establishing them as default values for installation variables. | hodinstallwin.exe -options-record responses.txt |
-options-template filename | Generates an options text file containing the default installation values. | hodinstallwin.exe -options-template template.txt |
-silent
(Suppresses the GUI wizard) |
Installs Host On-Demand in silent mode, accepting all default installation values. | hodinstallwin.exe -silent |
The following additional command line options apply only to the process of calling and running the installation program. Enter them at the command line with the native platform launcher.
Option | Purpose | Example usage |
---|---|---|
-is:logfilename | Generates a log file for the native launcher's JVM searches. | hodinstallwin.exe -is:log myLogFile.txt |
-is:silent | Prevents the display of the launcher user interface (UI) while JVM searches and other initializations are taking place. (Commonly used with the command line option silent.) | hodinstallwin.exe -is:silent |
-is:tempdirdirectory | Sets the temporary directory used by the Host On-Demand install. | hodinstallwin.exe -is:tempdir "c:\temp" |
This information was developed for products and services offered in the U.S.A.
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 give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or region or send inquiries, in writing, to:
IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other country or region where such provisions are inconsistent with local law: 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 states 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 Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM Corporation Department T01 Building B062 P.O. Box 12195 Research Triangle Park, NC 27709-2195 U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
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.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
Microsoft, Windows, Windows NT, and the Windows logo are registered trademarks of Microsoft Corporation.
Other company, product, and service names may be trademarks or service marks of others.