One solution is to combine the bankapp application and the credit card authorization application into one Oracle Tuxedo application, or domain, as shown in the following Figure.

Figure 2-2 Combining Two Oracle Tuxedo System Applications

• Creating the UBBCONFIG File for the Combined Application
  
• Limitations of Option 1
  

Another solution is to reconfigure the bankapp application and the credit card authorization application as a Domains configuration, as shown in the following figure. The two domains interoperate through two TDomain gateway server processes, one running in each domain.

Figure 2-3 Domains Configuration

To create the Domains configuration for the bankapp and credit card authorization applications, you need to create two UBBCONFIG files, one for each of the Oracle Tuxedo applications, and two DMCONFIG files, one for each of the Oracle Tuxedo applications.

• Creating the UBBCONFIG File for the bankapp Application in the Domains Environment
  
• Creating a DMCONFIG File for the bankapp Application
  
• Creating the UBBCONFIG File for the Credit Card Authorization Application in the Domains Environment
  
• Creating a DMCONFIG File for the Credit Card Authorization Application
  

The Domains example, illustrated in the following figure, consists of two Oracle Tuxedo domains: lapp, a local application based on simpapp, and rapp, a remote application based on simpapp. The lapp application is configured to allow its clients to access a service called TOUPPER that is available in the rapp application.

Figure 2-4 Local and Remote Applications in simpapp

The following tasks are required to configure the lapp and rapp applications.

Figure 2-5 DMPROC

You require to set the following environment variables for the lapp application to be configured successfully:

• TUXDIR—Absolute pathname to the Oracle Tuxedo system root directory on this machine; sometimes represented as tux_prod_dir .
• APPDIR—Absolute pathname to the lapp application root directory on this machine.
• TUXCONFIG—Absolute pathname of the device or filename where the application binary configuration file for lapp is found on this machine.
• BDMCONFIG—Absolute pathname of the device or filename where the Domains binary configuration file for lapp is found on this machine.
• PATH—must include %TUXDIR%\bin (Windows) or $TUXDIR/bin (UNIX).
• LD_LIBRARY_PATH (UNIX only)—list of dynamically loadable libraries that must be loaded on this machine (must include $TUXDIR/lib); on HP-UX on the HP 9000, use SHLIB_PATH instead of LD_LIBRARY_PATH.

• Windows Example
  
• UNIX Example
  

In lapp.ubb, the text version of the lapp application configuration file, only the required parameters are defined. Default settings are used for the other parameters. The following Listing shows the content of lapp.ubb.

Listing lapp.ubb Configuration File

# lapp.ubb
#
*RESOURCES
IPCKEY 111111
MASTER LAPP
MODEL SHM

*MACHINES
giselle
LMID=LAPP
TUXDIR=”/home/rsmith/tuxedo”
APPDIR=”/home/rsmith/lapp”
TUXCONFIG=”/home/rsmith/lapp/lapp.tux”
*GROUPS
LDMGRP GRPNO=1 LMID=LAPP
LGWGRP GRPNO=2 LMID=LAPP
.
.
.
*SERVERS
DMADM SRVGRP=LDMGRP SRVID=1
GWADM SRVGRP=LGWGRP SRVID=1
GWTDOMAIN SRVGRP=LGWGRP SRVID=2 REPLYQ=N
.
.
.
*SERVICES
.
.
.

• Server Group Definitions
  
• Server Definitions
  

In lapp.dom, the text version of the lapp Domains configuration file, only the required parameters are defined. Default settings are used for optional parameters. The following Listing shows the content of the lapp.dom file.

Listing lapp.dom Domains Configuration File

#
# lapp.dom
#
*DM_LOCAL
LAPP GWGRP=LGWGRP
TYPE=TDOMAIN
ACCESSPOINTID=”111111"
*DM_REMOTE
RAPP TYPE=TDOMAIN
ACCESSPOINTID=”222222"
*DM_EXPORT
*DM_IMPORT
TOUPPER
*DM_TDOMAIN
LAPP NWADDR=”//giselle:5000"
RAPP NWADDR=”//juliet:5000"

• DM_LOCAL Section Definitions
  
• DM_REMOTE Section Definitions
  
