Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
eLink OSI TP Doc Home | eLink OSI TP User Guide | Previous Topic | Next Topic | Contents | Index

Configuring BEA eLink OSI TP

After the installation of BEA eLink OSI TP is complete, you must configure the software. The proper configuration of eLink OSI TP sets up the gateway configuration.

This section covers the following topics:

- Configuration Prerequisites

- Setting Environment Variables

- Defining Gateway Configurations

- Defining eLink OSI TP Servers for BEA Tuxedo

- Setting up Security

- Editing the UDMCONFIG File

- Processing a Configuration File with the Udmloadcf Utility

- Tuning OSI TP-Specific Tables with the TAILOR File

Configuration Prerequisites

The eLink OSI TP product software must be installed and accessible to your text editor. You must have file permission to access the install directory and modify the sample UDMCONFIG file.

In addition, the following prerequisites must be met to successfully complete the configuration procedure:

- The $TUXDIR/udataobj/DMTYPE file defining the valid domain types must exist so the udmloadcf utility can load the binary configuration file and must contain a domain type of OSITP. During the installation process if the DMTYPE file does not contain an OSI TP entry, the DMTYPE file is automatically updated with the required OSITP domain type.

- The effective user identifier of the person running udmloadcf must match the UID in the RESOURCES section of the TUXCONFIG file.

Setting Environment Variables

Before you can invoke system commands, you must set several system environment variables. Most of the environment variables required by BEA eLink OSI TP are set when you set up Tuxedo. Refer to your Tuxedo documentation for more information about setting the Tuxedo environment variables.

In addition to the Tuxedo environment variables, eLink OSI TP requires two additional environment variables, OSIRUNDIR and GW_DFLT_TRANTIME.

You must set OSIRUNDIR, before you can boot the gateway or run the osiadmin utility. If you do not set the OSIRUNDIR environment variable before you boot the gateway, you will receive a message telling you to set OSIRUNDIR. This environment variable specifies the path that the eLink gateway uses for runtime files. You can set the OSIRUNDIR environment variable through a script, a command line entry, or through the Windows System Properties in the Control Panel. The variable value should include the path and directory as appropriate for your operating system. If the directory does not exist, the system will create it for you.

The default transaction time on the server is determined at startup by an optional environment variable call GW_DFLT_TRANTIME. If you do not set this variable, the default value is 5 minutes (300 seconds). This environment variable can be set to a different value at startup, but if the value exceeds the maximum allowed for a LONG, then the value is reset to 300 and a LIBGWO_CAT msg 2204 is sent to the ULOG to indicate that the maximum has been exceeded.

Note: The maximum for a LONG is 2147483647.

Defining Gateway Configurations

Whether you are defining a new gateway configuration or modifying an existing one, both processes are similar. Defining a gateway configuration requires the following steps:

1. Define the eLink OSI TP servers in Tuxedo so that the BEA eLink system can recognize the eLink OSI TP administrative and gateway servers. Refer to Defining eLink OSI TP Servers for BEA Tuxedo for more information.

2. Run the osiadmin processor if you are upgrading from a previous version of eLink OSI TP. Refer to Using the OSI TP Administration Utility for more information.

3. Determine which parameter information needs to be added or changed to define the gateway. Refer to Understanding the UDMCONFIG File for more information.

4. Edit the OSI TP Tailor file if OSI TP-specific tables need to be tuned. Refer to Tuning OSI TP-Specific Tables with the TAILOR File for more information.

5. Create or edit the UDMCONFIG file with new gateway information. Refer to Editing the UDMCONFIG File and Understanding the UDMCONFIG File for more information.

6. Generate a binary version of the UDMCONFIG file by running the udmloadcf utility. Refer to Processing a Configuration File with the Udmloadcf Utility for more information.

After you perform these steps, you are ready to start the gateway using the Tuxedo tmboot command. Refer to the BEA Tuxedo Online Documentation for more information about Tuxedo commands.

Defining eLink OSI TP Servers for BEA Tuxedo

To establish a gateway configuration, the BEA Tuxedo system must recognize the eLink OSI TP administrative and gateway servers, DMADM, UDMADM, GWADM, and GWOSITP. You define the eLink OSI TP administrative and gateway servers to the BEA Tuxedo system by editing the UBBCONFIG file.

Perform the following steps to define eLink OSI TP servers for BEA Tuxedo:

1. In the GROUPS section of the UBBCONFIG file, add a server group using the following format:

>     OSIGRP  GRPNO=1  LMID=SITE1

Note: OSIGRP is used as an example. You may give the group any name you wish.

- In the SERVERS section of the UBBCONFIG file, add the four server names: DMADM, UDMADM,GWADM,and GWOSITP.

Notes: The DMADM, UDMADM, and GWADM entries should be placed in this order BEFORE GWOSITP in the UBBCONFIG file so the admin servers are loaded before the GWOSITP gateway server. UDMADM is optional in a single-host machine environment, but you will receive some warning messages in the ulog file. Refer to Utilities Reference for more detailed information about UDMADM and the other the admin servers.

It is recommended that you set the RESTART parameter in the SERVERS section to Y so that the gateway will automatically restart in case of failure.

Sample UBBCONFIG File

The following file is a sample UBBCONFIG file that defines eLink OSI TP administrative and gateway servers to the BEA Tuxedo system.

Listing 4-1 Sample UBBCONFIG File

>     #-----------------------------------
>     # Connect OSI Test; Client ubbconfig
>     #-----------------------------------

>     *RESOURCES
>     #---------------
>     # Replace IPCKEY
>     #---------------
>     IPCKEY       52029
>     MASTER       SITE1
>     DOMAINID     FRONTEND
>     PERM         0660
>     MAXACCESSERS 40
>     MAXSERVERS   80
>     MAXSERVICES  80
>     MAXCONV      120
>     MODEL        SHM
>     LDBAL        Y
>     MAXGTT       120
>     MAXBUFTYPE   16
>     MAXBUFSTYPE  32
>     SCANUNIT     5
>     SANITYSCAN   10
>     DBBLWAIT     5
>     BBLQUERY     50
>     BLOCKTIME    15

