Planning and Configuring ATMI Domains

2 Planning and Configuring ATMI Domains

The following sections explain how to plan and configure a domain for an Oracle Tuxedo ATMI Domains environment:

2.1 Planning to Build Domains from Multiple Oracle Tuxedo Applications

The following figure illustrates two Oracle Tuxedo applications: the bankapp application and a credit card authorization application.

Figure 2-1 Two Oracle Tuxedo Applications

The bankapp application connects ATMs at various bank branches to the central bank office. The credit card authorization application processes customer requests for credit cards. Over time, the bank managers realize that their customers would be better served if the bankapp application could communicate directly with the credit card authorization application. With direct communication, the bank could offer instant credit cards to anyone opening a new account.

The bankapp application is a sample application included with the Oracle Tuxedo distribution, and the credit card authorization application is a hypothetical extension of bankapp. The bankapp application files reside at the following location:

tux_prod_dir\samples\atmi\bankapp (Windows)
tux_prod_dir/samples/atmi/bankapp (UNIX)

Where tux_prod_dir represents the directory in which the Oracle Tuxedo distribution is installed.

The following Listing shows the content of a file named ubbmp, which is the UBBCONFIG file for the multiple-machine version of the bankapp application.

Listing ubbmp Configuration File for the bankapp Application

.
.
.
*RESOURCES
IPCKEY           80952
UID              <user id from id(1)>
GID              <group id from id(1)>
PERM             0660
MAXACCESSERS     40
MAXSERVERS       35
MAXSERVICES      75
MAXCONV          10
MAXGTT           20
MASTER           SITE1,SITE2
SCANUNIT         10
SANITYSCAN       12
BBLQUERY         30
BLOCKTIME        30
DBBLWAIT         6
OPTIONS          LAN,MIGRATE
MODEL            MP
LDBAL            Y
##SECURITY       ACL
##AUTHSVC        "..AUTHSVC"
#
*MACHINES
<SITE1's uname>  LMID=SITE1
                 TUXDIR="<TUXDIR1>"
                 APPDIR="<APPDIR1>"
                 ENVFILE="<APPDIR1>/ENVFILE"
                 TLOGDEVICE="<APPDIR1>/TLOG"
                 TLOGNAME=TLOG
                 TUXCONFIG="<APPDIR1>/tuxconfig"
                 TYPE="<machine type1>"
                 ULOGPFX="<APPDIR1>/ULOG"
<SITE2's uname>  LMID=SITE2
                 TUXDIR="<TUXDIR2>"
                 APPDIR="<APPDIR2>"
                 ENVFILE="<APPDIR2>/ENVFILE"
                 TLOGDEVICE="<APPDIR2>/TLOG"
                 TLOGNAME=TLOG
                 TUXCONFIG="<APPDIR2>/tuxconfig"
                 TYPE="<machine type2>"
                 ULOGPFX="<APPDIR2>/ULOG"
#
*GROUPS
#
# Group for Authentication Servers
#
##AUTHGRP        LMID=SITE1   GRPNO=101
#
# Group for Application Queue (/Q) Servers
#
##QGRP1          LMID=SITE1   GRPNO=102
##               TMSNAME=TMS_QM  TMSCOUNT=2
##               OPENINFO="TUXEDO/QM:<APPDIR1>/qdevice:QSP_BANKAPP"
#
# Group for Application Manager's Servers
#
##MGRGRP1        LMID=SITE1   GRPNO=103
#
# Group for EventBroker Servers
#
##EVBGRP1        LMID=SITE1   GRPNO=104
DEFAULT:         TMSNAME=TMS_SQL   TMSCOUNT=2
BANKB1           LMID=SITE1   GRPNO=1
                 OPENINFO="TUXEDO/SQL:<APPDIR1>/bankdl1:bankdb:readwrite"
BANKB2           LMID=SITE2   GRPNO=2
                 OPENINFO="TUXEDO/SQL:<APPDIR2>/bankdl2:bankdb:readwrite"
*NETWORK
SITE1            NADDR="<network address of SITE1>"
                 BRIDGE="<device of provider1>"
                 NLSADDR="<network listener address of SITE1>"
SITE2            NADDR="<network address of SITE2>"
                 BRIDGE="<device of provider2>"
                 NLSADDR="<network listener address of SITE2>"
*SERVERS
#
# TUXEDO System /T server providing application specific authentication.
# Ref. AUTHSVR(5).
#
##AUTHSVR        SRVGRP=AUTHGRP  SRVID=1  RESTART=Y  GRACE=0  MAXGEN=2
##               CLOPT="-A"
#
# TUXEDO System /T Message Queue Manager. It is a server that enqueues and
# dequeues messages on behalf of programs calling tpenqueue(3) and
# tpdequeue(3) respectively. Ref. TMQUEUE(5).
#
##TMQUEUE        SRVGRP=QGRP1    SRVID=1  CONV=N  GRACE=0
##               CLOPT="-s QSP_BANKAPP:TMQUEUE"
#
# TUXEDO System /T Message Forwarding Server that forwards messages that have
# been stored using tpenqueue(3) for later processing. Ref. TMQFORWARD(5).
#
##TMQFORWARD     SRVGRP=QGRP1    SRVID=2  CONV=N  REPLYQ=N  GRACE=0
##               CLOPT="-- -e -n -d -q Q_OPENACCT_LOG"
#
# TUXEDO System /T User Event Broker that manages user events by notifying
# subscribers when those events are posted. Ref. TMUSREVT(5).
#
##TMUSREVT       SRVGRP=EVBGRP1  SRVID=1  GRACE=3600
##               ENVFILE="<APPDIR1>/TMUSREVT.ENV"
##               CLOPT="-e tmusrevt.out -o tmusrevt.out -A --
##                    -f <APPDIR1>/tmusrevt.dat"
##               SEQUENCE=11
#
# TUXEDO Application Server that subscribes to certain events.
#
##ACCTMGR SRVGRP=MGRGRP1         SRVID=1
##               CLOPT="-A -o ACCTMGR.LOG -- -w 1000.00"
##               SEQUENCE=12
DEFAULT: RESTART=Y    MAXGEN=5   REPLYQ=Y  CLOPT="-A"
TLR              SRVGRP=BANKB1   SRVID=1  RQADDR=tlr1
                 CLOPT="-A -- -T 100 -e 1000.00"
TLR              SRVGRP=BANKB1   SRVID=2  RQADDR=tlr1
                 CLOPT="-A -- -T 200 -e 1000.00"
TLR              SRVGRP=BANKB2   SRVID=3  RQADDR=tlr2
                 CLOPT="-A -- -T 600 -e 1000.00"
TLR              SRVGRP=BANKB2   SRVID=4  RQADDR=tlr2
                 CLOPT="-A -- -T 700 -e 1000.00"
XFER             SRVGRP=BANKB1   SRVID=5
XFER             SRVGRP=BANKB2   SRVID=6
ACCT             SRVGRP=BANKB1   SRVID=7
ACCT             SRVGRP=BANKB2   SRVID=8
BAL              SRVGRP=BANKB1   SRVID=9
BAL              SRVGRP=BANKB2   SRVID=10
BTADD            SRVGRP=BANKB1   SRVID=11
BTADD            SRVGRP=BANKB2   SRVID=12
AUDITC           SRVGRP=BANKB1   SRVID=13  CONV=Y  MIN=1 MAX=10 RQADDR="auditc"
BALC             SRVGRP=BANKB1   SRVID=24
BALC             SRVGRP=BANKB2   SRVID=25
#
*SERVICES
DEFAULT:         LOAD=50  AUTOTRAN=Y  TRANTIME=30
WITHDRAWAL       PRIO=50  ROUTING=ACCOUNT_ID
DEPOSIT          PRIO=50  ROUTING=ACCOUNT_ID
TRANSFER         PRIO=50  ROUTING=ACCOUNT_ID
INQUIRY          PRIO=50  ROUTING=ACCOUNT_ID
CLOSE_ACCT       PRIO=40  ROUTING=ACCOUNT_ID
OPEN_ACCT        PRIO=40  ROUTING=BRANCH_ID
BR_ADD           PRIO=20  ROUTING=BRANCH_ID
TLR_ADD          PRIO=20  ROUTING=BRANCH_ID
ABAL             PRIO=30  ROUTING=b_id
TBAL             PRIO=30  ROUTING=b_id
ABAL_BID         PRIO=30  ROUTING=b_id
TBAL_BID         PRIO=30  ROUTING=b_id
ABALC_BID        PRIO=30  ROUTING=b_id
TBALC_BID        PRIO=30  ROUTING=b_id
#
*ROUTING
ACCOUNT_ID       FIELD=ACCOUNT_ID
                 BUFTYPE="FML"
                 RANGES="10000-59999:BANKB1,
                         60000-109999:BANKB2"
BRANCH_ID        FIELD=BRANCH_ID
                 BUFTYPE="FML"
                 RANGES="1-5:BANKB1,
                         6-10:BANKB2"
b_id             FIELD=b_id
                 BUFTYPE="VIEW:aud"
                 RANGES="1-5:BANKB1,
                         6-10:BANKB2"

The following sections demonstrate two different ways of reconfiguring the bankapp application and the credit card authorization application so that they can communicate directly with one another:

Parent topic: Planning and Configuring ATMI Domains

2.1.1 Option 1: Reconfigure the Applications as a Single Oracle Tuxedo Domain

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

Combining Two Oracle Tuxedo System Applications Diagram

Parent topic: Planning to Build Domains from Multiple Oracle Tuxedo Applications

2.1.1.1 Creating the UBBCONFIG File for the Combined Application

To create the UBBCONFIG file for the combined application, take the following information from the UBBCONFIG file for the credit card authorization application and add it to the UBBCONFIG file for the bankapp application:

Add machine, network, and group entries for the credit card authorization application to the UBBCONFIG file.
Add Server entries for the credit card authorization application to the UBBCONFIG file.
Add Service entries for the credit card authorization to the UBBCONFIG file.

The following Listing shows a possible UBBCONFIG file for the combined application.

Listing Sample UBBCONFIG File for the Combined Application

*RESOURCES
IPCKEY 76666
UID 0000
GID 000
PERM 0660
MAXACCESSERS 40
MAXSERVERS 35
MAXSERVICES 75
MAXCONV 10
MAXGTT 100
MASTER SITE1,SITE2
SCANUNIT 10
SANITYSCAN 5
BBLQUERY 50
BLOCKTIME 2
DBBLWAIT 6
OPTIONS LAN,MIGRATE
MODEL MP
LDBAL Y
#
*MACHINES
#
# Machines for the bankapp part
mach1            LMID=SITE1
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
ENVFILE=“/home/rsmith/bankapp/ENVFILE”
TLOGDEVICE=“/home/rsmith/bankapp/TLOG”
TLOGNAME=TLOG
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
                 TYPE=“type1”
                 ULOGPFX=“/home/rsmith/bankapp/ULOG”
mach2            LMID=SITE2
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
ENVFILE=“/home/rsmith/bankapp/ENVFILE”
TLOGDEVICE=“/home/rsmith/bankapp/TLOG”
TLOGNAME=TLOG
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
TYPE=“type2”
ULOGPFX=“/home/rsmith/bankapp/ULOG”
mach3            LMID=SITE3
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
ENVFILE=“/home/rsmith/bankapp/ENVFILE”
TLOGDEVICE=“/home/rsmith/bankapp/TLOG”
TLOGNAME=TLOG
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
TYPE=“type2”
ULOGPFX=“/home/rsmith/bankapp/ULOG”
#
# Machine for the credit card authorization part
sfexpz           LMID=SITE4
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
ENVFILE=“/home/rsmith/bankapp/ENVFILE”
TLOGDEVICE=“/home/rsmith/bankapp/TLOG”
TLOGNAME=TLOG
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
                 TYPE=“type1”
                 ULOGPFX=“/home/rsmith/bankapp/ULOG”
#
*GROUPS
DEFAULT: TMSNAME=TMS_SQL TMSCOUNT=2
#
# Groups for the bankapp part
BANKB1 LMID=SITE1 GRPNO=1
          OPENINFO=“TUXEDO/SQL:/home/rsmith/bankapp/bankdl1:bankdb:readwrite”
BANKB2    LMID=SITE2 GRPNO=2
          OPENINFO=“TUXEDO/SQL:/home/rsmith/bankapp/bankdl2:bankdb:readwrite”
BANKB3    LMID=SITE3 GRPNO=3
          OPENINFO=“TUXEDO/SQL:/home/rsmith/bankapp/bankdl3:bankdb:readwrite”
#
# Group for the credit card authorization part
CREDIT    LMID=SITE4 GRPNO=4
          OPENINFO=“TUXEDO/SQL:/home/rsmith/bankapp/crdtdl1:bankdb:readwrite”
#
*NETWORK
#
# Network connections for the bankapp part
SITE1  NADDR=“<network address of SITE1>”
 BRIDGE=“<device of provider1>”
 NLSADDR=“<network listener address of SITE1>”
SITE2  NADDR=“<network address of SITE2>”
 BRIDGE=“<device of provider2>”
 NLSADDR=“<network listener address of SITE2>”
SITE3  NADDR=“<network address of SITE3>”
 BRIDGE=“<device of provider3>”
 NLSADDR=“<network listener address of SITE3>”
#
# Network connections for the credit card authorization part
SITE4  NADDR=“<network address of SITE4>”
 BRIDGE=“<device of provider4>”
 NLSADDR=“<network listener address of SITE4>”
#
*SERVERS
DEFAULT:  RESTART=Y       MAXGEN=5      REPLYQ=Y   CLOPT=“-A”
#
# Servers for the bankapp part
TLR   SRVGRP=BANKB1 SRVID=1       RQADDR=tlr1
          CLOPT=“-A -- -T 100 -e 1000.00”
TLR   SRVGRP=BANKB1   SRVID=2       RQADDR=tlr1
          CLOPT=“-A -- -T 200 -e 1000.00”
TLR   SRVGRP=BANKB2   SRVID=3       RQADDR=tlr2
          CLOPT=“-A -- -T 600 -e 1000.00”
TLR   SRVGRP=BANKB2   SRVID=4       RQADDR=tlr2
          CLOPT=“-A -- -T 700 -e 1000.00”
TLR   SRVGRP=BANKB3   SRVID=5       RQADDR=tlr3
          CLOPT=“-A -- -T 800 -e 1000.00”
TLR   SRVGRP=BANKB3 SRVID=6       RQADDR=tlr3
          CLOPT=“-A -- -T 900” -e 1000.00
XFER   SRVGRP=BANKB1 SRVID=7
XFER   SRVGRP=BANKB2 SRVID=8
XFER   SRVGRP=BANKB3 SRVID=9
ACCT   SRVGRP=BANKB1 SRVID=10
ACCT   SRVGRP=BANKB2 SRVID=11
ACCT   SRVGRP=BANKB3 SRVID=12
BAL       SRVGRP=BANKB1 SRVID=13
BAL       SRVGRP=BANKB2 SRVID=14
BAL       SRVGRP=BANKB3 SRVID=15
BTADD     SRVGRP=BANKB1 SRVID=16
BTADD     SRVGRP=BANKB2 SRVID=17
BTADD     SRVGRP=BANKB3 SRVID=18
AUDITC    SRVGRP=BANKB1 SRVID=19      CONV=Y  MIN=1  MAX=10  RQADDR=”auditc”
BALC      SRVGRP=BANKB1 SRVID=20
BALC      SRVGRP=BANKB2 SRVID=21
BALC      SRVGRP=BANKB3 SRVID=22
#
# Servers for the credit card authorization part
TLRA   SRVGRP=CREDIT   SRVID=26
          CLOPT=“-A -- -T 300”
ACCTA   SRVGRP=CREDIT   SRVID=27
CRDT   SRVGRP=CREDIT   SRVID=35
#
*SERVICES
DEFAULT:  LOAD=50  AUTOTRAN=Y  TRANTIME=30
#
# Services for the bankapp part
WITHDRAWAL       PRIO=50  ROUTING=ACCOUNT_ID
DEPOSIT          PRIO=50  ROUTING=ACCOUNT_ID
TRANSFER         PRIO=50  ROUTING=ACCOUNT_ID
INQUIRY          PRIO=50  ROUTING=ACCOUNT_ID
CLOSE_ACCT       PRIO=40  ROUTING=ACCOUNT_ID
OPEN_ACCT        PRIO=40  ROUTING=BRANCH_ID
BR_ADD           PRIO=20  ROUTING=BRANCH_ID
TLR_ADD          PRIO=20  ROUTING=BRANCH_ID
ABAL             PRIO=30  ROUTING=b_id
TBAL             PRIO=30  ROUTING=b_id
ABAL_BID         PRIO=30  ROUTING=b_id
TBAL_BID         PRIO=30  ROUTING=b_id
ABALC_BID        PRIO=30  ROUTING=b_id
TBALC_BID        PRIO=30  ROUTING=b_id
#
# Services for the credit card authorization part
WITHDRAWALA  PRIO=50
INQUIRYA  PRIO=50
OPENCA  PRIO=40
CLOSECA  PRIO=40
DEPOSITA  PRIO=50
OPEN_ACCT2  PRIO=40
OPENC  PRIO=40
#
*ROUTING
ACCOUNT_ID       FIELD=ACCOUNT_ID
                 BUFTYPE=“FML”
                 RANGES=“10000-39999:BANKB1,
                         40000-69999:BANKB2,
                         70000-109999:BANKB3,
                         *:*”
BRANCH_ID        FIELD=BRANCH_ID
                 BUFTYPE=“FML”
                 RANGES=“1-5:BANKB1,
                         6-10:BANKB2,
                         11-15:BANKB3”
b_id             FIELD=b_id
                 BUFTYPE="VIEW:aud"
                 RANGES="1-5:BANKB1,
                         6-10:BANKB2,
                         11-15:BANKB3"

Parent topic: Option 1: Reconfigure the Applications as a Single Oracle Tuxedo Domain

2.1.1.2 Limitations of Option 1

Administering a single large application can be more cumbersome than administering two smaller ones; each smaller one has its own UBBCONFIG file and hence its own administrative interface.
Booting a networked application can be more costly because of the time required to boot each server and because of the need to propagate bulletin boards across the network. Smaller, separate applications can be booted simultaneously.

