Section 1 - Commands

Command Reference

ISL(1)

Name

Enables access to BEA Tuxedo objects by remote BEA Tuxedo clients using IIOP.

Synopsis

ISL SRVGRP="identifier"

    SRVID="number"

    CLOPT="[-A ] [ servopts options ] -- -n netaddr 
           [-C {detect|warn|none} ]
           [-d device ]
           [-E principal_name]
           [-K {client|handler|both|none} ]
           [-m minh ]
           [-M maxh ]
           [-T Client-timeout]
           [-x mpx-factor ] 
           [-H external-netaddr]
           #options for Outbound IIOP
           [-O]
           [-o outbound-max-connections]
           [-s Server-timeout]
           [-u out-mpx-users]
           #options for SSL
           [-a]
           [-R renegotiation-interval]
           [-S secure port]
           [-v {detect|warn|none} ]
           [-z [0|40|56|128]]
           [-Z [0|40|56|128]]"

Description

The IIOP Server Listener (ISL) is a BEA Tuxedo-supplied server command that enables access to BEA Tuxedo objects by remote BEA Tuxedo clients using IIOP. The application administrator enables access to the application objects by specifying the IIOP Server Listener as an application server in the SERVERS section. The associated command-line options are used to specify the parameters of the IIOP Server Listener and IIOP Server Handlers.

The location, server group, server ID, and other generic server-related parameters are associated with the ISL using the standard configuration file mechanisms for servers. ISL command-line options allow for customization.

Each ISL booted as part of an application facilitates application access for a large number of remote BEA Tuxedo clients by providing access via a single, well-known network address. The IIOP Server Handlers are started and stopped dynamically by the ISL, as necessary, to meet the incoming load.

For joint client/servers, if the remote joint client/server ORB supports bidirectional IIOP connections, the ISL can use the same inbound connection for outbound invokes to the remote joint client/server. The ISL also allows outbound invokes (outbound IIOP) to objects located in a joint client/server that is not connected to an ISH. This capability is enabled when the -O option is specified. The associated command-line options allow configuration of outbound IIOP support:

Parameters

-A

Indicates that the ISL is to be booted to offer all its services. This is a default, but it is shown to emphasize the distinction between system-supplied servers and application servers. The latter can be booted to offer only a subset of their available services. The double-dash (--) marks the beginning of parameters that are passed to the ISL after it has been booted.

You specify the following options in the CLOPT string after the double-dash (--) in the CLOPT parameters:

-n netaddr

Specifies the network address to be used by a server listener to accept connections from remote CORBA clients. The remote client must set the environment variable (TOBJADDR) to this value, or specify the value in the Bootstrap object constructor. See the C++ Programming Reference for details. This is the only required parameter.

TCP/IP addresses must be specified in one of the following two formats:

"//hostname:port_number"
"//#.#.#.#:port_number"

In the first format, the domain finds an address for hostname using the local name facilities (usually DNS). The host must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.

Note: The hostname must begin with a letter character.

In the second format, the "#.#.#.#" is the dotted decimal format. In dotted decimal format, each # must 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 listens for incoming requests. port_number can be a number between 0 and 65535 or a name. If port_number is a name, it must be found in the network services database on your local machine.

Note: The Java Tobj_Bootstrap object uses a short type to store the port_number. Therefore, you must use a port_number in the range of 0 to 32767 if you plan to support connections from Java clients.

Note: The network address that is specified by programmers in the Bootstrap constructor or in TOBJADDR must exactly match the network address in the application's UBBCONFIG file. The format of the address as well as the capitalization must match. If the addresses do not match, the call to the Bootstrap constructor will fail with a seemingly unrelated error message:

ERROR: Unofficial connection from client at <tcp/ip address>/<port-number>:For example, if the network address is specified as //TRIXIE:3500 in the ISL command line option string, specifying either //192.12.4.6:3500 or //trixie:3500 in the Bootstrap constructor or in TOBJADDR will cause the connection attempt to fail.

On UNIX systems, use the uname -n command on the host system to determine the capitalization used. On Windows NT systems, see the host system's Network control panel to determine the capitalization used.

Note: Unlike the BEA Tuxedo system Workstation Listener (WSL), the format of the network addresses is limited to //host:port. The reason for this limitation is that the host name and port number are used by BEA Tuxedo servers; the host name does not appear as such in the hexadecimal format, and it could only be passed to the servers using the dotted IP address format.

[-a]

Specifies that certificate-based authentication should be enabled when accepting an SSL connection from a remote application.

[-C detect|warn|none]

Determines how the IIOP Listener/Handler will behave when unofficial connections are made to it. The default value is detect.