>     *MACHINES
>     #---------------------
>     # Replace machine name
>     #---------------------
>     DALNT45      LMID=SITE1
>     #------------------------------
>     # Replace directories as needed
>     #------------------------------
>       TUXDIR="c:\tuxedo"
>       APPDIR="D:\dwh\base\ositp\test\client"
>       TUXCONFIG="D:\dwh\base\ositp\test\client\tuxconfig"
>       TLOGDEVICE="D:\dwh\base\ositp\test\client\TLOG"
>       TLOGNAME="TLOG"

>     *GROUPS
>     OSIGRP2      GRPNO=2 LMID=SITE1
>     OSIGRP3      GRPNO=3 LMID=SITE1 TMSNAME="TMS" TMSCOUNT=2

>     *SERVERS
>     DEFAULT: RESTART=Y
>     DMADM      SRVID=101 SRVGRP=OSIGRP2 CLOPT="-A"
>     GWADM      SRVID=103 SRVGRP=OSIGRP2 CLOPT="-A"
>     GWOSITP    SRVID=104 SRVGRP=OSIGRP2 CLOPT="-A" GRACE=0
>     CRPCSERV   SRVID=8 SRVGRP=OSIGRP3 CLOPT="-A" RQADDR="rpcq"
>     CCONVSRV   SRVID=9 SRVGRP=OSIGRP3 CLOPT="-A" RQADDR="convq "CONV=Y
>                     MIN=3 MAX=5

>     *SERVICES
>     DEFAULT:      LOAD=50 AUTOTRAN=N
>     CTOUPPER      PRIO=50
>     CCONVRTN      PRIO=50
>     CCONVRTN2     PRIO=50
>     CCONVRTN3     PRIO=50
>     CTOUPPER2      PRIO=50

Refer to the BEA Tuxedo Reference Manual for additional information about the UBBCONFIG file.

Example of a Multiple Gateway Configuration

Following is a sample UBBCONFIG file and corresponding UDMCONFIG file for multiple gateways that reside on the same physical system. Note that use of LDBAL=Y in the UBBCONFIG file is not required for multiple gateways. Loads are automatically balanced for multiple gateways.

Listing 4-2 UBBCONFIG for Multiple Gateways

>     *RESOURCES
>     IPCKEY        65952
>     MASTER        "SITE1"
>     MODEL         SHM
>     PERM          0660
>     LDBAL         N   # not needed for gateway load balancing
>     MAXACCESSERS  40
>     MAXSERVERS    80
>     MAXSERVICES   80
>     MAXGTT        120
>     SCANUNIT      5
>     SANITYSCAN    10
>     BLOCKTIME     15
>     MAXCONV       120

>     *MACHINES
>     "SITE1"       LMID="SITE1"

>                   TUXCONFIG="D:\tuxedo\configs\TUXCONFIG"
>                   TUXDIR="D:\tuxedo"
>                   APPDIR="D:\tuxedo\apps"
>                   TLOGDEVICE="D:\tuxedo\log\TLOG"
>                   ULOGPFX="D:\tuxedo\log\ULOG"
>                   TLOGNAME=TLOG
>                   TLOGSIZE=20
>                   TYPE="SITE1"
>     *GROUPS

>     GROUP1        LMID="SITE1"
>                   GRPNO=1
>     GROUP2        LMID="SITE1"
>                   GRPNO=2

>     DMGRP         LMID="SITE1"
>                   GRPNO=3

>     *SERVERS

>     DEFAULT:      RQPERM=0666
>                   RPPERM=0666
>                   MIN=1
>                   MAX=1
>                   CONV=N
>                   MAXGEN=1
>                   GRACE=86400
>                   RESTART=Y
>                   SYSTEM_ACCESS=FASTPATH

>     DMADM         SRVGRP=DMGRP
>                   SRVID=20
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2

>     GWADM         SRVGRP=GROUP1
>                   SRVID=21
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2

>     GWOSITP       SRVGRP=GROUP1
>                   SRVID=22
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2

>     GWADM         SRVGRP=GROUP2
>                   SRVID=23
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2

>     GWOSITP       SRVGRP=GROUP2
>                   SRVID=24
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2

>     *SERVICES

>     DEFAULT:  LOAD=50 AUTOTRAN=N

Listing 4-3 UDMCONFIG File for Multiple Gateways

>     *DM_RESOURCES
>     VERSION="SITE1"
>     #
>     *DM_LOCAL_DOMAINS

>     "GW-1"
>     GWGRP       = GROUP1
>     TYPE        = OSITPX
>     DOMAINID    = "GW-1"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG"

>     "GW-2"
>     GWGRP       = GROUP2
>     TYPE        = OSITPX
>     DOMAINID    = "GW-2"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG2"

>     ###############################################################
>     *DM_REMOTE_DOMAINS

>     DEFAULT:

>     "OPENTI" TYPE="OSITPX" DOMAINID="OPENTI"

>     ###############################################################
>     *DM_OSITPX

>     "GW-1"
>           AET="{1.3.145.62.103},{2}"
>           TAILOR_PATH="d:\tuxedo\configs\tailor.txt"
>                                  # Inserted from OSITP's config file:
>           NWADDR="//SITE1:102"

>     "GW-2"
>           AET="{1.3.145.62.103},{3}"
>           TAILOR_PATH="d:\tuxedo\configs\tailor2.txt"
>                                  # Inserted from OSITP's config file:
>           NWADDR="//SITE1:2000" #second gateway must use another
>                                          #IP or different port number

>     "OPENTI"
>           AET="{1.3.122.61.203},{20}"
>           NWADDR="122.61.203.20"

>     *DM_LOCAL_SERVICES