• DM_EXPORT Section Definitions
  
• DM_IMPORT Section Definitions
  
• DM_TDOMAIN Section Definitions
  

The lapp.ubb application configuration file contains the information necessary to boot the lapp application. You compile this file into a binary data file by running tmloadcf(1).

The lapp.dom Domains configuration file contains the information used by the local lapp TDomain gateway to communicate with the remote rapp TDomain gateway. You compile this file into a binary data file by running dmloadcf(1).

To compile both configuration files, use the following sample session as a guide.

Windows:

prompt> cd C:\home\lapp

prompt> set TUXCONFIG=C:\home\lapp\lapp.tux

prompt> tmloadcf -y lapp.ubb

prompt> set BDMCONFIG=C:\home\lapp\lapp.bdm

prompt> dmloadcf -y lapp.dom

UNIX:

prompt> cd /home/rsmith/lapp

prompt> TUXCONFIG=/home/rsmith/lapp/lapp.tux

prompt> export TUXCONFIG

prompt> tmloadcf -y lapp.ubb

prompt> BDMCONFIG=/home/rsmith/lapp/lapp.bdm

prompt> export BDMCONFIG

prompt> dmloadcf -y lapp.dom

Once you build both the lapp and rapp applications, you boot the applications on their respective machines by executing the tmboot(1) command:

prompt> tmboot -y

The order in which the two applications are booted does not matter. Monitor the applications with dmadmin(1), as described in Administering Domains. Once both applications are booted, a client in the lapp application can call the TOUPPER service provided by the rapp application.

You need to set the following environment variables for the rapp application to be configured successfully:

• TUXDIR—Absolute pathname to the Oracle Tuxedo system root directory on this machine; sometimes represented as tux_prod_dir .
• APPDIR—Absolute pathname to the rapp application root directory on this machine.
• TUXCONFIG—Absolute pathname of the device or filename where the application binary configuration file for rapp is found on this machine.
• BDMCONFIG—Absolute pathname of the device or filename where the Domains binary configuration file for rapp is found on this machine.
• PATH—must include %TUXDIR%\bin (Windows) or $TUXDIR/bin (UNIX).
• LD_LIBRARY_PATH (UNIX only)—list of dynamically loadable libraries that must be loaded on this machine (must include $TUXDIR/lib); on HP-UX on the HP 9000, use SHLIB_PATH instead of LD_LIBRARY_PATH.

• Windows Example
  
• UNIX Example
  

In rapp.ubb, the text version of the rapp application configuration file, only the required parameters are defined. Default settings are used for the other parameters. The following Listing shows the content of the rapp.ubb file.

Listing rapp.ubb Application Configuration File

# rapp.ubb
#
*RESOURCES
IPCKEY 222222
MASTER RAPP
MODEL SHM
*MACHINES
juliet
LMID=RAPP
TUXDIR=”/home/rsmith/bea/tuxedo”
APPDIR=”/home/rsmith/rapp”
TUXCONFIG=”/home/rsmith/rapp/rapp.tux”
*GROUPS
RDMGRP GRPNO=1 LMID=RAPP
RGWGRP GRPNO=2 LMID=RAPP
APPGRP GRPNO=3 LMID=RAPP
.
.
.
*SERVERS
DMADM SRVGRP=RDMGRP SRVID=1
GWADM SRVGRP=RGWGRP SRVID=1
GWTDOMAIN SRVGRP=RGWGRP SRVID=2 REPLYQ=N
simpserv SRVGRP=APPGRP SRVID=1
.
.
.
*SERVICES
TOUPPER
.
.
.

The following server groups are defined in rapp.ubb:

• RDMGRP—contains the Domains server DMADM.
• RGWGRP—contains the Domains servers GWADM and GWTDOMAIN.
• APPGRP—contains the application server simpserv.

The simpserv server advertises the TOUPPER service, which converts strings from lowercase to uppercase characters.

In rapp.dom, the text version of the rapp Domains configuration file, only the required parameters are defined. Default settings are used for the other parameters. The following Listing shows the content of the rapp.dom file.

Listing 2‑12 rapp.dom Domains Configuration File

