This chapter explains how to configure Jolt 1.1 and describes the Jolt Internet Relay, Event Subscription, and security features. Readers of this chapter are assumed to be system administrators and/or application developers who have experience with the operating systems and workstation platforms on which they are going to configure TUXEDO and Jolt.

This chapter includes the following sections:

• Using the Jolt Server

• Using the Jolt Repository

• Event Subscription

• Jolt Internet Relay

• Using Sample Applications in Jolt Online Resources

Using the Jolt Server

The Jolt Server consists of listeners and handlers.

Jolt Server Listener (JSL). The JSL is configured to support clients on an IP/port combination.The JSL works with the Jolt Server Handler (JSH) to provide client connectivity to the backend of the Jolt system. The JSL is administered by the same tools used to manage any resource within a BEA TUXEDO environment.

Jolt Server Handler (JSH). The JSH is a program that runs on a TUXEDO server machine to provide a network connection point for remote clients. The JSH works with the JSL to provide client connectivity residing on the backend of the Jolt system.

The system administrator's responsibilities for the server components of Jolt include:

• Determining server network addresses.

• Determining the number of Jolt clients to be serviced by one JSH (for example, if there are 10 clients per JSH and 10 JSHs, 100 clients can be connected).

• Determining the minimum and maximum number of JSHs.

Jolt Internet Relay

The Jolt Internet Relay is a component that routes messages from a Jolt client to a JSL or JSH. This alleviates the need for the JSL/JSH and TUXEDO to run on the same machine as the Web server. The Jolt Relay (JRLY) is not required to be a TUXEDO server or a TUXEDO client. It is a stand-alone piece of software that routes the Jolt messages to the JSL or JSH. Refer to the "Jolt Internet Relay" in this chapter.

Security and Encryption

Authentication and key exchange data that are transmitted between Jolt clients and the JSL/JSH are encrypted using DES (56-bit) encryption. All subsequent exchanges are encrypted using RC4 encryption. International packages use a 40-bit key.

Programs using the 56/128-bit encryption cannot be used outside the United States without proper approval from the United States government. Customers with intranets extending beyond the United States cannot use this mode of encryption if any internal clients are outside of the United States.

The 128-bit version generates a 128-bit RC4 session encryption key at logon time, and this session key is transmitted over the network in a message protected by 56-bit DES encryption. The temporary session key is then used to encrypt the session's data. The overall security level achieved is equivalent to 56-bit DES encryption, even though the data encryption is using a 128-bit key.

Starting the Jolt Server

Type tmloadcf and tmboot -y to start all administrative and server processes. (The prompt only displays when the command is entered with none of the limiting options). See the TUXEDO System Administration Guide for information on tmloadcf and tmboot.

Note: TUXEDO monitors the JSL and restarts it in the event of a failure. When TUXEDO restarts the listener process, the following occurs:

• Clients attempting a listener connection must try to reconnect. Clients attempting a handler connection receive a timeout or a time delay.

• Clients currently connected to a handler are disconnected (JSH exits when its corresponding JSL exits).

Configuring the Jolt Server

The Jolt Server Listener (JSL) is a TUXEDO server responsible for distributing connection requests from Jolt to the JSH. TUXEDO must be running on the host machine where the JSL and JREPSVR is located.

To configure the JSL, you must modify the UBBCONFIG file. For information regarding TUXEDO configuration, refer to the TUXEDO Administration Guide. Listing 3-1 shows relevant portions of the UBBCONFIG file.

Listing 3-1 UBBCONFIG File

---

Change the following sections of the UBBCONFIG file.

The parameters shown in Table 3-1 are the only parameters that should be designated for the Jolt Server groups and Jolt Servers. You do not need to specify any other parameters.

Note: Ensure that Resource Managers are not assigned as a default value for all groups in the *GROUPS section of your UBBCONFIG file. This will assign a Resource Manager to the JSL and you will receive an error during tmboot. In the *SERVERS section, default values for RESTART, MAXGEN, etc., are acceptable defaults for the JSL.

*MACHINES Section

The MAXWSCLIENTS parameter is required in the *MACHINES section for the configuration file and applies to specific machines. The Jolt Server and /WS use MAXWSCLIENTS in the same way. MAXWSCLIENTS communicates the number of accesser slots to reserve for Jolt and /WS clients to TUXEDO. For example, if 200 slots are configured for MAXWSCLIENTS, this number configures TUXEDO for the total number of remote clients used by Jolt and /WS.