>     *DM_REMOTE_SERVICES
>     DEFAULT: TRANTIME=300
>         # TUXEDO will alternate outgoing calls between the two LDOMs.

>     callSvc2   RDOM="OPENTI" LDOM="GW-1" PRIO=66
>     callSvc2   RDOM="OPENTI" LDOM="GW-2" PRIO=66

Using the Tuxedo MP Model with the eLink OSI TP Gateway

It is useful to use the Tuxedo MP model (for multiprocessors that do not have global shared memory or for networked applications) when you require two eLink OSI TP systems to exist in the same domain. (Refer to the BEA Tuxedo documentation for more information about the MODEL parameter.) A practical example of this is setting up a Windows NT cluster. The eLink OSI TP gateway supports active-active failover on an NT cluster. In the MP model case, there are two unique nodes, one defined as the master and a second one defined as a slave or backup system in the case of clustering. There is one UBBCONFIG and one UDMCONFIG that physically exist on the master node. At TMBOOT time, a copy of the TUXCONFIG is propagated to the slave or backup system. When the backup system is booted and the eLink gateway requires configuration information, the UDMADM service retrieves the configuration information from the master system.

Listing 4-4 UBBCONFIG File for MP Model

>     UBBCONFIG

>     *RESOURCES
>     IPCKEY        65952
>     MASTER        SITE1,SITE2
>     MODEL         MP
>     OPTIONS       LAN
>     PERM          0660
>     LDBAL         N   # not needed for gateway load balancing
>     MAXACCESSERS  40
>     MAXSERVERS    80
>     MAXSERVICES   80
>     MAXGTT        120
>     SCANUNIT      5
>     SANITYSCAN    10
>     BLOCKTIME     15
>     MAXCONV       120

>     *MACHINES
>     "SITE1"       LMID="SITE1"
>                   TUXCONFIG="D:\tuxedo\configs\TUXCONFIG"
>                   TUXDIR="D:\tuxedo"
>                   APPDIR="D:\tuxedo\apps"
>                   TLOGDEVICE="D:\tuxedo\log\TLOG"
>                   ULOGPFX="D:\tuxedo\log\ULOG"
>                   TLOGNAME=TLOG
>                   TLOGSIZE=20
>                   TYPE="INTEL"

>     "SITE2"       LMID="SITE2"
>                   TUXCONFIG="D:\tuxedo\configs\TUXCONFIG"
>                   TUXDIR="D:\tuxedo"
>                   APPDIR="D:\tuxedo\apps"
>                   TLOGDEVICE="D:\tuxedo\log\TLOG"
>                   ULOGPFX="D:\tuxedo\log\ULOG"
>                   TLOGNAME=TLOG
>                   TLOGSIZE=20
>                   TYPE="INTEL"

>     *GROUPS
>     GROUP1        LMID="SITE1"
>                   GRPNO=1
>     GROUP2        LMID="SITE2"
>                   GRPNO=2
>     DMGRP         LMID="SITE1"
>                   GRPNO=3

>     *NETWORK
>     SITE1         NADDR="/SITE1:5020"
>                   NLSADDR="//SITE1:5021"
>     SITE2         NADDR="//SITE2:5020"
>                   NLSADDR="//SITE2:5021"

>     *SERVERS
>     DEFAULT:      RQPERM=0666
>                   REPLYQ=Y
>                   RPPERM=0666
>                   MIN=1
>                   MAX=1
>                   CONV=N
>                   MAXGEN=1
>                   GRACE=86400
>                   RESTART=N
>                   SYSTEM_ACCESS=FASTPATH

>     DMADM         SRVGRP=DMGRP
>                   SRVID=20
>                   CLOPT="-A"
>                   RESTART=Y
>     	       MAXGEN=2

>     UDMADM        SRVGRP=DMGRP
>                   SRVID=21
>                   CLOPT="-A"
>                   RESTART=Y
>         	       MAXGEN=2

>     GWADM         SRVGRP=GROUP1
>                   SRVID=22
>                   CLOPT="-A"
>                   RESTART=Y
>         	       MAXGEN=2

>     GWOSITP       SRVGRP=GROUP1
>                   SRVID=23
>                   CLOPT="-A"
>                   RESTART=Y
>     	       MAXGEN=2

>     GWADM         SRVGRP=GROUP2
>                   SRVID=24
>                   CLOPT="-A"
>                   RESTART=Y
>     	       MAXGEN=2

>     GWOSITP       SRVGRP=GROUP2
>                   SRVID=25
>                   CLOPT="-A"
>                   RESTART=Y
>                   MAXGEN=2

>     *SERVICES
>     DEFAULT:  LOAD=50 AUTOTRAN=N

Listing 4-5 UDMCONFIG File for MP Model

>     UDMCONFIG

>     *DM_RESOURCES
>     VERSION="SITE1"
>     #
>     *DM_LOCAL_DOMAINS

>     "GW-1"
>     GWGRP       = GROUP1
>     TYPE        = OSITPX
>     DOMAINID    = "GW-1"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG1"

>     "GW-2"
>     GWGRP       = GROUP2
>     TYPE        = OSITPX
>     DOMAINID    = "GW-2"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG2"

>     ###############################################################
>     *DM_REMOTE_DOMAINS

>     DEFAULT:

>     "OPENTI" TYPE="OSITPX" DOMAINID="OPENTI"

>     ###############################################################
>     *DM_OSITPX

>     "GW-1"
>                    AET="{1.3.145.62.103},{2}"
>                    TAILOR_PATH="d:\tuxedo\configs\tailor1.txt"
>                    # Inserted from OSITPX's config file:
>                    NWADDR="//SITE1:102"

>     "GW-2"
>                    AET="{1.3.145.62.103},{3}"
>                    TAILOR_PATH="d:\tuxedo\configs\tailor2.txt"
>                    # Inserted from OSITPX's config file:
>                    NWADDR="//SITE2:102" # second gateway must use
>                                         # another IP or different
>                                         # port number