Parent topic: Option 1: Reconfigure the Applications as a Single Oracle Tuxedo Domain

2.1.2 Option 2: Reconfigure the Applications as a Domains Configuration

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.

Parent topic: Planning to Build Domains from Multiple Oracle Tuxedo Applications

2.1.2.1 Creating the UBBCONFIG File for the bankapp Application in the Domains Environment

To create the UBBCONFIG file for the bankapp application in the Domains environment, start with a copy of the UBBCONFIG file shown in Sample UBBCONFIG File for the Combined Application and make the following changes:

In the MACHINES section, remove the machine entry for the credit card authorization application.
In the NETWORK section, remove the network entry for the credit card authorization application.
In the GROUPS section, do the following:
- Remove the group entry for the credit card authorization application.
- Add a group entry for the DMADM server and a different group entry for the GWADM and GWTDOMAIN servers.
In the SERVERS section, do the following:
- Remove the server entries for the credit card authorization application.
- Add server entries for the DMADM, GWADM, and GWTDOMAIN servers.
In the SERVICES section, remove the service entries for the credit card authorization application.

The following Listing shows a possible UBBCONFIG file for the bankapp application in the Domains environment.

Listing Sample UBBCONFIG File for the bankapp Application in the Domains Environment

*RESOURCES
IPCKEY 76666
UID 0000
GID 000
PERM 0660
MAXACCESSERS 40
MAXSERVERS 35
MAXSERVICES 75
MAXCONV 10
MAXGTT 100
MASTER SITE1,SITE2
SCANUNIT 10
SANITYSCAN 5
BBLQUERY 50
BLOCKTIME 2
DBBLWAIT 6
OPTIONS LAN,MIGRATE
MODEL MP
LDBAL Y
MAXBUFTYPE 16
#
*MACHINES
mach1            LMID=SITE1
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
ENVFILE=“/home/rsmith/bankapp/ENVFILE”
TLOGDEVICE=“/home/rsmith/bankapp/TLOG”
TLOGNAME=TLOG
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
                 TYPE=“type1”
                 ULOGPFX=“/home/rsmith/bankapp/ULOG”
mach2            LMID=SITE2
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
ENVFILE=“/home/rsmith/bankapp/ENVFILE”
TLOGDEVICE=“/home/rsmith/bankapp/TLOG”
TLOGNAME=TLOG
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
TYPE=“type2”
ULOGPFX=“/home/rsmith/bankapp/ULOG”
mach3            LMID=SITE3
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/bankapp”
ENVFILE=“/home/rsmith/bankapp/ENVFILE”
TLOGDEVICE=“/home/rsmith/bankapp/TLOG”
TLOGNAME=TLOG
TUXCONFIG=“/home/rsmith/bankapp/tuxconfig”
TYPE=“type2”
ULOGPFX=“/home/rsmith/bankapp/ULOG”
#
*GROUPS
DEFAULT: TMSNAME=TMS_SQL  TMSCOUNT=2
#
# Groups for bankapp
BANKB1 LMID=SITE1       GRPNO=1
          OPENINFO=“TUXEDO/SQL:/home/rsmith/bankapp/bankdl1:bankdb:readwrite”
BANKB2    LMID=SITE2       GRPNO=2
          OPENINFO=“TUXEDO/SQL:/home/rsmith/bankapp/bankdl2:bankdb:readwrite”
BANKB3    LMID=SITE3       GRPNO=3
          OPENINFO=“TUXEDO/SQL:/home/rsmith/bankapp/bankdl3:bankdb:readwrite”
#
# Groups for Domains
DMADMGRP  LMID=SITE1       GRPNO=4
GWTGROUP  LMID=SITE2       GRPNO=5
#
*NETWORK
SITE1  NADDR=“<network address of SITE1>”
 BRIDGE=“<device of provider1>”
 NLSADDR=“<network listener address of SITE1>”
SITE2  NADDR=“<network address of SITE2>”
 BRIDGE=“<device of provider2>”
 NLSADDR=“<network listener address of SITE2>”
SITE3  NADDR=“<network address of SITE3>”
 BRIDGE=“<device of provider3>”
 NLSADDR=“<network listener address of SITE3>”
#
*SERVERS
DEFAULT:  RESTART=Y       MAXGEN=5 REPLYQ=Y CLOPT=“-A”
#
# Servers for Domains
DMADM     SRVGRP=DMADMGRP
          SRVID=1001
          REPLYQ=N
          RESTART=Y
          GRACE=0
GWADM     SRVGRP=GWTGROUP
          SRVID=1002
          REPLYQ=N
          RESTART=Y
          GRACE=0
GWTDOMAIN SRVGRP=GWTGROUP
          SRVID=1003
          RQADDR=”GWTGROUP”
          REPLYQ=N
          RESTART=Y
          GRACE=0
#
# Servers for bankapp
TLR   SRVGRP=BANKB1 SRVID=1       RQADDR=tlr1
          CLOPT=“-A -- -T 100 -e 1000.00”
TLR   SRVGRP=BANKB1   SRVID=2       RQADDR=tlr1
          CLOPT=“-A -- -T 200 -e 1000.00”
TLR   SRVGRP=BANKB2   SRVID=3       RQADDR=tlr2
          CLOPT=“-A -- -T 600 -e 1000.00”
TLR   SRVGRP=BANKB2   SRVID=4       RQADDR=tlr2
          CLOPT=“-A -- -T 700 -e 1000.00”
TLR   SRVGRP=BANKB3   SRVID=5       RQADDR=tlr3
          CLOPT=“-A -- -T 800 -e 1000.00”
TLR   SRVGRP=BANKB3 SRVID=6       RQADDR=tlr3
          CLOPT=“-A -- -T 900” -e 1000.00
XFER   SRVGRP=BANKB1 SRVID=7
XFER   SRVGRP=BANKB2 SRVID=8
XFER   SRVGRP=BANKB3 SRVID=9
ACCT   SRVGRP=BANKB1 SRVID=10
ACCT   SRVGRP=BANKB2 SRVID=11
ACCT   SRVGRP=BANKB3 SRVID=12
BAL       SRVGRP=BANKB1 SRVID=13
BAL       SRVGRP=BANKB2 SRVID=14
BAL       SRVGRP=BANKB3 SRVID=15
BTADD     SRVGRP=BANKB1 SRVID=16
BTADD     SRVGRP=BANKB2 SRVID=17
BTADD     SRVGRP=BANKB3 SRVID=18
AUDITC    SRVGRP=BANKB1 SRVID=19      CONV=Y  MIN=1  MAX=10  RQADDR=”auditc”
BALC      SRVGRP=BANKB1 SRVID=20
BALC      SRVGRP=BANKB2 SRVID=21
BALC      SRVGRP=BANKB3 SRVID=22
#
*SERVICES
DEFAULT:  LOAD=50  AUTOTRAN=Y  TRANTIME=30
WITHDRAWAL       PRIO=50  ROUTING=ACCOUNT_ID
DEPOSIT          PRIO=50  ROUTING=ACCOUNT_ID
TRANSFER         PRIO=50  ROUTING=ACCOUNT_ID
INQUIRY          PRIO=50  ROUTING=ACCOUNT_ID
CLOSE_ACCT       PRIO=40  ROUTING=ACCOUNT_ID
OPEN_ACCT        PRIO=40  ROUTING=BRANCH_ID
BR_ADD           PRIO=20  ROUTING=BRANCH_ID
TLR_ADD          PRIO=20  ROUTING=BRANCH_ID
ABAL             PRIO=30  ROUTING=b_id
TBAL             PRIO=30  ROUTING=b_id
ABAL_BID         PRIO=30  ROUTING=b_id
TBAL_BID         PRIO=30  ROUTING=b_id
ABALC_BID        PRIO=30  ROUTING=b_id
TBALC_BID        PRIO=30  ROUTING=b_id
#
*ROUTING
ACCOUNT_ID       FIELD=ACCOUNT_ID
                 BUFTYPE=“FML”
                 RANGES=“10000-39999:BANKB1,
                         40000-69999:BANKB2,
                         70000-109999:BANKB3,
                         *:*”
BRANCH_ID        FIELD=BRANCH_ID
                 BUFTYPE=“FML”
                 RANGES=“1-5:BANKB1,
                         6-10:BANKB2,
                         11-15:BANKB3”
b_id             FIELD=b_id
                 BUFTYPE="VIEW:aud"
                 RANGES="1-5:BANKB1,
                         6-10:BANKB2,
                         11-15:BANKB3"

Note:

In the previous example, REPLYQ=N is specified for the DMADM, GWADM, and GWTDOMAIN servers. This setting is not required: you can, if you prefer, designate a reply queue for any of these servers by specifying REPLYQ=Y. When REPLYQ is set to N, however, performance may be improved.

Parent topic: Option 2: Reconfigure the Applications as a Domains Configuration

2.1.2.2 Creating a DMCONFIG File for the bankapp Application

You also need to create a DMCONFIG file for the bankapp application, an example of which is shown in the following Listing 2‑4. The binary version of the a DMCONFIG file (BDMCONFIG) must reside on the same machine as the DMADM server.

Listing Sample DMCONFIG File for the bankapp Application

