The TMA 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 DMCONFIG file.
• The $TUXDIR/udataobj/DMTYPE file defining the valid domain types must exist so the dmloadcf utility can load the binary configuration file and must contain a domain type of OSITPX. 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 dmloadcf must match the UID in the RESOURCES section of the TUXCONFIG file.
Table 4‑1 System Environment Variables 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 TMA 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 called 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:
1.
2. Run the osiadmin processor if you are upgrading from eLink OSI TP 1.3. 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 DMCONFIG File for more information.
4.
5. Create or edit the DMCONFIG file with new gateway information. Refer to Implementing Native-A Encoding and Understanding the DMCONFIG File for more information.
6. Generate a binary version of the dmconfig file by running the dmloadcf utility. Refer to Processing a Configuration File with the dmloadcf Utility for more information.After you perform these steps, you are ready to start the gateway using the Tuxedo tmboot command. Refer to the Oracle Tuxedo Online Documentation for more information about Tuxedo commands.To establish a gateway configuration, the Oracle Tuxedo system must recognize the gateway servers, DMADM, GWADM, and GWOSITP. You define the TMA OSI TP administrative and gateway servers to the Oracle Tuxedo system by editing the UBBCONFIG file.
1.
Note: OSIGRP is used as an example. You may give the group any name you wish.
2.
Note: The DMADM 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.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.The following file is a sample UBBCONFIG file that defines gateway servers to the Oracle Tuxedo system.Listing 4‑1 Sample UBBCONFIG FileFollowing is a sample UBBCONFIG file and corresponding DMCONFIG 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 GatewaysListing 4‑3 DMCONFIG File for Multiple GatewaysThe following example uses the same UBBCONFIG file as in Listing 4‑2 and shows how to configure one LDOM to support the non-multiplexed path and the other to support the multiplexed path.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 TMA OSI TP systems to exist in the same domain. (Refer to the Oracle Tuxedo documentation for more information about the MODEL parameter.) A practical example of this is setting up a Windows NT cluster. The TMA 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 DMCONFIG that physically exist on the master node. At TMBOOT time, a copy of the TUXCONFIG is propagated to the slave or backup system.Listing 4‑5 UBBCONFIG File for MP ModelListing 4‑6 DMCONFIG File for MP ModelFor this example, the TMA OSI TP gateway acts as a pass-through to allow access to services on other Tuxedo systems. The TMA OSI TP gateway receives 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:Listing 4‑7 shows a sample UBBCONFIG file and Listing 4‑8 shows the corresponding DMCONFIG file for a pass-through configuration.Note that the service that resides on the backend /TDOMAIN system must be defined as a local service on the TMA OSI TP system, so TMA 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.The Oracle Tuxedo UBBCONFIG and TMA OSI TP DMCONFIG files include five sections in which you specify security parameters for whichever type of security you want to implement:
• RESOURCES section of the UBBCONFIG file
• DM_LOCAL_DOMAINS section of the DMCONFIG file
• DM_OSITPX section of the DMCONFIG file
• DM_ACCESS_CONTROL section of the DMCONFIG file
• DM_LOCAL_SERVICES section of the DMCONFIG fileFigure 4‑2 TMA OSI TP Security ElementsTo enable security, both the local and remote domains must support security. For Link Layer Security (LLS), the administrator must define the SECURITY in the *LOCAL_DOMAINS section as DM_PW and the OPTIONS parameter in the DM_OSITPX section must be set to SECURITY_SUPPORTED. The Local and Remote domain passwords should be set by the administrator through the dmadmin command passwd.Whenever Link Layer Security is defined for the local domain and the remote domain, the passwd entered through dmadmin is hashed with a private key. The hashed value and private key are sent to the remote domain where it is compared with the hashed passwd on the remote system. This is a challenge response mechanism used to secure connections with a remote domain.Three sections in the DMCONFIG file contain parameters affecting how TMA 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 TMA OSI TP controls access to the Tuxedo local domain. If this parameter is set to NONE or APP_PW, the TMA OSI TP domain takes no action with regard to security. If this parameter is set to DM_PW, the TMA 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_REMOTE_DOMAINS section contains an OPTIONS=SECURITY_SUPPORTED parameter that specifies the type of security enforced for the Tuxedo remote domain.
• 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.Refer to “Enabling Tuxedo Authentication” for more information about Tuxedo security.The following sample is a DMCONFIG file that defines the necessary parameters for establishing Link Layer Security.Listing 4‑9 Sample DMCONFIG File for Establishing Link Layer SecurityOracle TMA OSI TP gateway supports Tuxedo authentication and authorization at both the client side (for Tuxedo clients) and server side. Authentication and authorization at the client side works the same as /T domains. Authentication and authorization on the server side requires that the Link Layer Security, described previously, is configured for both the LOCAL DOMAIN and the REMOTE DOMAIN involved in the service call.In order for user authentication at the server side domain to be performed, the SECURITY parameter defined in the servers local domain *RESOURCE section must be defined as either "APP_PW", "USER_AUTH", "ACL", or "MANDATORY_ACL".When SECURITY is set to either "APP_PW" or "USER_AUTH", user authentication is performed. If the ACL_POLICY for the remote domain from which the call was issued is defined as LOCAL, then the user ID used for authentication will be the LOCAL_PRINCIPAL_NAME of the remote domain if it has been defined. If the LOCAL_PRINCIPAL_NAME has not been defined, then the user ID will be the DOMAINID of the remote domain. If the ACL_POLICY for the remote domain from which the call was issued is defined as GLOBAL, then the userid passed with the call is used for user authentication. The user ID is authenticated against the user IDs defined in the tpusr file.When SECURITY is set to "ACL", then user authentication is performed as previously defined for "APP_PW" and "USER_AUTH". User authorization of the service, requested in the call, is also performed. ACL authorization requires that the services have been defined in the ACL Service list and that the user be a member of a group that is allowed access to this service. Services are added to the ACL Service list through the tpacladd command. If the requested service has not been added to the ACL Service list, then all users are allowed access to this service.When SECURITY is set to "MANDATORY_ACL" authentication and authorization are performed identical to that for SECURITY equal "ACL", however, the request service must be defined in the ACL Service list and the users group must be allowed access to this service.For more information regarding Tuxedo commands tpgrpadd, tpusradd, tpacladd, tpgrpmod, tpusrmod, tpaclmod, tpgrpdel, tpasrdel, and tpacldel, refer to the online Oracle Tuxedo documentation at http://www.oracle.com/bea/support.html.The following sample shows a UBBCONFIG file. The example defines the necessary parameters for establishing Link Layer Security.The following sample shows a DMCONFIG file. The example defines the necessary parameters for user authentication and authorization.Currently, the type of XATMI encoding must be configured for each RDOM using the XATMI_ENCODING parameter in the DM_OSITPX section of the DMCONFIG file. An XATMI_ENCODING keyword value of NATIVE_A_SERIES is used to indicate that the Tuxedo system will handle the encode/decode of data into the Native MCP format, not the Unisys MCP machine.There is an optional CODEPAGE parameter on the RDOM statement in the DM_REMOTE_DOMAINS section of the DMCONFIG file. The CODEPAGE parameter is configured to specify the pair of code sets involved when translating character strings between the Tuxedo system and the MCP (A-Series) system. If XATMI_ENCODING is not set to NATIVE_A_SERIES, then the CODEPAGE parameter is ignored.Where cpname is a case-insensitive keyword from the following table.
Table 4‑2 cpname Keywords If XATMI_ENCODING is not set to NATIVE_A_SERIES, then no conversion of character strings occurs. If XATMI_ENCODING is set to NATIVE_A_SERIES, then conversions occur according to the rules described in the following subsections.All view fields of type string must be null-terminated on both the Tuxedo and NATIVE_A_SERIES encoding feature, string fields may contain any non-zero bytes, followed by a zero byte as a null-terminator.All view fields of type string are always translated from the ISO character set to the MCP character set (as specified by the CODEPAGE parameter) when passing from the Tuxedo system to the MCP system. The input string must be null-terminated; any bytes after the null-terminator are ignored. The resulting string on the Unisys MCP system is null-terminated; any remaining space in the field is also padded with zero bytes.Conversly, all view fields of type string are translated from the MCP character set to the ISO character set (as specified by the CODEPAGE parameter) when passing from the Unisys MCP system to the Tuxedo system. The input string must be null-terminated; any bytes after the null-terminator are ignored. The resulting string on the Tuxedo system is null-terminated; any remaining space in the field is also padded with zero bytes.View fields of type carray need not be null-terminated. Carray fields may contain any non-zero bytes; if a zero byte is detected, it is treated as a null-terminator and scanning stops.All view fields of type carray are always translated from the ISO character set to the MCP character set (as specified by the CODEPAGE parameter) when passing from the Tuxedo system to the Unisys MCP system. The input string may or may not be null-terminated; any bytes after a null-terminator are ignored. The resulting string on the MCP system is not null-terminated; any remaining space in the field is padded with EBCDIC space characters (0x40 bytes).Conversly, all view fields of type carray are translated from the MCP character set to the ISO character set (as specified in the CODEPAGE parameter) when passing from the Tuxedo system to the Unisys MCP system. The input string may or may not be null-terminated; any bytes after a null-terminator are ignored. If the input string is not null-terminated, then any trailing EBCDIC space characters (0x40 bytes) are discarded before translation starts. The resulting string on the Tuxedo system is null-terminated if there is room; any remaining space in the field is also padded with zero bytes.For existing users who plan to use the Native-A feature, it is important to note that fields of type carray are always translated. If you wish to transmit binary data that should not be translated, then you must change your view field type from carray to an array of type char.View fields of type char may contain any arbitrary binary data. View fields of type char are never translated.For existing users who plan to use the Native-A feature, it is important to note that fields of type char are never translated. If you want to have fields of type char translated, you need to change your view field type from char to carray. See the following example.Listing 4‑12 Example of char Field Changed to carrayConversly, you may wish to change other data types (e.g., carray) to type char to prevent then from being translated. See the following example:Listing 4‑13 Example of carray Field Changed to charIf you are upgrading from eLink OSI TP 1.3, it is recommended that you use the osiadmin utility to update your DMCONFIG file; however, you may edit the DMCONFIG file manually. If you are upgrading from eLink OSI TP 4.0, you do not need to change your udmconfig input file. You can use it as input to the TMA OSI TP 10g R3 dmloadcf utility. Similarly, if you are upgrading from eLink OSI TP 4.1 or 4.2, you do not need to change your dmconfig input file. You can use it as input to the TMA OSI TP 10g R3 dmloadcf utility. Refer to Chapter 5, “Using the OSI TP Administration Utility,” for more information about the osiadmin utility.To edit the DMCONFIG file manually, perform the following steps:
1. Find the DMCONFIG file in your installation directory and open it in any text editor.
2. Edit the DMCONFIG file as necessary. Refer to the parameter descriptions in this section for details about defining your TMA OSI TP configuration.
3. When editing is complete, save the DMCONFIG file.
Note: You may want to save the original DMCONFIG file with a different name or in a different directory.
4. Process the DMCONFIG file with the dmloadcf utility. This parses the input and creates a binary file: the BDMCONFIG file, which is used by GWOSITP.Refer to Understanding the DMCONFIG File for more detailed information about the parameters in the DMCONFIG file.Perform the following steps to modify the DMCONFIG file parameters:You must define the local domains that use the OSI TP server group you defined in your Tuxedo UBBCONFIG file. Refer to Defining TMA OSI TP Servers for Oracle 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 DMCONFIG file:
1. Specify the local domain ID with the DOMAINID parameter.
2.
3.
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‑14 Example of DM_LOCAL_DOMAINS SectionIt is recommended that you use the importcfg command in the osiadmin utility to update remote domains if you are upgrading from eLink OSI TP 1.3; 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 DMCONFIG file:
1. Specify the remote domain ID with the DOMAINID parameter.
2. There are no optional parameters for the DM_REMOTE_DOMAINS section.Listing 4‑15 Example of DM_REMOTE_DOMAINS SectionPerform the following steps to define addressing information for OSI TP domains in the DM_OSITPX section of the DMCONFIG file:
1.
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, and separate them with a semi-colon (;). Put double quotes around the entire address.
3. Specify any of the optional DM_OSITPX parameters that you require: DNS_RESOLUTION, P_SEL, S_SEL, T_SEL, OPTIONS, TAILOR_PATH, and XATMI_ENCODING.Listing 4‑16 DM_OSITPX SectionIn the DM_ACCESS_CONTROL section of the DMCONFIG 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‑17 Example of DM_ACCESS_CONTROL SectionIn the DM_LOCAL_SERVICES section of the DMCONFIG 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, OUTBUFTYPE, OUTRECTYPE, and RNAME parameters. If the local service supports transactions, make sure the group it belongs to contains a TMS name.Listing 4‑18 Example of DM_LOCAL_SERVICES SectionIn the DM_REMOTE_SERVICES section of the DMCONFIG file, specify the remote services that can be requested by Tuxedo applications and define their options with the AUTOPREPARE, CODEPAGE, CONV, INBUFTYPE, INRECTYPE, LDOM, OUTBUFTYPE, OUTRECTYPE, RDOM, RNAME, ROUTING, and TRANTIME parameters. These parameters are all optional.Listing 4‑19 Example of DM_REMOTE_SERVICES SectionPerform the following steps to define routing information for service requests in the DM_ROUTING section of the DMCONFIG file:
1. Specify the name of the routing field with the FIELD parameter.
2.
3. Listing 4‑20 Example of DM_ROUTING SectionThe dmloadcf utility compiles the DMCONFIG file and creates a binary configuration file, BDMCONFIG, which is used by the DMADM server to control the run-time environment.Figure 4‑3 shows how the dmloadcf utility processes the configuration file. A description of the process follows the figure.Figure 4‑3 dmloadcf ProcessThe dmloadcf utility is invoked from a command line with the following syntax:Prints minimum IPC resources needed for each local domain (gateway group) in this configuration. The BDMCONFIG file is not updated.Suppresses a prompt to create and initialize the BDMCONFIG file. This parameter must be entered before the DMCONFIG file name.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.The dmloadcf 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, dmloadcf 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, dmloadcf exits without performing any updates to the BDMCONFIG file.The effective user ID of the person running dmloadcf must match the UID in the RESOURCES section of the TUXCONFIG file.After syntax checking, dmloadcf 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 withInitialize 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, dmloadcf ensures that the local domain described by that BDMCONFIG file is not running. If a local domain is running, dmloadcf prints an error message and exits. Otherwise, dmloadcf confirms that the file should be overwritten by prompting the user with:Prompting is suppressed if the standard input or output are not terminals. Any response other than “y” or “Y” causes dmloadcf to exit without creating the configuration file. If the BDMCONFIG file is not properly initialized and the user has responded with “Y”, dmloadcf creates the Tuxedo file system and then creates the BDMCONFIG tables.If the SECURITY parameter is specified in the RESOURCES section of the TUXCONFIG file, then dmloadcf flushes the standard input, turns off terminal echo, and prompts the user for an application password.Assuming no errors, and if all checks have passed, dmloadcf 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.DMCONFIG ASCII file. The BDMCONFIG device is created (or reinitialized) with 2000 blocks:If an error is detected in the input, the erroneous 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 dmloadcf is run on an active node, the following error message is displayed:If dmloadcf 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:Upon successful completion, dmloadcf exits. If the BDMCONFIG file is updated, a userlog message is generated to record this event.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:
Table 4‑3 Parameters for OSI TP TAILOR FIle Toggle for TCP keepalive packets Following is more detailed information about each of the TAILOR file parameters:FreeOldRetryTimer = numericKeepAliveCheck = numericKeepAliveTimeout = numericMaxConnections = numericMaxRemoteNodes = numericOldAssocTimeout = numericSpecifies 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.RdomAssocRetry = numericSpecifies the time in seconds between automatic retries of associations to unavailable RDOMs. This value must be greater than zero. The default value is 60. This value may be overridden on each RDOM with the EXTENSION parameter and the RdomAssocRetry keyword.StartFlowControlThreshold = numericStopFlowControlThreshold = numericSpecifies 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}
-1 (default) Time that a TCP/IP socket connection stays in the TIME_WAIT state is determined by the operating system. TCPSocketsListenQueueDepth = numeric
5 (default) 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.TraceIpcKey = numericBy default, TMA OSI TP will retry connections to an RDOM that has failed every 60 seconds. This delay may be overridden with the RdomAssocRetry tailor parameter described in the “Tuning OSI TP-Specific Tables with the TAILOR File” section. It may also be overridden for specific RDOMs using the EXTENSIONS="RdomAssocRetry=n" parameter in the DM_OSITPX section, where n is the number of seconds to wait between retries. The value specified on the EXTENSIONS parameter overrides the corresponding tailor parameter. Refer to “DM_OSITPX Section” for more information.In test environments, RDOMs may be configured that are unavailable and are considered offline. TMA OSI TP continually tries to connect to these systems. To disable the RDOMs and the remote services configured to them, specify EXTENSIONS="ONLINE=N" on each offline RDOM in the DM_OSITPX section of the DMCONFIG file. At run-time, these RDOMs can be brought online using the ONLINE osiadmin command described in “Using osiadmin Commands”.