>     "OPENTI"
>                    AET="{1.3.122.61.203},{20}"
>                    NWADDR="122.61.203.20"

>     ########################################################################*DM_LOCAL_SERVICES

>     ###############################################################
>     *DM_REMOTE_SERVICES
>     DEFAULT: TRANTIME=300
>     # Each system will service different applications.

>     callSvc2   RDOM="OPENTI" LDOM="GW-1" PRIO=66
>     callSvc3   RDOM="OPENTI" LDOM="GW-2" PRIO=66

Using eLink OSI TP as a Pass-Through to Other TUXEDO Systems

For this example, the eLink OSI TP gateway acts as a pass-through to allow access to services on other Tuxedo systems. The eLink OSI TP gateway recieves service requests from a remote OLTP system and then forwards them through the /TDOMAINS gateway to a remote Tuxedo system. The systems are as follows:

Figure 4-1 Example of eLink OSI TP Acting as a Pass-Through to Other Tuxedo Systems

Listing 4-6 shows a sample UBBCONFIG file and Listing 4-7 shows the corresponding UDMCONFIG file for a pass-through configuration.

Listing 4-6 Sample UBBCONFIG File for Pass-Through Configuration

>     *RESOURCES
>     IPCKEY        65952
>     MASTER        "SITE1"
>     MODEL         SHM
>     PERM          0777

>     *MACHINES
>     "SITE1" LMID="SITE1"

>                   TUXCONFIG="D:\tuxedo\appdir\TUXCONFIG"
>                   TUXDIR="D:\tuxedo"
>                   APPDIR="D:\tuxedo\appdir"
>                   TLOGDEVICE="D:\tuxedo\log\TLOG"
>                   ULOGPFX="D:\tuxedo\log\ULOG"
>                   TLOGNAME=TLOG
>                   TLOGSIZE=20
>                   TYPE="SITE1"
>     *GROUPS

>     ADMGRP        LMID="SITE1"
>                   GRPNO=1

>     OSIGRP        LMID="SITE1"
>                   GRPNO=2

>     TDOMGRP       LMID="SITE1"
>                   GRPNO=3
>                   OPENINFO=NONE

>     *SERVERS

>     DEFAULT:      RQPERM=0666
>                   RPPERM=0666
>                   MIN=1
>                   MAX=1
>                   CONV=N
>                   MAXGEN=1
>                   GRACE=86400
>                   RESTART=N
>                   SYSTEM_ACCESS=FASTPATH

>     DMADM         SRVGRP=ADMGRP
>                   SRVID=20
>                   CLOPT="-A"
>                   RESTART=N

>     GWADM         SRVGRP=OSIGRP
>                   SRVID=21
>                   CLOPT="-A"
>                   RESTART=N

>     GWOSITP       SRVGRP=OSIGRP
>                   SRVID=22
>                   CLOPT="-A"
>                   RESTART=Y

>     GWADM         SRVGRP=TDOMGRP
>                   SRVID=51
>                   CONV=N
>                   CLOPT="-A"
>                   REPLYQ=N
>                   RESTART=N

>     GWTDOMAIN     SRVGRP=TDOMGRP
>                   SRVID=52
>                   CLOPT="-A"
>                   REPLYQ=N
>                   RESTART=Y
>     *SERVICES

>     DEFAULT:  LOAD=50 AUTOTRAN=N

Listing 4-7 Sample UDMCONFIG File for Pass-Through Configuration

>     *DM_RESOURCES
>     VERSION="SITE1"
>     #
>     *DM_LOCAL_DOMAINS

>      #  SECURITY=NONE

>     "osi-local"
>                  GWGRP       = OSIGRP
>                  TYPE        = OSITPX
>                  DOMAINID    = "local"
>                  BLOCKTIME   = 2000
>                  AUDITLOG    = "D:\tuxedo\log\AUDIT"
>                  DMTLOGDEV   = "D:\tuxedo\log\DMLOG"
>                  DMTLOGSIZE  = 2048
>                  DMTLOGNAME  = "DMLOG"

>     "td-local"   GWGRP=TDOMGRP
>                  TYPE=TDOMAIN
>                  DOMAINID="td-local"
>                  DMTLOGDEV="D:\tuxedo\log\TDMLOG"

>     ###############################################################
>     *DM_REMOTE_DOMAINS

>     DEFAULT:

>     "osi-client" TYPE=OSITPX   DOMAINID="osi-client"
>     "td-backend" TYPE=TDOMAIN DOMAINID="td-tpaix1"

>     ###############################################################
>     *DM_TDOMAIN

>     "td-local"        NWADDR="192.63.22.2:5000"
>     "td-backend"      NWADDR="192.63.24.74:5000"
>     ###############################################################
>     *DM_OSITPX

>     "osi-local"
>                   AET="{1.3.192.63.22},{2}"
>                   TAILOR_PATH="d:\tuxedo\configs\tailor.txt"

>     # the NWADDR for OSI TP may have the same IP as /TDOMAINS, but
>     # requires a different port number
>                   NWADDR="192.63.22.2:102"

>     "osi-client"
>                    AET="{1.3.192.23.2},{3}"
>       	       NWADDR="192.23.2.3"
>                    T_SEL="OSITP"

>     ###############################################################
>     *DM_LOCAL_SERVICES
>     # define the incoming services here, eventhough they reside on
>     # some remote /TDOMAIN machine.  Include views also on this machine
>     # for eLink OSI TP to process incoming messages

>     callSvc1

>     ###############################################################
>     *DM_REMOTE_SERVICES
>     DEFAULT:

>     # define the actual remote service request here.  It will be
>     # routed by /TDOMAINS

>     callSvc1   RDOM="td-backend"   LDOM="td-local" RNAME="callSvc1"