*DM_LOCAL
LOCAL1       GWGRP=GWTGROUP
             TYPE=TDOMAIN
             ACCESSPOINTID=”BANK”
             BLOCKTIME=10
             CONNECTION_POLICY=ON_STARTUP
             DMTLOGDEV=“/home/rsmith/bankapp/DMTLOG”
             AUDITLOG=“/home/rsmith/bankapp/AUDITLOG”
#
*DM_REMOTE
REMOT1       TYPE=TDOMAIN
             ACCESSPOINTID=”CREDIT.CARD”
#
# If the DM_EXPORT section is absent, as in this sample DMCONFIG
# file, all services advertised by the local domain are available
# to the remote domains. Thus, the following bankapp services are
# available to the credit card authorization application:
#
# WITHDRAWAL
# DEPOSIT
# TRANSFER
# INQUIRY
# CLOSE_ACCT
# OPEN_ACCT
# BR_ADD
# TLR_ADD
# ABAL
# TBAL
# ABAL_BID
# TBAL_BID
# ABALC_BID
# TBALC_BID
#
*DM_IMPORT
WITHDRAWALA  RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
INQUIRYA     RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
OPENCA       RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
CLOSECA      RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
DEPOSITA     RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
OPEN_ACCT2   RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
OPENC        RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
#
*DM_TDOMAIN
LOCAL1       NWADDR=“albany.acme.com:4051”
REMOT1       NWADDR=“newyork.acme.com:65431”

Parent topic: Option 2: Reconfigure the Applications as a Domains Configuration

2.1.2.3 Creating the UBBCONFIG File for the Credit Card Authorization Application in the Domains Environment

To create the UBBCONFIG file for the credit card authorization application in the Domains environment, make the following changes to the UBBCONFIG file for the credit card authorization application:

In the GROUPS section, add a group entry for the DMADM server and a different group entry for the GWADM and GWTDOMAIN servers.
In the SERVERS section, add server entries for the DMADM, GWADM, and GWTDOMAIN servers.

The following Listing shows a possible UBBCONFIG file for the credit card authorization application in the Domains environment.

Listing Sample UBBCONFIG File for the Credit Card Authorization Application in the Domains Environment

*RESOURCES
IPCKEY 76666
UID 0000
GID 000
PERM 0660
MAXACCESSERS 40
MAXSERVERS 35
MAXSERVICES 75
MAXCONV 10
MAXGTT 100
MASTER SITE1
SCANUNIT 10
MODEL            SHM
LDBAL Y
#
*MACHINES
sfexpz           LMID=SITE1
TUXDIR=“/home/rsmith/tuxroot”
APPDIR=“/home/rsmith/creditapp”
ENVFILE=“/home/rsmith/creditapp/ENVFILE”
TLOGDEVICE=“/home/rsmith/creditapp/TLOG”
TLOGNAME=TLOG
TUXCONFIG=“/home/rsmith/creditapp/tuxconfig”
                 TYPE=“type1”
                 ULOGPFX=“/home/rsmith/creditapp/ULOG”
#
*GROUPS
DEFAULT: TMSNAME=TMS_SQL  TMSCOUNT=2
#
# Group for credit card authorization
CREDIT    LMID=SITE1      GRPNO=1
          OPENINFO=“TUXEDO/SQL:/home/rsmith/creditapp/crdtdl1:bankdb:readwrite”
#
# Groups for Domains
DMADMGRP  LMID=SITE1      GRPNO=2
GWTGROUP  LMID=SITE1      GRPNO=3
#
*SERVERS
DEFAULT:  RESTART=Y        MAXGEN=5  REPLYQ=Y  CLOPT=“-A”
#
# Servers for Domains
DMADM     SRVGRP=DMADMGRP
          SRVID=50
          REPLYQ=N
          RESTART=Y
          GRACE=0
GWADM     SRVGRP=GWTGROUP
          SRVID=60
          REPLYQ=N
          RESTART=Y
          GRACE=0
GWTDOMAIN SRVGRP=GWTGROUP
          SRVID=70
          RQADDR=”GWTGROUP”
          REPLYQ=N
          RESTART=Y
          GRACE=0
#
# Servers for credit card authorization
TLRA   SRVGRP=CREDIT   SRVID=1
          CLOPT=“-A -- -T 600”
ACCTA   SRVGRP=CREDIT   SRVID=2
CRDT   SRVGRP=CREDIT   SRVID=3
#
*SERVICES
DEFAULT:  LOAD=50  AUTOTRAN=Y  TRANTIME=30
# Services for credit card authorization
WITHDRAWALA  PRIO=50
INQUIRYA  PRIO=50
OPENCA  PRIO=40
CLOSECA  PRIO=40
DEPOSITA  PRIO=50
OPEN_ACCT2  PRIO=40
OPENC  PRIO=40

Note:

Parent topic: Option 2: Reconfigure the Applications as a Domains Configuration

2.1.2.4 Creating a DMCONFIG File for the Credit Card Authorization Application

You also need to create a DMCONFIG file for the credit card authorization application, an example of which is shown in the following Listing.

Listing Sample DMCONFIG File for the Credit Card Authorization Application

*DM_LOCAL
LOCAL1       GWGRP=GWTGROUP
             TYPE=TDOMAIN
             ACCESSPOINTID=”CREDIT.CARD”
             BLOCKTIME=8
             DMTLOGDEV=“/home/rsmith/creditapp/DMTLOG”
             AUDITLOG=“/home/rsmith/creditapp/AUDITLOG”
#
*DM_REMOTE
REMOT1       TYPE=TDOMAIN
             ACCESSPOINTID=”BANK”
#
# If the DM_EXPORT section is absent, as in this sample DMCONFIG
# file, all services advertised by the local domain are available
# to the remote domains. Thus, the following credit card
# authorization services are available to the bankapp application:
#
# WITHDRAWALA
# INQUIRYA
# OPENCA
# CLOSECA
# DEPOSITA
# OPEN_ACCT2
# OPENC
#
*DM_IMPORT
WITHDRAWAL   RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
DEPOSIT      RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
TRANSFER     RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
INQUIRY      RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
CLOSE_ACCT   RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
OPEN_ACCT    RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
BR_ADD       RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
TLR_ADD      RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
ABAL         RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
TBAL         RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
ABALC_BID    RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
TBALC_BID    RACCESSPOINT=REMOT1
             LACCESSPOINT=LOCAL1
#
*DM_TDOMAIN
LOCAL1       NWADDR=“newyork.acme.com:65431”
REMOT1       NWADDR=“albany.acme.com:4051”

Parent topic: Option 2: Reconfigure the Applications as a Domains Configuration

2.2 Examining the creditapp Domains Configuration

The creditapp application is a sample Domains configuration that spans four machines. In effect, the creditapp application is yet another solution to reconfiguring the bankapp application and the credit card authorization application—as described in Planning to Build Domains from Multiple Oracle Tuxedo Applications—so that the two applications can communicate directly with one another. In this solution, the bankapp and credit card authorization applications are reconfigured as four Oracle Tuxedo domains, one domain per machine, that interoperate using TDomain gateway server processes.

The creditapp application is included with the Oracle Tuxedo distribution. Its files reside at the following location:

tux_prod_dir \samples\atmi\creditapp (Windows)
tux_prod_dir /samples/atmi/creditapp (UNIX)

Where tux_prod_dir represents the directory in which the Oracle Tuxedo distribution is installed.

The Domains configuration for the creditapp application requires four UBBCONFIG files, one for each of the Oracle Tuxedo domains, and four DMCONFIG files, one for each of the Oracle Tuxedo domains. The four UBBCONFIG files are named ubbdom1 through ubbdom4, and the four DMCONFIG files are named domcon1 through domcon4. The files reside in the creditapp directory.

The following Listing shows the content of the ubbdom1 configuration file. Notice in the SERVERS section that this domain is configured for three TDomain gateway groups, to be used by this domain to communicate with the three other domains in the Domains configuration.

Listing ubbdom1 Configuration File for the creditapp Application

.
.
.
*RESOURCES
IPCKEY           80952
UID              <user id from id(1)>
GID              <group id from id(1)>
PERM             0660
MAXACCESSERS     40
MAXSERVERS       35
MAXSERVICES      75
MAXCONV          10
MASTER           SITE1
MODEL            SHM
LDBAL            Y
MAXGTT           100
MAXBUFTYPE       16
SCANUNIT         10
SANITYSCAN       5
DBBLWAIT         6
BBLQUERY         50
BLOCKTIME        2
#
#
*MACHINES
<SITE1's uname>  LMID=SITE1
                 TUXDIR="<TUXDIR1>"
                 APPDIR="<APPDIR1>"
                 ENVFILE="<APPDIR1>/ENVFILE"
                 TLOGDEVICE="<APPDIR1>/TLOG"
                 TLOGNAME=TLOG
                 TUXCONFIG="<APPDIR1>/tuxconfig"
                 ULOGPFX="<APPDIR1>/ULOG"
                 TYPE="<machine type1>"
#
#
*GROUPS
DEFAULT:         LMID=SITE1
BANKB1           GRPNO=1     TMSNAME=TMS_SQLTMSCOUNT=2
                 OPENINFO="TUXEDO/SQL:<APPDIR1>/crdtdl1:bankdb:readwrite"