Specify MAXWSCLIENTS in the configuration file. If it is not specified, the default is 0.

*GROUPS Section

A *GROUPS entry is required for the group that includes the Jolt Server Listener (JSL). The group name is selected by the application.

1. Specify the same identifiers given as the value of the LMID parameter in the *MACHINES section.

2. Specify the value of the GRPNO between 1 and 30,000 in the *GROUPS section.

Clients connect to Jolt applications through the JSL. Services are accessed through the Jolt Server Handler (JSH). The JSL supports multiple clients and acts as a single point of contact for all the clients to connect to the application at the network address that is specified on the JSL command line. The JSL schedules work for handler processes. A handler process acts as a substitute for clients on remote workstations within the administrative domain of the application. The handler uses a multiplexing scheme to support the multiple clients concurrently.

The network address specified for the JSL designates a TCP/IP address for both the JSL and any JSH processes associated with that JSL. The port number identified by the network address specifies the port number on which the JSL accepts new client connections. Each JSH associated with the JSL uses consecutive port numbers at the same TCP/IP address. For example, if the initial port number is 8000 and there are a maximum of three JSH processes, the JSH processes use ports 8001, 8002, and 8003.

Note: Port numbers used by the JSHs are sequentially incremented by one numeric digit after the JSL port number. If JSL is using port number 8000, its JSHs use 8001, and so on. Misconfiguration of the subsequent JSL results in a port number collision.

Each handler uses a multiplexing scheme on its designated port to support multiple clients concurrently on one port.

TUXEDO parameters including RESTART, RQADDR, and REPLYQ can be used with the JSL. See the TUXEDO Administration Guide for additional information regarding run-time parameters. Enter the following parameters:

1. To identify the SRVGRP parameter, type the previously defined group name value from the *GROUPS section.

2. To indicate the SRVID, type a number between 1 and 30,000 that identifies the server within its group.

3. Verify that the syntax for the CLOPT parameter is as follows:

   CLOPT= "-- -n 0x0002PPPPNNNNNNNN -d /dev/tcp -m2 -M4 -x10"

   Note: The CLOPT parameters may vary. Refer to Table 3-2 for pertinent command-line information.

4. If necessary, type the optional parameters:

   • Type the SEQUENCE parameter to determine the order that the servers are booted.

   • Specify Y to permit release of the RESTART parameter.

   • Type 0 to permit an infinite number of server restarts using the GRACE parameter.

     Table 3-2 Command Line Options

     Command Line Option	Description
     [-c connection_mode]	Allowed connection modes from clients: RETAINED - the network connection is retained for the full duration of a session. RECONNECT - the client establishes and brings down a connection when an idle timeout is reached, reconnecting for multiple requests within a session. ANY - the server allows a client to request either a RETAINED or RECONNECT type of connection for a session. Default is ANY. (Optional)
     [-d device_name]	The device for platforms using the Transport Layer Interface. There is no default. (Required; optional for sockets)
     [-H external netaddr]	The external netaddr is the network address Jolt clients use to connect to the application. The JSL process uses this address to listen for clients attempting to connect at this address. If the address is 0x0002MMMMdddddddd and JSH network address is 0x00021111ffffffff, the known network address is 0x00021111dddd dddd. If the address starts with "//" network address, the type is IP based and the TCP/IP port number of JSH network address is copied into the address to form the combined network address. (Optional for JSL in TUXEDO 6.3)
     [-I init-timeout]	The time (in seconds) that a Jolt client is allowed to complete initialization through the JSH before it is timed out by the JSL. Default is 60 seconds. (Optional)
     [-m minh]	The minimum number of JSHs that are available in conjunction with the JSL at one time. The range of this parameter is between 0 and 255. Default is 0. (Optional)
     [-M maxh]	The maximum number of JSHs that are available in conjunction with the JSL at one time. The range of this parameter is between 1 and 4096. If this option is not specified, the parameter defaults to MAXWSCLIENTS divided by the rounded-up -x multiplexing factor. (Optional)
     -n netaddr (TUXEDO 6.1 and 6.2)	Network address used by the Jolt Listener for Jolt 1.1 with TUXEDO 6.1 and 6.2. Indicate the network address where the clients connect to the JSL. This is a required parameter and is the contact point used by Java workstation clients to access the application. The port number identified by the network address specifies the port number on which the JSL accepts new client connections. Each JSH associated with the JSL uses consecutive port numbers at the same TCP/IP address. The network address is composed of 1) an initial two digits indicating hexadecimal characters, followed by three groups of numbers indicating 2) protocol, 3) port number, and 4) IP address. For example: 0x 0002 PPPP NNNNNNNN There is no default. (Required)
     -n netaddr (for TUXEDO 6.3)	Network address used by the Jolt listener for Jolt 1.1 with TUXEDO 6.3. TCP/IP addresses may be specified in the following forms: "//host.name:port_number" "//#.#.#.#:port_number" In the first format, the domain finds an address for hostname using the local name resolution facilities (usually DNS). Hostname must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine. In the second example, the "#.#.#.#" is in dotted decimal format. In dotted decimal format, each # should be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine.
     	In both of the above formats, port_number is the TCP port number at which the domain process will listen for incoming requests. port_number can either be a number between 0 and 65535 or a name. If port_number is a name, then it must be found in the network services database on your local machine. The address can also be specified in hexadecimal format when preceded by the characters "0x". Each character after the initial "0x" is a number between 0 and 9 or a letter between A and F (case insensitive). The hexadecimal format is useful for arbitrary binary network addresses such as IPX/SPX or TCP/IP. There is no default. (Required)
     [-T Client-timeout]	The time (in minutes) allowed for a client to stay idle. If a client does not make any requests during this time, the JSH disconnects the client and the session is terminated. If an argument is not supplied, the session does not timeout. When the -c ANY or -c RECONNECT option is used, always specify -T with an idle timeout value. If -T is not specified and the connection is suspended, JSH does not automatically terminate the session. The session never terminates if a client abnormally ends the session. If a parameter is not specified, the default is no timeout. (Optional)
     [-w JSH]	The Jolt Server Handler is indicated by this command line option. Default is JSH. (Optional)
     [-x mpx-factor]	A parameter used to control the degree of multiplexing within each JSH process. This is the number of clients that one JSH can service. Default value is 10. (Optional)
     [-Z 40|128]	When establishing a network link between a Jolt client and the JSH, allow encryption up to this level. 40 and 56/128 specify the length (in bits) of the encryption key. The default value is 0. The length, 128, is synonymous with 56/128. See "Security and Encryption" for more information.