Note that the service that resides on the backend /TDOMAIN system must be defined as a local service on the eLink OSI TP system, so eLink OSI TP can process the incoming request. It must also be defined as a remote service so that the /TDOMAIN gateway can pass the service request to the backend /TDOMAIN system. The gateway system must have available the viewfiles and corresponding environment variables that are required by the service, even though the service exists on the backend system.

Setting up Security

In order for any security checking to occur, each domain must have a security mechanism in place. For the TUXEDO domain, the Authorization Server is the security mechanism. Refer to the BEA Tuxedo Online Documentation CD at http://download.oracle.com/docs/cd/E13203_01/tuxedo/tux65/index.htm for more information about security for TUXEDO domains.

Note: A domain without an operational security mechanism in place accepts all transaction requests by treating user IDs as "trusted users."

The eLink OSI TP gateway has a new feature to support link layer security. Each domain communicating over OSI TP must have the OSI TP security extensions implemented.

The BEA Tuxedo UBBCONFIG and eLink OSI TP UDMCONFIG files include five sections in which you specify security parameters:

- RESOURCES section of the UBBCONFIG file

- DM_LOCAL_DOMAINS section of the UDMCONFIG file

- DM_OSITPX section of the UDMCONFIG file

- DM_ACCESS_CONTROL section of the UDMCONFIG file

- DM_LOCAL_SERVICES section of the UDMCONFIG file

The following figure shows the relationships between security elements for eLink OSI TP.

Figure 4-2 eLink OSI TP Security Elements

Four sections in the UDMCONFIG file contain parameters affecting how eLink OSI TP controls access to the local TUXEDO domain:

- DM_LOCAL_DOMAINS section contains a SECURITY parameter that specifies the type of security enforced for the TUXEDO local domain.

The SECURITY parameter settings in this section work in conjunction with the SECURITY parameter in the RESOURCES section of the Tuxedo domain's UBBCONFIG file to establish how eLink OSI TP controls access to the Tuxedo local domain. If this parameter is set to NONE or APP_PW, the eLink OSI TP domain takes no action with regard to security. If this parameter is set to DM_PW, the eLink OSI TP domain enforces security according to the security settings in the DM_PASSWORDS section of the BDMCONFIG file.

Caution: Do not delete the Tuxedo BDMCONFIG file. The DM_PW information will be lost if the file is deleted. When new passwords are entered, the GWOSITP service must be shut down and restarted for the passwords to take effect.

- DM_OSITPX section contains an OPTION of SECURITY_SUPPORTED, which indicates that the remote domain supports the OSI TP security extension. The OSI TP security extension allows OSI TP systems to perform link-layer security. The link layer security feature is activated when the DM_LOCAL_DOMAINS section has SECURITY=DM_PW set and OPTIONS=SECURITY_SUPPORTED is set for the remote domain.

- DM_ACCESS_CONTROL section contains local access control lists used by the Tuxedo domain to associate local resources with remote OSI environments permitted to have access to them.

- DM_LOCAL_SERVICES section contains an ACL parameter that works in conjunction with the ACL_NAME defined in the DM_ACCESS_CONTROL section to restrict requests made to the local services by remote domains.

For more information about these parameters, refer to Understanding the UDMCONFIG File

Editing the UDMCONFIG File

If you are upgrading from a previous version of eLink OSI TP, it is recommended that you use the osiadmin utility to update your UDMCONFIG file; however, you may edit the UDMCONFIG file manually. Refer to Using the OSI TP Administration Utility

for more information about the osiadmin utility.

To edit the UDMCONFIG file manually, perform the following steps:

1. Find the UDMCONFIG file in your installation directory and open it in any text editor.

2. Edit the UDMCONFIG file as necessary. Refer to the parameter descriptions in this section for details about defining your eLink OSI TP configuration.

3. When editing is complete, save the UDMCONFIG file.

Note: You may want to save the original UDMCONFIG file with a different name or in a different directory.

4. Process the UDMCONFIG file with the udmloadcf utility. This parses the input and creates two binary files: the BDMCONFIG file, which is used by GWOSITP, and the BUDMCONFIG file, which is used by UDMADM.

Refer to Understanding the UDMCONFIG File for more detailed information about the parameters in the UDMCONFIG file.

Steps for Modifying the UDMCONFIG File Parameters

Perform the following steps to modify the UDMCONFIG file parameters:

- Step 1 - Define Local Domains

- Step 2 - Define Remote Domains

- Step 3 - Specify Addressing Information for OSI TP Domains

- Step 4 - Specify Access Control for OSI TP Domains

- Step 5 - Specify Available Local Tuxedo Services

- Step 6 - Specify Available Remote Tuxedo Services

- Step 7 - Specify Routing Information

Step 1 - Define Local Domains

You must define the local domains that use the OSI TP server group you defined in your Tuxedo UBBCONFIG file. Refer to Defining eLink OSI TP Servers for BEA Tuxedo for more information about the UBBCONFIG file.

Perform the following steps to define a local domain in the DM_LOCAL_DOMAINS section of the UDMCONFIG file:

1. Specify the local domain ID with the DOMAINID parameter.

2. Specify the gateway group you defined in the UBBCONFIG file with the GWGRP parameter.

3. Specify the domain type of OSITPX with the TYPE parameter.

4. Specify the size of the domain transaction log with the DMTLOGSIZE parameter.

5. Specify any of the optional DM_LOCAL_DOMAINS parameters that you require: AUDITLOG, BLOCKTIME, DMTLOGDEV, DMTLOGNAME, MAXRDTRAN, MAXTRAN, and SECURITY.

Listing 4-8 Example of DM_LOCAL_DOMAINS Section

>     *DM_LOCAL_DOMAINS

>     dalnt8
>     GWGRP       = OSIGRP
>     TYPE        = OSITPX
>     DOMAINID    = "dalnt8"
>     BLOCKTIME   = 30
>     DMTLOGDEV   = "D:\tuxedo\log\DMLOG"
>     SECURITY    = DM_PW  # turns link layer security on