BANKB2           GRPNO=2
BANKB3           GRPNO=3
BANKB4           GRPNO=4
#
#
*SERVERS
#
DEFAULT:         RESTART=Y       MAXGEN=5   REPLYQ=Y  CLOPT="-A"
DMADM            SRVGRP=BANKB2   SRVID=32
GWADM            SRVGRP=BANKB2   SRVID=30
GWTDOMAIN        SRVGRP=BANKB2   SRVID=31
GWADM            SRVGRP=BANKB3   SRVID=24
GWTDOMAIN        SRVGRP=BANKB3   SRVID=25
GWADM            SRVGRP=BANKB4   SRVID=20
GWTDOMAIN        SRVGRP=BANKB4   SRVID=21
TLRA             SRVGRP=BANKB1   SRVID=2
                 CLOPT="-A -- -T 100"
BTADD            SRVGRP=BANKB1   SRVID=3
ACCTA            SRVGRP=BANKB1   SRVID=4
CRDT             SRVGRP=BANKB1   SRVID=5
CRDTA            SRVGRP=BANKB1   SRVID=6
#
*SERVICES
DEFAULT:         LOAD=50
INQUIRYA         PRIO=50
WITHDRAWALA      PRIO=50
OPEN_ACCT2       PRIO=40
OPENC            PRIO=40
OPENCA           PRIO=40
CLOSECA          PRIO=40
BR_ADD           PRIO=20
TLR_ADD          PRIO=20

The following Listing shows the content of the domcon1 Domains configuration file. Notice in the DM_LOCAL section (also known as the DM_LOCAL_DOMAINS section) that this domain is configured for three TDomain gateway groups, to be used by this domain to communicate with the three other domains in the Domains configuration. The domcon1 content shown here has been updated with the improved Domains terminology described in Terminology Improvements for DMCONFIG File.

Listing domcon1 Domains Configuration File for the creditapp Application

.
.
.
*DM_RESOURCES
#
VERSION=U22
#
#
#
*DM_LOCAL
#
QDOM1        GWGRP=BANKB2
             TYPE=TDOMAIN
             ACCESSPOINTID=”QDOM1”
             BLOCKTIME=10
             MAXACCESSPOINT=89
             DMTLOGDEV=“<APPDIR1>/DMTLOG”
             AUDITLOG=“<APPDIR1>/AUDITLOG”
             DMTLOGNAME=”DMTLOG_TDOM1”
QDOM2        GWGRP=BANKB3
             TYPE=TDOMAIN
             ACCESSPOINTID=”QDOM2”
             BLOCKTIME=10
             MAXACCESSPOINT=89
             DMTLOGDEV=“<APPDIR1>/DMTLOG”
             AUDITLOG=“<APPDIR1>/AUDITLOG”
             DMTLOGNAME=”DMTLOG_TDOM2”
QDOM3        GWGRP=BANKB4
             TYPE=TDOMAIN
             ACCESSPOINTID=”QDOM3”
             BLOCKTIME=10
             MAXACCESSPOINT=89
             DMTLOGDEV=“<APPDIR1>/DMTLOG”
             AUDITLOG=“<APPDIR1>/AUDITLOG”
             DMTLOGNAME=”DMTLOG_TDOM3”
#
#
*DM_REMOTE
#
TDOM1        TYPE=TDOMAIN
             ACCESSPOINTID=”TDOM1”
TDOM2        TYPE=TDOMAIN
             ACCESSPOINTID=”TDOM2”
TDOM3        TYPE=TDOMAIN
             ACCESSPOINTID=”TDOM3”
#
#
*DM_TDOMAIN
#
TDOM1         NWADDR=“<network address of SITE2>”
              NWDEVICE=”<device of provider2>
TDOM2         NWADDR=“<network address of SITE3>”
              NWDEVICE=”<device of provider3>
TDOM3         NWADDR=“<network address of SITE4>”
              NWDEVICE=”<device of provider4>
QDOM1         NWADDR=“<network address of SITE1>”
              NWDEVICE=”<device of provider1>
QDOM2         NWADDR=“<network address of SITE1A>”
              NWDEVICE=”<device of provider1>
QDOM3         NWADDR=“<network address of SITE1B>”
              NWDEVICE=”<device of provider1>
#
#
*DM_EXPORT
#
WITHDRAWALA
INQUIRYA
OPENCA
CLOSECA

If you decide to run the creditapp application, start by reading the README file in the creditapp directory. The README file explains how to use a UNIX shell script named RUNME.sh to run the creditapp application. If you want to run the creditapp application on a Windows system, read the README file to learn the basic setup information and then execute the comparable tasks in the Windows environment. For details on using Oracle Tuxedo on Windows, see,Using Oracle Tuxedo ATMI on Windows.

Parent topic: Planning and Configuring ATMI Domains

2.3 Setting Up a Domains Configuration

To configure a Domains environment, you as the Domains administrator must specify all the information that an Oracle Tuxedo domain needs to know about the other domains—the remote domains—involved in the Domains configuration. This information includes local services exported to the remote domains, services imported from the remote domains, and addressing and security parameters for contacting the remote domains. This information is defined in the UBBCONFIG and DMCONFIG configuration files for each domain involved in the Domains configuration.

The Domains example described in the following sections is based on the simpapp application, which is a sample application included with the Oracle Tuxedo distribution at the following location:

tux_prod_dir \samples\atmi\simpapp (Windows)
tux_prod_dir /samples/atmi/simpapp (UNIX)

Where tux_prod_dir represents the directory in which the Oracle Tuxedo distribution is installed.

Parent topic: Planning and Configuring ATMI Domains

2.3.1 Configuring a Sample Domains Application (simpapp)

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

Local and Remote Applications in simpapp Diagram

Parent topic: Setting Up a Domains Configuration

2.3.2 Configuration Tasks

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

Figure 2-5 DMPROC

Parent topic: Setting Up a Domains Configuration

2.3.3 How to Set Environment Variables for lapp

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.

Parent topic: Setting Up a Domains Configuration

2.3.3.1 Windows Example

prompt> set TUXDIR=C:\bea\tuxedo

prompt> set APPDIR=C:\home\lapp

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

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

prompt> set PATH=%APPDIR%;%TUXDIR%\bin;%PATH%

Note:

Windows accesses the required dynamically loadable library files through its PATH variable setting.

Parent topic: How to Set Environment Variables for lapp

2.3.3.2 UNIX Example

prompt> TUXDIR=/home/rsmith/bea/tuxedo

prompt> APPDIR=/home/rsmith/lapp

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

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

prompt> PATH=$APPDIR:$TUXDIR/bin:/bin:$PATH

prompt> LD_LIBRARY_PATH=$APPDIR:$TUXDIR/lib:/lib:/usr/lib: $LD_LIBRARY_PATH

prompt> export TUXDIR APPDIR TUXCONFIG BDMCONFIG PATH LD_LIBRARY_PATH

Parent topic: How to Set Environment Variables for lapp

2.3.4 How to Define the Domains Environment for lapp in the UBBCONFIG File

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
.
.
.

Note:

In the previous UBBCONFIG file listing, REPLYQ=N is specified for the DMADM, GWADM, and GWTDOMAIN servers. This setting is not required: you can, if you prefer, designate a reply queue for any of these servers by specifying REPLYQ=Y. When REPLYQ is set to N, however, performance may be improved.

Parent topic: Setting Up a Domains Configuration

2.3.4.1 Server Group Definitions

The following server groups are defined in lapp.ubb:

LDMGRP—contains the Domains administrative server (DMADM).
LGWGRP—contains the gateway administrative server (GWADM) and the TDomain gateway server (GWTDOMAIN).

Parent topic: How to Define the Domains Environment for lapp in the UBBCONFIG File

2.3.4.2 Server Definitions

DMADM—the Domains administrative server enables run-time modification of the Domains configuration information in the binary Domains configuration file (BDMCONFIG). DMADM supports a list of registered gateway groups. Only one instance of DMADM may be running in an Oracle Tuxedo domain involved in a Domains configuration.
GWADM—the gateway administrative server enables run-time administration of a particular domain gateway group. This server gets Domains configuration information from the DMADM server. It also provides administrative functionality and transaction logging for the gateway group.
GWTDOMAIN—the TDomain gateway server enables access to and from remote Oracle Tuxedo domains, allowing interoperability of two or more Oracle Tuxedo domains. Information about the local and remote services that the TDomain gateway exports and imports is included in the Domains configuration file (DMCONFIG).

Parent topic: How to Define the Domains Environment for lapp in the UBBCONFIG File

2.3.5 How to Define Domains Parameters for lapp in the DMCONFIG File

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"

Parent topic: Setting Up a Domains Configuration

2.3.5.1 DM_LOCAL Section Definitions

The DM_LOCAL section identifies the local domain access points, their associated domain gateway groups, and their characteristics. There is one and only one local domain access point per domain gateway group.

The lapp.dom file specifies only one local domain access point, LAPP, and defines the following properties for the LAPP access point:

GWGRP value is LGWGRP, the name of the domain gateway server group specified in the lapp.ubb file.
TYPE of TDOMAIN indicates that the lapp application will be communicating with the rapp application through the local TDomain gateway server. This parameter indicates the protocol used by the gateways. Other TYPE values include IDOMAIN (Oracle Tuxedo Mainframe Adapter for TCP) and SNAX (Oracle Tuxedo Mainframe Adapter for SNA).
ACCESSPOINTID identifies the name of the local domain access point; this identifier must be unique across all domains involved in the Domains configuration.

Parent topic: How to Define Domains Parameters for lapp in the DMCONFIG File

2.3.5.2 DM_REMOTE Section Definitions

The DM_REMOTE section identifies the remote domain access points and their characteristics. There may be one or more remote domain access points per domain gateway group.

The lapp.dom file specifies only one remote domain access point, RAPP, and defines the following properties for the RAPP access point:

TYPE of TDOMAIN indicates that the lapp application will be communicating with the rapp application through the local TDomain gateway server.
ACCESSPOINTID identifies the name of the remote domain access point; this identifier must be unique across all domains involved in the Domains configuration.

Parent topic: How to Define Domains Parameters for lapp in the DMCONFIG File

2.3.5.3 DM_EXPORT Section Definitions

The DM_EXPORT section provides information about the services that are exported to one or more remote domains through a local domain access point. If this section is absent, or is present but empty, all services advertised by the local domain are available to the remote domains associated with the access points defined in the DM_REMOTE section.

As specified in the lapp.dom file, no lapp services are available to the rapp application through the LAPP access point.

Parent topic: How to Define Domains Parameters for lapp in the DMCONFIG File

2.3.5.4 DM_IMPORT Section Definitions

The DM_IMPORT section provides information about the services that are imported through one or more remote domain access points and made available to the local domain through one or more local domain access points. If this section is absent, or is present but empty, no remote services are available to the local domain.

As specified in the lapp.dom file, the rapp service named TOUPPER is available to the lapp application.

Parent topic: How to Define Domains Parameters for lapp in the DMCONFIG File

2.3.5.5 DM_TDOMAIN Section Definitions

The DM_TDOMAIN section defines the addressing information required by the Oracle Tuxedo Domains component. Each domain access point specified in the LOCAL and REMOTE sections of the configuration file appears as an entry in the in the DM_TDOMAIN section.

Associated with each local domain access point entry is a NWADDR value, which specifies the network address at which the local domain will accept connections from one or more remote domains.

Associated with each remote domain access point entry is a NWADDR value, which specifies the network address at which the local domain will make a connection to a remote domain.

As specified in the lapp.dom file, the lapp application will listen for incoming connection requests on the network address giselle:5000, where giselle is the name of the machine on which the lapp application is running, and 5000 is the listening port. Also specified in lapp.dom is that when the lapp application attempts to make a connection to the rapp application, it will use the network address juliet:5000, where juliet is the name of the machine on which the rapp application is running, and 5000 is the destination port.

Parent topic: How to Define Domains Parameters for lapp in the DMCONFIG File

2.3.6 How to Compile Application and Domains Gateway Configuration Files for lapp

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.

2.3.7 How to Set Environment Variables for rapp

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.

Parent topic: Setting Up a Domains Configuration

2.3.7.1 Windows Example

prompt> set TUXDIR=C:\bea\tuxedo

prompt> set APPDIR=C:\home\rapp

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

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

prompt> set PATH=%APPDIR%;%TUXDIR%\bin;%PATH%

Note:

Windows accesses the required dynamically loadable library files through its PATH variable setting.

Parent topic: How to Set Environment Variables for rapp

2.3.7.2 UNIX Example

prompt> TUXDIR=/home/rsmith/bea/tuxedo

prompt> APPDIR=/home/rsmith/rapp

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

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

prompt> PATH=$APPDIR:$TUXDIR/bin:/bin:$PATH

prompt> LD_LIBRARY_PATH=$APPDIR:$TUXDIR/lib:/lib:/usr/lib: $LD_LIBRARY_PATH

prompt> export TUXDIR APPDIR TUXCONFIG BDMCONFIG PATH LD_LIBRARY_PATH

Parent topic: How to Set Environment Variables for rapp

2.3.8 How to Define the Domains Environment for rapp in the UBBCONFIG File

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
.
.
.

Note:

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.

Parent topic: Setting Up a Domains Configuration

2.3.9 How to Define Domains Parameters for rapp in the DMCONFIG File

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.

Parent topic: Setting Up a Domains Configuration

2.3.10 How to Compile Application and Domain Gateway Configuration Files for rapp

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

2.3.11 How to Compress Data Between Domains

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.

Parent topic: Setting Up a Domains Configuration

2.3.12 How to Route Service Requests to Remote Domains

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.

Parent topic: Setting Up a Domains Configuration

2.4 Setting Up Security in a Domains Configuration

This section contains the following topics:

Parent topic: Planning and Configuring ATMI Domains

2.4.1 Overview

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.

Parent topic: Setting Up Security in a Domains Configuration

2.4.2 Domains Security Mechanisms

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.

Parent topic: Setting Up Security in a Domains Configuration

2.4.3 How to Configure Principal Names for Domains Authentication

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.

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"

Parent topic: Setting Up Security in a Domains Configuration

2.4.4 How to Configure Domains Password Security

Parent topic: Setting Up Security in a Domains Configuration

2.4.4.1 Overview

Domain gateways can be made to authenticate incoming connections requested by remote domains. Application administrators can define when security should be enforced for incoming connections from remote domains.

As the administrator, you can specify the level of security used by a particular local domain by setting the SECURITY parameter in the DM_LOCAL section of the DMCONFIG file. There are three levels of password security:

No security (using the NONEoption)—Incoming connections from remote domains are not authenticated.
Application password (using the APP_PW option)—Incoming connections from remote domains are authenticated using the application password defined in the TUXCONFIG file. (The application password is not included in the UBBCONFIG file.) The Oracle Tuxedo application password is administered with tmloadcf(1), which prompts for the password when the SECURITY option is enabled in the TUXCONFIG file. The password is automatically propagated with the TUXCONFIG file to the other machines in the configuration. You can update the password dynamically using the tmadmin command.
Domains password (using the DM_PW option)—Connections between the local and remote domains are authenticated using passwords defined in the DM_PASSWORDS section of the BDMCONFIG file. (The DM_PASSWORDS section is not included in the DMCONFIG file.) These passwords are added to the binary configuration file after dmloadcf has been run, using DM_MIB(5) or the passwd sub command of the dmadmin(1) command. Each entry contains the password used by a remote domain to access the local domain, and the password required by the local domain to access a remote domain.

If in the TUXCONFIG file the SECURITY parameter is set to NONE or is not set, the Domains configuration can still require the TDomain gateways to enforce security at the DM_PW level. If the DM_PW option is selected, each remote domain must have a password defined in the DM_PASSWORDS section of the BDMCONFIG file. In other words, incoming connections without a password are rejected by the TDomain gateway.

2.4.4.2 Using the DM_MIB(5) to Set Domains Passwords (DM_PW)

You can use the DM_MIB to set Domains passwords (DM_PW). The T_DM_PASSWORDS class in the DM_MIB represents configuration information for interdomain authentication through local and remote access points of type TDOMAIN. The T_DM_PASSWORDS class contains the following entries for each remote domain.

TA_DMLACCESSPOINT—Name of the local domain access point to which the password applies.
TA_DMRACCESSPOINT—Name of the remote domain access point to which the password applies.
TA_DMLPWD—Local password used to authenticate connections between the local domain access point (identified by TA_DMLACCESSPOINT) and the remote domain access point (identified by TA_DMRACCESSPOINT).
TA_DMRPWD—Remote password used to authenticate connections between the remote domain access point (identified by TA_DMRACCESSPOINT) and the local domain access point (identified by TA_DMLACCESSPOINT).

Note:

Passwords are stored securely in encrypted format.

For information about formatting MIB administrative requests and interpreting MIB administrative replies, see reference page DM_MIB(5)in Oracle Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference.

Parent topic: How to Configure Domains Password Security

2.4.4.3 Using the dmadmin Command to Set Domains Passwords (DM_PW)

You can also use the dmadmin command to set Domains Passwords (DM_PW):

prompt> dmadmin passwd [-r] local_domain_access_point_name remote_domain_access_point_name remote_domain_access_point_name

The dmadmin command prompts you for new passwords for the specified local and remote domain access points. For more information about dmadmin(1), see Administering Domains.

Parent topic: How to Configure Domains Password Security

2.4.4.4 Session Negotiation Phase Retry

If the session authentication is set to DM_PW then it uses domain password pair as an encryption key for SNP. Session Negotiation Phase Retry cause the GWTDOMAIN gateway to retry certain Session Negotiation Protocol states using different Domain Password pairs.

There can be at most two pairs of password co-exist within a system for the same TDOMAIN session. At least one key pair must be presented and valid when SNP started if session authentication is set to DM_PW, while the second password pair may not need to be specified, this is to keep it compatible with current operation. When SNP started and session authentication is set to DM_PW it always uses the newer password pair first to encrypt or decrypt a session key and authenticator in the SNP protocol if the newer password pair exists and not yet expired.

Parent topic: How to Configure Domains Password Security

2.4.4.4.1 Password Pair Expiration Handling