All shutdown requests to the Jolt servers are initiated by the TUXEDO command, tmshutdown -y. During shutdown:

• No new client connections are accepted.

• All current client connections are terminated. TUXEDO will rollback in-flight transactions. Each client receives an error message indicating that the service is unavailable.

Using the Jolt Repository

The Jolt Repository contains TUXEDO service definitions that allow the Jolt clients to access TUXEDO services. The Jolt Repository files included with the installation contain services definitions used internally by Jolt. See Chapter 5, "Using the Jolt Repository Editor," for detailed instructions on how to add definitions to the application services.

Configuring the Jolt Repository

To configure the Jolt Repository, modify the application UBBCONFIG file. The UBBCONFIG file is an ASCII version of the TUXEDO configuration file. Create a new UBBCONFIG file for each application. See the TUXEDO Reference Manual for information regarding the syntax of the entries for the file. Listing 3-2 shows relevant portions of the UBBCONFIG file.

Listing 3-2 Sample of UBBCONFIG File

---

Note: For UNIX systems, use the slash (/) when setting the path to the jrepository file. For NT systems, use the backslash (\) and specify the drive name (e.g., c:\app\repository).

Change the following sections of the UBBCONFIG file:

*GROUPS Section

A *GROUPS entry is required for the group that includes the Jolt Repository. The group name parameter is a name selected by the application.

1. Specify the same identifiers given as the value of the LMID parameter in the *MACHINES section.

2. Specify the value of the GRPNO between 1 and 30,000 in the *GROUPS section.

The Jolt Repository server, JREPSVR, contains services for access and editing the Repository. Multiple JREPSVR instances share repository information through a shared file. Include JREPSVR in the *SERVERS section of the UBBCONFIG file.

1. Indicate a new server identification (e.g., 98) with the SRVID parameter.

2. Specify the -W flag for one JREPSVR to ensure that you can edit the Repository. The Repository is read-only without this flag.

   Note: You must install only one writable JREPSVR (i.e., only one JREPSVR with the -W flag). Multiple read-only JREPSVRs may be installed on the same host.

3. Type the -P flag to specify the path of the repository file. An error message displays in the TUXEDO ULOG file if the argument for the -P flag is not entered.

4. Add the file pathname of the Repository file (e.g., /app/jrepository).

5. Boot the TUXEDO system using the tmloadcf command (e.g., tmloadcf -y ubbconfig) and tmboot command. See the TUXEDO Administration Guide for information on tmloadcf and tmboot.