Refer to Sample Configuration File for more detailed information.

Step 2 - Define Remote Domains

It is recommended that you use the importcfg command in the osiadmin utility to update remote domains if you are upgrading from a previous version of BEA eLink OSI TP; however, you can manually define remote domains. Refer to Using the OSI TP Administration Utility

for more information about the osiadmin utility.

Perform the following steps to define remote domains in the DM_REMOTE_DOMAINS section of the UDMCONFIG file:

1. Specify the remote domain ID with the DOMAINID parameter.

2. Specify the OSITPX domain type with the TYPE parameter.

There are no optional parameters for the DM_REMOTE_DOMAINS section.

Listing 4-9 Example of DM_REMOTE_DOMAINS Section

>     *DM_REMOTE_DOMAINS

>     dal2200 TYPE=OSITPX DOMAINID="dal2200"
>     openti  TYPE=OSITPX DOMAINID="openti"
>     icl2    TYPE=OSITPX DOMAINID="icl2"
>     aseries1 TYPE=OSITPX DOMAINID="aseries1"

Refer to DM_REMOTE_DOMAINS Section for more detailed information.

Step 3 - Specify Addressing Information for OSI TP Domains

Perform the following steps to define addressing information for OSI TP domains in the DM_OSITPX section of the UDMCONFIG file:

1. Specify the Application Entity Title for each local and remote OSI TP domain with the AET parameter.

2. Specify the IP address or DNS name and port number for each local and remote OSI TP domain with the NWADDR parameter. If you are using multiple IP addresses, make sure to enter all the addresses on one line, with quotes around each address, and separate them with a semi-colon (;).

3. Specify the logical name for the software that provides transport layer services for all LDOMS and RDOMS with the T_SEL parameter.

4. Specify any of the optional DM_OSITPX parameters that you require: DNS_RESOLUTION, P_SEL, S_SEL, OPTIONS, TAILOR_PATH, and XATMI_ENCODING.

Listing 4-10 DM_OSITPX Section

>     *DM_OSITPX

>     dalnt8
>                    AET="{1.3.144.23.103},{208}"
>                    TAILOR_PATH="d:\tuxedo\configs\tailor.txt"
>                    NWADDR="//dalnt8:102"
>                    DNS_RESOLUTION=STARTUP # this is the default

>     dal2200
>                    AET="{1.3.132.61.146},{3}"
>                    XATMI_ENCODING="OLTP_TM2200"
>                    NWADDR="132.61.146.3; 132.61.147.1"
>                    T_SEL="OSITP"

>     openti
>                    AET="{1.3.122.62.103},{209}"
>                    NWADDR="122.62.103.209"

>     icl2
>                   AET="{1.3.142.60.203},{4}"
>                   NWADDR="142.60.203.4"
>                   T_SEL="ICLTP"
>                   S_SEL="SSEL"
>                   P_SEL="PSEL"
>                   SECURITY_SUPPORTED=N  # this is the default

>     aseries1
>                   AET="{1.3.123.55.222},{51}"
>                   NWADDR="123.55.222.51"
>                   XATMI_ENCODING="PRELIMINARY"
>                   T_SEL=0x5453
>                   S_SEL=0x3F5C3F
>                   OPTIONS=SECURITY_SUPPORTED

Refer to DM_OSITPX Section for more detailed information.

Step 4 - Specify Access Control for OSI TP Domains

In the DM_ACCESS_CONTROL section of the UDMCONFIG file, specify a list of all the remote OSI TP domain IDs that can access the local domain with the ACLIST parameter. This parameter is optional.

Listing 4-11 Example of DM_ACCESS_CONTROL Section

>     *DM_ACCESS_CONTROL
>     mylist  ACLIST = dalnt8, dal2200

Refer to DM_ACCESS_CONTROL Section for more detailed information.

Step 5 - Specify Available Local Tuxedo Services

In the DM_LOCAL_SERVICES section of the UDMCONFIG file, specify the Tuxedo services that will be made available to OSI TP applications and define their options with the ACL, COUPLING, INBUFTYPE, INRECTYPE, LDOM, OUTRECTYPE, OUTBUFTYPE, and RNAME parameters. If the local service supports transactions, make sure the group it belongs to contains a TMS name.

These DM_LOCAL_SERVICES parameters are all optional.

Listing 4-12 Example of DM_LOCAL_SERVICES Section

>     *DM_LOCAL_SERVICES
>     TOUPPERF
>       INRECTYPE="VIEW:view10"
>       OUTBUFTYPE="FML:"
>       COUPLING=LOOSE

>     TOUPPERF32
>       INRECTYPE="VIEW:view10a"
>       OUTBUFTYPE="FML32:"
>       COUPLING=TIGHT

>     TOUPPERV
>       INBUFTYPE="X_C_TYPE:v10"
>       INRECTYPE="VIEW:upper"
>       COUPLING=LOOSE

>     TOUPPERC OUTRECTYPE="X_OCTET" OUTBUFTYPE="CARRAY"
>             INRECTYPE="X_OCTET"
>             COUPLING=TIGHT

>     TOUPPERS  OUTRECTYPE="X_OCTET" OUTBUFTYPE="STRING"
>             INRECTYPE="X_OCTET"

>     TOUPPERX  OUTRECTYPE="STRING" OUTBUFTYPE="STRING"
>              INRECTYPE="X_OCTET"

Refer to DM_LOCAL_SERVICES Section for more detailed information.

Step 6 - Specify Available Remote Tuxedo Services

In the DM_REMOTE_SERVICES section of the UDMCONFIG file, specify the remote services that can be requested by Tuxedo applications and define their options with the AUTOPREPARE, CONV, INBUFTYPE, INRECTYPE, LDOM, OUTRECTYPE, OUTBUFTYPE, RDOM, RNAME, ROUTING, and TRANTIME parameters. These parameters are all optional.

Listing 4-13 Example of DM_REMOTE_SERVICES Section