The official way for the CORBA client to connect to the IIOP Listener/Handler is via a Bootstrap object. The unofficial connection is established directly from an IOR. For example, a client could connect to one IIOP Listener/Handler via a Bootstrap object and then, perhaps inadvertently, connect to a second IIOP Listener/Handler by using an IOR that contains the host and port of the second IIOP Listener/Handler. Typically, this is not the case. Usually, the client uses IORs that contain the host and port of the IIOP Listener/Handler that the client connected to via a Bootstrap object. Use of such IORs does not cause an additional connection to be made.

Caution: The use of unofficial connections can cause problems for remote client applications that use transactions. The application may have the notion that invocations on both the official and unofficial connections within the same transaction have succeeded; however, in reality, only invocations on the official connection are ACID (Atomicity, Consistency, Isolation, and Durability).

A value of detect causes the ISL/ISH to raise a NO_PERMISSION exception when an unofficial connection is detected. A value of warn causes the ISL/ISH to log a message to the user log exception when an unofficial connection is detected; no exception will be raised. A value of none causes the ISL/ISH to ignore unofficial connections.

[-d device]

Specifies the device filename used for network access by the server listener and its server handlers. This parameter is optional because some transport providers (for example, sockets) do not require a device name. However, other providers (for example, TLI) do require a device name. In the case of TLI, this option is mandatory. There is no default for this parameter. (This does not apply to Windows 2003 systems.)

[-E principal_ name]

An optional parameter that indicates the identity of the principal that is required in order to establish a trusted connection pool. A trusted connection pool can only be established if a CORBA application is configured to require users to be authenticated.

If a remote client application attempts to propagate per-request security information over a connection that is not part of a trusted connection pool, the accompanying propagated security information will be ignored.

[-K {client|handler|both|none}]

Directs the client, or the ISH process, or both, to activate the network provider's KEEPALIVE option. This option improves the speed and reliability of network failure detection by actively testing an idle connection's state at the protocol stack level. The availability and timeout thresholds for this feature are determined by operating system tunable parameters.

A value of client configures this option for the client; a value of handler configures this option for the ISL; and a value of both will configure both sides of the connection. The default value is none, in which case neither side has the KEEPALIVE option configured.

Note: The KEEPALIVE interval is an operating system parameter, so changing the value affects any other applications that enable KEEPALIVE. Many platforms have a two-hour default value that may be longer than desired.

This option is not available on all platforms. A userlog warning message is generated if the KEEPALIVE option is specified but is not available on the ISH's machine. If KEEPALIVE is requested but is not available on the client's machine, the setting is ignored.

[-m minh]

Specifies the minimum number of handlers that should be available in conjunction with this ISL at any given time. The default is 0. The ISL will start this many ISHs immediately upon being booted and will not deplete the supply of ISHs below this number until the administrator issues a shutdown to the ISL. The default value for this parameter is 0. The legal range is between 0 and 255.

[-M maxh]

Specifies the maximum number of handlers that should be available in conjunction with this ISL at any given time. The Handlers are started as necessary to meet the demand of remote BEA Tuxedo clients attempting to access the system. The default value for this parameter is equal to the setting for MAXWSCLIENTS on the logical machine, divided by the multiplexing factor for this ISL (see -x option below), rounded up by one. The legal range for this parameter is between 1 and 4096. The value must be equal to or greater than minh.

[-T Client-timeout]

Specifies the inactive client timeout option. The inactive client timeout is the time (in minutes) allowed for a client to stay idle. If a client does not make any requests within this time period, the IIOP Listener/Handler disconnects the client. If this argument is not given or is set to 0, the timeout is infinite.

[-x mpx-factor]

This is an optional parameter used to control the degree of multiplexing desired within each ISH. The value for this parameter indicates the number of remote BEA Tuxedo clients that can be supported simultaneously by each ISH. The ISH ensures that new handlers are started as necessary to handle new remote BEA Tuxedo clients. This value must be greater than or equal to 1 and less than or equal to 4096. The default value for this parameter is 10.

[-H external netadder]

Specifies the external network address to be set as the host and port in interoperable object references returned to clients of the ISL. It has the same format as the ISL CLOPT -n netaddr option. This feature is useful when an IIOP, or remote, client needs to connect to an ISL through a firewall.

[-O]

This option (uppercase letter O) enables outbound IIOP to objects that are not located in a client that is connected to an ISH. Since the -O option requires a small amount of extra resources, the default is to not allow outbound IIOP.

[-o outbound-max-connections]

This option (lowercase letter o) specifies the maximum number of outbound connections that each ISH may have. In effect, it limits the number of simultaneous Outbound IIOP sockets that any single ISH under the control of this ISL will have active at one time.

This option requires that the -O (uppercase letter O) option is also specified. The value of this option must be greater than 0, but not more than 4096. An additional requirement is that the value of this option, (outbound-max-connections) times the maximum number of handlers, must be less than 32767. The default for this option is 20.

[-R renegotiation-interval]