If both password pair stored locally expires, it logs a warning message and stops the session negotiation process. If the first password failed to decrypt the authenticator and the second password pair expires, it also logs a warning message. If none of the password pairs can successfully decrypt the authenticator (whether one or two password pairs, an error message is logged..

If the password pair used to successfully decrypt the authentication is within the time specified, it logs an informational message. By default the GWTDOMAIN gateway will not log this informational message; however, if the environmental variable “GWT_SNP_WARN_PW_EXPIRING” is set to a valid decimal value this message is logged. The decimal value is for the number of days before the password pair expires.

For instance, “GWT_SNP_WARN_PW_EXPIRING=7”, the GWTDOMAIN logs an informational message regarding which key pair ( that is, 1 or 2), and its expiration date when the authenticator decryption is done within seven days of the password pair expiration.

The expired password pair will not be deleted by GWTDOMAIN gateway from the BDMCONFIG file. You must explicitly delete it using DM MIB or the “dmadmin -c” command line configuration.

Parent topic: Session Negotiation Phase Retry

2.4.4.4.2 Environmental Variable(s)

GWT_SNP_WARN_PW_EXPIRING

This environmental variable tells GWTDOMAIN whether it needs to, and when to, log the message 1610. The valid value for this environmental variable is from 0 to MAXINT. The unit of counting is days. The default value is 0, which indicates no logging of the approaching expiration for the password pair.

If it is set to a valid value other than 0, the warning message is shown when connection is being negotiated. The local GWTDOMAIN gateway requires DM_PW for session security, and the password pair that was used is within the number of day(s) specified by this environmental variable. For instance “GWT_SNP_WARN_PW_EXPIRING=2” issues message 1610 for all the TDomain sessions for this local GWTDOMAIN gateway when the password is less than 48 hours before expiration. The following message is logged in the USERLOG if this environment variable is set to any valid value other than 0:

1611 “INFO: Log password pair approaching expiration is enabled for ldom-id.

Note:

When a password pair expires, it is the your responsibility to delete or update it from the system. GWTDOMAIN gateway does not delete the password pair automatically.

Parent topic: Session Negotiation Phase Retry

2.4.4.5 Examples of Coding Password Security Between Domains

The SECURITY parameter in the DM_LOCAL section of the DMCONFIG file specifies the security type of a local domain. If authentication is required, it is done every time a connection is established between the local domain and a remote domain. If the security types of the two domains are incompatible, or if the passwords do not match, the connection fails.

Parent topic: How to Configure Domains Password Security

2.4.4.5.1 Example 1: Setting Security to NONE

If SECURITY is set to NONE for a local domain, incoming connection attempts are not authenticated. Even with SECURITY set to NONE, a local domain can still connect to a remote domain that has SECURITY set to DM_PW, but before such a connection can be established, you must define the passwords on both sides by using DM_MIB(5) or the dmadmin passwd command.

The following Listing shows setting security to NONE for both application and domains.

Listing Setting Security to NONE for Both Application and Domains

LOCAL1: SECURITY in UBBCONFIG set to NONE
        SECURITY in DMCONFIG set to NONE
REMOT1: SECURITY in UBBCONFIG set to NONE
        SECURITY in DMCONFIG set to DM_PW

In this example, LOCAL1 is not enforcing any security but REMOT1 is enforcing DM_PW security. On the initiator (LOCAL1) side, the pertinent attributes in UBBCONFIG and DMCONFIG are set as follows:

UBBCONFIG
 *RESOURCES
SECURITY  NONE
DMCONFIG
 *DM_LOCAL
 LOCAL1    GWGRP=bankg1
           TYPE=TDOMAIN
           ACCESSPOINTID="BA.CENTRAL01"
           CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"
           SECURITY=NONE
*DM_REMOTE
 REMOT1    TYPE=TDOMAIN
           ACCESSPOINTID="BA.BANK01"
           CONNECTION_PRINCIPAL_NAME="BA.BANK01"

On the responder (REMOT1) side, the pertinent attributes in UBBCONFIG and DMCONFIG are set as follows:

UBBCONFIG
 *RESOURCES
SECURITY  NONE
DMCONFIG
 *DM_LOCAL
 REMOT1    GWGRP=bankg2
           TYPE=TDOMAIN
           ACCESSPOINTID="BA.BANK01"
           CONNECTION_PRINCIPAL_NAME="BA.BANK01"
           SECURITY=DM_PW
*DM_REMOTE
 LOCAL1    TYPE=TDOMAIN
           ACCESSPOINTID="BA.CENTRAL01"
           CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"

After the required attributes have been set in the TUXCONFIG and BDMCONFIG files, boot the applications on LOCAL1 and REMOT1.

On LOCAL1:

dmadmin
     passwd LOCAL1 REMOT1
      Enter Local Domain Password:foo1
      Reenter Local Domain Password:foo1
     Enter Remote Domain Password:foo2
     Reenter Remote Domain Password:foo2

On REMOT1:

dmadmin
     passwd REMOT1 LOCAL1
     Enter Local Domain Password:foo2
     Reenter Local Domain Password:foo2
     Enter Remote Domain Password:foo1
           Reenter Remote Domain Password:foo1

Once passwords have been created on both domains, a connection can be established and services can be invoked on the remote domain.

The following Listing 2‑14 shows the setting application security to NONE and domains security to DM_PW.

Listing Setting Application Security to NONE and Domains Security to DM_PW

On the initiator (LOCAL1) side, the pertinent attributes in UBBCONFIG and DMCONFIG are set as follows:

UBBCONFIG
 *RESOURCES
SECURITY  NONE
DMCONFIG
 *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"

On the responder (REMOT1) side, the pertinent attributes in UBBCONFIG and DMCONFIG are set as follows:

UBBCONFIG
 *RESOURCES
SECURITY  NONE
DMCONFIG
 *DM_LOCAL
 REMOT1    GWGRP=bankg2
           TYPE=TDOMAIN
           ACCESSPOINTID="BA.BANK01"
           CONNECTION_PRINCIPAL_NAME="BA.BANK01"
           SECURITY=DM_PW
*DM_REMOTE
 LOCAL1    TYPE=TDOMAIN
           ACCESSPOINTID="BA.CENTRAL01"
           CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"

After the required attributes have been set in the TUXCONFIG and BDMCONFIG files, boot the applications on LOCAL1 and REMOT1:

On LOCAL1:

dmadmin
     passwd LOCAL1 REMOT1
     Enter Local Domain Password:foo1
     Reenter Local Domain Password:foo1
     Enter Remote Domain Password:foo2
           Reenter Remote Domain Password:foo2

On REMOT1:

dmadmin
     passwd REMOT1 LOCAL1
     Enter Local Domain Password:foo2
     Reenter Local Domain Password:foo2
     Enter Remote Domain Password:foo1
     Reenter Remote Domain Password:foo1

Once passwords have been created on both domains, a connection can be established and services can be invoked on the remote domain.

Parent topic: Examples of Coding Password Security Between Domains

2.4.4.5.2 Example 2: Setting Security to APP_PW

If the SECURITY parameter in the UBBCONFIG is set to APP_PW or higher, then SECURITY in the DMCONFIG can be set to NONE, APP_PW, or DM_PW. However, you can define multiple views of a domain in one DMCONFIG file (one view per local domain definition), you can assign a different type of security mechanism to each of those views.

Note:

If SECURITY is set to APP_PW for a local domain access point in the DMCONFIG, then SECURITY in the UBBCONFIG must be set to APP_PW or higher.

The following Listing shows the setting security to APP_PW for both application and domains.

Listing Setting Security to APP_PW for Both Application and Domains

LOCAL1: SECURITY in UBBCONFIG set to APP_PW
  SECURITY in DMCONFIG set to APP_PW
REMOT1: SECURITY in UBBCONFIG set to APP_PW
  SECURITY in DMCONFIG set to APP_PW

In this example, both LOCAL1 and REMOT1 enforce APP_PW security.

On the initiator (LOCAL1) side, the pertinent attributes in UBBCONFIG and DMCONFIG are set as follows:

UBBCONFIG
 *RESOURCES
SECURITY  APP_PW
DMCONFIG
 *DM_LOCAL
 LOCAL1    GWGRP=bankg1
           TYPE=TDOMAIN
           ACCESSPOINTID="BA.CENTRAL01"
           CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"
           SECURITY=APP_PW
*DM_REMOTE
 REMOT1    TYPE=TDOMAIN
           ACCESSPOINTID="BA.BANK01"
           CONNECTION_PRINCIPAL_NAME="BA.BANK01"

On the responder (REMOT1) side, the pertinent attributes in UBBCONFIG and DMCONFIG are set as follows.

UBBCONFIG
 *RESOURCES
SECURITY  APP_PW
DMCONFIG
 *DM_LOCAL
 REMOT1    GWGRP=bankg2
           TYPE=TDOMAIN
           ACCESSPOINTID="BA.BANK01"
           CONNECTION_PRINCIPAL_NAME="BA.BANK01"
           SECURITY=APP_PW
*DM_REMOTE
 LOCAL1    TYPE=TDOMAIN
           ACCESSPOINTID="BA.CENTRAL01"
           CONNECTION_PRINCIPAL_NAME="BA.CENTRAL01"

After the TUXCONFIG and BDMCONFIG files have been created, boot the applications on LOCAL1 and REMOT1.

Parent topic: Examples of Coding Password Security Between Domains

2.4.4.6 Using Triple-DES to Encrypt /Domain Password

Parent topic: How to Configure Domains Password Security

2.4.4.6.1 Overview

When using triple-DES as default algorithm for encryption and decryption of domain password the *SERVERS section of the UBBCONFIG file must be changed for DMADM to indicate the new algorithm to be used when encrypting Domain passwords. Without this change, the current DES algorithm is used as the default for encryption/decryption.

The DMADM command line option -3 is specified in the UBBCONFIG file *SERVERS section. This command line option encrypts the domain password received using triple-DES. These new or updated domain password requests can come from either using DM MIB or the dmadmin command interpreter. The encrypted passwords (whether they are encrypted using DES or triple-DES) are stored in the BDMCONFIG file.

Listing DMADM Triple-DES Configuration

…
*SERVERS
DMADM SRVGRP=GROUP4 SRVID=1 CLOPT=”-A -- -3”
…

Note:

If the -3 option is not specified, then DMADM continues to use DES to encrypt the password, and ignores the triple-DES capability bit from GWADM. The DMADM must current.

The GWTDOMAIN gateway is also be enhanced to use Triple-DES or DES to encrypt the authenticator. The GWT_SNP_3DES environmental variable must be set to enable the connection timeout. If not set, GWTDOMAIN is open to SYN flood type of attack.

When GWADM is booted, it registers itself to DMADM and send its own capability bits indicating it can handling triple-DES encrypted passwords. DMADM sends the passwords to GWADM indicating which algorithm it used to encrypted the passwords. GWADM stores the encrypted password in shared memory. When GWTDOMAIN gateway needs the password to authenticate a connection over the TDOMAIN session, it reads the encrypted password from shared memory. Depending on which algorithm the shared memory password entries indicate was encrypted, the GWTDOMAIN gateway uses that algorithm to decrypt the passwords.

Parent topic: Using Triple-DES to Encrypt /Domain Password

2.4.4.6.2 Limitations/Constraints

Triple-DES encryption runs slower than DES, as a result the DMADM and GWTDOMAIN gateway using triple-DES runs slower when domain connection security is required. Performance degradation is not significant for each encryption/decryption operation; however, you should be aware that multiple open session connection requests (coupled with the two password pairs), there may be a noticeable impact. This requires DMADM must be current. GWADM and GWTDOMAIN must be of the same release.

Note:

You must adjust your connection negotiation timeout values; factors that you should consider are the speed of the network, and the topology of the network. The TDOMAIN SNP retry using an older password pair requires both local and remote GWTDOMAIN gateway patched with this feature.

Parent topic: Using Triple-DES to Encrypt /Domain Password

2.4.5 How to Configure Domains Access Control Lists

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.

Table 2-1 How to Configure Domains Access Control Lists

Domain ACL Field	Description
Domains ACL name	The name of this ACL. A valid name consists of a string of 1-30 characters, inclusive. It must be printable and it may not include a colon, a pound sign, or a newline character. Example: `ACLGRP1`
Remote Domains list	The list of remote domains that are granted access in this access control list. A valid value in this field is a set of one or more comma-separated remote domain names. Examples: `REMDOM1,REMDOM2,REMDOM3`

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).