>     *DM_REMOTE_SERVICES
>     DEFAULT: TRANTIME=300

>     ECHOXOCT RNAME="ECHOSRVR" OUTBUFTYPE="X_COMMON:ECHOVIEW" RDOM=dal2200 LDOM=dalnt8
>     ECHOXCOM RNAME="ECHOSRVR" RDOM=openti LDOM=dalnt8 AUTOPREPARE=Y

>     ECHOXCTYPE RNAME="ECHOSRVR"
>              INBUFTYPE="X_C_TYPE:ECHOVIEW"
>              INRECTYPE="X_COMMON:ECHOVIEW"
>              OUTBUFTYPE="X_C_TYPE:ECHOVIEW"
>              OUTRECTYPE="X_COMMON:ECHOVIEW"
>              RDOM=aseries1
>              LDOM=dalnt8
>              CONV=Y
>     ECHOVIEW RNAME="ECHOSRVR"
>              INBUFTYPE="VIEW:ECHOVIEW"
>              INRECTYPE="X_COMMON:ECHOVIEW"
>              OUTBUFTYPE="VIEW:ECHOVIEW"
>              OUTRECTYPE="X_COMMON:ECHOVIEW"
>              RDOM=icl2
>              LDOM=dalnt8
>              REM_TPSUT="tpmvs"

Refer to DM_REMOTE_SERVICES Section for more detailed information.

Step 7 - Specify Routing Information

Perform the following steps to define routing information for service requests in the DM_ROUTING section of the UDMCONFIG file:

1. Specify the name of the routing field with the FIELD parameter.

2. Specify the data buffer type and subtype for which the routing entry is valid with the BUFTYPE parameter.

3. Specify the ranges and associated remote domain names for the routing field with the RANGES parameter.

Listing 4-14 Example of DM_ROUTING Section

>     *DM_ROUTING
>     ACCOUNT FIELD = branchid BUFTYPE = "View:account"
>             RANGE = "MIN - 1000:aseries1, 1001-3000:openti, *:dal2200"

Refer to DM_ROUTING Section for more detailed information.

Processing a Configuration File with the Udmloadcf Utility

The udmloadcf utility compiles the UDMCONFIG file and creates two binary configuration files, BDMCONFIG, which is used by the DMADM server to control the run-time environment, and BUDMCONFIG, which is used by the GWOSITP server at run time.

Figure 4-3 shows how the udmloadcf utility processes the configuration file. A description of the process follows the figure.

Figure 4-3 Udmloadcf Process

When you start udmloadcf from the command line (A), it analyzes the input parameters and saves off any of the parameters ([-c] [-n] [-y] [-b blocks]) that are entered on the command line. If no command line syntax errors are detected, udmloadcf opens the input configuration file. It reads and processes the configuration file line by line. udmloadcf removes new (OSITP 4.0) parameters, saves them internally, and writes the modified information to a temporary output file (B) that will be used as input to BEA's dmloadcf. udmloadcf then takes the internally saved new parameters and creates a new binary file (C) that will be used as input to the access functions used by the gateway at runtime. This file is named by using the directory portion of the environment variable, BDMCONFIG, and adding the filename, BUDMCONFIG. Next, udmloadcf invokes dmloadcf with all of the parameters saved during command line checking to process the temporary DMCONFIG file (which it previously created) and create the BDMCONFIG file (D). Finally, udmloadcf deletes the temporary DMCONFIG file (B), unless the -k option has been specified, in which case it copies the temporary file to a file named dmconfig.sav in the current directory.

Invoking the Udmloadcf Utility

The udmloadcf utility is invoked from a command line with the following syntax:

>     udmloadcf [-c] [-n] [-y] [-b blocks] [-k] udmconfig_file

where the following options are valid:

  -c

  Prints minimum IPC resources needed for each local domain (gateway group) in this configuration. The BDMCONFIG file is not updated.

  -n

  Checks only the syntax of the ASCII DMCONFIG file without actually updating the BDMCONFIG file.

  -y

  Suppresses a prompt to create and initialize the BDMCONFIG file. This parameter must be entered before the DMCONFIG file name.

  -b blocks

  Indicates the number of blocks the device should use to create the Tuxedo file system. If the value of the -b option is large enough to hold the new BDMCONFIG tables, dmloadcf uses the specified value to create the new file system; otherwise, dmloadcf prints an error message and exits. If the -b option is not specified, dmloadcf creates a new file system large enough to hold the BDMCONFIG tables. The -b option is ignored if the file system already exists. The -b option is highly recommended if BDMCONFIG is a raw device (that has not been initialized) and should be set to the number of blocks on the raw device.

  -k

  Keeps the temporary file used as input to dmloadcf. This parameter must be entered before the UDMCONFIG file name. The temporary file is saved as dmconfig.sav.

  udmconfig_file

  Specifies the name of the input configuration file to udmloadcf.

Getting Help for the Udmloadcf Utility

You can also get help or usage information about the udmloadcf utility by entering any one of the following commands:

>     udmloadcf /?
>     udmloadcf /help
>     udmloadcf -?
>     udmloadcf -help

How the Udmloadcf Utility Works

The udmloadcf utility prints an error message if any required section of the DMCONFIG file is missing. If a syntax error is found while parsing the input file, udmloadcf exits without performing any updates to the BDMCONFIG file.

A Tuxedo DMTYPE file is required to define the valid domain types. If this file does not exist, udmloadcf exits without performing any updates to the BDMCONFIG file.

The effective user ID of the person running udmloadcf must match the UID in the RESOURCES section of the TUXCONFIG file.

After syntax checking, udmloadcf verifies that the file pointed to by BDMCONFIG exists, is a valid Tuxedo System file system, and contains BDMCONFIG tables. If these conditions are not true and the -y option was not entered on the command line, the user is prompted to create and initialize the file with

>     Initialize BDMCONFIG file: path {y, q}?