Specifies the renegotiation internal in minutes. If a connection does not have a renegotiation in the specified interval, the IIOP Listener/Handler will request that the client renegotiate the session for inbound connections or actually perform the renegotiation in the case of outbound connections. The default is 0 minutes which results in no periodic session renegotiations.

[-S secure-port]

Specifies the port number that the IIOP Listener/Handler should use to listen for secure connections using the SSL protocol. You can configure the IIOP Listener/Handler to allow only secure connections by setting the port numbers specified by the -S and -n options to the same value.

[-s Server-timeout]

Server-timeout is the time, in minutes, allowed for a remote server to remain idle. If a remote server does not receive any requests within this time period, the ISL disconnects the outbound IIOP connection to the server. The ISH reconnects to the remote server on subsequent requests. This option can be used for server platforms that are unstable. Note that this is a best-attempt value in that the ISL does not disconnect the connection before this time is up, but does not guarantee to disconnect the connection once the exact time has elapsed. This option requires that the -O (uppercase letter O) option is also specified. The value must be greater than or equal to 1. If this option is not specified, the default is 60 (one hour).

[-u out-mpx-users]

An optional parameter used to control the degree of outbound multiplexing desired within each ISH. The value for this option indicates the number of outbound IIOP users (native clients or servers) that can be supported simultaneously by each outbound IIOP connection in the ISH. The ISL ensures that new ISHs are started, as necessary, to handle new users up to the value of this option (out-mpx-users). This option requires that the -O (uppercase letter O) option is also specified. This option must be greater than 0 (zero), but not more than 1024; the default value is 10.

[-v {detect|warn|none}]

Determines how the IIOP Listener/Handler will behave when a digital certificate for a peer of an outbound connection initiated by the BEA object request broker (ORB) is received as part of the Secure Sockets Layer (SSL) protocol handshake. The validation is only performed by the initiator of a secure connection and confirms that the peer server is actually located at the same network address as specified by the domain name in the server's digital certificate. This validation is not technically part of the SSL protocol but is similar to the check done in web browsers.

A value of detect causes the BEA ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer server's digital certificate. If the comparison fails, the BEA ORB refuses the authenticate the peer and drops the connection. The detect value is the default value.

A value of warn causes the BEA ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer's digital certificate. If the comparison fails, the BEA ORB logs a message to the user log but continues to process the connection.

A value of none causes the BEA ORB to not perform the peer validation and to continue to process the connection.

The -v parameter is only available if licenses for SSL and LLE (link level encryption) are installed.

[-z |0|40|56|128]]

Specifies the minimum level of encryption when establishing a network connection between a client and the IIOP Listener/Handler. 0 means no encryption while 40, 56, and 128 specify the length (in bits) of the encryption key. If this minimum level of encryption cannot be met, a connection will not be established. This option is only available if licenses for SSL and LLE (link level encryption) are installed.

[-Z |0|40|56|128]]

Specifies the maximum level of encryption when establishing a network connection between a client and the IIOP Listener/Handler. 0 means no encryption while 40, 56, and 128 specify the length (in bits) of the encryption key. The default is whatever capability is specified by the license. This option is only available if licenses for SSL and LLE (link level encryption) are installed.

Portability

The IIOP Server Listener is supported as a BEA Tuxedo-supplied server on UNIX and Microsoft Windows NT operating systems.

Interoperability

The ISL works with any IIOP compliant ORB.

Depending on the type of remote object and the desired outbound IIOP configuration, you may have to perform additional programming tasks. Table 14 lists the requirements for each type of object and outbound IIOP configuration.

Table 14 Programming Requirements for Using Outbound IIOP

Types of Objects	Asymmetric Requirements	Paired-connection Requirements	Bidirectional Requirements
Remote joint client/servers	Set `ISL CLOPT -O` option.	Use the `Tobj_Bootstrap::register_callback_port` method to register the callback port.	Use the `CORBA::ORB::create_policy` method to set `BiDirPolicy` on the POA.
Foreign (non-CORBA) ORBs	Set `ISL CLOPT -O` option.	Not applicable.	If the foreign ORB supports the POA and `BiDirPolicy`, use the `CORBA::ORB::create_policy` method to set `BiDirPolicy` on the POA.
Remote clients	Remote clients are not servers, so outbound IIOP is not possible.
Native joint client/servers	Outbound IIOP is not used.
Native clients	Outbound IIOP is not used.

Network Addresses

Suppose the local machine on which the ISL is being run is using TCP/IP addressing and is named backus.company.com, with address 155.2.193.18. Further suppose that the port number at which the ISL should accept requests is 2334. The address specified by the -l option could be:

        //155.2.193.18:2334

     //backus.company.com:2334

Examples

*SERVERS

ISL SRVGRP="ISLGRP" SRVID=1002 RESTART=Y GRACE=0

        CLOPT="-A -- -n //piglet:1900 -d /dev/tcp"