# rapp.dom
#
*DM_LOCAL
RAPP GWGRP=RGWGRP
TYPE=TDOMAIN
ACCESSPOINTID=”222222"
*DM_REMOTE
LAPP TYPE=TDOMAIN
ACCESSPOINTID=”111111"
*DM_EXPORT
TOUPPER
*DM_IMPORT
*DM_TDOMAIN
RAPP NWADDR=”//juliet:5000"
LAPP NWADDR=”//giselle:5000"

The rapp.dom Domains configuration file is similar to the lapp.dom Domains configuration file, except that the two files list different services to be exported and imported. Specifically, the rapp.dom file defines the following Domains configurations for the rapp application:

• Specifies a local domain access point named RAPP, and a remote domain access point named LAPP. Both access points are associated with the TDomain gateway server group named RGWGRP.
• Specifies that the rapp service named TOUPPER is available to the lapp application.
• Specifies that no lapp services are available to the rapp application.
• Specifies that the rapp application will listen for incoming connection requests on network address juliet:5000, where juliet is the name of the machine on which the rapp application is running, and 5000 is the listening port.
• Specifies that if the rapp application attempts to make a connection to the lapp application, it will use the network address giselle:5000, where giselle is the name of the machine on which the lapp application is running, and 5000 is the destination port.
• Specifies that if the rapp application attempts to make a connection to the lapp application, it will use the network address giselle:5000, where giselle is the name of the machine on which the lapp application is running, and 5000 is the destination port.

The rapp.ubb application configuration file contains the information necessary to boot the rapp application. You compile this file into a binary data file by running tmloadcf(1).

The rapp.dom Domains configuration file contains the information used by the local rapp TDomain gateway to communicate with the remote lapp TDomain gateway. You compile this file into a binary data file by running dmloadcf(1).

To compile both configuration files, use the following sample session as a guide.

Windows:

prompt> cd C:\home\rapp

prompt> set TUXCONFIG=C:\home\rapp\rapp.tux

prompt> tmloadcf -y rapp.ubb

prompt> set BDMCONFIG=C:\home\rapp\rapp.bdm

prompt> dmloadcf -y rapp.dom

UNIX:

prompt> cd /home/rsmith/rapp

prompt> TUXCONFIG=/home/rsmith/rapp/rapp.tux

prompt> export TUXCONFIG prompt> tmloadcf -y rapp.ubb

prompt> BDMCONFIG=/home/rsmith/rapp/rapp.bdm

prompt> export BDMCONFIG

prompt> dmloadcf -y rapp.dom

Once you build both the rapp and lapp applications, you boot the applications on their respective machines by executing the tmboot(1) command:

prompt> tmboot -y

The order in which the two applications are booted does not matter. Monitor the applications with dmadmin(1), as described in Administering Domains. Once both applications are booted, a client in the lapp application can call the TOUPPER service provided by the rapp application.

Data sent between domains can be compressed for faster performance. To configure compression, set the CMPLIMIT parameter in the DM_TDOMAIN section of the DMCONFIG file. This parameter, which is only relevant to remote domain access points, specifies the compression threshold to be used when sending data to a remote domain. The minimum value is 0, and the maximum value is 2147483647. The default setting is 2147483647. Application buffers larger than the specified size will be compressed.

For more information about setting the CMPLIMIT parameter, see “Compressing Data Over a Network” in Administering an Oracle Tuxedo Application at Run Time.

Data-dependent routing information used by domain gateways to send service requests to specific remote domains is provided in the DM_ROUTING section of the DMCONFIG file. The FML, FML32, VIEW, VIEW32, X_C_TYPE, X_COMMON, and XML typed buffers are supported.

To create a routing table for a domain involved in a Domains configuration, you specify the following information in the DM_ROUTING section of the DMCONFIG file:

• Buffer type for which the routing entry is valid
• Name of the routing entry and field
• Ranges and associated remote domain names of the routing field.

For an example of a Domains data-dependent routing configuration, see Specifying Domains Data-Dependent Routing. For a detailed description of Domains data-dependent routing, see the DM_ROUTING section on reference page DMCONFIG(5)in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