where path is the complete file name of the BDMCONFIG file and "Y" indicates that the configuration file should be created.

If the BDMCONFIG file is determined to already have been initialized, udmloadcf ensures that the local domain described by that BDMCONFIG file is not running. If a local domain is running, udmloadcf prints an error message and exits. Otherwise, udmloadcf confirms that the file should be overwritten by prompting the user with:

>     "Really overwrite BDMCONFIG file {y, q}?"

Prompting is suppressed if the standard input or output are not terminals. Any response other than "y" or "Y" causes udmloadcf to exit without creating the configuration file. If the BDMCONFIG file is not properly initialized and the user has responded with "Y", udmloadcf creates the Tuxedo file system and then creates the BDMCONFIG tables. Any response other than "y" or "Y" causes udmloadcf to exit without overwriting the file.

If the SECURITY parameter is specified in the RESOURCES section of the TUXCONFIG file, then udmloadcf flushes the standard input, turns off terminal echo, and prompts the user for an application password as follows:

>     Enter Application Password?

The password is truncated to 8 characters. You cannot load the ASCII DMCONFIG file through the standard input (rather than a file) when the SECURITY parameter is turned on. If the standard input is not a terminal, that is, if the user cannot be prompted for a password, then the environment variable APP_PW is accessed to set the application password. If the environment variable APP_PW is set with terminal as the standard input, then udmloadcf prints an error message, generates a log message, and fails to create the BDMCONFIG file.

Assuming no errors, and if all checks have passed, udmloadcf loads the DMCONFIG file into the BDMCONFIG file and overwrites all existing information found in the BDMCONFIG tables.

The following example shows how a binary configuration file is loaded from the bank.udmconfig ASCII file. The BDMCONFIG device is created (or reinitialized) with 2000 blocks:

>     udmloadcf -b 2000 -y bank.udmconfig

Diagnostics

If an error is detected in the input, the offending line is printed to the standard error log along with a message indicating the problem. If a syntax error is found in the DMCONFIG file or the system is currently running, no information is updated in the BDMCONFIG file and dmloadcf exits.

If udmloadcf is run on an active node, the following error message is displayed:

>     *** dmloadcf cannot run on an active node ***

If udmloadcf is run by a person whose effective user ID doesn't match the UID specified in the TUXCONFIG file, the following error message is displayed:

>     *** UID is not effective user ID ***

Upon successful completion, udmloadcf exits. If the BDMCONFIG file is updated, a userlog message is generated to record this event.

Tuning OSI TP-Specific Tables with the TAILOR File

The OSI TP TAILOR file is external to the DMCONFIG and is used for tuning OSI TP- specific tables. All parameters in the TAILOR file are optional with preset defaults.

Following is a list of valid TAILOR parameters:

####

Parameter | Default | Description
--- | --- | ---
FreeOldRetryTime | 600 seconds | Time in seconds between automatic terminations of old connections
MaxConnections | 500 | Maximum number of active concurrent calls
MaxRemoteNodes | 1000 | Maximum number of total remote domains
OldAssocTimeout | 3600 seconds | Time in seconds denoting an "old" connection (association)
TCPSocketsKeepAlives | N | Toggle for TCP keepalive packets
TCPSocketsLinger | -1 | Amount of time TCP/IP socket connection stays open
TCPSocketsListenQueueDepth | 5 | Number of held TCP/IP connections waiting to be accepted by eLink OSI TP
TCPSocketsNoDelay | N | Toggle to delay sends of TCP/IP packets until an ACK is received from remote machine
TracelpcKey | 32800 seconds | IPC key value for the OSI TP log and trace shared memory section

Following is more detailed information about each of the TAILOR file parameters:

  FreeOldRetryTimer = numeric

  Specifies the time in seconds between automatic terminations of old connections (associations). OSI TP reuses established socket connections to a remote domain. The default value is 600 seconds.

  MaxConnections = numeric

  Specifies the maximum number of active concurrent calls. The default value is 500.

  MaxRemoteNodes = numeric

  Specifies the maximum number of total remote domains, including those added dynamically. The default value is 1000.

  OldAssocTimeout = numeric

  Specifies the time in seconds denoting an "old" connection (association). Any connection to a remote domain that remains unused by a tpcall() for this amount of time is subject to automatic termination. This default value is 3600 seconds.

  TCPSocketsKeepAlives = {Y | N}

  Specifies whether the TCP keepalive packets are sent. This is useful to insure the integrity of the TCP connection. If Y is specified the TCP/IP packets are sent out in a time period specified by the operating system. Most operating systems use a 2 hour time period. The default is N.

  TCPSocketsLinger = {-1 | 0 | numeric}

  Specifies the amount of the time that the TCP/IP socket connection will stay open. This can be used to timeout hung connections.

  Possible values are:

####

-1 (default) | Time that a TCP/IP socket connection stays in the TIME_WAIT state is determined by the operating system.
0 | TCP/IP connection is closed immediately.
n | TCP/IP connection stays in the TIME_WAIT state for n seconds before closing.

  TCPSocketsListenQueueDepth = numeric

  Specifies the number of held TCP/IP connections waiting to be accepted by eLink OSI TP.

  Possible values are:

####

5 (default) | A minimum of 5 incoming TCP/IP connections are held.
>5 | More than 5 incoming TCP/IP connections are held. The operating system may only supports a number up to a "reasonable value".

  TCPSocketsNoDelay = {Y | N}

  Specifies if subsequent sends of TCP/IP packets are held until an ACK is received from a remote machine. The default is N, the subsequent sends of TCP/IP packets may be held until an ACK is received. If Y is specified, the TCP/IP packets are sent immediately without waiting for an ACK of the previous send.

  TracelpcKey = numeric

  For UNIX systems, specifies the IPC key value for the OSI TP log and trace shared memory segment. If there are multiple local domains, then each doamin must have a unique IPC key value. On Windows NT systems, this value is ignored. The default is 32800.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.