A Repository file, jrepository, is available with Jolt 1.1. This file includes bankapp services and the Repository services that you can modify, test, and delete using the Repository Editor.

Start with the jrepository file provided with the installation, even if you are not going to test the bankapp application with Jolt. Delete the bankapp packages or services that are not needed.

The pathname of the file must match the argument of the -P option.

Warning: Do not modify the Repository files manually or you will not be able to use the Repository Editor. Although the jrepository file can be modified and read with any text editor, the Jolt system does not have integrity checks to ensure that the file is in the proper format. Any manual changes to the jrepository file may not be detected until runtime. See "Using the Jolt Repository Editor" for additional information.

You must initially define the TUXEDO services using TUXEDO and Jolt in order to make the Jolt services available to the client.

1. Build the TUXEDO server containing the service. See the TUXEDO Administration Guide or TUXEDO Programmer's Guide for additional information on the following:

   • Building the TUXEDO applications/server

   • Editing the UBBCONFIG file

   • Updating the TUXCONFIG file

   • Administering the tmboot command

2. Access the Jolt Repository Editor. See Chapter 5, "Using the Jolt Repository Editor," in this book for additional information on the following:

   • "Adding a Service"

   • "Saving Your Work"

   • "Testing a Service"

   • "Exporting/Unexporting Services"

Jolt Event Subscription is used to receive event notifications from either TUXEDO services or other TUXEDO clients:

Unsolicited Event Notifications. These are notifications that a Jolt client receives as a result of a TUXEDO client or service subscribing to unsolicited events, and a TUXEDO client issuing broadcast (using either a tpbroadcast() or a directly targeted message via a tpnotify() ATMI call).

Brokered Event Notifications. These notifications are received by a Jolt client via the TUXEDO Event Broker. The notifications are only received when both Jolt clients subscribes to an event and any TUXEDO client or server issues system posted event or a tppost() call.

Configuration

Configure the TUXEDO TMUSREVT server and modify the application UBBCONFIG file. Listing 3-3 shows the relevant portions TMUSREVT parameters in the UBBCONFIG file. See the TUXEDO Programmer's Guide for information regarding the syntax of the entries for the file.

Listing 3-3 UBBCONFIG File

---

Change the following sections of the UBBCONFIG file:

Filtering TUXEDO FML or VIEW Buffers

"Filtering" is a process that allows you to customize a subscription. If you require additional information about the TUXEDO Event Broker, subscribing to events, or filtering, refer to the BEA TUXEDO Programmer's Guide, Volume 1.

In order to filter TUXEDO FML or VIEW buffers, the field definition file must be available to TUXEDO at runtime.

Note: There are no special requirements for filtering STRING buffers.

FML Buffer Example

Listing 3-4 shows an example using the FML buffer. The FML field definition table is made available to TUXEDO by setting the FIELDTBLS and FLDTBLDIR variables.

To filter a field found in the my.flds file:

1. Copy the my.flds file to /usr/me/bankapp directory.

2. Add my.flds to the FIELDTBLS variable in the TMUSREVT.ENV file as shown in Listing 3-4:

   Listing 3-4 FIELDTBLS Variable in the TMUSREVT.ENV File

   ---

   FIELDTBLS=Usysflds,bank.flds,credit.flds,event.flds,my.flds
   FLDTBLDIR=/usr/tuxedo/me/T6.2/udataobj:/usr/me/bankapp

   ---

If ENVFILE="/usr/me/bankapp/TMUSREVT.ENV" is included in the definition of the UBBCONFIG file (shown in Listing 3-3), the FIELDTBLS and FLDTBLDIR definitions are taken from the TMUSREVT.ENV file and not from your environment variable settings.

If you remove the ENVFILE="/usr/me/bankapp/TMUSREVT.ENV" definition, the FIELDTBLS and FLDTBLDIR definitions are taken from your environment variable settings. The FIELDTBLS and FLDTBLDIR definitions must be set to the appropriate value prior to booting the TUXEDO system.

For additional information on event subscriptions and the Jolt Class Library, refer to Chapter 6, "Using the Jolt Class Library."

Jolt Internet Relay

The Jolt Internet Relay is a component that routes messages from a Jolt client to a JSL or JSH. This eliminates the need for the JSH and TUXEDO to run on the same machine as the Web server (generally considered as insecure). The Jolt Relay (JRLY) is not a TUXEDO server or a TUXEDO client. It is a stand-alone program that routes the Jolt messages from the Internet to the JSL or JSH