The Oracle Tuxedo ATMI environment provides the following basic security capabilities for Domains configurations:

• Authentication—Verifies the identities of the local domain and a remote domain when attempting to establish a connection to one another
• Authorization—Restricts remote client access to local services via access control lists (ACLs)
• Link-level encryption—Keeps interdomain communications private

The security capabilities available to Domains configurations and those available to individual Oracle Tuxedo applications are relatively independent but compatible. For information about the security capabilities available to Oracle Tuxedo applications, see Using Security in ATMI Applications.

The Oracle Tuxedo Domains component provides the following security mechanisms:

• Domains authentication—Supplies the means by which the local domain and a remote domain can mutually authenticate one another when attempting to connect to one another. You specify identities, or principal names, for the local domain and each remote domain via the CONNECTION_PRINCIPAL_NAME parameter in the DM_LOCAL and DM_REMOTE sections of the DMCONFIG file.

  In addition, the local domain and a remote domain can use any of three levels of password security when attempting to connect to one another. You configure the level of password security on a local domain basis by setting the SECURITY parameter in the DM_LOCAL section of the DMCONFIG file.

• Domains local domain access—Restricts local services to remote domains. If a service is not exported to remote domains, it is unavailable to them. You export a service by placing an entry for the service in the DM_EXPORT section of the DMCONFIG file.
• Domains access control lists (ACLs)—Restricts the availability of services in a local domain to only certain remote domains. You create ACL names in the DM_ACCESS_CONTROL section of the DMCONFIG file and apply the ACL names to services in the EXPORT section of the DMCONFIG file.
• Domains ACL policy—Controls the ACL policy for remote domains. You configure a local or global ACL policy for a remote domain via the ACL_POLICY parameter in the DM_REMOTE section of the DMCONFIG file.
• Domains link-level encryption —Ensures data privacy between communicating domain gateways. For TDomain gateways, you configure link-level encryption by setting the MINENCRYPTBITS and MAXENCRYPTBITS parameters in the DM_TDOMAIN section of the DMCONFIG file.

As described in “Establishing a Link Between Domains” in Using Security in ATMI Applications, a local TDomain gateway needs an identity, or principal name, that both the local domain and a remote domain know about so that the remote domain can authenticate the local domain when the domains are attempting to connect to one another. Similarly, the remote TDomain gateway needs an identity, or principal name, that both the remote domain and the local domain know about so that the local domain can authenticate the remote domain when the domains are attempting to establish a connection to one another. In addition, the local TDomain gateway uses its assigned principal name to acquire a set of security credentials needed when setting up the connection.

The local TDomain gateway needs a second principle name to acquire a set of security credentials required to enforce the local access control list (ACL) policy described in How to Configure ACL Policy for a Remote Domain.

As the administrator, you use the following configuration parameters to specify the principal names for the TDomain gateways running in your Release 7.1 or later Oracle Tuxedo applications:

SEC_PRINCIPAL_NAME (string) in UBBCONFIG

Specifies the security principal name identification string to be used for authentication purposes by an application running Oracle Tuxedo 7.1 or later software. This parameter may contain a maximum of 511 characters (excluding the terminating NULL character). The principal name specified for this parameter becomes the identity of one or more system processes—including TDomain gateway (GWTDOMAIN) processes—running in this application.

During application booting, each TDomain gateway process in the application calls the authentication plug-in to acquire security credentials for the security principal name specified in SEC_PRINCIPAL_NAME. A TDomain gateway acquires these credentials for the principal name specified in the SEC_PRINCIPAL_NAME parameter.

CONNECTION_PRINCIPAL_NAME (string) in DM_LOCAL section of DMCONFIG

Specifies the connection principal name identifier, which is the principal name for verifying the identity of the domain gateway associated with this local domain access point when establishing a connection to a remote domain. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software.

The CONNECTION_PRINCIPAL_NAME parameter may contain a maximum of 511 characters (excluding the terminating NULL character). If this parameter is not specified, the connection principal name defaults to the ACCESSPOINTID string for this local domain access point.

For default authentication plug-ins, if a value is assigned to the CONNECTION_PRINCIPAL_NAME parameter for this local domain access point, it must be the same as the value assigned to the ACCESSPOINTID parameter for this local domain access point. If these values do not match, the local TDomain gateway process will not boot, and the system generates the following userlog(3c) message:

ERROR: Unable to acquire credentials

CONNECTION_PRINCIPAL_NAME (string) in DM_REMOTE section of DMCONFIG

Specifies the connection principal name identifier, which is the principal name for verifying the identity of this remote domain access point when establishing a connection to the local domain. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software.

The CONNECTION_PRINCIPAL_NAME parameter may contain a maximum of 511 characters (excluding the terminating NULL character). If this parameter is not specified, the connection principal name defaults to the ACCESSPOINTID string for this remote domain access point.

For default authentication plug-ins, if a value is assigned to the CONNECTION_PRINCIPAL_NAME parameter for this remote domain access point, it must be the same as the value assigned to the ACCESSPOINTID parameter for this remote domain access point. If these values do not match, any attempt to set up a connection between the local TDomain gateway and the remote TDomain gateway will fail, and the system will generate the following userlog(3c) message:

ERROR: Unable to initialize administration key for domain domain_name

In the following example, the CONNECTION_PRINCIPAL_NAME identities in the DMCONFIG file are used when establishing a connection through the LOCAL1 access point and the REMOT1 access point.

*DM_LOCAL
LOCAL1   GWGRP=bankg1
         TYPE=TDOMAIN
         ACCESSPOINTID="BA.CENTRAL01"
         CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"
*DM_REMOTE
REMOT1   TYPE=TDOMAIN
         ACCESSPOINTID="BA.BANK01"
         CONNECTION_PRINCIPAL_NAME="BA.BANK01"

• Overview
  
• Using the DM_MIB(5) to Set Domains Passwords (DM_PW)
  
• Using the dmadmin Command to Set Domains Passwords (DM_PW)
  
• Session Negotiation Phase Retry
  
• Examples of Coding Password Security Between Domains
  
• Using Triple-DES to Encrypt /Domain Password
  

To set up a Domains access control list (ACL) in the DM_ACCESS_CONTROL section of the DMCONFIG file, you specify the name of the ACL and the remote domain access points associated with the ACL name. The following table clarifies the procedure.

Upon creating an ACL, you use the ACL parameter in the DM_EXPORT section of the DMCONFIG file to restrict access to a local service exported through a particular local domain access point to just those remote domain access points associated with the ACL name (for example, ACL=ACLGRP1).

As the administrator, you use the following configuration parameters to set and control the ACL policy for remote domains running Oracle Tuxedo release 7.1 or later software. You set these parameters in the DM_REMOTE section of the DMCONFIG file.

• ACL_POLICY (LOCAL | GLOBAL)

  Specifies the access control list (ACL) policy for this remote domain access point. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software.

  LOCAL means that the local domain replaces the credential (identity) of any service request received from the remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME parameter for this remote domain access point. GLOBAL means that the local domain does not replace the credential received with a remote service request; if no credential is received with a remote service request, the local domain forwards the service request to the local service as is (which usually fails). If not specified, the default is LOCAL

• LOCAL_PRINCIPAL_NAME (string)

  The local principal name identifier (credential) assigned by the local domain to service requests received from the remote domain when the ACL_POLICY parameter for this remote domain access point is set (or defaulted) to LOCAL. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 7.1 or later software. The LOCAL_PRINCIPAL_NAME parameter may contain a maximum of 511 characters (excluding the terminating NULL character). If this parameter is not specified, the local principal name defaults to the ACCESSPOINTID string for this remote domain access point.