Parent topic: Setting Up Security in a Domains Configuration

2.4.6 How to Configure ACL Policy for a Remote Domain

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"

Parent topic: Setting Up Security in a Domains Configuration

2.4.7 How to Configure Domains Link-Level Encryption

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.

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

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.

Parent topic: Setting Up Security in a Domains Configuration

2.5 Setting Up Connections in a Domains Configuration

You can specify the conditions under which a local domain gateway tries to establish a connection to a remote domain. To specify these conditions, assign a value to the CONNECTION_POLICY parameter in the DM_LOCAL section of the DMCONFIG file. You can select any of the following connection policies:

Connect when a local client program requests a remote service ( ON_DEMAND )
Connect at boot time ( ON_STARTUP)
Accept incoming connections but do not initiate a connection automatically ( INCOMING_ONLY )

For Oracle Tuxedo release 8.1 or later, you can also define the connection policy on a per remote domain basis in the DM_TDOMAIN section of the DMCONFIG file. For details, see How To Configure Your Connection Policy.

For connection policies of ON_STARTUP and INCOMING_ONLY, Dynamic Status is invoked. Dynamic Status, described in How Connection Policy Determines Availability of Remote Services, is a Oracle Tuxedo Domains capability that checks and reports the status of remote services.

Parent topic: Planning and Configuring ATMI Domains

2.5.1 How to Request Connections for Client Demands (ON_DEMAND Policy)

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

Connections Made with an ON_DEMAND Policy Diagram

Parent topic: Setting Up Connections in a Domains Configuration

2.5.2 How to Request Connections at Boot Time (ON_STARTUP 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

Connections Made with an ON_STARTUP Policy Diagram

Parent topic: Setting Up Connections in a Domains Configuration

2.5.3 How to Limit Connections to Incoming Messages Only (INCOMING_ONLY 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)

Connections Made with an INCOMING_ONLY Policy (Accept Incoming Connections) Diagram

Parent topic: Setting Up Connections in a Domains Configuration

2.5.4 How to Configure the Connection Retry Interval for ON_STARTUP Only

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.

Parent topic: Setting Up Connections in a Domains Configuration

2.5.5 How to Configure the Maximum Retry Number

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.

Table 2-2 Example Settings of the MAXRETRY and RETRY_INTERVAL Parameters

If You Set...	Then...
`CONNECTION_POLICY=ON_STARTUP MAXRETRY=3 RETRY_INTERVAL=30`	The local domain gateway makes three attempts to establish a connection, at 30 seconds intervals, before quitting.
`CONNECTION_POLICY=ON_STARTUP MAXRETRY=0`	The local domain gateway attempts to establish a connection at initialization time but does not retry if the first attempt fails.
`CONNECTION_POLICY=ON_STARTUP RETRY_INTERVAL=30`	The domain gateway attempts to establish a connection every 30 seconds until a connection is established.

Parent topic: Setting Up Connections in a Domains Configuration

2.5.6 Example of Coding Connection Policies Between Domains

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"

Parent topic: Setting Up Connections in a Domains Configuration

2.6 Controlling Connections in a Domains Configuration

As the administrator, you can control the number of connections you want to establish between domains. You can also break the connections between local and remote domains.

Parent topic: Planning and Configuring ATMI Domains

2.6.1 How to Establish Connections Between Domains

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.

Parent topic: Controlling Connections in a Domains Configuration

2.6.2 How to Break Connections Between Domains

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.

Parent topic: Controlling Connections in a Domains Configuration

2.6.3 How to Report on Connection Status

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.

Parent topic: Controlling Connections in a Domains Configuration

2.6.4 How to Initiate Domain Connection Events

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

Parent topic: Controlling Connections in a Domains Configuration

2.6.5 Session Negotiation Phase Timeout

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.

Note:

VALIDATE_HOST is required.

Environment Variables

Parent topic: Controlling Connections in a Domains Configuration

2.6.5.1 Environment Variables

GW_VALIDATE_HOST: The following are valid values for GW_VALIDATE_HOST.; Y or YES N or NOAny other values are ignored and the default will be used. The default value is “NO” that means there is no host IP address checking when received an inbound connection request from a remote GWTDOMAIN gateway. If this feature is enabled there will be an IP address checking against the configuration information to determine whether the inbound connection request is originated from a legal remote host.
GWT_SNP_LOG_INVALID_IP: The following are valid values for GWT_SNP_LOG_INVALID_IP.Y or YES N or NOAny other values are errors and will cause the default value to be used. The default value for this environmental variable is “YES”, by default every time an inbound create TDomain session request that came from an invalid host causes USERLOG message 1587 to be logged. To avoid exceedingly large amounts of logging when being attacked, you can turn it off by setting its value to “NO”.

Note:
This is not the best way to do this as it requires shutting down and then rebooting the gateway so the changed Environmental Variable value is in effect.
GWT_SNP_TIMEOUT: The value for this environmental variable is in seconds. The valid value range is from 0 to MAXINT(2147483647). Any other values being specified are errors and cause default value to be used. The default value is 600 seconds (10 minutes). To disable this feature set the value to 0.If a valid value is being specified and it is not 0 (that is, not disabled), the Session Negotiation Timeout is enforced for the whole Session Negotiation Protocol. If the Session Negotiation has not yet been completed by the number of seconds specified, it is treated as either a problem occurred at the remote gateway, or the local gateway is being attacked. When this situation is detected, the local domain gateway marks a security failure for the remote domain and an error message is logged.

Parent topic: Session Negotiation Phase Timeout

2.7 Configuring Domains Link-Level Failover and Keepalive

Domains link-level failover is a mechanism that ensures that an alternate network link becomes active when a primary link fails. Domains keepalive is a mechanism that keeps interdomain connections open through firewalls during periods of inactivity and enables quick detection of connection failures. Domains keepalive is available in Oracle Tuxedo release 8.1 or later.

For a description of Domains link-level failover, see How to Configure Domains Link-Level Failover. For a description of Domains keepalive, see Specifying Domains Keepalive.

Parent topic: Planning and Configuring ATMI Domains