The Jolt Internet Relay consists of two components illustrated in Figure 3-1.

• Jolt Relay (JRLY). The JRLY is not a TUXEDO client or server. It is a stand-alone software component. It requires only minimal configuration to allow it to work with Jolt clients.

• Jolt Relay Adapter (JRAD). The JRAD is a TUXEDO application server, but does not include any TUXEDO services. It requires command line arguments to allow it to work with the JSL and the TUXEDO system.

  Note: The Jolt relay is transparent to Jolt clients and Jolt servers. A Jolt server can simultaneously connect clients directly to the Jolt Server (intranet clients), or via the Jolt Relay (Internet clients).

  Figure 3-1 Jolt Internet Relay Path

  

Figure 3-1 shows how a browser connects to the Web server software and downloads the Jolt applets. The Jolt applet or client connects to the JRLY on the Web server machine. The JRLY forwards the Jolt messages across the firewall to the JRAD. The JRAD selectively forwards messages to the JSL or appropriate JSH.

Jolt Relay (JRLY)

The JRLY (front-end relay) process may be started before or after the JRAD is started. If the JRAD is not available when the JRLY is started, the JRLY attempts to connect to the JRAD when it receives a client request. If JRLY is unable to connect to the JRAD, the client is denied access and is disconnected. A warning is written to the JRLY error log file.

Starting the JRLY

The JRLY process is started by typing the command name at a system prompt.

jrly -f <config_file_path>

If the configuration file does not exist or cannot be opened, the JRLY prints an error message. Refer to Appendix B for the Jolt Relay messages.

If the JRLY is unable to start, it writes a message to standard error and attempts to log the startup failure in the error log if possible, then exit.

JRLY Configuration File

The format of the configuration file is a TAG=VALUE format. Blank lines or lines starting with a "#" are ignored. Refer to Listing 3-5 for an example of the formal specifications of the configuration file.

Listing 3-5 Specification of Configuration File

---

Refer to Listing 3-6 for an example of the JRLY configuration file. The CONNECT line specifies the IP address and port number of JRAD machine.

Listing 3-6 Example of JRLY Configuration File

---

The format for directory and file names is determined by the operating system. UNIX systems use the forward slash (/). NT systems use the backslash (\). If any of the files specified in LOGDIR, ACCESS_LOG or ERROR_LOG cannot be opened for writing, the JRLY prints an error message on stderr and exits.

The format for host names and port numbers are shown in Table 3-5.

Jolt Relay Adapter (JRAD)

The JRAD (back-end relay) is a TUXEDO system server. The JRAD server may or may not be located on the same TUXEDO host machine (in SHM mode) and server group that the JSL server it is connected to.

The JRAD can be started independently of its associated JRLY. JRAD tracks its startup and shutdown activity in the TUXEDO log file.

Starting the JRAD

Type tmloadcf and tmboot to start the JRAD.

Configuration entry in the UBBCONFIG is described in the "JRAD Configuration" section.

JRAD Configuration

A single JRAD process can only be connected to a single JRLY. A JRAD can only be configured to communicate with one JSL and its associated JSHs. However, multiple JRADs can be configured to communicate with one JSL. The CLOPT parameter for the TUXEDO servers must be included in the UBBCONFIG file. For additional information about the CLOPT parameters, refer to Table 3-2 and Table 3-6.

Note: The format is 0x0002PPPPNNN. Refer to the Jolt 1.1 Release Notes for additional information on JRAD.

Listing 3-7 shows the sample UBBCONFIG file.

Listing 3-7 Sample JRAD Entry in UBBCONFIG File

---

There are several networked components that need to be configured to work together when configuring a Jolt Internet Relay. Prior to configuration, review the criteria required in Table 3-7 and record the information. This will help minimize the possibility of misconfiguration.

Using Sample Applications in Jolt Online Resources

You can access sample code that can be modified for use with BEA Jolt through the BEA Jolt product Web page at:

http://www.beasys.com/products/jolt/index.htm

These samples demonstrate and utilize Jolt features and functionality.

Other Web sites with Java-related information include:

• Javasoft Home Page (http://www.javasoft.com/)

• Deja News Home Page (http://www.dejanews.com/), an archive of Java-related newsgroups

• Java Programmers FAQ (http://www.best.com/~pvdl/javafaq.txt)

• In addition, the newsgroups in the comp.lang.java hierarchy contain lists of past articles and communications regarding Java, and is a valuable source of archival material.