• CREDENTIAL_POLICY (LOCAL | GLOBAL)

  Specifies the credential policy for this remote domain access point. This parameter applies only to domain gateways of type TDOMAIN running Oracle Tuxedo 8.0 or later software. LOCAL means that the local domain removes the credential (identity) from a local service request destined for this remote domain access point. GLOBAL means that the local domain does not remove the credential from a local service request destined for this remote domain access point. If not specified, the default is LOCAL. Note that the CREDENTIAL_POLICY parameter controls whether or not the local domain removes the credential from a local service request before sending the request to a remote domain. The ACL_POLICY parameter controls whether or not the local domain replaces the credential of a service request received from a remote domain with the principal name specified in the LOCAL_PRINCIPAL_NAME parameter.

  In the following example, the connection for the REMOT1 access point is configured for global ACL in the DMCONFIG file, meaning that the domain gateway for the LOCAL1 access point passes client requests from the REMOT1 access point without change. For global ACL, the LOCAL_PRINCIPAL_NAME entry for the REMOT1 access point is ignored. Also, because CREDENTIAL_POLICY=GLOBAL, the domain gateway for the LOCAL1 access point does not remove the credential from any local service request destined for the REMOT1 access point.

*DM_LOCAL
LOCAL1   GWGRP=bankg1
         TYPE=TDOMAIN
         ACCESSPOINTID="BA.CENTRAL01"
         CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"
         SECURITY=DM_PW
*DM_REMOTE
REMOT1   TYPE=TDOMAIN
         ACCESSPOINTID="BA.BANK01"
         CONNECTION_PRINCIPAL_NAME="BA.BANK01"
         ACL_POLICY=GLOBAL
         CREDENTIAL_POLICY=GLOBAL
         LOCAL_PRINCIPAL_NAME="BA.BANK01.BOB"

Domains link-level encryption (LLE) establishes data privacy for messages moving over the network links that connect the local domain gateway to the remote domain gateway. There are three levels of link-level encryption security: 0-bit (no encryption), 56-bit (International), and 128-bit (United States and Canada).

To set up Domains link-level encryption on domain gateway links, follow these steps.

1. Open theDMCONFIG file with a text editor and add the following lines to the DM_TDOMAIN section.

   *DM_TDOMAIN
   LOCAL1   NWADDR=“newyork.acme.com:65431”
            MINENCRYPTBITS=min
            MAXENCRYPTBITS=max
   REMOT1   NWADDR=“albany.acme.com:4051”
            MINENCRYPTBITS=min
            MAXENCRYPTBITS=max

2. Load the configuration by running dmloadcf(1). The dmloadcf command parses DMCONFIG and loads the binary BDMCONFIG file to the location referenced by the BDMCONFIG variable.

In the preceding example, when tmboot(1) starts the application, each domain gateway reads the BDMCONFIG file to access various parameters, including MINENCRYPTBITS and MAXENCRYPTBITS, and propagates those parameters to its local and remote domains. When the local domain is establishing a network link with a remote domain, the two domains negotiate the key size until they agree on the largest key size supported by both.

A connection policy of ON_DEMAND (CONNECTION_POLICY=ON_DEMAND) means that a connection is attempted only when either a local client requests a remote service or an administrative dmadmin connect command is run. ON_DEMAND is the default connection policy setting.

The following figure shows how connections are attempted and made by a domain gateway for which the connection policy is ON_DEMAND.

Figure 2-6 Connections Made with an ON_DEMAND Policy

A connection policy of ON_STARTUP (CONNECTION_POLICY=ON_STARTUP) means that a domain gateway attempts to establish a connection with its remote domains when the domain gateway server is initialized. By default, the ON_STARTUP connection policy retries failed connections every 60 seconds, but you can specify a different value for this interval, as explained in How to Configure the Connection Retry Interval for ON_STARTUP Only.

The following figure shows how connections are attempted and made by a domain gateway for which the connection policy is ON_STARTUP.

Figure 2-7 Connections Made with an ON_STARTUP Policy

A connection policy of INCOMING_ONLY (CONNECTION_POLICY=INCOMING_ONLY) means that a domain gateway does not try to establish a connection to remote domains upon starting. The following figure illustrates how connections are attempted and made by a domain gateway for which the connection policy is INCOMING_ONLY.

Figure 2-8 Connections Made with an INCOMING_ONLY Policy (Accept Incoming Connections)

When the CONNECTION_POLICY parameter is set to ON_STARTUP, automatic connection retry processing is available. Connection retry processing enables a domain gateway to retry, automatically, a failed attempt to connect to a remote domain. As the administrator, you can control the frequency of automatic connection attempts. To do so, specify the length (in seconds) of the interval during which the gateway should wait before trying, again, to establish a connection. You can specify the retry interval by setting the RETRY_INTERVAL parameter as follows:

RETRY_INTERVAL=number_of_seconds 

You can specify between 0 and 2147483647 seconds. If the connection policy is ON_STARTUP and you do not specify a value for the RETRY_INTERVAL parameter, a default of 60 seconds is used.

The RETRY_INTERVAL parameter is valid only when the connection policy is ON_STARTUP. For the other connection policies (ON_DEMAND and INCOMING_ONLY), connection retry processing is not available.

You indicate the number of times that a domain gateway tries to establish connections to remote domains before quitting by assigning a value to the MAXRETRY parameter: the minimum value is 0; the default and maximum value is the value of the MAXLONG parameter (2147483647).

• If you set MAXRETRY=0, connection retry processing is turned off. The local domain gateway does not attempt to connect to the remote domain gateway(s) automatically.
• If you set MAXRETRY= number , the gateway tries to establish a connection the specified number of times before quitting.
• If you set MAXRETRY=MAXLONG, the default setting, connection retry processing is repeated up to 2147483647 times or until a connection is established.

The MAXRETRY parameter is valid only when the connection policy is ON_STARTUP. For the other connection policies (ON_DEMAND and INCOMING_ONLY), connection retry processing is not available.

The following table presents examples of how MAXRETRY and RETRY_INTERVAL affect automatic connection retry processing.

CONNECTION_POLICY=ON_STARTUP 
MAXRETRY=3
RETRY_INTERVAL=30

CONNECTION_POLICY=ON_STARTUP 
MAXRETRY=0

CONNECTION_POLICY=ON_STARTUP
RETRY_INTERVAL=30

Because domains involved in a Domains configuration work independently of one another, any combination of connection policies is allowed in a Domains configuration. However, not every connection policy combination is practical. In most cases, for example, configuring each of two interoperating domains with a connection policy of ON_STARTUP does not make much sense.

The following configuration example is a practical connection policy combination. In this example, LOCAL1 is configured for ON_STARTUP in the local DMCONFIG file, and REMOT1 is configured for INCOMING_ONLY in the remote DMCONFIG file.

In local DMCONFIG file:

*DM_LOCAL
LOCAL1    GWGRP=bankg1
          TYPE=TDOMAIN
          CONNECTION_POLICY=ON_STARTUP
          MAXRETRY=5
          RETRY_INTERVAL=100
*DM_REMOTE
REMOT1    TYPE=TDOMAIN
          ACCESSPOINTID="BA.BANK01"

In remote DMCONFIG file:

*DM_LOCAL
REMOT1    GWGRP=bankg2
          TYPE=TDOMAIN
          ACCESSPOINTID="BA.BANK01"
          CONNECTION_POLICY=INCOMING_ONLY
*DM_REMOTE
LOCAL1    TYPE=TDOMAIN
          ACCESSPOINTID="BA.CENTRAL01"
          CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"

To establish a connection between a local domain gateway and a remote domain, run the dmadmin command with the connect (co) sub command:

prompt> dmadmin co -d local_domain_access_point_name

By default, connections are established between the local domain you have specified and all remote domains configured for the local gateway. If you want to establish a connection to only one remote domain, specify that domain on the command line with the -R option:

prompt> dmadmin co -d local_domain_access_point_name -R remote_domain_access_point_name

If a connection attempt fails and the connection policy is ON_STARTUP with connection retry processing turned on, repeated attempts to connect (via connection retry processing) are made.

To break a connection between a local gateway and a remote domain (making sure that the gateway does not try to re-establish the connection through automatic connection retry processing), run the dmadmin command with the disconnect (dco) sub command:

prompt> dmadmin dco -d local_domain_access_point_name

By default, all remote domains configured for the local gateway are disconnected. If you want to end the connection to only one remote domain, specify that domain on the command line with the -R option:

prompt> dmadmin co -d local_domain_access_point_name -R remote_domain_access_point_name

Automatic connection retry processing is stopped by this command, regardless of whether there are any active connections when the command is run.

Using the dmadmin printdomain command, you can generate a report on connection status and the connections being retried. The connect command reports whether a connection attempt has succeeded. The printdomain command prints information about the specified local domain, including a list of remote domains, a list of remote domains to which it is connected, and a list of remote domains to which it is trying to establish connections.

The following example shows a dmadmin session in which the printdomain command is issued (in its abbreviated form, pd) for a local domain access point named LOCAL1.

prompt> dmadmin
dmadmin - Copyright ...
.
.
.
pd -d LOCAL1
Local domain :LOCAL1
Connected domains:
Domainid: REMOT1
Disconnected domains being retried:
Domainid: REMOT2
dco -d LOCAL1 -R REMOT1
Operation completed successfully. Use printdomain(pd) to obtain results.
dco -d LOCAL1 -R REMOT2
Operation completed successfully. Use printdomain(pd) to obtain results.
co -d LOCAL1 -R REMOT1
Operation completed successfully. Use printdomain(pd) to obtain results.
pd -d LOCAL1
Local domain :LOCAL1
Connected domains:
Domainid: REMOT1

In this example, the remote domain access point names (REMOT1, REMOT2) and their DOMAINID—ACCESSPOINTID—names (REMOT1, REMOT2) are the same, as defined in the DM_REMOTE section of the DMCONFIG file, to keep the example simple.

Domain connection events are generated by default when configuration or connection status changes occur between two or more domains; however, you must subscribe to a domain connection event in order to display/output warning or error messages.

Tuxedo generates the following four domain connection events:

• .SysConnectionSuccess - Connection successfully established
• .SysConnectionConfig - Connection configuration has changed. The Connection configuration changed event may happen when the following configuration parameters change between two domains:
  • CONNECTION_POLICY
  • CMPLIMIT
  • MINENCRYPTBITS
  • MAXENCRYPTBITS
  • RETRY_INTERVAL
  • MAXRETRY
  • DMKEEPALIVE
  • DMKEEPALIVEWAIT
  • TCPKEEPALIVE

  When several parameters are changed in one operation (DMMIB ordmadmin), only one event is generated.

• .SysConnectionDropped - Connection has dropped. The .SysConnectionDropped event must also indicate the reason for the drop. There are three specific reasons why a connection drop can occur and each of them must be appended to the INFO message. They are:
  • ·LDOM issued disconnect
  • ·RDOM issued disconnect
  • ·Unknown connection loss
• .SysConnectionFailed - Connection is unsuccessful. The .SysConnectionFailed event also indicates the reason for failure. There can be several reasons for why a failure and all must be appended to the INFO message:
  • ·Socket Failure
  • ·Authentication Failure
  • ·Unconfigured RDOM

Session Negotiation Phase Timeout causes the GWTDOMAIN gateway to close the connection if the remote GWTDOMAIN gateway does not finish each protocol state in the specified time, or does not finish the whole Session Negotiation protocol in a specific time frame when trying to establish a TDOMAIN session between the two GWTDOMAIN gateways. It is useful in defending against SYN flood type DoS attacks.

No configuration change is required. The default session establishing phase timeout value is preset to 10 minutes, and there is no individual state timeout. This must be large enough to be close to past behavior, (that is, no session negotiation phase timeout). You must be able to overwrite it using the following environment variables: GWT_SNP_TIMEOUT, and GWT_SNS_TIMEOUT. The default value of GWT_SNP_TIMEOUT is 0, and the default value for GWT_SNS_TIMEOUT is 0.

The measurement value for both environmental variables is in seconds. To disable this feature, set both timeout values to 0. For release earlier than Tuxedo 8.1, the resolution of the timeout value is limited to a multiple of the scan unit, so the smallest timeout value is one UBB scan unit. For release 8.1 and later, the smallest timeout resolution is 1 second.

GWT_SNP_TIMEOUT is used for overall timeouts. From socket opening to establishing a TDOMAIN session, this includes several protocol states. GWT_SNS_TIMEOUT is used for each individual protocol state. If a timeout occurs, and the state has not transitioned to next state, the connection is closed. Any one of the two timeouts causes the connection to close prematurely. If the connection policy for that connection is ON_STARTUP, then GWTDOMAIN gateway schedules a reconnect event at the next RETRY_INTERVAL time.

• Environment Variables